@zxh126/pi-qqbot 1.3.2 → 1.4.0

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`, 「进度」). 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`. |
 
 ## 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 |
+| `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) |
 
@@ -75,6 +79,7 @@ Start pi, then message the bot in QQ; pi handles it and replies.
 | `/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 |
 | `/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) |
 | `/cancel` | **Interrupt the task that is running right now** and empty the queue (aliases: `/stop`, `/abort`, 「取消」, 「停止」, 「中止」, 「终止」, 「算了」) |
 | `/help` | Show help |
 
@@ -117,7 +122,7 @@ Some extension commands never print into the conversation — they call `ctx.ui.
 
 | Command | What happens |
 |---|---|
-| `/usage [range]`, `/cost [range]` | re-dispatched as `/qq usage <range>`: the bridge runs the original `/usage` command, then reads the **fresh** `customType: "usage-report"` entry — first from `sessionManager.getEntries()`, and if that view has not picked up the append yet, straight from the tail of the session file — and renders it as text (requests, tokens, cache ratio, cost, per-model). **Usage unchanged** — keep sending `/usage today`. |
+| `/usage [range]`, `/cost [range]` | re-dispatched as `/qq usage <range>`: the bridge runs the original `/usage` command, then **polls** for the fresh `customType: "usage-report"` entry for up to 2 s (the append lands ~100 ms *after* `sendUserMessage()` resolves, so a single read always misses it), falling back to the tail of the session file, and renders it as text (requests, tokens, cache ratio, cost, per-model). **Usage unchanged** — keep sending `/usage today`. |
 | `/usage rate <value>`, `/usage rate auto` | really executed (they write `~/.pi/agent/pi-usage-report.json` / refresh the cached rate); the bridge then reads those files back and reports the resulting rate, so an invalid value shows up as "unchanged" |
 | `/mcp`, `/llama` | answered: they need host-TUI selection dialogs / browser login, so nothing is dispatched |
 
@@ -176,6 +181,27 @@ 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.
+- **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.
+
 ### Cancelling a run
 
 Long tasks started from QQ (installs, builds, a runaway agent loop) can be interrupted without going

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`、「进度」）可立即获取；推送失败后自动推送静默，直到你再次问询。 |
+| **敏感信息脱敏** | 离开本机的文本先脱敏——进度摘要、审批提示、队列预览、日志文件：`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` | 任务运行期间是否定期推送进度摘要 |
+| `progress.intervalMs` | `15000` | 推送间隔（可用环境变量 `PI_QQBOT_PROGRESS_MS` 覆盖，便于测试） |
 
 也可用环境变量 `QQ_BOT_APPID` / `QQ_BOT_APPSECRET` 代替文件里的凭据。
 
@@ -75,6 +79,7 @@ pi install ./pi-qqbot
 | `/reset` | 重置：清空回复缓冲、审批记忆与自动同意开关（**不换会话**，换会话发 `/new`） |
 | `/status` | 查看忙闲状态、队列长度、自动同意状态、待审批数量 |
 | `/queue` | 查看队列（别名 `/q`）；`/queue clear` 清空，`/queue drop <编号>` 删一条 |
+| `/progress` | **立即获取当前进度摘要**并恢复自动推送（别名 `/p`、「进度」「进展」；忙碌时「到哪了」「怎么样了」这类问法同样生效） |
 | `/cancel` | **中断当前正在运行的任务**并清空队列（别名：`/stop`、`/abort`、「取消」、「停止」、「中止」、「终止」、「算了」） |
 | `/help` | 帮助 |
 
@@ -115,7 +120,7 @@ TUI/RPC 前端。在 QQ 里的表现就是「已派发，然后没下文」。
 
 | 命令 | 现在发生什么 |
 |---|---|
-| `/usage [范围]`、`/cost [范围]` | 改派为 `/qq usage <范围>`：桥接先重跑原 `/usage` 命令，再取**本次新写入**的 `customType: "usage-report"` 条目（先读 `sessionManager.getEntries()` 的增量；发现另一个扩展的 `appendEntry` 还没反映到该视图时，直接读会话文件尾部），渲染成文本回 QQ（请求数/总 token/缓存比/费用/按模型）。**用法不变**，照旧发 `/usage today` |
+| `/usage [范围]`、`/cost [范围]` | 改派为 `/qq usage <范围>`：桥接先重跑原 `/usage` 命令，再**轮询等待**本次新写入的 `customType: "usage-report"` 条目（`appendEntry` 比 `sendUserMessage()` 返回晚约 100 ms，只读一次必然落空），最多等 2 秒，仍未命中才退回读会话文件尾部；然后渲染成文本回 QQ（请求数/总 token/缓存比/费用/按模型）。**用法不变**，照旧发 `/usage today` |
 | `/mcp`、`/llama` | 直接回执：它们需要主机 TUI 的选择框 / 浏览器登录，不会派发 |
 | `/usage rate <值>`、`/usage rate auto` | 会真的执行（写 `~/.pi/agent/pi-usage-report.json` / 刷新汇率缓存），桥接再读回文件确认新汇率，无效值会体现在“汇率未变”上；只发 `/usage rate` 与 `/usage help` 则本地直接回执，不执行命令 |
 
@@ -167,6 +172,26 @@ 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`（或「进度」）即恢复。
+- **保护最终答案**：答案因配额发不出去时会被缓存，等你发下一条消息时以
+  `（上一条回复发送失败，补发如下）` 前缀补发。
+- `agent_settled` / `/cancel` / 会话关闭时定时器都会清掉。
+- 想彻底关掉：`progress.enabled: false`。
+
 ### 取消正在运行的任务
 
 从 QQ 发起的耗时任务（装依赖、编译、agent 跑飞了）不必回到机器上处理：

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,14 @@ interface State {
   runStarted: boolean;
   /** /cancel 之后等 agent_settled 的兜底定时器 */
   cancelTimer: ReturnType<typeof setTimeout> | null;
+  /** 任务进度摘要 */
+  progress: ProgressTracker;
+  /** 自动推送进度的定时器 */
+  progressTimer: ReturnType<typeof setInterval> | null;
+  /** 推送失败后暂停自动推送，直到用户主动询问 */
+  progressPaused: boolean;
+  /** 最终答案发送失败时缓存，下一条消息时补发 */
+  undelivered: { openid: string; text: string } | null;
 }
 
 /** 扩展运行所需的状态（导出只为测试用） */
