拆解 coze 如何支持本地 Agent

勇哥AI笔记

发布于 2026-06-03 12:58:45

640

今天突然被扣子 3.0 更新刷屏了，主要都在说扣子（Coze）的可以添加本地 Agent ，支持 Claude Code，Codex CLI。

我一看，这不是之前我心心念的想法么：做一个管理中枢，让它可以分配任务到六个本地编程智能体么。

2个多月龙虾 OpenClaw 正火的时候，我构思过用 Git 文件仓库作为任务看板来驱动多代理的团队协作，还让 Claude 给设计了一套方案：https://claude.ai/share/6369d9ac-aa77-4907-9879-92b9d155eaa1。

翻遍了所有广告文章，都没看到怎么连的，顶多就是有一句话：只需要输入一行命令，就可以连接本地的Claude Code。

那就上官网看看，按帮助的操作步骤，在接入本地Agent 界面拿到了这行命令：

npx -y coze-bridge@latest --pat-token=sat_QK6PJiIoT6cN......GsZ0zj95Wetq2 --pair-code=ab0d0a......c7d19e

这就好了，把 coze-bridge 这个 npm 包下载下来做了个完整的源码分析。

发现它的核心是一套叫 ACP（Agent Client Protocol） 的协议。

ACP 是一个基于 JSON-RPC 2.0 的开放协议，用来标准化编辑器/IDE（Client）和 AI 编程助手（Agent）之间的通信方式。

现在已经扩展到各类 Web/桌面应用与 AI Agent。

这就让我的想法有实现的路径：基于 ACP 协议的特点，做一个多 Agent 协同管理的产品。

coze-bridge 是什么？

coze-bridge 是字节跳动发布的一个 npm 包（当前版本 0.1.90）。它的角色是：本机后台 daemon，把扣子云端的 Agent Service 跟本地 AI Agent（Claude Code / Codex / OpenClaw）桥接起来。

它是一个"翻译官"——把扣子云端的 Frontier 协议翻译成本地 Agent 能理解的 ACP 协议，反过来，把本地Agent的ACP协议翻译成扣子云端的 Frontier 协议。

coze-bridge 的架构是这样的：

Coze Cloud（云端）

Agent UI		Agent Svc

↓ pair-code↓ Frontier WS

coze-bridge daemon（本机）

IPC HTTP127.0.0.1		Frontier WS Client（长连接 + 心跳）

Agent Registry (Map) claude-code | codex | openclaw

spawn 子进程

claude-agent-acp		codex-acp		openclaw

用户在扣子网页操作 → 云端通过 Frontier WebSocket 下发指令 → 本机 bridge daemon 解析指令 → spawn 本地 ACP Agent 子进程执行 → 结果原路返回。

Daemon 生命周期管理

coze-bridge 以 daemon（守护进程）模式运行，通过 ~/.coze/bridge/bridge.pid 文件实现单实例锁。

启动时会 spawn 一个 detached: true 的子进程，在 127.0.0.1 随机端口起一个 HTTP IPC 服务，通过 token 认证。

支持 macOS（launchd）、Linux（systemctl）、Windows（schtasks）三种自启注册。

配对流程（Pair）

配对流程

CLI 带--pat-token--pair-code	→	启动 daemon（如未运行）	→	POST /pair到本地 IPC

↓

调用 Coze 云端handshake APIhttps://www.coze.cn	→	获取 deviceId	→	建立 FrontierWebSocket 连接

↓

10s 周期心跳（_agent/health）· 自动 connect Agent

Spawn 子进程机制

coze-bridge 是启动全新的子进程，而不是连接用户本地已经运行的 Agent。

它安装的是专门的 ACP wrapper 包，不是用户日常使用的 CLI 工具。

所以运行扣子命令时，我的Mac 弹出了两次 Codex 对电脑有危害的提示。

用户日常用的	bridge 启动的	NPM 包
claude（Claude Code CLI）	claude-agent-acp	@agentclientprotocol/claude-agent-acp
codex（Codex CLI）	codex-acp	@zed-industries/codex-acp
openclaw	openclaw	检测本地安装

coze-bridge 通过 Node.js 的 child_process.spawn() 启动子进程，stdio 设为管道模式，通过 stdin 写入命令、stdout 读取响应。

外部调用清单

