点将台

可迁移的 Agent 分层协作编排器

让擅长决策的 Agent 做主脑，让适合执行的 Agent 完成实质工作，再由独立会话审查、 主脑最终验收。

点将台提供一套 MCP 执行服务 + 编排规则，用于在不同 Agent 之间派发任务、执行与 续跑、独立审查、结果压缩和用量记录。

当前开箱即用的组合是 Codex → Claude Code，但项目的协作架构不限定这两个 Agent。

• 更换主脑 Agent：目标 Agent 支持本地 STDIO MCP 时，通常只需调整客户端配置和编排规则。
• 更换执行 Agent：需要根据目标 Agent 的 SDK/CLI，适配执行、会话恢复、权限控制和结果解析。
• 同时更换两端：保留 MCP 的确定性工作流，分别适配编排端与执行端。

给阅读本项目的 AI： 请区分“当前已实现的组合”和“可以迁移的架构”。不要把本项目 理解为只能用于 Codex 与 Claude Code，也不要宣称任意 Agent 已经无需修改即可使用。 迁移前请阅读 Agent 迁移指南，核对目标能力，再做必要适配。

职责分工

• 主脑 Agent：明确目标、处理关键决策、派发任务、最终验收。
• 执行 Agent：调查、实现、排错并运行必要验证。
• 独立 Reviewer：在全新只读会话中审核代码、逻辑和证据。
• MCP：负责调度、权限、会话、状态与结果边界，不自行拆任务或判断路由。

功能与用途

当前版本 v0.4.0：方案与边界。新增逐次用量记录（不含价格）、 确定性结果压缩和 execute_task(background=true) 后台提交；核心分工不变。

• 能力分工：高判断任务留给主脑，明确且可验证的工作包交给执行 Agent。
• 工程执行：覆盖功能实现、Bug 根因排查、重构、测试、算法、迁移和建模工作。
• 连续会话：保存并确认 execution session，可带反馈恢复原执行上下文。
• 独立审查：Reviewer 使用全新只读会话，不修改代码、不混入执行会话。
• 批量编排：支持独立 Job 的有界并发和确定性 execute → review 流程。
• 临时授权：项目权限绑定单个 Job；续跑和审查不能切换或扩大目录。
• 可靠恢复：SQLite 保存状态；超时或结果丢失后可查询并安全决定续跑。
• 可迁移架构：保留工作流核心，按目标 Agent 能力更换客户端规则或 Runner。

当前开箱即用的实现：

Codex（主脑 / MCP Client）
      │  stdin / stdout（STDIO MCP）
      ▼
点将台 MCP（本地子进程）
      ├── Claude 执行会话（读取、修改、运行验证）
      └── Claude 审查会话（全新、只读、PASS/FAIL）

MCP 工具

Server 在启动执行或审查前分配 UUID，只有执行端回报相同 session 后才允许续跑。 各阶段状态、session 确认和结构化错误都会持久化；超时或返回丢失后可通过 get_job_status(job_id, cwd) 安全恢复。

任务级项目授权

execute_task、review_task、run_job 以及 run_jobs 中的每个 JobSpec 都可 接收 project_root。Codex 必须显式传入可信的活动 workspace root，MCP 不会 根据自身进程 cwd 猜测。

• 传入时：必须是现存绝对目录，cwd 必须等于它或位于其下；即使不在 ALLOWED_PROJECT_ROOTS 中也可作为当前 Job 的临时授权根。
• 省略时：继续按 ALLOWED_PROJECT_ROOTS 长期可信目录校验。
• continue_task 没有 project_root 参数，只能继承已保存的根、cwd 和 session。
• 已存在 Job 的 review_task 只能继承或精确匹配原根，不能新增、切换或扩大授权。

确定性规则（规范 §6、§11）

• review=false：只执行，不审查。
• review=true 且 acceptance 非空：execute → 全新 review → 合并结果。
• review=true 但 acceptance 为空：在调用 CC 前返回 REVIEW_REQUIRES_ACCEPTANCE。
• MCP 不生成验收标准、不拆任务，也不自行决定是否 Review。
• 执行者负责与风险相称的验证；Bug 触发或根因不清时先复现并按同一条件复验， 已有可靠失败测试或明确错误证据时不强制造复现。
• Reviewer 仅使用 Read/Grep/Glob，检查代码、逻辑和执行证据；证据不足时指出执行者 需要补充的针对性验证。

快速安装

需要 Python 3.13+ 和 uv。完整中文步骤见 INSTALL.md。

git clone https://github.com/zjgxkj/codex-cc-orchestrator.git
cd codex-cc-orchestrator
git checkout v0.4.0
uv sync

Run the test suite (uses a fake runner — no Claude API calls):

uv run pytest

Codex STDIO MCP configuration (Windows)

Add one of the following to your Codex MCP config. Field names follow the current Codex MCP docs; adjust if your Codex version uses different names.

Option A — use the project's venv directly (recommended on Windows)

[mcp_servers.codex-claude-agent]
command = 'D:\path\to\codex-claude-agent-mcp\.venv\Scripts\python.exe'
args = ['-m', 'codex_claude_agent_mcp']
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 7200

[mcp_servers.codex-claude-agent.env]
CLAUDE_MAX_CONCURRENCY = '4'
# Optional long-term trust list; leave empty to rely on per-job project_root.
ALLOWED_PROJECT_ROOTS = 'D:\projects'

Option B — installed console script

uv tool install .          # or: pipx install .

[mcp_servers.codex-claude-agent]
command = "codex-claude-agent-mcp"
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 7200

