qq-bot-roost 0.8.13 → 0.9.0

package/README.md

@@ -8,9 +8,9 @@
 
 <img src="https://img.shields.io/badge/Node.js-22.13%2B-339933?logo=node.js&logoColor=white" alt="Node.js 22.13+">
 <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="零依赖">
-<img src="https://img.shields.io/badge/tests-600%2B%20passed-brightgreen" alt="测试 600+ 项">
+<img src="https://img.shields.io/badge/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.13-blueviolet" alt="版本 0.8.13">
+<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            框架自检（431 项）
-│   ├── e2e.mjs                 端到端测试（168 项，起真实服务打接口）
+│   ├── 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.13",
+  "version": "0.9.0",
   "type": "module",
   "description": "栖 Roost：零依赖的 QQ 官方机器人框架，填 AppID/AppSecret 即连，插件可写任意语言",
   "license": "SEE LICENSE IN LICENSE",

package/src/api.js

@@ -10,8 +10,11 @@ const log = createLogger('api');
 export const FILE_TYPE = { IMAGE: 1, VIDEO: 2, VOICE: 3, FILE: 4 };
 
 /**
- * 官方硬限制：同一条消息最多被动回复 5 次（`msg_seq` 取 1–5）。
- * 第 6 次服务端返回 40034128「被动回复时间或次数超限」。
+ * 被动回复序号的**最后一道**兜底上限。
+ *
+ * 官方口径按会话类型不同：群聊 5 次（`msg_seq` 1–5），单聊 4 次（1–4）。
+ * 这里只按 `msgId` 记，拿不到会话类型，所以取两者较大的 5 当「绝不可能超过」的硬顶。
+ * 精确拦截在 `outbound.js`（`PASSIVE_MAX_REPLIES[kind]`），正常流程走不到这里。
  */
 const PASSIVE_MAX_SEQ = 5;
 
@@ -164,6 +167,16 @@ export class QQApi {
       const err = new Error(`HTTP ${res.status} ${method} ${path}: ${msg}`);
       err.status = res.status;
       err.body = data;
+      /**
+       * QQ 的业务错误码，和 HTTP 状态码是两回事。
+       *
+       * 同样是 400，`40054004`（无好友关系）和 `40034006`（内容违规）
+       * 该做的事完全不同：前者要更新可达性状态，后者只能改文案。
+       * 上层拿不到这个码就只能瞎猜，所以在这里就拆出来。
+       *
+       * 常见值见 `docs/官方接口限制.md` 与 `src/reach.js`。
+       */
+      err.qqCode = Number(data?.code ?? data?.err_code ?? 0) || 0;
       throw err;
     }
     return data;
@@ -946,14 +959,14 @@ export class QQApi {
   }
 
   /**
-   * 被动回复序号。官方硬限制：**同一条消息最多回复 5 次**（msg_seq 取 1–5），
-   * 第 6 次返回 40034128。这里兜一道，正常流程由 outbound.js 先拦。
+   * 被动回复序号。硬顶见 `PASSIVE_MAX_SEQ`（群聊 5 / 单聊 4，这里取 5 兜底），
+   * 超了服务端返回 40034128。正常流程由 outbound.js 按会话类型先拦。
    */
   #nextSeq(msgId) {
     const cur = this.seqMap.get(msgId) ?? 0;
     if (cur >= PASSIVE_MAX_SEQ) {
       throw new Error(
-        `同一条消息最多回复 ${PASSIVE_MAX_SEQ} 次（QQ 官方限制），这条已经回了 ${cur} 次`,
+        `同一条消息最多回复 5 次（群聊）/ 4 次（单聊），这条已经回了 ${cur} 次`,
       );
     }
     const next = cur + 1;

package/src/bot.js

@@ -16,6 +16,9 @@ import { BotMetrics } from './runtime.js';
 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';
 
 /**
  * 一个机器人的完整运行时。
@@ -86,6 +89,25 @@ export class BotRuntime {
      */
     this.groupNames = new Map();
     this.roles = new RoleStore(this.paths.roles);
