@zxh126/pi-qqbot 2.0.1 → 2.3.0

package/index.ts

@@ -1,4 +1,6 @@
 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,
@@ -8,7 +10,26 @@ import {
   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";
@@ -18,10 +39,23 @@ 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 */
@@ -67,8 +101,22 @@ interface State {
   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;
 }
 
 /** 扩展运行所需的状态（导出只为测试用） */
@@ -98,7 +146,14 @@ export function createInitialState(): State {
     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,
@@ -118,6 +173,59 @@ export default function (
 ) {
   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;
@@ -126,6 +234,7 @@ export default function (
     clearCancelTimer(state);
     state.progress.start();
     state.progressPaused = false;
+    state.progressHeldForApproval = false;
     startProgressTimer(pi, state);
   });
 
@@ -201,24 +310,28 @@ export default function (
     const toolName: string = ev.toolName ?? "tool";
     const cfg = state.cfg;
 
-    // 判断是否需要审批：配置的 tools 列表 + destructiveHint 兑底
+    // 判断是否需要审批：配置的 tools 列表 + destructiveHint 兑底 + 强制审批工具（外发文件）
     const allTools = (pi.getAllTools() ?? []) as any[];
     const toolMeta = allTools.find((t) => t.name === toolName);
     const destructive = toolMeta?.annotations?.destructiveHint === true;
-    const needsApproval = cfg.approve.tools.includes(toolName) || destructive;
+    const forced = FORCE_APPROVAL_TOOLS.has(toolName);
+    const needsApproval = forced || cfg.approve.tools.includes(toolName) || destructive;
     if (!needsApproval) return; // 放行
 
-    // 会话级自动同意（用户回复过「以后都同意」）：本会话内直接放行，不落盘、不跨会话
-    if (state.approver.autoAllowed) {
-      log("[approve] 自动同意放行:", toolName);
-      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 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);
@@ -226,11 +339,13 @@ export default function (
       // 超时通知
       state.api?.sendC2C(openid, `审批 #${seq} 已超时，已自动拒绝。`).catch(() => {});
     });
-    await state.api.sendC2C(openid, state.approver.render(seq)).catch(() => {});
+    await state.api
+      .sendC2C(openid, state.approver.render(seq, { strict: forced }))
+      .catch(() => {});
     const decision = await done;
 
     if (decision === "allow") {
-      if (cfg.approve.remember) state.approver.remember(toolName, "allow");
+      if (!forced && cfg.approve.remember) state.approver.remember(toolName, "allow");
       log("[approve] 用户批准 #", seq);
       return;
     }
@@ -244,7 +359,7 @@ export default function (
       return { block: true, reason: `QQ 审批超时（#${seq}）：${summary}` };
     }
     // block（用户显式拒绝）
-    if (cfg.approve.remember) state.approver.remember(toolName, "block");
+    if (!forced && cfg.approve.remember) state.approver.remember(toolName, "block");
     log("[approve] 用户拒绝 #", seq);
     return { block: true, reason: `QQ 用户拒绝了 ${summary}` };
   });
@@ -276,6 +391,11 @@ export default function (
 
     // 新会话：清空 remember 记忆与自动同意开关（自动同意只在当前会话有效）
     state.approver.reset();
+    // 远程上下文提醒同样只在本会话提醒一次
+    state.remoteNotified = false;
+    // 「QQ ↔ 本机」的来源切换状态也随会话重置
+    state.lastRunOrigin = null;
+    state.localHandoffPending = false;
     // 手动暂停的自动汇报同样只在本会话有效
     state.progressMuted = false;
     state.progressPaused = false;
@@ -338,6 +458,22 @@ export default function (
       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 网关");
@@ -433,6 +569,12 @@ export default function (
     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");
@@ -458,6 +600,8 @@ export default function (
     state.releaseLock = null;
     state.gateway = null;
     state.api = null;
+    state.getToken = null;
+    state.restBase = null;
     state.account = null;
   });
 
@@ -466,13 +610,24 @@ export default function (
   // 而 reload()/newSession() 又必须拿到 ExtensionCommandContext。于是注册一个扩展
   // 命令，QQ 侧收到 /reload 时改派 /qq reload，就能在合法的命令上下文里执行。
   pi.registerCommand("qq", {
-    description: "pi-qqbot 内部桥接：/qq <reload|new|compact|quit|session|name|model|thinking> [args]",
+    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) {
@@ -481,6 +636,29 @@ export default function (
       }
     },
   });
+
+  // ---- 工具：把本机文件发到 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 } };
+      },
+    }),
+  );
 }
 
 /** 取消/停止这类「打断当前任务」的表达 */
@@ -498,6 +676,70 @@ 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;
 
@@ -562,6 +804,7 @@ function startJob(pi: ExtensionAPI, state: State, job: QueuedJob) {
     "text=",
     job.text.slice(0, 60),
   );
