dsh-qq-digest 0.1.0 → 0.2.0

package/README.md

@@ -49,6 +49,9 @@
 
 - `llm`（默认）：OpenAI 兼容接口，结构化 JSON。密钥取 `QQ_DIGEST_LLM_API_KEY` 或 `~/.dsh/.credentials.yaml` 的 `DEEPSEEK_API_KEY`。
   失败**不静默降级**，直接抛 `LLM_*` 错误码。
+  ⚠️ **知情提示**：选 `llm` 意味着被摘要的群/私聊**消息正文、昵称，以及被 @ 的 QQ 号**会发送到
+  模型服务商（默认 `api.deepseek.com`）。不能接受这一点就选 `heuristic`（纯本地规则，不出网）。
+  摘要是对**不可信输入**的加工结果：群成员可以往群名/正文里塞指令，摘要只能当数据看，不能当指令执行。
 - `heuristic`：本地关键词规则，零网络零成本，质量有上限（会漏也会误抓）。
 
 ## 配置
@@ -69,7 +72,10 @@
 
 - 不写 `groups` = 所有群都可读。
 - `groups` 里只用于**关掉**某个群或给它起名。
-- 写出 `private` / `friend` / `send` / `scope` 一类键 → 整份配置作废 → **全关**（fail-closed）。
+- `private` 是**受支持的一等键**：`{ "88880001": { "enabled": true } }` 逐条打开私聊；
+  不允许一键全开（`private.defaultEnabled=true` 在策略解析阶段即判非法 → 全关）。
+- 写出 `friend` / `send` / `reply` / `scope` / `write` 一类**危险键** → 整份配置作废 → **全关**（fail-closed）；
+  与安全无关的未知键被忽略。
 - 配置损坏同理：全关，不回退到「默认允许」。
 
 ## 落盘
@@ -82,9 +88,11 @@
 ## 验证
 
 ```bash
-npm run verify            # core 纯净性检查 + 51 个用例
-node scripts/smoke.mjs        # fixture 端到端（真实子进程走 MCP 协议）
-node scripts/smoke.mjs bridge # 真桥接只读冒烟
+npm run verify                      # core 纯净性检查 + 全部用例（当前 116）
+node scripts/smoke.mjs              # fixture 端到端（真实子进程走 MCP 协议）
+node scripts/smoke.mjs bridge       # 真桥接只读冒烟
+node scripts/host-smoke.mjs         # 宿主半：假 ctx 跑 apply()，真 req/res 打路由（含跨站/伪造 Host 用例）
+node scripts/final-check.mjs        # 发布前自检（脱敏词从 QQ_DIGEST_SENSITIVE_PATTERNS 读，不写死在仓库里）
 ```
 
 core 纯净性检查锁定：`src/core/` 不许 import `node:fs` / 子进程 / 网络，不许出现 `fetch(`、`send_*`、`/api/send`、写文件符号。
@@ -148,9 +156,10 @@ core 纯净性检查锁定：`src/core/` 不许 import `node:fs` / 子进程 /
 
 ## 安装进 DSH
 
-这一步分两块，互不冲突（row id 不同）：
-
 ```bash
+# 0) （可选）从 npm 拿包，或直接把本仓库放到任意目录
+npm i dsh-qq-digest
+
 # 1) MCP 行：给模型用的四个只读工具
 node scripts/install.mjs --apply
 
@@ -158,6 +167,11 @@ node scripts/install.mjs --apply
 node scripts/link-profile.mjs --apply
 ```
 
+第 1 步还会把本机 qq-bridge 的位置写进 `<DSH_HOME>/qq-digest/bridge-root.txt`
+（源码里不硬编码任何绝对路径）。如果没自动找到，用 `--bridge-root=D:/path/to/qq-bridge` 指定。
+
+**包内不含任何作者的个人信息**：QQ 号、群号、用户目录都是脱敏后的假值或运行时解析。
+
 第 2 步**不走 pnpm**：本机 profile 的 `node_modules` 里有文件被占用
 （`@img/sharp-win32-x64` 会在 pnpm 重装时报 `ERR_PNPM_EPERM`），所以这里用
 junction + 手改 profile `package.json`（会自动备份），和本机 `dsh-instruction-memory` 的装法一致。
