mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-21 15:55:50 +00:00
5e30697950
对照 /Users/konghayao/code/knowledgebase/origin/acp 规范审计并修复 53 条合规性
发现（critical 5 / major 17 / minor 20 / nit 11），完整审计报告见
docs/acp-compliance-audit.md。
Agent 端 (src/services/acp/agent.ts):
- initialize() 补齐 authMethods，promptCapabilities.image 降级为 false（声明与
实现脱节，按 initialization.mdx 不声明的 capability 视为不支持）
- sessionCapabilities.fork 移至 _meta.claudeCode.forkSession（fork 在
meta.unstable.json 中，避免在 stable sessionCapabilities 中暴露 unstable 特性）
- unstable_resumeSession 传 replay:false，不再通过 session/update 重放历史
（session-setup.mdx:239 明确禁止）
- PromptResponse.usage 移至 _meta.claudeCode.usage
（extensibility.mdx:39 禁止在 spec 类型根添加自定义字段）
- 空字符串 prompt 改为显式 throw（不再误返 end_turn）
Bridge (src/services/acp/bridge.ts):
- 删除全部 usage_update discriminator（不在 stable v1 schema 中）
- 显式映射 refusal stop_reason（之前误报 end_turn）
- max_tokens / isError 检查互斥
- Read/Write/Edit/Glob 路径全部绝对化（协议规定路径 MUST 绝对）
- 补全 resource_link / resource ContentBlock 渲染
Permissions (src/services/acp/permissions.ts):
- 补齐 reject_always PermissionOption（schema 规定的四个 option 之一）
- checkTerminalOutput 优先检查标准 clientCapabilities.terminal，
回退到 _meta.terminal_output
- 新增 onPermissionCancelled 回调：cancelled permission outcome →
StopReason::Cancelled（schema.json:629）
- ExitPlanMode cancelled 分支补上 toolUseID 字段
PromptConversion (src/services/acp/promptConversion.ts):
- resource 分支处理 BlobResource（之前静默丢弃 blob 内容）
acp-link 代理 (packages/acp-link/src/):
- WS 协议从专有 {type, payload} 改造为标准 JSON-RPC 2.0
（transports.mdx:52 要求自定义 transport MUST 保留 JSON-RPC 消息格式），
同时向后兼容旧 envelope
- 实现 $/cancel_request 处理
- 使用 JSON-RPC 标准错误码 -32700 / -32600 / -32601 / -32602 / -32603
- capability / agentInfo / protocolVersion 完整透传
验证：bun run precheck 全部通过（tsc 零错误、biome ci 零警告、5841/5841 测试通过）；
ACP 专项测试 221/221 通过。独立 verification agent 抽查全部 PASS。
已知暂缓项（审计文档附录 B/C）：
- §3.5 traceparent/trace-context 传播（QueryEngine 无 header hook）
- §5.2 terminal/create 完整生命周期（P1，非阻断，需新 RPC 流程）
- §4.2 in_progress tool_call status（SHOULD 级）
- §8.8/8.9/8.14 stale types.ts（不在 owner 分配集合，runtime 已修正）
Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win>
acp-link
ACP proxy server that bridges WebSocket clients to ACP (Agent Client Protocol) agents.
Source code adapted from chrome-acp.
Installation
From source
# From monorepo root
bun install
Usage
# Via global install
acp-link /path/to/agent
# Via source
bun src/cli/bin.ts /path/to/agent
Examples
# Basic usage
acp-link /path/to/agent
# With custom port and host
acp-link --port 9000 --host 0.0.0.0 /path/to/agent
# With debug logging
acp-link --debug /path/to/agent
# Enable HTTPS with self-signed certificate
acp-link --https /path/to/agent
# Disable authentication (dangerous)
acp-link --no-auth /path/to/agent
# Register to RCS with a specific channel group
acp-link --group my-team /path/to/agent
# Pass arguments to the agent (use -- to separate)
acp-link /path/to/agent -- --verbose --model gpt-4
CLI Reference
USAGE
acp-link [--port value] [--host value] [--debug] [--no-auth] [--https] [--group value] <command>...
acp-link --help
acp-link --version
FLAGS
[--port] Port to listen on [default = 9315]
[--host] Host to bind to [default = localhost]
[--debug] Enable debug logging to file
[--no-auth] Disable authentication (dangerous)
[--https] Enable HTTPS with self-signed cert
[--group] Channel group ID for RCS registration (letters, digits, hyphens, underscores only)
-h --help Print help information and exit
-v --version Print version information and exit
ARGUMENTS
command... Agent command followed by its arguments
How It Works
- Listens for WebSocket connections from clients
- When a "connect" message is received, spawns the configured ACP agent as a subprocess
- Bridges messages between the WebSocket (client) and stdin/stdout (agent via ACP protocol)
- Supports session management: create, load, resume, list sessions
- Handles permission approval flow and heartbeat keepalive
Authentication
By default, a random token is auto-generated on startup. Connect to the WebSocket endpoint without putting the token in the URL:
ws://localhost:9315/ws
Set ACP_AUTH_TOKEN env var to use a fixed token, or use --no-auth to
disable (not recommended). Clients that cannot send an Authorization header
must send the token in a WebSocket subprotocol named
rcs.auth.<base64url-token>.
RCS Upstream
acp-link can register to a Remote Control Server (RCS) for remote access. Set the following environment variables:
| Variable | Description |
|---|---|
ACP_RCS_URL |
RCS server URL (e.g. http://rcs.example.com:3000) |
ACP_RCS_TOKEN |
API token for RCS authentication |
ACP_RCS_GROUP |
Channel group ID to lock the agent into (letters, digits, -, _ only) |
You can also use --group <id> on the CLI. The CLI flag takes priority over the env var.
Manager UI
通过 --manager flag 启动独立的管理服务（不启动代理）：
# 启动 Manager（默认端口 9315）
acp-link --manager
# 指定端口
acp-link --manager --port 3210
在浏览器打开 http://localhost:<port> 即可访问管理界面，创建、停止、删除多个 acp-link 子进程实例并实时查看日志。
通过 Manager UI 创建的子进程会自动跳过 Manager UI。
License
MIT