dsh-plugin-rack 0.1.1 → 0.1.3

package/README.md

@@ -1,4 +1,4 @@
-# dsh-plugin-dashboard · 插件管理台
+# dsh-plugin-rack · 插件管理台
 
 DSH（DeepSeek Harness）的插件面板：**所有插件一屏看完，一个开关直接开关，更新完不用重启。**
 
@@ -37,6 +37,7 @@ DSH（DeepSeek Harness）的插件面板：**所有插件一屏看完，一个
 ### 更新
 
 - 「检查更新」把 profile 里按精确版本锁定的依赖逐个查 registry 最新版，有新的直接在列表行里标出来：`⬆ v0.1.29 ➡ v0.1.30 npm`，**点一下只更新那一个插件**。
+- **尊重你写的版本范围**：`package.json` 里锁死精确版本（`1.2.3`）时照旧只看那一个版本；写成 `^1.2.3` / `~1.2.3` / `1.2` / `1.x` / `>=1.2.3` / `>1.2.3` / `<2.0.0` / `1.2.3 - 2.0.0` / `^1 || ^2` 时，只有落在范围内的新版才算「可更新」。超出范围的新版会单独列在下方，标「超出声明范围」并附上你写的那段 spec —— 不会被批量更新悄悄顶到下一个大版本。`link:` / `file:` / `github:` / tarball 这些不可比的范围仍走「其他安装方式」，不参与版本更新。
 - 更新由宿主执行：**点完就可以关掉面板**，pnpm 照样跑完。重新打开面板时，顶部会显示「后台更新中 · N 个插件」，跑完了补一条结果提示。不用守着这个界面，也不用去翻日志。卡住了可以点横幅右边的「取消」。
 - **会话正忙时也不白点**：需要下载的更新会先把附件取下来、核对 sha256，然后排队；宿主每 10 秒看一眼，等所有会话都空了就自己装上（下载过的东西不会重下）。排队期间横幅显示「已排队…」。
 - **网络不用你配**：下载按这个顺序自动选路，`config.json` 里明确指定的代理 → 环境变量（`HTTPS_PROXY` / `ALL_PROXY`，`NO_PROXY` 会照规矩跳过）→ 系统代理（Windows 的 Internet 设置）→ 直连；一条走不通就换下一条，不会因为代理没开就整个更新失败。HTTP 代理和 SOCKS5 都支持，带用户名密码也行，查 GitHub 接口的部分同样走这些代理。
@@ -48,7 +49,7 @@ DSH（DeepSeek Harness）的插件面板：**所有插件一屏看完，一个
 - 能识别 **GitHub 直装 / npm 镜像 tar 包 / 本地文件包 / 本地软链** 这四种装法，并在同一个列表里标出各自来源；本地软链没有「升级」这回事，不会被勾选。
 - registry 取 profile 自己的配置（`pluginManager.registries()`），不强行走 npmjs；装了 `GITHUB_TOKEN` 的话查 GitHub 版本会用它提额。
 
-### 安装与卸载
+## 安装与卸载
 
 - 输入包名先「检查」：**只做预检，什么都不动**。它会告诉你这是不是个 DSH 插件包、版本多少、干什么用的。像 `is-odd` 这种普通 npm 包会被拦下来，因为它没声明 `dsh.bundle`，装了也不会被加载。
 - 确认了再「安装」，走宿主官方的插件管理接口。
@@ -82,13 +83,13 @@ node test/self-check.mjs
 **① 从 GitHub 装（推荐，不依赖 npm）**
 
 ```bash
-dsh plugin add github:LZM-P/dsh-plugin-dashboard
+dsh plugin add github:LZM-P/dsh-plugin-rack
 ```
 
 **② 从 npm 装（发布后可用）**
 
 ```bash
-dsh plugin add dsh-plugin-dashboard
+dsh plugin add dsh-plugin-rack
 ```
 
 **③ 在插件管理界面里点「安装」**，把上面任意一条的 spec 填进去。
@@ -96,7 +97,7 @@ dsh plugin add dsh-plugin-dashboard
 装好后侧边栏会出现「插件管理」。
 
 > 如果宿主版本不认 `github:` 前缀，改用 tarball 地址：
