542 lines
14 KiB
Markdown
542 lines
14 KiB
Markdown
TZ_Assistant_Mode_vNext.md
|
||
|
||
## Переход от route-plan ответа к нормальному диалоговому ответу по данным базы
|
||
|
||
---
|
||
|
||
## 1. Цель этапа
|
||
|
||
Превратить текущий Assistant Mode из технического интерфейса, который показывает:
|
||
|
||
* decomposition,
|
||
* route plan,
|
||
* trace,
|
||
* sandbox-пояснения,
|
||
|
||
в рабочий диалоговый режим, который:
|
||
|
||
* принимает вопрос пользователя;
|
||
* прогоняет его через normalizer/decomposition;
|
||
* выполняет реальный retrieval/query по маршруту;
|
||
* получает фактические данные;
|
||
* собирает **человекочитаемый ответ на русском языке**;
|
||
* показывает debug только как дополнительный раскрываемый слой.
|
||
|
||
---
|
||
|
||
## 2. Текущее состояние
|
||
|
||
Сейчас Assistant Mode работает как **planner/debug shell**:
|
||
|
||
**что уже есть:**
|
||
|
||
* ввод вопроса;
|
||
* decomposition / route selection;
|
||
* trace id;
|
||
* debug drawer;
|
||
* session-based диалоговая оболочка.
|
||
|
||
**что отсутствует:**
|
||
|
||
* реальный factual retrieval по данным базы;
|
||
* route-specific execution с возвратом нормальных данных;
|
||
* финальный answer composition по результатам retrieval;
|
||
* русскоязычный user-facing reply policy;
|
||
* разделение user-answer и technical-debug.
|
||
|
||
Комментарий:
|
||
Сейчас пользователь получает “planned routes / sandbox retrieval mode / trace”,
|
||
а должен получать ответ по сути вопроса.
|
||
|
||
---
|
||
|
||
## 3. Новая целевая архитектура
|
||
|
||
Нужен полный контур:
|
||
|
||
**User message → Normalizer → Execution Planner → Route-specific Retrieval → Result Normalization → Final Answer Composer → Assistant Reply**
|
||
|
||
---
|
||
|
||
## 4. Что должно происходить после сообщения пользователя
|
||
|
||
## 4.1. Шаг 1 — Normalization
|
||
|
||
Оставляем текущий `normalizer_v2.x`:
|
||
|
||
* scope filter;
|
||
* fragments;
|
||
* execution readiness;
|
||
* route status;
|
||
* clarification/out-of-scope detection.
|
||
|
||
## 4.2. Шаг 2 — Execution planning
|
||
|
||
Для каждого исполнимого fragment:
|
||
|
||
* определить маршрут;
|
||
* собрать execution plan;
|
||
* передать fragment в route-specific executor.
|
||
|
||
## 4.3. Шаг 3 — Real retrieval / query
|
||
|
||
Вместо sandbox plan нужно выполнять **реальный вызов backend data layer**:
|
||
|
||
* к 1С / хранилищу / API / query handlers;
|
||
* получать фактические данные;
|
||
* нормализовать их в общий result schema.
|
||
|
||
## 4.4. Шаг 4 — Final answer composition
|
||
|
||
На основе:
|
||
|
||
* user message,
|
||
* fragments,
|
||
* data results,
|
||
* fallback state
|
||
|
||
нужно собрать **один нормальный ответ для пользователя**.
|
||
|
||
---
|
||
|
||
# 5. Главный принцип нового режима
|
||
|
||
## Пользователь не должен видеть:
|
||
|
||
* planned routes;
|
||
* store canonical selected;
|
||
* sandbox retrieval mode;
|
||
* raw trace explanation;
|
||
* транслит;
|
||
* служебные внутренние названия маршрутов.
|
||
|
||
## Пользователь должен видеть:
|
||
|
||
* нормальный русский ответ;
|
||
* если данных нет — понятное объяснение;
|
||
* если нужен clarification — уточняющий вопрос;
|
||
* если часть вопроса вне контура — вежливое ограничение;
|
||
* при желании — кнопку “Показать технический разбор”.
|
||
|
||
---
|
||
|
||
# 6. Новый слой: Route-specific factual retrieval
|
||
|
||
---
|
||
|
||
## 6.1. Для каждого route нужен executor
|
||
|
||
Нужно реализовать route executors как отдельные backend handlers.
|
||
|
||
### A. `hybrid_store_plus_live`
|
||
|
||
Для causal / cross-entity / chain queries:
|
||
|
||
* искать связанные сущности;
|
||
* возвращать:
|
||
|
||
* контрагент/объект,
|
||
* документы,
|
||
* оплаты,
|
||
* проводки,
|
||
* подтверждающие связи,
|
||
* признаки разрыва цепочки.
|
||
|
||
### B. `store_feature_risk`
|
||
|
||
Для anomaly / rule-check / suspicious scan:
|
||
|
||
* искать проблемные объекты/записи;
|
||
* возвращать:
|
||
|
||
* сущность,
|
||
* причина попадания,
|
||
* риск-признак,
|
||
* релевантные поля.
|
||
|
||
### C. `batch_refresh_then_store`
|
||
|
||
Для overview / ranking / top / period risk:
|
||
|
||
* возвращать агрегаты;
|
||
* топы;
|
||
* summary blocks;
|
||
* приоритеты проверки;
|
||
* зоны риска.
|
||
|
||
### D. `store_canonical`
|
||
|
||
Для canonical factual path:
|
||
|
||
* выдавать прямую фактическую информацию по каноническому учётному представлению.
|
||
|
||
### E. `live_mcp_drilldown` (если уже подключён)
|
||
|
||
Для точечного drilldown:
|
||
|
||
* конкретный документ;
|
||
* конкретная проводка;
|
||
* конкретный объект;
|
||
* source-of-record.
|
||
|
||
---
|
||
|
||
## 6.2. Все executors должны возвращать unified result schema
|
||
|
||
Нужен единый формат результата, чтобы answer composer не зависел от route руками.
|
||
|
||
Примерно так:
|
||
|
||
```json
|
||
{
|
||
"fragment_id": "F1",
|
||
"route": "hybrid_store_plus_live",
|
||
"status": "ok | empty | partial | error",
|
||
"result_type": "list | summary | object | chain | ranking",
|
||
"items": [],
|
||
"summary": {},
|
||
"evidence": [],
|
||
"errors": []
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
# 7. Новый слой: Result normalization
|
||
|
||
Перед финальной генерацией ответа retrieval-результаты нужно привести в нормализованный вид.
|
||
|
||
Нужен слой:
|
||
|
||
* `normalize_retrieval_result(fragment, raw_backend_result)`
|
||
|
||
Задача:
|
||
|
||
* привести все маршруты к общему формату;
|
||
* отдать composer понятный и предсказуемый payload.
|
||
|
||
---
|
||
|
||
# 8. Новый слой: Final Answer Composer
|
||
|
||
Это ключевой этап.
|
||
|
||
## 8.1. Что он получает
|
||
|
||
На вход:
|
||
|
||
* `user_message`
|
||
* `normalized_query_v2_x`
|
||
* `resolved_fragments`
|
||
* `retrieval_results`
|
||
* `fallback state`
|
||
* `session context`
|
||
|
||
## 8.2. Что он должен делать
|
||
|
||
Собирать **один связный user-facing ответ**.
|
||
|
||
### Если один fragment
|
||
|
||
Отвечать прямо по вопросу.
|
||
|
||
### Если несколько fragments
|
||
|
||
Собирать один ответ с понятной структурой:
|
||
|
||
* сначала общий вывод;
|
||
* потом блоки по подзадачам;
|
||
* без ощущения, что это 5 несвязанных кусков.
|
||
|
||
### Если часть вопроса не выполнима
|
||
|
||
Отвечать по доступной части и мягко пояснять ограничения.
|
||
|
||
---
|
||
|
||
## 8.3. Ответ должен быть на русском
|
||
|
||
Жёсткое требование:
|
||
|
||
* никакого транслита;
|
||
* никаких англоязычных route names в тексте;
|
||
* никаких внутренних служебных формулировок.
|
||
|
||
---
|
||
|
||
## 8.4. Ответ не должен быть “сухой отладкой”
|
||
|
||
Нельзя выводить пользователю:
|
||
|
||
* `planned routes`
|
||
* `trace`
|
||
* `store canonical selected`
|
||
* `fallback_type=...`
|
||
|
||
Это всё — только в debug drawer.
|
||
|
||
---
|
||
|
||
# 9. Типы user-facing ответов
|
||
|
||
---
|
||
|
||
## 9.1. Normal factual reply
|
||
|
||
Когда данные найдены.
|
||
|
||
Пример:
|
||
|
||
* перечисление поставщиков с хвостами;
|
||
* список проблемных объектов;
|
||
* summary по рискам;
|
||
* ranking.
|
||
|
||
## 9.2. Empty result reply
|
||
|
||
Когда запрос корректен, но ничего не найдено.
|
||
|
||
Пример:
|
||
|
||
> По текущим данным явных проблемных записей по этому условию не найдено.
|
||
|
||
## 9.3. Partial reply
|
||
|
||
Когда по части вопроса данные найдены, по части — нет.
|
||
|
||
## 9.4. Clarification reply
|
||
|
||
Когда нужно уточнение.
|
||
|
||
## 9.5. Out-of-scope reply
|
||
|
||
Когда вопрос не про базу компании.
|
||
|
||
## 9.6. Backend error reply
|
||
|
||
Когда retrieval сломался технически.
|
||
|
||
Пример:
|
||
|
||
> Не удалось получить данные из контура. Попробуйте повторить запрос или уточнить формулировку.
|
||
|
||
---
|
||
|
||
# 10. Нужно разделить два уровня ответа
|
||
|
||
---
|
||
|
||
## 10.1. User Reply
|
||
|
||
То, что человек видит в чате.
|
||
|
||
## 10.2. Debug Payload
|
||
|
||
То, что раскрывается по кнопке:
|
||
|
||
* fragments
|
||
* execution readiness
|
||
* route status
|
||
* no_route_reason
|
||
* retrieval status
|
||
* trace id
|
||
|
||
Это должно жить отдельно.
|
||
|
||
---
|
||
|
||
# 11. Что изменить в GUI
|
||
|
||
---
|
||
|
||
## 11.1. Assistant message bubble
|
||
|
||
В ответе ассистента должен отображаться:
|
||
|
||
* нормальный текст;
|
||
* опционально таблица/список результатов, если уместно;
|
||
* без технического мусора.
|
||
|
||
## 11.2. Debug toggle
|
||
|
||
Кнопка:
|
||
|
||
* `Показать разбор`
|
||
или
|
||
* `Технические детали`
|
||
|
||
Внутри:
|
||
|
||
* decomposition;
|
||
* routes;
|
||
* fragments;
|
||
* trace id;
|
||
* backend status;
|
||
* fallback state.
|
||
|
||
## 11.3. Loading states
|
||
|
||
Во время выполнения:
|
||
|
||
* `Разбираю запрос`
|
||
* `Ищу данные`
|
||
* `Собираю ответ`
|
||
|
||
---
|
||
|
||
# 12. Что изменить в backend API
|
||
|
||
Нужен нормальный assistant endpoint, который возвращает уже готовый user reply.
|
||
|
||
## Пример
|
||
|
||
`POST /api/assistant/message`
|
||
|
||
### Request
|
||
|
||
```json
|
||
{
|
||
"session_id": "...",
|
||
"message": "...",
|
||
"mode": "assistant",
|
||
"period_hint": "...",
|
||
"business_context": "..."
|
||
}
|
||
```
|
||
|
||
### Response
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"assistant_reply": "человекочитаемый ответ",
|
||
"reply_type": "factual | clarification | out_of_scope | partial | empty | error",
|
||
"debug": {
|
||
"trace_id": "...",
|
||
"fragments": [...],
|
||
"routes": [...],
|
||
"retrieval_status": [...]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
# 13. Что логировать
|
||
|
||
Для каждого сообщения логировать:
|
||
|
||
* `session_id`
|
||
* `message_id`
|
||
* `user_message`
|
||
* `normalizer_output`
|
||
* `execution_plan`
|
||
* `retrieval_calls`
|
||
* `retrieval_results_raw`
|
||
* `retrieval_results_normalized`
|
||
* `assistant_reply`
|
||
* `reply_type`
|
||
* `trace_id`
|
||
|
||
Это пригодится потом для field-based hardening.
|
||
|
||
---
|
||
|
||
# 14. Минимальный MVP этого этапа
|
||
|
||
Чтобы не расползтись, можно сделать MVP так:
|
||
|
||
### Этап MVP-1
|
||
|
||
Сделать хотя бы 2 полноценных route executor:
|
||
|
||
* `hybrid_store_plus_live`
|
||
* `store_feature_risk`
|
||
|
||
И уже через них показать нормальный user-facing reply.
|
||
|
||
### Этап MVP-2
|
||
|
||
Добавить:
|
||
|
||
* `batch_refresh_then_store`
|
||
* `store_canonical`
|
||
|
||
### Этап MVP-3
|
||
|
||
Дополировать:
|
||
|
||
* partial replies
|
||
* better formatting
|
||
* richer debug drawer
|
||
|
||
---
|
||
|
||
# 15. Формат ответа ассистента
|
||
|
||
Ответ должен быть:
|
||
|
||
* на русском;
|
||
* коротким, но содержательным;
|
||
* с понятной привязкой к вопросу;
|
||
* без внутренних названий маршрутов.
|
||
|
||
### Пример плохого ответа
|
||
|
||
> Planned routes: store canonical. Sandbox mode. Trace...
|
||
|
||
### Пример допустимого ответа
|
||
|
||
> По текущему запросу найдены проблемные хвосты по нескольким поставщикам.
|
||
> Основные расхождения связаны с оплатами без корректного закрытия и неполной связкой документов.
|
||
> Ниже показаны контрагенты и проблемные цепочки.
|
||
|
||
---
|
||
|
||
# 16. Что НЕ делать на этом этапе
|
||
|
||
Не надо сейчас:
|
||
|
||
* строить суперсложную агентную систему;
|
||
* делать память на долгий диалог;
|
||
* пытаться решить все типы route сразу идеально;
|
||
* снова уходить в synthetic eval hardening;
|
||
* показывать пользователю внутреннюю кухню как основной результат.
|
||
|
||
---
|
||
|
||
# 17. Критерии приёмки
|
||
|
||
Этап считается принятым, если:
|
||
|
||
1. Assistant Mode возвращает **русский человекочитаемый ответ**, а не route plan;
|
||
2. debug остаётся доступен, но вынесен отдельно;
|
||
3. хотя бы для 2 route’ов работает полный factual loop:
|
||
|
||
* question → retrieval → factual reply;
|
||
4. out-of-scope / clarification / partial fallback корректно отображаются в чате;
|
||
5. decomposition mode не сломан;
|
||
6. транслит и технический мусор исчезли из основного ответа.
|
||
|
||
---
|
||
|
||
# 18. Артефакты, которые должен выдать Codex
|
||
|
||
1. `docs/assistant_mode_vnext_spec.md`
|
||
2. `docs/route_executor_contracts.md`
|
||
3. `docs/final_answer_composer_spec.md`
|
||
4. backend endpoint для assistant reply
|
||
5. unified retrieval result schema
|
||
6. GUI update для user-facing reply + debug drawer
|
||
7. `docs/known_limits_current_routes.md`
|
||
|
||
---
|
||
|
||
# 19. Короткий итог
|
||
|
||
Следующий шаг — это уже **не normalizer**, а:
|
||
|
||
**сделать так, чтобы ассистент после нормализации реально ходил за фактами и отвечал человеку по сути, а не показывал внутренний план работы.**
|
||
|
||
Если хочешь, я следующим сообщением сделаю ещё **короткую жёсткую версию этого ТЗ для вставки в Codex**.
|