ACP 协议集成

下载

聚焦模式

字号

最后更新时间： 2026-09-30 18:15:49

ACP (Agent Client Protocol) 是 Zed 编辑器推出的一种通用智能体协议，使智能体的核心功能（服务端）和用户界面（客户端）解耦，允许用户自由选择不同的智能体服务端和客户端进行搭配使用。
CodeBuddy Code 原生支持 ACP 协议，可以作为智能体服务端与支持 ACP 的编辑器无缝集成。
快速开始
启动 ACP 模式
使用 --acp 参数启动 CodeBuddy Code 的 ACP 服务器：
codebuddy --acp
Zed 编辑器集成
配置步骤
打开 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：
海外版：不设置（默认）
中国版：`internal`
iOA 版：`ioa`
ACP 协议特性
认证信息扩展
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 协议规范 - 协议详细文档
﻿

帮助和支持

本页内容是否解决了您的问题？

您也可以联系销售或提交工单以寻求帮助。

填写满意度调查问卷，共创更好文档体验。

文档反馈

tencent cloud

Tencent WorkBuddy Enterprise

ACP 协议集成

快速开始

启动 ACP 模式

Zed 编辑器集成

配置步骤

配置说明

ACP 协议特性

认证信息扩展

工具代理机制

命令列表推送

Agent Teams 协议扩展

Team 状态事件

成员流式消息

页面刷新恢复

其他编辑器支持

故障排除

连接失败

工具调用失败

相关链接

帮助和支持