vault backup: 2026-06-09 23:15:17

2026-06-09 23:15:17 +08:00
parent 31fd89aafe
commit e92c0327d9
111 changed files with 7276 additions and 8846 deletions
@@ -1,12 +1,20 @@
+---
+tags: [acp, zed, ide集成, protocol, claude-code]
+create time: 2026-06-09 22:30
+---
+
 # ACP (Agent Client Protocol) — Zed / IDE 集成

+## 概述
+
+ACP 是一种标准化的 stdio 协议，允许 IDE 和编辑器通过 stdin/stdout 的 NDJSON 流驱动 AI Agent。CCB 实现了完整的 ACP agent 端，可被 Zed、Cursor 等支持 ACP 的客户端直接调用。
+
+> [!info]
 > 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 的客户端直接调用。
+## 正文

 ### 核心特性

@@ -19,24 +27,20 @@ ACP (Agent Client Protocol) 是一种标准化的 stdio 协议，允许 IDE 和
 - **模式切换**：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     │ ← 内部查询引擎
-                                    └──────────────────┘
+```mermaid
+graph LR
+    A["Zed / IDE (Client)"] -->|"NDJSON/stdio stdin/stdout"| B["CCB ACP Agent"]
+    B --> C["entry.ts: stdio → NDJSON stream"]
+    B --> D["agent.ts: ACP protocol handler"]
+    B --> E["bridge.ts: SDKMessage → ACP SessionUpdate"]
+    B --> F["permissions.ts: 权限桥接"]
+    B --> G["utils.ts: 通用工具"]
+    B --> H["QueryEngine: 内部查询引擎"]
 ```

-### 文件职责
+#### 文件职责

 | 文件 | 职责 |
 |------|------|
@@ -46,9 +50,9 @@ ACP (Agent Client Protocol) 是一种标准化的 stdio 协议，允许 IDE 和
 | `permissions.ts` | ACP `requestPermission()` → CCB `CanUseToolFn` 桥接 |
 | `utils.ts` | Pushable、流转换、权限模式解析、session fingerprint、路径显示 |

-## 三、配置 Zed 编辑器
+### 配置 Zed 编辑器

-### 3.1 Zed settings.json 配置
+#### Zed settings.json 配置

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

@@ -64,7 +68,7 @@ ACP (Agent Client Protocol) 是一种标准化的 stdio 协议，允许 IDE 和
 }
 ```

-### 3.3 API 认证配置
+#### API 认证配置

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

@@ -85,7 +89,7 @@ CCB 的 ACP agent 在启动时会自动加载 `settings.json` 中的环境变量
 }
 ```

-### 3.4 在 Zed 中使用
+#### 在 Zed 中使用

 1. 配置完成后重启 Zed
 2. 打开任意项目目录
@@ -93,7 +97,7 @@ CCB 的 ACP agent 在启动时会自动加载 `settings.json` 中的环境变量
 4. 在 Agent Panel 顶部的下拉菜单中选择 **claude-code**
 5. 开始对话

-### 3.5 功能说明
+#### 功能说明

 | 功能 | 操作 |
 |------|------|
@@ -104,7 +108,7 @@ CCB 的 ACP agent 在启动时会自动加载 `settings.json` 中的环境变量
 | 模型切换 | 通过 Agent Panel 的设置菜单切换 AI 模型 |
 | 会话恢复 | 关闭重开 Zed 后，之前的会话可自动恢复（含历史消息） |

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

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

@@ -115,11 +119,11 @@ ACP 是开放协议，任何支持 ACP 的客户端都可以连接 CCB。通用
 协议版本: ACP v1
 ```

-### 4.1 Cursor
+#### Cursor

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

-### 4.2 自定义客户端
+#### 自定义客户端

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

@@ -155,7 +159,7 @@ client.on('sessionUpdate', (update) => {
 })
 ```

-## 五、ACP 协议支持矩阵
+### ACP 协议支持矩阵

 | 方法 | 状态 | 说明 |
 |------|------|------|
@@ -173,7 +177,7 @@ client.on('sessionUpdate', (update) => {
 | `setSessionModel` | ✅ | 切换 AI 模型 |
 | `setSessionConfigOption` | ✅ | 动态修改配置 |

-### SessionUpdate 类型
+#### SessionUpdate 类型

 | 类型 | 状态 | 说明 |
 |------|------|------|
@@ -187,3 +191,9 @@ client.on('sessionUpdate', (update) => {
 | `available_commands_update` | ✅ | 斜杠命令 & skills 列表 |
 | `current_mode_update` | ✅ | 模式切换通知 |
 | `config_option_update` | ✅ | 配置更新通知 |
+
+## 关联笔记
+
+- [[acp-link]]
+- [[remote-control-self-hosting]]
+- [[all-features-guide]]