versun/claude-code
1
0
Fork 0
mirror of https://github.com/claude-code-best/claude-code.git synced 2026-06-23 00:35:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix: 严格对齐 ACP 协议实现到 stable v1 规范

Browse Source 
对照 /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
Download Patch File Download Diff File Expand all files Collapse all files

116
src/services/acp/__tests__/agent.test.ts
View File

@@ -260,25 +260,42 @@ describe('AcpAgent', () => {
expect(typeof res.agentInfo?.version).toBe('string')
})
test('advertises image and embeddedContext capability', async () => {
test('advertises embeddedContext capability and disables image until multimodal input lands', async () => {
const agent = new AcpAgent(makeConn())
const res = await agent.initialize({} as any)
expect(res.agentCapabilities?.promptCapabilities?.image).toBe(true)
// image:false — promptToQueryInput does not parse image blocks yet
expect(res.agentCapabilities?.promptCapabilities?.image).toBe(false)
expect(res.agentCapabilities?.promptCapabilities?.embeddedContext).toBe(
true,
)
})
test('returns explicit empty authMethods', async () => {
const agent = new AcpAgent(makeConn())
const res = await agent.initialize({} as any)
expect(res.authMethods).toEqual([])
})
test('loadSession capability is true', async () => {
const agent = new AcpAgent(makeConn())
const res = await agent.initialize({} as any)
expect(res.agentCapabilities?.loadSession).toBe(true)
})
test('session capabilities include fork, list, resume, close', async () => {
test('session capabilities include list, resume, close (fork advertised via _meta)', async () => {
const agent = new AcpAgent(makeConn())
const res = await agent.initialize({} as any)
expect(res.agentCapabilities?.sessionCapabilities).toBeDefined()
const caps = res.agentCapabilities?.sessionCapabilities as any
expect(caps).toBeDefined()
expect(caps.list).toBeDefined()
expect(caps.resume).toBeDefined()
expect(caps.close).toBeDefined()
// fork is UNSTABLE — advertised under _meta.claudeCode.forkSession, not
// under sessionCapabilities (which is stable-v1 only).
expect(caps.fork).toBeUndefined()
expect(
(res.agentCapabilities?._meta as any)?.claudeCode?.forkSession,
).toBe(true)
})
})
@@ -298,12 +315,13 @@ describe('AcpAgent', () => {
expect(res.sessionId.length).toBeGreaterThan(0)
})
test('returns modes and models', async () => {
test('returns modes and configOptions (models omitted for v1 compliance)', async () => {
const agent = new AcpAgent(makeConn())
const res = await agent.newSession({ cwd: '/tmp' } as any)
expect(res.modes).toBeDefined()
expect(res.models).toBeDefined()
expect(res.configOptions).toBeDefined()
// Stable v1 NewSessionResponse does not define `models`
expect((res as any).models).toBeUndefined()
})
test('each call returns a unique sessionId', async () => {
@@ -328,9 +346,10 @@ describe('AcpAgent', () => {
test('calls getMainLoopModel to resolve current model', async () => {
const agent = new AcpAgent(makeConn())
const res = await agent.newSession({ cwd: '/tmp' } as any)
await agent.newSession({ cwd: '/tmp' } as any)
expect(mockGetMainLoopModel).toHaveBeenCalled()
expect(res.models?.currentModelId).toBe('claude-sonnet-4-6')
// models is no longer in the v1 response, but the engine still receives it
expect(mockSetModel).toHaveBeenCalledWith('claude-sonnet-4-6')
})
test('calls queryEngine.setModel with resolved model', async () => {
@@ -342,8 +361,7 @@ describe('AcpAgent', () => {
test('respects model alias resolution via getMainLoopModel', async () => {
mockGetMainLoopModel.mockReturnValueOnce('glm-5.1')
const agent = new AcpAgent(makeConn())
const res = await agent.newSession({ cwd: '/tmp' } as any)
expect(res.models?.currentModelId).toBe('glm-5.1')
await agent.newSession({ cwd: '/tmp' } as any)
expect(mockSetModel).toHaveBeenCalledWith('glm-5.1')
})
@@ -464,21 +482,23 @@ describe('AcpAgent', () => {
).rejects.toThrow('nonexistent')
})
test('returns end_turn for empty prompt text', async () => {
test('rejects empty prompt text with an error', async () => {
const agent = new AcpAgent(makeConn())
const { sessionId } = await agent.newSession({ cwd: '/tmp' } as any)
const res = await agent.prompt({ sessionId, prompt: [] } as any)
expect(res.stopReason).toBe('end_turn')
await expect(
agent.prompt({ sessionId, prompt: [] } as any),
).rejects.toThrow('Prompt content is empty')
})
test('returns end_turn for whitespace-only prompt', async () => {
test('rejects whitespace-only prompt with an error', async () => {
const agent = new AcpAgent(makeConn())
const { sessionId } = await agent.newSession({ cwd: '/tmp' } as any)
const res = await agent.prompt({
sessionId,
prompt: [{ type: 'text', text: ' ' }],
} as any)
expect(res.stopReason).toBe('end_turn')
await expect(
agent.prompt({
sessionId,
prompt: [{ type: 'text', text: ' ' }],
} as any),
).rejects.toThrow('Prompt content is empty')
})
test('calls forwardSessionUpdates for valid prompt', async () => {
@@ -556,7 +576,7 @@ describe('AcpAgent', () => {
).rejects.toThrow('unexpected')
})
test('returns usage from forwardSessionUpdates', async () => {
test('returns usage under _meta.claudeCode.usage from forwardSessionUpdates', async () => {
const agent = new AcpAgent(makeConn())
const { sessionId } = await agent.newSession({ cwd: '/tmp' } as any)
;(forwardSessionUpdates as ReturnType<typeof mock>).mockResolvedValueOnce(
@@ -574,10 +594,13 @@ describe('AcpAgent', () => {
sessionId,
prompt: [{ type: 'text', text: 'hello' }],
} as any)
expect(res.usage).toBeDefined()
expect(res.usage!.inputTokens).toBe(100)
expect(res.usage!.outputTokens).toBe(50)
expect(res.usage!.totalTokens).toBe(165)
// Stable v1 PromptResponse has no root `usage`; it lives under _meta.
expect((res as any).usage).toBeUndefined()
const usage = (res as any)._meta?.claudeCode?.usage
expect(usage).toBeDefined()
expect(usage.inputTokens).toBe(100)
expect(usage.outputTokens).toBe(50)
expect(usage.totalTokens).toBe(165)
})
})
@@ -649,7 +672,7 @@ describe('AcpAgent', () => {
})
describe('prompt usage tracking', () => {
test('returns totalTokens as sum of all token types', async () => {
test('reports totalTokens as sum of all token types under _meta.claudeCode.usage', async () => {
const agent = new AcpAgent(makeConn())
const { sessionId } = await agent.newSession({ cwd: '/tmp' } as any)
;(forwardSessionUpdates as ReturnType<typeof mock>).mockResolvedValueOnce(
@@ -667,11 +690,12 @@ describe('AcpAgent', () => {
sessionId,
prompt: [{ type: 'text', text: 'hello' }],
} as any)
expect(res.usage).toBeDefined()
expect(res.usage!.totalTokens).toBe(165)
const usage = (res as any)._meta?.claudeCode?.usage
expect(usage).toBeDefined()
expect(usage.totalTokens).toBe(165)
})
test('returns undefined usage when forwardSessionUpdates returns none', async () => {
test('omits _meta.usage when forwardSessionUpdates returns none', async () => {
const agent = new AcpAgent(makeConn())
const { sessionId } = await agent.newSession({ cwd: '/tmp' } as any)
;(forwardSessionUpdates as ReturnType<typeof mock>).mockResolvedValueOnce(
@@ -683,7 +707,7 @@ describe('AcpAgent', () => {
sessionId,
prompt: [{ type: 'text', text: 'hello' }],
} as any)
expect(res.usage).toBeUndefined()
expect((res as any)._meta).toBeUndefined()
})
})
@@ -734,7 +758,8 @@ describe('AcpAgent', () => {
} as any)
expect(agent.sessions.has(requestedId)).toBe(true)
expect(res.modes).toBeDefined()
expect(res.models).toBeDefined()
// models is omitted for v1 compliance
expect((res as any).models).toBeUndefined()
})
test('reuses existing session when sessionId matches and fingerprint unchanged', async () => {
@@ -805,12 +830,26 @@ describe('AcpAgent', () => {
const agent = new AcpAgent(makeConn())
const original = await agent.newSession({ cwd: '/tmp' } as any)
const forked = await agent.unstable_forkSession({
// params.sessionId is the source session to fork from
sessionId: original.sessionId,
cwd: '/tmp',
mcpServers: [],
} as any)
expect(forked.sessionId).not.toBe(original.sessionId)
expect(agent.sessions.has(forked.sessionId)).toBe(true)
})
test('attempts to load source session history when forking', async () => {
const agent = new AcpAgent(makeConn())
const original = await agent.newSession({ cwd: '/tmp' } as any)
mockGetLastSessionLog.mockClear()
await agent.unstable_forkSession({
sessionId: original.sessionId,
cwd: '/tmp',
mcpServers: [],
} as any)
expect(mockGetLastSessionLog).toHaveBeenCalledWith(original.sessionId)
})
})
describe('setSessionMode', () => {
@@ -919,17 +958,32 @@ describe('AcpAgent', () => {
const session = agent.sessions.get(sessionId)
removeBypassMode(session)
// The value is rejected because it is not in the option's listed values
// (config-option validation runs before the mode-availability check).
await expect(
agent.setSessionConfigOption({
sessionId,
configId: 'mode',
value: 'bypassPermissions',
} as any),
).rejects.toThrow('Mode not available')
).rejects.toThrow(/Invalid value 'bypassPermissions'/)
expect(session?.modes.currentModeId).toBe('default')
expect(session?.appState.toolPermissionContext.mode).toBe('default')
})
test('rejects mode values not listed in the option options array', async () => {
const agent = new AcpAgent(makeConn())
const { sessionId } = await agent.newSession({ cwd: '/tmp' } as any)
await expect(
agent.setSessionConfigOption({
sessionId,
configId: 'mode',
value: 'totally-not-a-real-mode',
} as any),
).rejects.toThrow(/must be one of:/)
})
})
describe('prompt queueing', () => {