@zaofan/dsh-qqbot 1.1.0 → 1.1.3

package/settings-host.js

@@ -3,7 +3,7 @@
  * ②表情包图库管理 API(列表/缩略图/批量/导入), 与 dsh-qqbot 共享同进程 store 单例。
  * 仅 web profile 装配; 同源 fence 抄 modsearch。
  */
-import { readFileSync, writeFileSync, rmSync, mkdirSync, existsSync, readdirSync, statSync, cpSync, renameSync, openSync, readSync, closeSync, createWriteStream } from 'node:fs';
+import { readFileSync, writeFileSync, appendFileSync, rmSync, mkdirSync, existsSync, readdirSync, statSync, cpSync, renameSync, openSync, readSync, closeSync, createWriteStream } from 'node:fs';
 import { extname, join, resolve, dirname, normalize, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawn } from 'node:child_process';
@@ -13,7 +13,14 @@ import { getStickerStore } from '@zaofan/dsh-qqbot/sticker-store';
 import { getScheduleStore } from '@zaofan/dsh-qqbot/schedule-store';
 
 export const name = 'qqbot-settings';
-export const inject = ['settings', 'webServer', 'agentPresets'];
+/**
+ * 服务依赖(2026-09-10 排查修复): 只声明必备的 settings/webServer。
+ * ⚠️ 曾声明 ['settings','webServer','agentPresets'] —— cordis 对 inject 声明的服务是
+ *    「等齐才调用 apply」语义: 若宿主未提供 agentPresets, 桥的 apply 永远不被调用,
+ *    所有 /api/qqbot-settings/* 路由都不会注册(实测表现为全部 404, 面板显示「无账号」)。
+ *    agentPresets 现改为可选: apply 内使用时判空降级(缺失时该路由返回 500 提示)。
+ */
+export const inject = ['settings', 'webServer'];
 
 const NS = 'im-qqbot';
 /**
@@ -99,21 +106,43 @@ function dirOf(u, key) {
 
 const MIME = { jpg: 'image/jpeg', jpeg: 'image/jpeg', png: 'image/png', gif: 'image/gif', webp: 'image/webp', bmp: 'image/bmp' };
 
-/** 注册一条路由, 统一 fence + method 检查 */
+/** 注册一条路由, 统一 fence + method 检查。
+ * ⚠️ 2026-09-10 关键修复: 同 path 只向 dsh webServer register 一次, 多 method 内部按
+ *    req.method 分发。原实现对每个 route() 调用各 register 一次 —— dsh webServer 对同一
+ *    path 重复 register 会抛错, 导致 apply 从该处中断, 其后所有路由全部未注册
+ *    (实测: /group/botplay-events 的 GET+POST 同路径 → 其后 30 个路由缺失,
+ *     dock 聊天视图/群发/审批全挂)。route() 本就接受 method 数组, 这里补按 path 去重。 */
+const routeByPath = new Map();
 function route(ctx, method, path, handler) {
-  const methods = Array.isArray(method) ? method : [method];
-  ctx.effect(() => ctx.webServer.register({
-    kind: 'exact',
-    path,
-    handler: async (req, res) => {
-      if (!isTrusted(req)) return writeJson(res, 403, { error: 'refused: same-origin loopback only' });
-      if (!methods.includes(req.method)) return writeJson(res, 405, { error: 'method not allowed' });
-      try { await handler(req, res); } catch (e) { writeJson(res, 500, { error: String(e?.message ?? e) }); }
-    },
-  }), `qqbot-settings: ${path}`);
+  const methods = (Array.isArray(method) ? method : [method]).map((m) => String(m).toUpperCase());
+  let reg = routeByPath.get(path);
+  if (!reg) {
+    reg = { handlers: new Map() };
+    routeByPath.set(path, reg);
+    ctx.effect(() => ctx.webServer.register({
+      kind: 'exact',
+      path,
+      handler: async (req, res) => {
+        if (!isTrusted(req)) return writeJson(res, 403, { error: 'refused: same-origin loopback only' });
+        const h = reg.handlers.get(String(req.method || '').toUpperCase());
+        if (!h) return writeJson(res, 405, { error: 'method not allowed' });
+        try { await h(req, res); } catch (e) { writeJson(res, 500, { error: String(e?.message ?? e) }); }
+      },
+    }), `qqbot-settings: ${path}`);
+  }
+  for (const m of methods) reg.handlers.set(m, handler);
 }
 
 export function apply(ctx) {
+  // ── 桥装载诊断(2026-09-10 排查路由全 404): 落 ~/.dsh/qqbot-bridge-diag.log ──
+  // 用途: 宿主重启后可确认 apply 是否真的被 cordis 调用(以及当时 ctx 上有哪些服务)。
+  try {
+    const services = ['settings', 'webServer', 'agentPresets'].map((s) => s + '=' + (ctx && ctx[s] ? 'Y' : 'N')).join(' ');
+    appendFileSync(
+      join(homedir(), '.dsh', 'qqbot-bridge-diag.log'),
+      `[${new Date().toISOString()}] bridge apply 被调用 inject=${JSON.stringify(inject)} ${services}\n`,
+    );
+  } catch { /* 诊断失败不影响装载 */ }
   // ── 临时诊断(排查"设置读取失败"): settings 服务可用性 + 已注册命名空间 ──
   route(ctx, 'GET', '/api/qqbot-settings/_debug', async (_req, res) => {
     try {
@@ -253,9 +282,9 @@ export function apply(ctx) {
   /** 解析 patch: 返回 {raw, bots:[{id,start,end,ins,cfg:{appId,appSecret,preset,cwd},disabled}], hasFile}
    *  patch 语义(宿主 dsh-app-boot applyEntryPatches): 顶层 `- id: X` 只能覆盖已存在 id(bundle insert 建的);
    *  新增实例必须 `- insert:` 包装(其下 4 空格 `- id: Y`)。本文件里两种形态都识别。 */
-  function parsePatch() {
+  function parsePatchFrom(rawText) {
     const hasFile = existsSync(PATCH_FILE);
-    const raw = hasFile ? readFileSync(PATCH_FILE, 'utf8') : '';
+    const raw = rawText !== undefined && rawText !== null ? String(rawText) : (hasFile ? readFileSync(PATCH_FILE, 'utf8') : '');
     // 行尾容错: 兼容 CRLF(2026-09-08 曾因 patch 被写成 CRLF 导致整段解析失败)
     const lines = raw.split(/\r?\n/);
     const bots = [];
@@ -280,7 +309,7 @@ export function apply(ctx) {
           }
           j += 1;
         }
-        bots.push({ id, start, end: j, ins: false, cfg, disabled });
+        bots.push({ id, start, end: j, ins: false, cfg, disabled, headLine: start });
         i = j;
       } else if (isTopLine(t) && /^\s*-\s*insert:\s*$/.test(t)) {
         // insert 形态: 找其下 4 空格 `- id: im-qqbot*`
@@ -313,7 +342,7 @@ export function apply(ctx) {
             if (isTopLine(lines[j])) break;
             j += 1;
           }
-          bots.push({ id, start: insStart, end: j, ins: true, cfg, disabled });
+          bots.push({ id, start: insStart, end: j, ins: true, cfg, disabled, headLine: found.line });
           i = j;
         } else {
           i += 1;
@@ -324,6 +353,8 @@ export function apply(ctx) {
     }
     return { raw, hasFile, bots };
   }
+  /** 从磁盘读取并解析(parsePatchFrom 的包装) */
+  function parsePatch() { return parsePatchFrom(undefined); }
 
   /** 渲染一个实例块。主 im-qqbot(bundle 已 insert)→ 顶层覆盖; 新实例 → `- insert:` 包装(4/6/8 缩进) */
   function renderBotBlock(inst) {
@@ -350,47 +381,158 @@ export function apply(ctx) {
     return out.join('\n');
   }
 
+  /** 在已有条目块内只更新指定键，保留原结构(缩进/位置/未知字段如 groupAdmin、dataRoot、name)。
+   *  ⚠️ 2026-09-10 新增: 原实现用 renderBotBlock 整块重建 —— 会把 insert: 下的 im-qqbot-2 提成顶层
+   *  `- id: im-qqbot`(新版无此 entry, 直接让整棵插件树加载失败), 并丢掉 name/settingsNs/historyLimit/
+   *  groupAdmin/dataRoot 等未在渲染里列出的字段。改为原地增量更新后结构不再被破坏。
+   *  ⚠️ 2026-09-10 二次修复: 除更新已存在的键外, 还要**补写缺失的键**(如原本没有 cwd 的实例),
+   *  否则前端填了 cwd 也保存不进去(实测 im-qqbot-3 只更新 3/4 个键)。disabled 走块头层(children of id)。
+   *  @param {string[]} lines 文件全部行(会被原地修改)
+   *  @param {number} start 块首行索引(含, 即 `- id:` 或 `- insert:` 行)
+   *  @param {number} end 块结束行索引(不含)
+   *  @param {Record<string,string>} kv 要写入的键值(值为字符串); 已存在则改, 缺失则按规矩新增
+   *  @returns {number} 实际写入的键数 */
+  function updateKeysInBlock(lines, start, end, kv) {
+    // 块头行: insert 包装时块首是 `- insert:`, 真正的 `- id:` 在下一行
+    let headIdx = start;
+    for (let i = start; i < Math.min(start + 3, end); i += 1) {
+      if (/^\s*-\s*id:/.test(lines[i])) { headIdx = i; break; }
+    }
+    const headIndent = ((lines[headIdx] ?? '').match(/^\s*/) ?? [''])[0].length;
+    const childIndent = headIndent + 2;      // name: / disabled: / config: 的缩进
+
+    const pending = new Map(Object.entries(kv));
+    let touched = 0;
+    // ① 已存在的键: 原地改写(保留原缩进)
+    for (let i = headIdx + 1; i < end && pending.size > 0; i += 1) {
+      const m = /^(\s*)([A-Za-z_][A-Za-z0-9_]*):\s*(.*)$/.exec(lines[i]);
+      if (!m) continue;
+      const key = m[2];
+      if (!pending.has(key)) continue;
+      lines[i] = `${m[1]}${key}: ${pending.get(key)}`;
+      pending.delete(key);
+      touched += 1;
+    }
+    if (pending.size === 0) return touched;
+
+    // ② 缺失的键: 找本条目自己的 `config:` 行(缩进 = childIndent, 避免命中嵌套的 groupAdmin 等)
+    let cfgLine = -1;
+    for (let i = headIdx + 1; i < end; i += 1) {
+      if (new RegExp(`^\\s{${childIndent}}config:\\s*$`).test(lines[i])) { cfgLine = i; break; }
+    }
+    const keyIndent = childIndent + 2;       // config 下子键的缩进
+    const addLines = [];
+    for (const [key, val] of pending) {
+      // disabled 属于条目层(childIndent), 也放这里 —— YAML 不要求键顺序
+      addLines.push(`${' '.repeat(key === 'disabled' ? childIndent : keyIndent)}${key}: ${val}`);
+    }
+    if (cfgLine >= 0) {
+      // 找 config: 之下最后一个同级键(含其子块), 插在后面。
+      // 注意: 同级键的缩进 == keyIndent(不是 >), 用 >= 才能走到最后一个键;
+      //       带子块的键(如 groupAdmin:) 其子行缩进 > keyIndent 也要一并跨过。
+      let scan = cfgLine + 1;
+      let lastLine = cfgLine;
+      while (scan < end) {
+        const blank = lines[scan].trim() === '';
+        const ind = ((lines[scan].match(/^\s*/) ?? [''])[0]).length;
+        if (!blank && ind >= keyIndent) { lastLine = scan; scan += 1; continue; }
+        break;
+      }
+      lines.splice(lastLine + 1, 0, ...addLines);
+    } else {
+      // 没有 config: —— 在块头后补一个 config: 再放键
+      let insertAt = end;
+      for (let i = headIdx + 1; i < end; i += 1) {
+        const ind = ((lines[i].match(/^\s*/) ?? [''])[0]).length;
+        if (lines[i].trim() !== '' && ind <= headIndent && /- /.test(lines[i])) { insertAt = i; break; }
+      }
+      lines.splice(insertAt, 0, `${' '.repeat(childIndent)}config:`, ...addLines);
+    }
+    return touched + addLines.length;
+  }
+
+
   /** 保存实例清单(全量同步; 行级重建, 其它插件行/注释原样保留)
    *  借鉴 dsh-qqbot-panel(2026-09-06): appSecret 空值/掩码(********) = 保留原值,
    *  只有提供全新非掩码值才覆盖 —— 前端只回显掩码, 不会因漏传/未改而误清 secret。
    *  ⚠️ 2026-09-09: dataRoot 同理 —— 前端不编辑它, 保存时必须保留原值,
-   *     否则 accounts/save 会把 patch.yml 里的 dataRoot 覆盖掉(图库路径回退 cwd 的根因)。 */
+   *     否则 accounts/save 会把 patch.yml 里的 dataRoot 覆盖掉(图库路径回退 cwd 的根因)。
+   *  ⚠️ 2026-09-10: 已存在的条目改为"原地只更新字段", 不再整块重建(见 updateKeysInBlock 注释)。 */
   function saveInstances(instances) {
     const { raw, hasFile, bots } = parsePatch();
     if (!hasFile) return { ok: false, error: '找不到 cordis.patch.yml(仅 web profile 支持)' };
     const lines = raw.split('\n');
-    const edits = [];
+    const removals = [];
+    const updates = [];
+    const appends = [];
     const targetIds = new Set(instances.filter((x) => !x.remove).map((x) => String(x.id)));
-    for (const b of bots) {
-      if (!targetIds.has(b.id)) edits.push({ start: b.start, end: b.end, text: null });
+    // 删除: 只删「没被提交的机器人条目」或显式 remove 的条目, 且范围严格限定在该条目自身:
+    //   起点 = 它自己的 `- id:` 行(headLine, 不是包裹它的 `- insert:` 行),
+    //   终点 = 下一个同级机器人条目的 headLine(或该 insert 块结束)。
+    // ⚠️ 2026-09-10 事故一: 原用 { start: b.start }(insert 包装时为 `- insert:` 行) 且 end 取块末,
+    //    导致同一 insert 下的其它插件条目(mcp-chrome)被连带删除。现改为按 headLine 精确切分。
+    // ⚠️ 2026-09-10 事故二: 前端把"空骨架实例"(如用于禁用幽灵 im-qqbot 的 `- id: im-qqbot`
+    //    + disabled: true, appId/appSecret 均为空)过滤掉不提交 → 会被当成"要删除"而误删,
+    //    删掉后下次启动又触发扫码。故: 无凭据(appId/appSecret 皆空)的条目一律保留, 不参与自动删除。
+    const removeIds = new Set(instances.filter((x) => x.remove).map((x) => String(x.id)));
+    const doomed = bots.filter((b) => {
+      if (removeIds.has(b.id)) return true;
+      if (targetIds.has(b.id)) return false;
+      const hasCred = !!(b.cfg?.appId || b.cfg?.appSecret);
+      return hasCred;
+    });
+    for (const b of doomed) {
+      const sameGroup = bots
+        .filter((o) => o !== b && o.ins === b.ins && o.start === b.start && o.headLine > b.headLine)
+        .sort((x, y) => x.headLine - y.headLine);
+      const nextHead = sameGroup.length ? sameGroup[0].headLine : b.end;
+      let tail = nextHead;
+      while (tail > b.headLine + 1 && (lines[tail - 1] ?? '').trim() === '') tail -= 1;
+      removals.push({ start: b.headLine, end: tail });
     }
     for (const inst of instances) {
       if (inst.remove) continue;
-      const t = bots.find((b) => b.id === inst.id);
-      const orig = bots.find((b) => b.id === inst.id);
+      const orig = bots.find((b) => b.id === String(inst.id));
       // 掩码/空 → 保留原 secret(仅当原值存在; 全新账号本就无原值则维持空)
-      if (!inst.appSecret || inst.appSecret === SECRET_MASK) {
-        if (orig && orig.cfg?.appSecret) inst.appSecret = orig.cfg.appSecret;
-        else inst.appSecret = '';
-      }
+      let secret = String(inst.appSecret ?? '');
+      if (!secret || secret === SECRET_MASK) secret = orig?.cfg?.appSecret ? String(orig.cfg.appSecret) : '';
       // 前端不编辑 dataRoot → 保留原值(2026-09-09: 曾因保存覆盖丢失导致图库路径回退 cwd)
-      if (inst.dataRoot === undefined && orig && orig.cfg?.dataRoot) inst.dataRoot = orig.cfg.dataRoot;
-      const blockText = renderBotBlock(inst);
-      if (t) edits.push({ start: t.start, end: t.end, text: blockText });
-      else edits.push({ append: blockText });
+      let dataRoot = inst.dataRoot;
+      if (dataRoot === undefined && orig?.cfg?.dataRoot) dataRoot = orig.cfg.dataRoot;
+
+      if (orig) {
+        const kv = {};
+        if (inst.appId !== undefined) kv.appId = yq(String(inst.appId));
+        if (secret) kv.appSecret = ysec(secret);
+        if (inst.preset !== undefined && String(inst.preset) !== '') kv.preset = yq(String(inst.preset));
+        if (inst.cwd !== undefined && String(inst.cwd) !== '') kv.cwd = yq(String(inst.cwd));
+        if (inst.disabled !== undefined) kv.disabled = inst.disabled ? 'true' : 'false';
+        updates.push({ id: String(inst.id), kv });
+      } else {
+        appends.push(renderBotBlock({ ...inst, appSecret: secret, dataRoot }));
+      }
+    }
+    // 先删块(倒序), 再逐条原地改字段。
+    // ⚠️ 每次更新前重新 parsePatch 取最新下标: splice 过(删除或插入新键)之后,
+    //    之前算好的 start/end 会错位, 曾导致插入落到错误缩进上把 YAML 写坏。
+    for (const r of removals.sort((a, b) => b.start - a.start)) lines.splice(r.start, r.end - r.start);
+    for (const u of updates) {
+      let fresh = null;
+      try {
+        const reparsed = parsePatchFrom(lines.join('\n'));
+        fresh = reparsed.bots.find((b) => b.id === u.id) ?? null;
+      } catch { fresh = null; }
+      if (!fresh) continue;
+      updateKeysInBlock(lines, fresh.start, fresh.end, u.kv);
     }
-    edits.filter((e) => e.start !== undefined).sort((a, b) => b.start - a.start).forEach((e) => {
-      if (e.text === null) lines.splice(e.start, e.end - e.start);
-      else lines.splice(e.start, e.end - e.start, ...e.text.split('\n'));
-    });
     let out = lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
-    const appendParts = edits.filter((e) => e.append).map((e) => e.append);
-    if (appendParts.length) out += (out ? '\n' : '') + appendParts.join('\n') + '\n';
+    if (appends.length) out += (out.trimEnd() ? '\n' : '') + appends.join('\n') + '\n';
     writeFileSync(`${PATCH_FILE}.bak`, raw, 'utf8');
     writeFileSync(PATCH_FILE, out, 'utf8');
     return { ok: true, file: PATCH_FILE, needRestart: true };
   }
 
+
   // 账号列表(多账号: 每条带 settings ns 与数据目录, 供二级 UI 按账号读写)
   // 借鉴 zhengjy01/dsh-qqbot-panel(2026-09-06): appSecret 只回显掩码(不泄露明文),
   // 并带 hasSecret 供前端区分"已保存"与"真空"; 保存时空值/掩码 = 保留原 secret。
@@ -848,6 +990,30 @@ export function apply(ctx) {
   function readPendingJson(cwd) {
     try { return JSON.parse(readFileSync(join(cwd, '.qqbot', 'join-pending.json'), 'utf8') || '{}'); } catch { return {}; }
   }
+  // ── botplay 事件独立文件存储(2026-09-10 M4.3): {dataRoot}/botplay-events.json
+  //    (主人定: 事件配置放工作目录根, 和「表情包」等平级; 曾放 .qqbot 子目录, 读时兼容迁移)
+  function readBotplayEventsFile(cwd) {
+    try {
+      const root = join(cwd, 'botplay-events.json');
+      if (existsSync(root)) return JSON.parse(readFileSync(root, 'utf8') || '{}');
+      const legacy = join(cwd, '.qqbot', 'botplay-events.json');
+      if (existsSync(legacy)) { try { renameSync(legacy, root); } catch { /* 迁移失败继续读旧 */ } return JSON.parse(readFileSync(legacy, 'utf8') || '{}'); }
+      return {};
+    } catch { return {}; }
+  }
+  function writeBotplayEventsFile(cwd, events) {
+    try {
+      const f = join(cwd, 'botplay-events.json');
+      const tmp = f + '.tmp-' + Date.now();
+      writeFileSync(tmp, JSON.stringify({ version: 1, events: Array.isArray(events) ? events : [] }, null, 2), 'utf8');
+      renameSync(tmp, f);
+      return true;
+    } catch { return false; }
+  }
+  // 从 settings 现值取 botplayEvents(迁移/兜底用)
+  function botplayEventsFromSettings(ns) {
+    try { const v = viewOf(ctx.settings, ns); const ev = v && v.value && v.value.botplayEvents; return Array.isArray(ev) ? ev : []; } catch { return []; }
+  }
   const NSQ = (u) => (u.searchParams.get('ns') || '').trim() || undefined;
   const GQ = (u) => (u.searchParams.get('gid') || '').trim();
 
@@ -1156,6 +1322,246 @@ export function apply(ctx) {
     } catch (e) { writeJson(res, 500, { error: String((e && e.message) || e) }); }
   });
 
+  // ── 自定义卡片按钮(2026-09-10 主人要求: 卡片按钮要能写「回文本 / 跳链接 / 执行命令」) ──
+  // client 传结构化 cardButtons=[{label, action:'text'|'cmd'|'url', payload}]。
+  // 这里生成 cardId、把按钮动作写进 {dataRoot}/.qqbot/card-callbacks.json —— 格式与 dist 侧
+  // src/features/card-callback.ts 严格一致(改格式两边都要改); 按钮 data 编 `bpk:<cardId>:<btnId>`:
+  //   action=url  → action.type=0 官方跳转(客户端直接跳, 不走回调)
+  //   其余        → action.type=1 回调 → 点击后 QQ 推 INTERACTION_CREATE → bootstrap 的
+  //                 cardCallbackController 查表执行(text 回文本 / cmd 走命令执行器)
+  function writeCardCallbacks(dataRoot, card) {
+    try {
+      const p = join(dataRoot, '.qqbot', 'card-callbacks.json');
+      mkdirSync(dirname(p), { recursive: true });
+      let f = { version: 1, cards: [] };
+      try { if (existsSync(p)) f = JSON.parse(readFileSync(p, 'utf8')) || f; } catch { f = { version: 1, cards: [] }; }
+      const now = Date.now();
+      const kept = (Array.isArray(f.cards) ? f.cards : []).filter(c => c && c.cardId !== card.cardId && (c.expireAt || 0) > now);
+      kept.push(card);
+      writeFileSync(p, JSON.stringify({ version: 1, cards: kept.slice(-200) }, null, 1), 'utf8');
+    } catch { /* 写失败只影响按钮回调, 不阻断发卡 */ }
+  }
+  function buildCardKeyboardFromPairs(dataRoot, pairs, meta) {
+    const list = (Array.isArray(pairs) ? pairs : []).filter(b => b && b.label).slice(0, 25);
+    if (!list.length) return undefined;
+    const cardId = 'c' + Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
+    const buttons = list.map((b, i) => ({
+      id: 'b' + (i + 1),
+      label: String(b.label).slice(0, 20),
+      action: b.action === 'url' ? 'url' : (b.action === 'cmd' ? 'cmd' : 'text'),
+      payload: String(b.payload == null ? '' : b.payload),
+    }));
+    const rows = buttons.map(b => ({
+      buttons: [{
+        id: b.id,
+        render_data: { label: b.label, style: 1 },
+        action: {
+          type: b.action === 'url' ? 0 : 1, // 0=跳转 1=回调
+          permission: { type: 2 },
+          data: 'bpk:' + cardId + ':' + b.id,
+          unsupport_tips: '请在支持的客户端点击',
+        },
+      }],
+    }));
+    writeCardCallbacks(dataRoot, {
+      cardId,
+      buttons,
+      createdAt: Date.now(),
+      expireAt: Date.now() + 7 * 24 * 3600 * 1000,
+      scope: meta && meta.scope,
+      targetId: meta && meta.targetId,
+    });
+    return { content: { rows } };
+  }
+
+  // ── 自定义 markdown 卡片发送(2026-09-10 主人实测: markdown 嵌网络图+按钮可渲染):
+  //     接收 {ns?, gid | openid, markdown, keyboard?} → 群用 sendGroupCard / 私聊用 sendC2cCard;
+  //     群发走 broadcast/create(type=markdown)。openid 支持为 2026-09-10 主人要求(卡片可选私聊目标)。
+  route(ctx, 'POST', '/api/qqbot-settings/chat/send-card', async (req, res) => {
+    const body = await readJsonBody(req);
+    if (!body || typeof body !== 'object') return writeJson(res, 400, { error: 'bad body' });
+    const gid = String(body.gid || '').trim();
+    const openid = String(body.openid || '').trim();
+    const md = String(body.markdown || '').trim();
+    if (!gid && !openid) return writeJson(res, 400, { error: 'gid 或 openid 必填' });
+    if (!md) return writeJson(res, 400, { error: 'markdown 必填' });
+    if (md.length > 8000) return writeJson(res, 400, { error: 'markdown 过长(最多 8000 字符)' });
+    try {
+      const gc = await groupClientOf(String(body.ns || ''));
+      if (!gc) return writeJson(res, 400, { error: '找不到该账号实例' });
+      // 结构化按钮(新路径) → 生成回调表 + bpk: 键盘; 也兼容旧路径直接给 keyboard
+      let kb = body.keyboard && body.keyboard.content && Array.isArray(body.keyboard.content.rows) ? body.keyboard : undefined;
+      if (!kb && Array.isArray(body.cardButtons) && body.cardButtons.length) {
+        kb = buildCardKeyboardFromPairs(gc.bot.cwd, body.cardButtons, { scope: openid ? 'c2c' : 'group', targetId: openid || gid });
+      }
+      const r = openid
+        ? await gc.client.sendC2cCard(openid, md, kb)
+        : await gc.client.sendGroupCard(gid, md, kb);
+      audit(gc.bot.cwd, { ev: 'chat.send-card', ns: gc.bot.id, gid, openid, mdLen: md.length, kbRows: kb ? kb.content.rows.length : 0, cbButtons: Array.isArray(body.cardButtons) ? body.cardButtons.length : 0, ok: r.ok, code: r.ok ? undefined : (r.err && r.err.code) });
+      writeJson(res, 200, r.ok
+        ? { ok: true, msg: '✅ 卡片已发送' + (openid ? '(私聊)' : '(群)'), id: r.data && r.data.id }
+        : { ok: false, err: r.err });
+    } catch (e) { writeJson(res, 500, { error: String((e && e.message) || e) }); }
+  });
+
+  // ── botplay 事件独立文件存储(M4.3): GET 读 / POST 写, 均按 ns 取 dataRoot ──
+  // ⚠️ 2026-09-10 修复: NSQ 参数是 URL 对象(内部调 u.searchParams.get), 原写法 NSQ(req.url)
+  //    传了字符串 → "Cannot read properties of undefined (reading 'get')" 500。
+  route(ctx, 'GET', '/api/qqbot-settings/group/botplay-events', async (req, res) => {
+    const ns = NSQ(new URL(req.url ?? '/', 'http://x'));
+    const bot = nsBot(ns);
+    if (!bot || !bot.cwd) return writeJson(res, 400, { error: '找不到该账号实例' });
+    const fromFile = readBotplayEventsFile(bot.cwd);
+    let events = Array.isArray(fromFile.events) ? fromFile.events : (Array.isArray(fromFile) ? fromFile : []);
+    // 文件缺失/空 → 迁移 settings 旧数据(botplay 事件曾存 settings.yaml, 2026-09-10 前)
+    if (events.length === 0) {
+      const legacy = botplayEventsFromSettings(bot.ns);
+      if (Array.isArray(legacy) && legacy.length > 0) { writeBotplayEventsFile(bot.cwd, legacy); events = legacy; }
+    }
+    writeJson(res, 200, { ok: true, events, source: 'file' });
+  });
+
+  route(ctx, 'POST', '/api/qqbot-settings/group/botplay-events', async (req, res) => {
+    const body = await readJsonBody(req);
+    if (!body || typeof body !== 'object') return writeJson(res, 400, { error: 'bad body' });
+    const ns = String(body.ns || 'im-qqbot').trim();
+    const bot = nsBot(ns);
+    if (!bot || !bot.cwd) return writeJson(res, 400, { error: '找不到该账号实例' });
+    if (!Array.isArray(body.events)) return writeJson(res, 400, { error: 'events 必须为数组' });
+    const okFile = writeBotplayEventsFile(bot.cwd, body.events);
+    // settings 现值同步清空(2026-09-10: 事件已独立文件, settings 里残留旧数组会与新文件重复/歧义 → 置空)
+    let okSettings = true;
+    try {
+      const cur = viewOf(ctx.settings, bot.ns);
+      const curVal = (cur && cur.value) || {};
+      if (curVal.botplayEvents !== undefined && Array.isArray(curVal.botplayEvents) && curVal.botplayEvents.length > 0) {
+        const patch = Object.assign({}, curVal, { botplayEvents: [] });
+        await ctx.settings.update(bot.ns, patch, (cur && cur.revision) || undefined);
+      }
+    } catch { okSettings = false; }
+    audit(bot.cwd, { ev: 'botplay.events-save', ns: bot.ns, n: body.events.length, okFile, okSettings });
+    writeJson(res, 200, { ok: okFile, msg: okFile ? '✅ 已保存(独立文件, live 热更已生效)' : '写入文件失败' });
+  });
+
+  // ── M3 群发任务队列(2026-09-10): 持久化状态机 draft→queued→sending→done, 二次确认, 可中止/撤回 ──
+  // 数据: {dataRoot}/.qqbot/broadcast-tasks.json(broadcast.ts 管理); 推进由每次 list 请求驱动(串行, 天然限频)。
+  // 路由: broadcast/create(草稿) → broadcast/confirm(二次确认后入队) → broadcast/list(推进+展示) →
+  //       broadcast/cancel(中止) → broadcast/recall(撤回某目标已发消息)。
+  async function broadcastMod() {
+    return import('./dist/features/broadcast.js');
+  }
+
+  // 创建群发草稿 {ns?, type:'text'|'markdown', text, targets:[{scope,peerId,name?}]}
+  route(ctx, 'POST', '/api/qqbot-settings/group/broadcast/create', async (req, res) => {
+    const body = await readJsonBody(req);
+    if (!body || typeof body !== 'object') return writeJson(res, 400, { error: 'bad body' });
+    const text = String(body.text || '').trim();
+    const targets = Array.isArray(body.targets) ? body.targets : [];
+    // 卡片群发(2026-09-10 主人要求): type=card 时 text 为 markdown 正文, 另带 keyboard
+    const wantCard = body.type === 'card';
+    if (!text) return writeJson(res, 400, { error: wantCard ? 'markdown 必填' : 'text 必填' });
+    if (text.length > (wantCard ? 8000 : 2000)) return writeJson(res, 400, { error: wantCard ? 'markdown 过长(最多 8000 字符)' : '文本过长(最多 2000 字符)' });
+    // 卡片群发(2026-09-10 主人要求): type=card 时 text 为 markdown 正文, 另带 keyboard;
+    // 优先用结构化 cardButtons 现生成(回调表+bpk: 键盘, 与 chat/send-card 同一套), 兼容直接给 keyboard
+    let kb = wantCard && body.keyboard && body.keyboard.content && Array.isArray(body.keyboard.content.rows) ? body.keyboard : undefined;
+    if (targets.length === 0) return writeJson(res, 400, { error: 'targets 至少一个(勾选群/私聊)' });
+    if (targets.length > 200) return writeJson(res, 400, { error: '目标太多(最多 200)' });
+    for (const t of targets) {
+      if (!t || (t.scope !== 'group' && t.scope !== 'c2c') || !t.peerId) return writeJson(res, 400, { error: 'targets 每项需 scope(group|c2c)+peerId' });
+    }
+    try {
+      const bot = nsBot(String(body.ns || ''));
+      if (!bot) return writeJson(res, 400, { error: '找不到该账号实例(请先在账号页配置 appId/appSecret)' });
+      // 结构化按钮 → 现生成回调表 + bpk: 键盘(与 chat/send-card 同一套; 群发各目标共用这张表)
+      if (wantCard && !kb && Array.isArray(body.cardButtons) && body.cardButtons.length) {
+        kb = buildCardKeyboardFromPairs(bot.cwd, body.cardButtons, { scope: 'group', targetId: '' });
+      }
+      const bm = await broadcastMod();
+      const task = bm.createTask(bot.cwd, {
+        type: wantCard ? 'card' : (body.type === 'markdown' ? 'markdown' : 'text'),
+        content: text,
+        keyboard: kb,
+        targets: targets.map((t) => ({ scope: t.scope, peerId: t.peerId, name: t.name ? String(t.name) : undefined })),
+        created_by: 'dock',
+      });
+      audit(bot.cwd, { ev: 'group.broadcast.create', ns: bot.id, task_id: task.task_id, targets: targets.length, type: wantCard ? 'card' : 'text' });
+      writeJson(res, 200, { ok: true, task });
+    } catch (e) { writeJson(res, 500, { error: String((e && e.message) || e) }); }
+  });
+
+  // 确认群发(二次确认后调用) {ns?, task_id}
+  route(ctx, 'POST', '/api/qqbot-settings/group/broadcast/confirm', async (req, res) => {
+    const body = await readJsonBody(req);
+    if (!body || typeof body !== 'object') return writeJson(res, 400, { error: 'bad body' });
+    const taskId = String(body.task_id || '');
+    if (!taskId) return writeJson(res, 400, { error: 'task_id 必填' });
+    try {
+      const bot = nsBot(String(body.ns || ''));
+      if (!bot) return writeJson(res, 400, { error: '找不到该账号实例' });
+      const bm = await broadcastMod();
+      const t = bm.confirmTask(bot.cwd, taskId);
+      if (!t) return writeJson(res, 400, { error: '任务不存在' });
+      if (t.state !== 'queued') return writeJson(res, 200, { ok: false, msg: `任务状态为 ${t.state}, 无法确认` });
+      audit(bot.cwd, { ev: 'group.broadcast.confirm', ns: bot.id, task_id: taskId });
+      writeJson(res, 200, { ok: true, task: t });
+    } catch (e) { writeJson(res, 500, { error: String((e && e.message) || e) }); }
+  });
+
+  // 群发任务列表(读时推进一个目标) {ns?}
+  route(ctx, 'GET', '/api/qqbot-settings/group/broadcast/list', async (req, res) => {
+    try {
+      const u = new URL(req.url ?? '/', 'http://x');
+      const bot = nsBot(NSQ(u));
+      if (!bot) return writeJson(res, 400, { error: '找不到该账号实例' });
+      const bm = await broadcastMod();
+      // 推进一步: 找第一个 queued/sending 的任务推进(串行限频)
+      const gc = await groupClientOf(NSQ(u));
+      if (gc) {
+        const tasks = bm.listTasks(bot.cwd);
+        const active = tasks.find((t) => t.state === 'queued' || t.state === 'sending');
+        if (active) await bm.advanceTask(bot.cwd, active.task_id, gc.client);
+      }
+      const after = bm.listTasks(bot.cwd);
+      writeJson(res, 200, { ok: true, tasks: after });
+    } catch (e) { writeJson(res, 500, { error: String((e && e.message) || e) }); }
+  });
+
+  // 中止群发 {ns?, task_id}
+  route(ctx, 'POST', '/api/qqbot-settings/group/broadcast/cancel', async (req, res) => {
+    const body = await readJsonBody(req);
+    if (!body || typeof body !== 'object') return writeJson(res, 400, { error: 'bad body' });
+    const taskId = String(body.task_id || '');
+    if (!taskId) return writeJson(res, 400, { error: 'task_id 必填' });
+    try {
+      const bot = nsBot(String(body.ns || ''));
+      if (!bot) return writeJson(res, 400, { error: '找不到该账号实例' });
+      const bm = await broadcastMod();
+      const t = bm.cancelTask(bot.cwd, taskId, 'dock');
+      if (!t) return writeJson(res, 400, { error: '任务不存在' });
+      audit(bot.cwd, { ev: 'group.broadcast.cancel', ns: bot.id, task_id: taskId });
+      writeJson(res, 200, { ok: true, task: t });
+    } catch (e) { writeJson(res, 500, { error: String((e && e.message) || e) }); }
+  });
+
+  // 撤回群发中某目标已发的消息(2 分钟窗口) {ns?, task_id, peerId}
+  route(ctx, 'POST', '/api/qqbot-settings/group/broadcast/recall', async (req, res) => {
+    const body = await readJsonBody(req);
+    if (!body || typeof body !== 'object') return writeJson(res, 400, { error: 'bad body' });
+    const taskId = String(body.task_id || '');
+    const peerId = String(body.peerId || '');
+    if (!taskId || !peerId) return writeJson(res, 400, { error: 'task_id 与 peerId 必填' });
+    try {
+      const bot = nsBot(String(body.ns || ''));
+      const gc = await groupClientOf(String(body.ns || ''));
+      if (!bot || !gc) return writeJson(res, 400, { error: '找不到该账号实例' });
+      const bm = await broadcastMod();
+      const r = await bm.recallTaskMessage(bot.cwd, taskId, peerId, gc.client);
+      audit(bot.cwd, { ev: 'group.broadcast.recall', ns: bot.id, task_id: taskId, peerId, ok: r.ok });
+      writeJson(res, 200, r);
+    } catch (e) { writeJson(res, 500, { error: String((e && e.message) || e) }); }
+  });
+
+
   // ── 悬浮球「💬 聊天视图」(2026-09-07): 读某 QQ 会话最近的入站/出站消息, 只读不建会话 ──
   // 会话事件结构(宿主 dsh-session): {type, seq, time, data}; user/message 的 data=消息体根(data.content),
   // assistant/message 的 data={turn,step,message:{role,content,…}}。只收这两型:
@@ -1221,10 +1627,19 @@ export function apply(ctx) {
   function chatLocalRawUrl(p) {
     return '/api/qqbot-settings/chat/raw-media?p=' + encodeURIComponent(p);
   }
-  // 附件行/URL 归属类型: 文件名/URL fname 扩展名优先(voice/image/file), 无扩展名看行标签与上下文
-  // 语音上下文(- ASR:/[Voice message])→ voice; 默认 image(QQ 图消息常走 [附件: url] 无扩展名)
+  // 附件行/URL 归属类型: 行内**显式类型标签**优先, 其次文件名/URL fname 扩展名, 最后行标签与上下文
+  // ⚠️ 2026-09-10 根因修复(主人实测: "视频还是附件形式, 图片也变成附件了"):
+  //   QQ 群聊里图片/视频的 content_type 实测可能是 `'file'`(不是 image/jpeg) —— 官方取值表:
+  //   voice / image/jpeg|png|gif / video/mp4 / file(=群文件)。端上(media-kind.ts)已按
+  //   MIME→扩展名→宽高→URL 特征(appid/orgfmt) 推断真实类型, 并以 `- Image: 名 → url` 注入 Layer 4。
+  //   这里必须认这些**显式前缀**, 否则 `- File:` 会把图片/视频判成 📎 附件(图片不显示、视频不能播)。
   function chatAttachmentKind(line, hasVoiceCtx, defaultKind) {
     const l = String(line || '');
+    // ① 显式类型标签(我方注入格式, 最权威)
+    if (/^-\s*(?:Image|图片)\s*:/i.test(l) || /^\[(?:Image|图片)\s*:/i.test(l)) return 'image';
+    if (/^-\s*(?:Video|视频)\s*:/i.test(l) || /^\[(?:Video|视频)\s*:/i.test(l)) return 'video';
+    if (/^-\s*(?:Voice|语音|音频)\s*:/i.test(l) || /^\[(?:Voice|语音|音频)\s*:/i.test(l)) return 'voice';
+    if (/^-\s*(?:File|文件)\s*:/i.test(l) || /^\[(?:File|文件)\s*:/i.test(l)) return 'file';
     // 从行内或 URL fname 参数取文件名
     let name = '';
     const fm = l.match(/fname=([^&\s]+)/);
@@ -1279,8 +1694,9 @@ export function apply(ctx) {
         const lk = chatLocalExtKind(lp[1]);
         if (lk) { images.push({ url: chatLocalRawUrl(lp[1]), kind: lk }); continue; }
       }
-      // 附件描述行: "- Attachment URLs: …" / "- File: …" / "[附件: …]" / "[文件: …]" / "[图片: …]" / "[Attachment: name -> …]"
-      if (/^-\s*Attachment URLs:/i.test(raw) || /^-\s*File:/i.test(raw) || /^\[(图片|附件|文件|语音|视频|音频):/i.test(raw) || /^\[Attachment:|^\[File:/i.test(raw)) {
+      // 附件描述行: "- Image: …" / "- Video: …" / "- Voice: …" / "- File: …" / "- Attachment URLs: …"
+      //            / "[图片: …]" / "[视频: …]" / "[附件: …]" / "[Attachment: name -> …]" / Layer1 的英文标签行
+      if (/^-\s*Attachment URLs:/i.test(raw) || /^-\s*(Image|Video|Voice|File)s?:/i.test(raw) || /^\[(图片|附件|文件|语音|视频|音频):/i.test(raw) || /^\[(Attachment|File|Image|Video):/i.test(raw)) {
         const urls = raw.match(QQ_URL_RE) || [];
         let got = 0;
         for (const u of urls) {
@@ -1290,6 +1706,10 @@ export function apply(ctx) {
           else if (QQ_MEDIA_RE.test(u)) { images.push({ url: u, kind: k }); got++; }
         }
         if (!got) {
+          // Layer 1 的英文描述行(`[Image: 名 800×600]` / `[Video: 名]` / `[File: 名 (1.2MB)]`)不含 URL,
+          // 其媒体由 Layer 4 的 `- Image:/- Video:/- File:` 行承载 → 直接丢弃, 避免显示成
+          // `📎 [Image: 名 800×600]` 这种丑文本(主人 2026-09-10 实测反馈)。
+          if (/^\[(Image|Video|File):/i.test(raw)) continue;
           // 无 URL 的 File/附件描述行(如 "- File: a.zip (3.0MB)")→ 保留可读文本, 不给空占位
           const desc = raw
             .replace(/^-\s*File:\s*/i, '').replace(/^\[File:\s*/i, '')
@@ -1343,6 +1763,12 @@ export function apply(ctx) {
   function chatSplitHistoryBlock(body) {
     const out = [];
     let cur = null;
+    // ⚠️ 2026-09-10 修复(主人实测: 当前消息的语音被挂到了上一条历史消息上):
+    //   Layer 4 的媒体元数据行(`- Attachment URLs:` / `- File:` …)排在 `[Current message]` 之后、
+    //   带昵称的当前消息之前 —— 原逻辑"无昵称行并入上一个气泡"会把它算到上一条历史消息头上。
+    //   改为: 这类 `- ` 开头的元数据行先暂存(pendingMeta), 等下一个带昵称的消息出现时归属它
+    //   (即"元数据行属于它下面那条消息"), 找不到归属时才丢弃。
+    let pendingMeta = [];
     const flush = () => {
       if (cur) {
         const t = cur.lines.join('\n').trim();
@@ -1355,9 +1781,12 @@ export function apply(ctx) {
       if (!s) continue;
       if (/^\[Chat history begins\]$/.test(s) || /^\[Chat history ends\]$/.test(s) || /^\[Current message\]$/.test(s) || /^\[当前时间/.test(s)) continue;
       if (/^\[系统提示\]/.test(s)) { flush(); return out; } // 系统注入段, 之后都不属于群聊内容
+      // 媒体元数据行: 暂存, 等归属给下面那条带昵称的消息
+      // (Layer 4 现输出 `- Image:/- Video:/- Voice:/- File:` 单数前缀, 此处一并覆盖)
+      if (/^-\s*(Attachment URLs|Files?|Images?|ASR|Voices?|Videos?)\s*[:：]/i.test(s)) { pendingMeta.push(s); continue; }
       const m = s.match(/^\[([^\]\n]*?)\s*\([A-Za-z0-9_-]{6,}\)\](.*)$/);
-      if (m) { flush(); cur = { sender: m[1].trim(), lines: [m[2].trim()].filter(Boolean) }; }
-      else { if (cur) cur.lines.push(s); else { flush(); cur = { sender: '', lines: [s] }; } }
+      if (m) { flush(); cur = { sender: m[1].trim(), lines: [m[2].trim(), ...pendingMeta].filter(Boolean) }; pendingMeta = []; }
+      else { if (cur) cur.lines.push(...pendingMeta, s); else { flush(); cur = { sender: '', lines: [...pendingMeta, s] }; } pendingMeta = []; }
     }
     flush();
     return out;
@@ -1376,6 +1805,15 @@ export function apply(ctx) {
     const mm = chatSplitMedia(chatDisplayClean(b, nameByMid));
     return { sender, mm };
   }
+  // 🔍 临时诊断(2026-09-10): 把含媒体标记的入站原文落盘到 ~/.dsh/qqbot-chat-raw.jsonl ——
+  //    用于核对 Layer1/Layer4 实际注入格式与 dock 解析结果(主人验收通过后删除本函数与调用)。
+  function chatRawDiag(raw0) {
+    try {
+      const s = String(raw0 || '');
+      if (!/(Image|Video|Voice|File|Attachment|图片|视频|语音|文件|附件)|multimedia\.nt\.qq\.com|qpic\.cn/i.test(s)) return;
+      appendFileSync(join(homedir(), '.dsh', 'qqbot-chat-raw.jsonl'), JSON.stringify({ t: Date.now(), body: s.slice(0, 5000) }) + '\n');
+    } catch { /* 诊断失败不影响主流程 */ }
+  }
   // 解码一条会话事件为聊天条目(群打包会展开成多条); 非聊天事件/噪声返回 null
   function chatDecodeEvent(ev, scope, nameByMid, fallbackSender) {
     if (!ev || typeof ev.type !== 'string') return null;
@@ -1386,6 +1824,7 @@ export function apply(ctx) {
       if (src.kind === 'plugin') return null; // runtime context / 系统注入等, 非真人对话
       const raw0 = chatTextOf(data.content);
       if (!raw0) return null;
+      chatRawDiag(raw0);
       const raw = chatPeelTimeHead(raw0);
       const isRelay = /^用户代你发送: /.test(raw);
       // 后台任务/面板大文件完成通知([系统] 后台任务…)→ 显示为 bot 侧气泡并打来源标; 其余系统注入滤掉
@@ -1499,7 +1938,22 @@ export function apply(ctx) {
         if (low === 0) { reachedEnd = true; break; }
         high = low - 1;
       }
-      items.reverse(); // 升序(旧→新)
+      // ⚠️ 2026-09-10 修复(主人实测"同一批次的历史消息会倒序"):
+      //   原为 items.reverse() —— 倒扫时同一打包块([Chat history begins]…[Chat history ends])
+      //   拆出的多条共用同一个 ev.seq, 块内本就是旧→新; 整体 reverse 会把"块内顺序"也翻反,
+      //   表现为"整批之间顺序对、批内倒序"。
+      //   改为: 按 seq 分块 → 块间倒序(旧→新), 块内保持原顺序。
+      {
+        const blocks = [];
+        for (const it of items) {
+          const last = blocks[blocks.length - 1];
+          if (last && last.seq === it.seq) last.arr.push(it);
+          else blocks.push({ seq: it.seq, arr: [it] });
+        }
+        blocks.reverse();
+        items.length = 0;
+        for (const b of blocks) for (const one of b.arr) items.push(one);
+      }
       // QQ 媒体域的语音 URL → 经 /chat/voice-play 转 mp3 播放(浏览器解不了 SILK)
       for (const it of items) {
         if (!Array.isArray(it.images)) continue;
@@ -2010,4 +2464,44 @@ const WHY_MAP = { busy: '目标会话回合活跃,已等待至回合结束仍超
     } catch (e) { writeJson(res, 500, { error: String((e && e.message) || e) }); }
   });
 
+  // ── 🚀 群发任务「后台自动推进」(2026-09-10 修: 原设计靠 client 每次 list 驱动, 页面不动就永久卡 queued) ──
+  // 每 5s 扫全部实例, 有 queued/sending 任务就推进一步(串行 → 天然限频); 单实例失败不影响其他实例。
+  try {
+    const BC_TICK_MS = 5000;
+    let bcTickRunning = false; // 定时器自身防重入: 上一轮未跑完不叠加(2026-09-10)
+    const bcTick = async () => {
+      if (bcTickRunning) return;
+      bcTickRunning = true;
+      try {
+      let bots = [];
+      try { bots = parsePatch().bots || []; } catch { return; }
+      for (const b of bots) {
+        try {
+          if (b.disabled) continue;
+          const bot = nsBot(b.id);
+          if (!bot || !bot.cwd) continue;
+          const bm = await broadcastMod();
+          const tasks = bm.listTasks(bot.cwd);
+          const active = tasks.find((t) => t.state === 'queued' || t.state === 'sending');
+          if (!active) continue;
+          const gc = await groupClientOf(b.id);
+          if (!gc) continue;
+          await bm.advanceTask(bot.cwd, active.task_id, gc.client);
+          audit(bot.cwd, { ev: 'group.broadcast.auto-advance', ns: b.id, task_id: active.task_id });
+        } catch (e) {
+          try {
+            const bot2 = nsBot(b.id);
+            if (bot2 && bot2.cwd) audit(bot2.cwd, { ev: 'group.broadcast.auto-advance-failed', ns: b.id, error: String((e && e.message) || e) });
+          } catch { /* ignore */ }
+        }
+      }
+      } finally { bcTickRunning = false; }
+    };
+    ctx.effect(() => {
+      const timer = setInterval(() => { bcTick().catch(() => {}); }, BC_TICK_MS);
+      timer.unref?.();
+      return () => { try { clearInterval(timer); } catch { /* ignore */ } };
+    }, 'qqbot-settings: 群发任务后台自动推进');
+  } catch { /* 定时器失败不影响插件 */ }
+
 }