> ## Documentation Index
> Fetch the complete documentation index at: https://ccb.agent-aura.top/llms.txt
> Use this file to discover all available pages before exploring further.

# Acp zed

# ACP (Agent Client Protocol) — Zed / IDE 集成

> Feature Flag: `FEATURE_ACP=1`（build 和 dev 模式默认启用）
> 实现状态：可用（支持 Zed、Cursor 等 ACP 客户端）
> 源码目录：`src/services/acp/`

## 一、功能概述

ACP (Agent Client Protocol) 是一种标准化的 stdio 协议，允许 IDE 和编辑器通过 stdin/stdout 的 NDJSON 流驱动 AI Agent。CCB 实现了完整的 ACP agent 端，可以被 Zed、Cursor 等支持 ACP 的客户端直接调用。

### 核心特性

* **会话管理**：新建 / 恢复 / 加载 / 分叉 / 关闭会话
* **历史回放**：恢复会话时自动加载并回放对话历史
* **权限桥接**：ACP 客户端的权限决策映射到 CCB 的工具权限系统
* **斜杠命令 & Skills**：加载真实命令列表，支持 `/commit`、`/review` 等 prompt 型 skill
* **Context Window 跟踪**：精确的 usage\_update，含 model prefix matching
* **Prompt 排队**：支持连续发送多条 prompt，自动排队处理
* **模式切换**：auto / default / acceptEdits / plan / dontAsk / bypassPermissions
* **模型切换**：运行时切换 AI 模型

## 二、架构

```
┌──────────────┐    NDJSON/stdio    ┌──────────────────┐
│  Zed / IDE   │ ◄────────────────► │  CCB ACP Agent   │
│  (Client)    │   stdin / stdout   │  (Agent)         │
└──────────────┘                    │                  │
                                    │  entry.ts        │ ← stdio → NDJSON stream
                                    │  agent.ts        │ ← ACP protocol handler
                                    │  bridge.ts       │ ← SDKMessage → ACP SessionUpdate
                                    │  permissions.ts  │ ← 权限桥接
                                    │  utils.ts        │ ← 通用工具
                                    │                  │
                                    │  QueryEngine     │ ← 内部查询引擎
                                    └──────────────────┘
```

### 文件职责

| 文件               | 职责                                                        |
| ---------------- | --------------------------------------------------------- |
| `entry.ts`       | 入口，创建 stdio → NDJSON stream，启动 `AgentSideConnection`      |
| `agent.ts`       | 实现 ACP `Agent` 接口：会话 CRUD、prompt、cancel、模式/模型切换           |
| `bridge.ts`      | `SDKMessage` → ACP `SessionUpdate` 转换：文本/思考/工具/用量/编辑 diff |
| `permissions.ts` | ACP `requestPermission()` → CCB `CanUseToolFn` 桥接         |
| `utils.ts`       | Pushable、流转换、权限模式解析、session fingerprint、路径显示              |

## 三、配置 Zed 编辑器

### 3.1 Zed settings.json 配置

打开 Zed 的 `settings.json`（`Cmd+,` → Open Settings），添加 `agent_servers` 配置：

```json theme={null}
{
  "agent_servers": {
    "ccb": {
      "type": "custom",
      "command": "ccb",
      "args": ["--acp"]
    }
  }
}
```

### 3.3 API 认证配置

CCB 的 ACP agent 在启动时会自动加载 `settings.json` 中的环境变量（`ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN` 等）。确保已通过 `/login` 配置好 API 供应商。

也可通过环境变量传入：

```json theme={null}
{
  "agent_servers": {
    "claude-code": {
      "command": "ccb",
      "args": ["--acp"],
      "env": {
        "ANTHROPIC_BASE_URL": "https://api.example.com/v1",
        "ANTHROPIC_AUTH_TOKEN": "sk-xxx"
      }
    }
  }
}
```

### 3.4 在 Zed 中使用