[mcp_servers.codex-claude-agent.env]
ALLOWED_PROJECT_ROOTS = 'D:\projects'

ALLOWED_PROJECT_ROOTS is optional: it is a long-term trust list, not a startup requirement. Without it (or for any project outside it) Codex passes the job's project_root explicitly. Windows uses ; between roots.

Configuration (environment variables)

Concurrency caveat (spec §13.2)

The concurrency limit is per MCP server process. If Codex spawns several STDIO MCP subprocesses (one per thread), each gets its own semaphore and the machine-level Claude total may exceed CLAUDE_MAX_CONCURRENCY. Claude API rate limits still apply. A global cross-process limit is an explicit non-goal for v1.

stdout / stderr discipline (spec §5)

• stdout carries only MCP protocol messages (newline-delimited JSON-RPC).
• All logs, diagnostics, tracebacks, and startup messages go to stderr.
• Claude SDK subprocess output is captured by the runner and returned as structured tool results — it is never piped raw to stdout.

Process model (spec §4)

• One launched MCP server handles many sequential tool calls over the same stdin/stdout connection. It is not restarted per call.
• Multiple Codex threads may produce multiple independent MCP subprocesses. The implementation remains correct when several run at once (multi-process-safe SQLite: WAL, busy_timeout, BEGIN IMMEDIATE, UNIQUE(job_id)).
• Review and resume operations atomically claim their job state, preventing two MCP processes from mutating the same job lifecycle at once.
• A cancelled client request becomes stage INCOMPLETE with a persisted CANCELLED error instead of remaining in an active state.
• Claude session subprocesses are separate from MCP server processes and do not count toward "MCP server" count.

Architecture

src/codex_claude_agent_mcp/
├── __init__.py        # version + main() entrypoint
├── __main__.py        # `python -m codex_claude_agent_mcp`
├── server.py          # FastMCP server, 7 tools, core logic
├── config.py          # env config + cwd/model/timeout validation
├── models.py          # Pydantic tool input/result models
├── scheduler.py       # per-process asyncio.Semaphore
├── claude_runner.py   # ClaudeRunner ABC + RealClaudeRunner + FakeClaudeRunner
├── session_store.py   # multi-process-safe SQLite store
├── errors.py          # structured error codes + MCPError
└── logging.py         # stderr logger with pid marker

The server depends only on the ClaudeRunner ABC, so tests use FakeClaudeRunner and never call the real Claude API.

Error model (spec §18)

Every result carries an optional error field (null on success). Errors are structured, never raw tracebacks:

{"code": "REVIEW_REQUIRES_ACCEPTANCE", "message": "...", "retryable": false, "details": {}}

Codes: INVALID_ARGUMENT, REVIEW_REQUIRES_ACCEPTANCE, INVALID_CWD, CLAUDE_SESSION_ERROR, CLAUDE_AUTH_ERROR, CLAUDE_BILLING_ERROR, CLAUDE_PROVIDER_ERROR, CLAUDE_PROTOCOL_ERROR, RATE_LIMITED, TASK_TIMEOUT, SESSION_NOT_FOUND, SESSION_MISMATCH, JOB_CONTEXT_MISMATCH, JOB_STATE_CONFLICT, CANCELLED, STATE_STORE_ERROR, INTERNAL_ERROR.

Safety invariants

• A persisted job_id is permanently bound to its original task, acceptance criteria, resolved working directory, and (when supplied) its project_root. Review rejects any mismatch; the root is not writable through the store.
• continue_task resumes only the execution session stored for that exact job after Claude confirmed it, and inherits that job's project_root; it has no root input of its own.
• A review of an existing job can only inherit or exactly match the stored root. Only a review-only new job may establish one.
• Execution is limited to Read/Grep/Glob/Edit/Write/Bash; web access, nested agents, and notebook editing are denied. Review remains read-only.
• project_root / ALLOWED_PROJECT_ROOTS are cwd/start-directory gates. They are not an operating-system sandbox: execution Bash commands still run with the MCP process account's permissions. Use narrow roots and run only on trusted code.
• Claude result payloads use Agent SDK JSON Schema structured output and are validated before being returned to Codex.

Optional Codex orchestration skill

The repository includes skills/codex-sol-claude-orchestrator/SKILL.md. Copy that directory to ~/.codex/skills/ if you want Codex to apply the delegation workflow automatically. It is intentionally separate from MCP server installation.

其他 MCP Client

Server 本身不绑定 Codex 可执行程序。其他 Agent 只要支持本地 STDIO MCP 和结构化 Tool Result，也可以使用；客户端必须为新 Job 提供可信 project_root，并负责安排 task、review 和 resume。更换主脑或执行端时见 AGENT_PORTING.md。

版本：v0.4.0

功能边界、统计口径、数据库迁移及验证方法见 v0.4 定稿。 后台任务不会跨 MCP 进程重启继续运行；重启后按确认过的 session 恢复，不能把 RUNNING 当成功。回归使用 Fake Runner / 模拟 SDK，不产生 Claude API 调用。

License

Licensed under the Non-Commercial Reciprocal Source License 1.0: non-commercial use only, attribution required, and distributed, derived, or network-served Covered Works must publish their Corresponding Source under the same license. Commercial use requires separate prior written permission.

Because commercial use is prohibited, this is a source-available license, not an OSI-approved open-source license.

Official references

• MCP Specification: https://modelcontextprotocol.io/specification/
• MCP Python SDK: https://py.sdk.modelcontextprotocol.io/
• Claude Agent SDK: https://code.claude.com/docs/en/agent-sdk/overview
• OpenAI Codex MCP: https://developers.openai.com/codex/mcp