AgentBridge

简体中文 | English | Español | 给 AI Agent 的部署手册

AgentBridge 是一个本地优先的 MCP 协作核心，让 Claude Code 和 Codex 能在同一个项目中互相提问、回复、重试、达成一致，并把讨论状态保存在项目本地的 SQLite 数据库中。

当前开发版本：v0.8.1。本项目以 GitHub Release 分发本地 stdio MCP；便携包自带 Node.js 运行时，不要求用户另外安装 Node 或 npm。Release 安装后程序独立位于用户目录，不依赖下载目录或源码仓库。

当前源码验证状态：UTF-8 校验、TypeScript 构建以及完整自动化测试均已通过，其中 Release MCP 使用官方 SDK 连续完成 30 次握手。auto/reuse 会通过同一项目的 collaboration session 复用 Provider 原生会话；fresh 会建立隔离 room，并在该 room 内复用自己的 Provider 会话。上述自动化测试不等同于真实 Provider 端到端验收；只有 Claude → Codex 和 Codex → Claude 两个方向都完成实际 ask_peer 调用，才能声明真实双向通信可用。

如果你准备把本项目交给 Claude、Codex 或其他 AI Agent 自动部署，请优先让它完整阅读 README.ai.md。该手册要求 Agent 明确判断当前连接的是 Codex App 的 App Server 还是独立 Codex CLI，并完成 doctor、配置文件、MCP 工具、真实双向调用四层验收。

许可提醒：v0.5.0 起采用 PolyForm-Noncommercial-1.0.0，公开许可只允许非商业用途；商业使用需要 HeadStone1 的单独书面授权。v0.4.2 及更早已发布版本继续适用当时的 Apache-2.0，详见 许可历史。因此 v0.5.0 起应称为“源码可用（source-available）”，不应称为 OSI 开源软件。

使用方法（先看这里）

v0.6 系列最重要的变化：只需全局注册一次

安装后只运行一次 agentbridge setup。它会在 ~/.claude.json 和 ~/.codex/config.toml 中各写入一个全局 AgentBridge MCP 条目，不固定项目路径、数据库路径或 Codex cwd。以后打开项目 A、项目 B 或新项目时，不需要再次 setup。

Claude Code/Codex 第一次调用 AgentBridge 工具时，服务会依次使用显式兼容路径、CLAUDE_PROJECT_DIR、MCP roots/list、客户端启动目录识别当前项目，并在 <当前项目>/.agentbridge/agentbridge.sqlite 建立独立数据库。一个 MCP 进程只绑定一个项目，防止切换工作区后串库。如果客户端没有提供可靠项目上下文，AgentBridge 会明确报错且不会在用户目录建库；让 Agent 在第一次 ask_peer 或 list_discussions 中传入绝对 projectPath 即可。

最短安装与验证命令：

npm install --global @headstone/agentbridge
agentbridge setup
agentbridge doctor

从 v0.5.x 升级时，安装最新版后执行一次 agentbridge setup。它会把已登记的项目级 Claude/Codex 条目迁移为全局条目，保留其他 MCP 配置和各项目已有数据库。然后彻底退出并重启 Claude Code 与 ChatGPT/Codex。

1. 先选择安装方式

三种方式只需选择一种。不要把 Release、npm 和源码命令混用。普通用户直接从 AgentBridge Releases 下载即可。

2. 安装前必须满足

• Claude Code 和 Codex 必须与 AgentBridge 安装在同一台机器或同一个虚拟机中，并且都能访问目标项目目录。宿主机安装的 Codex App 不能直接为虚拟机内的 AgentBridge 提供本地 App Server。

• 先安装并登录 Claude Code。AgentBridge 当前对接的是 Claude Code，不是只有聊天界面的 Claude Desktop。

• Codex 只需满足下面任意一种：

  • 已安装并登录 Codex App；不要求另外安装 Codex CLI。

  • 已安装并登录 Codex CLI，供没有 Codex App 的服务器或虚拟机使用。

• 使用 Codex App 时，建议先正常打开并完成一次登录。AgentBridge 会发现 App 自带的 Codex 可执行文件并启动受控的 app-server 子进程，不会接管已经打开的 GUI 进程。

• 每个要使用 AgentBridge 的项目都必须拥有本地读写权限。项目路径必须真实存在，建议始终使用绝对路径。

3. GitHub Release 安装（推荐）

Windows 10/11 x64

1. 从 最新 Release 下载以下两个文件：

   • AgentBridge-v0.7.1-win32-x64.zip

   • SHA256SUMS.txt

2. 在下载目录校验压缩包。下面命令在哈希不一致时会直接报错：

$asset = 'AgentBridge-v0.7.1-win32-x64.zip'
$line = Get-Content -LiteralPath '.\SHA256SUMS.txt' |
  Where-Object { $_ -match "\s+$([regex]::Escape($asset))$" }
if (-not $line) { throw "SHA256SUMS.txt 中找不到 $asset" }
$expected = (($line -split '\s+')[0]).ToLowerInvariant()
$actual = (Get-FileHash -LiteralPath ".\$asset" -Algorithm SHA256).Hash.ToLowerInvariant()
if ($actual -ne $expected) { throw "SHA-256 校验失败，禁止安装" }
"SHA-256 verified: $asset"

3. 解压 ZIP，进入解压后的 AgentBridge-v0.7.1-win32-x64 目录，然后执行一次全局安装：

Unblock-File -LiteralPath '.\install.ps1'
powershell -ExecutionPolicy Bypass -File .\install.ps1

Test-Path 必须返回 True。安装完成时，最后应看到类似输出：

AgentBridge 0.7.1 installed in C:\Users\<用户名>\.agentbridge
Launcher: C:\Users\<用户名>\.agentbridge\bin\agentbridge.cmd
Full uninstall: & "C:\Users\<用户名>\.agentbridge\bin\agentbridge.cmd" uninstall-all --yes --remove-program
AgentBridge is registered globally. Restart Claude Code and Codex, then open any project.