-> `dsh plugin add https://github.com/LZM-P/dsh-plugin-dashboard/archive/refs/heads/main.tar.gz`
+> `dsh plugin add https://github.com/LZM-P/dsh-plugin-rack/archive/refs/heads/main.tar.gz`
 
 ## 数据放在哪
 
@@ -124,11 +125,21 @@ dsh plugin add dsh-plugin-dashboard
 | 文件 | 作用 |
 | --- | --- |
 | `index.js` | 宿主端：注册 `/api/dsh-plugin-rack` 前缀路由，负责读取插件状态、批量操作、更新与安装卸载 |
-| `client.js` | 客户端：侧边栏图标 + `main` 面板的界面（无需构建步骤，浏览器直接加载） |
-| `cordis.patch.yml` | bundle 补丁，插入 `plugin-dashboard` 这一行 |
+| `client.js` | 客户端：侧边栏图标 + `main` 面板的界面。**生成文件**，由 `src/client/*.js` 拼装（`npm run build`） |
+| `src/client/i18n.js` | 中英词条表与插值（纯函数，可单独测） |
+| `src/client/view.js` | 面板的判定逻辑：失败归类、勾选分流、报告合并、行尾徽章、更新页状态 |
+| `src/client/style.js` | 面板样式表 |
+| `src/client/panel.js` | 面板组件本身（React `h`，无构建期依赖） |
+| `scripts/build-client.mjs` | 把上面几块拼成 `client.js`；`--check` 供 CI 判断是否过期 |
+| `lib/spec.js` | 版本范围算术（精确 / `^` / `~` / `>=` / `<` / 通配 / 连字符 / `||` 并集），纯函数，`index.js` 与测试共用同一份 |
+| `cordis.patch.yml` | bundle 补丁，插入 `plugin-rack` 这一行 |
 | `locale/{en,zh}.json` | 插件名与描述（插件管理页展示用） |
 | `icon.svg` | 插件图标 |
 | `test/self-check.mjs` | 自检脚本：词条对照、路由对照、hook 顺序、调试残留 |
+| `test/spec.mjs` | 范围算术单测：`^0.2.3` 不含 `0.3.0`、`~1.2.3` 不含 `1.3.0`、预发布版不穿越等边界 |
+| `test/*.mjs` | 行为 / 后台作业 / 下载 / pnpm 启动四套测试 |
+| `scripts/publish.mjs` | 发布脚本：token 只从 `NPM_TOKEN` 读，版本重复直接拒绝 |
+| `eslint.config.js` / `tsconfig.json` | lint 与 `tsc --checkJs`（类型只覆盖 `lib/`） |
 
 ## 接口
 
@@ -178,7 +189,7 @@ POST /api/dsh-plugin-rack/uninstall   { name }
 
 1. **网络暴露面**：API 只在 `127.0.0.1` / `localhost` / `::1` 上可达。宿主的 web server 本来就只绑 loopback，所以外网碰不到这个端口。
 2. **Host / Origin 校验**：每个请求都先过两道闸：Host 头必须指向 loopback，Origin 头（如果存在）也必须解析到 loopback。这挡的是同机浏览器里的恶意网页：它无法用 `<img>` 或 `fetch` 跨站调用你的 API（DNS rebinding / CSRF 都被这两道闸拦下）。
-2b. **写操作还要求"你确实是从面板来的"**：`POST` 除了要 `application/json`，还必须带 `Origin`、或 `Sec-Fetch-Site: same-origin`、或显式加上 `x-dsh-plugin-dashboard: 1` 请求头。
+2b. **写操作还要求"你确实是从面板来的"**：`POST` 除了要 `application/json`，还必须带 `Origin`、或 `Sec-Fetch-Site: same-origin`、或显式加上 `x-dsh-plugin-rack: 1` 请求头。
 
    这道门挡的是**无意的跨站 POST**（比如别处一个表单顺手打过来、或者某个页面被 XSS 后盲发请求），它对「完全不带 Origin」的请求本来是不设防的，而 `curl -X POST` 正好属于这一类。
 
