@zxh126/pi-qqbot 1.1.0 → 1.2.0

package/README.md

@@ -11,12 +11,13 @@ Bridge the **[Pi](https://pi.dev) coding agent** into QQ private (C2C) chats: se
 | Feature | Description |
 |---|---|
 | **Chat-driven agent** | QQ private messages are fed into the current pi session; the assistant's answer is sent back to QQ (long replies are split automatically). |
+| **Message queue** | While a task is running, further QQ messages are **queued** instead of rejected; each one starts automatically as soon as the current run settles. `/cancel` is the exception — it acts immediately and clears the queue. |
 | **Remote approval** | Before pi runs `bash` / `powershell` / `write` / `edit` — or any tool annotated `destructiveHint` — the bot asks in QQ first. |
 | **Session-scoped "always allow"** | Reply 「以后都同意」 and every approval request in the **current session** is auto-approved, including the one already waiting. |
 | **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 and the half-written answer are all cleaned up. |
+| **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`, `/reset`, `/cancel`, `/help`. |
+| **Built-in commands** | `/status`, `/queue`, `/reset`, `/cancel`, `/help`. |
 
 ## Install
 
@@ -42,6 +43,10 @@ Then create `~/.pi/agent/pi-qqbot.json`:
   "approve": {
     "tools": ["bash", "powershell", "write", "edit"],
     "remember": true
+  },
+  "queue": {
+    "max": 20,
+    "ack": true
   }
 }
 ```
@@ -56,6 +61,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` |
+| `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) |
 
 Credentials can also come from the `QQ_BOT_APPID` / `QQ_BOT_APPSECRET` environment variables.
 
@@ -66,8 +73,9 @@ 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, auto-approve state and pending approval count |
-| `/cancel` | **Interrupt the task that is running right now** (aliases: `/stop`, `/abort`, 「取消」, 「停止」, 「中止」, 「终止」, 「算了」) |
+| `/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 |
+| `/cancel` | **Interrupt the task that is running right now** and empty the queue (aliases: `/stop`, `/abort`, 「取消」, 「停止」, 「中止」, 「终止」, 「算了」) |
 | `/help` | Show help |
 
 ### Slash commands from QQ
@@ -104,6 +112,9 @@ Guards:
 
 - `/reload`, `/new`, `/compact`, `/quit`, `/tree`, `/fork`, `/clone` and `/resume` refuse to run while a task
   is in progress — send `/cancel` first.
+- Prompt templates and `/skill:name` start an agent run, so while a task is in progress they are
+  **queued** like ordinary messages (see [Queueing while busy](#queueing-while-busy)). Extension commands
+  that manage their own LLM interaction still run immediately.
 - Selection commands (`/tree`, `/fork`, `/resume`) answer with a numbered list of at most 10 entries, scoped to
   the user who asked and valid for 10 minutes. The next bare number from that user executes the choice; anything
   else (or 「取消」) abandons it. A number without a pending list is ordinary chat.
@@ -115,6 +126,39 @@ Guards:
   hard-coded here because pi does not export its built-in list; any unknown `/word` falls back to
   plain text.
 
+### Queueing while busy
+
+pi's session runs one agent run at a time, so the bot serializes QQ input itself:
+
+```text
+you: 帮我把测试跑一遍
+bot: 收到，正在处理
+you: 顺便看看 README 有没有错别字
+bot: 已排队 #1，当前任务结束后自动执行。发 /queue 查看队列，/cancel 可中止当前任务并清空队列。
+you: /queue
+bot: 当前任务：处理中（发 /cancel 可中断）
+     队列：1 条（上限 20）
+       1. #1 · 12s 前 · 顺便看看 README 有没有错别字
+     发 /queue clear 清空，/queue drop <编号> 删除一条。
+bot: （第一轮结束后）开始执行队列 #1
+```
+
+Semantics:
+
+- Every message that would start a run — plain chat, prompt templates, `/skill:name` — is queued while a
+  task is running, in arrival order (FIFO). Replies go to the QQ user who sent that message.
+- The next entry starts when pi has **settled** (`agent_settled`, no automatic continuation left), so a
+  retry, a compaction retry or a follow-up turn is never cut in half.
+- The queue holds at most `queue.max` entries; beyond that the message is refused with a notice. `queue.max: 0`
+  restores the old "上一条消息还在处理中" behaviour.
+- If handing a message to pi fails (pi was still finishing the previous run), it is put back at the head of
+  the queue and retried — messages are not lost. A run that already started is never retried, so a failure
+  inside a run cannot execute the same message twice.
+- Control commands are **not** queued: approvals, `/status`, `/queue`, `/reset`, `/help`, the pi built-ins
+  and `/cancel` all act immediately.
+- `/cancel` empties the queue as well, because "cancel" means "stop doing all of this". Use `/queue drop <id>`
+  to remove a single entry instead.
+
 ### Cancelling a run
 
 Long tasks started from QQ (installs, builds, a runaway agent loop) can be interrupted without going
@@ -122,14 +166,16 @@ back to the machine:
 
 ```
 you: /cancel
