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:
claude-code-best
2026-06-19 12:33:58 +08:00
parent f69c705166
commit 5e30697950
13 changed files with 2693 additions and 258 deletions

View File

@@ -234,7 +234,7 @@ describe('createAcpCanUseTool', () => {
}
})
test('options include allow always, allow once, and reject once', async () => {
test('options include allow always, allow once, reject once, and reject always', async () => {
const conn = makeConn({ outcome: { outcome: 'cancelled' } })
const canUseTool = createAcpCanUseTool(conn, 'sess-3', () => 'default')
await canUseTool(makeTool('Write'), {}, dummyContext, dummyMsg, 'tu_8')
@@ -245,6 +245,7 @@ describe('createAcpCanUseTool', () => {
expect(opts.find(option => option.kind === 'allow_always')).toBeTruthy()
expect(opts.find(option => option.kind === 'allow_once')).toBeTruthy()
expect(opts.find(option => option.kind === 'reject_once')).toBeTruthy()
expect(opts.find(option => option.kind === 'reject_always')).toBeTruthy()
})
test('ExitPlanMode omits bypass option when the session does not expose it', async () => {
@@ -332,4 +333,92 @@ describe('createAcpCanUseTool', () => {
(conn.sessionUpdate as ReturnType<typeof mock>).mock.calls,
).toHaveLength(0)
})
test('checkTerminalOutput honors standard clientCapabilities.terminal', async () => {
// Standard ACP v1 client advertises terminal: true without any _meta hint.
const conn = makeConn({ outcome: { outcome: 'cancelled' } })
const capabilities = { terminal: true } as any
const canUseTool = createAcpCanUseTool(
conn,
'sess-term',
() => 'default',
capabilities,
)
await canUseTool(makeTool('Bash'), {}, dummyContext, dummyMsg, 'tu_term')
const { toolCall } = (conn.requestPermission as ReturnType<typeof mock>)
.mock.calls[0][0] as Record<string, unknown>
// toolInfoFromToolUse is mocked; we only assert the standard capability is
// respected (no crash, request delegated). The legacy _meta path is
// exercised separately below.
expect(toolCall).toBeDefined()
})
test('checkTerminalOutput falls back to legacy _meta.terminal_output', async () => {
const conn = makeConn({ outcome: { outcome: 'cancelled' } })
const capabilities = { _meta: { terminal_output: true } } as any
const canUseTool = createAcpCanUseTool(
conn,
'sess-term-legacy',
() => 'default',
capabilities,
)
await canUseTool(makeTool('Bash'), {}, dummyContext, dummyMsg, 'tu_term2')
expect(
(conn.requestPermission as ReturnType<typeof mock>).mock.calls,
).toHaveLength(1)
})
test('cancelled permission outcome invokes onPermissionCancelled callback', async () => {
const conn = makeConn({ outcome: { outcome: 'cancelled' } })
const onPermissionCancelled = mock(() => {})
const canUseTool = createAcpCanUseTool(
conn,
'sess-cancel',
() => 'default',
undefined,
undefined,
undefined,
undefined,
onPermissionCancelled,
)
const result = await canUseTool(
makeTool('Bash'),
{},
dummyContext,
dummyMsg,
'tu_cancel',
)
expect(result.behavior).toBe('deny')
expect(onPermissionCancelled).toHaveBeenCalledTimes(1)
})
test('ExitPlanMode cancelled outcome invokes onPermissionCancelled callback', async () => {
const conn = makeConn({ outcome: { outcome: 'cancelled' } })
const onPermissionCancelled = mock(() => {})
const canUseTool = createAcpCanUseTool(
conn,
'sess-cancel-plan',
() => 'plan',
undefined,
undefined,
undefined,
undefined,
onPermissionCancelled,
)
const result = await canUseTool(
makeTool('ExitPlanMode'),
{},
dummyContext,
dummyMsg,
'tu_cancel_plan',
)
expect(result.behavior).toBe('deny')
expect(onPermissionCancelled).toHaveBeenCalledTimes(1)
})
})