@@ -201,9 +215,18 @@ node scripts/verify-dsh.mjs      # 宿主半在线？客户端半上次启动有
 
 ## 已知限制（不美化）
 
-- **设置页的开关不是安全边界**：`/qq-digest-api` 只允许回环地址访问，但本机任何进程
-  （包括模型通过 bash 起一个 `curl`）都能 POST 改配置。开关管的是「默认不读」，
-  不是「别人改不了」。真要防，得给 API 加一次性的会话令牌，本期没做。
+- **设置页的开关不是安全边界**：`/qq-digest-api` 允许**本机进程**（包括模型通过 bash 起一个 `curl`）直接 POST 改配置。
+  它挡住的是**浏览器与网络**，不是本机同一用户下的进程。
+- 管理面已做的校验（`lib/index.js` 的 `denyUntrustedRequest`）：
+  ① 来源必须是回环（`remoteAddress`）；② `Host` 必须是回环字面量（挡 DNS rebinding）；
+  ③ `Origin` 必须是回环来源；④ `Sec-Fetch-Site: cross-site` 直接拒；
+  ⑤ 写操作必须是 `application/json` —— 这个类型跨源必预检，而本服务不返回任何 CORS 头，
+  于是 `<form>` / `text/plain` 的 CSRF 简单请求进不来。
+- 反代 / 公网隧道仍会让 `remoteAddress` 看起来是回环：**不要把本插件挂在公网隧道后面**。
+- 句柄密钥不再有源码默认值：`QQ_DIGEST_SECRET` → `<数据目录>/handle-secret`（首次启动随机生成并落盘）。
+  写不进去就拒绝启动，而不是退回弱密钥。`/state` 的 `secretSource` 会如实告诉你当前用哪一种。
+- 读取摘要会**按当前策略现算授权**：关掉某个群或关掉总开关之后，该群历史摘要立即读不到（本轮修复）。
+  拒绝列表里返回的是 `auditRef`（独立 HMAC 域），它**不能**用来读任何摘要。
 - 私聊只在 `bridge` 数据源下可用；`snowluma` 适配器只调群历史，没有私聊取数路径。
 - `bridge` 源的群名是空的（桥接不存群名）；可在 `config.json` 的 `groups.<id>.name` 里人工命名。
 - `bridge` 源每轮最多回看 **100 条**（桥接 `/api/messages` 的硬上限）。两次运行之间新增超过 100 条时，
@@ -212,6 +235,11 @@ node scripts/verify-dsh.mjs      # 宿主半在线？客户端半上次启动有
 - `snowluma` 源是 `stateless`：每轮全量重算固定窗口（默认 60 条）。原因是 OneBot 的 `message_id`
   不保证单调，拿它当水位线会静默漏读新消息。
 - 句子级启发式摘要对「谁负责」判断保守：猜不准就回退成发消息的人，不做过度推断。
-- `config.json` 里的 `schedule` 字段目前只是**描述性配置**：插件本身不注册定时任务。
-  要每天自动跑，需要另外用 DSH 的 automation 建一条定时任务去调用 `qq_digest_run_summary`。
+- `config.json` 的 `schedule` 由**宿主半自己**执行：`lib/index.js` 每 30s tick 一次，到点跑一轮
+  （启动后 5s 还会补跑一次，避免刚好在到点后才启动而整天漏跑）。
+  跨进程互斥用 `run.lock`（带心跳续租，长轮次不会被判成陈旧锁抢占）。
+- 手动「立即总结」**不会**吞掉当天的定时：去重只认 `lastTrigger === "scheduled"` 的那一次。
 - 未评估 QQ 侧 ToS 与账号风险；本插件只读本地桥接/网关接口，不额外登录。
