# 开发笔记 面向改这个插件的人。用户文档在 [README.md](./README.md)。 > 约定：文中 `<客户端安装目录>`、`<旧会话 id>`、`<包名>@<版本>`、`<临时目录>` 等尖括号内容是占位符，按自己的环境替换；仓库不包含本机路径、会话 ID 或任何凭据。 **导读**：维护者笔记；每条「坑」都给成因与对策。 - **骨架 / 本地开发**：文件构成、四处须同步的标识、`file:` vs `link:`、装卸与刷新。 - **已知坑**：注入、类名、data 标记、Shadow DOM 浮层、卸载清理。 - **更新检查（模块 3）**：成熟期门禁与豁免表、cooling、强制更新、豁免到期清理、兼容门禁、Auto review；**自更新只走 CLI**（面板不能卸载自己）。 - **动画修复（模块 4）**：删 `prefers-reduced-motion` 规则 + `matchMedia` 门控。 - **回合改动补位卡（模块 5）**：用会话日志里的 `meta.diffs` 重建回合尾卡、**必须实现 `buildLocationData` 才能被卡片读到**、补位条件是「官方那侧不会画」而非「探测到 404」、`tool/ptc-dispatch` 的 turn 归属。 - **改动卡数据/动作适配层（模块 5b）**：包 `window.fetch` 把日志重建的 summary/diff 喂给官方卡（坐标在渲染期登记）；会话释放后 `/api/changes.open` 的「打开 / 显示位置 / 打开方式」由 host 复用官方 `dsh-native-command` 补位。 - **改动审查默认单栏（模块 8）**：官方新标签写死 `split:true`，用它的切换按钮改一次。 - **窗口记忆（模块 6，仅 host 半区）**：helper + 预编译 DLL、宿主识别、编码坑、360 误报。 - **立即重启（模块 7）**：三模式判定、会话运行态、蒙皮、弹窗定位。 - **其余**：键盘与焦点、界面验证手法、迁移、待办、发布。 ## 骨架（与 dsh-model-organizer 同构） - `lib/index.js`：host 半区 8 条回环路由（统一前缀 `/api/ui-tweaks/`）：`GET local-plugins`（本地来源清单 + DSH 版本）、`POST normalize-excludes`（豁免表归并）、`POST precheck-exempt` / `POST force-exempt`（预检 / 写豁免）、`POST schedule-exempt-cleanup`（豁免到期自动删）、`POST open-path`（打开 / 显示位置 / 用指定应用打开；`action:"probe"` 只诊断不弹窗）、`POST open-apps`（系统关联应用列表）、`GET|POST restart`（立即重启）；加载时静默归并一次豁免表。 - `lib/client.js`：浏览器半区，`module.exports = { name, apply, inject }`；`apply(ctx)` 由客户端 cordis 调用。 - `cordis.patch.yml`：`- insert: [{id: ui-tweaks, name: '@nimoxie/dsh-ui-tweaks'}]`。**profile 必须声明 `dsh.bundle.patch`，否则启动报 declares no dsh.bundle**；**`insert.name` 必须写全 scope**。 - `package.json`：`exports["./client"]` 指 client bundle；`dsh.client.platform: "web"`；inject 只需 `@deepseek-ai/dsh-api-remotes`（提供 `remote.*`）；`react`/`react-dom` 是 shell 内置（PLATFORM_MODULES）。 - loader `id` 与 `exports.name` 只是内部标识；要同步四处：package.json、cordis.patch.yml、两个 profile 的依赖键 + `dsh.profile.bundles`、桌面 profile 的 lockfile 与软链。 ## 本地开发 - **`file:` 是打包快照，`link:` 才是符号链接**：`file:` 时 pnpm 把目录复制进 store，改仓库不生效。 - 安装/重装： ```sh dsh plugin --profile web remove @nimoxie/dsh-ui-tweaks dsh plugin --profile web add "link:<本仓库绝对路径>" ``` - 改完 client.js 要 **Ctrl+Shift+R**（bundle 带 `Cache-Control: immutable` 且 URL 不随代码变化，普通刷新吃缓存）；装卸插件要**重启 dsh web**。 - **桌面 profile 由 Electron 独占管理**：npm 版 CLI 装/卸被拒（`managed exclusively by the Electron application`）；**客户端自带的 CLI 可以（0.1.8 修订）**：`<客户端安装目录>/resources/runtime/cli/bin/dsh.cmd` 经 `dsh-desktop-host/lib/cli.js` 以 `manageDesktopProfile: true` 调 `runCli`，故 `dsh plugin --profile desktop add|remove <包>` 与「插件管理」页同实现，连装 5 个插件成功。三条路：① 自带 CLI；② 插件管理页填 `link:<路径>`；③ 手改四件套（package.json + `dsh.profile.bundles`、pnpm-lock importers、node_modules 软链）。 ## 已知坑 - **`ctx.inject([...])` 有一个服务名不存在，回调就永不执行且不报错**：升级 dsh 后功能静默消失，先去新版 `dsh-client-ui-*` 包 grep 注入的每个服务名。本插件 8 秒拿不到服务会给明确错误行。 - 每个模块的注册各套 `guard()`：失败记 `console.warn`，不拖垮同文件其它模块。 - 官方 CSS-module 类名是「哈希_原名」，锚定一律用**属性前缀**（`[class*="tableScroll"]`、`[class*="widthHandle"]`、`[class*="composerSeat"]`），绝不硬编码 hash——版本间会变。 - **0.2.0-rc.1 已移除 0.1.x 的 `data-dsh-part` 标记**（滚动条/调宽条/输入框选择器都改过）；`[data-slot="..."]` 是渲染器统一输出的，锚插槽容器用它。 - Shadow DOM 里的浮层，`position: fixed` 会被困在深层堆叠上下文，z-index 再高也没用——面板浮层挂 body 的 shadow root 规避。 - **定时器 / 观察器 / 全局哨兵要能被卸载**：client 插件被 HMR 重载时旧实例不会自动停表，重复注册会叠加扫描与按钮。所有 `setInterval` / `MutationObserver` / 全局 `matchMedia` 包装都走 `onDispose()`，由 `apply()` 末尾的 `ctx.effect` 统一回收；原先用 `window.__DSHUIW_*__` 挡住二次安装的单例模块，改成「新实例先调旧实例的 cleanup（`window.__DSHUIW_UPDATES_CLEANUP__`）摘 DOM」，否则新实例被哨兵挡住、界面永久消失。 ## 更新检查（模块 3） ### 关键经验：pnpm 的 minimumReleaseAge 是主要的静止源（0.1.5 起分成两条路径看） - **`minimumReleaseAge` 有两条独立作用路径**（0.1.4 只写对一半）： 1. **门禁（解析之前）**：`pnpm install/add` 先校验**磁盘上现有的** lockfile，任一 entry 发布时间在窗口内 → **整体中止整个 profile 的安装**，报 `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`（exit 1）；**写精确版本号也救不了**。 2. **解析（门禁之后）**：候选不合法时 pnpm 挑「最新合法版本」（版本没变 → 面板判「暂缓」）；**显式写 `name@版本`** 时打印 `Added 1 entry to minimumReleaseAgeExclude in pnpm-workspace.yaml` 并照常安装——只绕开 ②。 - **豁免表的坑**：`minimumReleaseAgeExclude` 同包名**多条**时只有**靠前那条生效**（非并集：`[pkg@0.69.0, pkg@0.61.0]` 通过、`[pkg@0.61.0, pkg@0.69.0]` 失败）。陈旧条目**静默遮蔽**新条目，成功的未成熟安装又把新条目**追加在末尾**让旧条重新靠前 → 下次安装立刻失败。**成因：0.1.5 前「更新某插件 → 报一长串 pnpm 错误 → 之后所有插件都装不上」。** - **对策（0.1.5）**：host 半区新增归并器 `normalizeReleaseAgeExcludes()`（`lib/index.js`），收敛成「每包一条」：同包多条只留「与 lockfile 锁定版本一致」的那条（否则留靠前那条）；受管包名（profile `dependencies`）唯一条且版本 ≠ 锁定版本 → 删除；非受管不重复的不动。结果恒为原条目的**子集**。触发：加载时 + `POST /api/ui-tweaks/normalize-excludes`（安装成功后/「重新检查」时 fire-and-forget）。约束：只改该段、写前留 `pnpm-workspace.yaml.bak-<时间戳>`、临时文件 + `renameSync` 原子替换、写后重读校验、无变化不写盘、幂等、异常不外抛。 - **0.1.6 收尾**：解析与强制豁免**共用** `excludeBlockOf`（两份复制代码会让两个写者对「块从哪到哪」失配、再造遮蔽条）；备份/原子替换收敛到 `atomicWriteWorkspace`、只留最近 3 份 `.bak`；补 14 条回归测试（`dirOverride` 指向临时目录）：重复折叠/陈旧剪除/裸名豁免/非受管不动/块外字节不变/无变化不写盘/无键/无 lockfile/`.bak` 上限。 - **成熟期硬闸（0.1.6，装前校验）**：预判还在飞时那行仍可点「有新版本」，点下去 `startOne` 用精确版本 spec，而精确版本会被 pnpm 自动写进豁免表并照常安装 → **未成熟版本被静默装进去、没有确认**。现在 `startOne` 在 `installBundle` 前调 `guardMaturity(名字, 目标版本, 放行回调)`：未成熟且非强制 → 不装，落回 cooling（回填成熟时刻 + 技术细节 + 排自动重查）并清空 busy；强制流程写 `forcedNames[name]`（一次性凭据，用后即删、`done()` 终态也清）。判定表（10/10）：未成熟且非强制＝拦；有凭据＝放行并消费；已成熟、registry 无发布时间、packument 失败、目标版本未知（`@latest`）＝放行——后四条**刻意**：数据源不可用不该挡正常更新。 - **客户端「冷静期中」(cooling)**：① 预判：拉该包**全量 packument** 读 `time[版本]`（`//latest` 与 abbreviated packument 都**没有** `time`），`发布时间 + 窗口 > 现在` 即标 cooling；② 反应式：门禁报错里同时有 `published at ` 与 `cutoff `，于是 `窗口 = now − cutoff`、`成熟时刻 = 发布 + 窗口`。反推窗口只接受 (0, 30 天]，越界退回会话默认值。cooling 标签**不可点安装**；`enqueue` 第二道闸只有 `force` 能过，装前还有第三道闸。 - **强制更新（0.1.6，跳过冷静期）**：真机复现（自带 pnpm 11.7.0，客户端 Electron 以 `ELECTRON_RUN_AS_NODE=1` 跑 `pnpm.cjs`，隔离临时工程，样本＝发布 4 小时的 `undici@8.12.1`）： 1. **精确版本 spec 装未成熟版本 → 成功**：pnpm 打印 `Added 1 entry to minimumReleaseAgeExclude in pnpm-workspace.yaml` 并自行写豁免表 → 0.1.5 的「写精确版本也救不了」只对**无污染 lockfile** 成立。 2. **豁免表为空 + lockfile 含未成熟条目**：跑 `install`（无事可做）→ 开头校验、整体失败、**磁盘零改动**；**若安装有活要干，安装照常落地、门禁在结尾才报 exit 1**（T2b/T3c）→ 必须**先预检、拒绝在动手之前**；「先试一下看报什么错」会把 profile 留在「装上了但命令报错」的混乱态。 3. **遮蔽语义确认**：`[陈旧条, 未成熟条]` 失败、`[未成熟条, 陈旧条]` 通过 → 写入必须把目标版本放**块内第一条**。 - 实现：host 侧新增 `POST /api/ui-tweaks/precheck-exempt`（只读预检）与 `POST /api/ui-tweaks/force-exempt`；`forceExemptVersion` 只动豁免段落（目标插块首、其余字节逐字节保留、备份＋renameSync＋写后重读校验；**有意突破**归并器「结果恒为子集」）；`precheckExempt` 只扫 **profile 直连依赖**（lockfile importers）＋发布时刻 10 分钟缓存，列出「未生效豁免且仍在窗口内」的包（传递依赖不扫，漏判靠安装失败时的反应式报错兜底）。客户端三段式：入口 → 预检 → 拦路者清单/二次确认 → 写豁免 → 安装；`enqueue(name, { force: true })` 是唯一放行冷却行的入口。 - 验证：host 隔离 15/15（写入位置、字节保留、去重、预检筛选、目标跳过）；UI 渲染 9/9；真机路由 `precheck-exempt` 返回 `{ok:true,blocked:[]}`，`local-plugins` 正常。 - **cooling 文案（0.1.6 定稿）**：列表默认只有**一句话**——`0.70.0 还需等待 10 小时 40 分才能更新（10-15 07:54 到期，点标签看详情）`。完整解释走 `coolingReasonText(detail, windowMs)`，**只在点「冷静期中」标签展开时渲染**（`.dtl`）：为什么等（dsh 的 24 小时策略讲成人话）→ 硬装的后果（连坐整个 profile，故不提供直接安装）→ 到点自动恢复 → 末尾附原始诊断（预检＝registry 记录，反应式＝pnpm 报错）。等待期已过 / 结束时间未知各有文案。换行由 `.why` 的 `white-space:pre-wrap` 呈现。 - **到期自动重查（0.1.6）**：`scheduleCoolingRefresh(name, matureAt)` 给 cooling 行排到点（+3s 缓冲）的 `checkOne(name)` 定时器（按包名去重）；触发点＝`applyCoolingGuess` 落 cooling 后、`judge` 冷却分支落 cooling 后；上限（约 24.8 天）之外不排。 - **兼容门禁（0.1.7，借鉴 plugin-manager）**：新版 registry 清单可能声明最低 DSH 版本（`dsh.engines.dsh` → 顶层 `engines.dsh` → `peerDependencies["@deepseek-ai/dsh"]`）；本机版本由 host 半区读 `profileContext.installAnchor` 的清单，兜底读 profile 里的 `@deepseek-ai/dsh`。低于要求 → 标 **「DSH 不符」**、不给点、不计入「全部更新」。**只认 `>=x.y.z`**；未声明、写法不认识（`^`/`~`）、读不到版本 → 一律不拦。 - **更新＝卸载 + 安装（0.1.8）**：官方 `installBundle` 在**开着 HMR 的运行时**里会直接拒绝已装过的包 —— `@deepseek-ai/dsh-plugin-manager/lib/index.js` 的 `installBundle`：`if (this.ownerContext.get("hmr") !== void 0 && known !== void 0 && Object.hasOwn(before, known)) throw new ManagementFailure("already-installed")`；判据是「包名已在 profile 依赖里」，**与版本无关**（所以 0.1.7 前直接 `installBundle("name@新版本")` 的更新必然以 `already-installed` 收场）。官方工具说明本身就写着：换版本要 **先 `removeBundle` 再 `installBundle`**，官方 UI 也只有「装 / 卸 / 开关」、没有更新。对策 `installBundleEx()`：① 先直接装（没有 HMR 的运行时一步到位、不碰卸载）；② 只有被 `already-installed` 拒绝时才 `removeBundle(包名)` → 再装；③ 卸载也被拒就**把原始拒绝原样报出**（不掩盖原因，也别白拆一次）。**失败回滚**：卸载成功过而结果落 `failed`/`cancelled` 时用原版本 `name@busyBefore` 装回去；`unknown` 不回滚（安装可能仍在飞，硬回滚会打架）改为在文案里提醒确认。错误码统一翻人话（`installCodeText`：already-installed / incompatible-version / not-removable / bundle-in-use / operation-error / stale-approval …），带错误码的拒绝不再走「回包丢了」的恢复逻辑。**两种形状都要认**（`isAlreadyInstalledResult`）：① 远程 API 的拒绝信封 `{ok:false, error:{code}}`；② **桌面端进程内管理器把它报成「应用层失败」** —— `{ok:true, value:{application:"failed", error:{code:"already-installed"}}}`（`failureText` 取的就是 `st.error.code`，真机上报的正是这条，0.2.1 第一版只认①所以没生效）。测试：`installBundleEx` 四条路径（直接成功 / 拒绝信封转两步 / 别的码不卸载 / 卸载被拒）+ **失败信封形状触发两步** + 判定谓词六种输入 + 错误码表 + 回滚与「不再单步安装」的静态断言（client 60/60）。 - **自更新必须走 CLI（0.2.3 修）**：`removeBundle` 在 HMR 运行时里先 `selectBundle(name,false)` + `reload()`（**把本插件的条目卸掉**），`bundle-in-use` 守卫随后才检查、此时已放行 —— 于是插件被真正卸载；而负责第二步「装回来」的正是本插件自己的 client 半区，插件一卸载 remote 绑定即失效（`cannot get required service … in inactive context`），真机表现就是**「卸完就结束了」**。没有 HMR 的运行时反而会被 `stop-profile` 挡住，所以这个坑只在桌面客户端/默认 web 出现。对策：`enqueue()` / `startOne()` 对 `SELF_NAME` 直接短路（**绝不入队、绝不调 installBundle/removeBundle**），标签改成「手动更新」，点开给一条 CLI 命令 + 复制按钮；CLI 的 `dsh plugin … add` 原样转发 pnpm（`runProfilePnpm`，带 `withFileLock(profile/package.json)`），**不经过安装/卸载守卫**，因此不需要先卸载自己。命令来源：host 的 `/api/ui-tweaks/local-plugins` 新增 `selfUpdate: {desktop, profile, cli}`（桌面端用 `dirname(process.execPath)/resources/runtime/cli/bin/dsh.cmd`，web 用 PATH 上的 `dsh`；`cli` 不存在时留空，前端退化成 `<客户端安装目录>` 占位写法）。路径由运行中的 host 用 `process.execPath` 推导，**不随包分发**——每个用户看到的是自己机器上的安装路径。「全部更新」的计数与执行都排除自己，表头单独提示「本插件需手动更新」。 - **0.2.1 补丁二：失败信封也会骗人 + 等卸载落地 + 退避重试**：① `resultFailure()` 统一判定"这次调用的结果到底成没成" —— **不能只看 `ok`**：桌面端把失败包成 `{ok:true, value:{application:"failed", error:{code}}}`，0.2.1 第一版用 `rm.ok !== false` 判"卸载成功"，于是**卸载被拒被当成成功**、随后重装又失败，最终还假报"已回滚到 0.4.6"、把真原因（`not-removable` 之类）吞掉。现在失败信息会把"卸载被拒（X）"如实带出。② `removeBundle` 会触发一次 profile 重载；真机上"卸载刚返回就重装"仍被打回 `already-installed`（新请求可能还在上一代管理器里跑、读的是卸载前的清单 —— 而紧接着的回滚安装却成功，差别只在"中间隔了一次重载"）。对策：`waitBundlesGone()` 轮询 `listBundles()` 直到清单里没有该包（10s 上限、400ms 间隔），再 `installRetrying()` 退避重试（3 次 × 1.5s）；拿不到清单就当"没有"，绝不把更新卡死。测试：新增"等清单消失 + 重试到成功"的调用序列断言、"卸载被拒不会再被当成功"、"一直没消失就到点返回 false"、`resultFailure` 六种输入（client 64/64）。 - **「Auto review」提醒条（0.1.7，只读不改）**：DSH 0.2.0-rc.2 的已知缺陷 —— `auto` 模式的会话会让 `permissionPresets` 在热重载（装/更新插件就会触发）时构造失败（`pinInitialPermission` 构造期遍历已驻留会话，`autoAdmit` 还没注册就抛错），表现为装插件报一长串错、连带 `sessionProjections` 也起不来，要重启客户端才恢复。面板顶部加琥珀色提醒，**只读检测**「是否有驻留会话的 permissions 投影 currentValue === 'auto'」（读法同官方权限面板：`ctx.get('sessions')` → `list.getSnapshot().ids` → `binding(id).session.projections.faceOf('permissions').getSnapshot()`）；**不写设置、不拦操作**。 - **0.2.1-rc.2 复核（2026-10-18）**：预设标识仍是 `AUTO_PRESET = "auto"`，界面文案改叫「自动审查」，判定串 `currentValue === 'auto'` **不受影响**；旧缺陷的 throw 仍在，但 auto-review 集成新增卸载时的收尾迁移（先把所有 auto 会话改成 `danger-full-access` 再退出），触发窗口收窄、日志无该错误痕迹。该模式还有**调用前审查**：服务不可用或限流时工具调用**直接被拒、工具体不执行**（`503` 与 `429 请求过于频繁（limit 30）`）。 - **本机环境**：dsh 用**自带的 pnpm 11.7.0**，**不是** PATH 上那个（PATH 是 11.21.0）；排查必须用前者复现，否则结论会反过来。自带运行时在 **`<客户端安装目录>/resources/runtime/`**：`pnpm/`（11.7.0 包）、`bin/node`（shim，exec `$DSH_DESKTOP_NODE_EXECUTABLE`＝客户端 Electron + `ELECTRON_RUN_AS_NODE=1`）、`versions.json`（node 24.18.1 / pnpm 11.7.0）。复现：`ELECTRON_RUN_AS_NODE=1 npm_config_minimum_release_age=1440 "<客户端>/DeepSeek Harness.exe" --expose-internals "<客户端>/resources/runtime/pnpm/bin/pnpm.cjs" add @ --registry=https://registry.npmjs.org/`。 - 参考实现：社区分叉版 `@linxin666/dsh-client-ui-plugin-manager` 同样先 `fetchManifest` 再 `installBundle(name@version)`——它「能更新」不是绕过门禁，而是用了精确版本。 ### 本地包识别 = host 路由为主，404 签名兜底 - `listBundles()` 不透传安装来源（`installed` 不是 spec 字符串），发布到 npm 的本地包（如 `@nimoxie/dsh-model-organizer`）连 registry 404 签名都不命中 —— 故 host 半区挂 `GET /api/ui-tweaks/local-plugins`（读 profile `package.json` 的 dependencies：**local** = `link:`/`file:` 标「本地链接」，**remote** = `git:`/`github:`/`http` 标「Git 直装」；仅回环放行）；0.1.5 起还有 `POST /api/ui-tweaks/normalize-excludes`。两者都**不参与 registry 比对**（如 `dsh-ego-browser` 有 `github:` 声明、registry 也有 0.8.6，装的仍是仓库源码）。client 每轮先取名单，取不到（host 未重启）再退回 404 签名。**改 host 半区必须重启 dsh/客户端**。 - profile 目录定位：从 `import.meta.url` 向上找带 `dsh.profile.bundles` 且包含自身的 package.json（npm 直装必命中）；软链安装时模块解析到 profile 外，退回 `DSH_HOME/profiles/*` 扫描，多 profile 命中按 `ELECTRON_RUN_AS_NODE` 区分 desktop/web。 ### 其它要点 - **更新主路径全部走官方 remote API**：`pluginManager.listBundles()`、`installBundle("<名>@版本", { enabled, requestId })`（更新）、`waitForInstall(requestId)`（仅响应丢失恢复）、`cancelInstall(requestId)`（取消，回 `{status}`）。 - **`installBundle` 等装完才返回，返回值即终态**（0.1.4 纠正）：信封 `{ok, value}`，`value` 含 `{changed, application, stage, target, enabled?, error?, warnings?, packageResult?, bundle?, pendingBuilds?, approvedBuilds?, registries?, failedAt?}`；官方插件页同样 `await installBundle(...)` 后 `settleInstall(result.value)`。 - **`waitForInstall` 不是进度轮询器**（0.1.3 的理解是错的，正是「更新永远超时」的成因）：它只在**响应丢失后**恢复同一请求，请求不在活动中返回 `null` 且**已完成结果不保留**。装完再轮询只会空转到 240s 看门狗、丢掉真实结果。0.1.4 起只读 `res.value`，仅信封失败（`res.ok === false`）才恢复一次，仍 `null` 就报「未能确认」。 - **终态判定读 `application`**：`applied` / `restart-required`（都算成功，后者提示重启）→ 回读版本；`cancelled` → 退回「有新版本」；`failed` → 标「更新失败」，把 `error.code`（译中文）+ `error.diagnostic` + `packageResult.kind/exitCode/output/logPath` + `pendingBuilds` + `failedAt` 写进行内 `why`（带 `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` 时判 `cooling`，反推窗口记进会话复用）；`overridden` → 可重试；未知值按「结果未知」。 - **回读版本是唯一成功判据**：`listBundles()` 里读到该行版本且**与安装前不同**才判「已是最新」。只用 `pluginManager.listBundles()`（`pluginInventory` 只有 `list()` 没有 `listBundles`，会造成假阳性）；清单短暂不可用时重试 3 次（1.5s）。基准 `busyBefore` 在 `startOne` 抓取。 - **registry 比对在浏览器直连**：`registry.npmjs.org` 带 CORS *，逐包**串行** fetch `/latest`（0.2.2 起 12 秒超时，见下条）。代价：安装走 `.npmrc` 的 npmmirror，镜像未同步的新版本会「面板说有、装时报 no-matching-version」。 - **取消要分清对象**（0.1.4 修）：排队项取消只摘出自己（`cancelQueued`）；在装项取消才 `cancelInstall(requestId)`，且**保留队列**，落定后 `done() → pump()`。旧实现 `requestCancel` 一句 `queue = []` 清空全队列，导致「等待更新」的项全退回「有新版本」——这是「取消一项后其余项不更新」的成因。回值 `{status: cancelled|not-running|too-late}`。 - **重新检查必须回填在飞状态**（0.1.4 修）：`checkNow` 重建 `rows` 会把「更新中/等待更新」抹成「有新版本」而 `busyName`/`queue` 还在，点那行撞上 `enqueue` 的 `name === busyName` 保护而**静默无反应**（「重新检查后无法更新」的成因）。修法：重建后立刻 `reconcileInstallStates()` 盖回 busy/queuing，这两种行不参与比对。 - **看门狗按「进度」而不是「总时长」判活**（0.2.2 修）：旧实现固定 240 秒、从调用开始计时；真机一次重链 44 个包的卸载跑了 **5 分 08 秒**就被误判超时。更糟的是判超时后立刻 `pump()` 下一项、旧请求还在跑，两条 pnpm 叠在 profile 锁上——表现就是「全都卡住」。现在：`ctx.remote.$on("plugin-manager/install-log|install-state|changed")` 当心跳（拿不到就退回纯计时）；无输出 90s 只在行内提示「仍在运行」；单项 15 分钟才判超时，判超时后仍等底层链收尾（最多再 5 分钟）才放行队列。放行闸是 `releaseBusy()`：`busyChainDone`（底层链收尾）+ `busyFinished`（终态已判定）同时成立，才清 busy 并 `pump()`。 - **unknown 终态必须复查并回滚**（0.2.2 加）：判超时/结果未知且本次**中途卸载过**时，旧实现只写一句「请确认」，而后续「装回」那一步的结果会因为 `settled` 被丢弃 —— 真机上 `@linxin666/dsh-session-archive` 就是这样被卸掉后没装回来。现在 `recoverAfterUnknown()` 主动 `listBundles()` 复查：不在清单里就用 `busyBefore` 自动装回，并把结果写进行内文案。 - **registry / host 请求必须有超时**（0.2.2 加）：`fetchLatest`（`/latest`）12 秒、host 来源名单 8 秒。比对是串行的，一个挂起的请求会让后面所有包永远停在「比对中 …」；`fetchLocalNames` 更靠前 —— 它不回调，整条比对链根本不会开始。 - **清单里「装了但读不到」的行要带原因**（0.2.2 加）：`listBundles` 对读不到 `package.json` 的包仍会返回一行（带 `error`、没有 `version`），面板原来只显示「无法比对」。现在把 `error.code` / `availability: "missing"` 写进 `why`，悬停就能看出是文件缺失还是清单坏了。 - **总看门狗只是兜底**（0.1.4 起，0.2.2 重写）：正常路径一次 `installBundle` 定案，不必等它；它只兜 fetch/网络这类异常分支。 - **`enabled` 用清单真实状态**：传 `!(row.enabled === false)`，保留用户手动禁用（旧实现一律 `enabled: true`，会重新启用）。 - **更新完仍是关闭的插件给一键启用**（0.2.2 加）：官方安装默认不启用（`installBundle` 的 `enabled` 默认 false），面板又刻意保留原状态，所以「原本关着的插件」更新完仍然关着。`finishOne` 回读清单时记下这次更新过、且 `enabled === false` 的名字（`updatedOff`），重启提示栏里长出一枚橙色按钮（`.fbtn.fgo`，与冷静期详情里的「强制更新」同款），点它**串行**调 `pluginManager.setBundleEnabled(name, true)`（官方插件页总开关同款 API）；成功即清标记，失败写红字并留按钮可重试。只动本次更新过的包，不碰用户没更新的插件。 - **豁免表写 YAML 必须能过 pnpm 的解析器**（0.2.2 修）：`minimumReleaseAgeExclude` 里的 scoped 包名不能做 plain scalar —— `@scope/pkg@1.2.3` 裸写会让整个 `pnpm-workspace.yaml` 解析失败（`bad indentation of a sequence entry`），后果是 profile 里**所有** pnpm 操作（安装、卸载）全部 `operation-error`，面板只会显示「卸载被拒（operation-error）」，看不出真因。现在新条目统一经 `yamlScalar()` 输出（仅必要时加单引号、内部单引号翻倍），归并器还会顺手修复历史上写坏的行；客户端在卸载被拒时把 `error.diagnostic` / `packageResult.output` 首行 + 日志路径带进失败文案。 - **强制更新的豁免要到期才删**（0.2.2 加）：pnpm 每次安装都拿**整个 lockfile** 校验供应链策略，被强制装上的版本还没满 24h 时删掉豁免，之后所有 pnpm 操作都会被整体拒绝（比留着更糟）。所以客户端在写豁免成功后调 `POST /api/ui-tweaks/schedule-exempt-cleanup` 登记「成熟时刻 +60s」；host 侧 `dropExemptVersion()` 到点删表项，清单落盘在 `profile/ui-tweaks/exempt-pending.json`，客户端重启后按记录重排（已到期的立刻删）；删失败保留记录、10 分钟后再试。 - **面板滚动条参照对话区那条自绘滚动条**（0.2.2 加）：原生滚动条在 Windows 上会占列表 17px 宽，把行内容整体挤窄。面板列表隐藏原生条（`scrollbar-width:none` / `::-webkit-scrollbar{width:0}`），在 `.rowswrap` 右缘绝对定位 12px 轨道 + `.sbthumb`；视觉走 `.sbthumb::after`：`color-mix(in srgb,currentColor 36%,transparent)`，悬停/拖动加宽到 9px、60%（与模块 2 同一配方，颜色跟随主题文字色，不再靠容器 opacity）。**可拖动**：PointerCapture + 按下点偏移（不是拇指中心跳过来），点轨道先把拇指中心挪到点击处再顺势进入拖动；pointermove 同步写 `scrollTop`，`scroll` 事件回纠几何；轨道上滚轮转发给真容器。`paint()` 每次重画后 `bindSb()+syncSb()`（innerHTML 换过就重绑），resize/重排后补一次 `syncSb`。 - **失败原因要可见**：`fail`/`unchanged`/`unconfirmed`/`error`/`cooling` 行下多渲染 `.why`（只放 `title` 悬停等于没显示）。0.1.5 起先 `stripAnsi`（CSI/OSC/控制字符/CRLF，否则首屏是 `鈺?` 残渣），`diagnostic` 与 `packageResult.output` 互相包含只留更完整的一份。 ## 动画修复（模块 4） - **原理**：Windows「动画效果」关闭 → Chromium 报 `prefers-reduced-motion: reduce`，dsh 的 40 处（17 包）`@media (prefers-reduced-motion: reduce)` 规则关掉动画。媒体查询的求值删不掉，但规则删得掉：dsh 的 CSS 全经 `