AgentBridge v0.2

AgentBridge 是一个完全在本机运行的智能体通信与只读项目共享原型。v0.2 在 v0.1 Gateway/权限边界上增加了 Codex 与 Claude Code 适配层。Codex Desktop 的真实 MCP 注册已经验证；Claude Code 适配层已通过自动化 MCP 测试，但尚未完成真实宿主握手 验证，因此本项目不声称两种真实宿主之间的双向通信已经完整验证。

当前功能

• 仅监听 127.0.0.1:17890 的 Fastify Gateway

• REST、WebSocket 与 MCP Streamable HTTP (/mcp)

• SQLite 自动建库/迁移及 repository 层

• chat_only、ask_before_read、trusted_read 三级权限

• 单文件、目录、项目范围的申请；单次和固定分钟有效期

• 安全路径解析、realpath 根目录校验、符号链接/Windows junction 逃逸防护

• 敏感文件、二进制文件、超大文件和疑似凭证内容拒绝

• 安全文件列表、文本读取/搜索、无 shell 的 Git 状态与变更摘要

• React 本地控制面板与管理员批准/拒绝/撤销/紧急断开

• 两个命令行模拟客户端、自动演示和安全/集成/MCP 测试

• 所有消息、授权申请、权限变更和项目读取结果写入结构化审计日志

• Codex 插件 + AgentBridge Skill，以及 Claude Code MCP/CLAUDE.md 集成

• 适配器 secret 的 scrypt 哈希、轮换、撤销和 re-pair

• 消息大小/频率/未读上限、非可信输入标记和最长 25 秒的受限等待工具

Related MCP server: Twining MCP Server

安全边界

v0.2 是本地、只读原型：

• Gateway 和控制面板只绑定 127.0.0.1，没有公网通信、隧道或遥测。

• 当前不支持远程网络或项目写入；首次安装请只连接测试项目和非敏感文件。

• 所有项目读取统一经过服务端权限引擎和安全路径模块；MCP annotations 只是描述，不是安全边界。

• MCP 没有批准授权、改变权限、撤销他人授权、shell 或文件修改工具。

• 即使 trusted_read 也不能创建、修改、删除文件，不能运行命令或安装依赖。

• .env*、密钥、令牌、凭据目录、依赖/构建输出和 .git 内部文件不返回。

• 管理接口必须携带环境变量中的本地管理员令牌。令牌不会返回给智能体或 MCP 客户端。

• Codex/Claude Code 宿主适配器使用管理员配对的 clientId + clientSecret；SQLite 只存带随机 salt 的 scrypt hash。agentId + deviceId 仅保留给明确标记的模拟器。

• adapter identity 和 secret 只应保留在本机，不得提交、复制到文档或与他人分享；泄漏后应立即撤销并重新配对。

• Git 功能使用 isomorphic-git 读取仓库并只返回路径/状态矩阵摘要，不执行 Git 或项目命令。

完整威胁模型见 docs/security-model.md。

要求与安装

• Node.js 22+

• pnpm 11（项目由 Corepack 固定）

Set-Location C:\path\to\AgentBridge
corepack enable
corepack pnpm install
Copy-Item .env.example .env

编辑 .env，至少设置一个不少于 16 字符、仅用于本机的管理员令牌，并将项目根目录指向允许读取的项目：

AGENTBRIDGE_HOST=127.0.0.1
AGENTBRIDGE_PORT=17890
AGENTBRIDGE_ADMIN_TOKEN=change-this-local-token
AGENTBRIDGE_DB_PATH=./data/agentbridge.db
AGENTBRIDGE_PROJECT_ROOT=C:\path\to\TestProject
AGENTBRIDGE_PROJECT_NAME=Test Project

Windows PowerShell 启动

Set-Location C:\path\to\AgentBridge
corepack pnpm dev

• Gateway: http://127.0.0.1:17890

• 控制面板: http://127.0.0.1:5173

• 健康检查: Invoke-RestMethod http://127.0.0.1:17890/health

在控制面板输入与 .env 相同的管理员令牌。控制面板没有登录系统，令牌只保存在浏览器本地存储中并用于本机管理请求。

接入 Codex Desktop 与 Claude Code