+    /**
+     * 可达性：谁能私聊、哪个群能主动推。
+     *
+     * 官方没有查好友的接口，只能靠 6 个事件维护（FRIEND_ADD/DEL、
+     * C2C_MSG_REJECT/RECEIVE、GROUP_MSG_REJECT/RECEIVE）。
+     * 插件可以通过 `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;
@@ -159,6 +181,7 @@ export class BotRuntime {
     this.pipeline = createDefaultPipeline(cfg, {
       isSticky: (chatId) => this.session.isSticky(chatId),
       metrics: this.metrics,
+      gate: this.gate,
     });
 
     /**
@@ -171,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,
@@ -183,6 +219,9 @@ export class BotRuntime {
       outbound: this.outbound,
       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,
@@ -194,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) });
@@ -344,6 +401,51 @@ export class BotRuntime {
     return this.groupNames.get(groupOpenid)?.name || undefined;
   }
 
+  /**
+   * 用 6 个事件维护可达性。
+   *
+   * 官方**没有查好友列表的接口**（sitemap 里 `friend` 只有两个事件页），
+   * 所以「接入之前就存在的关系」永远是未知的，只能维护「接入之后的变化」。
+   * 三态语义与判定顺序见 `src/reach.js` 头注释。
+   */
+  async #noteReach(eventName, d) {
+    const openid = d?.openid ?? '';
+    switch (eventName) {
+      case 'FRIEND_ADD':
+        await this.reach.noteFriendAdd({
+          openid,
+          unionOpenid: d?.author?.union_openid ?? '',
+          scene: d?.scene ?? 0,
+        });
+        break;
+      case 'FRIEND_DEL':
+        await this.reach.noteFriendDel({ openid });
+        break;
+      case 'C2C_MSG_REJECT':
+        await this.reach.noteC2cPush({ openid, on: false });
+        break;
+      case 'C2C_MSG_RECEIVE':
+        await this.reach.noteC2cPush({ openid, on: true });
+        break;
+      case 'GROUP_MSG_REJECT':
+        await this.reach.noteGroupPush({
+          groupOpenid: d?.group_openid,
+          on: false,
+          by: d?.op_member_openid,
+        });
+        break;
+      case 'GROUP_MSG_RECEIVE':
+        await this.reach.noteGroupPush({
+          groupOpenid: d?.group_openid,
+          on: true,
+          by: d?.op_member_openid,
+        });
+        break;
+      default:
+        break;
+    }
+  }
+
   /**
    * 补一个群的名字（给面板调的公开入口，内部走带缓存的那份）。
    * 不会抛异常，调用方不用 try/catch。
@@ -415,11 +517,96 @@ export class BotRuntime {
     await this.outbound?.flush().catch(() => {});
     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 };
+  }
+
   /* ---------------- 事件分发 ---------------- */
 
   /**
@@ -456,6 +643,12 @@ export class BotRuntime {
         await groups.onRemoved(d?.group_openid);
       }
 
+      // 可达性：官方没有查询接口，只能靠这 6 个事件维护（见 src/reach.js）
+      // 放在插件监听器之前，插件读到的就是最新状态
+      await this.#noteReach(eventName, d).catch((e) => {
+        this.log.warn(`可达性更新失败: ${e.message}`);
+      });
+
       const meta = EVENTS[eventName] ?? null;
       for (const l of registry.listeners.get(eventName) ?? []) {
         // 事件里的群：有 group_openid 就按群开关过滤，没有（如私聊事件）就放行
@@ -478,6 +671,42 @@ 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
+        .noteC2cObserved({ openid: msg.userId, unionOpenid: d?.author?.union_openid })
+        .catch(() => {});
+    }
+
     /**
      * 先播出去，再做业务处理。
      *
@@ -606,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 },
   });