Наталия
293 lines
13 KiB
Markdown
293 lines
13 KiB
Markdown
# Постановка задачи для разработчика и код-агента
|
|
|
|
Ты работаешь над локальным прототипом витрины сервисного входа "ВКУС". Нужно построить действующий прототип, который демонстрирует два слоя:
|
|
|
|
1. Пользовательская витрина обращений.
|
|
2. Административный слой подготовки базы знаний из сырых инструкций.
|
|
|
|
Работай итерационно. После каждой законченной итерации прототип должен запускаться локально и быть пригодным для user-теста.
|
|
|
|
## Исходные данные
|
|
|
|
Используй данные из папки:
|
|
|
|
```text
|
|
input_data/
|
|
```
|
|
|
|
Там находятся:
|
|
|
|
- `Start data` - исходные материалы по CJM, capabilities, C4, sequence и общей методике ВКУС.
|
|
- `Manuals` - сырые инструкции, из которых нужно строить базу знаний для RAG.
|
|
|
|
Также есть стартовые JSON:
|
|
|
|
```text
|
|
seed_data/knowledge.json
|
|
seed_data/services.json
|
|
```
|
|
|
|
Их можно использовать как начальные демонстрационные знания и каталог услуг.
|
|
|
|
Не используй и не запрашивай `.env` или другие секреты. Если нужен LLM, сделай работу через переменные окружения и fallback без LLM.
|
|
|
|
## Цель прототипа
|
|
|
|
Пользователь описывает проблему своими словами. Витрина должна:
|
|
|
|
1. Принять свободное описание.
|
|
2. Найти релевантные знания в базе инструкций.
|
|
3. Определить намерение пользователя.
|
|
4. Подобрать подходящую услугу из каталога.
|
|
5. Сформировать короткую рекомендацию.
|
|
6. Подготовить черновик обращения с предзаполненными полями.
|
|
7. Показать компактную трассировку взаимодействий: RAG, intent, service mapping, LLM/fallback, prefill.
|
|
|
|
Главная витрина не должна выглядеть как отладочная панель RAG. Детальный вывод источников и управление знаниями должны быть вынесены в административный инструмент.
|
|
|
|
## Пользовательская витрина
|
|
|
|
Сделай локальное web-приложение, например на Python `http.server` или другом простом стеке без тяжелой инфраструктуры.
|
|
|
|
Минимальный UI:
|
|
|
|
- поле для описания проблемы;
|
|
- несколько кнопок с примерами;
|
|
- кнопка "Проанализировать";
|
|
- блок результата:
|
|
- рекомендация;
|
|
- шаги, если применимо;
|
|
- подобранная услуга;
|
|
- намерение и уверенность;
|
|
- черновик обращения;
|
|
- компактная трассировка.
|
|
|
|
Не показывай пользователю длинные RAG-фрагменты, сырой JSON, список всех источников, score-таблицы и диагностические дампы. Это можно оставить только в трассировке в сжатом виде.
|
|
|
|
Пример пользовательского запроса для проверки:
|
|
|
|
```text
|
|
В ЛИМС не вижу проект SAP PPM, хотя он должен быть доступен для работы.
|
|
```
|
|
|
|
Ожидаемое поведение:
|
|
|
|
- витрина должна найти контекст в инструкциях ЛИМС;
|
|
- подобрать услугу поддержки ЛИМС;
|
|
- предложить создание обращения или понятный следующий шаг;
|
|
- показать, что RAG и service mapping участвовали в обработке.
|
|
|
|
## RAG и база знаний
|
|
|
|
Создай отдельный административный инструмент для подготовки базы знаний.
|
|
|
|
Источник данных:
|
|
|
|
```text
|
|
input_data/Manuals
|
|
```
|
|
|
|
Структура подпапок внутри `Manuals` не является контрактом. Она нужна человеку для удобства раскладки файлов.
|
|
|
|
Поддержи извлечение текста как минимум из:
|
|
|
|
- PDF;
|
|
- DOCX;
|
|
- PPTX;
|
|
- XLSX;
|
|
- TXT.
|
|
|
|
Архивы `.7z` можно поддержать технически, но пароль должен передаваться через переменную окружения. Если архив не читается, он не должен ломать весь прогон индексации.
|
|
|
|
## Что такое индексация
|
|
|
|
Индексация - это конвейер:
|
|
|
|
```text
|
|
сырой файл
|
|
-> извлечение текста
|
|
-> очистка текста
|
|
-> разбиение на knowledge items
|
|
-> определение метаданных
|
|
-> сохранение нормализованной базы знаний
|
|
-> использование в поиске
|
|
```
|
|
|
|
Минимальная структура knowledge item:
|
|
|
|
```json
|
|
{
|
|
"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 должен показывать русские названия.
|
|
|
|
Создай общий справочник типов знаний:
|
|
|
|
```json
|
|
[
|
|
{"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 должны возвращать и использовать оба значения:
|
|
|
|
```json
|
|
{
|
|
"content_type": "integration",
|
|
"content_type_title": "Интеграция"
|
|
}
|
|
```
|
|
|
|
## Административный UI базы знаний
|
|
|
|
Сделай отдельный локальный web-ui администратора.
|
|
|
|
Функции:
|
|
|
|
- выбрать стартовую директорию;
|
|
- выполнить полную пересборку базы знаний;
|
|
- добавить только новые источники;
|
|
- увидеть статистику индекса;
|
|
- увидеть диагностику ошибок и пропусков;
|
|
- увидеть проиндексированные документы деревом каталогов с collapse/expand;
|
|
- исключить выбранный источник из базы знаний без удаления физического файла.
|
|
|
|
Важно: удаление из базы знаний не должно удалять исходный файл с диска.
|
|
|
|
## Manifest источников
|
|
|
|
Добавь manifest источников, например:
|
|
|
|
```json
|
|
{
|
|
"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'ы витрины:
|
|
|
|
```text
|
|
POST /api/analyze
|
|
POST /api/search
|
|
GET /health
|
|
```
|
|
|
|
Минимальные endpoint'ы админки:
|
|
|
|
```text
|
|
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
|
|
|
|
1. Витрина запускается локально и позволяет выполнить сценарий `/api/analyze`.
|
|
2. Админка запускается локально и умеет собрать базу знаний из `Manuals`.
|
|
3. База знаний строится из реальных документов.
|
|
4. Витрина использует базу знаний, созданную админкой.
|
|
5. Можно добавить новые источники без полной пересборки.
|
|
6. Можно исключить ошибочный источник из базы знаний.
|
|
7. Типы знаний показываются на русском, но внутренние коды остаются стабильными.
|
|
8. `.env` и секреты не требуются для запуска fallback-сценария.
|
|
|
|
## Рекомендуемая последовательность работ
|
|
|
|
1. Создать минимальную витрину и endpoint `/api/analyze` на seed data.
|
|
2. Добавить индексатор документов из `Manuals`.
|
|
3. Добавить базу знаний JSON и endpoint `/api/search`.
|
|
4. Подключить витрину к базе знаний.
|
|
5. Создать админку базы знаний.
|
|
6. Добавить manifest, `Добавить новые`, `Исключить источник`.
|
|
7. Упростить пользовательскую витрину: убрать отладочный RAG-дамп, оставить компактную трассировку.
|
|
8. Прогнать user-тесты на сценариях ЛИМС, 1С и восстановление файла.
|
|
|
|
## Важное ограничение
|
|
|
|
Это прототип. Не усложняй инфраструктуру раньше времени. PostgreSQL, pgvector, OCR, очереди задач и полноценный RBAC стоит проектировать как следующий этап после стабилизации JSON-модели и пользовательского сценария.
|