PeerBridge MCP

English | 繁體中文 | 简体中文

将 Codex、Claude Code、Grok、Kimi、DeepSeek、Gemini、本地模型以及其他 MCP 或 OpenAI 兼容的智能体汇聚成一个可审计的 AI 团队。

PeerBridge 连接官方客户端、中继服务、兼容 API 和本地模型， 而不会将团队锁定在单一提供商上。它为每个智能体提供平等的席位、共享的 已批准记忆、有边界的并行讨论、任务所有权、相互评分、 跨智能体审计以及一个人类可控且工作可见的房间。一个实时代币 仪表盘按提供商和模型显示使用情况。PeerBridge 在本地 SQLite 上运行，将 提供商凭据排除在聊天和项目历史之外，并保留消息、决策、证据、评分、审查和交接的 SHA 链接记录。

人类或智能体消息可以唤醒房间，协作在达成共识、遇到阻碍、停滞或达到明确限制时停止， 操作员可以随时干预。

状态：alpha。协调和审计核心已测试，但公共 API 和 数据库模式可能在 1.0 版本之前发生变化。

运营连续性和商业化是明确的设计边界。请参阅 内存和长时间运行操作 以及 开放核心边界。远程/移动模块是 实验性的且默认关闭。路线图条目并非能力声明。

为什么

针对一个代码仓库运行两个编码智能体会产生可预测的故障模式：

• 两个智能体编辑相同的文件；

• 一个智能体假设其同伴在线，但实际上并非如此；

• 聊天消息丢失或全局确认，而不是按消费者确认；

• 审查批准的是过时的文件，而不是实际测试过的文件；

• 人类无法看到谁拥有任务或为什么将其标记为完成。

PeerBridge 在不使任一智能体成为主导的情况下解决这些协调失败问题。 一个任务只有一个写入者租约，同伴可以相互审查，人类可以干预。

Related MCP server: JustClone Coordination MCP Server

架构

flowchart LR
    H["Human operator"] --> M["Pixel control room"]
    C["Codex / Claude Code"] --> S1["PeerBridge stdio process"]
    A["Grok / Kimi / DeepSeek / Gemini / local Agents"] --> S2["PeerBridge stdio process"]
    M --> S3["PeerBridge stdio process"]
    R["Private mobile UI"] -->|"Tailnet HTTPS"| T["Tailscale Serve"]
    T -->|"loopback only"| S4["Human MCP message gateway"]
    S1 --> DB[("Shared SQLite store")]
    S2 --> DB
    S3 --> DB
    S4 --> DB
    DB --> L["SHA-linked audit events"]
    DB --> W["Mailbox, leases, reviews, proofs"]

每个 MCP 客户端使用不同的 --agent-id 启动自己的 stdio 服务器进程。 这些进程通过一个项目本地的 .peerbridge/peerbridge.sqlite3 数据库进行协调。SQLite WAL 模式和 BEGIN IMMEDIATE 事务序列化状态更改。

特性

• 基于过期时间的按智能体存在状态，而非永久在线标志。

• 经过审计的运行时身份标签，用于客户端、提供商路由和所选模型。

• SHA 绑定的直接和广播消息。

• 持久的全局智能体库，具有可重复使用的、作用域于房间的席位；将智能体添加到一个 房间永远不会将其从库或其他房间中移除。

• 持久的多人房间对话，具有独立的成员会话、收件箱光标、 回复边界和房间绑定的协作回执。

• 提供商中立的记忆账本，包含仅所有者可见的私有记录、成员绑定的房间记录和 人类批准的项目记录，每条记录都 SHA 绑定到其明确的源证据。

• 按消费者的回执和连续的持久光标。

• 能力令牌任务租约，具有过期和恢复功能。

• 确定性读/写路径重叠检查。

• solo_allowed、two_party_required、presence_aware 和 N 节点法定人数策略。

• 源绑定的同伴审查请求和同等同伴裁决。

• 相互智能体评分和跨智能体审计追踪，链接到确切的已审查源。

• 实时代币使用仪表盘，显示按提供商/模型细分的输入、输出、缓存写入 和缓存读取趋势。

• 一键 CC Switch 提供商/模型同步，通过其官方 CLI，同时凭据保留在 用户现有的 CC Switch 安装中。

