@nimoxie/dsh-ui-tweaks 0.1.3 → 0.1.4

package/{DEVELOPING.md → DEVELOPMENT.md}

@@ -45,12 +45,18 @@
 
 ### 其它要点
 
-- **更新主路径全部走官方 remote API**（host 半区只挂一条本地包识别路由）：`pluginManager.listBundles()`（清单+版本）、`installBundle("<名>@版本", { enabled: true, requestId })`（更新）、`waitForInstall(requestId)`（进度）、`cancelInstall(requestId)`（取消）。`installBundle` 的第二参官方还传了 `registry`（来自 `pluginManager.registries()`），本插件省略——若某天报 registry 缺失，先补它。
-- **registry 比对在浏览器直连**：`registry.npmjs.org` 带 CORS *（实测），逐包**串行** fetch `/latest`，不打并发。
-- **装完必须回读实际版本**：回读**只用 `pluginManager.listBundles()`**——`pluginInventory` 只有 `list()` 没有 `listBundles`，先取它掉进「回读版本失败」假阳性（踩过）；装完瞬间清单可能短暂不可用，重试 3 次（1.5s 间隔）再下结论。重试后仍读不到就直接 mark「已发起·未确认」（可点重查）。
-- **更新严格串行**：pnpm 对 profile 的 package.json 有文件锁，并发发起不会真并行、只会排队。队列顶项标「等待更新」，正在装的标「更新中 …」，两者都可点取消。
-- **总看门狗（0.1.3）**：`startOne` 入口起 240s 定时器，`finish` 里 `clearTimeout`——覆盖 fetchLatest（现场查 registry，fetch 本身无超时）与 specPromise（原先无 catch）这两段不设防的异步；超时先 `finish(false, "更新超时…")` 再 `cancelInstall(busyReq)`。
-- **`waitForInstall` 的返回形态已实测收紧（0.1.3，从 app.asar 的 zod schema 解出）**：终态读 `application`（`applied` / `restart-required` / `failed` / `cancelled` / `overridden`），进行中读 `stage`（`remove` / `install` / `enable`，行内 why 显示「阶段：…」），失败定位读 `failedAt`（`registry` / `spec-host`）。原先按 `phase/state/status/ok` 猜的形状全都不存在——那正是更新中无限挂起的原因：终态永远匹配不上，且更早的 fetchLatest/specPromise 两段异步在 240s 兜底之前就不设防。
+- **更新主路径全部走官方 remote API**（host 半区只挂一条本地包识别路由）：`pluginManager.listBundles()`（清单+版本）、`installBundle("<名>@版本", { enabled, requestId })`（更新）、`waitForInstall(requestId)`（**仅**响应丢失后的恢复）、`cancelInstall(requestId)`（取消，回 `{status}`）。
+- **`installBundle` 是「等到装完才返回」的调用，它的返回值就是终态**（0.1.4 的关键纠正）：remote 信封是 `{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`，而且**已完成的结果不保留**。`installBundle` 已经 await 到装完，此时再轮询 `waitForInstall` 必然一路读到 `null` → 空转到 240s 看门狗 → 面板报「更新超时」，真实结果（成功或 pnpm 报错）全被丢掉。0.1.4 起：正常路径只读 `res.value`；**仅当信封本身失败（`res.ok === false`，结果未知）**才调一次 `waitForInstall` 恢复，仍为 `null` 就如实报「已发起·未确认」。
+- **终态判定读 `application`**：`applied` / `restart-required`（都算成功，后者提示重启）→ 回读版本核对；`cancelled` → 该行退回「有新版本」（取消不是失败，仍可重试）；`failed` → 行标「更新失败」，并把 `error.code`（译成中文）+ `error.diagnostic` + `packageResult.kind/exitCode/output/logPath` + `pendingBuilds` + `failedAt` 一起写进行内 `why`；`overridden` → 提示被覆盖、可重试；未知值一律按「结果未知」处理，不硬判成功。
+- **回读版本是唯一成功判据**：只有在 `listBundles()` 里读到该行版本、且**与安装前不同**时才判「已是最新」。回读**只用 `pluginManager.listBundles()`**——`pluginInventory` 只有 `list()` 没有 `listBundles`（踩过，会造成「回读版本失败」假阳性）；装完瞬间清单可能短暂不可用，重试 3 次（1.5s 间隔）。比对基准 `busyBefore` 在 `startOne` 抓取，**不受中途「重新检查」重建行的影响**。
+- **registry 比对在浏览器直连**：`registry.npmjs.org` 带 CORS *（实测），逐包**串行** fetch `/latest`，不打并发。代价要知道：比对源是 npmjs，而安装走 pnpm 自己的 registry（本机 `.npmrc` 指向 npmmirror）——镜像尚未同步到的新版本会「面板说有、装时报 no-matching-version」（见「待办」）。
+- **取消要分清对象**（0.1.4 修）：排队项点取消只把它自己摘出队列（`cancelQueued`）；在装项点取消才 `cancelInstall(requestId)`，且**保留队列**，等这次落定后 `done() → pump()` 接着装下一项。旧实现 `requestCancel` 里一句 `queue = []` 把整个队列清空，于是「等待更新」的项全部退回「有新版本」不再开始——这就是「取消一项后，等待的项不更新、反而变回有新版本」的真因。`cancelInstall` 的回值 `{status: cancelled|not-running|too-late}` 也要读：`too-late` 说明已进入应用阶段、取消不掉，得如实告诉用户。
+- **重新检查必须回填在飞状态**（0.1.4 修）：`checkNow` 重建 `rows` 会把「更新中/等待更新」抹成「有新版本」，而 `busyName`/`queue` 仍在——此时点那一行会撞上 `enqueue` 的 `name === busyName` 保护而**静默无反应**（这就是「重新检查后无法更新」的真因），真正在装的那一项也失去取消入口。修法是重建行后立刻 `reconcileInstallStates()` 把 busy/queuing 盖回去，且这两种行不参与 registry 比对。
+- **总看门狗（0.1.4 起只是兜底）**：正常路径一次 `installBundle` 就定案，不必再等 240s；看门狗只覆盖 fetchLatest（现场查 registry，fetch 无超时）这类异常分支，触发时报「结果未知」并 `cancelInstall`。
+- **`enabled` 用清单里的真实状态**：`installBundle` 的 `enabled` 传 `!(row.enabled === false)`，保留用户手动禁用的选择（旧实现一律 `enabled: true`，会把禁用的插件重新启用）。
+- **失败原因要可见**：`fail` / `unchanged` / `unconfirmed` / `error` 行在行下多渲染一行 `.why`——只放在 `title` 悬停提示里，等于 pnpm 的报错没显示。
+
 
 ## 动画修复（模块 4）
 
