qq-bot-roost 0.8.14 → 0.9.0

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-700%2B%20passed-brightgreen" alt="测试 700+ 项">
 <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.14-blueviolet" alt="版本 0.8.14">
+<img src="https://img.shields.io/badge/version-0.9.0-blueviolet" alt="版本 0.9.0">
 <img src="https://img.shields.io/badge/license-Non--Commercial-red" alt="禁止商用">
 <a href="https://github.com/tdcq9594/qq-bot-roost/actions"><img src="https://img.shields.io/github/actions/workflow/status/tdcq9594/qq-bot-roost/ci.yml?branch=master" alt="CI"></a>
 
@@ -418,14 +418,16 @@ bot/
 │   ├── api.js                  HTTP API
 │   ├── message.js              事件 → 统一 Message
 │   ├── roles.js                权限存储
+│   ├── reach.js                可达性：好友关系 + 主动推送开关（官方没有查询接口，靠事件维护）
+│   ├── ledger.js               事件账本：原始消息落库，官方无历史消息接口，这是唯一的历史来源
 │   ├── logger.js               日志：控制台 + 落盘 + 轮转
 │   ├── services/               后台服务：健康巡检、清理、配置热加载、定时重启、插件热重载
-│   ├── storage/                统计库：SQLite 连接、表结构迁移、消息与成员统计
+│   ├── storage/                SQLite 连接与两套表结构：统计库（不存正文）/ 事件账本（存原文）
 │   ├── web/server.js           面板服务端（REST + SSE）
 │   └── plugin/                 插件加载、配置、依赖、子进程宿主、面板页面注册
 ├── test/
-│   ├── selftest.mjs            框架自检（511 项）
-│   ├── e2e.mjs                 端到端测试（185 项，起真实服务打接口）
+│   ├── selftest.mjs            框架自检（538 项）
+│   ├── e2e.mjs                 端到端测试（230 项，起真实服务打接口）
 │   ├── qrlogin.mjs             扫码建机器人（8 项）
 │   └── deps.mjs                插件依赖安装（11 项）
 ├── web/                        面板前端（原生 JS/CSS，无构建）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qq-bot-roost",
-  "version": "0.8.14",
+  "version": "0.9.0",
   "type": "module",
   "description": "栖 Roost：零依赖的 QQ 官方机器人框架，填 AppID/AppSecret 即连，插件可写任意语言",
   "license": "SEE LICENSE IN LICENSE",

package/src/bot.js

@@ -17,6 +17,8 @@ import { claimInstance, releaseInstance } from './instance.js';
 import { botPaths, DIRS, rel } from './paths.js';
 import { StatsStore } from './storage/index.js';
 import { createReach } from './reach.js';
+import { createLedger } from './ledger.js';
+import { createGate } from './gate.js';
 
 /**
  * 一个机器人的完整运行时。
@@ -95,6 +97,17 @@ export class BotRuntime {
      * 插件可以通过 `bot.reach` 直接问，不用自己监听一遍。
      */
     this.reach = createReach({ file: this.paths.reach });
+    /**
+     * 暂停闸：三级（全局 / 这只鸟 / 单个会话）+ 静默。
+     *
+     * 这是**唯一的刹车**。以前配错一只鸟只能关进程，那连别的鸟一起停了。
+     * 闸状态按鸟拆文件（`data/gate/<id>.json`），跨鸟只有 `global.json` 一个。
+     */
+    this.gate = createGate({
+      dir: DIRS.gate,
+      botId: this.id,
+      log: (m) => this.log.warn(m),
+    });
     this.outbound = null;
     this.session = null;
     this.pipeline = null;