在这些提示之前会依次输出 setup 和 doctor 的 JSON。setup.configured 应列出 Claude 和 Codex 两项配置结果；changed: false 只表示配置已经是最新状态，不是失败。doctor.ok: false 表示仍有环境或登录项要处理，按 recommendations 修复后重跑即可；只有 doctor 命令本身无法启动时安装脚本才会失败。

4. 运行诊断：

$ab = "$env:USERPROFILE\.agentbridge\bin\agentbridge.cmd"
& $ab version
& $ab doctor

常见 Windows 错误：

• Resolve-Path 或“找不到路径”：项目目录不存在或路径写错；先让 Test-Path 返回 True。

• 脚本被阻止：确认压缩包来自本项目 Release 且 SHA-256 已通过，然后运行上面的 Unblock-File 和 -ExecutionPolicy Bypass。

• Access denied：默认安装到当前用户的 %USERPROFILE%\.agentbridge，通常不需要管理员权限；检查安全软件的“受控文件夹访问”以及当前用户是否能写入自己的用户目录。

• 找不到 launcher：确认 %USERPROFILE%\.agentbridge\current 和 %USERPROFILE%\.agentbridge\bin\agentbridge.cmd 均存在，不要从解压目录直接移动安装后的内部文件。

Linux x64 / macOS Apple Silicon

先确认系统与架构：

uname -s
uname -m

当前 Release 不提供 Linux ARM64 或 Intel Mac x64 便携包；这些平台请使用 npm 或源码安装。

下载对应压缩包和 SHA256SUMS.txt 后校验。Linux 示例：

asset='AgentBridge-v0.7.1-linux-x64.tar.gz'
grep "  $asset$" SHA256SUMS.txt | sha256sum -c -

macOS 示例：

asset='AgentBridge-v0.7.1-darwin-arm64.tar.gz'
expected=$(awk -v file="$asset" '$2 == file {print $1}' SHA256SUMS.txt)
actual=$(shasum -a 256 "$asset" | awk '{print $1}')
test -n "$expected" && test "$actual" = "$expected" || { echo 'SHA-256 校验失败，禁止安装' >&2; exit 1; }
echo "SHA-256 verified: $asset"

解压、补充执行权限并安装：

tar -xzf "$asset"
cd "${asset%.tar.gz}"
chmod +x install.sh
./install.sh
~/.agentbridge/bin/agentbridge version
~/.agentbridge/bin/agentbridge doctor

压缩包通常已经保留执行权限；如果出现 Permission denied，重新执行 chmod +x install.sh。安装脚本会依次运行全局 setup 和 doctor；完成时应看到 AgentBridge 0.7.1 installed in ...、Launcher: ...、Full uninstall: ... 和重启提示。

4. npm 安装（已有 Node.js 的开发者）

npm 包名为 @headstone/agentbridge，要求 Node.js 22.13 或更高版本。建议全局安装，不建议使用一次性的 npx 执行 setup，因为 MCP 配置需要稳定的程序路径。

node --version
npm install --global @headstone/agentbridge
agentbridge --version
agentbridge setup
agentbridge doctor

升级 npm 安装版本：

npm install --global @headstone/agentbridge@latest
agentbridge setup

npm 安装不携带 Node 运行时。不想自行管理 Node/npm 时使用 GitHub Release 便携包。

5. 源码安装（仅用于开发）

git clone https://github.com/HeadStone1/AgentBridge.git
cd AgentBridge
npm ci
npm test
node packages/cli/dist/index.js setup
node packages/cli/dist/index.js doctor

npm test 会先构建全部 workspace，再运行单元和集成测试。源码安装的详细开发流程见后文“开发与发布”。

6. 只安装 Codex App、没有 Codex CLI

这是受支持的正常用法，不需要为了 AgentBridge 再全局安装 Codex CLI。运行 doctor 后重点检查：

{
  "providers": {
    "codexAppServer": true,
    "codexSelectedBackend": {
      "mode": "app-server",
      "source": "desktop"
    }
  }
}

• mode: "app-server" 表示实际选择了 App Server 协议。

• source: "desktop" 表示发现的是 Codex App 自带运行文件。

• codexAppDetected 只表示 GUI 进程是否正在运行，是诊断信息，不是可用性的判定条件。

• 没有独立 PATH 安装的 Codex CLI 时，不能把 codex --version 是否成功当成唯一验收标准；以 codexSelectedBackend 和后面的真实 MCP 调用为准。

• 如果显示 source: "system" 或 mode: "cli"，说明当前实际走的是系统 CLI，而不是 Codex App 后端。

7. 全局注册与多项目隔离

安装时执行一次 setup 即可。Claude 的全局条目位于 ~/.claude.json，Codex App、CLI 和 IDE 共用的全局条目位于 ~/.codex/config.toml。配置中只保存启动命令和 AGENTBRIDGE_AGENT 身份，不保存固定项目路径、数据库路径或 cwd。

每个客户端项目会启动或绑定自己的 stdio MCP 进程。首次工具调用自动创建该项目的 .agentbridge/project.json 和 .agentbridge/agentbridge.sqlite，因此项目 A 与项目 B 的讨论仍然物理隔离。切换到另一个项目时请打开新的客户端任务/窗口；一个已经绑定的 MCP 进程不会在运行中改绑，以免串库。

配置后完全退出并重新启动 Claude Code 和 Codex App；仅关闭项目窗口不一定会重新加载 MCP。从 v0.5.x 升级也只需重新执行一次无参数 agentbridge setup。

配置自主调用与讨论生命周期

AgentBridge 的运行时配置分为“全局默认”和“项目覆盖”两层，不需要再为每个项目手工设置环境变量：

• 全局配置：~/.agentbridge/config.json；可通过 AGENTBRIDGE_CONFIG_HOME 更换配置根目录。

• 项目配置：<项目>/.agentbridge/config.json；可以提交到 Git，与团队共享项目规则。

• 生效优先级：程序默认值 < 全局配置 < 项目配置 < 兼容性的 AGENTBRIDGE_* 环境变量。