目标	协议	用途
https://www.coze.cn	HTTP	handshake API、pair 配对、reconnect
wss://frontier.coze.cn	WebSocket	长连接通道、指令收发、心跳
https://llm-gateway.coze.cn	HTTP	LLM 网关、model API 调用
npm install -g <pkg>	本地进程	自动安装 ACP wrapper 包

ACP 协议：专为AI Agent 设计

ACP（Agent Client Protocol）：这是一套标准化的本地进程间通信协议，类似于 LSP（Language Server Protocol）的思路，专门为 AI Agent 设计。

协议格式

每一帧是一行 JSON（ldjson，Line-Delimited JSON），通过 stdin/stdout 双向通信：

ACP 通信方式

coze-bridge daemonstdin → 写入 JSON 命令	⇄	Agent 子进程stdout → 输出 JSON 响应

每帧 = 一行 JSON：{"method":"session.prompt","params":{...},"id":"1"}

协议核心能力

ACP 方法	方向	用途
initialize	Client → Agent	握手，协商协议版本和能力
session.prompt	Client → Agent	发送用户消息给 agent
session.cancel	Client → Agent	取消正在进行的 prompt
session.request_permission	Agent → Client	Agent 请求权限（如执行命令）
fs/read_text_file	Agent → Client	Agent 请求读取文件
fs/write_text_file	Agent → Client	Agent 请求写入文件

三种协议的层级关系

协议栈

ACP（Agent Client Protocol）stdin/stdout 上的 ldjson · 开放协议bridge ↔ 本地 agent 子进程

▲ 协议转换（bridge 做翻译）▼

Frontier（字节内部协议）WebSocket 上的自定义帧格式 · 字节私有coze 云端 ↔ 本机 bridge daemon

因为扣子用的 Frontier 协议，与 ACP 不兼容，coze-bridge 就是连接两者的连接器。

基于 ACP 的 Agent 团队管理方案

ACP 协议的核心特性，正好解决了 Agent 团队管理的几个关键难题：

传统痛点	ACP 怎么解决
每个 Agent CLI 接口不同	统一的 stdin/stdout ldjson 协议
无法程序化控制 Agent	ACP 天生就是给程序用的
Agent 之间无法协作	内置 fs/read + fs/write 文件协作
状态管理混乱	session 机制天然支持会话隔离
权限控制困难	session.request_permission 机制

产品架构设计

Agent 团队管理产品架构

产品控制面板（Web UI）

任务管理		Agent 管理		监控看板		成果输出

调度引擎（Scheduler）

任务编排引擎：任务拆解 · 依赖管理 · 并行调度 · 结果聚合

ACP Agent Pool

Agent #1claude（编码）		Agent #2claude（设计）		Agent #3codex（测试）		Agent #4openclaw（审查）

任务拆解与分发流程

用户输入一个复杂任务后，主控 Agent 先拆解，再分发给多个专职 Agent 并行执行：

任务拆解与分发

用户输入：「开发一个用户登录模块」

↓ session.prompt → 主控 Agent 拆解

返回子任务列表：1.数据库设计 → 2.API 接口 → 3.前端页面 → 4.单元测试 → 5.代码审查

↓ ACP 并行分发

Agent #1数据库设计claude-agent-acp		Agent #2API 接口开发claude-agent-acp		Agent #3前端页面开发codex-acp		Agent #4单元测试codex-acp

Agent 间协作机制

ACP 协议内置的 fs/read_text_file 和 fs/write_text_file 让 Agent 之间可以通过共享 workspace 文件间接协作：

Agent 间文件协作

Agent #1 writeTextFile("schema.sql")	→	共享 Workspace schema.sql · api-spec.json	→	Agent #2 readTextFile("schema.sql")

协作链路

#1 写 schema.sql → #2 读 schema 写 API → #3 读 API 写前端 → #4 读 API 写测试

实现与挑战

三步走路线图

实现路线图

MVP启动多个 ACP AgentWeb UI 创建任务简单任务队列	→	智能调度主控 Agent 自动拆解DAG 依赖管理并行 + 失败重试	→	团队协作多用户共享 Agent 池实时监控看板成果自动聚合

关键技术挑战

挑战	解决方案
Agent 进程管理	守护进程 + 健康检查 + 自动重启
任务状态同步	基于 ACP session 机制 + 本地状态机
Agent 间通信	共享 workspace 文件 + 可选消息队列
资源消耗	Agent 池大小限制 + 空闲回收
错误处理	ACP 错误码映射 + 重试策略