@zxh126/pi-qqbot 0.3.0 → 1.1.0

package/README.md

@@ -15,7 +15,8 @@ Bridge the **[Pi](https://pi.dev) coding agent** into QQ private (C2C) chats: se
 | **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. |
-| **Built-in commands** | `/new`, `/status`, `/cancel`, `/help`. |
+| **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
 
@@ -54,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.
 
@@ -63,11 +65,56 @@ 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` |
+| `/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`, `/import`, `/export`, `/share`, `/bug`,
+`/copy`, `/privacy`.
+
+Guards:
+
+- `/reload`, `/new`, `/compact`, `/quit`, `/tree`, `/fork`, `/clone` and `/resume` refuse to run while a task
+  is in progress — send `/cancel` first.
+- 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
+  (`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

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

@@ -15,7 +15,8 @@
 | **会话级「以后都同意」** | 回复「以后都同意」，**当前会话**内所有审批请求直接放行，连已经挂起的那条也一起放行。 |
 | **单实例锁** | 只有一个 pi 进程作为宿主连接 QQ，其余待命，宿主退出后自动接管。 |
 | **中断正在运行的任务** | 发 `/cancel`（或「取消」/「停止」），当前任务立刻中断 —— QQ 回复、待审批工具调用、写到一半的回答一并清理。 |
-| **内置指令** | `/new`、`/status`、`/cancel`、`/help`。 |
+| **斜杠命令路由** | 以 `/` 开头的 QQ 消息会先被路由：pi 的扩展命令、prompt 模板、`/skill:name` 交给 pi 派发；一部分 pi 内置命令（`/reload`、`/new`、`/compact`、`/session`、`/name`、`/model`、`/thinking`、`/quit`）由本扩展接管；只能在主机执行的内置命令直接回执，不会送给模型。 |
+| **内置指令** | `/status`、`/reset`、`/cancel`、`/help`。 |
 
 ## 安装
 
@@ -54,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` 代替文件里的凭据。
 
@@ -63,11 +65,53 @@ 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` |
+| `/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`、`/import`、`/export`、`/share`、`/bug`、`/copy`、`/privacy`。
+
+约束：
+
+- 有任务在跑时，`/reload`、`/new`、`/compact`、`/quit`、`/tree`、`/fork`、`/clone`、`/resume` 会拒绝执行
+  —— 先发 `/cancel`。
+- 选择型命令（`/tree`、`/fork`、`/resume`）会回一个最多 10 项的编号列表，只对该用户有效、10 分钟内有效；
+  该用户下一条「纯数字」消息即执行选择，其它内容（或「取消」）则放弃。没有待选列表时，数字就是普通对话。
+- `/reload` 默认关闭：它会重启 bot，如果新代码加载失败，bot 会一直哑着，只能在主机上救。
+  置 `commands.allowReload: true` 才启用。
+- 为什么要绕一层：pi 只对**扩展命令**执行派发（`prompt()` → `_tryExecuteExtensionCommand`），而
+  `reload()` / `newSession()` 又只能在命令上下文里调用。于是本扩展注册了 `/qq`，把 `/reload`
+  改派成 `/qq reload`。内置命令名是硬编码的（pi 没有把内置清单导出给扩展）；任何不认识的
+  `/xxx` 都会退回当普通文字。
+
 ### 取消正在运行的任务
 
 从 QQ 发起的耗时任务（装依赖、编译、agent 跑飞了）不必回到机器上处理：

package/index.ts

@@ -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 { parsePickIndex, pickerExpired, routeSlash, runBridge, type PickerState } from "./slash";
 import { ReplyBuffer } from "./stream-buffer";
 import { splitText } from "./util/chunk";
 
@@ -30,6 +31,14 @@ interface State {
   busy: boolean;
   /** 当前 run 的上下文（用来 abort）；run 结束或取消后清空 */
   ctx: ExtensionContext | null;
+  /** 最近一条 QQ 消息的发送者：桥接命令用它回执 */
+  lastOpenid: string | null;
+  /** 待选择列表（/tree、/fork、/resume 发出后的编号等待状态） */
+  picker: PickerState | null;
+  /** 发出列表的 QQ 用户：只有他能回编号 */
+  pickerOwner: string | null;
+  /** /qq 桥接命令的回执通道（每次收到 QQ 消息时刷新） */
+  bridgeReply: ((text: string) => void) | null;
   /** 本轮已被用户取消：settle 时丢弃半截回复 */
   cancelled: boolean;
 }
@@ -47,6 +56,10 @@ export default function (pi: ExtensionAPI) {
     passiveRefs: new Map(),
     busy: false,
     ctx: null,
+    lastOpenid: null,
+    picker: null,
+    pickerOwner: null,
+    bridgeReply: null,
     cancelled: false,
   };
 
@@ -204,6 +217,27 @@ 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, state);
+      } catch (e) {
+        log("[/qq] 桥接失败:", String(e));
+        reply(`/${sub} 执行失败：${String(e).slice(0, 200)}`);
+      }
+    },
+  });
 }
 
 /** 取消/停止这类「打断当前任务」的表达 */
