mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-24 17:15:50 +00:00
fix: 严格对齐 ACP 协议实现到 stable v1 规范
对照 /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>
This commit is contained in:
@@ -7,12 +7,65 @@ export class WsPayloadTooLargeError extends Error {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Legacy proprietary envelope shape: `{ type, payload? }`.
|
||||
* Retained for backwards compatibility with older clients (e.g. the RCS Web UI)
|
||||
* that have not migrated to JSON-RPC 2.0 yet.
|
||||
*/
|
||||
export interface JsonWsMessage {
|
||||
type: string
|
||||
payload?: unknown
|
||||
[key: string]: unknown
|
||||
}
|
||||
|
||||
/**
|
||||
* JSON-RPC 2.0 envelope as defined by the specification.
|
||||
* See transports.mdx: custom transports MUST preserve the JSON-RPC message
|
||||
* format and lifecycle requirements defined by ACP.
|
||||
*/
|
||||
export interface JsonRpc2Request {
|
||||
jsonrpc: '2.0'
|
||||
id: string | number | null
|
||||
method: string
|
||||
params?: unknown
|
||||
}
|
||||
|
||||
export interface JsonRpc2Notification {
|
||||
jsonrpc: '2.0'
|
||||
method: string
|
||||
params?: unknown
|
||||
}
|
||||
|
||||
export interface JsonRpc2Response {
|
||||
jsonrpc: '2.0'
|
||||
id: string | number | null
|
||||
result?: unknown
|
||||
error?: { code: number; message: string; data?: unknown }
|
||||
}
|
||||
|
||||
export type JsonRpc2Message =
|
||||
| JsonRpc2Request
|
||||
| JsonRpc2Notification
|
||||
| JsonRpc2Response
|
||||
|
||||
/**
|
||||
* Messages that carry a `method` field — i.e. requests and notifications that
|
||||
* the proxy can route. Responses (no method) are excluded because clients are
|
||||
* not expected to send them to the agent.
|
||||
*/
|
||||
export type JsonRpc2ClientMessage = JsonRpc2Request | JsonRpc2Notification
|
||||
|
||||
export function isJsonRpc2Message(
|
||||
value: unknown,
|
||||
): value is JsonRpc2ClientMessage {
|
||||
return (
|
||||
typeof value === 'object' &&
|
||||
value !== null &&
|
||||
(value as { jsonrpc?: unknown }).jsonrpc === '2.0' &&
|
||||
typeof (value as { method?: unknown }).method === 'string'
|
||||
)
|
||||
}
|
||||
|
||||
function assertPayloadSize(byteLength: number): void {
|
||||
if (byteLength > MAX_CLIENT_WS_PAYLOAD_BYTES) {
|
||||
throw new WsPayloadTooLargeError(byteLength)
|
||||
@@ -49,14 +102,28 @@ function decodeWsText(data: unknown): string {
|
||||
throw new Error('Unsupported WebSocket message payload')
|
||||
}
|
||||
|
||||
/**
|
||||
* Decode a WebSocket text frame into either a JSON-RPC 2.0 message or the
|
||||
* legacy proprietary `{type, payload}` envelope.
|
||||
*
|
||||
* Accepts:
|
||||
* - JSON-RPC 2.0 requests/notifications/responses (`{ jsonrpc: '2.0', method, ... }`)
|
||||
* - Legacy proprietary messages (`{ type: string, payload?: unknown }`)
|
||||
*
|
||||
* Rejects anything else with `Invalid WebSocket message payload`.
|
||||
*/
|
||||
export function decodeJsonWsMessage(data: unknown): JsonWsMessage {
|
||||
const parsed = JSON.parse(decodeWsText(data)) as unknown
|
||||
if (
|
||||
typeof parsed !== 'object' ||
|
||||
parsed === null ||
|
||||
!('type' in parsed) ||
|
||||
typeof parsed.type !== 'string'
|
||||
) {
|
||||
if (typeof parsed !== 'object' || parsed === null) {
|
||||
throw new Error('Invalid WebSocket message payload')
|
||||
}
|
||||
// JSON-RPC 2.0 envelope — preserve all original fields so the router can
|
||||
// correlate request ids and forward notifications unchanged.
|
||||
if (isJsonRpc2Message(parsed)) {
|
||||
return parsed as unknown as JsonWsMessage
|
||||
}
|
||||
// Legacy proprietary envelope `{ type, payload? }`.
|
||||
if (!('type' in parsed) || typeof parsed.type !== 'string') {
|
||||
throw new Error('Invalid WebSocket message payload')
|
||||
}
|
||||
return parsed as JsonWsMessage
|
||||
|
||||
Reference in New Issue
Block a user