# ACP 协议集成

> ACP (Agent Client Protocol) 是 Zed 编辑器推出的一种通用智能体协议，使智能体的核心功能（服务端）和用户界面（客户端）解耦，允许用户自由选择不同的智能体服务端和客户端进行搭配使用。

CodeBuddy Code 原生支持 ACP 协议，可以作为智能体服务端与支持 ACP 的编辑器无缝集成。

## 快速开始

### 启动 ACP 模式

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

```bash
codebuddy --acp
```

## Zed 编辑器集成

### 配置步骤

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

```json
{
  "agent_servers": {
    "CodeBuddy Code": {
      "command": "codebuddy",
      "args": ["--acp"],
      "env": {}
    }
  }
}
```

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

### 配置说明

- **command**：指定 CodeBuddy Code 的命令路径（确保 `codebuddy` 在 PATH 中可用）
- **args**：使用 `["--acp"]` 启用 ACP 协议模式
- **env**：可选的环境变量配置，例如：

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

  > **注意**：使用 `CODEBUDDY_API_KEY` 时，必须根据版本正确配置 `CODEBUDDY_INTERNET_ENVIRONMENT`：
  > - 海外版：不设置（默认）
  > - 中国版：`internal`
  > - iOA 版：`ioa`
  >
  > 详见 [身份和访问管理文档](iam.md#个人用户获取-api-key)。

## ACP 协议特性

### 认证信息扩展

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

```json
{
  "_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 模式的命令。

## 其他编辑器支持

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

```json
{
  "agent_servers": {
    "CodeBuddy": {
      "command": "codebuddy",
      "args": ["--acp"]
    }
  }
}
```

## 故障排除

### 连接失败

**问题**: Zed 无法连接到 CodeBuddy

**解决方法**:

1. 确认 `codebuddy` 命令可用：

   ```bash
   which codebuddy
   ```

2. 测试 ACP 模式启动：

   ```bash
   codebuddy --acp
   ```

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

### 工具调用失败

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

**解决方法**:

1. 检查工作目录权限
2. 查看 CodeBuddy 日志

## 相关链接

- [CLI 参考手册](./cli-reference.md) - 查看所有命令行参数
- [IDE 集成说明](./ide-integrations.md) - 更多编辑器集成方式
- [ACP 协议规范](https://github.com/agentclientprotocol/agent-client-protocol) - 协议详细文档

---

*通过 ACP 协议，让 CodeBuddy Code 融入您喜爱的编辑器 🚀*
