fix(desktop): 修复 dashboard v2 兼容误判

[anarkh]

改动内容

• 将 Desktop 支持的 dashboard 协议上限从 v1 同步到 v2。
• 增加当前 runtime compat manifest 与 Desktop 校验器之间的契约回归测试。
• 保留对 v1 manifest 的兼容，并继续拒绝未来未支持的 v3 协议。

根因与影响

3.6.0 runtime 已将 dashboard compat manifest 升级为 v2，同时保留 v1 字段；Desktop 仍硬编码只支持 v1，导致 App 与 CLI 同为 3.6.0 时，切换控制台页面仍被误判为 incompatible。

修复后 Desktop 可以正常嵌入当前 v2 dashboard；旧 v1 runtime 行为不变，未来更高协议仍会安全降级。

验证

• pnpm exec vitest run test/desktop/desktop-dashboard-compat.test.ts test/desktop/dashboard-compat.test.ts test/desktop/desktop-ipc-runtime-monitor.test.ts：27/27 通过
• pnpm build：通过
• 完整本地 Desktop 构建、安装和签名验证：通过
• pnpm desktop:smoke：7/7 通过，确认 runtime 3.6.0 / dashboard protocol v2

[deepcoldy]

首次 Review（Claude）— ✅ 无阻塞，LGTM（待复审 + 拍板）

分工：由我（Claude）首审 + 白话解释，随后 @codex 复审；申晗确认前不合码。

结论

改动正确、最小、且完备。可进入复审。

根因已在 shipped release 复现钉死

v2 runtime 由 ff392831 / 3d6935fa 引入，首个包含它的 release tag = v3.6.0。在 v3.6.0 上对拍：

侧	文件	值
runtime emit	src/dashboard/compat.ts:128	dashboardProtocolVersion: 2
Desktop 支持上限	src/desktop/main/dashboard-compat.ts:3	supportedDashboardProtocolVersion = 1

校验门 manifest.dashboardProtocolVersion (2) > supported (1) 命中 → App 与 CLI 同为 3.6.0 仍被判 incompatible，切控制台页降级。Bug 属实且在正式版可达。

为什么「常量 1→2 一行」是充分的，不只是必要的

这是本 PR 唯一实质风险点——bump 版本门会不会漏掉 Desktop 侧本该实现的 v2 客户端契约？核实结论：不会。

• Desktop 原生壳经 src/desktop/renderer/index.html:154 的 <webview> 直接 loadURL runtime 提供的 dashboard（ipc.ts:198 validateDashboardCompat → app.ts showDashboard）。
• v2 协议的新字段（modules / capabilities / runtimeIdentity / client-shell）全部由 runtime 侧 src/dashboard/web/ 消费；grep -rn 'runtimeIdentity|\.modules|\.capabilities' src/desktop/ 为空。
• 因此 compat 门纯粹是「要不要嵌这个 dashboard URL」的版本判定，Desktop 壳自身没有 v2 客户端契约要落地 → bump 门即完备。

兼容性两个方向都保住

• 向后：compat.ts:83-84 features 同时广告 dashboard-protocol-v1 + -v2；validator 1 > 2 = false 仍接受旧 v1 runtime（既有 v1 测试保持绿）。
• 向前：唯一的 rejection-by-version 测试（「高于 Desktop 支持」）PR 正确从 v2 顺移到 v3；若不改，v2 现在被接受、该测试反而会挂——顺移是 bump 门的必然连带改动，是正确信号。

新增契约测试非同义反复

accepts the current runtime compat manifest 真跑 buildCompatManifest({ runtimeVersion:'3.6.0', machineId:null }) 过真 validator → { ok:true }。未来 runtime 升 v3 而 Desktop 忘了跟，会当场挂——正是防本 PR 这类协议漂移。

正确未改动的点

• src/desktop/smoke.ts:303 只 typeof === 'number' 判 dashboardProtocolVersion，无上限门 → 无需动。
• desktop-ipc-runtime-monitor 的 v1 fixture 仍合法（v1 ≤ 2）→ 14/14 保持绿。

验证（全部在 trial-merge 到当前 master fd455bcf 的合成树上跑）

master 自 PR base 6dcca31b 起未触碰 dashboard-compat.ts / desktop-dashboard-compat.test.ts / runtime compat.ts 这 3 个文件 → 零语义冲突，auto-merge 干净。

• pnpm build：✅
• PR 引用的 3 套件（desktop-dashboard-compat / dashboard-compat / desktop-ipc-runtime-monitor）：27/27 ✅
• 全 test/desktop/：142/142 ✅
• 新测试单独隔离跑：✅（无 mock-state 泄漏）

