qq-bot-roost 1.0.8 → 1.0.9

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-813%20passed-brightgreen" alt="测试 813 项">
+<img src="https://img.shields.io/badge/tests-826%20passed-brightgreen" alt="测试 826 项">
 <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-1.0.8-blueviolet" alt="版本 1.0.8">
+<img src="https://img.shields.io/badge/version-1.0.9-blueviolet" alt="版本 1.0.9">
 <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": "1.0.8",
+  "version": "1.0.9",
   "type": "module",
   "description": "栖 Roost：零依赖的 QQ 官方机器人框架，填 AppID/AppSecret 即连，插件可写任意语言",
   "license": "SEE LICENSE IN LICENSE",

package/src/api.js

@@ -147,6 +147,8 @@ export class QQApi {
     this.seqMap = new Map();
     // 群管内邀开关，由 BotRuntime 按配置同步；默认关
     this.groupInvited = false;
+    // 「发图带空格」兼容开关，由 BotRuntime 按 cfg.media.placeholderSpace 同步；默认关
+    this.mediaPlaceholderSpace = false;
     // 群角色查询缓存：groupOpenid -> { at, value }。bot_state 只有 30 QPM
     this.roleCache = new Map();
     /**
@@ -564,11 +566,15 @@ export class QQApi {
     const up = await this.uploadMedia(scene, target, { fileType, url, fileData });
     if (!up?.file_info) throw new Error('上传成功但未返回 file_info');
     /**
-     * **不要 content。**
+     * **不要在这里传 content。**
      *
      * 官方字段表：`msg_type=7` 时生效的是 `media`，`content` 只在
      * `msg_type=0` 时是全文。以前这里填了一个空格占位，客户端会把
      * 它当成正文，渲染出一块空的文字区（图被挤到一侧）。
+     *
+     * 那个空格现在做成面板「配置 → 发图兼容」的可选开关（默认关）：
+     * 打开后由 `#payload()` 在最终报文里补，这里依旧不带 content，
+     * 免得开关关着时又冒出空格、开着时补两遍。
      */
     const opts = {
       msgType: 7,
@@ -632,6 +638,19 @@ export class QQApi {
     return this.groupInvited;
   }
 
+  /**
+   * 「发图带空格」开关。由 BotRuntime 按 cfg.media.placeholderSpace 初始化，
+   * 面板改动时由 /api/config 同步进来，立即生效、不用重启。
+   *
+   * 只认布尔 true：`"false"` / `0` / `undefined` 一律当关。
+   * 面板配置走 HTTP，字符串 "false" 按真值判断会被读成「开」——
+   * security.trust.enforce 踩过这个坑，这里不重犯。
+   */
+  setMediaPlaceholderSpace(v) {
+    this.mediaPlaceholderSpace = v === true;
+    return this.mediaPlaceholderSpace;
+  }
+
   /** 内邀接口的统一闸门。没开门就抛错，别把请求发出去刷一屏 11253 */
   #needInvite() {
     if (!this.groupInvited) {
@@ -1260,7 +1279,24 @@ export class QQApi {
   }
 
   #payload(opts) {
-    return buildSendPayload(opts, (id) => this.#nextSeq(id));
+    const payload = buildSendPayload(opts, (id) => this.#nextSeq(id));
+    /**
+     * 「发图带空格」兼容开关（默认关，面板「配置 → 发图兼容」）。
+     *
+     * 放在最终报文这一层，是为了**一处覆盖所有发图路径**：
+     * msg.replyImage / replyImageBuffer、api.sendMedia、插件拿到的
+     * ctx.api.sendMedia、以及没有调度器时的 api.sendGroup 兜底，最后都过这里。
+     * 放在 outbound 或 message 层都会漏，还会污染投递账本的正文摘要
+     * （账本把纯空格当「没有正文」，测试也断言富媒体不带 content）。
+     *
+     * 只补「没有正文的富媒体」：
+     *   · msg_type=7 且 content 为空 —— 老版就是在这里塞 ' '
+     *   · 有 text 的图文混排不动，markdown(2) / ark(3) / 卡片(8) 也不动
+     */
+    if (this.mediaPlaceholderSpace && payload.msg_type === 7 && !payload.content) {
+      payload.content = ' ';
+    }
+    return payload;
   }
 
   /**

package/src/bot.js

@@ -200,6 +200,9 @@ export class BotRuntime {
     // 群管内邀开关：api 层有自己的副本，配置变了由面板接口同步过来。
     // mock 的 api 也实现了同名方法，一起同步，方便本地验证插件的群管逻辑
     this.api.setGroupInvited?.(cfg.groupManage?.invited);
+    // 发图带空格：只影响真实 QQApi 的最终报文；mock api 不拼官方报文、
+    // 没实现这个 setter，?. 会直接跳过（演示模式下开关不适用）
+    this.api.setMediaPlaceholderSpace?.(cfg.media?.placeholderSpace);
 
     this.session = new SessionManager({
       stickyMs: Math.max(0, (cfg.session?.stickySec ?? 180) * 1000),

package/src/config.js

@@ -335,6 +335,22 @@ const BOT_DEFAULTS = {
   groupManage: {
     invited: false,
   },
+
+  /**
+   * 富媒体（图片 / 视频 / 语音 / 文件）发送兼容选项。
+   *
+   * `placeholderSpace` 默认 false：只发一张图时，msg_type=7 的 content
+   * 保持空串，QQ 里是一张干净的图（v1.0.6 起的行为）。
+   * 打开后由 `QQApi.#payload()` 给没有正文的富媒体补一个空格，回到
+   * v1.0.6 之前的排版：客户端按图文混排渲染，图外面多一块空白文字区。
+   * 老客户端 / 旧插件依赖那个占位空格时才需要打开。
+   *
+   * 官方对非图片类型的 content 会忽略，所以实际只对图片有观感影响；
+   * 带说明文字的图片（replyImage 的 text）不受影响。
+   */
+  media: {
+    placeholderSpace: false,
+  },
 };
 
 function deepMerge(base, extra) {
@@ -529,6 +545,8 @@ export async function saveBotConfig(id, cfg) {
     gate: cfg.gate ?? { pauseOnStart: false },
     plugins: cfg.plugins,
     groupManage: cfg.groupManage ?? { invited: false },
+    // 脏值（字符串 / 数组 / 旧配置里混进来的东西）一律规范成默认关，别污染配置文件
+    media: { placeholderSpace: cfg.media?.placeholderSpace === true },
   });
 }
 

package/src/message.js

@@ -848,6 +848,9 @@ export function buildMessage(eventName, d, { api, cfg, outbound, session, traceI
    * 理由是「官方不接受空 content」——那说的是传 `''`，跟不传不是一回事，
    * 结果客户端按图文混排渲染，图外面多出一圈文字区（v1.0.6 修掉）。
    *
+   * 面板「配置 → 发图兼容」把这个空格做成了可选开关：打开后由 api 层在
+   * 最终报文里补回占位空格（老客户端 / 旧插件需要时），这里依旧不带 content。
+   *
    * 发送前会先把攒着的文本 flush 掉，免得「缓冲中的回复」被这条
    * 富媒体消息挤成顺序错乱的两条。
    */

package/src/web/server.js

@@ -1605,6 +1605,24 @@ export async function startWebServer({
             cfg.groupManage = { invited: Boolean(body.groupManage.invited) };
             rt.api?.setGroupInvited?.(cfg.groupManage.invited);
           }
+          /**
+           * 「发图带空格」兼容开关（默认关）。
+           * 严格只认布尔 true：字符串 "false" 按真值判断会被当成「开」，
+           * 和 security.trust.enforce 踩过的是同一个坑。
+           * 同步给 api 实例，勾选后立即生效、不用重启。
+           *
+           * 还要求「对象 + 布尔字段」齐全才写：面板漏传字段、旧版前端、
+           * 或者 body.media 是 [] / {} 时，不该把已经打开的开关静默关掉。
+           */
+          if (
+            body.media &&
+            typeof body.media === 'object' &&
+            !Array.isArray(body.media) &&
+            typeof body.media.placeholderSpace === 'boolean'
+          ) {
+            cfg.media = { placeholderSpace: body.media.placeholderSpace };
+            rt.api?.setMediaPlaceholderSpace?.(cfg.media.placeholderSpace);
+          }
 
           await saveBotConfig(rt.id, cfg);
           log.info('配置已通过面板更新');

package/web/app.js

@@ -1070,6 +1070,8 @@ function fillForm(c) {
   f.logLevel.value = c.logLevel || 'info';
 
   f.groupInvited.checked = Boolean(c.groupManage?.invited);
+  // 严格只认 true：老配置文件里没这个字段时保持关闭
+  f.mediaPlaceholderSpace.checked = c.media?.placeholderSpace === true;
 
   /**
    * 插件来源校验开关。`pubkeySet: false` 时必须说清楚「开了也没用」——
@@ -1405,6 +1407,36 @@ document.addEventListener('click', async (e) => {
   }
 });
 
+/* ---------------- 发图兼容：勾选即生效 ---------------- */
+
+/**
+ * 「保存配置」按钮在表单顶部/底部，离这块设置很远，勾完还得滚过去点一下才生效。
+ * 这里跟 `autoSaveIntents` 一个套路：change 时局部 PUT 只提交 media 一个字段，
+ * 后端 `/api/config` 是合并语义，其它配置项不会被这次请求碰。
+ * 不需要防抖——勾一下就是一次，且不会像 intents 那样触发重连。
+ */
+$('#mediaPlaceholderSpace').addEventListener('change', async (e) => {
+  const on = e.target.checked;
+  const tip = $('#mediaSpaceMsg');
+  if (tip) tip.textContent = '正在应用…';
+  try {
+    await api('/api/config', {
+      method: 'PUT',
+      body: JSON.stringify({ media: { placeholderSpace: on } }),
+    });
+    if (tip) {
+      tip.textContent = on ? '已生效：发图会带空格' : '已生效：恢复干净图';
+      setTimeout(() => {
+        if (tip.textContent.startsWith('已生效')) tip.textContent = '';
+      }, 4000);
+    }
+  } catch (err) {
+    // 没保存成功就把勾选退回去，别让用户以为已经开了
+    e.target.checked = !on;
+    if (tip) tip.textContent = '应用失败: ' + err.message;
+  }
+});
+
 $('#cfgForm').addEventListener('submit', async (e) => {
   e.preventDefault();
   const f = e.target;
@@ -1444,6 +1476,10 @@ $('#cfgForm').addEventListener('submit', async (e) => {
     groupManage: {
       invited: f.groupInvited.checked,
     },
+    // 发图兼容：和 groupManage 一样是每台机器人一份，勾选后立即生效
+    media: {
+      placeholderSpace: f.mediaPlaceholderSpace.checked,
+    },
     // 全局设置（config/bot.json），和 webui 一样不写进机器人配置
     security: {
       trust: { enforce: f.trustEnforce.checked },

package/web/index.html

@@ -517,6 +517,22 @@
         </label>
       </div>
 
+      <div class="box">
+        <div class="box-hd"><h3>发图兼容</h3><span class="hint">默认关闭</span></div>
+        <label class="switch">
+          <input type="checkbox" name="mediaPlaceholderSpace" id="mediaPlaceholderSpace">
+          发图片时带一个空格（v1.0.6 之前的行为）
+        </label>
+        <div class="hint" id="mediaSpaceMsg" style="margin-top:4px"></div>
+        <div class="hint" style="margin-top:8px">
+          只发一张图时，框架本来不带正文，QQ 里就是干净的一张图。打开后会在富媒体消息里
+          补一个空格当正文，回到旧版排版：图片被挤向一侧、外面多出一块空白文字区。<br>
+          可能有奇妙的作用（），<b>勾选后立即生效、不用点保存也不用重启</b>。
+          带说明文字的图片（<code>replyImage(..., { text })</code>）不受影响；
+          视频 / 语音 / 文件的 content 官方会忽略，勾上也没有副作用。
+        </div>
+      </div>
+
       <div class="box">
         <div class="box-hd"><h3>群管能力</h3><span class="hint">禁言 / 撤回已开放；群成员与踢人需官方白名单</span></div>
         <label class="switch">