@zxh126/pi-qqbot 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -0,0 +1,129 @@
+# Changelog
+
+本文件记录 pi-qqbot 的版本变更。格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
+版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
+
+## [1.5.0] - 2026-10-25
+
+### Added
+
+- **暂停 / 恢复自动进度汇报（会话内有效）**：`/progress off`（别名 `/p pause`、`暂停`、`stop`、
+  「暂停汇报」「关闭自动汇报」）停掉定时推送，`/progress on`（别名 `resume`、`start`、`恢复`、
+  「恢复汇报」「继续汇报」）重新打开。
+  - 手动暂停跨 run 保留（`agent_start` 不再顺手复位），只在 `session_start`（`/new`、`/reload`、重启）复位为默认开启。
+  - 手动暂停期间，`/progress`、「进度」、「当前进度」、「现在进度」、「进展」**只回一次当前摘要**，
+    不会偷偷把 15 s 定时器打开，回复末尾附「（自动汇报已暂停，发 /progress on 恢复）」提示。
+  - 与原有的「配额静默」严格区分：配额静默是发送失败后的自动暂停，问一次进度即恢复；
+    手动暂停只有 `on`/「恢复汇报」能解除。
+  - `/progress <看不懂的参数>` 回用法提示，不再静默忽略。
+- `/status` 新增 `自动汇报:` 一行，区分四种模式：`开启（每 Ns）` / `已暂停（本会话…）` /
+  `推送失败已静默` / `未启用（配置 progress.enabled=false）`。
+- 裸文本口令「当前进度」「现在进度」「目前进展」（可带子命令，如「进度 暂停」）也走进度查询。
+- 测试：`test/progress.test.mjs` 新增 7 个用例（暂停/恢复即时生效、跨 run 保留、暂停后手动查看不解除、
+  中文口令且不误伤任务句、空闲时问「当前进度」、`/status` 文案、未知子命令）。
+
+### Changed
+
+- `/progress`（无参数）在**手动暂停**状态下不再解除暂停（此前任何一次问询都会清掉暂停标志）。
+- 「推送失败已静默」与「用户手动暂停」拆成两个独立状态（`progressPaused` / `progressMuted`），
+  互不覆盖。
+- README（英文）与 `docs/README.zh-CN.md` 的指令表、进度小节、`progress.enabled` 说明同步更新。
+
+## [1.4.0] - 2026-10-24
+
+### Added
+
+- 任务运行期间按 `progress.intervalMs`（默认 15 s）推送进度摘要：轮次、工具调用次数与前三名、
+  失败次数、最近完成的工具（含耗时）、正在跑的工具、token 用量。全部由本地事件拼装，
+  不调用模型、不消耗 token。
+- 全链路敏感信息脱敏（`redact.ts`）：进度摘要、审批提示、队列预览、日志落盘统一过一遍，
+  覆盖 `Authorization` / QQ bot token / `sk-…` / `ghp_…` / `npm_…` / `AKIA…` / JWT / PEM /
+  `token=` / `password=` / `--api-key` / URL `user:pass@` / 高熵串。
+- `/progress`（别名 `/p`、「进度」）与忙碌时的「到哪了」「怎么样了」问询。
+- 最终答案因配额发不出去时缓存，下条消息以「（上一条回复发送失败，补发如下）」补发。
+- 配置 `progress.enabled` / `progress.intervalMs`（环境变量 `PI_QQBOT_PROGRESS_MS` 可覆盖）。
+
+## [1.3.3] - 2026-10-24
+
+### Fixed
+
+- `/usage` 报告读回改为轮询等待：`appendEntry` 晚于命令 `await` 返回，导致偶发读不到刚写入的报告。
+
+## [1.3.2] - 2026-10-24
+
+### Fixed
+
+- `/usage` 读回兜底：`getEntries` 尚未刷新时直接读会话文件尾部；`generatedAt` 兼容毫秒时间戳。
+
+## [1.3.1] - 2026-10-24
+
+### Fixed
+
+- `/usage rate` 真正执行并读回配置文件确认，不再「口头成功」。
+
+## [1.3.0] - 2026-10-24
+
+### Added
+
+- `/usage`、`/cost`（只往 `ctx.ui.*` 输出的扩展命令）桥接回 QQ，不再沉默。
+- `/mcp`、`/llama` 这类需要主机 TUI 选择框/登录的命令改为明确回执说明。
+
+## [1.2.1] - 2026-10-24
+
+### Changed
+
+- 日志时间戳改为本地时间并带 UTC 偏移（如 `[2026-10-24T07:39:09.762+08:00]`），与文件 mtime、
+  进程启动时间直接对齐，不再需要心算时区。
+
+## [1.2.0] - 2026-10-24
+
+### Added
+
+- 忙碌时收到的消息进入队列，当前任务 settle 后自动续跑；`/cancel` 永远不入队、立即生效。
+- `/queue`（别名 `/q`）查看队列，`/queue clear`、`/queue drop <编号>` 管理队列。
+- 配置 `queue.max`（0 = 关闭排队）、`queue.ack`。
+
+## [1.1.0] - 2026-10-24
+
+### Added
+
+- `/tree`、`/fork`、`/resume` 的编号选择器接管：回一个最多 10 项的列表，只对发出者有效、10 分钟过期；
+- `/clone` 支持。
+
+## [1.0.0] - 2026-10-24
+
+### Added
+
+- 接管 pi 的斜杠命令（白名单 `commands.passthrough` / `allowReload` / `allowQuit` / `allowSession`）：
+  `/reload`、`/new`、`/compact`、`/session`、`/name`、`/model`、`/thinking`、`/quit`，
+  以及扩展命令、prompt 模板、`/skill:name` 的透传。
+- 有任务在跑时，`/reload`、`/new`、`/compact`、`/quit`、`/tree`、`/fork`、`/clone`、`/resume` 拒绝执行。
+
+## [0.3.0] - 2026-10-24
+
+### Added
+
+- `/cancel`（别名 `/stop`、`/abort`、「取消」「停止」「中止」「终止」「算了」）中断正在运行的任务：
+  先终止待审批、清空队列，再 `ctx.abort()`，丢弃半截回复；8 秒看门狗兜底释放忙碌标记。
+
+## [0.2.1] - 2026-10-24
+
+### Changed
+
+- 中文 README 移入 `docs/README.zh-CN.md`，修复 npm 页面默认 readme 被中文版顶掉。
+
+## [0.2.0] - 2026-10-24
+
+### Added
+
+- 会话级「以后都同意」自动放行（`approve.remember`），含已在等待的那一条；
+  「取消自动同意」「恢复审批」等**长得像取消**的说法仍走审批分支。
+- 中英文双语 README。
+
+## [0.1.0] - 2026-10-16
+
+### Added
+
+- 初始版本：把 Pi coding agent 接入 QQ 单聊（C2C），单会话 + `proper-lockfile` 单实例锁（宿主接管）、
+  危险工具（`bash` / `powershell` / `write` / `edit` 及 `destructiveHint` 工具）执行前远程审批、
+  长回复自动分段。