@@ -73,7 +79,11 @@
 - [ ] 有更新时按钮加角标（现在要点开面板才看得到）。
 - [ ] i18n（`ctx.locale.register(NS, {zh, en})`，照 dsh-model-organizer 写法）。
 - [ ] 会话内重启 dsh 的入口（需要 host 配合或官方重启 API，未调研）。
-- [x] 0.1.3：`waitForInstall` 终态已按实测收紧（application/stage/failedAt）+ 全程总看门狗。
+- [x] 0.1.3：`waitForInstall` 终态按 zod schema 收紧了字段名（`application`/`stage`/`failedAt`）+ 全程总看门狗。**注意：这一版的结论是错的**——字段名猜对了，但把 `waitForInstall` 当进度轮询器用，而它只做「响应丢失恢复」；见 0.1.4 条目。
+- [x] 0.1.4：终态改读 `installBundle().value`（`waitForInstall` 只在信封失败时兜一次）；取消不再清空队列、排队项可单独取消；`checkNow` 回填 busy/queuing；失败原因（`error`/`packageResult`/`pendingBuilds`）落到面板；`enabled` 沿用清单里的真实状态。
+- [ ] 比对 registry 与安装 registry 对齐：面板查 `registry.npmjs.org`，pnpm 走 `.npmrc`（npmmirror）。镜像未同步的新版本会造成「面板说有新版、装时报 no-matching-version」。可用 `pluginManager.registries()` 取实际 registry 再比对（需先确认镜像的 CORS）。
+- [ ] `pendingBuilds` 的「允许这些脚本并重试」入口（`installBundle(spec, { approvedBuilds })`）。现在只在失败行里列出待授权名单。
+- [ ] `removable === false` / `optional` / 带 `readOnlyReason` 的 bundle 在面板隐藏或标注——否则点了会以 `management-required` 失败。
 - [ ] `installBundle` 的 `registry` 参数补齐（官方传了，本插件省略）。
 - [ ] 插件被禁用/卸载时的运行时清理（目前 DOM 残留到页面刷新为止）。
 

package/README.md

@@ -56,6 +56,8 @@ dsh plugin --profile <profile> add link:/absolute/path/to/dsh-ui-tweaks
 - 非 npm 来源的插件没有可比的 registry 版本，直接跳过比对：`link:` / `file:` 本地路径标「本地链接」；`git:` / `github:` / `http` 直装标「Git 直装」（例如 `github:Fisfzy/dsh-ego-browser` 会显示为 Git 直装，即使 npm 上有同名包，装的也是仓库源码、与 npm 版本不是一回事）
 - `@deepseek-ai` 官方插件直接从检查列表里剔除：它们的更新由 dsh 本体流程负责
 - 更新走 profile 内的插件安装接口，与官方插件管理页同源；安装按 registry 解析出的**精确版本号**发起（而非 `@latest`），不受 pnpm 发布时长策略（minimumReleaseAge）拦挡，刚发布的版本也能装
