qq-bot-roost 0.9.0 → 0.9.2

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.9.0-blueviolet" alt="版本 0.9.0">
+<img src="https://img.shields.io/badge/version-0.9.2-blueviolet" alt="版本 0.9.2">
 <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>
 
@@ -427,7 +427,7 @@ bot/
 │   └── plugin/                 插件加载、配置、依赖、子进程宿主、面板页面注册
 ├── test/
 │   ├── selftest.mjs            框架自检（538 项）
-│   ├── e2e.mjs                 端到端测试（230 项，起真实服务打接口）
+│   ├── 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.9.0",
+  "version": "0.9.2",
   "type": "module",
   "description": "栖 Roost：零依赖的 QQ 官方机器人框架，填 AppID/AppSecret 即连，插件可写任意语言",
   "license": "SEE LICENSE IN LICENSE",

package/src/bot.js

@@ -19,6 +19,7 @@ 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';
 
 /**
  * 一个机器人的完整运行时。
@@ -233,6 +234,28 @@ 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();
 

package/src/delivery.js

@@ -0,0 +1,346 @@
+/**
+ * 投递账本
+ * ========
+ *
+ * 一句话：**发出的每一条消息都有据可查，且永远不会因为「不确定」而被重发。**
+ *
+ * ── 为什么需要 ──
+ *
+ * 现在「我说过 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;
+    }
+  }
+
+  /**
+   * 一条逻辑消息可能对应好几行。
+   *
+   * 为什么：被动回复超过 1800 字时，发送层会切成几块各发一次，
+   * 每块一个幂等键（`${base}#1`、`${base}#2`…，见 ai-chat 的 `sendReply`）。
+   * 这是必须的——共用一个 id 的话第 2 块起会被 `claim` 判成 `reuse` 直接丢掉。
+   *
+   * 但「这条消息到底送没送到」问的是**整条**，不是某一块。所以这里把
+   * base 和它的所有分块聚合成一个状态。
+   *
+   * 聚合规则按「坏消息优先」：只要有一块 `unknown`，整条就是 `unknown`
+   * （**绝不能重发**——重发会把已经出去的那块再发一遍）；有一块 `failed`
+   * 就是 `failed`（可重试，重试只会补没发出去的那块，因为 id 是确定的）；
+   * 还在飞就是 `pending`；等审核是 `audited`；全成功才是 `sent`。
+   *
+   * @param {string} requestId base id
+   * @returns {null | {state:string, parts:number, msgId:string, code:string,
+   *   attempts:number, at:number, rows:object[]}}
+   */
+  function family(requestId) {
+    if (!ready()) return null;
+    const base = String(requestId ?? '').trim();
+    if (!base) return null;
+    /**
+     * `LIKE` 里的 `%` `_` 要转义，否则 base 里带这两个字符会误匹配到别人的行。
+     * requestId 是我们自己生成的（`qs-…` / `sp-…`），正常不会有，
+     * 但这里是公共入口，不能靠上游自觉。
+     */
+    const esc = base.replace(/[\\%_]/g, (m) => `\\${m}`);
+    try {
+      const rows = db
+        .prepare(`SELECT * FROM deliveries WHERE request_id = ? OR request_id LIKE ? ESCAPE '\\' ORDER BY request_id`)
+        .all(base, `${esc}#%`);
+      if (!rows.length) return null;
+
+      const rank = {
+        [DELIVERY_STATE.SENT]: 0,
+        [DELIVERY_STATE.AUDITED]: 1,
+        [DELIVERY_STATE.PENDING]: 2,
+        [DELIVERY_STATE.FAILED]: 3,
+        [DELIVERY_STATE.UNKNOWN]: 4,
+      };
+      /**
+       * 认不出的状态**不参与比较**，不能给它一个默认名次。
+       *
+       * 给 0（等于 sent）会让一条状态坏掉的行被当成已送达；
+       * 给 99（等于最坏）又会让它压过真正的 `unknown`，把「绝对不能重发」
+       * 这条信息淹掉。两种情况都会让人对着一个假答案往下走。
+       *
+       * 正常不会出现（`settle` 会校验状态），但账本是跨版本存活的，
+       * 老版本写过什么值谁也不敢保证。
+       */
+      const known = rows.filter((r) => r.state in rank);
+      const pool = known.length ? known : rows;
+      let worst = pool[0];
+      for (const r of pool) if (rank[r.state] > rank[worst.state]) worst = r;
+      if (!known.length) log(`投递账本里有认不出的状态：${rows.map((r) => r.state).join('、')}`);
+
+      /** 报最坏那块的 msg_id / code，人核对时想知道的是「哪块出问题了」 */
+      const at = rows.reduce((m, r) => Math.max(m, Number(r.settled_at || r.created_at || 0)), 0);
+      return {
+        state: worst.state,
+        parts: rows.length,
+        msgId: worst.msg_id || '',
+        code: worst.code || '',
+        attempts: rows.reduce((m, r) => Math.max(m, Number(r.attempts || 0)), 0),
+        at,
+        rows,
+      };
+    } catch (e) {
+      log(`投递账本家族查询失败：${e.message}`);
+      return null;
+    }
+  }
+
+  return { claim, settle, settleByMsgId, recoverPending, get, family, recent, stats };
+}

