AgentBridge

状态：迁移中，本 README 描述的是旧形态。

AgentBridge 最初是 Claude-Code 到 Codex/Antigravity 的桥接工具，下文记录的所有功能目前均可正常使用。它正在被泛化，以便任何受支持的 CLI 都可以作为编排者，任何其他 CLI 都可以作为工作节点，路由由每个用户的配置文件驱动，而不是硬编码的模型名称。

关于未来方向，请阅读 docs/architecture.md 和 docs/roles.md。正在进行中的工作：provider 适配层（src/providers/）、路由配置文件（src/profile/）以及 agentbridge init 设置流程。Cursor 适配器已存在但未经验证——其标志位是根据先前知识编写的，而非从已安装的 CLI 中读取，文件顶部已注明这一点。

在迁移完成之前，请将以下各节视为对 Codex 和 Antigravity 工作节点的准确描述，并将文档视为对设计的准确描述。

编排者

AgentBridge 将其 /agentbridge … 命令面以 MCP prompts 的形式提供，因此任何支持 prompts/list 的 MCP 客户端都能从服务器本身获得相同的命令——无需安装或同步各主机的命令文件。

这些命令背后的原则位于 doctrine/ 中，不涉及任何模型名称——它按角色路由，.agentbridge/profile.json 将角色映射到用户实际安装的内容上。

一个本地小型 stdio MCP 服务器，让 Claude Code 可以将工作委派给 Codex CLI 和 Antigravity CLI（agy） 作为外部工作节点——使用你已登录的 CLI 会话，无需 API 密钥。

Claude 始终是编排者。AgentBridge 是刻意设计的简单管道：它将 Claude 的结构化请求转换为工作节点提示词，运行 CLI，然后返回紧凑的结构化结果。

User
 └─> Claude Code                      (orchestrator — decides what to delegate)
      └─> AgentBridge MCP tool        (codex_run / antigravity_run)
           └─> codex exec  |  agy --print
                └─> result
           <─ structured MCP result
      <─ Claude inspects the work and continues

Related MCP server: agent-intern

它不是什么

没有云服务、Web UI、数据库、守护进程、仪表盘、任务队列、账户系统或 API 密钥管理。它是一个 Node 进程，由 Claude Code 通过 stdio 启动，并在退出时停止。

工作原理

1. Claude 调用 codex_run 或 antigravity_run，传入结构化请求（目标、模式、模型、努力程度、路径、契约、验收标准……）。

2. AgentBridge 仅根据这些字段组装工作节点提示词。它本身不运行任何模型——这是字符串组装，不是推理。

3. 它预留写入范围，对 git 工作树做快照，然后以参数数组（shell: false）启动 CLI。

4. 它解析 CLI 的机器可读输出，提取工作节点的最终结果（绝不提取其内部推理过程），对 git 树做 diff 以确定实际变更内容，并返回紧凑的 JSON 结果。

一次 MCP 调用 = 一次工作节点尝试。AgentBridge 从不重试。是否值得再次尝试由 Claude 决定。

要求

AgentBridge 从不读取、复制、导出或修改你的 Codex 或 Antigravity 凭据。它完全像已登录的人类用户一样调用 CLI。

安装与构建

npm install

npm run build

npm test

测试套件全程使用模拟进程，因此常规的 npm test 不消耗任何模型配额。

注册到 Claude Code

在用户范围注册一次，以便每个项目都能使用：

claude mcp add --transport stdio --scope user agentbridge -- node D:\Code\Agentbridge\dist\index.js

从终端验证：

claude mcp list

claude mcp get agentbridge

然后在 Claude Code 内部通过运行 /mcp 验证。你应该看到 agentbridge 已连接，并带有三个工具：codex_run、antigravity_run、bridge_status。让 Claude 调用 bridge_status 获取完整的健康报告。

如果你重新构建了 AgentBridge，请重启 Claude Code（或从 /mcp 重新连接服务器），以便它加载新的 dist/。

