Codex Agent Orchestrator MCP

一个面向 Codex 原生侧栏任务的可复用本地 MCP 控制平面。团队顶层固定为“主控 / 执行 / 验收”，但每轮任务的专业身份根据项目动态决定。MCP 把任务、岗位、动态专业身份、Codex threadId/hostId、等待游标、依赖、所有权、租约、讨论、汇报、审批和事件记录持久化到项目目录中。

本项目从参考包中只保留通用编排核心，不包含其业务项目、Dashboard、Redis、Gitea、聊天后端或模型调用。

核心能力

• 持久化任务队列：状态保存到项目的 .codex-orchestrator/，Codex 重启后仍可恢复。
• 启动前项目采访：主控先检查仓库，再用一轮 3–6 个问题补齐真正缺失的范围、技术栈、环境和验收信息。
• 工作区三态探测：统一支持目录不存在/空目录、已有但不规范的代码目录、规范仓库。
• Project Brief 门禁：没有结构化 projectBrief 就不能初始化工作流；采访结论会随工作流持久化。
• 开发前能力侦察：主控先做有界 GitHub 参考项目搜索和当前 Codex skills 匹配，把许可证、可借鉴模式、风险、基础架构、综合洞察、原创取舍和采用的 skill 写入 Project Brief。
• 动态专业能力库：orchestrator_specialty_match 根据任务和技术栈匹配少量候选能力档案，再由主控改写成项目专属 specialistContract；不会把专业身份固化成额外侧栏。
• 专业任务契约：每项任务明确使命、能力、交付物、成功指标、非目标、证据要求、允许工具和失败处理，减少角色含糊和交接损耗。
• 依赖门禁：任务以 DAG 表达；依赖完成前不能领取，并拒绝未知依赖、自依赖和循环依赖。
• 原子抢占：用工作流级文件锁串行化 claim，同一任务不会同时分配给两个 Agent。
• 并发上限：每个工作流可设置 maxParallel。
• Agent 租约：claim 后获得有期限的所有权；heartbeat 续租；超时后可自动或手动回收。
• 结构化汇报：支持 completed、failed、blocked、requeue，记录变更文件、验证、证据、置信度、产物、风险和失败分类。
• 证据化验收：validation 任务默认至少需要一项通过的验证或独立证据；截图、测试、测量、审查、产物和 trace 都可结构化记录。
• 质量指标：状态汇总包含总尝试次数、一次通过数、证据覆盖任务数、证据记录数和平均尝试次数。
• 阻塞恢复：主控确认障碍已解除后，可显式重新入队；由失败依赖造成的下游阻塞会自动重新计算。
• 文件范围门禁：完成报告中的 changedFiles 必须落在任务的 allowedPaths 内，否则拒绝完成并阻塞任务。
• 人工审批：高风险和关键风险任务默认进入审批门禁，主 Agent 不得伪造用户批准。
• Agent 通信：提供有界的 inbox/message 通道，适合问题、阻塞和结果通知。
• 可见侧栏团队：orchestrator_team_dispatch 返回 Codex App 原生 create_thread、send_message_to_thread 和 wait_threads 主机动作，不再把不可见的临时 subagent 当作团队窗口。
• 三层团队与长期会话：当前任务是主控；执行和验收各绑定一个持久化的 threadId + hostId + cursor，后续任务继续发送到对应岗位窗口。
• 动态专业身份：task.lane 决定进入执行或验收，task.role 描述本轮所需能力，例如前端、后端、数据库、UI、测试、安全、性能或视觉审查，而不是永久侧栏角色。
• 团队自治：技术方案、问题修复、测试、验收和美工讨论在团队任务之间路由；只有产品决策、凭据/权限、不可逆操作、重大范围变化和人工审批升级给用户。
• 动态任务：发现缺陷或返工时，用同一个任务队列新增 repair/follow-up task，而不是另建一套脆弱的 issue 状态机。
• 审计历史：保留最近 1000 个事件和 500 条消息。
• Codex 原生衔接：初始化和状态查询保留兼容的 spawnRecommendations；v0.5 主流程使用 orchestrator_team_dispatch 的可见线程动作。

