qq-bot-roost 0.8.14 → 0.9.1

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.1-blueviolet" alt="版本 0.9.1">
 <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                 端到端测试（243 项，起真实服务打接口）
 │   ├── 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.1",
   "type": "module",
   "description": "栖 Roost：零依赖的 QQ 官方机器人框架，填 AppID/AppSecret 即连，插件可写任意语言",
   "license": "SEE LICENSE IN LICENSE",

package/src/bot.js

@@ -17,6 +17,9 @@ 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';
+import { createDeliveryLedger } from './delivery.js';
 
 /**
  * 一个机器人的完整运行时。
@@ -95,6 +98,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 +182,7 @@ export class BotRuntime {
     this.pipeline = createDefaultPipeline(cfg, {
       isSticky: (chatId) => this.session.isSticky(chatId),
       metrics: this.metrics,
+      gate: this.gate,
     });
 
     /**
@@ -180,6 +195,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 +221,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,
@@ -205,6 +235,46 @@ export class BotRuntime {
     // 统计库要在插件之前打开：插件上报的运行数据也算统计的一部分
     this.stats.open();
 
+    /**
+     * 投递账本（阶段 5）放在统计库里，所以必须等 `stats.open()` 之后。
+     *
+     * `outbound` 在更早的地方就构造好了（它不依赖库），这里补上引用——
+     * 账本是**增强**，`stats` 打不开时 `db` 是 null，账本自己会退回「照发」。
+     */
+    this.delivery = createDeliveryLedger({
+      db: this.stats.db,
+      botId: this.id,
+      log: (m) => this.log.warn(m),
+    });
+    if (this.outbound) this.outbound.delivery = this.delivery;
+    /** 插件管理器更早构造（那时还没有库），这里补上引用 */
+    if (this.plugins) this.plugins.delivery = this.delivery;
+    /**
+     * 崩溃恢复：上次进程死掉时还在 `pending` 的，全部标 `unknown`。
+     *
+     * 现在还没有任何发送在跑，所以那些 `pending` 一定是崩溃残留——
+     * 我们不知道发没发出去，只能标未知，等人核对。**不能当失败重发。**
+     */
+    this.delivery.recoverPending();
+    // 账本更要在插件之前开：插件一加载就可能开始收消息，漏一条就永久没了
+    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 +541,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 +695,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 +858,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/delivery.js