当前真实验证范围是 Codex Desktop。Claude Code 部分提供独立 identity、MCP 配置、 安装脚本和自动化测试，但真实 Claude Code 宿主连接仍在验证中。

保持 pnpm dev 运行，在另一个 PowerShell 创建两套独立本地身份：

Set-Location C:\path\to\AgentBridge
corepack pnpm adapter:pair
corepack pnpm adapter:check
corepack pnpm adapter:smoke
corepack pnpm codex:diagnose
corepack pnpm codex:desktop-check
corepack pnpm codex:runtime-check

codex:diagnose 对 Codex Desktop 的 AppData 目录和标准 Codex 配置路径只做文件名/元数据分析，不读取账号 token、登录凭据或配置正文，也不修改用户目录。 结果写入 reports/codex-desktop-diagnose.json。

安装 Codex Desktop MCP（优先检测 %USERPROFILE%\.codex\config.toml，不要求 安装 Codex CLI）：

.\scripts\install-codex-plugin.ps1 -DryRun
.\scripts\install-codex-plugin.ps1

安装器先将原配置备份到 %USERPROFILE%\.codex\backups\agentbridge\，再以受管 TOML 块追加 mcp_servers.agentbridge。原有 model、projects、plugins、features 和其他 MCP 保持不变；配置只引用 adapter identity 环境变量，不包含管理员令牌或 adapter secret。可用 -WhatIf 或 -DryRun 做零写入预演。

安装完成后的日常启动只需要两个窗口：

# 窗口一
Set-Location C:\path\to\AgentBridge
corepack pnpm dev

# 窗口二
Set-Location C:\path\to\AgentBridge
corepack pnpm codex:start

codex:start 从被 Git 忽略的 data/adapters/codex.json 读取配对身份，以 Bearer <clientSecret> 生成 Gateway 实际要求的 Authorization，并且只把两项 认证环境变量注入本次 Codex Desktop 进程树。它不写入 TOML、注册表或永久 Windows 环境变量，也不会在输出中显示密钥。Microsoft Store/AppX 版本通过 shell:AppsFolder\<AppUserModelId> 激活；普通安装继续直接启动可信 GUI executable。

检查与卸载：

corepack pnpm codex:desktop-check
corepack pnpm codex:runtime-check
.\scripts\uninstall-codex-plugin.ps1

卸载优先恢复安装备份；如果安装后又增加了其他配置，则只移除 AgentBridge 受管块。脚本不会读取 auth.json、Cookies、Login Data、Local Storage 或 Session Storage。

安装 Claude Code 集成（会备份并合并私有配置，不覆盖其他 MCP server）：

.\scripts\install-claude-code.ps1 -ProjectPath C:\path\to\TestProject

安装或 secret 轮换后必须重启客户端/开始新任务。完整步骤：

• Codex adapter

• Claude Code adapter

• 兼容性与当前环境实测

• 故障排查

测试、构建与演示

一键完整验收：

corepack pnpm verify

分层验收：

corepack pnpm verify:fast         # lint、typecheck、unit tests、build
corepack pnpm verify:security     # 权限、路径、敏感文件和并发授权安全
corepack pnpm verify:integration  # 临时 Gateway、SQLite、REST 和 MCP 端到端验收

完整验收使用 data/verification/ 中的唯一临时目录、随机管理员令牌和随机 loopback 端口，不接触配置的真实项目或 data/agentbridge.db。无论成功或失败都会关闭 Gateway 并清理临时数据。结果写入：

• reports/verification-latest.json

• reports/verification-latest.md

自动验收覆盖环境版本、消息隔离、三级权限、单次/定时授权、撤销/过期并发竞争、 敏感路径和内容、遍历/绝对路径、二进制/大小限制、管理员认证、MCP 权限隔离、审计、 令牌泄漏检查及 junction/symlink 逃逸。仅界面视觉和交互确认保留在 人工验收清单。

独立开发命令：

corepack pnpm lint
corepack pnpm typecheck
corepack pnpm test
corepack pnpm build
corepack pnpm demo
corepack pnpm adapter:check
corepack pnpm adapter:smoke

pnpm demo 在 127.0.0.1:17890 临时启动 Gateway，创建仅位于 data/ 的演示项目/数据库，验证十项安全与通信行为，最后删除演示数据。如果该端口已被占用，请先停止正在运行的开发 Gateway。

