covalent-bond

Covalent Bond

安全信道，让两台不同机器上的 AI 编码 Agent 像一个整体般协同工作。

快速开始 · 工作原理 · 工具 · 安全性 · 架构 · 参与贡献

---

共价键是两个原子共享一对电子。Covalent Bond 则让两台不同机器上的两个编码 Agent 共享同样基本的东西：一条私有、经过身份验证的信道，以及借助这条信道协作的方式。

想象两位开发者远程结对编程。一位调校好了自己的 Agent（技能组织有序、约定清晰、加载了恰当的上下文），因此能产出出色的成果。另一位则更随性一些，他的 Agent 做出的东西也就还行。Covalent Bond 就是缩小差距的信道：调校完善的一方可以交付文件、上下文和约定，让自己的 Agent 表现出色，从而让两个 Agent 都逐步采用同一种高质量的工作方式。它联结的不只是两个 Agent，还有两种工作方式；双方地位平等，让较弱的一方提升到较强一方的水平。

它采用点对点和端到端加密：两个 Agent 配对后，通过中继交换消息和文件，而中继永远无法读取传输内容。它适用于任何兼容 MCP 的 Agent（Claude Code、Cursor、Codex、Windsurf、Cline 等），通过 Model Context Protocol 提供 bond_* 工具。它还让人类参与其中：每个收到的文件都必须先获得明确同意，才会写入磁盘。

• 🤝 联结两种工作方式：共享文件、上下文和约定，让两个 Agent 一起提升
• 🔒 经过身份验证的 E2EE：恶意中继无法读取信道内容，也无法对信道实施 MITM 攻击
• 🌐 跨机器协作：通过不具备其他功能的中继，在任意位置配对 Agent（无需开放入站端口）
• 🙋 人类参与其中：写入任何文件前都需征得同意；提供完整审计日志
• 🔌 不绑定 Agent：支持任何 MCP 客户端，不局限于某个供应商

它不会神奇地将一种配置克隆到另一台机器上。它提供的是一条安全、需经同意的信道，让两台原本无法互相连接的机器能够有意地共享各自的工作方式。

快速开始

快捷方式：让你的 Agent 完成所有设置。 将 docs/AGENT-SETUP.md 粘贴给任意编码 Agent，并说“设置 Covalent Bond”。它会引导 Agent 完成安装、中继配置、MCP 注册和配对，并在只有人类才能完成的步骤前明确暂停。

或者，先在两台设备上自行完成（步骤 1–2），然后配对（步骤 3）。

1. 向你的 Agent 注册 MCP 服务——无需安装，npx 会获取 npm 包。对于 Claude Code：

   claude mcp add --scope user --env COVALENT_RELAY_URL=https://covalent-bond-relay.gopalrajsuresh.workers.dev covalent -- npx -y covalent-bond
   

   （--scope user 会让每个项目都能使用 bond_* 工具。环境变量指向公共中继；若要自行托管，请参阅选择中继。）

   对于其他 MCP 客户端（Cursor、Codex、Windsurf 等），这种标准的 stdio-server 配置适用于大多数客户端；将其粘贴到客户端的 MCP 设置 JSON 中（顶层键通常是 mcpServers 或 servers）：

   {
     "mcpServers": {
       "covalent": {
         "command": "npx",
         "args": ["-y", "covalent-bond"],
         "env": {
           "COVALENT_RELAY_URL": "https://covalent-bond-relay.gopalrajsuresh.workers.dev"
         }
       }
     }
   }
   

   Windows 和本地测试说明

   在 Windows 上，如果你的客户端难以直接启动 npx，请使用包装命令："command": "cmd", "args": ["/c", "npx", "-y", "covalent-bond"]。若要在没有已部署中继的情况下进行本地测试，请从源代码检出目录运行模拟中继（npm run relay:dev），并将 COVALENT_RELAY_URL 指向 http://localhost:8787。

   更希望从源代码运行？

   git clone https://github.com/gopalrajsuresh/covalent-bond.git covalent-bond
   cd covalent-bond
   npm install
   npm test                    # optional but recommended; all suites run offline
   cp .env.example .env        # PowerShell: Copy-Item .env.example .env
   

   .env 已包含公共中继 URL。然后使用 command: node 注册，args 为 /absolute/path/to/covalent-bond/bin/cli.js（Claude Code：claude mcp add --scope user covalent -- node /absolute/path/to/covalent-bond/bin/cli.js），无需环境变量。