项目目录

工作节点在单个项目目录中运行，并被限定在该目录内，解析顺序如下：

1. AGENTBRIDGE_PROJECT_DIR，然后是旧的 CLAUDE_PROJECT_DIR（由 Claude Code 导出）。

2. MCP 客户端通告的第一个 file:// 根目录。

3. 服务器进程的工作目录。

bridge_status 会报告实际使用的是哪一个。

工具

codex_run

模型。 可寻址三个 slug，每个都会原样传递给 CLI：

努力程度映射（编排者标签 → Codex model_reasoning_effort）：

该映射是完备且确定性的。Codex 的 ultra 层级被刻意不暴露：只有部分模型提供该层级，而一个只对三个模型中的两个有效的第六个标签会使路由依赖于具体模型。

可用性。 在启动之前，AgentBridge 会根据 Codex CLI 自身的模型目录（CODEX_HOME 中的 models_cache.json）检查请求的模型和努力程度——这是文件读取，不涉及推理。

• 模型已列出、努力程度已列出 → 任务运行

• 模型已列出、努力程度未列出 → invalid_effort，附带 details.supported_efforts

• 模型未列出 → requested_model_unavailable，附带 details.available_models

• 目录不可读 → 任务照常运行，并附带可用性为 unverified 的警告

任何内容都不会被替换为其他内容。无法兑现的路由决策会以结构化错误的形式返回，携带足够的元数据以便一步完成重新路由，而不是静默地降级为更弱的模型。

构建的调用为：

codex exec --json --skip-git-repo-check -m <MODEL> -c model_reasoning_effort="<EFFORT>" \
           -s <read-only|workspace-write> -C <PROJECT> -o <tmpfile> --color never

提示词通过 stdin 流式传输。每次调用都会传递模型、努力程度和沙箱，因此运行永远不会继承 ~/.codex/config.toml 中恰好设置的任何内容。

analyze 和 review 使用 Codex 真正的 read-only 沙箱——写入确实被阻止，而不仅仅是被劝阻。

antigravity_run

相同的模式，区别如下：

逻辑名称在运行时根据实时的 agy models 列表解析：

Antigravity 将推理层级编码在模型 id 中，因此 model + effort 解析为单个 id，无需发送单独的 --effort 标志——两者永远不会不一致。Flash 只有这三个层级：extra high 和 max 会返回 invalid_effort，而不是静默地以比你要求的更弱的层级运行。

Antigravity 被刻意限定在廉价的 Gemini 层级。agy 也提供的 Claude 模型不作为可路由标签暴露——对于 Claude 级别的推理，请使用 Claude Code 本身或 Codex，它们具有真正的沙箱能力，并且（对于 Codex）可选择努力程度。

该标签包含同一模型的有序候选 ID 列表。如果已安装的 CLI 未提供其中任何一个，调用将以 requested_model_unavailable 失败，并返回完整的可用模型列表。它绝不会静默回退到其他模型。 解析出的 ID 会在每次运行时通过 warnings 回显。

构建的调用为：

agy --print <PROMPT> --model <RESOLVED_ID> --output-format json \
    --mode <plan|accept-edits> --add-dir <PROJECT> \
    --dangerously-skip-permissions --print-timeout <N>s

--disable-slash-commands 仅针对 implement 运行添加：CLI 在禁用斜杠命令扩展时会忽略 --mode plan，因此同时发送两者会静默丢弃 Antigravity 提供的唯一无写入行为。

bridge_status

无参数。不消耗任何模型推理——它仅运行 --version 探测、agy models、一次 git rev-parse，以及读取 Codex CLI 的模型缓存。

返回：

• AgentBridge 版本、项目目录（及其解析方式）、节点/平台

• git_verification——基于 git 的 files_changed / scope_violations 在此处是否完全可用。当不可用时，空的 scope_violations 是沉默而非健康证明，警告中会明确说明

• codex.installed / version / path / auth

