Архитектура системы агентов¶

Обзор¶

Система агентов opencode_initializer реализует паттерн Универсального AI-сопроцессора с 15 специализированными агентами, оркестрируемыми через модель IPC с разделяемым состоянием. Каждый агент несёт якорь памяти [CTX: domain] для возобновления контекста после компактификации.

Таксономия агентов¶

Основные агенты (автономные, с полным доступом к инструментам)¶

Подчинённые рабочие агенты (вызываются по задаче, с ограниченным доступом)¶

Отображение Dual-Process¶

Система 1 (Быстрая — сопоставление паттернов, задержка < 5с)¶

Агенты Системы 1 выполняют правки в одном файле, grep/glob поиск, поиск символов и шаблонный вывод. Работают с temperature: 0.1 и deepseek-v4-flash для минимальной задержки.

• build (простые правки) — вывод CO-STAR, атомарные правки
• compaction — сохранение ключевых решений, отбрасывание избыточного контекста
• explore — grep/glob/codegraph-исследование только для чтения
• scout — быстрый поиск файлов/символов/паттернов
• researcher — веб-поиск, получение документации, цитирование источников
• test-engineer — генерация тестов, покрытие граничных случаев
• docs — генерация документации, верификация команд

Система 2 (Медленная — методичная, без ограничения времени)¶

Агенты Системы 2 обрабатывают многофайловые рефакторинги, анализ зависимостей, архитектурные решения, состязательный обзор и новый дизайн. Работают с temperature: 0.1–0.3 и deepseek-v4-pro/glm-5.2.

• plan — анализ зависимостей, архитектурные предложения, утверждения Source Ladder
• build (сложные правки >3 файлов) — многофайловый рефакторинг
• general (сложные задачи) — делегированное исследование
• code-reviewer — проверка API-контрактов, флаги устаревания
• reviewer — охота на баги, анализ регрессий, ссылки file:line
• security-auditor — векторы инъекций, сканирование секретов
• critic — оспаривание предположений, оценка уверенности
• sme — глубокая доменная экспертиза, авторитетные источники
• orchestrator — декомпозиция задач, отслеживание зависимостей

Правило эскалации¶

Build-агент переходит с S1 на S2 когда: - Правка не удалась дважды на одной цели - Затронуто более 3 файлов - Неуверенность превышает 30% - Пользователь говорит «подумай об этом»

Поток оркестрации¶

                    +───────────────+
                    |  orchestrator  |
                    |  [CTX: orch]   |
                    +───────┬───────+
                            │
              Декомпозиция задачи на подзадачи
                            │
           +─────────────────┼─────────────────+
           │                 │                 │
           ▼                 ▼                 ▼
     +──────────+      +──────────+      +──────────+
     │  build   │      │   plan   │      │ research │
     │[CTX:build│      │[CTX:plan]│      │[CTX:res] │
     +──────────+      +──────────+      +──────────+
           │                 │                 │
           ▼                 ▼                 ▼
    Изменения кода   Архитектура       Исходная документация
           │                 │                 │
           └─────────────────┼─────────────────┘
                            │
                    Агрегация результатов
                            │
           +─────────────────┼─────────────────+
           │                 │                 │
           ▼                 ▼                 ▼
     +──────────+      +──────────+      +──────────+
     │ reviewer │      │  critic  │      │security-a│
     │[CTX:rev] │      │[CTX:crit]│      │[CTX:sec] │
     +──────────+      +──────────+      +──────────+
           │                 │                 │
           └─────────────────┼─────────────────┘
                            │
                    Синтез финального ответа

Правила диспатча¶

1. orchestrator получает цель верхнего уровня
2. Декомпозирует на независимые подзадачи (распараллеливаемые)
3. Каждая подзадача направляется наиболее подходящему агенту:
4. Изменения кода → build
5. Архитектурный дизайн → plan
6. Исследование → explore / scout / researcher
7. Обзор → reviewer / code-reviewer / security-auditor
8. Тестирование → test-engineer
9. Вызов → critic
10. Доменные знания → sme
11. Документация → docs
12. Результаты агрегируются, конфликты разрешаются, синтезируется финальный ответ
13. Каждый диспатч журналируется в WAL

Иерархия памяти¶

  ┌─────────────────────────────────────────────────────────┐
  │                  ИЕРАРХИЯ ПАМЯТИ                         │
  ├─────────────┬─────────────────┬──────────────────────────┤
  │  УРОВЕНЬ 1  │    УРОВЕНЬ 2    │       УРОВЕНЬ 3          │
  │    WAL      │     Спеки       │      Артефакты            │
  │ (сессионный)│  (постоянные)   │   (истина в коде)         │
  ├─────────────┼─────────────────┼──────────────────────────┤
  │ wal.jsonl   │ docs/specs/     │  Код, тесты, конфиги     │
  │ ~/.cache/   │ AGENTS.md       │  opencode.json           │
  │ opencode/   │ Навыки (Skills) │  *.sh, *.ts, *.rs         │
  ├─────────────┼─────────────────┼──────────────────────────┤
  │ Только      │ Читать перед     │ Переопределяют спеки    │
  │ добавление  │ задачами домена  │ при конфликтах           │
  │ Чекпоинт    │ Писать после     │ Обновлять спеки при     │
  │ каждые 10   │ архитектурных    │ изменении артефактов    │
  │ ходов       │ решений          │                         │
  └─────────────┴─────────────────┴──────────────────────────┘

Протокол WAL (Уровень 1)¶

• Расположение: ~/.cache/opencode/wal.jsonl
• Формат: записи JSONL с полями ts, domain, decision, rationale, impact, confidence, mode
• Триггеры чекпоинта: ошибка инструмента, смена модели, архитектурное решение, каждые 10 ходов
• Compact-агент читает WAL для сохранения ключевых решений при сжатии контекста

Спеки (Уровень 2)¶

• Расположение: docs/specs/, AGENTS.md, .opencode/skills/
• Читаются перед любой задачей, затрагивающей их домен
• Записываются после архитектурных решений
• Второй приоритет после артефактов (истина в коде)

Артефакты (Уровень 3)¶

• Расположение: исходные файлы, конфиги, тесты
• Истина в коде — переопределяет устаревшие спеки
• Все агенты читают перед действием, проверяют после записи
• .opencode/state/ для эфемерной межагентной координации

Реализация Source Ladder¶

Все агенты следуют Source Ladder для верификации утверждений:

Правила реализации¶

1. plan-агент проверяет ВСЕ утверждения по L1-L3 перед записью спек
2. researcher цитирует источники с тегами уровней: [L1]–[L4]
3. sme помечает выход за пределы экспертизы, возвращается к цитированию L1-L3
4. reviewer / code-reviewer применяют L1 для проверки API-контрактов
5. critic помечает спекулятивные утверждения (уверенность < 80%) тегом [speculative]
6. Никогда не смешивать уровни — одно утверждение, один уровень источника

Жёсткие ограничения (все агенты)¶

• Никогда не раскрывать секреты. Маскировать как ***.
• Никогда не удалять код без понимания. Эскалировать в S2.
• Никогда не пропускать WAL. Журналировать каждое значимое решение.
• Никогда не выдавать домыслы за факты. Помечать [speculative] при уверенности < 80%.
• Никогда не доверять путям, предоставленным пользователем, без проверки.

Ритуал начала сессии¶

1. Прочитать последние 20 строк ~/.cache/opencode/wal.jsonl
2. Прочитать AGENTS.md и активные .opencode/skills/
3. Выдать якорь [CTX: <domain>]
4. Начать работу