• 没有写入项目配置的字段会继承全局值；项目配置只需要保存差异。

直接在项目目录运行下面的命令，会打开一次性的本地配置页面（监听 127.0.0.1；关闭页面或空闲超时后退出）：

agentbridge ui

页面可以分别编辑全局默认、当前项目覆盖，并显示最终生效值及其来源。Release 用户和源码用户分别替换为自己的 launcher 或 node packages/cli/dist/index.js ui 即可。项目路径未指定时会使用当前工作目录；从用户根目录、磁盘根目录或安装目录启动时不会把这些目录误当成项目。

最小配置示例：

{
  "version": 1,
  "invocation": {
    "autonomous": true
  },
  "discussion": {
    "maxDuration": "2h",
    "idleTimeout": "10m",
    "turnHardLimit": "1h",
    "maxTurns": 20
  },
  "session": {
    "retentionDays": 30,
    "archiveOnClose": false
  }
}

invocation.autonomous 默认是 true，允许 Agent 在判断需要跨模型协作时自主调用 ask_peer。设置为 false 后，MCP 只接受明确由用户发起的调用；调用方需要把 ask_peer.invocationOrigin 标记为 user_requested，标记为 autonomous 的调用会被拒绝。Skill 只描述讨论流程和质量要求，不能绕过这项配置。

生命周期字段支持 ms、s、m、h、d：

• discussion.maxDuration：整场讨论的最长墙钟时间，支持 null 表示不设置整体时限。

• discussion.idleTimeout：讨论在无新消息时的静默超时。

• discussion.startupTimeout、stallGrace、turnHardLimit、leaseTimeout、terminationGrace：启动、卡顿、单轮、租约和终止宽限控制。

• discussion.maxTurns：1–50 的安全上限，不代表必须完成这么多轮。

即使将 maxDuration 设为 null，静默、单轮、provider 和进程级安全控制仍然生效。完整字段、校验范围、备份行为及环境变量兼容映射见 配置说明。

8. 分四层验证安装结果

doctor 会检查安装模式、Node、项目元数据、项目登记、数据库读写、Claude/Codex MCP 配置、启动命令和 provider 后端。单项失败会写入 JSON 的 recommendations，不会因项目未初始化或 provider 不可用而中途崩溃，也不会为了检查而创建不存在的项目。它仍然不能证明已经打开的 Claude Code 或 Codex App 已重新加载 MCP 配置，因此请依次完成下面四层验证。

第一层：运行环境

& "$env:USERPROFILE\.agentbridge\bin\agentbridge.cmd" doctor 'C:\你的项目目录'

Linux/macOS 或 npm 安装时使用对应的 agentbridge doctor 命令。重点检查：

• 顶层 ok 为 true；若为 false，按 recommendations 从上到下处理后重跑。

• node.ok 和 installation.valid 为 true；Release/npm 用户还应确认 installation.sourceIndependent 为 true，源码开发模式为 false 是预期结果。

• project.initialized、project.metadataValid 和 registry.registered 为 true。

• database.ok、configuration.claude.ok、configuration.codex.ok 为 true。

• providers.claudeCli 为 true。

• Codex App 用户检查 codexSelectedBackend.mode=app-server、source=desktop。

• Codex CLI 用户检查 codexSelectedBackend.mode=cli，并确认选择的是预期命令。

第二层：配置文件确实写入

Windows：

Select-String -LiteralPath "$env:USERPROFILE\.claude.json" -Pattern 'agentbridge'
Select-String -LiteralPath "$env:USERPROFILE\.codex\config.toml" -Pattern 'mcp_servers.agentbridge|AGENTBRIDGE_AGENT|AGENTBRIDGE_PROJECT_PATH|AGENTBRIDGE_DB_PATH|cwd'

Linux/macOS：

grep -n 'agentbridge' ~/.claude.json
grep -nE 'mcp_servers.agentbridge|AGENTBRIDGE_AGENT|AGENTBRIDGE_PROJECT_PATH|AGENTBRIDGE_DB_PATH|cwd' ~/.codex/config.toml

Claude 条目应位于用户级 mcpServers.agentbridge；Codex 条目应位于用户级 [mcp_servers.agentbridge]。Claude 身份为 claude，Codex 身份为 codex；两边都不应固定 AGENTBRIDGE_PROJECT_PATH、AGENTBRIDGE_DB_PATH 或 cwd。

第三层：两个客户端已经加载 MCP

1. 完全退出并重新打开 Claude Code 和 Codex App/CLI，然后在两边打开同一个项目。

2. 在各客户端的 MCP/工具列表中确认服务器名 agentbridge 已加载。客户端版本不同，入口可能显示为 MCP、Tools 或 Integrations。

3. 应能看到八个工具：ask_peer、reply_peer、get_discussion、wait_discussion、list_discussions、close_discussion、cancel_discussion、retry_discussion。

4. 如果配置文件正确但工具没有出现，查看客户端自己的 MCP 启动错误；doctor 无法代替这一检查。

第四层：真实双向调用

先在 Claude Code 中执行：

请使用 AgentBridge 的 ask_peer 工具询问 Codex：检查当前项目 README，并概括项目用途。

再在 Codex 中执行相反方向的请求：

请使用 AgentBridge 的 ask_peer 工具询问 Claude：检查当前项目 README，并指出一项可以改进的地方。

最后检查讨论是否已保存：

& "$env:USERPROFILE\.agentbridge\bin\agentbridge.cmd" status 'C:\你的项目目录'

Linux/macOS 或 npm 安装使用 agentbridge status /absolute/path/to/your-project。只有两个方向的真实工具调用都成功，才能确认端到端联通。

9. 检查更新、安装更新和回滚

Windows：

$ab = "$env:USERPROFILE\.agentbridge\bin\agentbridge.cmd"
& $ab version
& $ab update
& $ab update --install
& $ab rollback

Linux/macOS：

