@zxh126/pi-qqbot 1.0.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
@@ -90,15 +98,26 @@ Any message that starts with `/` is routed before it can become a chat prompt:
 | `/name [name]` | get or set the session name | `commands.allowSession` |
 | `/model [provider/model]` | list available models or switch | `commands.allowSession` |
 | `/thinking [level]` | get or set the thinking level | `commands.allowSession` |
+| `/tree` | list branch points (numbered), answer with a number to jump there | `commands.allowSession` |
+| `/fork` | list earlier user messages (numbered), answer with a number to fork from it | `commands.allowSession` |
+| `/clone` | duplicate the current session at its current leaf | `commands.allowSession` |
+| `/resume` | list the project's other sessions (numbered), answer with a number to switch | `commands.allowSession` |
 | `/quit` | shuts the host pi down | `commands.allowQuit` (default **false**) |
 
 Host-only (answered, never forwarded to the model): `/settings`, `/hotkeys`, `/changelog`,
-`/trust`, `/login`, `/logout`, `/scoped-models`, `/llama`, `/tree`, `/fork`, `/clone`, `/resume`,
-`/import`, `/export`, `/share`, `/bug`, `/copy`, `/privacy`, `/handoff`.
+`/trust`, `/login`, `/logout`, `/scoped-models`, `/llama`, `/import`, `/export`, `/share`, `/bug`,
+`/copy`, `/privacy`.
 
 Guards:
 
-- `/reload`, `/new`, `/compact` and `/quit` refuse to run while a task is in progress — send `/cancel` first.
+- `/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.
 - `/reload` is off by default: it restarts the bot, and if the new code fails to load the bot stays
   down until someone fixes it on the host. Turn it on with `commands.allowReload: true`.
 - Why the indirection: pi only dispatches **extension** commands from a message
@@ -107,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
@@ -114,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 里的斜杠命令
@@ -90,15 +98,23 @@ pi install ./pi-qqbot
 | `/name [名字]` | 查看或设置会话名 | `commands.allowSession` |
 | `/model [provider/model]` | 列出可用模型或切换 | `commands.allowSession` |
 | `/thinking [等级]` | 查看或设置思考等级 | `commands.allowSession` |
+| `/tree` | 列出会话树上的分支点（编号），回编号即跳转 | `commands.allowSession` |
+| `/fork` | 列出之前的用户消息（编号），回编号即从该处分叉 | `commands.allowSession` |
+| `/clone` | 在当前叶子位置复制整个会话 | `commands.allowSession` |
+| `/resume` | 列出本项目其他会话（编号），回编号即切换 | `commands.allowSession` |
 | `/quit` | 关掉主机上的 pi | `commands.allowQuit`（默认 **false**） |
 
 只能在主机执行（回执，不转发给模型）：`/settings`、`/hotkeys`、`/changelog`、`/trust`、`/login`、
-`/logout`、`/scoped-models`、`/llama`、`/tree`、`/fork`、`/clone`、`/resume`、`/import`、`/export`、
-`/share`、`/bug`、`/copy`、`/privacy`、`/handoff`。
+`/logout`、`/scoped-models`、`/llama`、`/import`、`/export`、`/share`、`/bug`、`/copy`、`/privacy`。
 
 约束：
 
-- 有任务在跑时，`/reload`、`/new`、`/compact`、`/quit` 会拒绝执行 —— 先发 `/cancel`。
+- 有任务在跑时，`/reload`、`/new`、`/compact`、`/quit`、`/tree`、`/fork`、`/clone`、`/resume` 会拒绝执行
+  —— 先发 `/cancel`。
+- prompt 模板与 `/skill:name` 会开启一轮 agent run，因此忙碌时会像普通消息一样**排队**
+  （见 [忙碌时的队列](#忙碌时的队列)）；自己管理 LLM 交互的扩展命令仍然立即执行。
+- 选择型命令（`/tree`、`/fork`、`/resume`）会回一个最多 10 项的编号列表，只对该用户有效、10 分钟内有效；
+  该用户下一条「纯数字」消息即执行选择，其它内容（或「取消」）则放弃。没有待选列表时，数字就是普通对话。
 - `/reload` 默认关闭：它会重启 bot，如果新代码加载失败，bot 会一直哑着，只能在主机上救。
   置 `commands.allowReload: true` 才启用。
 - 为什么要绕一层：pi 只对**扩展命令**执行派发（`prompt()` → `_tryExecuteExtensionCommand`），而
@@ -106,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。