@@ -186,7 +197,7 @@ POST /api/dsh-plugin-rack/uninstall   { name }
    ```bash
    curl -X POST http://127.0.0.1:9546/api/dsh-plugin-rack/bulk \
      -H 'content-type: application/json' \
-     -H 'x-dsh-plugin-dashboard: 1' \
+     -H 'x-dsh-plugin-rack: 1' \
      -d '{"enabled":false,"scope":"installed"}'
    ```
 3. **卸载白名单**：界面上的「卸载」按钮不是对所有行都显示。只有宿主 `pluginManager` 服务明确标记为 `removable` 的包才会出现按钮。核心组件、面板自己、harness 命脉都**永远不会**出现在可卸载列表里，所以误点卸载也不会把系统拆坏。
@@ -196,10 +207,25 @@ POST /api/dsh-plugin-rack/uninstall   { name }
 
 ## 兼容性
 
+- DSH `>=0.2.1-rc.2 <0.2.3-0`。已实测 `0.2.1-rc.2`、`0.2.1-rc.5`、`0.2.2-rc.1`、`0.2.2-rc.2`、`0.2.2-rc.3`；
+  名单之外的版本会明说不确定，不会假装兼容。
 - DSH 的 Web 界面（`dsh.client.platform = web`）。
 - 需要宿主提供 `pluginManager` 服务；没有它会明确报错，而不是假装成功。
 - 热替换依赖宿主的 HMR 服务；拿不到时退回提示「重启一次生效」，**不会骗你说已经生效了**。
 
+## 开发
+
+```bash
+npm ci         # 只装 eslint + typescript（开发依赖，发布包不含 node_modules）
+npm test       # 六套：自检 / 行为 / 范围算术 / 后台作业 / 下载 / pnpm 启动
+npm run lint   # eslint（no-dupe-keys、no-undef 在这套配置下抓出过两处真 bug）
+npm run types  # tsc --checkJs，只覆盖 lib/（JSDoc 当类型，不引入构建步骤）
+```
+
+- 范围算术只有一份实现：`lib/spec.js`。`index.js` import 它，`test/spec.mjs` 直接跑它，所以「测试通过的是一套逻辑、线上跑的是另一套」不会发生。
+- CI 在 Windows 上跑 Node 20 与 22；另有一格把 `npm pack` 出来的 tarball 解压再跑一遍测试——`files` 里漏了哪个文件，本地是发现不了的。
+- 发布：`NPM_TOKEN=… npm run publish`。token 只从环境变量读，版本已存在会直接拒绝，不会落进任何文件。
+
 ## English
 
 A plugin dashboard panel for DSH (DeepSeek Harness): every plugin in one list, a power switch per plugin,

package/client.js