• 任务完成前的实时文件重新哈希。

• 隔离的计划和补丁草稿，永远不会自动应用。

• 每个作用域的仅追加 SHA-256 事件链，带有验证器。

• 像素风格本地控制室，具有人类 MCP 消息组合功能。

• 协调核心除了 Python 标准库外没有运行时依赖； 可选的加密反馈使用 feedback 额外依赖（cryptography）。

• 双时代 MCP 支持：传统初始化和 2026-07-28 发现模型。

• 可选的零租金私有移动控制，通过回环加 Tailscale Serve 实现。

• 有界房间历史分页、活动标签渲染以及用于可选提供商运行器的单例低内存邮箱 监控器。

快速入门

Windows 便携应用

从 GitHub Alpha 版本下载 PeerBridgeControlRoom-0.1.0a6-windows-x64-portable.zip， 将完整的 ZIP 解压到一个可写文件夹，然后双击 Launch PeerBridge.cmd。便携应用在 %LOCALAPPDATA%\PeerBridge\workspace 下创建其本地工作空间；它不包含提供商凭据或 私有运行时数据。

此 Alpha 可执行文件未经代码签名，因此 Windows SmartScreen 可能会要求您审查 发布者。在打开之前验证发布版本的 SHA-256。PeerBridge 不提供 自动安装程序或修改现有的 Python 环境。

从源码安装

要求：Python 3.11 或更新版本。

git clone https://github.com/hoylon/peerbridge-mcp.git
cd peerbridge-mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
peerbridge init --project-root . --scope demo
peerbridge doctor --project-root . --scope demo

手动运行服务器：

peerbridge serve --project-root . --agent-id codex-main --scope demo

当一个客户端可以选择多个官方或中继支持的模型时，记录路由 而不暴露凭据：

peerbridge serve --project-root . --agent-id grok-relay-reviewer --scope demo `
  --client-name relay-coding-client `
  --provider-id relay:grok-official-channel `
  --model-id grok

agent-id 标识逻辑工作进程。client-name 标识支持 MCP 的 应用程序或适配器。provider-id 是操作员提供的非秘密路由标签， model-id 标识所选模型。Grok 或 DeepSeek 官方网站和 中继路由是不同的身份，即使它们暴露相同的模型系列。

直接的 OpenAI 兼容端点不需要 CC Switch。在安全 连接页面上，将 API 基础 URL 和 API 密钥保存到 Windows 凭据管理器中， 然后为每个逻辑智能体注册一个路由。API 密钥永远不会进入 SQLite 或 MCP 消息。 一些中继接受一个请求的模型 ID，但在响应中报告一个稳定的部署别名。 在这种情况下，显式设置期望的响应模型。例如， 一个路由可能请求 grok-4.6，同时要求响应报告 grok-4.6-build。未配置或更改的别名会失败关闭，而不是被静默地视为请求的模型。

服务器通过 stdin/stdout 使用换行符分隔的 JSON-RPC 进行通信。通常 MCP 客户端 会为您启动它，因此手动启动的等待输入的服务器是预期行为。

连接客户端

使用绝对 Python 可执行文件路径，以便每个客户端启动相同的已安装 环境和共享数据库。

Codex

codex mcp add peerbridge -- C:\path\to\peerbridge-mcp\.venv\Scripts\python.exe `
  -m peerbridge_mcp serve --project-root C:\path\to\your-project `
  --agent-id codex-main --scope your-project

Claude Code

claude mcp add --scope project --transport stdio peerbridge -- `
  C:\path\to\peerbridge-mcp\.venv\Scripts\python.exe `
  -m peerbridge_mcp serve --project-root C:\path\to\your-project `
  --agent-id claude-code --scope your-project

当两个客户端都写入共享项目配置时，使用不同的 MCP 服务器入口名称， 例如 peerbridge-codex 和 peerbridge-claude。请参阅 客户端配置 了解 TOML、JSON、Linux 和 macOS 示例。 相同的 stdio 服务器可以在 Kimi Code CLI 中注册；其他提供商可能需要一个单独的 API 支持运行器。请参阅智能体集成边界。

PeerBridge 报告每个绑定房间席位的有效能力，而不是从智能体名称推断：

