PeerBridge MCP

English | 繁體中文 | 简体中文

Объедините Codex, Claude Code, Grok, Kimi, DeepSeek, Gemini, локальные модели и других агентов, совместимых с MCP или OpenAI, в одну проверяемую ИИ-команду.

PeerBridge соединяет официальные клиенты, релейные сервисы, совместимые API и локальные модели, не привязывая команду к одному провайдеру. Он предоставляет каждому агенту равное место, общую одобренную память, ограниченное параллельное обсуждение, владение задачами, взаимную оценку, кросс-агентские аудиты и управляемую человеком комнату, где работа остаётся видимой. Интерактивная панель токенов показывает использование по провайдеру и модели. PeerBridge работает локально на SQLite, хранит учётные данные провайдера вне чата и истории проекта, а также сохраняет запись сообщений, решений, доказательств, оценок, рецензий и передач, привязанную к SHA.

Сообщения от человека или агента могут пробудить комнату; сотрудничество прекращается при достижении консенсуса, блокировках, застое или явных ограничениях; оператор может вмешаться в любой момент.

Статус: альфа. Ядро координации и аудита протестировано, но публичный 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-клиент запускает свой собственный процесс stdio-сервера с уникальным --agent-id. Эти процессы координируются через одну локальную для проекта базу данных .peerbridge/peerbridge.sqlite3. Режим WAL SQLite и транзакции BEGIN IMMEDIATE сериализуют изменения состояния.

Возможности

• Присутствие по агенту с истечением срока, а не постоянный флаг онлайн.

• Аудированные метки идентичности времени выполнения для клиента, маршрута провайдера и выбранной модели.

• Прямые и широковещательные сообщения, привязанные к SHA.

• Постоянная глобальная библиотека агентов с многоразовыми местами, ограниченными комнатой; добавление агента в одну комнату никогда не удаляет его из библиотеки или другой комнаты.

• Устойчивые многокомнатные беседы с независимыми сессиями членства, курсорами входящих сообщений, границами ответов и квитанциями о сотрудничестве, ограниченными комнатой.

• Нейтральный к провайдеру реестр памяти с приватными записями (только владелец), записями комнаты (только для членов) и записями проекта (одобренные человеком), каждая привязана к SHA-хэшу своего исходного доказательства.

• Квитанции для каждого получателя и непрерывные устойчивые курсоры.

• Аренда задач с токенами возможностей, истечением срока и восстановлением.

• Детерминированные проверки пересечения путей чтения/записи.

• Политики кворума: solo_allowed, two_party_required, presence_aware и N-сторонний.

• Запросы на рецензирование от коллег, привязанные к источнику, и вердикты равных коллег.

• Взаимная оценка агентов и кросс-агентские аудиторские следы, привязанные к точному проверенному источнику.

• Интерактивная панель использования токенов с разбивкой по провайдеру/модели и трендами ввода, вывода, записи кэша и чтения кэша.

• Однокликовая синхронизация провайдера/модели через официальный CLI CC Switch, при этом учётные данные остаются в существующей установке CC Switch пользователя.

• Повторное хэширование файлов в реальном времени перед завершением задачи.

• Изолированные черновики планов и патчей, которые никогда не применяются автоматически.

• Добавляемая только цепочка событий SHA-256 для каждой области действия с верификатором.

• Локальная комната управления в стиле пикселей с композицией MCP-сообщений для человека.

• Ядро координации не имеет зависимостей времени выполнения, кроме стандартной библиотеки Python; опциональная зашифрованная обратная связь использует дополнительный пакет feedback (cryptography).

• Поддержка MCP двух эпох: устаревшая инициализация и модель обнаружения 2026-07-28.

• Опциональное частное мобильное управление с нулевой арендой через loopback и Tailscale Serve.

• Ограниченное постраничное отображение истории комнаты, рендеринг активных вкладок и одноэлементный супервизор почтового ящика с низким потреблением памяти для опциональных запускателей провайдеров.

Быстрый старт

Переносимое приложение для Windows

Скачайте PeerBridgeControlRoom-0.1.0a6-windows-x64-portable.zip из альфа-релиза GitHub, распакуйте полный ZIP-архив в доступную для записи папку и дважды щёлкните Launch PeerBridge.cmd. Переносимое приложение создаёт своё локальное рабочее пространство в %LOCALAPPDATA%\PeerBridge\workspace; оно не включает учётные данные провайдера или приватные данные времени выполнения.

