Инженерные документы

Модель-супервайзер: роль, кейсы и метрики человеческого фактора

Статус: принято (фаза 1 реализована). Связанные документы: agent-quality-loop.md, system-dashboard.md, human-knowledge-explorer.md.

#1. Роль

Супервайзер — installation-wide модель, которая работает для администратора, а не над задачами пользователей. Она не выполняет работу пользователей и не пишет в их артефакты; её продукция — суждения: оценки, диагнозы, предложения, предупреждения. Каждое суждение имеет доказательную базу (id ранов и событий) и остаётся предложением, пока человек не примет.

Сегодня супервайзер (= судья) уже: оценивает скиллы и изменения агентов (golden-кейсы + калибровка согласия), упорядочивает области знаний. Настройка — Агенты → «Настройки качества» (/v1/workspace/supervisor).

#2. Настройки (фаза 1, реализовано)

Параметр	Ключ	Назначение
Модель-супервайзер	`eval.judge.model`	роль судьи: оценки качества, упорядочивание областей знаний
Модель зрения	`supervisor.vision.model`	fallback для вызовов с изображениями, если основная модель не мультимодальная (роутинг в `CallModel`)
HAB-коэффициенты	`supervisor.hab.*`	оценка внимания человека (§5)
Расписание качества	`eval.schedule.interval`	периодичность оценочных прогонов

#3. Каталог кейсов супервайзера (дорожная карта)

#Волна A — мониторинг проблем (наблюдатель) — реализована целиком

