Files

T

Наталия 71537b1e63 Initial commit: add project files and documentation

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-06-28 23:57:34 +07:00

13 KiB

Raw Permalink Blame History

Постановка задачи для разработчика и код-агента

Ты работаешь над локальным прототипом витрины сервисного входа "ВКУС". Нужно построить действующий прототип, который демонстрирует два слоя:

Пользовательская витрина обращений.
Административный слой подготовки базы знаний из сырых инструкций.

Работай итерационно. После каждой законченной итерации прототип должен запускаться локально и быть пригодным для user-теста.

Исходные данные

Используй данные из папки:

input_data/

Там находятся:

Start data - исходные материалы по CJM, capabilities, C4, sequence и общей методике ВКУС.
Manuals - сырые инструкции, из которых нужно строить базу знаний для RAG.

Также есть стартовые JSON:

seed_data/knowledge.json
seed_data/services.json

Их можно использовать как начальные демонстрационные знания и каталог услуг.

Не используй и не запрашивай .env или другие секреты. Если нужен LLM, сделай работу через переменные окружения и fallback без LLM.

Цель прототипа

Пользователь описывает проблему своими словами. Витрина должна:

Принять свободное описание.
Найти релевантные знания в базе инструкций.
Определить намерение пользователя.
Подобрать подходящую услугу из каталога.
Сформировать короткую рекомендацию.
Подготовить черновик обращения с предзаполненными полями.
Показать компактную трассировку взаимодействий: RAG, intent, service mapping, LLM/fallback, prefill.

Главная витрина не должна выглядеть как отладочная панель RAG. Детальный вывод источников и управление знаниями должны быть вынесены в административный инструмент.

Пользовательская витрина

Сделай локальное web-приложение, например на Python http.server или другом простом стеке без тяжелой инфраструктуры.

Минимальный UI:

поле для описания проблемы;
несколько кнопок с примерами;
кнопка "Проанализировать";
блок результата:
- рекомендация;
- шаги, если применимо;
- подобранная услуга;
- намерение и уверенность;
- черновик обращения;
- компактная трассировка.

Не показывай пользователю длинные RAG-фрагменты, сырой JSON, список всех источников, score-таблицы и диагностические дампы. Это можно оставить только в трассировке в сжатом виде.

Пример пользовательского запроса для проверки:

В ЛИМС не вижу проект SAP PPM, хотя он должен быть доступен для работы.

Ожидаемое поведение:

витрина должна найти контекст в инструкциях ЛИМС;
подобрать услугу поддержки ЛИМС;
предложить создание обращения или понятный следующий шаг;
показать, что RAG и service mapping участвовали в обработке.

RAG и база знаний

Создай отдельный административный инструмент для подготовки базы знаний.

Источник данных:

input_data/Manuals

Структура подпапок внутри Manuals не является контрактом. Она нужна человеку для удобства раскладки файлов.

Поддержи извлечение текста как минимум из:

PDF;
DOCX;
PPTX;
XLSX;
TXT.

Архивы .7z можно поддержать технически, но пароль должен передаваться через переменную окружения. Если архив не читается, он не должен ломать весь прогон индексации.

Что такое индексация

Индексация - это конвейер:

сырой файл
-> извлечение текста
-> очистка текста
-> разбиение на knowledge items
-> определение метаданных
-> сохранение нормализованной базы знаний
-> использование в поиске

Минимальная структура knowledge item:

{
  "id": "...",
  "title": "...",
  "summary": "...",
  "text": "...",
  "system": "ЛИМС НИОКР",
  "source_file": "...",
  "source_type": "pdf",
  "section": "Страница 1",
  "content_type": "instruction",
  "content_type_title": "Инструкция",
  "module": "...",
  "role": "...",
  "source_ref": "file / section",
  "keywords": [],
  "self_service": true
}

Внутренние коды типов знаний должны быть стабильными на английском языке, а UI должен показывать русские названия.

Создай общий справочник типов знаний:

