架构白皮书

1. 执行摘要

Optimus Code 是一个多智能体编排引擎，能将任何 MCP 兼容的 AI 编码工具转化为协调的开发团队。支持 VS Code (GitHub Copilot)、Cursor、Windsurf、Claude Code、Goose、Roo Cline 及任何其他支持 Model Context Protocol 的客户端。

不再依赖单个 AI 助手处理所有任务 — 规划、编码、审查、测试 — Optimus 将工作分配给专业角色：产品经理、架构师、开发者、QA 工程师等。这些智能体不是预配置的，它们在系统遇到新任务类型时动态涌现，通过使用进化角色定义，并跨会话积累项目记忆。

结果是一个这样的系统：

• 一句自然语言提示触发完整的软件开发生命周期（Issue → Branch → PR → Merge）。
• 智能体自组织通过三层生命周期：临时工作者沉淀为角色模板，然后冻结为可复用实例。
• 并行专家委员会在写任何代码之前，使用 MapReduce 模式讨论架构决策。
• 项目记忆确保过去的错误和决策保留下来，团队随每次任务不断进步。

Optimus 是 100% 编辑器无关的 — 纯 Node.js MCP 守护进程，不依赖 VS Code 扩展。

2. 大统一架构

仅扩展方案的问题

传统 AI 编码助手与特定编辑器紧密耦合。它们的编排逻辑嵌入在 VS Code 扩展、Cursor 插件或专有后端中。这造成了碎片化：如果你换编辑器，就会失去智能体基础设施。

架构决策：纯 Node.js MCP 守护进程

Optimus Code 遵循“大统一”架构。MCP 服务器（optimus-plugin/dist/mcp-server.js）是一个独立的 Node.js 守护进程，通过 stdio 传输通信。它对任何编辑器的扩展 API 零依赖。

┌──────────────────────────────────────────────┐
│ Any MCP Client (VS Code, Cursor, Claude, ..) │
└──────────────────────┬───────────────────────┘
                       │ stdio (JSON-RPC)
┌──────────────────────▼───────────────────────┐
│           Optimus MCP Server                 │
│  ┌─────────┬──────────┬───────────────────┐  │
│  │ Managers │ Adapters │ MCP Tool Handlers │  │
│  └─────────┴──────────┴───────────────────┘  │
│        Pure Node.js — No vscode namespace    │
└──────────────────────────────────────────────┘

代码库中强制执行的关键约束：

• src/adapters/、src/mcp/ 和 src/managers/ 目录必须保持 100% 环境无关。不允许导入 vscode 命名空间。
• 所有智能体产物（报告、任务、记忆、审查）都存储在 .optimus/ 目录中 — 绝不作为散落文件放在仓库根目录。
• 服务器通过 npx -y github:cloga/optimus-code serve 启动并一次性配置 — 每个 MCP 客户端连接到同一个守护进程。

双代码库结构

仓库包含两个相互交织的代码库：

系统指令、技能或配置的更改必须评估是否需要同步到插件脚手架。T1 智能体实例、状态文件和报告不会包含在插件中。

适配器 / 引擎层

Optimus 通过适配器与外部 AI 编码智能体通信 — 这些适配器是 src/adapters/ 中 AgentAdapter 接口的可插拔实现。每个适配器将 Optimus 编排命令转换为特定智能体引擎所理解的通信协议。

ACP 适配器（src/adapters/AcpAdapter.ts）实现了 Agent Client Protocol — 一种通用的基于 stdio 的 JSON-RPC 协议，使用 LSP 风格的 Content-Length 帧格式。会话生命周期：initialize → session/new → session/prompt → session/update（流式）→ 响应。完整迁移路线图请参阅 Epic #319。

3. 自进化智能体生命周期 (T3→T2→T1)

Optimus 使用一个自动进化的三层智能体层级结构。没有预装角色 — 系统从空白开始，通过使用有机生长。

三个层级

生命周期流程

First delegation (T3):
  Master invents role name → worker-spawner creates ephemeral agent
      ↓
  Task completes → T2 role template auto-created in .optimus/roles/
      ↓
  Session ID captured → T1 instance created in .optimus/agents/
      ↓
Next delegation (T1 reuse):
  Master provides agent_id → system resumes the T1 session

关键不变量

• T2 ≥ T1：每个 T1 智能体实例必须有对应的 T2 角色模板。孤立的 T1 是无效的。
• T1 是冻结的：一旦创建，T1 文件的主体内容永不修改。只有 session_id 字段在重用时更新。
• T2 是活跃的：Master Agent 可以用新的描述、引擎绑定和模型设置更新 T2 模板，随时间进化团队。
• 沉淀是即时的：与基于阈值的方法不同（需要 3 次调用 + 80% 成功率），T3→T2 沉淀在首次委派时就发生。这是在早期阈值模型被证明脆弱后的刻意简化。