package/src/message.js

@@ -365,7 +365,15 @@ export function buildMessage(eventName, d, { api, cfg, outbound, session }) {
   // 一律经过 outbound，由它处理被动窗口（群聊 5 分钟 / 单聊 60 分钟）、每秒限速、主动消息额度。
   const send = (opts, passive) => {
     if (kind !== 'group' && kind !== 'c2c') return Promise.resolve(null);
-    const body = passive ? { msgId: msg.id, ...opts } : { ...opts };
+    /**
+     * `requestId` **不是官方字段**，要从 body 里摘出来单独传给 outbound——
+     * 混进去会被 api.js 当成未知参数一路带到接口上。
+     *
+     * 它是投递账本的幂等键（阶段 5）：同一个 id 再调一次只发一条。
+     * 没有它就退回原来的「发一次算一次」。
+     */
+    const { requestId, ...rest } = opts ?? {};
+    const body = passive ? { msgId: msg.id, ...rest } : { ...rest };
     msg.replied = true;
 
     if (!outbound) {
@@ -378,6 +386,7 @@ export function buildMessage(eventName, d, { api, cfg, outbound, session }) {
       chatKey: `${kind}:${chatId}`,
       payload: body,
       receivedAt,
+      ...(requestId ? { requestId: String(requestId) } : {}),
     });
   };
 
@@ -540,11 +549,17 @@ export function buildMessage(eventName, d, { api, cfg, outbound, session }) {
     return send({ content: String(text), ...opts }, false);
   };
 
-  /** Markdown 消息（可带按钮 keyboard）。Markdown 是独立消息类型，先把攒的文本发掉 */
-  msg.replyMarkdown = async (markdown, keyboard) => {
+  /**
+   * Markdown 消息（可带按钮 keyboard）。Markdown 是独立消息类型，先把攒的文本发掉。
+   *
+   * `opts.requestId`：投递账本的幂等键。以前这条路完全绕开账本——
+   * 插件给了 id 也只对纯文本生效，markdown 那条永远记不上，重发就会重复。
+   * 第三个参数是可选的，老调用方不传，行为不变。
+   */
+  msg.replyMarkdown = async (markdown, keyboard, opts = {}) => {
     await msg.flushReplies();
     try {
-      return await send({ markdown, keyboard }, true);
+      return await send({ markdown, keyboard, ...(opts?.requestId ? { requestId: opts.requestId } : {}) }, true);
     } catch (e) {
       /**
        * Markdown 是**独立消息类型**，没有纯文本兜底：平台不放行（没权限、
@@ -572,7 +587,13 @@ export function buildMessage(eventName, d, { api, cfg, outbound, session }) {
        * 按钮里的指令本来也会出现在正文里（ctx.menu 渲染时带上），信息不丢。
        */
       log.warn(`Markdown 被拒（${e.message}），降级为纯文本重发`);
-      return send({ content: plain }, true).catch((e2) => {
+      /**
+       * 降级重发**沿用同一个 requestId**：对用户来说这仍然是「一条消息」，
+       * 账本里就该只有一行。上一步抛错时已经结算成 `failed`（可重试），
+       * 所以这里 claim 会放行并复用同一行，最终状态是 `sent`。
+       * 万一是 `unknown`，claim 会抛错——那正是我们要的「不重复发」。
+       */
+      return send({ content: plain, ...(opts?.requestId ? { requestId: opts.requestId } : {}) }, true).catch((e2) => {
         log.error('降级纯文本也没发出去:', e2.message);
         return null;
       });

package/src/outbound.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { createLogger } from './logger.js';
+import { DELIVERY_STATE, digestOf } from './delivery.js';
 import { DIRS } from './paths.js';
 
 const log = createLogger('outbound');
@@ -103,6 +104,23 @@ export class SendError extends Error {
   }
 }
 
+/**
+ * 这次失败是「确定没发出去」还是「不知道发没发出去」。
+ *
+ * 只有 `api` 这一类可能不确定：超时、5xx、连接重置——请求发出去了但响应没回来。
+ * 其余四种（`offline` / `expired` / `quota` / `rate`）都是**本地判定**，
+ * 消息一定没发出去，记 `failed` 可以放心重试。
+ *
+ * 判错的代价不对称：把「确定失败」误判成 unknown，用户要人工核对（麻烦但安全）；
+ * 把 unknown 误判成「确定失败」，就会重发一条可能已经发出去的消息（重复打扰）。
+ * 所以这里宁可保守——拿不准就当 unknown。
+ */
+function uncertainOf(e) {
+  if (e?.code !== 'api') return false;
+  const s = String(e?.detail ?? e?.message ?? '');
+  return /timeout|timed out|ETIMEDOUT|ECONNRESET|ECONNREFUSED|socket hang up|aborted|\b5\d\d\b/i.test(s);
+}
+
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
 /** 本地日期键，按用户所在时区算，不用 UTC 免得跨天错位 */
@@ -200,8 +218,10 @@ export class Outbound {
    * @param {object} opts.cfg            全局配置
    * @param {() => boolean} opts.isOnline 机器人是否已连上网关
    */
-  constructor({ api, cfg, isOnline = () => true, quotaFile }) {
+  constructor({ api, cfg, isOnline = () => true, quotaFile, delivery = null }) {
     this.api = api;
+    /** 投递账本（阶段 5）。没有它就退回原来的「发一次算一次」 */
+    this.delivery = delivery;
     this.cfg = cfg;
     this.isOnline = isOnline;
 
@@ -257,13 +277,91 @@ export class Outbound {
    * @param {number} [p.receivedAt] 触发本次回复的消息接收时间
    * @returns {Promise<{id?:string, pending?:boolean, degraded?:boolean}>}
    */
-  async send({ kind, target, chatKey, payload, receivedAt }) {
+  /**
+   * 发送。**有 `requestId` 就走投递账本，没有就照旧发一次。**
+   *
+   * 为什么不是「所有发送都记账」：`requestId` 由调用方生成，只有它知道
+   * 「一段话」的语义边界（`qq_send` 每调一次是一段独立消息）。插件直接
+   * `msg.reply()` 那种没有 id，按原行为走——被动回复本身有 `msg_seq` 兜底。
+   *
+   * 账本是**增强**不是主链路：`claim` 失败一律退回「照发」，不能让记账把消息堵死。
+   */
+  async send(opts) {
+    const requestId = String(opts?.requestId ?? '').trim();
+    if (!requestId || !this.delivery) return this.#sendOnce(opts);
+
+    const c = this.delivery.claim({
+      requestId,
+      kind: opts.kind,
+      chatId: opts.target,
+      replyTo: opts.payload?.msgId,
+      msgSeq: opts.payload?.msgSeq,
+      digest: digestOf(opts.payload?.content ?? opts.payload?.text ?? ''),
+    });
+
+    if (c.action === 'reuse') {
+      // 已经发过：直接回上次的结果，**不再打接口**
+      return {
+        id: c.row?.msg_id || '',
+        reused: true,
+        pending: c.row?.state === DELIVERY_STATE.AUDITED,
+        requestId,
+      };
+    }
+    if (c.action === 'unknown') {
+      /**
+       * 上次结果未知，**绝不自动重发**。
+       *
+       * 官方配额下重发的代价是双份：可能重复发一条，还会撞上限流。
+       * 宁可让人去面板核对一次。
+       */
+      throw new SendError(
+        '这条消息上次的发送结果未知（超时或进程崩溃），不会自动重发。请到面板「投递」页核对',
+        'unknown',
+      );
+    }
+    if (c.action === 'wait') {
+      throw new SendError('这条消息正在发送中，别重复调用', 'pending');
+    }
+
+    try {
+      const r = await this.#sendOnce(opts);
+      this.delivery.settle(
+        requestId,
+        r?.pending ? DELIVERY_STATE.AUDITED : DELIVERY_STATE.SENT,
+        { msgId: r?.id },
+      );
+      return { ...r, requestId };
+    } catch (e) {
+      /**
+       * 失败也要结算，否则这一行永远卡在 `pending`。
+       *
+       * `unknown` 只给「不知道发没发出去」的情况（超时 / 5xx / 连接重置）。
+       * `offline` / `expired` / `quota` / `rate` 是**确定没发出去**，记 `failed` 允许重试。
+       */
+      this.delivery.settle(requestId, uncertainOf(e) ? DELIVERY_STATE.UNKNOWN : DELIVERY_STATE.FAILED, {
+        code: e?.code || 'error',
+      });
+      throw e;
+    }
+  }
+
+  async #sendOnce({ kind, target, chatKey, payload, receivedAt }) {
     if (kind !== 'group' && kind !== 'c2c') {
       throw new SendError(`不支持的会话类型: ${kind}`, 'api');
     }
     if (!this.isOnline()) {
       this.stats.offline += 1;
-      throw new SendError('机器人当前没有连上 QQ，消息发不出去', 'offline');
+      /**
+       * 错误消息要**带上下一步怎么办**。
+       *
+       * 只解释原因（「没连上」）时，调用方只能自己猜是重试还是放弃；
+       * 写明「等它上线」，它就知道这类错误不该重试。
+       */
+      throw new SendError(
+        '机器人当前没有连上 QQ，消息发不出去。等它重新上线再试（面板「运行」页能看状态）。',
+        'offline',
+      );
     }
 
     const body = { ...payload };
@@ -351,7 +449,7 @@ export class Outbound {
         if (!this.#allowActiveThisMinute(chatKey)) {
           this.stats.rateBlocked += 1;
           throw new SendError(
-            `这个会话的主动消息发得太密（官方限制 ${this.activePerMin} 条/分钟），稍后再试。`,
+            `这个会话的主动消息发得太密（官方限制 ${this.activePerMin} 条/分钟），**等 1 分钟**就好。`,
             'rate',
           );
         }

package/src/plugin/context.js

@@ -39,6 +39,23 @@ function readOnlyLedger(ledger) {
  *
  * `by` 记成 `plugin:<id>`，面板上一眼能看出是哪个插件停的。
  */
+/**
+ * 给插件的投递账本视图：**只能标记失败，不能标记成功**。
+ *
+ * 为什么只给 `fail`：`settle(requestId, 'sent')` 一暴露，插件就能把一条
+ * 根本没发出去的消息标成「已发送」——而账本的全部价值就是「记录的事实」。
+ * 插件唯一正当的需求是「这段我不发了」，所以只给这一个动作。
+ */
+function readOnlyDelivery(ledger) {
+  return Object.freeze({
+    /** 标记这条没发出去（截断、被跳过），允许以后重试 */
+    fail: (requestId, code = 'plugin') =>
+      ledger.settle(String(requestId ?? ''), 'failed', { code }),
+    /** 查一条（只读） */
+    get: (requestId) => ledger.get(requestId),
+  });
+}
+
 function readOnlyGate(gate, pluginId) {
   const by = `plugin:${pluginId}`;
   return Object.freeze({
@@ -348,7 +365,7 @@ export class PluginStorage {
 /**
  * 插件上下文：插件能用的全部能力都在这里，不暴露内部实现。
  */
-export function createContext({ meta, paths, registry, api, cfg, config, configStore, groups, roles, levels, outbound, session, pipeline, reach, ledger, gate, isOwner, pages = null, routes = null, state = null }) {
+export function createContext({ meta, paths, registry, api, cfg, config, configStore, groups, roles, levels, outbound, session, pipeline, reach, ledger, gate, delivery, isOwner, pages = null, routes = null, state = null }) {
   const id = meta.id;
   // 日志 tag 带机器人 id，多机器人下同名插件的日志不会串
   const logger = createLogger(`plugin:${paths?.id ?? '-'}:${id}`);
@@ -416,6 +433,8 @@ export function createContext({ meta, paths, registry, api, cfg, config, configS
      * 所以一定要能带时长，`ms <= 0` 表示解除。
      */
     gate: gate ? readOnlyGate(gate, id) : null,
+    /** 投递账本（阶段 5）：只能 `fail`，见 readOnlyDelivery */
+    delivery: delivery ? readOnlyDelivery(delivery) : null,
     storage: new PluginStorage(paths.pluginData(id)),
 
     /**
@@ -773,13 +792,18 @@ export function createContext({ meta, paths, registry, api, cfg, config, configS
      *
      *   await ctx.push(groupOpenid, '今天的魂兽森林刷新了')
      */
-    push(chatId, text, { kind = 'group' } = {}) {
+    push(chatId, text, { kind = 'group', requestId = '' } = {}) {
       if (!outbound) throw new Error('当前环境不支持主动推送');
       return outbound.send({
         kind,
         target: chatId,
         chatKey: `${kind}:${chatId}`,
         payload: { content: String(text ?? '') },
+        /**
+         * 幂等键（阶段 5）。同一个 id 再推一次只发一条——
+         * 调用方（`qq_send`）知道「一段话」的语义边界，只有它给得出这个 id。
+         */
+        ...(requestId ? { requestId: String(requestId) } : {}),
       });
     },
 

package/src/plugin/loader.js

@@ -27,7 +27,7 @@ const log = createLogger('plugins');
  * 启用状态存在 data/bots/<机器人id>/plugins.json，删掉文件夹即等于卸载。
  */
 export class PluginManager {
-  constructor({ pluginsDir, paths, registry, api, cfg, goBin, groups, roles, outbound, session, pipeline, isOwner, reach, ledger, gate, ignoreCompat }) {
+  constructor({ pluginsDir, paths, registry, api, cfg, goBin, groups, roles, outbound, session, pipeline, isOwner, reach, ledger, gate, delivery, ignoreCompat }) {
     this.dir = pluginsDir;
     // 该机器人的全套路径（配置/数据/日志），多机器人下互不干扰
     this.paths = paths;
@@ -47,6 +47,8 @@ export class PluginManager {
     this.ledger = ledger;
     /** 暂停闸（只给会话级，见 context.js 的 readOnlyGate），见 src/gate.js */
     this.gate = gate;
+    /** 投递账本（只给 fail，见 context.js 的 readOnlyDelivery），见 src/delivery.js */
+    this.delivery = delivery;
     this.isOwner = isOwner;
     /** 跳过插件声明的 frameworkVersion 校验（作者本地调试用） */
     this.ignoreCompat = Boolean(ignoreCompat);
@@ -416,6 +418,7 @@ export class PluginManager {
       reach: this.reach,
       ledger: this.ledger,
       gate: this.gate,
+      delivery: this.delivery,
       isOwner: this.isOwner,
       pages: this.pages,
       routes: this.routes,

package/src/storage/schema.js

@@ -14,7 +14,7 @@
  *     那个存群，这个存人。
  */
 
-export const SCHEMA_VERSION = 1;
+export const SCHEMA_VERSION = 2;
 
 const V1 = `
 CREATE TABLE IF NOT EXISTS messages (
@@ -60,6 +60,35 @@ CREATE TABLE IF NOT EXISTS commands (
 );
 `;
 
+/**
+ * v2：投递账本（阶段 5）。
+ *
+ * 为什么放在统计库而不是事件账本库：deliveries **不含正文**（只有 `digest` 摘要），
+ * 和 `stats` 同一个隐私口径（「只存聚合结果」），生命周期也一样（bot 侧、跟着机器人走）。
+ * events 库是 7 天滚动删的全文库，投递记录要活得更久。
+ *
+ * `digest` 不存全文，沿用 `schema.js` 的原则。全文只在事件账本里。
+ */
+const V2 = `
+CREATE TABLE IF NOT EXISTS deliveries (
+  request_id  TEXT PRIMARY KEY,   -- 幂等键，由调用方给（qq_send 生成）
+  bot_id      TEXT    NOT NULL,
+  kind        TEXT    NOT NULL,   -- group / c2c
+  chat_id     TEXT    NOT NULL,
+  reply_to    TEXT,               -- 被动回复时的 msg_id
+  msg_seq     INTEGER,            -- 群 1..5 / 单聊 1..4，官方硬限制
+  digest      TEXT    NOT NULL,   -- 前 120 字 + 总长 + sha1 前 8 位
+  state       TEXT    NOT NULL,   -- pending/sent/audited/failed/unknown
+  msg_id      TEXT,
+  code        TEXT,
+  attempts    INTEGER NOT NULL DEFAULT 0,
+  created_at  INTEGER NOT NULL,
+  settled_at  INTEGER
+);
+CREATE INDEX IF NOT EXISTS deliveries_chat ON deliveries(bot_id, chat_id, created_at);
+CREATE INDEX IF NOT EXISTS deliveries_open ON deliveries(state) WHERE state IN ('pending','unknown');
+`;
+
 /**
  * 把库升到最新结构。
  * @param {object} db DatabaseSync
@@ -68,8 +97,9 @@ export function migrate(db) {
   const cur = Number(db.prepare('PRAGMA user_version').get()?.user_version ?? 0);
   if (cur >= SCHEMA_VERSION) return { from: cur, to: cur };
 
-  // 以后加表就往这里追加：if (cur < 2) { ... }
+  // 以后加表就往这里追加：if (cur < 3) { ... }
   if (cur < 1) db.exec(V1);
+  if (cur < 2) db.exec(V2);
 
   db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
   return { from: cur, to: SCHEMA_VERSION };

package/src/web/server.js

@@ -2433,6 +2433,30 @@ export async function startWebServer({
           return json(res, 400, { error: `不认识的 scope：${scope}（global / bot / chat / silence）` });
         }
 
+        /* ---------------- 投递账本 ---------------- */
+
+        /**
+         * `GET /api/delivery?requestId=` 查一条；不带就列最近的。
+         *
+         * 给「这条到底发出去没有」一个可查的地方——`unknown` 状态的全部意义
+         * 就是让人能核对，没有这个接口那个状态就只能靠翻日志。
+         */
+        if (pathname === '/api/delivery' && req.method === 'GET') {
+          const rid = String(url.searchParams.get('requestId') ?? '').trim();
+          if (rid) {
+            const row = rt.delivery?.get(rid) ?? null;
+            if (!row) return json(res, 404, { ok: false, error: '没有这条投递记录' });
+            return json(res, 200, { ok: true, item: row });
+          }
+          const limit = Number(url.searchParams.get('limit')) || 50;
+          const state = String(url.searchParams.get('state') ?? '').trim();
+          return json(res, 200, {
+            ok: true,
+            items: rt.delivery?.recent({ limit, state }) ?? [],
+            stats: rt.delivery?.stats() ?? { available: false },
+          });
+        }
+
         // 网关操作
         if (pathname === '/api/gateway/reconnect' && req.method === 'POST') {
           // 已经下线时没有「重连」可言，直接当上线处理，免得点了没反应
@@ -2465,7 +2489,7 @@ export async function startWebServer({
          */
         if (pathname === '/api/send' && req.method === 'POST') {
           const body = await readBody(req);
-          const { scene, target, content } = body;
+          const { scene, target, content, requestId } = body;
           if (!target || !content) return json(res, 400, { error: '需要 target 和 content' });
           const kind = scene === 'c2c' ? 'c2c' : 'group';
           const sender = kind === 'c2c' ? api?.sendC2C : api?.sendGroup;
@@ -2478,9 +2502,20 @@ export async function startWebServer({
                 target,
                 chatKey: `${kind}:${target}`,
                 payload: { content },
+                /**
+                 * 幂等键（阶段 5）。面板重试、脚本重放时带上同一个 id，
+                 * 第二次不会真的再发一遍，直接回上次的结果。
+                 */
+                ...(requestId ? { requestId: String(requestId) } : {}),
               });
               // pending = 主动消息进了审核。既不是失败，也不是「已经送达」
-              return json(res, 200, { ok: true, id: r?.id ?? '', pending: Boolean(r?.pending) });
+              return json(res, 200, {
+                ok: true,
+                id: r?.id ?? '',
+                pending: Boolean(r?.pending),
+                // reused = 这条 requestId 之前已经发过，这次没打接口
+                ...(r?.reused ? { reused: true } : {}),
+              });
             } catch (e) {
               const hint = userFacingSendError(e);
               if (!hint) throw e; // 真正的接口错误交给外层兜底（500 + 原始信息）

package/web/app.js

@@ -233,6 +233,7 @@ async function selectBot(id) {
   if (tab === 'plugins') loadPlugins();
   if (tab === 'events') loadEvents();
   if (tab === 'reach') loadReach();
+  if (tab === 'delivery') loadDelivery();
   if (tab === 'groups') loadGroups();
   if (tab === 'roles') { loadRoles(); loadPeople(); }
   if (tab === 'stats') loadStats();
@@ -599,6 +600,7 @@ function activateTab(name) {
   if (name === 'config') loadConfig();
   if (name === 'groups') loadGroups();
   if (name === 'reach') loadReach();
+  if (name === 'delivery') loadDelivery();
   if (name === 'roles') { loadRoles(); loadPeople(); }
 }
 
@@ -3040,6 +3042,71 @@ function triSelect(field, v, yes = '是', no = '否') {
   }</select>`;
 }
 
+/* ---------------- 投递账本 ---------------- */
+
+/**
+ * 状态文案。
+ *
+ * `unknown` 是唯一需要人动手的状态——**它不会自动重发**，
+ * 所以文案要把「去核对」写清楚，而不是只显示「未知」。
+ */
+const DELIVERY_LABEL = {
+  pending: { text: '发送中', tip: '正在发' },
+  sent: { text: '已发送', tip: '确认送达' },
+  audited: { text: '审核中', tip: '主动消息进了审核，既不是成功也不是失败' },
+  failed: { text: '失败', tip: '确定没发出去，可以重试' },
+  unknown: { text: '结果未知', tip: '超时或崩溃，不知道服务端收没收到。不会自动重发，需要人工核对' },
+};
+
+async function loadDelivery() {
+  const body = $('#deliveryBody');
+  if (!body) return;
+  try {
+    renderDelivery(await api('/api/delivery?limit=50'));
+  } catch (e) {
+    body.innerHTML = `<tr><td colspan="6" class="empty">加载失败: ${escapeHtml(e.message)}</td></tr>`;
+  }
+}
+
+function renderDelivery(d) {
+  const stats = d?.stats ?? {};
+  const el = $('#deliveryStats');
+  if (el) {
+    const by = stats.by ?? {};
+    el.innerHTML = Object.keys(DELIVERY_LABEL)
+      .map((k) => {
+        const v = by[k] ?? 0;
+        // 有值才显眼：全 0 的时候整排彩色卡片只会让人以为出事了
+        const hot = k === 'unknown' && v > 0;
+        return `<div class="card"><div class="k">${DELIVERY_LABEL[k].text}</div>`
+          + `<div class="v"${hot ? ' style="color:var(--warn-text)"' : ''}>${v}</div></div>`;
+      })
+      .join('');
+  }
+
+  const body = $('#deliveryBody');
+  const items = d?.items ?? [];
+  if (!items.length) {
+    body.innerHTML = '<tr><td colspan="6" class="empty">还没有记录（只有带幂等键的发送才记账）</td></tr>';
+    return;
+  }
+  body.innerHTML = items
+    .map((x) => {
+      const st = DELIVERY_LABEL[x.state] ?? { text: x.state, tip: '' };
+      const when = x.created_at ? new Date(Number(x.created_at)).toLocaleString('zh-CN', { hour12: false }) : '-';
+      const warn = x.state === 'unknown' || x.state === 'failed';
+      return `<tr>
+        <td>${escapeHtml(when)}</td>
+        <td class="mono">${escapeHtml(String(x.chat_id ?? '').slice(0, 12))}</td>
+        <td${warn ? ' style="color:var(--warn-text)"' : ''} title="${escapeHtml(st.tip)}">${escapeHtml(st.text)}</td>
+        <td>${escapeHtml(String(x.digest ?? '').slice(0, 60))}</td>
+        <td class="num">${Number(x.attempts ?? 0)}</td>
+        <td class="mono">${escapeHtml(String(x.code ?? ''))}</td>
+      </tr>`;
+    })
+    .join('');
+}
+
 async function loadReach() {
   const ub = $('#reachUserBody');
   const gb = $('#reachGroupBody');

package/web/index.html

@@ -57,6 +57,7 @@
         <button class="tab-item" data-tab="stats">统计</button>
         <button class="tab-item" data-tab="events">事件</button>
         <button class="tab-item" data-tab="reach">可达性</button>
+        <button class="tab-item" data-tab="delivery">投递</button>
         <button class="tab-item" data-tab="logs">日志</button>
       </div>
     </div>
@@ -514,6 +515,34 @@
     </div>
   </section>
 
+  <!-- 投递账本 -->
+  <section id="tab-delivery" class="panel">
+    <div class="box">
+      <div class="box-hd">
+        <h3>投递账本</h3>
+        <span class="hint">带幂等键的消息发没发出去，这里查得到</span>
+      </div>
+      <ul class="tips">
+        <li><b>已发送</b>确认送达；<b>审核中</b>是主动消息进了审核——既不是成功也不是失败，
+          等审核事件回来才会落定</li>
+        <li><b>结果未知</b>：超时或进程崩了，我们<b>不知道服务端收没收到</b>。
+          这种<b>不会自动重发</b>——宁可让人核对一次，也不重复打扰</li>
+        <li><b>失败</b>：确定没发出去（离线 / 超窗 / 额度 / 限流），可以重试</li>
+        <li>只有<b>带幂等键</b>的发送才记账（`qq_send` 那类「一次调用 = 一段话」的）。
+          插件直接回一句话不记账，靠 `msg_seq` 天然去重</li>
+      </ul>
+      <div class="cards" id="deliveryStats"></div>
+      <div class="table-wrap">
+        <table>
+          <thead>
+            <tr><th>时间</th><th>会话</th><th>状态</th><th>摘要</th><th class="num">重试</th><th>原因码</th></tr>
+          </thead>
+          <tbody id="deliveryBody"><tr><td colspan="6" class="empty">暂无数据</td></tr></tbody>
+        </table>
+      </div>
+    </div>
+  </section>
+
   <!-- 可达性 -->
   <section id="tab-reach" class="panel">
     <div class="box">