• MCP NATIVE：一个真正的支持 MCP 的客户端或终端拥有会话，并且可以直接调用 PeerBridge 服务器。

• MCP TOOL：一个 API 支持的模型位于 PeerBridge 有界、已列入白名单的 MCP 工具 循环内；这具有工具能力，但不表示为原生客户端会话。

• INFERENCE：路由可以返回一个有界的模型答案，但不能调用 PeerBridge 工具。Web 聊天标签和一次性 CLI 回退属于此类。

任何其他实现 MCP 的客户端或终端都可以使用客户端配置中显示的相同 stdio 命令。 配置的路由在相应客户端实际运行并授权之前不被视为活跃。

官方客户端参考：

• Codex MCP 配置

• Claude Code MCP 配置

• Kimi Code CLI

像素控制室

peerbridge monitor --project-root C:\path\to\your-project --scope your-project

监视器显示消息、任务所有权、同伴审查、证明记录和 事件日志。其编辑器通过与智能体相同的 MCP stdio 路径发送人类消息， 因此人类干预接收相同的哈希值和审计追踪。

智能体存在于一个持久的全局智能体库中。将智能体拖放或添加到一个 房间会创建一个作用域于房间的席位；它不会移动或消耗全局身份。 因此，同一个智能体可以同时参与多个房间。每个席位都有一个独立的 room_session_id、请求的路由和房间光标。 移除席位会停止该房间内的未来投递，同时保留其消息和审计历史。 上下文不会在房间之间静默复制；当操作员想要共享上下文时，需要一条明确的、经过审计的摘要消息。

每个自定义房间都有一个明确的自动化策略。关闭记录历史而不唤醒 模型。一轮恰好一次并行询问每个路由的智能体席位。 有界讨论仅在所有当前调度终止后才推进并行轮次。回复以 CONTINUE、CONSENSUS 或 BLOCKED 结束；协调器在达成共识、 遇到阻碍、停滞、达到轮次限制或消息预算时停止。房间栏让人类 暂停和恢复正在进行的轮次，在自动停止条件后继续有界讨论， 或显式停止它。

回复永远不会创建不受控制的回复级联。只有协调器创建的提示是 可调度的，轮次推进是幂等的，并且每个作用域有一个监控器写入锁。 启动一个新的房间帖子会停止较旧的开放讨论，同时保留其历史和 停止原因。

桌面编辑器可以附加最多五个显式选择的 PNG/JPEG/GIF/WebP 或 UTF-8 文本/Markdown/CSV/JSON/日志文件（每个 8 MiB，总共 16 MiB）。PeerBridge 验证 声明的类型，拒绝类似凭据的文本，将每个文件复制到被忽略的本地 .peerbridge-artifacts/chat/ 存储中，以其 SHA-256 名称命名，并且仅将该相对内容寻址路径绑定到消息。 原始绝对路径和文件名不会进入 SQLite。初始分发/讨论提示接收绑定一次；后续轮次不会 重复它。传输附件并不证明所选提供商可以解释图像， 因此不支持的路由必须将其视为可审计的文件引用。

共享内存页面显示与聊天分开的显式内存记录。PeerBridge 不会提取或同步隐藏的思维链、提供商侧对话状态或凭据。 智能体可以写入自己的私有草稿摘要，活跃房间成员可以读取房间内存， 只有 human-operator 可以发布或撤销项目内存。项目提升 需要 SHA 绑定的源消息、父内存或项目工件。撤销 保留原始记录并附加新的审计回执，而不是删除历史。

API 支持的 OpenAI 兼容运行器默认只接收只读的 list_memories 和 read_memory 工具。因此，它们可以使用与 Codex、Claude Code、Grok、Kimi、DeepSeek 或本地模型相同的已批准事实，而无需获得发布项目范围内存的权限。每个房间保持独立的模型会话和光标， 即使同一个全局智能体在多个房间中拥有席位。

私有移动控制

可选的实验性远程页面通过 Tailscale Serve 暴露一个故意狭窄的人类界面。 后端仅绑定到 127.0.0.1；tailnet 代理提供 经过身份验证的用户身份。它支持作用域范围的观察和经过审计的人类 MCP 消息， 而不是 shell 执行或文件修改。

.\scripts\launch_remote_control.cmd -Port 8765 -Scope your-project