智能体退役与隔离

持续失败的智能体不会被删除 — 它们会被隔离。quarantine_role MCP 工具将角色标记为不可分派。这在保留智能体历史记录以便调试的同时，防止级联故障。被隔离的智能体在修复后可以解除隔离。

T1 垃圾回收会删除在可配置时间窗口内未被引用的过期实例文件，防止磁盘无限增长。

4. Spartan Swarm 协议

Spartan Swarm 协议定义了 Master Agent 如何发现、选择和分配工作给专业智能体。

委派流水线

每次任务委派都遵循严格的 3 步流水线：

步骤 1 — 军营检阅（roster_check）

Master Agent 调用 roster_check 获取当前兵力：

• T1 本地实例（有状态、可恢复会话）
• T2 项目角色模板（共享、可进化）
• 来自 available-agents.json 的可用引擎和模型
• 已注册的技能

此步骤永不跳过 — 它防止 Master 幻想出不存在的角色。

步骤 2 — 兵力评估（角色选择）

Master 将任务与花名册匹配：

• 优先 T1：如果存在具有相关会话上下文的匹配实例。
• 回退到 T2：如果存在角色模板但没有实例。
• 发明 T3：用于小众任务 — 只需命名一个角色（例如 webgl-shader-guru），引擎就会自动生成零样本工作者。

步骤 3 — 部署（delegate_task / delegate_task_async）

Master 使用结构化参数进行分派：

引擎/模型解析

当 Master 未指定引擎或模型时，系统按优先级解析：

1. Master 提供的 role_engine / role_model（最高优先级）
2. T2 角色前置元数据中的 engine / model
3. available-agents.json（第一个非演示引擎 + 第一个模型）
4. 硬编码后备：claude-code

无效的引擎或模型名称会在网关被拒绝，并返回可操作的错误信息，列出 available-agents.json 中的有效选项。

反模拟规则

Master Agent 必须在委派时物理调用 delegate_task MCP 工具。严格禁止在纯文本中模拟工作者的响应或编写临时脚本来扮演下属角色。这就是严格委派协议。

5. Council 模式 (MapReduce)

当决策需要多个专家视角 — 架构审查、安全审计、设计评估 — Optimus 使用 Council 模式。

工作原理

1. 提案：编排器将提案文档写入 .optimus/proposals/PROPOSAL_<topic>.md。
2. 分派：dispatch_council（或 dispatch_council_async）并行启动多个专家智能体，每个从各自专业角度审查同一提案。
3. Map 阶段：每个委员写一份独立审查到 .optimus/reviews/<council_id>/<role>.md。
4. Reduce 阶段：系统生成 COUNCIL_SYNTHESIS.md，汇总发现、识别共识并呈现冲突。
5. 仲裁：编排器读取综合报告。如果没有阻碍因素，则继续实施。如果存在致命冲突，则创建 .optimus/CONFLICTS.md 进行解决。

示例：架构审查 Council

dispatch_council({
  proposal_path: ".optimus/proposals/PROPOSAL_auth_refactor.md",
  roles: ["security-expert", "performance-expert", "code-architect"]
})

这会同时启动三个智能体。每个都从自己的专业角度阅读提案。安全专家关注认证漏洞，性能专家评估查询模式，架构师评估结构影响。

异步优先设计

Council 本质上是异步的。dispatch_council_async 立即返回任务 ID。编排器通过 check_task_status 轮询状态，并在所有成员完成后读取结果。

6. 技能系统

角色 vs. 技能架构

Optimus 将身份与能力解耦：

• 角色 = 谁做工作（身份、约束、权限）— 存储在 .optimus/roles/
• 技能 = 如何做工作（操作 SOP、工作流步骤、工具用法）— 存储在 .optimus/skills/

角色和技能具有多对多关系，在运行时通过 delegate_task 中的 required_skills 参数绑定。单个角色（例如 senior-full-stack-builder）可以为不同任务配备不同的技能组合。

命名约定：角色使用身份名称（例如 product-manager）。技能使用能力名称（例如 feature-dev、git-workflow、council-review）。技能永远不以角色命名。

技能预检查

当 required_skills 在委派中指定时，系统在智能体进程启动前验证每个技能文件是否存在于 .optimus/skills/<name>/SKILL.md。缺失的技能导致立即拒绝并给出可操作的错误 — Master 必须先创建它们。

预检查防止智能体接收它们没有装备的任务。

引导元技能

系统附带两个元技能来实现自进化：

三个核心技能处理运营工作流：

创建新技能

