@zxh126/pi-qqbot 2.0.0 → 2.2.1

package/docs/README.zh-CN.md

@@ -20,7 +20,9 @@
 | **进度汇报** | 任务运行期间按 `progress.intervalMs`（默认 **15 秒**）推一条进度摘要（轮次、工具调用、正在跑的工具、token 用量）。随时发 `/progress`（别名 `/p`、「进度」）可立即获取；`/progress off` 在本会话内暂停自动汇报，`/progress on` 恢复。推送失败后自动推送静默，直到你再次问询。 |
 | **敏感信息脱敏** | 离开本机的文本先脱敏——进度摘要、审批提示、队列预览、日志文件：`Authorization` 头（含 QQ bot token）、`sk-…`/`ghp_…`/`npm_…`/`AKIA…`/JWT/PEM、`token=`/`password=`/`--api-key` 的值、URL 里的 `user:pass@`，以及超长高熵串。 |
 | **多 bot 同机** | 一份配置里写多个 QQ bot（`qqbots: [...]`，详见 [accounts.md](./accounts.md)），同一台机器上每个 pi 进程按配置顺序接入第一个未上线的 bot；全部在线则待命、每 5 秒重扫，有人退出就接管。别人只是 `/reload` 临时释放的 bot 不会被抢（留 20 秒预约窗口）。接入/接管时会告知当前 bot 名称与工作目录。 |
-| **内置指令** | `/status`、`/queue`、`/progress`、`/reset`、`/cancel`、`/help`。 |
+| **图片与文件** | QQ 里发来的附件会先下载到临时文件，再以标记行交给 pi——图片是 `图片路径 <path>`，其余按类型是 `语音路径` / `视频路径` / `文档路径` / `压缩包路径` / `文件路径`；QQ 侧收到一条回执（数量、类型、路径）。pi 的 `read` 工具能直接看图片，`bash` 能处理文件。 |
+| **把本机文件发到 QQ** | 让 agent 把机器上的文件发给你（「把 D:\docs\报告.pdf 发给我」）或发 `/sendfile <路径>`；机器人按 5MB 分片上传（QQ 富媒体），图片(png/jpg) / 视频(mp4) / 语音(silk) 直接展示，其余变成可下载的文件卡片。**外发必须先在 QQ 里审批。** |
+| **内置指令** | `/status`、`/queue`、`/progress`、`/reset`、`/cancel`、`/sendfile`、`/help`。 |
 
 ## 安装
 