-bot: 已取消当前任务，并终止了 1 个待审批请求。可以发送新消息继续。
+bot: 已取消当前任务，并终止了 1 个待审批请求，队列中的 2 条已清空。可以发送新消息继续。
 ```
 
-What it does, in order: terminate every pending approval request, call `ctx.abort()` on the current
-run (the same path as pressing Escape in the TUI), drop the partially streamed answer so it is not
-sent to QQ, clear the busy flag so the next message is accepted immediately, and reply with a
-confirmation. Replies that only *look* like cancelling — 「取消自动同意」, 「恢复审批」 — still go to the
-approval handler, so the auto-approve switch keeps working as before.
+What it does, in order: terminate every pending approval request, empty the queue, call `ctx.abort()` on
+the current run (the same path as pressing Escape in the TUI), drop the partially streamed answer so it is
+not sent to QQ, keep the busy flag until pi reports `agent_settled` (so messages arriving during the abort
+are queued instead of racing it), and reply with a confirmation. If `agent_settled` never arrives, an
+8-second watchdog releases the busy flag and continues the queue. Replies that only *look* like cancelling
+— 「取消自动同意」, 「恢复审批」 — still go to the approval handler, so the auto-approve switch keeps working
+as before.
 
 Anything else is forwarded to pi as a user message.
 

package/config.ts

@@ -1,6 +1,14 @@
 import fs from "node:fs";
 import { CONFIG_PATH } from "./constants";
 import { DEFAULT_COMMANDS, type CommandConfig } from "./slash";
+import { DEFAULT_QUEUE_MAX } from "./queue";
+
+export interface QueueConfig {
+  /** 忙碌时最多排队多少条消息；0 = 关闭排队（忙碌时直接拒绝） */
+  max: number;
+  /** 排队任务开始执行时是否给 QQ 回执（入队回执不受此开关控制） */
+  ack: boolean;
+}
 
 export interface ApproveConfig {
   /** 需要 QQ 审批的工具名（如 bash/powershell/write/edit） */
@@ -20,6 +28,8 @@ export interface QQBotConfig {
   approve: ApproveConfig;
   /** QQ 侧斜杠命令的路由开关（/reload、/new… 以及扩展命令透传） */
   commands: CommandConfig;
+  /** 忙碌时的消息队列 */
+  queue: QueueConfig;
 }
 
 export function loadConfig(): QQBotConfig | null {
@@ -50,5 +60,9 @@ export function loadConfig(): QQBotConfig | null {
       allowQuit: file.commands?.allowQuit ?? DEFAULT_COMMANDS.allowQuit,
       allowSession: file.commands?.allowSession ?? DEFAULT_COMMANDS.allowSession,
     },
+    queue: {
+      max: file.queue?.max ?? DEFAULT_QUEUE_MAX,
+      ack: file.queue?.ack ?? true,
+    },
   };
 }

package/constants.ts

@@ -10,6 +10,10 @@ export const MAX_REPLIES_PER_MSG_ID = 4;
 export const APPROVAL_TIMEOUT_MS = 10 * 60 * 1000;
 export const STREAM_FLUSH_INTERVAL_MS = 1200;
 export const GATEWAY_PATH = "/gateway";
+/** 队列任务派发给 pi 失败（通常是上一轮还没收尾）时的重试间隔 */
+export const DISPATCH_RETRY_MS = 3000;
+/** /cancel 之后等 agent_settled 的宽限时间，超时就强制释放 busy */
+export const CANCEL_SETTLE_GRACE_MS = 8000;
 
 const PI_DIR = path.join(os.homedir(), ".pi", "agent");
 export const CONFIG_PATH = () => path.join(PI_DIR, "pi-qqbot.json");

package/docs/README.zh-CN.md

@@ -11,12 +11,13 @@
 | 功能 | 说明 |
 |---|---|
 | **对话驱动 agent** | QQ 单聊消息送入当前 pi 会话，AI 的回复发回 QQ（长文本自动分片）。 |
+| **消息队列** | 正在处理任务时，后续 QQ 消息会被**排队**而不是被拒；当前任务结束（settled）后按到达顺序自动逐条执行。`/cancel` 是例外——立即生效并清空队列。 |
 | **远程审批** | pi 执行 `bash` / `powershell` / `write` / `edit`，或任何带 `destructiveHint` 注解的工具前，先在 QQ 里申请审批。 |
 | **会话级「以后都同意」** | 回复「以后都同意」，**当前会话**内所有审批请求直接放行，连已经挂起的那条也一起放行。 |
 | **单实例锁** | 只有一个 pi 进程作为宿主连接 QQ，其余待命，宿主退出后自动接管。 |
-| **中断正在运行的任务** | 发 `/cancel`（或「取消」/「停止」），当前任务立刻中断 —— QQ 回复、待审批工具调用、写到一半的回答一并清理。 |
+| **中断正在运行的任务** | 发 `/cancel`（或「取消」/「停止」），当前任务立刻中断 —— QQ 回复、待审批工具调用、写到一半的回答、排队中的消息一并清理。 |
 | **斜杠命令路由** | 以 `/` 开头的 QQ 消息会先被路由：pi 的扩展命令、prompt 模板、`/skill:name` 交给 pi 派发；一部分 pi 内置命令（`/reload`、`/new`、`/compact`、`/session`、`/name`、`/model`、`/thinking`、`/quit`）由本扩展接管；只能在主机执行的内置命令直接回执，不会送给模型。 |
-| **内置指令** | `/status`、`/reset`、`/cancel`、`/help`。 |
+| **内置指令** | `/status`、`/queue`、`/reset`、`/cancel`、`/help`。 |
 
 ## 安装
 
@@ -42,6 +43,10 @@ pi install ./pi-qqbot
   "approve": {
     "tools": ["bash", "powershell", "write", "edit"],
     "remember": true
+  },
+  "queue": {
+    "max": 20,
+    "ack": true
   }
 }
 ```
@@ -56,6 +61,8 @@ pi install ./pi-qqbot
 | `approve.tools` | `["bash","powershell","write","edit"]` | 需要审批的工具名；带 `destructiveHint` 注解的工具同样会拦截 |
 | `approve.remember` | `true` | 会话内按工具记住决策（同类工具不再重复询问） |
 | `commands` | 见下 | 斜杠命令路由开关：`passthrough`、`allowReload`、`allowQuit`、`allowSession` |
