@zxh126/pi-qqbot 2.4.0 → 2.4.1

package/CHANGELOG.md

@@ -3,6 +3,46 @@
 本文件记录 pi-qqbot 的版本变更。格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
 
+## [2.4.1] - 2026-11-01
+
+### Added
+
+- **`!` / `!!` 在 QQ 侧明确回执，不再静默丢给模型**：这两个前缀（含全角 `！` / `！！`）只在 pi 主机
+  TUI / RPC 前端被当成 shell 命令（`interactive-mode` 的 `text.startsWith("!")`、RPC 的 `bash` 控制命令），
+  扩展 API 没有等价能力（`pi.sendUserMessage()` 不分派它们，`pi.exec()` 不过审批、不写会话历史）。现在
+  `routeSlash()` 的第一步就拦下来，回一条说明：为什么不能执行，以及该怎么做（用中文说需求，走 `bash`
+  工具并在执行前审批）。既不执行，也不当聊天送给模型。
+- **`/help` 增补一行**：说明 `!` / `!!` 不支持。
+
+### Changed
+
+- **判定刻意收紧**：只有「前缀 + 非空命令」才算 bang 命令（单独 `!`、`!!`、`!!!`、`/xxx`、句末感叹号
+  `你好!` 都照旧走普通对话），避免把情绪化感叹号吞掉。
+
+### Fixed
+
+- **`/qq reload` 不再报 `This extension ctx is stale after session replacement or reload`**（`/new`、
+  `/clone`、`/resume`、`/fork`、`/tree` 的编号选择同理）：`runBridge()` 之后处理器还要 `syncModelFromCtx()`
+  读一次 `ctx.model`，而 `reload()` / `newSession()` / `fork()` / `switchSession()` / `navigateTree()`
+  一返回，pi 就把旧 `ExtensionCommandContext` 的**每个 guard getter 都变成抛错**（`runner.js` 的
+  `createCommandContext` 刻意保留 lazy descriptors）。现在：新增 `REPLACES_RUNTIME`
+  （`reload` / `update` / `new` / `quit` / `clone`），换过运行时就直接跳过 ctx 收尾；`syncModelFromCtx()`
+  自身也容错（`pick` 选 tree/fork/resume 这类运行时才知道的分支靠它兜底）；桥接抛错后也不再继续碰 ctx。
+  回归用例 `test/bridge-stale-ctx.test.mjs` 用「替换后任何 getter 都抛 stale」的假 ctx 复现原报错栈
+  （`syncModelFromCtx` ← `handler`）：修前 3 例失败、修后 5 例全绿。
+
+### Compatibility
+
+- 纯新增分支：斜杠命令路由、审批、队列、进度、凭据接手都不受影响。
+- 行为变化仅一处：`!xxx` / `!!xxx` 以前是「当作普通正文送给模型」，现在是「回执不执行」。如果之前靠发
+  `!xxx` 让模型自己去调 `bash`，请改成正常描述需求。
+- 带附件的消息仍绕过所有指令路由（含 bang 判定），与原来一致。
+- `/reload`、`/update`、`/new`、`/clone` 的**功能**还是原来的（会话确实被替换/重载），只是不再多报一条错误。
+- 测试：新增 `test/bang-notice.test.mjs`（6 例）、`test/bridge-stale-ctx.test.mjs`（5 例），
+  `npm test` 19 个用例文件全绿。
+- 升级无痛：配置格式、命令名、审批与队列语义均未变；`!` / `!!` 之前就是「不执行」，只是从「静默丢给模型」
+  改成「明确回执」。
+
 ## [2.4.0] - 2026-11-01
 
 ### Added
@@ -96,8 +136,6 @@
   `source=extension` 的 input 不算接管。
 - `test/remote-notice.test.mjs` 加 `qq-local-handoff` 的 tag 与文案断言。
 
-## [Unreleased]
-
 ## [2.2.1] - 2026-02-11
 
 ### Fixed

package/README.md