@@ -77,6 +87,10 @@ export function createInitialState(): State {
     dispatching: false,
     runStarted: false,
     cancelTimer: null,
+    progress: new ProgressTracker(),
+    progressTimer: null,
+    progressPaused: false,
+    undelivered: null,
   };
 }
 
@@ -93,19 +107,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 +159,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 的派发阶段）
@@ -237,6 +287,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 +527,8 @@ async function handleCancel(
     return;
   }
 
+  stopProgressTimer(state);
+  state.progress.stop();
   state.cancelled = true;
   state.replyBuffer.reset();
   state.currentOpenid = null; // 被中止的 run 不再往 QQ 发半截回复
@@ -516,6 +569,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)) {
@@ -667,16 +732,29 @@ 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}`,
+      ];
+      if (state.busy) {
+        const snapshot = state.progress.summary();
+        if (snapshot) lines.push("", snapshot);
+        // 用户主动问询：恢复自动推送
+        state.progressPaused = false;
+      }
+      await replyTo(api, state, msg.openid, lines.join("\n"));
+      return;
+    }
+    if (cmd?.name === "progress") {
+      const snapshot = state.progress.summary();
+      state.progressPaused = false;
       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"),
+        snapshot || (state.busy ? "当前任务刚启动，还没有可汇报的进度。" : "当前没有正在运行的任务。"),
       );
       return;
     }
@@ -693,6 +771,13 @@ export async function handleMessage(
 
     // 忙检查：单会话串行处理——忙碌时入队，当前任务结束后自动继续
     if (isBusy(state)) {
+      // 忙碌时问「进度」不该排队，直接回当前进度并恢复自动推送
+      if (RE_PROGRESS_QUERY.test(msg.content.trim())) {
+        const snapshot = state.progress.summary();
+        state.progressPaused = false;
+        await replyTo(api, state, msg.openid, snapshot || "任务刚启动，还没有可汇报的进度。");
+        return;
+      }
       await enqueueJob(api, state, msg.openid, msg.content);
       return;
     }
@@ -713,27 +798,80 @@ 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;
+  }
+}
+
+/** 推一条进度摘要；失败就暂停自动推送（用户问一次即恢复） */
+async function pushProgress(state: State, reason: "tick" | "ask"): Promise<boolean> {
+  if (reason === "tick" && state.progressPaused) 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;
 }
 
-function parseCommand(text: string): { name: "reset" | "status" | "help" | "queue"; args: string } | null {
+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());
+  // 斜杠形式：全部内置指令；不带斜杠时只接受明确表达「进度」的词，避免把聊天里的 "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: (raw === "q" ? "queue" : raw) as "reset" | "status" | "help" | "queue",
+    name: name as "reset" | "status" | "help" | "queue" | "progress",
     args: (m[2] ?? "").trim(),
   };
 }
@@ -778,17 +916,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.2",
+  "version": "1.4.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"
+    "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",
@@ -38,10 +38,14 @@
     "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;
@@ -382,6 +383,13 @@ export function pickerExpired(picker: PickerState | null): boolean {
 /** pi-usage-report 写入 session 的 custom entry 类型（耦合点，约定值） */
 const USAGE_ENTRY_TYPE = "usage-report";
 
+/**
+ * appendEntry 的写入比 `sendUserMessage` 的 resolve 晚（实测 promise 183ms 返回，
+ * entry 在之后 ~100ms 才出现在 getEntries 里），所以必须轮询而不是只读一次。
+ */
+const USAGE_WAIT_TIMEOUT_MS = 2000;
+const USAGE_POLL_INTERVAL_MS = 100;
+
 /** pi-usage-report 的配置/汇率缓存（读回来确认：命令真的生效了，而不是口头应下） */
 const USAGE_SETTINGS_FILE = "pi-usage-report.json";
 const USAGE_RATE_FILE = "pi-usage-report-rate.json";
@@ -483,7 +491,7 @@ function readUsageEntryFromFile(file: string | undefined, since: number): any |
 			} catch {
 				continue;
 			}
-			if (entry?.type !== "custom" || entry?.customType !== USAGE_ENTRY_TYPE) continue;
+			if (!isUsageEntry(entry)) continue;
 			const when = entryTime(entry?.data?.generatedAt ?? entry?.timestamp);
 			return Number.isFinite(when) && when >= since ? entry : undefined;
 		}
@@ -504,6 +512,28 @@ function localStamp(value: unknown): string {
 	return `${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
 }
 