分别模拟 Codex 和 Claude

先运行 Gateway。另开两个 PowerShell 终端：

# 终端 A
Set-Location C:\path\to\AgentBridge
corepack pnpm --filter @agentbridge/test-clients codex register
corepack pnpm --filter @agentbridge/test-clients codex peers
corepack pnpm --filter @agentbridge/test-clients codex inbox

# 终端 B
Set-Location C:\path\to\AgentBridge
corepack pnpm --filter @agentbridge/test-clients claude register
corepack pnpm --filter @agentbridge/test-clients claude peers
corepack pnpm --filter @agentbridge/test-clients claude inbox

register 输出的 peer UUID 可用于发送：

corepack pnpm --filter @agentbridge/test-clients codex send <CLAUDE_AGENT_UUID> "你好 Claude"
corepack pnpm --filter @agentbridge/test-clients claude inbox

项目命令：

corepack pnpm --filter @agentbridge/test-clients codex permissions
corepack pnpm --filter @agentbridge/test-clients codex request-access README.md "阅读说明"
corepack pnpm --filter @agentbridge/test-clients codex list-files .
corepack pnpm --filter @agentbridge/test-clients codex read-file README.md
corepack pnpm --filter @agentbridge/test-clients codex search AgentBridge .

模拟客户端身份只保存在 data/codex-local.json 和 data/claude-local.json。

REST API

公共接口：

模拟器客户端接口要求 X-Agent-Id 和 X-Device-Id；真实适配器要求 X-AgentBridge-Client-Id 和自己的 bearer secret：

• GET /api/client/peers

• GET /api/client/runtime-status

• POST/GET /api/client/messages

• GET /api/client/permissions

• POST /api/client/access-requests

• GET /api/client/files?path=.

• GET /api/client/file?path=README.md

• GET /api/client/search?query=text&path=.

• GET /api/client/git/status

• GET /api/client/git/diff

管理接口要求 Authorization: Bearer <AGENTBRIDGE_ADMIN_TOKEN>：

• GET /api/agents|messages|access-requests|grants|audit|project

• PUT /api/grants/:agentId

• POST /api/access-requests/:id/approve|deny

• POST /api/grants/:id/revoke

• POST /api/emergency-disconnect

• GET /api/adapter-identities

• POST /api/adapter-identities/pair

• POST /api/adapter-identities/:clientId/rotate|revoke

所有业务结果采用：

{
  "ok": true,
  "data": {},
  "error": null,
  "auditEventId": "uuid-or-null"
}

协议详情见 docs/protocol.md。

MCP 工具

• agentbridge_register

• agentbridge_list_peers

• agentbridge_send_message

• agentbridge_get_messages

• agentbridge_wait_for_message

• agentbridge_get_permissions

• agentbridge_request_project_access

• agentbridge_list_files

• agentbridge_read_file

• agentbridge_search_project

• agentbridge_get_git_status

• agentbridge_get_git_diff

没有任何 MCP 工具能批准请求或提升权限。真实适配器身份绑定在 MCP HTTP 头部和 服务端 session；工具参数不能切换身份。agentbridge_wait_for_message 最长等待 25 秒， 每个 agent 只允许一个活跃等待。所有 peer 消息都是非可信文本，Skill/CLAUDE.md 建议 最多自动往返 6 轮。

常见错误

若更换了项目根目录，重启 Gateway。若开发数据库损坏，可在 Gateway 停止后删除 data/agentbridge.db* 再启动，首次运行会自动迁移。

UI 入口说明

Codex 与 Claude Code 的官方稳定入口是插件/Skill/MCP 和客户端自己的 MCP 状态界面。 当前官方能力没有第三方强制注入固定左侧栏项目的 API，因此 AgentBridge 不伪造该能力； 管理界面继续使用 http://127.0.0.1:5173。

免责声明

AgentBridge is an independent open-source project.

It is not affiliated with, endorsed by, or officially supported by OpenAI or Anthropic.

Codex, ChatGPT, Claude, and Claude Code are trademarks of their respective owners.

许可证

AgentBridge 使用 Apache License 2.0 发布。