@zxh126/pi-qqbot 1.4.0 → 2.0.0

package/docs/accounts.md

@@ -0,0 +1,88 @@
+# 多 QQ bot（2.0）
+
+一份配置里可以写多个 QQ bot；同一台机器上每个 pi 进程启动时，按配置顺序找**第一个没上线的**
+bot 接入，抢不到的进程待命并每 5 秒重扫。进程退出（或崩溃导致的锁心跳超时）后，该 bot 下线，
+待命进程接管。
+
+## 配置
+
+### 多 bot（v2）
+
+```jsonc
+// ~/.pi/agent/pi-qqbot.json
+{
+  "qqbots": [
+    { "name": "work", "appId": "1903340143", "appSecret": "……", "sandbox": true },
+    { "name": "home", "appId": "1020123456", "appSecret": "……", "sandbox": false }
+  ],
+
+  // 以下是全局默认值，qqbots 里可以逐键覆盖
+  "queue": { "max": 20, "ack": true },
+  "progress": { "enabled": true, "intervalMs": 15000 }
+}
+```
+
+- **顺序就是抢占顺序**：先起的进程拿 `work`，第二个进程拿 `home`，第三个进程抢不到就待命。
+- `name` 缺省为 `bot-<appId 后 6 位>`；日志、`/status`、接管提示都用它。
+- `name` 或 `appId` 重复、凭据缺失 → 该条被跳过并写日志，其余照常可用（不会双连接同一个 bot）。
+- 同时写顶层 `appId` 和 `qqbots` → 报错，插件不接入（歧义不猜）。
+
+### 单 bot（v1，原格式，无需改动）
+
+```json
+{ "appId": "1903340143", "appSecret": "……", "sandbox": true }
+```
+
+等价于只有一个名叫 `default` 的 bot，行为与 1.x 完全一致。凭据也仍可来自
+`QQ_BOT_APPID` / `QQ_BOT_APPSECRET` 环境变量（只用于单 bot 场景）。
+
+## 实例身份
+
+| 场景 | 表现 |
+|---|---|
+| 首次接入 | 日志 `[lock] 接入 qqbot "work" (1903340143) · cwd=E:\Projects\foo · pid=1234`；QQ 首条回执前加「（已接入 qqbot「work」）」；`/status` 显示 `bot: work (…0143) · cwd: …` |
+| 换进程接管 | 日志记录新旧 pid 与新旧 cwd；QQ 首条回执前加「（qqbot「work」已由新实例接管 · 当前工作目录 E:\Projects\foo）」 |
+| 全部在线 | 日志 `[lock] 无可接入的 qqbot（…），本进程待命，5s 后重扫`；本进程不连 QQ，pi 本身照常用 |
+| 会话重建（`/reload`、`/new`、`/fork`、`/resume`） | 释放锁**之前**先写 20 秒预约窗口，其他进程不会趁机抢走；新 runtime 用自己的 pid 认回同一个 bot，静默不打扰 |
+| 凭据无效 | 抢到锁后先换一次 `access_token`；失败就**放锁跳过该 bot**（不占槽位），继续试下一个。日志：`[lock] qqbot "x" 凭据不可用：code=100016 invalid appid or secret → 已放锁并跳过该 bot`。全部不可用时不空转重扫 |
+
+`/status` 一眼确认：
+
+```
+bot: work (…0143) · cwd: E:\Projects\foo
+状态: 空闲
+```
+
+> **工作目录与 bot 无绑定。** 分配只看「配置顺序 + 谁在线」，跟 cwd 无关：
+> 同一台机器上可以在不同的项目目录各开一个 pi，也可以在一个大工作区（里面好几个项目）里
+> 同时开几个 pi——后者照样一人接一个 bot，互不干扰。cwd 只用于日志、接管提示和 `/status` 展示，
+> 让你能分辨「现在是哪个实例在管这个 bot」。
+
+## 可选：钉住某个 bot
+
+自动抢占是默认行为。调试或需要「这个目录固定用某个 bot」时，用环境变量钉住：
+
+```powershell
+$env:PI_QQBOT_ACCOUNT = "work"; pi
+```
+
+钉选时只尝试该账号（可写 name 或 appId）；名字不存在则**不接入**并写日志（不会乱接别的 bot）。
+
+## 能/不能
+
+- **能**：同一台机器上开 N 个 pi，各接一个 bot，互不串话；目录随意（同一目录开多个也成立，目录只是 pi 的工作区）；某个 pi 退出后由待命进程接管。
+- **能**：一个 bot 同一时刻只有一个进程连着（锁 + 心跳 + 30 秒僵尸锁回收）。
+- **不能**：一个 pi 进程同时服务多个 bot（扩展的 session 是单租户模型）。要多路并行就多开 pi 进程。
+
+## 日志
+
+多 bot 场景下日志按账号分文件：`~/.pi/agent/pi-qqbot-<name>.log`（单 bot 旧格式仍写
+`pi-qqbot.log`）。身份记录与锁在 `~/.pi/agent/pi-qqbot-<appId>.lock` / `…owner.json`。
+
+## 排查：某个 bot 一直不上线
+
+1. 看日志：`凭据不可用：code=100016 invalid appid or secret` → appId/secret 写错了
+   （可用 `POST https://api.bot.qq.com/app/getAppAccessToken` 自己验一下）；
+2. 看日志：`本轮无可接入的 qqbot（x:在线）` → 这个 bot 已被别的 pi 进程连着；
+3. 看日志：`被 pid 1234 重载中` → 对方正在 `/reload`，等几秒即可；
+4. 什么都没打 → 确认配置能解析（`loadAccounts()` 报错会写 `[setup] 配置问题:`）。