flowchart LR
    U["用户"] <--> M["主 Codex / 控制器"]
    M <--> Q["Orchestrator MCP"]
    Q <--> S[".codex-orchestrator JSON 状态"]
    M --> H["Codex App 线程工具"]
    H --> A1["侧栏任务｜执行"]
    H --> A2["侧栏任务｜验收"]
    A1 <--> Q
    A2 <--> Q

MCP 是编排状态层，不会绕过 Codex 主程序自行启动模型或私自修改侧栏。它返回严格的主机动作契约，由主 Codex 调用 Codex App 原生线程工具，因此角色会成为真正可打开的侧栏任务。若客户端没有 create_thread / wait_threads / send_message_to_thread 能力，队列仍可使用，但无法提供侧栏团队体验。

侧栏团队工作方式

初始化工作流后，主控循环执行：

1. 调用 orchestrator_team_dispatch 预留当前 ready task，并取得主机动作。
2. 先执行 controllerAction，把当前任务标题设为“团队名 | 主控”。对 create_visible_thread：先用 Codex App list_projects 找到 projectRoot 对应项目，再调用 create_thread；成功后立即用 orchestrator_team_bind 保存 threadId 与 hostId，并按返回动作设置“执行”或“验收”标题。
3. 对 continue_visible_thread：调用 send_message_to_thread，把新任务或团队讨论发送到已绑定的角色任务。
4. 执行 waitAction 中的 wait_threads；每次快照都调用 orchestrator_team_sync 保存 cursor、状态、摘要和消息确认。
5. 再次调用 orchestrator_team_dispatch。新依赖释放后会自动派工；同一角色会复用原线程。
6. 只有 userConfirmationRequired 非空时才向用户确认。其他技术讨论通过 orchestrator_message_send 在团队内部继续路由。

默认团队始终是三层：当前 Codex 任务为主控，另建“执行”和“验收”两个可见侧栏岗位。主控根据项目给每个任务选择动态专业身份：实现、设计、调研、修复和环境准备通常属于 execution；独立测试、代码审查、安全、性能和视觉验收属于 validation。只有特殊项目需要改变顶层结构时才调用 orchestrator_team_configure。

在初始化工作流之前，主控还会调用 orchestrator_discovery_plan：根据目标、仓库技术栈和所需能力生成 2–4 个 GitHub 查询，并检查当前会话可用的 skills。最多保留 5 个高价值参考项目，优先选择许可证明确、近期维护、有文档和测试的仓库。参考项目只是经验样本：主控必须先根据当前需求建立基础架构，再综合多个来源的优点并形成自己的设计取舍，不能把某个仓库当成蓝图复刻。已安装且相关的 skill 可直接使用；安装缺失 skill 或 plugin 必须先得到用户明确许可。

任务拆分后，主控会对不同任务类型调用 orchestrator_specialty_match。内置档案涵盖架构、前端、后端、最小变更调试、DevOps/SRE、UI/UX、代码审查、测试、视觉证据、安全、性能和多智能体架构等高频能力。匹配结果只是原料：主控必须按当前项目改写使命和指标，并仍把任务派到“执行”或“验收”长期侧栏。

环境要求

• Node.js 20 或更高版本
• 支持本地 STDIO MCP 的 Codex 桌面端、CLI 或 IDE 扩展
• projectRoot 必须是安全的绝对路径；可以尚不存在、为空、缺少 manifest，或是规范仓库

安装

从 GitHub main 安装当前源码版本：

npm install -g "git+https://github.com/3135804887-ops/codex-agent-orchestrator-mcp.git#main"

或者克隆源码：

git clone https://github.com/3135804887-ops/codex-agent-orchestrator-mcp.git
cd codex-agent-orchestrator-mcp
npm ci
npm run build
npm install -g .

解压后，在本目录执行：

npm ci
npm run build

也可以安装打包产物：

npm install -g .\codex-agent-orchestrator-mcp-0.5.0.tgz

全局安装后，可把 Codex 配置中的启动命令直接写成：