~/.agentbridge/bin/agentbridge version
~/.agentbridge/bin/agentbridge update
~/.agentbridge/bin/agentbridge update --install
~/.agentbridge/bin/agentbridge rollback

update 只检查，不修改文件；只有 update --install 才会下载对应平台的 Release 包，校验 SHA256SUMS.txt 后安装。程序按版本保存在 ~/.agentbridge/versions/，项目中的配置和 SQLite 数据不会被覆盖。rollback 只切换到已经安装的上一版本。

升级后重新运行 setup 可以确认 Claude/Codex 配置仍指向当前安装位置。

10. 项目卸载和一键完整卸载

删除某一个项目的数据时执行：

& "$env:USERPROFILE\.agentbridge\bin\agentbridge.cmd" uninstall 'C:\你的项目目录' --yes

或 npm/Unix：

agentbridge uninstall /absolute/path/to/your-project --yes

该命令只会：

• 删除当前项目的 .agentbridge 运行数据和讨论数据库，但保留 .agentbridge/config.json 项目配置。

• 从自动清理登记中移除该项目。

• 保留全局 Claude/Codex MCP 条目、其他项目、其他 MCP 服务以及 AgentBridge 程序本身。

它不会删除 Release 安装目录 %USERPROFILE%\.agentbridge 或 ~/.agentbridge，也不会卸载 npm 全局包。需要保留讨论记录时，先备份项目的 .agentbridge 目录；项目配置会被自动保留。Windows、Linux、macOS 使用相同语义。

要删除所有已登记项目的 AgentBridge 配置、讨论数据和程序本身，使用一键完整卸载。该命令需要两个明确确认参数，避免误操作。

Windows Release 安装：

& "$env:USERPROFILE\.agentbridge\bin\agentbridge.cmd" uninstall-all --yes --remove-program

Linux/macOS Release 安装：

~/.agentbridge/bin/agentbridge uninstall-all --yes --remove-program

npm 安装：

agentbridge uninstall-all --yes --remove-program

完整卸载会读取 ~/.agentbridge/projects.json，并兼容发现旧版本已写入 ~/.claude.json 的 AgentBridge 项目；先删除各项目 .agentbridge 数据和全局/旧版 MCP 条目，再卸载程序。若任一项目清理失败，程序文件会保留，方便修复权限后重试。源码开发模式不会自动删除 Git 仓库；请先运行 uninstall-all --yes 清配置和数据，再自行决定是否删除源码目录。

可以在 Claude Code 或 Codex 编码任务中要求代理运行上述命令，但它仍必须获得你的命令执行授权。AgentBridge 不提供可被普通 MCP 调用直接触发的自毁工具。Windows Release 完整卸载会在后台等待 AgentBridge 进程退出；执行命令后请完全退出 Claude Code 与 Codex，程序目录随后会被删除。Linux/macOS 可在当前命令退出后删除已打开的程序文件。

Related MCP server: Agent Nudge

目录

• 它如何工作

• 使用方法（先看这里）

• 给 AI Agent 的部署手册

• English README

• README en español

• 当前功能与边界

• 虚拟机源码开发快速开始

• 配置 Claude 和 Codex

• 配置自主调用与讨论生命周期

• 首次真实联通测试

• MCP 工具说明

• 讨论状态说明

• 管理命令

• 环境变量

• 更新到最新版

• 备份、恢复与卸载

• 常见问题

• 开发与发布

• 安全说明

它如何工作

Claude Code 和 Codex 各自启动一个短生命周期的 stdio MCP 进程。两个 MCP 进程共享项目中的 SQLite 数据库，但各自代表不同的代理身份。

flowchart LR
    C["Claude Code"] -->|"stdio · AGENT=claude"| CM["AgentBridge MCP"]
    X["Codex"] -->|"stdio · AGENT=codex"| XM["AgentBridge MCP"]
    CM -->|"App Server 优先 · CLI 回退"| XP["Codex peer"]
    XM -->|"调用 Claude CLI"| CP["Claude peer"]
    CM --> DB[(".agentbridge/agentbridge.sqlite")]
    XM --> DB

AgentBridge 不会把代码或讨论上传到自己的云服务。实际模型请求仍由本机安装并已登录的 Claude/Codex 客户端发送给各自的服务商。

当前功能与边界

已实现：

• 使用 Node 内置 node:sqlite 的 SQLite WAL 存储。

• 双 MCP 进程共享讨论、消息、决定、审计事件、会话租约和 provider 原生会话 ID。

• ask_peer、reply_peer、get_discussion、wait_discussion、list_discussions、close_discussion、cancel_discussion、retry_discussion 八个 MCP 工具。

• Claude CLI、Codex CLI 和 Codex App Server 的会话 ID 通过项目级 collaboration session 持久化；auto/reuse 可跨同项目 discussion 续接 AgentBridge 所有的会话，fresh 保持隔离；续接失败时使用 SQLite 历史重建有界上下文。

• 自动发现 Codex Desktop 或新版 ChatGPT Desktop 自带的 Codex 运行程序，优先使用 App Server stdio 协议。

• App Server 不可用时自动回退到 Codex CLI exec --json 和 exec resume。

• 讨论轮数、重试次数、总消息长度和持续时间限制。

• 全局/项目两级 JSON 配置、配置来源追踪，以及用完即走的 agentbridge ui 配置页面。

• init、setup、ui、doctor、status、register-session、version、update、rollback、项目 uninstall 和系统级 uninstall-all 管理命令。

• 增量修改 Claude JSON 与 Codex TOML 配置，修改前生成备份。

• 并发 SQLite 启动锁等待与双进程回归测试。

当前边界：

• 必须在运行 AgentBridge 的系统或虚拟机内安装并登录 Claude/Codex；宿主机登录状态不会自动进入虚拟机。

• Codex App Server 适配器会启动一个新的受控子进程，不会接管已打开的 Codex Desktop 私有进程。

• agentbridge ui 只启动一次性的本地 HTTP 配置页面；没有常驻 Web 服务、PostgreSQL/Redis、严格模式或等待队列。

