# 关键踩坑记录（勿重蹈）

> 本项目开发过程中踩过的坑，按“现象 → 原因 → 正确做法”整理。新坑持续补充。

## 配置与 dsh 集成

1. **settings 命名空间白名单**
   - dsh api-proxy 的 `settings.describe` 只返回硬编码 `WEB_SETTINGS_NAMESPACES` + model providers + product 名单。
   - 第三方插件命名空间 RPC 永远看不到（官方注释 "deferred work"）。
   - 正确做法：第三方配置 UI 一律走插件自有 HTTP 路由。

2. **route 唯一性**
   - `ctx.webServer.register` 的 exact route 同 path 不能注册两次。
   - 正确做法：GET/POST 合并进一个 handler，按 method 分发。

3. **client 插件机制**
   - patch 行 name 用包名。
   - client row 由 modules node half 扫描 `dsh.client` 自动编入 `__DSH_BOOT__`，无需特殊 client 行。

4. **client 使用 `ctx.workspaces` 必须注入 `workspaces`**
   - `inject` 只写 `slots` 时 `ctx.workspaces` 为 undefined，托盘“新建任务”会静默失败。
   - 正确做法：`inject: ['slots', ..., 'workspaces', 'sessions']`。

5. **事件类型合并**
   - `session/event` / `agent/created` 等 Events 由 `@deepseek-ai/dsh-session` / `@deepseek-ai/dsh-agent` 声明合并。
   - 使用方需显式 `import type {} from` 这两个包。

6. **顶层会话 delegationDepth 是 undefined**
   - dsh 顶层会话 `delegationDepth` 为 absent（undefined），不是 0。
   - 判断顶层会话时不要写 `!== 0`，应写 `(session.header?.delegationDepth ?? 0) !== 0`。

## 窗口与 WebView2

7. **窗口退化 bug**
   - 状态记忆必须校验最小尺寸/坐标，防 boot 期 0 尺寸持久化。
   - `??` 不会跳过 0，要显式判断。

8. **webviewjs 无关闭拦截**（WebView2 时代，已过时）
   - `window-close-requested` 只是通知，没有 preventDefault。
   - 关闭到托盘用“不 exit + 隐藏保活窗口重建”方案。

9. **最小化到托盘恢复闪烁**
   - hide 前先 `setMinimized(false)` 清标志，showWindow 前同样清理。

10. **splash 期间主题探测**
    - splash 页无主题标记，探测必须三态（`na` / `-1`），否则标题栏启动时闪浅色。

11. **主动退出必须写 quit.marker + `process.exit(0)`**（WebView2 时代，已过时）
    - webviewjs 的 `app.exit()` 在 Windows 可能以 `0xC0000005` 崩溃。
    - launcher 会把非 0 退出误判为异常并自动重启；主动退出走 `quit.marker`。
    - 当前（dev-v2）：退出语义归 Rust 壳 `src-tauri/src/helpers/quit.rs`（写 `quit.marker` + `process::exit(0)`，supervisor 区分主动退出/崩溃重启）；webviewjs `app.exit()` 与 npm launcher 机制均已删除。

## 主题与系统调用

12. **PowerShell 慢**
    - 冷启动约 1.3s/次，常驻 stdin pipeline 每行约 1s。
    - 标题栏 Dwm 调用必须用 FFI（koffi，~1ms），PowerShell 仅兜底。

13. **`explorer.exe` 不要加 `windowsHide: true`**
    - 会导致 Explorer 窗口隐藏启动，“打开工作区”看起来无反应。
    - 需要前置时用后台 PowerShell 按窗口标题查找并 `AppActivate` + 短暂 TOPMOST。

14. **evaluateScriptWithCallback 返回值带引号**
    - 字符串结果被带引号序列化（`'dark'` → `"dark"`），`.trim()` 无法匹配。
    - 探测一律用数字（1/0/-1）避免歧义。

15. **托盘桥返回值用数字**
    - 字符串返回值同样带引号，host 判断永远失败并重复派发。
    - `dispatchScript` 成功/未就绪返回 `1/0`。

## 右侧栏 / 前端

16. **shell.overlay 方案不可用**
    - 官方 overlay 层在 AppFrame 内部，fixed 子元素定位/裁剪行为异常，侧边栏会跑到左侧。
    - 正确做法：参考 DSH-better-sidebar，用 **body portal** 挂载右侧栏。

17. **新对话无法展开**
    - 官方 details 列对 blank session 强制 width 0（`detailsSession` 仅在 `blank === false` 时传入）。
    - 不要依赖 details slot 承载主侧边栏；用 body portal 自管宽度。

18. **body portal 需要 react-dom**
    - tsdown 配置已 externalize `react-dom/client`，但构建需要本地安装 `react-dom` 与 `@types/react-dom`。
    - 运行时由 dsh 平台模块表提供。

19. **npm install 会清掉 SDK junction**
    - `build-client` 建立的 `@deepseek-ai/dsh-*` junction 会被 `npm install` 移除。
    - 装完依赖后必须重新运行 `npm run build:client`。

20. **postinstall 可能改动 bin/launcher.vbs**（WebView2 时代，已过时）
    - `npm install` 后 `git status` 常出现 `bin/launcher.vbs` 被修改。
    - 提交前确认是否为无关改动；不需要时 `git checkout -- bin/launcher.vbs`。

## 构建 / 发布 / 合并

21. **合并 PR 时生成文件冲突**
    - `lib/client.js.map`、`package-lock.json` 等生成文件极易冲突。
    - 正确做法：保留源码合并结果后，重新 `npm install` + `npm run build` + `npm run build:client` 再提交。

22. **默认 npm registry 可能是华为云镜像**
    - `npm view` / `npm install` 默认走 `https://repo.huaweicloud.com/repository/npm/`，新版本可能未同步。
    - 发布和验证请显式使用 `--registry=https://registry.npmjs.org/`。

23. **发布候选版用 `--tag rc`**
    - 直接 `npm publish` 会覆盖/影响 `latest`。
    - 候选版应 `npm publish --tag rc`，用户安装用 `npm install @marecgents/dsh-hub@rc`。

## 多实例 / 会话数据

24. **多个 dsh 实例并存会损坏会话数据（已实际发生）**
    - 现象：同一会话在两个 dsh 实例（不同端口）中同时打开 → 该会话读取报 corrupt、GUI 不可用。
    - 根因：两个实例共享同一 `$DSH_HOME/sessions` 存储；在同一个 turn 处交错 append 时产生两组相同 seq 的冲突事件（一组「interrupted 死分支」+ 一组「真实活分支」），`SessionLogScanner` 检测到 seq 回退 → 判定会话损坏。
    - 修复（2026-08-16）：帧级字节拼接剔除死分支 4 行（checksum 无需重算），保留活分支后续 2 万+ 事件；备份 `.corrupt.bak` 可回滚。详见 `docs/会话损坏修复记录-2026-08-16-1023.md`（已归档外部档案仓库 `../docs/archived/会话损坏修复记录-2026-08-16-1023.md`，未随仓库分发）。
    - **复发（2026-08-21）**：`session-7dbdbc85`（dsh-hub开发会话）再次因双实例双写损坏（seq 653843 回退，死分支帧 29329/29330），同法修复（剔除死分支 4 行，保留活分支后续 6 万+ 事件）。详见 `../docs/archived/会话损坏修复记录-2026-08-21-2322.md`（已归档外部档案仓库，未随仓库分发）。
    - 预防：
      - dsh-hub 启动时检测已有 dsh 实例（任意端口），默认**拒绝**共存（设置 → DSH HUB 设置 → 「允许同时运行多个实例」未勾选时直接拦截）。
      - 确需共存须勾选该选项，并确认严重警告（共享 `$DSH_HOME`、同会话双写会损坏日志）。
      - 任何情况下都不要在两个实例中同时操作同一个会话。

## 设置保存 / 皮肤

25. **设置保存回环不可信任服务端响应（勾选"保存后又被取消"）**
    - 现象：设置卡片勾选 → 保存 → 勾选被取消（或重开卡片发现没保存）。
    - 根因（两类）：
      - a) 运行中的 dsh 实例内存里是**旧代码**（Node 启动时加载 lib/，之后改的 src/lib 不生效）——旧 host 的 POST 白名单没有新字段 → 响应缺字段 → 客户端 `setDraft(saved)` 静默回退。本机实测：实例 10:43 启动，早于皮肤/声音/新白名单，重启即恢复。
      - b) 双实例并存时，旧 host 的 `writeShellConfig` 用**旧 DEFAULT 合并回写**，会抹掉新 host 写入的新字段（skin/soundEnabled）→ 皮肤选择/勾选被"取消"。
    - 正确做法：
      - 客户端保存成功路径 `setDraft({ ...saved, ...patch })` **回放提交的 patch**——勾选永不静默回退；`config` 保持服务端真相，真丢字段时显示"未保存"而非消失（dsh-hub 已修复）。
      - 测试新构建前先**重启**实例（会话持久化在 `$DSH_HOME/sessions`，重启不丢）；不要在旧实例上判断新功能行为。
      - 新增配置字段必须三处一致（ShellConfig 接口 / DEFAULT_SHELL_CONFIG / POST 白名单），漏白名单 = 本坑重现。

26. **皮肤只覆盖 alias 背景会导致左右侧边栏不跟随（浅色停留官方白）**
    - 现象：浅色模式下应用皮肤，只有中栏背景变了，左导航/右侧栏还是官方白。
    - 根因：dsh 左导航背景用 `--dsw-specific-sidebar-fill`（specific token），卡片徽章用 `--dsw-alias-bg-module-platform`，浮层用 `--dsw-specific-menu`——都不在皮肤原本只覆盖的 alias bg 集合里。
    - 正确做法：皮肤必须同时覆盖 alias 全量 + specific 组（sidebar-fill / sidebar-nav-item-active-accent / sidebar-nav-item-active / sidebar-nav-item-hover / menu）+ bg-module-platform，且 `skins.ts` 的 `buildCss` 按 `specific` 字段输出 `--dsw-specific-` 前缀（alias 与 specific 放错位置 = 前缀错误 = 覆盖无效）。详见 `docs/skins/AGENTS.md`。

## 进程身份 / 音源

27. **Windows 进程身份 = exe 内嵌资源（不是运行时改名）**（WebView2 时代，已过时）
    - 现象：任务管理器把 dsh-hub 显示为 "Node.js JavaScript Runtime" + node 图标。
    - 根因：进程显示名来自 exe 的 VERSIONINFO（ProductName/FileDescription）+ 内嵌图标 + 文件名；dsh 运行时就是 node.exe，资源是微软的。
    - 正确做法（dsh-hub 已实现）：`bin/hub-exe.mjs` 复制当前 node.exe → `dsh-hub.exe` / `dsh-hub-guard.exe`，用 `@electron/rcedit` 替换图标与版本信息（ProductName=DeepSeek Harness Hub / Launcher），缓存 `$DSH_HOME/dsh-hub/bin/` + stamp（node 升级自动重建）；launcher re-exec 为 guard、spawn 应用用 patched exe。**补丁 exe 不可提交进 git**（跨机器/node 版本会失效）；生成失败回退 cmd shim。
    - 教训：别想用运行时 API 改名进程——任务管理器读的是 PE 资源。
    - 当前（dev-v2）：`hub-exe.mjs` / rcedit / cmd shim 已随 launcher 家族删除；Tauri 原生 exe 自带图标/版本信息（任务管理器显示 DeepSeek Harness Hub）。

28. **提示音素材不要原封复用他人项目的文件**
    - 现象：曾把 DeepSeek-Reasonix 的 4 个 mixkit WAV 复制进 assets/sounds（用户要求改为自有资源）。
    - 正确做法：原创合成（`scripts/synthesize-sounds.mjs`，44.1kHz/16bit WAV，正弦+谐波+指数衰减包络）——零版权、体积 ~30-80KB、播放链路不变（winmm PlaySoundW 只认 WAV）。可脚本化下载的免费库（Pixabay/Mixkit）只提供 MP3，无 API key 拿不到 freesound 的 WAV，故合成是 WAV 原生播放的最优解。

## 前端 DOM 增强（置顶会话）

29. **ui-workspace 的 CSS-module hash 不可作为插件定位锚点**
    - 现象/风险：`ui-workspace` 的行/标题/操作区类名是构建期 hash（`.YDXeBa_*`），dsh 升级重编译即变——把功能定位写死在 hash 上 = 升级即失效（PR #4 原实现即如此）。
    - 正确做法（dsh-hub 已实现）：定位只用 **framework 稳定契约**——`div[data-slot="sidebar.workspaces"]`（slot 渲染器固定输出，web-react/scoped-slots）、`role="tree"`、`div[role="treeitem"]`（排除 `[aria-expanded]` 分组行、`:not(button)` 搜索行）；**行→会话映射用内容匹配**（行内文本 == displayTitle，同名整组跳过，读错=跳过不误标），插入位置 = 匹配到的标题元素之后。
    - 单点豁免（仅 2 处，dsh 升级回归清单必查）：① 自绘 pin 图标（官方 `Icon*Outline16` 无 pin，见根 AGENTS §3 豁免条款，官方提供后切换）；② 无（标题提取已用内容匹配替代，零 hash）。
    - 数据正确性纪律：pins 写路径必须等 `phase==='ready'` 基线落地（空 byId 时收缩会清空 pins.json，真实事故风险）；boot 结果与用户交互增量合并（dirtyDelta），剪枝连续 2 次 ready 快照缺失才删；disposer 必须移除注入 DOM（HMR 重装防僵尸闭包写）。

30. **官方组件内联 token 不被皮肤覆盖（升级检查项，勿用 body.style 竞争）**
    - 现象/风险：部分官方表面**直接硬编码颜色**而不走 `--dsw-*` token——例如 ui-primitives Tooltip 文字固定 `bluish-00` 白、部分按钮变体。皮肤注入的 `<style>` 只对走 token 的表面生效；`body.style.setProperty` 竞争注入顺序/特异性不可控（预留设计，见修复方案 D1）。
    - 真实事故：terminal/aurora 深色曾把 `tooltip-bg`/`toast-bg` 设计为"反色浮层"（`#a9f0a9` / `#e2dcff` 亮底），但官方 tooltip 文字固定白 → 白字浅底不可读；2026-08-16 修复为深底（`#0e1c10` / `#151331`）。
    - 正确做法：皮肤升级回归清单——① 深色模式逐表面检查 tooltip/按钮/气泡文字可读；② 新增官方 token 时补进 5 套皮肤浅/深两套（`docs/skins/AGENTS.md` 覆盖纪律表，含 `bubble`/`bubble-highlight`）；③ 浮层 token 一律"深底浅字"，勿再引入反色浮层。

