qq-bot-roost 0.9.9 → 0.9.11

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-679%20passed-brightgreen" alt="测试 679 项">
 <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.9-blueviolet" alt="版本 0.9.9">
+<img src="https://img.shields.io/badge/version-0.9.11-blueviolet" alt="版本 0.9.11">
 <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>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qq-bot-roost",
-  "version": "0.9.9",
+  "version": "0.9.11",
   "type": "module",
   "description": "栖 Roost：零依赖的 QQ 官方机器人框架，填 AppID/AppSecret 即连，插件可写任意语言",
   "license": "SEE LICENSE IN LICENSE",
@@ -29,9 +29,9 @@
     "start": "node src/main.js",
     "mock": "node src/main.js --mock",
     "check": "node src/main.js --check",
-    "test": "node test/selftest.mjs && node test/qrlogin.mjs && node test/deps.mjs && node --test test/trust.mjs && node --test test/manifest.mjs && node --test test/trace.mjs && node --test test/fuzz-tar.mjs",
+    "test": "node test/selftest.mjs && node test/qrlogin.mjs && node test/deps.mjs && node --test test/trust.mjs && node --test test/manifest.mjs && node --test test/trace.mjs && node --test test/fuzz-tar.mjs && node --test test/group-name.mjs",
     "test:e2e": "node test/e2e.mjs",
-    "test:all": "node test/selftest.mjs && node test/qrlogin.mjs && node test/deps.mjs && node --test test/trust.mjs && node --test test/manifest.mjs && node --test test/trace.mjs && node --test test/fuzz-tar.mjs && node test/e2e.mjs && node test/live-driver.mjs",
+    "test:all": "node test/selftest.mjs && node test/qrlogin.mjs && node test/deps.mjs && node --test test/trust.mjs && node --test test/manifest.mjs && node --test test/trace.mjs && node --test test/fuzz-tar.mjs && node --test test/group-name.mjs && node test/e2e.mjs && node test/live-driver.mjs",
     "check:secrets": "node scripts/check-secrets.mjs",
     "create": "node scripts/create-plugin.mjs",
     "test:plugin": "node scripts/test-plugin.mjs",

package/src/api.js