请参阅私有远程和移动控制了解安全边界、 测试、手机设置以及明确禁止公开 Tailscale Funnel 暴露的规定。

产品状态和选择性指标

PeerBridge 暴露了一个机器可读的能力边界，而无需激活托管服务、支付流程或商业授权提供商：

peerbridge product --project-root . status
peerbridge product --project-root . status --capability remote.experimental.self_hosted

本地分析钩子默认关闭。未经明确选择加入，它不会创建安装 ID、排队事件或联系网络端点。当前的 Alpha 版本根本没有分析发送器；启用的数据保留在本地机器上，作为 UTC 日聚合计数器，并带有一个随机、可重置的安装 ID。

peerbridge analytics --project-root . status
peerbridge analytics --project-root . enable
peerbridge analytics --project-root . export
peerbridge analytics --project-root . disable

GitHub Release 资源 download_count 衡量的是文件下载次数，而非独立用户。实际的 DAU/WAU/MAU 估算需要一个未来的透明收集器以及明确的应用程序选择加入，并且必须描述为活跃的安装，而非人员。提示、消息体、API 密钥、模型输出、文件名/路径、项目名称、账户身份、IP 地址和任意元数据不在公共事件模式中。请参阅遥测和启动指标以及实验性远程/商业钩子。

公告独立于分析。打包的 Alpha 版本默认启用一个只读的 HTTPS 公告连接，以便无需更新检查即可显示紧急通知。每个请求会发送选定的 UI 语言环境、每个语言环境的公告光标以及一个固定的非标识性 PeerBridge 公告客户端 User-Agent；正常的网络基础设施也可以观察到源 IP 地址。它不会发送安装 ID、凭据、项目路径、消息内容或模型输出。公告页面提供了一个独立的网络开关：关闭它会停止公告请求，同时保留有界本地缓存的可读性。弹出通知有其独立的偏好设置。如果保存的偏好文件不可读，则网络轮询和弹出通知都会失败关闭，直到用户明确保存新的偏好。

反馈通过 HTTPS 私下提交。普通的报告元数据、用户选择的诊断信息、联系方式和附件在传输过程中受到保护，但在支持包内部并非端到端加密。只有用户明确选择包含的可选凭据会在上传前在本地使用固定的维护者支持公钥进行加密。请参阅反馈隐私。

控制室提供了一个持久化的 zh-Hant / zh-Hans / 英语语言环境基础、一个可重播的首次运行教程以及一个明确的只读更新检查。Alpha 安装会报告较新的 GitHub 版本。未来的稳定频道将仅遵循稳定版本轨道。检查器从不下载或安装代码；签名的一键更新和回滚仍是未来工作。

安全连接页面支持两种本地引导路径：

• 输入一个私有 HTTPS 端点和 API 密钥；PeerBridge 将两者存储在当前 Windows 用户的凭据管理器中，并仅通过 MCP 写入编辑后的标识符和 SHA-256 指纹；

• 通过官方 CC Switch CLI 发现现有的 Claude、Codex、Gemini、OpenCode、Hermes 或 OpenClaw 提供商，使用 CC Switch 已保存的凭据获取模型 ID，注册一个 PeerBridge 路由，并且仅在明确的人工确认后才进行切换。

对于仅限主机的 OpenAI 兼容 URL，PeerBridge 会添加常规的 /v1 API 基础路径。如果提供商发布了明确的兼容路径，请输入该完整的基础路径；PeerBridge 会保留它。这支持诸如 Gemini 的 /v1beta/openai/ 兼容基础路径等端点，而无需特定于提供商的代码。

PeerBridge 不会将原始 API 密钥或完整的私有端点放入 MCP 消息、SQLite、审计事件、收据、日志、命令行参数、深度链接、Git 或遥测中。它不会读取 CC Switch 数据库或导出 CC Switch 配置。自动创建 CC Switch 提供商被有意禁用，因为其公共深度链接/导入合约可能会在操作系统密钥存储之外暴露密钥。