31. **置顶会话升级冒烟清单（锚点契约漂移）**
    - 现象/风险：置顶功能定位依赖 framework 稳定契约（`data-slot="sidebar.workspaces"`、`role="tree"`、`div[role="treeitem"]:not([aria-expanded])`）+ 内容匹配（行内文本 == displayTitle）+ 几何镜像（`--dsh-session-list-*` var）。dsh 升级若改变列表 DOM 结构/标题元素/搜索行形态/分组与扁平布局切换，置顶会静默失效或误标。
    - 正确做法：每次 dsh 升级后跑置顶冒烟清单——① 分组/扁平模式行 pin 按钮出现、置顶/取消生效；② 搜索有结果/清空/空结果三种状态置顶区不闪现、不注入搜索行；③ 会话折叠/展开后行状态保持；④ 同名会话多开整组跳过（不误标）；⑤ 重启 pins 保留、多标签同步（storage 事件）；⑥ 置顶区与行对齐（edge-inset/scrollbar var 回退值生效）。详见 `../docs/archived/深度审查报告-2026-08-16-1603.md`（已归档外部档案仓库，未随仓库分发）D 组。

32. **背景图必须注入应用 frame 层，且锚点不可用 CSS-module hash**
    - 现象/风险：PR #6 首版把背景图注入 `body{background-image}`——dsh 的 AppFrame（`.frame{background:var(--dsw-alias-bg-base)}`）以不透明 token 背景全屏覆盖 body，图片**完全不可见**（三轮审查实证：注入红色样张，frame 区域像素无红色）。若再图省事用 frame 的 hash 类名定位（`.pI_x6G_frame`），dsh 升级重编译即失效（同 #29）。
    - 教训 1（渲染层级）：**新增背景/覆盖层必须先验证目标层的绘制顺序**——`body` 背景在 AppFrame 之下；负 z-index 伪元素按 CSS2.1 Appendix E 绘制序（step2）确定性垫在 frame（positioned, step6）之下，同样不可见。
    - 教训 2（结构锚点）：frame 是 `#root` 下唯一带内联 `grid-template-columns` 的元素——**`#root div[style*="grid-template-columns"]` 是唯一稳定非 hash 锚点**（`#root > div` 是 slot 出口 `display:contents` 无盒，不可用；frame 无稳定 data-*）。升级冒烟项：该选择器必须仍唯一命中 frame。
    - 教训 3（第二层覆盖，2026-08-16 真机复现）：**frame 背景命中 ≠ 可见**——frame 的三个栏子元素（sidebarCol 280px + centerCol 内容根 1000×720 白底等）盖满全窗，把 frame 背景图**完全遮死**（用户真机：选图"闪烁一下没变化"；像素实测 frame 注入红色后中栏仍全白）。必须**透明化中栏内容根**才可见：`[data-slot="conversation"] > div`（官方 slot 契约锚点，非 hash）→ `background-color:transparent`。侧栏保持皮肤 fill 不动。升级冒烟项：`[data-slot="conversation"]` 直接子 div 必须仍唯一命中中栏内容根。
    - 正确做法（dsh-hub 已实现）：`backgrounds.ts applyBackground` 注入规则——① `#root div[style*="grid-template-columns"]{background-image:linear-gradient(rgba(0,0,0,.25),...),url(...)!important;...}` 双层背景（蒙层 + 图片都在 frame 自身背景层，零层叠上下文风险；`background-color` 保留 token fallback）；② 左/中/右三栏表面 `color-mix(原 token 75%, transparent)`（背景图透出 ~25%，用户要求 20-30%；左栏 = sidebarCol 设 transparent + `[data-slot="sidebar"] > div` 75% fill，中栏 `[data-slot="conversation"] > div` 75% bg-base，右栏 `[data-slot="details"] > div` 75% bg-base）；③ 自研右侧栏（body portal）把图画在自身上（多层背景 `[fill 75% 渐变] + [黑蒙] + [url]`，内部 `[class*="mg-rs-"]` 透明，见教训 5）。`'none'` 清空注入（全部移除）。静态资源走 `/api/dsh-hub/backgrounds/*`（backgrounds-api.ts，正则白名单防路径穿越，`decodeURIComponent` 包 try/catch 保证畸形 % 编码返回 404 而非 400）。
    - 教训 4（双层叠加，2026-08-16）：给"容器 + 内容根"**同时**设半透明会叠乘——0.75²=0.9375，背景图只剩 ~6%（用户实测左右栏"几乎没变化"）。半透明只能加在**单层**：容器（sidebarCol/detailsCol）要么设 `transparent`（露出下层）要么不设，75% 只给内容根一层。
    - 教训 5（fixed portal 半透明合成，2026-08-16 真机复现）：**body portal 的 fixed 面板，半透明背景（color-mix / opacity / backdrop-filter）都不会透出背后的内容**——WebView2/Chromium 合成器对 fixed 合成层不采样背后（像素实测：右栏无论 color-mix 75% 还是 opacity 0.75 都呈纯 fill 色；backdrop-filter 更直接导致面板内容消失变纯色块）。自研右侧栏（body portal）只能**把背景图画在面板自身上**：`background-image: [fill 75% 渐变层] + [黑蒙 25%] + [url 图]`（多层背景，`background-attachment: fixed` 与 frame 对齐），并把面板内部 `[class*="mg-rs-"]` 背景透明化避免叠层——像素实测 25% 透出与理论值一致（RGB(222,171,186) ≈ 75% fill + 25% 蒙层图）。教训：**body portal 元素只能在"加载插件的真实实例"验证**（CLI 实例无插件、无右侧栏）；任何半透明/毛玻璃方案先像素验证。
    - 教训 6（fixed 合成层是根因，与 DOM 位置无关，2026-08-16 真机复现）：曾评估"把右侧栏注册进官方树（detailsCol/grid 第 3 列）以复用官方流内混合行为"——实验证伪：**在 `#root` 内注入 position:fixed 探针 + color-mix 75%，同样不透出背后**（像素 RGB(232,228,247) 纯 fill）。即 **`position:fixed` 本身触发合成层、半透明背景不采样背后，与元素挂 body 还是 #root 无关**；唯一能透出的是**非定位流内元素**（中栏内容根 static ✓）。而"流内右栏"= 占用官方 detailsCol/grid 第 3 列 = 与官方 details 冲突 + 修改官方内联 grid-template-columns = 侵入官方布局（违反 stable anchors 纪律）。**结论：右栏浮层无法通过"注册进官方树"获得透出能力，自绘画图（教训 5）是唯一可靠路径**；官方树注入方案永久归档为不可行。