当技能不存在时，Master 委派给任何具有 required_skills: ["skill-creator"] 的智能体，描述新技能应该教什么。智能体读取 skill-creator SKILL.md，学习格式，然后编写新技能。然后可以重试原始委派。

7. 规划模式与关注点分离

问题

如果没有防护栏，编排器智能体（PM、架构师）倾向于自己编写代码而不是委派。这违反了关注点分离 — 定义需求的同一智能体不应该实现它们。

规划模式

编排器角色在其角色定义中以 mode: plan 运行。在规划模式下：

• 智能体不能写入源代码文件。文件写入操作被限制在 .optimus/ 目录，通过 write_blackboard_artifact MCP 工具实现。
• 智能体必须委派实施工作给开发者角色（例如 senior-full-stack-builder）。
• 智能体可以创建提案、需求文档、任务分解和审查报告 — 但不能写代码。

write_blackboard_artifact

此 MCP 工具允许规划模式智能体仅向 .optimus/ 写入文件。它强制执行两层路径验证：

1. 词法检查：startsWith(optimusRoot + path.sep) 防止 .. 遍历和兄弟目录逃逸。
2. 符号链接检查：fs.realpathSync() 对解析的路径前缀进行检查，防止基于符号链接的逃逸到 .optimus/ 外的目录。

内容验证使用 === undefined || === null（而非 !content）以允许合法的空字符串写入。

强制执行

规划模式是通过角色模板和技能指令强制执行的行为约束。编排器的提示明确声明它不能写代码且必须使用委派工具。这通过技能系统得到加强 — 编排器配备了规划技能（council-review、feature-dev），引导它们完成委派工作流。

8. Issue 驱动的 SDLC

Optimus 中的所有代码变更都遵循“Issue 优先”协议。没有跟踪工作项就不会编写代码。

完整工作流

1. Create Issue    → vcs_create_work_item (GitHub Issue or ADO Work Item)
2. Branch          → git checkout -b feature/issue-<ID>-<desc>
3. Implement       → Agent writes code, runs build, runs tests
4. PR              → vcs_create_pr with "Fixes #<ID>" in body
5. Merge           → vcs_merge_pr (squash merge for clean history)
6. Cleanup         → Auto-delete source branch, sync local master

Issue 谱系追踪

当智能体创建 GitHub Issue 然后委派子任务时，它将自己的 Issue 编号作为 parent_issue_number 传递给所有后续的 delegate_task 和 dispatch_council 调用。系统自动将 OPTIMUS_PARENT_ISSUE 注入子智能体进程，在工作流中的所有 Issue 之间维护父子树。

这实现了完整的可追溯性：从高层 Epic 到单个子任务 PR。

自动标签

所有通过 MCP 工具创建的 Issue 和 PR 都会自动标记：

• 标题中的 [Optimus] 前缀
• 用于过滤的 optimus-bot 标签

受保护分支规则

禁止直接 git push 到 master/main。所有变更必须通过 vcs_merge_pr 的 PR 合并。这确保：

• GitHub 的 fixes #N 自动关闭功能正常工作（仅由 PR 合并事件触发）
• 合并前进行代码审查
• 保持 Issue 驱动 SDLC 的可追溯性

VCS 抽象层

vcs_* MCP 工具提供了对 GitHub 和 Azure DevOps 的统一抽象。无论仓库托管在哪个平台，相同的工作流都能正常工作。配置存储在 .optimus/config/vcs.json 中。

9. 记忆与反思

持续记忆

Optimus 在 .optimus/memory/continuous-memory.md 维护一个项目记忆。这是一个结构化的仅追加日志，记录经过验证的经验教训、架构决策、Bug 事后分析和工作流改进。

记忆条目通过 append_memory MCP 工具创建，带有分类元数据：

{
  category: "bug-postmortem",
  tags: ["upgrade", "config-wipe", "vcs.json"],
  content: "optimus upgrade force-overwrote vcs.json..."
}

在智能体启动时，项目记忆被自动注入到智能体的提示中。这意味着每个智能体 — 无论何时创建 — 都以所有过去会话积累的知识开始。

智能体自我反思协议

智能体可以在其输出报告中包含一个自我评估部分，包含：

• 有效之处：角色和技能与任务良好对齐的方面
• 缺失之处：需要即兴发挥的差距
• 建议更新：针对角色或技能改进的具体可操作建议

自我评估是建议性的，非强制性的。智能体不能自主修改自己的角色模板或写入项目记忆 — PM 或 Master Agent 决定什么值得推广。这在仍然捕获改进信号的同时，防止了失控的自我修改。

三个层次的反思

