qq-bot-roost 0.8.7 → 0.8.9

package/README.md

@@ -10,7 +10,7 @@
 <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="零依赖">
 <img src="https://img.shields.io/badge/tests-600%2B%20passed-brightgreen" alt="测试 600+ 项">
 <img src="https://img.shields.io/badge/plugins-JS%20%7C%20Python%20%7C%20Go%20%7C%20any-blue" alt="多语言插件">
-<img src="https://img.shields.io/badge/version-0.8.7-blueviolet" alt="版本 0.8.7">
+<img src="https://img.shields.io/badge/version-0.8.8-blueviolet" alt="版本 0.8.8">
 <img src="https://img.shields.io/badge/license-Non--Commercial-red" alt="禁止商用">
 
 [快速开始](#3-分钟跑起来) ｜ [写插件](docs/插件开发规范.md) ｜ [外部插件协议](docs/插件协议.md) ｜ [配置参考](docs/配置参考.md) ｜ [常见问题](docs/常见问题.md) ｜ [贡献](CONTRIBUTING.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qq-bot-roost",
-  "version": "0.8.7",
+  "version": "0.8.9",
   "type": "module",
   "description": "栖 Roost：零依赖的 QQ 官方机器人框架，填 AppID/AppSecret 即连，插件可写任意语言",
   "license": "SEE LICENSE IN LICENSE",
@@ -29,14 +29,17 @@
     "start": "node src/main.js",
     "mock": "node src/main.js --mock",
     "check": "node src/main.js --check",
-    "test": "node test/selftest.mjs && node test/qrlogin.mjs",
+    "test": "node test/selftest.mjs && node test/qrlogin.mjs && node test/deps.mjs",
     "test:e2e": "node test/e2e.mjs",
-    "test:all": "node test/selftest.mjs && node test/qrlogin.mjs && node test/e2e.mjs && node test/live-driver.mjs",
+    "test:all": "node test/selftest.mjs && node test/qrlogin.mjs && node test/deps.mjs && node test/e2e.mjs && node test/live-driver.mjs",
     "check:secrets": "node scripts/check-secrets.mjs",
     "create": "node scripts/create-plugin.mjs",
     "test:plugin": "node scripts/test-plugin.mjs",
     "live": "node scripts/live-test.mjs",
-    "market:index": "node scripts/build-market-index.mjs"
+    "market:index": "node scripts/build-market-index.mjs",
+    "sums": "node scripts/build-sums.mjs",
+    "sums:check": "node scripts/build-sums.mjs --check",
+    "sums:verify": "node scripts/build-sums.mjs --verify"
   },
   "author": {
     "name": "倦飞之鸟"

package/src/fsutil.js

@@ -23,7 +23,20 @@ export async function writeJsonAtomic(file, data) {
   const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
   const text = `${JSON.stringify(data, null, 2)}\n`;
   try {
-    await fs.writeFile(tmp, text, 'utf8');
+    /**
+     * `mode: 0o600` —— 只有属主能读写。
+     *
+     * 这些 JSON 里有 `config/bot.json`、`config/bots/<id>.json`，都带明文
+     * AppSecret；还有权限表、群档案。Linux 默认 umask 022 下新建文件是 644，
+     * 同机其他用户直接 `cat` 就能拿到机器人凭证。
+     *
+     * 注意两点：
+     *   - mode 只在**创建**时生效，而这里的 tmp 每次都是新文件，所以一定吃到
+     *   - rename 会保留临时文件的权限，覆盖掉旧文件原来的 644 —— 也就是说
+     *     用户只要保存过一次配置，老文件的权限就被修正了，不需要单独做迁移
+     *   - Windows 上 mode 被忽略，不影响运行
+     */
+    await fs.writeFile(tmp, text, { encoding: 'utf8', mode: 0o600 });
     await fs.rename(tmp, file);
   } catch (e) {
     await fs.rm(tmp, { force: true }).catch(() => {});

package/src/hashdir.js

@@ -77,16 +77,24 @@ async function collect(root) {
 }
 
 /**
- * 算目录的内容指纹。
+ * 按给定的相对路径清单算指纹。
  *
- * @param {string} dir 插件目录
+ * 为什么要单独一个入口：仓库根目录里有 `data/`、`logs/`、`config/`、`plugins/`
+ * 这些**不会被 tarball 打包**的东西，直接 `hashDir(ROOT)` 会把它们算进去，
+ * 跟「解包后的 tarball」永远对不上。
+ *
+ * 所以发布流程用 `git ls-files` 拿到「真正会被打进包的文件」，再喂给这里；
+ * 更新校验则用 `hashDir(解包目录)`。两边必须用同一套拼接方式，否则校验必失败。
+ *
+ * @param {string} root 根目录
+ * @param {string[]} rels 相对路径（`/` 分隔）；内部会去重并排序，顺序无关
  * @returns {Promise<string>} 64 位十六进制
  */
-export async function hashDir(dir) {
-  const files = await collect(dir);
+export async function hashFileList(root, rels) {
+  const files = [...new Set(rels)].sort();
   const h = crypto.createHash('sha256');
   for (const rel of files) {
-    const buf = normalize(await fs.readFile(path.join(dir, rel)));
+    const buf = normalize(await fs.readFile(path.join(root, rel)));
     h.update(rel);
     h.update('\0');
     h.update(String(buf.length));
@@ -96,3 +104,38 @@ export async function hashDir(dir) {
   }
   return h.digest('hex');
 }
+
+/**
+ * 算目录的内容指纹。
+ *
+ * @param {string} dir 插件目录
+ * @param {{exclude?: string[], only?: string[]}} [opts]
+ *   - `exclude`：精确匹配要跳过的相对路径（如 `SHA256SUMS` 这种会自引用的文件）
+ *   - `only`：只算这些路径（`src` 这类目录前缀，或 `package.json` 这类文件名）。
+ *     用途：GitHub 的 tarball 是**全量**（含 .github、scripts、sdk），
+ *     而 Gitee 源只拉会被更新覆盖的那几个条目，两边目录内容天生不同。
+ *     用 `only` 把范围收窄到「真正会被替换的代码」，两边才算得出同一个值。
+ * @returns {Promise<string>} 64 位十六进制
+ */
+export async function hashDir(dir, opts = {}) {
+  /**
+   * 根目录不存在时必须报错，**不能静默返回空哈希**。
+   *
+   * `collect()` 里对每个目录都有 try/catch（遍历时子目录读不到要跳过），
+   * 但连根目录都不存在时它也会安静地返回空数组，算出来就是
+   * `e3b0c442…`（空字符串的 sha256）—— 那是一个**合法值**，会像真指纹一样
+   * 参与比对，现象是「内容全变了」而不是「路径写错了」，排查时非常误导。
+   */
+  const st = await fs.stat(dir).catch(() => null);
+  if (!st?.isDirectory()) throw new Error(`算指纹失败：目录不存在或不是目录 —— ${dir}`);
+
+  const skip = new Set(opts.exclude ?? []);
+  const only = (opts.only ?? []).map((p) => String(p));
+  let files = (await collect(dir)).filter((rel) => !skip.has(rel));
+  if (only.length) {
+    files = files.filter((rel) =>
+      only.some((p) => rel === p || rel.startsWith(p.endsWith('/') ? p : `${p}/`)),
+    );
+  }
+  return hashFileList(dir, files);
+}

package/src/mirror.js

@@ -86,9 +86,36 @@ const AUTO_TTL = 10 * 60_000;
 export function configureMirror(globalCfg) {
   const n = globalCfg?.network ?? {};
   const id = String(n.mirror ?? 'auto').trim() || 'auto';
+
+  /**
+   * 自定义下载前缀必须是 https。
+   *
+   * 这个值会被直接拼在 tarball 地址前面（见 applyMirror），而这个项目**更新包
+   * 没有内容校验**（updater.js 的 expectSha256 恒为 null）。也就是说：
+   * 填一个 http 地址，等于让链路上的任何人决定你下一版跑什么代码。
+   *
+   * 不合法就退回默认（不用它），而不是抛错 —— 配置文件写错了不该让整个框架起不来。
+   */
+  let custom = String(n.mirrorCustom ?? '').trim();
+  if (custom) {
+    let u = null;
+    try {
+      u = new URL(custom.includes('://') ? custom : `https://${custom}`);
+    } catch {
+      u = null;
+    }
+    if (!u || u.protocol !== 'https:') {
+      log.warn(
+        `network.mirrorCustom 必须是 https:// 开头，已忽略：${custom}\n` +
+          '  （自定义下载源会决定你下一版跑什么代码，明文 http 等于把它交给链路上的任何人）',
+      );
+      custom = '';
+    }
+  }
+
   current = {
     id: PRESETS.some((p) => p.id === id) ? id : 'auto',
-    custom: String(n.mirrorCustom ?? '').trim(),
+    custom,
     // Gitee 私人令牌：选填。公开仓库匿名也能用，填了只是把 API 配额提上去
     giteeToken: String(n.giteeToken ?? '').trim(),
   };
@@ -160,6 +187,17 @@ export function applyMirror(url, preset, custom = current.custom) {
     // 允许用户只填域名，自动补协议和结尾斜杠
     let b = base.trim();
     if (!/^https?:\/\//i.test(b)) b = `https://${b}`;
+    /**
+     * 自定义前缀必须是 https —— 这里再挡一道。
+     *
+     * configureMirror 已经校验过配置里的值，但 `probeMirrors` 的 custom 是
+     * 面板请求体直接传进来的（「测速」按钮），不经过 configureMirror。
+     * 不合法就**退回原始地址**，不要拼一个 http 前缀上去。
+     */
+    if (preset.kind === 'custom' && !/^https:\/\//i.test(b)) {
+      log.warn(`自定义下载源必须是 https，已忽略：${base}`);
+      return url;
+    }
     if (!b.endsWith('/')) b += '/';
     // 已经是这个前缀了就别套第二次
     if (url.startsWith(b)) return url;

package/src/plugin/deps.js

@@ -1,5 +1,7 @@
 import { spawn } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
 import fs from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { rel } from '../paths.js';
@@ -74,9 +76,65 @@ async function usable(cmd, args = ['--version']) {
 
 let cachedRuntimes = null;
 
+const IS_WIN = process.platform === 'win32';
+
+/** npm 的安装参数。`--ignore-scripts` 见下面调用处的注释 */
+const NPM_ARGS = ['install', '--omit=dev', '--no-audit', '--no-fund', '--ignore-scripts'];
+
+/**
+ * pnpm 的安装参数。
+ *
+ * `--config.node-linker=hoisted`：默认的 pnpm 用软链把 `node_modules` 指到全局
+ * store，插件是被人手动丢进 `plugins/` 的，不归 pnpm 管；store 一清，
+ * `import` 就断。hoisted 给的是跟 npm 一样的扁平目录，行为最可预期。
+ *
+ * `--ignore-workspace`：插件目录万一落在某个 pnpm workspace 里面（用户把
+ * Roost 放在自己项目里就会），pnpm 会拒绝安装并让你去 workspace 根装。
+ */
+const PNPM_ARGS = ['install', '--prod', '--ignore-scripts', '--config.node-linker=hoisted', '--ignore-workspace'];
+
+/**
+ * DSH 桌面版自带的运行时目录。
+ *
+ * **为什么必须找它**：DSH 是 Electron，安装目录里既没有 `node.exe` 也没有
+ * npm；但它自己带了一整套运行时（node / pnpm / python），放在
+ * `~/.dsh/dsh-runtimes/<runtime>/dependencies/` 下——DSH 装插件用的就是那套 pnpm。
+ *
+ * 只查 PATH 的后果很严重：没单独装过 Node.js 的用户 PATH 里当然没有 npm，
+ * 于是任何带依赖的插件都会「缺少 npm」而**整个加载失败**，
+ * 明明机器上有一套现成能用的。
+ */
+export function bundledRuntimeRoots({ home = os.homedir() } = {}) {
+  const base = path.join(home, '.dsh', 'dsh-runtimes');
+  const out = [];
+  try {
+    for (const name of readdirSync(base)) {
+      const dir = path.join(base, name, 'dependencies');
+      if (existsSync(dir)) out.push(dir);
+    }
+  } catch {
+    // 没有这个目录很正常：用户可能根本没装 DSH 桌面版
+  }
+  // 名字里带 primary 的排前面——DSH 自己也优先用它
+  return out.sort((a, b) => Number(b.includes('primary')) - Number(a.includes('primary')));
+}
+
+/** 在若干运行时根目录里找同一个相对路径，找到就返回绝对路径 */
+function pickIn(roots, ...segs) {
+  for (const r of roots) {
+    const p = path.join(r, ...segs);
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
 /**
- * 找出这台机器上能用的 Python / Node 命令。
+ * 找出这台机器上能用的 Python / Node 命令，以及「用谁来装 Node 依赖」。
  * 只在第一次调用时真正探测，之后走缓存。
+ *
+ * 返回里的 `installer` 是个描述符 `{ kind, cmd, args, label }`——
+ * 因为 npm 和 pnpm 的参数不一样，而且 DSH 自带的 pnpm 还得靠自带的 node 去跑，
+ * 光有一个命令名表达不了。
  */
 export async function detectRuntimes({ refresh = false } = {}) {
   if (cachedRuntimes && !refresh) return cachedRuntimes;
@@ -103,7 +161,50 @@ export async function detectRuntimes({ refresh = false } = {}) {
     }
   }
 
-  cachedRuntimes = { python, npm, node: process.execPath };
+  // PATH 上的 pnpm：装了 Node.js 的人常常也装了它，参数比 npm 好控
+  let pnpm = null;
+  for (const c of IS_WIN ? ['pnpm.cmd', 'pnpm'] : ['pnpm']) {
+    if (await usable(c)) {
+      pnpm = c;
+      break;
+    }
+  }
+
+  /* ---------- DSH 自带运行时（PATH 上找不到时的兜底） ---------- */
+  const roots = bundledRuntimeRoots();
+  const bundledNode = pickIn(roots, 'node', 'bin', IS_WIN ? 'node.exe' : 'node');
+  const bundledPnpm = pickIn(roots, 'pnpm', 'bin', 'pnpm.cjs');
+  const bundledPython = IS_WIN
+    ? pickIn(roots, 'python', 'python.exe')
+    : (pickIn(roots, 'python', 'bin', 'python3') || pickIn(roots, 'python', 'bin', 'python'));
+
+  // 系统 Python 优先（用户可能装了带自己库的那个），找不到才用自带的
+  if (!python && bundledPython) python = bundledPython;
+
+  /**
+   * 装依赖用哪个工具。顺序：npm → pnpm → DSH 自带 pnpm。
+   *
+   * 自带 pnpm 必须用**自带的 node** 去跑 `pnpm.cjs`，不能用 `process.execPath`：
+   * 那是 DSH 的 Electron 主程序，只有在带 `ELECTRON_RUN_AS_NODE` 时才当 node 用，
+   * 而这个变量不在 `buildPluginEnv` 的白名单里，直接跑会把 GUI 拉起来。
+   */
+  let installer = null;
+  if (npm) {
+    installer = { kind: 'npm', cmd: npm, args: NPM_ARGS, label: 'npm' };
+  } else if (pnpm) {
+    installer = { kind: 'pnpm', cmd: pnpm, args: PNPM_ARGS, label: 'pnpm' };
+  } else if (bundledPnpm && bundledNode) {
+    installer = { kind: 'dsh-pnpm', cmd: bundledNode, args: [bundledPnpm, ...PNPM_ARGS], label: 'DSH 自带 pnpm' };
+  }
+
+  cachedRuntimes = {
+    python,
+    npm,
+    pnpm,
+    node: process.execPath,
+    installer,
+    bundled: { node: bundledNode, pnpm: bundledPnpm, python: bundledPython },
+  };
   return cachedRuntimes;
 }
 
@@ -146,15 +247,22 @@ function venvPython(venvDir) {
  * @param {object} p.manifest plugin.json 内容
  * @param {object} p.log      日志器
  * @param {boolean} [p.enabled] 是否允许自动安装（来自 config.plugins.autoInstallDeps）
+ * @param {object} [p.runtimes] 直接指定运行时探测结果，跳过 detectRuntimes()。
+ *   **只给测试用**：`detectRuntimes()` 带全局缓存，测「一个工具都没有」这条分支
+ *   只能靠伪造 PATH / HOME，会把别的测试带歪。
  * @returns {Promise<{python?:string, installed:string[], skipped:string[], warnings:string[]}>}
  */
-export async function ensurePluginDeps({ dir, manifest = {}, log = null, enabled = true }) {
+export async function ensurePluginDeps({ dir, manifest = {}, log = null, enabled = true, runtimes = null }) {
   const result = { python: null, installed: [], skipped: [], warnings: [] };
   // 统一转绝对路径：下面给 pip / npm 传的路径和 cwd 都以它为准，避免相对路径被拼两次
   dir = path.resolve(dir);
   const runtime = String(manifest.runtime ?? '').toLowerCase();
   const wantsPython = runtime === 'python' || runtime === 'python3';
 
+  // 一次探测，两处用；注入的优先
+  let rt = runtimes;
+  const getRt = async () => (rt ??= await detectRuntimes());
+
   const reqFile = path.join(dir, 'requirements.txt');
   const pkgFile = path.join(dir, 'package.json');
   const requirements = await readIfExists(reqFile);
@@ -162,10 +270,10 @@ export async function ensurePluginDeps({ dir, manifest = {}, log = null, enabled
 
   // 先确定 Python 解释器：有 venv 用 venv 的，没有就找系统的
   if (wantsPython) {
-    const rt = await detectRuntimes();
+    const rt = await getRt();
     if (!rt.python) {
       throw new Error(
-        '这个插件需要 Python，但系统里找不到 python / python3 / py。\n' +
+        '这个插件需要 Python，但系统里找不到 python / python3 / py，也没找到 DSH 自带的 Python。\n' +
           '请先安装 Python 3.9+（https://www.python.org/downloads/），装完重试。',
       );
     }
@@ -250,8 +358,20 @@ export async function ensurePluginDeps({ dir, manifest = {}, log = null, enabled
     } catch {
       result.warnings.push('package.json 不是合法 JSON，已跳过依赖安装');
     }
-    const deps = pkg ? Object.keys({ ...(pkg.dependencies ?? {}), ...(pkg.optionalDependencies ?? {}) }) : [];
-    if (deps.length) {
+
+    /**
+     * **必装和可选必须分开。**
+     *
+     * `dependencies` 缺了插件就是坏的；`optionalDependencies` 缺了只是某个功能
+     * 用不了。以前两者合并成一个列表，于是「语音这种可选能力」能把整个插件
+     * 拦在门外：找不到 npm 就 throw，`loader.js` 接住之后插件直接不加载。
+     * ai-chat 就是这么在没装 Node.js 的机器上整个起不来的。
+     */
+    const required = pkg ? Object.keys(pkg.dependencies ?? {}) : [];
+    const optional = pkg ? Object.keys(pkg.optionalDependencies ?? {}) : [];
+    const all = [...new Set([...required, ...optional])];
+
+    if (all.length) {
       const hasModules = await fs
         .access(path.join(dir, 'node_modules'))
         .then(() => true)
@@ -265,27 +385,41 @@ export async function ensurePluginDeps({ dir, manifest = {}, log = null, enabled
           '检测到 package.json 依赖需要安装，但 config 里 plugins.autoInstallDeps = false，已跳过',
         );
       } else {
-        const rt = await detectRuntimes();
-        if (!rt.npm) {
-          throw new Error('这个插件需要 npm 安装依赖，但系统里找不到 npm（通常随 Node.js 一起安装）');
-        }
-        log?.info(`安装 Node 依赖（${deps.length} 个），首次会慢一点…`);
-        // --ignore-scripts：依赖的 postinstall 就是任意代码执行入口，
-        // 装依赖不该顺带跑别人的安装脚本
-        const r = await run(
-          rt.npm,
-          ['install', '--omit=dev', '--no-audit', '--no-fund', '--ignore-scripts'],
-          { cwd: dir },
-        );
-        if (!r.ok) {
-          throw new Error(
-            `安装 Node 依赖失败：${r.reason || (r.err || r.out).slice(-600)}\n` +
-              `可以手动执行：cd ${rel(dir)} && npm install`,
+        const rt = await getRt();
+        if (!rt.installer) {
+          // 必装缺工具才算致命；可选缺工具只丢功能，不能让插件起不来
+          if (required.length) {
+            throw new Error(
+              `这个插件需要 ${required.length} 个 Node 依赖（${required.join('、')}），`
+                + '但系统里既没有 npm 也没有 pnpm，也没找到 DSH 自带的运行时。\n'
+                + '装一个 Node.js（https://nodejs.org/）再重启即可。',
+            );
+          }
+          result.warnings.push(
+            `有 ${optional.length} 个可选依赖（${optional.join('、')}）没装：`
+              + '找不到 npm / pnpm，也没找到 DSH 自带的运行时。相关功能会不可用，其余功能正常。',
+          );
+        } else {
+          log?.info(
+            `安装 Node 依赖（${all.length} 个，用 ${rt.installer.label}）`
+              + `${optional.length && !required.length ? '，都是可选的' : ''}，首次会慢一点…`,
           );
+          // --ignore-scripts：依赖的 postinstall 就是任意代码执行入口，
+          // 装依赖不该顺带跑别人的安装脚本
+          const r = await run(rt.installer.cmd, rt.installer.args, { cwd: dir });
+          const detail = `${r.reason || (r.err || r.out).slice(-600)}\n`
+            + `可以手动执行：cd ${rel(dir)} && ${rt.installer.label} install`;
+          if (!r.ok) {
+            if (required.length) throw new Error(`安装 Node 依赖失败：${detail}`);
+            result.warnings.push(`可选依赖没装上（不影响主功能）：${detail}`);
+          } else {
+            result.installed.push(`Node 依赖（${rt.installer.label}）`);
+          }
+          // 装过就记账（成不成功都记）。**不能靠它拦住重试**——
+          // 失败时 node_modules 仍然不存在，上面 `!hasModules` 会让下次加载再试一遍
+          marker.packageJson = wantPkg;
+          await writeMarker(dir, marker);
         }
-        result.installed.push('Node 依赖');
-        marker.packageJson = wantPkg;
-        await writeMarker(dir, marker);
       }
     }
   }

package/src/plugin/pages.js

@@ -17,8 +17,23 @@
  *   - 页面在 iframe 里渲染：CSS 不会漏到面板上，脚本也拿不到面板的 DOM
  *
  * 关于安全：插件**本身**就是可信代码（内建插件跑在主进程，外部插件是子进程），
- * 所以这里不做权限校验。iframe 的作用是样式隔离和避免互相干扰，不是沙箱边界。
+ * 所以这里不做权限校验。iframe 的作用是样式隔离和避免互相干扰。
+ *
+ * ## 页面令牌（page token）
+ *
+ * 2026-10-28 加：以前 iframe 地址上直接拼面板的 accessKey，插件页一行
+ * `location.search` 就能拿到面板全权（装插件 = 交出面板密码）。现在每个页面
+ * 注册时生成一个随机 token，iframe 只带 `?pt=<token>`，并且在面板侧配
+ * `sandbox="allow-scripts allow-forms"`（不给 allow-same-origin），
+ * 插件页既读不到父页 localStorage，也拿不到面板密钥。
+ *
+ * token 的权限边界由 server.js 的 `authorized()` 决定：只放行**该插件自己**的
+ * 页面与接口（`/api/pages/<id>:<key>/html`、`/api/plugins/<id>/panel`、
+ * `/api/plugins/<id>/r/*`），不放行 `/api/config`、`/api/logs` 等面板接口。
+ * 方法不限于 GET —— 斗罗那类运营后台要 POST 改数据，只读会直接废掉它，
+ * 而限制「插件写自己的数据」没有安全收益（插件本来就有子进程执行权）。
  */
+import crypto from 'node:crypto';
 import { createLogger } from '../logger.js';
 
 const log = createLogger('pages');
@@ -51,7 +66,13 @@ export class PageRegistry {
     }
 
     const full = `${pluginId}:${key}`;
-    this.pages.set(full, { key: full, shortKey: key, label, html, pluginId });
+    /**
+     * 页面令牌：24 字节随机（48 位十六进制），进程内有效。
+     * 插件重载会重新 register，于是自动换一把新的——旧页面标签刷一下就拿不到了，
+     * 这正是想要的（卸载/重载后旧链接失效）。
+     */
+    const token = crypto.randomBytes(24).toString('hex');
+    this.pages.set(full, { key: full, shortKey: key, label, html, pluginId, token });
     log.info(`插件 ${pluginId} 注册了面板页面「${label}」(${full})`);
     return full;
   }
@@ -75,9 +96,24 @@ export class PageRegistry {
       key: p.key,
       label: p.label,
       pluginId: p.pluginId,
+      // 前端拼 iframe 地址用。列表接口本身是鉴权过的，所以这里给得出去
+      token: p.token,
     }));
   }
 
+  /**
+   * 按页面令牌反查。给 `authorized()` 用：iframe 是 opaque origin，
+   * 拿不到 Cookie，只能靠这个 token 证明「我是这个面板页」。
+   * @returns {{key:string, pluginId:string, token:string}|null}
+   */
+  findByToken(token) {
+    if (!token) return null;
+    for (const p of this.pages.values()) {
+      if (p.token === token) return p;
+    }
+    return null;
+  }
+
   get(key) {
     return this.pages.get(String(key)) ?? null;
   }

package/src/update-scope.js

@@ -0,0 +1,28 @@
+/**
+ * 更新会替换的代码条目（单一来源）
+ * ================================
+ *
+ * 三处共用：
+ *   1. `updater.js` 备份与替换（rsync 式覆盖，绝不碰 config/data/logs/plugins）
+ *   2. `gitee.js` 的前缀过滤（Gitee 没有 archive 直链，只能按清单逐个拉）
+ *   3. `scripts/build-sums.mjs` 算内容指纹的范围
+ *
+ * 为什么指纹也按这个范围算：GitHub 的 tarball 是**全量**（还带 .github、
+ * scripts、sdk、types），而 Gitee 源只拉下面这几个条目。如果指纹按「包里的
+ * 全部文件」算，两条下载路径永远对不上 —— 一边写死校验失败，一边等于没校验。
+ *
+ * 改这个清单要连带重跑 `npm run sums`，否则已发布的指纹会全部失配。
+ */
+export const CODE_ENTRIES = [
+  'src',
+  'web',
+  'test',
+  'docs',
+  'package.json',
+  'README.md',
+  'LICENSE',
+  'start.bat',
+];
+
+/** 绝对不能删/覆盖的目录（双保险） */
+export const PROTECTED_ENTRIES = new Set(['config', 'data', 'logs', 'plugins', 'node_modules', '.git']);

package/src/updater.js

@@ -20,6 +20,8 @@ import { createLogger } from './logger.js';
 import { fetchAndExtract } from './tarball.js';
 import { fetchViaMirror, currentMirror } from './mirror.js';
 import { fetchGiteeTree, detectGiteeRef, giteeRawUrl } from './gitee.js';
+import { hashDir } from './hashdir.js';
+import { CODE_ENTRIES, PROTECTED_ENTRIES as PROTECTED } from './update-scope.js';
 import { ROOT } from './config.js';
 
 const log = createLogger('update');
@@ -27,11 +29,11 @@ const log = createLogger('update');
 /** 仓库信息。换成自己的 fork 就改这里 */
 const REPO = 'tdcq9594/qq-bot-roost';
 
-/** 允许被更新覆盖的顶层条目。**用户数据一个都不在里面** */
-const CODE_ENTRIES = ['src', 'web', 'test', 'docs', 'package.json', 'README.md', 'LICENSE', 'start.bat'];
-
-/** 绝对不能删的目录，双保险 */
-const PROTECTED = new Set(['config', 'data', 'logs', 'plugins', 'node_modules', '.git']);
+/**
+ * 允许被更新覆盖的顶层条目、以及绝对不能碰的目录，都在 ./update-scope.js。
+ * 内容指纹用的是**同一份清单**——GitHub tarball 是全量、Gitee 只拉这几个条目，
+ * 范围不一致的话两条下载路径算出来的指纹永远对不上。
+ */
 
 /**
  * Gitee 源下拉取的文件范围：只拉会被更新覆盖的代码条目。
@@ -100,9 +102,58 @@ async function updatedButNotRestarted() {
  * 包一层而不是往 checkUpdate 里塞：里面有好几个返回分支（Gitee /
  * 主站 302 / API 兜底 / 404 / 失败），每个都手写一遍 needsRestart 迟早漏一个。
  */
+/**
+ * 拉 SHA256SUMS，得到「版本 → 内容指纹」的映射。
+ *
+ * 两个源都试：GitHub raw（经下载源改写）和 Gitee raw。任何一边拿到都行，
+ * 因为指纹是「代码内容」的，与从哪个源下载无关。
+ *
+ * @returns {Promise<Map<string,string>>} 版本号 → 64 位十六进制
+ */
+async function fetchSumsMap() {
+  const urls = [
+    `https://raw.githubusercontent.com/${REPO}/master/SHA256SUMS`,
+    `https://gitee.com/${REPO}/raw/master/SHA256SUMS`,
+  ];
+  for (const u of urls) {
+    try {
+      const res = await fetchViaMirror(u, {
+        headers: { 'User-Agent': 'qq-bot-roost-updater' },
+        signal: AbortSignal.timeout(8000),
+      });
+      if (!res.ok) continue;
+      const text = await res.text();
+      const map = new Map();
+      for (const line of text.split(/\r?\n/)) {
+        const m = /^([a-f0-9]{64})\s+v?([0-9][\w.+-]*)$/i.exec(line.trim());
+        if (m) map.set(m[2].replace(/^v/i, ''), m[1].toLowerCase());
+      }
+      if (map.size) return map;
+    } catch {
+      // 换下一个源
+    }
+  }
+  return new Map();
+}
+
+/**
+ * 查某个版本的内容指纹。拿不到返回 null —— 真正的拒绝发生在 applyUpdate，
+ * 因为「只检查不安装」时面板仍应正常显示有新版本，只是点更新会失败。
+ */
+async function fetchTreeSha256(version) {
+  try {
+    const map = await fetchSumsMap();
+    return map.get(String(version).replace(/^v/, '')) ?? null;
+  } catch {
+    return null;
+  }
+}
+
 export async function checkUpdate() {
   const needsRestart = await updatedButNotRestarted();
   const r = await checkUpdateCore();
+  // 有新版本才值得多跑一次网络请求
+  if (r?.ok && r.hasUpdate) r.treeSha256 = await fetchTreeSha256(r.latest);
   return { ...r, needsRestart };
 }
 
@@ -442,6 +493,37 @@ async function applyUpdateOnce(info) {
       throw new Error('下载的包里没有 src/main.js，不是合法的框架包，已中止');
     });
 
+    /**
+     * 内容指纹校验 —— **必须放在备份和替换之前**。
+     *
+     * 这一步失败就等于什么都没发生过：文件没动、备份也没建。
+     *
+     * 为什么必须严格：更新会直接覆盖 `src/`、`web/` 这些要执行的代码。
+     * 只要能改掉下载地址（自定义镜像、上游仓库被入侵、链路劫持），
+     * 就能决定用户下一版跑什么。指纹对不上就说明「下载到的东西不是作者发的」。
+     *
+     * 为什么没有指纹也要拒绝：留一个「没指纹就放行」的口子，攻击者只要把
+     * SHA256SUMS 里那条删掉或让仓库回到没有该文件的形态就能绕过。
+     * 代价是发布流程必须每版都带指纹 —— 这由 CI 的 `npm run sums:check` 守着。
+     */
+    if (!rel.treeSha256) {
+      throw new Error(
+        `v${rel.latest} 没有发布内容指纹（SHA256SUMS 里查不到），已拒绝自动更新。\n` +
+          '这不是你的网络问题：作者这一版可能漏了生成指纹。\n' +
+          '可以手动到 GitHub Releases 下载安装，或等下一版。你的代码没有任何改动。',
+      );
+    }
+    const gotHash = await hashDir(workDir, { only: CODE_ENTRIES });
+    if (gotHash !== rel.treeSha256) {
+      throw new Error(
+        `更新内容校验失败，已中止（你的代码没有任何改动）。\n` +
+          `  期望 ${rel.treeSha256}\n` +
+          `  实际 ${gotHash}\n` +
+          '可能是下载源被篡改，或者发布时改了代码却忘了重跑 npm run sums。',
+      );
+    }
+    log.info(`内容指纹校验通过（${gotHash.slice(0, 12)}…）`);
+
     // 备份现有代码
     await fs.mkdir(backupDir, { recursive: true });
     for (const name of CODE_ENTRIES) {