package/README.md

@@ -17,9 +17,9 @@ Bridge the **[Pi](https://pi.dev) coding agent** into QQ private (C2C) chats: se
 | **Single-instance lock** | Only one pi process hosts the QQ gateway; the others stand by and take over automatically when the host exits. |
 | **Cancel a running task** | Send `/cancel` (or 「取消」/「停止」) and the current run is aborted immediately — the QQ reply, the pending tool calls, the half-written answer and the pending queue are all cleaned up. |
 | **Slash-command routing** | QQ messages starting with `/` are routed: pi extension commands, prompt templates and `/skill:name` are dispatched to pi; a set of pi built-ins (`/reload`, `/new`, `/compact`, `/session`, `/name`, `/model`, `/thinking`, `/quit`) is taken over; host-only commands are answered instead of being fed to the model. |
-| **Progress reports** | While a run is in progress the bot posts a short progress summary (turns, tool calls, the tool currently running, tokens) every `progress.intervalMs` (default **15 s**). Ask at any time with `/progress` (aliases `/p`, 「进度」). If a report cannot be delivered the automatic reports stay quiet until you ask again. |
+| **Progress reports** | While a run is in progress the bot posts a short progress summary (turns, tool calls, the tool currently running, tokens) every `progress.intervalMs` (default **15 s**). Ask at any time with `/progress` (aliases `/p`, 「进度」). `/progress off` pauses the automatic reports for the rest of the session, `/progress on` brings them back. If a report cannot be delivered the automatic reports stay quiet until you ask again. |
 | **Secret redaction** | Anything leaving the machine is scrubbed first — progress reports, approval prompts, queue previews and the log file: `Authorization` headers (incl. QQ bot tokens), `sk-…` / `ghp_…` / `npm_…` / `AKIA…` / JWTs / PEM blocks, `token=` / `password=` / `--api-key` values, URL `user:pass@`, and long high-entropy strings. |
-| **Built-in commands** | `/status`, `/queue`, `/progress`, `/reset`, `/cancel`, `/help`. |
+| **Built-in commands** | `/status`, `/queue`, `/progress` (+ `/progress off` / `on`), `/reset`, `/cancel`, `/help`. |
 
 ## Install
 
@@ -63,7 +63,7 @@ Then create `~/.pi/agent/pi-qqbot.json`:
 | `approve.tools` | `["bash","powershell","write","edit"]` | Tools that require approval; tools annotated `destructiveHint` are always gated too |
 | `approve.remember` | `true` | Remember the decision per tool inside the session (no more prompts for that tool) |
 | `commands` | see below | Slash-command routing gates: `passthrough`, `allowReload`, `allowQuit`, `allowSession` |
-| `progress.enabled` | `true` | Post periodic progress reports while a task is running |
+| `progress.enabled` | `true` | Post periodic progress reports while a task is running (read at session start — restart or `/new` after changing; at runtime use `/progress off`) |
 | `progress.intervalMs` | `15000` | Interval of those reports (env override: `PI_QQBOT_PROGRESS_MS`) |
 | `queue.max` | `20` | How many messages may wait while a task runs; `0` disables queueing (busy messages are refused as before) |
 | `queue.ack` | `true` | Reply to QQ when a queued [message](#queueing-while-busy) starts (the "queued" ack is always sent) |
@@ -77,9 +77,11 @@ Start pi, then message the bot in QQ; pi handles it and replies.
 | Command | Description |
 |---|---|
 | `/reset` | Clear the reply buffer, approval memory and session-wide auto-approve (**does not** switch sessions — send `/new` for that) |
-| `/status` | Show busy/idle state, queue length, auto-approve state and pending approval count |
+| `/status` | Show busy/idle state, queue length, auto-approve state, pending approval count and the progress-report mode |
 | `/queue` | Show the queue (aliases: `/q`); `/queue clear` empties it, `/queue drop <id>` removes one entry |
-| `/progress` | **Show the current progress summary immediately** and resume automatic progress reports (aliases: `/p`, 「进度」, 「进展」; plain-text questions like 「到哪了」「怎么样了」 work while busy) |
+| `/progress` | **Show the current progress summary immediately** (aliases: `/p`, 「进度」, 「当前进度」, 「进展」; plain-text questions like 「到哪了」「怎么样了」 work while busy). While you paused reports yourself it only replies once — use `/progress on` to resume; while reports are merely quota-quiet, asking resumes them |
+| `/progress off` | **Pause automatic progress reports for the rest of the session** (aliases: `pause`, `stop`, `暂停`, 「暂停汇报」, 「关闭汇报」). Manual `/progress` still works, it just no longer resumes the timer |
+| `/progress on` | **Resume automatic progress reports** (aliases: `resume`, `start`, `恢复`, 「恢复汇报」, 「继续汇报」) |
 | `/cancel` | **Interrupt the task that is running right now** and empty the queue (aliases: `/stop`, `/abort`, 「取消」, 「停止」, 「中止」, 「终止」, 「算了」) |
 | `/help` | Show help |
 
@@ -197,10 +199,14 @@ While a run is in progress, a summary is pushed to QQ every `progress.intervalMs
 - **Quota-aware**: one QQ message buys only 4 passive replies, so a long run will eventually run out.
   The first failed send stops automatic reports for that run (no retry spam); send `/progress`
   (or 「进度」) and they resume.
+- **Manual pause / resume**: `/progress off` (or 「暂停汇报」) silences the reports for the rest of the
+  session — it survives `agent_settled` and the next run, and asking for `/progress` no longer turns it
+  back on. `/progress on` (or 「恢复汇报」) resumes. A new session (`/new`, restart) starts enabled again.
+  `/status` shows which of the four modes you are in (on / paused-by-you / quota-quiet / disabled).
 - **The final answer is protected**: if it cannot be delivered (quota), it is cached and re-sent with a
   `（上一条回复发送失败，补发如下）` prefix as soon as you send the next message.
 - Timer is cleared on `agent_settled` / `/cancel` / session shutdown.
-- Set `progress.enabled: false` to turn the whole thing off.
+- Set `progress.enabled: false` to turn the whole thing off (across sessions; read at session start).
 
 ### Cancelling a run
 
@@ -266,6 +272,11 @@ The QQ gateway keeps only one active connection per bot. The extension uses a `p
 
 Debug logs are written to `~/.pi/agent/pi-qqbot.log`. Each line starts with a **local** timestamp that carries the UTC offset, e.g. `[2026-10-24T07:39:09.762+08:00]`, so it lines up with file mtimes and process start times without mental arithmetic.
 
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) — every release with what changed and why. The progress-report
+pause/resume (`/progress off` / `on`) landed in **1.5.0**.
+
 ## License
 
 MIT

package/docs/README.zh-CN.md

@@ -17,7 +17,7 @@
 | **单实例锁** | 只有一个 pi 进程作为宿主连接 QQ，其余待命，宿主退出后自动接管。 |
 | **中断正在运行的任务** | 发 `/cancel`（或「取消」/「停止」），当前任务立刻中断 —— QQ 回复、待审批工具调用、写到一半的回答、排队中的消息一并清理。 |
 | **斜杠命令路由** | 以 `/` 开头的 QQ 消息会先被路由：pi 的扩展命令、prompt 模板、`/skill:name` 交给 pi 派发；一部分 pi 内置命令（`/reload`、`/new`、`/compact`、`/session`、`/name`、`/model`、`/thinking`、`/quit`）由本扩展接管；只能在主机执行的内置命令直接回执，不会送给模型。 |
-| **进度汇报** | 任务运行期间按 `progress.intervalMs`（默认 **15 秒**）推一条进度摘要（轮次、工具调用、正在跑的工具、token 用量）。随时发 `/progress`（别名 `/p`、「进度」）可立即获取；推送失败后自动推送静默，直到你再次问询。 |
+| **进度汇报** | 任务运行期间按 `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@`，以及超长高熵串。 |
 | **内置指令** | `/status`、`/queue`、`/progress`、`/reset`、`/cancel`、`/help`。 |
 
@@ -65,7 +65,7 @@ pi install ./pi-qqbot
 | `commands` | 见下 | 斜杠命令路由开关：`passthrough`、`allowReload`、`allowQuit`、`allowSession` |
 | `queue.max` | `20` | 任务运行期间最多排队多少条；`0` = 关闭排队（忙碌时直接拒绍，回到旧行为） |
 | `queue.ack` | `true` | 排队消息开始执行时是否回执 QQ（入队回执总是会发） |
-| `progress.enabled` | `true` | 任务运行期间是否定期推送进度摘要 |
+| `progress.enabled` | `true` | 任务运行期间是否定期推送进度摘要（会话启动时读取，改完需 `/new` 或重启；运行时用 `/progress off`） |
 | `progress.intervalMs` | `15000` | 推送间隔（可用环境变量 `PI_QQBOT_PROGRESS_MS` 覆盖，便于测试） |
 
 也可用环境变量 `QQ_BOT_APPID` / `QQ_BOT_APPSECRET` 代替文件里的凭据。
@@ -77,9 +77,11 @@ pi install ./pi-qqbot
 | 指令 | 说明 |
 |---|---|
 | `/reset` | 重置：清空回复缓冲、审批记忆与自动同意开关（**不换会话**，换会话发 `/new`） |
-| `/status` | 查看忙闲状态、队列长度、自动同意状态、待审批数量 |
+| `/status` | 查看忙闲状态、队列长度、自动同意状态、待审批数量、自动汇报模式 |
 | `/queue` | 查看队列（别名 `/q`）；`/queue clear` 清空，`/queue drop <编号>` 删一条 |
-| `/progress` | **立即获取当前进度摘要**并恢复自动推送（别名 `/p`、「进度」「进展」；忙碌时「到哪了」「怎么样了」这类问法同样生效） |
+| `/progress` | **立即获取当前进度摘要**（别名 `/p`、「进度」「当前进度」「进展」；忙碌时「到哪了」「怎么样了」这类问法同样生效）。手动暂停期间**问一次只回一次**，要重新打开定时汇报需发 `/progress on` 或「恢复汇报」；若只是配额静默，问一次即恢复 |
+| `/progress off` | **在本会话内暂停自动进度汇报**（别名：`pause`、`stop`、`暂停`、「暂停汇报」、「关闭汇报」）。手动 `/progress` 仍可看一次，但不再解除暂停 |
+| `/progress on` | **恢复自动进度汇报**（别名：`resume`、`start`、`恢复`、「恢复汇报」、「继续汇报」） |
 | `/cancel` | **中断当前正在运行的任务**并清空队列（别名：`/stop`、`/abort`、「取消」、「停止」、「中止」、「终止」、「算了」） |
 | `/help` | 帮助 |
 
@@ -187,10 +189,13 @@ pi 的会话一次只跑一轮 agent run，所以串行调度由 bot 自己做
 - 工具参数先脱敏再截断，带凭据的命令不会明文出现在 QQ 里。
 - **配额感知**：一条用户消息只有 4 次被动回复额度，长任务迟早会用完。第一次发送失败就停掉本轮
   的自动推送（不重试、不刷屏）；你发 `/progress`（或「进度」）即恢复。
+- **手动暂停/恢复**：`/progress off`（或「暂停汇报」）在本会话内停掉自动推送——跨 run 保留，
+  之后问 `/progress` 也不会把它打开；`/progress on`（或「恢复汇报」）恢复。开新会话（`/new`、重启）后
+  恢复默认开启。`/status` 会显示当前处于哪种模式（开启 / 手动暂停 / 配额静默 / 配置关闭）。
 - **保护最终答案**：答案因配额发不出去时会被缓存，等你发下一条消息时以
   `（上一条回复发送失败，补发如下）` 前缀补发。
 - `agent_settled` / `/cancel` / 会话关闭时定时器都会清掉。
-- 想彻底关掉：`progress.enabled: false`。
+- 想彻底关掉（跨会话）：`progress.enabled: false`（改完需 `/new` 或重启才生效）。
 
 ### 取消正在运行的任务
 
@@ -253,6 +258,10 @@ QQ 网关对同一 bot 只保留一个活跃连接。插件用 `proper-lockfile`
 
 调试日志写入 `~/.pi/agent/pi-qqbot.log`。每行开头是**本地时间 + 时区偏移**（如 `[2026-10-24T07:39:09.762+08:00]`），和文件 mtime、进程启动时间直接对得上，不需要再拿 UTC 换算。
 
+## 变更日志
+
+见 [CHANGELOG.md](../CHANGELOG.md)：每个版本改了什么、为什么改。进度汇报的暂停/恢复（`/progress off` / `on`）在 **1.5.0** 加入。
+
 ## License
 
 MIT

package/index.ts

@@ -60,6 +60,8 @@ interface State {
   progressTimer: ReturnType<typeof setInterval> | null;
   /** 推送失败后暂停自动推送，直到用户主动询问 */
   progressPaused: boolean;
+  /** 用户手动暂停自动推送（本会话有效：跨 run 保留，/progress on 恢复） */
+  progressMuted: boolean;
   /** 最终答案发送失败时缓存，下一条消息时补发 */
   undelivered: { openid: string; text: string } | null;
 }
@@ -90,6 +92,7 @@ export function createInitialState(): State {
     progress: new ProgressTracker(),
     progressTimer: null,
     progressPaused: false,
+    progressMuted: false,
     undelivered: null,
   };
 }
