Initial commit: add project files and documentation
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Наталия
@@ -0,0 +1,292 @@
|
||||
# Постановка задачи для разработчика и код-агента
|
||||
|
||||
Ты работаешь над локальным прототипом витрины сервисного входа "ВКУС". Нужно построить действующий прототип, который демонстрирует два слоя:
|
||||
|
||||
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-модели и пользовательского сценария.
|
||||
Reference in New Issue
Block a user