2. 重启 Agent 会话，然后验证：让 Agent 运行 bond_status。它应回复“No active session”（无活动会话），这表示工具已就绪。

3. 配对并共享

   • 设备 A：“创建 Covalent Bond 会话” → Agent 运行 bond_connect → 你会获得一个类似 AbCd-1234-XyZw 的代码。
   • 通过带外渠道（聊天或语音，绝不要通过中继）将代码告知另一位用户。
   • 设备 B：“加入 Covalent Bond 会话 AbCd-1234-XyZw” → Agent 运行 bond_join。
   • 任意一方：bond_status → 安全通道已建立 → 发送文件（bond_send）和消息（bond_message）。收到的文件会等待人类执行 bond_accept。
   • 完成后？双方都运行 bond_end。

工作原理

两个 Agent 会在一个设计上不可信的中继处会合——中继只转发密文，永远无法解密。会话代码在人与人之间传递，绝不会经过中继；这个带外密钥用于验证通道：

sequenceDiagram
    participant A as Agent A (host)
    participant H as Humans (out-of-band)
    participant R as Relay (untrusted)
    participant B as Agent B (guest)

    A->>A: bond_connect → session code
    A-->>H: code shared by chat / voice
    H-->>B: code entered on the other side
    B->>B: bond_join(code)
    A->>R: ephemeral public key (routing ID only)
    B->>R: ephemeral public key (routing ID only)
    Note over A,B: key = X25519 ⊕ session code → AES-256-GCM
    A->>R: ciphertext
    R->>B: ciphertext (relay sees nothing else)
    B->>B: file held until human runs bond_accept

如果中间环节篡改密钥交换，密钥确认就会失败，会话会在任何数据传输之前中止——恶意中继既无法读取，也无法冒充任何一方。

选择中继

中继只是一个简单的管道，从设计上就不可信：它只能看到随机路由 ID 和密文，永远看不到会话代码、密钥或明文；即使中继是恶意的，也无法读取或伪造任何内容（测试套件中的 MITM 场景对此有覆盖）。因此，下面两个选项同样安全；选择哪个纯粹取决于方便程度。

选项 1：使用公共中继（最快）

COVALENT_RELAY_URL=https://covalent-bond-relay.gopalrajsuresh.workers.dev

会话在 30 分钟无活动后过期，不会保留任何内容。可用性尽力保障，并设有速率限制。

在哪里设置 COVALENT_RELAY_URL（两处任选其一；真实环境变量优先于 .env）

• .env 文件（最简单）：将 .env.example 复制到 covalent-bond 文件夹中的 .env，然后编辑该值。MCP 服务会在启动时读取它，因此无论你在哪个项目中使用 Agent，该设置都会生效。

• MCP 客户端配置：注册服务时传入该值，例如用于 Claude Code：

  claude mcp add --scope user --env COVALENT_RELAY_URL=https://... covalent -- node /absolute/path/to/covalent-bond/bin/cli.js
  

  对于其他 MCP 客户端，请将其添加到 JSON 配置中服务的 env 块。

更改任一设置后，请重启 Agent 会话，以便重新启动 MCP 服务。

选项 2：约 2 分钟内部署自己的中继（需要免费的 Cloudflare 帐户）

npm install -g wrangler
wrangler login          # opens the browser; create a free account if you don't have one
cd cloudflare-worker
wrangler deploy         # prints your relay URL: https://covalent-bond-relay.<your-subdomain>.workers.dev

然后在两台机器上将 COVALENT_RELAY_URL 设置为该 URL。完整详情（Durable Object 迁移、可选的按 IP 限流、本地 wrangler dev）请参阅 cloudflare-worker/README.md。

或者让你的 Agent 来部署

将以下内容粘贴给在此代码库中运行的任意编码 Agent：

部署我自己的 Covalent Bond 中继：如果尚未安装 wrangler，则安装；运行 wrangler login 并等待我在浏览器中完成身份验证，然后从 cloudflare-worker/ 运行 wrangler deploy，并告知我应该在两台机器上将 COVALENT_RELAY_URL 设置为什么 URL。请遵循 cloudflare-worker/README.md。

唯一需要手动完成的步骤是在浏览器中登录；其余工作由 Agent 处理。

配对两个 Agent

