@zxh126/pi-qqbot 0.2.1 → 1.0.0

package/README.md

@@ -14,7 +14,9 @@ Bridge the **[Pi](https://pi.dev) coding agent** into QQ private (C2C) chats: se
 | **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. |
-| **Built-in commands** | `/new`, `/status`, `/help`. |
+| **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. |
+| **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`. |
 
 ## Install
 
@@ -53,6 +55,7 @@ Then create `~/.pi/agent/pi-qqbot.json`:
 | `streaming` | `false` | Reserved, streaming is not enabled in v1 |
 | `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` |
 
 Credentials can also come from the `QQ_BOT_APPID` / `QQ_BOT_APPSECRET` environment variables.
 
@@ -62,10 +65,64 @@ Start pi, then message the bot in QQ; pi handles it and replies.
 
 | Command | Description |
 |---|---|
-| `/new` | Reset: clear the reply buffer, approval memory and session-wide auto-approve |
+| `/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`, 「取消」, 「停止」, 「中止」, 「终止」, 「算了」) |
 | `/help` | Show help |
 
+### Slash commands from QQ
+
+Any message that starts with `/` is routed before it can become a chat prompt:
+
+| # | Kind | Behaviour |
+|---|---|---|
+| 1 | pi **extension commands**, prompt templates, `/skill:name` | dispatched to pi with `expandPromptTemplates: true`, so things like `/usage`, `/cost` or your own commands work from QQ |
+| 2 | pi built-ins this bridge can take over | re-implemented through the extension API (table below) |
+| 3 | pi built-ins that only exist in the TUI | answered with "run it on the host", never sent to the model |
+| 4 | everything else (`/tmp 里有什么`, `/etc 看看` …) | ordinary chat |
+
+| QQ command | What happens | Gate |
+|---|---|---|
+| `/reload` | reloads extensions / skills / templates / themes — **the bot restarts too** and reconnects the gateway | `commands.allowReload` (default **false**) |
+| `/new` | real new pi session (`ctx.newSession()`) | `commands.allowSession` |
+| `/compact [instructions]` | compacts the context | `commands.allowSession` |
+| `/session` | session id / cwd / model / thinking level / context usage | `commands.allowSession` |
+| `/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` |
+| `/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`.
+
+Guards:
+
+- `/reload`, `/new`, `/compact` and `/quit` refuse to run while a task is in progress — send `/cancel` first.
+- `/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
+  (`prompt()` → `_tryExecuteExtensionCommand`), and `reload()` / `newSession()` are command-context
+  APIs. So this extension registers `/qq` and forwards `/reload` → `/qq reload`. Built-in names are
+  hard-coded here because pi does not export its built-in list; any unknown `/word` falls back to
+  plain text.
+
+### Cancelling a run
+
+Long tasks started from QQ (installs, builds, a runaway agent loop) can be interrupted without going
+back to the machine:
+
+```
+you: /cancel
+bot: 已取消当前任务，并终止了 1 个待审批请求。可以发送新消息继续。
+```
+
+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.
+
 Anything else is forwarded to pi as a user message.
 
 ## Remote approval
@@ -82,7 +139,7 @@ Reply vocabulary (approval keywords are Chinese, with English aliases):
 |---|---|
 | Approve one request | `同意 1` / `allow 1` — a bare `同意` / `allow` applies to the oldest pending request |
 | Reject one request | `拒绝 1` / `deny 1` — a bare `拒绝` / `deny` applies to the oldest pending request |
-| Abort the pending requests | `停止` |
+| Abort the pending requests *and* the running task | `停止` / `/cancel` |
 | Allow everything in this session | `以后都同意`, `一直同意`, `全部放行`, `别再问了`, `always allow` |
 | Back to per-request approval | `取消自动同意`, `恢复审批`, `以后都不同意` |
 

package/approver.ts

@@ -29,7 +29,7 @@ const RE_ALWAYS =
 /** 「取消自动同意」类表达（含「以后都不同意」） */
 const RE_REVOKE =
   /(取消|关闭|结束|停止)\s*自动同意|^恢复审批$|(以后|之后|今后|都|全部)\s*不(同意|允许|批准|放行)/;
-/** 「停止」终止本轮 */
+/** 「停止」终止本轮（index.ts 里同时会 abort 当前 run） */
 const RE_TERMINATE = /^停止$/;
 /** 带或不带编号的批准/拒绝 */
 const RE_DECIDE = /^(同意|批准|放行|允许|allow|拒绝|驳回|deny)\s*(\d+)?$/i;
@@ -80,7 +80,7 @@ export class Approver {
     const item = this.pending.get(seq);
     return [
       `[审批 #${seq}] ${item?.summary ?? ""}`,
-      `回复「同意 ${seq}」批准，「拒绝 ${seq}」拒绝，「停止」终止本轮。`,
+      `回复「同意 ${seq}」批准，「拒绝 ${seq}」拒绝，「停止」（/cancel）中断本轮任务。`,
       `要本会话内全部放行，回复「以后都同意」（可用「取消自动同意」关闭）。`,
     ].join("\n");
   }

package/config.ts

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import { CONFIG_PATH } from "./constants";
+import { DEFAULT_COMMANDS, type CommandConfig } from "./slash";
 
 export interface ApproveConfig {
   /** 需要 QQ 审批的工具名（如 bash/powershell/write/edit） */
@@ -17,6 +18,8 @@ export interface QQBotConfig {
   streaming: boolean;
   toolProgress: boolean;
   approve: ApproveConfig;
+  /** QQ 侧斜杠命令的路由开关（/reload、/new… 以及扩展命令透传） */
+  commands: CommandConfig;
 }
 
 export function loadConfig(): QQBotConfig | null {
@@ -41,5 +44,11 @@ export function loadConfig(): QQBotConfig | null {
       tools: file.approve?.tools ?? ["bash", "powershell", "write", "edit"],
       remember: file.approve?.remember ?? true,
     },
+    commands: {
+      passthrough: file.commands?.passthrough ?? DEFAULT_COMMANDS.passthrough,
+      allowReload: file.commands?.allowReload ?? DEFAULT_COMMANDS.allowReload,
+      allowQuit: file.commands?.allowQuit ?? DEFAULT_COMMANDS.allowQuit,
+      allowSession: file.commands?.allowSession ?? DEFAULT_COMMANDS.allowSession,
+    },
   };
 }

package/docs/README.zh-CN.md

@@ -14,7 +14,9 @@
 | **远程审批** | pi 执行 `bash` / `powershell` / `write` / `edit`，或任何带 `destructiveHint` 注解的工具前，先在 QQ 里申请审批。 |
 | **会话级「以后都同意」** | 回复「以后都同意」，**当前会话**内所有审批请求直接放行，连已经挂起的那条也一起放行。 |
 | **单实例锁** | 只有一个 pi 进程作为宿主连接 QQ，其余待命，宿主退出后自动接管。 |
-| **内置指令** | `/new`、`/status`、`/help`。 |
+| **中断正在运行的任务** | 发 `/cancel`（或「取消」/「停止」），当前任务立刻中断 —— QQ 回复、待审批工具调用、写到一半的回答一并清理。 |
+| **斜杠命令路由** | 以 `/` 开头的 QQ 消息会先被路由：pi 的扩展命令、prompt 模板、`/skill:name` 交给 pi 派发；一部分 pi 内置命令（`/reload`、`/new`、`/compact`、`/session`、`/name`、`/model`、`/thinking`、`/quit`）由本扩展接管；只能在主机执行的内置命令直接回执，不会送给模型。 |
+| **内置指令** | `/status`、`/reset`、`/cancel`、`/help`。 |
 
 ## 安装
 
@@ -53,6 +55,7 @@ pi install ./pi-qqbot
 | `streaming` | `false` | 预留，v1 未启用流式 |
 | `approve.tools` | `["bash","powershell","write","edit"]` | 需要审批的工具名；带 `destructiveHint` 注解的工具同样会拦截 |
 | `approve.remember` | `true` | 会话内按工具记住决策（同类工具不再重复询问） |
+| `commands` | 见下 | 斜杠命令路由开关：`passthrough`、`allowReload`、`allowQuit`、`allowSession` |
 
 也可用环境变量 `QQ_BOT_APPID` / `QQ_BOT_APPSECRET` 代替文件里的凭据。
 
@@ -62,10 +65,60 @@ pi install ./pi-qqbot
 
 | 指令 | 说明 |
 |---|---|
-| `/new` | 重置：清空回复缓冲、审批记忆与自动同意开关 |
+| `/reset` | 重置：清空回复缓冲、审批记忆与自动同意开关（**不换会话**，换会话发 `/new`） |
 | `/status` | 查看忙闲状态、自动同意状态、待审批数量 |
+| `/cancel` | **中断当前正在运行的任务**（别名：`/stop`、`/abort`、「取消」、「停止」、「中止」、「终止」、「算了」） |
 | `/help` | 帮助 |
 
+### QQ 里的斜杠命令
+
+任何以 `/` 开头的消息都会先走路由，再决定是否当成对话：
+
+| # | 类型 | 行为 |
+|---|---|---|
+| 1 | pi 的**扩展命令**、prompt 模板、`/skill:name` | 以 `expandPromptTemplates: true` 派发给 pi，所以 `/usage`、`/cost` 或你自己注册的命令在 QQ 里也能用 |
+| 2 | 本桥接能接管的 pi 内置命令 | 用扩展 API 重新实现（见下表） |
+| 3 | 只能在 TUI 里跑的 pi 内置命令 | 回执「请在主机执行」，**不会**送进模型 |
+| 4 | 其余（`/tmp 里有什么`、`/etc 看看` …） | 当普通对话处理 |
+
+| QQ 命令 | 实际动作 | 开关 |
+|---|---|---|
+| `/reload` | 重载扩展 / 技能 / 模板 / 主题 —— **bot 自己也会重启**并重连网关 | `commands.allowReload`（默认 **false**） |
+| `/new` | 真正开新会话（`ctx.newSession()`） | `commands.allowSession` |
+| `/compact [指令]` | 压缩上下文 | `commands.allowSession` |
+| `/session` | 会话 id / cwd / 模型 / 思考等级 / 上下文用量 | `commands.allowSession` |
+| `/name [名字]` | 查看或设置会话名 | `commands.allowSession` |
+| `/model [provider/model]` | 列出可用模型或切换 | `commands.allowSession` |
+| `/thinking [等级]` | 查看或设置思考等级 | `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`。
+
+约束：
+
+- 有任务在跑时，`/reload`、`/new`、`/compact`、`/quit` 会拒绝执行 —— 先发 `/cancel`。
+- `/reload` 默认关闭：它会重启 bot，如果新代码加载失败，bot 会一直哑着，只能在主机上救。
+  置 `commands.allowReload: true` 才启用。
+- 为什么要绕一层：pi 只对**扩展命令**执行派发（`prompt()` → `_tryExecuteExtensionCommand`），而
+  `reload()` / `newSession()` 又只能在命令上下文里调用。于是本扩展注册了 `/qq`，把 `/reload`
+  改派成 `/qq reload`。内置命令名是硬编码的（pi 没有把内置清单导出给扩展）；任何不认识的
+  `/xxx` 都会退回当普通文字。
+
+### 取消正在运行的任务
+
+从 QQ 发起的耗时任务（装依赖、编译、agent 跑飞了）不必回到机器上处理：
+
+```
+你：/cancel
+机器人：已取消当前任务，并终止了 1 个待审批请求。可以发送新消息继续。
+```
+
+执行顺序：先终止所有待审批请求，再对当前 run 调用 `ctx.abort()`（和 TUI 里按 Escape 同一条路径），
+丢弃已经流式产生的半截回答（不会发到 QQ），清掉忙碌标记使下一条消息立刻可用，最后回执确认。
+像「取消自动同意」「恢复审批」这类**只是长得像**取消的回复仍然走审批分支，自动同意开关行为不变。
+
 其余文本都作为用户消息交给 pi。
 
 ## 远程审批
@@ -82,7 +135,7 @@ pi install ./pi-qqbot
 |---|---|
 | 批准某条 | `同意 1` / `allow 1`；裸 `同意` / `allow` 作用于最早的一条待审批 |
 | 拒绝某条 | `拒绝 1` / `deny 1`；裸 `拒绝` / `deny` 作用于最早的一条待审批 |
-| 终止当前待审批 | `停止` |
+| 终止待审批 **并中断当前任务** | `停止` / `/cancel` |
 | 本会话全部放行 | `以后都同意`、`一直同意`、`全部放行`、`别再问了`、`always allow` |
 | 恢复逐条审批 | `取消自动同意`、`恢复审批`、`以后都不同意` |
 

package/index.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { loadConfig, QQBotConfig } from "./config";
 import {
   REST_BASE_PROD,
@@ -14,6 +14,7 @@ import { AuthManager } from "./qq/auth";
 import { QQApi } from "./qq/api";
 import { createGatewayUrlFetcher, QQGateway, QQMessage } from "./qq/gateway";
 import { Approver } from "./approver";
+import { routeSlash, runBridge } from "./slash";
 import { ReplyBuffer } from "./stream-buffer";
 import { splitText } from "./util/chunk";
 
@@ -28,6 +29,14 @@ interface State {
   stopRetry: (() => void) | null;
   passiveRefs: Map<string, { msgId: string; receivedAt: number }>;
   busy: boolean;
+  /** 当前 run 的上下文（用来 abort）；run 结束或取消后清空 */
+  ctx: ExtensionContext | null;
+  /** 最近一条 QQ 消息的发送者：桥接命令用它回执 */
+  lastOpenid: string | null;
+  /** /qq 桥接命令的回执通道（每次收到 QQ 消息时刷新） */
+  bridgeReply: ((text: string) => void) | null;
+  /** 本轮已被用户取消：settle 时丢弃半截回复 */
+  cancelled: boolean;
 }
 
 export default function (pi: ExtensionAPI) {
@@ -42,8 +51,18 @@ export default function (pi: ExtensionAPI) {
     stopRetry: null,
     passiveRefs: new Map(),
     busy: false,
+    ctx: null,
+    lastOpenid: null,
+    bridgeReply: null,
+    cancelled: false,
   };
 
+  // ---- 事件：run 开始，记住 ctx（取消指令要调用 ctx.abort()）----
+  pi.on("agent_start", (_event, ctx) => {
+    state.ctx = ctx;
+    state.cancelled = false;
+  });
+
   // ---- 事件：累积 assistant 文本 ----
   pi.on("message_update", (event) => {
     const ev = event.assistantMessageEvent as any;
@@ -54,10 +73,17 @@ export default function (pi: ExtensionAPI) {
 
   // ---- 事件：run 结束，发回复 ----
   pi.on("agent_settled", async () => {
+    const cancelled = state.cancelled;
     const text = state.replyBuffer.take();
     const openid = state.currentOpenid;
     state.currentOpenid = null;
     state.busy = false;
+    state.ctx = null;
+    state.cancelled = 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)) {
@@ -185,10 +211,85 @@ export default function (pi: ExtensionAPI) {
     state.gateway = null;
     state.api = null;
   });
+
+  // ---- /qq：QQ 侧命令的桥接入口 ----
+  // pi 只对「扩展命令」执行派发，内置命令（/reload、/new…）只能在 TUI/RPC 层跑；
+  // 而 reload()/newSession() 又必须拿到 ExtensionCommandContext。于是注册一个扩展
+  // 命令，QQ 侧收到 /reload 时改派 /qq reload，就能在合法的命令上下文里执行。
+  pi.registerCommand("qq", {
+    description: "pi-qqbot 内部桥接：/qq <reload|new|compact|quit|session|name|model|thinking> [args]",
+    handler: async (args, ctx) => {
+      const trimmed = args.trim();
+      const space = trimmed.indexOf(" ");
+      const sub = (space === -1 ? trimmed : trimmed.slice(0, space)).toLowerCase();
+      const rest = (space === -1 ? "" : trimmed.slice(space + 1)).trim();
+      const reply = (text: string) => state.bridgeReply?.(text);
+      try {
+        await runBridge(sub, rest, ctx, pi, reply);
+      } catch (e) {
+        log("[/qq] 桥接失败:", String(e));
+        reply(`/${sub} 执行失败：${String(e).slice(0, 200)}`);
+      }
+    },
+  });
+}
+
+/** 取消/停止这类「打断当前任务」的表达 */
+const RE_CANCEL =
+  /^(\/cancel|\/stop|\/abort|取消|停止|中止|终止|算了|cancel|stop|abort)$/i;
+
+function isCancelIntent(text: string): boolean {
+  return RE_CANCEL.test(text.trim());
+}
+
+/**
+ * 用户发来取消指令：终止待审批、abort 当前 run、丢弃半截回复，然后回执。
+ * （「取消自动同意」/「关闭自动同意」不属于取消指令，仍走审批分支。）
+ */
+async function handleCancel(
+  state: State,
+  api: QQApi,
+  openid: string,
+): Promise<void> {
+  const terminated = state.approver.terminateAll();
+  const running = state.busy || Boolean(state.ctx?.signal);
+
+  if (!running) {
+    await replyTo(
+      api,
+      state,
+      openid,
+      terminated > 0
+        ? `已终止 ${terminated} 个待审批请求，当前没有正在运行的任务。`
+        : "当前没有正在运行的任务。",
+    );
+    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, "个");
+  } catch (e) {
+    log("[cancel] abort 失败:", String(e));
+  }
+  await replyTo(
+    api,
+    state,
+    openid,
+    terminated > 0
+      ? `已取消当前任务，并终止了 ${terminated} 个待审批请求。可以发送新消息继续。`
+      : "已取消当前任务。可以发送新消息继续。",
+  );
 }
 
 // ---- QQ 消息处理 ----
-async function handleMessage(
+export async function handleMessage(
   pi: ExtensionAPI,
   state: State,
   api: QQApi,
@@ -203,6 +304,30 @@ async function handleMessage(
     }
     state.passiveRefs.set(msg.openid, { msgId: msg.msgId, receivedAt: Date.now() });
 
+    // 取消指令优先于审批解析：「取消」不该被当成审批动作
+    if (isCancelIntent(msg.content)) {
+      await handleCancel(state, api, msg.openid);
+      return;
+    }
+
+    // 斜杠命令路由：pi 扩展命令 → 可接管的内置命令 → 仅主机可用的内置命令 → 普通文字
+    state.lastOpenid = msg.openid;
+    state.bridgeReply = (text: string) => {
+      void replyTo(api, state, msg.openid, text);
+    };
+    const routed = await routeSlash(
+      {
+        listPiCommands: () => (pi.getCommands?.() ?? []) as { name: string }[],
+        dispatch: (text: string) => pi.sendUserMessage(text, { expandPromptTemplates: true }),
+        reply: (text: string) => replyTo(api, state, msg.openid, text),
+        busy: state.busy,
+        cfg: cfg.commands,
+        log,
+      },
+      msg.content,
+    );
+    if (routed !== "text") return;
+
     // 远程审批回复优先
     const parsed = state.approver.parseReply(msg.content.trim());
     if (parsed) {
@@ -263,7 +388,15 @@ async function handleMessage(
         api,
         state,
         msg.openid,
-        ["pi-qqbot 指令:", "/new — 开新会话", "/status — 查看状态", "/help — 帮助", "其余文本交给 pi 处理。"].join("\n"),
+        [
+          "pi-qqbot 指令:",
+          "/status — 查看状态（忙闲 / 自动同意 / 待审批）",
+          "/reset — 清空回复缓冲、审批记忆与自动同意（不换会话；换会话发 /new）",
+          "/cancel（或「取消」「停止」）— 中断正在运行的任务",
+          "/help — 帮助",
+          "pi 的命令优先：/reload /new /compact /session /name /model /thinking，以及扩展命令、模板与 /skill:xxx。",
+          "其余文本交给 pi 当作对话处理。",
+        ].join("\n"),
       );
       return;
     }
@@ -273,17 +406,17 @@ async function handleMessage(
         state,
         msg.openid,
         [
-          `状态: ${state.busy ? "处理中" : "空闲"}`,
+          `状态: ${state.busy ? "处理中（发送 /cancel 可中断）" : "空闲"}`,
           `自动同意: ${state.approver.autoAllowed ? "已开启（本会话有效）" : "未开启"}`,
           `待审批: ${state.approver.pendingCount}`,
         ].join("\n"),
       );
       return;
     }
-    if (cmd === "new") {
+    if (cmd === "reset") {
       state.replyBuffer.reset();
       state.approver.reset();
-      await replyTo(api, state, msg.openid, "已重置（含审批记忆/自动同意），下一条消息开启新对话。");
+      await replyTo(api, state, msg.openid, "已重置（回复缓冲/审批记忆/自动同意）。要开新会话请发 /new。");
       return;
     }
 
@@ -298,6 +431,7 @@ async function handleMessage(
 
     state.currentOpenid = msg.openid;
     state.busy = true;
+    state.cancelled = false;
     state.replyBuffer.reset();
 
     // 交给 pi 处理
@@ -328,9 +462,11 @@ async function replyTo(
   }
 }
 
-function parseCommand(text: string): "new" | "status" | "help" | null {
-  const m = /^\/(new|status|help)\s*$/i.exec(text.trim());
-  return m ? (m[1].toLowerCase() as "new" | "status" | "help") : null;
+function parseCommand(text: string): "reset" | "status" | "help" | 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;
 }
 
 /** 从 tool_call 事件提取可读摘要，让用户在 QQ 里看清要执行什么 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zxh126/pi-qqbot",
-  "version": "0.2.1",
+  "version": "1.0.0",
   "type": "module",
   "description": "Bridge the Pi coding agent into QQ private chats, with remote tool-call approval",
   "license": "MIT",

package/slash.ts

@@ -0,0 +1,298 @@
+/**
+ * Slash-command routing for pi-qqbot.
+ *
+ * QQ messages that start with `/` are handled in this order:
+ *
+ *   1. **pi extension commands / prompt templates / skill commands** — anything the
+ *      running pi instance reports in `pi.getCommands()` (source: extension | prompt |
+ *      skill). These are dispatched verbatim with
+ *      `pi.sendUserMessage(text, { expandPromptTemplates: true })`, the only path pi
+ *      uses to execute extension commands from a message.
+ *   2. **pi built-in commands we can take over** (`TAKEOVER`) — pi never dispatches
+ *      built-ins from a message (only the TUI/RPC layer does), so these are
+ *      re-implemented through the extension API. The command-only APIs
+ *      (`reload`, `newSession`) need a fresh `ExtensionCommandContext`, so they run
+ *      inside the `/qq` bridge command registered by this extension.
+ *   3. **built-ins we cannot reach** (`HOST_ONLY`) — reply "run it on the host".
+ *   4. **anything else** — treated as ordinary chat text (the caller forwards it).
+ *
+ * Everything is opted in conservatively through `commands` in the config file.
+ */
+
+export interface SlashCommandText {
+	/** command name without the leading slash, lower-cased (`skill:name` keeps its colon) */
+	name: string;
+	/** raw text after the command name */
+	args: string;
+	/** the original message */
+	raw: string;
+}
+
+const SLASH = /^\/([A-Za-z0-9:_-]+)(?:\s+([\s\S]*))?$/;
+
+export function parseSlash(text: string): SlashCommandText | null {
+	const match = SLASH.exec(text.trim());
+	if (!match) return null;
+	return { name: match[1]!.toLowerCase(), args: (match[2] ?? "").trim(), raw: text.trim() };
+}
+
+export type BridgeSub = "reload" | "new" | "compact" | "quit" | "session" | "name" | "model" | "thinking";
+
+interface Takeover {
+	sub: BridgeSub;
+	/** the command tears down the current runtime/session: reply before dispatching */
+selfDestroying?: boolean;
+	/** unsafe to run while a task is in progress */
+	needsIdle?: boolean;
+	needsArgs?: boolean;
+	hint: string;
+}
+
+/**
+ * pi built-ins that can be re-implemented with extension APIs.
+ * `dist/core/slash-commands.d.ts` marks the full built-in list, but pi does not
+ * export it, so this table is maintained here on purpose.
+ */
+export const TAKEOVER: Readonly<Record<string, Takeover>> = {
+	reload: { sub: "reload", selfDestroying: true, needsIdle: true, hint: "重新加载扩展/技能/模板/主题" },
+	new: { sub: "new", selfDestroying: true, needsIdle: true, hint: "开启新的 pi 会话" },
+	compact: { sub: "compact", needsIdle: true, hint: "压缩上下文（可带自定义指令）" },
+	quit: { sub: "quit", selfDestroying: true, needsIdle: true, hint: "退出主机上的 pi" },
+	session: { sub: "session", hint: "查看当前会话信息与上下文用量" },
+	name: { sub: "name", hint: "设置或查看会话名称" },
+	model: { sub: "model", hint: "查看/切换模型（provider/model）" },
+	thinking: { sub: "thinking", hint: "查看/切换思考等级" },
+};
+
+/** pi built-ins that the extension API cannot reach at all. */
+export const HOST_ONLY: ReadonlySet<string> = new Set([
+	"settings",
+	"hotkeys",
+	"changelog",
+	"trust",
+	"login",
+	"logout",
+	"scoped-models",
+	"llama",
+	"tree",
+	"fork",
+	"clone",
+	"resume",
+	"import",
+	"export",
+	"share",
+	"bug",
+	"copy",
+	"privacy",
+	"handoff",
+]);
+
+export interface CommandConfig {
+	/** forward pi extension commands / prompt templates / skill commands */
+	passthrough: boolean;
+	/** allow /reload (restarts this bot too) */
+	allowReload: boolean;
+	/** allow /quit (stops the host pi process) */
+	allowQuit: boolean;
+	/** allow session-level commands: /new, /compact, /session, /name, /model, /thinking */
+	allowSession: boolean;
+}
+
+export const DEFAULT_COMMANDS: CommandConfig = {
+	passthrough: true,
+	allowReload: false,
+	allowQuit: false,
+	allowSession: true,
+};
+
+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;
+	/** answer the QQ user */
+	reply(text: string): Promise<void>;
+	busy: boolean;
+	cfg: CommandConfig;
+	log(message: string, ...rest: unknown[]): void;
+}
+
+export type RouteResult = "dispatched" | "handled" | "text";
+
+const allowed = (cfg: CommandConfig, name: string): boolean => {
+	if (name === "reload") return cfg.allowReload;
+	if (name === "quit") return cfg.allowQuit;
+	return cfg.allowSession;
+};
+
+/** Route one slash message. Returns "text" when it should be treated as chat. */
+export async function routeSlash(deps: RouteDeps, text: string): Promise<RouteResult> {
+	const parsed = parseSlash(text);
+	if (!parsed) return "text";
+	const { name } = parsed;
+
+	// 1. pi extension commands, prompt templates and skill commands
+	if (deps.cfg.passthrough) {
+		const known = deps.listPiCommands().some((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。`);
+			return "dispatched";
+		}
+	}
+
+	// 2. built-ins we can take over
+	const takeover = TAKEOVER[name];
+	if (takeover) {
+		if (!allowed(deps.cfg, name)) {
+			await deps.reply(
+				`/${name} 在 QQ 侧被禁用（配置 commands.allow${name === "reload" ? "Reload" : name === "quit" ? "Quit" : "Session"}）。`,
+			);
+			return "handled";
+		}
+		if (takeover.needsIdle && deps.busy) {
+			await deps.reply(`当前有任务在跑，先发 /cancel 取消，再执行 /${name}。`);
+			return "handled";
+		}
+		const bridge = takeover.needsArgs && !parsed.args ? `/qq ${takeover.sub}` : `/qq ${takeover.sub}${parsed.args ? ` ${parsed.args}` : ""}`;
+		deps.log("[cmd] 接管内置命令:", parsed.raw.slice(0, 80), "->", bridge.slice(0, 80));
+		if (takeover.selfDestroying) {
+			// the command tears the runtime down; answer before it lands
+			await deps.reply(`已请求 /${name}（${takeover.hint}）…`);
+			deps.dispatch(bridge);
+			return "dispatched";
+		}
+		deps.dispatch(bridge);
+		return "dispatched";
+	}
+
+	// 3. built-ins only the host TUI can run
+	if (HOST_ONLY.has(name)) {
+		await deps.reply(`/${name} 只能在主机上的 pi 里执行（扩展 API 没有对应能力）。`);
+		return "handled";
+	}
+
+	// 4. not a command we know: ordinary text
+	return "text";
+}
+
+const MAX_LIST = 12;
+
+function formatTokens(value: number | null | undefined): string {
+	if (typeof value !== "number" || !Number.isFinite(value)) return "?";
+	if (value >= 1_000_000) return `${(value / 1_000_000).toFixed(2)}M`;
+	if (value >= 1_000) return `${(value / 1_000).toFixed(1)}k`;
+	return String(value);
+}
+
+/**
+ * Body of the `/qq` bridge command: pi hands it a fresh `ExtensionCommandContext`,
+ * which is the only place `reload()` / `newSession()` are legal.
+ */
+export async function runBridge(
+	sub: string,
+	arg: string,
+	ctx: any,
+	pi: any,
+	reply: (text: string) => void,
+): Promise<void> {
+	const level = String(sub ?? "").toLowerCase();
+	switch (level) {
+		case "reload": {
+			await ctx.reload();
+			return;
+		}
+		case "new": {
+			await ctx.newSession();
+			return;
+		}
+		case "quit": {
+			reply("正在退出主机上的 pi…");
+			ctx.shutdown();
+			return;
+		}
+		case "compact": {
+			reply(arg ? `开始压缩上下文（指令：${arg.slice(0, 80)}）…` : "开始压缩上下文…");
+			ctx.compact({
+				customInstructions: arg || undefined,
+				onComplete: () => reply("上下文压缩完成。"),
+				onError: (error: Error) => reply(`上下文压缩失败：${String(error?.message ?? error).slice(0, 200)}`),
+			});
+			return;
+		}
+		case "session": {
+			const sm = ctx.sessionManager;
+			const usage = ctx.getContextUsage?.();
+			const model = ctx.model;
+			const entries = (() => {
+				try {
+					return sm.getEntries().length;
+				} catch {
+					return "?";
+				}
+			})();
+			const lines = [
+				`会话：${sm.getSessionName?.() || "(未命名)"}`,
+				`id：${sm.getSessionId?.() ?? "?"}`,
+				`cwd：${sm.getCwd?.() ?? ctx.cwd ?? "?"}`,
+				`模型：${model ? `${model.provider}/${model.id}` : "(未设置)"}  思考：${ctx.thinkingLevel ?? "?"}`,
+				`条目：${entries}   上下文：${usage && usage.tokens !== undefined ? `${formatTokens(usage.tokens)}${usage.percent !== undefined ? ` (${Math.round(usage.percent)}%)` : ""}` : "未知"}`,
+			];
+			reply(lines.join("\n"));
+			return;
+		}
+		case "name": {
+			if (!arg) {
+				reply(`当前会话名：${ctx.sessionManager.getSessionName?.() || "(未命名)"}`);
+				return;
+			}
+			pi.setSessionName(arg);
+			reply(`会话名已设为：${arg}`);
+			return;
+		}
+		case "model": {
+			const registry = ctx.modelRegistry;
+			const available = registry?.getAvailable?.() ?? [];
+			const current = ctx.model;
+			if (!arg) {
+				const names = available.slice(0, MAX_LIST).map((m: any) => `${m.provider}/${m.id}`);
+				reply(
+					[
+						`当前模型：${current ? `${current.provider}/${current.id}` : "(未设置)"}`,
+						available.length > 0 ? `可选（${available.length}）：${names.join(", ")}${available.length > MAX_LIST ? " …" : ""}` : "没有可用模型",
+					].join("\n"),
+				);
+				return;
+			}
+			const wanted = arg.toLowerCase();
+			const found = available.find((m: any) => `${m.provider}/${m.id}`.toLowerCase() === wanted)
+				?? available.find((m: any) => String(m.id).toLowerCase() === wanted);
+			if (!found) {
+				reply(`找不到模型 ${arg}。发 /model 查看可用列表。`);
+				return;
+			}
+			const ok = await pi.setModel(found);
+			reply(ok ? `模型已切换为 ${found.provider}/${found.id}` : `切换到 ${found.provider}/${found.id} 失败（缺少凭据？）`);
+			return;
+		}
+		case "thinking": {
+			if (!arg) {
+				reply(`当前思考等级：${pi.getThinkingLevel()}`);
+				return;
+			}
+			const levels = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+			const wanted = arg.toLowerCase();
+			if (!levels.includes(wanted)) {
+				reply(`思考等级只能是：${levels.join(" / ")}`);
+				return;
+			}
+			pi.setThinkingLevel(wanted);
+			reply(`思考等级已设为 ${wanted}`);
+			return;
+		}
+		default: {
+			reply(`未知的桥接命令：/qq ${arg ? `${level} ${arg}` : level}`);
+		}
+	}
+}