+const isUsageEntry = (entry: any): boolean =>
+	entry?.type === "custom" && entry?.customType === USAGE_ENTRY_TYPE;
+
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+/**
+ * 等本次 /usage 写的报告出现：每 100ms 查一次 getEntries（最多 2s），
+ * 全程未命中再试一次会话文件（custom entry 可能很晚才落盘）。
+ */
+async function waitForUsageEntry(
+	ctx: any,
+	opts: { before: Set<unknown>; since: number; file?: string },
+): Promise<any | undefined> {
+	const deadline = Date.now() + USAGE_WAIT_TIMEOUT_MS;
+	while (Date.now() < deadline) {
+		const fresh = [...sessionEntries(ctx)].reverse().find((entry: any) => isUsageEntry(entry) && !opts.before.has(entry?.id));
+		if (fresh) return fresh;
+		await sleep(USAGE_POLL_INTERVAL_MS);
+	}
+	return readUsageEntryFromFile(opts.file, opts.since);
+}
+
 /** 把 pi-usage-report 的 ReportData 渲染成 QQ 可读的纯文本 */
 function formatUsage(data: any): string {
 	if (!data?.totals) return "用量报告为空。";
@@ -687,12 +717,8 @@ export async function runBridge(
 				reply(`统计失败：${String((error as any)?.message ?? error).slice(0, 200)}`);
 				return;
 			}
-			// 先看 sessionManager 的增量，再退回读会话文件（appendEntry 可能还没同步到视图）
-			const entry =
-				[...sessionEntries(ctx)]
-					.reverse()
-					.find((e: any) => e?.type === "custom" && e?.customType === USAGE_ENTRY_TYPE && !before.has(e?.id)) ??
-				readUsageEntryFromFile(file, since);
+			// 先轮询 getEntries 的增量（appendEntry 晚于 await 返回），超时再退回读会话文件
+			const entry = await waitForUsageEntry(ctx, { before, since, file });
 			if (!entry) {
 				reply("没拿到用量报告：/usage 已执行但找不到报告数据（可重试一次；若反复出现请把 pi-qqbot.log 尾部发我）。");
 				return;