+| `queue.max` | `20` | 任务运行期间最多排队多少条；`0` = 关闭排队（忙碌时直接拒绍，回到旧行为） |
+| `queue.ack` | `true` | 排队消息开始执行时是否回执 QQ（入队回执总是会发） |
 
 也可用环境变量 `QQ_BOT_APPID` / `QQ_BOT_APPSECRET` 代替文件里的凭据。
 
@@ -66,8 +73,9 @@ pi install ./pi-qqbot
 | 指令 | 说明 |
 |---|---|
 | `/reset` | 重置：清空回复缓冲、审批记忆与自动同意开关（**不换会话**，换会话发 `/new`） |
-| `/status` | 查看忙闲状态、自动同意状态、待审批数量 |
-| `/cancel` | **中断当前正在运行的任务**（别名：`/stop`、`/abort`、「取消」、「停止」、「中止」、「终止」、「算了」） |
+| `/status` | 查看忙闲状态、队列长度、自动同意状态、待审批数量 |
+| `/queue` | 查看队列（别名 `/q`）；`/queue clear` 清空，`/queue drop <编号>` 删一条 |
+| `/cancel` | **中断当前正在运行的任务**并清空队列（别名：`/stop`、`/abort`、「取消」、「停止」、「中止」、「终止」、「算了」） |
 | `/help` | 帮助 |
 
 ### QQ 里的斜杠命令
@@ -103,6 +111,8 @@ pi install ./pi-qqbot
 
 - 有任务在跑时，`/reload`、`/new`、`/compact`、`/quit`、`/tree`、`/fork`、`/clone`、`/resume` 会拒绝执行
   —— 先发 `/cancel`。