1. 机器 A："创建一个 Covalent Bond 会话。" → Agent 调用 bond_connect 并返回类似 AbCd-1234-XyZw 的代码。
2. 通过带外方式将该代码分享给机器 B（聊天、语音、当面告知）。这是保护连接的秘密。切勿将它粘贴到中继中。
3. 机器 B："加入 Covalent Bond 会话 AbCd-1234-XyZw。" → Agent 调用 bond_join。
4. 当 bond_status 显示安全通道已建立时，即可开始分享："将 src/auth.js 发送给我的对端，" 或者交接让你的 Agent 更出色的内容：技能文件、约定文档，以及塑造其工作方式的上下文。对端会看到同意提示，并在接受后才会写入任何内容；收到的内容会以不可信数据的形式封装，供另一个 Agent 阅读和采用。

工具

• bond_connect — 创建会话并获取可分享的会话码
• bond_join — 使用通过带外方式分享的代码加入会话
• bond_status — 查看连接状态、待处理传输和新事件
• bond_send — 向已连接的对端发送文件，端到端加密
• bond_message — 向对端发送简短的加密文本消息
• bond_wait — 长轮询以等待下一个对端事件
• bond_accept — 在获得人工同意后接受待处理的文件传输
• bond_decline — 拒绝待处理的文件传输
• bond_end — 结束会话并断开与中继的连接

完整参考：

工具	参数	功能	要求
bond_connect	—	以主机身份创建会话；返回可通过带外方式分享的代码	—
bond_join	sessionCode	使用代码加入会话（XXXX-XXXX-XXXX，Base58）	—
bond_status	—	握手状态、待处理传输、未读事件数，以及自上次调用以来的事件	—
bond_send	filepath、message?	发送文件（类型白名单、大小上限、10 秒速率限制），并可附带上下文消息	已确认的通道
bond_message	content	发送简短的加密文本消息，最多 4000 个字符（Agent 间对话）	已确认的通道
bond_wait	timeoutSeconds?	长轮询以等待下一个对端事件（消息、文件、断开连接）；默认 50 秒，最长 300 秒	已确认的通道
bond_accept	transferId	将待处理文件写入 ~/.covalent/incoming/，并以不可信数据的形式返回其内容	人工同意
bond_decline	transferId	丢弃待处理的传输（不会通知发送方）	人工同意
bond_end	—	断开连接并清除会话状态，包括待处理的传输	—

? 表示可选参数。已确认的通道表示在双方都成功完成密钥确认前，工具不会运行；人工同意表示只有在人明确决定如何处理待处理的传输后，Agent 才能调用该工具。

收到事件时会触发桌面通知（可通过 COVALENT_NOTIFICATIONS=off 关闭）。文件大小默认为 256 KB，可通过 COVALENT_MAX_FILE_KB 覆盖（最高 384 KB，受中继的线路限制约束）。

安全性

每个会话都由两个秘密保护：通过中继交换的临时 X25519 密钥，以及两位用户通过带外方式分享的简短会话码。会话码会混入加密密钥，但绝不会发送给中继，因此篡改密钥交换的中继（中间人攻击）无法推导出密钥，密钥确认会失败，并且会话会在任何数据传输前中止。中继只能看到路由 ID、公钥和 AES-256-GCM 密文。每个收到的文件都必须经人工明确同意，每项操作也都会记录在日志中。

完整详情、威胁模型和握手图： docs/ARCHITECTURE.md。

请通过中继运营方无法控制的渠道分享会话码。 正是这个带外步骤让通道获得身份验证，而不只是加密。

测试

npm test          # all suites, via test/run-all.js, against an in-process mock relay

无需网络或 wrangler。测试套件涵盖密钥计划、完整握手和文件传输、两个 MCP 服务的端到端测试、模拟恶意中继（mitm），以及中继的强化措施。测试细分说明请参阅 docs/ARCHITECTURE.md，真实的双机测试请参阅 docs/TWO-MACHINE-TEST.md。

部署中继

中继是一个 Cloudflare Worker，位于 cloudflare-worker/，每个会话对应一个 Durable Object。它只存储路由 ID、公钥和密文，并在最后一次活动 30 分钟后过期。它无法解密任何内容。

状态

已完成身份验证的 E2EE，MCP 集成已端到端接通，完整测试套件全部通过。尚未达到 1.0 版本：协议和 API 仍可能发生变化。

贡献与安全报告

欢迎贡献。请先阅读 CONTRIBUTING.md，其中介绍了安全不变量以及分支/PR 工作流程。要报告漏洞，请使用 SECURITY.md 中的私密流程，而不要提交公开议题。

许可证

MIT；详见 LICENSE。

---

_{两台机器。一种工作方式。 返回顶部 ↑}