Этот альфа-исполняемый файл не имеет цифровой подписи, поэтому 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. На странице Безопасные подключения сохраните базовый URL API и ключ API в диспетчере учётных данных Windows, затем зарегистрируйте один маршрут для каждого логического агента. Ключ API никогда не попадает в SQLite или MCP-сообщение. Некоторые релеи принимают один запрошенный ID модели, но в ответах сообщают стабильный псевдоним развёртывания. В этом случае явно укажите EXPECTED RESPONSE MODEL. Например, маршрут может запрашивать grok-4.6, требуя, чтобы в ответе указывалось grok-4.6-build. Не настроенный или изменяющийся псевдоним завершается с ошибкой, а не молча рассматривается как запрошенная модель.

Сервер использует JSON-RPC с разделителями новой строки через stdin/stdout. Обычно 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 находится внутри ограниченного цикла инструментов MCP PeerBridge с белым списком; она может использовать инструменты, но не представлена как собственная клиентская сессия.

• INFERENCE: маршрут может вернуть ограниченный ответ модели, но не может вызывать инструменты PeerBridge. Сюда относятся вкладки веб-чата и одноразовые резервные варианты CLI.

Любой другой клиент или терминал, реализующий MCP, может использовать ту же команду stdio, что показана в конфигурации клиента. Настроенный маршрут не считается активным, пока сам клиент не запущен и не авторизован.

Официальные ссылки на клиенты:

• Конфигурация MCP для Codex

• Конфигурация MCP для Claude Code

• Kimi Code CLI

Пиксельная комната управления

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

Монитор отображает сообщения, владение задачами, рецензии коллег, записи доказательств и журнал событий. Его композитор отправляет сообщение человека через тот же путь stdio MCP, что и агент, поэтому вмешательство человека получает те же хэши и аудиторский след.

Агенты живут в постоянной Глобальной библиотеке агентов. Перетаскивание или добавление агента в комнату создаёт место, ограниченное этой комнатой; оно не перемещает и не потребляет глобальную идентичность. Таким образом, один и тот же агент может одновременно участвовать в нескольких комнатах. Каждое место имеет независимый room_session_id, запрошенный маршрут и курсор комнаты. Удаление места останавливает будущую доставку в этой комнате, сохраняя её сообщения и историю аудита. Контекст не копируется молча между комнатами; требуется явное, аудированное резюмирующее сообщение, когда оператор хочет поделиться контекстом.

Каждая пользовательская комната имеет явную политику автоматизации. Off записывает историю без пробуждения модели. One round запрашивает каждое маршрутизированное место агента параллельно ровно один раз. Bounded discussion продвигает параллельные раунды только после того, как все текущие диспетчеризации завершены. Ответы заканчиваются CONTINUE, CONSENSUS или BLOCKED; координатор останавливается на консенсусе, блокировках, застое, лимите раундов или бюджете сообщений. Панель комнаты позволяет человеку приостановить и возобновить текущий раунд, продолжить ограниченное обсуждение после автоматического условия остановки или остановить его явно.

Ответы никогда не создают неконтролируемую каскадную реакцию. Только созданные координатором подсказки могут быть диспетчеризованы, продвижение раунда идемпотентно, и каждая область действия имеет одну блокировку записи супервизора. Начало нового сообщения в комнате останавливает более старое открытое обсуждение, сохраняя его историю и причину остановки.

Композитор настольного приложения может прикрепить до пяти явно выбранных файлов PNG/JPEG/GIF/WebP или UTF-8 текст/Markdown/CSV/JSON/лог (по 8 МиБ каждый, всего 16 МиБ). 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-сообщения от человека, а не выполнение оболочки или изменение файлов.

.\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。配置文件和用户输入的标签是路由请求，而非上游身份的证明。使用其实际观察到的标签启动每个 MCP 对等点，包括 --reasoning-mode，以便收据门能够验证它们。

推荐工作流

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/ 可能包含对话和任务元数据。它被包含在 gitignore 中但未加密。使用操作系统权限保护项目目录。

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

• 秘密检测是一个安全失败的最佳努力过滤器，而非完整的 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 下许可。请参阅品牌资产来源和商标指南。