33. **全新环境 `npm i -g` 后「连续异常退出」（ERR_MODULE_NOT_FOUND）**（WebView2 时代，已过时）
    - 现象（2026-08-16 测试电脑真机）：全新机器装好 Node + `npm i -g @marecgents/dsh-hub` 后，点桌面快捷方式弹「dsh-hub 连续异常退出，请看 dsh.log」；日志显示 `Cannot find package '@marecgents/dsh-hub' imported from C:\Users\...\.dsh\profiles\web\`（ERR_MODULE_NOT_FOUND），崩溃 3 次后放弃。
    - 原因：launcher 的 `ensureBundleInstalled` 在 profile 未注册 scoped 名时走 **bare-name 兜底**——junction 建 `node_modules/dsh-hub` + bundles 追加 `dsh-hub`；但 `cordis.patch.yml` 的 loader entry 是 **scoped 名** `@marecgents/dsh-hub`（身份四重相等铁律）→ dsh 装配插件树时从 profile 根 resolve scoped 包 → 找不到 → 崩。**全新环境必现**（postinstall 只装 dsh/pnpm/建快捷方式、不注册 bundle，首启由 launcher 装配）；本机此前从未暴露只因 profile 是 `npm link` scoped 装配（`node_modules/@marecgents/dsh-hub` 真实存在）绕过了兜底路径。
    - 正确做法（已修复）：launcher 统一 **scoped 装配**——junction 建 `node_modules/@marecgents/dsh-hub`、bundles 只注册 scoped 名；**每次启动都校验 scoped junction 指向当前包根并自愈**（补建/重指，防链接丢失场景）；发现 bare 遗留（junction 或 bundle 名）幂等清理（防 duplicate loader entry 双挂）；新增诊断模式 `DSH_HUB_ASSEMBLE_ONLY=1`（只装配不启动，跳过单实例/多实例门禁）。升级冒烟项：① 全新环境装包 → 首启成功；② 手动删除 `profiles/web/node_modules/@marecgents/dsh-hub` 后重开 → 自动补建；③ 含 bare 遗留的旧 profile 首启 → 自动迁移 scoped 并清理。
    - 当前（dev-v2）：npm launcher 链路已删除；scoped 装配 / junction 自愈 / 裸名清理由 Rust 壳 `node.rs` → `scripts/assemble-profile.mjs` 承担（教训继承自本条目）。

## Tauri 迁移（M4 壳）

34. **assemble-profile.mjs 复制 cordis.patch.yml → 全新 profile 启动即崩（duplicate loader entry id: dsh-hub）**
    - 现象（2026-08-18 E2E 验证，隔离 DSH_HOME 首启）：Tauri 壳 node.rs 调 `assemble-profile.mjs` 装配全新 profile 后，`dsh web` 启动即崩 `TypeError: duplicate loader entry id: dsh-hub`；60s READY 超时 → 壳回退临时页（无标题栏/无托盘菜单/无通知，功能全失效）。真实运行 profile 从未触发，因其 cordis.patch.yml 早已存在（`!existsSync` 跳过复制）。
    - 原因：`assemble-profile.mjs` 步骤 5 把包的 `cordis.patch.yml`（含 `- insert: - id: dsh-hub`）复制进 profile；而步骤 2 已在 `dsh.profile.bundles` 注册 `@marecgents/dsh-hub`——**同一插件的 patch insert 与 bundles 条目双挂**，loader 以 `dsh-hub` 为 entry id 去重 → 崩（与 #33 同族：双装载路径）。
    - 正确做法（已修复）：**bundles 是唯一装载机制**，与 `bin/launcher.mjs ensureBundleInstalled`（从不复制 patch，实测 rc.14+ 正常）保持一致——assemble-profile.mjs 删除 patch 复制步骤；用户自定义 patch（如 MCP 配置）自行维护 `profiles/web/cordis.patch.yml`，脚本不覆盖。升级冒烟项：隔离 `DSH_HOME` 首启装配 → dsh web 正常 READY；含旧 patch 的临时 profile 需删除重建。

35. **Tauri initialization_script 在「文档创建时」执行（head/body 为 null）**
    - 现象/风险（2026-08-18 E2E 实测）：init_script 里解析期 `document.head.appendChild(st)` → **`document.head` 为 null 抛错，整个脚本死亡**——标题栏/菜单/声音全失效（`E2E:titlebar missing`）。旧版脚本只做 `addEventListener`（无 DOM 访问）故从未暴露；新加样式注入即炸。
    - 正确做法：**所有 DOM 访问推迟到 `DOMContentLoaded`**（ensureShellStyles/injectTitleBar 由 initShell 统一调度）；初始化脚本抽成独立 `src-tauri/src/shell-init.js` 用 `include_str!` 注入（可 `node --check` 校验语法）。升级冒烟项：标题栏/托盘菜单存在性。

36. **Node 进程没有 `Audio`（提示音实现放错进程）+ 浏览器无声音路由**
    - 现象（2026-08-18 用户实测日志）：`tauri sound "success" init failed: ReferenceError: Audio is not defined`——`tauri-shell.ts` 跑在 **dsh web 的 Node 进程**里，`new Audio()` 不存在 → 提示音全失效；且 `/api/dsh-hub/sounds/*` 静态路由**从未实现**（浏览器端 HTMLAudio 也会 404）。
    - 正确做法：声音必须由**浏览器**播放——Node `playSound` → `DSH_CMD play_sound` → Rust → `win.eval("window.__mgPlaySound('kind')")` → HTMLAudio；配套 ① `/api/dsh-hub/sounds/*` 静态路由（sounds-api.ts，正则白名单防穿越）② `additional_browser_args("--autoplay-policy=no-user-gesture-required")`（WebView2 默认拦截无用户手势音频）。升级冒烟项：任务完成时 `play_sound: 'success' dispatched to page` 日志 + 真实可听。

37. **未打包 Windows 应用 toast 不显示（AUMID 未注册）**
    - 现象（2026-08-18 用户实测）：`notify: toast sent` 命令执行成功但系统**无 toast**。`tauri-plugin-notification` 用 config identifier（`com.marecgents.dsh-hub`）作 AUMID（desktop.rs:27），未打包应用不注册 AUMID 则 toast 静默不显示。
    - 正确做法：启动时幂等注册 `HKCU\Software\Classes\AppUserModelId\com.marecgents.dsh-hub`（DisplayName/IconUri，`reg add /f`）；打包安装（M5 NSIS）后快捷方式自带 AUMID，reg 仅保开发期。升级冒烟项：AUMID 注册日志 + toast 真实弹出。

## dev-v2 Tauri 收口期踩坑（2026-08-19）

38. **插件 fiber 拆除硬杀进程**
    - 现象：host 插件 dispose 时整实例退出（dispose → onExit → exitProcess 链路）。
    - 原因：把「插件 fiber 拆除」误当「应用退出」，拆除时硬杀进程。
    - 正确做法：拆除只释放句柄/关闭资源；进程退出由 Rust 壳（supervisor + quit.marker）负责。

39. **peerDependencies ^0.0.1-rc.1 与 dsh 0.1.0-rc.7 冲突**
    - 现象：dsh 升级后首启即崩（peer 区间过旧）。
    - 原因：peer 声明 ^0.0.1-rc.1 与已发布的 dsh 0.1.0-rc.7 不匹配。
    - 正确做法：peer 对齐 `^0.1.0-rc.6`（与 dsh 实际版本区间一致，已入库）。

40. **mingw ld cdylib `export ordinal too large`**
    - 现象：GNU 工具链链接 dsh_hub_lib.dll 报导出序号溢出。
    - 原因：mingw ld 自动导出 windows crate 全部符号，序号超 PE/COFF 上限（tauri-apps/tauri#10843）。
    - 正确做法：`src-tauri/.cargo/config.toml` 加 `--exclude-all-symbols`（已入库；桌面 exe 静态链接 rlib，cdylib 无需导出符号）。

41. **cmd-shim 兜底只杀 cmd.exe 留下 node 孙进程孤儿**
    - 现象：退出/重启后 dsh 端口仍被占用，下次启动被多实例门禁锁死。
    - 原因：cmd /c 兜底路径的 child 是 cmd.exe，kill 只杀它，node 孙进程残留。
    - 正确做法：kill 后补 `taskkill /PID <pid> /T /F` 杀整棵进程树 + resolve 硬化（优先解析 shim 为 node.exe + entry 直接 spawn）。

42. **tauri-plugin-notification 无点击回调 API**
    - 现象：toast 点击无法回到窗口（插件 2.3.3 无 onClick）。
    - 原因：通知插件不提供点击回调。
    - 正确做法：改用 notify-rust 直弹 + `wait_for_action` 实现点击回窗。

43. **本机 WQL `-or` 报无效查询 0x80041017**
    - 现象：多实例检测的 CIM 查询报 0x80041017 无效查询。
    - 原因：WQL 顶层 `-or` 连接条件不被接受（运算符优先级歧义）。
    - 正确做法：把 OR 条件括号化（`(A) or (B)`）再查询。

44. **Rust `if let` scrutinee 的 MutexGuard 临时存活导致内层重锁死锁**
    - 现象：supervisor 线程偶发死锁/卡死。
    - 原因：`if let Some(child) = lock().unwrap()` 中 Guard 活到整个块结束，块内再次 lock 同一把锁 = 重入死锁（clippy::if_let_mutex）。
    - 正确做法：先 `take()` 出来再进 if-let 做 `try_wait`，块内不持锁。

45. **GNU 测试二进制缺 WebView2Loader.dll 报 0xc0000139**
    - 现象：GNU 构建/测试产物运行报 0xc0000139（DLL 缺失）。
    - 原因：WebView2Loader.dll 在 deps/ 不是自动产物，GNU 链接不自动带出。
    - 正确做法：手工复制 WebView2Loader.dll 到目标目录（或 CI 改用 MSVC 工具链）。

46. **config.json 写入非原子（writeFileSync 直写目标）**
    - 现象：崩溃/断电时 config.json 被截断 → 设置全丢。
    - 原因：直接 writeFileSync 到目标路径，无临时文件 + rename。
    - 正确做法：先写临时文件再 `renameSync`（原子替换，已修复）。

47. **workspace 路径二次 decode**
    - 现象：含字面 `%` 的工作区路径抛 URIError。
    - 原因：`searchParams.get` 已解码一次，再 `decodeURIComponent` 二次解码遇 `%` 抛错。
    - 正确做法：去掉二次 decode，直接用 `searchParams.get` 结果（已修复）。

48. **settings 超范围宽高回放未 clamp → 永久 dirty**
    - 现象：回放的保存宽高超出当前屏范围后，设置卡永久「未保存」。
    - 原因：回放未与服务端同域 clamp，回写值再次越界。
    - 正确做法：回放前与服务端同域 clamp（`[480,屏宽]`/`[360,屏高]`）再回写（已修复）。

49. **GNU 工具链 + 官方预编译 tauri CLI 导致 WebView2Loader.dll 缺失**
    - 现象：GNU 编译的 NSIS 安装包，安装后启动报「找不到 WebView2Loader.dll，无法继续执行代码」。
    - 原因：webview2-com-sys 在 GNU 下**动态链接** WebView2Loader.dll（MSVC 才静态链接）；而 tauri-bundler 的「GNU 时自动打包 DLL」逻辑用 `cfg!(target_env)` **编译时宏**判断 target，官方 tauri CLI 是 **MSVC 编译的预编译二进制** → 运行时误判 target=msvc → 跳过 DLL 打包。
    - 正确做法：① 首选 **MSVC 工具链**（静态链接，彻底无需 DLL）；② 临时 workaround：把 `target/release/WebView2Loader.dll` 纳入 resources 落到 exe 同目录（已随切 MSVC 移除）。

50. **Tauri 2 NSIS resources 实际落点是 `$INSTDIR\_up_\`（非 `$INSTDIR`）**
    - 现象：安装期 hook 找不到引导脚本 / 打包态装配脚本路径解析失败，私有 node 引导不触发。
    - 原因：Tauri 2 NSIS 把 `bundle.resources` 解包到 `$INSTDIR\_up_\<相对路径>`，而非 `$INSTDIR\<相对路径>`；误以为落到 `$INSTDIR\scripts\` 导致 `installerHooks.nsi` 与 `node.rs` 路径写错。
    - 正确做法：打包态按 `_up_\` 前缀定位 resources，dev 态按仓库 `scripts\`（用 `assemble_script_path()` 双态判别修复）。

51. **开发机 Schannel TLS 异常：PowerShell/curl SSL 全失败，Node/OpenSSL 正常**
    - 现象：PowerShell `Invoke-WebRequest` / `curl.exe` 连 nodejs.org、npm 镜像全报「SSL connection could not be established」；但 `node fetch`、`npm` 命令正常。
    - 原因：本机 Windows Schannel（.NET HttpWebRequest / curl 的 Schannel 后端）证书链/防火墙问题；Node 自带 OpenSSL 独立于系统 Schannel。
    - 正确做法：引导脚本下载 node 时加 **node fetch 回退**（OpenSSL 后端）绕开 Schannel；标准 Windows 上 Schannel 正常则走 Invoke-WebRequest。

52. **PowerShell 5.1 读取无 BOM UTF-8 脚本，中文注释致变量解析失败**
    - 现象：`dsh-deps-install.ps1` 安装期报「检索不到变量 HubPkg」。
    - 原因：脚本无 BOM 且含中文注释，PowerShell 5.1 按 ANSI(GBK) 误读，中文字节破坏下一行 `$HubPkg = ...` 语句。
    - 正确做法：PS 5.1 脚本保持**全英文注释**（或加 UTF-8 BOM）；已把中文注释改英文并验证 ANSI 读取解析通过。

53. **托盘图标从 `env!("CARGO_MANIFEST_DIR")/icons/32x32.png` 加载 → 打包态 setup Err → panic → 进程消失**
    - 现象：安装后双击快捷方式，窗口刚出现（AUMID/建窗日志正常）进程就退出，dsh.log 停在「theme: DWM attributes set」。
    - 原因：`env!("CARGO_MANIFEST_DIR")` 是**编译时展开的打包机源路径**（如 `E:\Workdata\...\src-tauri`），安装到新电脑后该路径不存在 → `Image::from_path` 失败 → `setup_tray` 返回 Err → setup `?` → `.expect()` panic → 进程崩溃退出。
    - 正确做法：托盘图标改用 `include_bytes!("../../icons/32x32.png")` 编译期内嵌（与 theme.rs 窗口图标一致）；**打包态严禁用 `env!(CARGO_MANIFEST_DIR)` 拼运行时文件路径**（仅 dev 可用）。排查工具：dsh.log 停在 AUMID/建窗后 + 无 node 日志 = 卡在门禁/托盘段。

54. **壳 spawn dsh web 缺 `--no-open` → dsh web 弹浏览器，与壳分离渲染**
    - 现象：新电脑安装后，壳显示占位页，同时**默认浏览器弹出渲染 dsh web**（壳与插件分离）。
    - 原因：壳 spawn dsh web 命令 `dsh web --port 0` **没传 `--no-open`**，dsh web 默认打开系统浏览器。
    - 正确做法：壳 spawn 命令必须带 `--no-open`（`spawn_inner` 正常路径 + `spawn_via_cmd_shim` 兜底路径都加）。

55. **README 同步等待 60s 超时 → 壳停在占位页（dsh web 冷启动慢）**
    - 现象：dsh web 实际能启动（浏览器渲染），但壳一直显示占位页不导航。
    - 原因：壳在 setup 主线程**同步轮询 READY 最多 60s**，dsh web 冷启动（私有 node + 全新 `~/.dsh` 首次初始化 + 插件装配）可能超过 60s → 超时 fallback 到占位页，放弃导航。
    - 正确做法：README 等待改**后台线程**（setup 不阻塞，窗口先显示"启动中"占位页），轮询 `state.port` 最长 300s，READY 后 `win.navigate` 复用窗口；失败仅 warn 保持占位页。

56. **打包产物复制静默失败（build/ 里的包不是最新）**
    - 现象：`Copy-Item` 到 `build/<version>/` 后，文件时间戳还是旧的（hash 与 target 产物不一致），用户装到旧包。
    - 原因：目标 exe 被占用（查看器/杀毒扫描）时 `Copy-Item -Force` 覆盖失败，但命令不检查结果、错误被后续输出掩盖。
    - 正确做法：复制后**校验 SHA256**（源与目标 hash 相同才确认），失败先删目标再复制；打包脚本内置 hash 校验。

57. **多桌面壳插件同时在 web profile bundles 里 → 窗口互斥/自关闭**（吸收自 PR #24 排错经验，映射 dev-v2）
    - 现象：窗口打开后约 3 秒自动消失，或两个壳插件互相覆盖/销毁；dsh.log 出现两次壳初始化。
    - 原因：web profile 的 `bundles` 同时挂了多个桌面壳插件（如 dsh-hub + 另一个 mg-* 壳），后加载的覆盖前者。
    - 正确做法：确保 web profile `bundles` 中**只有一个桌面壳插件**（`@marecgents/dsh-hub`）；排查 `~/.dsh/profiles/web/package.json` 的 `dsh.profile.bundles` 与 `node_modules/@marecgents` 下是否有重复/多余壳。

58. **dsh provider 配置陷阱：图片剥离靠 `modalities.input` 配 `"pdf"`，`supportsImages` 无效**（吸收自 PR #24，dsh 生态通用）
    - 现象：发送含图片消息后模型报错或忽略图片。
    - 原因：`modalities.input` 只配了 `["text"]`，宿主不剥离图片，直接把图片发给纯文本模型；`supportsImages` 字段直接写无效。
    - 正确做法：`modalities.input` 必须配 **`["text", "pdf"]`**——`"pdf"` 是触发宿主剥离图片的关键字；vision hook 只负责注入文字描述，不负责剥离。另：免费模型额度用尽时换 `deepseek/deepseek-v4-flash(free)`（独立额度池）。

59. **Windows 任务栏按钮图标走 ICON_BIG 槽——Tauri `set_icon` 只设 ICON_SMALL（S6 鲸鱼娘图标"任务栏不变"的根因）**
    - 现象：设置卡切换鲸鱼娘后 Alt-Tab/标题栏图标变了，但**任务栏按钮与桌面快捷方式不动**；探针确认 ICON_SMALL 已是鲸鱼娘、ICON_BIG=0。
    - 原因：tao 源码（`platform_impl/windows/window.rs`）把 ICON_BIG 槽命名为 `set_taskbar_icon`（任务栏按钮图标来源）；Tauri 2 `WebviewWindow::set_icon` 仅设 SMALL，ICON_BIG 缺失时任务栏回退**窗口类图标**（exe 内嵌鲸鱼）。另：桌面/开始菜单快捷方式图标来自 `.lnk` IconLocation（默认 exe），`WM_SETICON` 改不到。
    - 正确做法：① 窗口双槽位设置（SMALL=Tauri set_icon + BIG=Win32 `CreateIcon` → `WM_SETICON(ICON_BIG)`，见 theme.rs `set_icon_big_win32`）；② `.lnk` IconLocation / AUMID IconUri 同步更新 + `SHChangeNotify(SHCNE_ASSOCCHANGED)`（`update_shell_icon_sources`）。**CreateIcon 必须用 tao 同款构造**：32bpp BGRA XOR + **逐字节反相 alpha 的 AND 掩码**（每像素一字节，非紧缩位图）；全零掩码会与 alpha 混合路径冲突，实测渲染错乱（覆盖残缺/颜色异常）。进程无显式 AUMID 时任务栏不走注册表 IconUri（tauri-winrt-notification 只把 app_id 传给 toast，不设进程 AUMID）。

60. **PowerShell `GetHicon()+Icon.Save()` 生成 4bpp/16 色无 Alpha 劣质 ICO**
    - 现象：`.lnk`/AUMID 图标源指向生成的 .ico 后，256×256 彩色插画显示为严重抖动的花斑（5 个文件字节数还完全相同=4bpp 定长编码的巧合）。
    - 原因：GDI+ `Bitmap.GetHicon()` + `Icon.Save()` 走 16 色调色板路径，丢 Alpha、抖动降色；且只产单尺寸条目。
    - 正确做法：用 Pillow 生成规范 ICO（`scripts/generate-desktop-icons.py`）：7 档尺寸（16~256）、32bpp、PNG 压缩条目、保留 Alpha；不透明方图（鲸鱼娘插画）先加圆角透明遮罩（4x 超采样抗锯齿）。**.lnk 的 IconLocation 只认 .ico 不认 .png**——需把 .ico 经 tauri.conf.json `bundle.resources: ["icons/*.ico"]` 打进 `$INSTDIR\icons\`。

61. **`desktop_icon_ico_path` 文件名双重前缀 + 桌面路径 `USERPROFILE\Desktop` 近似在重定向机器失效**
    - 现象：鲸鱼娘选择后日志报 `no .ico for 'whale-girl-sad'`，.lnk/AUMID 从未更新（'default' 碰巧正确——`whale.ico` 无前缀拼接）；桌面快捷方式在桌面重定向（如 `D:\快速访问\桌面`）的机器上永远改不到。
    - 原因：① `format!("whale-girl-{}.ico", icon_id)` 而 icon_id 已是完整前缀 `"whale-girl-sad"` → 拼出 `whale-girl-whale-girl-sad.ico`；② 桌面路径用 `USERPROFILE\Desktop` 近似，而 lib.rs 建快捷方式用 `FOLDERID_Desktop`（OneDrive/自定义重定向安全），两处不一致。
    - 正确做法：文件名直接 `{icon_id}.ico`；桌面路径统一 `theme::known_desktop_path()`（SHGetKnownFolderPath/FOLDERID_Desktop，迁到 Helper 层共用）。**教训：同一资源路径的"写入口"和"改入口"必须共用一个解析函数。**

62. **IShellLink 写 AUMID 属性：`IPersistFile::Save` 必须在 `IPropertyStore::SetValue` 之后**
    - 现象：lib.rs 日志报 `shortcut(x): created ... with AUMID`，但 .lnk 文件里实际**没有** AUMID 属性（toast 归组/图标关联失效）。
    - 原因：代码先 `persist.Save()` 落盘、后 `props.SetValue(PKEY_AppUserModelID)` 且**不再保存**——属性停留在内存对象上。
    - 正确做法：微软官方顺序：建 ShellLink → QI `IPropertyStore` → `SetValue` → QI `IPersistFile` → `Save` **最后**执行。另附探针经验：release 构建 + 隔离 DSH_HOME 仍会弹多实例确认框（`allowMultipleInstances=true` 走 Yes/No 确认分支）——**自动化探针用 debug 构建**（`debug_assertions` + 隔离 home 直接跳过门控），否则 `MainWindowHandle` 抓到的是警告图标对话框，画出的"黄三角"是对话框图标而非应用图标。

63. **安装器从 npm registry 拉插件本体 → 安装包永远缺最新功能（全量打包修复）**
    - 现象：测试机装新 NSIS 包后，Rust 壳是新的（图标修复生效），但设置卡/客户端新功能（鲸鱼娘选择器、对话定位条等）全部缺失。
    - 原因：`tauri.conf.json` resources 只打包了 2 个脚本 + 图标；插件本体靠 `dsh-deps-install.ps1` 的 `npm install -g @marecgents/dsh-hub`（安装期从 registry 拉）+ `node.rs` junction 优先指 `dsh-hub-win\node_modules` 的这份副本——registry 上最后发布的是旧版（0.0.2-rc.3，8-20），仓库里之后的所有插件层功能都没发布过 → 永远旧版。
    - 正确做法：**插件本体随安装器分发**——resources 增加 `../package.json`、`../cordis.patch.yml`、`../lib/**/*`、`../assets/**/*`、`../bin/**/*`（Tauri 2 约定 `../` 前缀资源映射到 `$INSTDIR\_up_\`，`_up_` 即完整插件包根）；`node.rs` junction 三级优先：`_up_`（安装包自带，与壳同版本）→ dsh-hub-win npm 副本（老机器兜底）→ dev 仓库根；`repo_root()` 判定改**完整 `_up_` 优先**（package.json + lib + scripts 齐全才判打包态；同时修复"打包机上运行安装后的 exe 永远误判 dev"的缺陷，且天然排除旧事故里 target/debug 残缺 `_up_` 残留）。旧机器升级后 junction 由 assemble-profile.mjs 自动 relink（自愈）。**教训：凡是"安装器"必须自包含全部运行时，任何"运行期从 registry 拉自己的另一份副本"的设计都会造成壳/插件版本漂移。**

64. **打包态插件缺 node_modules → 目标机 ERR_MODULE_NOT_FOUND、永远卡"正在启动 dsh 服务"**
    - 现象：rc.4 安装后一直停在占位页；dsh.log 反复 `Cannot find package '@deepseek-ai/dsh-settings' imported from $INSTDIR\_up_\lib\index.js`，sidecar 3 次重启失败。
    - 原因：`_up_` 只打包了插件自身文件——host 侧运行时 import 的外部包（`@deepseek-ai/dsh-settings`、`@deepseek-ai/schemastery`）无法从 `$INSTDIR\_up_\` 解析（旧 registry 布局靠 npm 安装时顺带拉依赖，dev 态靠仓库 node_modules，两条路在 `_up_` 都不存在）。**教训：改插件装载路径后必须在"目标机布局"下做真实 import 验证，不能只验证 junction 指向。**
    - 正确做法：① 依赖闭包（BFS 遍历 dependencies+peerDependencies）作为 resources 打进 `_up_\node_modules\`（`../node_modules/<pkg>/**/*` 的 array-form 映射天然正确；当前闭包 10 包 ~1.8MB：cordis/loader/include、cosmokit、dsh-brand/invariants/settings、schemastery、@standard-schema/spec、argparse、js-yaml；平台限定包 node-addon-require-builtin 本机也没有、运行不需要，排除）；② build-installer.mjs 加 **host 依赖打包守卫**——扫描 lib host 产物（排除浏览器 bundle）的外部 import，逐个核对 node:* 内置或已入 resources 闭包，缺则构建 FAIL，防此类问题再次溜出。

65. **卸载残留 400MB：Tauri NSIS 模板卸载段不删 glob resources 与运行期生成内容**
    - 现象：卸载后安装目录只剩主 exe 被删，`_up_`（resources）、`icons`、`dsh-hub-win`（安装期下载的私有 Node 运行时，~400MB）、引导日志全部残留。
    - 原因：Tauri 生成的卸载段只跟踪主二进制/快捷方式/uninstaller；glob resources 与安装期 PowerShell 下载的内容不在其清单。
    - 正确做法：`installer-hooks.nsi` 增 `NSIS_HOOK_POSTUNINSTALL`——`RMDir /r` 仅限 `$INSTDIR` 的已知子目录（_up_/icons/dsh-hub-win）+ 删引导日志 + 末尾**非递归** `RMDir "$INSTDIR"`（目录空才移除，绝不递归 INSTDIR 本身）；另 best-effort 清理 profile（DSH_HOME 环境变量或默认 `~/.dsh`）：从 bundles 移除 `@marecgents/dsh-hub` + 删除 junction（**悬空 junction 的 Test-Path 会跟随返回 false，必须查 ReparsePoint 属性**；`(Get-Item).Delete()` 只删链接点不递归）——不清理的话卸载后用户 `dsh web` 会因加载不存在的条目直接崩。

66. **对话定位条固定低透明 token → 背景图/皮肤下几乎不可见**
    - 现象：开背景图（表面 75% 半透明、~25% 图透出）后 rail 小横条对比度趋近 1:1，看不清。
    - 原因：tick 用 `--dsw-alias-border-l2`（≈12% alpha）+ 根节点 0.55 透明度——专为原生不透明表面设计的弱化装饰色，在中亮度混合背景上必然失效；且深浅两套固定色无法覆盖各类皮肤/背景。
    - 正确做法：**对比度必须相对"有效背景"计算**——采样 rail 下方实际背景（slot 子元素 computed backgroundColor 解析皮肤 token 与 color-mix 透明度 × 背景图 cover 数学复算采样条），按采样色相派生深/浅两个候选色调取 WCAG 对比度更高者（实测 7.5–16:1）；激活态用同色相饱和强调色（双亮度候选择优）+ 1px 反差描边 + 阴影兜底；换肤/换背景/主题翻转/resize 均触发重算（settings-card 显式调用 + body 属性 MutationObserver + 几何同步）。

67. **NSIS 卸载对数千资源文件逐条 Delete → 慢于手动删除**
    - 现象：卸载 uninstall.exe 删文件极慢（用户反馈"甚至不如手动删除"）。
    - 原因：Tauri NSIS 模板卸载段对每个 resource 文件逐条 `Delete /REBOOTOK` + 详情视图逐行刷新——`_up_`（lib + node_modules 闭包）+ `dsh-hub-win`（运行期下载的私有运行时，数千文件）全是单文件操作。
    - 正确做法：`NSIS_HOOK_PREUNINSTALL` 先 `RMDir /r` 已知大目录（NSIS 卸载器自 %TEMP% 副本运行，$INSTDIR 内容可全删），模板逐文件阶段变 no-op；`POSTUNINSTALL` 保留清扫兜底 + 非递归 `RMDir $INSTDIR`（空才删，防误删自定义安装位置的周边文件）。安装体验同理：bootstrap（1-3 分钟）改 `Exec` 异步 + 轮询 DEP 日志镜像到详情视图（ps1 加 `-LogPath` 落进度行 + `DEP: FAILED` 哨兵），替换 `ExecWait` 全程冻结。启动关键路径：AUMID 注册（reg.exe×2 + COM 快捷方式）移后台线程，完成后 `sync_shell_icon_sources` 补竞态窗口漏掉的 .lnk 更新。

## dev-v2 图标/卸载/进程收口期踩坑（2026-08-23）

**68. 图标快速切换卡死——SendMessageW 阻塞 + 多面双通道竞争**
现象：连续快速切换桌面图标时窗口线程忙/卡死；各面应用互相打架。
原因：① BIG 槽 WM_SETICON 走 SendMessageW（同步等窗口线程泵消息），快速切换时积压 → 调用线程阻塞；② 图标应用分散在多个调用点（helpers/theme.rs 持 static + commands 直调），无双通道合并 → 并发竞争 + 线程积压 + shell 面风暴。
正确做法（已实现，managers/icon.rs IconManager）：apply() 只写 pending Mutex<Option<(id,dark)>> + notify 后立即返回（IPC 不阻塞）；快速切换只保留最新请求；单常驻 worker（Condvar）消费；apply_all 内全局 apply_lock 串行；面级幂等去重键含 dark（'default' 输出依赖主题）。升级冒烟：快速连点 10+ 次，最终图标=最后一次，无卡顿。

**69. 图标 BIG 槽 SendMessageW → PostMessageW（异步防阻塞）**
现象：WM_SETICON(ICON_BIG) 跨线程同步发送导致切换卡顿。
原因：SendMessageW 跨线程等窗口线程处理完才返回；积压即阻塞。
正确做法（已实现，helpers/theme.rs）：BIG 槽改 PostMessageW（异步投递）；HICON 由调用方（IconManager.big_icon）持有，替换 Destroy 旧值。教训：跨线程发窗口消息不要求同步结果的一律 PostMessageW。

**70. 卸载器启动慢——Defender 首次扫描 3.5 万文件私有运行时**
现象：全新电脑（无 Defender 缓存）双击卸载器等很久才出界面。
原因：$INSTDIR\dsh-hub-win 是私有 Node 运行时（~3.5 万小文件），Defender 实时扫描全目录后才放行。
正确做法（已实现）：dsh-deps-install.ps1 安装期尽力 Add-MpPreference -ExclusionPath $InstallDir（需管理员；无权限/第三方杀毒静默跳过，绝不影响安装）。

**71. Job Object 的 SyncHandle——HANDLE 不是 Send/Sync**
现象：壳退出后私有 sidecar（node）残留；Job 句柄放 static 共享报编译错。
原因：win32 HANDLE 是裸指针不实现 Send/Sync；KILL_ON_JOB_CLOSE 要求单例活到进程结束。
正确做法（已实现，managers/node.rs）：struct SyncHandle(HANDLE) + unsafe impl Send/Sync + OnceLock 单例；spawn 成功路径 assign_sidecar_to_kill_job。教训：包装系统句柄进共享状态必须显式 unsafe impl Send/Sync 并注释理由。

**72. Cargo.toml windows features 依赖传递失效——必须显式声明**
现象：use windows::Win32::System::JobObjects 编译报找不到模块。
原因：windows crate feature-gated，features 只在本包 Cargo.toml 直接声明生效，依赖树其他包启用不传递。
正确做法（已实现）：src-tauri/Cargo.toml 显式列 Win32_System_JobObjects + Win32_Security。凡 use windows::* 的模块 feature 必须本包显式列出。

**73. 标题栏标签条锚点契约（#dsh-hub-titlebar .tb-title）**
现象：会话标签栏（SessionTabs）createPortal 到标题栏 .tb-title——壳/标题栏结构改动后标签条可能静默消失（无日志）。
原因：.tb-title 是匿名 class 结构锚点（shell-init.js injectTitleBar 幂等注入，42px 预留"为未来浏览器标签页留空间"）；client 300ms 轮询等标题栏出现（启动竞态兜底）。
正确做法（已实现，M2）：client 端持续轮询（标题栏可能晚挂载）+ 找不到 return null 优雅降级（应用功能零影响，store 保留，恢复后自动重现）。
升级冒烟项：① 壳/Tauri 升级后 #dsh-hub-titlebar .tb-title 仍唯一命中；② 标签条全交互可用（+/切换/×/右键/拖拽）且标题栏其余区域仍可拖窗（no-drag）；③ 主题/皮肤切换后标签条仍在（标题栏不重建）；④ 慢启动下标签条最终出现。

**74. 交互终端——node-pty 打包 + PTY 生命周期 + SSE 契约**
现象：终端（M4）涉及 node-pty 原生模块——未声明依赖/未进 resources 白名单时，全新环境插件加载即崩（rc.10-13 同型首启事故）。
原因：node-pty 是 native 模块；dsh 依赖树里只有嵌套私有副本（subprocess-local），hub 向上解析不到；裸 pty.kill() 不杀进程树；SSE 载荷含换行/ANSI 需 JSON 信封。
正确做法（已实现，M4）：
- 打包：package.json dependencies node-pty@1.2.0-beta.15（与 dsh 同版本去重）+ tauri.conf resources ../node_modules/node-pty/**/*（N-API prebuild 免编译，Node 24 实测加载 OK）
- ESM：严禁 require——import { isAbsolute } from 'node:path'
- 生命周期：onExit 清理 Map + close 用 taskkill /PID <pid> /T /F 杀进程树 + disposeAll() 挂 teardown（热重载不剩孤儿 PowerShell）
- SSE：data: JSON.stringify(chunk) 信封（chunk 含 \n 会破坏原始帧）+ 15s 心跳 + req close 清理；客户端 JSON.parse
- 安全：进程级随机 token（webserver/index-inject 注入 __DSH_HUB_TOKEN__ → globalThis）+ Authorization Bearer / ?token= + Origin 白名单 + 错误脱敏；BLOCKED_CMDS 只是 UX 护栏（非安全边界，可绕过）
升级冒烟项：① 全新机器安装后 Ctrl+J 可开终端（node-pty 随 resources 装进 _up_）；② 关闭终端后任务管理器无孤儿 powershell.exe；③ 断线/宿主重启后 SSE 重连不重复回放；④ 无 token/跨源 POST 全被 403。
**75. rc.8 初始化卡死：旧 profile 的 legacy `dsh-hub` loader 条目与包 patch 重复（duplicate loader entry）**
现象：测试机安装 0.0.2-rc.8 后首启一直卡在「初始化 dsh 界面」（placeholder 永不跳转 dsh web）；dsh.log 见 `dsh-stderr: Error: dsh: plugin tree failed to load: duplicate loader entry id: dsh-hub`，sidecar 退出后 READY 永不出现（supervisor 重启后仍失败）。
原因（2026-08-25 隔离环境复现确证）：旧安装（WebView2 时代 launcher / 早期 rc）在 `$DSH_HOME/profiles/web/cordis.patch.yml` 残留 legacy 行 `- insert: - id: dsh-hub / name: dsh-hub`（裸名）；rc.8 插件包自身 patch（`_up_/cordis.patch.yml`）也插入 `id: dsh-hub`（name 为 scoped `@marecgents/dsh-hub`）→ cordis-plugin-loader EntryGroup 对同 id 直接 throw → 插件树加载失败 → dsh web 启动即崩 → 壳卡初始化。assemble-profile.mjs 的迁移此前只清理 bundles 裸名条目与 junction，**未清理 profile patch 中的 legacy 行**（「不覆盖用户 patch」的盲区）。
正确做法（已修复，rc.9 起）：`scripts/assemble-profile.mjs` 新增 `scrubLegacyPatch`——装配时从 `profiles/web/cordis.patch.yml` 移除「name 为裸名 dsh-hub」的 loader 行（文本级行处理，不解析 YAML，保护用户 patch 的 `!!js` 表达式与其他 id 的条目；若清除后无剩余数组条目则写标准空数组 `[]`，避免 comment-only 文件被 loadOverlayPatches 拒绝）。用户自定义 patch（如 MCP 配置）不受影响。
升级冒烟项：① 含 legacy `dsh-hub` 行的旧 profile 首启 → 自动 scrub + 正常进入 dsh UI；② 含用户自定义 patch（其他 id）的 profile → 自定义条目原样保留；③ 全新 profile → scrub 零副作用（不写文件）；④ 卡死复现命令：隔离 DSH_HOME + 旧 patch 播种 + 安装版 exe 启动（见 hub-fix 报告 E 轨）。

## dev-v2 UI / i18n / 右键菜单收口期踩坑（2026-08-27）

**76. 卸载残留 = 裸 `dsh web` 崩 + 重装卡初始化（同源）**
现象：测试机（rc.9 早期）卸载后裸 `dsh web` 无法启动（`cannot resolve profile bundle`）；再装新包后一直卡「启动中」。
原因：卸载只清了 hub bundle，`@dsh-external/*`（4 插件）的 bundle 注册与 junction 残留；`resolveBundleDir` 对不可解析 bundle 直接抛错；残留 junction 指向已删安装目录（悬空）→ 裸启动崩；重装咬合残留 profile → 卡初始化。dsh **无** junction 型 bundle 的卸载命令（`dsh plugin remove` 只针对 pnpm 依赖，`profile.ts` 无 remove API）→ 卸载清理必须安装器侧实现。
正确做法（已实现，rc.9 打包）：`scripts/uninstall-cleanup.ps1`（随包 `_up_/scripts/`）遍历 `$DSH_HOME/profiles/*`：bundles 过滤 hub+`@dsh-external/*`、删除相关 junction（只删链接点、悬空可删）、清空 `@dsh-external` 目录、无 BOM 写回（PS5.1 `Set-Content -Encoding UTF8` 的 BOM 会崩 dsh 的 JSON.parse）；NSI PREUNINSTALL 在删 `_up_` 前执行它，POSTUNINSTALL 单行兜底（旧安装）。`.dsh` 本体与用户数据绝不碰。

**77. WebView2 原生右键菜单无法被 DOM 拦截——必须 Rust 层禁用**
现象：左栏对象行右键一直弹浏览器原生「刷新/后退/检查」菜单；页面 `contextmenu` + `preventDefault` 完全拦不住（多轮 DOM 方案无效——承接 #79 之前的错误路径）。
原因：WebView2 的默认上下文菜单是浏览器级（原生层独立于页面事件），DOM 无法阻止其显示；且单次只能出现一套原生菜单（这也是后面判别 DOM/原生的判据）。
正确做法（已实现）：Rust 侧窗口建立后经 `PlatformWebview.with_webview` 拿 webview2-com 类型化 controller，链 `controller.CoreWebView2()?.Settings()?.SetAreDefaultContextMenusEnabled(false)`（wry 同款调用链；`controller()` 在 `impl PlatformWebview`，须在 `with_webview` 回调内取；COM 调用是 unsafe fn → `// SAFETY:` + 单 unsafe 块）。成功后打 `log::info!`（取证锚点）。教训：WebView2/Tauri 桌面壳的「右键菜单」问题先分清楚「原生菜单 vs DOM 菜单」，原生菜单只能壳层关。

**78. 全局 contextmenu 处理器重复注册 → 两个刷新菜单重叠**
现象：空白处右键同时弹出两个「刷新」。
原因：index.ts 本来就有一套 `context menu (refresh-only)`（Bug-2 时代），本次排查又新增了一整套 refresh-menu 模块 → 两个 handler 同弹。
正确做法（已实现，修复即收敛）：全局监听**只保留一个刷新源**；新增功能前先用 `grep "addEventListener('contextmenu'"` 盘点全仓注册点；同类「页面级全局 handler」建单一模块 + 单例防重（HMR/include.refresh 重装载时 disposer 必须清理，见 #78bis 的 armed/registered 验证法）。

**79. 同节点多个 contextmenu 监听都会执行——preventDefault 不阻止其他监听**
现象：会话行右键出现「会话专属菜单 + 刷新」两个菜单（刷新盖在专属菜单上）。
原因：多个监听注册在同一 `document` 节点时，冒泡到该节点后**全部**执行（执行序=注册序，preventDefault 只抑制默认动作，不影响其他监听）；老兜底的设计假设「我们的菜单会 stopPropagation」未达成——pin 只 preventDefault 没 stopPropagation → 事件继续冒泡到兜底。
正确做法（已实现）：① 专属菜单处理器必须 `preventDefault + stopPropagation`（双保险）；② 兜底刷新处理器自备目标豁免（不依赖其他代码的 stopPropagation 副作用）。教训：DOM 事件层的协作尽量用「自身判定」，不要依赖他方行为。

**80. 右键豁免选择器过宽 → 空白处无反应**
现象：空白处右键弹不出刷新菜单（左栏尤甚）。
原因：豁免清单含 `button / a / [role=button]`——dsh UI 大量「看似空白」的容器是按钮式元素包裹（chrome 遍布），空白右键落到这些元素即被豁免。
正确做法（已实现，最终语义）：豁免取**事件语义最小集**——对象行 `div[role="treeitem"]`（closest 上行连带行内子按钮）+ 文本编辑要素 `textarea/input/select/[contenteditable]`；其余一切（含左栏空态/空白、按钮/链接上的右键）落入刷新菜单 →「对象控件豁免、空白全可刷」。
教训：豁免/白名单设计先盘点目标 DOM 的实际结构（官方 `WorkspaceBrowser.tsx`/`Rows.tsx` 的 `role="tree"/treeitem`、`.empty` 空态位置、`sidebar.workspaces` slot 锚点），勿凭猜测列宽泛类名。

**81. i18n 词典值若生成成函数调用 → 模块顶层 TDZ（Cannot access X before initialization）**
现象：dsh 官方报错 `Failed to load plugins … Cannot access 't' before initialization`，界面/插件区崩。
原因：usage-stats client 改造时 `zhDict` 的值被生成成 `'ui.title': t('ui.title')`，而 `const t` 定义在其后——模块顶层（loader entry factory）求值 zhDict 时 t 处于 TDZ。
正确做法（已实现）：词典必须是**纯数据**（零函数调用）；顶层定义顺序：常量 → 词典 → 函数；验证用「t 定义前零顶层调用」扫描 + 模拟 loader 装载（stub window/document/__ModuleLoader__ 执行 factory）。教训：脚本生成代码时，生成结果须包含「定义顺序正确性」自检，别只验语法。

**82. 标题栏图标启动时序——去重缓存让早期失败永久化**
现象：启动时标题栏最左侧图标空白，手动切换图标后才出现。
原因：`apply_titlebar_face` 带 titlebar 去重缓存（同 id 直接 return）；启动早期首次注入若撞上页面未就绪/icons-api 未起（img 404），缓存即写入 → 后续 apply_page_theme 不再重灌 → 永久空白（手动切换 id 变化才触发）。
正确做法（已实现）：移除 titlebar 面去重（页面端 setDesktopIcon 幂等，每次重灌成本可忽略）+ tb-icon `img.onerror` 品牌圆点 data-uri 兜底。教训：启动早竞争态 + 去重缓存 = 一旦首帧失败再无机会；「幂等重灌」优于「去重」当注入便宜时。

**83. dev 实例调试的常见环境坑**
现象/原因：多次 tauri:dev 前后台混起（`&` 启动日志不落盘、旧实例 dev-server 残留）→ EADDRINUSE(:17891) 启动即败；实例频繁被关闭（closeToTray=false 点 X 即退）导致「测一轮关一轮」。
正确做法：统一用后台任务启动并落日志文件；启动失败先 `netstat -ano | grep :17891` 杀残留；用 `grep READY on port` 判就绪、`grep ctx-trace` 等探针读页面侧行为（浏览器 console 不进 dsh 日志——页面调试需 host 转发端点或 a11y 取证）。

**84. 皮肤移植与 i18n 的工程纪律（伴随经验）**
- 参考主题移植（Reasonix 官方 8 + opencode 2）：生成器统一推导规则（直映射 + 混合 + dimmed 夹取 ≥3.5:1），回归逐键比对已提交条目 vs 生成结果（防手改漂移）；词典/生成器脚本里 python 与 node 的舍入差异（banker's vs half-up）会让「同值」逐位不同——用同语言重算或银行家舍入对齐。
- i18n 语言源：跟随 dsh 设置语言走**官方 locale 插件写入的 `<html lang>`**（`document.documentElement.lang` + MutationObserver），React 用 `useSyncExternalStore` 订阅；DOM 原生模块「打开菜单时求值」即可。词典 zhsatisfies 键源 / en 用 Record<HubKey> 保证完整性，tsc 兜底。
- 数据安全红线贯穿：所有测试一律隔离 DSH_HOME（%TEMP%），真实 `~/.dsh` 全程零触碰（审计证据：时间戳 + junction 指向不变）。

**85. 会话「重命名任务」三易其稿——官方 ⋯ 菜单在本环境不可用（合成事件无效 + 真实点击也无反应）**
现象：左栏会话行右键菜单「重命名任务」点击无反应（原实现的内联编辑只渲染于置顶区）；多轮修复（行内注入、官方 ⋯ 菜单链、合成 click/指针序列）均失败——官方 ⋯ 菜单连真实用户点击都打不开。
根因（DMAIC 测量，双轮 ctx-trace 探针定论）：① 原实现 beginRename 的编辑表单只在【置顶区】渲染（live=置顶 ids），未置顶会话点重命名无处渲染；② 官方重命名对话框 = WorkspaceBrowser 内部 React state（setSessionRenameTarget），唯一入口是行 ⋯ 菜单链（⋯ → Menu onSelect → onRename），而**官方 ⋯ 弹层在本 WebView2/React 环境对合成 click/指针序列与真实点击均无法打开**（污染确认：poll 只见自绘菜单 10 项、官方 3 项从不渲染）——对话框不可达；③ 可用的只剩官方数据层 `session.rename`（标题栏标签改名同源、联动正常）。
正确做法（已实现，Plan A′）：右键菜单「重命名任务」→ 就地展开 `.mg-ctxmenu` 改名微表单（当前标题 input + 保存/取消，Enter/Esc/外点关闭）→ 调**同一官方 `sessions.binding(id).session.rename`** → 快照联动左右栏/标签文本更新（与标题栏改名一致）；失败保留表单可重试；置顶区菜单保留原 pinned 表单。五轮审查（正确性/时序/安全/兼容/副作用）+ 全流程事件模拟后落地，已验证。
教训：① 弹层类官方 UI 可能主动/被动不可达（合成事件非万能、甚至真实事件异常）——先做「用户直点该官方入口」判别，别在不可达链上死磕；② 功能落点优先找**官方数据层 API**（同源保证联动一致性），UI 形态可自收敛（菜单内嵌表单=复用容器样式、零新布局）；③ 对「点击后无反应」类 bug，用链路探针（host 日志通道）量化每一步（btn→click→菜单渲染→dialog）比猜测高效得多；④ 合成事件驱动第三方 React 弹层在本环境不可靠（两轮实测）。

**86. 插件工具 output.render 返回字符串而非 ContentBlock[] → 会话整轮崩溃（content.some is not a function）**
现象（用户真实事故）：两个「优化论文审稿恢复方案」会话（~/.dsh/sessions）最后一轮均以「本轮运行失败 content.some is not a function」（code UNKNOWN）结束；轮内模型调用 `permission_status` 工具后下一步立即崩溃。
根因链（DMAIC 测量，会话日志 zstd 解码 + 官方源码交叉定位）：① dsh-permission-guard 的 `permission_status`/`permission_reload` 与 dsh-findings-ledger 的 3 个工具，`output.render` 返回**字符串**（如 `v.ok ? JSON.stringify(v.config, null, 2) : v.error`），而官方契约 `render(...): ContentBlock[]` 必须返回数组（`packages/core/tools/src/schema.ts`）；② 插件自造最小版 defineTool 绕过了 cordis-host-runner `harness.defineTool` 的 `assertRenderedContent` 数组校验（guard.ts:537），core/tools 的 `snapshotProjection`（index.ts:530）只做 JSON 快照、不校验数组 → 字符串畅通写入会话日志的 tool-result block（`content: "<json>"`）；③ 下一轮 LLM 请求重建时，provider adapter 的图片检查 `contentHasImage(message.content)`（llm/content.ts:39，pi-ai adapter.ts:350 等）递归进入 tool-result block 对字符串调 `.some()` → TypeError → 整轮 error。provider 为 tokenrhythm（pi-ai）时必现；模型在写操作被 permission-guard confirm 层拦截后按 GUIDANCE 查 `permission_status` → 必经路径必现。
正确做法（已实现，rc.12）：全部 5 处 render 改为返回 `[{ type: 'text', text: … }]` 数组（permission-guard 2 处 + findings-ledger 3 处）；已确认 project-memory 本来就是数组、usage-stats 无工具。防御方向（已建议 dsh 官方）：snapshotProjection 对 render 结果做数组校验，隔离畸形插件而非毒化整个会话。
教训：① cordis 插件自造 defineTool 会绕过官方 harness 校验——插件工具必须用 harness.defineTool（或至少保证 render 返回 ContentBlock[] 数组）；② 已损坏会话的历史 tool-result block 无法自愈（每次请求重建都会再崩）——修复后需新开会话；③ 排查会话崩溃类 bug 的黄金路径：`session.jsonl.zstd` 用 Node 内置 `node:zlib.zstdDecompressSync` 逐帧解码（复用官方 scanZstdFrames 帧边界逻辑）→ 定位崩溃前的 tool/result 畸形 block → 再对官方源码找 `.some()` 递归调用点。

**87. 手改 dsh 会话 zstd 文件必须保留官方帧结构——第一帧必须是「恰好一行 header」**
现象（真实事故，rc.12 启动连环）：修复两个崩溃会话（#86）后，rc.12 安装启动一直卡在壳启动中间态；dsh 日志报 `corrupt Zstandard session log: first frame is not exactly one header line`（dsh-workspace 加载即崩，sidecar 无限重启）。
根因（三要素）：① 直接原因——修复脚本重编码时把整个日志（header + 全部事件）压成**单帧**，违反 dsh 会话格式不变量：`session.jsonl.zstd` 第一帧解压后必须**恰好一行 header**（`assertZstdHeaderFrame`，dsh-session-persistence-jsonl `readFirstZstdLine`）；② 环境——dsh-workspace `[cordis.init]` 的 `list()` 会 `readFirstZstdLine` 扫描每个会话目录，任一文件违规 → 整棵插件树加载失败 → dsh web 不启动；③ 触发——上一轮修会话时未读官方格式源码即重编码。
正确做法（已修复）：重写会话时**帧 1 复用原文件第一帧的原始压缩字节**（逐字节拷贝，保证合法），修复后的明文事件单独用 `zstdCompressSync(..., {params:{[ZSTD_c_checksumFlag]:1})` 压成事件帧，`Buffer.concat([headerFrame, eventFrame])` 写回；验证用「逐文件扫描：帧 1 解压后行数 === 1」门禁（当前 8 个会话 0 bad）。
教训：① 修改 dsh 持久化文件前先读官方格式源码（`zstd.ts` / `readFirstZstdLine` 的帧不变量），别按「能解压」就以为合法；② 事件级正确 ≠ 格式级正确——`session.jsonl.zstd` 是「多帧容器」，帧边界有语义（第 1 帧 header 单行）；③ 会话修复类改动必须跑「全目录格式扫描」回归，因为 workspace 初始化会扫全部会话，一个坏文件拖垮全局；④ 备份的原始字节是格式修复的黄金参照——重编码时优先复用原始帧字节而非重新压缩。

> **#87 补充（同事故二阶段：事件帧混入 header 行 → torn JSONL）**：第一版重编码虽修好了「单帧」问题（帧 1 复用原 header 帧字节），但事件帧直接 `decodeAll` 全部帧后 `split('\n')`——**把 header 行也当事件塞进了事件帧**。dsh 的 `SessionLogScanner` 对事件帧第一行 `seq=undefined` 报 seq gap（`event.seq !== events.length`），`committedBytes` 停在该行前 → 加载完整历史时抛 `complete frame contains a torn JSONL record`。修复：事件行必须 `slice(1)` 排除 header 行（header 已独立成帧），事件帧从 `seq=0` 的 `permission/preset` 行开始。验证纪律：① 判「第一帧是否一行」必须用 **Buffer 字节级**（`plaintext.indexOf(10) === plaintext.length - 1`，安装库 `assertZstdHeaderFrame` 原样）——**JS string 的 `indexOf/length` 是 UTF-16 code unit**，中文 cwd 路径（UTF-8 多字节）会让字节数与 code unit 数不一致，产生「截断假象」；② 最终验证用**安装库真实路径**：`new JsonlSessionPersistence(ctxStub, {root, compression:'zstd'}).listArtifacts()`（dsh-workspace 启动同款调用），ctx 只需 stub `sessions.list = () => []`；③ `SessionLogScanner` 要求**事件 seq 从 0 连续**（`event.seq === events.length`），所以「删除中间事件」类修复必须同步重排 seq 或只删尾部事件（本次只删尾部 4 个，seq 0..40805 仍连续）。

**88. 会话修复三阶段连环事故——「内容正确 ≠ 格式正确」的完整教训（2026-08-28 全链）**
现象：修好两个崩溃会话（#86 内容修复）后，rc.12 启动连环两错：先卡启动中间态（`first frame is not exactly one header line`），再报会话「历史加载失败」（`complete frame contains a torn JSONL record`）。最终验证全部通过。
三阶段根因与修复（环环相扣，每阶段「自验证通过」仍是假阳性）：
- 阶段 A（启动崩）：把整个日志（header+事件）压成**单帧** → 违反「帧 1 解压后恰好一行 header」（`assertZstdHeaderFrame`）→ dsh-workspace 初始化扫全部会话即崩。修复：帧 1 复用原文件第一帧原始压缩字节 + 事件单独成帧。**但自验证只查「帧 1 行数」通过，没查事件帧内容 → 漏过阶段 B。**
- 阶段 B（打开崩/torn）：事件帧由 `decodeAll` 全部帧 `split('\n')` 生成——**header 行也被当事件塞进事件帧**。`SessionLogScanner` 要求事件 `seq === events.length`（从 0 连续），header 行 `seq=undefined` → seq gap → `committedBytes` 停在首行 → `committedBytes !== inputBytes` → `torn JSONL record`。修复：事件行 `slice(1)` 排除 header（header 已独立成帧）。**自验证（自写 scanner）当时漏检——直到用安装库真实读取才捕获。**
- 阶段 C（通过）：排除 header 行重建 → 安装库 `loadStored` 完整读取全过。
核心教训：① 改 dsh 持久化文件，**内容正确 ≠ 格式正确**——帧边界语义（帧 1 = header 单行）、事件 seq 连续性、packChunks storage rows 都是格式不变量；② **验证必须走安装库真实读取路径**（`new JsonlSessionPersistence(ctxStub, {root, compression:'zstd'}).listArtifacts()/loadStored(id)`，ctx 只 stub `sessions.list=()=>[]`），自写复刻易与官方逻辑有微妙差异且易出假阳性；③ **字节级 vs 字符级陷阱**：判断「第一帧是否一行」用 `Buffer.indexOf(10) === buffer.length-1`；JS string 的 `indexOf/length` 是 UTF-16 code unit，中文路径（UTF-8 多字节）会让字节数与 code unit 数不一致，产生「截断假象」误判；④ 每阶段修复后必须跑「全目录 + 完整读取」两层验证（header 扫描全目录、事件读取逐个会话），单文件/单层验证会漏；⑤ 备份原始文件字节是格式修复的黄金参照——优先复用原始帧字节，重压缩仅限事件帧。完整技术路线见《调试与修复技术路线手册》§1。

**89. permission-guard 死锁：只读工具（permission_reload / ask_user_question）被 confirm 拦截**
现象（真实事故，2026-08-28）：两个论文会话最新轮次全部卡死——模型写文件被拦（`权限拦截（confirm 层）：此操作需先确认 → write`）→ 调 `permission_reload` 想让新配置生效 → **reload 也被拦**（`... → permission_reload`）→ 模型无法推进，只能总结「全部被拦截」后 stop。Paper1 里连 `ask_user_question` 都被拦。
根因（三要素）：① 直接原因——`DEFAULT_CONFIG.tiers.auto` 只含只读工具 `read/glob/grep/permission_status`，而 **`permission_reload` 是只读操作（重新读取配置文件、零副作用）却落在 defaultTier=confirm**：模型永远无法让用户新写入的放行配置生效，配置更新死锁；② 环境——`ask_user_question` 是 confirm 机制**本身的人工确认通道**，被拦后模型连「征求用户确认」都做不到，confirm 流程整体失效；③ 触发——默认配置下模型写论文文件必被拦，进而尝试 reload 解锁 → 连环死锁。
正确做法（已修复，未发布）：`DEFAULT_CONFIG.tiers.auto` 增加 `permission_reload`、`ask_user_question`（附注释说明只读无副作用原则）；GUIDANCE 改为「reload 为只读 auto 放行；用户改配置后先 reload 再重试」。**注意合并语义**：`tiers: {...DEFAULT_CONFIG.tiers, ...raw.tiers}` 是**整体覆盖**——用户已有 `tiers.auto` 时插件默认新增条目不生效，需用户手动补条目或删配置重建（模拟验证：fresh=auto / 现有用户配置=confirm / 补条后=auto）。
教训：① 权限系统的拦截层必须按**副作用**分类：只读/无副作用工具（reload、status、ask_user_question）永不该进 confirm——confirm 的意义是「有副作用的操作等确认」，拦只读工具 = 死锁；② 「让配置生效」的工具（reload）被拦 = 配置更新机制自杀；③ confirm 通道工具（ask_user_question）被拦 = 确认机制自杀；④ 修改插件默认配置时，若合并语义是「用户层整体覆盖默认层」，必须提示存量用户补配置（或提供迁移）。

**90. permission-guard 与官方权限体系脱节——Full Access 无效的根因与联动修复**
现象（2026-08-28 续 #89）：一个会话「确认了也写不进去」、另一个「开 Full Access 也不行」；会话日志铁证：Paper1 六次 write 全被插件拦（含切 danger-full-access 之后），Paper2 一开始就是 danger-full-access 仍被拦。
根因（三层交叉验证）：① dsh 官方权限管线顺序 `pre-execute 监听 → approval ask → guards`（core/tools/src/index.ts:1376）——插件 guard 挂在最后；② `danger-full-access` 只作用于官方层（approval=never 跳过询问 + sandbox 全放行），插件 `ctx.tools.guard` 只看自己的 permission-guard.json、**不读会话 sandbox/approval**——官方放行 ≠ 插件放行；③ 插件的 confirm 拦截没有「用户确认后放行」通道（ask_user_question 只是对话工具，不改变 guard 决策）——「确认了也不行」。
正确做法（已实现 rc.14）：插件 `policy` 档位（默认 `follow`）联动会话官方 preset——guard 从 `exec.agent.session.events` 折叠 sandbox/approval（零依赖），`danger-full-access`/approval=never → 只留 never 红线；`read-only` → 只读放行；`workspace-write` → 白名单；`strict`/`read-only` 档不跟随。never 红线任何档位都生效。配置写 `~/.dsh/permission-guard.json` 的 `policy` 字段（mtime 检测自动生效）。UI：hub 设置卡「权限策略」区 + 会话左下角 `conversation.input.left` slot 的权限策略 chip（官方权限 chip 旁）。
教训：① 插件叠加官方权限体系时必须读官方状态（会话日志事件折叠是零依赖正解），否则「官方授权」全部失效；② 权限管线的多层叠加（approval + guards）每层都要知道上层的决定；③ 会话权限状态无单独可变字段，全部由 `sandbox/mode`/`approval/policy`/`permission/preset` 事件折叠而来（`effectiveSandboxMode`/`effectiveApprovalPolicy`）；④ composer 工具行官方扩展点 `conversation.input.left`（list slot，注册需 `id`）可挂第三方 chip。

**91. Rust 测试并行读写环境变量 → CI 随机失败（dsh_home_custom 断言挂）**
现象（2026-08-28 CI）：PR #47 的 rust workflow 失败——`state::tests::dsh_home_custom` 断言 `left: "C:\Users\runneradmin\.dsh"` ≠ `right: "/tmp/test_dsh"`；同一次 main push 的 workflow 却 success（随机性）。
根因：`dsh_home_*` 三个测试直接 `set_var/remove_var` 进程级 `DSH_HOME`，Rust 测试默认**多线程并行**——`dsh_home_custom` 的 `set_var` 被并行的 `dsh_home_default` 的 `remove_var` 冲掉（或反之）→ 读到默认 home。
正确做法（已修复）：环境变量测试用**静态 `Mutex` 串行化**（`static ENV_LOCK: Mutex<()>`，每个测试 `let _g = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner())`，容忍 poison）；本地连跑 5 次 cargo test 确认稳定 + fmt/clippy 门禁。
教训：① 任何读写**进程级状态**（环境变量、全局缓存、当前目录）的单测都必须串行化——并行测试是默认行为，不是可选项；② 「本地过了、CI 随机挂」优先怀疑测试并行竞争；③ 修复后重复跑测试（≥5 次）+ 依赖 CI 双路径（push + PR）都绿才算稳。

**92. 左栏会话行右键/⋯ 拦截失效——displayTitle 歧义（同工作区无标题会话标题相同）**
现象（2026-08-29）：会话开始后，该会话左侧栏行的右键菜单消失，⋯ 按钮回退成官方原版菜单。
根因（实测 + 源码）：`mapRowByContent`（pin-conversations）按行内 `displayTitle` 文本匹配会话 id，**重复标题整组跳过**。而 dsh 的 `displayTitleOf`（client/runtime/sessions/service.ts:169）：无持久标题的会话 → displayTitle = **cwd basename**——同一工作区的多个无标题会话标题全部相同（实测真实 ~/.dsh：Paper1 工作区 17 个会话、Paper2 23 个、DeepSeekHarness 5 个，basename 相同）→ 标题组永远歧义 → 右键/⋯ 拦截全部失效 → 回退官方菜单。「会话开始后」才暴露是因为 blank 行本就不渲染 ⋯、也被右键跳过。
正确做法（已修复）：标题歧义时**选最近 updatedAt 的候选**（被操作的行几乎总是该组最近活跃的）；`SessionSummaryLike` 补 `updatedAt`；唯一标题/blank 排除逻辑不变。模拟验证（歧义→最近、唯一→精确、blank→排除）+ tsc/client 构建通过。
教训：① 用「显示文本」做行→id 映射时，**同工作区多会话标题冲突是常态**（basename 标题），不是边缘情况——歧义处理必须存在；② 歧义时的「最近更新」近似有局限（右键旧会话会命中最近会话）——根治需官方行暴露稳定 id（data 属性），作为上游建议；③ 复现此类「回退官方行为」的 bug：对比我们 handler 的守卫链（选择器→内容匹配→blank 判断→拦截），逐环在真实会话数据上验证。

**93. 快捷方式改进误删「桌面 lnk 存在才更新图标」→ 自定义图标不跟随**
现象（2026-08-29）：桌面快捷方式改进（#49，启动不创建/不检查桌面 lnk）后，桌面快捷方式图标不再跟随自定义图标设置；用户连带反馈「标题栏图标等也没跟随」。
根因（两轮审查）：① `update_shell_icon_sources`（icon.rs shell 面）在改进时把「桌面 lnk 存在才更新」整段删除（连同 `known_desktop_path` 函数）——安装时创建、用户未移走的桌面快捷方式图标从此不再更新；② 标题栏面（`apply_titlebar_face`，页面 eval `__mgSetDesktopIcon`）链路独立、未受影响（隔离实测 `titlebar face applied (whale-girl-duo)` 正常跟随）——用户观察的「标题栏」问题非此改动导致（可能为 AUMID SHCNE 落地延迟或主环境时序）。
正确做法（已修复）：恢复 `theme::known_desktop_path` + `update_shell_icon_sources` 恢复「桌面 lnk **存在才更新**图标」（不创建——创建仍仅 NSIS 安装器）；`create_toast_shortcuts` 保持不创建桌面。边界：用户把快捷方式**移动到任意文件夹**后位置未知，图标不自动跟随（设计限制，需手动重建或告知路径）。
教训：①「不创建/不检查」≠「不更新已存在的」——改进移除逻辑时逐个面核对（创建 vs 更新 vs 检查是三件事）；② 图标六面（shell lnk / AUMID / 窗口 / 托盘 / 标题栏 / 通知）链路独立，删一面别误伤其它；③ 删共享 Helper 前 grep 全部调用方（known_desktop_path 曾两处共用）。

**94. 壳内官方工作区行拖拽排序"被固定住"——主根因：Tauri dragDropEnabled 覆盖 WebView2 IDropTarget（页内 HTML5 DnD 全灭）；官方无 key 翻转重建 → dragend 丢失为浏览器侧次生缺陷（非壳内根因）**
现象（2026-08-29）：官方左侧栏"工作区控件"（workspace 行）原本可上下拖拽排序，壳内被固定住——列表顺序无法调整；同一页面在普通浏览器拖拽正常。排查与定案（三轮交叉调研 + 多环境真实拖拽对照）：① 官方拖拽是纯 HTML5 DnD（`div.projectRow[role="treeitem"][aria-expanded][draggable]` → `dragstart` 置 `workspaceDrag` → `groupSection` 的 `dragover/drop` → `insertWorkspaceBefore` RPC）。② 关键对照：**同一 dsh 页面，普通浏览器真实拖拽正常，壳内真实拖拽连 dragstart 之后的 dragenter/dragover/drop 都不派发**——注入代码无嫌疑，排查方向从页面层转到壳层。早期用合成 DragEvent 验证得到"壳内也能触发"的假象（合成事件不经过 OS IDropTarget / wry 拦截层），是第一轮误判的来源；改用真实鼠标拖拽对照后才定案。③ 官方源码侧确有一个浏览器侧缺陷（见根因②），曾据此误判为主根因——壳内 dragover 都不派发，轮不到触发它。
根因：**主根因在壳层**：Tauri 2.x `dragDropEnabled` 默认 true → wry 的 DragDropController 在 Windows 上枚举每个 WebView2 子 HWND，`RevokeDragDrop` + `RegisterDragDrop` 把 OS IDropTarget 换成**只认文件**的实现（`SetAllowExternalDrop(false)`）——页内 HTML5 DnD 事件链在 OS 层被整体截走，壳内拖拽无从发起（浏览器同页正常；Tauri 官方文档自认 "Disabling it is required to use HTML5 drag and drop on the frontend on Windows"，同型 issue tauri#2014/#15138/#13761——**Rust 手工建窗不受 tauri.conf.json 配置影响**）。**官方浏览器侧次生缺陷（真实存在，非壳内根因）**：2026-08-11 `fcbe3ac` 引入 `listTopDropIndicator`，`workspaceDropAtListStart`（悬停第一个真实工作区组上半部）置真时 `.treeBody` 首子元素在**无 key 数组** `[false|span, div.list, fade]` 间翻转 → React 18 对整个 `div.list` 子树卸载重建 → 被拖行 DOM 被替换；Blink `DragSourceEndedAt` 只查 null 不查 isConnected（dragend 仍派发到脱离文档的源节点）但**脱离文档的事件不冒泡到 React root** → 官方 `onDragEnd` 收不到 → `workspaceDrag` 残留非 null。影响边界：仅 flip-OFF 那一次 dragend 丢失，drop 提交不受影响，下次 dragstart 自愈。另：我们的注入（置顶区 40vh 插 `.treeBody` 内、pin 按钮）不参与 React 协调（外来节点无 fiber），不是根因，但置顶区把用户引向"拖到最前"手势并放大卡顿。
正确做法（已修复，壳层 + 插件层，不改官方源码）：**壳层主修复**——`src-tauri/src/managers/window.rs` builder 加 `.disable_drag_drop_handler()`，撤掉 wry DragDropController 覆盖、恢复 WebView2 默认 IDropTarget，页内 DnD 行为回归 Chrome；壳不消费任何 tauri drag-drop 事件（grep 全壳核实），无功能损失。**壳层配套**——`src-tauri/src/shell-init.js` Files-only 拖放兜底（document capture 阶段对 dragover/drop `preventDefault`）：撤覆盖后文件拖放回归 WebView2 原生行为，官方 ComposerAttachments 挂载时自己 preventDefault（= 拖文件进输入区即官方附件上传），但占位页/设置页/composer 卸载空窗期等"页面无 drop 处理器"时刻，默认动作会把拖入文件当 file:// 导航整窗跳走——兜底只认 `dataTransfer.types` 含 `'Files'`（页内 HTML5 拖拽不含 Files，零打扰）、只 preventDefault 绝不 stopPropagation、不动 dropEffect。**插件层精简**——`src/client/workspace-drag-guard.ts` 从三合一（C/B/G2）精简为 **B + G2**：B watchdog——dragstart 记录源行，若上次拖拽未收到 dragend/drop（如次生缺陷的 flip-OFF 重建吞 dragend），下次 dragstart 向旧源行合成 `new DragEvent('dragend',{bubbles:true})` 自愈清空官方 workspaceDrag（源行仍连接时可达 React root，尽力而为）；G2——拖拽中 body 加 `mg-drag-active`，CSS 收缩置顶区到 96px（消除横穿 40vh 死区的放大因素）；pin-conversations `sync()` 在 `mg-drag-active` 时短路（拖拽中不写会话行 DOM，官方列表重建会重新触发 observer 补刷不丢状态）。**撤销 C**（document 捕获拦截首组上半部 dragover）：定案后其防的仅是"每次拖拽至多一次可自愈的 dragend 丢失"，却让"拖到最前"失去官方顶部插入线、stopPropagation 侵入官方事件流——收益不再值回代价。
教训：① 方法学——**合成事件验证不了真实拖拽**：合成 DragEvent 不经过 OS IDropTarget / wry 拦截层，"合成事件能触发"≠"真实拖拽可用"；壳内 DnD 问题必须用**真实鼠标拖拽在壳内 vs 浏览器做同页同手势对照**，对照结果决定排查层。② 壳/运行时层能力（dragDropEnabled、IDropTarget 覆盖）会整体改写 OS 级输入行为，HTML5 事件层监控对它**完全失明**（事件根本不产生）——排查"事件不派发"先查壳/运行时层，再查页面层。③ 先定主根因再设计兜底：壳内根因未除时，任何页面层兜底都无效；根因消除后，兜底按"剩余风险 × 侵入代价"重新评估——C 就是在根因改判后失去存在理由而撤销的。④ "持续失效"优先怀疑状态卡死回路（一次异常 → 状态残留 → 之后每次失败）；React 18 事件委托在 root 容器，脱离文档子树的事件不冒泡——HTML5 拖拽源被 React 重挂载后 dragend 必然丢失，第三方注入无法改官方 fiber，状态层兜底（合成 dragend watchdog）是唯一无损手段。⑤ 无 key 数组的条件首子元素（`{cond && <span/>}` 混在数组首）是 React 整体重建的经典雷区（上游建议：给 `listTopDropIndicator` 加 key 或改渲染结构）；`div[role="treeitem"][aria-expanded][draggable="true"]` 是真实工作区行的稳定 DOM 锚点（ungrouped 桶行无 draggable，天然排除）。

**95. dsh-usage-stats 落地即坏——loadPrices/savePrices 被调用但从未定义（overview 500 一个月未被发现）**
现象（2026-08-29 用户反馈"用量统计失效"）：设置页用量统计卡片"无法读取"；`GET /dsh-usage-stats/api/overview` 返回 500 `ReferenceError: loadPrices is not defined`。
根因（git 考古）：`3698dfb`（PR #34+#36+#37 三插件落地）引入时，`computeOverview` 调用 `prices: await loadPrices()`、prices POST 路由调用 `savePrices(obj)`，但**两个函数从未被定义**——自落地第一天起 overview 就 500，数据扫描/聚合（dsh-usage-stats-sessions.json 一直在写）全部正常，只有"读取聚合结果"这一环断掉，潜伏一个月未被察觉。
正确做法（已修复）：补上两个缺失函数——`loadPrices()` 读 `$DSH_HOME/storages/dsh-usage-stats-prices.json`（缺失/损坏 → 默认 `{modelPrices:{}, exchangeRate:7.2}`，与设置 UI 初始态一致）；`savePrices(obj)` 白名单清洗（modelPrices 仅对象、exchangeRate 须正数）后落盘。修复后隔离实测：overview 200（45 会话/116M tokens 完整返回）、POST /prices 200 且文件落盘、`?refresh=1` 触发后台重算（stale-while-revalidate 语义正常）。
教训：① **"数据在写"≠"功能在用"**——插件的持久化链路（扫描/聚合/落盘）正常掩盖了读取链路（API 500）断裂，用户只有打开设置页才会撞见；新插件的每个 HTTP 路由落地时必须**当场 curl/浏览器实测一遍**（本次修复后立即补测即发现并闭环）；② `ReferenceError: ... is not defined` 在 ESM 模块里是**运行时**错误（调用才炸），`node --check`（语法级）查不出来——模块级冒烟（import + 调用一次主路径）是语法检查的必要补充；③ 交叉审查三插件落地（3698dfb）时漏掉了"函数定义与调用点配对"——多函数新增的 PR 需要一次 `grep 调用点 → 逐个确认定义存在` 的机械检查。

**96. 用量统计表格透出背景皮肤图片——frame 背景图选择器 `[style*="grid-template-columns"]` 过宽，误命中面板内所有 inline grid 元素**
现象（2026-08-29，截图定案）：用量统计"各模型用量"的模型卡片内（请求/输入命中缓存/输出网格）与"按天统计"日期表格直接显示背景皮肤图片；同页其他卡片正常。
根因（两轮误诊后由截图定位）：壳的背景图功能把图片画在 AppFrame 层，选择器 `#root div[style*="grid-template-columns"]` 本意只命中 frame（唯一带 inline 三列的容器，踩坑 #32 的断言），但它是**后代选择器**——页面上**任何** inline 携带 `grid-template-columns` 的元素都会命中并被 `!important` 强加上背景图。usage-stats 的模型信息网格（3 列）与按天表头/行（动态列数）恰好都用 inline grid → 全部被画图（CDP 实证：面板内 4 个命中元素 computed backgroundImage 均为 `linear-gradient(rgba(0,0,0,.25)…),url(ds-vs-gpt)`）。**此前两轮修复（卡片加 background-color/字面色）方向错误**：`background-image !important` 画在 background-color 之上，改颜色压不住图片；且这些网格卡片路径在 #95 修复前从未渲染（API 一直 500），属于「真实数据首次渲染暴露的注入冲突」。
正确做法（已修复）：① usage-stats 三处网格改 `<style>` class（`.mg-us-grid` / `.mg-us-model-line2` / `.mg-us-day-head` / `.mg-us-day-row`），动态列数经 inline `--mg-us-cols` 自定义属性传入（style 属性不含 "grid-template-columns" 子串）；② `backgrounds.ts` frame 选择器收紧为子元素组合链 `#root > div > div[style*="grid-template-columns"]`（frame 实测路径 `#root > div > DIV.frame`），conversation-rail 的同名查询同步收紧——双保险，任何未来的 inline grid 内容都不再被误伤。隔离实测（rx-sage-breeze + ds-vs-gpt 同款组合）：面板内命中 0、收紧后选择器仍命中 frame、背景图正常应用、4 个网格 computed backgroundImage = none 且列数正确（3/6 列）。
教训：① **属性子串选择器 `[style*="…"]` 是全局误伤源**——宿主注入样式用它时要假设页面任何第三方内容都可能携带同款 inline 声明，能用结构锚点（子元素组合器/稳定 data 属性）就不要用子串匹配；② 挂在全局选择器下的 `!important` 背景会压过第三方元素自己的 background-color——**改颜色救不了被强加的 image**，必须让元素脱离选择器命中面；③ 动态网格的 inline `grid-template-columns` 可以用「class 承载 grid 声明 + inline 只赋 `--cols` 自定义属性」替代——inline 里不再出现该子串，天然免疫这类宿主选择器；④ 用户截图是最快的定位证据（两轮源码推理不如一张截图指出"透图的恰好都是网格"）；⑤ 回退重做的价值：v1/v2 的卡片填充修复建立在错误根因上，按用户指示回退到干净基点后，凭截图一次定位真根因——**方向错了就回基点，不要在错误修复上继续叠加**。

**97. 图标不跟随已移走的快捷方式 + 启动 Splash 风格割裂/加载不流畅（同批两项壳层体验修复）**
现象（2026-08-29 用户反馈）：① 桌面快捷方式移到其他文件夹后，切换图标时该 lnk 与任务栏图标不变；② 启动页慢、配色与启动后界面差异大、加载不流畅（淡出后闪白）。
根因：① 图标切换只改写「能找到的」lnk（开始菜单 + 桌面**存在时**）的 IconLocation → 移走的 lnk 停在旧 `{icon_id}.ico` 上永不跟随；任务栏走 AUMID→lnk 解析 + 图标缓存，同样断链。② Splash 配色固定深灰 `#18181b`（浅色仅跟 `prefers-color-scheme`），与用户皮肤（如米白系）完全不同系；且 placeholder 页的 Splash 在 window load 即淡出——READY 前数秒只剩系统白背景；dsh 页 3s 定时淡出可能早于 SPA 首绘 → 白屏一瞬。
正确做法：① **固定图标锚点 `current.ico`**——lnk/AUMID IconLocation 统一指向 exe 相邻 `icons\current.ico`，切换图标时把选中的 `{icon_id}.ico` **复制**为 current.ico + SHCNE_UPDATEITEM/ASSOCCHANGED 通知 Explorer：快捷方式无论被移到哪里都经由稳定路径取图标（用户建议「改 exe 图标/lnk 链 lnk」的更稳替代——运行中 exe 不可写、lnk→lnk 图标跟随不可靠，固定 ico 文件两条都规避）；已存在的 lnk 更新时一并把 IconLocation 改写为 current.ico，从此永久跟随（**旧机制创建且已移走的 lnk 仍找不到——重装一次重建 lnk 即进入新机制**）。② `scripts/export-skin-colors.mjs` 生成 `src-tauri/src/skin-colors.json`（15 套皮肤浅/深 bg-base+label-primary）；`helpers/boot_theme.rs` 读 config（theme/skin，system 读注册表 AppsUseLightTheme）生成动态 initialization_script 注入 `window.__MG_BOOT_THEME`（在 shell-init.js 之前执行）；Splash 配色 = 皮肤色（body/html 背景同步，导航间隙不再闪白）；**placeholder 页 Splash 常驻**（阶段文案「正在启动服务…」，30s 兜底）；dsh 页 Splash「正在加载界面…」**轮询 #root 等 SPA 首绘再淡出**（8s 兜底，不再固定 3s 早退）。隔离实测：bootTheme=皮肤值（#151E19/#EEF6F0）、placeholder 3.5s 仍常驻、dsh 页首绘即淡出；切图标后 current.ico 内容 = 目标 ico、开始菜单 lnk IconLocation = current.ico、AUMID → current.ico。
教训：① **「跟随」类需求用稳定锚点**：让所有引用方（lnk/AUMID）指向一个固定文件，更新只写锚点文件——逐个改写引用方永远追不上用户对引用方的搬移；② 启动体验的「风格割裂」来自**两套配色系统**（壳 Splash 硬编码 vs 用户皮肤）——宿主在窗口创建前把用户配置注入注入脚本（initialization_script 可多次调用按序执行）即可统一；③ placeholder 的 Splash **不能按 load 淡出**——占位页 load 早于真正内容，生命周期必须绑定「目标内容首绘」而非「文档加载完成」。

**98. 标题栏会话标签与标题栏同色、区域边界不明显（选中只有底部 2px 品牌线）**
现象（2026-08-30 用户反馈）：标题栏会话标签栏点击切换有底部高亮线，但标签本身颜色与标题栏一致，标签区域与标题栏边界不明显。
根因：标题栏（shell-init.js `#dsh-hub-titlebar`）涂的是皮肤 `bg-layer-1`；标签非选中背景 `transparent`、选中只有 `interactive-bg-hover`（16% 半透明叠加）——叠加量太小，深色皮肤下标签几乎"溶进"标题栏，只剩 2px 品牌线可辨。
正确做法：标签改用皮肤的**抬升面 `bg-layer-3`**（与浮层/卡片同级，天然比标题栏亮一档并跟随皮肤）：非选中 `color-mix(layer-3 30%, transparent)`（淡淡抬升、仍可区分标题栏）；选中 `85%` 近实心 + 原品牌底线（2px brand）。颜色全部走 token，浅/深皮肤自动适配（实测深色 rx-sage-breeze：标题栏 rgb(35,35,36) vs 选中 color(srgb … /0.85)；浅色 midnight：rgb(228,233,244) vs 近实心 layer-3）。层次 = 标题栏 < 非选中 30% < 选中 85%。
教训：① 壳内浮层/卡片类 UI 用「比底色高一档的面 token」做背景（layer-3），而不是透明/低透明度叠加——叠加量 < ~30% 在深色下视觉上几乎不可辨；② `color-mix(in srgb, token X%, transparent)` 是"跟随主题的半透明抬升"通用写法（避免写死 rgba 与皮肤脱节）；③ 深色主题下审查对比度重点看「相邻面的色差」，不只是文字对比度。

**99. 激活标签对比四连回归——半透明 color-mix 在浅色模式无效（layer 全同色时）**
现象（2026-09-01 用户反馈）：标题栏会话标签激活区域对比消失（浅色/默认皮肤下标签与标题栏同色、分不清哪个是激活的）。
根因（四版迭代）：① 原实现 `layer-3 85% transparent` 在深色皮肤下正常，但**浅色默认皮肤 layer-1==layer-2==layer-3==白**，抬升全消失（仅剩 2px 品牌线）；② 审查修复改成 `interactive-bg-hover 70%`——hover 色本身是 16% 灰，再乘 70% alpha ≈ 7% 有效，深色下也接近不可辨；③ 双叠色（hover 45% + layer-3 85%）同样因 hover 灰太弱而失败；④ 不透明 `brand 10% + layer-3` 在深色可辨、但浅色白底 10% 品牌仍太淡。**最终 v5**：不透明 `color-mix(brand-primary 22%, bg-layer-3)`——浅色=淡蓝卡片、深色=蓝灰卡片，双端对比明确。
教训：① `color-mix(..., transparent)` 的半透明叠色在「目标色与底色同色」时必然失效——CSS 里 `alpha 混合永远不能产生对比`；要制造对比必须用**不透明**混合（含实心基色）或加边框；② 浅色皮肤下审查 UI 对比不能只看深色——默认皮肤+浅色 OS 是最常见配置，token 全白时任何「同色系叠色」都不可见；③ 激活态不一定要靠「更亮」，`品牌色 tint + 品牌底线` 双指示在两端皮肤都成立。

**100. 状态变更路由缺 Token 验证——config POST / pins PUT 仅靠 host+origin 两层守卫**
现象（2026-09-02 三轮审计发现）：config POST / pins PUT 等状态变更路由未验证 process token，仅靠 host-guard（loopback 白名单）+ origin-guard（POST/PUT Origin 校验）两层。terminal-pty-api 已有 `verifyToken(req)` 但其他 mutate 路由遗漏。
根因：terminal-pty-api 是第一批引入 token 安全设计的路由（PR #25+），后续 config/pins 在更早阶段落地，当时安全架构尚未升级；host-guard 覆盖了「外部攻击」场景，团队误认为两层已足够——忽略了「本地同源页面越权改配置/钉选」这一本地攻击面。
正确做法（已修复，v0.1.5）：所有 state-changing route（POST/PUT/DELETE）统一 `if (!verifyToken(req)) { return 401 }`；GET/HEAD 跳过（无副作用，boot 皮肤加载/用量读取无需 token）。客户端改用共享 `authHeaders()` helper（`src/client/api-auth.ts`）读取 `__DSH_HUB_TOKEN__` 全局注入并发送 Bearer。三层守卫缺一不可：host-guard 防外部/网卡攻击、origin-guard 防 DNS-rebinding、token 防本地同源越权。
教训：① 安全守卫不可分散依赖——"已经有两层了"不是遗漏第三层的理由；新增状态变更路由时必须检查 token 验证清单（grep `verifyToken` 全仓对账）；② Token 生成/验证只需一次实现，放到共享模块（`src/server/token.ts`），避免路由间遗漏。

**101. Rust `let _ =` 静默忽略关键路径错误——quit.marker 写入失败导致 supervisor 重启循环**
现象（2026-09-02 审计发现）：window_ops.rs / tray.rs / quit.rs 多处 `let _ =` 忽略 UI 状态及文件操作返回错误，日志无任何痕迹；quit.marker 写入失败（磁盘满/权限问题）时 supervisor 无从察觉。
根因：初始实现认为 best-effort UI 操作（窗口 hide/show/unminimize、quit.marker 写入）成功概率极高，错误只在"窗口已关闭"等极端场景才触发；quit.marker 写入路径沿用该模式——`let _ = fs::write(path, "quit")`，未处理磁盘满、权限拒绝等场景。
正确做法（已修复，v0.1.5）：非关键路径至少 `log::warn!` 记录错误（便于排查用户反馈的"图标没变"/"窗口状态异常"）；quit.marker 的写入失败必须 `log::warn!` 并附路径（影响 supervisor 重启判定——写入失败时 supervisor 误判为崩溃触发重启循环，是 P1 问题）；仅在"窗口已隐藏"等明确预期失败且后果可忽略的路径保留 `let _ =` 并附注释说明为何忽略。4 个插件的 `readJsonBody` 等 best-effort 辅助函数仍保留 `let _ =`（有独立 try/catch 包裹，异常已上报）。
教训：① Rust `let _ =` 是编译器级别的"静默忽略"——类型系统不会提醒你丢弃了什么；非关键路径仍需至少 `warn!`，关键路径必须 `error!`/`return Err`；② `quit.marker` 这类跨进程信号文件属于关键路径——写入失败的级联效应（重启循环）远超单次 UI 操作失败；③ 日志不是可选的——`let _ =` 让所有失败在日志中蒸发，排查时变成"黑箱"；至少 `warn!` 是最低成本的可见性保障。

**102. 右键菜单四层优先级——WebView2 原生菜单禁用后的 DOM 补全**
现象（2026-09-04 用户反馈）：对话文本选中右键只显示"刷新"；输入框 textarea 右键无任何菜单（被豁免但无替代）；对话中的链接左键点击可能导航走 webview 而非在浏览器打开。
根因：WebView2 原生右键菜单在 Rust 层全局禁用（`SetAreDefaultContextMenusEnabled(false)`，踩坑 #77），所有右键行为由 DOM 层接管。原实现仅对空白处显示"刷新"菜单，对 textarea/input/选中文本/链接均无处理——禁用原生菜单后这些场景变成"右键死区"。
正确做法（v0.2.0）：全局 contextmenu handler 扩展为四层优先级分派——① `div[role="treeitem"]` → 会话/工作区专属菜单（pin-conversations / workspace-menu）；② `getSelection().type !== 'Collapsed'` → 复制菜单（复制 / 添加到当前任务 / 在辅助对话中提问）；③ `a[href]` http(s) → 链接菜单（在浏览器中打开 / 复制链接地址）；④ `textarea / input / [contenteditable]` → 编辑菜单（撤销/重做/剪切/复制/粘贴/删除/全选）；⑤ 其余 → 刷新菜单。链接左键点击通过 `open_url` Tauri 命令在默认浏览器打开（安全校验：`url::Url::parse` + http/https 协议白名单）。菜单构建器复用 `.mg-ctxmenu` 样式类（`context-menu.ts`），与 session-menu 视觉一致。
教训：① 禁用原生菜单后必须**补全所有右键场景**——不能只处理"空白处"就认为完成；② 菜单优先级必须显式文档化（AGENTS.md §3）并写入踩坑记录，防止后续开发者误改豁免逻辑；③ 链接打开必须走 Tauri IPC（`open_url` 命令）而非 `window.open()`——WebView2 的 `window.open` 可能在 webview 内部打开，导致用户离开 dsh UI；④ 剪贴板操作需要用户手势触发（click 事件内），不能在 hover 或 mouseenter 中执行。

**103. 输入框右键菜单不生效 + 选中文本菜单重叠——contenteditable 的优先级与焦点陷阱**
现象（2026-09-04 用户反馈）：① 对话输入框（composer）中右键菜单"不生效"——点了撤销/剪切等没反应；② 在输入框中用光标选中一段文本后右键，弹出的是"对话上下文菜单"（复制/添加到任务/辅助对话）而不是输入框编辑菜单，功能重叠。
根因（两处）：① **优先级顺序错误**——contextmenu handler 先检查 `getSelection()`（选中文本→对话上下文菜单）再检查 `textarea/input/[contenteditable]`（编辑菜单）。composer 是 `contenteditable` div（官方 `ComposerContentEditable` 渲染 `contentEditable` + `data-composer-input`），在输入框内选中文本时 `getSelection()` 非空 → 走了对话上下文菜单分支，编辑菜单永远不出现。② **焦点丢失**——菜单项是 `<button>`，点击时浏览器把焦点从 composer 移到 button，`document.execCommand('undo'/'cut'/...)` 作用在错误元素上（或无效），表现为"菜单不生效"。
正确做法（已修复，v0.1.5）：① 优先级改为 **编辑要素 > 链接 > 选中文本 > 空白**——`target.closest('textarea, input, select, [contenteditable="true"]')` 必须在 `getSelection()` 检查之前，因为 contenteditable 内的选中文本属于"编辑场景"而非"对话上下文场景"；② `context-menu.ts` 的菜单容器加 `mousedown` 阶段 `preventDefault()`——阻止 button 抢焦点，让 execCommand 作用在 composer 上。
教训：① **contenteditable 是"编辑要素"**——判断"是否在输入框内"必须用 `closest('textarea, input, [contenteditable]')`，不能只看 `getSelection()` 是否非空；② 自定义右键菜单的按钮点击会**抢走底层编辑器的焦点**——所有基于 `execCommand` 的编辑操作（undo/cut/paste）必须保证焦点仍在编辑器上，菜单容器 `mousedown preventDefault` 是标准解法；③ 菜单优先级不是"越具体越靠前"——**编辑场景必须优先于文本选中场景**，否则输入框内选中文本永远弹错菜单。

**104. 会话归档失效 + 未分组工作区右键奇怪——静默吞错与虚拟桶无菜单**
现象（2026-09-04 用户反馈）：① dsh-hub 对某些会话右键→归档"失效"（点了没反应）；② 用 dsh web 归档后，会话出现在"未分组"工作区，很奇怪；③ 未分组工作区"关不掉"。
根因（三处）：① **归档错误被静默吞掉**——`session-menu.ts` 的归档动作 `void runtime.workspaces?.archiveSession?.(params.id)?.catch(() => {})`，任何失败（会话 id 匹配错、RPC 失败）都无反馈，用户看到"点了没反应"；② **未分组桶是官方虚拟桶**——`UNGROUPED_KEY = ''`，官方 `groupByWorkspace` 把"不属于任何工作区的会话"（stray）归入未分组桶，这是**官方设计**（归档后会话从原工作区消失、但若其 workspace 归属丢失则落入未分组），不是 dsh-hub 的 bug；③ **未分组桶无菜单**——官方 `ProjectRowItem` 对 `workspaceId === undefined` 的桶不渲染 actions（无 rename/delete），dsh-hub 的 `matchWorkspaceByContent` 对未分组桶返回 `undefined` → 右键落到全局刷新菜单，用户看到"刷新"很奇怪；未分组桶的展开/折叠由官方 `groupExpansion` store 控制，dsh-hub 不干预。
正确做法（已修复，v0.1.5）：① 归档失败改为 `console.warn('[dsh-hub] session archive failed:', error)`——错误可见、可诊断；② 未分组桶右键（`div[role="treeitem"][aria-expanded]` 且 `matchWorkspaceByContent` 返回 undefined）直接 `preventDefault + stopPropagation` 吞掉——不弹刷新菜单（未分组桶无操作是官方设计，弹"刷新"是误导）。
教训：① **"点了没反应"先查静默吞错**——`.catch(() => {})` 让所有失败在用户面前蒸发，至少 `console.warn` 让错误可诊断；② **"未分组"是官方虚拟桶**——归档后会话落入未分组是官方行为（会话的 workspace 归属丢失），不是 bug；③ 对"无操作"的 UI 元素，右键应**吞掉事件**而非落到全局兜底菜单——弹一个无意义的"刷新"比什么都不弹更困惑。

**105. 最大化记忆失效——boot applySize 无条件退最大化打掉 restore_window_state**
现象（2026-09-05 用户反馈）：窗口最大化状态下退出 dsh-hub，再次打开是窗口化而非最大化。
根因：启动时序冲突——Rust setup 先 `restore_window_state`（lib.rs:726）恢复最大化；数秒后 sidecar 内插件启动连接壳时无条件 `applySize(配置宽高)`（src/index.ts boot 路径），Rust `set_window_size` 统一 unmaximize-first（当年"双路径行为一致"决策，R2-3），把刚恢复的最大化打掉，且 resize 监听随即把 `maximized:false` 写回状态文件。
正确做法（已修复，v0.1.6）：`set_window_size` 增加可选 `allow_unmaximize` 语义（invoke `Option<bool>` 缺省 true / DSH_CMD `allowUnmaximize` 可选字段缺省 true——完全向后兼容），boot 同步路径传 false：窗口最大化时 info 留痕后跳过（最大化优先于配置尺寸）；手动保存路径保持 unmaximize-first。判定抽纯函数 `resize_action` + 4 例单测。
教训：① "同一实现、双路径行为一致"在语义分化时会变成 bug 源——共享实现要留语义参数位；② boot 同步类操作（配置→窗口）必须让位于窗口状态恢复类操作，二者要有时序上的主从约定。

**106. settings path op 的数组陷阱——applyPathOp 会用对象覆盖数组中间节点**
现象（2026-09-06 插件方案审查发现）：对 `providers.<route>.models.<idx>.reasoningEfforts` 这类数组下标 path 做 set，整个 models 数组会被替换成普通对象，随后被 z.array schema 拒绝（写不落盘但功能不可用）。
根因：settings 的 `applyPathOp` 对中间节点一律展开为 plain object（`{...section, [head]: …}`），`isPlainObject` 排除数组——中间节点若是数组就被整体替换。
正确做法：① 逐字段写只走字典路径（如 `modelOverrides.<modelId>.reasoningEfforts`）；② 手填 models 数组的路由只能读-改-写**整组数组**（单 op set，基于 resolved 值 + revision 围栏），写前递归剥 undefined（cloneJsonShaped 拒绝）；③ 写回 `[]` 与缺省同语义（catalog 路由安全）。
教训：路径寻址式 API 的中间节点语义必须读实现确认——"自然假设下标可写"在展开式实现里是数据毁灭器。

**107. 最大化时保存尺寸记 0——退出最大化总落默认 3/4 而非用户上次尺寸（既有 quirk，待后续项）**
现象（2026-09-06 问题 1 修复审查中发现）：resize 监听在最大化时把保存尺寸写成 0（lib.rs:767-771，防 0 尺寸退化的历史设计），之后**任何一次**退出最大化都因 saved.width<480 落到 `default_three_quarter_size`，用户上次手动尺寸丢失。
根因：保存策略"最大化时不污染保存尺寸"用了 0 哨兵而非"保留上次非最大化尺寸"——退出最大化的恢复分支把 0 当"无保存"处理。
正确做法（待办，未在 v0.1.6 修复）：状态文件增加"上次非最大化尺寸"持久化字段，最大化期间不清除；或退出最大化时先恢复哨兵前的有效尺寸。
教训：哨兵值（0/null）承载"无数据"语义时，会把"暂时不可采样"与"从未有数据"混为一谈——持久化设计要用独立字段表达状态而不是清空数据。

**108. dsh-usage-stats POST prices 路由缺 host/origin/token 三层守卫（既有缺口，待修登记）**
现象（2026-09-06 插件安全审查发现）：`plugins/dsh-usage-stats/lib/index.js` 的 POST `/dsh-usage-stats/api/prices`（写单价数据）未接入 hub 的三层守卫（host-guard/origin-guard/verifyToken），低于 hub 审计 P1-5 标准（对照踩坑 #100）。
根因：独立插件的 webServer 路由在 hub S0 安全架构升级（#100）时被遗漏——守卫清单 grep 以 `src/server/*` 为主，未覆盖 `plugins/*/lib` 的 webServer 路由。
正确做法（待办）：独立插件的 state-changing 路由对齐 hub 标准（host 白名单 + POST Origin 校验 + token 常量时间比较），verify-plugin 增加一条"P 系检查：POST 路由必须含守卫"的静态断言防再犯。
教训：安全门禁的覆盖范围必须包含插件双轨的分发面——"主仓干净"不等于"产物干净"；新守卫上线时要对全部 HTTP 面做一次对账（含 plugins/）。

**109. composer 模型 seat 被旧设置页方案偏移——功能落点必须与官方默认 seat 对齐**
现象（2026-09-06 用户反馈）：右下角模型切换仍显示 dsh 官方默认逻辑；自定义模型只有 Default 思考强度；此前把档位编辑器错误放到了独立设置页。
根因：PR #33 的原始目标是替换 composer `conversation.input.model` 默认 seat，模型与 effort 共用同一个 session directory/select 链路；后续新增的 `dsh-model-efforts` 仅注册 `settings.section`，既偏离目标，又没有改变 composer seat 的真实 Host catalog 能力。另一个回归是旧 apply-time `ctx.get('modelDirectories')` 在 rc.1 服务尚未提供时静默 return，官方 seat 因而留在原位。
正确做法（v0.1.6 修订）：保留静态 hub seat 的 priority -1（官方默认 priority 0，最低值胜出）；用 scoped `ctx.inject(['modelDirectories'])` 等待服务后直接 `slots.inject` 注册；UI 对齐官方单一 trigger + Model/Effort 两级弹层。自定义模型没有 reasoning 元数据时，在同一个 Effort pane 通过官方 `settingsScope` 写入 `llm-pi-ai.reasoningEfforts`，随后重新加载共享 model directory，正式档位仍由 Host catalog 返回并由 `directory.select` 提交；不在设置功能页、不在 client 侧伪造档位。
教训：① 历史 PR 的原始交互契约优先于后续补丁的临时 UI；② 能力配置入口应贴近能力消费位置，但实际请求仍必须走官方 Host 校验；③ 删除一个错误插件后必须同步清理 profile bundle、junction、资源 staging 和文档，避免用户继续加载旧页面。