• codex.model_status——按模型：available | unavailable | unverified，AgentBridge 工作量标签可接受的值，以及 CLI 的原始推理级别

• codex.model_source——可用性信息来源及其新鲜度

• antigravity.installed / version / path / auth、检测到的模型、每个逻辑标签 + 层级如何解析，以及同样三态形式的 model_status

• antigravity.unsupported_efforts——Flash 无法承接的编排器标签

• 活动作业及其写入范围

• 警告

可用性从不猜测。当已安装的 CLI 不提供廉价证明时，状态为 unverified，而非任何方向的断言。

它绝不返回凭据或环境变量。

结果格式

{
  "status": "success",
  "provider": "codex",
  "model": "gpt-5.6-luna",
  "effort": "high",
  "mode": "implement",
  "duration_ms": 12345,
  "exit_code": 0,
  "summary": "...",
  "files_changed": ["src/upload.ts"],
  "scope_violations": [],
  "tests_or_checks_run": ["npm test -- upload"],
  "test_results": "12 passed",
  "concerns_or_blockers": [],
  "stderr_tail": "",
  "warnings": []
}

effort 对两个提供方均存在——Codex 推理级别，或模型 ID 编码的 Flash 层级。files_changed 和 scope_violations 由 AgentBridge 基于 git 计算，而非采信工作进程的说法。内部推理被丢弃。summary 上限为 16 000 个字符，保留开头和结尾，截断时设置 summary_truncated: true。

错误

失败返回相同信封结构，包含 status: "failed"、一个 error 类别、可操作的 message，以及（可用时）exit_code、stderr_tail 和 details 对象。

Claude 调用工作进程的示例

廉价、快速的分析：

{ "tool": "codex_run",
  "goal": "Explain how session refresh works and where it can race.",
  "mode": "analyze", "model": "gpt-5.6-luna", "effort": "light",
  "relevant_files": ["src/auth/session.ts"] }

硬性实现、最大推理、严格限定范围：

{ "tool": "codex_run",
  "goal": "Make the uploader retry 502s with exponential backoff.",
  "mode": "implement", "model": "gpt-5.6-sol", "effort": "max",
  "allowed_paths": ["src/upload.ts", "tests/upload.test.ts"],
  "no_touch": ["src/auth"],
  "contract": "export function upload(f: File): Promise<Result>",
  "acceptance_criteria": ["Retries up to 3 times", "Existing callers unchanged"],
  "tests": ["npm test -- upload"] }

两个 Codex 工作进程处理不相交的范围——它们并发运行：

{ "tool": "codex_run", "mode": "implement", "model": "gpt-5.6-sol",
  "effort": "high", "allowed_paths": ["src/api"], "goal": "..." }
{ "tool": "codex_run", "mode": "implement", "model": "gpt-5.6-luna",
  "effort": "medium", "allowed_paths": ["src/ui"], "goal": "..." }

Antigravity 处理廉价机械性工作：

{ "tool": "antigravity_run", "goal": "Summarise every exported symbol in src/lib.",
  "mode": "analyze", "model": "Gemini Flash 3.7", "effort": "light" }

{ "tool": "antigravity_run", "goal": "Build the settings page from design.png.",
  "mode": "implement", "model": "Gemini Flash 3.7", "effort": "high",
  "allowed_paths": ["src/pages/settings"] }

并发与文件范围

• implement 要求 allowed_paths。路径针对项目根目录进行规范化；任何逃逸路径（..、其他驱动器、其他位置的绝对路径）在进程启动前即被拒绝。

• 活动的 implement 作业在内存中持有其写入范围。新作业的范围与活动作业重叠时，将以 scope_conflict 被拒绝。不相交的范围并行运行——无关工作绝不串行化。

• analyze 和 review 不保留任何内容：它们从不阻塞，也从不被阻塞。

V1 限制：检测而非隔离