@@ -276,12 +310,62 @@ export async function handleMessage(
     }
     state.passiveRefs.set(msg.openid, { msgId: msg.msgId, receivedAt: Date.now() });
 
+    // 待选择的编号回复（/tree、/fork、/resume 之后）
+    if (state.picker) {
+      if (pickerExpired(state.picker)) {
+        state.picker = null;
+      } else if (state.picker.openid === msg.openid) {
+        const index = parsePickIndex(msg.content);
+        if (index !== null) {
+          if (state.busy) {
+            await replyTo(api, state, msg.openid, "当前有任务在跑，先发 /cancel 取消，再回编号。");
+            return;
+          }
+          if (index > state.picker.items.length) {
+            await replyTo(api, state, msg.openid, `编号 ${index} 超出范围（1-${state.picker.items.length}）。`);
+            return;
+          }
+          state.pickerOwner = msg.openid;
+          state.bridgeReply = (text: string) => {
+            void replyTo(api, state, msg.openid, text);
+          };
+          log("[cmd] 选择编号", index, "kind=", state.picker.kind);
+          pi.sendUserMessage(`/qq pick ${index}`, { expandPromptTemplates: true });
+          return;
+        }
+        if (/^(取消|算了|cancel)$/i.test(msg.content.trim())) {
+          state.picker = null;
+          await replyTo(api, state, msg.openid, "已放弃选择。");
+          return;
+        }
+      }
+    }
+
     // 取消指令优先于审批解析：「取消」不该被当成审批动作
     if (isCancelIntent(msg.content)) {
       await handleCancel(state, api, msg.openid);
       return;
     }
 
+    // 斜杠命令路由：pi 扩展命令 → 可接管的内置命令 → 仅主机可用的内置命令 → 普通文字
+    state.lastOpenid = msg.openid;
+    state.pickerOwner = 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) {
@@ -344,11 +428,12 @@ export async function handleMessage(
         msg.openid,
         [
           "pi-qqbot 指令:",
-          "/new — 开新会话（清空审批记忆/自动同意）",
-          "/status — 查看状态",
+          "/status — 查看状态（忙闲 / 自动同意 / 待审批）",
+          "/reset — 清空回复缓冲、审批记忆与自动同意（不换会话；换会话发 /new）",
           "/cancel（或「取消」「停止」）— 中断正在运行的任务",
           "/help — 帮助",
-          "其余文本交给 pi 处理。",
+          "pi 的命令优先：/reload /new /compact /session /name /model /thinking，以及扩展命令、模板与 /skill:xxx。",
+          "其余文本交给 pi 当作对话处理。",
         ].join("\n"),
       );
       return;
@@ -366,10 +451,10 @@ export async function handleMessage(
       );
       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;
     }
 