+- 更新失败时行内会直接给出原因（pnpm 的输出、退出码与日志路径），不再只说一句「失败」；失败行可点击重试。取消只作用于你点的那一项：取消排队的项不影响正在装的，取消正在装的也不会丢掉后面排队的（它会自动接着装）
+- 面板比对用的是 npm 官方 registry，而安装走你本机 pnpm 配置的源（如 npmmirror 镜像）。镜像尚未同步到的新版本会出现「面板说有新版、装时报找不到版本」，稍后镜像同步后重试即可
 - 个别插件（如社区插件管理页扩展）自带单独的「检查更新」入口，与本插件的检查互不关联，结果可能不同
 - 与启动器 dsh-web-shell 的分工：对话区滚动条、宽表格修复等界面增强已由本插件接管，dsh-web-shell 自身不再注入；其「检查更新」按钮仍负责 **dsh 本体**的比对与升级提示
 
@@ -65,4 +67,4 @@ MIT
 
 ---
 
-想自己改这个插件、或者想了解它在内部怎么实现的，见 [DEVELOPING.md](./DEVELOPING.md)。
+想自己改这个插件、或者想了解它在内部怎么实现的，见 [DEVELOPMENT.md](./DEVELOPMENT.md)。

package/lib/client.js

@@ -14,7 +14,7 @@ window.__ModuleLoader__.load({
     const module = { exports: {} };
     const exports = module.exports;
 
-    const BUILD = "0.1.2";
+    const BUILD = "0.1.4";
 
     /* 每个模块的注册各套一层 guard：失败只记 warn（座位/模块失败模式是「静默消失」，
        必须主动吭声；但不能让一个模块的异常打断同文件里其它模块的 apply）。 */
@@ -474,6 +474,8 @@ window.__ModuleLoader__.load({
       var queue = [];             // 待更新名单（串行队列）
       var busyName = "";          // 正在更新的那个
       var busyReq = "";
+      var busyBefore = "";       // 本次安装前该行的版本（回读比对基准，不受中途重查影响）
+      var busyLatest = "";       // 本次安装解析出的目标版本（取消后退回「有新版本」要用）
       var cancelling = false;
       var checking = false;
       var listeners = [];         // 面板重绘订阅（面板未开时也维护状态）
@@ -526,11 +528,13 @@ window.__ModuleLoader__.load({
                 return {
                   name: name, version: ver, latest: "",
                   state: isLocalSrc(src) ? "local" : (isRemoteSrc(src) ? "remote" : (ver ? "checking" : "unknown")),
-                  src: src, why: ""
+                  src: src, enabled: b.enabled !== false, why: ""
                 };
               }).filter(function (x) { return x.name; })
               /* 官方 @deepseek-ai 插件由 dsh 本体更新流程负责，直接从检查列表里剔除 */
               .filter(function (x) { return !/^@deepseek-ai\//.test(x.name); });
+              /* 与在飞的安装对齐（见 reconcileInstallStates）：重查不得抹掉「更新中/等待更新」 */
+              reconcileInstallStates();
               checking = false;
               emit();
               // 先向 host 半区要非 registry 直装名单，命中的行直接标「本地链接」或「Git 直装」
@@ -577,144 +581,228 @@ window.__ModuleLoader__.load({
         waitScope();
       }
 
-      /* ---- 更新执行：串行队列；装完回读实际版本判定真实结果 ---- */
+            /* ---- 更新执行：串行队列 ------------------------------------------------
+       * installBundle 是「等到装完才返回」的调用：返回信封的 .value 就是终态对象
+       * （application / stage / target / error / packageResult / pendingBuilds …），
+       * 官方桌面端 UI 也是 await 它之后直接拿 .value 定案。
+       * waitForInstall 只用于**响应丢失后的恢复**：请求不在活动中时返回 null，
+       * 且「已完成的结果不保留」。把它当进度轮询器（旧实现）必然永远读到 null、
+       * 一路空转到 240s 看门狗 —— 这就是「更新总是超时」的真因。
+       * 正常路径只读 res.value；仅当信封本身失败（res.ok === false，结果未知）才用
+       * waitForInstall 兜一次，仍为 null 就如实报「结果未知」。
+       * ------------------------------------------------------------------ */
+      function findRow(name) {
+        for (var i = 0; i < rows.length; i++) { if (rows[i].name === name) { return rows[i]; } }
+        return null;
+      }
+      function msgOf(e) { return String((e && e.message) || e); }
+
+      /* 重新检查后把在飞状态盖回新行：否则「更新中/等待更新」会被抹成「有新版本」，
+         点它会撞上 enqueue 的 busyName 保护而毫无反应（表现为「重新检查后无法更新」），
+         真正在装的那一项也失去取消入口。busy / queuing 行不参与 registry 比对。 */
+      function reconcileInstallStates() {
+        if (busyName) { var b = findRow(busyName); if (b) { b.state = "busy"; b.why = ""; } }
+        for (var i = 0; i < queue.length; i++) {
+          var q = findRow(queue[i]);
+          if (q) { q.state = "queuing"; q.why = ""; }
+        }
+      }
+
+      var ERROR_CODE_TEXT = {
+        "management-required": "该 profile 由桌面端独占管理，不能从这里安装",
+        "unaddressable": "插件地址无法解析",
+        "unknown-plugin": "未知插件",
+        "invalid-spec": "安装 spec 非法",
+        "ambiguous-install": "目标不明确，无法确定要装哪个包",
+        "not-bundle": "该包不是 dsh 组合包（缺少 bundle patch）",
+        "not-removable": "该包不可卸载",
+        "stop-profile": "profile 正在停止，请稍后重试",
+        "bundle-in-use": "插件正在使用中，无法替换",
+        "stale-approval": "构建脚本授权已失效，需重新授权",
+        "incompatible-version": "版本与当前 dsh 不兼容",
+        "operation-error": "安装命令执行失败（pnpm 非零退出）"
+      };
+      /* 失败原因必须落到面板上：旧实现只回一句「安装失败」，把 pnpm 的真实报错
+         （如 ERR_PNPM_UNEXPECTED_STORE）连同 logPath 一起丢掉，用户只看到「超时」。 */
+      function failureText(st) {
+        var parts = [];
+        var code = st && st.error && st.error.code;
+        parts.push("安装失败" + (code ? "：" + (ERROR_CODE_TEXT[code] || code) : ""));
+        var diag = st && st.error && st.error.diagnostic;
+        if (diag) { parts.push(String(diag)); }
+        var pr = st && st.packageResult;
+        if (pr) {
+          if (pr.kind) { parts.push("分类：" + pr.kind); }
+          if (pr.exitCode) { parts.push("pnpm 退出码 " + pr.exitCode); }
+          var out = String(pr.output || "").trim();
+          if (out) { parts.push("输出：" + out.slice(-800)); }
+          if (pr.logPath) { parts.push("日志：" + pr.logPath); }
+        }
+        var pend = st && st.pendingBuilds;
+        if (pend && pend.length) { parts.push("待授权的构建脚本：" + pend.join("、") + "（需在官方插件页授权后重试）"); }
+        if (st && st.failedAt) { parts.push("失败环节：" + st.failedAt); }
+        return parts.join(" ｜ ");
+      }
+      function lostReplyText(res) {
+        var m = res && res.error && res.error.message;
+        return "安装请求未返回结果" + (m ? "：" + String(m) : "");
+      }
+
       function enqueue(name) {
+        if (name === busyName) { return; }        // 正在装它（行内已是「更新中」态）
         if (busyName) {
-          if (queue.indexOf(name) < 0 && name !== busyName) { queue.push(name); setRow(name, { state: "queuing" }); }
+          if (queue.indexOf(name) < 0) { queue.push(name); setRow(name, { state: "queuing" }); }
           return;
         }
         queue.push(name);
         pump();
       }
       function pump() {
+        if (busyName) { return; }
         var name = queue.shift();
         if (!name) { return; }
         startOne(name);
       }
+      /* 排队项取消：只把它自己摘出队列，其余照旧等待。 */
+      function cancelQueued(name) {
+        var i = queue.indexOf(name);
+        if (i < 0) { return; }
+        queue.splice(i, 1);
+        setRow(name, { state: "update", why: "" });
+      }
+
       function startOne(name) {
+        var row = findRow(name);
         busyName = name;
+        busyBefore = row ? row.version : "";
+        busyLatest = (row && row.latest) || "";
         busyReq = uuid();
-        setRow(name, { state: "busy" });
+        setRow(name, { state: "busy", why: "" });
         emit();
         var pm = pickService(null, "remote.pluginManager");
-        if (!pm) { finishOne(name, false, "remote.pluginManager 不可用"); return; }
+        if (!pm) { finishOne(name, "failed", "remote.pluginManager 不可用"); return; }
         var settled = false;
-        /* 总看门狗：无论卡在 fetchLatest / installBundle / 轮询哪一段，240 秒未结束就判超时并请求取消 */
+        /* 看门狗只作兜底：正常路径一次调用就定案，不等它。 */
         var watchdog = setTimeout(function () {
-          finish(false, "更新超时（240 秒未结束）");
-          try { var pm2 = pickService(null, "remote.pluginManager"); if (pm2 && pm2.cancelInstall && busyReq) { pm2.cancelInstall(busyReq); } } catch (err) {}
+          finish("unknown", "更新超时（240 秒未结束）；结果未知，请点「重新检查」确认");
+          try { var pm2 = pickService(null, "remote.pluginManager"); if (pm2 && pm2.cancelInstall && busyReq) { pm2.cancelInstall(busyReq); } } catch (e) {}
         }, 240000);
-        function finish(ok, why) {
+        function finish(kind, why) {
           if (settled) { return; }
           settled = true;
-        clearTimeout(watchdog);
-          finishOne(name, ok, why || "");
+          clearTimeout(watchdog);
+          finishOne(name, kind, why || "");
         }
-/* 安装 spec 用面板已解析的精确版本（`name@版本`）而不是 @latest：
-         * pnpm 11 的 minimumReleaseAge 门禁只拦「最新版本」解析 —— 发布不足
-         * 24h 的新版会被静默跳过、回落到旧版；显式版本则会触发 pnpm 的
-         * minimumReleaseAgeExclude 自动豁免并照常安装（社区分叉版
-         * @linxin666/dsh-client-ui-plugin-manager 的 update 正是这样：先
-         * fetchManifest 拿 registry 的 version，再按 `id@版本` 安装）。
-         * 行内没解析过（没点过检查）则现场查 registry，仍失败退回 @latest。 */
-        var row = null;
-        for (var i = 0; i < rows.length; i++) { if (rows[i].name === name) { row = rows[i]; break; } }
-        var specPromise = (row && row.latest)
-          ? Promise.resolve(name + "@" + row.latest)
+        function settle(st) {
+          if (!st || typeof st !== "object") { finish("unknown", "安装未返回可判定的结果"); return; }
+          var app = st.application;
+          if (app === "applied") { finish("applied", ""); return; }
+          if (app === "restart-required") { finish("applied", "已应用，重启桌面端后生效"); return; }
+          if (app === "cancelled") { finish("cancelled", "已取消"); return; }
+          if (app === "overridden") { finish("failed", "已被另一次安装覆盖，请重试"); return; }
+          if (app === "failed") { finish("failed", failureText(st)); return; }
+          finish("unknown", "安装返回了无法识别的结果（application=" + String(app) + "）");
+        }
+        function lostReply(res) {
+          var pm2 = pickService(null, "remote.pluginManager");
+          var wait = pm2 && pm2.waitForInstall;
+          if (!wait) { finish("unknown", lostReplyText(res) + "，且无法恢复，请点「重新检查」确认"); return; }
+          Promise.resolve(wait.call(pm2, busyReq)).then(function (r) {
+            var st = r && r.ok ? r.value : null;
+            if (st) { settle(st); return; }
+            finish("unknown", lostReplyText(res) + "；该请求已不在活动中，结果未知，请点「重新检查」确认");
+          }).catch(function () {
+            finish("unknown", lostReplyText(res) + "；恢复结果失败，请点「重新检查」确认");
+          });
+        }
+        /* 安装 spec 用面板已解析的精确版本（`name@版本`），不用 @latest：pnpm 11 的
+           minimumReleaseAge 只拦「最新版本」解析，显式版本会触发
+           minimumReleaseAgeExclude 自动豁免并照常安装。行内没解析过则现场查 registry。 */
+        var specPromise = busyLatest
+          ? Promise.resolve(name + "@" + busyLatest)
           : fetchLatest(name)
               .then(function (v) { return v ? name + "@" + v : name + "@latest"; })
               .catch(function () { return name + "@latest"; });
+        /* 保留原本的启用选择：不再一律 enabled:true（那会把用户手动禁用的插件重新启用）。 */
+        var enabled = !(row && row.enabled === false);
         specPromise.then(function (spec) {
-          try {
-            pm.installBundle(spec, { enabled: true, requestId: busyReq })
-              .then(function (res) {
-                if (!res || res.ok === false) {
-                  finish(false, (res && res.failure && (res.failure.message || res.failure.reason)) || (res && res.message) || "安装请求被拒");
-                  return;
-                }
-                /* 轮询进度；终态形态未知，多形状都认，240s 兜底 */
-                var t0 = Date.now();
-                function poll() {
-                  var done = false;
-                  try {
-                    var p = pm.waitForInstall ? pm.waitForInstall(busyReq) : null;
-                    Promise.resolve(p).then(function (st) {
-                        if (!st) { return; }
-                        var app = st.application;
-                        if (app === "applied" || app === "restart-required") { done = true; finish(true, app === "restart-required" ? "已应用，重启桌面端后生效" : ""); return; }
-                        if (app === "failed") { done = true; finish(false, "安装失败" + (st.failedAt ? "（" + st.failedAt + "）" : "")); return; }
-                        if (app === "cancelled") { done = true; finish(false, "已取消"); return; }
-                        if (st.stage) { setRow(name, { state: "busy", why: "阶段：" + st.stage }); emit(); }
-                    }).catch(function () { /* 轮询失败不作为终态 */ });
-                  } catch (e) {}
-                  if (!done && !settled && Date.now() - t0 < 240000) { setTimeout(poll, 900); }
-                  else if (!settled && Date.now() - t0 >= 240000) { finish(false, "更新超时（240 秒未结束）"); }
-                }
-                poll();
-              })
-              .catch(function (e) { finish(false, String(e && e.message || e)); });
-          } catch (e) { finish(false, String(e && e.message || e)); }
-        });
-specPromise.catch(function (e) { finish(false, "解析安装版本失败：" + String(e && e.message || e)); });
+          return pm.installBundle(spec, { enabled: enabled, requestId: busyReq });
+        }).then(function (res) {
+          if (!res || res.ok === false) { lostReply(res); return; }
+          settle(res.value);
+        }).catch(function (e) { finish("failed", "安装请求失败：" + msgOf(e)); });
       }
-/* 装完回读清单：版本变了才算真的装上——安装走精确版本后 pnpm 已不会因
-       * minimumReleaseAge 拦新版本，但如果 registry 与 pnpm 解析不一致（如
-       * profile 配了镜像源），仍可能装回旧版，所以回读判据保留作最后兜底。
-       * 只用 pluginManager.listBundles —— pluginInventory 没有 listBundles 方法
-       * （只有 list()），之前先取 inventory 导致 guard 落到 reject，面板上的
-       * 「安装已发起，但回读版本失败」假阳性就是它。装完瞬间清单可能短暂
-       * 不可用，重试 3 次（间隔 1.5s）再下结论。 */
-      function finishOne(name, ok, why) {
-        var before = null;
-        for (var i = 0; i < rows.length; i++) { if (rows[i].name === name) { before = rows[i].version; break; } }
+
+      /* 终态落定：回读清单核对真实版本（registry 解析与 pnpm 实际安装可能不一致，
+         如镜像源），再按 kind 决定文案。kind: applied | failed | cancelled | unknown。
+         回读只用 pluginManager.listBundles（pluginInventory 只有 list()，没有
+         listBundles）；装完瞬间清单可能短暂不可用，重试 3 次（1.5s 间隔）再下结论。 */
+      function finishOne(name, kind, why) {
+        var before = busyBefore;
+        var latest = busyLatest;
         var pm = pickService(null, "remote.pluginManager");
         function done() {
-          busyName = ""; busyReq = ""; cancelling = false;
+          busyName = ""; busyReq = ""; busyBefore = ""; busyLatest = "";
+          cancelling = false;
           emit();
           pump();
         }
-        function attempt(n) {
-          if (!pm || !pm.listBundles) {
-            setRow(name, ok ? { state: "unconfirmed", why: "安装已发起；清单服务不可用，未能回读版本" } : { state: "error", why: why || "更新失败" });
-            done();
-            return;
+        function judge(ver) {
+          if (ver && ver !== before) {
+            setRow(name, { version: ver, state: "current", latest: ver, why: "" });
+          } else if (kind === "cancelled") {
+            /* 取消不是失败：该行仍有新版本，退回可再次更新的状态。 */
+            setRow(name, { state: "update", latest: latest, why: "" });
+          } else if (kind === "failed") {
+            setRow(name, { state: "fail", why: why || "更新失败" });
+          } else if (kind === "applied" && ver) {
+            setRow(name, { state: "unchanged", why: "安装已应用，但版本未变化：可能 registry 与 pnpm 实际解析不一致（如配置了镜像源）" });
+          } else {
+            setRow(name, { state: "unconfirmed", why: why || "未能回读版本；点击重查确认" });
           }
+          done();
+        }
+        function attempt(n) {
+          if (!pm || !pm.listBundles) { judge(""); return; }
           Promise.resolve(pm.listBundles()).then(function (r) {
             var bundles = (r && r.ok && r.value) || [];
+            if (!bundles.length && n < 3) { setTimeout(function () { attempt(n + 1); }, 1500); return; }
             var ver = "";
             for (var i = 0; i < bundles.length; i++) {
               if (bundles[i].name === name) { ver = bundles[i].version != null ? String(bundles[i].version) : ""; break; }
             }
-            if (!bundles.length && n < 3) { setTimeout(function () { attempt(n + 1); }, 1500); return; }
-            if (ver) {
-              if (before && ver === before) {
-                setRow(name, { state: "unchanged", why: "版本未变化：可能 registry 解析与 pnpm 实际安装不一致（如配置了镜像源），也可能检查时远端版本信息有误" });
-              } else {
-                setRow(name, { version: ver, state: "current", latest: ver, why: "" });
-              }
-            } else if (ok) {
-              setRow(name, { state: "unconfirmed", why: "安装已发起，但清单里没读到它；点击重查确认" });
-            } else {
-              setRow(name, { state: "error", why: why || "更新失败" });
-            }
-            done();
+            judge(ver);
           }).catch(function () {
             if (n < 3) { setTimeout(function () { attempt(n + 1); }, 1500); return; }
-            setRow(name, ok ? { state: "unconfirmed", why: "安装已发起，但回读版本失败；点击重查确认" } : { state: "error", why: why || "更新失败" });
-            done();
+            judge("");
           });
         }
         attempt(0);
       }
+
+      /* 取消：排队项只摘自己（cancelQueued）；在装项请求取消**本次**，队列保留，
+         等它落定后 done() → pump() 自然接着装下一项。
+         旧实现把整个 queue 清空，于是「等待更新」的项全部退回「有新版本」——
+         这就是「取消一项后，等待的项不再开始、反而变回有新版本」的真因。 */
       function requestCancel() {
         if (!busyName || cancelling) { return; }
         cancelling = true;
-        queue = [];
-        rows.forEach(function (r) { if (r.state === "queuing") { r.state = r.latest && cmpSemver(r.latest, r.version) > 0 ? "update" : "current"; } });
-        var pm = pickService(null, "remote.pluginManager");
-        try { if (pm && pm.cancelInstall && busyReq) { pm.cancelInstall(busyReq); } } catch (e) {}
-        setRow(busyName, { state: "error", why: "已请求取消" });
+        var name = busyName;
+        setRow(name, { state: "busy", why: "正在取消 …" });
         emit();
+        var pm = pickService(null, "remote.pluginManager");
+        if (!pm || !pm.cancelInstall || !busyReq) {
+          setRow(name, { state: "busy", why: "取消服务不可用，仍在等待它自行结束" });
+          return;
+        }
+        Promise.resolve(pm.cancelInstall(busyReq)).then(function (r) {
+          var status = r && r.ok && r.value ? r.value.status : "";
+          if (status === "too-late") { setRow(name, { state: "busy", why: "已进入应用阶段，取消不了，正在等它结束" }); }
+          else if (status === "not-running") { setRow(name, { state: "busy", why: "该请求已不在运行，等待结果回传" }); }
+          /* status === "cancelled"：安装调用会以 application:"cancelled" 落定，不在此改状态 */
+        }).catch(function (e) {
+          setRow(name, { state: "busy", why: "取消请求失败：" + msgOf(e) + "；仍在等待它结束" });
+        });
       }
 
       /* ---- 面板 UI：挂在 body 的 Shadow DOM（fixed 浮层不能放进 flex 工具栏）---- */
@@ -741,9 +829,10 @@ specPromise.catch(function (e) { finish(false, "解析安装版本失败：" + S
           ".x{cursor:pointer;opacity:.55;font-size:17px;line-height:1;padding:0 3px}" +
           ".x:hover{opacity:1}" +
           ".rows{flex:1 1 auto;min-height:0;overflow:auto}" +
-          ".row{display:flex;align-items:center;gap:8px;padding:7px 12px;" +
-          "border-bottom:1px solid var(--dsw-alias-border-l2,rgba(128,128,128,.12))}" +
-          ".row:last-child{border-bottom:0}" +
+          ".rowwrap{border-bottom:1px solid var(--dsw-alias-border-l2,rgba(128,128,128,.12))}" +
+          ".rowwrap:last-child{border-bottom:0}" +
+          ".row{display:flex;align-items:center;gap:8px;padding:7px 12px}" +
+          ".why{padding:0 12px 8px;font-size:12px;line-height:1.45;opacity:.7;word-break:break-word;white-space:pre-wrap}" +
           ".nm{flex:1;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}" +
           ".ver{opacity:.6;font-size:12px;white-space:nowrap;font-variant-numeric:tabular-nums}" +
           ".tag{font-size:11px;padding:1px 7px;border-radius:999px;white-space:nowrap;" +
@@ -831,7 +920,11 @@ specPromise.catch(function (e) { finish(false, "解析安装版本失败：" + S
             if (nm) { enqueue(nm); }
             return;
           }
-          if (t.classList.contains("cancel")) { requestCancel(); return; }
+          if (t.classList.contains("cancel")) {
+            var nmc = t.getAttribute("data-n");
+            if (nmc && nmc !== busyName) { cancelQueued(nmc); } else { requestCancel(); }
+            return;
+          }
           if (t.classList.contains("retry")) {
             var nm2 = t.getAttribute("data-n");
             checkOne(nm2);
@@ -867,7 +960,7 @@ specPromise.catch(function (e) { finish(false, "解析安装版本失败：" + S
       var TAG_TEXT = {
         checking: "比对中 …", current: "已是最新", update: "有新版本",
         local: "本地链接", remote: "Git 直装", unknown: "无法比对", error: "检查失败", queuing: "等待更新",
-        busy: "更新中 …", unchanged: "暂缓更新", unconfirmed: "已发起·未确认"
+        busy: "更新中 …", unchanged: "暂缓更新", unconfirmed: "已发起·未确认", fail: "更新失败"
       };
       function tagHtml(r) {
         var cls = "tag other", act = "", title = "";
@@ -877,7 +970,9 @@ specPromise.catch(function (e) { finish(false, "解析安装版本失败：" + S
         else if (r.state === "local") { title = " title=\"" + esc(r.src || r.why || "本地直装") + "；没有可比的 registry 版本\""; }
         else if (r.state === "remote") { title = " title=\"" + esc(r.src || r.why || "Git/URL 直装") + "；没有可比的 registry 版本\""; }
         else if (r.state === "unknown") { title = " title=\"" + esc(r.why || "插件清单未提供已装版本") + "，因此无法与 registry 比对\""; }
-        else if (r.state === "queuing" || r.state === "busy") { cls = "tag other cancel clickable"; title = " title=\"点击取消" + (r.state === "busy" ? "本次更新" : "排队") + "\""; }
+        else if (r.state === "queuing") { cls = "tag other cancel clickable"; act = " data-n=\"" + esc(r.name) + "\""; title = " title=\"点击取消排队\""; }
+        else if (r.state === "busy") { cls = "tag other cancel clickable"; act = " data-n=\"" + esc(r.name) + "\""; title = " title=\"" + esc(r.why ? r.why + "；" : "") + "点击取消本次更新\""; }
+        else if (r.state === "fail") { cls = "tag error act clickable"; act = " data-n=\"" + esc(r.name) + "\""; title = " title=\"" + esc(r.why || "更新失败") + "（点击重试）\""; }
         else if (r.state === "unchanged") { cls = "tag update act clickable"; act = " data-n=\"" + esc(r.name) + "\""; title = " title=\"" + esc(r.why || "") + "（点击重试）\""; }
         else if (r.state === "unconfirmed") { cls = "tag other reverify clickable"; title = " title=\"" + esc(r.why || "") + "（点击重查）\""; }
         return "<span class=\"" + cls + "\"" + act + title + ">" + esc(TAG_TEXT[r.state] || "未比对") + "</span>";
@@ -892,11 +987,14 @@ specPromise.catch(function (e) { finish(false, "解析安装版本失败：" + S
           body = "<div class=\"msg\">" + (checking ? "正在读取插件清单…" : "点上方「重新检查」开始比对") + "</div>";
         } else {
           body = rows.map(function (r) {
-            var ver = r.latest && (r.state === "update" || r.state === "unchanged") ? r.version + " → " + r.latest : r.version;
-            return "<div class=\"row\">" +
+            var showLatest = r.state === "update" || r.state === "unchanged" || r.state === "fail";
+            var ver = r.latest && showLatest ? r.version + " → " + r.latest : r.version;
+            var sub = r.why && (r.state === "fail" || r.state === "unchanged" || r.state === "unconfirmed" || r.state === "error")
+              ? "<div class=\"why\">" + esc(r.why) + "</div>" : "";
+            return "<div class=\"rowwrap\"><div class=\"row\">" +
               "<span class=\"nm\" title=\"" + esc(r.name) + "\">" + esc(r.name) + "</span>" +
               "<span class=\"ver\" title=\"" + esc(ver) + "\">" + esc(ver) + "</span>" +
-              tagHtml(r) + "</div>";
+              tagHtml(r) + "</div>" + sub + "</div>";
           }).join("");
         }
         var html = "<div class=\"hd\"><b>插件更新 · " + (busyName ? "正在更新 " + esc(busyName) + " …" : (checking ? "检查中…" : (rows.length ? upd + " 个插件有新版本" : "插件更新检查"))) + "</b>" +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimoxie/dsh-ui-tweaks",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "dsh Web UI 微调合集：宽表格越界修复、对话区左侧自绘滚动条、插件更新检查面板（不含 dsh 本体）",
   "type": "module",
   "main": "lib/index.js",
@@ -17,7 +17,7 @@
     "lib",
     "cordis.patch.yml",
     "README.md",
-    "DEVELOPING.md",
+    "DEVELOPMENT.md",
     "LICENSE"
   ],
   "keywords": [