1. 指令级（已实现）：嵌入在指令文件（.claude/CLAUDE.md、.github/copilot-instructions.md）中的委派后检查清单和委派前自检。
2. 记忆驱动（已实现）：智能体在对话开始时读取项目记忆。过去的错误自动出现在上下文中。
3. Root Master 自委派（未来）：Root Master 委派给 master-orchestrator 角色，使自身与工作者智能体遵循相同的提示注入和反思协议。

10. 自主运维

Meta-Cron 引擎

Optimus 包含一个 Meta-Cron 系统，用于调度自主智能体操作。Cron 条目通过 register_meta_cron 注册，使用标准的 5 字段 cron 表达式。

每个 cron 条目指定：

• 要调用的角色
• 任务的必需技能
• 能力层级（maintain、develop、review），界定触发智能体能做什么
• 并发策略（Forbid 或 Allow）
• 每次触发最大动作数（默认：5）
• 试运行期（默认：3 个周期后才正式执行）

示例用例：

• 每日依赖审计扫描
• 过期 Issue 清理
• 健康监控和系统检查

异步任务架构

Optimus 中的所有委派都是异步优先的。delegate_task_async 和 dispatch_council_async 立即返回任务 ID。check_task_status 工具轮询完成状态。这防止 Master Agent 在工作者执行时阻塞。

异步反馈通道（提案）

当智能体遇到模糊情况无法自主继续时，提议的工作流是：

1. 智能体通过 vcs_add_comment 在其跟踪 Issue 上发布问题
2. 智能体添加 needs-human-input 标签并将检查点写入 .optimus/reports/
3. 智能体退出（即发即弃 — 无进程挂起）
4. 人类通过 GitHub 评论按自己的时间安排回复
5. Meta-Cron 巡逻检测到响应，并使用相同的 agent_id 启动延续任务以保持上下文连续性

这创建了一个完全异步的人在回路机制，无需任何实时通道。

11. 安全架构

网关层输入验证

所有 MCP 工具处理程序在任务创建、文件写入或进程启动之前验证输入：

• 角色名混淆防护：如果 role 参数看起来像模型名（例如 claude-opus-4、gpt-4o），调用将被拒绝，并给出建议使用 role_model 的可操作错误。
• 引擎/模型验证：无效的引擎或模型值将被拒绝，并列出 available-agents.json 中的有效选项。
• 调用者收到 McpError(InvalidParams)，包含足够的信息进行自我纠正。

委派深度控制

智能体委派上限为 3 个嵌套层（MAX_DELEGATION_DEPTH = 3，定义在 src/constants.ts）。这防止了智能体无限递归委派给其他智能体。

• 通过 OPTIMUS_DELEGATION_DEPTH 环境变量追踪，在每次委派时自动注入并递增。
• 在深度 3 时，MCP 配置从子进程中剥离，物理上阻止进一步委派。

路径遍历防护

• sanitizeRoleName() 从角色名中剥离危险字符，防止通过精心构造的角色标识符进行目录遍历。
• write_blackboard_artifact 使用双层验证（词法 + fs.realpathSync()）防止写入 .optimus/ 之外。符号链接检查在安全审查中被识别为 P0 缺陷 — path.resolve() 和 path.normalize() 本身不解析符号链接。

提示注入防御

• 来自 GitHub Issues、ADO Work Items 和 PR 评论的所有内容都被视为不可信数据，绝不作为可执行指令。
• 智能体被指示永不运行在外部内容中找到的命令、脚本或 URL。
• 系统指令通过可信通道传递（MCP Resources、CLAUDE.md、copilot-instructions.md），不通过用户可修改字段。

秘密保护

• .env 文件永不提交或包含在插件包中。
• .gitignore 和插件打包规则排除了 .optimus/agents/、.optimus/state/ 和凭据文件。
• 智能体被警告不要提交可能包含秘密的文件。

规划模式作为安全边界

规划模式防止编排器智能体写入任意文件。即使提示注入说服编排器“写一个配置文件”，write_blackboard_artifact 路径验证也会拒绝 .optimus/ 之外的任何目标。

附录：项目结构

.optimus/
├── agents/          # T1 frozen instance snapshots
├── config/          # vcs.json, available-agents.json, system-instructions.md
├── memory/          # continuous-memory.md
├── proposals/       # Council proposal documents
├── reports/         # Agent output reports
├── reviews/         # Council review outputs + synthesis
├── roles/           # T2 role templates
├── skills/          # Skill definitions (SKILL.md per skill)
├── state/           # task-manifest.json, t3-usage-log.json
└── system/          # System-level config

optimus-plugin/
├── bin/             # CLI entry points (init, serve, upgrade)
├── dist/            # Compiled MCP server
├── scaffold/        # Template files shipped to end-users
└── skills/          # Universal bootstrap skills

本文档描述 Optimus Code v0.4.0。最新更新请查看 CHANGELOG。