@zxh126/pi-qqbot 1.3.3 → 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,7 +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. |
-| **Built-in commands** | `/status`, `/queue`, `/reset`, `/cancel`, `/help`. |
+| **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` (+ `/progress off` / `on`), `/reset`, `/cancel`, `/help`. |
 
 ## Install
 
@@ -61,6 +63,8 @@ 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 (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) |
 
@@ -73,8 +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** (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 |
 
@@ -176,6 +183,31 @@ Semantics:
 - `/cancel` empties the queue as well, because "cancel" means "stop doing all of this". Use `/queue drop <id>`
   to remove a single entry instead.
 
+### Progress reports
+
+While a run is in progress, a summary is pushed to QQ every `progress.intervalMs` (15 s by default):
+
+```
+[进度 02:15] · 第 3 轮 · 工具 6 次（bash 4 / read 2）· 失败 1
+最近: bash "npm test" · 6.2s
+正在: 分析测试输出… · 12.3k tok
+```
+
+- Built purely from local event data (`tool_execution_*`, `turn_end`, `message_end`, `message_update`)
+  — **no model call, no tokens spent**.
+- Tool arguments are redacted and truncated, so a command carrying a token never reaches QQ in clear.
+- **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 (across sessions; read at session start).
+
 ### Cancelling a run
 
 Long tasks started from QQ (installs, builds, a runaway agent loop) can be interrupted without going
@@ -240,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/config.ts

@@ -17,6 +17,13 @@ export interface ApproveConfig {
   remember: boolean;
 }
 
+export interface ProgressConfig {
+  /** 是否自动推送进度摘要（默认开） */
+  enabled: boolean;
+  /** 推送间隔（毫秒，默认 15000；可用 PI_QQBOT_PROGRESS_MS 覆盖，便于测试） */
+  intervalMs: number;
+}
+
 export interface QQBotConfig {
   appId: string;
   appSecret: string;
@@ -30,6 +37,8 @@ export interface QQBotConfig {
   commands: CommandConfig;
   /** 忙碌时的消息队列 */
   queue: QueueConfig;
+  /** 任务进度摘要推送 */
+  progress: ProgressConfig;
 }
 
 export function loadConfig(): QQBotConfig | null {
@@ -64,5 +73,9 @@ export function loadConfig(): QQBotConfig | null {
       max: file.queue?.max ?? DEFAULT_QUEUE_MAX,
       ack: file.queue?.ack ?? true,
     },
+    progress: {
+      enabled: file.progress?.enabled ?? true,
+      intervalMs: Number(process.env.PI_QQBOT_PROGRESS_MS ?? file.progress?.intervalMs ?? 15000),
+    },
   };
 }

package/docs/README.zh-CN.md

@@ -17,7 +17,9 @@
 | **单实例锁** | 只有一个 pi 进程作为宿主连接 QQ，其余待命，宿主退出后自动接管。 |
 | **中断正在运行的任务** | 发 `/cancel`（或「取消」/「停止」），当前任务立刻中断 —— QQ 回复、待审批工具调用、写到一半的回答、排队中的消息一并清理。 |
 | **斜杠命令路由** | 以 `/` 开头的 QQ 消息会先被路由：pi 的扩展命令、prompt 模板、`/skill:name` 交给 pi 派发；一部分 pi 内置命令（`/reload`、`/new`、`/compact`、`/session`、`/name`、`/model`、`/thinking`、`/quit`）由本扩展接管；只能在主机执行的内置命令直接回执，不会送给模型。 |
-| **内置指令** | `/status`、`/queue`、`/reset`、`/cancel`、`/help`。 |
+| **进度汇报** | 任务运行期间按 `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`。 |
 
 ## 安装
 
@@ -63,6 +65,8 @@ pi install ./pi-qqbot
 | `commands` | 见下 | 斜杠命令路由开关：`passthrough`、`allowReload`、`allowQuit`、`allowSession` |
 | `queue.max` | `20` | 任务运行期间最多排队多少条；`0` = 关闭排队（忙碌时直接拒绍，回到旧行为） |
 | `queue.ack` | `true` | 排队消息开始执行时是否回执 QQ（入队回执总是会发） |
+| `progress.enabled` | `true` | 任务运行期间是否定期推送进度摘要（会话启动时读取，改完需 `/new` 或重启；运行时用 `/progress off`） |
+| `progress.intervalMs` | `15000` | 推送间隔（可用环境变量 `PI_QQBOT_PROGRESS_MS` 覆盖，便于测试） |
 
 也可用环境变量 `QQ_BOT_APPID` / `QQ_BOT_APPSECRET` 代替文件里的凭据。
 
@@ -73,8 +77,11 @@ pi install ./pi-qqbot
 | 指令 | 说明 |
 |---|---|
 | `/reset` | 重置：清空回复缓冲、审批记忆与自动同意开关（**不换会话**，换会话发 `/new`） |
-| `/status` | 查看忙闲状态、队列长度、自动同意状态、待审批数量 |
+| `/status` | 查看忙闲状态、队列长度、自动同意状态、待审批数量、自动汇报模式 |
 | `/queue` | 查看队列（别名 `/q`）；`/queue clear` 清空，`/queue drop <编号>` 删一条 |
+| `/progress` | **立即获取当前进度摘要**（别名 `/p`、「进度」「当前进度」「进展」；忙碌时「到哪了」「怎么样了」这类问法同样生效）。手动暂停期间**问一次只回一次**，要重新打开定时汇报需发 `/progress on` 或「恢复汇报」；若只是配额静默，问一次即恢复 |
+| `/progress off` | **在本会话内暂停自动进度汇报**（别名：`pause`、`stop`、`暂停`、「暂停汇报」、「关闭汇报」）。手动 `/progress` 仍可看一次，但不再解除暂停 |
+| `/progress on` | **恢复自动进度汇报**（别名：`resume`、`start`、`恢复`、「恢复汇报」、「继续汇报」） |
 | `/cancel` | **中断当前正在运行的任务**并清空队列（别名：`/stop`、`/abort`、「取消」、「停止」、「中止」、「终止」、「算了」） |
 | `/help` | 帮助 |
 
@@ -167,6 +174,29 @@ pi 的会话一次只跑一轮 agent run，所以串行调度由 bot 自己做
   都立即生效。
 - `/cancel` 会连队列一起清空（“取消”就是“都别做了”）；只想删一条请用 `/queue drop <编号>`。
 
+### 任务进度汇报
+
+任务运行期间，每 `progress.intervalMs`（默认 15 秒）推一条摘要到 QQ：
+
+```
+[进度 02:15] · 第 3 轮 · 工具 6 次（bash 4 / read 2）· 失败 1
+最近: bash "npm test" · 6.2s
+正在: 分析测试输出… · 12.3k tok
+```
+
+- 全部由本地事件拼出来（`tool_execution_*`、`turn_end`、`message_end`、`message_update`），
+  **不调用模型、不花 token**。
+- 工具参数先脱敏再截断，带凭据的命令不会明文出现在 QQ 里。
+- **配额感知**：一条用户消息只有 4 次被动回复额度，长任务迟早会用完。第一次发送失败就停掉本轮
+  的自动推送（不重试、不刷屏）；你发 `/progress`（或「进度」）即恢复。
+- **手动暂停/恢复**：`/progress off`（或「暂停汇报」）在本会话内停掉自动推送——跨 run 保留，
+  之后问 `/progress` 也不会把它打开；`/progress on`（或「恢复汇报」）恢复。开新会话（`/new`、重启）后
+  恢复默认开启。`/status` 会显示当前处于哪种模式（开启 / 手动暂停 / 配额静默 / 配置关闭）。
+- **保护最终答案**：答案因配额发不出去时会被缓存，等你发下一条消息时以
+  `（上一条回复发送失败，补发如下）` 前缀补发。
+- `agent_settled` / `/cancel` / 会话关闭时定时器都会清掉。
+- 想彻底关掉（跨会话）：`progress.enabled: false`（改完需 `/new` 或重启才生效）。
+
 ### 取消正在运行的任务
 
 从 QQ 发起的耗时任务（装依赖、编译、agent 跑飞了）不必回到机器上处理：
@@ -228,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

@@ -18,6 +18,8 @@ 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 { redactSecrets } from "./redact";
 import { ReplyBuffer } from "./stream-buffer";
 import { splitText } from "./util/chunk";
 
@@ -52,6 +54,16 @@ interface State {
   runStarted: boolean;
   /** /cancel 之后等 agent_settled 的兜底定时器 */
   cancelTimer: ReturnType<typeof setTimeout> | null;
+  /** 任务进度摘要 */
+  progress: ProgressTracker;
+  /** 自动推送进度的定时器 */
+  progressTimer: ReturnType<typeof setInterval> | null;
+  /** 推送失败后暂停自动推送，直到用户主动询问 */
+  progressPaused: boolean;
+  /** 用户手动暂停自动推送（本会话有效：跨 run 保留，/progress on 恢复） */
+  progressMuted: boolean;
+  /** 最终答案发送失败时缓存，下一条消息时补发 */
+  undelivered: { openid: string; text: string } | null;
 }
 
 /** 扩展运行所需的状态（导出只为测试用） */
@@ -77,6 +89,11 @@ export function createInitialState(): State {
     dispatching: false,
     runStarted: false,
     cancelTimer: null,
+    progress: new ProgressTracker(),
+    progressTimer: null,
+    progressPaused: false,
+    progressMuted: false,
+    undelivered: null,
   };
 }
 
@@ -93,19 +110,46 @@ export default function (
     state.cancelled = false;
     state.runStarted = true;
     clearCancelTimer(state);
+    state.progress.start();
+    state.progressPaused = false;
+    startProgressTimer(pi, state);
   });
 
   // ---- 事件：累积 assistant 文本 ----
   pi.on("message_update", (event) => {
     const ev = event.assistantMessageEvent as any;
     if (ev?.type === "text_delta") {
-      state.replyBuffer.append(ev.delta ?? ev.text ?? "");
+      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;
@@ -118,8 +162,17 @@ export default function (
       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) => log("[reply] 发送失败:", String(e)));
+        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 的派发阶段）
@@ -192,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();
@@ -237,6 +293,7 @@ export default function (
   pi.on("session_shutdown", async () => {
     log("[shutdown] 清理资源");
     clearCancelTimer(state);
+    stopProgressTimer(state);
     const dropped = state.queue.clear();
     if (dropped.length > 0) log("[shutdown] 丢弃队列任务", dropped.length, "条");
     if (state.stopRetry) state.stopRetry();
@@ -476,6 +533,8 @@ async function handleCancel(
     return;
   }
 
+  stopProgressTimer(state);
+  state.progress.stop();
   state.cancelled = true;
   state.replyBuffer.reset();
   state.currentOpenid = null; // 被中止的 run 不再往 QQ 发半截回复
@@ -516,6 +575,18 @@ export async function handleMessage(
     }
     state.passiveRefs.set(msg.openid, { msgId: msg.msgId, receivedAt: Date.now() });
 
+    // 上一条最终答案没发出去（配额耗尽）：先补发
+    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 (state.picker) {
       if (pickerExpired(state.picker)) {
@@ -654,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（或「取消」「停止」）— 中断正在运行的任务并清空队列",
@@ -667,16 +739,71 @@ export async function handleMessage(
       return;
     }
     if (cmd?.name === "status") {
+      const lines = [
+        `状态: ${state.busy ? "处理中（发送 /cancel 可中断）" : state.queue.size > 0 ? "空闲，但有排队任务待派发" : "空闲"}`,
+        `队列: ${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.busy ? "处理中（发送 /cancel 可中断）" : state.queue.size > 0 ? "空闲，但有排队任务待派发" : "空闲"}`,
-          `队列: ${state.queue.size} 条待执行${state.queue.size > 0 ? "（发 /queue 查看）" : ""}`,
-          `自动同意: ${state.approver.autoAllowed ? "已开启（本会话有效）" : "未开启"}`,
-          `待审批: ${state.approver.pendingCount}`,
-        ].join("\n"),
+        state.progressMuted ? `${body}\n（自动汇报已暂停，发 /progress on 恢复）` : body,
       );
       return;
     }
@@ -693,6 +820,13 @@ export async function handleMessage(
 
     // 忙检查：单会话串行处理——忙碌时入队，当前任务结束后自动继续
     if (isBusy(state)) {
+      // 忙碌时问「进度」不该排队，直接回当前进度并恢复自动推送
+      if (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);
       return;
     }
@@ -713,29 +847,138 @@ async function replyTo(
   openid: string,
   text: string,
   format: "text" | "markdown" = "text",
-) {
+): Promise<boolean> {
   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;
+  const api = state.api;
+  const openid = state.currentOpenid ?? state.lastOpenid;
+  if (!api || !openid || !state.busy || !state.progress.running) return false;
+  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 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）`;
 }
 
