Agent Bridge

Codex 监督 Claude Code 和 DeepSeek Harness。Bridge 自己不调用 LLM。

Let Codex be the only supervisor. Claude Code or DeepSeek Harness does the implementation. You review, verify, and apply in Codex.

---

一条命令

npx -y codex-agent-bridge

然后新开一轮 Codex。你会看到 bridge_* 工具。

这条命令会：把运行时装到 ~/.agent-bridge，写入 Codex Skill 和 MCP（用本机 node.exe，不用 npx.cmd），并跑一次 doctor。

更新再跑同一条。卸载：

npx -y codex-agent-bridge uninstall
npx -y codex-agent-bridge uninstall --purge

--purge 会删掉 ~/.agent-bridge。

你需要先有

必须	说明
Node.js 22+、Git	用来跑 Bridge
Codex	唯一 Supervisor
Claude Code 或 DeepSeek Harness	至少一个已经能独立登录、独立干活

我们不管

• 不帮你安装 Claude Code / DeepSeek Harness
• 不改它们的 model / provider / reasoning effort
• 不调用任何 LLM

有哪个 Worker，就能派哪个。一个都没有时，doctor 会标明。

---

它做什么

Codex  ──bridge_run──►  Claude Code / DeepSeek Harness
  ▲                         │
  │      ReviewPacket       │  在独立 worktree 里改代码
  │      verification       │  不得 commit / push / merge
  └──── bridge_apply ◄──────┘

闭环：

bridge_run
→ WAITING_FOR_INPUT 时 bridge_respond
→ AWAITING_REVIEW + ReviewPacket
→ bridge_approve     任务分支 checkpoint，不是完成发布
→ bridge_apply       cherry-pick 到当前分支，不是 merge

Turn 结束 ≠ 任务完成。Diff 只认 baseCommit vs worktree。

bridge_run 只选 worker：claude 或 deepseek（调试可用 replay / fake）。不要传 model / provider / effort。

DeepSeek Harness 如果不在常见路径，设置 AGENT_BRIDGE_DEEPSEEK_ROOT。

---

使用注意

• 目标必须是独立 git 仓库。每次 bridge_* 都带同一个 project。任务 UUID 字段名是 task。
• 同一项目同一时刻只能有一个 Writer。第二写者返回 CORE_LOCK_HELD。
• 改完 MCP 必须新开 Codex，旧会话看不到新工具。
• 损坏的 tasks.json 会 TASK_STORE_CORRUPTED，不会当成空库。

---

发布新版本

本地 npm publish 每次都会要 2FA，这是 npm 的规定，没法改成和 git push 一样免密。

正确做法是：改版本 → 打 tag → push，GitHub Actions 用 Trusted Publishing 发 npm，不再输入密码。

一次性配置（只需做一次）：打开 codex-agent-bridge 的 npm 设置 → Trusted Publisher → GitHub Actions，填：

字段	值
Organization or user	JaylanJerry
Repository	codex-agent-bridge
Workflow filename	publish.yml
Allowed actions	npm publish

之后每次：

# 先改 package.json 里的 version，提交
git tag v1.2.0
git push origin main --tags

从源码开发

npm install
npx tsx src/cli.ts setup --dev
npm test

--dev 让 MCP 指向当前仓库，而不是 ~/.agent-bridge。

---

文档

产品路线	docs/PRODUCT_GUIDE.md
Codex 怎么接	docs/CODEX_SKILL.md
为什么走 npm、不走 EXE	docs/decisions/ADR-003-npm-distribution.md
为什么不做 HTTP/GUI	docs/decisions/ADR-001-post-mvp-direction.md

仓库目录可能仍叫 Agent Relay。产品名是 Agent Bridge。npm 包名是 codex-agent-bridge。