package/index.ts

@@ -1,17 +1,16 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { loadConfig, QQBotConfig } from "./config";
+import { loadAccounts, pinnedAccountName, type QQBotAccount, type QQBotConfig } from "./config";
 import {
   REST_BASE_PROD,
   REST_BASE_SANDBOX,
   INTENT_GROUP_AND_C2C,
   PASSIVE_WINDOW_MS,
   APPROVAL_TIMEOUT_MS,
-  LOCK_PATH,
   DISPATCH_RETRY_MS,
   CANCEL_SETTLE_GRACE_MS,
 } from "./constants";
-import { log } from "./logger";
-import { tryAcquireLock, startLockRetry } from "./lock";
+import { log, configureLog } from "./logger";
+import { claimAny, startClaimRetry, reserveBeforeRelease, readOwner, type Claim } from "./lock";
 import { AuthManager } from "./qq/auth";
 import { QQApi } from "./qq/api";
 import { createGatewayUrlFetcher, QQGateway, QQMessage } from "./qq/gateway";
@@ -25,6 +24,12 @@ import { splitText } from "./util/chunk";
 
 interface State {
   cfg: QQBotConfig | null;
+  /** 本进程当前服务的 QQ bot（自动抢占的结果）；未接入则为 null */
+  account: { name: string; appId: string } | null;
+  /** 本进程的候选 bot（按配置顺序），待命时用它重扫 */
+  candidates: { name: string; appId: string }[];
+  /** 首条回执前缀（接入成功 / 换进程接管时告知用户当前 bot 与工作目录） */
+  claimNote: string | null;
   api: QQApi | null;
   approver: Approver;
   gateway: QQGateway | null;
@@ -60,6 +65,8 @@ interface State {
   progressTimer: ReturnType<typeof setInterval> | null;
   /** 推送失败后暂停自动推送，直到用户主动询问 */
   progressPaused: boolean;
+  /** 用户手动暂停自动推送（本会话有效：跨 run 保留，/progress on 恢复） */
+  progressMuted: boolean;
   /** 最终答案发送失败时缓存，下一条消息时补发 */
   undelivered: { openid: string; text: string } | null;
 }
@@ -90,14 +97,24 @@ export function createInitialState(): State {
     progress: new ProgressTracker(),
     progressTimer: null,
     progressPaused: false,
+    progressMuted: false,
     undelivered: null,
+    account: null,
+    candidates: [],
+    claimNote: null,
   };
 }
 
 export default function (
   pi: ExtensionAPI,
   /** 仅测试用：注入状态，让事件处理器与 handleMessage 共享同一份状态 */
-  options?: { state?: State },
+  options?: {
+    state?: State;
+    /** 仅测试用：不真连 QQ 网关（避免单测打网络），其余流程（抢锁/身份/提示）照常 */
+    disableGateway?: boolean;
+    /** 仅测试用：替换「抢到锁后验凭据」的实现（默认真的去换 access_token） */
+    verifyCredentials?: (account: QQBotAccount) => Promise<AuthManager>;
+  },
 ) {
   const state: State = options?.state ?? createInitialState();
 
@@ -232,66 +249,205 @@ export default function (
     return { block: true, reason: `QQ 用户拒绝了 ${summary}` };
   });
 
