Skip to content

acp-zed.md

Latest commit

 

History

History
189 lines (150 loc) · 6.68 KB

acp-zed.md

File metadata and controls

189 lines (150 loc) · 6.68 KB

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 配置：

{
  "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 供应商。

也可通过环境变量传入：

{
  "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 客户端：

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 ✅ 配置更新通知