• 正在执行中的 provider 请求仍无法在进程崩溃后原地恢复；代码签名、静默后台更新和云端部署仍是后续工作。

• 是否能完成真实调用最终取决于本机 provider 版本、账号权限、网络和模型配额。

虚拟机源码开发快速开始

本节只适用于需要从源码构建 AgentBridge 的开发者。只想在虚拟机中使用 AgentBridge 时，优先按 README 顶部选择 Release 或 npm 安装。以下命令以 Linux/bash 为主；PowerShell 可执行同样的 git、npm 和 node 命令，只需把路径换成 Windows 路径。

1. 检查必需软件

git --version
node --version
npm --version
claude --version
# 仅 Codex CLI 用户需要：
codex --version

要求：

• Node.js 22.13 或更高版本。

• Git。

• Claude 侧需要可调用的 Claude CLI；Codex 侧可以只安装 Codex Desktop，也可以安装 Codex CLI。

• Claude/Codex 已在虚拟机内完成登录，并能各自单独执行一次普通请求。

GUI 用户不要求手工把 Codex 加入 PATH。新版 ChatGPT Desktop 的 MSIX 包内 runtime 不允许包外程序直接执行，因此 AgentBridge v0.7.1 随 npm/便携包安装官方 @openai/codex CLI，并优先用它启动独立 stdio App Server；同时兼容旧 Codex Desktop 的 %LOCALAPPDATA%\OpenAI\Codex\bin\codex.exe 及其版本化运行文件，最后才尝试 PATH 中的 codex。ChatGPT Desktop 登录不保证独立 CLI 已登录；若 codex login status 未登录，在同一 Windows 用户下执行一次 codex login。

如果 node --version 低于 v22.13.0，先升级 Node。Node 22.5–22.12 的 node:sqlite 默认仍需要实验开关，不在本项目支持范围内。

2. 获取或更新代码

首次下载：

git clone --branch main --single-branch https://github.com/HeadStone1/AgentBridge.git
cd AgentBridge

已经克隆过：

cd AgentBridge
git pull --ff-only origin main

确认版本：

git log -1 --oneline

3. 安装依赖并构建

npm ci
npm test

npm test 会先完成构建，再运行全部测试。测试成功时应看到所有测试通过；构建产物位于各 package 的 dist/ 目录。

4. 全局配置

源码模式也只需运行一次：

node packages/cli/dist/index.js setup
node packages/cli/dist/index.js doctor

setup 会增量更新用户级 ~/.claude.json 和 ~/.codex/config.toml，修改前创建 *.agentbridge.bak，并保留其他 MCP 服务。两个条目使用同一入口，但身份分别为 AGENTBRIDGE_AGENT=claude 和 AGENTBRIDGE_AGENT=codex。

全局条目不能包含固定的 AGENTBRIDGE_PROJECT_PATH、AGENTBRIDGE_DB_PATH 或 Codex cwd。项目路径在 MCP 运行时识别，数据库始终位于识别出的 <项目>/.agentbridge/agentbridge.sqlite。

如果使用自定义配置位置：

node packages/cli/dist/index.js setup \
  --claude-config /path/to/claude.json \
  --codex-config /path/to/codex/config.toml

5. 运行诊断

node packages/cli/dist/index.js doctor
node packages/cli/dist/index.js status /absolute/path/to/project

重点检查 doctor：configuration.claude.scope 和 configuration.codex.scope 应为 global，两端 dynamicRouting 应为 true；providers.codexSelectedBackend.mode 默认优先为 app-server，source: desktop 表示发现 Codex App 自带后端。尚未调用过工具的项目没有 .agentbridge 属于正常状态，doctor 会显示 autoInitialize: true，不要求为每个项目 setup。

相关用户级配置和 MCP roots 能力见 Claude Code MCP 文档 与 OpenAI Codex MCP 文档。

Codex GUI 优先与 App Server

默认策略为 auto，无需提供 Codex CLI 路径：

1. 先检查显式环境变量。

2. 自动查找 Codex Desktop 自带的可执行程序。

3. 对每个候选程序运行 app-server --help 能力探测。

4. 优先启动独立的 stdio App Server；不支持时才回退到 codex exec。

App Server 是 OpenAI 为富客户端集成提供的公开协议，stdio 是默认传输。参见 OpenAI Codex App Server 文档。

一般用户只需运行：

node packages/cli/dist/index.js setup
node packages/cli/dist/index.js doctor

如果自动发现失败，可以显式指定支持 App Server 的可执行程序：

node packages/cli/dist/index.js setup \
  --codex-app-command /absolute/path/to/codex-executable

也可以设置：

export AGENTBRIDGE_CODEX_APP_COMMAND=/absolute/path/to/codex-executable

也可以强制后端模式：

# 只允许 App Server，探测失败时直接报错
node packages/cli/dist/index.js setup --codex-mode app-server

# 强制使用传统 CLI 通道
node packages/cli/dist/index.js setup --codex-mode cli \
  --codex-command /absolute/path/to/codex

GUI 优先不等于接管当前窗口。AgentBridge 会复用 GUI 安装中公开的 Codex 运行程序和登录配置，但会启动新的受控 App Server 子进程；它不会连接到已经打开的 Codex Desktop 私有会话，也不会读取当前 GUI 对话。

首次真实联通测试

完成配置后，完全退出并重新启动 Claude Code 和 Codex，使 MCP 配置重新加载。

从 Claude 发起

在 Claude Code 中输入类似请求：

请使用 AgentBridge 的 ask_peer 工具询问 Codex：
检查当前项目的 README，并用一句话回复是否能正常读取项目。

Claude 调用的工具参数应类似：

{
  "peer": "codex",
  "message": "检查当前项目的 README，并用一句话回复是否能正常读取项目。",
  "projectPath": "/absolute/path/to/AgentBridge"
}

成功响应通常包含：

• discussionId，例如 dsc_...。

• messageId。

• status: "DISCUSSING"。

• provider 可用时的 peerResponse。