[mcp_servers.agent_orchestrator]
command = "codex-agent-orchestrator-mcp"
default_tools_approval_mode = "writes"
required = true

连接到 Codex

Codex 桌面端可以在 Settings → MCP servers → Add server 中添加 STDIO 服务，然后重启。也可以编辑用户级 ~/.codex/config.toml 或可信项目中的 .codex/config.toml：

[mcp_servers.agent_orchestrator]
command = "node"
args = ["C:\\absolute\\path\\to\\codex-agent-orchestrator-mcp\\dist\\index.js"]
startup_timeout_sec = 20
tool_timeout_sec = 120
default_tools_approval_mode = "writes"
required = true

[mcp_servers.agent_orchestrator.env]
CODEX_ORCHESTRATOR_ALLOWED_ROOTS = "C:\\Users\\Administrator\\Documents\\Codex"

CODEX_ORCHESTRATOR_ALLOWED_ROOTS 是可选的安全白名单。Windows 多个根目录用分号分隔；macOS/Linux 用冒号分隔。未配置时仍会拒绝文件系统根目录、用户主目录和没有项目标记的目录。

CLI 也可以直接注册：

codex mcp add agent_orchestrator -- node C:\absolute\path\to\codex-agent-orchestrator-mcp\dist\index.js
codex mcp list

在 Codex 中使用

直接对主 Codex 说：

使用 agent_orchestrator MCP 管理这次开发。开发前先搜索少量相关 GitHub 项目并匹配当前可用 skills。参考项目只用于吸取经验：先根据本项目需求建立基础架构，再综合多个来源形成原创取舍，禁止复刻单一仓库。把许可证、可借鉴模式、风险、基础架构、综合洞察和原创决定写入 discovery；不要复制未知许可证代码，也不要未经我许可安装 skill/plugin。团队分为主控、执行、验收：你作为主控与我沟通；执行岗位根据任务动态采用前端、后端、数据库、UI、调试等专业身份并直接写代码；验收岗位根据项目采用测试、审查、安全、性能或视觉验收身份独立验证。专业身份不能被固定成永久侧栏角色。只在产品决策、凭据/权限、不可逆操作、重大范围变化或人工审批时问我，直到集成验证通过。

如果客户端展示 MCP Prompts，也可以调用 orchestrator_controller，传入 projectRoot 和 objective。若希望项目中以后默认采用这套方式，可把 examples/AGENTS.orchestrator.md 的片段合并进项目现有的 AGENTS.md。

启动前采访

主控不会假定仓库已经存在，也不会一上来就安装依赖或创建 Agent，而是按以下顺序启动：

1. 先调用 orchestrator_workspace_probe，把路径分类成 absent、unstructured 或 structured。
2. 对已有项目读取适用的说明、manifest、lockfile、env 示例、构建/测试脚本和仓库状态。
3. 用只读命令检查已安装的 runtime、包管理器和关键工具。
4. 只针对无法从项目中发现的内容，一次性询问 3–6 个简短问题。
5. 根据目标和已识别技术栈完成有界 GitHub/skills 侦察。
6. 把采访与侦察结果汇总成 projectBrief，再初始化队列。

工作区状态	判定	主控行为
absent	路径不存在，或目录为空	按全新项目采访；约定技术栈、最小骨架、是否初始化 Git 和环境；先创建 bootstrap task
unstructured	有文件，但缺少可信的 manifest/说明组合	先只读盘点入口和现有行为；询问保持原样还是做最小规范化；禁止为了整洁大规模重构
structured	检测到 manifest，或 Git 与项目说明组合	遵守已有约定，只询问缺失的产品和环境决策

unstructured 不是错误状态。用户选择保持现状时可以直接编排现有代码；用户同意规范化时，只加入一个有明确范围的 baseline task，例如补 README、manifest、测试命令、.gitignore 或 AGENTS.md。

主控会根据项目动态删减问题，典型采访维度是：