+  // 每会话第一条真正跑起来的 QQ 消息，由 before_agent_start 注入远程上下文说明。
   try {
     void Promise.resolve(
       pi.sendUserMessage(job.text, { expandPromptTemplates: true, deliverAs: "followUp" }),
@@ -733,6 +976,50 @@ export async function handleMessage(
     }
     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;
@@ -745,8 +1032,8 @@ export async function handleMessage(
       }
     }
 
-    // 待选择的编号回复（/tree、/fork、/resume 之后）
-    if (state.picker) {
+    // 待选择的编号回复（/tree、/fork、/resume 之后）；带附件时不当作编号选择
+    if (!hasAttachment && state.picker) {
       if (pickerExpired(state.picker)) {
         state.picker = null;
       } else if (state.picker.openid === msg.openid) {
@@ -788,7 +1075,9 @@ export async function handleMessage(
     state.bridgeReply = (text: string) => {
       void replyTo(api, state, msg.openid, text);
     };
-    const routed = await routeSlash(
+    const routed = hasAttachment
+      ? ("text" as const)
+      : await routeSlash(
       {
         listPiCommands: () => (pi.getCommands?.() ?? []) as { name: string; source?: string }[],
         dispatch: (text, options) => {
@@ -821,8 +1110,8 @@ export async function handleMessage(
     );
     if (routed !== "text") return;
 
-    // 远程审批回复优先
-    const parsed = state.approver.parseReply(msg.content.trim());
+    // 远程审批回复优先（带附件时不当作审批动作）
+    const parsed = hasAttachment ? null : state.approver.parseReply(msg.content.trim());
     if (parsed) {
       if (parsed.decision === "terminate") {
         const n = state.approver.terminateAll();
@@ -874,8 +1163,8 @@ export async function handleMessage(
       log("[msg] 审批类文本但无待审批，按普通消息处理");
     }
 
-    // 内置指令
-    const cmd = parseCommand(msg.content);
+    // 内置指令（带附件时绕过：附件消息一律当普通内容交给 pi）
+    const cmd = hasAttachment ? null : parseCommand(msg.content);
     if (cmd?.name === "help") {
       await replyTo(
         api,
@@ -884,10 +1173,11 @@ export async function handleMessage(
         [
           "pi-qqbot 指令:",
           "/progress — 查看进度；/progress off 暂停自动汇报、/progress on 恢复（本会话有效）",
-          "/status — 查看状态（当前 qqbot / 忙闲 / 队列 / 自动同意 / 待审批 / 自动汇报）",
+          "/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。",
@@ -902,6 +1192,7 @@ export async function handleMessage(
       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}`,
@@ -982,20 +1273,20 @@ export async function handleMessage(
     // 忙检查：单会话串行处理——忙碌时入队，当前任务结束后自动继续
     if (isBusy(state)) {
       // 忙碌时问「进度」不该排队，直接回当前进度并恢复自动推送
-      if (RE_PROGRESS_QUERY.test(msg.content.trim())) {
+      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, msg.content);
+      await enqueueJob(api, state, msg.openid, incoming);
       return;
     }
 
     // ack
     await replyTo(api, state, msg.openid, "收到，正在处理");
 
-    startJob(pi, state, state.queue.mint(msg.openid, msg.content));
+    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(() => {});
@@ -1064,9 +1355,22 @@ function stopProgressTimer(state: State) {
 /** 推一条进度摘要；失败就暂停自动推送（用户问一次即恢复）；手动暂停（/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);
@@ -1077,6 +1381,13 @@ async function pushProgress(state: State, reason: "tick" | "ask"): Promise<boole
   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;
@@ -1084,7 +1395,8 @@ function describeProgressMode(state: State): string {
   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;
-  return `开启（每 ${Math.round(ms / 1000)}s）`;
+  const base = `开启（每 ${Math.round(ms / 1000)}s）`;
+  return state.approver.pendingCount > 0 ? `${base}，等审批期间暂缓` : base;
 }
 
 /** /progress 的子命令：暂停 / 恢复自动汇报 */
@@ -1251,6 +1563,8 @@ function summarizeTool(event: any): string {
       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))}`;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zxh126/pi-qqbot",
-  "version": "2.0.1",
+  "version": "2.3.0",
   "type": "module",
   "description": "Bridge the Pi coding agent into QQ private chats, with remote tool-call approval",
   "license": "MIT",
@@ -27,7 +27,7 @@
     ]
   },
   "scripts": {
-    "test": "node test/queue.test.mjs && node test/logger.test.mjs && node test/usage-bridge.test.mjs && node test/progress.test.mjs && node test/redact.test.mjs && node test/config.test.mjs && node test/lock.test.mjs && node test/accounts.test.mjs && node test/auth.test.mjs"
+    "test": "node test/queue.test.mjs && node test/approver.test.mjs && node test/logger.test.mjs && node test/usage-bridge.test.mjs && node test/progress.test.mjs && node test/redact.test.mjs && node test/config.test.mjs && node test/remote-notice.test.mjs && node test/lock.test.mjs && node test/accounts.test.mjs && node test/auth.test.mjs && node test/attachment.test.mjs && node test/upload.test.mjs"
   },
   "files": [
     "*.ts",
@@ -43,10 +43,18 @@
     "ws": "^8.18.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "typebox": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/proper-lockfile": "^4.1.4",
-    "@types/ws": "^8.18.2"
+    "@types/ws": "^8.18.2",
+    "jiti": "^2.6.1",
+    "typebox": "^1.3.27"
   }
 }