+- prompt 模板与 `/skill:name` 会开启一轮 agent run，因此忙碌时会像普通消息一样**排队**
+  （见 [忙碌时的队列](#忙碌时的队列)）；自己管理 LLM 交互的扩展命令仍然立即执行。
 - 选择型命令（`/tree`、`/fork`、`/resume`）会回一个最多 10 项的编号列表，只对该用户有效、10 分钟内有效；
   该用户下一条「纯数字」消息即执行选择，其它内容（或「取消」）则放弃。没有待选列表时，数字就是普通对话。
 - `/reload` 默认关闭：它会重启 bot，如果新代码加载失败，bot 会一直哑着，只能在主机上救。
@@ -112,17 +122,49 @@ pi install ./pi-qqbot
   改派成 `/qq reload`。内置命令名是硬编码的（pi 没有把内置清单导出给扩展）；任何不认识的
   `/xxx` 都会退回当普通文字。
 
+### 忙碌时的队列
+
+pi 的会话一次只跑一轮 agent run，所以串行调度由 bot 自己做：
+
+```text
+你：帮我把测试跑一遍
+机器人：收到，正在处理
+你：顺便看看 README 有没有错别字
+机器人：已排队 #1，当前任务结束后自动执行。发 /queue 查看队列，/cancel 可中止当前任务并清空队列。
+你：/queue
+机器人：当前任务：处理中（发 /cancel 可中断）
+       队列：1 条（上限 20）
+         1. #1 · 12s 前 · 顺便看看 README 有没有错别字
+       发 /queue clear 清空，/queue drop <编号> 删除一条。
+机器人：（第一轮结束后）开始执行队列 #1
+```
+
+语义：
+
+- 会开启一轮 run 的消息（普通对话、prompt 模板、`/skill:name`）在忙碌时按到达顺序（FIFO）排队；
+  回复发给该条消息的发送者。
+- 下一条在 pi **settled**（不再有任何自动续跑）之后才启动，所以重试、压缩重试、follow-up 轮次
+  不会被从中间撗断。
+- 队列上限为 `queue.max`，超出时拒绍入队并回执；`queue.max: 0` 回到旧的「上一条消息还在处理中」。
+- 交给 pi 失败时（通常上一轮还没收尾）任务会放回队首重试，不丢消息；已经真的启动过 run 的报错
+  不会重试，避免同一条消息执行两次。
+- 控制类指令**不排队**：审批回复、`/status`、`/queue`、`/reset`、`/help`、pi 内置命令与 `/cancel`
+  都立即生效。
+- `/cancel` 会连队列一起清空（“取消”就是“都别做了”）；只想删一条请用 `/queue drop <编号>`。
+
 ### 取消正在运行的任务
 
 从 QQ 发起的耗时任务（装依赖、编译、agent 跑飞了）不必回到机器上处理：
 
 ```
 你：/cancel
-机器人：已取消当前任务，并终止了 1 个待审批请求。可以发送新消息继续。
+机器人：已取消当前任务，并终止了 1 个待审批请求，队列中的 2 条已清空。可以发送新消息继续。
 ```
 
-执行顺序：先终止所有待审批请求，再对当前 run 调用 `ctx.abort()`（和 TUI 里按 Escape 同一条路径），
-丢弃已经流式产生的半截回答（不会发到 QQ），清掉忙碌标记使下一条消息立刻可用，最后回执确认。
+执行顺序：先终止所有待审批请求、清空队列，再对当前 run 调用 `ctx.abort()`（和 TUI 里按 Escape 同一条路径），
+丢弃已经流式产生的半截回答（不会发到 QQ），**忙碌标记保留到 pi 报 `agent_settled`**
+（所以 abort 期间新来的消息会排队，而不是和收尾中的 run 撞车），最后回执确认。如果 `agent_settled`
+一直不来，8 秒看门狗会强制释放忙碌标记并继续队列。
 像「取消自动同意」「恢复审批」这类**只是长得像**取消的回复仍然走审批分支，自动同意开关行为不变。
 
 其余文本都作为用户消息交给 pi。

package/index.ts

@@ -7,6 +7,8 @@ import {
   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";
@@ -15,6 +17,7 @@ import { QQApi } from "./qq/api";
 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 { ReplyBuffer } from "./stream-buffer";
 import { splitText } from "./util/chunk";
 
@@ -41,10 +44,19 @@ interface State {
   bridgeReply: ((text: string) => void) | null;
   /** 本轮已被用户取消：settle 时丢弃半截回复 */
   cancelled: boolean;
+  /** 忙碌时收到的任务：当前任务 settle 后逐条执行 */
+  queue: MessageQueue;
+  /** 正在出队派发（防 settled / 重试竞态下重复派发） */
+  dispatching: boolean;
+  /** 当前派发的任务已经真的启动了 run（agent_start 过）：此时报错不重试，避免重复执行 */
+  runStarted: boolean;
+  /** /cancel 之后等 agent_settled 的兜底定时器 */
+  cancelTimer: ReturnType<typeof setTimeout> | null;
 }
 
-export default function (pi: ExtensionAPI) {
-  const state: State = {
+/** 扩展运行所需的状态（导出只为测试用） */
+export function createInitialState(): State {
+  return {
     cfg: null,
     api: null,
     approver: new Approver(APPROVAL_TIMEOUT_MS),
@@ -61,12 +73,26 @@ export default function (pi: ExtensionAPI) {
     pickerOwner: null,
     bridgeReply: null,
     cancelled: false,
+    queue: new MessageQueue(),
+    dispatching: false,
+    runStarted: false,
+    cancelTimer: null,
   };
+}
+
+export default function (
+  pi: ExtensionAPI,
+  /** 仅测试用：注入状态，让事件处理器与 handleMessage 共享同一份状态 */
+  options?: { state?: State },
+) {
+  const state: State = options?.state ?? createInitialState();
 
   // ---- 事件：run 开始，记住 ctx（取消指令要调用 ctx.abort()）----
   pi.on("agent_start", (_event, ctx) => {
     state.ctx = ctx;
     state.cancelled = false;
+    state.runStarted = true;
+    clearCancelTimer(state);
   });
 
   // ---- 事件：累积 assistant 文本 ----
@@ -77,8 +103,9 @@ export default function (pi: ExtensionAPI) {
     }
   });
 
-  // ---- 事件：run 结束，发回复 ----
+  // ---- 事件：run 结束，发回复，然后接着跑队列里的下一条 ----
   pi.on("agent_settled", async () => {
+    clearCancelTimer(state);
     const cancelled = state.cancelled;
     const text = state.replyBuffer.take();
     const openid = state.currentOpenid;
@@ -86,15 +113,17 @@ export default function (pi: ExtensionAPI) {
     state.busy = false;
     state.ctx = null;
     state.cancelled = false;
+    state.runStarted = false;
     if (cancelled) {
       log("[reply] 本轮已被取消，丢弃半截回复（长度", text.length, "）");
-      return;
-    }
-    if (!text || !openid || !state.api) return;
-    log("[reply] agent_settled，回复 openid=", openid, "text=", text.slice(0, 80));
-    for (const chunk of splitText(text)) {
-      await state.api.sendC2C(openid, chunk).catch((e) => log("[reply] 发送失败:", String(e)));
+    } else if (text && openid && state.api) {
+      log("[reply] agent_settled，回复 openid=", openid, "text=", text.slice(0, 80));
+      for (const chunk of splitText(text)) {
+        await state.api.sendC2C(openid, chunk).catch((e) => log("[reply] 发送失败:", String(e)));
+      }
     }
+    // 本轮结束：取队列里的下一条继续执行（不 await，避免卡住 settled 的派发阶段）
+    drainQueue(pi, state);
   });
 
   // ---- 事件：tool_call 审批 ----
@@ -163,7 +192,10 @@ export default function (pi: ExtensionAPI) {
     state.cfg = cfg;
     // 新会话：清空 remember 记忆与自动同意开关（自动同意只在当前会话有效）
     state.approver.reset();
-    log("[setup] 配置已加载 sandbox=", cfg.sandbox);
+    // 队列上限来自配置；新会话不继承上一个会话遗留的待执行任务
+    state.queue.setLimit(cfg.queue.max);
+    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);
@@ -204,6 +236,9 @@ export default function (pi: ExtensionAPI) {
   // ---- 事件：session_shutdown 清理 ----
   pi.on("session_shutdown", async () => {
     log("[shutdown] 清理资源");
+    clearCancelTimer(state);
+    const dropped = state.queue.clear();
+    if (dropped.length > 0) log("[shutdown] 丢弃队列任务", dropped.length, "条");
     if (state.stopRetry) state.stopRetry();
     state.gateway?.stop();
     if (state.releaseLock) {
@@ -248,49 +283,220 @@ function isCancelIntent(text: string): boolean {
   return RE_CANCEL.test(text.trim());
 }
 
+/** 派发失败时最多重试几次（通常是 pi 上一轮还没收尾） */
+const MAX_DISPATCH_ATTEMPTS = 3;
+
+function clearCancelTimer(state: State) {
+  if (state.cancelTimer) {
+    clearTimeout(state.cancelTimer);
+    state.cancelTimer = null;
+  }
+}
+
+/**
+ * 对外看是“忙”：有任务在跑、正在派发，或者队列里还有任务等着（比如派发失败后的重试窗口）。
+ * 这三种情况新消息都应该进队列，而不是插队直接开新一轮。
+ */
+function isBusy(state: State): boolean {
+  return state.busy || state.dispatching || state.queue.size > 0;
+}
+
+/**
+ * /cancel 之后 abort() 是异步的：正常路径靠 agent_settled 释放 busy 并继续队列；
+ * 万一 abort 没能触发 settled（比如那一轮正好已经结束），宽限期后强制解锁。
+ */
+function armCancelWatchdog(pi: ExtensionAPI, state: State) {
+  clearCancelTimer(state);
+  const timer = setTimeout(() => {
+    state.cancelTimer = null;
+    if (!state.cancelled) return;
+    log("[cancel] abort 后", CANCEL_SETTLE_GRACE_MS, "ms 内没有 agent_settled，强制释放 busy");
+    state.cancelled = false;
+    state.busy = false;
+    state.ctx = null;
+    state.currentOpenid = null;
+    state.replyBuffer.reset();
+    drainQueue(pi, state);
+  }, CANCEL_SETTLE_GRACE_MS);
+  (timer as any).unref?.();
+  state.cancelTimer = timer;
+}
+
+/**
+ * 把一条任务交给 pi，并把它标记为「当前任务」。
+ * 不 await sendUserMessage：它返回的 promise 要等整轮跑完，await 会卡住调用方
+ * （agent_settled 里派发时更是不允许）。错误交给 onDispatchError 重试/回执。
+ */
+function startJob(pi: ExtensionAPI, state: State, job: QueuedJob) {
+  state.currentOpenid = job.openid;
+  state.lastOpenid = job.openid;
+  state.pickerOwner = job.openid;
+  state.bridgeReply = (text: string) => {
+    void replyTo(state.api!, state, job.openid, text);
+  };
+  state.busy = true;
+  state.cancelled = false;
+  state.runStarted = false;
+  state.replyBuffer.reset();
+  clearCancelTimer(state);
+  log(
+    "[msg] 送入 pi:",
+    job.id > 0 ? `队列 #${job.id}` : "直接",
+    "openid=",
+    job.openid,
+    "text=",
+    job.text.slice(0, 60),
+  );
+  try {
+    void Promise.resolve(
+      pi.sendUserMessage(job.text, { expandPromptTemplates: true, deliverAs: "followUp" }),
+    ).catch((error) => onDispatchError(pi, state, job, error));
+  } catch (error) {
+    onDispatchError(pi, state, job, error);
+  }
+}
+
+/** 派发失败：先重试（放回队首），多次失败就把错误回给发送者并继续队列 */
+function onDispatchError(pi: ExtensionAPI, state: State, job: QueuedJob, error: unknown) {
+  const message = String((error as any)?.message ?? error).slice(0, 200);
+  log("[msg] 派发失败:", message);
+  if (state.runStarted) {
+    // run 已经启动了：这次报错属于这一轮自己的问题，收尾交给 agent_settled，不能重试
+    log("[msg] 本轮已启动过 agent，不重试，等 agent_settled 收尾");
+    return;
+  }
+  state.busy = false;
+  state.currentOpenid = null;
+  job.attempts += 1;
+  if (job.attempts < MAX_DISPATCH_ATTEMPTS) {
+    state.queue.unshift(job);
+    log("[msg]", DISPATCH_RETRY_MS, "ms 后重试（第", job.attempts, "次）");
+    const timer = setTimeout(() => drainQueue(pi, state), DISPATCH_RETRY_MS);
+    (timer as any).unref?.();
+    return;
+  }
+  const api = state.api;
+  if (api) void replyTo(api, state, job.openid, `这条消息执行失败：${message}`);
+  drainQueue(pi, state);
+}
+
+/** 当前任务结束后，取队列里的下一条开始执行（空闲时才会真的派发） */
+function drainQueue(pi: ExtensionAPI, state: State) {
+  if (state.busy || state.dispatching) return;
+  const job = state.queue.shift();
+  if (!job) return;
+  state.dispatching = true;
+  try {
+    log("[queue] 出队 #", job.id, "剩余", state.queue.size, "条", "text=", job.text.slice(0, 60));
+    const api = state.api;
+    if (api && state.cfg?.queue.ack !== false) {
+      const rest = state.queue.size > 0 ? `（后面还有 ${state.queue.size} 条）` : "";
+      void replyTo(api, state, job.openid, `开始执行队列 #${job.id}${rest}`);
+    }
+    startJob(pi, state, job);
+  } finally {
+    state.dispatching = false;
+  }
+}
+
+/** 入队（忙碌时的统一入口）：回执排队位置 */
+async function enqueueJob(
+  api: QQApi,
+  state: State,
+  openid: string,
+  text: string,
+): Promise<boolean> {
+  const result = state.queue.push(openid, text);
+  if (!result.ok) {
+    log("[queue] 队列已满（上限", state.queue.max, "），拒绝入队");
+    if (state.queue.max === 0) {
+      await replyTo(api, state, openid, "上一条消息还在处理中，请稍候…（队列已关闭：queue.max=0）");
+      return false;
+    }
+    await replyTo(
+      api,
+      state,
+      openid,
+      `队列已满（上限 ${state.queue.max} 条），这条没排上。发 /queue 查看队列，或 /cancel 清空后重发。`,
+    );
+    return false;
+  }
+  log("[queue] 入队 #", result.job.id, "size=", state.queue.size, "ahead=", result.ahead);
+  await replyTo(
+    api,
+    state,
+    openid,
+    `已排队 #${result.job.id}${result.ahead > 0 ? `（前面还有 ${result.ahead} 条）` : ""}，当前任务结束后自动执行。发 /queue 查看队列，/cancel 可中止当前任务并清空队列。`,
+  );
+  return true;
+}
+
+function formatQueue(state: State): string {
+  const lines = [`当前任务：${state.busy ? "处理中（发 /cancel 可中断）" : "空闲"}`];
+  const jobs = state.queue.list();
+  if (jobs.length === 0) {
+    lines.push("队列：空");
+    return lines.join("\n");
+  }
+  lines.push(`队列：${jobs.length} 条（上限 ${state.queue.max}）`);
+  jobs.slice(0, 10).forEach((job, index) => {
+    lines.push(`  ${index + 1}. #${job.id} · ${agoLabel(job.enqueuedAt)} · ${previewText(job.text)}`);
+  });
+  if (jobs.length > 10) lines.push(`  … 还有 ${jobs.length - 10} 条`);
+  lines.push("发 /queue clear 清空，/queue drop <编号> 删除一条。");
+  return lines.join("\n");
+}
+
 /**
- * 用户发来取消指令：终止待审批、abort 当前 run、丢弃半截回复，然后回执。
+ * 用户发来取消指令：终止待审批、清空队列、abort 当前 run、丢弃半截回复，然后回执。
+ * 取消本身永不入队（“取消除外”），立即生效。
  * （「取消自动同意」/「关闭自动同意」不属于取消指令，仍走审批分支。）
  */
 async function handleCancel(
+  pi: ExtensionAPI,
   state: State,
   api: QQApi,
   openid: string,
 ): Promise<void> {
   const terminated = state.approver.terminateAll();
+  const dropped = state.queue.clear();
   const running = state.busy || Boolean(state.ctx?.signal);
-
   if (!running) {
+    const parts: string[] = [];
+    if (terminated > 0) parts.push(`已终止 ${terminated} 个待审批请求`);
+    if (dropped.length > 0) parts.push(`已清空队列（${dropped.length} 条）`);
     await replyTo(
       api,
       state,
       openid,
-      terminated > 0
-        ? `已终止 ${terminated} 个待审批请求，当前没有正在运行的任务。`
+      parts.length > 0
+        ? `${parts.join("，")}，当前没有正在运行的任务。`
         : "当前没有正在运行的任务。",
     );
     return;
   }
 
   state.cancelled = true;
-  state.busy = false;
   state.replyBuffer.reset();
   state.currentOpenid = null; // 被中止的 run 不再往 QQ 发半截回复
   const ctx = state.ctx;
   state.ctx = null;
   try {
     ctx?.abort();
-    log("[cancel] 已请求中止当前 run，终止待审批", terminated, "个");
+    log("[cancel] 已请求中止当前 run，终止待审批", terminated, "个，清空队列", dropped.length, "条");
   } catch (e) {
     log("[cancel] abort 失败:", String(e));
   }
+  // busy 保持 true 直到 agent_settled：期间新消息会排队，不会和正在收尾的 run 撞车
+  armCancelWatchdog(pi, state);
+  const notice: string[] = [];
+  if (terminated > 0) notice.push(`并终止了 ${terminated} 个待审批请求`);
+  if (dropped.length > 0) notice.push(`队列中的 ${dropped.length} 条已清空`);
   await replyTo(
     api,
     state,
     openid,
-    terminated > 0
-      ? `已取消当前任务，并终止了 ${terminated} 个待审批请求。可以发送新消息继续。`
-      : "已取消当前任务。可以发送新消息继续。",
+    `已取消当前任务${notice.length > 0 ? `，${notice.join("，")}` : ""}。可以发送新消息继续。`,
   );
 }
 
@@ -341,9 +547,9 @@ export async function handleMessage(
       }
     }
 
-    // 取消指令优先于审批解析：「取消」不该被当成审批动作
+    // 取消指令优先于审批解析：「取消」不该被当成审批动作；取消也永不入队
     if (isCancelIntent(msg.content)) {
-      await handleCancel(state, api, msg.openid);
+      await handleCancel(pi, state, api, msg.openid);
       return;
     }
 
@@ -355,10 +561,30 @@ export async function handleMessage(
     };
     const routed = await routeSlash(
       {
-        listPiCommands: () => (pi.getCommands?.() ?? []) as { name: string }[],
-        dispatch: (text: string) => pi.sendUserMessage(text, { expandPromptTemplates: true }),
+        listPiCommands: () => (pi.getCommands?.() ?? []) as { name: string; source?: string }[],
+        dispatch: (text, options) => {
+          // 提示模板 / /skill: 会开启一轮 agent run：和普通对话一样串行到队列
+          if (options?.runsTurn) {
+            if (!isBusy(state)) {
+              startJob(pi, state, state.queue.mint(msg.openid, text));
+              return "dispatched";
+            }
+            const queued = state.queue.push(msg.openid, text);
+            if (!queued.ok) {
+              log("[queue] 队列已满，命令未排队:", text.slice(0, 60));
+              return "rejected";
+            }
+            log("[queue] 命令入队 #", queued.job.id, text.slice(0, 60));
+            return "queued";
+          }
+          // 扩展命令 / 桥接命令（/qq …）不开 run，pi 允许流式期间执行，直接派发
+          void Promise.resolve(pi.sendUserMessage(text, { expandPromptTemplates: true })).catch(
+            (e) => log("[cmd] 派发失败:", String(e)),
+          );
+          return "dispatched";
+        },
         reply: (text: string) => replyTo(api, state, msg.openid, text),
-        busy: state.busy,
+        busy: isBusy(state),
         cfg: cfg.commands,
         log,
       },
@@ -421,60 +647,60 @@ export async function handleMessage(
 
     // 内置指令
     const cmd = parseCommand(msg.content);
-    if (cmd === "help") {
+    if (cmd?.name === "help") {
       await replyTo(
         api,
         state,
         msg.openid,
         [
           "pi-qqbot 指令:",
-          "/status — 查看状态（忙闲 / 自动同意 / 待审批）",
+          "/status — 查看状态（忙闲 / 队列 / 自动同意 / 待审批）",
+          "/queue — 查看队列；/queue clear 清空；/queue drop <编号> 删一条",
           "/reset — 清空回复缓冲、审批记忆与自动同意（不换会话；换会话发 /new）",
-          "/cancel（或「取消」「停止」）— 中断正在运行的任务",
+          "/cancel（或「取消」「停止」）— 中断正在运行的任务并清空队列",
           "/help — 帮助",
           "pi 的命令优先：/reload /new /compact /session /name /model /thinking，以及扩展命令、模板与 /skill:xxx。",
+          "忙碌时发来的普通消息（含模板/skill 命令）会排队，当前任务结束后自动执行。",
           "其余文本交给 pi 当作对话处理。",
         ].join("\n"),
       );
       return;
     }
-    if (cmd === "status") {
+    if (cmd?.name === "status") {
       await replyTo(
         api,
         state,
         msg.openid,
         [
-          `状态: ${state.busy ? "处理中（发送 /cancel 可中断）" : "空闲"}`,
+          `状态: ${state.busy ? "处理中（发送 /cancel 可中断）" : state.queue.size > 0 ? "空闲，但有排队任务待派发" : "空闲"}`,
+          `队列: ${state.queue.size} 条待执行${state.queue.size > 0 ? "（发 /queue 查看）" : ""}`,
           `自动同意: ${state.approver.autoAllowed ? "已开启（本会话有效）" : "未开启"}`,
           `待审批: ${state.approver.pendingCount}`,
         ].join("\n"),
       );
       return;
     }
-    if (cmd === "reset") {
+    if (cmd?.name === "queue") {
+      await handleQueueCommand(api, state, msg.openid, cmd.args);
+      return;
+    }
+    if (cmd?.name === "reset") {
       state.replyBuffer.reset();
       state.approver.reset();
       await replyTo(api, state, msg.openid, "已重置（回复缓冲/审批记忆/自动同意）。要开新会话请发 /new。");
       return;
     }
 
-    // 忙检查：单会话串行处理
-    if (state.busy) {
-      await replyTo(api, state, msg.openid, "上一条消息还在处理中，请稍候…");
+    // 忙检查：单会话串行处理——忙碌时入队，当前任务结束后自动继续
+    if (isBusy(state)) {
+      await enqueueJob(api, state, msg.openid, msg.content);
       return;
     }
 
     // ack
     await replyTo(api, state, msg.openid, "收到，正在处理");
 
-    state.currentOpenid = msg.openid;
-    state.busy = true;
-    state.cancelled = false;
-    state.replyBuffer.reset();
-
-    // 交给 pi 处理
-    pi.sendUserMessage(msg.content, { deliverAs: "followUp" });
-    log("[msg] 已送入 pi:", msg.content.slice(0, 60));
+    startJob(pi, state, state.queue.mint(msg.openid, msg.content));
   } catch (e) {
     log("[msg] 处理失败:", String(e));
     await replyTo(api, state, msg.openid, `处理失败: ${String(e).slice(0, 200)}`).catch(() => {});
@@ -500,11 +726,53 @@ async function replyTo(
   }
 }
 
-function parseCommand(text: string): "reset" | "status" | "help" | null {
+function parseCommand(text: string): { name: "reset" | "status" | "help" | "queue"; args: string } | null {
   // 注意：/new 现在属于 pi 的内置命令（由 slash 路由接管，真的开新会话），
   // 本地的「清缓冲/清审批记忆」改名为 /reset。
-  const m = /^\/(reset|status|help)\s*$/i.exec(text.trim());
-  return m ? (m[1].toLowerCase() as "reset" | "status" | "help") : null;
+  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(),
+  };
+}
+
+/** /queue [clear|drop <编号>] */
+async function handleQueueCommand(api: QQApi, state: State, openid: string, args: string) {
+  const parts = args.split(/\s+/).filter(Boolean);
+  const sub = parts[0]?.toLowerCase() ?? "";
+
+  if (!sub) {
+    await replyTo(api, state, openid, formatQueue(state));
+    return;
+  }
+  if (/^(clear|reset|清空)$/i.test(sub)) {
+    const dropped = state.queue.clear();
+    await replyTo(
+      api,
+      state,
+      openid,
+      dropped.length > 0 ? `已清空队列（${dropped.length} 条）。` : "队列本来就是空的。",
+    );
+    return;
+  }
+  if (/^(drop|del|rm|删除|删|去掉)$/i.test(sub)) {
+    const id = Number.parseInt(parts[1] ?? "", 10);
+    if (!Number.isFinite(id)) {
+      await replyTo(api, state, openid, "用法：/queue drop <编号>（编号见 /queue）");
+      return;
+    }
+    const removed = state.queue.remove(id);
+    await replyTo(
+      api,
+      state,
+      openid,
+      removed ? `已从队列删除 #${id}：${previewText(removed.text)}` : `队列里没有 #${id}，发 /queue 查看。`,
+    );
+    return;
+  }
+  await replyTo(api, state, openid, "用法：/queue 查看 / /queue clear 清空 / /queue drop <编号> 删一条");
 }
 
 /** 从 tool_call 事件提取可读摘要，让用户在 QQ 里看清要执行什么 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zxh126/pi-qqbot",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "description": "Bridge the Pi coding agent into QQ private chats, with remote tool-call approval",
   "license": "MIT",
@@ -26,6 +26,9 @@
       "./index.ts"
     ]
   },
+  "scripts": {
+    "test": "node test/queue.test.mjs"
+  },
   "files": [
     "*.ts",
     "qq",

package/queue.ts

@@ -0,0 +1,118 @@
+/**
+ * QQ 侧任务队列。
+ *
+ * pi 的单会话是串行执行的：一轮 agent run 结束（agent_settled）后才可能开始下一轮。
+ * 于是忙碌期间收到的消息不再丢弃/拒绝，而是排队；当前任务结束后由 index.ts 的
+ * `drainQueue()` 逐条取出执行。
+ *
+ * 设计要点：
+ * - 全局单队列（本扩展是单会话设计），每条任务记住自己的 openid，回复发给原主人。
+ * - FIFO，编号单调递增不复用，方便用户用 `/queue drop <编号>` 定点删除。
+ * - `/cancel` 不走队列（立即生效），并且会清空队列。
+ */
+
+export interface QueuedJob {
+	/** 队列编号，从 1 开始单调递增 */
+	id: number;
+	/** 任务来自哪个 QQ 用户 */
+	openid: string;
+	/** 交给 pi 的原始文本（普通对话 / 斜杠命令 / 提示模板 / skill 命令） */
+	text: string;
+	/** 入队时间戳（毫秒） */
+	enqueuedAt: number;
+	/** 派发失败的重试次数，由 index.ts 维护 */
+	attempts: number;
+}
+
+export type PushResult =
+	| { ok: true; job: QueuedJob; ahead: number }
+	| { 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();
+	return flat.length > max ? `${flat.slice(0, max)}…` : flat || "(空消息)";
+}
+
+/** 距离入队多久：`12s 前` / `3m 前` / `1h 前` */
+export function agoLabel(at: number, now = Date.now()): string {
+	const seconds = Math.max(0, Math.round((now - at) / 1000));
+	if (seconds < 60) return `${seconds}s 前`;
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) return `${minutes}m 前`;
+	return `${Math.floor(minutes / 60)}h 前`;
+}
+
+export class MessageQueue {
+	private jobs: QueuedJob[] = [];
+	private nextId = 1;
+	private limit: number;
+
+	/** `limit = 0` 表示关闭排队（忙碌时直接拒绝新消息） */
+	constructor(limit = DEFAULT_QUEUE_MAX) {
+		this.limit = Math.max(0, Math.floor(limit) || 0);
+	}
+
+	/** 按配置调整上限；已有的任务不会被丢弃 */
+	setLimit(limit: number) {
+		this.limit = Math.max(0, Math.floor(limit) || 0);
+	}
+
+	get size(): number {
+		return this.jobs.length;
+	}
+
+	get max(): number {
+		return this.limit;
+	}
+
+	/** 只读快照（保持插入顺序） */
+	list(): readonly QueuedJob[] {
+		return this.jobs;
+	}
+
+	push(openid: string, text: string): PushResult {
+		if (this.limit === 0 || this.jobs.length >= this.limit) return { ok: false, reason: "full" };
+		const job: QueuedJob = {
+			id: this.nextId++,
+			openid,
+			text,
+			enqueuedAt: Date.now(),
+			attempts: 0,
+		};
+		this.jobs.push(job);
+		return { ok: true, job, ahead: this.jobs.length - 1 };
+	}
+
+	/** 手动构造一条不入队的任务（直接执行 / 失败重试时用） */
+	mint(openid: string, text: string): QueuedJob {
+		return { id: 0, openid, text, enqueuedAt: Date.now(), attempts: 0 };
+	}
+
+	shift(): QueuedJob | undefined {
+		return this.jobs.shift();
+	}
+
+	/** 派发失败时放回队首重试 */
+	unshift(job: QueuedJob): void {
+		this.jobs.unshift(job);
+	}
+
+	/** 按编号删除一条 */
+	remove(id: number): QueuedJob | undefined {
+		const index = this.jobs.findIndex((job) => job.id === id);
+		if (index === -1) return undefined;
+		return this.jobs.splice(index, 1)[0];
+	}
+
+	/** 清空并返回被清掉的任务 */
+	clear(): QueuedJob[] {
+		const dropped = this.jobs;
+		this.jobs = [];
+		return dropped;
+	}
+}

package/slash.ts

@@ -114,8 +114,13 @@ export const DEFAULT_COMMANDS: CommandConfig = {
 export interface RouteDeps {
 	/** commands pi currently knows about (extension/prompt/skill) */
 	listPiCommands(): readonly { name: string; source?: string }[];
-	/** deliver a pi command through pi's own dispatcher */
-	dispatch(text: string): void;
+	/**
+	 * deliver a pi command through pi's own dispatcher.
+	 * `runsTurn` marks commands that start an agent run (prompt templates, `/skill:name`):
+	 * those are serialized through the bot's queue, everything else runs immediately.
+	 * Returns "queued" when the bot deferred it, "rejected" when the queue was full.
+	 */
+	dispatch(text: string, options?: { runsTurn?: boolean }): DispatchResult;
 	/** answer the QQ user */
 	reply(text: string): Promise<void>;
 	busy: boolean;
@@ -123,6 +128,8 @@ export interface RouteDeps {
 	log(message: string, ...rest: unknown[]): void;
 }
 
+export type DispatchResult = "dispatched" | "queued" | "rejected";
+
 export type RouteResult = "dispatched" | "handled" | "text";
 
 const allowed = (cfg: CommandConfig, name: string): boolean => {
@@ -139,11 +146,19 @@ export async function routeSlash(deps: RouteDeps, text: string): Promise<RouteRe
 
 	// 1. pi extension commands, prompt templates and skill commands
 	if (deps.cfg.passthrough) {
-		const known = deps.listPiCommands().some((c) => c.name.toLowerCase() === name);
+		const known = deps.listPiCommands().find((c) => c.name.toLowerCase() === name);
 		if (known) {
-			deps.log("[cmd] 派发 pi 扩展命令:", parsed.raw.slice(0, 80));
-			deps.dispatch(parsed.raw);
-			await deps.reply(`已派发 /${name} 给 pi。`);
+			// 提示模板与 /skill: 会开启一轮 agent run，交给队列串行；扩展命令自己管理 LLM 交互
+			const runsTurn = known.source === "prompt" || known.source === "skill";
+			deps.log("[cmd] 派发 pi 命令:", parsed.raw.slice(0, 80), "runsTurn=", runsTurn);
+			const result = deps.dispatch(parsed.raw, { runsTurn });
+			if (result === "queued") {
+				await deps.reply(`已排队 /${name}：当前任务结束后执行（发 /queue 查看队列）。`);
+			} else if (result === "rejected") {
+				await deps.reply(`队列已满，/${name} 没有排上。发 /queue 查看队列，或 /cancel 清空后重发。`);
+			} else {
+				await deps.reply(`已派发 /${name} 给 pi。`);
+			}
 			return "dispatched";
 		}
 	}