@@ -1,20 +1,13 @@
 /**
- * Client half of the plugin dashboard.
+ * Client half of the plugin rack.
  *
- * Registers a sidebar entry and the matching main panel. Every write goes to
- * the Host half over the same-origin JSON route, so nothing here depends on the
- * Client-side Remote access policy.
+ * GENERATED FILE — edit src/client/*.js and run `node scripts/build-client.mjs`.
+ * The module loader takes one plain script, so the parts are concatenated here
+ * instead of being imported at runtime.
  */
 window.__ModuleLoader__.load({
   id: 'dsh-plugin-rack',
   factory(require) {
-    const React = require('react');
-    const h = React.createElement;
-
-    const PANEL_ID = 'plugin-rack';
-    const API = '/api/dsh-plugin-rack';
-    const NS = 'plugin-rack';
-
     const DICT = {
       en: {
         title: 'Plugin rack',
@@ -145,6 +138,8 @@ window.__ModuleLoader__.load({
         updateRestart: 'Restart DSH once to load the new versions',
         updatePartialSwap: 'Some packages are live, some need a restart',
         updateSwapped: 'New versions are live; refresh the page for client-side plugins',
+        updateOutOfRange: 'outside the declared range',
+        updateOutOfRangeHint: 'Newest {v} does not satisfy "{spec}" — not updated by default',
         hasNewVersion: 'Update available',
         updateNow: 'Update just this plugin',
         jobRunning: 'Host is updating in the background · {n} plugins',
@@ -199,8 +194,6 @@ window.__ModuleLoader__.load({
         groupAllAuto: '整组已设为自动',
         groupAllManual: '整组已设为手动',
         colName: '插件名称',
-        colPower: '开启 / 关闭',
-        colMode: '自动 / 手动',
         modeAuto: '自动',
         modeManual: '手动',
         filterAll: '全部',
@@ -305,6 +298,8 @@ window.__ModuleLoader__.load({
         updateRestart: '重启一次 DSH 让新版本生效',
         updatePartialSwap: '部分包已生效，部分需要重启',
         updateSwapped: '新版本已即时生效；界面类插件刷新页面即可',
+        updateOutOfRange: '超出声明范围',
+        updateOutOfRangeHint: '最新 {v} 不满足「{spec}」，默认不更新',
         hasNewVersion: '有新版',
         updateNow: '只更新这一个插件',
         jobRunning: '宿主正在后台更新 · {n} 个插件',
@@ -416,57 +411,6 @@ window.__ModuleLoader__.load({
     // working — otherwise the UI reports a failure for a run that succeeds.
     const WRITE_TIMEOUT_MS = 60 * 60 * 1000;
 
-    async function request(path, body, options) {
-      const timeoutMs =
-        options && typeof options.timeoutMs === 'number' ? options.timeoutMs : DEFAULT_TIMEOUT_MS;
-      const init =
-        body === undefined
-          ? { method: 'GET', headers: { accept: 'application/json' } }
-          : {
-              method: 'POST',
-              headers: {
-                'content-type': 'application/json',
-                accept: 'application/json',
-                // 和宿主端的写操作闸门配对：面板自己永远带这个头，所以即使
-                // 某个环境下浏览器没发 Origin / Sec-Fetch-Site 也照样放行。
-                'x-dsh-plugin-rack': '1',
-              },
-              body: JSON.stringify(body),
-            };
-      // Without this a stuck Host call pins busy/pending forever and the only
-      // way out is reloading the page.
-      const controller = new AbortController();
-      init.signal = controller.signal;
-      const timer = setTimeout(() => controller.abort(), timeoutMs);
-      let response;
-      try {
-        response = await fetch(API + path, init);
-      } catch (error) {
-        void error;
-        throw new Error(controller.signal.aborted ? 'timeout' : 'unreachable');
-      } finally {
-        clearTimeout(timer);
-      }
-      let data = null;
-      try {
-        data = await response.json();
-      } catch (error) {
-        void error;
-        data = null;
-      }
-      // 服务端失败时常常带着细节（回滚那段 pnpm 输出在 data.failed.output 里），
-      // 之前只取 message 就抛，于是「为什么失败」的信息到不了界面。把整个 data
-      // 挂到 error 上，调用方要用就有。
-      if (!response.ok || data === null || data.ok !== true) {
-        const message =
-          (data && data.message) || (response.ok ? 'malformed response' : response.status + ' ' + response.statusText);
-        const error = new Error(message);
-        if (data !== null && typeof data === 'object') error.data = data;
-        throw error;
-      }
-      return data;
-    }
-
     /**
      * 把勾选的包名按更新通道分组。
      *
@@ -699,6 +643,53 @@ window.__ModuleLoader__.load({
       });
     }
 
+
+/**
+ * What to show at the right end of an installed plugin row.
+ *
+ * The cases are deliberately distinct: a plain npm install gets no label at all
+ * (it is the default — a label there is pure noise), a row installed some other
+ * way gets a small tag naming the source, and a row with an update gets a button
+ * — unless the release sits outside the version range the user wrote, in which
+ * case a button would be a lie, so it becomes a warning tag instead.
+ *
+ * @param {object|undefined} info  the check result for this row, if any
+ * @param {string|undefined} src  how the row itself was installed
+ * @returns {{kind: 'none'}|{kind: 'src', label: string}|{kind: 'outOfRange', label: string, spec: string}|{kind: 'update', label: string, source: string}}
+ */
+function badgeOf(info, src) {
+  if (info === undefined || info === null) {
+    return src === undefined || src === 'npm' ? { kind: 'none' } : { kind: 'src', label: src };
+  }
+  if (info.outOfRange === true) {
+    return { kind: 'outOfRange', label: info.label ?? '', spec: info.spec ?? '' };
+  }
+  return { kind: 'update', label: info.label ?? '', source: info.source ?? 'npm' };
+}
+
+/**
+ * Which of the update page's states to render.
+ *
+ * 'none' used to be decided on hasUpdate alone, which made the page claim there
+ * was nothing to do while listing out-of-range releases underneath. Both counts
+ * decide it now.
+ *
+ * @param {{ok?: boolean, message?: string, rows?: Array<{hasUpdate?: boolean, outOfRange?: boolean}>}|null} updates
+ * @param {boolean} checking
+ * @returns {{kind: 'idle'|'checking'|'error'|'none'|'list', message?: string, updatable?: Array<object>, outOfRange?: Array<object>}}
+ */
+function updatePageState(updates, checking) {
+  if (updates === null || updates === undefined) {
+    return { kind: checking === true ? 'checking' : 'idle' };
+  }
+  if (updates.ok !== true) return { kind: 'error', message: String(updates.message ?? 'error') };
+  const rows = Array.isArray(updates.rows) ? updates.rows : [];
+  const updatable = rows.filter((row) => row.hasUpdate === true);
+  const outOfRange = rows.filter((row) => row.outOfRange === true);
+  if (updatable.length === 0 && outOfRange.length === 0) return { kind: 'none' };
+  return { kind: 'list', updatable: updatable, outOfRange: outOfRange };
+}
+
     const CSS = [
       '.pd-root{display:flex;flex-direction:column;height:100%;min-height:0;box-sizing:border-box;',
       'background:var(--dsw-alias-bg-base);color:var(--dsw-alias-label-primary)}',
@@ -832,6 +823,14 @@ window.__ModuleLoader__.load({
       '.pd-upbtn-open{text-decoration:none}',
       '.pd-src{flex:none;font-size:10px;line-height:16px;padding:0 6px;border-radius:6px;white-space:nowrap;',
       'border:1px solid var(--dsw-alias-border-l3);color:var(--dsw-alias-label-tertiary)}',
+      '.pd-src-warn{border-color:var(--dsw-alias-state-warn-primary);',
+      'color:var(--dsw-alias-state-warn-label);background:var(--dsw-alias-state-warn-tertiary)}',
+      '.pd-up-section{margin-top:10px;font-size:11px;line-height:16px;color:var(--dsw-alias-label-tertiary)}',
+      '.pd-up-oob{display:flex;flex-direction:column;gap:2px;margin-top:6px}',
+      '.pd-up-oob-row{display:flex;gap:8px;align-items:baseline;font-size:11px;line-height:18px;',
+      'color:var(--dsw-alias-label-tertiary)}',
+      '.pd-up-oob-row b{font-weight:600;color:var(--dsw-alias-label-secondary)}',
+      '.pd-up-oob-row code{font-size:10px;opacity:.85}',
       '.pd-upbtn{display:inline-flex;align-items:center;gap:5px;flex:none;font-family:inherit;',
       'font-size:11px;line-height:16px;padding:1px 7px;border-radius:8px;white-space:nowrap;',
       'font-variant-numeric:tabular-nums;cursor:pointer;',
@@ -929,6 +928,8 @@ window.__ModuleLoader__.load({
       '.pd-update-row:hover{background:var(--dsw-alias-interactive-bg-hover)}',
       '.pd-update-name{flex:1;min-width:0;font-size:13px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}',
       '.pd-update-ver{flex:none;font-size:12px;color:var(--dsw-alias-label-secondary);font-variant-numeric:tabular-nums}',
+      '.pd-update-spec{flex:none;font-family:inherit;font-size:10px;line-height:16px;padding:0 5px;border-radius:5px;',
+      'border:1px solid var(--dsw-alias-border-l3);color:var(--dsw-alias-label-tertiary)}',
       '.pd-check{flex:none;width:15px;height:15px;margin:0;accent-color:var(--dsw-alias-state-business-primary);cursor:pointer}',
       '.pd-update-log{padding:10px 12px;border-radius:9px;font-size:12px;line-height:18px;background:var(--dsw-alias-bg-layer-2)}',
       '.pd-update-log-ok{border:1px solid var(--dsw-alias-state-success-primary)}',
@@ -938,6 +939,63 @@ window.__ModuleLoader__.load({
       '.pd-update-log-out{margin-top:6px;padding-top:6px;border-top:1px solid var(--dsw-alias-border-l3);font-size:11px;line-height:16px;color:var(--dsw-alias-label-tertiary);white-space:pre-wrap;word-break:break-all;max-height:140px;overflow:auto}',
     ].join('');
 
+    const React = require('react');
+    const h = React.createElement;
+
+    const PANEL_ID = 'plugin-rack';
+    const API = '/api/dsh-plugin-rack';
+    const NS = 'plugin-rack';
+    async function request(path, body, options) {
+      const timeoutMs =
+        options && typeof options.timeoutMs === 'number' ? options.timeoutMs : DEFAULT_TIMEOUT_MS;
+      const init =
+        body === undefined
+          ? { method: 'GET', headers: { accept: 'application/json' } }
+          : {
+              method: 'POST',
+              headers: {
+                'content-type': 'application/json',
+                accept: 'application/json',
+                // 和宿主端的写操作闸门配对：面板自己永远带这个头，所以即使
+                // 某个环境下浏览器没发 Origin / Sec-Fetch-Site 也照样放行。
+                'x-dsh-plugin-rack': '1',
+              },
+              body: JSON.stringify(body),
+            };
+      // Without this a stuck Host call pins busy/pending forever and the only
+      // way out is reloading the page.
+      const controller = new AbortController();
+      init.signal = controller.signal;
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      let response;
+      try {
+        response = await fetch(API + path, init);
+      } catch (error) {
+        void error;
+        throw new Error(controller.signal.aborted ? 'timeout' : 'unreachable');
+      } finally {
+        clearTimeout(timer);
+      }
+      let data = null;
+      try {
+        data = await response.json();
+      } catch (error) {
+        void error;
+        data = null;
+      }
+      // 服务端失败时常常带着细节（回滚那段 pnpm 输出在 data.failed.output 里），
+      // 之前只取 message 就抛，于是「为什么失败」的信息到不了界面。把整个 data
+      // 挂到 error 上，调用方要用就有。
+      if (!response.ok || data === null || data.ok !== true) {
+        const message =
+          (data && data.message) || (response.ok ? 'malformed response' : response.status + ' ' + response.statusText);
+        const error = new Error(message);
+        if (data !== null && typeof data === 'object') error.data = data;
+        throw error;
+      }
+      return data;
+    }
+
     function SidebarIcon(props) {
       const size = props && typeof props.size === 'number' ? props.size : 18;
       return h(
@@ -1333,7 +1391,6 @@ window.__ModuleLoader__.load({
           setExtrasBusy('check');
           try {
             setExtras(await request('/extras'));
-            setExtraLog(null);
           } catch (error) {
             // 进面板那一次自动检查失败时静默，别一打开就弹错。
             if (quiet !== true) setExtras({ ok: false, message: String(error && error.message) });
@@ -1553,7 +1610,7 @@ window.__ModuleLoader__.load({
         const doBulk = async (ask) => {
           if (ask === null) return;
           setBulkAsk(null);
-          const { enabled, scope, total, save } = ask;
+          const { enabled, scope, save } = ask;
           let accepted;
           try {
             accepted = await request('/bulk', {
@@ -1856,7 +1913,24 @@ window.__ModuleLoader__.load({
             if (typeof item.name !== 'string') continue;
             srcOf.set(item.name, 'npm');
             if (item.hasUpdate === true && typeof item.latest === 'string') {
-              updateOf.set(item.name, { label: 'v' + item.latest, source: 'npm', action: 'npm' });
+              updateOf.set(item.name, {
+                label: 'v' + item.latest,
+                source: 'npm',
+                action: 'npm',
+                spec: typeof item.spec === 'string' ? item.spec : '',
+                ranged: item.kind !== 'exact',
+              });
+            } else if (item.outOfRange === true && typeof item.latest === 'string') {
+              // 服务端已经判定这个新版本不满足 package.json 里写的范围，
+              // 批量更新也不会动它。主列表仍然要让人看见「有新版但不升」，
+              // 否则用户只会觉得「检查更新坏了」。
+              updateOf.set(item.name, {
+                label: 'v' + item.latest,
+                source: 'npm',
+                action: 'npm',
+                outOfRange: true,
+                spec: typeof item.spec === 'string' ? item.spec : '',
+              });
             }
           }
         }
@@ -2027,13 +2101,22 @@ window.__ModuleLoader__.load({
                 { className: 'pd-name-act', onClick: (event) => event.stopPropagation() },
                 (() => {
                   const info = updateOf.get(row.name);
-                  if (info === undefined) {
-                    const src = srcOf.get(row.name);
-                    // 普通 npm 装的是默认情况，标出来只是噪音；只有「不是按常规方式
-                    // 装的」才值得在主列表里露一个标签。
-                    return src === undefined || src === 'npm' ? null : h('span', { className: 'pd-src' }, src);
-                  }
+                  const badge = badgeOf(info, srcOf.get(row.name));
+                  if (badge.kind === 'none') return null;
+                  if (badge.kind === 'src') return h('span', { className: 'pd-src' }, badge.label);
                   const updating = pending['update:' + row.entryId] === true;
+                  if (badge.kind === 'outOfRange') {
+                    // 有新版、但不在 package.json 声明的范围内：这里不能给按钮，
+                    // 点了也不会升，只会让人以为按钮失灵。
+                    return h(
+                      'span',
+                      {
+                        className: 'pd-src pd-src-warn',
+                        title: t('updateOutOfRangeHint', { v: badge.label, spec: badge.spec }),
+                      },
+                      t('updateOutOfRange'),
+                    );
+                  }
                   const parts = [
                     updating ? h('span', { key: 'spin', className: 'pd-spin pd-upbtn-spin' }) : null,
                     'v' + (row.version ?? '?'),
@@ -2404,6 +2487,9 @@ window.__ModuleLoader__.load({
             }),
             h('span', { className: 'pd-update-name' }, row.name),
             h('span', { className: 'pd-update-ver' }, row.current + ' → ' + row.latest),
+            typeof row.spec === 'string' && row.kind !== 'exact'
+              ? h('code', { className: 'pd-update-spec', title: row.spec }, row.spec)
+              : null,
           );
 
         const installPanel = h(
@@ -2529,17 +2615,39 @@ window.__ModuleLoader__.load({
                     : String(logText.text).slice(-4000),
                 ),
               ),
-          updates === null
-            ? h(
+          (() => {
+            const state = updatePageState(updates, updatesBusy === 'check');
+            if (state.kind === 'list') return state.updatable.map(updateRowNode);
+            if (state.kind === 'error') return h('div', { className: 'pd-empty' }, state.message);
+            if (state.kind === 'none') return h('div', { className: 'pd-empty' }, t('updateNone'));
+            const key = state.kind === 'checking' ? 'updateChecking' : 'updateIdle';
+            return h('div', { className: 'pd-empty' }, t(key));
+          })(),
+          (() => {
+            // 「有新版但超出范围」单独列一段：它不是错误，也不该被批量更新
+            // 静默吞掉，放在主列表下面说明原因最省解释成本。
+            const state = updatePageState(updates, false);
+            const outOfRange = state.kind === 'list' ? state.outOfRange : [];
+            if (outOfRange.length === 0) return null;
+            return h(
+              'div',
+              { className: 'pd-up-section' },
+              h('div', null, t('updateOutOfRange') + ' (' + outOfRange.length + ')'),
+              h(
                 'div',
-                { className: 'pd-empty' },
-                updatesBusy === 'check' ? t('updateChecking') : t('updateIdle'),
-              )
-            : updates.ok !== true
-              ? h('div', { className: 'pd-empty' }, String(updates.message || 'error'))
-              : updates.rows.filter((row) => row.hasUpdate).length === 0
-                ? h('div', { className: 'pd-empty' }, t('updateNone'))
-                : updates.rows.filter((row) => row.hasUpdate).map(updateRowNode),
+                { className: 'pd-up-oob' },
+                outOfRange.map((row) =>
+                  h(
+                    'div',
+                    { key: row.name, className: 'pd-up-oob-row' },
+                    h('b', null, row.name),
+                    h('span', null, row.current + ' → ' + row.latest),
+                    typeof row.spec === 'string' ? h('code', null, row.spec) : null,
+                  ),
+                ),
+              ),
+            );
+          })(),
           updateLog === null
             ? null
             : h(
@@ -2837,7 +2945,6 @@ window.__ModuleLoader__.load({
 
       return Dashboard;
     }
-
     return {
       inject: ['slots', 'locale', 'layout'],
       apply(ctx) {