从 Codex 发起

在 Codex 中输入：

请使用 AgentBridge 的 ask_peer 工具询问 Claude：
总结 package.json 中提供的 npm scripts。

Codex 侧 peer 必须是 claude。

检查持久化结果

node packages/cli/dist/index.js status .

也可以让任一代理调用：

{
  "name": "list_discussions",
  "arguments": {
    "projectPath": "/absolute/path/to/AgentBridge"
  }
}

如果真实调用失败，讨论记录仍可能保存为 PEER_BUSY、FAILED 或 TIMEOUT，可通过 status 或 get_discussion 查看。

MCP 工具说明

ask_peer

开始一场新讨论，并调用另一代理。

{
  "peer": "codex",
  "message": "请审查这个实现方案。",
  "projectPath": "/project/path",
  "mode": "review"
}

• Claude 侧只能选择 codex。

• Codex 侧只能选择 claude。

• projectPath 可省略，默认使用 MCP 进程当前工作目录。

• 返回的 discussionId 用于后续所有操作。

• mode 可选：review、discussion、deep-discussion。review 是一次独立评审；discussion 和 deep-discussion 会在两个 Provider 间自动交替，达成共识后立即进行结论 hash 双签；安全上限分别为 3、12、20，不是必须完成的次数。

• 自动模式要求 Claude 和 Codex 两个 connector 都已配置；缺少任意一个时会明确返回 UNAVAILABLE，不会静默降级为单轮回答。

• ask_peer 固定同步执行：review 等待本次对端回复，自动模式等待整场讨论到完成、需要用户决策或已记录失败后才返回，不再转入后台并返回中间 WAIT。

• maxTurns 可选，范围 1–50；它覆盖模式默认值，只是安全上限，不是必须聊满的目标。

• get_discussion 会返回持久化的 mode、maxTurns 和最新 lastSignal；对端明确返回 NEEDS_USER_DECISION 时讨论会暂停交给用户决策。

reply_peer

继续手动/review 讨论，并把回复发送给另一参与者；自动讨论运行期间不能插入回复，暂停后可用它提交用户决定并恢复讨论。

{
  "discussionId": "dsc_xxxxxxxxxxxx",
  "message": "我接受第一点，但建议修改超时策略。"
}

发送者由当前 MCP 宿主身份决定，不需要在参数中指定。

get_discussion

读取讨论详情、全部消息以及最终决定。

{
  "discussionId": "dsc_xxxxxxxxxxxx"
}

wait_discussion

兼容性观察工具，用于读取已有 discussion 的后续状态；正常的同步 ask_peer / reply_peer 流程不需要调用它，等待超时也不会改变讨论状态：

{
  "discussionId": "dsc_xxxxxxxxxxxx",
  "timeoutMs": 30000,
  "afterMessageId": "msg_xxxxxxxxxxxx"
}

同一问题必须复用原 discussionId；不要为了读取状态再次调用 ask_peer。setup 会为 Claude Code 和 Codex 安全安装四项轻量 Skill：核心协作 Skill 可自动路由，三个专项 Skill 仅在明确调用时启用；同名自定义或已修改 Skill 不会被覆盖。

list_discussions

列出讨论。可按项目路径过滤：

{
  "projectPath": "/project/path"
}

不传 projectPath 时会列出当前数据库中的全部讨论。

close_discussion

记录当前代理对结论的接受，并自动请求对端确认：

{
  "discussionId": "dsc_xxxxxxxxxxxx",
  "conclusion": "采用 WAL，并在申请写锁前设置有界等待。"
}

重要规则：

• AgentBridge 会把规范结论和 decision hash 发送给对端，要求对端返回结构化的接受或拒绝结果。

• 对端接受同一 hash 时自动记录第二份 agreement，进入 COMPLETED 并生成决定记录。

• 对端接受同一 hash 时自动完成；拒绝确认时会根据 resolution 区分继续讨论或进入 NEEDS_USER_DECISION。无法统一的目标、风险或偏好会保留双方观点并交给用户决策。

• 对端临时不可用、回复格式无效或需要重试时保持可恢复状态，调用方可以在同一讨论上继续或重试。

• 自动确认不可用时仍兼容手工双签：另一个代理可使用相同 discussionId 和完全相同的 conclusion 调用一次 close_discussion。

讨论消息始终完整保存在 SQLite 中。发送给新 provider 会话的恢复上下文采用“首条提案 + 尽可能多的最近消息”，默认历史字符预算为 48,000，并对单条历史消息截断；成功续接 provider 原生会话时不会重复注入历史。

cancel_discussion

取消讨论并释放本地会话租约：

{
  "discussionId": "dsc_xxxxxxxxxxxx"
}

retry_discussion

在 FAILED、PEER_BUSY、TIMEOUT 或 NEEDS_USER_DECISION 后，重新派发最后一条消息：

{
  "discussionId": "dsc_xxxxxxxxxxxx"
}

失败重试会消耗重试预算。达到上限后，讨论进入 NEEDS_USER_DECISION。

讨论状态说明

管理命令

Release 安装用户在 Windows 使用：

& "$env:USERPROFILE\.agentbridge\bin\agentbridge.cmd" <command> [path] [options]

Linux/macOS 使用：

~/.agentbridge/bin/agentbridge <command> [path] [options]

从源码运行的开发者使用：

node packages/cli/dist/index.js <command> [path] [options]

查看帮助：

node packages/cli/dist/index.js help

手动登记会话示例：

node packages/cli/dist/index.js register-session \
  --provider codex \
  --session-id SESSION_ID \
  --status IDLE \
  --project-path . \
  --metadata '{"source":"manual"}'

支持的会话状态为 IDLE、BUSY、BRIDGE_OWNED、ARCHIVED 和 UNKNOWN。

环境变量

不要把测试专用的 AGENTBRIDGE_TEST_* 变量用于生产配置。

更新到最新版

Release 安装用户

检查新版不会修改本机：

& "$env:USERPROFILE\.agentbridge\bin\agentbridge.cmd" update