组合器使用一个经过验证的级联：接收方 Agent、已注册的提供商路由、该路由上可用的模型，然后是该确切模型可用的推理模式。模型系列和推理级别是分开的字段；像 gpt-5.6-luna 这样的模型变体不得作为推理级别呈现。路由消息保持 REQUESTED 状态，直到一个接收方会话（其观察到的运行时身份与每个请求的字段匹配）确认它。不匹配的会话无法确认该消息。只有在那时，PeerBridge 才会附加一个 SHA 绑定的 VERIFIED 路由收据。

保存的路由可以通过 MCP 注册：

{
  "route_id": "codex-luna-medium",
  "agent_id": "codex-main",
  "provider_id": "openai-official",
  "model_id": "gpt-5.6-luna",
  "reasoning_mode": "medium",
  "route_class": "official"
}

对于具有已验证响应别名的提供商，添加单独的绑定：

{
  "route_id": "relay-grok-4.6",
  "agent_id": "grok-relay",
  "provider_id": "relay-grok-sui-xiang",
  "model_id": "grok-4.6",
  "response_model_id": "grok-4.6-build",
  "route_class": "relay"
}

model_id 是出站请求身份。response_model_id 是每个完成响应中所需的确切模型身份；省略时默认为 model_id。两者都在路由配置文件和推理收据中进行 SHA 绑定。

使用该负载调用 upsert_route_profile，然后在监视器中选择该配置文件，或传递 route_profile_id 给 send_message。配置文件和用户输入的标签是路由请求，而非上游身份的证明。使用其实际观察到的标签（包括 --reasoning-mode）启动每个 MCP 对等体，以便收据网关可以验证它们。

推荐工作流程

1. 每个 Agent 在开始工作前调用 bridge_status 和 workboard。

2. 预期的写入者使用精确的读写路径调用 claim_task。

3. 写入者在 PeerBridge 外部工作时调用 announce_work。

4. 它使用 record_proof 记录实时哈希和测试证据。

5. 如果审批策略需要对等体，它调用 request_review。

6. 对等体读取绑定的工件并调用 submit_review。

7. 写入者调用 complete_task；PeerBridge 重新哈希文件并检查策略。

8. 任何人都可以调用 verify_audit_chain 或运行 peerbridge doctor。

request_review 是一个手动治理队列。它从不调用模型，并出现在审查页面上，而不是在房间聊天中。要唤醒路由的房间 Agent，请通过 post_room_message 发布：once 发送一轮并行消息，而 discussion 运行有界的并行轮次。回复本身不会触发另一次扇出。

PeerBridge 协调工作。编码客户端仍然使用其正常工具读取、编辑和测试文件。

审批模式

存在感知模式支持间歇性使用。它避免了在只有一个付费 Agent 运行时阻塞所有工作，同时在指定对等体实际在线时仍要求审查。法定人数模式适用于三个或更多独立连接的 Agent。它不会启动、支付或认证这些 Agent。

安全边界

• .peerbridge/ 可能包含对话和任务元数据。它被 git 忽略但未加密。使用操作系统权限保护项目目录。

• 记忆体是明确的协调数据，而非加密的密钥存储。切勿将凭据、隐藏推理或无关的个人数据放入记忆记录中。

• 秘密检测是一个失败关闭的尽力而为过滤器，而非完整的 DLP 系统。

• 审计链检测到许多变异，但无法仅从数据库证明未锚定尾部的删除。导出或外部锚定重要的链头。

• 具有文件系统访问权限的恶意本地用户不在当前威胁模型范围内。

• 本地进程可以到达环回并伪造代理头；操作系统账户仍然是私有移动模式的可信边界。

• PeerBridge 从不将审查解释为运行破坏性 shell 命令的权限。

在敏感仓库上使用桥接之前，请阅读完整的威胁模型。

非目标

• 自动唤醒或支付另一个 AI 模型。

• 替换 Git、代码审查、CI 或仓库权限。

• 应用生成的补丁。

• 托管远程多租户 MCP 服务。

• 加密本地 SQLite 数据库。

• 声称 AI 审查等同于人工安全审查。

开发

python -m pytest
python -m compileall -q src
python -m build

请参阅 CONTRIBUTING.md、架构 和演示演练。未来的云和移动工作已在路线图中明确分离。

许可证

Apache 许可证 2.0。请参阅 LICENSE。

PeerBridge 名称和徽标是独立的品牌资产，未根据 Apache-2.0 许可。请参阅品牌资产来源和商标指南。