@zxh126/pi-qqbot 2.3.0 → 2.4.0

package/index.ts

@@ -1,1571 +1,1856 @@
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { defineTool } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-import { loadAccounts, pinnedAccountName, type QQBotAccount, type QQBotConfig } from "./config";
-import {
-  REST_BASE_PROD,
-  REST_BASE_SANDBOX,
-  INTENT_GROUP_AND_C2C,
-  PASSIVE_WINDOW_MS,
-  APPROVAL_TIMEOUT_MS,
-  DISPATCH_RETRY_MS,
-  CANCEL_SETTLE_GRACE_MS,
-  DEFAULT_ATTACHMENT_MAX_BYTES,
-  DEFAULT_ATTACHMENT_MAX_FILES,
-  DEFAULT_ATTACHMENT_MAX_PER_MESSAGE,
-  DEFAULT_ATTACHMENT_RETENTION_HOURS,
-  DEFAULT_SEND_MAX_BYTES,
-} from "./constants";
-import {
-  defaultAttachmentDir,
-  renderAttachmentAck,
-  renderAttachmentFailureLines,
-  renderAttachmentLines,
-  saveIncoming,
-  sweepAttachmentDir,
-  type AttachmentConfig,
-} from "./attachment";
-import {
-  explainUploadError,
-  mediaKindLabel,
-  uploadRichMedia,
-} from "./qq/upload";
-import { log, configureLog } from "./logger";
-import { claimAny, startClaimRetry, reserveBeforeRelease, readOwner, type Claim } from "./lock";
-import { AuthManager } from "./qq/auth";
-import { QQApi } from "./qq/api";
-import { createGatewayUrlFetcher, QQGateway, QQMessage } from "./qq/gateway";
-import { Approver } from "./approver";
-import { parsePickIndex, pickerExpired, routeSlash, runBridge, type PickerState } from "./slash";
-import { agoLabel, MessageQueue, previewText, type QueuedJob } from "./queue";
-import { ProgressTracker } from "./progress";
-import {
-  buildLocalHandoffNotice,
-  buildRemoteGuidelines,
-  buildRemoteNotice,
-  LOCAL_HANDOFF_SECTION,
-  REMOTE_NOTICE_SECTION,
-  resolveRemoteConfig,
-} from "./remote";
-import { redactSecrets } from "./redact";
-import { ReplyBuffer } from "./stream-buffer";
-import { splitText } from "./util/chunk";
-
-/** 发送本机文件的工具名 */
-const QQ_SEND_FILE_TOOL = "qq_send_file";
-/** 外发文件必须审批：不受配置 approve.tools 影响，也不吃「以后都同意」/会话内记忆 */
-const FORCE_APPROVAL_TOOLS = new Set<string>([QQ_SEND_FILE_TOOL]);
-
-interface State {
-  cfg: QQBotConfig | null;
-  /** 本进程当前服务的 QQ bot（自动抢占的结果）；未接入则为 null */
-  account: { name: string; appId: string } | null;
-  /** 本进程的候选 bot（按配置顺序），待命时用它重扫 */
-  candidates: { name: string; appId: string }[];
-  /** 首条回执前缀（接入成功 / 换进程接管时告知用户当前 bot 与工作目录） */
-  claimNote: string | null;
-  api: QQApi | null;
-  approver: Approver;
-  gateway: QQGateway | null;
-  currentOpenid: string | null;
-  replyBuffer: ReplyBuffer;
-  releaseLock: (() => Promise<void>) | null;
-  stopRetry: (() => void) | null;
-  passiveRefs: Map<string, { msgId: string; receivedAt: number }>;
-  busy: boolean;
-  /** 当前 run 的上下文（用来 abort）；run 结束或取消后清空 */
-  ctx: ExtensionContext | null;
-  /** 最近一条 QQ 消息的发送者：桥接命令用它回执 */
-  lastOpenid: string | null;
-  /** 待选择列表（/tree、/fork、/resume 发出后的编号等待状态） */
-  picker: PickerState | null;
-  /** 发出列表的 QQ 用户：只有他能回编号 */
-  pickerOwner: string | null;
-  /** /qq 桥接命令的回执通道（每次收到 QQ 消息时刷新） */
-  bridgeReply: ((text: string) => void) | null;
-  /** 本轮已被用户取消：settle 时丢弃半截回复 */
-  cancelled: boolean;
-  /** 忙碌时收到的任务：当前任务 settle 后逐条执行 */
-  queue: MessageQueue;
-  /** 正在出队派发（防 settled / 重试竞态下重复派发） */
-  dispatching: boolean;
-  /** 当前派发的任务已经真的启动了 run（agent_start 过）：此时报错不重试，避免重复执行 */
-  runStarted: boolean;
-  /** /cancel 之后等 agent_settled 的兜底定时器 */
-  cancelTimer: ReturnType<typeof setTimeout> | null;
-  /** 任务进度摘要 */
-  progress: ProgressTracker;
-  /** 自动推送进度的定时器 */
-  progressTimer: ReturnType<typeof setInterval> | null;
-  /** 推送失败后暂停自动推送，直到用户主动询问 */
-  progressPaused: boolean;
-  /** 用户手动暂停自动推送（本会话有效：跨 run 保留，/progress on 恢复） */
-  progressMuted: boolean;
-  /** 等审批期间暂缓自动进度推送（避免把审批消息顶走）；审批处理完自动恢复 */
-  progressHeldForApproval: boolean;
-  /** 本会话是否已给 pi 注入过「远程用户」提醒（每会话一次，压缩后重新注入） */
-  remoteNotified: boolean;
-  /** 上一轮 run 的来源：null = 还没跑过 */
-  lastRunOrigin: "qq" | "local" | null;
-  /** 本机在 TUI 接管了对话，等下一轮 run 开跑时更正「远程前提作废」 */
-  localHandoffPending: boolean;
-  /** 最终答案发送失败时缓存，下一条消息时补发 */
-  undelivered: { openid: string; text: string } | null;
-  /** 附件下载 401/403 时重试用的凭据（接入后由 applyClaim 注入） */
-  getToken: (() => Promise<string>) | null;
-  /** 仅测试用：替换附件落盘时的 fetch */
-  attachmentFetch: typeof fetch | null;
-  /** 当前 bot 的 REST 基址（发文件用） */
-  restBase: string | null;
-}
-
-/** 扩展运行所需的状态（导出只为测试用） */
-export function createInitialState(): State {
-  return {
-    cfg: null,
-    api: null,
-    approver: new Approver(APPROVAL_TIMEOUT_MS),
-    gateway: null,
-    currentOpenid: null,
-    replyBuffer: new ReplyBuffer(),
-    releaseLock: null,
-    stopRetry: null,
-    passiveRefs: new Map(),
-    busy: false,
-    ctx: null,
-    lastOpenid: null,
-    picker: null,
-    pickerOwner: null,
-    bridgeReply: null,
-    cancelled: false,
-    queue: new MessageQueue(),
-    dispatching: false,
-    runStarted: false,
-    cancelTimer: null,
-    progress: new ProgressTracker(),
-    progressTimer: null,
-    progressPaused: false,
-    progressMuted: false,
-    progressHeldForApproval: false,
-    remoteNotified: false,
-    lastRunOrigin: null,
-    localHandoffPending: false,
-    undelivered: null,
-    getToken: null,
-    attachmentFetch: null,
-    restBase: null,
-    account: null,
-    candidates: [],
-    claimNote: null,
-  };
-}
-
-export default function (
-  pi: ExtensionAPI,
-  /** 仅测试用：注入状态，让事件处理器与 handleMessage 共享同一份状态 */
-  options?: {
-    state?: State;
-    /** 仅测试用：不真连 QQ 网关（避免单测打网络），其余流程（抢锁/身份/提示）照常 */
-    disableGateway?: boolean;
-    /** 仅测试用：替换「抢到锁后验凭据」的实现（默认真的去换 access_token） */
-    verifyCredentials?: (account: QQBotAccount) => Promise<AuthManager>;
-  },
-) {
-  const state: State = options?.state ?? createInitialState();
-
-  // ---- 事件：本机用户在 TUI 直接打字（source=interactive）→ 记一笔「可能接管」----
-  // 只记待定，真正注入要等下一轮 run 开跑（before_agent_start）。
-  // 本扩展自己的 sendUserMessage 是 source=extension，不会走到这里；QQ run 跑着时接管不处理。
-  pi.on("input", (event) => {
-    const ev = event as any;
-    if (ev?.source !== "interactive") return;
-    if (state.busy) return;
-    if (state.lastRunOrigin !== "qq") return;
-    if (state.localHandoffPending) return;
-    state.localHandoffPending = true;
-    log("[remote] 检测到本机 TUI 输入，下一轮按「本机用户」前提处理");
-  });
-
-  // ---- 事件：真正开始一轮 run 时，按「来自 QQ 还是本机」准备系统提示 ----
-  // 不在扩展载入时注入，也不在本机 TUI 自己对话时注入：只有 startJob() 派发的
-  // QQ 消息真的开跑（state.busy + currentOpenid）才会走到这里。
-  pi.on("before_agent_start", (event) => {
-    const cfg = state.cfg;
-    if (!cfg) return;
-    if ((event as any).messageType !== "user") return;
-    const options = (event as any).systemPromptOptions;
-    if (!options || typeof options !== "object") return;
-
-    // 本扩展派发的 QQ 消息
-    if (state.busy && state.currentOpenid) {
-      const remote = resolveRemoteConfig(cfg);
-      if (remote.guidelines && Array.isArray(options.promptGuidelines)) {
-        const guidelines = buildRemoteGuidelines();
-        // 同一次 run 可能重复触发（如压缩后重试），别叠加两遍
-        if (!options.promptGuidelines.includes(guidelines[0])) options.promptGuidelines.push(...guidelines);
-      }
-      if (remote.notice && !state.remoteNotified) {
-        state.remoteNotified = true;
-        // 放进系统提示的 section：排在用户消息之前，模型不会把它当成要回复的消息；
-        // 只在本轮生效，操作规则由 guidelines 继续带在后续每一轮。
-        options.sections = { ...(options.sections ?? {}), [REMOTE_NOTICE_SECTION]: buildRemoteNotice(remote) };
-        log("[remote] 首次向 pi 交付 QQ 消息，已注入远程上下文说明（系统提示 section）");
-      }
-      // 又轮到 QQ 了：刚才的本机接管待定作废
-      state.localHandoffPending = false;
-      state.lastRunOrigin = "qq";
-      return;
-    }
-
-    // 本机 TUI/CLI 直接开跑：上一轮是 QQ 的话，更正一次「远程前提作废」
-    const handoff = state.localHandoffPending;
-    state.localHandoffPending = false;
-    state.lastRunOrigin = "local";
-    if (!handoff) return;
-    options.sections = { ...(options.sections ?? {}), [LOCAL_HANDOFF_SECTION]: buildLocalHandoffNotice() };
-    log("[remote] 本机接管本轮对话，已注入「远程前提作废」更正");
-  });
-
-  // ---- 事件：run 开始，记住 ctx（取消指令要调用 ctx.abort()）----
-  pi.on("agent_start", (_event, ctx) => {
-    state.ctx = ctx;
-    state.cancelled = false;
-    state.runStarted = true;
-    clearCancelTimer(state);
-    state.progress.start();
-    state.progressPaused = false;
-    state.progressHeldForApproval = false;
-    startProgressTimer(pi, state);
-  });
-
-  // ---- 事件：累积 assistant 文本 ----
-  pi.on("message_update", (event) => {
-    const ev = event.assistantMessageEvent as any;
-    if (ev?.type === "text_delta") {
-      const delta = ev.delta ?? ev.text ?? "";
-      state.replyBuffer.append(delta);
-      state.progress.appendText(delta);
-    }
-  });
-
-  // ---- 事件：进度统计（工具/轮次/用量）----
-  pi.on("tool_execution_start", (event) => {
-    const ev = event as any;
-    state.progress.toolStart(ev.toolCallId, ev.toolName, ev.args);
-  });
-
-  pi.on("tool_execution_end", (event) => {
-    const ev = event as any;
-    state.progress.toolEnd(ev.toolCallId, ev.toolName, ev.isError === true, ev.durationMs);
-  });
-
-  pi.on("turn_end", () => {
-    state.progress.turn();
-  });
-
-  pi.on("message_end", (event) => {
-    const message = (event as any).message;
-    if (message?.role === "assistant") state.progress.addUsage(message.usage);
-  });
-
-  // ---- 事件：run 结束，发回复，然后接着跑队列里的下一条 ----
-  pi.on("agent_settled", async () => {
-    clearCancelTimer(state);
-    stopProgressTimer(state);
-    state.progress.stop();
-    const cancelled = state.cancelled;
-    const text = state.replyBuffer.take();
-    const openid = state.currentOpenid;
-    state.currentOpenid = null;
-    state.busy = false;
-    state.ctx = null;
-    state.cancelled = false;
-    state.runStarted = false;
-    if (cancelled) {
-      log("[reply] 本轮已被取消，丢弃半截回复（长度", text.length, "）");
-    } else if (text && openid && state.api) {
-      log("[reply] agent_settled，回复 openid=", openid, "text=", text.slice(0, 80));
-      let delivered = true;
-      for (const chunk of splitText(text)) {
-        await state.api.sendC2C(openid, chunk).catch((e) => {
-          delivered = false;
-          log("[reply] 发送失败:", String(e));
-        });
-      }
-      if (!delivered) {
-        // 配额耗尽等情况：缓存下来，用户下次发消息时补发
-        state.undelivered = { openid, text };
-        log("[reply] 最终答案发送失败，已缓存待补发（openid=", openid, "len=", text.length, "）");
-      }
-    }
-    // 本轮结束：取队列里的下一条继续执行（不 await，避免卡住 settled 的派发阶段）
-    drainQueue(pi, state);
-  });
-
-  // ---- 事件：tool_call 审批 ----
-  pi.on("tool_call", async (event) => {
-    const openid = state.currentOpenid;
-    if (!openid || !state.api || !state.cfg) return; // 无 QQ 上下文，放行
-    const ev = event as any;
-    const toolName: string = ev.toolName ?? "tool";
-    const cfg = state.cfg;
-
-    // 判断是否需要审批：配置的 tools 列表 + destructiveHint 兑底 + 强制审批工具（外发文件）
-    const allTools = (pi.getAllTools() ?? []) as any[];
-    const toolMeta = allTools.find((t) => t.name === toolName);
-    const destructive = toolMeta?.annotations?.destructiveHint === true;
-    const forced = FORCE_APPROVAL_TOOLS.has(toolName);
-    const needsApproval = forced || cfg.approve.tools.includes(toolName) || destructive;
-    if (!needsApproval) return; // 放行
-
-    // 强制审批的工具（发送文件）每次都问：不吃「以后都同意」，也不吃会话内记住的决策
-    if (!forced) {
-      // 会话级自动同意（用户回复过「以后都同意」）：本会话内直接放行，不落盘、不跨会话
-      if (state.approver.autoAllowed) {
-        log("[approve] 自动同意放行:", toolName);
-        return;
-      }
-
-      // 会话内已记住的决策
-      const remembered = cfg.approve.remember ? state.approver.isRemembered(toolName) : undefined;
-      if (remembered === "allow") return; // 已记住放行
-      if (remembered === "block") return { block: true, reason: `QQ 用户已拒绝 ${toolName}` };
-      if (remembered === "terminate") return { block: true, terminate: true, reason: "已停止" };
-    }
-
-    const summary = summarizeTool(ev);
-    log("[approve] 工具需要审批:", summary);
-    const { seq, done } = state.approver.register(summary, () => {
-      // 超时通知
-      state.api?.sendC2C(openid, `审批 #${seq} 已超时，已自动拒绝。`).catch(() => {});
-    });
-    await state.api
-      .sendC2C(openid, state.approver.render(seq, { strict: forced }))
-      .catch(() => {});
-    const decision = await done;
-
-    if (decision === "allow") {
-      if (!forced && cfg.approve.remember) state.approver.remember(toolName, "allow");
-      log("[approve] 用户批准 #", seq);
-      return;
-    }
-    if (decision === "terminate") {
-      log("[approve] 用户停止");
-      return { block: true, terminate: true, reason: "QQ 用户停止" };
-    }
-    if (decision === "timeout") {
-      // 超时不写 remember：一次没回复不该永久封死该工具
-      log("[approve] 审批超时 #", seq);
-      return { block: true, reason: `QQ 审批超时（#${seq}）：${summary}` };
-    }
-    // block（用户显式拒绝）
-    if (!forced && cfg.approve.remember) state.approver.remember(toolName, "block");
-    log("[approve] 用户拒绝 #", seq);
-    return { block: true, reason: `QQ 用户拒绝了 ${summary}` };
-  });
-
-  // ---- 事件：session_start 选/抢 qqbot + 启动网关 ----
-  pi.on("session_start", async (event) => {
-    const { accounts, errors } = loadAccounts();
-    for (const message of errors) log("[setup] 配置问题:", message);
-    if (accounts.length === 0) {
-      log("[setup] 未配置 QQ bot（或配置不可用），插件未启用");
-      return;
-    }
-
-    // 会话重建（/reload、/new…）时优先沿用自己的 bot：上一轮释放前写了 owner 记录
-    const pin = pinnedAccountName();
-    const pool: QQBotAccount[] = pin
-      ? accounts.filter((a) => a.name === pin || a.appId === pin)
-      : accounts;
-    if (pool.length === 0) {
-      log("[setup] PI_QQBOT_ACCOUNT=", pin, "不在配置里（可选:", accounts.map((a) => a.name).join(", "), "），插件未启用");
-      return;
-    }
-    state.candidates = pool.map((a) => ({ name: a.name, appId: a.appId }));
-
-    const ownPid = process.pid;
-    const preferredAppId = state.candidates
-      .map((c) => readOwner(c.appId))
-      .find((owner) => owner?.pid === ownPid)?.appId;
-
-    // 新会话：清空 remember 记忆与自动同意开关（自动同意只在当前会话有效）
-    state.approver.reset();
-    // 远程上下文提醒同样只在本会话提醒一次
-    state.remoteNotified = false;
-    // 「QQ ↔ 本机」的来源切换状态也随会话重置
-    state.lastRunOrigin = null;
-    state.localHandoffPending = false;
-    // 手动暂停的自动汇报同样只在本会话有效
-    state.progressMuted = false;
-    state.progressPaused = false;
-    state.queue.clear();
-
-    // 凭据不可用的 bot 在本次会话内不再尝试（配置在 session_start 读取，改完 /reload 才生效）
-    const unusable = new Set<string>();
-    const verifyAccount =
-      options?.verifyCredentials ??
-      (async (account: QQBotAccount) => {
-        const auth = new AuthManager(account.appId, account.config.appSecret);
-        await auth.getToken(); // 抢到锁之后先验凭据，失败就不占着这个槽位
-        return auth;
-      });
-
-    const applyClaim = (claim: Claim, account: QQBotAccount, auth: AuthManager) => {
-      const cfg = account.config;
-      state.cfg = cfg;
-      state.account = { name: account.name, appId: account.appId };
-      state.releaseLock = claim.release;
-      // 只有一个 bot（含 v1 旧配置）→ 继续写旧文件名，升级后日志不断线
-      configureLog(accounts.length === 1 ? null : account.name);
-      state.queue.setLimit(cfg.queue.max);
-      log(
-        "[setup] 配置已加载 bot=",
-        `"${account.name}"`,
-        "appId=",
-        account.appId,
-        "sandbox=",
-        cfg.sandbox,
-        "queue.max=",
-        cfg.queue.max,
-        "reason=",
-        (event as any)?.reason ?? "startup",
-      );
-
-      // 提示：接入成功 / 换进程接管（后者一定要带工作目录）
-      const cwd = process.cwd();
-      if (claim.takeover && claim.previous) {
-        log(
-          "[lock] qqbot",
-          `"${account.name}"`,
-          "换进程接管: pid",
-          claim.previous.pid,
-          "→",
-          process.pid,
-          "· cwd",
-          claim.previous.cwd || "?",
-          "→",
-          cwd,
-        );
-        state.claimNote = `（qqbot「${account.name}」已由新实例接管 · 当前工作目录 ${cwd}）`;
-      } else if (claim.reclaimed) {
-        log("[lock] 重新接入自己的 qqbot（同进程会话重建）");
-      } else {
-        log("[lock] 接入 qqbot", `"${account.name}"`, `(${account.appId})`, "· cwd=", cwd, "· pid=", process.pid);
-        state.claimNote = `（已接入 qqbot「${account.name}」）`;
-      }
-
-      const restBase = cfg.sandbox ? REST_BASE_SANDBOX : REST_BASE_PROD;
-      const api = new QQApi({ restBase, getToken: () => auth.getToken() });
-      state.api = api;
-      state.getToken = () => auth.getToken();
-      state.restBase = restBase;
-
-      // 顺手清掉上一轮留下的临时附件（失败不影响启动）
-      const attCfg = attachmentConfig(cfg);
-      if (attCfg.enabled) {
-        const attDir = attCfg.dir || defaultAttachmentDir(cfg.appId);
-        void sweepAttachmentDir(attDir, {
-          retentionHours: attCfg.retentionHours,
-          maxFiles: attCfg.maxFiles,
-        })
-          .then((r) => {
-            if (r.removed > 0) log("[attachment] 清理临时附件", r.removed, "个", `(dir=${attDir})`);
-          })
-          .catch((e) => log("[attachment] 清理失败:", String(e).slice(0, 160)));
-      }
-
-      if (options?.disableGateway) {
-        log("[setup] 测试模式：跳过 QQ 网关");
-        return;
-      }
-      const gateway = new QQGateway({
-        getGatewayUrl: createGatewayUrlFetcher(restBase, () => auth.getToken()),
-        getToken: () => auth.getToken(),
-        intents: INTENT_GROUP_AND_C2C,
-        connected: () => {},
-        disconnected: () => {},
-        message: (msg) => handleMessage(pi, state, api, state.cfg ?? cfg, msg),
-      });
-      state.gateway = gateway;
-      log("[lock] 启动 QQ 网关");
-      gateway.start();
-    };
-
-    // 抢一个、验一下凭据、验不过就放锁换下一个
-    const tryClaimOnce = async (): Promise<boolean> => {
-      const remaining = state.candidates.filter((c) => !unusable.has(c.appId));
-      if (remaining.length === 0) return false;
-      const result = await claimAny(remaining, { preferredAppId });
-      if (!result.claim) {
-        const detail = result.skipped
-          .map(
-            (s) =>
-              `${s.name}:${s.reason === "online" ? "在线" : s.reason === "reserved" ? `被 pid ${s.owner?.pid} 重载中` : "刚被抢走"}`,
-          )
-          .join(", ");
-        log("[lock] 本轮无可接入的 qqbot（", detail, "）");
-        return false;
-      }
-      const claim = result.claim;
-      const account = pool.find((a) => a.appId === claim.appId);
-      if (!account) {
-        await claim.release().catch(() => {});
-        unusable.add(claim.appId);
-        return tryClaimOnce();
-      }
-      try {
-        const auth = await verifyAccount(account);
-        applyClaim(claim, account, auth);
-        return true;
-      } catch (e) {
-        await claim.release().catch(() => {});
-        unusable.add(account.appId);
-        log(
-          "[lock] qqbot",
-          `"${account.name}"`,
-          "凭据不可用：",
-          String(e).slice(0, 160),
-          "→ 已放锁并跳过该 bot（改好配置后 /reload 再试）",
-        );
-        return tryClaimOnce();
-      }
-    };
-
-    // 待命：还有「可能变可用」的候选就 5s 重扫——否则别人退出后没人接管
-    const enterStandby = () => {
-      if (!state.candidates.some((c) => !unusable.has(c.appId))) {
-        log("[lock] 没有可接入的 qqbot（其余在线或凭据不可用），本进程不接入 QQ");
-        return;
-      }
-      log("[lock] 本进程待命，5s 后重扫");
-      state.stopRetry = startClaimRetry(
-        () => state.candidates.filter((c) => !unusable.has(c.appId)),
-        (claim) => {
-          state.stopRetry = null;
-          void (async () => {
-            const account = pool.find((a) => a.appId === claim.appId);
-            if (!account || state.gateway) {
-              await claim.release().catch(() => {});
-              enterStandby();
-              return;
-            }
-            try {
-              const auth = await verifyAccount(account);
-              applyClaim(claim, account, auth);
-            } catch (e) {
-              await claim.release().catch(() => {});
-              unusable.add(account.appId);
-              log("[lock] qqbot", `"${account.name}"`, "凭据不可用：", String(e).slice(0, 160), "→ 放锁继续待命");
-              enterStandby();
-            }
-          })();
-        },
-        { preferredAppId },
-      );
-    };
-
-    if (await tryClaimOnce()) return;
-    enterStandby();
-  });
-
-  // ---- 事件：上下文压缩可能把「远程用户」提醒压掉：下一条消息重新注入 ----
-  pi.on("session_compact", (event) => {
-    state.remoteNotified = false;
-    log("[remote] 上下文已压缩（reason=", String((event as any)?.reason ?? "?"), "），下一条消息重新注入提醒");
-  });
-
-  // ---- 事件：session_shutdown 清理 ----
-  pi.on("session_shutdown", async (event) => {
-    const reason = String((event as any)?.reason ?? "quit");
-    log("[shutdown] 清理资源 reason=", reason);
-    clearCancelTimer(state);
-    stopProgressTimer(state);
-    const dropped = state.queue.clear();
-    if (dropped.length > 0) log("[shutdown] 丢弃队列任务", dropped.length, "条");
-    if (state.stopRetry) state.stopRetry();
-    state.gateway?.stop();
-    // reload/new/fork/resume 只是「本进程换会话」，马上会重新接入：先贴预约，别让别人抢走
-    if (state.account && state.releaseLock && reason !== "quit") {
-      reserveBeforeRelease(state.account, reason);
-      log("[lock] qqbot", `"${state.account.name}"`, "临时释放（reason=", reason, "），已留预约窗口");
-    }
-    if (state.releaseLock) {
-      try {
-        await state.releaseLock();
-      } catch {
-        /* ignore */
-      }
-    }
-    state.releaseLock = null;
-    state.gateway = null;
-    state.api = null;
-    state.getToken = null;
-    state.restBase = null;
-    state.account = null;
-  });
-
-  // ---- /qq：QQ 侧命令的桥接入口 ----
-  // pi 只对「扩展命令」执行派发，内置命令（/reload、/new…）只能在 TUI/RPC 层跑；
-  // 而 reload()/newSession() 又必须拿到 ExtensionCommandContext。于是注册一个扩展
-  // 命令，QQ 侧收到 /reload 时改派 /qq reload，就能在合法的命令上下文里执行。
-  pi.registerCommand("qq", {
-    description:
-      "pi-qqbot 内部桥接：/qq <reload|new|compact|quit|session|name|model|thinking|sendfile> [args]",
-    handler: async (args, ctx) => {
-      const trimmed = args.trim();
-      const space = trimmed.indexOf(" ");
-      const sub = (space === -1 ? trimmed : trimmed.slice(0, space)).toLowerCase();
-      const rest = (space === -1 ? "" : trimmed.slice(space + 1)).trim();
-      const reply = (text: string) => state.bridgeReply?.(text);
-      // 发本机文件不需要命令上下文，先于 runBridge 处理
-      if (sub === "sendfile") {
-        try {
-          reply(await sendFileToQQ(state, rest));
-        } catch (e) {
-          log("[/qq] sendfile 失败:", String(e));
-          reply(`发送失败：${explainUploadError(e)}`);
-        }
-        return;
-      }
-      try {
-        await runBridge(sub, rest, ctx, pi, reply, state);
-      } catch (e) {
-        log("[/qq] 桥接失败:", String(e));
-        reply(`/${sub} 执行失败：${String(e).slice(0, 200)}`);
-      }
-    },
-  });
-
-  // ---- 工具：把本机文件发到 QQ ----
-  // 外发文件属于数据出境，必须在 QQ 里审批（见 FORCE_APPROVAL_TOOLS）。
-  pi.registerTool(
-    defineTool({
-      name: QQ_SEND_FILE_TOOL,
-      label: "Send file to QQ",
-      description:
-        "把本机上已有的文件发送到当前 QQ 对话（对方收到可下载的文件卡片/图片/视频/语音）。" +
-        "只在用户明确要求把某个文件发给他时使用；path 必须是本机绝对路径。" +
-        "发送前会先在 QQ 里自动申请审批，用户同意后才会真正上传。",
-      parameters: Type.Object({
-        path: Type.String({ description: "本机文件的绝对路径，例如 D:\\docs\\report.pdf" }),
-        name: Type.Optional(
-          Type.String({ description: "在 QQ 里显示的文件名（含扩展名），默认用原文件名" }),
-        ),
-      }),
-      async execute(_toolCallId: string, params: any) {
-        const text = await sendFileToQQ(state, String(params?.path ?? ""), params?.name ? String(params.name) : undefined);
-        return { content: [{ type: "text", text }], details: { tool: QQ_SEND_FILE_TOOL } };
-      },
-    }),
-  );
-}
-
-/** 取消/停止这类「打断当前任务」的表达 */
-/**
- * 取消/停止这类「打断当前任务」的表达。
- *
- * 注意分工：「停」「停下」「停一下」属于**中断任务**（用户定的：停 = 停止干活）；
- * 想只关掉进度推送请用「别汇报了」「闭嘴」「/progress off」；
- * 「停止汇报」因为带了名词，不算取消，走静音。
- */
-const RE_CANCEL =
-  /^(\/cancel|\/stop|\/abort|取消|停止|中止|终止|算了|停|停下|停一下|停停|停掉|别跑了|cancel|stop|abort)$/i;
-
-function isCancelIntent(text: string): boolean {
-  return RE_CANCEL.test(text.trim());
-}
-
-/** files 配置兜底：老配置 / 测试里可能没这个键 */
-function filesConfig(cfg: QQBotConfig): { enabled: boolean; maxBytes: number } {
-  const raw = (cfg as any)?.files;
-  return {
-    enabled: raw?.enabled ?? true,
-    maxBytes: Number(raw?.maxBytes ?? DEFAULT_SEND_MAX_BYTES),
-  };
-}
-
-/**
- * 把本机文件发到当前 QQ 对话。
- * 工具（qq_send_file）与 `/sendfile` 命令共用；失败抛异常，文案由 explainUploadError 翻译。
- */
-async function sendFileToQQ(state: State, filePath: string, displayName?: string): Promise<string> {
-  const cfg = state.cfg;
-  if (!cfg) throw new Error("还没有接入 QQ bot（会话未就绪）");
-  const files = filesConfig(cfg);
-  if (!files.enabled) throw new Error("发送文件已关闭（配置 files.enabled=false）");
-  const openid = state.currentOpenid ?? state.lastOpenid;
-  if (!openid || !state.api) throw new Error("没有 QQ 会话目标（先让用户从 QQ 发一条消息）");
-  if (!state.restBase || !state.getToken) throw new Error("QQ 凭据未就绪");
-
-  const raw = String(filePath ?? "")
-    .trim()
-    .replace(/^["']|["']$/g, "")
-    .trim();
-  if (!raw) throw new Error("缺少文件路径（用法：/sendfile <绝对路径>）");
-
-  const media = await uploadRichMedia({
-    restBase: state.restBase,
-    openid,
-    getToken: state.getToken,
-    filePath: raw,
-    fileName: displayName,
-    maxBytes: files.maxBytes,
-    log,
-    onProgress: (done, total) => log("[send] 分片", done, "/", total),
-  });
-
-  const ref = state.passiveRefs.get(openid);
-  const usePassive = !!ref && Date.now() - ref.receivedAt < PASSIVE_WINDOW_MS;
-  await state.api.sendC2CMedia(openid, media.fileInfo, usePassive ? { msgId: ref.msgId } : {});
-  log("[send] 已发出", media.fileName, media.size, "bytes", `type=${media.fileType}`);
-  return `已发送「${media.fileName}」（${formatSize(media.size)}，${mediaKindLabel(media.fileType)}）`;
-}
-
-function formatSize(bytes: number): string {
-  if (!Number.isFinite(bytes) || bytes < 0) return "?";
-  if (bytes < 1024) return `${bytes} B`;
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
-  return `${(bytes / 1024 / 1024).toFixed(2)} MB`;
-}
-function attachmentConfig(cfg: QQBotConfig): AttachmentConfig {
-  const raw = (cfg as any)?.attachments;
-  return {
-    enabled: raw?.enabled ?? true,
-    dir: String(raw?.dir ?? "").trim(),
-    maxBytes: Number(raw?.maxBytes ?? DEFAULT_ATTACHMENT_MAX_BYTES),
-    maxPerMessage: Number(raw?.maxPerMessage ?? DEFAULT_ATTACHMENT_MAX_PER_MESSAGE),
-    retentionHours: Number(raw?.retentionHours ?? DEFAULT_ATTACHMENT_RETENTION_HOURS),
-    maxFiles: Number(raw?.maxFiles ?? DEFAULT_ATTACHMENT_MAX_FILES),
-  };
-}
-
-/** 派发失败时最多重试几次（通常是 pi 上一轮还没收尾） */
-const MAX_DISPATCH_ATTEMPTS = 3;
-
-function clearCancelTimer(state: State) {
-  if (state.cancelTimer) {
-    clearTimeout(state.cancelTimer);
-    state.cancelTimer = null;
-  }
-}
-
-/**
- * 对外看是“忙”：有任务在跑、正在派发，或者队列里还有任务等着（比如派发失败后的重试窗口）。
- * 这三种情况新消息都应该进队列，而不是插队直接开新一轮。
- */
-function isBusy(state: State): boolean {
-  return state.busy || state.dispatching || state.queue.size > 0;
-}
-
-/**
- * /cancel 之后 abort() 是异步的：正常路径靠 agent_settled 释放 busy 并继续队列；
- * 万一 abort 没能触发 settled（比如那一轮正好已经结束），宽限期后强制解锁。
- */
-function armCancelWatchdog(pi: ExtensionAPI, state: State) {
-  clearCancelTimer(state);
-  const timer = setTimeout(() => {
-    state.cancelTimer = null;
-    if (!state.cancelled) return;
-    log("[cancel] abort 后", CANCEL_SETTLE_GRACE_MS, "ms 内没有 agent_settled，强制释放 busy");
-    state.cancelled = false;
-    state.busy = false;
-    state.ctx = null;
-    state.currentOpenid = null;
-    state.replyBuffer.reset();
-    drainQueue(pi, state);
-  }, CANCEL_SETTLE_GRACE_MS);
-  (timer as any).unref?.();
-  state.cancelTimer = timer;
-}
-
-/**
- * 把一条任务交给 pi，并把它标记为「当前任务」。
- * 不 await sendUserMessage：它返回的 promise 要等整轮跑完，await 会卡住调用方
- * （agent_settled 里派发时更是不允许）。错误交给 onDispatchError 重试/回执。
- */
-function startJob(pi: ExtensionAPI, state: State, job: QueuedJob) {
-  state.currentOpenid = job.openid;
-  state.lastOpenid = job.openid;
-  state.pickerOwner = job.openid;
-  state.bridgeReply = (text: string) => {
-    void replyTo(state.api!, state, job.openid, text);
-  };
-  state.busy = true;
-  state.cancelled = false;
-  state.runStarted = false;
-  state.replyBuffer.reset();
-  clearCancelTimer(state);
-  log(
-    "[msg] 送入 pi:",
-    job.id > 0 ? `队列 #${job.id}` : "直接",
-    "openid=",
-    job.openid,
-    "text=",
-    job.text.slice(0, 60),
-  );
-  // 每会话第一条真正跑起来的 QQ 消息，由 before_agent_start 注入远程上下文说明。
-  try {
-    void Promise.resolve(
-      pi.sendUserMessage(job.text, { expandPromptTemplates: true, deliverAs: "followUp" }),
-    ).catch((error) => onDispatchError(pi, state, job, error));
-  } catch (error) {
-    onDispatchError(pi, state, job, error);
-  }
-}
-
-/** 派发失败：先重试（放回队首），多次失败就把错误回给发送者并继续队列 */
-function onDispatchError(pi: ExtensionAPI, state: State, job: QueuedJob, error: unknown) {
-  const message = String((error as any)?.message ?? error).slice(0, 200);
-  log("[msg] 派发失败:", message);
-  if (state.runStarted) {
-    // run 已经启动了：这次报错属于这一轮自己的问题，收尾交给 agent_settled，不能重试
-    log("[msg] 本轮已启动过 agent，不重试，等 agent_settled 收尾");
-    return;
-  }
-  state.busy = false;
-  state.currentOpenid = null;
-  job.attempts += 1;
-  if (job.attempts < MAX_DISPATCH_ATTEMPTS) {
-    state.queue.unshift(job);
-    log("[msg]", DISPATCH_RETRY_MS, "ms 后重试（第", job.attempts, "次）");
-    const timer = setTimeout(() => drainQueue(pi, state), DISPATCH_RETRY_MS);
-    (timer as any).unref?.();
-    return;
-  }
-  const api = state.api;
-  if (api) void replyTo(api, state, job.openid, `这条消息执行失败：${message}`);
-  drainQueue(pi, state);
-}
-
-/** 当前任务结束后，取队列里的下一条开始执行（空闲时才会真的派发） */
-function drainQueue(pi: ExtensionAPI, state: State) {
-  if (state.busy || state.dispatching) return;
-  const job = state.queue.shift();
-  if (!job) return;
-  state.dispatching = true;
-  try {
-    log("[queue] 出队 #", job.id, "剩余", state.queue.size, "条", "text=", job.text.slice(0, 60));
-    const api = state.api;
-    if (api && state.cfg?.queue.ack !== false) {
-      const rest = state.queue.size > 0 ? `（后面还有 ${state.queue.size} 条）` : "";
-      void replyTo(api, state, job.openid, `开始执行队列 #${job.id}${rest}`);
-    }
-    startJob(pi, state, job);
-  } finally {
-    state.dispatching = false;
-  }
-}
-
-/** 入队（忙碌时的统一入口）：回执排队位置 */
-async function enqueueJob(
-  api: QQApi,
-  state: State,
-  openid: string,
-  text: string,
-): Promise<boolean> {
-  const result = state.queue.push(openid, text);
-  if (!result.ok) {
-    log("[queue] 队列已满（上限", state.queue.max, "），拒绝入队");
-    if (state.queue.max === 0) {
-      await replyTo(api, state, openid, "上一条消息还在处理中，请稍候…（队列已关闭：queue.max=0）");
-      return false;
-    }
-    await replyTo(
-      api,
-      state,
-      openid,
-      `队列已满（上限 ${state.queue.max} 条），这条没排上。发 /queue 查看队列，或 /cancel 清空后重发。`,
-    );
-    return false;
-  }
-  log("[queue] 入队 #", result.job.id, "size=", state.queue.size, "ahead=", result.ahead);
-  await replyTo(
-    api,
-    state,
-    openid,
-    `已排队 #${result.job.id}${result.ahead > 0 ? `（前面还有 ${result.ahead} 条）` : ""}，当前任务结束后自动执行。发 /queue 查看队列，/cancel 可中止当前任务并清空队列。`,
-  );
-  return true;
-}
-
-function formatQueue(state: State): string {
-  const lines = [`当前任务：${state.busy ? "处理中（发 /cancel 可中断）" : "空闲"}`];
-  const jobs = state.queue.list();
-  if (jobs.length === 0) {
-    lines.push("队列：空");
-    return lines.join("\n");
-  }
-  lines.push(`队列：${jobs.length} 条（上限 ${state.queue.max}）`);
-  jobs.slice(0, 10).forEach((job, index) => {
-    lines.push(`  ${index + 1}. #${job.id} · ${agoLabel(job.enqueuedAt)} · ${previewText(job.text)}`);
-  });
-  if (jobs.length > 10) lines.push(`  … 还有 ${jobs.length - 10} 条`);
-  lines.push("发 /queue clear 清空，/queue drop <编号> 删除一条。");
-  return lines.join("\n");
-}
-
-/**
- * 用户发来取消指令：终止待审批、清空队列、abort 当前 run、丢弃半截回复，然后回执。
- * 取消本身永不入队（“取消除外”），立即生效。
- * （「取消自动同意」/「关闭自动同意」不属于取消指令，仍走审批分支。）
- */
-async function handleCancel(
-  pi: ExtensionAPI,
-  state: State,
-  api: QQApi,
-  openid: string,
-): Promise<void> {
-  const terminated = state.approver.terminateAll();
-  const dropped = state.queue.clear();
-  const running = state.busy || Boolean(state.ctx?.signal);
-  if (!running) {
-    const parts: string[] = [];
-    if (terminated > 0) parts.push(`已终止 ${terminated} 个待审批请求`);
-    if (dropped.length > 0) parts.push(`已清空队列（${dropped.length} 条）`);
-    await replyTo(
-      api,
-      state,
-      openid,
-      parts.length > 0
-        ? `${parts.join("，")}，当前没有正在运行的任务。`
-        : "当前没有正在运行的任务。",
-    );
-    return;
-  }
-
-  stopProgressTimer(state);
-  state.progress.stop();
-  state.cancelled = true;
-  state.replyBuffer.reset();
-  state.currentOpenid = null; // 被中止的 run 不再往 QQ 发半截回复
-  const ctx = state.ctx;
-  state.ctx = null;
-  try {
-    ctx?.abort();
-    log("[cancel] 已请求中止当前 run，终止待审批", terminated, "个，清空队列", dropped.length, "条");
-  } catch (e) {
-    log("[cancel] abort 失败:", String(e));
-  }
-  // busy 保持 true 直到 agent_settled：期间新消息会排队，不会和正在收尾的 run 撞车
-  armCancelWatchdog(pi, state);
-  const notice: string[] = [];
-  if (terminated > 0) notice.push(`并终止了 ${terminated} 个待审批请求`);
-  if (dropped.length > 0) notice.push(`队列中的 ${dropped.length} 条已清空`);
-  await replyTo(
-    api,
-    state,
-    openid,
-    `已取消当前任务${notice.length > 0 ? `，${notice.join("，")}` : ""}。可以发送新消息继续。`,
-  );
-}
-
-// ---- QQ 消息处理 ----
-export async function handleMessage(
-  pi: ExtensionAPI,
-  state: State,
-  api: QQApi,
-  cfg: QQBotConfig,
-  msg: QQMessage,
-) {
-  try {
-    log("[msg] 收到消息 openid=", msg.openid, "content=", msg.content.slice(0, 100));
-    if (cfg.allowlist.length > 0 && !cfg.allowlist.includes(msg.openid)) {
-      log("[msg] 被 allowlist 拦截");
-      return;
-    }
-    state.passiveRefs.set(msg.openid, { msgId: msg.msgId, receivedAt: Date.now() });
-
-    // ---- 附件落盘：图片 / 语音 / 视频 / 文档 / 压缩包 / 普通文件 ----
-    // 落盘后拼成「图片路径 <path>」这类标记行交给 pi；有附件时绕过 picker/指令/审批路由
-    const attachments = msg.attachments ?? [];
-    const hasAttachment = attachments.length > 0;
-    let incoming = msg.content;
-    if (hasAttachment) {
-      const acc = attachmentConfig(cfg);
-      if (!acc.enabled) {
-        const names = attachments.map((a, i) => a.filename || `附件 ${i + 1}`).join("、");
-        log("[attachment] 已被配置忽略", attachments.length, "个附件");
-        await replyTo(
-          api,
-          state,
-          msg.openid,
-          `已忽略 ${attachments.length} 个附件（配置 attachments.enabled=false）：${names}。本次只处理文字内容。`,
-        );
-        if (!msg.content.trim()) return; // 纯附件 + 已忽略：不给 pi 送空消息
-      } else {
-        const dir = acc.dir || defaultAttachmentDir(cfg.appId);
-        const { saved, failed } = await saveIncoming(attachments, {
-          dir,
-          maxBytes: acc.maxBytes,
-          maxPerMessage: acc.maxPerMessage,
-          fetchFn: state.attachmentFetch ?? undefined,
-          credential: state.getToken,
-          prefix: msg.msgId,
-        });
-        log(
-          "[attachment] 落盘",
-          saved.length,
-          "个，失败",
-          failed.length,
-          "个 →",
-          saved.map((s) => `${s.kind}:${s.name}`).join(", ") || "(无)",
-        );
-        const ack = renderAttachmentAck(saved, failed);
-        if (ack) await replyTo(api, state, msg.openid, ack);
-        incoming = [msg.content.trim(), ...renderAttachmentLines(saved), ...renderAttachmentFailureLines(failed)]
-          .filter(Boolean)
-          .join("\n");
-        if (!incoming) return; // 全部失败且无正文：已经回执过，不再送空消息
-      }
-    }
-
-    // 上一条最终答案没发出去（配额耗尽）：先补发
-    if (state.undelivered && state.undelivered.openid === msg.openid) {
-      const pending = state.undelivered;
-      state.undelivered = null;
-      log("[reply] 补发上一条未送达的回复，长度", pending.text.length);
-      const ok = await replyTo(api, state, msg.openid, `（上一条回复发送失败，补发如下）\n\n${pending.text}`);
-      if (!ok) {
-        state.undelivered = pending;
-        log("[reply] 补发仍然失败，继续保留");
-      }
-    }
-
-    // 待选择的编号回复（/tree、/fork、/resume 之后）；带附件时不当作编号选择
-    if (!hasAttachment && state.picker) {
-      if (pickerExpired(state.picker)) {
-        state.picker = null;
-      } else if (state.picker.openid === msg.openid) {
-        const index = parsePickIndex(msg.content);
-        if (index !== null) {
-          if (state.busy) {
-            await replyTo(api, state, msg.openid, "当前有任务在跑，先发 /cancel 取消，再回编号。");
-            return;
-          }
-          if (index > state.picker.items.length) {
-            await replyTo(api, state, msg.openid, `编号 ${index} 超出范围（1-${state.picker.items.length}）。`);
-            return;
-          }
-          state.pickerOwner = msg.openid;
-          state.bridgeReply = (text: string) => {
-            void replyTo(api, state, msg.openid, text);
-          };
-          log("[cmd] 选择编号", index, "kind=", state.picker.kind);
-          pi.sendUserMessage(`/qq pick ${index}`, { expandPromptTemplates: true });
-          return;
-        }
-        if (/^(取消|算了|cancel)$/i.test(msg.content.trim())) {
-          state.picker = null;
-          await replyTo(api, state, msg.openid, "已放弃选择。");
-          return;
-        }
-      }
-    }
-
-    // 取消指令优先于审批解析：「取消」不该被当成审批动作；取消也永不入队
-    if (isCancelIntent(msg.content)) {
-      await handleCancel(pi, state, api, msg.openid);
-      return;
-    }
-
-    // 斜杠命令路由：pi 扩展命令 → 可接管的内置命令 → 仅主机可用的内置命令 → 普通文字
-    state.lastOpenid = msg.openid;
-    state.pickerOwner = msg.openid;
-    state.bridgeReply = (text: string) => {
-      void replyTo(api, state, msg.openid, text);
-    };
-    const routed = hasAttachment
-      ? ("text" as const)
-      : await routeSlash(
-      {
-        listPiCommands: () => (pi.getCommands?.() ?? []) as { name: string; source?: string }[],
-        dispatch: (text, options) => {
-          // 提示模板 / /skill: 会开启一轮 agent run：和普通对话一样串行到队列
-          if (options?.runsTurn) {
-            if (!isBusy(state)) {
-              startJob(pi, state, state.queue.mint(msg.openid, text));
-              return "dispatched";
-            }
-            const queued = state.queue.push(msg.openid, text);
-            if (!queued.ok) {
-              log("[queue] 队列已满，命令未排队:", text.slice(0, 60));
-              return "rejected";
-            }
-            log("[queue] 命令入队 #", queued.job.id, text.slice(0, 60));
-            return "queued";
-          }
-          // 扩展命令 / 桥接命令（/qq …）不开 run，pi 允许流式期间执行，直接派发
-          void Promise.resolve(pi.sendUserMessage(text, { expandPromptTemplates: true })).catch(
-            (e) => log("[cmd] 派发失败:", String(e)),
-          );
-          return "dispatched";
-        },
-        reply: (text: string) => replyTo(api, state, msg.openid, text),
-        busy: isBusy(state),
-        cfg: cfg.commands,
-        log,
-      },
-      msg.content,
-    );
-    if (routed !== "text") return;
-
-    // 远程审批回复优先（带附件时不当作审批动作）
-    const parsed = hasAttachment ? null : state.approver.parseReply(msg.content.trim());
-    if (parsed) {
-      if (parsed.decision === "terminate") {
-        const n = state.approver.terminateAll();
-        state.approver.setAutoAllow(false);
-        await replyTo(api, state, msg.openid, `已终止 ${n} 个待审批请求，自动同意已关闭`);
-        return;
-      }
-      if (parsed.decision === "always") {
-        // 「以后都同意」= 本会话内全部放行：立刻开启开关并放行当前所有待审批
-        state.approver.setAutoAllow(true);
-        const n = state.approver.allowAll();
-        log("[approve] 开启会话级自动同意，放行", n, "个待审批");
-        await replyTo(
-          api,
-          state,
-          msg.openid,
-          [
-            `已开启自动同意：本会话内需审批的工具全部放行${n > 0 ? `，已放行 ${n} 个待审批请求` : ""}。`,
-            "回复「取消自动同意」或 /new 恢复逐条审批。",
-          ].join("\n"),
-        );
-        return;
-      }
-      if (parsed.decision === "revoke") {
-        const was = state.approver.autoAllowed;
-        state.approver.setAutoAllow(false);
-        log("[approve] 关闭自动同意 was=", was);
-        await replyTo(
-          api,
-          state,
-          msg.openid,
-          was ? "已关闭自动同意，恢复逐条审批。" : "当前没有开启自动同意，仍需逐条审批。",
-        );
-        return;
-      }
-      // allow / block：没写编号时作用于最早的一条待审批
-      const seq = parsed.seq ?? state.approver.oldestSeq();
-      if (seq !== undefined) {
-        const ok = state.approver.confirm(seq, parsed.decision);
-        const text = !ok
-          ? `#${seq} 不存在或已超时`
-          : parsed.decision === "allow"
-            ? `已批准 #${seq}`
-            : `已拒绝 #${seq}`;
-        await replyTo(api, state, msg.openid, text);
-        return;
-      }
-      // 没有待审批：这句「同意/拒绝」当普通消息交给 pi，继续往下走
-      log("[msg] 审批类文本但无待审批，按普通消息处理");
-    }
-
-    // 内置指令（带附件时绕过：附件消息一律当普通内容交给 pi）
-    const cmd = hasAttachment ? null : parseCommand(msg.content);
-    if (cmd?.name === "help") {
-      await replyTo(
-        api,
-        state,
-        msg.openid,
-        [
-          "pi-qqbot 指令:",
-          "/progress — 查看进度；/progress off 暂停自动汇报、/progress on 恢复（本会话有效）",
-          "/status — 查看状态（当前 qqbot / 忙闲 / 来源 / 队列 / 自动同意 / 待审批 / 自动汇报）",
-          "/queue — 查看队列；/queue clear 清空；/queue drop <编号> 删一条",
-          "/reset — 清空回复缓冲、审批记忆与自动同意（不换会话；换会话发 /new）",
-          "/cancel（或「取消」「停止」「停」）— 中断正在运行的任务并清空队列",
-          "/sendfile <路径> — 把本机文件发到你的 QQ（png/jpg/mp4/silk 直显，其余为文件卡片；外发需审批）",
-          "只关进度推送：/progress off（或「别汇报了」「闭嘴」）；「停」是中断任务，不是静音",
-          "/help — 帮助",
-          "pi 的命令优先：/reload /new /compact /session /name /model /thinking，以及扩展命令、模板与 /skill:xxx。",
-          "忙碌时发来的普通消息（含模板/skill 命令）会排队，当前任务结束后自动执行。",
-          "多 bot：配置了多个 qqbot 时，多个 pi 进程会按列表顺序各自接入一个，抢不到的待命重扫。",
-          "其余文本交给 pi 当作对话处理。",
-        ].join("\n"),
-      );
-      return;
-    }
-    if (cmd?.name === "status") {
-      const lines = [
-        `bot: ${state.account ? `${state.account.name} (…${state.account.appId.slice(-4)})` : "未接入"} · cwd: ${process.cwd()}`,
-        `状态: ${state.busy ? "处理中（发送 /cancel 可中断）" : state.queue.size > 0 ? "空闲，但有排队任务待派发" : "空闲"}`,
-        `来源: ${describeRunOrigin(state)}`,
-        `队列: ${state.queue.size} 条待执行${state.queue.size > 0 ? "（发 /queue 查看）" : ""}`,
-        `自动同意: ${state.approver.autoAllowed ? "已开启（本会话有效）" : "未开启"}`,
-        `待审批: ${state.approver.pendingCount}`,
-        `自动汇报: ${describeProgressMode(state)}`,
-      ];
-      if (state.busy) {
-        const snapshot = state.progress.summary();
-        if (snapshot) lines.push("", snapshot);
-        // 用户主动问询：恢复自动推送（手动暂停的不算）
-        if (!state.progressMuted) state.progressPaused = false;
-      }
-      await replyTo(api, state, msg.openid, lines.join("\n"));
-      return;
-    }
-    if (cmd?.name === "progress") {
-      const sub = (cmd.args ?? "").trim().toLowerCase();
-      if (MUTE_ARGS.has(sub)) {
-        const was = state.progressMuted;
-        state.progressMuted = true;
-        state.progressPaused = false;
-        log("[progress] 用户暂停自动进度推送（本会话有效）", was ? "（已经是暂停状态）" : "");
-        await replyTo(
-          api,
-          state,
-          msg.openid,
-          was
-            ? "自动汇报本来就已暂停。发 /progress on（或「恢复汇报」）可以恢复。"
-            : "已暂停自动进度汇报（本会话有效，换会话或重启后恢复默认开启）。需要时发 /progress 仍可查看一次，发 /progress on 恢复。",
-        );
-        return;
-      }
-      if (UNMUTE_ARGS.has(sub)) {
-        const was = state.progressMuted;
-        state.progressMuted = false;
-        state.progressPaused = false;
-        log("[progress] 用户恢复自动进度推送");
-        await replyTo(
-          api,
-          state,
-          msg.openid,
-          was
-            ? `已恢复自动进度汇报${state.cfg?.progress?.enabled === false ? "（但配置 progress.enabled=false，仍不会推送）" : ""}。`
-            : "自动汇报本来就是开启的。",
-        );
-        return;
-      }
-      if (sub) {
-        await replyTo(
-          api,
-          state,
-          msg.openid,
-          "用法: /progress（看一次）| /progress off（暂停自动汇报）| /progress on（恢复）。也可以说「暂停汇报」「恢复汇报」。",
-        );
-        return;
-      }
-      const snapshot = state.progress.summary();
-      if (!state.progressMuted) state.progressPaused = false;
-      const body = snapshot || (state.busy ? "当前任务刚启动，还没有可汇报的进度。" : "当前没有正在运行的任务。");
-      await replyTo(
-        api,
-        state,
-        msg.openid,
-        state.progressMuted ? `${body}\n（自动汇报已暂停，发 /progress on 恢复）` : body,
-      );
-      return;
-    }
-    if (cmd?.name === "queue") {
-      await handleQueueCommand(api, state, msg.openid, cmd.args);
-      return;
-    }
-    if (cmd?.name === "reset") {
-      state.replyBuffer.reset();
-      state.approver.reset();
-      await replyTo(api, state, msg.openid, "已重置（回复缓冲/审批记忆/自动同意）。要开新会话请发 /new。");
-      return;
-    }
-
-    // 忙检查：单会话串行处理——忙碌时入队，当前任务结束后自动继续
-    if (isBusy(state)) {
-      // 忙碌时问「进度」不该排队，直接回当前进度并恢复自动推送
-      if (!hasAttachment && RE_PROGRESS_QUERY.test(msg.content.trim())) {
-        const snapshot = state.progress.summary();
-        if (!state.progressMuted) state.progressPaused = false;
-        await replyTo(api, state, msg.openid, snapshot || "任务刚启动，还没有可汇报的进度。");
-        return;
-      }
-      await enqueueJob(api, state, msg.openid, incoming);
-      return;
-    }
-
-    // ack
-    await replyTo(api, state, msg.openid, "收到，正在处理");
-
-    startJob(pi, state, state.queue.mint(msg.openid, incoming));
-  } catch (e) {
-    log("[msg] 处理失败:", String(e));
-    await replyTo(api, state, msg.openid, `处理失败: ${String(e).slice(0, 200)}`).catch(() => {});
-  }
-}
-
-async function replyTo(
-  api: QQApi,
-  state: State,
-  openid: string,
-  text: string,
-  format: "text" | "markdown" = "text",
-): Promise<boolean> {
-  // 本进程刚接入 / 刚接管这个 qqbot：第一条回执带上身份与工作目录
-  if (state.claimNote) {
-    const note = state.claimNote;
-    state.claimNote = null;
-    text = `${note}\n${text}`;
-  }
-  const ref = state.passiveRefs.get(openid);
-  let delivered = true;
-  for (const chunk of splitText(text)) {
-    const usePassive = !!ref && Date.now() - ref.receivedAt < PASSIVE_WINDOW_MS;
-    try {
-      await api.sendC2C(openid, chunk, usePassive ? { msgId: ref.msgId, format } : { format });
-      log("[reply] 已发送 (passive=", usePassive, "):", chunk.slice(0, 50));
-    } catch (e) {
-      delivered = false;
-      log("[reply] 发送失败:", String(e));
-    }
-  }
-  return delivered;
-}
-
-/** 用户问进度的表达（忙碌时用来区分「排队」和「问进度」） */
-// 忙碌时判断「这是在问进度」：只认句首的明确表达，避免把「帮我加个进度条」这类任务误当问询
-const RE_PROGRESS_QUERY = new RegExp(
-  "^(?:" +
-    "\\/(?:progress|p|status)" +
-    "|(?:现在|当前|目前)?\\s*(?:的)?\\s*(?:progress|进度|进展)" +
-    "|跑到哪|怎么样了|到哪了|还在跑吗|好慢" +
-  ")",
-  "i",
-);
-
-function startProgressTimer(pi: ExtensionAPI, state: State) {
-  stopProgressTimer(state);
-  const cfg = state.cfg?.progress;
-  if (!cfg?.enabled) return;
-  const interval = Number.isFinite(cfg.intervalMs) && cfg.intervalMs >= 50 ? cfg.intervalMs : 15000;
-  const timer = setInterval(() => {
-    void pushProgress(state, "tick");
-  }, interval);
-  (timer as any).unref?.();
-  state.progressTimer = timer;
-  log("[progress] 自动进度推送已启动，间隔", interval, "ms");
-}
-
-function stopProgressTimer(state: State) {
-  if (state.progressTimer) {
-    clearInterval(state.progressTimer);
-    state.progressTimer = null;
-  }
-}
-
-/** 推一条进度摘要；失败就暂停自动推送（用户问一次即恢复）；手动暂停（/progress off）管到底 */
-async function pushProgress(state: State, reason: "tick" | "ask"): Promise<boolean> {
-  if (reason === "tick" && (state.progressPaused || state.progressMuted)) return false;
-  // 有审批在等用户回复：暂停自动推送，否则每 15s 一条进度会把审批提示顶出屏幕
-  // （手动问进度不受影响：用户自己要看的）
-  if (reason === "tick" && state.approver.pendingCount > 0) {
-    if (!state.progressHeldForApproval) {
-      state.progressHeldForApproval = true;
-      log("[progress] 有", state.approver.pendingCount, "个待审批，暂缓自动进度推送");
-    }
-    return false;
-  }
-  const api = state.api;
-  const openid = state.currentOpenid ?? state.lastOpenid;
-  if (!api || !openid || !state.busy || !state.progress.running) return false;
-  if (state.progressHeldForApproval) {
-    state.progressHeldForApproval = false;
-    log("[progress] 审批已处理，恢复自动进度推送");
-  }
-  const text = state.progress.summary();
-  if (!text) return false;
-  const ok = await replyTo(api, state, openid, text);
-  if (!ok) {
-    state.progressPaused = true;
-    log("[progress] 推送失败（多半是配额），暂停自动进度推送，直到用户询问");
-  }
-  return ok;
-}
-
-/** /status 用：最近一轮对话是谁发起的 */
-function describeRunOrigin(state: State): string {
-  if (state.lastRunOrigin === "qq") return "QQ（远程）";
-  if (state.lastRunOrigin === "local") return "本机（TUI）";
-  return "尚未开始";
-}
-
-/** 自动汇报当前状态的人话描述（/status 用） */
-function describeProgressMode(state: State): string {
-  const cfg = state.cfg?.progress;
-  if (state.progressMuted) return "已暂停（本会话，发 /progress on 恢复）";
-  if (cfg?.enabled === false) return "未启用（配置 progress.enabled=false）";
-  if (state.progressPaused) return "推送失败已静默，发 /progress 恢复";
-  const ms = Number.isFinite(cfg?.intervalMs) && (cfg?.intervalMs ?? 0) >= 50 ? cfg!.intervalMs : 15000;
-  const base = `开启（每 ${Math.round(ms / 1000)}s）`;
-  return state.approver.pendingCount > 0 ? `${base}，等审批期间暂缓` : base;
-}
-
-/** /progress 的子命令：暂停 / 恢复自动汇报 */
-const MUTE_ARGS = new Set([
-  "off",
-  "pause",
-  "stop",
-  "mute",
-  "关",
-  "关闭",
-  "关掉",
-  "停",
-  "停止",
-  "暂停",
-  "暂停汇报",
-  "停止汇报",
-]);
-const UNMUTE_ARGS = new Set([
-  "on",
-  "resume",
-  "start",
-  "unmute",
-  "开",
-  "开启",
-  "打开",
-  "恢复",
-  "继续",
-  "恢复汇报",
-  "开启汇报",
-  "继续汇报",
-]);
-
-/**
- * 不带斜杠的口令（整句匹配，避免误伤正常聊天）。
- *
- * 三类：
- * 1. 问进度：「汇报一下当前进度」「看一下进度」「进度如何」→ 回一次摘要
- * 2. 静音：「暂停汇报进度」「别汇报了」「别说了」「闭嘴」「停」→ 暂停自动汇报
- * 3. 恢复：「恢复汇报」「接着说」→ 重新打开自动汇报
- *
- * 注意：「停止/取消/中止」是**中断任务**（RE_CANCEL，更早判定），不是静音；
- * 「停止汇报」才走静音。
- */
-const REPORT_LEAD = "(?:请|帮我|给我|麻烦|暂时|先)?\\s*";
-/** 汇报名词的两种语序（进度汇报 / 汇报进度） */
-const REPORT_NOUN =
-  "(?:(?:进度|进展)(?:汇报|报告|推送|播报|上报)?|(?:汇报|报告|推送|播报|上报)(?:进度|进展)?)";
-const REPORT_TAIL = "\\s*(?:了|吧|哦|啊|呀|嘛|啦|呗)*";
-
-/** 问进度（含「汇报一下…」这类祈使句） */
-const BARE_PROGRESS_RE = new RegExp(
-  "^" +
-    REPORT_LEAD +
-    "(?:(?:汇报|报告|报|说说|讲讲|看|看看|查|查查|查看|显示|展示)(?:一下|下|个|一眼)?\\s*)?" +
-    "(?:当前|现在|目前)?\\s*(?:的)?\\s*(?:progress|进度|进展)" +
-    "(?:\\s*(?:如何|怎么样|怎样|呢|啦|了|吗))?" +
-    "(?:\\s+([\\s\\S]*))?$",
-  "i",
-);
-
-/** 静音：带「汇报」名词的 */
-const RE_REPORTS_OFF = new RegExp(
-  "^" +
-    REPORT_LEAD +
-    "(?:暂停|停止|停下|关闭|关掉|别再|别|不要|不用|甭|闭嘴|安静|打住)\\s*" +
-    "(?:自动|定时|定期)?\\s*(?:的)?\\s*" +
-    REPORT_NOUN +
-    REPORT_TAIL +
-    "$",
-);
-/** 静音：不提「汇报」的纯闭嘴类（停/停下 不在此列——它们属于中断任务） */
-const RE_SILENCE = new RegExp(
-  "^" +
-    REPORT_LEAD +
-    "(?:闭嘴|安静|安静点|安静下|别说了|别讲了|别吵了?|别推了|别发了|别报了|打住)" +
-    REPORT_TAIL +
-    "$",
-);
-/** 恢复：说清楚要恢复汇报，或者「接着说」 */
-const RE_REPORTS_ON = new RegExp(
-  "^" +
-    REPORT_LEAD +
-    "(?:恢复|继续|开启|打开|开始|接着说|接着说吧|说下去|接着报)\\s*" +
-    "(?:自动|定时|定期)?\\s*(?:的)?\\s*" +
-    REPORT_NOUN +
-    REPORT_TAIL +
-    "$",
-);
-const RE_RESUME_TALK = new RegExp("^" + REPORT_LEAD + "(?:接着说|说下去|接着报)" + REPORT_TAIL + "$");
-
-/** 不带斜杠的进度问询：「进度」「当前进度」「汇报一下当前进度」（可带子命令） */
-
-function parseCommand(text: string): { name: "reset" | "status" | "help" | "queue" | "progress"; args: string } | null {
-  // 注意：/new 现在属于 pi 的内置命令（由 slash 路由接管，真的开新会话），
-  // 本地的「清缓冲/清审批记忆」改名为 /reset。
-  // 斜杠形式：全部内置指令；不带斜杠时只接受明确表达「进度」的词，避免把聊天里的 "p" / "status" 误判成命令
-  const t = text.trim();
-  const slash = /^\/(reset|status|help|queue|q|progress|p)(?:\s+([\s\S]*))?$/i.exec(t);
-  if (slash) {
-    const raw = slash[1].toLowerCase();
-    const name = raw === "q" ? "queue" : raw === "p" ? "progress" : raw;
-    return {
-      name: name as "reset" | "status" | "help" | "queue" | "progress",
-      args: (slash[2] ?? "").trim(),
-    };
-  }
-  // 裸文本：先认「问进度」，再认「静音/恢复」
-  const bare = BARE_PROGRESS_RE.exec(t);
-  if (bare) return { name: "progress", args: (bare[1] ?? "").trim() };
-  if (RE_REPORTS_OFF.test(t) || RE_SILENCE.test(t)) return { name: "progress", args: "off" };
-  if (RE_REPORTS_ON.test(t) || RE_RESUME_TALK.test(t)) return { name: "progress", args: "on" };
-  return null;
-}
-
-/** /queue [clear|drop <编号>] */
-async function handleQueueCommand(api: QQApi, state: State, openid: string, args: string) {
-  const parts = args.split(/\s+/).filter(Boolean);
-  const sub = parts[0]?.toLowerCase() ?? "";
-
-  if (!sub) {
-    await replyTo(api, state, openid, formatQueue(state));
-    return;
-  }
-  if (/^(clear|reset|清空)$/i.test(sub)) {
-    const dropped = state.queue.clear();
-    await replyTo(
-      api,
-      state,
-      openid,
-      dropped.length > 0 ? `已清空队列（${dropped.length} 条）。` : "队列本来就是空的。",
-    );
-    return;
-  }
-  if (/^(drop|del|rm|删除|删|去掉)$/i.test(sub)) {
-    const id = Number.parseInt(parts[1] ?? "", 10);
-    if (!Number.isFinite(id)) {
-      await replyTo(api, state, openid, "用法：/queue drop <编号>（编号见 /queue）");
-      return;
-    }
-    const removed = state.queue.remove(id);
-    await replyTo(
-      api,
-      state,
-      openid,
-      removed ? `已从队列删除 #${id}：${previewText(removed.text)}` : `队列里没有 #${id}，发 /queue 查看。`,
-    );
-    return;
-  }
-  await replyTo(api, state, openid, "用法：/queue 查看 / /queue clear 清空 / /queue drop <编号> 删一条");
-}
-
-/** 从 tool_call 事件提取可读摘要，让用户在 QQ 里看清要执行什么 */
-function summarizeTool(event: any): string {
-  const input = event.input ?? {};
-  // 审批提示会发到 QQ：先脱敏再截断
-  const clip = (value: unknown) => redactSecrets(String(value ?? "")).slice(0, 200);
-  switch (event.toolName) {
-    case "bash":
-    case "powershell":
-      return `${event.toolName}: ${clip(input.command)}`;
-    case "write":
-    case "edit":
-    case "read":
-      return `${event.toolName}: ${clip(input.path ?? input.file ?? input.filePath)}`;
-    case "grep":
-      return `${event.toolName}: ${clip(input.pattern)}`;
-    case "qq_send_file":
-      return `发送文件到 QQ: ${clip(input.path)}${input.name ? `（显示名 ${clip(input.name)}）` : ""}`;
-    default:
-      return `${event.toolName}: ${clip(JSON.stringify(input))}`;
-  }
-}
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { loadAccounts, pinnedAccountName, type QQBotAccount, type QQBotConfig } from "./config";
+import {
+  REST_BASE_PROD,
+  REST_BASE_SANDBOX,
+  INTENT_GROUP_AND_C2C,
+  PASSIVE_WINDOW_MS,
+  APPROVAL_TIMEOUT_MS,
+  DISPATCH_RETRY_MS,
+  CANCEL_SETTLE_GRACE_MS,
+  DEFAULT_ATTACHMENT_MAX_BYTES,
+  DEFAULT_ATTACHMENT_MAX_FILES,
+  DEFAULT_ATTACHMENT_MAX_PER_MESSAGE,
+  DEFAULT_ATTACHMENT_RETENTION_HOURS,
+  DEFAULT_SEND_MAX_BYTES,
+} from "./constants";
+import {
+  defaultAttachmentDir,
+  renderAttachmentAck,
+  renderAttachmentFailureLines,
+  renderAttachmentLines,
+  saveIncoming,
+  sweepAttachmentDir,
+  type AttachmentConfig,
+} from "./attachment";
+import {
+  explainUploadError,
+  mediaKindLabel,
+  uploadRichMedia,
+} from "./qq/upload";
+import { log, configureLog } from "./logger";
+import { claimAny, startClaimRetry, reserveBeforeRelease, readOwner, type Claim } from "./lock";
+import { AuthManager } from "./qq/auth";
+import { QQApi } from "./qq/api";
+import { createGatewayUrlFetcher, QQGateway, QQMessage } from "./qq/gateway";
+import { Approver } from "./approver";
+import { parsePickIndex, pickerExpired, routeSlash, runBridge, type PickerState } from "./slash";
+import { agoLabel, MessageQueue, previewText, type QueuedJob } from "./queue";
+import { ProgressTracker } from "./progress";
+import {
+  buildLocalHandoffNotice,
+  buildRemoteGuidelines,
+  buildRemoteNotice,
+  LOCAL_HANDOFF_SECTION,
+  REMOTE_NOTICE_SECTION,
+  resolveRemoteConfig,
+} from "./remote";
+import { redactSecrets } from "./redact";
+import {
+  isUpdateSelfIntent,
+  runSelfUpdate,
+  installedVersion,
+  checkLatestVersion,
+  applyUpdate,
+  shellRunner,
+} from "./selfupdate";
+import {
+  billingNotice,
+  borrowModelMeta,
+  classifyProviderError,
+  errorNotice,
+  existingProviderIds,
+  filterChatModelIds,
+  formatModelPicker,
+  kindLabel,
+  maskSecret,
+  MODEL_PICK_LIMIT,
+  modelLabel,
+  normalizeBaseUrl,
+  parseCredentialMessage,
+  probeEndpoint,
+  providerIdForEndpoint,
+  providerModelConfig,
+  updateProviderKey,
+  upsertEndpointProvider,
+  type CredentialIntake,
+  type ErrorContext,
+  type ProviderErrorKind,
+  type ProbeResult,
+} from "./billing";
+import { ReplyBuffer } from "./stream-buffer";
+import { splitText } from "./util/chunk";
+
+/** 发送本机文件的工具名 */
+const QQ_SEND_FILE_TOOL = "qq_send_file";
+/** 外发文件必须审批：不受配置 approve.tools 影响，也不吃「以后都同意」/会话内记忆 */
+const FORCE_APPROVAL_TOOLS = new Set<string>([QQ_SEND_FILE_TOOL]);
+
+interface State {
+  cfg: QQBotConfig | null;
+  /** 本进程当前服务的 QQ bot（自动抢占的结果）；未接入则为 null */
+  account: { name: string; appId: string } | null;
+  /** 本进程的候选 bot（按配置顺序），待命时用它重扫 */
+  candidates: { name: string; appId: string }[];
+  /** 首条回执前缀（接入成功 / 换进程接管时告知用户当前 bot 与工作目录） */
+  claimNote: string | null;
+  api: QQApi | null;
+  approver: Approver;
+  gateway: QQGateway | null;
+  currentOpenid: string | null;
+  replyBuffer: ReplyBuffer;
+  releaseLock: (() => Promise<void>) | null;
+  stopRetry: (() => void) | null;
+  passiveRefs: Map<string, { msgId: string; receivedAt: number }>;
+  busy: boolean;
+  /** 当前 run 的上下文（用来 abort）；run 结束或取消后清空 */
+  ctx: ExtensionContext | null;
+  /** 最近一条 QQ 消息的发送者：桥接命令用它回执 */
+  lastOpenid: string | null;
+  /** 待选择列表（/tree、/fork、/resume 发出后的编号等待状态） */
+  picker: PickerState | null;
+  /** 发出列表的 QQ 用户：只有他能回编号 */
+  pickerOwner: string | null;
+  /** /qq 桥接命令的回执通道（每次收到 QQ 消息时刷新） */
+  bridgeReply: ((text: string) => void) | null;
+  /** 本轮已被用户取消：settle 时丢弃半截回复 */
+  cancelled: boolean;
+  /** 忙碌时收到的任务：当前任务 settle 后逐条执行 */
+  queue: MessageQueue;
+  /** 正在出队派发（防 settled / 重试竞态下重复派发） */
+  dispatching: boolean;
+  /** 当前派发的任务已经真的启动了 run（agent_start 过）：此时报错不重试，避免重复执行 */
+  runStarted: boolean;
+  /** /cancel 之后等 agent_settled 的兜底定时器 */
+  cancelTimer: ReturnType<typeof setTimeout> | null;
+  /** 任务进度摘要 */
+  progress: ProgressTracker;
+  /** 自动推送进度的定时器 */
+  progressTimer: ReturnType<typeof setInterval> | null;
+  /** 推送失败后暂停自动推送，直到用户主动询问 */
+  progressPaused: boolean;
+  /** 用户手动暂停自动推送（本会话有效：跨 run 保留，/progress on 恢复） */
+  progressMuted: boolean;
+  /** 等审批期间暂缓自动进度推送（避免把审批消息顶走）；审批处理完自动恢复 */
+  progressHeldForApproval: boolean;
+  /** 本会话是否已给 pi 注入过「远程用户」提醒（每会话一次，压缩后重新注入） */
+  remoteNotified: boolean;
+  /** 上一轮 run 的来源：null = 还没跑过 */
+  lastRunOrigin: "qq" | "local" | null;
+  /** 本机在 TUI 接管了对话，等下一轮 run 开跑时更正「远程前提作废」 */
+  localHandoffPending: boolean;
+  /** 最终答案发送失败时缓存，下一条消息时补发 */
+  undelivered: { openid: string; text: string } | null;
+  /** 本轮 run 中模型接口返回的错误（分类 + 已脱敏原文），结束时转告 QQ */
+  lastError: ErrorContext | null;
+  /** 最近一次欠费/鉴权失败：让用户直接发来的新 key 知道该落到哪个 provider */
+  billing: { kind: ProviderErrorKind; provider: string; modelId: string; at: number } | null;
+  /** 最近一次真正生效的模型（带 baseUrl，用于探测新 key 是否有效） */
+  lastModel: { provider: string; modelId: string; baseUrl?: string } | null;
+  /** 只读的 command/session 上下文：拿 modelRegistry 借内置目录里的模型元数据 */
+  registryCtx: ExtensionContext | null;
+  /** 附件下载 401/403 时重试用的凭据（接入后由 applyClaim 注入） */
+  getToken: (() => Promise<string>) | null;
+  /** 仅测试用：替换附件落盘时的 fetch */
+  attachmentFetch: typeof fetch | null;
+  /** 当前 bot 的 REST 基址（发文件用） */
+  restBase: string | null;
+}
+
+/** 扩展运行所需的状态（导出只为测试用） */
+export function createInitialState(): State {
+  return {
+    cfg: null,
+    api: null,
+    approver: new Approver(APPROVAL_TIMEOUT_MS),
+    gateway: null,
+    currentOpenid: null,
+    replyBuffer: new ReplyBuffer(),
+    releaseLock: null,
+    stopRetry: null,
+    passiveRefs: new Map(),
+    busy: false,
+    ctx: null,
+    lastOpenid: null,
+    picker: null,
+    pickerOwner: null,
+    bridgeReply: null,
+    cancelled: false,
+    queue: new MessageQueue(),
+    dispatching: false,
+    runStarted: false,
+    cancelTimer: null,
+    progress: new ProgressTracker(),
+    progressTimer: null,
+    progressPaused: false,
+    progressMuted: false,
+    progressHeldForApproval: false,
+    remoteNotified: false,
+    lastRunOrigin: null,
+    localHandoffPending: false,
+    undelivered: null,
+    lastError: null,
+    billing: null,
+    lastModel: null,
+    registryCtx: null,
+    getToken: null,
+    attachmentFetch: null,
+    restBase: null,
+    account: null,
+    candidates: [],
+    claimNote: null,
+  };
+}
+
+export default function (
+  pi: ExtensionAPI,
+  /** 仅测试用：注入状态，让事件处理器与 handleMessage 共享同一份状态 */
+  options?: {
+    state?: State;
+    /** 仅测试用：不真连 QQ 网关（避免单测打网络），其余流程（抢锁/身份/提示）照常 */
+    disableGateway?: boolean;
+    /** 仅测试用：替换「抢到锁后验凭据」的实现（默认真的去换 access_token） */
+    verifyCredentials?: (account: QQBotAccount) => Promise<AuthManager>;
+  },
+) {
+  const state: State = options?.state ?? createInitialState();
+
+  // ---- 事件：本机用户在 TUI 直接打字（source=interactive）→ 记一笔「可能接管」----
+  // 只记待定，真正注入要等下一轮 run 开跑（before_agent_start）。
+  // 本扩展自己的 sendUserMessage 是 source=extension，不会走到这里；QQ run 跑着时接管不处理。
+  pi.on("input", (event) => {
+    const ev = event as any;
+    if (ev?.source !== "interactive") return;
+    if (state.busy) return;
+    if (state.lastRunOrigin !== "qq") return;
+    if (state.localHandoffPending) return;
+    state.localHandoffPending = true;
+    log("[remote] 检测到本机 TUI 输入，下一轮按「本机用户」前提处理");
+  });
+
+  // ---- 事件：真正开始一轮 run 时，按「来自 QQ 还是本机」准备系统提示 ----
+  // 不在扩展载入时注入，也不在本机 TUI 自己对话时注入：只有 startJob() 派发的
+  // QQ 消息真的开跑（state.busy + currentOpenid）才会走到这里。
+  pi.on("before_agent_start", (event) => {
+    const cfg = state.cfg;
+    if (!cfg) return;
+    if ((event as any).messageType !== "user") return;
+    const options = (event as any).systemPromptOptions;
+    if (!options || typeof options !== "object") return;
+
+    // 本扩展派发的 QQ 消息
+    if (state.busy && state.currentOpenid) {
+      const remote = resolveRemoteConfig(cfg);
+      if (remote.guidelines && Array.isArray(options.promptGuidelines)) {
+        const guidelines = buildRemoteGuidelines();
+        // 同一次 run 可能重复触发（如压缩后重试），别叠加两遍
+        if (!options.promptGuidelines.includes(guidelines[0])) options.promptGuidelines.push(...guidelines);
+      }
+      if (remote.notice && !state.remoteNotified) {
+        state.remoteNotified = true;
+        // 放进系统提示的 section：排在用户消息之前，模型不会把它当成要回复的消息；
+        // 只在本轮生效，操作规则由 guidelines 继续带在后续每一轮。
+        options.sections = { ...(options.sections ?? {}), [REMOTE_NOTICE_SECTION]: buildRemoteNotice(remote) };
+        log("[remote] 首次向 pi 交付 QQ 消息，已注入远程上下文说明（系统提示 section）");
+      }
+      // 又轮到 QQ 了：刚才的本机接管待定作废
+      state.localHandoffPending = false;
+      state.lastRunOrigin = "qq";
+      return;
+    }
+
+    // 本机 TUI/CLI 直接开跑：上一轮是 QQ 的话，更正一次「远程前提作废」
+    const handoff = state.localHandoffPending;
+    state.localHandoffPending = false;
+    state.lastRunOrigin = "local";
+    if (!handoff) return;
+    options.sections = { ...(options.sections ?? {}), [LOCAL_HANDOFF_SECTION]: buildLocalHandoffNotice() };
+    log("[remote] 本机接管本轮对话，已注入「远程前提作废」更正");
+  });
+
+  // ---- 事件：run 开始，记住 ctx（取消指令要调用 ctx.abort()）----
+  pi.on("agent_start", (_event, ctx) => {
+    state.ctx = ctx;
+    state.cancelled = false;
+    state.runStarted = true;
+    state.lastError = null;
+    syncModelFromCtx(state, ctx);
+    clearCancelTimer(state);
+    state.progress.start();
+    state.progressPaused = false;
+    state.progressHeldForApproval = false;
+    startProgressTimer(pi, state);
+  });
+
+  // ---- 事件：累积 assistant 文本 ----
+  pi.on("message_update", (event) => {
+    const ev = event.assistantMessageEvent as any;
+    if (ev?.type === "text_delta") {
+      const delta = ev.delta ?? ev.text ?? "";
+      state.replyBuffer.append(delta);
+      state.progress.appendText(delta);
+    }
+  });
+
+  // ---- 事件：进度统计（工具/轮次/用量）----
+  pi.on("tool_execution_start", (event) => {
+    const ev = event as any;
+    state.progress.toolStart(ev.toolCallId, ev.toolName, ev.args);
+  });
+
+  pi.on("tool_execution_end", (event) => {
+    const ev = event as any;
+    state.progress.toolEnd(ev.toolCallId, ev.toolName, ev.isError === true, ev.durationMs);
+  });
+
+  pi.on("turn_end", () => {
+    state.progress.turn();
+  });
+
+  pi.on("message_end", (event) => {
+    const message = (event as any).message;
+    if (message?.role !== "assistant") return;
+    state.progress.addUsage(message.usage);
+    // 接口报错（402 余额不足 / 401 鉴权失败 / 5xx 等）：pi 把 provider 返回的原文塞进
+    // errorMessage，且不会有任何 text_delta —— 不记下来 QQ 侧就是「没反应」。
+    if (message.stopReason === "error") {
+      const raw = String(message.errorMessage ?? "未知错误");
+      const kind = classifyProviderError(raw);
+      const detail = redactSecrets(raw).replace(/\s+/g, " ").trim().slice(0, 600);
+      const model = [message.provider, message.model].filter(Boolean).join("/") || null;
+      state.lastError = { kind, detail, model };
+      if (message.provider && message.model) {
+        state.lastModel = {
+          provider: String(message.provider),
+          modelId: String(message.model),
+          baseUrl: state.lastModel?.baseUrl,
+        };
+      }
+      log("[reply] 本轮模型接口报错:", kindLabel(kind), model ?? "", detail);
+    }
+  });
+
+  // ---- 事件：run 结束，发回复，然后接着跑队列里的下一条 ----
+  pi.on("agent_settled", async () => {
+    clearCancelTimer(state);
+    stopProgressTimer(state);
+    state.progress.stop();
+    const cancelled = state.cancelled;
+    const text = state.replyBuffer.take();
+    const errorInfo = state.lastError;
+    state.lastError = null;
+    // 本轮吐出了正文 = 模型跑通了：欠费状态作废，避免把用户下一条正文误当成 key
+    if (text && !cancelled) state.billing = null;
+    const openid = state.currentOpenid;
+    state.currentOpenid = null;
+    state.busy = false;
+    state.ctx = null;
+    state.cancelled = false;
+    state.runStarted = false;
+    if (cancelled) {
+      log("[reply] 本轮已被取消，丢弃半截回复（长度", text.length, "）");
+    } else if (!text && errorInfo && openid && state.api) {
+      // 欠费/鉴权类失败：除了报错，还要把「怎么恢复」和「当前是哪家服务」讲清楚，
+      // 并记住上下文，让用户直接把新 key / 新 endpoint 发过来就能用。
+      const recoverable =
+        errorInfo.kind === "billing" || errorInfo.kind === "auth" || errorInfo.kind === "permission";
+      if (recoverable) {
+        const [provider, ...rest] = String(errorInfo.model ?? "").split("/");
+        state.billing = {
+          kind: errorInfo.kind,
+          provider: provider || state.lastModel?.provider || "",
+          modelId: rest.join("/") || state.lastModel?.modelId || "",
+          at: Date.now(),
+        };
+        log("[billing] 记为可恢复的接口失败:", kindLabel(errorInfo.kind), errorInfo.model ?? "?");
+      }
+      const notice = recoverable ? billingNotice(errorInfo) : errorNotice(errorInfo);
+      log("[reply] 本轮接口报错，转告 QQ：", notice.split("\n")[0]);
+      for (const chunk of splitText(notice)) {
+        await state.api.sendC2C(openid, chunk).catch((e) => {
+          log("[reply] 错误提示发送失败:", String(e));
+        });
+      }
+    } else if (text && openid && state.api) {
+      log("[reply] agent_settled，回复 openid=", openid, "text=", text.slice(0, 80));
+      let delivered = true;
+      for (const chunk of splitText(text)) {
+        await state.api.sendC2C(openid, chunk).catch((e) => {
+          delivered = false;
+          log("[reply] 发送失败:", String(e));
+        });
+      }
+      if (!delivered) {
+        // 配额耗尽等情况：缓存下来，用户下次发消息时补发
+        state.undelivered = { openid, text };
+        log("[reply] 最终答案发送失败，已缓存待补发（openid=", openid, "len=", text.length, "）");
+      }
+    }
+    // 本轮结束：取队列里的下一条继续执行（不 await，避免卡住 settled 的派发阶段）
+    drainQueue(pi, state);
+  });
+
+  // ---- 事件：tool_call 审批 ----
+  pi.on("tool_call", async (event) => {
+    const openid = state.currentOpenid;
+    if (!openid || !state.api || !state.cfg) return; // 无 QQ 上下文，放行
+    const ev = event as any;
+    const toolName: string = ev.toolName ?? "tool";
+    const cfg = state.cfg;
+
+    // 判断是否需要审批：配置的 tools 列表 + destructiveHint 兑底 + 强制审批工具（外发文件）
+    const allTools = (pi.getAllTools() ?? []) as any[];
+    const toolMeta = allTools.find((t) => t.name === toolName);
+    const destructive = toolMeta?.annotations?.destructiveHint === true;
+    const forced = FORCE_APPROVAL_TOOLS.has(toolName);
+    const needsApproval = forced || cfg.approve.tools.includes(toolName) || destructive;
+    if (!needsApproval) return; // 放行
+
+    // 强制审批的工具（发送文件）每次都问：不吃「以后都同意」，也不吃会话内记住的决策
+    if (!forced) {
+      // 会话级自动同意（用户回复过「以后都同意」）：本会话内直接放行，不落盘、不跨会话
+      if (state.approver.autoAllowed) {
+        log("[approve] 自动同意放行:", toolName);
+        return;
+      }
+
+      // 会话内已记住的决策
+      const remembered = cfg.approve.remember ? state.approver.isRemembered(toolName) : undefined;
+      if (remembered === "allow") return; // 已记住放行
+      if (remembered === "block") return { block: true, reason: `QQ 用户已拒绝 ${toolName}` };
+      if (remembered === "terminate") return { block: true, terminate: true, reason: "已停止" };
+    }
+
+    const summary = summarizeTool(ev);
+    log("[approve] 工具需要审批:", summary);
+    const { seq, done } = state.approver.register(summary, () => {
+      // 超时通知
+      state.api?.sendC2C(openid, `审批 #${seq} 已超时，已自动拒绝。`).catch(() => {});
+    });
+    await state.api
+      .sendC2C(openid, state.approver.render(seq, { strict: forced }))
+      .catch(() => {});
+    const decision = await done;
+
+    if (decision === "allow") {
+      if (!forced && cfg.approve.remember) state.approver.remember(toolName, "allow");
+      log("[approve] 用户批准 #", seq);
+      return;
+    }
+    if (decision === "terminate") {
+      log("[approve] 用户停止");
+      return { block: true, terminate: true, reason: "QQ 用户停止" };
+    }
+    if (decision === "timeout") {
+      // 超时不写 remember：一次没回复不该永久封死该工具
+      log("[approve] 审批超时 #", seq);
+      return { block: true, reason: `QQ 审批超时（#${seq}）：${summary}` };
+    }
+    // block（用户显式拒绝）
+    if (!forced && cfg.approve.remember) state.approver.remember(toolName, "block");
+    log("[approve] 用户拒绝 #", seq);
+    return { block: true, reason: `QQ 用户拒绝了 ${summary}` };
+  });
+
+  // ---- 事件：session_start 选/抢 qqbot + 启动网关 ----
+  pi.on("session_start", async (event, ctx) => {
+    // 只读地存一份上下文：注册新 endpoint 时要拿 modelRegistry 借内置目录的模型元数据
+    state.registryCtx = ctx ?? state.registryCtx;
+    const { accounts, errors } = loadAccounts();
+    for (const message of errors) log("[setup] 配置问题:", message);
+    if (accounts.length === 0) {
+      log("[setup] 未配置 QQ bot（或配置不可用），插件未启用");
+      return;
+    }
+
+    // 会话重建（/reload、/new…）时优先沿用自己的 bot：上一轮释放前写了 owner 记录
+    const pin = pinnedAccountName();
+    const pool: QQBotAccount[] = pin
+      ? accounts.filter((a) => a.name === pin || a.appId === pin)
+      : accounts;
+    if (pool.length === 0) {
+      log("[setup] PI_QQBOT_ACCOUNT=", pin, "不在配置里（可选:", accounts.map((a) => a.name).join(", "), "），插件未启用");
+      return;
+    }
+    state.candidates = pool.map((a) => ({ name: a.name, appId: a.appId }));
+
+    const ownPid = process.pid;
+    const preferredAppId = state.candidates
+      .map((c) => readOwner(c.appId))
+      .find((owner) => owner?.pid === ownPid)?.appId;
+
+    // 新会话：清空 remember 记忆与自动同意开关（自动同意只在当前会话有效）
+    state.approver.reset();
+    // 远程上下文提醒同样只在本会话提醒一次
+    state.remoteNotified = false;
+    // 「QQ ↔ 本机」的来源切换状态也随会话重置
+    state.lastRunOrigin = null;
+    state.localHandoffPending = false;
+    // 手动暂停的自动汇报同样只在本会话有效
+    state.progressMuted = false;
+    state.progressPaused = false;
+    state.queue.clear();
+
+    // 凭据不可用的 bot 在本次会话内不再尝试（配置在 session_start 读取，改完 /reload 才生效）
+    const unusable = new Set<string>();
+    const verifyAccount =
+      options?.verifyCredentials ??
+      (async (account: QQBotAccount) => {
+        const auth = new AuthManager(account.appId, account.config.appSecret);
+        await auth.getToken(); // 抢到锁之后先验凭据，失败就不占着这个槽位
+        return auth;
+      });
+
+    const applyClaim = (claim: Claim, account: QQBotAccount, auth: AuthManager) => {
+      const cfg = account.config;
+      state.cfg = cfg;
+      state.account = { name: account.name, appId: account.appId };
+      state.releaseLock = claim.release;
+      // 只有一个 bot（含 v1 旧配置）→ 继续写旧文件名，升级后日志不断线
+      configureLog(accounts.length === 1 ? null : account.name);
+      state.queue.setLimit(cfg.queue.max);
+      log(
+        "[setup] 配置已加载 bot=",
+        `"${account.name}"`,
+        "appId=",
+        account.appId,
+        "sandbox=",
+        cfg.sandbox,
+        "queue.max=",
+        cfg.queue.max,
+        "reason=",
+        (event as any)?.reason ?? "startup",
+      );
+
+      // 提示：接入成功 / 换进程接管（后者一定要带工作目录）
+      const cwd = process.cwd();
+      if (claim.takeover && claim.previous) {
+        log(
+          "[lock] qqbot",
+          `"${account.name}"`,
+          "换进程接管: pid",
+          claim.previous.pid,
+          "→",
+          process.pid,
+          "· cwd",
+          claim.previous.cwd || "?",
+          "→",
+          cwd,
+        );
+        state.claimNote = `（qqbot「${account.name}」已由新实例接管 · 当前工作目录 ${cwd}）`;
+      } else if (claim.reclaimed) {
+        log("[lock] 重新接入自己的 qqbot（同进程会话重建）");
+      } else {
+        log("[lock] 接入 qqbot", `"${account.name}"`, `(${account.appId})`, "· cwd=", cwd, "· pid=", process.pid);
+        state.claimNote = `（已接入 qqbot「${account.name}」）`;
+      }
+
+      const restBase = cfg.sandbox ? REST_BASE_SANDBOX : REST_BASE_PROD;
+      const api = new QQApi({ restBase, getToken: () => auth.getToken() });
+      state.api = api;
+      state.getToken = () => auth.getToken();
+      state.restBase = restBase;
+
+      // 顺手清掉上一轮留下的临时附件（失败不影响启动）
+      const attCfg = attachmentConfig(cfg);
+      if (attCfg.enabled) {
+        const attDir = attCfg.dir || defaultAttachmentDir(cfg.appId);
+        void sweepAttachmentDir(attDir, {
+          retentionHours: attCfg.retentionHours,
+          maxFiles: attCfg.maxFiles,
+        })
+          .then((r) => {
+            if (r.removed > 0) log("[attachment] 清理临时附件", r.removed, "个", `(dir=${attDir})`);
+          })
+          .catch((e) => log("[attachment] 清理失败:", String(e).slice(0, 160)));
+      }
+
+      if (options?.disableGateway) {
+        log("[setup] 测试模式：跳过 QQ 网关");
+        return;
+      }
+      const gateway = new QQGateway({
+        getGatewayUrl: createGatewayUrlFetcher(restBase, () => auth.getToken()),
+        getToken: () => auth.getToken(),
+        intents: INTENT_GROUP_AND_C2C,
+        connected: () => {},
+        disconnected: () => {},
+        message: (msg) => handleMessage(pi, state, api, state.cfg ?? cfg, msg),
+      });
+      state.gateway = gateway;
+      log("[lock] 启动 QQ 网关");
+      gateway.start();
+    };
+
+    // 抢一个、验一下凭据、验不过就放锁换下一个
+    const tryClaimOnce = async (): Promise<boolean> => {
+      const remaining = state.candidates.filter((c) => !unusable.has(c.appId));
+      if (remaining.length === 0) return false;
+      const result = await claimAny(remaining, { preferredAppId });
+      if (!result.claim) {
+        const detail = result.skipped
+          .map(
+            (s) =>
+              `${s.name}:${s.reason === "online" ? "在线" : s.reason === "reserved" ? `被 pid ${s.owner?.pid} 重载中` : "刚被抢走"}`,
+          )
+          .join(", ");
+        log("[lock] 本轮无可接入的 qqbot（", detail, "）");
+        return false;
+      }
+      const claim = result.claim;
+      const account = pool.find((a) => a.appId === claim.appId);
+      if (!account) {
+        await claim.release().catch(() => {});
+        unusable.add(claim.appId);
+        return tryClaimOnce();
+      }
+      try {
+        const auth = await verifyAccount(account);
+        applyClaim(claim, account, auth);
+        return true;
+      } catch (e) {
+        await claim.release().catch(() => {});
+        unusable.add(account.appId);
+        log(
+          "[lock] qqbot",
+          `"${account.name}"`,
+          "凭据不可用：",
+          String(e).slice(0, 160),
+          "→ 已放锁并跳过该 bot（改好配置后 /reload 再试）",
+        );
+        return tryClaimOnce();
+      }
+    };
+
+    // 待命：还有「可能变可用」的候选就 5s 重扫——否则别人退出后没人接管
+    const enterStandby = () => {
+      if (!state.candidates.some((c) => !unusable.has(c.appId))) {
+        log("[lock] 没有可接入的 qqbot（其余在线或凭据不可用），本进程不接入 QQ");
+        return;
+      }
+      log("[lock] 本进程待命，5s 后重扫");
+      state.stopRetry = startClaimRetry(
+        () => state.candidates.filter((c) => !unusable.has(c.appId)),
+        (claim) => {
+          state.stopRetry = null;
+          void (async () => {
+            const account = pool.find((a) => a.appId === claim.appId);
+            if (!account || state.gateway) {
+              await claim.release().catch(() => {});
+              enterStandby();
+              return;
+            }
+            try {
+              const auth = await verifyAccount(account);
+              applyClaim(claim, account, auth);
+            } catch (e) {
+              await claim.release().catch(() => {});
+              unusable.add(account.appId);
+              log("[lock] qqbot", `"${account.name}"`, "凭据不可用：", String(e).slice(0, 160), "→ 放锁继续待命");
+              enterStandby();
+            }
+          })();
+        },
+        { preferredAppId },
+      );
+    };
+
+    if (await tryClaimOnce()) return;
+    enterStandby();
+  });
+
+  // ---- 事件：上下文压缩可能把「远程用户」提醒压掉：下一条消息重新注入 ----
+  pi.on("session_compact", (event) => {
+    state.remoteNotified = false;
+    log("[remote] 上下文已压缩（reason=", String((event as any)?.reason ?? "?"), "），下一条消息重新注入提醒");
+  });
+
+  // ---- 事件：session_shutdown 清理 ----
+  pi.on("session_shutdown", async (event) => {
+    const reason = String((event as any)?.reason ?? "quit");
+    log("[shutdown] 清理资源 reason=", reason);
+    clearCancelTimer(state);
+    stopProgressTimer(state);
+    const dropped = state.queue.clear();
+    if (dropped.length > 0) log("[shutdown] 丢弃队列任务", dropped.length, "条");
+    if (state.stopRetry) state.stopRetry();
+    state.gateway?.stop();
+    // reload/new/fork/resume 只是「本进程换会话」，马上会重新接入：先贴预约，别让别人抢走
+    if (state.account && state.releaseLock && reason !== "quit") {
+      reserveBeforeRelease(state.account, reason);
+      log("[lock] qqbot", `"${state.account.name}"`, "临时释放（reason=", reason, "），已留预约窗口");
+    }
+    if (state.releaseLock) {
+      try {
+        await state.releaseLock();
+      } catch {
+        /* ignore */
+      }
+    }
+    state.releaseLock = null;
+    state.gateway = null;
+    state.api = null;
+    state.getToken = null;
+    state.restBase = null;
+    state.account = null;
+  });
+
+  // ---- /qq：QQ 侧命令的桥接入口 ----
+  // pi 只对「扩展命令」执行派发，内置命令（/reload、/new…）只能在 TUI/RPC 层跑；
+  // 而 reload()/newSession() 又必须拿到 ExtensionCommandContext。于是注册一个扩展
+  // 命令，QQ 侧收到 /reload 时改派 /qq reload，就能在合法的命令上下文里执行。
+  pi.registerCommand("qq", {
+    description:
+      "pi-qqbot 内部桥接：/qq <reload|new|compact|quit|session|name|model|thinking|sendfile> [args]",
+    handler: async (args, ctx) => {
+      const trimmed = args.trim();
+      const space = trimmed.indexOf(" ");
+      const sub = (space === -1 ? trimmed : trimmed.slice(0, space)).toLowerCase();
+      const rest = (space === -1 ? "" : trimmed.slice(space + 1)).trim();
+      const reply = (text: string) => state.bridgeReply?.(text);
+      // 发本机文件不需要命令上下文，先于 runBridge 处理
+      if (sub === "sendfile") {
+        try {
+          reply(await sendFileToQQ(state, rest));
+        } catch (e) {
+          log("[/qq] sendfile 失败:", String(e));
+          reply(`发送失败：${explainUploadError(e)}`);
+        }
+        return;
+      }
+      try {
+        await runBridge(sub, rest, ctx, pi, reply, state);
+      } catch (e) {
+        log("[/qq] 桥接失败:", String(e));
+        reply(`/${sub} 执行失败：${String(e).slice(0, 200)}`);
+      }
+      // 命令可能换了模型（/model、编号选择）：同步一份给「欠费后发新 key」用
+      syncModelFromCtx(state, ctx);
+    },
+  });
+
+  // ---- 工具：把本机文件发到 QQ ----
+  // 外发文件属于数据出境，必须在 QQ 里审批（见 FORCE_APPROVAL_TOOLS）。
+  pi.registerTool(
+    defineTool({
+      name: QQ_SEND_FILE_TOOL,
+      label: "Send file to QQ",
+      description:
+        "把本机上已有的文件发送到当前 QQ 对话（对方收到可下载的文件卡片/图片/视频/语音）。" +
+        "只在用户明确要求把某个文件发给他时使用；path 必须是本机绝对路径。" +
+        "发送前会先在 QQ 里自动申请审批，用户同意后才会真正上传。",
+      parameters: Type.Object({
+        path: Type.String({ description: "本机文件的绝对路径，例如 D:\\docs\\report.pdf" }),
+        name: Type.Optional(
+          Type.String({ description: "在 QQ 里显示的文件名（含扩展名），默认用原文件名" }),
+        ),
+      }),
+      async execute(_toolCallId: string, params: any) {
+        const text = await sendFileToQQ(state, String(params?.path ?? ""), params?.name ? String(params.name) : undefined);
+        return { content: [{ type: "text", text }], details: { tool: QQ_SEND_FILE_TOOL } };
+      },
+    }),
+  );
+}
+
+/** 取消/停止这类「打断当前任务」的表达 */
+/**
+ * 取消/停止这类「打断当前任务」的表达。
+ *
+ * 注意分工：「停」「停下」「停一下」属于**中断任务**（用户定的：停 = 停止干活）；
+ * 想只关掉进度推送请用「别汇报了」「闭嘴」「/progress off」；
+ * 「停止汇报」因为带了名词，不算取消，走静音。
+ */
+const RE_CANCEL =
+  /^(\/cancel|\/stop|\/abort|取消|停止|中止|终止|算了|停|停下|停一下|停停|停掉|别跑了|cancel|stop|abort)$/i;
+
+function isCancelIntent(text: string): boolean {
+  return RE_CANCEL.test(text.trim());
+}
+
+/** files 配置兜底：老配置 / 测试里可能没这个键 */
+function filesConfig(cfg: QQBotConfig): { enabled: boolean; maxBytes: number } {
+  const raw = (cfg as any)?.files;
+  return {
+    enabled: raw?.enabled ?? true,
+    maxBytes: Number(raw?.maxBytes ?? DEFAULT_SEND_MAX_BYTES),
+  };
+}
+
+/**
+ * 把本机文件发到当前 QQ 对话。
+ * 工具（qq_send_file）与 `/sendfile` 命令共用；失败抛异常，文案由 explainUploadError 翻译。
+ */
+async function sendFileToQQ(state: State, filePath: string, displayName?: string): Promise<string> {
+  const cfg = state.cfg;
+  if (!cfg) throw new Error("还没有接入 QQ bot（会话未就绪）");
+  const files = filesConfig(cfg);
+  if (!files.enabled) throw new Error("发送文件已关闭（配置 files.enabled=false）");
+  const openid = state.currentOpenid ?? state.lastOpenid;
+  if (!openid || !state.api) throw new Error("没有 QQ 会话目标（先让用户从 QQ 发一条消息）");
+  if (!state.restBase || !state.getToken) throw new Error("QQ 凭据未就绪");
+
+  const raw = String(filePath ?? "")
+    .trim()
+    .replace(/^["']|["']$/g, "")
+    .trim();
+  if (!raw) throw new Error("缺少文件路径（用法：/sendfile <绝对路径>）");
+
+  const media = await uploadRichMedia({
+    restBase: state.restBase,
+    openid,
+    getToken: state.getToken,
+    filePath: raw,
+    fileName: displayName,
+    maxBytes: files.maxBytes,
+    log,
+    onProgress: (done, total) => log("[send] 分片", done, "/", total),
+  });
+
+  const ref = state.passiveRefs.get(openid);
+  const usePassive = !!ref && Date.now() - ref.receivedAt < PASSIVE_WINDOW_MS;
+  await state.api.sendC2CMedia(openid, media.fileInfo, usePassive ? { msgId: ref.msgId } : {});
+  log("[send] 已发出", media.fileName, media.size, "bytes", `type=${media.fileType}`);
+  return `已发送「${media.fileName}」（${formatSize(media.size)}，${mediaKindLabel(media.fileType)}）`;
+}
+
+function formatSize(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes < 0) return "?";
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(2)} MB`;
+}
+function attachmentConfig(cfg: QQBotConfig): AttachmentConfig {
+  const raw = (cfg as any)?.attachments;
+  return {
+    enabled: raw?.enabled ?? true,
+    dir: String(raw?.dir ?? "").trim(),
+    maxBytes: Number(raw?.maxBytes ?? DEFAULT_ATTACHMENT_MAX_BYTES),
+    maxPerMessage: Number(raw?.maxPerMessage ?? DEFAULT_ATTACHMENT_MAX_PER_MESSAGE),
+    retentionHours: Number(raw?.retentionHours ?? DEFAULT_ATTACHMENT_RETENTION_HOURS),
+    maxFiles: Number(raw?.maxFiles ?? DEFAULT_ATTACHMENT_MAX_FILES),
+  };
+}
+
+/** 派发失败时最多重试几次（通常是 pi 上一轮还没收尾） */
+const MAX_DISPATCH_ATTEMPTS = 3;
+
+function clearCancelTimer(state: State) {
+  if (state.cancelTimer) {
+    clearTimeout(state.cancelTimer);
+    state.cancelTimer = null;
+  }
+}
+
+/**
+ * 对外看是“忙”：有任务在跑、正在派发，或者队列里还有任务等着（比如派发失败后的重试窗口）。
+ * 这三种情况新消息都应该进队列，而不是插队直接开新一轮。
+ */
+function isBusy(state: State): boolean {
+  return state.busy || state.dispatching || state.queue.size > 0;
+}
+
+/**
+ * /cancel 之后 abort() 是异步的：正常路径靠 agent_settled 释放 busy 并继续队列；
+ * 万一 abort 没能触发 settled（比如那一轮正好已经结束），宽限期后强制解锁。
+ */
+function armCancelWatchdog(pi: ExtensionAPI, state: State) {
+  clearCancelTimer(state);
+  const timer = setTimeout(() => {
+    state.cancelTimer = null;
+    if (!state.cancelled) return;
+    log("[cancel] abort 后", CANCEL_SETTLE_GRACE_MS, "ms 内没有 agent_settled，强制释放 busy");
+    state.cancelled = false;
+    state.busy = false;
+    state.ctx = null;
+    state.currentOpenid = null;
+    state.replyBuffer.reset();
+    drainQueue(pi, state);
+  }, CANCEL_SETTLE_GRACE_MS);
+  (timer as any).unref?.();
+  state.cancelTimer = timer;
+}
+
+/**
+ * 把一条任务交给 pi，并把它标记为「当前任务」。
+ * 不 await sendUserMessage：它返回的 promise 要等整轮跑完，await 会卡住调用方
+ * （agent_settled 里派发时更是不允许）。错误交给 onDispatchError 重试/回执。
+ */
+function startJob(pi: ExtensionAPI, state: State, job: QueuedJob) {
+  state.currentOpenid = job.openid;
+  state.lastOpenid = job.openid;
+  state.pickerOwner = job.openid;
+  state.bridgeReply = (text: string) => {
+    void replyTo(state.api!, state, job.openid, text);
+  };
+  state.busy = true;
+  state.cancelled = false;
+  state.runStarted = false;
+  state.replyBuffer.reset();
+  clearCancelTimer(state);
+  log(
+    "[msg] 送入 pi:",
+    job.id > 0 ? `队列 #${job.id}` : "直接",
+    "openid=",
+    job.openid,
+    "text=",
+    job.text.slice(0, 60),
+  );
+  // 每会话第一条真正跑起来的 QQ 消息，由 before_agent_start 注入远程上下文说明。
+  try {
+    void Promise.resolve(
+      pi.sendUserMessage(job.text, { expandPromptTemplates: true, deliverAs: "followUp" }),
+    ).catch((error) => onDispatchError(pi, state, job, error));
+  } catch (error) {
+    onDispatchError(pi, state, job, error);
+  }
+}
+
+/** 派发失败：先重试（放回队首），多次失败就把错误回给发送者并继续队列 */
+function onDispatchError(pi: ExtensionAPI, state: State, job: QueuedJob, error: unknown) {
+  const message = String((error as any)?.message ?? error).slice(0, 200);
+  log("[msg] 派发失败:", message);
+  if (state.runStarted) {
+    // run 已经启动了：这次报错属于这一轮自己的问题，收尾交给 agent_settled，不能重试
+    log("[msg] 本轮已启动过 agent，不重试，等 agent_settled 收尾");
+    return;
+  }
+  state.busy = false;
+  state.currentOpenid = null;
+  job.attempts += 1;
+  if (job.attempts < MAX_DISPATCH_ATTEMPTS) {
+    state.queue.unshift(job);
+    log("[msg]", DISPATCH_RETRY_MS, "ms 后重试（第", job.attempts, "次）");
+    const timer = setTimeout(() => drainQueue(pi, state), DISPATCH_RETRY_MS);
+    (timer as any).unref?.();
+    return;
+  }
+  const api = state.api;
+  if (api) void replyTo(api, state, job.openid, `这条消息执行失败：${message}`);
+  drainQueue(pi, state);
+}
+
+/**
+ * 同步一份「当前真正生效的模型」到 state：
+ * 1. 欠费后用户发新 key 时，要知道落到哪个 provider；
+ * 2. 探测新 key 需要 baseUrl，只有 ctx.model 里有。
+ */
+function syncModelFromCtx(state: State, ctx: any): void {
+  const model = ctx?.model;
+  if (!model?.provider || !model?.id) return;
+  state.lastModel = {
+    provider: String(model.provider),
+    modelId: String(model.id),
+    baseUrl: typeof model.baseUrl === "string" ? model.baseUrl : state.lastModel?.baseUrl,
+  };
+}
+
+/** 把检测用的 fetch 换成注入实现（单测用），默认 globalThis.fetch */
+function probeFetch(state: State): typeof fetch {
+  return state.attachmentFetch ?? fetch;
+}
+
+/** 裸 key 只在欠费上下文里认（平时贴一串随机字符不应当被吞掉）；带显式前缀的总认 */
+export function shouldAcceptCredential(billing: boolean, intake: CredentialIntake | null): boolean {
+  return !!intake && (intake.explicit || billing);
+}
+
+/**
+ * 欠费/鉴权失败后，用户在 QQ 里直接发来的凭据：
+ *   - 新 key → 写 auth.json（并真探测一次）
+ *   - endpoint + key → 写 models.json + registerProvider（当前进程立即生效），
+ *     再把模型列表做成编号选择发回给用户。
+ * 明文 key 不进日志、不回显（只回 maskSecret 片段）。
+ */
+async function handleCredentialIntake(
+  pi: ExtensionAPI,
+  state: State,
+  api: QQApi,
+  msg: QQMessage,
+  intake: CredentialIntake,
+): Promise<void> {
+  const reply = async (text: string) => {
+    await replyTo(api, state, msg.openid, text);
+  };
+  const target = state.lastModel;
+
+  if (intake.kind === "key") {
+    const provider = target?.provider || state.billing?.provider || "";
+    if (!provider) {
+      await reply(
+        "我还不知道当前用的是哪个 provider。先发 /model 看当前模型，或发「https://api.xxx.com/v1 <你的 key>」注册新服务。",
+      );
+      return;
+    }
+    log("[billing] 收到新 key", maskSecret(intake.key), "provider=", provider);
+    const written = await updateProviderKey(provider, intake.key);
+    if (!written.ok) {
+      await reply(`❌ 写入 auth.json 失败：${written.error ?? "未知错误"}`);
+      return;
+    }
+    const modelLabel =
+      target && target.provider === provider
+        ? `${provider}/${target.modelId}`
+        : state.billing
+          ? `${provider}/${state.billing.modelId}`
+          : provider;
+    const baseUrl = target?.baseUrl ?? null;
+    let probe: ProbeResult | null = null;
+    if (baseUrl) {
+      probe = await probeEndpoint(baseUrl, intake.key, probeFetch(state));
+      log("[billing] 新 key 探测:", baseUrl, probe.ok ? "ok" : `失败 ${probe.error ?? probe.status ?? "?"}`);
+    }
+    const lines = [`✅ 已更新 ${provider} 的 key（${maskSecret(intake.key)}），当前模型：${modelLabel}`];
+    if (probe?.ok) {
+      lines.push(`探测通过（${probe.url} 返回 ${probe.ids.length} 个模型）：直接再发一次刚才的问题就行。`);
+    } else if (probe) {
+      lines.push(`已保存，但探测没通过：${probe.error ?? "未知原因"}。key 可能无效，或该服务没有 /models 接口。`);
+    } else {
+      lines.push("没记录到 baseUrl，无法自动探测；发一条普通消息就能验证是否生效。");
+    }
+    state.billing = null;
+    await reply(lines.join("\n"));
+    return;
+  }
+
+  // ---- endpoint + key：注册新 provider，然后让用户选模型 ----
+  const base = normalizeBaseUrl(intake.baseUrl);
+  log("[billing] 收到 endpoint", base, "key=", maskSecret(intake.key), "显式模型=", intake.models.length);
+  const probe = await probeEndpoint(intake.baseUrl, intake.key, probeFetch(state));
+  const rawIds = intake.models.length > 0 ? intake.models : probe.ids;
+  if (rawIds.length === 0) {
+    const why = probe.ok
+      ? "该服务的 /models 没有返回任何模型"
+      : `探测失败：${probe.error ?? `HTTP ${probe.status ?? "?"}`}`;
+    await reply(
+      [
+        `❌ ${base} 暂时用不了（${why}）`,
+        "如果它没有 /models 接口，可以带上模型 id 再发一次：",
+        "<endpoint> <key> models 模型1,模型2",
+      ].join("\n"),
+    );
+    return;
+  }
+  const providerId = providerIdForEndpoint(intake.baseUrl, existingProviderIds());
+  // `/models` 通常只给 id，没有上下文窗/输出上限；先从 pi 已有目录里同 id 的模型借（
+  // 比如 glm-5.3 在 zai / zai-coding-cn 下已带 contextWindow=1e6、maxTokens=131072）。
+  const catalog = (state.registryCtx?.modelRegistry?.getAll?.() ?? []) as any[];
+  const ids = filterChatModelIds(rawIds.slice(0, 40));
+  if (ids.length === 0) {
+    await reply(`❌ ${base} 只返回了非对话类模型（embedding/rerank 等），没法当聊天模型用。`);
+    return;
+  }
+  const metas = ids.map((id) => borrowModelMeta(id, catalog, base));
+  const models = ids.map((id, index) => providerModelConfig(id, metas[index]));
+  const borrowed = metas.filter(Boolean).length;
+  log("[billing] 模型元数据：共", ids.length, "个，借到", borrowed, "个");
+  const written = await upsertEndpointProvider({
+    providerId,
+    baseUrl: intake.baseUrl,
+    apiKey: intake.key,
+    models,
+  });
+  if (!written.ok) {
+    await reply(`❌ 写入 models.json 失败：${written.error ?? "未知错误"}`);
+    return;
+  }
+  // models.json 负责重启后仍在；registerProvider 让当前进程立刻能用（无需 /reload）
+  try {
+    pi.registerProvider(providerId, {
+      name: `QQ 接入 (${providerId})`,
+      baseUrl: base,
+      api: "openai-completions",
+      apiKey: intake.key,
+      models: models as any,
+    });
+  } catch (error) {
+    log("[billing] registerProvider 失败（重启后仍可用）:", String(error).slice(0, 160));
+  }
+  state.picker = {
+    kind: "model",
+    items: models.slice(0, MODEL_PICK_LIMIT).map((model, index) => ({
+      id: `${providerId}/${model.id}`,
+      label: modelLabel(model.id, metas[index]),
+    })),
+    openid: msg.openid,
+    createdAt: Date.now(),
+  };
+  state.billing = null;
+  log("[billing] 已注册 provider", providerId, "模型数", models.length, "→ 发编号选择");
+  await reply(formatModelPicker(providerId, base, models, borrowed));
+}
+
+/** 当前任务结束后，取队列里的下一条开始执行（空闲时才会真的派发） */
+function drainQueue(pi: ExtensionAPI, state: State) {
+  if (state.busy || state.dispatching) return;
+  const job = state.queue.shift();
+  if (!job) return;
+  state.dispatching = true;
+  try {
+    log("[queue] 出队 #", job.id, "剩余", state.queue.size, "条", "text=", job.text.slice(0, 60));
+    const api = state.api;
+    if (api && state.cfg?.queue.ack !== false) {
+      const rest = state.queue.size > 0 ? `（后面还有 ${state.queue.size} 条）` : "";
+      void replyTo(api, state, job.openid, `开始执行队列 #${job.id}${rest}`);
+    }
+    startJob(pi, state, job);
+  } finally {
+    state.dispatching = false;
+  }
+}
+
+/** 入队（忙碌时的统一入口）：回执排队位置 */
+async function enqueueJob(
+  api: QQApi,
+  state: State,
+  openid: string,
+  text: string,
+): Promise<boolean> {
+  const result = state.queue.push(openid, text);
+  if (!result.ok) {
+    log("[queue] 队列已满（上限", state.queue.max, "），拒绝入队");
+    if (state.queue.max === 0) {
+      await replyTo(api, state, openid, "上一条消息还在处理中，请稍候…（队列已关闭：queue.max=0）");
+      return false;
+    }
+    await replyTo(
+      api,
+      state,
+      openid,
+      `队列已满（上限 ${state.queue.max} 条），这条没排上。发 /queue 查看队列，或 /cancel 清空后重发。`,
+    );
+    return false;
+  }
+  log("[queue] 入队 #", result.job.id, "size=", state.queue.size, "ahead=", result.ahead);
+  await replyTo(
+    api,
+    state,
+    openid,
+    `已排队 #${result.job.id}${result.ahead > 0 ? `（前面还有 ${result.ahead} 条）` : ""}，当前任务结束后自动执行。发 /queue 查看队列，/cancel 可中止当前任务并清空队列。`,
+  );
+  return true;
+}
+
+function formatQueue(state: State): string {
+  const lines = [`当前任务：${state.busy ? "处理中（发 /cancel 可中断）" : "空闲"}`];
+  const jobs = state.queue.list();
+  if (jobs.length === 0) {
+    lines.push("队列：空");
+    return lines.join("\n");
+  }
+  lines.push(`队列：${jobs.length} 条（上限 ${state.queue.max}）`);
+  jobs.slice(0, 10).forEach((job, index) => {
+    lines.push(`  ${index + 1}. #${job.id} · ${agoLabel(job.enqueuedAt)} · ${previewText(job.text)}`);
+  });
+  if (jobs.length > 10) lines.push(`  … 还有 ${jobs.length - 10} 条`);
+  lines.push("发 /queue clear 清空，/queue drop <编号> 删除一条。");
+  return lines.join("\n");
+}
+
+/**
+ * 用户发来取消指令：终止待审批、清空队列、abort 当前 run、丢弃半截回复，然后回执。
+ * 取消本身永不入队（“取消除外”），立即生效。
+ * （「取消自动同意」/「关闭自动同意」不属于取消指令，仍走审批分支。）
+ */
+async function handleCancel(
+  pi: ExtensionAPI,
+  state: State,
+  api: QQApi,
+  openid: string,
+): Promise<void> {
+  const terminated = state.approver.terminateAll();
+  const dropped = state.queue.clear();
+  const running = state.busy || Boolean(state.ctx?.signal);
+  if (!running) {
+    const parts: string[] = [];
+    if (terminated > 0) parts.push(`已终止 ${terminated} 个待审批请求`);
+    if (dropped.length > 0) parts.push(`已清空队列（${dropped.length} 条）`);
+    await replyTo(
+      api,
+      state,
+      openid,
+      parts.length > 0
+        ? `${parts.join("，")}，当前没有正在运行的任务。`
+        : "当前没有正在运行的任务。",
+    );
+    return;
+  }
+
+  stopProgressTimer(state);
+  state.progress.stop();
+  state.cancelled = true;
+  state.replyBuffer.reset();
+  state.currentOpenid = null; // 被中止的 run 不再往 QQ 发半截回复
+  const ctx = state.ctx;
+  state.ctx = null;
+  try {
+    ctx?.abort();
+    log("[cancel] 已请求中止当前 run，终止待审批", terminated, "个，清空队列", dropped.length, "条");
+  } catch (e) {
+    log("[cancel] abort 失败:", String(e));
+  }
+  // busy 保持 true 直到 agent_settled：期间新消息会排队，不会和正在收尾的 run 撞车
+  armCancelWatchdog(pi, state);
+  const notice: string[] = [];
+  if (terminated > 0) notice.push(`并终止了 ${terminated} 个待审批请求`);
+  if (dropped.length > 0) notice.push(`队列中的 ${dropped.length} 条已清空`);
+  await replyTo(
+    api,
+    state,
+    openid,
+    `已取消当前任务${notice.length > 0 ? `，${notice.join("，")}` : ""}。可以发送新消息继续。`,
+  );
+}
+
+// ---- QQ 消息处理 ----
+export async function handleMessage(
+  pi: ExtensionAPI,
+  state: State,
+  api: QQApi,
+  cfg: QQBotConfig,
+  msg: QQMessage,
+) {
+  try {
+    log("[msg] 收到消息 openid=", msg.openid, "content=", msg.content.slice(0, 100));
+    if (cfg.allowlist.length > 0 && !cfg.allowlist.includes(msg.openid)) {
+      log("[msg] 被 allowlist 拦截");
+      return;
+    }
+    state.passiveRefs.set(msg.openid, { msgId: msg.msgId, receivedAt: Date.now() });
+
+    // ---- 附件落盘：图片 / 语音 / 视频 / 文档 / 压缩包 / 普通文件 ----
+    // 落盘后拼成「图片路径 <path>」这类标记行交给 pi；有附件时绕过 picker/指令/审批路由
+    const attachments = msg.attachments ?? [];
+    const hasAttachment = attachments.length > 0;
+    let incoming = msg.content;
+    if (hasAttachment) {
+      const acc = attachmentConfig(cfg);
+      if (!acc.enabled) {
+        const names = attachments.map((a, i) => a.filename || `附件 ${i + 1}`).join("、");
+        log("[attachment] 已被配置忽略", attachments.length, "个附件");
+        await replyTo(
+          api,
+          state,
+          msg.openid,
+          `已忽略 ${attachments.length} 个附件（配置 attachments.enabled=false）：${names}。本次只处理文字内容。`,
+        );
+        if (!msg.content.trim()) return; // 纯附件 + 已忽略：不给 pi 送空消息
+      } else {
+        const dir = acc.dir || defaultAttachmentDir(cfg.appId);
+        const { saved, failed } = await saveIncoming(attachments, {
+          dir,
+          maxBytes: acc.maxBytes,
+          maxPerMessage: acc.maxPerMessage,
+          fetchFn: state.attachmentFetch ?? undefined,
+          credential: state.getToken,
+          prefix: msg.msgId,
+        });
+        log(
+          "[attachment] 落盘",
+          saved.length,
+          "个，失败",
+          failed.length,
+          "个 →",
+          saved.map((s) => `${s.kind}:${s.name}`).join(", ") || "(无)",
+        );
+        const ack = renderAttachmentAck(saved, failed);
+        if (ack) await replyTo(api, state, msg.openid, ack);
+        incoming = [msg.content.trim(), ...renderAttachmentLines(saved), ...renderAttachmentFailureLines(failed)]
+          .filter(Boolean)
+          .join("\n");
+        if (!incoming) return; // 全部失败且无正文：已经回执过，不再送空消息
+      }
+    }
+
+    // 上一条最终答案没发出去（配额耗尽）：先补发
+    if (state.undelivered && state.undelivered.openid === msg.openid) {
+      const pending = state.undelivered;
+      state.undelivered = null;
+      log("[reply] 补发上一条未送达的回复，长度", pending.text.length);
+      const ok = await replyTo(api, state, msg.openid, `（上一条回复发送失败，补发如下）\n\n${pending.text}`);
+      if (!ok) {
+        state.undelivered = pending;
+        log("[reply] 补发仍然失败，继续保留");
+      }
+    }
+
+    // 待选择的编号回复（/tree、/fork、/resume 之后）；带附件时不当作编号选择
+    if (!hasAttachment && state.picker) {
+      if (pickerExpired(state.picker)) {
+        state.picker = null;
+      } else if (state.picker.openid === msg.openid) {
+        const index = parsePickIndex(msg.content);
+        if (index !== null) {
+          if (state.busy) {
+            await replyTo(api, state, msg.openid, "当前有任务在跑，先发 /cancel 取消，再回编号。");
+            return;
+          }
+          if (index > state.picker.items.length) {
+            await replyTo(api, state, msg.openid, `编号 ${index} 超出范围（1-${state.picker.items.length}）。`);
+            return;
+          }
+          state.pickerOwner = msg.openid;
+          state.bridgeReply = (text: string) => {
+            void replyTo(api, state, msg.openid, text);
+          };
+          log("[cmd] 选择编号", index, "kind=", state.picker.kind);
+          pi.sendUserMessage(`/qq pick ${index}`, { expandPromptTemplates: true });
+          return;
+        }
+        if (/^(取消|算了|cancel)$/i.test(msg.content.trim())) {
+          state.picker = null;
+          await replyTo(api, state, msg.openid, "已放弃选择。");
+          return;
+        }
+      }
+    }
+
+    // 欠费/鉴权失败后的「凭据接手」：用户直接发 key，或 endpoint + key。
+    // 裸 key 只在欠费上下文里认（平时用户贴一串随机字符不该被吞掉）；带显式前缀的总认。
+    if (!hasAttachment) {
+      const intake = parseCredentialMessage(incoming);
+      if (shouldAcceptCredential(!!state.billing, intake) && intake) {
+        log("[billing] 识别为凭据接手:", intake.kind, intake.explicit ? "(显式)" : "(裸 key)");
+        await handleCredentialIntake(pi, state, api, msg, intake);
+        return;
+      }
+    }
+
+    // 取消指令优先于审批解析：「取消」不该被当成审批动作；取消也永不入队
+    if (isCancelIntent(msg.content)) {
+      await handleCancel(pi, state, api, msg.openid);
+      return;
+    }
+
+    // 「更新自己」：在线升级 pi-qqbot（npm + pi update + 重载），优先于斜杠路由
+    if (isUpdateSelfIntent(msg.content)) {
+      if (!cfg.commands?.allowUpdate) {
+        await replyTo(api, state, msg.openid, "自我更新在 QQ 侧被禁用（配置 commands.allowUpdate=true 可开启）。也可直接发 /update。");
+        return;
+      }
+      if (isBusy(state)) {
+        await replyTo(api, state, msg.openid, "当前有任务在跑，先发 /cancel 取消，再更新。");
+        return;
+      }
+      await runSelfUpdate({
+        currentVersion: installedVersion(),
+        checkLatest: () => checkLatestVersion(shellRunner),
+        applyUpdate: () => applyUpdate(shellRunner),
+        versionAfterUpdate: () => installedVersion(),
+        reply: (text) => replyTo(api, state, msg.openid, text),
+        // 更新后走 pi 自己的 reload：sendUserMessage("/qq reload") 与 takeover 同路径
+        reload: () => {
+          try {
+            void Promise.resolve(pi.sendUserMessage("/qq reload", { expandPromptTemplates: true })).catch((error) =>
+              log("[update] 重载派发失败:", String((error as any)?.message ?? error)),
+            );
+          } catch (error) {
+            log("[update] 重载派发异常:", String(error));
+          }
+        },
+      });
+      return;
+    }
+
+    // 斜杠命令路由：pi 扩展命令 → 可接管的内置命令 → 仅主机可用的内置命令 → 普通文字
+    state.lastOpenid = msg.openid;
+    state.pickerOwner = msg.openid;
+    state.bridgeReply = (text: string) => {
+      void replyTo(api, state, msg.openid, text);
+    };
+    const routed = hasAttachment
+      ? ("text" as const)
+      : await routeSlash(
+      {
+        listPiCommands: () => (pi.getCommands?.() ?? []) as { name: string; source?: string }[],
+        dispatch: (text, options) => {
+          // 提示模板 / /skill: 会开启一轮 agent run：和普通对话一样串行到队列
+          if (options?.runsTurn) {
+            if (!isBusy(state)) {
+              startJob(pi, state, state.queue.mint(msg.openid, text));
+              return "dispatched";
+            }
+            const queued = state.queue.push(msg.openid, text);
+            if (!queued.ok) {
+              log("[queue] 队列已满，命令未排队:", text.slice(0, 60));
+              return "rejected";
+            }
+            log("[queue] 命令入队 #", queued.job.id, text.slice(0, 60));
+            return "queued";
+          }
+          // 扩展命令 / 桥接命令（/qq …）不开 run，pi 允许流式期间执行，直接派发
+          void Promise.resolve(pi.sendUserMessage(text, { expandPromptTemplates: true })).catch(
+            (e) => log("[cmd] 派发失败:", String(e)),
+          );
+          return "dispatched";
+        },
+        reply: (text: string) => replyTo(api, state, msg.openid, text),
+        busy: isBusy(state),
+        cfg: cfg.commands,
+        log,
+      },
+      msg.content,
+    );
+    if (routed !== "text") return;
+
+    // 远程审批回复优先（带附件时不当作审批动作）
+    const parsed = hasAttachment ? null : state.approver.parseReply(msg.content.trim());
+    if (parsed) {
+      if (parsed.decision === "terminate") {
+        const n = state.approver.terminateAll();
+        state.approver.setAutoAllow(false);
+        await replyTo(api, state, msg.openid, `已终止 ${n} 个待审批请求，自动同意已关闭`);
+        return;
+      }
+      if (parsed.decision === "always") {
+        // 「以后都同意」= 本会话内全部放行：立刻开启开关并放行当前所有待审批
+        state.approver.setAutoAllow(true);
+        const n = state.approver.allowAll();
+        log("[approve] 开启会话级自动同意，放行", n, "个待审批");
+        await replyTo(
+          api,
+          state,
+          msg.openid,
+          [
+            `已开启自动同意：本会话内需审批的工具全部放行${n > 0 ? `，已放行 ${n} 个待审批请求` : ""}。`,
+            "回复「取消自动同意」或 /new 恢复逐条审批。",
+          ].join("\n"),
+        );
+        return;
+      }
+      if (parsed.decision === "revoke") {
+        const was = state.approver.autoAllowed;
+        state.approver.setAutoAllow(false);
+        log("[approve] 关闭自动同意 was=", was);
+        await replyTo(
+          api,
+          state,
+          msg.openid,
+          was ? "已关闭自动同意，恢复逐条审批。" : "当前没有开启自动同意，仍需逐条审批。",
+        );
+        return;
+      }
+      // allow / block：没写编号时作用于最早的一条待审批
+      const seq = parsed.seq ?? state.approver.oldestSeq();
+      if (seq !== undefined) {
+        const ok = state.approver.confirm(seq, parsed.decision);
+        const text = !ok
+          ? `#${seq} 不存在或已超时`
+          : parsed.decision === "allow"
+            ? `已批准 #${seq}`
+            : `已拒绝 #${seq}`;
+        await replyTo(api, state, msg.openid, text);
+        return;
+      }
+      // 没有待审批：这句「同意/拒绝」当普通消息交给 pi，继续往下走
+      log("[msg] 审批类文本但无待审批，按普通消息处理");
+    }
+
+    // 内置指令（带附件时绕过：附件消息一律当普通内容交给 pi）
+    const cmd = hasAttachment ? null : parseCommand(msg.content);
+    if (cmd?.name === "help") {
+      await replyTo(
+        api,
+        state,
+        msg.openid,
+        [
+          "pi-qqbot 指令:",
+          "/progress — 查看进度；/progress off 暂停自动汇报、/progress on 恢复（本会话有效）",
+          "/status — 查看状态（当前 qqbot / 忙闲 / 来源 / 队列 / 自动同意 / 待审批 / 自动汇报）",
+          "/queue — 查看队列；/queue clear 清空；/queue drop <编号> 删一条",
+          "/reset — 清空回复缓冲、审批记忆与自动同意（不换会话；换会话发 /new）",
+          "/cancel（或「取消」「停止」「停」）— 中断正在运行的任务并清空队列",
+          "/sendfile <路径> — 把本机文件发到你的 QQ（png/jpg/mp4/silk 直显，其余为文件卡片；外发需审批）",
+          "只关进度推送：/progress off（或「别汇报了」「闭嘴」）；「停」是中断任务，不是静音",
+          "/help — 帮助",
+          "pi 的命令优先：/reload /new /compact /session /name /model /thinking，以及扩展命令、模板与 /skill:xxx。",
+          "忙碌时发来的普通消息（含模板/skill 命令）会排队，当前任务结束后自动执行。",
+          "多 bot：配置了多个 qqbot 时，多个 pi 进程会按列表顺序各自接入一个，抢不到的待命重扫。",
+          "其余文本交给 pi 当作对话处理。",
+        ].join("\n"),
+      );
+      return;
+    }
+    if (cmd?.name === "status") {
+      const lines = [
+        `bot: ${state.account ? `${state.account.name} (…${state.account.appId.slice(-4)})` : "未接入"} · cwd: ${process.cwd()}`,
+        `状态: ${state.busy ? "处理中（发送 /cancel 可中断）" : state.queue.size > 0 ? "空闲，但有排队任务待派发" : "空闲"}`,
+        `来源: ${describeRunOrigin(state)}`,
+        `队列: ${state.queue.size} 条待执行${state.queue.size > 0 ? "（发 /queue 查看）" : ""}`,
+        `自动同意: ${state.approver.autoAllowed ? "已开启（本会话有效）" : "未开启"}`,
+        `待审批: ${state.approver.pendingCount}`,
+        `自动汇报: ${describeProgressMode(state)}`,
+      ];
+      if (state.busy) {
+        const snapshot = state.progress.summary();
+        if (snapshot) lines.push("", snapshot);
+        // 用户主动问询：恢复自动推送（手动暂停的不算）
+        if (!state.progressMuted) state.progressPaused = false;
+      }
+      await replyTo(api, state, msg.openid, lines.join("\n"));
+      return;
+    }
+    if (cmd?.name === "progress") {
+      const sub = (cmd.args ?? "").trim().toLowerCase();
+      if (MUTE_ARGS.has(sub)) {
+        const was = state.progressMuted;
+        state.progressMuted = true;
+        state.progressPaused = false;
+        log("[progress] 用户暂停自动进度推送（本会话有效）", was ? "（已经是暂停状态）" : "");
+        await replyTo(
+          api,
+          state,
+          msg.openid,
+          was
+            ? "自动汇报本来就已暂停。发 /progress on（或「恢复汇报」）可以恢复。"
+            : "已暂停自动进度汇报（本会话有效，换会话或重启后恢复默认开启）。需要时发 /progress 仍可查看一次，发 /progress on 恢复。",
+        );
+        return;
+      }
+      if (UNMUTE_ARGS.has(sub)) {
+        const was = state.progressMuted;
+        state.progressMuted = false;
+        state.progressPaused = false;
+        log("[progress] 用户恢复自动进度推送");
+        await replyTo(
+          api,
+          state,
+          msg.openid,
+          was
+            ? `已恢复自动进度汇报${state.cfg?.progress?.enabled === false ? "（但配置 progress.enabled=false，仍不会推送）" : ""}。`
+            : "自动汇报本来就是开启的。",
+        );
+        return;
+      }
+      if (sub) {
+        await replyTo(
+          api,
+          state,
+          msg.openid,
+          "用法: /progress（看一次）| /progress off（暂停自动汇报）| /progress on（恢复）。也可以说「暂停汇报」「恢复汇报」。",
+        );
+        return;
+      }
+      const snapshot = state.progress.summary();
+      if (!state.progressMuted) state.progressPaused = false;
+      const body = snapshot || (state.busy ? "当前任务刚启动，还没有可汇报的进度。" : "当前没有正在运行的任务。");
+      await replyTo(
+        api,
+        state,
+        msg.openid,
+        state.progressMuted ? `${body}\n（自动汇报已暂停，发 /progress on 恢复）` : body,
+      );
+      return;
+    }
+    if (cmd?.name === "queue") {
+      await handleQueueCommand(api, state, msg.openid, cmd.args);
+      return;
+    }
+    if (cmd?.name === "reset") {
+      state.replyBuffer.reset();
+      state.approver.reset();
+      await replyTo(api, state, msg.openid, "已重置（回复缓冲/审批记忆/自动同意）。要开新会话请发 /new。");
+      return;
+    }
+
+    // 忙检查：单会话串行处理——忙碌时入队，当前任务结束后自动继续
+    if (isBusy(state)) {
+      // 忙碌时问「进度」不该排队，直接回当前进度并恢复自动推送
+      if (!hasAttachment && RE_PROGRESS_QUERY.test(msg.content.trim())) {
+        const snapshot = state.progress.summary();
+        if (!state.progressMuted) state.progressPaused = false;
+        await replyTo(api, state, msg.openid, snapshot || "任务刚启动，还没有可汇报的进度。");
+        return;
+      }
+      await enqueueJob(api, state, msg.openid, incoming);
+      return;
+    }
+
+    // ack
+    await replyTo(api, state, msg.openid, "收到，正在处理");
+
+    startJob(pi, state, state.queue.mint(msg.openid, incoming));
+  } catch (e) {
+    log("[msg] 处理失败:", String(e));
+    await replyTo(api, state, msg.openid, `处理失败: ${String(e).slice(0, 200)}`).catch(() => {});
+  }
+}
+
+async function replyTo(
+  api: QQApi,
+  state: State,
+  openid: string,
+  text: string,
+  format: "text" | "markdown" = "text",
+): Promise<boolean> {
+  // 本进程刚接入 / 刚接管这个 qqbot：第一条回执带上身份与工作目录
+  if (state.claimNote) {
+    const note = state.claimNote;
+    state.claimNote = null;
+    text = `${note}\n${text}`;
+  }
+  const ref = state.passiveRefs.get(openid);
+  let delivered = true;
+  for (const chunk of splitText(text)) {
+    const usePassive = !!ref && Date.now() - ref.receivedAt < PASSIVE_WINDOW_MS;
+    try {
+      await api.sendC2C(openid, chunk, usePassive ? { msgId: ref.msgId, format } : { format });
+      log("[reply] 已发送 (passive=", usePassive, "):", chunk.slice(0, 50));
+    } catch (e) {
+      delivered = false;
+      log("[reply] 发送失败:", String(e));
+    }
+  }
+  return delivered;
+}
+
+/** 用户问进度的表达（忙碌时用来区分「排队」和「问进度」） */
+// 忙碌时判断「这是在问进度」：只认句首的明确表达，避免把「帮我加个进度条」这类任务误当问询
+const RE_PROGRESS_QUERY = new RegExp(
+  "^(?:" +
+    "\\/(?:progress|p|status)" +
+    "|(?:现在|当前|目前)?\\s*(?:的)?\\s*(?:progress|进度|进展)" +
+    "|跑到哪|怎么样了|到哪了|还在跑吗|好慢" +
+  ")",
+  "i",
+);
+
+function startProgressTimer(pi: ExtensionAPI, state: State) {
+  stopProgressTimer(state);
+  const cfg = state.cfg?.progress;
+  if (!cfg?.enabled) return;
+  const interval = Number.isFinite(cfg.intervalMs) && cfg.intervalMs >= 50 ? cfg.intervalMs : 15000;
+  const timer = setInterval(() => {
+    void pushProgress(state, "tick");
+  }, interval);
+  (timer as any).unref?.();
+  state.progressTimer = timer;
+  log("[progress] 自动进度推送已启动，间隔", interval, "ms");
+}
+
+function stopProgressTimer(state: State) {
+  if (state.progressTimer) {
+    clearInterval(state.progressTimer);
+    state.progressTimer = null;
+  }
+}
+
+/** 推一条进度摘要；失败就暂停自动推送（用户问一次即恢复）；手动暂停（/progress off）管到底 */
+async function pushProgress(state: State, reason: "tick" | "ask"): Promise<boolean> {
+  if (reason === "tick" && (state.progressPaused || state.progressMuted)) return false;
+  // 有审批在等用户回复：暂停自动推送，否则每 15s 一条进度会把审批提示顶出屏幕
+  // （手动问进度不受影响：用户自己要看的）
+  if (reason === "tick" && state.approver.pendingCount > 0) {
+    if (!state.progressHeldForApproval) {
+      state.progressHeldForApproval = true;
+      log("[progress] 有", state.approver.pendingCount, "个待审批，暂缓自动进度推送");
+    }
+    return false;
+  }
+  const api = state.api;
+  const openid = state.currentOpenid ?? state.lastOpenid;
+  if (!api || !openid || !state.busy || !state.progress.running) return false;
+  if (state.progressHeldForApproval) {
+    state.progressHeldForApproval = false;
+    log("[progress] 审批已处理，恢复自动进度推送");
+  }
+  const text = state.progress.summary();
+  if (!text) return false;
+  const ok = await replyTo(api, state, openid, text);
+  if (!ok) {
+    state.progressPaused = true;
+    log("[progress] 推送失败（多半是配额），暂停自动进度推送，直到用户询问");
+  }
+  return ok;
+}
+
+/** /status 用：最近一轮对话是谁发起的 */
+function describeRunOrigin(state: State): string {
+  if (state.lastRunOrigin === "qq") return "QQ（远程）";
+  if (state.lastRunOrigin === "local") return "本机（TUI）";
+  return "尚未开始";
+}
+
+/** 自动汇报当前状态的人话描述（/status 用） */
+function describeProgressMode(state: State): string {
+  const cfg = state.cfg?.progress;
+  if (state.progressMuted) return "已暂停（本会话，发 /progress on 恢复）";
+  if (cfg?.enabled === false) return "未启用（配置 progress.enabled=false）";
+  if (state.progressPaused) return "推送失败已静默，发 /progress 恢复";
+  const ms = Number.isFinite(cfg?.intervalMs) && (cfg?.intervalMs ?? 0) >= 50 ? cfg!.intervalMs : 15000;
+  const base = `开启（每 ${Math.round(ms / 1000)}s）`;
+  return state.approver.pendingCount > 0 ? `${base}，等审批期间暂缓` : base;
+}
+
+/** /progress 的子命令：暂停 / 恢复自动汇报 */
+const MUTE_ARGS = new Set([
+  "off",
+  "pause",
+  "stop",
+  "mute",
+  "关",
+  "关闭",
+  "关掉",
+  "停",
+  "停止",
+  "暂停",
+  "暂停汇报",
+  "停止汇报",
+]);
+const UNMUTE_ARGS = new Set([
+  "on",
+  "resume",
+  "start",
+  "unmute",
+  "开",
+  "开启",
+  "打开",
+  "恢复",
+  "继续",
+  "恢复汇报",
+  "开启汇报",
+  "继续汇报",
+]);
+
+/**
+ * 不带斜杠的口令（整句匹配，避免误伤正常聊天）。
+ *
+ * 三类：
+ * 1. 问进度：「汇报一下当前进度」「看一下进度」「进度如何」→ 回一次摘要
+ * 2. 静音：「暂停汇报进度」「别汇报了」「别说了」「闭嘴」「停」→ 暂停自动汇报
+ * 3. 恢复：「恢复汇报」「接着说」→ 重新打开自动汇报
+ *
+ * 注意：「停止/取消/中止」是**中断任务**（RE_CANCEL，更早判定），不是静音；
+ * 「停止汇报」才走静音。
+ */
+const REPORT_LEAD = "(?:请|帮我|给我|麻烦|暂时|先)?\\s*";
+/** 汇报名词的两种语序（进度汇报 / 汇报进度） */
+const REPORT_NOUN =
+  "(?:(?:进度|进展)(?:汇报|报告|推送|播报|上报)?|(?:汇报|报告|推送|播报|上报)(?:进度|进展)?)";
+const REPORT_TAIL = "\\s*(?:了|吧|哦|啊|呀|嘛|啦|呗)*";
+
+/** 问进度（含「汇报一下…」这类祈使句） */
+const BARE_PROGRESS_RE = new RegExp(
+  "^" +
+    REPORT_LEAD +
+    "(?:(?:汇报|报告|报|说说|讲讲|看|看看|查|查查|查看|显示|展示)(?:一下|下|个|一眼)?\\s*)?" +
+    "(?:当前|现在|目前)?\\s*(?:的)?\\s*(?:progress|进度|进展)" +
+    "(?:\\s*(?:如何|怎么样|怎样|呢|啦|了|吗))?" +
+    "(?:\\s+([\\s\\S]*))?$",
+  "i",
+);
+
+/** 静音：带「汇报」名词的 */
+const RE_REPORTS_OFF = new RegExp(
+  "^" +
+    REPORT_LEAD +
+    "(?:暂停|停止|停下|关闭|关掉|别再|别|不要|不用|甭|闭嘴|安静|打住)\\s*" +
+    "(?:自动|定时|定期)?\\s*(?:的)?\\s*" +
+    REPORT_NOUN +
+    REPORT_TAIL +
+    "$",
+);
+/** 静音：不提「汇报」的纯闭嘴类（停/停下 不在此列——它们属于中断任务） */
+const RE_SILENCE = new RegExp(
+  "^" +
+    REPORT_LEAD +
+    "(?:闭嘴|安静|安静点|安静下|别说了|别讲了|别吵了?|别推了|别发了|别报了|打住)" +
+    REPORT_TAIL +
+    "$",
+);
+/** 恢复：说清楚要恢复汇报，或者「接着说」 */
+const RE_REPORTS_ON = new RegExp(
+  "^" +
+    REPORT_LEAD +
+    "(?:恢复|继续|开启|打开|开始|接着说|接着说吧|说下去|接着报)\\s*" +
+    "(?:自动|定时|定期)?\\s*(?:的)?\\s*" +
+    REPORT_NOUN +
+    REPORT_TAIL +
+    "$",
+);
+const RE_RESUME_TALK = new RegExp("^" + REPORT_LEAD + "(?:接着说|说下去|接着报)" + REPORT_TAIL + "$");
+
+/** 不带斜杠的进度问询：「进度」「当前进度」「汇报一下当前进度」（可带子命令） */
+
+function parseCommand(text: string): { name: "reset" | "status" | "help" | "queue" | "progress"; args: string } | null {
+  // 注意：/new 现在属于 pi 的内置命令（由 slash 路由接管，真的开新会话），
+  // 本地的「清缓冲/清审批记忆」改名为 /reset。
+  // 斜杠形式：全部内置指令；不带斜杠时只接受明确表达「进度」的词，避免把聊天里的 "p" / "status" 误判成命令
+  const t = text.trim();
+  const slash = /^\/(reset|status|help|queue|q|progress|p)(?:\s+([\s\S]*))?$/i.exec(t);
+  if (slash) {
+    const raw = slash[1].toLowerCase();
+    const name = raw === "q" ? "queue" : raw === "p" ? "progress" : raw;
+    return {
+      name: name as "reset" | "status" | "help" | "queue" | "progress",
+      args: (slash[2] ?? "").trim(),
+    };
+  }
+  // 裸文本：先认「问进度」，再认「静音/恢复」
+  const bare = BARE_PROGRESS_RE.exec(t);
+  if (bare) return { name: "progress", args: (bare[1] ?? "").trim() };
+  if (RE_REPORTS_OFF.test(t) || RE_SILENCE.test(t)) return { name: "progress", args: "off" };
+  if (RE_REPORTS_ON.test(t) || RE_RESUME_TALK.test(t)) return { name: "progress", args: "on" };
+  return null;
+}
+
+/** /queue [clear|drop <编号>] */
+async function handleQueueCommand(api: QQApi, state: State, openid: string, args: string) {
+  const parts = args.split(/\s+/).filter(Boolean);
+  const sub = parts[0]?.toLowerCase() ?? "";
+
+  if (!sub) {
+    await replyTo(api, state, openid, formatQueue(state));
+    return;
+  }
+  if (/^(clear|reset|清空)$/i.test(sub)) {
+    const dropped = state.queue.clear();
+    await replyTo(
+      api,
+      state,
+      openid,
+      dropped.length > 0 ? `已清空队列（${dropped.length} 条）。` : "队列本来就是空的。",
+    );
+    return;
+  }
+  if (/^(drop|del|rm|删除|删|去掉)$/i.test(sub)) {
+    const id = Number.parseInt(parts[1] ?? "", 10);
+    if (!Number.isFinite(id)) {
+      await replyTo(api, state, openid, "用法：/queue drop <编号>（编号见 /queue）");
+      return;
+    }
+    const removed = state.queue.remove(id);
+    await replyTo(
+      api,
+      state,
+      openid,
+      removed ? `已从队列删除 #${id}：${previewText(removed.text)}` : `队列里没有 #${id}，发 /queue 查看。`,
+    );
+    return;
+  }
+  await replyTo(api, state, openid, "用法：/queue 查看 / /queue clear 清空 / /queue drop <编号> 删一条");
+}
+
+/** 从 tool_call 事件提取可读摘要，让用户在 QQ 里看清要执行什么 */
+function summarizeTool(event: any): string {
+  const input = event.input ?? {};
+  // 审批提示会发到 QQ：先脱敏再截断
+  const clip = (value: unknown) => redactSecrets(String(value ?? "")).slice(0, 200);
+  switch (event.toolName) {
+    case "bash":
+    case "powershell":
+      return `${event.toolName}: ${clip(input.command)}`;
+    case "write":
+    case "edit":
+    case "read":
+      return `${event.toolName}: ${clip(input.path ?? input.file ?? input.filePath)}`;
+    case "grep":
+      return `${event.toolName}: ${clip(input.pattern)}`;
+    case "qq_send_file":
+      return `发送文件到 QQ: ${clip(input.path)}${input.name ? `（显示名 ${clip(input.name)}）` : ""}`;
+    default:
+      return `${event.toolName}: ${clip(JSON.stringify(input))}`;
+  }
+}