chore(acp): ACP v2 draft 缺口清账（state_update 生命周期、整消息 upsert、终端归属、diff 结构化等）

[YoungSx]

结论

AcpProtocolVersion.Latest = V2 但 Default = V1，且运行时硬性拒绝以 V2 初始化。已建模的只是方法名分叉与少数类型；v2 的核心变更——新 prompt 生命周期（state_update）、整消息 upsert、agent 自持终端、流式工具内容、权限主体、diff 结构化——一项都没有。本 issue 记录完整缺口清单与依赖顺序，不主张立刻实现（v2 仍是 draft）。

证据链

1. 代码自认未完成

src/SalmonEgg.Acp/Protocol/AcpProtocolVersion.cs：

/// Draft ACP v2 wire model. Live client support remains disabled until the complete
/// prompt, update, permission, configuration, and batch lifecycles are implemented.
public const int V2 = 2;

public const int Default = V1;

/// Highest protocol version whose wire contracts are modeled by this SDK. This does not
/// imply that the live client runtime is ready to negotiate that draft version.
public const int Latest = V2;

运行时闸门 src/SalmonEgg.Acp/Client/AcpClient.cs:189-196：

if (AcpProtocolVersion.IsSupported(@params.ProtocolVersion)
    && @params.ProtocolVersion != AcpProtocolVersion.V1)
{
    throw new AcpException(
        JsonRpcErrorCode.ProtocolVersionMismatch,
        StableV1RuntimeOnlyMessage);
}

StableV1RuntimeOnlyMessage（:25）："ACP live client support is limited to stable protocolVersion 1 while newer modeled versions remain draft or incomplete."

2. 已经做对的部分（不要重做）

方法名按版本分叉已就位，AcpClient.cs:719 / :756：

var methodName = _protocolVersion == AcpProtocolVersion.V2 ? "auth/login" : "authenticate";
var methodName = _protocolVersion == AcpProtocolVersion.V2 ? "auth/logout" : "logout";

SessionResumeParams.ReplayFrom 已建模（OtherSessionTypes.cs:339，配 SessionReplayFrom 开放 type 判别，:185-295）。

3. 缺口清单（逐项 grep 核实，src/ 零命中；同名巧合已排除）

v2 类型 / 机制	v2 schema 位置	我们
StateUpdate + RunningStateUpdate / IdleStateUpdate / RequiresActionStateUpdate	:5579 :4619 :3341 :4531	无
AgentMessage / AgentThought / UserMessage（整消息 upsert 变体）	:1214 :1250 :6494	无（只有 v1 的 *_chunk）
TerminalUpdate / TerminalOutput / TerminalOutputChunk	:5978 :5928 :5951	无
ToolCallContentChunk（流式工具内容）	:6224	无
DiffChange / DiffPatch / DiffPatchFormat / DiffFileType / DiffPathChange / DiffPathPairChange	:2181 :2340 :2356 :2310 :2377 :2389	无（v1 的三字段 path/oldText/newText 已合规，见 Tool/ToolCallContent.cs:63-77）
RequestPermissionSubject / ToolCallPermissionSubject / CommandPermissionSubject	:4454 :6290 :1790	无
PromptImageCapabilities / PromptAudioCapabilities / PromptEmbeddedContextCapabilities（bool → 对象）	:4257 :4170 :4239	无（PromptCapabilities 三个字段仍是 bool，InitializeTypes.cs:537-556）
McpHttpCapabilities / TerminalAuthCapabilities	:3513 :5868	无
Icon / IconTheme	:3289 :3319	无
SessionListCursor	:5080	无（分页游标目前是裸 cursor）
TextCommandInput	:6019	无
PlanUpdateContent / plan 变体	:4109	无

4. 我们仍携带 v2 已删除的表面

按 /tmp/acp-v2-migration.md「Session modes become config options」（:586）与「session/load is gone. session/resume does both」（:554），下列在 v2 已移除，我们仍建模（v1 需要，因此不能直接删，只能做版本门控）：