@@ -415,9 +500,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.3.0",
+  "version": "1.1.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,513 @@
+/**
+ * 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`, `fork`, `navigateTree`, `switchSession`) 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).
+ *
+ * Selection-style commands (`/tree`, `/fork`, `/resume`) answer with a numbered list
+ * and accept the number as the next message; the pending list lives in `BridgeStore`.
+ *
+ * Everything is opted in conservatively through `commands` in the config file.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+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" | "tree" | "fork" | "clone" | "resume";
+
+interface Takeover {
+	sub: string;
+	/** 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: "查看/切换思考等级" },
+	tree: { sub: "list tree", needsIdle: true, hint: "在会话树上跳转（回编号选择）" },
+	fork: { sub: "list fork", needsIdle: true, hint: "从某条历史用户消息分叉（回编号选择）" },
+	resume: { sub: "list resume", needsIdle: true, hint: "切换到本项目的另一个会话（回编号选择）" },
+	clone: { sub: "clone", selfDestroying: true, needsIdle: true, 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",
+	"import",
+	"export",
+	"share",
+	"bug",
+	"copy",
+	"privacy",
+]);
+
+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, /tree, /fork, /clone, /resume */
+	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)) {
+			const gate = name === "reload" ? "allowReload" : name === "quit" ? "allowQuit" : "allowSession";
+			await deps.reply(`/${name} 在 QQ 侧被禁用（配置 commands.${gate}）。`);
+			return "handled";
+		}
+		if (takeover.needsIdle && deps.busy) {
+			await deps.reply(`当前有任务在跑，先发 /cancel 取消，再执行 /${name}。`);
+			return "handled";
+		}
+		const bridge = `/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);
+}
+
+// ---------------------------------------------------------------------------
+// pickers (tree / fork / resume)
+// ---------------------------------------------------------------------------
+
+export type PickerKind = "tree" | "fork" | "resume";
+
+export interface PickerItem {
+	/** entry id (tree/fork) */
+	id?: string;
+	/** session file (resume) */
+	path?: string;
+	/** what the user sees next to the number */
+	label: string;
+}
+
+export interface PickerState {
+	kind: PickerKind;
+	items: PickerItem[];
+	/** only this QQ user may answer with a number */
+	openid: string | null;
+	createdAt: number;
+}
+
+/** Shared mutable state between the router (index.ts) and the bridge command. */
+export interface BridgeStore {
+	picker: PickerState | null;
+	/** set by the router right before dispatching a `list` command */
+	pickerOwner: string | null;
+}
+
+export const PICKER_TTL_MS = 10 * 60_000;
+export const PICKER_MAX_ITEMS = 10;
+
+const KIND_LABEL: Record<PickerKind, string> = {
+	tree: "会话树节点",
+	fork: "可分叉的用户消息",
+	resume: "本项目的其他会话",
+};
+
+function previewText(content: unknown): string {
+	const parts = Array.isArray(content) ? content : [];
+	const text = parts
+		.map((part: any) => (part?.type === "text" && typeof part.text === "string" ? part.text : ""))
+		.join(" ")
+		.replace(/\s+/g, " ")
+		.trim();
+	return text.length > 50 ? `${text.slice(0, 50)}…` : text || "(无文本)";
+}
+
+const stamp = (value: unknown): string => {
+	const date = typeof value === "string" || typeof value === "number" ? new Date(value) : new Date();
+	if (Number.isNaN(date.getTime())) return "?";
+	const pad = (n: number) => String(n).padStart(2, "0");
+	return `${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+};
+
+function branchItems(ctx: any): PickerItem[] {
+	let branch: any[] = [];
+	try {
+		branch = ctx.sessionManager.getBranch() ?? [];
+	} catch {
+		branch = [];
+	}
+	return branch
+		.filter((entry) => entry?.type === "message" && entry?.message?.role === "user")
+		.slice(-PICKER_MAX_ITEMS)
+		.map((entry) => ({
+			id: entry.id,
+			label: `${stamp(entry.timestamp)}  ${previewText(entry.message.content)}`,
+		}));
+}
+
+function resumeItems(ctx: any): PickerItem[] {
+	let dir: string | undefined;
+	let current: string | undefined;
+	try {
+		dir = ctx.sessionManager.getSessionDir?.();
+		current = ctx.sessionManager.getSessionFile?.();
+	} catch {
+		return [];
+	}
+	if (!dir) return [];
+	let names: string[] = [];
+	try {
+		names = fs.readdirSync(dir).filter((name) => name.endsWith(".jsonl"));
+	} catch {
+		return [];
+	}
+	return names
+		.map((name) => {
+			const full = path.join(dir!, name);
+			let mtime = 0;
+			let size = 0;
+			try {
+				const stat = fs.statSync(full);
+				mtime = stat.mtimeMs;
+				size = stat.size;
+			} catch {
+				// unreadable: keep it out of the ranking
+			}
+			return { full, name, mtime, size };
+		})
+		.filter((row) => row.mtime > 0 && row.full !== current)
+		.sort((a, b) => b.mtime - a.mtime)
+		.slice(0, PICKER_MAX_ITEMS)
+		.map((row) => ({
+			path: row.full,
+			label: `${stamp(row.mtime)}  ${Math.max(1, Math.round(row.size / 1024))}KB  ${row.name.replace(/\.jsonl$/, "").slice(0, 44)}`,
+		}));
+}
+
+function buildPickerItems(kind: PickerKind, ctx: any): PickerItem[] {
+	if (kind === "resume") return resumeItems(ctx);
+	return branchItems(ctx);
+}
+
+function formatPicker(picker: PickerState): string {
+	const header = `选择${KIND_LABEL[picker.kind]}（${picker.items.length} 项）：`;
+	const rows = picker.items.map((item, index) => `  ${index + 1}. ${item.label}`);
+	return [
+		header,
+		...rows,
+		`回复编号执行，或回复「取消」放弃（${Math.round(PICKER_TTL_MS / 60000)} 分钟内有效）。`,
+	].join("\n");
+}
+
+/** Parse a bare "3" reply that answers the pending picker. */
+export function parsePickIndex(text: string): number | null {
+	const match = /^\s*(\d{1,3})\s*$/.exec(text);
+	if (!match) return null;
+	const value = Number(match[1]);
+	return Number.isFinite(value) && value > 0 ? value : null;
+}
+
+export function pickerExpired(picker: PickerState | null): boolean {
+	return !picker || Date.now() - picker.createdAt > PICKER_TTL_MS;
+}
+
+/**
+ * Body of the `/qq` bridge command: pi hands it a fresh `ExtensionCommandContext`,
+ * which is the only place `reload()`, `newSession()`, `fork()`, `navigateTree()` and
+ * `switchSession()` are legal.
+ *
+ * Session-replacing actions (`reload`, `new`, `tree`/`fork`/`resume` picks, `clone`)
+ * tear this runtime down; the caller answers the QQ user before dispatching them.
+ */
+export async function runBridge(
+	sub: string,
+	arg: string,
+	ctx: any,
+	pi: any,
+	reply: (text: string) => void,
+	store?: BridgeStore,
+): Promise<void> {
+	const level = String(sub ?? "").toLowerCase();
+	const first = arg.split(/\s+/)[0]?.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 "list": {
+			const kind = first as PickerKind;
+			if (kind !== "tree" && kind !== "fork" && kind !== "resume") {
+				reply(`未知列表类型：${first || "(空)"}`);
+				return;
+			}
+			const items = buildPickerItems(kind, ctx);
+			if (items.length === 0) {
+				reply(`没有可用的${KIND_LABEL[kind]}。`);
+				return;
+			}
+			const picker: PickerState = { kind, items, openid: store?.pickerOwner ?? null, createdAt: Date.now() };
+			if (store) store.picker = picker;
+			reply(formatPicker(picker));
+			return;
+		}
+		case "pick": {
+			const index = Number.parseInt(first, 10);
+			const picker = store?.picker ?? null;
+			if (!picker || !Number.isFinite(index)) {
+				reply("选择列表已失效，请重新发送命令。");
+				return;
+			}
+			const item = picker.items[index - 1];
+			if (!item) {
+				reply(`编号 ${first} 超出范围（1-${picker.items.length}）。`);
+				return;
+			}
+			if (store) store.picker = null;
+			if (picker.kind === "tree") {
+				reply(`正在跳转到第 ${index} 个节点…`);
+				await ctx.navigateTree(item.id);
+				return;
+			}
+			if (picker.kind === "fork") {
+				reply(`正在从第 ${index} 条消息分叉…`);
+				await ctx.fork(item.id);
+				return;
+			}
+			reply(`正在切换会话：${item.label.slice(0, 44)}…`);
+			await ctx.switchSession(item.path);
+			return;
+		}
+		case "clone": {
+			let leaf: string | null = null;
+			try {
+				leaf = ctx.sessionManager.getLeafId?.() ?? null;
+			} catch {
+				leaf = null;
+			}
+			if (!leaf) {
+				reply("当前会话还没有可复制的位置（先发一条消息）。");
+				return;
+			}
+			reply("正在当前叶子位置复制会话…");
+			await ctx.fork(leaf, { position: "at" });
+			return;
+		}
+		case "session": {
+			const sm = ctx.sessionManager;
+			const usage = ctx.getContextUsage?.();
+			const model = ctx.model;
+			const entries = (() => {
+				try {
+					return sm.getEntries().length;
+				} catch {
+					return "?";
+				}
+			})();
+			reply(
+				[
+					`会话：${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)}%)` : ""}`
+							: "未知"
+					}`,
+				].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}`);
+		}
+	}
+}