@@ -242,6 +245,9 @@ export default function (
     state.cfg = cfg;
     // 新会话：清空 remember 记忆与自动同意开关（自动同意只在当前会话有效）
     state.approver.reset();
+    // 手动暂停的自动汇报同样只在本会话有效
+    state.progressMuted = false;
+    state.progressPaused = false;
     // 队列上限来自配置；新会话不继承上一个会话遗留的待执行任务
     state.queue.setLimit(cfg.queue.max);
     state.queue.clear();
@@ -719,7 +725,8 @@ export async function handleMessage(
         msg.openid,
         [
           "pi-qqbot 指令:",
-          "/status — 查看状态（忙闲 / 队列 / 自动同意 / 待审批）",
+          "/progress — 查看进度；/progress off 暂停自动汇报、/progress on 恢复（本会话有效）",
+          "/status — 查看状态（忙闲 / 队列 / 自动同意 / 待审批 / 自动汇报）",
           "/queue — 查看队列；/queue clear 清空；/queue drop <编号> 删一条",
           "/reset — 清空回复缓冲、审批记忆与自动同意（不换会话；换会话发 /new）",
           "/cancel（或「取消」「停止」）— 中断正在运行的任务并清空队列",
@@ -737,24 +744,66 @@ export async function handleMessage(
         `队列: ${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);
-        // 用户主动问询：恢复自动推送
-        state.progressPaused = false;
+        // 用户主动问询：恢复自动推送（手动暂停的不算）
+        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();
-      state.progressPaused = false;
+      if (!state.progressMuted) state.progressPaused = false;
+      const body = snapshot || (state.busy ? "当前任务刚启动，还没有可汇报的进度。" : "当前没有正在运行的任务。");
       await replyTo(
         api,
         state,
         msg.openid,
-        snapshot || (state.busy ? "当前任务刚启动，还没有可汇报的进度。" : "当前没有正在运行的任务。"),
+        state.progressMuted ? `${body}\n（自动汇报已暂停，发 /progress on 恢复）` : body,
       );
       return;
     }
@@ -774,7 +823,7 @@ export async function handleMessage(
       // 忙碌时问「进度」不该排队，直接回当前进度并恢复自动推送
       if (RE_PROGRESS_QUERY.test(msg.content.trim())) {
         const snapshot = state.progress.summary();
-        state.progressPaused = false;
+        if (!state.progressMuted) state.progressPaused = false;
         await replyTo(api, state, msg.openid, snapshot || "任务刚启动，还没有可汇报的进度。");
         return;
       }
@@ -845,9 +894,9 @@ function stopProgressTimer(state: State) {
   }
 }
 
-/** 推一条进度摘要；失败就暂停自动推送（用户问一次即恢复） */
+/** 推一条进度摘要；失败就暂停自动推送（用户问一次即恢复）；手动暂停（/progress off）管到底 */
 async function pushProgress(state: State, reason: "tick" | "ask"): Promise<boolean> {
-  if (reason === "tick" && state.progressPaused) return false;
+  if (reason === "tick" && (state.progressPaused || state.progressMuted)) return false;
   const api = state.api;
   const openid = state.currentOpenid ?? state.lastOpenid;
   if (!api || !openid || !state.busy || !state.progress.running) return false;
@@ -861,19 +910,75 @@ async function pushProgress(state: State, reason: "tick" | "ask"): Promise<boole
   return ok;
 }
 
+/** 自动汇报当前状态的人话描述（/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;
+  return `开启（每 ${Math.round(ms / 1000)}s）`;
+}
+
+/** /progress 的子命令：暂停 / 恢复自动汇报 */
+const MUTE_ARGS = new Set([
+  "off",
+  "pause",
+  "stop",
+  "mute",
+  "关",
+  "关闭",
+  "关掉",
+  "停",
+  "停止",
+  "暂停",
+  "暂停汇报",
+  "停止汇报",
+]);
+const UNMUTE_ARGS = new Set([
+  "on",
+  "resume",
+  "start",
+  "unmute",
+  "开",
+  "开启",
+  "打开",
+  "恢复",
+  "继续",
+  "恢复汇报",
+  "开启汇报",
+  "继续汇报",
+]);
+
+/** 不带斜杠的「暂停汇报」类说法（整句匹配，避免误伤正常聊天） */
+const RE_REPORTS_OFF =
+  /^(?:请|帮我|给我)?\s*(?:暂停|停止|关闭|关掉|别|不要|别再)(?:自动)?(?:的)?(?:进度汇报|进度|进展|汇报|推送|播报|报告)(?:上报|推送|汇报)?(?:了|吧)?$/;
+const RE_REPORTS_ON =
+  /^(?:请|帮我|给我)?\s*(?:恢复|继续|开启|打开|开始)(?:自动)?(?:的)?(?:进度汇报|进度|进展|汇报|推送|播报|报告)(?:上报|推送|汇报)?(?:吧)?$/;
+
+/** 不带斜杠的进度问询：「进度」「当前进度」「现在进展」（可带子命令） */
+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 路由接管，真的开新会话），
   // 本地的「清缓冲/清审批记忆」改名为 /reset。
   // 斜杠形式：全部内置指令；不带斜杠时只接受明确表达「进度」的词，避免把聊天里的 "p" / "status" 误判成命令
-  const m = /^\/(reset|status|help|queue|q|progress|p)(?:\s+([\s\S]*))?$/i.exec(text.trim())
-    ?? /^(progress|进度|进展)(?:\s+([\s\S]*))?$/i.exec(text.trim());
-  if (!m) return null;
-  const raw = m[1].toLowerCase();
-  const name = raw === "q" ? "queue" : raw === "p" || raw === "进度" || raw === "进展" ? "progress" : raw;
-  return {
-    name: name as "reset" | "status" | "help" | "queue" | "progress",
-    args: (m[2] ?? "").trim(),
-  };
+  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)) return { name: "progress", args: "off" };
+  if (RE_REPORTS_ON.test(t)) return { name: "progress", args: "on" };
+  return null;
 }
 
 /** /queue [clear|drop <编号>] */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zxh126/pi-qqbot",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "type": "module",
   "description": "Bridge the Pi coding agent into QQ private chats, with remote tool-call approval",
   "license": "MIT",
@@ -34,6 +34,7 @@
     "qq",
     "util",
     "README.md",
+    "CHANGELOG.md",
     "docs",
     "LICENSE"
   ],