@@ -284,14 +284,22 @@ export class QQApi {
     const body = { file_type: fileType, srv_send_msg: false };
     if (url) body.url = url;
     if (fileData) body.file_data = fileData;
+    /**
+     * `file_name` **不只分片合并要**。
+     *
+     * 官方字段说明：「文件名（分片上传或者二进制上传时必填）」。
+     * 以前只在 `upload_id` 那条路带上，于是小文件走 base64 直传时是**无名文件**——
+     * QQ 客户端拿不到名字，显示出来就没有扩展名（`报告` 而不是 `报告.docx`），
+     * 对方还得自己猜怎么打开。2026-11-02 线上真踩过。
+     *
+     * URL 上传不用带：那种路径平台自己下载转存，名字从 URL 里取。
+     */
+    if (fileName) body.file_name = fileName;
     /**
      * 分片合并：`upload_id` 一进，服务端就走「合并已上传分片」那条路，
-     * `url` 可以为空。但 `file_name` 这条路径**必填**（官方字段说明）。
+     * `url` 可以为空。
      */
-    if (uploadId) {
-      body.upload_id = uploadId;
-      if (fileName) body.file_name = fileName;
-    }
+    if (uploadId) body.upload_id = uploadId;
     const r = await this.#request('POST', path, body);
 
     if (cacheKey && r?.file_info) {
@@ -348,6 +356,11 @@ export class QQApi {
     const up = await this.uploadMedia(scene, target, {
       fileType,
       fileData: buf.toString('base64'),
+      /**
+       * 二进制直传**必须带文件名**（官方字段说明：分片上传或二进制上传时必填）。
+       * 少了它 QQ 侧就是个无名文件，客户端连扩展名都显示不出来。
+       */
+      fileName: filePath.split(/[\\/]/).pop() || 'file',
       reuse: false,
     });
     if (cacheKey && up?.file_info) {
@@ -967,7 +980,21 @@ export class QQApi {
       content_raw: String(p.contentRaw ?? ''),
     };
     if (p.streamMsgId) payload.stream_msg_id = p.streamMsgId;
-    if (p.msgId) payload.msg_id = p.msgId;
+    if (p.msgId) {
+      payload.msg_id = p.msgId;
+      /**
+       * `msg_seq` 必须显式给，而且**所有分片用同一个值**。
+       *
+       * 流式消息是「一条消息在长」，不是多条——官方示例里首片、续片、结束片
+       * 都是同一个 `msg_seq`。不传的话服务端按 1 处理，而我们自己的普通回复
+       * 也从 1 开始递增，于是「先流式、再发图/文件」会撞
+       * `40054005 消息被去重`。
+       *
+       * 取值由调用方先算好传进来（`replyStream` 会在首片前调 `takeSeq`）。
+       */
+      if (p.msgSeq != null) payload.msg_seq = Number(p.msgSeq);
+      else payload.msg_seq = this.#nextSeq(p.msgId);
+    }
     if (p.eventId) payload.event_id = p.eventId;
     if (p.isWakeup) payload.is_wakeup = true;
     return this.#request('POST', `/v2/users/${enc(openid)}/stream_messages`, payload);
@@ -1198,6 +1225,18 @@ export class QQApi {
 
   /* ---------------- 内部 ---------------- */
 
+  /**
+   * 先占一个 `msg_seq`，供流式消息这种「一条消息发好几次」的场景用。
+   *
+   * 为什么要有：流式接口不走 `#payload`，所以以前完全不占序号——首片按默认 1 算，
+   * 而我们自己后续的普通回复也从 1 开始递增，两边撞上就是
+   * `40054005 消息被去重`（用户那边表现为「发了但没出现」）。
+   * 流式所有分片共用这一个值（一条消息一个序号）。
+   */
+  takeSeq(msgId) {
+    return this.#nextSeq(msgId);
+  }
+
   #payload(opts) {
     return buildSendPayload(opts, (id) => this.#nextSeq(id));
   }

package/src/bot.js

@@ -89,6 +89,16 @@ export class BotRuntime {
      * 拉不到就退回显示 openid，不影响任何功能。
      */
     this.groupNames = new Map();
+    /** 同群并发补名时复用同一个请求，避免一条消息打两次接口 */
+    this.groupNameInflight = new Map();
+    /**
+     * 群名接口的**全局**并发闸（`getGroupInfo` 是 30 QPM）。
+     *
+     * 原来只在 `fetchGroupNames` 里限流，那是「每次调用」的上限：
+     * 面板批量拉一次、消息链路每条群消息又拉一次，两条并发就翻倍。
+     */
+    this.groupNameActive = 0;
+    this.groupNameWaiters = [];
     this.roles = new RoleStore(this.paths.roles);
     /**
      * 可达性：谁能私聊、哪个群能主动推。
@@ -484,20 +494,45 @@ export class BotRuntime {
    * 再自己刷新一次很别扭；但也不能为了几个群名把面板卡住（接口有频控，
    * 群多了还会串行超时）。所以给一个总超时，到点有多少用多少。
    *
+   * **并发要限**：`getGroupInfo` 是 30 QPM。以前这里是 `allSettled` 全并行，
+   * 群多的用户一次打开面板就打 30+ 个请求，正好撞在限频上——
+   * 结果是**一个群名都拿不到**，面板继续显示一串 openid。
+   *
    * @param {string[]} ids
-   * @param {{timeoutMs?:number}} [opts]
+   * @param {{timeoutMs?:number, concurrency?:number}} [opts]
    */
-  async fetchGroupNames(ids = [], { timeoutMs = 2500 } = {}) {
-    const todo = [...new Set(ids.filter((id) => id && !this.groupName(id)))];
+  async fetchGroupNames(ids = [], { timeoutMs = 2500, concurrency = 4 } = {}) {
+    /** NaN / 0 / 负数都退回默认值：`Math.min(NaN, n)` 是 NaN，`Array.from({length:NaN})` 是空数组，一个群都不拉 */
+    const limit = Number.isFinite(concurrency) && concurrency >= 1 ? Math.floor(concurrency) : 4;
+    /**
+     * 不能只拉「还没有名字」的群：那样群改名后缓存永远不刷新。
+     * 统一交给 #ensureGroupName 按 10 分钟 TTL 判断——缓存新的时候它直接返回，不打接口。
+     */
+    const todo = [...new Set(ids.filter(Boolean))];
     if (!todo.length) return;
 
-    const work = Promise.allSettled(todo.map((id) => this.#ensureGroupName(id)));
+    const queue = todo.slice();
+    /** 到点之后不再派新的：已经发出去的请求收不回来，但尾巴不能一直延长 */
+    let stopped = false;
+    const worker = async () => {
+      for (;;) {
+        if (stopped) return;
+        const id = queue.shift();
+        if (!id) return;
+        // #ensureGroupName 自己吞异常，这里再兜一层只为保险
+        await this.#ensureGroupName(id).catch(() => {});
+      }
+    };
+    const n = Math.max(1, Math.min(limit, queue.length));
+    const work = Promise.all(Array.from({ length: n }, worker));
+
     let timer;
     const cap = new Promise((r) => {
       timer = setTimeout(r, timeoutMs);
       timer.unref?.();
     });
     await Promise.race([work, cap]);
+    stopped = true;
     clearTimeout(timer);
   }
 
@@ -516,16 +551,58 @@ export class BotRuntime {
   async #ensureGroupName(groupOpenid) {
     if (!groupOpenid) return;
     const hit = this.groupNames.get(groupOpenid);
-    if (hit && Date.now() - hit.at < 10 * 60_000) return;
+    /** ttl 由写入时决定：成功 10 分钟；11253（无权限）一天；其它失败 30 秒 */
+    if (hit && Date.now() - hit.at < (hit.ttl ?? 10 * 60_000)) return;
 
-    try {
-      const info = await this.api.getGroupInfo(groupOpenid);
-      const name = String(info?.group_name ?? info?.name ?? '').trim();
-      this.groupNames.set(groupOpenid, { name, at: Date.now() });
-    } catch {
-      // 拉不到就算了：openid 也能认，只是没那么好认
-      this.groupNames.set(groupOpenid, { name: '', at: Date.now() });
+    /**
+     * 同一条群消息可能触发两次（消息事件里一次、面板补一次），
+     * 两次都在 `await getGroupInfo` 之前查缓存 → 都判 miss → 打两次接口。
+     * 用 in-flight Map 让同 key 复用同一个 promise。
+     */
+    const flying = this.groupNameInflight.get(groupOpenid);
+    if (flying) return flying;
+
+    const job = (async () => {
+      /** 全局闸：不管从哪条链路进来，同时在飞的群名请求不超过 4 个 */
+      await this.#groupNameSlot();
+      try {
+        const info = await this.api.getGroupInfo(groupOpenid);
+        const name = String(info?.group_name ?? info?.name ?? '').trim();
+        this.groupNames.set(groupOpenid, { name, at: Date.now(), ttl: 10 * 60_000 });
+      } catch (e) {
+        // 拉不到就算了：openid 也能认，只是没那么好认
+        /** api.js 抛的是 `qqCode`，不是 code；读错字段会让 11253 永远按 30 秒重试 */
+        const code = Number(e?.qqCode ?? e?.code ?? e?.errCode ?? e?.errcode ?? 0);
+        this.groupNames.set(groupOpenid, {
+          name: '',
+          at: Date.now(),
+          // 11253 = 应用无接口访问权限（仅白名单机器人可用），别每 30 秒重试
+          ttl: code === 11253 ? 24 * 3600_000 : 30_000,
+        });
+      } finally {
+        this.#freeGroupNameSlot();
+        this.groupNameInflight.delete(groupOpenid);
+      }
+    })();
+
+    this.groupNameInflight.set(groupOpenid, job);
+    return job;
+  }
+
+  /** 拿一个群名请求的名额（最多 4 个同时在飞） */
+  async #groupNameSlot() {
+    if (this.groupNameActive < 4) {
+      this.groupNameActive += 1;
+      return;
     }
+    await new Promise((resolve) => this.groupNameWaiters.push(resolve));
+  }
+
+  #freeGroupNameSlot() {
+    const next = this.groupNameWaiters.shift();
+    // 有人排队就把名额直接转给它（active 不变），没人排队才真的空出来
+    if (next) next();
+    else this.groupNameActive = Math.max(0, this.groupNameActive - 1);
   }
 
   async stop() {
@@ -695,6 +772,20 @@ export class BotRuntime {
     /* ---- 消息事件 ---- */
     const msg = buildMessage(eventName, d, { api: this.api, cfg, outbound, session });
 
+    /**
+     * 群名不在官方事件里（只有 `group_openid`），但框架有缓存。
+     *
+     * 以前只缓存不挂到消息上，ai-chat 取不到群名就回退成**发消息人的昵称**——
+     * 结果群会话的标题显示成「我的昵称」，和私聊分不开。
+     * 这里挂上缓存值，并异步补拉（不阻塞这条消息）。补拉按 TTL 去重，
+     * 所以群改名后最多 10 分钟能刷到。
+     */
+    if (msg.kind === 'group' && msg.groupId) {
+      msg.groupName = this.groupName(msg.groupId) || '';
+      /** 每条群消息都问一次（内部按 TTL 去重）：群改名后能刷到，没权限时也不会反复打接口 */
+      this.fetchGroupNames([msg.groupId]).catch(() => {});
+    }
+
     /**
      * 入账：**第一件要做的事**，在去重 / 白名单 / 限流 / 暂停之前。
      *

package/src/message.js

@@ -812,6 +812,14 @@ export function buildMessage(eventName, d, { api, cfg, outbound, session, traceI
     let index = 0;
     let streamId = opts.streamMsgId || '';
     const target = userId;
+    /**
+     * **一条流式消息只占一个 `msg_seq`**，所有分片共用。
+     *
+     * 这一步必须在首片之前做：流式接口不走 `#payload`，不主动占号的话
+     * 服务端按默认 1 算，而我们后续的普通回复也从 1 开始递增，
+     * 两边一撞就是 `40054005 消息被去重`（用户看到「发了但没出现」）。
+     */
+    const seq = typeof api.takeSeq === 'function' ? api.takeSeq(msg.id) : 1;
 
     return {
       /** 发一片。返回服务端生成的 stream_msg_id（第一片才有） */
@@ -823,6 +831,7 @@ export function buildMessage(eventName, d, { api, cfg, outbound, session, traceI
           mode: 'replace',
           streamMsgId: streamId || undefined,
           msgId: msg.id,
+          msgSeq: seq,
           isWakeup: opts.isWakeup,
         });
         if (r?.id && !streamId) streamId = r.id;
@@ -837,6 +846,7 @@ export function buildMessage(eventName, d, { api, cfg, outbound, session, traceI
           mode: 'replace',
           streamMsgId: streamId || undefined,
           msgId: msg.id,
+          msgSeq: seq,
           isWakeup: opts.isWakeup,
         });
       },

package/src/updater.js

@@ -74,9 +74,9 @@ export async function currentVersion() {
  *
  * 留 2 秒容差：解压/拷贝和 stat 之间总有毫秒级误差。
  */
-async function updatedButNotRestarted() {
+async function updatedButNotRestarted(pkgPath = path.join(ROOT, 'package.json')) {
   try {
-    const st = await fs.stat(path.join(ROOT, 'package.json'));
+    const st = await fs.stat(pkgPath);
     const startedAt = Date.now() - process.uptime() * 1000;
     return st.mtimeMs > startedAt + 2000;
   } catch {
@@ -179,8 +179,13 @@ async function fetchTreeSha256(version) {
   }
 }
 
-export async function checkUpdate() {
-  const needsRestart = await updatedButNotRestarted();
+/**
+ * @param {{pkgPath?: string}} [o] pkgPath 只给测试用：
+ *   自测原来直接改仓库里 package.json 的 mtime，两个 `npm test` 并行就会互相毒化
+ *   （一个把 mtime 拨到未来、另一个正好读到，于是「正常时不提示重启」假失败）。
+ */
+export async function checkUpdate({ pkgPath } = {}) {
+  const needsRestart = await updatedButNotRestarted(pkgPath);
   const r = await checkUpdateCore();
   // 有新版本才值得多跑一次网络请求
   if (r?.ok && r.hasUpdate) {