[tizerluo]

背景

业主更新官方 App 至 3.16.2（内嵌 CLI 0.17.0）——0.16.x 后第一个 minor 跳版。全链路活体探测结论：核心对话链路/删除面/信封/反向调用/headless CLI 与 0.16.9 逐项一致，三处破坏性变更，本 PR 修复并同步文档。

三处修复

① session/list 去 includeArchived：0.17.0 strict Zod 拒收该键（桥原无条件携带 → -32603，真机复现）。0.16.9（npm 3.15.3-37 vendor 实测）上 {} 与 {includeArchived:false/true} 逐项等价 → era 无关去键；客户端传 true 不再透传（archived 概念疑似已从 0.17 移除），取舍入 docstring。

② 模型 ID 大小写折叠：0.17.0 注册表身份改名 builtin:zai-coding-plan/GLM-5.3 → zai/glm-5.3（小写、精确大小写敏感），且显式选模型强制 options.reasoningLevel。桥 catalog 解析失败后按 casefold 第二轮匹配、命中用 catalog 规范 ID（调用方原始串绝不下发）——旧习惯 "GLM-5.3" 在 0.17.0 自动解析（真机 E2E 验证），0.16 后端精确轮先命中不受影响。不做 providerId 前缀映射魔法（无法从 catalog 泛化推导）。

③ generateText modelRef→selection 键映射：首发 selection 形态（0.17.0），-32602 且键级拒收特征时一次性重发 modelRef 形态（0.16 回退）；不双发（strict Zod 拒未知键）、不发明默认值。maxOutputTokens 之谜实证：服务端 selection 构建不再提供默认值（同号 0.16.9 构建已分叉——同号漂移再添实锤），可通组合 = 显式 maxOutputTokens ∈ [1024, catalog max] + reasoningLevel 取 defaultLevel。

文档四处

• docs/recheck-3.16.2.md（新，按 recheck-3.14.0 结构）：完整探测面 + 旗标面变化（新增 --attach/--force-mcs/--surface/--toolsearch-mode/--verbose/--workflow-mode）+ 新通知 + usage 新键 + 最小环境引导验证（feat: 最小 headless 环境引导自检 — bootstrap 结构化键 + gate 终态告警 + 文档口径 (#55) #57 原配方在 0.17.0 失效——符号链接入口被 runtime 解析到真实路径；两条实测可行替代已记录：入口真实文件+邻置 provider/、或桌面 App 同款显式 env 双变量）
• README.md：兼容表 0.17.0 行、模型面现状（新 ID/glm-5-turbo 回归）、setModel reasoningLevel 注记、bootstrap 节替代配方
• agent-help：version_described/tested_against → 0.17.0 (App 3.16.2)，旗标面与口径同步
• SKILL.md：版本表与方法表同步

验证

• pytest 606 passed + 58 subtests（基线 591+56，+15 测试）；ruff 0 告警
• 真机 E2E（桥 ↔ 官方 3.16.2）：session/new(model:"GLM-5.3") 折叠生效 ✓、session/list 恢复可用（50 会话在列、映射正确）✓
• 0.16.9 兼容回归：npm 3.15.3-37 vendor 真机实测（PATH 包装器已自动升级 3.16.2-38，故从 npm 复装旧版）

已知边界（非本 PR 范围）

• 最小 headless 环境 feat: 最小 headless 环境引导自检 — bootstrap 结构化键 + gate 终态告警 + 文档口径 (#55) #57 配方失效已文档化替代方案；如需桥侧自动探测可另开 issue
• --mode guarded 两代 help 在列但未实测（文档标勿盲用）
• prompt turn 真机最后一验因 API plan 切换在 provider 层失败（非桥缺陷，早间已全链路验证过流式）

[tizerluo]

R1 审查 + 精简轮记录 (7f3ea19)

R1: 0×P0 + 0×P1 + 7×P2 + 8×P3 → 全修

P2 要点：

• 重试判定收紧为键名精确正则（Unrecognized key 后紧跟 selection/modelRef 才触发）——嵌套键拒收（如 selection: Unrecognized key: "variant"）不再误触发重试把真错误掩盖成第二个错误；M7k 9 子测试直钉判定函数
• casefold 折叠歧义显式报错（列出全部 providerId/modelId 命中对 + 建议对象形态）——静默绑定任意 provider 危险
• 漂移证据链修正：/expert 与 --mode guarded 不是漂移证据（官方 0.16.9 记录里已存在/两代 help 均列）；「App 3.15.3」实为 zcode-app-cli 包装器版本（全仓误标清零）；结论降级为「vendor 0.16.9 与官方 0.16.9 的 generateText 参数面不同（官方未做参数级复测）」
• 「0.16.5 仍收 modelRef」如实标推断（本仓只有空 params 存活性记录，无参数级证据）
• P2-7 由主代理真机探测解决：toolAllowlist/toolDenylist 在 0.17 上字符串数组全通（含 * 通配）、对象条目被拒——桥 feat(acp-bridge): session/new 透传 toolAllowlist/toolDenylist #53 本地校验本就 fail-closed 只发字符串数组，双代兼容零代码改动，探测结果补记 recheck

四处仲裁：maxOutputTokens 维持显式失败+指引（注入默认会静默截断，fail-loud）；includeArchived 只 log 不加回退（垂死能力）；generateText 返回键只提醒不做 alias（alias 掩盖后端变化）；折叠措辞改「0.16 既有大写调用方行为不变；新增小写解析」。

simplifier（-13 行 + 3 口径修正）：折叠轮单趟合并、日志压 2 行、测试措辞同步、recheck 测试数字实测核实（608+67）。

验证：608 passed + 67 subtests（基线 591+56）；ruff 0 告警。