qq-bot-roost 0.8.13 → 0.9.0

package/src/message-bus.js

@@ -104,7 +104,7 @@ export function serializeMessage(botId, msg) {
     mentioned: Boolean(msg.mentioned),
     addressed: Boolean(msg.addressed),
     isCommand: Boolean(msg.isCommand),
-    /** 被动回复用（5 分钟窗口，同一条最多 5 次） */
+    /** 被动回复用（群聊 5 分钟 / 5 次，单聊 60 分钟 / 4 次） */
     msgId: msg.id,
     /** 引用回复用（message_reference.message_id） */
     msgIdx: msg.msgIdx,

package/src/message.js

@@ -362,7 +362,7 @@ export function buildMessage(eventName, d, { api, cfg, outbound, session }) {
   }
 
   // 底层发送：group 走群接口，c2c 走单聊接口。
-  // 一律经过 outbound，由它处理 5 分钟窗口、每秒限速、主动消息额度。
+  // 一律经过 outbound，由它处理被动窗口（群聊 5 分钟 / 单聊 60 分钟）、每秒限速、主动消息额度。
   const send = (opts, passive) => {
     if (kind !== 'group' && kind !== 'c2c') return Promise.resolve(null);
     const body = passive ? { msgId: msg.id, ...opts } : { ...opts };
@@ -410,7 +410,7 @@ export function buildMessage(eventName, d, { api, cfg, outbound, session }) {
   const MAX_CHUNK = 1500; // 单条上限，超了按行切成多条
 
   /**
-   * 被动回复（带 msg_id，5 分钟内有效）。
+   * 被动回复（带 msg_id，群聊 5 分钟内、单聊 60 分钟内有效）。
    * **不会立刻发出**，而是攒到本次处理结束，由 flushReplies() 合并成一条。
    * 想立刻发用 msg.replyNow()。
    */
@@ -446,7 +446,7 @@ export function buildMessage(eventName, d, { api, cfg, outbound, session }) {
    * 引用回复：以「引用某条消息」的样式发出去（官方 `message_reference`）。
    *
    * 跟 `reply()` 不是一回事：
-   *   - `reply()` 是**被动回复**，靠 msg_id，5 分钟内、同一条最多 5 次
+   *   - `reply()` 是**被动回复**，靠 msg_id，群聊 5 分钟 / 5 次，单聊 60 分钟 / 4 次
    *   - 这个是**引用**，靠 `REFIDX`，视觉上带"回复某某"的引用块
    *
    * 默认引用当前这条消息（用它的 `msg_idx`）。想引用别的传 `refIdx`。

package/src/outbound.js

@@ -20,15 +20,36 @@ const log = createLogger('outbound');
  * 插件只管调 msg.reply()，剩下的交给这里。
  */
 
-/** 官方给的有效期是 5 分钟，留 15 秒给网络和服务端时钟差 */
-const PASSIVE_WINDOW_MS = 5 * 60 * 1000;
-const PASSIVE_SAFE_MS = PASSIVE_WINDOW_MS - 15_000;
+/**
+ * 被动回复窗口。**两个接口不一样，别再用一个值。**
+ *
+ *   群聊 `/v2/groups/{group_openid}/messages`：5 分钟、最多 5 次
+ *   单聊 `/v2/users/{user_openid}/messages`：**60 分钟、最多 4 次**
+ *
+ * 以前两者共用「5 分钟 / 5 次」（群聊的口径），单聊的后果是：
+ *   · 5 分钟后就降级成主动消息，白吃「每个好友 1000 条/天」的额度，
+ *     而被动回复本来不占主动额度；
+ *   · 第 5 次回复会被服务端拒（40034128）。
+ *
+ * 各留 15 秒给网络和服务端时钟差。
+ */
+const PASSIVE_WINDOW_MS = {
+  group: 5 * 60 * 1000,
+  c2c: 60 * 60 * 1000,
+};
+const PASSIVE_SAFE_MS = {
+  group: PASSIVE_WINDOW_MS.group - 15_000,
+  c2c: PASSIVE_WINDOW_MS.c2c - 15_000,
+};
 
 /**
- * 官方硬限制：同一条消息最多回复 5 次（`msg_seq` 取 1–5）。
- * 第 6 次服务端会返回 40034128「被动回复时间或次数超限」。
+ * 同一条消息最多回复次数：群聊 5、单聊 4。
+ * 超过会返回 40034128「被动回复时间或次数超限」。
  */
-const PASSIVE_MAX_REPLIES = 5;
+const PASSIVE_MAX_REPLIES = {
+  group: 5,
+  c2c: 4,
+};
 
 /** 主动消息进入审核的返回码，属于正常结果 */
 const CODE_AUDIT = 304023;
@@ -69,7 +90,15 @@ export class SendError extends Error {
   constructor(message, code, detail) {
     super(message);
     this.name = 'SendError';
-    this.code = code; // offline | expired | quota | api
+    /**
+     * 五种，按「多久能好」排序：
+     *   offline  连不上 QQ —— 等它上线
+     *   expired  被动窗口过了 —— 等用户再说一句
+     *   quota    今天这个会话的主动额度用完了 —— 等跨天
+     *   rate     这一分钟发得太密 —— 等一分钟
+     *   api      接口报错 —— 看具体错误码
+     */
+    this.code = code; // offline | expired | quota | rate | api
     this.detail = detail;
   }
 }
@@ -207,7 +236,8 @@ export class Outbound {
       active: 0,
       degraded: 0, // 被动超窗降级为主动的次数
       expired: 0, // 因超窗被拒绝的次数
-      quotaBlocked: 0, // 因额度用完被拒绝的次数
+      quotaBlocked: 0, // 因日额度用完被拒绝的次数（等跨天才好）
+      rateBlocked: 0, // 因分钟限流被拒绝的次数（等一分钟就好）
       throttled: 0, // 因限速排队过的次数
       audit: 0, // 进入审核的主动消息
       offline: 0,
@@ -245,11 +275,12 @@ export class Outbound {
     // 1) 被动窗口检查：快过期就别发请求了，直接按主动消息处理
     if (wantPassive) {
       const age = receivedAt ? Date.now() - receivedAt : 0;
-      if (age > PASSIVE_SAFE_MS) {
+      const safeMs = PASSIVE_SAFE_MS[kind];
+      if (age > safeMs) {
         if (!this.downgrade) {
           this.stats.expired += 1;
           throw new SendError(
-            `这条消息已经过去 ${Math.round(age / 1000)} 秒，超过 QQ 的 5 分钟被动回复窗口，回复发不出去了`,
+            `这条消息已经过去 ${Math.round(age / 1000)} 秒，超过 QQ 的 ${Math.round(safeMs / 1000)} 秒被动回复窗口，回复发不出去了`,
             'expired',
           );
         }
@@ -267,17 +298,18 @@ export class Outbound {
     // 2) 排队 + 限速 + 额度扣减 + 实际发送
     //    额度的「查」和「扣」都放在队列里，避免两个并发推送同时通过检查后超额
     return this.#enqueue(chatKey, async () => {
-      // 2a) 被动回复次数上限：官方「每个消息最多回复 5 次」
+      // 2a) 被动回复次数上限：群聊 5 次、单聊 4 次
       //     同一条消息被多个插件连着回、或用户一句话触发多轮时很容易撞上，
       //     本地先拦，省得服务端返回 40034128 再兜底
       let passiveNow = wantPassive && !active;
       if (passiveNow) {
+        const maxReplies = PASSIVE_MAX_REPLIES[kind];
         const used = this.passiveCount.get(body.msgId) ?? 0;
-        if (used >= PASSIVE_MAX_REPLIES) {
+        if (used >= maxReplies) {
           if (!this.downgrade) {
             this.stats.expired += 1;
             throw new SendError(
-              `同一条消息最多回复 ${PASSIVE_MAX_REPLIES} 次（QQ 官方限制），这条已经回满了。\n` +
+              `同一条消息最多回复 ${maxReplies} 次（QQ 官方限制），这条已经回满了。\n` +
                 `等用户再说一句，就能继续用被动回复。`,
               'expired',
             );
@@ -308,11 +340,19 @@ export class Outbound {
             'quota',
           );
         }
+        /**
+         * 分钟限流单独一个 code（`rate`），**不能和日额度共用 `quota`**。
+         *
+         * 两者的「多久能好」差三个数量级：日额度要等跨天，分钟限流等一分钟。
+         * 以前都叫 `quota`，调用方只能按最坏情况处理——dsh-roost 的主动搭话
+         * 会把「发得太密」当成「今天说满了」，直接放弃一整天。
+         * 反过来按最好情况处理，就是每分钟重试一次空转到跨天。
+         */
         if (!this.#allowActiveThisMinute(chatKey)) {
-          this.stats.quotaBlocked += 1;
+          this.stats.rateBlocked += 1;
           throw new SendError(
             `这个会话的主动消息发得太密（官方限制 ${this.activePerMin} 条/分钟），稍后再试。`,
-            'quota',
+            'rate',
           );
         }
         await this.quota.consume(chatKey);
@@ -392,6 +432,16 @@ export class Outbound {
     );
   }
 
+  /**
+   * 最近 60 秒这个会话发了几条。
+   *
+   * 只读，不占坑——`#allowActiveThisMinute` 会顺手把当前时刻压进队列，
+   * 诊断用的时候不能有这个副作用（面板刷一次就少一次额度就离谱了）。
+   */
+  rateUsed(chatKey, now = Date.now()) {
+    return (this.activeLog.get(chatKey) ?? []).filter((t) => now - t < 60_000).length;
+  }
+
   /**
    * 主动消息分钟级限流。官方单关系维度是 20/qpm，
    * 日额度够但一分钟内猛发照样会被服务端 40034100 拦下，本地先挡。

package/src/paths.js

@@ -57,6 +57,14 @@ export const DIRS = {
   botsData: path.join(HOME, 'data', 'bots'),
   /** 机器人日志目录 */
   botsLogs: path.join(HOME, 'logs', 'bots'),
+  /**
+   * 暂停闸状态目录：`global.json` + `<botId>.json`。
+   *
+   * 按鸟拆文件而不是一个 `gate.json`：一个进程里可能同时跑好几只鸟，
+   * 共用一个文件时 `.tmp` + `rename` 只能保证「不会写坏」，
+   * 不能保证不丢更新（两只鸟同时改，后写的覆盖先写的）。
+   */
+  gate: path.join(HOME, 'data', 'gate'),
 };
 
 export const PATHS = {
@@ -113,8 +121,20 @@ export function botPaths(id) {
     groups: path.join(base, 'groups.json'),
     roles: path.join(base, 'roles.json'),
     quota: path.join(base, 'quota.json'),
+    /** 可达性（好友关系 / 主动推送开关），官方无查询接口，靠事件维护 */
+    reach: path.join(base, 'reach.json'),
     /** 统计库（SQLite，存消息计数与成员活跃，不存正文） */
     stats: path.join(base, 'stats.db'),
+    /**
+     * 事件账本（SQLite，存原始消息）。
+     *
+     * 和 `stats.db` 分开两个文件，不是随手分的：
+     *   - 生命周期不同：stats 留 90 天聚合，events 只留 7 天全文，滚动删的策略和频率都不一样
+     *   - 隐私边界不同：stats 明确「不存正文」，events 存正文。混一个库的话，
+     *     「这个库会不会被拷走」这个问题的答案就说不清了
+     *   - 备份/删除粒度不同：用户想清掉聊天记录，删 `events.db` 一个文件就够
+     */
+    events: path.join(base, 'events.db'),
     pluginState: path.join(base, 'plugins.json'),
     pluginDataDir: path.join(base, 'plugins'),
     /** 日志根目录 */

package/src/pipeline.js

@@ -1,4 +1,5 @@
 import { createLogger } from './logger.js';
+import { gateMiddleware } from './gate.js';
 
 const log = createLogger('pipeline');
 
@@ -250,8 +251,16 @@ export function cooldownMiddleware() {
 }
 
 /** 按配置组装默认管道 */
-export function createDefaultPipeline(cfg, { isSticky, metrics = null } = {}) {
+export function createDefaultPipeline(cfg, { isSticky, metrics = null, gate = null } = {}) {
   const p = new Pipeline({ metrics });
+  /**
+   * 闸在最前面，连去重表都不写。
+   *
+   * 账本**不在这里**——`bot.js` 里 `ledger.append()` 在 `pipeline.run()` 之前，
+   * 所以暂停期间的消息照样入账。这条顺序是暂停闸能「不丢消息」的前提：
+   * 闸放在账本之前的话，暂停就等于丢消息，而官方没有历史消息接口，丢了补不回来。
+   */
+  if (gate) p.use('gate', gateMiddleware(gate, { metrics }));
   p.use('dedup', dedupMiddleware(cfg, { metrics }));
   p.use('whitelist', whitelistMiddleware(cfg, { metrics }));
   p.use('ratelimit', ratelimitMiddleware(cfg, { isSticky, metrics }));