Глоссарий
Термины ниже — это единый язык (ubiquitous language): имя на экране то же, что в коде, в событии и в ADR. Некоторые из них существуют в других местах с более широким значением — эта страница говорит, что они значат в этой системе.
Упорядочено по темам, потому что искать «harness», не зная, что это понятие агента, приходится редко; обычно приходят через тему.
Сессия и событие
Сессия — разговор с эффектом, от начала до закрытия. Это единица работы, стоимости и трассировки: сессия — корневой trace в наблюдаемости и область бюджета. Она проходит через пять состояний (RN-001).
Журнал событий — таблица session_events. Только дополнение: UPDATE
никогда не бывает. У каждой строки непрерывный seq внутри сессии. Это
источник истины о том, что произошло, и то, что делает доказательства
Psicólogo отслеживаемыми
(RN-002).
seq — порядковый номер события внутри сессии. Плотный: начинается с 1 и
не имеет пропусков. Пропуск в seq — это повреждение, и восстановление из-за
него завершается ошибкой.
closing — переходное состояние, а не состояние покоя. Сессия,
застрявшая в closing, означает, что drain начался и не закончился; для этого
есть алерт.
Сирота — сессия active в api без живого процесса-владельца в engine. Это
режим отказа, ради устранения которого существует graceful shutdown;
операционное определение — в runbook.
Outbox — паттерн transactional outbox. api записывает событие и намерение его опубликовать в одной транзакции; engine потребляет его позже через Oban. Именно это не даёт «событие записано» и «engine узнал» когда-либо разойтись. Redis нет — очередь живёт в Postgres.
Агенты
Агент — долгоживущий процесс с ролью и идентичностью. Сегодня одиннадцать
канонических ролей, определённых в
apps/engine/lib/engine/harness/agents.ex:
| slug | роль |
|---|---|
criativo | ведёт идеацию с пользователем и выпускает бизнес-правила |
po | превращает бриф в бэклог (эпики, истории, задачи) с DoD и DoR |
arquiteto | технические решения (ADR), карта модулей и контракт между модулями (RN-684) |
dev-backend · dev-frontend | реализуют; работают в изолированном worktree |
infra | провижининг, деплой и окружения — проактивный, а не исполнитель |
qa | семантический гейт: тесты и критерии приёмки |
secops | детерминированный гейт: секреты, безопасность, соответствие требованиям |
psicologo · psicologo-leve | анализируют сессии и предлагают гипотезы с доказательствами |
anamnese | профилирует компетенции пользователя и предлагает патчи инструкций |
Имена — это продуктовые роли, с заглавной буквы при использовании как
существительное («Arquiteto предложил ADR»). Разработчики динамические: один
агент на модуль module_map, а не фиксированный список.
Контракт между модулями (ADR 0200) —
версионированный artifact.module_contracts от Arquiteto: для каждого модуля —
что он ПРЕДОСТАВЛЯЕТ (функция, маршрут, событие или форма данных, с
сигнатурой). То, что он потребляет, — это dependsOn из module_map. Dev agent
читает его через listar_contratos_de_modulos вместо worktree другого
разработчика.
Область (Фаза 8b/8c, ADR 0038) —
qa и infra из таблицы выше стали LEAD-ами областей: они остаются
единственным внешним контактом (тот же slug, то же поведение снаружи), но
теперь делегируют субагентам — qa-automacao/qa-performance-seguranca
(QA), infra-workflows (Infra). Делегирование — ВНУТРЕННИЙ механизм области,
никогда не хэндофф; то, что область возвращает наружу, остаётся единственным
артефактом (qa_verdict, open_infra_pr) — потребитель никогда не знает, что
за ним стоит больше одного агента.
Harness — обязательная обёртка для каждого агента. Ни один вызов LLM или инструмента не происходит вне её. Пять частей:
| часть | делает |
|---|---|
| PromptAssembler | собирает промпт упорядоченными слоями с бюджетом токенов на слой и детерминированным усечением — тот же контекст, тот же промпт |
| ContextManager | сжимает, когда контекст растёт |
| ToolLoop | цикл запрос инструмента → выполнение → результат, с потолком итераций |
| InstructionFiles | разрешает файлы AGENTS.md в порядке возрастания приоритета (корень → каталог → база данных) |
| Hooks | точки перехвата вокруг цикла |
Слой (промпта) — блок с id, содержимым и политикой усечения
(truncate_tail, keep_or_drop, drop_whole_units). Бюджет задаётся на слой,
и именно это делает усечение предсказуемым вместо «что влезло, то влезло».
ToolLoop — цикл агента. Ход — это: собрать промпт → вызвать модель → модель
запрашивает инструмент → инструмент становится proposed_action → политика
решает → выполнение → результат возвращается в контекст. У него есть потолок
итераций; когда он исчерпан, агент завершается блокирующим артефактом.
Ход (диалоговый агент) — один раунд работы одного из диалоговых агентов в
рамках сессии (Criativo, PO, Arquiteto, Dev Lead, UX Designer, Staff — начиная с
ADR 0088, спящий для автоматического запуска, но активируемый ручным хэндоффом
— и, начиная с RN-617, Infra Lead): один потоковый
вызов LLM плюс цикл инструментов, который он запускает. Начиная с
RN-122 он выполняется в контролируемом Task
(Engine.Agents.TurnoAssincrono), а не внутри handle_call, получившего
сообщение, — именно это позволяет кнопке «Стоп» в композере действительно
отменять ход (убивает task, разрывает соединение с api), а не просто
останавливать отрисовку на клиенте. Начиная с
RN-578 на команду, запускающую ход, отвечают при
ПРИНЯТИИ: клик возвращается, как только Task поднят, а конец хода приходит через
канал сессии и журнал событий, никогда через этот HTTP-ответ. У каждого
СОБСТВЕННЫЙ потолок раундов цикла (Criativo и PO 12, Arquiteto, Dev Lead,
UX Designer, Staff и Infra Lead 14) — это константа на собственном сервере
агента, а не потолок ToolLoop (Engine.Harness.Iteracoes), который относится к
агентам выполнения и гейтов. Staff — единственный без kickoff/1: он остаётся в
простое до первого user_message, потому что нет артефакта сессии, из которого
можно синтезировать начало. Из четырёх, существовавших на тот момент, Criativo
получил цикл последним, через
RN-163: до этого он вызывал модель один
раз за ход и обещал исправление, которого никогда не было. Этот собственный
потолок тоже перестал быть молчаливым: когда он исчерпан, выпускается ТОТ ЖЕ
toolloop.limit_reached (RN-166),
потому что это тот же факт, и читающему журнал событий не нужно второе имя для
него.
Регидратация (диалоговый агент) — как процесс диалогового агента
восстанавливает свою историю из журнала событий, когда поднимается над сессией,
в которой уже есть разговор (перезапуск или PO, принимающий работу от Criativo).
Один путь для всех семи, Engine.Agents.Reidratacao
(RN-580): он читает хвост (последние 200
событий, а не первые), возвращает структурированные вопросы и собственные
вызовы инструментов агента, а когда разговор не помещается, начинает с
системного сообщения, сообщающего, сколько более ранних событий было опущено.
Хэндофф — явная передача работы от одного агента другому. Явная, потому что адресат и причина записываются в журнал событий, вместо того чтобы один агент неявно «перехватывал» контекст другого.
Артефакт — структурированный, валидированный результат агента. Двенадцать
закрытых схем (note, business_rule, product_brief, decision_record,
plano_de_teste, prototipo_navegavel, threat_model, task_blocked,
qa_verdict, secops_verdict, infra_delegation_files): отсутствующее поле
проваливает выпуск. Так вердикт гейта становится данными, а не текстом.
business_rule проваливается и по второй причине: заголовок, уже
зарегистрированный в проекте (RN-080) —
поскольку артефакт является неизменяемым событием, выпуск — единственный момент,
когда дубликат можно отклонить.
Worktree — git worktree: рабочая копия, изолированная для каждого dev
agent, над одним и тем же репозиторием. Два разработчика работают с разными
ветками, не мешая друг другу. Он на агента, а не на задачу: кто берёт
следующую задачу, заменяет каталог, и именно это вынуждает агента удерживать
его, пока гейту ещё нужно его читать.
Режим workspace — где код проекта живёт на диске, выбирается при создании и
затем замораживается
(ADR 0072,
RN-169). container — управляемая
папка под PROJECT_WORKSPACES_ROOT, значение по умолчанию и обычное поведение;
local — собственный абсолютный путь пользователя, который работает, только
если он смонтирован в контейнер. Не путайте с workspace из IAM (группировка
проектов и участников): одно слово для разных вещей, а режим касается диска.
Состояния dev agent — working (реализует), awaiting_approval (предложил
commit/push/PR, и одно из них ждёт одобрения — ни один гейт не открывается без
PR, RN-050), awaiting_gate (PR открыт,
ждёт вердикта), idle (нет задачи для взятия, процесс жив) и idle_tripped
(сработал circuit breaker, выход только через явное перевзведение —
RN-047). Первые три удерживают worktree.
idle охватывает три разные причины, намеренно: очередь была пуста, взятие
не удалось и — начиная с RN-502 — у проекта нет
контейнера, ЗАРЕГИСТРИРОВАННОГО как running, что останавливает взятие до того,
как оно произойдёт. Для последней нет четвёртого статуса: idle —
единственное состояние, из которого wake ещё спасает, и каждый guard в
handle_info/2 привязан к нему. Различает три причины СОБЫТИЕ (dev.idle,
dev.error, dev.blocked_by_container), которое долговечно, а не статус.
Одобрение
proposed_action — каждое действие с внешним эффектом (команда терминала,
commit, push, PR, merge, расход) рождается здесь и никогда не выполняется
напрямую. Всего 21 тип и 6 состояний
(RN-003).
permissions.json — файл политики проекта. Сопоставляет шаблон команды
(структурно, не по подстроке) и возвращает allow, deny или
require_approval.
deny побеждает allow — правило, проходящее через всю систему. Решение
оценивает IAM → agent_autonomy → permissions.json, и deny на любом этапе
возвращается немедленно
(RN-004).
Потолок — понижение, применяемое после всей политики, выше которого никакая конфигурация не может поднять. Их два: merge в защищённую ветку (RN-006) и патч инструкции (RN-007). Потолок — это разница между «нет по умолчанию» и «нет».
agent_autonomy — режим работы агента в проекте: manual (каждое действие
запрашивает одобрение) или автоматический. Это первый переключатель, который
нужно перевести при инциденте со стоимостью.
Защищённая ветка — dev, qa, rc, main. Merge в любую из них —
всегда решение человека. Эквивалентная защита на платформе (GitHub/GitLab)
различается между провайдерами и не является гейтом — гейт это домен
(ADR 0028).
Гейты и выполнение
Гейт — обязательный шлюз между PR разработчика и merge. Их два: QA
(семантический, запускает LLM) и SecOps (детерминированный, запускает
сканер). Порядок неизменен:
awaiting_qa → awaiting_secops → awaiting_user
(RN-014).
awaiting_user — терминальное состояние машины гейтов. Терминальное
намеренно: система никогда не делает merge сама.
changes_requested — гейт, возвращающий работу разработчику, в той же
ветке. Новый PR не открывается.
Цикл K — потолок исправлений на задачу. Каждый возврат расходует один раунд; когда они исчерпаны, задача блокируется с причиной вместо бесконечного вращения. Субагент наследует потолок базового агента (RN-015).
task_blocked — артефакт, выпускаемый, когда задача застревает: несёт
reason и diagnosis. Это читаемая запись о сбое, а не молчание.
Припаркованный цикл гейта — цикл QA/SecOps, оставшийся in_progress без
активности более 2 часов. GateRescuer больше не возобновляет его сам (при
загрузке или по своему тику): он записывает gate.rescue_parked и
устанавливает parked_at, и возобновить его может только жест человека —
сегодня GateRescuer.retomar_estacionado/3 через bin/engine rpc оператора
(ADR 0207,
RN-722). Цикл, у сессии которого есть одобрение,
ожидающее от актора гейта, тоже не перезапускается: он ждёт вас. НЕДАВНИЙ цикл
in_progress, который убил сам перезапуск engine, не паркуется и не ждёт
15-минутного порога: при загрузке, если ни один узел кластера не держит его в
работе, rescuer записывает gate.interrupted и сразу перезапускает его
(RN-823).
Гейт implementavel (реализуемость) — шлюз ДО разработки, до появления dev
agent или worktree: Dev Lead оценивает, реализуема ли история, исходя из самой
истории и текущего module_map (до
ADR 0192 входом был план
тестирования QA-стратегии). dono: dev-lead, aprovacao_humana: true,
severidade: warn
(ADR 0090).
QA-стратегия — qa-lead во втором МОМЕНТЕ (тот же процесс, результат,
отдельный от вердикта PR): он создаёт план тестирования (синтез,
исполняемые критерии, стратегия автоматизации) для ПОСТАВКИ ОДНОЙ задачи, ПОСЛЕ
того как dev agent её выполнил, — первый шаг проверки qa-verificada, как вход
для неё, никогда не собственный вердикт
(RN-674,
ADR 0192). Никогда не
приостанавливается — ни один из его инструментов не проходит через конвейер
действий.
AppSec — secops во втором МОМЕНТЕ, та же форма, что у QA-стратегии над
qa-lead: ТОТ ЖЕ процесс (SecOpsAgentServer.run_design/2) создаёт модель
угроз STRIDE-lite по ДИЗАЙНУ истории — без worktree, без task_id, до
появления какого-либо кода или PR. Он никогда ничего не одобряет и не
отклоняет; он завершается выпуском artifact.threat_model и передаёт его
Arquiteto, Dev Lead и Infra. Запускается assess_implementability от Dev Lead,
параллельно, один раз на историю
(RN-360, RN-539,
ADR 0090).
Бэклог и архитектура
Бизнес-правило (RN) — единица, выпускаемая Criativo и привязанная к историям. Правило без истории — это пробел в покрытии, а не ошибка (RN-011).
История — четыре состояния; выход из draft требует DoD, DoR, как минимум
одного функционального требования и как минимум одного связанного правила
(RN-010).
DoD / DoR — Definition of Done и Definition of Ready. Здесь это не церемония: без обоих история не меняет состояние.
module_map — карта модулей системы от Arquiteto. Определяет, сколько
существует dev agent (по одному на модуль) и к какому модулю относится каждая
история. Не может содержать цикл (RN-013);
удалённый модуль понижает истории, которые от него зависели
(RN-012).
Образ проекта (artifact.project_image) — решение Arquiteto о том, какой
контейнер запускает код проекта: OCI-образ (обязателен явный тег, latest
отклоняется), сетевой режим (none по умолчанию, egress разрешён) и потолок
ресурсов. Версионируется в журнале событий, как module_map. Пока его нет,
состояние sem_decisao (нет решения) держит вкладку Code закрытой
(RN-105).
Стоимость
Учёт потребления (metering) — запись потребления по каждому вызову в
token_usage: токены, стоимость в микроединицах, задержка, модель, агент. Это
запись, а не возврат средств.
Бюджет — потолок расходов с исключительной областью: проект или сессия, никогда оба (RN-017). Уведомляет на 70/90/100% без повторов.
policy — поведение бюджета на потолке: block отклоняет вызов, allow
только записывает его. Проект с allow не останавливается сам — это самая
частая причина «бюджет не удержал»
(RN-019).
Binding — связь между областью и моделью LLM. Разрешается каскадом:
сессия > агент > область > проект > workspace, первое существующее
(RN-020). Поэтому можно поставить дорогую
модель только на QA. area — это значение ПО УМОЛЧАНИЮ, общее для lead и его
субагентов, и агент может от него отличаться
(RN-102).
Грань capability — то, что провайдер объявляет о модели: читает
изображения, генерирует изображения, делает thinking, принимает tools.
Приходит из удалённого каталога при синхронизации; false означает «не
объявил», а никогда не «не умеет»
(RN-056).
Использование модели — для чего этот workspace использует модель
(codigo, documentacao, analise, imagem, conversa). Это мнение
оператора, а не capability: ни один каталог не публикует «хороша для кода».
Пометка использования не включает модель в селекторе
(RN-057).
Psicólogo и Anamnese
Гипотеза — результат Psicólogo: утверждение о команде с evidenceEventIds,
указывающими на реальные события анализируемой сессии. Без действительных
доказательств она не записывается (RN-021).
Причина завершения — детерминированная классификация того, почему что-то
сломалось: infra, modelo, código или política. Берётся из
записанной причины, никогда из суждения LLM и никогда методом исключения
(RN-023).
proficiency_profile — профиль компетенций пользователя, поддерживаемый
Anamnese, по каждой компетенции. Шесть процессных компетенций, закрытый
список (git, agile, arquitetura, testes, seguranca, infra), плюс
технические стеки, выведенные из module_map. Ничто вне каталога не имеет пути
записи (RN-024) — Anamnese профилирует техническую
компетенцию, а не человека.
Допустимый субъект — кого может профилировать раунд Anamnese: ДЕЙСТВУЮЩИЙ участник проекта (строка проекта, а иначе — workspace), вне opt-out, с СОБСТВЕННЫМ взаимодействием в окне. Если никого нет, раунд не вызывает LLM (RN-680).
Факт профиля (FatoDoPerfil) — гипотеза Psicólogo, которую ПРИНЯЛ человек,
которому принадлежит сессия, спроецированная в граф из
psychologist.hypothesis_accepted и передаваемая агентам, разговаривающим с
этим человеком, как эфемерное системное сообщение
(RN-680).
instruction_patch — версионированное предложение изменить инструкцию
агента. Никогда не одобряется автоматически (RN-007);
отклонённое не предлагается повторно (RN-026);
откат создаёт новую версию вместо удаления
(RN-027).
Git и секреты
GitProvider — нормализованный контракт из двенадцати операций, который реализуют Local, GitHub и GitLab. Единый набор контрактных тестов запускается против всех трёх.
Capability — объявление того, что поддерживает данный провайдер. Неподдерживаемая операция отклоняется с явной ошибкой, никогда не молчаливым сбоем (RN-028).
Bootstrap Gitflow — шесть шагов, подготавливающих репозиторий (постоянные
ветки, защиты, базовые файлы). Идемпотентный и возобновляемый: skip — это
успех (RN-029).
Envelope encryption — каждый секрет пользователя шифруется собственным
DEK (data encryption key), а DEK «оборачивается» ключом
CREDENTIALS_MASTER_KEY. Ротация мастер-ключа переоборачивает DEK, не трогая
шифротекст, — поэтому ротацию можно прерывать
(runbook).
wrapped_dek — обёрнутый DEK в том виде, в каком он хранится в базе.
Не указывает, каким ключом он обёрнут — именно это свойство делает ротацию
процедурой из трёх шагов, а не заменой переменной.
Инфраструктура
Oban — библиотека очередей Elixir, использующая Postgres как бэкенд.
Глубина очереди (oban_queue_depth) — метрика, управляющая HPA engine.
Drain — фаза preStop engine: /ready начинает отвечать 503, новые сессии
отклоняются, и каждая сессия на узле предлагается живому соседу. То, что не
принято, закрывается как closed_abnormally / node_shutdown — корректное
завершение, а не сирота.
Принятие (adoption) — другой узел берёт на себя процесс сессии. Происходит
во время drain (активная передача) и в SessionAdoptionWorker, который проходит
каждые 30 с, чтобы покрыть kill -9 и OOMKill, когда preStop не выполняется.
:global — распределённый реестр Erlang. Гарантирует одного владельца на
сессию во всём кластере; без сформированного кластера Erlang каждая реплика
становится островом
(ADR 0026).
Корневой trace — одна сессия = один trace, охватывающий api ↔ engine.
traceparent сохраняется в sessions.trace_parent, и именно его используют
для навигации в Tempo. trace_id рождается в web (браузер генерирует
traceparent) и существует даже без коллектора: экспорт — решение, отдельное
от инструментирования
(ADR 0035).
Путь через слои — последовательность границ, которые запрос пересекает в api
(interfaces → application → infrastructure), с длительностью каждого шага,
выдаваемая одной строкой лога на запрос. Она берётся из
AsyncLocalStorage, наполняемого декоратором @Traced, а не из span — именно
это позволяет ей работать без коллектора. См.
наблюдаемость.
Слой — в пути выше, метка границы: interfaces, application, domain
или infrastructure. Соответствует каталогам под apps/api/src/ и правилу
зависимостей между ними.