feat: adapt to ZCode CLI 0.16.1 protocol (App 3.6.5)

[tizerluo]

摘要

ZCode App 3.6.5（CLI 0.16.1）对 app-server 协议做了破坏性变更，本 PR 完成 ACP bridge 适配并同步文档/能力清单。MCP server 与 agent-help 的 headless 路径不受影响（已实测）。

技术规格书（全部协议结论的真机实测记录 + Wave 2 复审勘误）：docs/upgrade-0.16.1-spec.md

核心变更

ACP bridge（packages/acp-bridge/zcode-acp-bridge）

• 0.16 新增 server→client 反向调用 session/requestRuntimePreferences：两个 scope（runtime-materialization / user-execution）均应答，这是 0.16 下桥接卡死的真正根因
• 双模协议探测：启动一次性探测 legacy vs v16（识别 -32600/invalid_union、含 invalid-message 占位 id 的拒绝帧），legacy 走原有路径，向后兼容保持
• session/subscribe 必传 deliveryKind:"desktop-continuous"
• 事件翻译层适配 0.16：session/event（type 在 params 顶层）的 turn.started / model.streaming(text_delta) / turn.completed(usage) / state.updated patch 投影；v4/telemetry/event、process/resourceSample 正确丢弃
• turn.failed 无条件判失败（0.16 载荷无 resultType，此前会被误报为 end_turn 假成功——复审 P0 修复）
• usage_update.size 用 subscribe 快照 projection.contextWindow 缓存兜底（0.16 的 turn.completed.usage 无 contextWindow）
• 0.16 已删方法（session/steer、session/rewind*、prompt/enhance*）的 -32601 映射为明确文案「ZCode 0.16 已移除该能力」
• v16 下 subscribe 失败直接报错（轮询降级仅限 legacy）

测试（tests/，149 → 170 用例）

• 4 个 ACP 相关文件按 0.16 重写；回归锚 4 文件（credentials/mcp_retry_lock/provider_error/projection_differ）零改动
• 覆盖：双模探测三分支、反向调用应答 schema、deliveryKind、出站信封无 jsonrpc 键真断言、tool.updated（含 0.16 result dict 形态）、reasoning_delta、turn.failed 真实载荷、-32601 降级

文档（README + SKILL + 规格书）

• 兼容性表加 0.16.1/App 3.6.5 行；rename 注（ACP 面方法名不变，bridge 内部翻译）；已删方法标注
• Linux 安装段（/opt/ZCode/app/resources/glm/zcode.cjs）+ Node.js ≥18 前置依赖
• TUI 限制更新：0.16.1 起 CLI 帮助列出 tui 命令，但独立终端实测仍报 Cannot find package '@zcode/tui'
• updateRuntimeModelConfig 实测存活但 schema 新要求 runtimeModel.revision

agent-help（packages/agent-help/zcode-agent-help）

• 补 0.16.1 新参数（--max-turns/--allowed-tools/--disallowed-tools/--settings 等）、9 个子命令、16 个 slash 命令

验证矩阵

项	结果
ruff（CI 同款调用）	✅ All checks passed
unittest	✅ 170/170
可执行位	✅ 100755 ×3
真机 E2E（Mac，App 3.6.5 / CLI 0.16.1）	✅ 30/30（ACP 全流程含流式/usage/reverse-call 应答、已删方法降级文案、MCP stdio、agent-help、apiKey 脱敏）
turn.failed 失败注入（伪 HOME + 假 key → provider 401）	✅ 返回 -32603「zcode turn failed: Provider authentication failed.」而非假成功
双 reviewer 自审	✅ 无遗留 P0/P1/P2

已知 P3 级 follow-up（不阻塞）

• 停滞检查的投影优化实测不命中（0.16 turn 期间无 status:idle patch，行为正确、注释名不副实）
• turn.failed 的 error 字段若为字符串形态缺 isinstance 守卫（0.16.1 实测恒为 dict）
• usage size 快照兜底分支缺一条专项单测
• 个别测试注释/文档行文 nit（详见复审记录）

兼容性声明

legacy（CLI 0.14.8 ~ 0.15.x）路径原样保留，双模探测自动切换；对旧版向后兼容不变。

[tizerluo]

复审闭环记录（commander 总结）

第一轮（swarm reviewer ×2 + 真机 E2E）：E2E 30/30 PASS；reviewer 发现 P0×1（turn.failed 无 resultType 被误报成功，已修并失败注入实测）、P1×2（事件翻译覆盖回退、降级宣称失实）、P2×8，均已修复闭环。

第二轮（zcode 狗食 review，GLM-5.2，plan 模式 + diff 附件）：发现 P1×3（跨 turn 陈旧投影/cancel 双发 stop/探测超时硬判 v16）、P2×5（规格书口径、兼容性表缺项、agent-help 方法表、轮询失败检测局限、docstring），均已修复——其中「陈旧投影」经读码核实在 0.16.1 不可达（防御性修复 + 测试钉死）。

第三轮（zcode 复审）：无 P0/P1/P2，仅 5 条 P3 nit（已记录，后续跟进）。

终态验证：CI 全绿（lint/exec-bit/py3.11/py3.13）；真机 ACP 冒烟通过（initialize→session/new→流式 chunk→end_turn，usage_update {used:15939, size:1000000}，size 快照兜底生效）。本地 unittest 178/178。

合并标准（无 P0/P1/P2 + CI 绿 + E2E 绿）已满足。

[tizerluo]

P3 nit 清尾（commit aa06769）

zcode 复审第二轮留下的 5 条 P3 + 复审遗留 2 条已全部修完：

• session/cancel 空闲路径 stop 后端报错的吞没分支补用例 X3（179 用例全绿）
• turn.failed 的 error 字段非 dict 形态加 isinstance 防御（reviewer-1 N1）
• _REMOVED_IN_016 与文档清单双处维护互指注释
• probe id 固定值标注「依赖全程单次探测」
• test_pm7 标注 monkeypatch 模块级 time.time 的脆弱性
• session/prompt 的字符串 / {"content"} 键别名在 README/SKILL 文档化
• 规格书 process/resourceSample 措辞勘误

CI 四项全绿（此前一次 Lint fail 为 GitHub Actions 拉取 checkout 的基础设施故障，重跑已恢复）。至此所有 review 渠道（swarm ×2、zcode 两轮、CI、真机 E2E）零遗留。