文件范围保护检测并报告违规；它不将每个工作进程沙箱化到各自的树中。Codex implement 工作进程以 workspace-write 权限在整个项目中运行，因此它可以写入其 allowed_paths 之外——AgentBridge 会将每个此类文件列在 scope_violations 中，将状态从 success 降级，并明确告知你。

任何内容都不会被自动还原。 还原工作进程启动前已被修改的文件会破坏你（或 Claude）的现有工作。检测加如实报告是 V1 的契约；git-worktree 隔离被有意排除在范围之外。

归因对既有状态保持谨慎：运行前已脏且运行后字节完全一致的文件绝不会归咎于工作进程。比较使用 porcelain 状态加内容哈希，已提交文件通过 HEAD 移动差异捕获。

安全

• 进程以参数数组和 shell: false 方式生成——绝不使用插值命令字符串。参数中的 shell 元字符保持字面量。

• Windows .cmd/.ps1 启动器（Node 拒绝在没有 shell 的情况下生成）被解析为其真实的 Node 入口脚本，并以 node <script> 方式运行，因此永远不需要 shell: true。

• 提示词通过 stdin 发送给 Codex；过大的 Antigravity 提示词写入临时文件并通过路径引用。两者都不会触及 Windows 32 767 字符的命令行限制。

• tests 是供工作进程使用的上下文。AgentBridge 从不执行它，且任何 MCP 参数都不会变成 AgentBridge 运行的命令。

• 项目根目录之外的路径遍历被拒绝。

• 超时终止整个进程树：Windows 上使用 taskkill /T /F，POSIX 上向进程组发送 SIGTERM，3 秒宽限期后升级为 SIGKILL。该升级刻意在直接子进程退出后仍然存活，因为那正是后代进程可能仍在运行的时刻。这是尽力而为——Node 不暴露 Windows Job Object，因此如果 taskkill 本身无法启动，则只能触及直接子进程。

• 输出缓冲区有界（每流 8 MB），UTF-8 仅在重组后解码，因此多字节字符绝不会被拆分。

• 日志仅记录作业元数据。绝不记录令牌、环境，提示词/输出仅在 AGENTBRIDGE_DEBUG=1 时记录。

• AgentBridge 无法保护你免受的威胁： 工作进程是使用你的权限运行的真实编码代理。在 implement 模式下，它可以通过自己的工具运行仓库命令。请相应限定你的 allowed_paths。

验证

AgentBridge 在工作进程退出后自行运行项目自身的检查，在任何沙箱之外，并在 verification 中返回真实输出：

"verification": [
  { "command": "npm run typecheck", "ok": true,  "exit_code": 0, "timed_out": false, "duration_ms": 4120, "output_tail": "..." },
  { "command": "npm run test",      "ok": false, "exit_code": 1, "timed_out": false, "duration_ms": 8830, "output_tail": "..." }
]

• verify_commands——在任何模式下精确运行这些命令。

• 在 implement 模式下省略——AgentBridge 读取 package.json 并运行 typecheck 和 test 脚本（如果存在）。它绝不会主动运行 build、dev 或 start；请显式要求这些。

• skip_verification: true——不运行任何内容，依赖工作进程的说法。

命令在无 shell 情况下运行，因此引号外的 |、&&、;、> 和反引号会被拒绝而非半执行。失败的检查设置 error: "verification_failed" 并将 success 降级为 partial，因此声称测试通过的工作进程无法凌驾于测试本身之上。

tests_or_checks_run 和 test_results 在验证发生时报告 AgentBridge 实际运行的内容；仅在未验证时回退到工作进程自身的声明。

由于命令来自仓库，指定了错误运行器的简报无法让 AgentBridge 运行它：测试脚本为 node --import tsx --test 的仓库将使用该命令进行检查，无论简报怎么说。

环境变量