[
  {"code": "instruction", "title": "Инструкция"},
  {"code": "faq", "title": "Частые вопросы"},
  {"code": "troubleshooting", "title": "Решение проблем"},
  {"code": "role", "title": "Роли и доступы"},
  {"code": "reference", "title": "Справочная информация"},
  {"code": "table", "title": "Таблица"},
  {"code": "integration", "title": "Интеграция"},
  {"code": "architecture", "title": "Архитектура"}
]

API и UI должны возвращать и использовать оба значения:

{
  "content_type": "integration",
  "content_type_title": "Интеграция"
}

Административный UI базы знаний

Сделай отдельный локальный web-ui администратора.

Функции:

выбрать стартовую директорию;
выполнить полную пересборку базы знаний;
добавить только новые источники;
увидеть статистику индекса;
увидеть диагностику ошибок и пропусков;
увидеть проиндексированные документы деревом каталогов с collapse/expand;
исключить выбранный источник из базы знаний без удаления физического файла.

Важно: удаление из базы знаний не должно удалять исходный файл с диска.

Manifest источников

Добавь manifest источников, например:

{
  "schema_version": "knowledge-source-manifest.v1",
  "manuals_dir": "...",
  "updated_at": "...",
  "sources": [
    {
      "source_file": "Manuals/ЛИМС/example.pdf",
      "path": "...",
      "extension": ".pdf",
      "size": 12345,
      "modified_at": "...",
      "hash": "...",
      "status": "indexed",
      "items_count": 10,
      "indexed_at": "..."
    }
  ]
}

Поддержи статусы:

indexed - источник входит в базу знаний;
excluded - источник исключен администратором и не должен автоматически возвращаться при добавлении новых файлов.

Режимы:

Полная пересборка - заново читает стартовую директорию, но сохраняет excluded-источники.
Добавить новые - индексирует только ранее неизвестные файлы.
Исключить источник - удаляет knowledge items этого источника из базы знаний и помечает источник как excluded.

Поиск

Для MVP можно сделать локальный keyword/hybrid-like поиск без vectorDB:

токенизация запроса и текста;
overlap/coverage score;
бонусы за совпадение в title, system, module, content_type;
ограничение количества результатов из одного source_file;
возврат score и source_ref.

В дальнейшем решение должно быть совместимо с переносом в PostgreSQL и pgvector.

Связка витрины и базы знаний

Пользовательская витрина должна читать базу, созданную административным инструментом. Если база недоступна, допустим fallback на seed knowledge.

Желательно добавить hot-reload по времени изменения JSON-файла, чтобы витрина подхватывала обновления базы знаний без перезапуска.

API

Минимальные endpoint'ы витрины:

POST /api/analyze
POST /api/search
GET /health

Минимальные endpoint'ы админки:

GET /api/status
GET /api/documents
GET /api/errors
GET /api/manifest
GET /api/reference/knowledge-types
POST /api/reindex
POST /api/add-new
POST /api/delete-source
POST /api/search

LLM

Если доступны переменные окружения для LLM, можно вызывать внешний LLM для формулирования ответа. Но прототип обязан работать без LLM:

RAG-поиск локальный;
intent/service mapping локальные;
fallback-ответ формируется локальной логикой.

Не храни ключи в репозитории.

Критерии готовности MVP

Витрина запускается локально и позволяет выполнить сценарий /api/analyze.
Админка запускается локально и умеет собрать базу знаний из Manuals.
База знаний строится из реальных документов.
Витрина использует базу знаний, созданную админкой.
Можно добавить новые источники без полной пересборки.
Можно исключить ошибочный источник из базы знаний.
Типы знаний показываются на русском, но внутренние коды остаются стабильными.
.env и секреты не требуются для запуска fallback-сценария.

Важное ограничение

Это прототип. Не усложняй инфраструктуру раньше времени. PostgreSQL, pgvector, OCR, очереди задач и полноценный RBAC стоит проектировать как следующий этап после стабилизации JSON-модели и пользовательского сценария.

13 KiB Raw Permalink Blame History