1. 这次最终要交付什么，哪些内容明确不做？
2. 是改现有项目还是从零创建；已识别出的技术栈是否保持，是否有版本或框架限制？
3. 目标运行/部署平台以及必须保持的兼容性是什么？
4. 当前环境是否已能运行；缺少的依赖、数据库或服务是否先配置好再开发？
5. 如何判断完成，包括必须通过的测试、页面、接口或性能指标？

仓库已经能回答的问题不会重复采访。只有回答产生重大歧义时才追加一轮简短追问；非关键空白会作为明确写出的 assumption，不会无休止提问。

完整生命周期

1. 主 Codex 探测工作区状态并完成对应的精简采访。
2. 主 Codex 调用 orchestrator_discovery_plan，执行只读 GitHub 搜索与 skills 盘点，筛选有许可证和工程价值的少量参考。
3. 主 Codex 生成包含范围、交付物、技术栈、环境状态、约束、验收标准、assumptions 和 discovery 的 projectBrief。
4. 主 Codex 对不同任务类型调用 orchestrator_specialty_match，改写并持久化项目专属专业契约和证据门禁。
5. 无仓库时创建 bootstrap task；非规范目录只在用户同意时创建 minimal baseline task；环境需要准备时创建 setup task。实现类任务使用 lane=execution，每项交付物最后至少有一个依赖相关执行任务的 lane=validation 验收任务。
6. 主 Codex 调用 orchestrator_workflow_init。
7. 主 Codex 调用 orchestrator_team_dispatch，用 Codex App 原生工具创建/继续可见角色任务并绑定线程。
8. 每个岗位线程调用 orchestrator_task_claim 原子领取指定任务，并按本轮动态专业身份直接执行工作。
9. 长任务周期性调用 orchestrator_task_heartbeat；角色间问题用 orchestrator_message_send。
10. 角色任务调用 orchestrator_task_report，带验证、证据和置信度汇报完成、失败、阻塞或主动退回。
11. 主 Codex 用 wait_threads 监控，用 orchestrator_team_sync 持久化 cursor 和摘要，再次 dispatch 路由讨论或下一批任务。
12. 只有 userConfirmationRequired 中的关键门禁才询问用户；队列全部完成后由主控做最终集成验证并统一交付。

MCP 工具

工具	用途	是否写状态
orchestrator_workspace_probe	对可能不存在或不规范的项目路径做只读三态探测	否
orchestrator_discovery_plan	规划有界 GitHub 参考项目搜索和当前 skills 匹配	否
orchestrator_specialty_match	为任务匹配可改写的动态专业能力档案	否
orchestrator_workflow_init	校验并持久化 projectBrief，幂等创建任务 DAG 和审批项，返回首批创建建议	是
orchestrator_workflow_status	获取进度、活动任务、待审批、失败、事件和下一批建议	否
orchestrator_team_configure	特殊情况下调整执行/验收岗位覆盖范围、职责和讨论上限	是
orchestrator_team_dispatch	预留任务并返回创建/继续/等待侧栏任务的主机动作	是
orchestrator_team_bind	保存 Codex 侧栏任务的 threadId、hostId 与当前任务	是
orchestrator_team_sync	保存线程 cursor、状态、摘要、消息确认和用户决策门禁	是
orchestrator_task_add	动态加入修复、返工或新发现任务，并重新校验 DAG	是
orchestrator_task_claim	原子领取最高优先级或指定的 ready task	是
orchestrator_task_heartbeat	更新进度并续租	是
orchestrator_task_report	结构化汇报 outcome，并执行文件范围门禁	是
orchestrator_task_requeue	主控在障碍解除后显式重排 blocked/failed task	是
orchestrator_approval_resolve	记录用户明确给出的批准或拒绝	是
orchestrator_message_send	Agent 间发送问题、阻塞、信息或结果	是
orchestrator_message_inbox	读取定向消息和广播消息	否
orchestrator_recover_stale	回收租约过期或已确认失联的任务	是

任务定义示例

工作流初始化前必须先形成采访简报：