@@ -50,6 +52,18 @@ pi install ./pi-qqbot
   "queue": {
     "max": 20,
     "ack": true
+  },
+  "attachments": {
+    "enabled": true,
+    "dir": "",
+    "maxBytes": 26214400,
+    "maxPerMessage": 10,
+    "retentionHours": 24,
+    "maxFiles": 200
+  },
+  "files": {
+    "enabled": true,
+    "maxBytes": 31457280
   }
 }
 ```
@@ -68,6 +82,14 @@ pi install ./pi-qqbot
 | `queue.ack` | `true` | 排队消息开始执行时是否回执 QQ（入队回执总是会发） |
 | `progress.enabled` | `true` | 任务运行期间是否定期推送进度摘要（会话启动时读取，改完需 `/new` 或重启；运行时用 `/progress off`） |
 | `progress.intervalMs` | `15000` | 推送间隔（可用环境变量 `PI_QQBOT_PROGRESS_MS` 覆盖，便于测试） |
+| `attachments.enabled` | `true` | 是否把附件下载到临时文件并把路径交给 pi；`false` = 只回一句忽略提示、只处理文字 |
+| `attachments.dir` | `""` | 落盘目录；空 = 系统临时文件夹下的 `pi-qqbot/<bot>`（Windows：`%LOCALAPPDATA%\Temp\pi-qqbot\…`） |
+| `attachments.maxBytes` | `26214400` | 单个附件上限（25 MB），超出的记为下载失败、不落盘 |
+| `attachments.maxPerMessage` | `10` | 单条消息最多处理几个附件 |
+| `attachments.retentionHours` | `24` | 超过此时长的临时文件在会话启动时清理 |
+| `attachments.maxFiles` | `200` | 目录内最多保留多少个文件（超出删最旧） |
+| `files.enabled` | `true` | 是否允许把本机文件发到 QQ（工具与 `/sendfile` 共用）；`false` 则拒绕 |
+| `files.maxBytes` | `31457280` | 发送单个文件的上限（30MB；QQ 硬限 200MB） |
 
 也可用环境变量 `QQ_BOT_APPID` / `QQ_BOT_APPSECRET` 代替文件里的凭据（仅单 bot 场景）。
 
@@ -98,9 +120,67 @@ pi install ./pi-qqbot
 | `/progress` | **立即获取当前进度摘要**（别名 `/p`、「进度」「当前进度」「进展」；忙碌时「到哪了」「怎么样了」这类问法同样生效）。手动暂停期间**问一次只回一次**，要重新打开定时汇报需发 `/progress on` 或「恢复汇报」；若只是配额静默，问一次即恢复 |
 | `/progress off` | **在本会话内暂停自动进度汇报**（别名：`pause`、`stop`、`暂停`、「暂停汇报」、「关闭汇报」）。手动 `/progress` 仍可看一次，但不再解除暂停 |
 | `/progress on` | **恢复自动进度汇报**（别名：`resume`、`start`、`恢复`、「恢复汇报」、「继续汇报」） |
-| `/cancel` | **中断当前正在运行的任务**并清空队列（别名：`/stop`、`/abort`、「取消」、「停止」、「中止」、「终止」、「算了」） |
+| `/cancel` | **中断当前正在运行的任务**并清空队列（别名：`/stop`、`/abort`、「取消」、「停止」、「中止」、「终止」、「算了」、「停」、「停下」、「停一下」、「别跑了」）。注意：单说「停」是中断**任务**，要关进度推送请说「别汇报了」「闭嘴」或 `/progress off` |
 | `/help` | 帮助 |
 
+### QQ 里发来的图片与文件
+
+发一张图（或文档、压缩包、语音/视频），机器人会把它下载到临时文件，然后给 pi 一行路径：
+
+```
+图片路径 C:\Users\you\AppData\Local\Temp\pi-qqbot\bot-340143\2026-02-11\msg-abc-1-103045.jpg
+```
+
+| 附件类型 | 交给 pi 的行 |
+|---|---|
+| 图片 | `图片路径 <path>` |
+| 语音 / 音频 | `语音路径 <path>` |
+| 视频 | `视频路径 <path>` |
+| 文档（pdf、office、文本、代码…） | `文档路径 <path>` |
+| 压缩包（zip、rar、7z、tar…） | `压缩包路径 <path>` |
+| 其它 | `文件路径 <path>` |
+
+你自己的文字保持在第一行：发「看下这个」+ 一张图，送给 pi 的就是
+`看下这个\n图片路径 C:\…\a.jpg`——同一轮，路径已在里面。QQ 侧还会收到回执，例如
+`已收到 2 个附件（图片 ×1、文档 ×1），已存为临时文件并交给 pi：` 后跟各条路径；下载失败的附件会列出原因，
+文字部分照常执行。
+
+注意：
+
+- QQ 的下载地址带短期有效的 `rkey`，所以收到消息的当下就下载。
+- 带附件的消息会**绕过**斜杠命令、审批解析与编号选择，一律当作普通内容交给 pi（附带 `/status` 不会被执行）。
+- 临时文件由 `attachments.retentionHours` / `attachments.maxFiles` 在会话启动时清理；交给 pi 的路径在当前会话（通常一天内）都可读。
+- 落盘文件名只保留 `[0-9a-zA-Z._-]`，并以 QQ 消息 id 作为前缀。
+
+### 把本机文件发到 QQ
+
+两种触发方式：
+
+| 触发 | 用法 |
+|---|---|
+| 自然语言 | 「把 D:\docs\报告.pdf 发给我」——agent 会调 `qq_send_file` 工具 |
+| 斜杠命令 | `/sendfile D:\docs\报告.pdf`（路径带空格就加引号；不开 run，直接执行） |
+
+**审批是硬性的，而且每次都问**：`qq_send_file` 无论 `approve.tools` 怎么配都强制走审批，并且**不吃**会话级
+「以后都同意」、也不吃「同意后记住」，因为外发文件等于数据出境，每个文件单独确认。提示里会写明：
+`[审批 #1] 发送文件到 QQ: D:\…` + 「需单独确认」。
+
+发送形态（QQ 富媒体分片上传）：
+
+| 文件 | 对方看到 |
+|---|---|
+| `.png` / `.jpg` / `.jpeg` | 图片直接展示 |
+| `.mp4` | 视频直接播放 |
+| `.silk` | 语音条 |
+| 其他（pdf / zip / mp3 / epub / exe…） | 可下载的文件卡片 |
+
+注：
+
+- 必须走分片上传（`upload_prepare` → `PUT` → `upload_part_finish` → 合并）：URL 上传要求公网可访问，二进制直传只有 5MB 上限。
+- 用被动回复（`srv_send_msg: false` + `msg_type: 7` 带 `msg_id`/`msg_seq`），不烧主动消息额度。
+- QQ 侧还有 **200MB 硬上限**和**每天发送文件总容量上限**（错误码 `40093002`），都翻成中文回执。
+- 成功后会回一行：`已发送「报告.pdf」（2.31 MB，文件卡片）`。
+
 ### QQ 里的斜杠命令
 
 任何以 `/` 开头的消息都会先走路由，再决定是否当成对话：
@@ -213,6 +293,18 @@ pi 的会话一次只跑一轮 agent run，所以串行调度由 bot 自己做
 - `agent_settled` / `/cancel` / 会话关闭时定时器都会清掉。
 - 想彻底关掉（跨会话）：`progress.enabled: false`（改完需 `/new` 或重启才生效）。
 
+#### 口语说法（整句匹配，只在发整句时生效）
+
+| 意图 | 可以说 |
+|---|---|
+| 暂停自动汇报 | 「暂停汇报进度」「暂停进度汇报」「别汇报了」「别说了」「闭嘴」「安静」「打住」「停止汇报」，或 `/progress off` |
+| 恢复自动汇报 | 「恢复汇报」「恢复汇报进度」「接着说」「说下去」，或 `/progress on` |
+| 看一次当前进度 | 「汇报一下当前进度」「看一下进度」「说说进度」「进度如何」「进度怎么样」，或 `/progress` |
+| 中断当前任务 | 「停」「停下」「停一下」「停停」「停止」「取消」「别跑了」，或 `/cancel` |
+
+单说「停」是中断**任务**；只有带名词的（「停止汇报」）或明确的闭嘴词（「别说了」「闭嘴」）才是暂停汇报。
+「帮我加个进度条」这种任务句仍照常转给 pi，不会被当成口令。
+
 ### 取消正在运行的任务
 
 从 QQ 发起的耗时任务（装依赖、编译、agent 跑飞了）不必回到机器上处理：
@@ -278,7 +370,7 @@ QQ 网关对同一 bot 只保留一个活跃连接。插件用 `proper-lockfile`
 
 ## 变更日志
 
-见 [CHANGELOG.md](../CHANGELOG.md)：每个版本改了什么、为什么改。进度汇报的暂停/恢复（`/progress off` / `on`）在 **1.5.0** 加入；多 bot 自动抢占在 **2.0.0**。
+见 [CHANGELOG.md](../CHANGELOG.md)：每个版本改了什么、为什么改。进度汇报的暂停/恢复（`/progress off` / `on`）在 **1.5.0** 加入；多 bot 自动抢占在 **2.0.0**；接收 QQ 图片/文件（落盘后以 `图片路径 <path>` 这类标记行交给 pi）在 **2.1.0**；把本机文件发到 QQ（`qq_send_file` / `/sendfile`，富媒体分片上传）在 **2.2.0**。
 
 ## License
 

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";
@@ -22,6 +43,11 @@ 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 */
@@ -69,6 +95,12 @@ interface State {
   progressMuted: boolean;
   /** 最终答案发送失败时缓存，下一条消息时补发 */
   undelivered: { openid: string; text: string } | null;
+  /** 附件下载 401/403 时重试用的凭据（接入后由 applyClaim 注入） */
+  getToken: (() => Promise<string>) | null;
+  /** 仅测试用：替换附件落盘时的 fetch */
+  attachmentFetch: typeof fetch | null;
+  /** 当前 bot 的 REST 基址（发文件用） */
+  restBase: string | null;
 }
 
 /** 扩展运行所需的状态（导出只为测试用） */
@@ -99,6 +131,9 @@ export function createInitialState(): State {
     progressPaused: false,
     progressMuted: false,
     undelivered: null,
+    getToken: null,
+    attachmentFetch: null,
+    restBase: null,
     account: null,
     candidates: [],
     claimNote: null,
@@ -201,24 +236,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 +265,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 +285,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}` };
   });
@@ -338,6 +379,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 网关");
@@ -458,6 +515,8 @@ export default function (
     state.releaseLock = null;
     state.gateway = null;
     state.api = null;
+    state.getToken = null;
+    state.restBase = null;
     state.account = null;
   });
 
@@ -466,13 +525,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,16 +551,110 @@ 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 } };
+      },
+    }),
+  );
 }
 
 /** 取消/停止这类「打断当前任务」的表达 */
+/**
+ * 取消/停止这类「打断当前任务」的表达。
+ *
+ * 注意分工：「停」「停下」「停一下」属于**中断任务**（用户定的：停 = 停止干活）；
+ * 想只关掉进度推送请用「别汇报了」「闭嘴」「/progress off」；
+ * 「停止汇报」因为带了名词，不算取消，走静音。
+ */
 const RE_CANCEL =
-  /^(\/cancel|\/stop|\/abort|取消|停止|中止|终止|算了|cancel|stop|abort)$/i;
+  /^(\/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;
 
@@ -726,6 +890,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;
@@ -738,8 +946,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) {
@@ -781,7 +989,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) => {
@@ -814,8 +1024,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();
@@ -867,8 +1077,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,
@@ -880,7 +1090,9 @@ export async function handleMessage(
           "/status — 查看状态（当前 qqbot / 忙闲 / 队列 / 自动同意 / 待审批 / 自动汇报）",
           "/queue — 查看队列；/queue clear 清空；/queue drop <编号> 删一条",
           "/reset — 清空回复缓冲、审批记忆与自动同意（不换会话；换会话发 /new）",
-          "/cancel（或「取消」「停止」）— 中断正在运行的任务并清空队列",
+          "/cancel（或「取消」「停止」「停」）— 中断正在运行的任务并清空队列",
+          "/sendfile <路径> — 把本机文件发到你的 QQ（png/jpg/mp4/silk 直显，其余为文件卡片；外发需审批）",
+          "只关进度推送：/progress off（或「别汇报了」「闭嘴」）；「停」是中断任务，不是静音",
           "/help — 帮助",
           "pi 的命令优先：/reload /new /compact /session /name /model /thinking，以及扩展命令、模板与 /skill:xxx。",
           "忙碌时发来的普通消息（含模板/skill 命令）会排队，当前任务结束后自动执行。",
@@ -974,20 +1186,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(() => {});
@@ -1109,14 +1321,65 @@ const UNMUTE_ARGS = new Set([
   "继续汇报",
 ]);
 
-/** 不带斜杠的「暂停汇报」类说法（整句匹配，避免误伤正常聊天） */
-const RE_REPORTS_OFF =
-  /^(?:请|帮我|给我)?\s*(?:暂停|停止|关闭|关掉|别|不要|别再)(?:自动)?(?:的)?(?:进度汇报|进度|进展|汇报|推送|播报|报告)(?:上报|推送|汇报)?(?:了|吧)?$/;
-const RE_REPORTS_ON =
-  /^(?:请|帮我|给我)?\s*(?:恢复|继续|开启|打开|开始)(?:自动)?(?:的)?(?:进度汇报|进度|进展|汇报|推送|播报|报告)(?:上报|推送|汇报)?(?:吧)?$/;
+/**
+ * 不带斜杠的口令（整句匹配，避免误伤正常聊天）。
+ *
+ * 三类：
+ * 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 + "$");
 
-/** 不带斜杠的进度问询：「进度」「当前进度」「现在进展」（可带子命令） */
-const BARE_PROGRESS_RE = /^(?:progress|(?:当前|现在|目前)?的?(?:进度|进展))(?:\s+([\s\S]*))?$/i;
+/** 不带斜杠的进度问询：「进度」「当前进度」「汇报一下当前进度」（可带子命令） */
 
 function parseCommand(text: string): { name: "reset" | "status" | "help" | "queue" | "progress"; args: string } | null {
   // 注意：/new 现在属于 pi 的内置命令（由 slash 路由接管，真的开新会话），
@@ -1132,11 +1395,11 @@ function parseCommand(text: string): { name: "reset" | "status" | "help" | "queu
       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)) return { name: "progress", args: "off" };
-  if (RE_REPORTS_ON.test(t)) return { name: "progress", args: "on" };
+  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;
 }
 
@@ -1192,6 +1455,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))}`;
   }