qq-bot-roost 0.9.10 → 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.10-blueviolet" alt="版本 0.9.10">
+<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.10",
+  "version": "0.9.11",
   "type": "module",
   "description": "栖 Roost：零依赖的 QQ 官方机器人框架，填 AppID/AppSecret 即连，插件可写任意语言",
   "license": "SEE LICENSE IN LICENSE",

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/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,
         });
       },