{
  "projectType": "existing",
  "workspace": {
    "state": "unstructured",
    "existedAtIntake": true,
    "markers": [".git"],
    "bootstrapBeforeDevelopment": true,
    "bootstrapPlan": ["保留现有目录布局", "补充 package.json、测试命令和 README"]
  },
  "scope": "为现有后台增加账号密码登录；本次不做第三方 OAuth。",
  "deliverables": ["认证 API", "登录页面", "自动化测试"],
  "techStack": ["Node.js 20", "TypeScript", "PostgreSQL 16"],
  "environment": {
    "status": "needs_setup",
    "setupBeforeDevelopment": true,
    "notes": ["Node.js 已安装", "本地 PostgreSQL 尚未启动"]
  },
  "constraints": ["保持现有 API 兼容", "不得修改生产数据"],
  "acceptanceCriteria": ["登录成功和失败路径测试通过", "现有测试无回归"],
  "assumptions": ["本地开发使用 Docker 启动 PostgreSQL"],
  "discovery": {
    "mode": "always",
    "status": "completed",
    "githubQueries": ["typescript postgres authentication example"],
    "githubReferences": [
      {
        "repository": "example/reference-auth",
        "url": "https://github.com/example/reference-auth",
        "license": "MIT",
        "relevance": "认证分层和测试结构与当前目标接近。",
        "usefulPatterns": ["认证服务与路由解耦", "失败路径测试"],
        "cautions": ["仅借鉴结构，不复制实现代码"]
      }
    ],
    "skills": [
      {
        "name": "github:github",
        "status": "available",
        "reason": "用于仓库参考信息和 GitHub 工作流。"
      }
    ],
    "baselineArchitecture": ["按当前需求设计认证服务、路由适配层和独立测试边界"],
    "synthesizedInsights": ["综合多个项目的分层经验和失败路径测试方法，不沿用其目录结构"],
    "originalDecisions": ["为现有 API 兼容性保留适配层，并使用项目自己的错误模型"],
    "notes": []
  }
}

随后才创建具体任务：

{
  "id": "implement-api",
  "title": "实现认证 API",
  "description": "按探索结论实现认证接口并保持现有兼容性。",
  "role": "implementer",
  "lane": "execution",
  "priority": "high",
  "risk": "medium",
  "dependencies": ["explore-auth"],
  "allowedPaths": ["src/auth/**", "tests/auth/**"],
  "acceptanceCriteria": ["认证单元测试通过", "现有 API 合同不变"],
  "specialistContract": {
    "name": "认证后端工程师",
    "mission": "在保持现有 API 兼容的前提下实现认证能力。",
    "capabilities": ["认证授权", "API 契约", "失败路径测试"],
    "deliverables": ["认证实现", "自动化测试", "兼容性说明"],
    "successMetrics": ["成功和失败路径均通过", "现有合同无回归"],
    "nonGoals": ["不重写无关用户模块", "不引入第三方 OAuth"],
    "evidenceRequirements": ["通过的认证测试", "API 行为记录"],
    "permittedTools": ["file edit", "test runner", "local service"],
    "failureProtocol": ["外部依赖失败时提供可复现信息", "产品取舍交主控"]
  },
  "minimumEvidence": 1,
  "maxAttempts": 2
}

allowedPaths: [] 表示只读任务。普通路径如 docs 会匹配该路径及其子路径；* 只匹配一个路径段，** 可跨目录匹配。

持久化格式

每个工作流使用一个 JSON 文件：

<projectRoot>/.codex-orchestrator/
├── workflows/
│   └── <workflowId>.json
└── locks/
    └── <workflowId>.lock/   # 仅在一次原子更新期间存在

从 schema v4 起，任务还包含动态 specialistContract、最低证据数、证据和失败分类。读取旧 schema v1/v2/v3 文件时会补全兼容默认值；旧角色线程仍会迁移为执行与验收两个持久岗位，不需要手工迁移。

写入采用临时文件加 rename，claim/report 等读改写操作都持有工作流锁。事件和消息有长度上限，避免状态文件无限膨胀。

建议将 .codex-orchestrator/ 加入 .gitignore；如果团队明确希望共享审计状态，也可以选择提交 workflow JSON，但不要提交运行中的 locks/。