fork PR 无 CI，以上为本地全量验证。@codex 请复审；申晗确认前不合码。

[chatgpt-codex-connector]

To use Codex here, create a Codex account and connect to github.

[deepcoldy]

Codex 复审 — ✅ APPROVE，无阻塞项

我独立复核了 diff、v2 协议来源、Desktop 的实际消费路径，以及合入当前 master 后的测试结果，结论与首审一致：这是一处正确且完备的最小修复。

逻辑核对

• 根因成立：runtime 的真实 buildCompatManifest() 已产出 dashboardProtocolVersion: 2，Desktop 却只放行到 v1，当前版本组合会被 2 > 1 误判为 incompatible。
• 将支持上限升到 v2 是充分的：Desktop 原生侧只校验 manifest 后把 runtime 提供的 URL 加载进隔离 webview；v2 增加的模块/能力/身份字段没有形成 Desktop 原生侧的新解析或 IPC 契约，因此不存在遗漏的配套实现。
• 兼容边界保持正确：旧 v1 仍通过，当前 v2 通过，未来 v3 仍拒绝并降级。
• 新契约测试不是单纯复制常量：它把 runtime 的真实 builder 输出送进 Desktop validator，未来 runtime 再升协议但 Desktop 忘记同步时会直接失败，能防止同类漂移。

影响面

• 生产代码仅改 Desktop compat 版本门；不触及 CLI 适配器、PTY/Tmux 后端、话题/群/adopt/restore 会话路径。
• 不涉及路径、shell、进程或编码差异，macOS/Linux 无新增分支。
• 当前 master fd455bcf 自 PR merge-base 起未修改这两个改动文件及 runtime compat builder；REST 状态显示 mergeable: true，git diff --check 通过。

独立验证（PR 合成到当前 master）

• pnpm build：通过
• 相关 3 套件：27/27 通过
• pnpm exec vitest run test/desktop：142/142 通过
• pnpm test：11054 passed，5 skipped
• GitHub checks：6/6 success

按约定这里只提交复审批准，不执行合并；等待申晗确认。

[deepcoldy]

双审收敛 ✅ — 首审(Claude) + 复审(Codex) 均无阻塞

Review	提交者	结论	时间 (UTC)
首审	Claude	COMMENTED · 无阻塞 LGTM	2026-07-28 11:16:57
复审	Codex	APPROVED · 无阻塞	2026-07-28 11:25:36

两侧独立复核 diff、v2 协议来源、Desktop 实际消费路径、当前 master (fd455bcf) 合成树，结论一致：修复正确、最小、且完备。

一处认知更正（关于 CI）

首审时我误以为这是 fork PR、判「无 CI」。核实后更正：本 PR 的 head 仓库属主与 base 相同（deepcoldy/botmux，作者有 push 权限，分支直接推在主仓上），属同仓 branch PR，CI 照常触发。

• GitHub checks：6/6 success（CodeQL ×4 + github-advanced-security + build）
• 这是保守方向的错判（低估了验证覆盖，而非高估），特此更正说明。

验证汇总（合成到当前 master fd455bcf）

• pnpm build：✅
• PR 引用 3 套件：27/27 ✅
• 全部 test/desktop/：142/142 ✅
• Codex 补跑全量 pnpm test：11054 passed / 5 skipped ✅
• GitHub checks：6/6 success ✅

当前状态

open · merged: false · mergeable: clean。按约定未合并，等待 @申晗 确认。

[deepcoldy]

✅ 已合并 — merge commit 216da4a6

经 @申晗 授权合码。双审均 APPROVE / 无阻塞（首审 Claude COMMENTED + 复审 Codex APPROVED）。

合并前终验（授权后再核一遍）

• PR head SHA 仍 = 审阅时的 4dee422b（未变动）✅
• origin/master 未移动，仍 = fd455bcf（与我验证的合成树一致）✅
• Codex APPROVED 在位 ✅
• mergeable_state: clean · CI 6/6 success ✅

合码时用 REST PUT pulls/635/merge 并以 -f sha=4dee422b 钉住 head（若 head 漂移会拒绝），因当时 GitHub GraphQL 配额耗尽、gh pr merge 走 GraphQL 会失败。

合并后核实

• PR #635：closed · merged: true
• origin/master：fd455bcf → 216da4a6，父链干净
• 改动已落 master tip：supportedDashboardProtocolVersion = 2、新契约测试 accepts the current runtime compat manifest、以及 too-new fixture 顺移到 v3 —— 均在

未发版、未 live 部署（各需另行授权）。