ddadminandClaude Fable 5
43a93cd3c3
- Зачем: - боевой прогон 2026-07-22 (конвейер issue #5 в демо-стенде) прошёл через плагин-обёртку Codex и воспроизвёл её известные баги; ресёрч 2026-07-07 давно рекомендовал прямой CLI, но в скилл не был поглощён. - Что: - roles.md: третий режим «Канал командной строки» — codex exec фоном у координатора, resume треда, плагин только для интерактива; - SKILL.md: передача владения только после остановки прежнего владельца; проверка команд сценария на живом объекте до прогона; - lessons.md: два датированных наблюдения 2026-07-22, вопрос №9 переориентирован на проверку CLI-канала боем. - Проверка: - перечитка трёх файлов на связность и отсутствие дублей; следующий прогон конвейера — по CLI-каналу. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
208 lines
14 KiB
Markdown
208 lines
14 KiB
Markdown
# Уровни и роли
|
||
|
||
Маршрутизация моделей обновлена 2026-07-13. Имена и уровни здесь — датированная
|
||
настройка среды; логика [основной оптики](../SKILL.md) остаётся относительной.
|
||
|
||
Читай этот файл только при настройке ролей или когда нужная роль недоступна.
|
||
[Основная оптика](../SKILL.md) описывает, когда отдельный агент вообще нужен.
|
||
Этот файл — условные настройки мандата, а не список обязательных участников.
|
||
Один агент может совмещать совместимую работу; не создавай тред на каждое имя.
|
||
|
||
- [Возможности хоста](#возможности-хоста)
|
||
- [Выбор уровня](#выбор-уровня)
|
||
- [Текущая маршрутизация](#текущая-маршрутизация)
|
||
- [Возможные мандаты](#возможные-мандаты)
|
||
- [Файл пользовательского агента](#файл-пользовательского-агента)
|
||
- [Пределы параллельности](#пределы-параллельности)
|
||
|
||
## Возможности хоста
|
||
|
||
Сначала установи, позволяет ли текущий хост выбрать пользовательского агента
|
||
и его конфигурацию, а для линии другого семейства — каким каналом её
|
||
запускать.
|
||
|
||
- **Управляемая стоимость.** Хост видит агентов из `~/.codex/agents` или
|
||
`.codex/agents` и схема `spawn_agent` открывает `agent_type`, `model` и
|
||
`reasoning_effort`. Для TOML-роли передавай `agent_type`, а модель и
|
||
глубину бери из её файла. Для разового выбора передавай `model` и
|
||
`reasoning_effort` без пользовательской роли с закреплённой моделью.
|
||
Плейбук использует `fork_turns="none"` ради чистого контекста. Технически
|
||
ограниченный fork числом тоже допускает переопределения; только полный
|
||
fork `all` наследует модель координатора и отклоняет их.
|
||
- **Неуправляемая стоимость.** Интерфейс запуска принимает только задачу и
|
||
имя треда. Передавай роль мандатом в промпте, но не утверждай, что выбрана
|
||
дешёвая или сильная модель. `task_name` — идентификатор треда, а не выбор
|
||
конфигурации агента.
|
||
- **Канал командной строки.** Хост другого семейства запускай напрямую:
|
||
`codex exec` в собственной фоновой команде координатора — pid, код выхода
|
||
и лог принадлежат координатору, а не посреднику. Модель и effort задавай
|
||
явно; тред продолжай через `codex exec resume <session-id>`.
|
||
Плагин-обёртку с фоновыми задачами для конвейера не используй: известные
|
||
сбои — ложный «started» с подменой ответа, зависшие фоновые ревью, воркеры
|
||
без признаков жизни (openai/codex-plugin-cc issues #279, #158, #49, #277);
|
||
она годится только для интерактива по явному запросу партнёра.
|
||
|
||
Если способ выбора роли не виден в доступном инструменте, считай стоимость
|
||
неуправляемой, отметь это в итоговом отчёте и не разделяй совместимую работу
|
||
на дополнительные роли без явной пользы.
|
||
|
||
Вызов TOML-роли:
|
||
|
||
```json
|
||
{
|
||
"task_name": "explore_code",
|
||
"message": "Исследуй код и верни выжимку по договору роли.",
|
||
"fork_turns": "none",
|
||
"agent_type": "explorer"
|
||
}
|
||
```
|
||
|
||
Разовый выбор модели без TOML-роли с закреплёнными настройками:
|
||
|
||
```json
|
||
{
|
||
"task_name": "explore_code",
|
||
"message": "Исследуй код и верни выжимку по договору результата.",
|
||
"fork_turns": "none",
|
||
"model": "<быстрая модель>",
|
||
"reasoning_effort": "medium"
|
||
}
|
||
```
|
||
|
||
Не смешивай режимы: роль применяется отдельным слоем конфигурации и может
|
||
перекрыть прямые параметры. `service_tier` передавай только по явному запросу;
|
||
он технически совместим и с полным fork. Если TOML-роль закрепляет
|
||
`service_tier`, значение роли перекрывает аргумент вызова; для гарантированного
|
||
разового tier используй роль без закреплённого tier.
|
||
|
||
Основание: [официальная документация о субагентах](https://learn.chatgpt.com/docs/agent-configuration/subagents)
|
||
и [актуальная схема `spawn_agent`](https://github.com/openai/codex/blob/main/codex-rs/core/src/tools/handlers/multi_agents_spec.rs).
|
||
|
||
## Выбор уровня
|
||
|
||
| Уровень | Для чего | Настройка |
|
||
|---|---|---|
|
||
| Быстрый | Поиск, журналы, известные проверки, ограниченная механика | Дешёвая подходящая модель, обычно `medium` |
|
||
| Рабочий | Обычная реализация и проверка по задаче | Подходящая ролевая модель, `medium` |
|
||
| Глубокий | Архитектура, сложная реализация, ревью кода | Сильная модель, `high` |
|
||
| Исключительный | Необратимое решение или несходимость сильных агентов | Самая сильная модель, `max` |
|
||
|
||
Модель задаёт потолок способности, effort — глубину работы этой модели.
|
||
Повышай effort, когда подходящей модели не хватило поиска или рассуждения.
|
||
Повышай модель, когда не хватает качества решения. После двух слабых
|
||
результатов замени исполнителя свежим более сильным агентом вместо переноса
|
||
его неудачного контекста.
|
||
|
||
`xhigh` не является автоматической ступенью: текущая эмпирика показывает
|
||
малый прирост относительно `high` при заметной цене. Выбирай его вручную для
|
||
узкой задачи. `max` заметно сильнее и дороже; используй по явному триггеру и
|
||
объясняй партнёру причину.
|
||
|
||
## Текущая маршрутизация
|
||
|
||
Это начальная рабочая таблица, а не рейтинг моделей. Проверяй её на прогонах и
|
||
меняй после согласования эмпирики с партнёром.
|
||
|
||
| Роль | Модель и effort |
|
||
|---|---|
|
||
| Простая ограниченная реализация, `fast-worker`, известная проверка | Luna `medium` |
|
||
| Узкий обзор постановки, проверка реализации по задаче | Terra `medium` |
|
||
| Обычная нетривиальная реализация | Sol `medium` |
|
||
| Сложная или рискованная реализация | Sol `high` |
|
||
| `deep-reasoner`: архитектурное предложение, декомпозиция, компромиссы | Sol `high` |
|
||
| Ревью кода | Sol `high` |
|
||
| Необратимое решение, спор сильных агентов, повторная несходимость | Sol `max` |
|
||
|
||
Официальное назначение текущих уровней семейства — в
|
||
[каталоге моделей OpenAI](https://developers.openai.com/api/docs/models).
|
||
Конкретные имена держи здесь и в конфигурации агентов, а не в `SKILL.md`.
|
||
|
||
## Возможные мандаты
|
||
|
||
### `fast-worker`
|
||
|
||
Уровень: быстрый. Читает шумный ввод, запускает проверки, выполняет простые
|
||
пакетные операции. Возвращает только выжимку и пути к полным журналам.
|
||
|
||
Обычно: `sandbox_mode = "workspace-write"`, потому что тесты и инструменты
|
||
создают временные файлы. В инструкциях ограничить изменения явно названной
|
||
механикой.
|
||
|
||
### `explorer`
|
||
|
||
Уровень: быстрый. Строит карту кода, находит точки входа, контракты и команды
|
||
проверки. Не запускает полный набор тестов и не проектирует решение, пока
|
||
координатор прямо не попросит. Узкую команду запускает только для проверки факта,
|
||
без которого карта ненадёжна.
|
||
|
||
Обычно: `sandbox_mode = "read-only"`.
|
||
|
||
### `worker`
|
||
|
||
Уровень: рабочий или глубокий по сложности задачи. Единственный владелец
|
||
реализации. Читает самодостаточный файл-задачу, меняет код и проверяет свою
|
||
часть. Не делает коммит.
|
||
|
||
Обычно: `sandbox_mode = "workspace-write"`.
|
||
|
||
### `deep-reasoner`
|
||
|
||
Уровень: глубокий. Принимает одно сложное решение: архитектура, алгоритм,
|
||
диагноз, противоречие требований. Возвращает предложение, ключевые доводы и
|
||
непроверенные предположения; итоговое решение принимает координатор.
|
||
|
||
Обычно: `sandbox_mode = "read-only"`.
|
||
|
||
### `reviewer`
|
||
|
||
Уровень: глубокий. Свежий тред без истории исполнителя. Ищет ошибки
|
||
корректности, безопасности, контракта и тестов. Каждая находка содержит
|
||
сценарий сбоя, доказательство, влияние и способ проверки.
|
||
|
||
Для полноценного ревью обычно нужен `sandbox_mode = "workspace-write"`: тесты,
|
||
кэши, временные артефакты и исследование не следует урезать ради запрета
|
||
правок. Исходники и постоянное окружение защищает явный мандат, Git сверяется
|
||
до и после. Доступ к сети проверять отдельно: право записи не гарантирует
|
||
поиск и документацию. Непроверенную внешнюю механику отмечать как гипотезу.
|
||
Канал результата от песочницы не зависит. При выбранном ревью используй
|
||
[единый договор](review-and-triage.md): назначенный файл отчёта — единственный
|
||
результат наблюдателя; временные кэши допустимы, исходники и Git неизменны.
|
||
|
||
### `verifier`
|
||
|
||
Уровень: быстрый. Запускает уже известные команды приёмки, разбирает сбои и
|
||
возвращает счётчики. Не ищет новые требования и не исправляет продуктовый
|
||
код.
|
||
|
||
Обычно: `sandbox_mode = "workspace-write"`.
|
||
|
||
## Файл пользовательского агента
|
||
|
||
Роли Codex хранятся в `~/.codex/agents/*.toml` или `.codex/agents/*.toml`.
|
||
Минимальный шаблон:
|
||
|
||
```toml
|
||
name = "role-name"
|
||
description = "Когда координатору выбирать эту роль."
|
||
model = "<актуальная модель нужного уровня>"
|
||
model_reasoning_effort = "medium"
|
||
sandbox_mode = "read-only"
|
||
developer_instructions = """
|
||
Одна узкая роль и её договор результата.
|
||
"""
|
||
```
|
||
|
||
Не подменяй выбор роли совпадением `task_name` с её именем: это работает
|
||
только при явной гарантии хоста. После добавления или изменения TOML начни
|
||
новую сессию и проверь, что имя роли появилось в описании `agent_type`.
|
||
|
||
## Пределы параллельности
|
||
|
||
- Держи глубину `1`: субагенты не создают собственное дерево исполнителей.
|
||
- Оставляй один слот координатору.
|
||
- Параллельно запускай только работу без конфликтующих входов, команд и
|
||
изменяемого состояния. Второй слепой обзор добавляй ради отдельной линии, а
|
||
не ради заполнения свободного слота.
|
||
- Реализацию и починку одного рабочего дерева выполняй последовательно одним
|
||
владельцем.
|