A1. Триаж упавших ранов (реализовано). После run.failed супервайзер читает трассу и пишет структурный диагноз: класс причины (ошибка модели / лимит песочницы / дефект харнеса / промпт агента / ошибка пользователя), доказательства, предложение. Пополняет очередь проблем администратора.
A2. Кластеризация повторяющихся сбоев (реализовано). Каждый вердикт несёт детерминированный cluster_key (класс причины + нормализованный текст ошибки: цифры → #, пути → ~) и короткую модельную метку паттерна («cpu range», «provider 429»). Очередь проблем сворачивает раны с одним ключом в один тикет со счётчиком ×N и списком ранов; группировка не зависит от стабильности формулировок модели.
A3. Аномалии здоровья (реализовано). Детектор в kernel/agent сравнивает текущий час с предыдущим (health-агрегат с until-окном): рост доли ошибок модели, шторм ретраев (≥3×), всплеск упавших ранов (≥2× при ≥3), очередь подтверждений, кратный рост p95. Находка журналируется как supervisor.insight: объяснение от супервайзера, при выключенной модели — детерминированный шаблон с теми же числами; дедуп по метрике 6 часов.

#Волна B — качество и развитие (реализована)

B1. Триаж противоречий знаний (реализовано). Каждому knowledge.challenged (rule contradiction) — вердикт-черновик решения (action: invalidate_old / supersede_old / keep_both_scoped / confirm_new, закрытый словарь, деградация к безопасному) с subject=knowledge id; человек применяет в UI знаний.
B2. Контрактные предложения (реализовано). Кластер A2 с классом agent_prompt по одному агенту при ≥3 ранах превращается в черновик эволюции (agent.DraftContractProposal) и подаётся в реестр предложений (CreateAgentProposal, author=supervisor) — дальше обычный человеческий ревью.
B3. Наблюдение за развитием (реализовано). Когда у агента две последние оценки накрывают разные версии определения, супервайзер пишет нарратив «что улучшилось/что деградировало» (subject=agent:vN).
B4. Гигиена знаний (реализовано). knowledge.challenged с правилом aging → рекомендация confirm/update/retire (subject=knowledge id).

#Волна C — пользовательские ошибки и трение (реализована)

C1. Ошибки пользователей (реализовано). Два детерминированных паттерна: один и тот же нормализованный запрос ≥3× от одного актора и дважды отклонённая операция в одном ране → суждение case=user_friction.
C2. Проверка intake-классификации (реализовано). Выборочный аудит intake.classified (task/amendment): супервайзер сверяет метку с текстом сообщения и тем, что стартовалось после; молчание при согласии — шум только на расхождениях.
C3. Валидация цели поправки (реализовано). Перед стартом поправки (start_task с amend_run_id) супервайзер сверяет текст поправки с целью (тайтл + дайджест ответа); явное несовпадение — 422 с рекомендацией, сбой супервайзера не блокирует поправку.
C4. Майнинг кандидатов в навыки (реализовано). 3-граммы тулов, повторяющиеся в ≥3 разных ранах и не покрытые существующими навыками: сперва дешёвый детерминированный фильтр шума (подряд идущие повторы одного тула — пагинация/ретраи, сплошь read-only последовательности — навигация), затем судья решает, стоит ли повторение процедуры (worth_skill), и только для «да» публикуется черновик навыка (name/description/steps) кейсом skill_candidate.
C5. Прогноз конфликтов знаний (реализовано). Backfill эмбеддингов проверяет соседей свежевстроенной пропозиции: косинус в полосе [0.85, 0.97) — вердикт knowledge_conflict до того, как противоречие дойдёт до рана. Эндпоинт GET /v1/observations/knowledge/embeddings/neighbors.

Все кейсы работают на одной и той же поверхности: журнальные события → структурное суждение супервайзера → очередь администратора. Ни одно суждение не исполняется автоматически.

#4. Vision-роутинг (фаза 1, реализовано)

Вызов модели, несущий изображения, направляется на модель из supervisor.vision.model, если задана и отличается от модели запроса; маршрутизация провайдера — общая с обычными вызовами. Без настройки изображения идут в основную модель (прежнее поведение).

#5. Человеческий фактор: HAB, HWT и Flow Efficiency (фаза 1, реализовано)

Метрики разделяют два разных явления, которые раньше смешивались в «human approval budget»:

Метрика	Канбанский аналог	Определение
HAB — Human Attention Spend («внимание»)	touch time	Оценка времени внимания: чтение итоговых и промежуточных заключений, принятие подтверждений, обдумывание и написание ответов
HWT — Human Wait Time («простой»)	queue wait time	wall-clock время, которое работа простояла в ожидании человека (вопрос поднят → решён), вне зависимости от того, сколько внимания это заняло
Flow Efficiency	flow efficiency	`HAB / (HAB + HWT)` — доля человеческой шкалы времени, которая ушла на реальное внимание, а не на простой

#Как считается HAB (оценка, коэффициенты настраиваются)

решение по подтверждению/сверке: supervisor.hab.approval_seconds (45с);
ответ на ask_human: база answer_base_seconds (20с) + набор текста (длина ответа / 5 символов на слово / reading_wpm);
чтение сгенерированного: финальный ответ читается целиком (слова agent.summary.answer), остальная выдача (completion-токены без ответа) — с коэффициентом беглого просмотра 10%; промпт-токены не читаются никогда (это контекст, который человек не видит). words ≈ tokens × 0.75; секунды = слова / reading_wpm × 60.

#Как считается HWT

Σ (момент решения − момент постановки вопроса) по разрешённым подтверждениям/вопросам в окне. Это чистая задержка потока — канбан-очередь.

#Где смотреть

Два слоя одних и тех же метрик:

Окно (существующее): дашборд → обзор → карточка «Человеческий фактор» — HAB, HWT, Flow Efficiency и счётчики решений/ответов за час.
Персистентно, по скоупам (реализовано): агрегаты kernel/cost несут human в каждом rollup — ран/задача (/cost/task), сага и проект (/cost/budget), team-run (/cost/team-run). HAB копится из решений, ответов и чтения заключений за всю жизнь скоупа, HWT — из ожиданий approvals (зеркало wait_ms); коэффициенты читаются из настроек супервайзера при старте ядра. В UI — подсказка у ячейки approvals в обзоре проекта и строка «внимание/простой» в бюджете задачи на странице рана. Появление HWT ≫ HAB — сигнал: вопросы зависают, поток блокируется на людях.

#6. Семантический слой знаний (фаза 2, реализовано)

Модель эмбеддингов — локальная и фиксированная, работает в процессе ядра через pure-Go движок rembed (intfloat/multilingual-e5-small, 384-мерные векторы, 100+ языков, weight-only int8): ни отдельного сервиса, ни провайдеров, ни ключей. Провайдерские эмбеддинги выпилены: облачные каталоги не отдают эмбеддинг-модели, а качество локального e5 для наших коротких пропозиций выше (multilingual-e5 специально обучен на 100+ языках). Модель лениво загружается с HF Hub при старте ядра в персистентный кэш (/var/cache/rembed, volume rembed_cache; вне контейнера — кэш ОС, путь переопределяется REMBED_CACHE); до готовности подсказки работают в лексическом режиме.

Матчер подсказок многотирный: точные попадания тем/сущностей → термы (с IDF-фильтром: токены, живущие в большой доле корпуса, не считаются совпадением) → семантический тир на эмбеддингах. Семантический тир идёт ниже лексических, помечается semantic:<score> в matched_by, допускает до 3 кандидатов от косинуса ≥ 0.35 и держит зарезервированные места в бюджете подсказок, чтобы лексический шум не вытеснял смысловые совпадения.

#Как устроено (реализовано)

Движок инференса — pure-Go библиотека rembed в процессе ядра (KERNEL_EMBEDDINGS_MODEL, по умолчанию e5-small; KERNEL_EMBEDDING_WORKERS ограничивает CPU), без HTTP-хопа и внешних зависимостей.
Хранение — журнал-БД уже на pgvector: миграция добавляет к знанию вектор (размерность — под выбранную модель) и штамп версии модели эмбеддингов. Смена модели ⇒ фоновый пересчёт.
Наполнение — ingest-хук на knowledge.proposed/corrected + фоновый проход по записям без вектора/с чужим штампом.
Запрос — слот подсказки эмбеддит текст задачи; косинусная близость даёт новый тир в hintCandidate (между точными сущностями и IDF-лексикой), существующие механизмы (понижение за novelty B5, бюджеты, исходы) — без изменений. e5-префиксы: kernel добавляет query: к тексту слота и passage: к пропозициям знаний (rembed отдаёт текст как есть — без префиксов e5 молча теряет качество).
Деградация — модель не настроена/недоступна ⇒ ровно текущее лексическое поведение + счётчик пропусков в health.
Оценка эффекта — A/B по существующим исходам подсказок (helpful/harmful) до/после включения; золотые запросы в оценку.

Оценка объёма: миграция + клиент провайдера + ingest-хук + тир в матчере + бейдж в UI — один сосредоточенный релиз.

#7. Дальше (фаза 2+)

Отдельная страница супервайзера (реализовано, /supervisor и вкладка «Супервайзер» на дашборде): очередь проблем с кластерами (A1+A2), пояснения аномалий (A3), здоровье семантического слоя и эффективность тиров подсказок. Вкладка — только мониторинг: коэффициенты HAB и модели редактируются в Агентах → «Настройки качества» (одна поверхность правки, дашборд не второй редактор), вердикты закрываются кнопкой «Разобрано» (журналируется, ничего не применяет).
Волны B и C из §3 по одной за релиз, каждая — с флагом выключения (волны A, B и C целиком реализованы: триаж — KERNEL_SUPERVISOR_TRIAGE_INTERVAL, по умолчанию 2 минуты; инсайты и кейсы B/C едут в том же цикле, дедуп по субъекту; всё отключается KERNEL_SUPERVISOR_CASES=off).
Расширение capabilities: web (веб-исследования без raw-сети песочницы), ask_human (лимит человеческого внимания), mcp, artifacts, vision — точки принуждения: workspace/models.go (канонические имена), kernel/agent PrepareRun/advertisedTools, workspace run-config.