-  // ---- 事件：session_start 抢锁 + 启动网关 ----
-  pi.on("session_start", async () => {
-    const cfg = loadConfig();
-    if (!cfg) {
-      log("[setup] 缺少 QQ_BOT_APPID/QQ_BOT_APPSECRET 或配置，插件未启用");
+  // ---- 事件：session_start 选/抢 qqbot + 启动网关 ----
+  pi.on("session_start", async (event) => {
+    const { accounts, errors } = loadAccounts();
+    for (const message of errors) log("[setup] 配置问题:", message);
+    if (accounts.length === 0) {
+      log("[setup] 未配置 QQ bot（或配置不可用），插件未启用");
       return;
     }
-    state.cfg = cfg;
+
+    // 会话重建（/reload、/new…）时优先沿用自己的 bot：上一轮释放前写了 owner 记录
+    const pin = pinnedAccountName();
+    const pool: QQBotAccount[] = pin
+      ? accounts.filter((a) => a.name === pin || a.appId === pin)
+      : accounts;
+    if (pool.length === 0) {
+      log("[setup] PI_QQBOT_ACCOUNT=", pin, "不在配置里（可选:", accounts.map((a) => a.name).join(", "), "），插件未启用");
+      return;
+    }
+    state.candidates = pool.map((a) => ({ name: a.name, appId: a.appId }));
+
+    const ownPid = process.pid;
+    const preferredAppId = state.candidates
+      .map((c) => readOwner(c.appId))
+      .find((owner) => owner?.pid === ownPid)?.appId;
+
     // 新会话：清空 remember 记忆与自动同意开关（自动同意只在当前会话有效）
     state.approver.reset();
-    // 队列上限来自配置；新会话不继承上一个会话遗留的待执行任务
-    state.queue.setLimit(cfg.queue.max);
+    // 手动暂停的自动汇报同样只在本会话有效
+    state.progressMuted = false;
+    state.progressPaused = false;
     state.queue.clear();
-    log("[setup] 配置已加载 sandbox=", cfg.sandbox, "queue.max=", cfg.queue.max);
 
-    const restBase = cfg.sandbox ? REST_BASE_SANDBOX : REST_BASE_PROD;
-    const auth = new AuthManager(cfg.appId, cfg.appSecret);
-    const api = new QQApi({ restBase, getToken: () => auth.getToken() });
-    state.api = api;
+    // 凭据不可用的 bot 在本次会话内不再尝试（配置在 session_start 读取，改完 /reload 才生效）
+    const unusable = new Set<string>();
+    const verifyAccount =
+      options?.verifyCredentials ??
+      (async (account: QQBotAccount) => {
+        const auth = new AuthManager(account.appId, account.config.appSecret);
+        await auth.getToken(); // 抢到锁之后先验凭据，失败就不占着这个槽位
+        return auth;
+      });
+
+    const applyClaim = (claim: Claim, account: QQBotAccount, auth: AuthManager) => {
+      const cfg = account.config;
+      state.cfg = cfg;
+      state.account = { name: account.name, appId: account.appId };
+      state.releaseLock = claim.release;
+      // 只有一个 bot（含 v1 旧配置）→ 继续写旧文件名，升级后日志不断线
+      configureLog(accounts.length === 1 ? null : account.name);
+      state.queue.setLimit(cfg.queue.max);
+      log(
+        "[setup] 配置已加载 bot=",
+        `"${account.name}"`,
+        "appId=",
+        account.appId,
+        "sandbox=",
+        cfg.sandbox,
+        "queue.max=",
+        cfg.queue.max,
+        "reason=",
+        (event as any)?.reason ?? "startup",
+      );
+
+      // 提示：接入成功 / 换进程接管（后者一定要带工作目录）
+      const cwd = process.cwd();
+      if (claim.takeover && claim.previous) {
+        log(
+          "[lock] qqbot",
+          `"${account.name}"`,
+          "换进程接管: pid",
+          claim.previous.pid,
+          "→",
+          process.pid,
+          "· cwd",
+          claim.previous.cwd || "?",
+          "→",
+          cwd,
+        );
+        state.claimNote = `（qqbot「${account.name}」已由新实例接管 · 当前工作目录 ${cwd}）`;
+      } else if (claim.reclaimed) {
+        log("[lock] 重新接入自己的 qqbot（同进程会话重建）");
+      } else {
+        log("[lock] 接入 qqbot", `"${account.name}"`, `(${account.appId})`, "· cwd=", cwd, "· pid=", process.pid);
+        state.claimNote = `（已接入 qqbot「${account.name}」）`;
+      }
 
-    const startGateway = () => {
+      const restBase = cfg.sandbox ? REST_BASE_SANDBOX : REST_BASE_PROD;
+      const api = new QQApi({ restBase, getToken: () => auth.getToken() });
+      state.api = api;
+
+      if (options?.disableGateway) {
+        log("[setup] 测试模式：跳过 QQ 网关");
+        return;
+      }
       const gateway = new QQGateway({
         getGatewayUrl: createGatewayUrlFetcher(restBase, () => auth.getToken()),
         getToken: () => auth.getToken(),
         intents: INTENT_GROUP_AND_C2C,
         connected: () => {},
         disconnected: () => {},
-        message: (msg) => handleMessage(pi, state, api, cfg, msg),
+        message: (msg) => handleMessage(pi, state, api, state.cfg ?? cfg, msg),
       });
       state.gateway = gateway;
       log("[lock] 启动 QQ 网关");
       gateway.start();
     };
 
-    // 单实例锁：只有抢到锁的实例连接 QQ
-    const lockPath = LOCK_PATH(cfg.appId);
-    const release = await tryAcquireLock(lockPath);
-    if (release) {
-      state.releaseLock = release;
-      log("[lock] 抢锁成功，本实例为 QQ bot 宿主");
-      startGateway();
-    } else {
-      log("[lock] 锁被占用，本实例进入待命");
-      state.stopRetry = startLockRetry(lockPath, (r) => {
-        state.releaseLock = r;
-        log("[lock] 抢锁成功，接管 QQ bot");
-        startGateway();
-      });
-    }
+    // 抢一个、验一下凭据、验不过就放锁换下一个
+    const tryClaimOnce = async (): Promise<boolean> => {
+      const remaining = state.candidates.filter((c) => !unusable.has(c.appId));
+      if (remaining.length === 0) return false;
+      const result = await claimAny(remaining, { preferredAppId });
+      if (!result.claim) {
+        const detail = result.skipped
+          .map(
+            (s) =>
+              `${s.name}:${s.reason === "online" ? "在线" : s.reason === "reserved" ? `被 pid ${s.owner?.pid} 重载中` : "刚被抢走"}`,
+          )
+          .join(", ");
+        log("[lock] 本轮无可接入的 qqbot（", detail, "）");
+        return false;
+      }
+      const claim = result.claim;
+      const account = pool.find((a) => a.appId === claim.appId);
+      if (!account) {
+        await claim.release().catch(() => {});
+        unusable.add(claim.appId);
+        return tryClaimOnce();
+      }
+      try {
+        const auth = await verifyAccount(account);
+        applyClaim(claim, account, auth);
+        return true;
+      } catch (e) {
+        await claim.release().catch(() => {});
+        unusable.add(account.appId);
+        log(
+          "[lock] qqbot",
+          `"${account.name}"`,
+          "凭据不可用：",
+          String(e).slice(0, 160),
+          "→ 已放锁并跳过该 bot（改好配置后 /reload 再试）",
+        );
+        return tryClaimOnce();
+      }
+    };
+
+    // 待命：还有「可能变可用」的候选就 5s 重扫——否则别人退出后没人接管
+    const enterStandby = () => {
+      if (!state.candidates.some((c) => !unusable.has(c.appId))) {
+        log("[lock] 没有可接入的 qqbot（其余在线或凭据不可用），本进程不接入 QQ");
+        return;
+      }
+      log("[lock] 本进程待命，5s 后重扫");
+      state.stopRetry = startClaimRetry(
+        () => state.candidates.filter((c) => !unusable.has(c.appId)),
+        (claim) => {
+          state.stopRetry = null;
+          void (async () => {
+            const account = pool.find((a) => a.appId === claim.appId);
+            if (!account || state.gateway) {
+              await claim.release().catch(() => {});
+              enterStandby();
+              return;
+            }
+            try {
+              const auth = await verifyAccount(account);
+              applyClaim(claim, account, auth);
+            } catch (e) {
+              await claim.release().catch(() => {});
+              unusable.add(account.appId);
+              log("[lock] qqbot", `"${account.name}"`, "凭据不可用：", String(e).slice(0, 160), "→ 放锁继续待命");
+              enterStandby();
+            }
+          })();
+        },
+        { preferredAppId },
+      );
+    };
+
+    if (await tryClaimOnce()) return;
+    enterStandby();
   });
 
   // ---- 事件：session_shutdown 清理 ----
-  pi.on("session_shutdown", async () => {
-    log("[shutdown] 清理资源");
+  pi.on("session_shutdown", async (event) => {
+    const reason = String((event as any)?.reason ?? "quit");
+    log("[shutdown] 清理资源 reason=", reason);
     clearCancelTimer(state);
     stopProgressTimer(state);
     const dropped = state.queue.clear();
     if (dropped.length > 0) log("[shutdown] 丢弃队列任务", dropped.length, "条");
     if (state.stopRetry) state.stopRetry();
     state.gateway?.stop();
+    // reload/new/fork/resume 只是「本进程换会话」，马上会重新接入：先贴预约，别让别人抢走
+    if (state.account && state.releaseLock && reason !== "quit") {
+      reserveBeforeRelease(state.account, reason);
+      log("[lock] qqbot", `"${state.account.name}"`, "临时释放（reason=", reason, "），已留预约窗口");
+    }
     if (state.releaseLock) {
       try {
         await state.releaseLock();
@@ -302,6 +458,7 @@ export default function (
     state.releaseLock = null;
     state.gateway = null;
     state.api = null;
+    state.account = null;
   });
 
   // ---- /qq：QQ 侧命令的桥接入口 ----
@@ -719,13 +876,15 @@ export async function handleMessage(
         msg.openid,
         [
           "pi-qqbot 指令:",
-          "/status — 查看状态（忙闲 / 队列 / 自动同意 / 待审批）",
+          "/progress — 查看进度；/progress off 暂停自动汇报、/progress on 恢复（本会话有效）",
+          "/status — 查看状态（当前 qqbot / 忙闲 / 队列 / 自动同意 / 待审批 / 自动汇报）",
           "/queue — 查看队列；/queue clear 清空；/queue drop <编号> 删一条",
           "/reset — 清空回复缓冲、审批记忆与自动同意（不换会话；换会话发 /new）",
           "/cancel（或「取消」「停止」）— 中断正在运行的任务并清空队列",
           "/help — 帮助",
           "pi 的命令优先：/reload /new /compact /session /name /model /thinking，以及扩展命令、模板与 /skill:xxx。",
           "忙碌时发来的普通消息（含模板/skill 命令）会排队，当前任务结束后自动执行。",
+          "多 bot：配置了多个 qqbot 时，多个 pi 进程会按列表顺序各自接入一个，抢不到的待命重扫。",
           "其余文本交给 pi 当作对话处理。",
         ].join("\n"),
       );
@@ -733,28 +892,71 @@ export async function handleMessage(
     }
     if (cmd?.name === "status") {
       const lines = [
+        `bot: ${state.account ? `${state.account.name} (…${state.account.appId.slice(-4)})` : "未接入"} · cwd: ${process.cwd()}`,
         `状态: ${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);
-        // 用户主动问询：恢复自动推送
-        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 +976,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;
       }
@@ -799,6 +1001,12 @@ async function replyTo(
   text: string,
   format: "text" | "markdown" = "text",
 ): Promise<boolean> {
+  // 本进程刚接入 / 刚接管这个 qqbot：第一条回执带上身份与工作目录
+  if (state.claimNote) {
+    const note = state.claimNote;
+    state.claimNote = null;
+    text = `${note}\n${text}`;
+  }
   const ref = state.passiveRefs.get(openid);
   let delivered = true;
   for (const chunk of splitText(text)) {
@@ -845,9 +1053,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 +1069,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 <编号>] */