@@ -0,0 +1,271 @@
+/**
+ * 投递账本
+ * ========
+ *
+ * 一句话：**发出的每一条消息都有据可查，且永远不会因为「不确定」而被重发。**
+ *
+ * ── 为什么需要 ──
+ *
+ * 现在「我说过 X」靠**调用顺序**保证——必须挂在发送成功之后。
+ * 这在 `msg_seq` 群 1–5 / 单聊 1–4 的约束下很脆：一次超时重发就撞上限流，
+ * 还会把「我说过」写进记忆，形成自洽幻觉（她坚称自己说过一句没人看见的话）。
+ *
+ * 改造后靠**状态查询**：顺序会被并发打乱，状态不会。
+ *
+ * ── 状态机 ──
+ *
+ *                     ┌──────── 304023 ────────→ audited（等审核事件结算）
+ *                     │
+ *   created → pending ┼──────── 有 msg_id ──────→ sent
+ *                     │
+ *                     ├── 超窗/配额/离线/限流 ──→ failed（可重试）
+ *                     │
+ *                     └── 超时/5xx/连接重置 ───→ unknown（**永不自动重发**）
+ *
+ * 三个非显然的点：
+ *
+ * 1. **`audited` 不是成功也不是失败。** 官方文档里的 `pending` 指「结果未确定」，
+ *    而账本里的 `pending` 指「尚未发出」——两个 `pending` 会打架，所以这里叫 `audited`。
+ *    审核期间**不能回写「我说过」**，否则审核不通过就变成她坚称说过一句没人看见的话。
+ *
+ * 2. **`unknown` 必须存在。** 网络超时后我们**无法知道**服务端是否收到。
+ *    原则是「未知结果必须人工核对，绝不自动重发」——官方配额下重发的代价更高
+ *    （撞限流 + 重复消息）。
+ *
+ * 3. **`pending` 会在崩溃后残留。** 启动时扫一遍全部转 `unknown`。
+ *    不做这一步，重启后这些记录永远卡在「正在发送」。
+ */
+
+import { createHash } from 'node:crypto';
+
+export const DELIVERY_STATE = {
+  PENDING: 'pending',
+  SENT: 'sent',
+  AUDITED: 'audited',
+  FAILED: 'failed',
+  UNKNOWN: 'unknown',
+};
+
+const ALL_STATES = new Set(Object.values(DELIVERY_STATE));
+
+/**
+ * 摘要：前 120 字 + 总长 + sha1 前 8 位。
+ *
+ * **不存全文**——沿用 `schema.js` 的原则「只存聚合结果，不存消息正文」。
+ * 全文只在事件账本里（且受 7 天保留策略约束）。
+ * 摘要的用途是「人工核对时认出是哪一条」，不是「重发时照抄」。
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function digestOf(text) {
+  const s = String(text ?? '');
+  const sha = createHash('sha1').update(s, 'utf8').digest('hex').slice(0, 8);
+  return `${s.slice(0, 120)}…(${s.length})#${sha}`;
+}
+
+/**
+ * @param {object} o
+ * @param {object} o.db      StatsStore 的 DatabaseSync（库不可用时为 null）
+ * @param {string} o.botId
+ * @param {(m:string)=>void} [o.log]
+ */
+export function createDeliveryLedger({ db, botId, log = () => {} }) {
+  const ready = () => Boolean(db);
+
+  /**
+   * 认领一次发送。
+   *
+   * 这是整个账本的入口：**同一个 requestId 调多少次，都只有第一次会真的发**。
+   *
+   * @param {object} p
+   * @param {string} p.requestId 幂等键，由调用方给（`qq_send` 生成）
+   * @param {'group'|'c2c'} p.kind
+   * @param {string} p.chatId
+   * @param {string} [p.replyTo]  被动回复时的 msg_id
+   * @param {number} [p.msgSeq]
+   * @param {string} p.digest
+   * @returns {{action:'send'|'reuse'|'unknown'|'wait', row?:object}}
+   *   - `send`    没发过 / 上次 failed，可以发
+   *   - `reuse`   已经 sent/audited，直接返回上次结果
+   *   - `unknown` 上次结果未知，**不能重发**
+   *   - `wait`    正在发送中（并发调用）
+   */
+  function claim({ requestId, kind, chatId, replyTo, msgSeq, digest }) {
+    if (!ready()) return { action: 'send' };
+    const id = String(requestId ?? '').trim();
+    if (!id) return { action: 'send' };
+
+    try {
+      const row = db.prepare('SELECT * FROM deliveries WHERE request_id = ?').get(id);
+      if (!row) {
+        db.prepare(
+          `INSERT INTO deliveries
+             (request_id, bot_id, kind, chat_id, reply_to, msg_seq, digest, state, attempts, created_at)
+           VALUES (?,?,?,?,?,?,?,?,?,?)`,
+        ).run(
+          id,
+          botId,
+          String(kind ?? ''),
+          String(chatId ?? ''),
+          replyTo ?? null,
+          msgSeq ?? null,
+          String(digest ?? ''),
+          DELIVERY_STATE.PENDING,
+          0,
+          Date.now(),
+        );
+        return { action: 'send' };
+      }
+
+      if (row.state === DELIVERY_STATE.SENT || row.state === DELIVERY_STATE.AUDITED) {
+        return { action: 'reuse', row };
+      }
+      if (row.state === DELIVERY_STATE.UNKNOWN) return { action: 'unknown', row };
+      if (row.state === DELIVERY_STATE.PENDING) return { action: 'wait', row };
+
+      // failed：允许重试，复用同一行（不新建，否则同一个 requestId 会散成好几条）
+      db.prepare(
+        'UPDATE deliveries SET state = ?, attempts = attempts + 1, code = NULL, settled_at = NULL WHERE request_id = ?',
+      ).run(DELIVERY_STATE.PENDING, id);
+      return { action: 'send', row };
+    } catch (e) {
+      /**
+       * 账本坏了不能把消息也堵死。
+       * 记账是增强，发送是主链路——这里退回「照发」，并留一条日志。
+       */
+      log(`投递账本认领失败（照常发送）：${e.message}`);
+      return { action: 'send' };
+    }
+  }
+
+  /**
+   * 结算。
+   *
+   * @param {string} requestId
+   * @param {string} state `sent` / `audited` / `failed` / `unknown`
+   * @param {{msgId?:string, code?:string}} [extra]
+   */
+  function settle(requestId, state, { msgId, code } = {}) {
+    if (!ready()) return false;
+    const id = String(requestId ?? '').trim();
+    if (!id) return false;
+    if (!ALL_STATES.has(state) || state === DELIVERY_STATE.PENDING) {
+      log(`投递账本结算状态不合法：${state}`);
+      return false;
+    }
+    try {
+      const r = db
+        .prepare(
+          'UPDATE deliveries SET state = ?, msg_id = ?, code = ?, settled_at = ? WHERE request_id = ?',
+        )
+        .run(state, msgId ?? null, code ?? null, Date.now(), id);
+      /**
+       * 返回**是否真的更新了一行**。
+       *
+       * 结算一个不存在的 requestId 会静默 0 行——以前这里无条件 `return true`，
+       * 调用方以为结算成功，实际那条记录还是 pending，重启后又被转成 unknown。
+       */
+      return Number(r?.changes ?? 0) > 0;
+    } catch (e) {
+      log(`投递账本结算失败：${e.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * 崩溃恢复：把所有 `pending` 转 `unknown`。
+   *
+   * 只在**启动时**调。那时没有任何发送在跑，所以 `pending` 一定是上次崩了
+   * 留下的——那些消息我们不知道发没发出去，只能标未知，等人核对。
+   *
+   * @returns {number} 转了多少条
+   */
+  function recoverPending() {
+    if (!ready()) return 0;
+    try {
+      const r = db
+        .prepare(
+          `UPDATE deliveries SET state = ?, code = 'crash', settled_at = ? WHERE state = ?`,
+        )
+        .run(DELIVERY_STATE.UNKNOWN, Date.now(), DELIVERY_STATE.PENDING);
+      const n = Number(r?.changes ?? 0);
+      if (n > 0) log(`${n} 条投递记录在崩溃前没结算，已标为未知（不会自动重发）`);
+      return n;
+    } catch (e) {
+      log(`投递账本恢复失败：${e.message}`);
+      return 0;
+    }
+  }
+
+  /** 查一条（面板 / 跨进程桥 3 用） */
+  function get(requestId) {
+    if (!ready()) return null;
+    try {
+      return db.prepare('SELECT * FROM deliveries WHERE request_id = ?').get(String(requestId ?? '')) ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  /** 最近若干条，面板用 */
+  function recent({ limit = 50, state = '' } = {}) {
+    if (!ready()) return [];
+    try {
+      const n = Math.min(200, Math.max(1, Number(limit) || 50));
+      return state
+        ? db.prepare('SELECT * FROM deliveries WHERE state = ? ORDER BY created_at DESC LIMIT ?').all(state, n)
+        : db.prepare('SELECT * FROM deliveries ORDER BY created_at DESC LIMIT ?').all(n);
+    } catch {
+      return [];
+    }
+  }
+
+  /** 统计：每种状态多少条。面板卡片用 */
+  function stats() {
+    if (!ready()) return { available: false };
+    try {
+      const rows = db.prepare('SELECT state, COUNT(*) AS c FROM deliveries GROUP BY state').all();
+      const by = Object.fromEntries(rows.map((r) => [r.state, Number(r.c)]));
+      return { available: true, by, total: Object.values(by).reduce((a, b) => a + b, 0) };
+    } catch {
+      return { available: false };
+    }
+  }
+
+  /**
+   * 审核事件结算（`MESSAGE_AUDIT_PASS` / `MESSAGE_AUDIT_REJECT`）。
+   *
+   * 官方在审核有结果时推事件，事件里带的是 `msg_id`（不是我们给的 requestId），
+   * 所以按 `msg_id` 反查。
+   *
+   * @param {string} msgId
+   * @param {boolean} passed
+   * @returns {boolean} 有没有找到并结算
+   */
+  function settleByMsgId(msgId, passed) {
+    if (!ready()) return false;
+    const id = String(msgId ?? '').trim();
+    if (!id) return false;
+    try {
+      const r = db
+        .prepare(
+          `UPDATE deliveries SET state = ?, code = ?, settled_at = ?
+            WHERE msg_id = ? AND state = ?`,
+        )
+        .run(
+          passed ? DELIVERY_STATE.SENT : DELIVERY_STATE.FAILED,
+          passed ? null : 'audit-reject',
+          Date.now(),
+          id,
+          DELIVERY_STATE.AUDITED,
+        );
+      return Number(r?.changes ?? 0) > 0;
+    } catch (e) {
+      log(`审核结算失败：${e.message}`);
+      return false;
+    }
+  }
+
+  return { claim, settle, settleByMsgId, recoverPending, get, recent, stats };
+}