# Задание A28: субагенты и реестр ролей ## Дата поступления 2026-08-25 ## База Проверочный HEAD на момент выдачи: **`d5429da`**. ## Ветка `antigravity/subagents-role-registry` ## Порядок исполнения Два прохода: **Flash** реализует, **Pro** проводит аудит. Пункт **P0-5** написан для аудитора. Это **первое** из трёх заданий по новому фронтенду (A28, A29, A30) и **основа для остальных**: главный экран рисует агентов, поэтому агенты должны появиться раньше экрана. A29 и A30 опираются на реестр ролей отсюда. --- ## Порядок работы с git ``` cd <каталог репозитория>; git fetch origin --prune; git status git checkout main; git pull --ff-only origin main git checkout -b antigravity/subagents-role-registry git commit -m "..." <- сначала коммит git push -u origin antigravity/subagents-role-registry ``` В `main` напрямую не пушить. В конце — push, `git log --oneline -1`, `git status` чистый. --- ## Задача Сейчас в системе **шесть** ролей. Владелец хочет двенадцать — полноценную команду субагентов с внятно расписанными обязанностями. Список и формулировки даны им дословно и приведены ниже; **менять их смысл нельзя**. --- ## Что проверено исполнением — заново не выясняйте **1. Новая роль добавляется через конфигурацию и доходит до снапшота.** ``` ролей в умолчаниях: 6 -> orchestrator, coder-primary, coder-secondary, reviewer, research, fast после добавления роли tester в router_profiles.yaml: True видна ли в снапшоте: True ``` Архитектуру ломать не нужно: `config.roles` уже произвольный словарь. **2. Но подпись падает в сырой идентификатор.** У добавленной роли `role_name_ru` оказался `tester`, а не человеческое имя, потому что таблица подписей зашита в код: ``` unified_health.py:775 ROLE_NAMES = {...} семь записей auto_assigner.py:28 HUMAN_ROLE_LABELS = {...} одиннадцать записей ``` **3. Список ролей зашит ещё в двух местах:** ``` auto_assigner.py:371 canonical_roles = ["orchestrator", "coder-primary", ...] telemetry_service.py:402 roles = set(known_roles or ["orchestrator", ...]) ``` Пока эти списки литеральные, новые роли будут выпадать из авто-распределения и из аналитики. **4. Понятия «субагент» как сущности нет.** `universal_subagent` в `auto_assigner` — это подпись слота, а не отдельный агент. Файлов агентов (`agents/*.md`) в проекте нет вовсе. --- ## P0-1. Реестр ролей вместо литералов Завести **один** источник истины для ролей: идентификатор, человеческое имя, описание обязанностей, порядок отображения. Все четыре места выше должны читать оттуда. Литеральных списков ролей в коде остаться не должно — проверяется поиском. Реестр обязан оставаться **расширяемым**: владелец добавляет роль в конфигурацию, и она появляется всюду — в маршрутизации, в обзоре, в аналитике, в авто-распределении — с человеческой подписью, а не с сырым идентификатором. ## P0-2. Двенадцать ролей и их обязанности Формулировки владельца. Описание каждой роли обязано быть **видно в интерфейсе** — на карточке агента и в инспекторе, а не только в конфигурации. | Идентификатор | Имя | Обязанности | |---|---|---| | `researcher` | Исследователь | Изучает данные, кодовую базу, документацию и внешние источники, чтобы собрать информацию для решения задачи. | | `developer-1` | Разработчик 1 | Пишет код, реализует функционал, исправляет ошибки. | | `developer-2` | Разработчик 2 | Проверяет код Разработчика 1 и выдаёт ему задание на исправление. | | `code-reviewer` | Код-ревьювер | Анализирует код на ошибки, проблемы безопасности и соответствие стандартам. Работает **после** Разработчика 2. | | `tester` | Тестировщик | Создаёт тесты, проверяет корректность работы кода, находит дефекты. | | `tech-writer` | Технический писатель | Создаёт документацию, инструкции, README. | | `analyst` | Аналитик | Проводит глубокий анализ данных, выявляет тренды, строит прогнозы. | | `guardian` | Надзиратель (агент безопасности) | Проверяет входящие инструкции на промпт-инъекции, анализирует планы и вызовы инструментов, блокирует обход системных правил, не допускает утечки секретов, следит за границами песочницы. | | `cost-controller` | Агент контроля затрат | Оценивает планируемый расход токенов, сравнивает с остатком бюджета, предлагает упрощения, сверяет факт с прогнозом, останавливает цепочку при исчерпании лимита. | | `manager` | Менеджер (планировщик) | Определяет стратегию, распределяет ресурсы, контролирует ход выполнения. | | `integration-expert` | Специалист по интеграции | Работает с API и внешними сервисами, отправляет вебхуки. | | `security-expert` | Юрист / специалист по безопасности | Проверяет код и данные на уязвимости. | Порядок в таблице — порядок отображения. **Существующие шесть ролей не удалять и не переименовывать молча.** У владельца в конфигурации на трёх машинах живут `orchestrator`, `coder-primary`, `coder-secondary`, `reviewer`, `research`, `fast`, и на них ссылаются цепочки. Предложите соответствие старых новым (например `research` → `researcher`, `coder-primary` → `developer-1`) и **проведите миграцию**, сохранив цепочки. Соответствие описать в отчёте; спорные случаи вынести владельцу, а не решать молча. ## P0-3. Надзиратель и контроль затрат — особый случай Эти двое отличаются от остальных: они не выполняют задачу пользователя, а **проверяют** работу других. Задание **не требует** реализовывать их поведение — это отдельная работа. Требуется: 1. Завести их как роли наравне с прочими, с полным описанием обязанностей в интерфейсе. 2. **Честно показать, что исполнение ещё не реализовано.** Не рисовать зелёный статус «Работает» у агента, который ничего не делает. Состояние «Роль объявлена, исполнение не реализовано» — допустимо и честно; выдуманная активность — нет. Правило проекта без исключений: ни одного статуса, числа или метрики без основания. ## P0-4. Двенадцать ролей и квоты Двенадцать агентов на нескольких аккаунтах — это про распределение нагрузки, и здесь легко всё сломать. - Один аккаунт по-прежнему может обслуживать несколько ролей (проверено в A26, движок это держит). - Авто-распределение из A26 обязано работать и на двенадцати ролях: при одном провайдере он встаёт во все двенадцать, при нескольких — по назначению. - Пороги квот из A26 не должны деградировать. Прогоните авто-распределение на двенадцати ролях и приложите вывод. ## P0-5. Аудит вторым проходом 1. **Литеральные списки ролей.** Пройдите поиском по `orchestrator`, `coder-primary`, `reviewer` и убедитесь, что нигде не осталось зашитого перечня. Именно из-за таких списков добавленная роль показывалась как `tester`. 2. **Выдуманные статусы.** Особый риск в P0-3: у нереализованных ролей не должно быть активности, метрик и зелёных индикаторов. 3. **Миграция конфигурации владельца.** Проверьте на копии его `router_profiles.yaml`, что цепочки уцелели и маршрутизация работает. Конфигурацию литералами не править. 4. **Запустить изменённое**, а не только импортировать. 5. **Побочные изменения** объяснить. 6. **Пропущенный пункт назвать пропущенным.** --- ## Ограничения - Десктоп (`router/ui/**`) не трогать. - Ваша зона: `auto_assigner.py`, `unified_health.py`, `telemetry_service.py`, `router_config.py`, конфигурации, соответствующие тесты и минимальные правки веб-клиента для показа описаний. - Граф workflow и связи между агентами — **не здесь**, это A30. Не начинайте. - Дизайн-система и темы — **не здесь**, это A29. - Правило честности без исключений. - Тег `v0.1.1` не создавать. ## Критерии приёмки 1. Ветка в `origin`, `git status` чист. 2. Двенадцать ролей заведены, у каждой человеческое имя и описание обязанностей; описание видно в интерфейсе. 3. Литеральных списков ролей в коде не осталось; проверено поиском, результат в отчёте. 4. Добавление роли в конфигурацию даёт человеческую подпись всюду; проверено на роли, которой нет в реестре по умолчанию. 5. Существующие шесть ролей мигрированы, цепочки владельца уцелели; проверено на копии его конфигурации. 6. Авто-распределение отработало на двенадцати ролях; вывод приложен. 7. У ролей без реализации исполнения нет выдуманной активности и метрик. 8. `ruff check .` чисто; релизный гейт не ухудшен. 9. Отчёт: `START_HEAD`, `FINAL_HEAD`, `origin/main`, `git status`, `X passed / Y skipped / Z failed`. На `main` сейчас **450 passed, 2 skipped**. ## Главное Двенадцать субагентов с внятными обязанностями — основа нового главного экрана. Пока роли зашиты литералами, ни новый экран, ни маршрутизация из A29 нормально не заработают. ## Порядок сдачи Передать точный `FINAL_COMMIT_SHA`. Сдано только после появления коммита в `origin`.