@@ -27,6 +27,7 @@ Bridge the **[Pi](https://pi.dev) coding agent** into QQ private (C2C) chats: se
 | **Images & files** | Anything you attach in QQ is downloaded to a temp file and handed to pi as a marked line — `图片路径 <path>` for images, `语音路径` / `视频路径` / `文档路径` / `压缩包路径` / `文件路径` for the rest — and QQ gets a receipt with the counts and paths. pi's `read` tool can open the image, `bash` can process the file. |
 | **Send files to your QQ** | Ask the agent to send a file from the machine (`把 D:\docs\report.pdf 发给我`) or run `/sendfile <path>`; the bot uploads it in 5 MB chunks (QQ rich media) and sends it as an image / video / voice / file card. Images (png/jpg), videos (mp4) and voice (silk) render natively; everything else arrives as a downloadable file card. **Always approved in QQ first.** |
 | **Built-in commands** | `/status`, `/queue`, `/progress` (+ `/progress off` / `on`), `/reset`, `/cancel`, `/sendfile`, `/update`, `/help`. |
+| **`!` / `!!` are answered, not executed** | pi's shell shortcuts only exist inside its TUI / RPC front end, and the extension API exposes no equivalent — so the bot replies with an explanation instead of forwarding `!ls` to the model. Ask in plain language and the agent runs it through the `bash` tool, with a QQ approval first. |
 
 ## Install
 
@@ -265,6 +266,14 @@ Host-only (answered, never forwarded to the model): `/settings`, `/hotkeys`, `/c
 `/trust`, `/login`, `/logout`, `/scoped-models`, `/llama`, `/import`, `/export`, `/share`, `/bug`,
 `/copy`, `/privacy`.
 
+Messages that start with `!` or `!!` (full-width `！` / `！！` included) are **not** shell commands here.
+Those prefixes are expanded only by pi's TUI / RPC front end (`!` runs the command and lets the model see
+the output, `!!` keeps it out of the context), and the extension API has no equivalent — `pi.sendUserMessage()`
+does not dispatch them, and `pi.exec()` bypasses approval and session history. So `!ls` gets a receipt saying it
+was **not executed**; it is never forwarded to the model as prose either. To run something, just ask in words
+— the agent then calls the `bash` tool and asks in QQ before it runs. A lone `!`, `!!!`, or an exclamation
+mark at the end of a sentence is still ordinary chat.
+
 ### TUI-only commands come back to QQ
 
 Some extension commands never print into the conversation — they call `ctx.ui.notify()` (and
@@ -298,6 +307,10 @@ Guards:
   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.
+- The bridged command never touches the command ctx after a session replacement: `reload` / `update` / `new` /
+  `clone` / `quit` (and the `tree` / `fork` / `resume` picks) invalidate it, and pi then throws
+  `This extension ctx is stale after session replacement or reload` on **any** property access. The model
+  cache sync is skipped in those cases instead (`REPLACES_RUNTIME` + a guarded read).
 
 ### Queueing while busy
 

package/docs/README.zh-CN.md

@@ -24,6 +24,7 @@
 | **图片与文件** | QQ 里发来的附件会先下载到临时文件，再以标记行交给 pi——图片是 `图片路径 <path>`，其余按类型是 `语音路径` / `视频路径` / `文档路径` / `压缩包路径` / `文件路径`；QQ 侧收到一条回执（数量、类型、路径）。pi 的 `read` 工具能直接看图片，`bash` 能处理文件。 |
 | **把本机文件发到 QQ** | 让 agent 把机器上的文件发给你（「把 D:\docs\报告.pdf 发给我」）或发 `/sendfile <路径>`；机器人按 5MB 分片上传（QQ 富媒体），图片(png/jpg) / 视频(mp4) / 语音(silk) 直接展示，其余变成可下载的文件卡片。**外发必须先在 QQ 里审批。** |
 | **内置指令** | `/status`、`/queue`、`/progress`、`/reset`、`/cancel`、`/sendfile`、`/update`、`/help`。 |
+| **`!` / `!!` 只回执、不执行** | 这两个 shell 快捷前缀只在 pi 的 TUI / RPC 前端生效，扩展 API 没有等价能力，所以 QQ 侧只回一条说明，既不执行、也不把 `!ls` 当聊天丢给模型。要跑命令直接用中文说需求，agent 会调 `bash` 工具并在执行前向你申请审批。 |
 
 ## 安装
 
@@ -250,6 +251,12 @@ QQ run 还在跑时插话不处理（那时不会开新的 run）。`/status`
 只能在主机执行（回执，不转发给模型）：`/settings`、`/hotkeys`、`/changelog`、`/trust`、`/login`、
 `/logout`、`/scoped-models`、`/llama`、`/import`、`/export`、`/share`、`/bug`、`/copy`、`/privacy`。
 
+以 `!` 或 `!!` 开头的消息（全角 `！` / `！！` 也认）**不会被执行**。这两个前缀只在主机 pi 的 TUI / RPC 前端
+被当成 shell 命令（`!` 跑完把输出交给模型，`!!` 跑完把输出排除出上下文），而扩展 API 没有等价入口：
+`pi.sendUserMessage()` 不做这个分派，`pi.exec()` 又不过审批、不写会话历史。所以 `!ls` 只会收到一条
+「QQ 侧不支持」的回执，也不会被当成正文送给模型。想跑命令直接用中文说需求（例如「列一下当前目录里的仓库」），
+agent 会调 `bash` 工具，执行前在 QQ 里向你申请审批。单独一个 `!`、`!!!`、以及句末感叹号仍按普通对话处理。
+
 ### 只往 TUI 打字的命令，现在会回到 QQ
 
 有些扩展命令从不往对话里输出，而是调 `ctx.ui.notify()`（配合 `pi.appendEntry()`）——只渲染在主机
@@ -278,6 +285,10 @@ custom entry 类型名，以及它写在 `~/.pi/agent/` 下的两个配置文件
   `reload()` / `newSession()` 又只能在命令上下文里调用。于是本扩展注册了 `/qq`，把 `/reload`
   改派成 `/qq reload`。内置命令名是硬编码的（pi 没有把内置清单导出给扩展）；任何不认识的
   `/xxx` 都会退回当普通文字。
+- 桥接命令不会在「换掉运行时」之后再去碰旧 ctx：`reload` / `update` / `new` / `clone` / `quit`
+  （以及 `tree` / `fork` / `resume` 的编号选择）会让旧 `ExtensionCommandContext` 立刻失效，之后**读任何
+  属性** pi 都会抛 `This extension ctx is stale after session replacement or reload`。这些情况下模型缓存同步
+  直接跳过（`REPLACES_RUNTIME` + 防御式读取），不再多报一条错误。
 
 ### 忙碌时的队列
 

package/index.ts

@@ -36,7 +36,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 { parsePickIndex, pickerExpired, REPLACES_RUNTIME, routeSlash, runBridge, type PickerState } from "./slash";
 import { agoLabel, MessageQueue, previewText, type QueuedJob } from "./queue";
 import { ProgressTracker } from "./progress";
 import {
@@ -725,8 +725,12 @@ export default function (
       } catch (e) {
         log("[/qq] 桥接失败:", String(e));
         reply(`/${sub} 执行失败：${String(e).slice(0, 200)}`);
+        return;
       }
-      // 命令可能换了模型（/model、编号选择）：同步一份给「欠费后发新 key」用
+      // 命令可能换了模型（/model、编号选择）：同步一份给「欠费后发新 key」用。
+      // 但 reload / update / new / quit / clone 会把运行时换掉，pi 立刻把旧 ctx 判为 stale，
+      // 这时再读 ctx.model 就是错的（新实例会自己同步）——直接跳过，不发多余的错误。
+      if (REPLACES_RUNTIME.has(sub)) return;
       syncModelFromCtx(state, ctx);
     },
   });
@@ -936,9 +940,18 @@ function onDispatchError(pi: ExtensionAPI, state: State, job: QueuedJob, error:
  * 同步一份「当前真正生效的模型」到 state：
  * 1. 欠费后用户发新 key 时，要知道落到哪个 provider；
  * 2. 探测新 key 需要 baseUrl，只有 ctx.model 里有。
+ *
+ * ctx 可能是 **stale** 的：`reload()` / `newSession()` / `fork()` / `switchSession()` / `navigateTree()`
+ * 之后 pi 会把旧 ctx 的每个 guard getter 都变成抛错（"This extension ctx is stale after session
+ * replacement or reload"）。这只是个顺带的缓存，读不到就算了，不能让错误冒到命令处理器外面。
  */
 function syncModelFromCtx(state: State, ctx: any): void {
-  const model = ctx?.model;
+  let model: any;
+  try {
+    model = ctx?.model;
+  } catch {
+    return;
+  }
   if (!model?.provider || !model?.id) return;
   state.lastModel = {
     provider: String(model.provider),
@@ -1465,6 +1478,7 @@ export async function handleMessage(
           "/sendfile <路径> — 把本机文件发到你的 QQ（png/jpg/mp4/silk 直显，其余为文件卡片；外发需审批）",
           "只关进度推送：/progress off（或「别汇报了」「闭嘴」）；「停」是中断任务，不是静音",
           "/help — 帮助",
+          "不支持 ! / !! 命令：那是主机 pi 的 shell 快捷方式，QQ 侧只回执不执行；要跑命令直接用中文说需求。",
           "pi 的命令优先：/reload /new /compact /session /name /model /thinking，以及扩展命令、模板与 /skill:xxx。",
           "忙碌时发来的普通消息（含模板/skill 命令）会排队，当前任务结束后自动执行。",
           "多 bot：配置了多个 qqbot 时，多个 pi 进程会按列表顺序各自接入一个，抢不到的待命重扫。",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zxh126/pi-qqbot",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "type": "module",
   "description": "Bridge the Pi coding agent into QQ private chats, with remote tool-call approval",
   "license": "MIT",
@@ -27,7 +27,7 @@
     ]
   },
   "scripts": {
-    "test": "node test/queue.test.mjs && node test/approver.test.mjs && node test/logger.test.mjs && node test/usage-bridge.test.mjs && node test/progress.test.mjs && node test/redact.test.mjs && node test/config.test.mjs && node test/remote-notice.test.mjs && node test/lock.test.mjs && node test/accounts.test.mjs && node test/auth.test.mjs && node test/attachment.test.mjs && node test/upload.test.mjs && node test/error-notice.test.mjs && node test/billing.test.mjs && node test/credential-intake.test.mjs && node test/selfupdate.test.mjs"
+    "test": "node test/queue.test.mjs && node test/approver.test.mjs && node test/logger.test.mjs && node test/usage-bridge.test.mjs && node test/bang-notice.test.mjs && node test/bridge-stale-ctx.test.mjs && node test/progress.test.mjs && node test/redact.test.mjs && node test/config.test.mjs && node test/remote-notice.test.mjs && node test/lock.test.mjs && node test/accounts.test.mjs && node test/auth.test.mjs && node test/attachment.test.mjs && node test/upload.test.mjs && node test/error-notice.test.mjs && node test/billing.test.mjs && node test/credential-intake.test.mjs && node test/selfupdate.test.mjs"
   },
   "files": [
     "*.ts",

package/slash.ts

@@ -17,6 +17,13 @@
  *   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).
  *
+ * Messages starting with `!` / `!!` are not slash commands but they are handled here too,
+ * for the same reason: pi only turns them into shell commands in the **TUI / RPC front end**
+ * (`interactive-mode` checks `text.startsWith("!")`, RPC has a `bash` control command), and the
+ * extension API exposes no equivalent (`pi.sendUserMessage()` does not dispatch them,
+ * `pi.exec()` bypasses approval and session history). Forwarding `!ls` to the model would just
+ * confuse it, so the bridge answers with an explicit "not supported in QQ" receipt.
+ *
  * 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`.
  *
@@ -45,6 +52,39 @@ export function parseSlash(text: string): SlashCommandText | null {
 	return { name: match[1]!.toLowerCase(), args: (match[2] ?? "").trim(), raw: text.trim() };
 }
 
+export interface BangCommand {
+	/** `!` (run + show output to the model) or `!!` (run, keep output out of the context) */
+	prefix: "!" | "!!";
+	/** whatever followed the prefix */
+	command: string;
+}
+
+/** `!` / `!!`，全角 `！` / `！！` 也认（中文输入法很容易打出全角） */
+const BANG = /^([!！]{1,2})\s*([\s\S]*\S)\s*$/;
+
+/**
+ * 识别 pi 的 shell 快捷前缀。只有「前缀 + 非空命令」才算，单独一个 `!`、`!!!`、`你好!` 都退回普通文本，
+ * 免得把情绪化感叹号当成命令吞掉。
+ */
+export function parseBangCommand(text: string): BangCommand | null {
+	const match = BANG.exec(text.trim());
+	if (!match) return null;
+	const rest = match[2]!.trim();
+	// `!!!ls` 这类：第三个别当成命令内容，整体退回普通文本
+	if (/^[!！]/.test(rest)) return null;
+	return { prefix: match[1]!.replace(/！/g, "!") as "!" | "!!", command: rest };
+}
+
+/** `!` / `!!` 的 QQ 侧回执：说清为什么不能执行、以及该怎么做 */
+export function bangNotice(cmd: BangCommand): string {
+	return [
+		`QQ 侧不支持 ${cmd.prefix} 命令，这一条没有执行。`,
+		`${cmd.prefix} 是主机 pi 里的 shell 快捷方式${cmd.prefix === "!!" ? "（`!!` 还会把输出排除出模型上下文）" : ""}，` +
+			"只有 TUI / RPC 前端认识；扩展 API 没有等价能力，桥接不会假装执行一遍（也不会把这条丢给模型去猜）。",
+		"想在本机跑命令：直接用中文说需求（例如「列一下当前目录里的仓库」），我会调 bash 工具执行，执行前在 QQ 里向你申请审批。",
+	].join("\n");
+}
+
 export type BridgeSub =
 	| "reload"
 	| "new"
@@ -92,6 +132,18 @@ update: { sub: "update", needsIdle: true, hint: "在线更新 pi-qqbot 并重载
 	sendfile: { sub: "sendfile", needsArgs: true, hint: "把本机文件发送到你的 QQ" },
 };
 
+/**
+ * `/qq <sub>` 里会**换掉运行时**的动作。
+ *
+ * pi 在它们返回后立刻把旧 `ExtensionCommandContext` 判为 stale：每个 guard getter /
+ * 方法都会抛 `This extension ctx is stale after session replacement or reload`。
+ * 所以调用方在这几个动作之后不能再碰 ctx（读 `ctx.model` 也算）。
+ *
+ * `/qq pick` 选 tree / fork / resume 时同样会换运行时，但运行时才知道选的是哪一类，
+ * 调用方对它靠 `syncModelFromCtx()` 内部的 try/catch 兜底。
+ */
+export const REPLACES_RUNTIME: ReadonlySet<string> = new Set(["reload", "update", "new", "quit", "clone"]);
+
 /** pi built-ins that the extension API cannot reach at all. */
 export const HOST_ONLY: ReadonlySet<string> = new Set([
 	"settings",
@@ -184,6 +236,14 @@ const allowed = (cfg: CommandConfig, name: string): boolean => {
 
 /** Route one slash message. Returns "text" when it should be treated as chat. */
 export async function routeSlash(deps: RouteDeps, text: string): Promise<RouteResult> {
+	// 0. `!` / `!!`：主机前端的 shell 快捷方式，扩展 API 够不到 → 明确回执，别当聊天丢给模型
+	const bang = parseBangCommand(text);
+	if (bang) {
+		deps.log("[cmd] 收到不支持的 shell 前缀:", bang.prefix, bang.command.slice(0, 60));
+		await deps.reply(bangNotice(bang));
+		return "handled";
+	}
+
 	const parsed = parseSlash(text);
 	if (!parsed) return "text";
 	const { name } = parsed;