确认后安装：

& "$env:USERPROFILE\.agentbridge\bin\agentbridge.cmd" update --install

更新流程会：

1. 调用 HeadStone1/AgentBridge 的 GitHub Releases API。

2. 选择当前操作系统和 CPU 架构对应的包。

3. 下载 Release 包与 SHA256SUMS.txt。

4. 校验 SHA-256；缺少校验文件或校验失败时拒绝安装。

5. 安装到 ~/.agentbridge/versions/<版本>/，再切换 current 版本指针。

6. 保留旧版本、项目 MCP 配置和项目 SQLite 数据。

安装成功后重启 Claude Code 和 Codex。需要回退时：

& "$env:USERPROFILE\.agentbridge\bin\agentbridge.cmd" rollback

Linux/macOS 把命令入口替换为 ~/.agentbridge/bin/agentbridge。

源码安装用户

在虚拟机或目标机器中执行：

cd AgentBridge
git status
git pull --ff-only origin main
npm install
npm test
npm run build
node packages/cli/dist/index.js setup
node packages/cli/dist/index.js doctor

如果 git status 显示有未提交修改，先确认这些修改是否需要保留。需要保留时：

git stash
git pull --ff-only origin main
git stash pop

不要在不了解本地修改用途时执行强制重置。

备份、恢复与卸载

配置备份

AgentBridge 修改已有配置前会创建：

• ~/.claude.json.agentbridge.bak

• ~/.codex/config.toml.agentbridge.bak

每次配置前建议另外复制一份带时间戳的备份，因为固定名称的 .agentbridge.bak 可能被后续操作覆盖。

Linux 恢复示例：

cp ~/.claude.json.agentbridge.bak ~/.claude.json
cp ~/.codex/config.toml.agentbridge.bak ~/.codex/config.toml

讨论数据备份

停止 Claude/Codex 后，复制整个 .agentbridge 目录：

cp -a .agentbridge .agentbridge.backup

数据库可能使用 -wal 和 -shm 文件，因此不要只复制主 .sqlite 文件，也不要在活跃写入期间直接复制。

卸载

node packages/cli/dist/index.js uninstall . --yes

该操作会：

• 从 Claude/Codex 配置中移除名为 agentbridge 的 MCP 条目。

• 保留其他 MCP 服务和 provider 配置。

• 删除当前项目的 .agentbridge 运行数据和讨论数据库，保留 .agentbridge/config.json。

卸载会删除本地讨论数据；项目配置不会被删除，需要保留讨论数据时仍应先执行备份。

这只是“项目卸载”：不会删除 Release 安装目录 %USERPROFILE%\.agentbridge / ~/.agentbridge，也不会卸载 npm 全局包。完整卸载直接运行：

agentbridge uninstall-all --yes --remove-program

Release 安装用户使用固定 launcher 的完整路径运行同一命令；详见 README 顶部“项目卸载和一键完整卸载”。完整卸载失败时不会继续删除程序，修复输出中的权限或配置错误后可以重试。

常见问题

Cannot find module 'node:sqlite' 或 SQLite 实验功能错误

原因：Node 版本过低。

node --version

升级到 Node 22.13 或更高版本，然后重新执行：

npm install
npm run build

Claude 或 Codex 后端诊断异常

Claude Code 用户先执行：

claude --version

Codex CLI 用户再执行：

codex --version

只安装 Codex App 的用户不要求 PATH 中存在 codex 命令，应检查 providers.codexSelectedBackend.mode 是否为 app-server、source 是否为 desktop。如果 provider 只在某个 shell 中可用，请在 MCP 配置中把 AGENTBRIDGE_CLAUDE_COMMAND 或 AGENTBRIDGE_CODEX_COMMAND 设置为绝对路径。还要确认 provider 已在 AgentBridge 所在的同一台机器或虚拟机内完成登录。

MCP 工具中出现了错误的 peer

例如 Codex 侧的 ask_peer 仍只允许选择 codex，通常说明 Codex MCP 被错误识别成 Claude。

检查 Codex 的 config.toml：

env.AGENTBRIDGE_AGENT = 'codex'

Claude 侧则应为：

"AGENTBRIDGE_AGENT": "claude"

修改后完全重启两个 provider。

两边看不到同一场讨论

确认两个配置中的 AGENTBRIDGE_DB_PATH 完全相同，并且虚拟机用户对该目录有读写权限。建议使用绝对路径。

database is locked

当前版本会在启动阶段进行 5 秒有界等待。若仍出现锁错误：

1. 确认使用的是最新 main 并已重新构建。

2. 确认数据库不在不可靠的网络共享或不支持标准文件锁的挂载点。

3. 关闭遗留的 Claude/Codex/MCP 进程后重试。

4. 不要让多个不同项目误用同一个数据库路径。

peer is not available 或 PEER_BUSY

执行：

node packages/cli/dist/index.js doctor .

确认 Claude CLI 或 Codex 实际选中的 App Server/CLI 后端可运行、账号已登录、网络正常。问题解决后调用 retry_discussion，无需重新创建讨论。

Codex 后端不可用或返回 no agent message

先运行诊断并查看实际选中的后端：

node packages/cli/dist/index.js doctor .

如果 codexSelectedBackend.mode 是 app-server，检查对应程序能否执行 app-server --help。如果模式是 cli，再独立验证：

codex --version
codex exec --json "只回复 OK"

如果底层命令本身失败，先修复 Codex 安装、登录或网络；AgentBridge 无法绕过 provider 的认证或账号限制。

修改配置后 MCP 工具没有出现

1. 检查 JSON/TOML 语法。

2. 确认 command 和 args 都是绝对路径。

3. 重新执行 npm run build。

4. 完全退出并重启 Claude Code/Codex。

5. 再运行 doctor。

git pull --ff-only 失败

先执行：

git status
git branch --show-current
git remote -v

确认当前在 main，远端是 https://github.com/HeadStone1/AgentBridge.git，并处理未提交修改后再更新。