-function parseCommand(text: string): { name: "reset" | "status" | "help" | "queue"; args: string } | null {
+/** /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。
-  const m = /^\/(reset|status|help|queue|q)(?:\s+([\s\S]*))?$/i.exec(text.trim());
-  if (!m) return null;
-  const raw = m[1].toLowerCase();
-  return {
-    name: (raw === "q" ? "queue" : raw) as "reset" | "status" | "help" | "queue",
-    args: (m[2] ?? "").trim(),
-  };
+  // 斜杠形式：全部内置指令；不带斜杠时只接受明确表达「进度」的词，避免把聊天里的 "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)) return { name: "progress", args: "off" };
+  if (RE_REPORTS_ON.test(t)) return { name: "progress", args: "on" };
+  return null;
 }
 
 /** /queue [clear|drop <编号>] */
@@ -778,17 +1021,19 @@ async function handleQueueCommand(api: QQApi, state: State, openid: string, args
 /** 从 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}: ${String(input.command ?? "").slice(0, 200)}`;
+      return `${event.toolName}: ${clip(input.command)}`;
     case "write":
     case "edit":
     case "read":
-      return `${event.toolName}: ${String(input.path ?? input.file ?? input.filePath ?? "").slice(0, 200)}`;
+      return `${event.toolName}: ${clip(input.path ?? input.file ?? input.filePath)}`;
     case "grep":
-      return `${event.toolName}: ${String(input.pattern ?? "").slice(0, 200)}`;
+      return `${event.toolName}: ${clip(input.pattern)}`;
     default:
-      return `${event.toolName}: ${JSON.stringify(input).slice(0, 200)}`;
+      return `${event.toolName}: ${clip(JSON.stringify(input))}`;
   }
 }

package/logger.ts

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { redactSecrets } from "./redact";
 
 const LOG_PATH = path.join(os.homedir(), ".pi", "agent", "pi-qqbot.log");
 
@@ -25,7 +26,9 @@ export function timestamp(date = new Date()): string {
 }
 
 export function log(...args: unknown[]) {
-  const line = `[${timestamp()}] ${args.map((a) => (typeof a === "string" ? a : JSON.stringify(a))).join(" ")}\n`;
+  const body = args.map((a) => (typeof a === "string" ? a : JSON.stringify(a))).join(" ");
+  // 日志会留在磁盘上：落盘前统一脱敏（Authorization、token=、URL userinfo、私钥块等）
+  const line = `[${timestamp()}] ${redactSecrets(body)}\n`;
   try {
     fs.appendFileSync(LOG_PATH, line, "utf8");
   } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zxh126/pi-qqbot",
-  "version": "1.3.3",
+  "version": "1.5.0",
   "type": "module",
   "description": "Bridge the Pi coding agent into QQ private chats, with remote tool-call approval",
   "license": "MIT",
@@ -27,21 +27,26 @@
     ]
   },
   "scripts": {
-    "test": "node test/queue.test.mjs && node test/logger.test.mjs && node test/usage-bridge.test.mjs"
+    "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"
   },
   "files": [
     "*.ts",
     "qq",
     "util",
     "README.md",
+    "CHANGELOG.md",
     "docs",
     "LICENSE"
   ],
   "dependencies": {
-    "ws": "^8.18.0",
-    "proper-lockfile": "^4.1.2"
+    "proper-lockfile": "^4.1.2",
+    "ws": "^8.18.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@types/proper-lockfile": "^4.1.4",
+    "@types/ws": "^8.18.2"
   }
 }

package/progress.ts

@@ -0,0 +1,176 @@
+/**
+ * 任务进度摘要：把 run 期间的事件（轮次、工具调用、流式文本、token）压成一条
+ * 适合发到 QQ 的短消息。纯本地字符串拼接，不产生任何模型调用。
+ */
+
+import { redactSecrets, shortRedacted } from "./redact";
+
+export interface ProgressSettings {
+  /** 是否自动推送进度 */
+  enabled: boolean;
+  /** 推送间隔（毫秒） */
+  intervalMs: number;
+}
+
+const MAX_PROGRESS_CHARS = 320;
+const TOOL_PREVIEW_CHARS = 60;
+const TAIL_CHARS = 120;
+
+/** 把工具参数压成一句人能看懂的话（已脱敏、已截断） */
+export function toolPreview(toolName: string, args: any): string {
+  const input = args ?? {};
+  switch (toolName) {
+    case "bash":
+    case "powershell":
+      return shortRedacted(input.command ?? "");
+    case "write":
+    case "edit":
+    case "read":
+      return shortRedacted(input.path ?? input.file ?? input.filePath ?? "");
+    case "grep":
+    case "bgrep":
+      return shortRedacted(input.pattern ?? "");
+    case "glob":
+    case "find":
+      return shortRedacted(input.pattern ?? input.path ?? "");
+    default:
+      try {
+        return shortRedacted(JSON.stringify(input));
+      } catch {
+        return shortRedacted(String(input));
+      }
+  }
+}
+
+const fmtDuration = (ms: number): string => {
+  const total = Math.max(0, Math.round(ms / 1000));
+  const h = Math.floor(total / 3600);
+  const m = Math.floor((total % 3600) / 60);
+  const s = total % 60;
+  if (h > 0) return `${h}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
+  return `${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
+};
+
+const fmtTokens = (n: number): string =>
+  n >= 1_000_000 ? `${(n / 1_000_000).toFixed(2)}M` : n >= 1_000 ? `${(n / 1_000).toFixed(1)}k` : String(n);
+
+interface OpenTool {
+  name: string;
+  preview: string;
+  startedAt: number;
+}
+
+export class ProgressTracker {
+  running = false;
+  private startedAt = 0;
+  private turns = 0;
+  private counts = new Map<string, number>();
+  private failures = 0;
+  private tokens = 0;
+  private tail = "";
+  private open = new Map<string, OpenTool>();
+  private last: { name: string; preview: string; ms?: number; ok?: boolean } | null = null;
+
+  start(now = Date.now()): void {
+    this.running = true;
+    this.startedAt = now;
+    this.turns = 0;
+    this.counts.clear();
+    this.failures = 0;
+    this.tokens = 0;
+    this.tail = "";
+    this.open.clear();
+    this.last = null;
+  }
+
+  stop(): void {
+    this.running = false;
+    this.open.clear();
+    this.tail = "";
+  }
+
+  toolStart(callId: string, toolName: string, args: any, now = Date.now()): void {
+    if (!this.running) return;
+    const name = toolName || "tool";
+    this.open.set(callId, { name, preview: toolPreview(name, args), startedAt: now });
+    this.counts.set(name, (this.counts.get(name) ?? 0) + 1);
+    this.tail = "";
+  }
+
+  toolEnd(callId: string, toolName: string, isError: boolean, durationMs?: number, now = Date.now()): void {
+    if (!this.running) return;
+    const open = this.open.get(callId);
+    this.open.delete(callId);
+    if (isError) this.failures += 1;
+    this.last = {
+      name: open?.name ?? toolName ?? "tool",
+      preview: open?.preview ?? "",
+      ms: typeof durationMs === "number" ? durationMs : open ? now - open.startedAt : undefined,
+      ok: !isError,
+    };
+  }
+
+  turn(): void {
+    if (this.running) this.turns += 1;
+  }
+
+  addUsage(usage: any): void {
+    if (!this.running) return;
+    const total = Number(usage?.totalTokens ?? 0);
+    if (Number.isFinite(total) && total > 0) this.tokens += total;
+  }
+
+  appendText(delta: string): void {
+    if (!this.running || !delta) return;
+    this.tail = `${this.tail}${delta}`.slice(-TAIL_CHARS * 2);
+  }
+
+  /** 当前正在执行的工具（如果卡在某个长命令上，这比「正在写」有用） */
+  private runningTool(): OpenTool | null {
+    let newest: OpenTool | null = null;
+    for (const tool of this.open.values()) {
+      if (!newest || tool.startedAt > newest.startedAt) newest = tool;
+    }
+    return newest;
+  }
+
+  /** 一条可直接发到 QQ 的摘要；没有可说的内容时返回空串 */
+  summary(now = Date.now()): string {
+    if (!this.running) return "";
+    const head: string[] = [`[进度 ${fmtDuration(now - this.startedAt)}]`];
+    if (this.turns > 0) head.push(`第 ${this.turns} 轮`);
+
+    const totalCalls = [...this.counts.values()].reduce((sum, n) => sum + n, 0);
+    if (totalCalls > 0) {
+      const top = [...this.counts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 3)
+        .map(([name, n]) => `${name} ${n}`)
+        .join(" / ");
+      head.push(`工具 ${totalCalls} 次（${top}）`);
+    }
+    if (this.failures > 0) head.push(`失败 ${this.failures}`);
+
+    const lines: string[] = [head.join(" · ")];
+
+    if (this.last) {
+      const timing = this.last.ms !== undefined ? ` · ${(this.last.ms / 1000).toFixed(1)}s` : "";
+      const status = this.last.ok === false ? " · 失败" : "";
+      const preview = this.last.preview ? ` "${this.last.preview}"` : "";
+      lines.push(`最近: ${this.last.name}${preview}${timing}${status}`);
+    }
+
+    const active = this.runningTool();
+    if (active) {
+      lines.push(`正在: ${active.name}${active.preview ? ` "${active.preview}"` : ""}（已 ${(Math.max(0, now - active.startedAt) / 1000).toFixed(0)}s）`);
+    } else {
+      const tail = shortRedacted(this.tail.slice(-TAIL_CHARS), TAIL_CHARS);
+      if (tail) lines.push(`正在: ${tail}`);
+    }
+
+    if (this.tokens > 0) lines.push(`已用 ${fmtTokens(this.tokens)} tok`);
+
+    const text = redactSecrets(lines.join("\n"));
+    return text.length > MAX_PROGRESS_CHARS ? `${text.slice(0, MAX_PROGRESS_CHARS)}…` : text;
+  }
+}

package/qq/auth.ts

@@ -20,7 +20,7 @@ export class AuthManager {
     });
     if (!res.ok) throw new Error(`getAppAccessToken failed: HTTP ${res.status}`);
     const data = (await res.json()) as any;
-    this.token = data.access_token;
+    this.token = String(data.access_token ?? "");
     this.expireAt = Date.now() + Number(data.expires_in) * 1000;
     return this.token;
   }

package/qq/gateway.ts

@@ -105,7 +105,7 @@ export class QQGateway {
     const ws = new WebSocket(url);
     this.ws = ws;
     ws.on("open", () => log("[gateway] WebSocket 已连接，等待 HELLO..."));
-    ws.on("message", (raw) => {
+    ws.on("message", (raw: any) => {
       let pkt: any;
       try {
         pkt = JSON.parse(raw.toString());
@@ -115,7 +115,7 @@ export class QQGateway {
       }
       this.handlePacket(pkt);
     });
-    ws.on("close", (code) => {
+    ws.on("close", (code: number) => {
       log("[gateway] WebSocket 关闭 code=", code);
       this.opts.disconnected();
       this.scheduleReconnect();

package/queue.ts

@@ -1,3 +1,5 @@
+import { redactSecrets } from "./redact";
+
 /**
  * QQ 侧任务队列。
  *
@@ -29,12 +31,12 @@ export type PushResult =
 	| { ok: false; reason: "full" };
 
 export const DEFAULT_QUEUE_MAX = 20;
-
 /** 单条预览的最大字符数 */
 const PREVIEW_MAX = 48;
 
 export function previewText(text: string, max = PREVIEW_MAX): string {
-	const flat = text.replace(/\s+/g, " ").trim();
+	// 预览会回显到 QQ 和日志：先脱敏
+	const flat = redactSecrets(text).replace(/\s+/g, " ").trim();
 	return flat.length > max ? `${flat.slice(0, max)}…` : flat || "(空消息)";
 }
 

package/redact.ts

@@ -0,0 +1,136 @@
+/**
+ * 敏感信息脱敏。
+ *
+ * 所有要「离开本地」或「落盘」的文本都应该先过这里：
+ *   - 发到 QQ 的消息（进度摘要、审批提示、队列预览）
+ *   - pi-qqbot.log
+ *
+ * 原则：
+ *   1. 认得出的凭据一律替换成 `***`（保留键名，方便排错）
+ *   2. 不碰正常内容（路径、命令、中文句子、git sha、UUID）
+ *   3. 幂等：对已脱敏文本再跑一次不会再变形
+ */
+
+/** PEM 私钥 / 证书块：整块替换 */
+const PEM_BLOCK =
+  /-----BEGIN [A-Z0-9 ]*(?:PRIVATE KEY|CERTIFICATE)-----[\s\S]*?-----END [A-Z0-9 ]*(?:PRIVATE KEY|CERTIFICATE)-----/g;
+
+/** `Authorization: Bearer xxx` / `QQBot xxx` / `Bot xxx` / `Token xxx` */
+const AUTH_HEADER =
+  /\b(authorization\s*[:=]\s*)(?:(?:bearer|basic|token|qqbot|bot|digest)\s+)?[^\s"',;]{6,}/gi;
+
+/** URL 里的 user:password@host */
+const URL_USERINFO = /\b([a-z][a-z0-9+.-]*:\/\/)[^\s/:@]+:[^\s/@]+@/gi;
+
+/** 敏感的键名（键值对 / JSON / 查询参数 / --flag） */
+const SENSITIVE_KEYS = [
+  'access[_-]?token',
+  'refresh[_-]?token',
+  'id[_-]?token',
+  'auth[_-]?token',
+  'api[_-]?key',
+  'apikey',
+  'x-api-key',
+  'client[_-]?id',
+  'client[_-]?secret',
+  'app[_-]?secret',
+  'appsecret',
+  'secret[_-]?key',
+  'private[_-]?key',
+  'session[_-]?id',
+  'sessionid',
+  'password',
+  'passwd',
+  'pwd',
+  'passphrase',
+  'credentials?',
+  'authorization',
+  'cookie',
+  'set-cookie',
+  'signature',
+  'sign',
+  'nonce',
+  'ticket',
+  'secret',
+].join('|');
+
+/** `key=value` / `"key": "value"` / `key: value`（值两侧的引号一并吃掉） */
+const KEY_VALUE = new RegExp(
+  `((?<![A-Za-z0-9_])(?:${SENSITIVE_KEYS})(?:["']?\\s*[:=]\\s*["']?))(?!\\*\\*\\*)[^\\s"',;&]{3,}`,
+  'gi',
+);
+
+/** 命令行形式：`--token xxx` / `--api-key xxx`（只认带短横线的 flag，避免误伤普通词） */
+const FLAG_VALUE = new RegExp(
+  `((?:^|\\s)--?(?:access-token|api-key|apikey|token|auth-token|client-secret|secret|password|passwd|pwd)\\s+["']?)(?!\\*\\*\\*)[^\\s"',;&]{3,}`,
+  'gi',
+);
+
+/** 中文键名 */
+const CN_KEY_VALUE = /((?:密码|密钥|秘钥|令牌|凭证|口令)\s*[:：=]\s*)(?!\*{3})\S+/g;
+
+/** 已知凭据格式 */
+const TOKEN_SHAPES: Array<[RegExp, string]> = [
+  [/\bsk-(?:ant-|proj-)?[A-Za-z0-9_-]{12,}/g, 'sk-***'],
+  [/\bgithub_pat_[A-Za-z0-9_]{20,}/g, 'github_pat_***'],
+  [/\bgh[pousr]_[A-Za-z0-9]{20,}/g, 'gh*_***'],
+  [/\bnpm_[A-Za-z0-9]{30,}/g, 'npm_***'],
+  [/\bpypi-[A-Za-z0-9_-]{20,}/g, 'pypi-***'],
+  [/\bglpat-[A-Za-z0-9_-]{16,}/g, 'glpat-***'],
+  [/\bhf_[A-Za-z0-9]{20,}/g, 'hf_***'],
+  [/\bAKIA[0-9A-Z]{16}\b/g, 'AKIA***'],
+  [/\bxox[abprs]-[A-Za-z0-9-]{10,}/g, 'xox*-***'],
+  [/\bAIza[0-9A-Za-z_-]{30,}/g, 'AIza***'],
+  [/\b(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{10,}/g, 'sk_live_***'],
+  [/\bSG\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g, 'SG.***'],
+  [/\bROBOT1\.0_[A-Za-z0-9._!-]{10,}/g, 'ROBOT1.0_***'],
+  [/\beyJ[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}/g, 'eyJ*** (JWT)'],
+];
+
+/**
+ * 兜底：超长高熵串（≥44 字符且同时含大小写与数字）。
+ * 刻意放过纯小写十六进制（git sha / md5）与带连字符的 UUID，避免把正常内容打码。
+ */
+const HIGH_ENTROPY = /\b(?=[A-Za-z0-9+/=_-]{44,}\b)(?=[^\s]*[a-z])(?=[^\s]*[A-Z])(?=[^\s]*\d)[A-Za-z0-9+/=_-]{44,}\b/g;
+
+export function redactSecrets(input: string): string {
+  if (!input) return input;
+  let out = input;
+  out = out.replace(PEM_BLOCK, '<已隐藏的私钥/证书>');
+  out = out.replace(AUTH_HEADER, '$1***');
+  out = out.replace(URL_USERINFO, '$1***:***@');
+  out = out.replace(KEY_VALUE, '$1***');
+  out = out.replace(FLAG_VALUE, '$1***');
+  out = out.replace(CN_KEY_VALUE, '$1***');
+  for (const [pattern, replacement] of TOKEN_SHAPES) out = out.replace(pattern, replacement);
+  out = out.replace(HIGH_ENTROPY, '***');
+  return out;
+}
+
+/** 递归脱敏：字符串值处理，数组/对象继续下钻，其余原样 */
+export function redactDeep<T>(value: T, depth = 0): T {
+  if (depth > 6 || value == null) return value;
+  if (typeof value === 'string') return redactSecrets(value) as unknown as T;
+  if (Array.isArray(value)) return value.map((item) => redactDeep(item, depth + 1)) as unknown as T;
+  if (typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+      out[key] = /pass|secret|token|key|credential|cookie|auth|sig/i.test(key)
+        ? typeof item === 'string'
+          ? '***'
+          : '***'
+        : redactDeep(item, depth + 1);
+    }
+    return out as unknown as T;
+  }
+  return value;
+}
+
+/** 单行化 + 脱敏 + 截断（用于 QQ 消息里的参数摘要） */
+export function shortRedacted(value: unknown, limit = 60): string {
+  const flat = String(value ?? '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  const safe = redactSecrets(flat);
+  return safe.length > limit ? `${safe.slice(0, limit)}…` : safe;
+}

package/slash.ts

@@ -124,7 +124,8 @@ export interface RouteDeps {
 	 */
 	dispatch(text: string, options?: { runsTurn?: boolean }): DispatchResult;
 	/** answer the QQ user */
-	reply(text: string): Promise<void>;
+	/** 回用户一条消息（返回值忽略，允许实现返回是否送达） */
+	reply(text: string): Promise<unknown>;
 	busy: boolean;
 	cfg: CommandConfig;
 	log(message: string, ...rest: unknown[]): void;