diff --git a/ops/ops/ORCHESTRATION.md b/ops/ops/ORCHESTRATION.md new file mode 100644 index 0000000..61bc4a2 --- /dev/null +++ b/ops/ops/ORCHESTRATION.md @@ -0,0 +1,94 @@ +# Оркестрирование секретаря (23.10, спринт 3) + +## Решение об архитектуре + +Секретарь остаётся **единым входом** — разбор намерений и проверка ролей +только там. Профильные боты — исполнители со своими командами. + +Почему не разносить разбор по ботам: + +| Причина | Эффект | +|---|---| +| Одна точка разбора | нет девяти разных парсеров | +| Одна проверка прав | `_role_gate` в одном `dispatch` | +| Один журнал решений | `routing.jsonl` | +| Новый бот = набор команд | не нужно копировать логику входа | + +## Цепочка обработки + +``` +1. намерение → конкретная команда бота (сильные намерения) +2. маршрут по словам → бот.dispatch +3. готовый ответ из /intent (слабые намерения) +4. RAG по документации +5. пожелание + эскалация владельцу +``` + +**Приоритет:** «сильные» намерения (`recommend, stats, who, similar, play, +infra, books, photos, home, digest`) идут в пункт 1. Слабое `find` уступает +маршруту по словам — иначе любая фраза превращалась в поиск. + +## Маршрут по словам: скоринг + +Раньше выбирался бот по самому длинному совпавшему слову. Теперь: + +``` +score = длина_слова × вес_бота +``` + +Веса: `DIGEST` 1.2 (длинные фразы «что нового»), `SEARCH` 0.8 (частые +глаголы не должны перебивать домен), остальные 1.0. + +Побеждает максимальный score среди доступных ботов. Все кандидаты +сохраняются в след (`candidates`) — видно, почему выбран именно этот. + +## Журнал решений + +`/var/lib/hub-bots/routing.jsonl`: + +```json +{"at": "2026-10-23T20:21:49", "user": "@akadmin:...", "text": "статус бэкапов", + "trace": {"intent": "infra", "bot": "INFRA", "command": "статус", + "via": "intent-command"}, "answered": true} +``` + +Поле `via`: `intent-command` · `route` · `intent-answer`. + +## Команда `!маршрут` + +Только владелец. Показывает разбор любой фразы: + +``` +!маршрут найди дюну + +намерение: find (источник: rules) +извлечённое название: «дюну» +цепочка: бот MEDIA, команда поиск +маршрут по словам: SEARCH (слово «найди») +кандидаты: SEARCH(4.0), MEDIA(1.0) +``` + +## Проверка на 11 фразах + +| Фраза | Намерение | Цепочка | Маршрут | +|---|---|---|---| +| включи музыку на кухне | play | MEDIA/включи | MEDIA | +| статус бэкапов | infra | INFRA/статус | INFRA | +| покажи книги Стругацкого | books | BOOK/поиск | BOOK | +| фотографии за лето | photos | PHOTO/поиск | PHOTO | +| что нового за неделю | digest | DIGEST/дайджест | DIGEST | +| температура в комнате | home | HOME/статус | HOME | +| найди дюну | find | маршрут | SEARCH | +| что посмотреть вечером | recommend | MEDIA/что посмотреть | MEDIA | +| сколько фильмов | stats | MEDIA/статистика | MEDIA | +| кто дома | who | HOME/кто дома | — | +| найди матрицу | find | маршрут | SEARCH | + +## Ловушка, которую поймал + +Первый патч оркестрирования **не сохранил файл** (забыл `write` в скрипте +правки), при этом напечатал «таблица маршрутов заменена». Проверка маркеров +после применения это выявила: `_intent_route` вызывался, но не был определён. + +Вывод: после любого патча проверять наличие маркеров в файле и синтаксис, +а не доверять сообщению «готово».