Справочник (Handbook)¶

Справочник — версионируемый свод правил тенанта. Оператор загружает Markdown, компилирует снимок и ищет по нему. Открытые противоречия не закрываются молча: совпавшая тема уходит на ручное согласование.

Prompt Guard проверяет текст до сохранения. Поиск — пересечение ключевых слов по скомпилированному снимку (не эмбеддинги).

Кто имеет доступ¶

Роль	Чтение / запрос	Компиляция / удаление источника	Разрешение конфликта
Viewer	—	—	—
Security Analyst	✔	—	—
Developer	✔	✔	✔
Admin	✔	✔	✔
Super Admin	✔	✔	✔

Пункт Handbook в группе меню Operate (/handbook).

Источники¶

POST /api/v1/handbook/sources:

`kind`	Тело
`paste`	обязательный `raw_text`, необязательный `uri`
`markdown_dir`	`uri` — каталог, который читает API
`archive`	`uri` или `raw_text` (zip в base64)

Компиляция: POST /api/v1/handbook/compile. В ответе version, entry_count, conflict_count, markdown и conflicts.

Удаление: DELETE /api/v1/handbook/sources/{source_id} (право compile). Если снимок уже есть, удаление пишется в аудит как handbook.compile.

Запрос¶

curl -X POST http://localhost:8001/api/v1/handbook/query \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"q":"лимит возврата"}'

SPA ходит с HttpOnly cookie (credentials: include). Для API-клиентов по-прежнему подходит X-API-Key тенанта.

Ответ содержит handbook_version, hits и open_conflicts по совпавшим темам.

Конфликты и HITL¶

POST /api/v1/handbook/conflicts/{conflict_id}/resolve:

{ "resolution_entry_id": "<uuid-записи>" }

На POST /api/v1/policies/check и в шагах workflow открытый конфликт меняет решение:

allow становится false
required_approval становится true
reason начинается с UNRESOLVED CONFLICT on <topic>/<id>
Одобрение HITL не снимает этот конфликт

Для action=workflow.step (по умолчанию HANDBOOK_WORKFLOW_FAIL_CLOSED=true) любой открытый конфликт в снимке ставит шаг на паузу, даже если тема промпта не совпала. Чат / Try Prompt по-прежнему смотрят на совпадение темы, пока флаг не включён явно.

Ворота работают, только если вызов идёт через этот control plane (workflow.step, webhook/cron в executor, или /agents/{id}/chat). Клиент, который игнорирует allowed: false и зовёт модель сам, обходит стоп.

Сначала закройте конфликт в Handbook, затем повторите шаг. После resolve stale handbook HITL истекает, resume снова прогоняет overlay (hitl_approved=false).

Компиляция и разрешение пишутся в аудит как handbook.compile и handbook.resolve. На странице Audit фильтр: ?action=handbook.compile или ?action=handbook.resolve.

Try Prompt¶

На карточке агента Try Prompt показывает версию справочника. Если промпт попал в открытый конфликт, результат ведёт на /handbook?focus=conflicts.

Фикстура eval¶

POST /api/v1/handbook/eval?fixture=studio_north&mode=compiler гоняет встроенную фикстуру компилятора (mode=runtime тоже доступен). Это регрессионная проверка, не данные тенанта. Нет фикстуры — 404.