与参考包核心能力的对应

参考能力	本 MCP
queue init / next / claim / report / status	workflow init / status + task claim / heartbeat / report
dependency gating	DAG 校验和运行时依赖门禁
issue queue	orchestrator_task_add 新增 repair/follow-up task，共用相同门禁
agent inbox / discussion	有界 message + inbox
autopilot launch prompt	带采访门禁的 MCP instructions、orchestrator_controller prompt、侧栏团队 host actions
文件 JSON 持久化	原子写入 + 工作流锁 + schemaVersion
失联恢复	租约、heartbeat、stale recovery

本实现刻意删除了与通用编排无关的业务后端、Dashboard、Redis、Gitea、会话代理和网络操作，从而缩小权限面和部署体积。

参考与归属

动态专业契约、证据化验收、开发—验收循环、最小变更约束和多智能体失败恢复等设计吸收了 msitarzewski/agency-agents 的经验，并针对本项目的三层持久侧栏、DAG、租约和 MCP 主机动作重新设计。没有把其 230+ 角色作为固定成员整体安装，也没有原样复制单个角色正文。该项目采用 MIT License，完整归属和许可见 THIRD_PARTY_NOTICES.md。

安全边界与限制

• MCP 只写入 projectRoot/.codex-orchestrator/；它不直接修改业务文件，也不执行 shell 命令。
• 当 workspace.state=absent 且路径尚不存在时，初始化工具只创建项目目录和其中的 .codex-orchestrator/ 状态目录；项目骨架仍由受范围约束的 bootstrap task 创建。
• allowedPaths 校验的是 Agent 的完成报告，不是操作系统级沙箱。实际文件权限仍由 Codex sandbox、审批策略和项目规则负责。
• specialistContract.permittedTools 是给主控和岗位线程的声明式最小权限约束，不会扩大主机已有权限，也不能代替 Codex sandbox 或审批策略。
• 这是单机/共享文件系统队列。多个 MCP 进程在同一机器上可通过锁协调；不建议把它当成跨数据中心分布式队列。
• 人工审批工具只记录明确发生的决定。主 Agent 必须先拿到用户批准，不能自行填写 resolvedBy 伪造批准。
• 原生任务创建、停止和侧栏展示由 Codex 客户端负责。MCP 通过 host action contract 要求主控调用当前 Codex App 工具，不直接控制客户端 UI 或模型进程。
• Codex App 线程工具属于主机能力，不属于 MCP 标准。CLI、IDE 或旧版 Codex 若未暴露这些工具，只能使用持久化队列和传统 spawnRecommendations，不能保证出现侧栏角色。
• 团队“持续对话”由主控的 dispatch/wait/sync 循环驱动；角色线程在一个 turn 完成后会空闲，不会在没有新消息时无限后台运行。
• GitHub/skills 侦察是有界的只读前置步骤，不是自动依赖安装器。搜索不可用时记录 status=unavailable 后继续；缺失 skill/plugin 不会在后台静默安装。
• GitHub 参考仅用于提炼经验，不是实现蓝图。主控必须先形成需求驱动的基础架构，尽量交叉综合多个来源，并持久化 baselineArchitecture、synthesizedInsights 和 originalDecisions；不得复刻单一仓库的目录、API、UI、命名或实现。
• 许可证未知或不兼容时不得复制代码；引用结果会连同 cautions 持久化，便于主控和验收追踪。

开发与验证

npm test       # 构建并运行服务层测试
npm run smoke  # 启动真实 STDIO MCP 客户端完成端到端调用
npm run check  # 两者都运行

测试覆盖三态工作区探测、GitHub/skills discovery、动态专业匹配、证据门禁和质量指标、无仓库初始化、状态不一致拒绝、依赖释放、高风险审批、路径越界、失败验证、阻塞重排、并发抢占、heartbeat/租约回收、消息、glob、循环依赖拒绝，以及执行/验收侧栏首次创建、动态专业身份路由、岗位复用、讨论路由、用户决策门禁和 v1/v2/v3→v4 自动迁移。

License

MIT