+- **`/state` 会明文回显群号与私聊 QQ 号**：设置页要靠它们做开关和提交，不做掩码是刻意选择
+  （入口已经用来源校验收窄到回环同源）。因此别在截图、录屏、远程协助里展示设置页。
+- 未做速率限制：`/run` 与 `run_summary` 可以被反复触发，会放大 LLM 调用费用。需要限流请在外层加。

package/install/cordis.patch.fragment.yml

@@ -6,7 +6,10 @@
       config:
         serverName: qq-digest
         transport: stdio
-        command: 'D:\Program Files\nodejs\node.exe'
+        # __NODE_EXE__ 由 install.mjs 用 process.execPath 替换。
+        # 模板里绝不能出现作者机器上的绝对路径：换台机器就会 spawn ENOENT，
+        # 表现为「MCP 工具全部消失但插件看起来装上了」。
+        command: '__NODE_EXE__'
         args:
           - '__PACKAGE_ROOT__/src/run-mcp.mjs'
         toolCallTimeoutMs: 180000

package/lib/index.js

@@ -18,7 +18,7 @@ import { join } from 'node:path';
 import { canonicalize, KIND } from '../src/core/canonical.js';
 import { roomHandle } from '../src/core/gate.js';
 import { configPath, defaultConfig, loadConfig, saveConfig } from '../src/config.js';
-import { resolveDataDir, resolveSecret, createRuntime } from '../src/runtime.js';
+import { resolveDataDir, createRuntime } from '../src/runtime.js';
 import { withRunLock } from '../src/run-lock.js';
 
 export const name = 'dsh-qq-digest';
