Справочник агентов и цифровых сотрудников

Этот справочник описывает текущую архитектуру agent-системы CodeGraph. Он намеренно сфокусирован на runtime-границах и точках расширения, а не на полном перечне классов и методов. За деталями уровня исходного кода используйте карту модулей и публичные справочные документы в конце файла.

Текущая модель¶

CodeGraph больше не является системой с единственным “конвейером агентов” как главной архитектурой. Текущая система состоит из нескольких согласованных плоскостей:

1. Workflow-агенты маршрутизируют намерение пользователя в scenario handlers, CPG-запросы, domain plugins и форматированные ответы.
2. Protocol adapters публикуют одни и те же возможности через REST, MCP, ACP, CLI и headless Codex/OpenCode automation.
3. Цифровые сотрудники добавляют управляемое владение ролями, task capsules, handoffs, evidence lanes и release-readiness reporting.
4. Context and memory services объединяют project scope, OpenViking resources, session memory, task memory, story capsules и repository sync state.
5. Graph intelligence services читают CPG-факты через GoCPG gRPC в runtime. GoCPG является writer для project CPG DuckDB files.

flowchart LR
    UI[Frontend / Dashboard] --> API[FastAPI REST]
    Codex[Codex / OpenCode] --> MCP[MCP tools]
    IDE[IDE / ACP client] --> ACP[ACP JSON-RPC / WS / stdio]
    CLI[CLI / headless scripts] --> Services[Application services]

    API --> Services
    MCP --> Services
    ACP --> Services

    Services --> Workflow[Workflow scenarios]
    Services --> Employees[Digital employees]
    Services --> Context[Context and memory]
    Services --> CPG[CPGQueryService]
    Employees --> Tasks[TaskCapsuleService]
    Employees --> Temporal[Temporal coordination]

    CPG --> GoCPG[GoCPG gRPC]
    GoCPG --> DuckDB[(Project CPG DuckDB)]
    Context --> OpenViking[OpenViking]
    Tasks --> AppDB[(Application DB)]
    Temporal --> AppDB

Карта модулей¶

Workflow-Агенты¶

Workflow-выполнение открыто через role-bound вызов сценариев цифровых сотрудников. Runtime-клиенты должны использовать invoke_role_bound_scenario или соответствующий MCP-инструмент с явными project, namespace и task scope.

Текущий workflow-код смешанный: часть сценариев использует новую handler/formatter registry форму, часть legacy-модулей еще содержит composite workflow logic. При добавлении или существенном изменении scenario behavior:

• разделяйте intent detection, CPG reads, structured data assembly и formatting;
• предпочитайте BaseHandler плюс formatter modules для новых handlers;
• сохраняйте benchmark-facing поля вроде answer, retrieved_functions, cpg_results, sources и evidence;
• используйте domain plugins из src/domains/ для reusable language/framework semantics;
• не обходите GoCPG/gRPC CPG reads в runtime paths.

Старые core helper agents все еще существуют, но теперь это один слой внутри более широкой workflow/governance системы:

Цифровые сотрудники¶

Цифровые сотрудники - это accountable role lanes, а не просто prompt personas. Текущий реестр содержит 13 ролевых дорожек. Вместе они задают управляемый SDLC contract для development work.

Runtime pattern:

Anna-owned task plan
    -> named employee task capsules and handoff chain
        -> lane-specific action or tool
            -> evidence refs, artifacts, checks, and events
                -> Anna release-readiness status

Важные границы:

• TaskCapsuleService является authoritative task state boundary.
• Handoff lifecycle state хранится через task capsules и events, а не в параллельном handoff truth store.
• Codex/general AI является operator, который может вызывать governed tools; он не является accountable owner для implementation, review, QA, AppSec, docs, traceability, support, product discovery или runtime readiness.
• Финальный отчет о complete delivery требует explicit lane evidence или explicit not-applicable waiver для обязательных lanes.
• Suggested handoffs не являются executed handoffs, пока offer/accept/complete lifecycle не записан.

Ключевые implementation areas:

Protocol Surfaces¶

REST, MCP и ACP должны публиковать capabilities через shared service/action boundaries.

REST router / MCP tool / ACP handler
    -> shared action or service
        -> context, workflow, digital employee, CPG, or repository service
            -> App DB, OpenViking, GoCPG, Temporal, or external runtime

Правила:

• REST routers валидируют HTTP shape, auth, rate limits и project context.
• MCP tools разбирают tool arguments и вызывают те же actions/services, что и REST.
• ACP transports и handlers адаптируют JSON-RPC, WebSocket, stdio, sessions, approvals, hover, diagnostics и workflow/chat traffic в существующие services.
• Frontend должен показывать backend-authored readiness, reviewability, approval и chain state, а не выводить governance локально.

Project Scope и Memory¶

В runtime-архитектуре нет глобального “current project”. Project scope должен быть explicit, route-bound, workspace-derived, session-bound или actor-scoped для user, digital employee или service account.

Используйте ProjectContext и ctx.db_path в project-sensitive API, MCP, workflow, automation и multi-tenant paths. Не доверяйте DB paths, переданным пользователем.

Memory layers:

OpenViking является primary context backend для repository resources, explicit sessions, memory resources и native MCP resource access. Project memory и CPG - разные системы: они могут объединяться для agent context, но ни одна из них не становится скрытым source of truth для другой.

CPG и Documentation Facts¶

GoCPG владеет CPG generation и project CPG DuckDB writes. Runtime reads должны идти через GoCPG gRPC via CPGQueryService.

Documentation extraction является CPG-first:

• canonical documentation facts приходят из method_documentation_facts;
• production consumers используют CPGQueryService.get_method_documentation_by_identity(...);
• same-name methods в разных файлах должны оставаться distinct;
• legacy name-only comment и description APIs являются compatibility/debug surfaces.

Configuration и Limits¶

Используйте get_unified_config() и attribute access на config objects. Не hardcode-ьте domains, DB paths, limits, thresholds, batch sizes или timeouts в feature code.

Domain-specific data должна находиться в src/domains/{domain}/config/ или reusable domain plugin. Runtime routing и access decisions должны использовать project scope, policy и backend-authored context.

Расширение системы¶

Добавить или изменить workflow scenario¶

1. Используйте карту модулей из этого справочника и релевантный scenario code.
2. Добавьте или обновите handler в src/workflow/scenarios/....
3. Используйте BaseHandler и formatter, если локальный scenario поддерживает этот pattern.
4. Используйте CPGQueryService и domain plugins вместо direct DB reads или hardcoded domain knowledge.
5. Добавьте focused tests для scenario или затронутого helper.

Добавить protocol capability¶

1. Поместите business logic в service или shared action.
2. Добавьте thin REST, MCP или ACP adapters по необходимости.
3. Сохраняйте REST/MCP/ACP parity, когда одна capability опубликована на нескольких surfaces.
4. Сохраняйте auth, project context, task evidence, rate limiting и approval gates.

Добавить или изменить digital employee behavior¶

1. Начните с Anna-owned plan/task capsule и required lane evidence.
2. Держите role accountability явной.
3. Пишите handoff и lifecycle state через task capsules.
4. Используйте shared employee action modules для REST/MCP/Temporal parity.
5. Не сообщайте full closure, пока required lane evidence не существует.

Валидация¶

Запускайте validation, соответствующую измененной поверхности. Не запускайте pytest ..

Связанные документы¶

• Справочник workflows
• Справочник API
• MCP tools