BRD — ORCH-074: фикс модели агентов (мёртвый frontmatter → валидация имени)

Work Item ID: ORCH-074 Эпик: ORCH-052 (слой 3), под-задача ORCH-52a Приоритет: urgent Тип: доработка механизма выбора модели агентов (self-modifying).

0. История ревизий

rev.1 (08.06): первичный пакет аналитики по фиксированному скоупу Славы.
rev.2 (08.06, текущая): задача возвращена стейкхолдером в In Progress. Проверены последние комментарии и описание issue в Plane — НОВЫХ субстантивных ответов/изменений скоупа нет (только bot-комменты + служебный маркер «Агент перезапущен с ответами стейкхолдера»). Скоуп остаётся прежним (G1 + G2 + опц. G4; G3 снят; эффорт не трогаем). Пакет переподтверждён против фактического кода (launcher.py, config.py); уточнён код-факт по G4: fallback читается напрямую на launcher.py:374 мимо resolve_agent_model, поэтому валидация G2 должна покрыть и fallback (детали — ТЗ §4, AC-5, TC-11).

1. Контекст и проблема

Каркас выбора модели агентов реализован в ORCH-041 и работает корректно: src/agents/launcher.py::resolve_agent_model(agent, project_id) резолвит модель по приоритету project-override → ORCH_AGENT_MODEL_<AGENT> → agent_model_default → CLI-дефолт. Все 6 агентов сейчас резолвятся в claude-opus-4-8 (через agent_model_default).

Аудит кода (08.06) выявил два дефекта данных/валидации (НЕ дефект механизма):

P1. Лживый/мёртвый model: во frontmatter .openclaw/agents/*.md. Все 6 промптов содержат model: в YAML-frontmatter: claude-sonnet-4-6 (analyst, developer, tester, deployer) и claude-opus-4-7 (architect, reviewer). launcher НЕ читает frontmatter model: — это мёртвая декларация, которая лжёт о реально используемой модели и нарушает принцип «документация = golden source». Мина: если кто-то «починит» launcher читать frontmatter → все агенты молча упадут на устаревшие модели.
P2. Нет валидации ИМЕНИ модели. В отличие от effort (есть VALID_EFFORTS-гард, невалидный effort логируется и дропается), имя модели не валидируется. Опечатка в agent_model_* / project-override → --model <мусор> → CLI падает или тихо деградирует. Нарушение принципа never-break.

2. Решение Славы (08.06) — фиксированный скоп

G3 model-routing НЕ включаем — ВСЕ 6 агентов остаются на claude-opus-4-8. Скоп: G1 (убрать лживый model: из frontmatter) + G2 (валидация имени модели, never-break) + опц. G4 (fallback_model — на усмотрение архитектора, НЕ routing). Эффорт НЕ трогать. AC-4 (routing) снят.

3. Бизнес-цели

ID	Цель	Драйвер
G1	Устранить лживый frontmatter: убрать `model:` из всех 6 `.openclaw/agents/*.md`. config — единственный источник правды модели.	Наблюдаемость (frontmatter не лжёт)
G2	Добавить валидацию имени модели: невалидное имя → лог + откат на default, никогда не передаётся в `--model`.	Надёжность (never-break)
G4	(опц., решает архитектор) Задать `agent_fallback_model` для страховки доступности.	Надёжность (availability)

4. Не-цели (явно вне скоупа)

G3 routing НЕ включаем. Все 6 агентов остаются claude-opus-4-8. AC-4 снят.
Эффорт НЕ трогать — уже корректно настроен (thinking → high, tester/deployer → medium).
Не менять resolve-механизм ORCH-041 — он корректен. Меняются только данные (frontmatter, опц. config) + добавляется валидация.
Не трогать non-self поведение — per-project override (projects.py agent_models) для enduro-trails остаётся рабочим.

5. Заинтересованные стороны

Owner (Слава) — зафиксировал скоп; деплой через штатный «Confirm Deploy».
Агенты оркестратора — потребители resolve-механизма (self-hosting).
Проект enduro-trails — НЕ должен пострадать (общий инстанс/БД/очередь).

6. Риски и инварианты

Self-hosting: изменение применяется к БУДУЩИМ запускам агентов. НЕ ломать текущий конвейер; не ронять прод-контейнер. Деплой только через «Confirm Deploy».
never-break: невалидная модель/эффорт НЕ должны ронять запуск агента — деградация на default/CLI-дефолт + лог.
frontmatter автогенерация: убедиться, что инструмент (если автогенерит frontmatter) не вернёт model: обратно. Frontmatter остаётся описательным (name/description/tools).
enduro per-project override не должен сломаться валидацией (валидные имена проходят без изменения поведения).

7. Бизнес-эффект

Frontmatter перестаёт лгать → меньше риск «починки», ломающей агентов.
Опечатка в имени модели больше не роняет/деградирует запуск агента.
(опц.) fallback повышает доступность при перегрузке основной модели.

6.8 KiB Raw Permalink Blame History Unescape Escape