@@ -168,6 +181,7 @@ export class BotRuntime {
     this.pipeline = createDefaultPipeline(cfg, {
       isSticky: (chatId) => this.session.isSticky(chatId),
       metrics: this.metrics,
+      gate: this.gate,
     });
 
     /**
@@ -180,6 +194,19 @@ export class BotRuntime {
       retentionDays: cfg.stats?.retentionDays ?? 90,
     });
 
+    /**
+     * 事件账本：官方没有历史消息接口，这是**唯一的历史来源**。
+     *
+     * 和 `stats` 是两个库、两套保留策略：统计留 90 天聚合且不存正文，
+     * 账本只留 7 天但存原文。混一个库的话「这个库会不会被拷走」就说不清了。
+     */
+    this.ledger = createLedger({
+      file: this.paths.events,
+      botId: this.id,
+      enabled: cfg.ledger?.enabled !== false,
+      retentionDays: cfg.ledger?.retentionDays ?? 7,
+    });
+
     this.plugins = new PluginManager({
       pluginsDir: DIRS.plugins,
       paths: this.paths,
@@ -193,6 +220,8 @@ export class BotRuntime {
       session: this.session,
       pipeline: this.pipeline,
       reach: this.reach,
+      ledger: this.ledger,
+      gate: this.gate,
       isOwner: (uid) => cfg.owners.includes(uid),
       // 插件声明了 frameworkVersion 就做兼容校验；作者本地调试可以关掉
       ignoreCompat: this.globalCfg.plugins?.ignoreFrameworkVersion === true,
@@ -204,6 +233,24 @@ export class BotRuntime {
 
     // 统计库要在插件之前打开：插件上报的运行数据也算统计的一部分
     this.stats.open();
+    // 账本更要在插件之前开：插件一加载就可能开始收消息，漏一条就永久没了
+    this.ledger.open();
+
+    /**
+     * 闸要在插件加载之前读好，否则插件 setup 里发的第一条主动消息就漏过了闸。
+     *
+     * `pauseOnStart` 只在**首次运行**生效（闸文件还不存在）。
+     * 每次启动都暂停会让人以为坏了——重启之后不说话，第一反应是「出故障了」，
+     * 不是「等我确认」。方案里那条「安装时自动暂停」靠这个分支实现。
+     */
+    const { botExisted } = await this.gate.open();
+    if (cfg.gate?.pauseOnStart && !botExisted) {
+      await this.gate.setBot(true, {
+        by: 'config',
+        reason: '首次启动自动暂停（gate.pauseOnStart），确认配置无误后在面板放开',
+      });
+      this.log.warn('首次启动已自动暂停，确认配置无误后在面板「运行」页放开');
+    }
 
     // 按配置过滤要加载的插件
     await this.plugins.scan({ filter: pluginFilterOf(cfg.plugins) });
@@ -471,11 +518,95 @@ export class BotRuntime {
     await this.groups?.flush().catch(() => {});
     await this.roles?.flush().catch(() => {});
     await this.reach?.flush().catch(() => {});
+    await this.gate?.flush().catch(() => {});
     this.stats?.close();
+    this.ledger?.close();
     if (!this.mock) await releaseInstance(this.cfg.appId).catch(() => {});
     this.state = 'stopped';
   }
 
+  /**
+   * 这只鸟现在能不能对 `chatId` 说话，以及不能的**原因**。
+   *
+   * 故障排查从「猜」变成「读」：面板直接把 `reasons` 列成中文，
+   * 用户不用去翻日志猜「为什么她不说话」。
+   *
+   * 归到这里的四类状态：闸（三级 + 静默）、网关在线、日额度、分钟限流。
+   * 没放 `Outbound` 里的理由：outbound 是发送执行器，只知道额度和离线，
+   * 不知道闸；而这个方法要回答的是「这只鸟现在能不能开口」，
+   * 是**运行时诊断**，不是发送动作。
+   *
+   * @param {string} chatId
+   * @param {{kind?:'group'|'c2c'}} [opts] 给了就按对应口径查额度；
+   *   不给就取两种里用得多的那个（chatId 在群和私聊里不会撞）
+   * @returns {Promise<{ok:boolean, reasons:{code:string,text:string}[]}>}
+   */
+  async canSpeak(chatId, { kind = '' } = {}) {
+    const reasons = [...this.gate.check(chatId).reasons];
+
+    /**
+     * 可达性：只对**主动消息**有意义。
+     *
+     * 用户刚说完话时的被动回复不受这两道门限制——他就在这儿，回一句当然收得到。
+     * 所以必须传 `kind` 才查：不知道是群还是私聊就查不了，而「不知道」不该变成「不能」。
+     *
+     * `unknown` 一律放行：群里聊过的人很可能早就加了好友，只是还没私聊过。
+     */
+    if (kind === 'c2c') {
+      const v = await this.reach?.canC2C?.(chatId).catch(() => null);
+      if (v?.verdict === 'no') {
+        reasons.push({
+          code: v.reason || 'reach:not-friend',
+          text:
+            v.reason === 'reach:push-off'
+              ? '对方在资料卡里关掉了主动消息推送'
+              : '对方没有加机器人好友',
+        });
+      }
+    } else if (kind === 'group') {
+      const v = await this.reach?.canGroupPush?.(chatId).catch(() => null);
+      if (v?.verdict === 'no') {
+        reasons.push({
+          code: v.reason || 'reach:push-off',
+          text: '群管理员关闭了机器人的主动消息推送',
+        });
+      }
+    }
+
+    if (!this.mock && this.state !== 'online') {
+      reasons.push({
+        code: 'gateway:offline',
+        text: `没连上 QQ（当前状态：${this.state}）`,
+      });
+    }
+
+    if (this.outbound) {
+      const keys = kind ? [`${kind}:${chatId}`] : [`group:${chatId}`, `c2c:${chatId}`];
+      const q = await this.outbound.quotaSnapshot().catch(() => ({}));
+      const used = Math.max(0, ...keys.map((k) => Number(q[k] ?? 0)));
+      if (used >= this.outbound.dailyActive) {
+        reasons.push({
+          code: 'quota:daily',
+          text: `今天的主动消息额度用完了（${used}/${this.outbound.dailyActive} 条）`,
+        });
+      }
+      /**
+       * 分钟限流也列出来，但它是**瞬时**状态——面板上看到这条通常
+       * 等一分钟就自己好了。列它的价值是「不用怀疑别的」，
+       * 而不是让用户去改配置。
+       */
+      const burst = Math.max(0, ...keys.map((k) => this.outbound.rateUsed(k)));
+      if (burst >= this.outbound.activePerMin && this.outbound.activePerMin > 0) {
+        reasons.push({
+          code: 'quota:permin',
+          text: `这一分钟发得太密（${burst}/${this.outbound.activePerMin} 条），等一分钟就好`,
+        });
+      }
+    }
+
+    return { ok: reasons.length === 0, reasons };
+  }
+
   /* ---------------- 事件分发 ---------------- */
 
   /**
@@ -541,6 +672,34 @@ export class BotRuntime {
     /* ---- 消息事件 ---- */
     const msg = buildMessage(eventName, d, { api: this.api, cfg, outbound, session });
 
+    /**
+     * 入账：**第一件要做的事**，在去重 / 白名单 / 限流 / 暂停之前。
+     *
+     * 顺序是有讲究的。账本记的是「发生过什么」，不是「我们怎么处理的」：
+     *   - 被去重拦下的那条，官方确实推了两次，事实是「推了两次」，只是我们处理了一次；
+     *   - 暂停期间的消息如果不记，恢复后就永久消失了——官方没有历史消息接口，补不回来。
+     *
+     * 重复推送由 `dedupe` 唯一约束兜底（官方明说「相同 msg_id 可能重复推送」），
+     * 所以放在最前面也不会记重。
+     *
+     * 同步写：`node:sqlite` 是同步 API，一条 INSERT 在 WAL 下是微秒级，
+     * 比「攒批 + 定时刷」更安全——进程被 kill 时不会丢最后一批。
+     */
+    /**
+     * 入账的返回值挂到消息上：`msg.eventId` / `msg.eventSeq`。
+     *
+     * dsh-roost 写记忆时要记「这条记忆从哪条消息来」（场景片段，阶段 4），
+     * 而它是另一个进程，只能靠转发时带过去的 id 反查原文。
+     *
+     * 撞 dedupe（官方重推同一条）时 `append` 也返回已有那条的 id，
+     * 所以重推的消息一样有出处。
+     */
+    const rec = this.ledger?.append(msg);
+    if (rec) {
+      msg.eventId = rec.id;
+      msg.eventSeq = rec.seq;
+    }
+
     // 收到私聊 = 好友关系存在的强证据。不置 c2cPush：他能发不等于他允许机器人主动推
     if (msg.kind === 'c2c' && msg.userId) {
       this.reach
@@ -676,7 +835,8 @@ export class BotRuntime {
           await commandEntry.handler(msg, { args: msg.args, raw: msg.content, bot: this });
         } catch (e) {
           this.metrics.bump('errors');
-          if (e?.code === 'offline' || e?.code === 'expired' || e?.code === 'quota') {
+          // 这几种是发送侧的已知限制，不是插件写错了，只 warn 不报堆栈
+          if (['offline', 'expired', 'quota', 'rate'].includes(e?.code)) {
             this.log.warn(`命令 ${commandEntry.name} 回复失败: ${e.message}`);
             return;
           }

package/src/config.js

@@ -242,6 +242,39 @@ const BOT_DEFAULTS = {
     retentionDays: 90,
   },
 
+  /**
+   * 事件账本：存原始消息，官方没有历史消息接口，这是唯一的历史来源。
+   *
+   * 和 `stats` 刻意分开：stats 不存正文（只计数），ledger 存正文。
+   * 保留期也短得多——全文落库是隐私成本，只留够做上下文和幂等的窗口即可，
+   * 长期记忆的证据由 dsh-roost 的 journal 自己留快照。
+   */
+  ledger: {
+    enabled: true,
+    /** 原始消息保留天数。7 天够「最近聊了什么」，再长就该由记忆层负责了 */
+    retentionDays: 7,
+  },
+
+  /**
+   * 暂停闸。
+   *
+   * 三级闸本身的状态不写在配置里（它天天变，写在 `data/gate/`），
+   * 这里只有一个**启动策略**。
+   */
+  gate: {
+    /**
+     * 首次启动自动暂停。**默认 false**。
+     *
+     * 对标的产品每次启动都全局暂停，我们不抄：他们是「先隔离检查再放开」的
+     * 探索型工具，我们是长期挂机的生产型框架。重启之后不说话，
+     * 用户第一反应是「坏了」，不是「等我确认」。
+     *
+     * 所以只在**首次运行**（闸文件还不存在）时生效：第一次装机要确认，
+     * 之后日常重启不添堵。安装向导生成配置时可以写 true。
+     */
+    pauseOnStart: false,
+  },
+
   /**
    * 启用哪些插件。三态：
    *   all     — 全部启用，新装插件自动生效
@@ -471,6 +504,8 @@ export async function saveBotConfig(id, cfg) {
     outbound: cfg.outbound,
     session: cfg.session,
     stats: cfg.stats ?? { enabled: true, retentionDays: 90 },
+    ledger: cfg.ledger ?? { enabled: true, retentionDays: 7 },
+    gate: cfg.gate ?? { pauseOnStart: false },
     plugins: cfg.plugins,
     groupManage: cfg.groupManage ?? { invited: false },
   });

package/src/gate.js

@@ -0,0 +1,325 @@
+/**
+ * 暂停闸
+ * ======
+ *
+ * 一句话：**任何一只鸟、任何一个会话，都能在不改配置、不重启的前提下闭嘴，
+ * 而且面板说得出「为什么不能说」。**
+ *
+ * 为什么需要它：以前 `grep -rn "paused" src/` 零命中。一只鸟配错了
+ * （人格写飞、模型抽风、群选错了），重启之后立刻对几个群开口，**没有刹车**。
+ * 唯一能止住的办法是关进程——那连别的鸟一起停了。
+ *
+ * 三级闸取「与」：任一道关着就不说话。
+ *
+ *   global（进程级）→ bot（每只鸟）→ chat（每个会话）
+ *                                  ↘ silence（静默：带 until，到期自动解除）
+ *
+ * ## 为什么按鸟拆文件
+ *
+ * 一个进程里可能同时跑好几只鸟，它们共用一个 `gate.json` 的话，
+ * `.tmp` + `rename` 只能保证「不会写坏」，**不能保证不丢更新**——
+ * 两只鸟同时改，后写的把先写的覆盖掉，表现是「点了暂停没生效」。
+ *
+ * 所以：`data/gate/global.json` 放全局闸，`data/gate/<botId>.json` 放这只鸟的
+ * bot/chat/silence。跨鸟只有全局那一个文件，而且它是低频写，进程内串行化就够。
+ *
+ * ## 为什么不放在 dsh-roost
+ *
+ * 闸要拦在 pipeline 里。dsh-roost 停了 bot 还在收消息，闸必须比 dsh-roost 活得久。
+ */
+
+import path from 'node:path';
+import { readJsonSafe, writeJsonAtomic } from './fsutil.js';
+
+/** 空状态。每次读盘都从它展开，字段少一个也不会 undefined */
+const EMPTY = () => ({
+  paused: false,
+  at: 0,
+  by: '',
+  reason: '',
+  chats: {},
+  silence: {},
+});
+
+/**
+ * @param {object} o
+ * @param {string} o.dir     闸文件目录（`data/gate`）
+ * @param {string} o.botId   这只鸟的 id
+ * @param {(m:string)=>void} [o.log]
+ */
+export function createGate({ dir, botId, log = () => {} }) {
+  const globalFile = path.join(dir, 'global.json');
+  const botFile = path.join(dir, `${botId}.json`);
+
+  let global = EMPTY();
+  let bot = EMPTY();
+  let opened = false;
+  /** 第一次读盘时文件存不存在，`pauseOnStart` 要用 */
+  let botExisted = false;
+  let globalExisted = false;
+
+  /**
+   * 写盘串行化。
+   *
+   * 同一只鸟的两个会话几乎不会同时改闸，但面板连点、插件批量改群闸
+   * 是可能并发的。串行化保证「读-改-写」不会互相覆盖。
+   */
+  let chain = Promise.resolve();
+
+  /**
+   * 读盘。
+   *
+   * @returns {Promise<{botExisted:boolean, globalExisted:boolean}>}
+   *   `botExisted=false` 表示这只鸟从来没写过闸文件（首次运行），
+   *   `gate.pauseOnStart` 靠它判断「要不要自动暂停」——
+   *   每次启动都暂停会让日常重启很难受，用户第一反应是「坏了」。
+   */
+  async function open() {
+    if (opened) return { botExisted, globalExisted };
+    const [g, b] = await Promise.all([
+      readJsonSafe(globalFile, (m) => log(`全局闸：${m}`)),
+      readJsonSafe(botFile, (m) => log(`闸状态：${m}`)),
+    ]);
+    botExisted = b !== null;
+    globalExisted = g !== null;
+    global = { ...EMPTY(), ...(g ?? {}) };
+    bot = { ...EMPTY(), ...(b ?? {}) };
+    opened = true;
+    return { botExisted, globalExisted };
+  }
+
+  function saveGlobal() {
+    const snap = { ...global };
+    chain = chain.then(() => writeJsonAtomic(globalFile, snap)).catch((e) => {
+      log(`全局闸写盘失败：${e.message}`);
+    });
+    return chain;
+  }
+
+  function saveBot() {
+    const snap = { ...bot };
+    chain = chain.then(() => writeJsonAtomic(botFile, snap)).catch((e) => {
+      log(`闸状态写盘失败：${e.message}`);
+    });
+    return chain;
+  }
+
+  /** 把 meta 归一成落盘字段，`by` 用来说明是谁改的（面板 / 插件 id / 命令行） */
+  const metaOf = (m = {}) => ({
+    at: Date.now(),
+    by: String(m.by ?? '').slice(0, 40),
+    reason: String(m.reason ?? '').slice(0, 200),
+  });
+
+  /**
+   * 这只鸟现在能不能对 `chatId` 说话。
+   *
+   * **只回答闸的部分**。网关在线、额度、插件启停由 `bot.canSpeak()` 汇总——
+   * 那些状态不在闸的职责里，混进来会让这个模块变成「什么都知道一点」。
+   *
+   * @param {string} chatId
+   * @param {number} [now]
+   * @returns {{ok:boolean, reasons:{code:string,text:string,until?:number}[]}}
+   */
+  function check(chatId, now = Date.now()) {
+    const reasons = [];
+
+    if (global.paused) {
+      reasons.push({
+        code: 'gate:global',
+        text: `全局暂停${global.reason ? `（${global.reason}）` : ''}`,
+      });
+    }
+    if (bot.paused) {
+      reasons.push({
+        code: 'gate:bot',
+        text: `这只鸟暂停${bot.reason ? `（${bot.reason}）` : ''}`,
+      });
+    }
+    if (chatId) {
+      const c = bot.chats?.[chatId];
+      if (c?.paused) {
+        reasons.push({
+          code: 'gate:chat',
+          text: `这个会话暂停${c.reason ? `（${c.reason}）` : ''}`,
+        });
+      }
+      const until = Number(bot.silence?.[chatId] ?? 0);
+      if (until > now) {
+        const mins = Math.ceil((until - now) / 60_000);
+        reasons.push({
+          code: 'gate:silence',
+          text: `静默中，还剩 ${mins} 分钟`,
+          until,
+        });
+      }
+    }
+
+    return { ok: reasons.length === 0, reasons };
+  }
+
+  /* ---------------- 改闸 ---------------- */
+
+  /**
+   * 改全局闸。
+   *
+   * @param {boolean} paused
+   * @param {{by?:string, reason?:string}} [meta]
+   * @param {{persist?:boolean}} [opts]
+   *   `persist: false` 只改内存不写盘 —— 给 `--paused` 启动参数用。
+   *   那是个**一次性的启动意图**（「这次先别说话」），不是「永久暂停」；
+   *   写进文件的话，下次不带参数启动却发现还在暂停，人会以为坏了。
+   */
+  async function setGlobal(paused, meta, { persist = true } = {}) {
+    await open();
+    global = { ...global, paused: Boolean(paused), ...metaOf(meta) };
+    if (persist) await saveGlobal();
+    return { ...global };
+  }
+
+  async function setBot(paused, meta) {
+    await open();
+    bot = { ...bot, paused: Boolean(paused), ...metaOf(meta) };
+    await saveBot();
+    return { ...bot };
+  }
+
+  async function setChat(chatId, paused, meta) {
+    await open();
+    if (!chatId) throw new Error('缺 chatId');
+    const chats = { ...(bot.chats ?? {}) };
+    if (paused) chats[chatId] = { paused: true, ...metaOf(meta) };
+    else delete chats[chatId];
+    bot = { ...bot, chats };
+    await saveBot();
+    return { chatId, paused: Boolean(paused) };
+  }
+
+  /**
+   * 静默一段时间。
+   *
+   * `until` 存绝对时间戳而不是「剩余毫秒」：进程重启后剩余时间还得重新算，
+   * 而「到几点解除」是事实，重启也成立。
+   *
+   * @param {string} chatId
+   * @param {number} ms 静默多久；`<= 0` 表示解除
+   */
+  async function setSilence(chatId, ms, meta) {
+    await open();
+    if (!chatId) throw new Error('缺 chatId');
+    const silence = { ...(bot.silence ?? {}) };
+    if (ms > 0) silence[chatId] = Date.now() + ms;
+    else delete silence[chatId];
+    bot = { ...bot, silence };
+    await saveBot();
+    return { chatId, until: silence[chatId] ?? 0, ...metaOf(meta) };
+  }
+
+  /**
+   * 重读全局闸。
+   *
+   * 每只鸟各有一个 gate 实例，各自缓存着一份 `global.json` 的内容。
+   * 面板改全局闸时只写了一个文件，其他鸟内存里还是旧值——不加这一步，
+   * 「全局暂停」要等重启才对其他鸟生效，等于没做。
+   *
+   * 只重读全局那一个文件：bot 文件是本实例独有的，重读会把排队中的
+   * 改动冲掉。
+   */
+  async function reloadGlobal() {
+    const g = await readJsonSafe(globalFile, (m) => log(`全局闸：${m}`));
+    global = { ...EMPTY(), ...(g ?? {}) };
+    return { ...global };
+  }
+
+  /**
+   * 清掉所有已到期的静默。
+   *
+   * `check()` 里已经按时间判断过了，这里只是别让 `silence` 表无限长——
+   * 每静默一次留一条，挂机半年就是几百条无用记录。
+   */
+  async function prune(now = Date.now()) {
+    await open();
+    const silence = bot.silence ?? {};
+    const alive = Object.entries(silence).filter(([, until]) => Number(until) > now);
+    if (alive.length === Object.keys(silence).length) return 0;
+    bot = { ...bot, silence: Object.fromEntries(alive) };
+    await saveBot();
+    return Object.keys(silence).length - alive.length;
+  }
+
+  /**
+   * 同步快照（不读盘）。
+   *
+   * `snapshot()` 要 await，而 `/api/status` 是个同步函数、每 2 秒被调一次。
+   * 闸在 `init()` 里已经 open 过，内存里就是最新的，没必要每次再读盘。
+   */
+  function peek() {
+    return {
+      global: { paused: global.paused, at: global.at, by: global.by, reason: global.reason },
+      bot: { paused: bot.paused, at: bot.at, by: bot.by, reason: bot.reason },
+    };
+  }
+
+  /** 面板用的完整快照（含每会话的闸，方便一次画完） */
+  async function snapshot(now = Date.now()) {
+    await open();
+    return {
+      global: { paused: global.paused, at: global.at, by: global.by, reason: global.reason },
+      bot: { paused: bot.paused, at: bot.at, by: bot.by, reason: bot.reason },
+      chats: Object.entries(bot.chats ?? {}).map(([chatId, v]) => ({
+        chatId,
+        paused: true,
+        at: v.at ?? 0,
+        by: v.by ?? '',
+        reason: v.reason ?? '',
+      })),
+      silence: Object.entries(bot.silence ?? {})
+        .filter(([, until]) => Number(until) > now)
+        .map(([chatId, until]) => ({ chatId, until })),
+    };
+  }
+
+  /** 退出前把排队的写盘任务等完 */
+  async function flush() {
+    await chain.catch(() => {});
+  }
+
+  return {
+    open,
+    check,
+    peek,
+    snapshot,
+    reloadGlobal,
+    setGlobal,
+    setBot,
+    setChat,
+    setSilence,
+    prune,
+    flush,
+    get dir() {
+      return dir;
+    },
+  };
+}
+
+/**
+ * 管道中间件：闸关着就不往下走。
+ *
+ * **必须排在账本之后**。`bot.js` 里 `ledger.append()` 在 `pipeline.run()` 之前，
+ * 所以暂停期间的消息照样入账——恢复之后 AI 能看见「你不在的时候群里聊了什么」。
+ * 顺序反过来的话，暂停就等于丢消息，而官方没有历史消息接口，丢了补不回来。
+ *
+ * 拦下时**不回任何话**：静默才是目的，回一句「我暂停了」等于没闭嘴。
+ */
+export function gateMiddleware(gate, { metrics = null } = {}) {
+  return async (ctx, next) => {
+    const chatId = ctx.msg?.chatId ?? '';
+    const v = gate.check(chatId);
+    if (!v.ok) {
+      metrics?.bump('gated');
+      ctx.halt('gate');
+      return;
+    }
+    return next();
+  };
+}