CodeBuddy ACP 协议集成

一、启动 ACP 模式

使用 –acp 参数启动 CodeBuddy Code 的 ACP 服务器：

codebuddy –acp

二、配置步骤

打开 Zed 配置文件（~/.config/zed/settings.json），添加以下配置：

{ "agent_servers": { "CodeBuddy Code": { "command": "codebuddy", "args": ["–acp"], "env": {} } }}

随后即可在 Zed 侧边栏创建 CodeBuddy Code Thread，开始使用。

三、配置说明

·command：指定 CodeBuddy Code 的命令路径（确保 codebuddy 在 PATH 中可用）

·args：使用 ["–acp"] 启用 ACP 协议模式

·env：可选的环境变量配置，例如：

{ "env": { "CODEBUDDY_API_KEY": "your-api-key", "CODEBUDDY_INTERNET_ENVIRONMENT": "internal" }}

注意：使用 CODEBUDDY_API_KEY 时，必须根据版本正确配置 CODEBUDDY_INTERNET_ENVIRONMENT：

四、认证信息扩展

CodeBuddy Code 在 authenticate 响应的 _meta 字段中返回用户信息：

{ "_meta": { "codebuddy.ai/userinfo": { "userId": "用户 ID", "userName": "用户名", "userNickname": "用户昵称" } }}

客户端可以利用这些信息提供更好的用户体验，例如显示当前登录用户、个性化界面等。

五、工具代理机制

ACP 协议支持客户端代理部分工具操作，提升性能和安全性：

·文件操作代理：基于客户端的 fs.readTextFile 和 fs.writeTextFile 能力

·终端操作代理：基于客户端的 terminal 能力

当客户端声明支持这些能力时，CodeBuddy Code 会自动将相关工具调用代理给客户端执行。

六、命令列表推送

CodeBuddy Code 会在创建新会话时自动向客户端推送可用的 Slash 命令列表（available_commands_update），让客户端能够：

·提供命令自动补全功能

·显示命令提示和帮助信息

·动态更新可用命令

命令列表会自动过滤掉本地命令（如 /clear、/exit）和客户端专属命令（如 /theme、/config），只推送适用于 ACP 模式的命令。

七、Agent Teams 协议扩展

CodeBuddy Code 通过 session_info_update 的 _meta 字段扩展 ACP 协议，支持 Agent Teams 多智能体协作的实时状态推送。

八、Team 状态事件

通过 _meta['codebuddy.ai/teamUpdate'] 推送以下事件类型：

成员状态变化 (member_status_change)：

{ "sessionUpdate": "session_info_update", "_meta": { "codebuddy.ai/teamUpdate": { "type": "member_status_change", "teamName": "my-team", "isAutoTeam": false, "members": [ { "name": "ux-designer", "color": "blue", "description": "用户体验设计分析", "status": "running", "taskId": "agent-abc123", "sessionId": "session-xyz", "tokenUsage": { "inputTokens": 1000, "outputTokens": 500, "lastContextWindow": 42000 }, "toolCallCount": 5 } ] } }}

Team 创建 (team_created) / 删除 (team_deleted)：

{ "sessionUpdate": "session_info_update", "_meta": { "codebuddy.ai/teamUpdate": { "type": "team_created", "teamName": "my-team" } }}

九、成员流式消息

成员的实时消息（文本、工具调用）通过标准 ACP 事件推送，附加 _meta['codebuddy.ai/memberEvent'] 标记来标识消息来源：

{ "sessionUpdate": "agent_message_chunk", "content": { "type": "text", "text": "正在分析架构方案…" }, "_meta": { "codebuddy.ai/memberEvent": "tech-architect" }}

客户端收到带 memberEvent 标记的事件后，应将其路由到对应成员的对话时间线，而非主对话区。

十、页面刷新恢复

页面刷新后，loadSession 的 replayHistory 完成后会自动推送当前 Team 状态（member_status_change 事件），客户端无需单独请求。AcpTeamBridge 在订阅成员 session 时会自动重放其完整历史，因此成员的对话数据也通过 ACP SSE 完整恢复，无需额外 HTTP API。

十一、其他编辑器支持

ACP 是开放协议，理论上任何支持 ACP 的编辑器都可以集成 CodeBuddy Code。配置方式与 Zed 类似：

{ "agent_servers": { "CodeBuddy": { "command": "codebuddy", "args": ["–acp"] } }}

十二、连接失败

问题: Zed 无法连接到 CodeBuddy

解决方法:

1. 确认 codebuddy 命令可用：

which codebuddy

2. 测试 ACP 模式启动：

codebuddy –acp

3. 检查配置文件 JSON 格式是否正确

十三、工具调用失败

问题：文件操作或命令执行报错

解决方法:

1. 检查工作目录权限

2. 查看 CodeBuddy 日志

十四、相关链接

·CLI 参考手册：查看所有命令行参数

·codebuddy.ai/* 扩展命名空间参考 – 全部 _meta 扩展键与 _codebuddy.ai/* 扩展方法清单，含公共 / 私有分界

·IDE 集成说明 – 更多编辑器集成方式

·ACP 协议规范 – 协议详细文档