• session/load：IAcpClient.cs、AcpClient.cs、OtherSessionTypes.cs、SessionUpdateTypes.cs
• session/set_mode + SessionMode / SessionModesState / CurrentModeUpdate：IAcpClient.cs、AcpClient.cs、OtherSessionTypes.cs、SessionNewTypes.cs、SessionUpdateTypes.cs、PublicSurface.Types.txt

另有两处 v2 语义变更需在门控时一并处理：

• MCP "type": "sse" 在 v2 移除，且 stdio 在 v2 必须带 "type": "stdio"（v1 无此字段）。我们的 Mcp/McpServerConfig.cs:407-443 三种都写、都读。
• v2 里 configOptions 的标识字段由 id 改名为 configId；我们 ConfigOptionTypes.cs:14 是 id。
• v2 里 messageId 在每个 chunk/message 上必填；我们 ContentChunkUpdate.MessageId 是 string?（SessionUpdateTypes.cs:165-169），v1 语义正确、v2 需收紧。

5. 最大的结构性差异：prompt 生命周期

/tmp/acp-v2-migration.md:248-295 原文要点：

In v2, the Agent MUST respond to session/prompt as soon as it has accepted the prompt, with an empty result
... the Agent MUST report where the user message was inserted into session history
... When foreground work starts or resumes, the Agent MUST send a state_update with "state": "running"
... When the Agent is ready to process a new prompt, it MUST report idle. When the transition ends foreground work, it MUST include the stop reason

即 v1 的「响应即整轮、stopReason 在响应里」变成「响应只是 ack、stopReason 由 idle 状态携带」。我们当前是纯 v1 模型：session/prompt 的返回值就是终态。这不是加几个类型能解决的，它改变了 AcpClient 与上层 ChatService / ChatViewModel 之间的完成语义，是本 issue 里唯一需要跨层重构的项。

取消语义也随之变化（:310）：v2 不再用 "stopReason": "cancelled" 响应，改为发完 pending 更新后送一个带 cancelled stop reason 的 idle state_update。

影响

当前无实际用户影响——v2 是 draft，且我们 fail-closed 拒绝以 V2 初始化（这是正确的默认）。风险在于 Latest = V2 这个常量可能被误读为「已支持」：它的注释说清了，但常量名本身有歧义。

建议范围

不建议现在整体实现。建议：

1. 先做无争议的一步：把 Latest 的语义在命名上说清（如改为 HighestModeled 或类似），消除「Latest 就是可用」的误读面。这一步独立、低风险。
2. v2 转 stable 后再排后续，依赖顺序大致为：能力对象化 → 消息/messageId 收紧 → state_update 生命周期（跨层，最重）→ 工具调用 upsert 与流式内容 → diff 结构化 → 权限主体 → 终端归属反转。
3. 版本门控原则：v1/v2 差异用声明式分叉表达（现有 auth/login 那种按版本取名的写法可以延续），不要在共享类型上塞双语义字段。

验证要求

真正实现某一项时：

• 每项都要有 v1 与 v2 两条线的报文级断言，且互不串味（v1 报文不得出现 v2 字段，反之亦然）。
• state_update 生命周期需真实 agent 端到端跑通，断言完成语义（何时算一轮结束）在两个版本下都正确。
• 反向验证：拆掉版本判别后，对应报文断言必须转红。

[YoungSx]

实测：v2 端到端在当前无法验证（外部约束，非架构选择）

本 issue 的「验证要求」写着：

state_update 生命周期需真实 agent 端到端跑通，断言完成语义（何时算一轮结束）在两个版本下都正确。

这一条在 v2 转 stable 且上游 agent 跟进之前客观上无法满足。实测证据如下。

证据：本机两个真实 agent 都不实现 v2

向 agent 发 protocolVersion: 2 的 initialize，读回第一帧：

agent	版本	请求 v2 时的应答
@agentclientprotocol/codex-acp	0.0.46	"protocolVersion":1
@agentclientprotocol/claude-agent-acp	0.48.0	"protocolVersion":1