AGENTBRIDGE_CODEX_SANDBOX=auto 对 analyze/review 使用 read-only，对 implement 使用 workspace-write——但 Windows 上沙箱化的 Codex 工作进程无法捕获子进程的输出（管道 stdio 上出现 spawn EPERM），而 npm 脚本、测试运行器和打包器都会这样做——因此它可以读取和编辑，但永远无法运行测试运行器、类型检查器或构建。这是 Codex 的限制，没有配置旋钮，因此 implement 作业在一次一次性探测确认后回退到 danger-full-access，并在 warnings 中说明。Analyze 和 review 保持其强制的 read-only 边界。在 Windows 上，如果运行因损坏的沙箱辅助程序（helper_unknown_error: apply deny-read ACLs）而失败，AgentBridge 会以 danger-full-access 重试该作业一次，在进程剩余时间内记住该结论，并为每个受影响的结果附加警告，说明边界未被强制执行。没有其他情况触发该回退，重启 AgentBridge 会重新尝试真正的沙箱——因此修复后的 Codex 版本会自动恢复它。macOS 和 Linux 从不探测、重试或回退。

日志为每个作业一行 JSON：时间戳、作业 ID、提供方、模型、工作量、模式、项目、持续时间、退出码、错误类别。

故障排查

executable_not_found——CLI 不在 Claude Code 导出给子进程的 PATH 中。在同一个 shell 中用 codex --version / agy --version 确认，或设置 AGENTBRIDGE_CODEX_BIN / AGENTBRIDGE_AGY_BIN。

authentication_required——你的 CLI 会话已过期。在终端中修复：Codex 使用 codex login，或使用 agy 重新登录。AgentBridge 刻意没有任何修复方式：它不触碰凭据。

requested_model_unavailable — 模型列表已更改，或已安装的 CLI 从未提供过该模型。运行 bridge_status（或 agy models）查看实际提供的模型；错误的 details 中已包含该信息。AgentBridge 在此处有意失败，而不是静默运行不同的模型。如果提供商重命名了模型 id，请将新 id 添加到 src/models/antigravity.ts 中该标签的候选列表（或添加到 src/models/codex.ts 中的 CODEX_MODELS），然后重新构建。

output_parse_failed — CLI 更改了其机器可读的输出格式。检查结果中的 details.stdout_head，然后与 parseCodexEvents / parseAgyOutput 进行比较。

CLI 更新之后 — 重新运行测试，然后进行实时冒烟检查：

SMOKE_LIVE=1 node scripts/smoke.mjs

这会驱动一个真实的 MCP 会话，并运行每个 worker 的最便宜配置。如果没有 SMOKE_LIVE=1，它只执行握手和 bridge_status，不消耗任何资源。

files_changed 始终为空 — 项目目录不在 git 工作树内。结果中的警告已说明这一点。变更验证需要 git。

/mcp 下没有任何内容 — 检查注册的路径指向 dist/index.js（构建后的，而非 src/），并在重新构建后重启 Claude Code。

布局

src/
  index.ts               stdio entry point
  server.ts              MCP server, tool schemas, dispatch
  config.ts              project-dir resolution, timeout clamping
  logging.ts             JSONL job log (stderr only, never stdout)
  parse.ts               worker-envelope parsing, summary capping
  types.ts
  cli/
    resolve.ts           PATH lookup + Windows shim unwrapping
    detect.ts            version probes, agy model listing, auth heuristics
    codex-catalogue.ts   zero-inference Codex model availability + effort capability
    codex-sandbox.ts     sandbox policy decision and helper-failure detection
  models/
    codex.ts             effort map, argv construction
    antigravity.ts       logical→real model resolution, argv construction
  process/
    runner.ts            shell-free spawn, bounded output, tree kill
  prompts/
    worker-prompt.ts     structured request → worker prompt
  scope/
    paths.ts             normalisation, traversal rejection, overlap
    locks.ts             in-memory write-scope registry
    git-state.ts         snapshot/diff file attribution
  tools/
    codex.ts  antigravity.ts  status.ts  common.ts
tests/                   252 tests, mocked processes, no quota used
scripts/smoke.mjs        real MCP end-to-end check