@@ -34,11 +34,12 @@ export function apply(ctx) {
   mkdirSync(dataDir, { recursive: true });
 
   const stateFile = join(dataDir, 'schedule-state.json');
-  const secret = resolveSecret();
 
   let runtime = null;
   const getRuntime = () => {
-    if (runtime === null) runtime = createRuntime({ dataDir, secret });
+    // createRuntime 自己解析密钥（env → <dataDir>/handle-secret → 首次生成），
+    // 与 MCP 半走同一份实现，保证两边算出的句柄一致。
+    if (runtime === null) runtime = createRuntime({ dataDir });
     return runtime;
   };
 
@@ -52,6 +53,7 @@ export function apply(ctx) {
   // ── 状态 ────────────────────────────────────────────────────────────────
 
   async function buildState() {
+    const secret = getRuntime().secret;
     const loaded = loadConfig(configPath(dataDir));
     const config = loaded.config;
     const scheduleState = readScheduleState(stateFile);
@@ -113,6 +115,8 @@ export function apply(ctx) {
       privateRooms,
       configError: loaded.error,
       policyDegraded: Boolean(loaded.policy?.degraded),
+      // 密钥来源如实上报（env / generated / file / explicit）。值本身永不下发。
+      secretSource: getRuntime().secretSource,
       summarizer: config.summarizer,
       schedule: config.schedule,
       scheduleState,
@@ -129,7 +133,11 @@ export function apply(ctx) {
   // ── 配置写入 ─────────────────────────────────────────────────────────────
 
   function saveFromUi(body) {
-    const current = loadConfig(configPath(dataDir)).config;
+    const loaded = loadConfig(configPath(dataDir));
+    // 配置文件本身坏了时 loadConfig 会回退成默认值；拿这个默认值当 current 再保存，
+    // 会把用户原有的 groups 静默清空。宁可明确拒绝，让人先修好文件。
+    if (loaded.error) throw badRequest(`CONFIG_UNREADABLE:${loaded.error}`);
+    const current = loaded.config;
 
     const groups = {};
     const inputGroups = body?.groups ?? {};
@@ -205,7 +213,7 @@ export function apply(ctx) {
   // ── 路由 ────────────────────────────────────────────────────────────────
 
   function handler(req, res) {
-    if (denyNonLoopback(req, res)) return;
+    if (denyUntrustedRequest(req, res)) return;
 
     let url;
     try {
@@ -249,9 +257,19 @@ export function apply(ctx) {
           if (!canonical.ok || canonical.kind !== KIND.GROUP) {
             return sendJson(res, 400, { ok: false, error: 'ONLY_GROUPS' });
           }
-          const handle = roomHandle(secret, canonical.canonicalId);
-          const entry = getRuntime().store.latest(handle);
-          return sendJson(res, 200, { ok: true, groupId: canonical.groupId, digest: entry?.digest ?? null, createdAt: entry?.createdAt ?? null });
+          // 与 MCP 工具走同一条读取路径：读取也要按当前策略复核，
+          // 否则「关掉这个群」只影响下一轮取数，历史摘要照样读得到。
+          const handle = roomHandle(getRuntime().secret, canonical.canonicalId);
+          const out = await getRuntime().service.getDigest(handle);
+          const entry = out.status === 'OK' ? out.entry : null;
+          return sendJson(res, 200, {
+            ok: true,
+            groupId: canonical.groupId,
+            status: out.status,
+            ...(out.reason ? { reason: out.reason } : {}),
+            digest: entry?.digest ?? null,
+            createdAt: entry?.createdAt ?? null,
+          });
         }
 
         return sendJson(res, 404, { ok: false, error: 'NOT_FOUND' });
@@ -279,10 +297,7 @@ export function apply(ctx) {
       if (!isDue(schedule, now)) return;
 
       const state = readScheduleState(stateFile);
-      if (state.lastRunAt) {
-        const last = nowIn(schedule.timeZone, new Date(state.lastRunAt));
-        if (last.dateKey === now.dateKey) return; // 今天已经跑过
-      }
+      if (alreadyRanToday(state, schedule, now)) return;
 
       const result = await runOnce('scheduled');
       ctx.logger?.info?.(`[qq-digest] 定时总结 ${now.dateKey} ${now.hhmm} → ${result.status}`);
@@ -381,7 +396,8 @@ function nowIn(timeZone, at = new Date()) {
   return {
     dateKey: `${year}-${month}-${day}`,
     hhmm: `${hour}:${minute}`,
-    weekday: index >= 0 ? WEEKDAY_CODES[index] : 'MO',
+    // 解析不出来就是 null，不再默默当成周一：fail-open 会让「每周一」的任务在错误的星期跑。
+    weekday: index >= 0 ? WEEKDAY_CODES[index] : null,
   };
 }
 
@@ -401,9 +417,22 @@ function normalizeSchedule(raw) {
   };
 }
 
+/**
+ * 今天是否已经「由定时任务」跑过。
+ *
+ * 只认 lastTrigger === 'scheduled'：手动跑也会写 lastRunAt，若把它当成定时已完成，
+ * 用户在 08:59 手点一次「立即总结」，09:00 的定时就会被静默吞掉 —— 而且没有任何提示。
+ */
+function alreadyRanToday(state, schedule, now) {
+  if (state?.lastTrigger !== 'scheduled' || !state.lastRunAt) return false;
+  const last = nowIn(schedule.timeZone, new Date(state.lastRunAt));
+  return last.dateKey === now.dateKey;
+}
+
 function isDue(schedule, now) {
   if (now.hhmm !== schedule.time) return false;
   if (schedule.kind === 'daily') return true;
+  if (!now.weekday) return false; // 周几不可判定 → 不跑，而不是猜一个
   return Array.isArray(schedule.weekdays) && schedule.weekdays.includes(now.weekday);
 }
 
@@ -412,10 +441,11 @@ function readScheduleState(file) {
     const parsed = JSON.parse(readFileSync(file, 'utf8'));
     return {
       lastRunAt: typeof parsed?.lastRunAt === 'string' ? parsed.lastRunAt : null,
+      lastTrigger: typeof parsed?.lastTrigger === 'string' ? parsed.lastTrigger : null,
       lastStatus: typeof parsed?.lastStatus === 'string' ? parsed.lastStatus : null,
     };
   } catch {
-    return { lastRunAt: null, lastStatus: null };
+    return { lastRunAt: null, lastTrigger: null, lastStatus: null };
   }
 }
 
@@ -429,14 +459,64 @@ function writeScheduleState(file, { lastRunAt, trigger, status }) {
   }
 }
 
-function denyNonLoopback(req, res) {
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1', '[::1]']);
+
+/**
+ * 管理面入口校验。
+ *
+ * 只判 remoteAddress 是不够的，有三种真实场景会绕过去：
+ *  1) DNS rebinding：攻击者的域名解析到 127.0.0.1，浏览器会把请求发到本机，remoteAddress 就是回环；
+ *  2) 任意网页的跨站请求：浏览器发出的简单请求（form / text-plain）不需要预检，服务端不校验就照做；
+ *  3) 反向代理 / 公网隧道：转进来的请求 remoteAddress 通常也是 127.0.0.1。
+ *
+ * 因此这里同时校验 Host、Origin、Sec-Fetch-Site，并要求写操作必须是 application/json
+ * （该类型跨源必预检，而本服务不返回任何 CORS 头，预检不可能通过）。
+ */
+function denyUntrustedRequest(req, res) {
   const address = String(req.socket?.remoteAddress ?? '');
   const loopback = address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1';
-  if (loopback) return false;
-  sendJson(res, 403, { ok: false, error: 'LOCAL_ONLY' });
+  if (!loopback) return reject(res, 403, 'LOCAL_ONLY');
+
+  if (!hostIsLoopback(req.headers?.host)) return reject(res, 403, 'BAD_HOST');
+  if (!originIsLoopback(req.headers?.origin)) return reject(res, 403, 'BAD_ORIGIN');
+
+  const site = String(req.headers?.['sec-fetch-site'] ?? '').toLowerCase();
+  if (site === 'cross-site') return reject(res, 403, 'CROSS_SITE');
+
+  const method = String(req.method ?? 'GET').toUpperCase();
+  if (method === 'POST') {
+    const type = String(req.headers?.['content-type'] ?? '').toLowerCase();
+    if (!type.startsWith('application/json')) return reject(res, 415, 'JSON_REQUIRED');
+  }
+
+  return false;
+}
+
+function reject(res, status, error) {
+  sendJson(res, status, { ok: false, error });
   return true;
 }
 
+function hostIsLoopback(header) {
+  if (typeof header !== 'string' || header.trim() === '') return false;
+  let value = header.trim().toLowerCase();
+  // IPv6 形如 [::1]:1875，先剥掉端口
+  if (value.startsWith('[')) value = value.slice(0, value.indexOf(']') + 1);
+  else value = value.split(':')[0];
+  return LOOPBACK_HOSTS.has(value);
+}
+
+function originIsLoopback(header) {
+  // 没有 Origin 说明不是跨源浏览器请求（同源导航、curl、脚本），交给 Host 校验兜住。
+  if (typeof header !== 'string' || header.trim() === '') return true;
+  try {
+    const url = new URL(header.trim());
+    return LOOPBACK_HOSTS.has(url.hostname.toLowerCase());
+  } catch {
+    return false;
+  }
+}
+
 function readJson(req) {
   return new Promise((resolve, reject) => {
     let size = 0;
@@ -475,5 +555,13 @@ function sendJson(res, status, payload) {
   res.end(body);
 }
 
-/** 仅供单元测试：时区换算与到期判定是定时逻辑里最容易错的部分。 */
-export const __test = { nowIn, isDue, normalizeSchedule };
+/** 仅供单元测试：时区换算、到期判定与管理面来源校验是最容易出错的三块。 */
+export const __test = {
+  nowIn,
+  isDue,
+  alreadyRanToday,
+  normalizeSchedule,
+  readScheduleState,
+  writeScheduleState,
+  denyUntrustedRequest,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-qq-digest",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "只读的 DSH QQ 摘要插件：群聊默认全开、私聊默认全关且只能逐条打开；MCP 四个只读工具 + 设置页（选群/起名/定时/立即总结），零发送能力",
   "type": "module",
   "license": "MIT",
@@ -26,7 +26,8 @@
     "mcp"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=20",
+    "dsh": ">=0.2.0-0 <0.3.0"
   },
   "main": "lib/index.js",
   "exports": {
@@ -51,6 +52,7 @@
   "files": [
     "lib",
     "src",
+    "scripts",
     "install",
     "cordis.patch.yml",
     "README.md",

package/scripts/check-all.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * 全量自检：把「插件在 DSH 里到底通不通」一次跑完。
+ *
+ * 只做只读探测 + 三个必然失败的写入（用来验证拒绝路径），不改动你的真实配置。
+ *
+ * 用法：node scripts/check-all.mjs [端口]
+ */
+
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const PORTS = process.argv[2] ? [Number(process.argv[2])] : [4845, 8784, 1402, 14802];
+const DATA_DIR = join(process.env.DSH_HOME?.trim() || join(homedir(), '.dsh'), 'qq-digest');
+
+let failures = 0;
+const ok = (label, detail) => console.log(`PASS  ${label}${detail ? `  ${detail}` : ''}`);
+const bad = (label, detail) => { console.log(`FAIL  ${label}${detail ? `  ${detail}` : ''}`); failures += 1; };
+const info = (label, detail) => console.log(`INFO  ${label}${detail ? `  ${detail}` : ''}`);
+
+// ── 1. 静态：源码完整性 ───────────────────────────────────────────────────
+for (const file of ['lib/index.js', 'lib/client.js', 'src/config.js', 'src/runtime.js', 'src/service.js', 'package.json', 'cordis.patch.yml']) {
+  if (existsSync(join(root, file))) ok(`文件存在 ${file}`);
+  else bad(`缺文件 ${file}`);
+}
+
+const manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+if (manifest.dsh?.bundle?.patch) ok('manifest: dsh.bundle.patch', manifest.dsh.bundle.patch);
+else bad('manifest 缺 dsh.bundle.patch');
+if (manifest.dsh?.client?.platform === 'web') ok('manifest: dsh.client.platform', 'web');
+else bad('manifest 缺 dsh.client.platform');
+if (Array.isArray(manifest.dsh?.client?.inject) && manifest.dsh.client.inject.length > 0) {
+  ok('manifest: dsh.client.inject', manifest.dsh.client.inject.length + ' 个依赖');
+} else bad('manifest 缺 dsh.client.inject');
+
+const patch = readFileSync(join(root, 'cordis.patch.yml'), 'utf8');
+if (/-\s*insert:/.test(patch) && /name:\s*dsh-qq-digest/.test(patch)) ok('bundle patch 形态正确');
+else bad('bundle patch 形态不对');
+
+// ── 2. profile 接线 ──────────────────────────────────────────────────────
+const profileDir = join(process.env.DSH_HOME?.trim() || join(homedir(), '.dsh'), 'profiles', 'desktop');
+try {
+  const profilePkg = JSON.parse(readFileSync(join(profileDir, 'package.json'), 'utf8'));
+  if (profilePkg.dsh?.profile?.bundles?.includes('dsh-qq-digest')) ok('profile 已登记 bundle');
+  else bad('profile 未登记 bundle');
+  if (profilePkg.dependencies?.['dsh-qq-digest']) ok('profile 已登记依赖', profilePkg.dependencies['dsh-qq-digest']);
+  else bad('profile 未登记依赖');
+
+  const linkPath = join(profileDir, 'node_modules', 'dsh-qq-digest');
+  if (existsSync(linkPath)) ok('junction 存在');
+  else bad('junction 不存在');
+} catch (err) {
+  bad('读不到 profile', String(err.message));
+}
+
+// ── 3. 宿主半在线与状态形状 ──────────────────────────────────────────────
+let base = null;
+for (const port of PORTS) {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/qq-digest-api/state`, {
+      headers: { accept: 'application/json' },
+      signal: AbortSignal.timeout(6000),
+    });
+    if (res.status === 200) { base = `http://127.0.0.1:${port}`; break; }
+  } catch { /* 下一个端口 */ }
+}
+
+if (base === null) {
+  bad('宿主半不在线（DSH 没跑，或 bundle 没加载）');
+} else {
+  ok('宿主半在线', base);
+  const state = await (await fetch(`${base}/qq-digest-api/state`, { headers: { accept: 'application/json' } })).json();
+  const newHost = typeof state.groupsEnabled === 'boolean';
+
+  if (typeof state.groupsEnabled === 'boolean') ok('状态含群聊总开关', String(state.groupsEnabled));
+  else bad('状态缺 groupsEnabled —— 宿主半还是旧版本，需要重启');
+
+  if (Array.isArray(state.privateRooms)) {
+    ok('状态含私聊列表', `${state.privateRooms.length} 条，打开 ${state.privateRooms.filter((r) => r.enabled).length} 条`);
+    const named = state.privateRooms.filter((r) => r.named);
+    info('已命名的私聊', named.length ? named.map((r) => `${r.qq}→${r.name}`).join(', ') : '(无)');
+  } else bad('状态缺 privateRooms —— 宿主半还是旧版本');
+
+  info('群列表', (state.rooms ?? []).map((r) => `${r.title ?? r.groupId}${r.enabled ? '' : '(关)'}`).join(' / ') || '(空)');
+  info('摘要器', state.summarizer);
+  info('定时', JSON.stringify(state.schedule));
+  info('客户端心跳', JSON.stringify(state.clientBoot ?? null));
+
+  if (state.clientBoot === undefined) {
+    info('clientBoot', '旧版宿主没有这个字段（重启后才有），不代表客户端有问题');
+  } else if (state.clientBoot?.mountedAt) {
+    ok('客户端半已注册设置页');
+  } else if (state.clientBoot?.factoryAt) {
+    bad('客户端半执行了但没注册上', state.clientBoot.lastError ?? state.clientBoot.lastPhase);
+  } else {
+    bad('客户端半没有任何心跳（bundle 没执行）');
+  }
+
+  if (state.policyDegraded) bad('策略降级（配置损坏 → 全关）', state.configError);
+  else ok('策略正常（未降级）');
+
+  if (state.adapterError) bad('数据源报错', state.adapterError.message);
+  else ok('数据源无报错');
+
+  // 拒绝路径：这三个都必须在落盘前被拒
+  const post = async (path, body) => {
+    const res = await fetch(`${base}${path}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    return { status: res.status, json: await res.json().catch(() => ({})) };
+  };
+
+  const badGroup = await post('/qq-digest-api/config', { groups: { 'private:88880001': { enabled: true } } });
+  if (badGroup.status === 400) ok('群列表里塞私聊 id → 400');
+  else bad('群列表里塞私聊 id 没被拒', badGroup.status);
+
+  const badTime = await post('/qq-digest-api/config', { schedule: { enabled: true, kind: 'daily', time: '25:99', weekdays: ['MO'], timeZone: 'Asia/Shanghai' } });
+  if (badTime.status === 400) ok('非法定时时间 → 400');
+  else bad('非法定时时间没被拒', badTime.status);
+
+  const badPrivate = newHost
+    ? await post('/qq-digest-api/config', { private: { abc: { enabled: true } } })
+    : null;
+  if (badPrivate === null) info('跳过私聊键校验', '宿主半是旧版本，还没有 private 字段');
+  else if (badPrivate.status === 400) ok('私聊键不是 QQ 号 → 400');
+  else bad('非法私聊键没被拒', badPrivate.status);
+
+  const badDigest = await fetch(`${base}/qq-digest-api/digest?group=private:1`);
+  if (badDigest.status === 400) ok('按私聊取摘要 → 400');
+  else bad('按私聊取摘要没被拒', badDigest.status);
+
+  const notFound = await fetch(`${base}/qq-digest-api/nope`);
+  if (notFound.status === 404) ok('未知路径 → 404');
+  else bad('未知路径返回异常', notFound.status);
+}
+
+// ── 4. 落盘 ──────────────────────────────────────────────────────────────
+for (const [name, label] of [['config.json', '配置'], ['digests.jsonl', '摘要'], ['watermarks.json', '水位线'], ['client-boot.json', '客户端心跳']]) {
+  const file = join(DATA_DIR, name);
+  if (!existsSync(file)) { info(`${label}文件`, `${name} 不存在`); continue; }
+  const size = statSync(file).size;
+  if (name.endsWith('.jsonl')) {
+    const lines = readFileSync(file, 'utf8').split('\n').filter(Boolean).length;
+    info(`${label}文件`, `${name} ${lines} 行 / ${size}B`);
+  } else {
+    info(`${label}文件`, `${name} ${size}B`);
+  }
+}
+
+if (existsSync(join(DATA_DIR, 'config.json'))) {
+  const cfg = JSON.parse(readFileSync(join(DATA_DIR, 'config.json'), 'utf8'));
+  info('配置内容', JSON.stringify({
+    groupsEnabled: cfg.groupsEnabled,
+    groups: Object.keys(cfg.groups ?? {}).length,
+    private: Object.entries(cfg.private ?? {}).filter(([, v]) => v.enabled).length + ' 条打开',
+    summarizer: cfg.summarizer,
+  }));
+  if (cfg.private && Object.values(cfg.private).some((v) => v.enabled === true)) {
+    info('注意', '有私聊处于打开状态（这是你显式设的，不是默认）');
+  }
+}
+
+console.log(`\n${failures === 0 ? '全部通过' : `${failures} 项失败`}`);
+process.exit(failures === 0 ? 0 : 1);

package/scripts/check-core-purity.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * core 层静态检查：纯逻辑层不许碰网络、子进程、文件系统写入，
+ * 也不许出现任何「发送」符号。
+ *
+ * 这不是风格检查，是安全边界检查：
+ * core 是唯一做裁决的地方，它如果能触网或写盘，
+ * 「只读」就从机制退化成一句承诺。
+ */
+
+import { readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { validateToolSurface, TOOLS } from '../src/core/toolSurface.js';
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const coreDir = join(root, 'src', 'core');
+
+const FORBIDDEN_IMPORTS = [
+  "node:fs",
+  "node:child_process",
+  "node:net",
+  "node:http",
+  "node:https",
+  "node:dns",
+  "node:tls",
+  "node:worker_threads",
+];
+
+const FORBIDDEN_TOKENS = [
+  /\bfetch\s*\(/,
+  /\bsend_message\b/,
+  /\bsend_group_msg\b/,
+  /\bsend_private_msg\b/,
+  /\bsendGroup\s*\(/,
+  /\bsendPrivate\s*\(/,
+  /\bmark_read\b/,
+  /\/api\/send/,
+  /\bwriteFileSync\b/,
+  /\bappendFileSync\b/,
+  /\bexecSync\b/,
+  /\bspawnSync\b/,
+];
+
+const violations = [];
+
+const files = readdirSync(coreDir).filter((name) => name.endsWith('.js'));
+for (const name of files) {
+  const text = readFileSync(join(coreDir, name), 'utf8');
+  for (const specifier of FORBIDDEN_IMPORTS) {
+    if (text.includes(`'${specifier}'`) || text.includes(`"${specifier}"`)) {
+      violations.push(`${name}: 不许 import ${specifier}`);
+    }
+  }
+  for (const pattern of FORBIDDEN_TOKENS) {
+    if (pattern.test(text)) violations.push(`${name}: 命中禁止符号 ${pattern}`);
+  }
+}
+
+const surface = validateToolSurface(TOOLS);
+for (const violation of surface.violations) violations.push(`toolSurface: ${violation}`);
+
+if (violations.length > 0) {
+  console.error('core 纯净性检查失败：');
+  for (const violation of violations) console.error(`  - ${violation}`);
+  process.exit(1);
+}
+
+console.log(`core 纯净性检查通过：${files.length} 个文件，0 违规；工具面 ${TOOLS.length} 个工具，0 违规。`);