ACP

这是什么

ACP（Agent Client Protocol）是一种标准化的 stdio 协议：编辑器 / IDE 作为客户端， 通过进程的 stdin / stdout 收发 NDJSON 消息来驱动一个 AI agent。 千手大师实现了完整的 agent 端，因此任何支持 ACP 的客户端（Zed、Cursor 等）都能直接调用它。

入口是一条快速路径：当首个参数为 --acp 时，CLI 跳过完整 REPL 启动流程， 直接加载 runAcpAgent()。读取端把 Node 流包成 ACP 的 Stream， 再用 AgentSideConnection 驱动 AcpAgent 实现。

AcpAgent 的角色是 ACP Agent 接口的实现体，负责会话 CRUD （新建 / 恢复 / 加载 / 分叉 / 关闭 / 列出）、发送 prompt、取消、以及运行时切换权限模式与模型。 它在会话内部复用千手大师的 QueryEngine 完成真正的对话执行。

前置条件

• 已在 Zed、Cursor 或自建 ACP 客户端中配置好以子进程方式启动 qsdashi --acp 的能力。
• 已通过 /login 配置好 API 供应商，或准备了 QS_BASE_URL / QS_AUTH_TOKEN 等凭证。
• 运行 ACP agent 的机器上已安装千手大师（qsdashi，英文命令别名 qs-master）。
• 使用 acp-link 远程接入时，需能运行仓库内 packages/acp-link 或已安装其 acp-link 可执行文件。

ACP agent 启动时会调用 applySafeConfigEnvironmentVariables()， 自动把 settings.json 中的环境变量（QS_BASE_URL、QS_AUTH_TOKEN、模型覆盖等） 注入 process.env。这一点很关键：由 Zed 拉起的进程默认拿不到这些变量。

安装与启用

qsdashi --acp

{
  "agent_servers": {
    "qsdashi": {
      "type": "custom",
      "command": "qsdashi",
      "args": ["--acp"]
    }
  }
}

# 源码目录内运行（monorepo）
bun packages/acp-link/src/cli/bin.ts qsdashi -- --acp

# 或使用安装后的 acp-link 可执行文件，指定端口与主机
acp-link --port 9000 --host 0.0.0.0 qsdashi -- --acp

配置

acp-link 命令行参数

环境变量

权限模式与 fallback 链

支持的权限模式：default、auto、acceptEdits、plan、dontAsk、bypassPermissions。当客户端未显式传入 permissionMode 时，按以下顺序兜底：

# 客户端传值 > config.permissionMode > ACP_PERMISSION_MODE 环境变量
ACP_PERMISSION_MODE=auto acp-link qsdashi -- --acp

认证传递

默认连接端点为 ws://localhost:9315/ws，token 不放在 URL 中。 无法发送 Authorization 头的 WebSocket 客户端，需通过 rcs.auth.<base64url-token> 子协议传递 token。

常用命令与参数

ACP 协议方法支持

SessionUpdate 类型（节选）：agent_message_chunk、agent_thought_chunk、user_message_chunk（历史回放）、tool_call、tool_call_update、usage_update、plan、available_commands_update、current_mode_update、config_option_update。

实战示例

带环境变量在 Zed 中启动（进程由 Zed 拉起、拿不到 shell 环境时）：

{
  "agent_servers": {
    "qsdashi": {
      "command": "qsdashi",
      "args": ["--acp"],
      "env": {
        "QS_BASE_URL": "https://api.example.com/v1",
        "QS_AUTH_TOKEN": "sk-xxx"
      }
    }
  }
}

接入 RCS，通过 Web UI 远程操控：

ACP_RCS_URL=http://localhost:3000 \
ACP_RCS_TOKEN=sk-rcs-your-key \
acp-link qsdashi -- --acp

注册分两步：先通过 REST POST /v1/environments/bridge 向 RCS 注册环境并拿到 agentId，再建立 WebSocket 后发送 identify 消息（携带 agentId）完成标识。RCS 的 ACP WebSocket 不接受 URL query token， acp-link 会用 rcs.auth.<base64url-token> 子协议发送 ACP_RCS_TOKEN。

Plan 可视化：当会话使用 TodoWrite 时，bridge 会把待办映射为 ACP 的 session/update 中 sessionUpdate: "plan" 消息， 每个条目带 content、归一化后的 status 与 priority。 支持 ACP Plan 视图的客户端会直接渲染为带进度与状态图标的清单。

自建 ACP 客户端（用 @agentclientprotocol/sdk）：

import { ClientSideConnection, ndJsonStream } from '@agentclientprotocol/sdk'

// 将 qsdashi --acp 作为子进程启动，接通 stdio
const child = spawn('qsdashi', ['--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' })
await client.prompt({
  sessionId,
  prompt: [{ type: 'text', text: '解释一下这个项目' }],
})

常见问题排错