1. 配置完成后重启 Zed
2. 打开任意项目目录
3. 按 `Cmd+'`（macOS）或 `Ctrl+'`（Linux）打开 Agent Panel
4. 在 Agent Panel 顶部的下拉菜单中选择 **claude-code**
5. 开始对话

### 3.5 功能说明

| 功能   | 操作                                           |
| ---- | -------------------------------------------- |
| 对话   | 在 Agent Panel 中直接输入消息                        |
| 斜杠命令 | 输入 `/` 查看可用 skills 列表（如 `/commit`、`/review`） |
| 工具权限 | 弹出权限请求时选择 Allow / Reject / Always Allow      |
| 模式切换 | 通过 Agent Panel 的设置菜单切换 auto/default/plan 等模式 |
| 模型切换 | 通过 Agent Panel 的设置菜单切换 AI 模型                 |
| 会话恢复 | 关闭重开 Zed 后，之前的会话可自动恢复（含历史消息）                 |

## 四、配置其他 ACP 客户端

ACP 是开放协议，任何支持 ACP 的客户端都可以连接 CCB。通用配置模式：

```
命令: ccb --acp
参数: ["--acp"]
通信: stdin/stdout NDJSON
协议版本: ACP v1
```

### 4.1 Cursor

在 Cursor 的设置中配置 MCP / Agent Server，使用同样的 `ccb --acp` 命令。

### 4.2 自定义客户端

使用 `@agentclientprotocol/sdk` 可以快速构建 ACP 客户端：

```typescript theme={null}
import { ClientSideConnection, ndJsonStream } from '@agentclientprotocol/sdk'

// 创建连接（将 ccb --acp 作为子进程启动）
const child = spawn('ccb', ['--acp'])
const stream = ndJsonStream(
  Writable.toWeb(child.stdin),
  Readable.toWeb(child.stdout),
)

const client = new ClientSideConnection(stream)

// 初始化
await client.initialize({ clientCapabilities: {} })

// 创建会话
const { sessionId } = await client.newSession({
  cwd: '/path/to/project',
})

// 发送 prompt
const response = await client.prompt({
  sessionId,
  prompt: [{ type: 'text', text: 'Hello, explain this project' }],
})

// 监听 session 更新
client.on('sessionUpdate', (update) => {
  console.log('Update:', update)
})
```

## 五、ACP 协议支持矩阵

| 方法                       | 状态 | 说明              |
| ------------------------ | -- | --------------- |
| `initialize`             | ✅  | 返回 agent 信息和能力  |
| `authenticate`           | ✅  | 无需认证（自托管）       |
| `newSession`             | ✅  | 创建新会话           |
| `resumeSession`          | ✅  | 恢复已有会话（含历史回放）   |
| `loadSession`            | ✅  | 加载指定会话（含历史回放）   |
| `listSessions`           | ✅  | 列出可用会话          |
| `forkSession`            | ✅  | 分叉会话            |
| `closeSession`           | ✅  | 关闭会话            |
| `prompt`                 | ✅  | 发送消息，支持排队       |
| `cancel`                 | ✅  | 取消当前/排队的 prompt |
| `setSessionMode`         | ✅  | 切换权限模式          |
| `setSessionModel`        | ✅  | 切换 AI 模型        |
| `setSessionConfigOption` | ✅  | 动态修改配置          |

### SessionUpdate 类型

| 类型                          | 状态 | 说明                        |
| --------------------------- | -- | ------------------------- |
| `agent_message_chunk`       | ✅  | 助手文本消息                    |
| `agent_thought_chunk`       | ✅  | 思考/推理内容                   |
| `user_message_chunk`        | ✅  | 用户消息（历史回放）                |
| `tool_call`                 | ✅  | 工具调用开始                    |
| `tool_call_update`          | ✅  | 工具调用结果/状态更新               |
| `usage_update`              | ✅  | token 用量 + context window |
| `plan`                      | ✅  | TodoWrite → plan entries  |
| `available_commands_update` | ✅  | 斜杠命令 & skills 列表          |
| `current_mode_update`       | ✅  | 模式切换通知                    |
| `config_option_update`      | ✅  | 配置更新通知                    |