不是「支持 v2 但选择降级」，是没有实现 v2：两者回的能力字段都是纯 v1 形状。

codex-acp 应答节选：

{"protocolVersion":1,
 "agentCapabilities":{"loadSession":true,
   "promptCapabilities":{"embeddedContext":true,"image":true},
   "mcpCapabilities":{"acp":false,"http":true,"sse":false}}}

对照权威 v2 schema（zed-industries/agent-client-protocol 的 schema/v2/schema.json）：

• promptCapabilities 在 v2 不存在（字面计数 0）；应为 capabilities.session.prompt.*。
• image / embeddedContext 在 v2 是对象（{} = 支持），不是 bool。
• loadSession 在 v2 不存在（session/load 已移除）。
• mcpCapabilities.sse 在 v2 不存在（"sse" 字面计数 0）。

也就是说：没有可协商到 v2 的对端，v2 的 prompt 生命周期拿不到活连接。这与我们选哪种版本架构无关——即使让运行时服务 v2，客户端请求 v2、agent 回 v1，仍然连不上。

规范澄清：不需要双版本分流

查官方 v2 规范（/protocol/v2/initialization）：

The initialize request MUST include the latest protocol version the Client supports.
If the Agent supports the requested version, it MUST respond with the same version. Otherwise, the Agent MUST respond with the latest version it supports.
If the Client does not support the version specified by the Agent in the initialize response, the Client SHOULD close the connection and inform the user about it.
Clients and Agents MUST agree on a protocol version and act according to its specification.

ACP 的版本模型是协商出单一版本后完全按那一版行事，并未要求任何一端同时支持多版本。单版本支持是合规的。所以本 issue 建议范围第 3 条「版本门控原则」应理解为：分叉只用于让 SDK 能同时建模两版线上契约，而不是让一个活连接同时服务两版。

因此可达到的最强验证（替代原验证要求）

1. 报文级双线断言：v2 上下文序列化出 v2 形状；v1 上下文写入 v2 专属类型即抛（沿用 SessionReplayFromJsonConverter 的 fail-closed 先例）。v1 报文不得出现 v2 字段，反之亦然。
2. 反向验证：拆掉版本判别后对应断言必须转红，并对每条断言插探针证明测试真能到达该分支。
3. v1 端到端继续用本机真 agent 跑，确保补 v2 建模不回归 v1 行为。

覆盖到的是「建模正确」与「不污染 v1」；覆盖不到「v2 活连接语义正确」。后者是本 issue 的显式待办前提，需等 v2 转 stable 且出现 v2 agent 后补做，不应视为已验证。

另外三处需要更正的事实（对着权威 schema 逐条核实）

