M0: framing (ndjson + lsp-frame), ACPClient, mock agent fixture, probe script; real claude-code-acp handshake verified
This commit is contained in:
1 parent
d96d4f73bb
commit
82c3763e5c
10 files changed
+967
-4
No files matched your search
+25
-3
@@ -2,16 +2,26 @@
|
||||
|
||||
> 供 agenthub 实现时对照。规范:agentclientprotocol.com
|
||||
> (spec 源:zed-industries/zed repo docs/src/ai/external-agents.md)
|
||||
>
|
||||
> ⚠️ **实测修正(M0 验证)**:当前 ACP 实现的 stdio 传输是
|
||||
> **newline-delimited JSON(ndjson)**——一行一条 JSON-RPC 消息,以 `\n` 分隔,
|
||||
> **不是** LSP 的 `Content-Length` 帧。依据:官方
|
||||
> `@agentclientprotocol/sdk` 的 `ndJsonStream()`,以及
|
||||
> `@zed-industries/claude-code-acp` 实测(发 Content-Length 帧会报
|
||||
> `Failed to parse JSON message: Content-Length: ...`)。
|
||||
> agenthub 默认 transport=`ndjson`,保留 `lsp-frame` 兼容模式备旧实现。
|
||||
|
||||
## 传输与分帧
|
||||
|
||||
- JSON-RPC 2.0 over stdio,LSP 风格 `Content-Length: N\r\n\r\n` 头分帧。
|
||||
- agent 子进程 = ACP **server**;桥 = ACP **client**。
|
||||
- JSON-RPC 2.0 over stdio:
|
||||
- **ndjson(默认/当前)**:`{"jsonrpc":...}\n`
|
||||
- lsp-frame(兼容备选):`Content-Length: N\r\n\r\n{...}`
|
||||
- agent 子进程 = ACP **server**;agenthub = ACP **client**。
|
||||
|
||||
## 生命周期(client → server)
|
||||
|
||||
1. `initialize`:`{protocolVersion, clientCapabilities}`
|
||||
→ 返回 agent 能力(loadSession、promptCapabilities…)
|
||||
→ 返回 agent 能力(loadSession、promptCapabilities…)+ authMethods
|
||||
2. `session/new`:`{cwd, mcpServers}` → `{sessionId}`
|
||||
3. `session/load`(可选能力):恢复会话,agent 重放全部历史为 update 流
|
||||
4. `session/prompt`:`{sessionId, prompt: [content_block]}` → `{stopReason}`
|
||||
@@ -31,9 +41,21 @@
|
||||
- client 反向方法:`fs/read_text_file`、`fs/write_text_file`、
|
||||
`terminal/create`(output截断/exit)、`terminal/wait_for_exit`…
|
||||
|
||||
## 实测到的真实行为(claude-code-acp v0.16 / claude CLI 2.1.290)
|
||||
|
||||
- `initialize` 返回:`{protocolVersion: 1, agentCapabilities: {promptCapabilities:
|
||||
{image, embeddedContext}, mcpCapabilities: {http, sse}, loadSession: true,
|
||||
sessionCapabilities: {fork, list, resume}}, authMethods: [{id: "claude-login"}]}`
|
||||
- `session/new` **未登录也能成功**(sessionId 立即返回)
|
||||
- `session/prompt` 未登录返回 JSON-RPC 错误 **`-32000 Authentication required`**
|
||||
—— 认证失败走 error 通道,不是 stopReason
|
||||
- 每个会话会先推一条 `available_commands_update` 通知
|
||||
|
||||
## 实现提醒
|
||||
|
||||
- id 复用规则:同方向自增;notification 无 id。
|
||||
- stdout 只能走协议帧——任何 agent 混入的裸日志都会破坏分帧。
|
||||
- 权限请求必须回应,否则 agent turn 会挂死;桥侧超时默认拒绝。
|
||||
- 版本协商失败(protocolVersion 不兼容)→ 直接报错,不要猜。
|
||||
- JSON-RPC 业务错误(如未认证 -32000)与传输层错误要分开处理:
|
||||
前者是 agent 的正常回复,不能当崩溃。
|
||||
Reference in new issue
Block a user