Windows 提示 Git dubious ownership

仅在确认仓库确实属于当前用户后执行：

git config --global --add safe.directory C:/absolute/path/to/AgentBridge

不要把不可信目录加入安全列表。

开发与发布

开发要求 Node.js 22.13 或更高版本。

npm install
npm test
npm run build
npm run baseline
npm run release
npm run release:package
npm run release:npm

脚本说明：

• npm test：运行单元和集成测试。

• npm run build：按依赖顺序构建所有 workspace。

• npm run baseline：测量 MCP 启动时间和内存基线。

• npm run release：重新构建并生成 release/agentbridge-mcp.mjs 与 release/agentbridge-cli.mjs。

• npm run release:package：为当前平台生成包含 Node 运行时、固定 launcher 和安装脚本的 artifacts/AgentBridge-v版本-平台-架构/。

• npm run release:npm：生成只包含编译 bundle 和必要文档的 artifacts/npm/，包名为 @headstone/agentbridge。

release/*.mjs 是需要 Node 的单文件 bundle；最终 GitHub Release 压缩包会同时携带 Node 运行时，因此普通用户不需要预装 Node/npm。它仍不是代码签名的原生 EXE。

发布新版本

1. 修改根目录 package.json 的版本号，并更新 README/DEVLOG。

2. 执行：

npm ci
npm test
npm run release:package

3. 提交代码后创建与 package.json 完全一致的标签：

git tag v0.7.1
git push origin main
git push origin v0.7.1

标签推送后，GitHub Actions Release 工作流 会再次执行构建和测试，然后分别在 Windows、Linux、macOS runner 上打包自带运行时的压缩包，生成 SHA256SUMS.txt，最后创建 GitHub Release。标签与 package.json 版本不一致时工作流会拒绝发布。

预发布版本使用标准 SemVer，例如把版本改为 0.4.1-beta.1，再推送 v0.4.1-beta.1 标签；工作流会把它标记为 GitHub prerelease，用户通过 update --channel beta 检查。

首次发布 npm 包

第一次创建 @headstone/agentbridge 时，需要包所有者在自己的终端完成 npm 登录和首次发布，不要把密码、Token 或一次性验证码提交到仓库或发送给其他人：

npm login
npm run release:npm
npm pack ./artifacts/npm --dry-run
npm publish ./artifacts/npm --access public

首次发布成功后，在 npmjs.com 的 @headstone/agentbridge 包设置中添加 GitHub Actions Trusted Publisher：

• GitHub owner：HeadStone1

• Repository：AgentBridge

• Workflow：release.yml

• Environment：留空，除非以后专门创建 npm 发布 environment

之后推送与 package.json 版本一致的 Git 标签时，Release 工作流会通过 GitHub OIDC 发布 npm 包并生成 provenance，不需要在 GitHub Secrets 中保存长期 npm Token。若相同版本已由首次手工发布，工作流会检测后跳过，避免重复版本导致失败。

项目主要目录：

packages/protocol       协议类型和状态机
packages/storage        SQLite 存储
packages/audit          审计与指标
packages/connectors     Claude/Codex/App Server 连接器
packages/collaboration  协作业务逻辑
packages/mcp            MCP Server 与 stdio 入口
packages/cli            管理命令与配置写入
tests                   单元和双进程集成测试
release                 打包后的 Node artifacts
artifacts               当前平台的便携 Release 目录（不提交 Git）
scripts                 打包、安装与固定 launcher
.github/workflows       标签触发的跨平台 Release 自动化

安全说明

• Claude 连接器使用 print/plan 模式，不开启 permission bypass。

• Codex 连接器默认使用 read-only sandbox，不默认启用危险权限绕过。

• 子进程通过参数数组启动，未使用 shell 字符串拼接。

• 对端讨论内容被标记为不可信上下文，但模型输出仍应由调用方审查。

• .agentbridge/agentbridge.sqlite 包含讨论消息和审计信息，默认未加密；请按项目敏感级别保护文件权限和备份。

• provider 配置备份可能包含其他 MCP 环境变量或凭据，不要上传到公共仓库。

• AgentBridge 不会替代 Claude/Codex 自身的权限、沙箱、认证和网络安全策略。

许可证与商业使用

AgentBridge v0.5.0 及以后版本采用 PolyForm Noncommercial License 1.0.0：

• 个人研究、实验、学习、业余项目等许可证列明的非商业用途可以使用。

• 除版权持有人外，公开许可证不授予商业使用权；销售、付费托管、纳入商业产品或把 AgentBridge 作为付费交付的重要组成部分前，必须取得 HeadStone1 的单独书面商业授权。

• 对用途是否属于商业用途存在疑问时，请先停止部署并联系作者确认，不要自行推定获准。

• 第三方依赖和随包运行时继续适用各自的许可证。

完整条款见 LICENSE，必需版权通知见 NOTICE，实际场景说明见 COMMERCIAL_LICENSE.md。这些说明不能追溯改变已经按 Apache-2.0 发布的 v0.4.2 及更早版本；版本边界见 LICENSE_HISTORY.md。

由于禁止商业用途不符合 OSI 对开源许可证“不得限制使用领域”的定义，本项目从 v0.5.0 起是公开源代码的非商业软件，而不是 OSI 认可的开源软件。此处是项目许可说明，不是法律意见。

最小验收清单

部署完成后逐项确认：

• node --version 不低于 22.13。

• npm test 全部通过。

• npm run build 成功。

• Claude 配置包含 AGENTBRIDGE_AGENT=claude。

• Codex 配置包含 AGENTBRIDGE_AGENT=codex。

• 两边使用同一个绝对 AGENTBRIDGE_DB_PATH。

• doctor 能检测到需要的 provider。

• Claude 能通过 ask_peer 收到 Codex 回复。

• Codex 能通过 ask_peer 收到 Claude 回复。

• status 能看到刚才的讨论记录。

• 一边提交结论且对端结构化接受后，讨论自动进入 COMPLETED；无法自动确认时手工双签仍可完成。