1. MCP stdio 的 type 分叉已经做完了，不是缺口：src/SalmonEgg.Acp/Mcp/McpServerConfig.cs:635 按 AcpProtocolWriteContext.Current >= V2 决定是否写 "type":"stdio"。另外 McpServerStdio 的 required 是 ["name","command"]，type 是判别值而非必填字段——原文「stdio 在 v2 必须带 type」不准确。
2. 整消息 upsert 不是替代 *_chunk，两者并存。v2 的 SessionUpdate 有 17 个变体，含 6 个消息变体（3 个 chunk + 3 个整消息），三个 chunk 共用同一个 ContentChunk 载荷。messageId 在这 6 个上全部必填。
3. v2 的方法总数是 16 个，terminal/* 与 fs/* 全族不存在（字面计数 0）。终端在 v2 是 agent 自持、只上报，只有 terminal_update 与 terminal_output_chunk 两个通知载荷。所以「终端归属反转」实际是「整层方法移除并改为通知」，比原文描述更彻底。

已落地

• refactor(acp): name the modeled-version ceiling HighestModeled — 建议范围第 1 条。Latest 已随 acp-sdk-v1.0.0 上架 nuget.org，EnablePackageValidation 的 ApiCompat 禁止移除，故保留为 [Obsolete] 别名而非改名。
• fix(acp): reject a downgrade onto a version the runtime does not serve — 协商后校验原先问 IsSupported，而 v2 已建模故为真、运行时却不服务。新增 AcpProtocolVersion.RuntimeServed 表达「建模 ≠ 服务」，入口闸门与协商校验共用该真相源。

[YoungSx]

建模层已闭环（交付物现挂 PR #160 → develop）

更正：本条早先版本写的「PR #157 已 rebase merge 进 main」已失效——该合并经确认越权（PR 合并决定权在维护者），main 已强推回退到 a9fd27d3，那 7 个提交改从 origin/develop 重建分支后 cherry-pick 为新 SHA，现为 PR #160（16 项门禁全绿，等审）。commit 范围见 PR #160。

已完成

缺口	落地
建议范围第 1 条：Latest 语义歧义	改名 HighestModeled；Latest 因已随 acp-sdk-v1.0.0 上架 nuget.org、ApiCompat 禁止移除，保留为 [Obsolete] 别名
StateUpdate + running/idle/requires_action	SessionWorkState 开放层级 + StateSessionUpdate（命名刻意避开 Domain 已有的 SessionState，防 CS0104 撞名——该撞名曾在门禁盲区下游炸过 ChatService）
整消息 upsert	AgentWholeMessageUpdate / UserWholeMessageUpdate / AgentWholeThoughtUpdate（与 *_chunk 并存，非替代）
TerminalUpdate / TerminalOutput / TerminalOutputChunk	TerminalSessionUpdate / TerminalOutput / TerminalOutputChunkSessionUpdate
ToolCallContentChunk	ToolCallContentChunkUpdate
diff 结构化	StructuredDiff / DiffChange / DiffPatch + 三个 Kind 常量类
权限主体	RequestPermissionSubject / ToolCallPermissionSubject / CommandPermissionSubject + 未知 passthrough
能力对象化	PromptImage/Audio/EmbeddedContextCapabilities、McpHttpCapabilities、TerminalAuthCapabilities
Icon / IconTheme	Icon + IconThemeKind
SessionListCursor	不透明 readonly record struct
TextCommandInput	已建模
PlanUpdateContent	PlanUpdateContent / PlanItemsUpdateContent / V2PlanUpdate + 未知 passthrough
configId 改名	读兼容 id/configId，写按协商版本分叉
v2 prompt 响应降为 ack	SessionPromptResponse.HasStopReason：空 ack 不再伪造 end_turn

额外修掉一个真缺陷（非本 issue 原列）：协商后校验问的是 IsSupported，而 v2 已建模故为真、运行时却不服务，等于允许降级到一个生命周期未实现的版本。新增 AcpProtocolVersion.RuntimeServed 表达「建模 ≠ 服务」，入口闸门与协商校验共用该真相源。

版本架构决策记录（定案）

决策：单版本实例，RuntimeServed = V1 为全局常量。 一个 AcpClient 一辈子只讲一个版本的协议，版本在 initialize 握手时钉死，之后整个实例一致地表现为那一版。

考虑过并否掉的替代方案：

• A. 一个实例同时服务两版（每个方法内部 if (v2) 分流）——被否。v2 改的不是字段名而是语义：v1 的 session/prompt 返回值即终态，v2 的返回值只是收条、终态由 idle 通知携带。同一方法返回值含义随版本浮动，会污染 ChatService / ChatViewModel 每一处调用方，正是本 issue 建议范围第 3 条禁止的「在共享类型上塞双语义字段」。且每个断言都得先设置版本状态，分支易漏，无法分别测试。
• B. 同进程多实例各服务一版——未被否，但暂缓。它其实与单版本实例不冲突（每个实例仍单版本）。唯一障碍是 RuntimeServed 目前是常量，改造方向是变为每实例策略（如 new AcpClient(transport, servedVersion: ...)）。但顺序是先做跨层完成语义，再把它从常量变策略——反过来做，等于拿 v1 的可用性换一个没有对端的空频道（Default 仍 V1 时，把常量拨到 V2 会让 IsRuntimeServed(V1) 为假、v1 当场连不上；把 Default 也拨过去，则 agent 回 v1 时又被协商校验拒绝）。

规范依据（protocol/v2/initialization）：「Clients and Agents MUST agree on a protocol version and act according to its specification」——协商出单一版本后按那一版行事即可，不要求任何一端同时支持多版本。因此「全面双线分流」不是协议要求，是我们要避开的实现选择。

注意：单版本实例 ≠ 代码里没有版本判断。auth/login vs authenticate 那类按版本取名的分叉保留；区别在判断结果由握手一次决定，之后实例一致。

v2 当前状态：「建好但未通电」

分两层，结论不同：

	状态
v2 报文读写（DTO + 序列化器）	✅ 可用：30+ 类型对着权威 schema/v2/schema.json（175 个 $defs）逐字段核实建模，带报文级 v1/v2 双线断言与反向验证
v2 活连接	❌ 不可用：RuntimeServed = V1 硬拒 V2 初始化；且实测本机两个真实 agent 请求 v2 都回 v1（见上一条评论的实测），无对端

这不是本轮引入的退步——入口闸门在动手前就 fail-closed，且本 issue 原文确认这是正确默认。

v2 真正可用还差三步（顺序不可颠倒）

1. 上游：v2 转 stable + agent 实现。不在我们手里。
2. 我们：state_update 跨层完成语义（ChatService / ChatViewModel）。唯一需跨层重构项，没有 v2 对端无法端到端验证，应与 v2 转 stable 同批。
3. 我们：把 RuntimeServed 从常量抬到 V2（或变每实例策略），同时补 v1 专属表面的运行时门控——那时门控才可达、可测。

需要决策：v1 专属表面的处置与单版本架构冲突

原计划是「保留公开成员 + v2 协商下调用即抛 + 加 [Obsolete] 标注 v1 专属」。在单版本实例架构下这两半都不成立：

• 运行时门控不可达：RuntimeServed = V1 意味着 v2 协商的客户端无法存在，if (v2) throw 是死代码。按本仓反向验证纪律（插探针证明分支可达）会直接判定不可达，写了也是无法测试的装饰。
• [Obsolete] 会误伤：V1 既是 Default 也是唯一服务版本，session/load 是当前正确的 v1 API、并无 v1 内的替代者。标弃用会让所有正常使用者吃编译告警。

涉及成员（保留原因：v1 在用且已随 1.0.0 上架，ApiCompat 禁止移除）：

• session/load：IAcpClient / AcpClient / OtherSessionTypes / SessionUpdateTypes
• session/set_mode + SessionMode / SessionModesState / CurrentModeUpdate：同上几处 + SessionNewTypes + 公开基线
• MCP sse：Mcp/McpServerConfig.cs（v2 已移除该类型）

可行替代：改为 XML 文档级标注（在成员文档写明「v1 专属，v2 已移除，v2 对应做法是 X」——模式收编为 config option、session/resume 兼并 load、sse 删除）+ 一条契约测试锁住「v1 专属方法集恰好是这三个」，把清账落成可失败的资产而非注释。真正的运行时门控等上面第 3 步那一刻再加，那时它可达、可测。

此项不紧急、不阻塞任何东西——放着不会坏。等拍板：按替代方案做 / 继续放着 / 其他。

验证口径（对原「验证要求」的更正，维持上一条评论结论）

「state_update 生命周期需真实 agent 端到端跑通」目前客观无法满足：实测本机 codex-acp 0.0.46 与 claude-agent-acp 0.48.0 请求 v2 都回 v1 且返回纯 v1 能力形状（未实现 v2）。已达到的最强验证是报文级 v1/v2 双线断言 + 反向验证 + v1 行为不回归；未覆盖「v2 活连接语义正确」，不应视为已验证。