@zxh126/pi-qqbot 2.4.0 → 2.6.0

package/constants.ts

@@ -5,6 +5,8 @@ export const TOKEN_URL = "https://api.bot.qq.com/app/getAppAccessToken";
 export const REST_BASE_PROD = "https://api.bot.qq.com";
 export const REST_BASE_SANDBOX = "https://sandbox.api.sgroup.qq.com";
 export const INTENT_GROUP_AND_C2C = 1 << 25;
+/** 按钮点击回调（INTERACTION_CREATE）*/
+ export const INTENT_INTERACTION = 1 << 26;
 export const PASSIVE_WINDOW_MS = 60 * 60 * 1000; // 单聊被动窗口 60 分钟
 export const MAX_REPLIES_PER_MSG_ID = 4;
 export const APPROVAL_TIMEOUT_MS = 10 * 60 * 1000;

package/docs/README.zh-CN.md

@@ -12,9 +12,9 @@
 |---|---|
 | **对话驱动 agent** | QQ 单聊消息送入当前 pi 会话，AI 的回复发回 QQ（长文本自动分片）。 |
 | **消息队列** | 正在处理任务时，后续 QQ 消息会被**排队**而不是被拒；当前任务结束（settled）后按到达顺序自动逐条执行。`/cancel` 是例外——立即生效并清空队列。 |
-| **远程审批** | pi 执行 `bash` / `powershell` / `write` / `edit`，或任何带 `destructiveHint` 注解的工具前，先在 QQ 里申请审批。 |
+| **远程审批** | pi 执行 `bash` / `powershell` / `write` / `edit`，或任何带 `destructiveHint` 注解的工具前，先在 QQ 里申请审批（`markdownReply` 开启时审批卡片带内联按钮，文本回复同样有效）。 |
 | **远程上下文提醒** | **每个会话第一次真正把 QQ 消息交给 pi 跑起来**时，才告诉它「对话来自远程 QQ 用户、本机可能锁屏」：桌面截屏 / 屏幕 OCR / UI 自动化 / 带界面的浏览器默认禁用，要图就离屏渲染再用 `qq_send_file` 发回。仅载入扩展、或本机 TUI 直接对话时都不注入；上下文压缩后自动重新注入。 |
-| **会话级「以后都同意」** | 回复「以后都同意」，**当前会话**内所有审批请求直接放行，连已经挂起的那条也一起放行。 |
+| **会话级「以后都同意」** | 点审批卡片上的 🚀 以后都同意（或回复「以后都同意」），**当前会话**内所有审批请求直接放行，连已经挂起的那条也一起放行。 |
 | **单实例锁** | 只有一个 pi 进程作为宿主连接 QQ，其余待命，宿主退出后自动接管。 |
 | **中断正在运行的任务** | 发 `/cancel`（或「取消」/「停止」），当前任务立刻中断 —— QQ 回复、待审批工具调用、写到一半的回答、排队中的消息一并清理。 |
 | **斜杠命令路由** | 以 `/` 开头的 QQ 消息会先被路由：pi 的扩展命令、prompt 模板、`/skill:name` 交给 pi 派发；一部分 pi 内置命令（`/reload`、`/new`、`/compact`、`/session`、`/name`、`/model`、`/thinking`、`/quit`）由本扩展接管；只能在主机执行的内置命令直接回执，不会送给模型。 |
@@ -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` 工具并在执行前向你申请审批。 |
 
 ## 安装
 
@@ -86,7 +87,7 @@ pi install ./pi-qqbot
 | `appId` / `appSecret` | 必填 | QQ 开放平台机器人凭据 |
 | `sandbox` | `false` | 未提审上线的 bot 用 `true`（沙箱环境） |
 | `allowlist` | `[]` | openid 白名单，空 = 不限制 |
-| `markdownReply` | `false` | QQ 单聊不支持 markdown，保持 `false` |
+| `markdownReply` | `false` | 用 QQ markdown 消息（msg_type=2）回复，GFM 表格可渲染，审批与选择列表附带内联按钮（自定义按钮需平台内邀开通）；需要该 bot 的 markdown 权限，发送失败自动回退纯文本 |
 | `streaming` | `false` | 预留，v1 未启用流式 |
 | `approve.tools` | `["bash","powershell","write","edit"]` | 需要审批的工具名；带 `destructiveHint` 注解的工具同样会拦截 |
 | `approve.remember` | `true` | 会话内按工具记住决策（同类工具不再重复询问） |
@@ -240,16 +241,22 @@ QQ run 还在跑时插话不处理（那时不会开新的 run）。`/status`
 | `/name [名字]` | 查看或设置会话名 | `commands.allowSession` |
 | `/model [provider/model]` | 列出可用模型或切换 | `commands.allowSession` |
 | `/thinking [等级]` | 查看或设置思考等级 | `commands.allowSession` |
-| `/tree` | 列出会话树上的分支点（编号），回编号即跳转 | `commands.allowSession` |
-| `/fork` | 列出之前的用户消息（编号），回编号即从该处分叉 | `commands.allowSession` |
+| `/tree` | 列出会话树上的分支点（编号），回编号或点按钮即跳转 | `commands.allowSession` |
+| `/fork` | 列出之前的用户消息（编号），回编号或点按钮即从该处分叉 | `commands.allowSession` |
 | `/clone` | 在当前叶子位置复制整个会话 | `commands.allowSession` |
-| `/resume` | 列出本项目其他会话（编号），回编号即切换 | `commands.allowSession` |
+| `/resume` | 列出本项目其他会话（编号），回编号或点按钮即切换 | `commands.allowSession` |
 | `/quit` | 关掉主机上的 pi | `commands.allowQuit`（默认 **false**） |
 | `/update` | 从 npm 更新 pi-qqbot（`pi update`）并重载自己，见[从 QQ 更新自己](#从-qq-更新自己) | `commands.allowUpdate`（默认 **false**） |
 
 只能在主机执行（回执，不转发给模型）：`/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()`）——只渲染在主机
@@ -270,7 +277,7 @@ custom entry 类型名，以及它写在 `~/.pi/agent/` 下的两个配置文件
   —— 先发 `/cancel`。
 - prompt 模板与 `/skill:name` 会开启一轮 agent run，因此忙碌时会像普通消息一样**排队**
   （见 [忙碌时的队列](#忙碌时的队列)）；自己管理 LLM 交互的扩展命令仍然立即执行。
-- 选择型命令（`/tree`、`/fork`、`/resume`）会回一个最多 10 项的编号列表，只对该用户有效、10 分钟内有效；
+- 选择型命令（`/tree`、`/fork`、`/resume`）会回一个最多 10 项的编号列表（`markdownReply` 开启时附带点选按钮），只对该用户有效、10 分钟内有效；
   该用户下一条「纯数字」消息即执行选择，其它内容（或「取消」）则放弃。没有待选列表时，数字就是普通对话。
 - `/reload` 默认关闭：它会重启 bot，如果新代码加载失败，bot 会一直哑着，只能在主机上救。
   置 `commands.allowReload: true` 才启用。
@@ -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` + 防御式读取），不再多报一条错误。
 
 ### 忙碌时的队列
 
@@ -430,7 +441,10 @@ provider 报错以前在 QQ 侧等于「没反应」：pi 在 assistant 消息
 要本会话内全部放行，回复「以后都同意」（可用「取消自动同意」关闭）。
 ```
 
-回复用语（审批关键词以中文为主，也支持英文别名）：
+`markdownReply: true` 时卡片附带 ✅ 允许一次 / ❌ 拒绝 / 🚀 以后都同意 三个按钮，点按钮与回复等价；
+强制审批工具（`qq_send_file`）只显示前两个按钮。无论是否带按钮，文本回复始终有效。
+
+回复用语（审批关键词以中文为主，也支持英文别名；有按钮时点卡片按钮更快）：
 
 | 意图 | 回复 |
 |---|---|

package/docs/accounts.md

@@ -1,88 +1,88 @@
-# 多 QQ bot（2.0）
-
-一份配置里可以写多个 QQ bot；同一台机器上每个 pi 进程启动时，按配置顺序找**第一个没上线的**
-bot 接入，抢不到的进程待命并每 5 秒重扫。进程退出（或崩溃导致的锁心跳超时）后，该 bot 下线，
-待命进程接管。
-
-## 配置
-
-### 多 bot（v2）
-
-```jsonc
-// ~/.pi/agent/pi-qqbot.json
-{
-  "qqbots": [
-    { "name": "work", "appId": "1903340143", "appSecret": "……", "sandbox": true },
-    { "name": "home", "appId": "1020123456", "appSecret": "……", "sandbox": false }
-  ],
-
-  // 以下是全局默认值，qqbots 里可以逐键覆盖
-  "queue": { "max": 20, "ack": true },
-  "progress": { "enabled": true, "intervalMs": 15000 }
-}
-```
-
-- **顺序就是抢占顺序**：先起的进程拿 `work`，第二个进程拿 `home`，第三个进程抢不到就待命。
-- `name` 缺省为 `bot-<appId 后 6 位>`；日志、`/status`、接管提示都用它。
-- `name` 或 `appId` 重复、凭据缺失 → 该条被跳过并写日志，其余照常可用（不会双连接同一个 bot）。
-- 同时写顶层 `appId` 和 `qqbots` → 报错，插件不接入（歧义不猜）。
-
-### 单 bot（v1，原格式，无需改动）
-
-```json
-{ "appId": "1903340143", "appSecret": "……", "sandbox": true }
-```
-
-等价于只有一个名叫 `default` 的 bot，行为与 1.x 完全一致。凭据也仍可来自
-`QQ_BOT_APPID` / `QQ_BOT_APPSECRET` 环境变量（只用于单 bot 场景）。
-
-## 实例身份
-
-| 场景 | 表现 |
-|---|---|
-| 首次接入 | 日志 `[lock] 接入 qqbot "work" (1903340143) · cwd=E:\Projects\foo · pid=1234`；QQ 首条回执前加「（已接入 qqbot「work」）」；`/status` 显示 `bot: work (…0143) · cwd: …` |
-| 换进程接管 | 日志记录新旧 pid 与新旧 cwd；QQ 首条回执前加「（qqbot「work」已由新实例接管 · 当前工作目录 E:\Projects\foo）」 |
-| 全部在线 | 日志 `[lock] 无可接入的 qqbot（…），本进程待命，5s 后重扫`；本进程不连 QQ，pi 本身照常用 |
-| 会话重建（`/reload`、`/new`、`/fork`、`/resume`） | 释放锁**之前**先写 20 秒预约窗口，其他进程不会趁机抢走；新 runtime 用自己的 pid 认回同一个 bot，静默不打扰 |
-| 凭据无效 | 抢到锁后先换一次 `access_token`；失败就**放锁跳过该 bot**（不占槽位），继续试下一个。日志：`[lock] qqbot "x" 凭据不可用：code=100016 invalid appid or secret → 已放锁并跳过该 bot`。全部不可用时不空转重扫 |
-
-`/status` 一眼确认：
-
-```
-bot: work (…0143) · cwd: E:\Projects\foo
-状态: 空闲
-```
-
-> **工作目录与 bot 无绑定。** 分配只看「配置顺序 + 谁在线」，跟 cwd 无关：
-> 同一台机器上可以在不同的项目目录各开一个 pi，也可以在一个大工作区（里面好几个项目）里
-> 同时开几个 pi——后者照样一人接一个 bot，互不干扰。cwd 只用于日志、接管提示和 `/status` 展示，
-> 让你能分辨「现在是哪个实例在管这个 bot」。
-
-## 可选：钉住某个 bot
-
-自动抢占是默认行为。调试或需要「这个目录固定用某个 bot」时，用环境变量钉住：
-
-```powershell
-$env:PI_QQBOT_ACCOUNT = "work"; pi
-```
-
-钉选时只尝试该账号（可写 name 或 appId）；名字不存在则**不接入**并写日志（不会乱接别的 bot）。
-
-## 能/不能
-
-- **能**：同一台机器上开 N 个 pi，各接一个 bot，互不串话；目录随意（同一目录开多个也成立，目录只是 pi 的工作区）；某个 pi 退出后由待命进程接管。
-- **能**：一个 bot 同一时刻只有一个进程连着（锁 + 心跳 + 30 秒僵尸锁回收）。
-- **不能**：一个 pi 进程同时服务多个 bot（扩展的 session 是单租户模型）。要多路并行就多开 pi 进程。
-
-## 日志
-
-多 bot 场景下日志按账号分文件：`~/.pi/agent/pi-qqbot-<name>.log`（单 bot 旧格式仍写
-`pi-qqbot.log`）。身份记录与锁在 `~/.pi/agent/pi-qqbot-<appId>.lock` / `…owner.json`。
-
-## 排查：某个 bot 一直不上线
-
-1. 看日志：`凭据不可用：code=100016 invalid appid or secret` → appId/secret 写错了
-   （可用 `POST https://api.bot.qq.com/app/getAppAccessToken` 自己验一下）；
-2. 看日志：`本轮无可接入的 qqbot（x:在线）` → 这个 bot 已被别的 pi 进程连着；
-3. 看日志：`被 pid 1234 重载中` → 对方正在 `/reload`，等几秒即可；
-4. 什么都没打 → 确认配置能解析（`loadAccounts()` 报错会写 `[setup] 配置问题:`）。
+# 多 QQ bot（2.0）
+
+一份配置里可以写多个 QQ bot；同一台机器上每个 pi 进程启动时，按配置顺序找**第一个没上线的**
+bot 接入，抢不到的进程待命并每 5 秒重扫。进程退出（或崩溃导致的锁心跳超时）后，该 bot 下线，
+待命进程接管。
+
+## 配置
+
+### 多 bot（v2）
+
+```jsonc
+// ~/.pi/agent/pi-qqbot.json
+{
+  "qqbots": [
+    { "name": "work", "appId": "1903340143", "appSecret": "……", "sandbox": true },
+    { "name": "home", "appId": "1020123456", "appSecret": "……", "sandbox": false }
+  ],
+
+  // 以下是全局默认值，qqbots 里可以逐键覆盖
+  "queue": { "max": 20, "ack": true },
+  "progress": { "enabled": true, "intervalMs": 15000 }
+}
+```
+
+- **顺序就是抢占顺序**：先起的进程拿 `work`，第二个进程拿 `home`，第三个进程抢不到就待命。
+- `name` 缺省为 `bot-<appId 后 6 位>`；日志、`/status`、接管提示都用它。
+- `name` 或 `appId` 重复、凭据缺失 → 该条被跳过并写日志，其余照常可用（不会双连接同一个 bot）。
+- 同时写顶层 `appId` 和 `qqbots` → 报错，插件不接入（歧义不猜）。
+
+### 单 bot（v1，原格式，无需改动）
+
+```json
+{ "appId": "1903340143", "appSecret": "……", "sandbox": true }
+```
+
+等价于只有一个名叫 `default` 的 bot，行为与 1.x 完全一致。凭据也仍可来自
+`QQ_BOT_APPID` / `QQ_BOT_APPSECRET` 环境变量（只用于单 bot 场景）。
+
+## 实例身份
+
+| 场景 | 表现 |
+|---|---|
+| 首次接入 | 日志 `[lock] 接入 qqbot "work" (1903340143) · cwd=E:\Projects\foo · pid=1234`；QQ 首条回执前加「（已接入 qqbot「work」）」；`/status` 显示 `bot: work (…0143) · cwd: …` |
+| 换进程接管 | 日志记录新旧 pid 与新旧 cwd；QQ 首条回执前加「（qqbot「work」已由新实例接管 · 当前工作目录 E:\Projects\foo）」 |
+| 全部在线 | 日志 `[lock] 无可接入的 qqbot（…），本进程待命，5s 后重扫`；本进程不连 QQ，pi 本身照常用 |
+| 会话重建（`/reload`、`/new`、`/fork`、`/resume`） | 释放锁**之前**先写 20 秒预约窗口，其他进程不会趁机抢走；新 runtime 用自己的 pid 认回同一个 bot，静默不打扰 |
+| 凭据无效 | 抢到锁后先换一次 `access_token`；失败就**放锁跳过该 bot**（不占槽位），继续试下一个。日志：`[lock] qqbot "x" 凭据不可用：code=100016 invalid appid or secret → 已放锁并跳过该 bot`。全部不可用时不空转重扫 |
+
+`/status` 一眼确认：
+
+```
+bot: work (…0143) · cwd: E:\Projects\foo
+状态: 空闲
+```
+
+> **工作目录与 bot 无绑定。** 分配只看「配置顺序 + 谁在线」，跟 cwd 无关：
+> 同一台机器上可以在不同的项目目录各开一个 pi，也可以在一个大工作区（里面好几个项目）里
+> 同时开几个 pi——后者照样一人接一个 bot，互不干扰。cwd 只用于日志、接管提示和 `/status` 展示，
+> 让你能分辨「现在是哪个实例在管这个 bot」。
+
+## 可选：钉住某个 bot
+
+自动抢占是默认行为。调试或需要「这个目录固定用某个 bot」时，用环境变量钉住：
+
+```powershell
+$env:PI_QQBOT_ACCOUNT = "work"; pi
+```
+
+钉选时只尝试该账号（可写 name 或 appId）；名字不存在则**不接入**并写日志（不会乱接别的 bot）。
+
+## 能/不能
+
+- **能**：同一台机器上开 N 个 pi，各接一个 bot，互不串话；目录随意（同一目录开多个也成立，目录只是 pi 的工作区）；某个 pi 退出后由待命进程接管。
+- **能**：一个 bot 同一时刻只有一个进程连着（锁 + 心跳 + 30 秒僵尸锁回收）。
+- **不能**：一个 pi 进程同时服务多个 bot（扩展的 session 是单租户模型）。要多路并行就多开 pi 进程。
+
+## 日志
+
+多 bot 场景下日志按账号分文件：`~/.pi/agent/pi-qqbot-<name>.log`（单 bot 旧格式仍写
+`pi-qqbot.log`）。身份记录与锁在 `~/.pi/agent/pi-qqbot-<appId>.lock` / `…owner.json`。
+
+## 排查：某个 bot 一直不上线
+
+1. 看日志：`凭据不可用：code=100016 invalid appid or secret` → appId/secret 写错了
+   （可用 `POST https://api.bot.qq.com/app/getAppAccessToken` 自己验一下）；
+2. 看日志：`本轮无可接入的 qqbot（x:在线）` → 这个 bot 已被别的 pi 进程连着；
+3. 看日志：`被 pid 1234 重载中` → 对方正在 `/reload`，等几秒即可；
+4. 什么都没打 → 确认配置能解析（`loadAccounts()` 报错会写 `[setup] 配置问题:`）。

package/index.ts

@@ -6,6 +6,7 @@ import {
   REST_BASE_PROD,
   REST_BASE_SANDBOX,
   INTENT_GROUP_AND_C2C,
+  INTENT_INTERACTION,
   PASSIVE_WINDOW_MS,
   APPROVAL_TIMEOUT_MS,
   DISPATCH_RETRY_MS,
@@ -34,9 +35,9 @@ import { log, configureLog } from "./logger";
 import { claimAny, startClaimRetry, reserveBeforeRelease, readOwner, type Claim } from "./lock";
 import { AuthManager } from "./qq/auth";
 import { QQApi } from "./qq/api";
-import { createGatewayUrlFetcher, QQGateway, QQMessage } from "./qq/gateway";
+import { createGatewayUrlFetcher, QQGateway, QQMessage, type QQInteractionEvent } 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 {
@@ -82,6 +83,14 @@ import {
 } from "./billing";
 import { ReplyBuffer } from "./stream-buffer";
 import { splitText } from "./util/chunk";
+import {
+  buildApprovalKeyboard,
+  buildPickerKeyboard,
+  decodeButtonData,
+  type ApprovalButtonData,
+  type InlineKeyboard,
+  type PickButtonData,
+} from "./qq/keyboard";
 
 /** 发送本机文件的工具名 */
 const QQ_SEND_FILE_TOOL = "qq_send_file";
@@ -114,7 +123,7 @@ interface State {
   /** 发出列表的 QQ 用户：只有他能回编号 */
   pickerOwner: string | null;
   /** /qq 桥接命令的回执通道（每次收到 QQ 消息时刷新） */
-  bridgeReply: ((text: string) => void) | null;
+  bridgeReply: ((text: string, keyboard?: InlineKeyboard) => void) | null;
   /** 本轮已被用户取消：settle 时丢弃半截回复 */
   cancelled: boolean;
   /** 忙碌时收到的任务：当前任务 settle 后逐条执行 */
@@ -369,7 +378,7 @@ export default function (
       const notice = recoverable ? billingNotice(errorInfo) : errorNotice(errorInfo);
       log("[reply] 本轮接口报错，转告 QQ：", notice.split("\n")[0]);
       for (const chunk of splitText(notice)) {
-        await state.api.sendC2C(openid, chunk).catch((e) => {
+        await state.api.sendC2C(openid, chunk, { format: replyFormat(state) }).catch((e) => {
           log("[reply] 错误提示发送失败:", String(e));
         });
       }
@@ -377,7 +386,7 @@ export default function (
       log("[reply] agent_settled，回复 openid=", openid, "text=", text.slice(0, 80));
       let delivered = true;
       for (const chunk of splitText(text)) {
-        await state.api.sendC2C(openid, chunk).catch((e) => {
+        await state.api.sendC2C(openid, chunk, { format: replyFormat(state) }).catch((e) => {
           delivered = false;
           log("[reply] 发送失败:", String(e));
         });
@@ -427,10 +436,13 @@ export default function (
     log("[approve] 工具需要审批:", summary);
     const { seq, done } = state.approver.register(summary, () => {
       // 超时通知
-      state.api?.sendC2C(openid, `审批 #${seq} 已超时，已自动拒绝。`).catch(() => {});
+      state.api?.sendC2C(openid, `审批 #${seq} 已超时，已自动拒绝。`, { format: replyFormat(state) }).catch(() => {});
     });
     await state.api
-      .sendC2C(openid, state.approver.render(seq, { strict: forced }))
+      .sendC2C(openid, state.approver.render(seq, { strict: forced }), {
+        format: replyFormat(state),
+        keyboard: buildApprovalKeyboard(seq, { strict: forced }),
+      })
       .catch(() => {});
     const decision = await done;
 
@@ -574,10 +586,24 @@ export default function (
       const gateway = new QQGateway({
         getGatewayUrl: createGatewayUrlFetcher(restBase, () => auth.getToken()),
         getToken: () => auth.getToken(),
-        intents: INTENT_GROUP_AND_C2C,
+        intents: INTENT_GROUP_AND_C2C | INTENT_INTERACTION,
         connected: () => {},
         disconnected: () => {},
         message: (msg) => handleMessage(pi, state, api, state.cfg ?? cfg, msg),
+        interaction: (event) => {
+          // 先同步路由（settle 审批 / 派发选择），再立即 ACK（平台要求 5 秒内回应）
+          let matched = false;
+          try {
+            matched = handleInteraction(pi, state, event);
+          } catch (e) {
+            log("[interaction] 按钮处理异常:", String(e));
+          }
+          if (event.id) {
+            void api.acknowledgeInteraction(String(event.id), matched ? 0 : 3).catch((e) => {
+              log("[interaction] ACK 失败:", String(e));
+            });
+          }
+        },
       });
       state.gateway = gateway;
       log("[lock] 启动 QQ 网关");
@@ -709,7 +735,7 @@ export default function (
       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);
+      const reply = (text: string, keyboard?: InlineKeyboard) => state.bridgeReply?.(text, keyboard);
       // 发本机文件不需要命令上下文，先于 runBridge 处理
       if (sub === "sendfile") {
         try {
@@ -725,8 +751,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);
     },
   });
@@ -882,8 +912,8 @@ function startJob(pi: ExtensionAPI, state: State, job: QueuedJob) {
   state.currentOpenid = job.openid;
   state.lastOpenid = job.openid;
   state.pickerOwner = job.openid;
-  state.bridgeReply = (text: string) => {
-    void replyTo(state.api!, state, job.openid, text);
+  state.bridgeReply = (text: string, keyboard?: InlineKeyboard) => {
+    void replyTo(state.api!, state, job.openid, text, keyboard);
   };
   state.busy = true;
   state.cancelled = false;
@@ -936,9 +966,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),
@@ -971,8 +1010,8 @@ async function handleCredentialIntake(
   msg: QQMessage,
   intake: CredentialIntake,
 ): Promise<void> {
-  const reply = async (text: string) => {
-    await replyTo(api, state, msg.openid, text);
+  const reply = async (text: string, keyboard?: InlineKeyboard) => {
+    await replyTo(api, state, msg.openid, text, keyboard);
   };
   const target = state.lastModel;
 
@@ -1079,7 +1118,7 @@ async function handleCredentialIntake(
   };
   state.billing = null;
   log("[billing] 已注册 provider", providerId, "模型数", models.length, "→ 发编号选择");
-  await reply(formatModelPicker(providerId, base, models, borrowed));
+  await reply(formatModelPicker(providerId, base, models, borrowed), buildPickerKeyboard(state.picker?.items ?? []));
 }
 
 /** 当前任务结束后，取队列里的下一条开始执行（空闲时才会真的派发） */
@@ -1292,8 +1331,8 @@ export async function handleMessage(
             return;
           }
           state.pickerOwner = msg.openid;
-          state.bridgeReply = (text: string) => {
-            void replyTo(api, state, msg.openid, text);
+          state.bridgeReply = (text: string, keyboard?: InlineKeyboard) => {
+            void replyTo(api, state, msg.openid, text, keyboard);
           };
           log("[cmd] 选择编号", index, "kind=", state.picker.kind);
           pi.sendUserMessage(`/qq pick ${index}`, { expandPromptTemplates: true });
@@ -1357,8 +1396,8 @@ export async function handleMessage(
     // 斜杠命令路由：pi 扩展命令 → 可接管的内置命令 → 仅主机可用的内置命令 → 普通文字
     state.lastOpenid = msg.openid;
     state.pickerOwner = msg.openid;
-    state.bridgeReply = (text: string) => {
-      void replyTo(api, state, msg.openid, text);
+    state.bridgeReply = (text: string, keyboard?: InlineKeyboard) => {
+      void replyTo(api, state, msg.openid, text, keyboard);
     };
     const routed = hasAttachment
       ? ("text" as const)
@@ -1465,6 +1504,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 进程会按列表顺序各自接入一个，抢不到的待命重扫。",
@@ -1578,12 +1618,18 @@ export async function handleMessage(
   }
 }
 
+/** 配置 markdownReply=true 时统一走 QQ markdown 消息（msg_type=2）；无权限时 api 层自动回退纯文本 */
+function replyFormat(state: State): "text" | "markdown" {
+  return state.cfg?.markdownReply ? "markdown" : "text";
+}
+
 async function replyTo(
   api: QQApi,
   state: State,
   openid: string,
   text: string,
-  format: "text" | "markdown" = "text",
+  format: "text" | "markdown" | "auto" = "auto",
+  keyboard?: InlineKeyboard,
 ): Promise<boolean> {
   // 本进程刚接入 / 刚接管这个 qqbot：第一条回执带上身份与工作目录
   if (state.claimNote) {
@@ -1591,13 +1637,14 @@ async function replyTo(
     state.claimNote = null;
     text = `${note}\n${text}`;
   }
+  const fmt = format === "auto" ? replyFormat(state) : format;
   const ref = state.passiveRefs.get(openid);
   let delivered = true;
   for (const chunk of splitText(text)) {
     const usePassive = !!ref && Date.now() - ref.receivedAt < PASSIVE_WINDOW_MS;
     try {
-      await api.sendC2C(openid, chunk, usePassive ? { msgId: ref.msgId, format } : { format });
-      log("[reply] 已发送 (passive=", usePassive, "):", chunk.slice(0, 50));
+      await api.sendC2C(openid, chunk, usePassive ? { msgId: ref.msgId, format: fmt, keyboard } : { format: fmt, keyboard });
+      log("[reply] 已发送 (passive=", usePassive, ", format=", fmt, "):", chunk.slice(0, 50));
     } catch (e) {
       delivered = false;
       log("[reply] 发送失败:", String(e));
@@ -1606,6 +1653,84 @@ async function replyTo(
   return delivered;
 }
 
+/** 审批按钮：按 seq 匹配 pending，settle 后 tool_call 的 done 继续原流程 */
+function handleApprovalButton(state: State, openid: string, button: ApprovalButtonData): boolean {
+  const api = state.api;
+  if (!api) return false;
+  if (button.d === "always") {
+    state.approver.setAutoAllow(true);
+    const n = state.approver.allowAll();
+    log("[approve] 按钮开启自动同意，放行", n, "个待审批");
+    void replyTo(
+      api,
+      state,
+      openid,
+      [
+        `已开启自动同意：本会话内需审批的工具全部放行${n > 0 ? `，已放行 ${n} 个待审批请求` : ""}。`,
+        "回复「取消自动同意」或 /new 恢复逐条审批。",
+      ].join("\n"),
+    );
+    return true;
+  }
+  if (button.d === "allow" || button.d === "deny") {
+    const decision = button.d === "allow" ? "allow" : "block";
+    const ok = state.approver.confirm(button.s, decision);
+    const text = !ok
+      ? `#${button.s} 不存在或已超时`
+      : decision === "allow"
+        ? `已批准 #${button.s}`
+        : `已拒绝 #${button.s}`;
+    void replyTo(api, state, openid, text);
+    return ok; // 过期卡片 → false → ACK 重复操作
+  }
+  return false;
+}
+
+/** 选择按钮：等价于「回复编号」，复用 /qq pick 派发路径 */
+function handlePickButton(pi: ExtensionAPI, state: State, openid: string, button: PickButtonData): boolean {
+  const api = state.api;
+  const picker = state.picker;
+  if (!api || !picker || pickerExpired(picker)) return false;
+  if (picker.openid !== openid) return false; // 只认发起人点击
+  if (button.i < 1 || button.i > picker.items.length) return false;
+  if (isBusy(state)) {
+    void replyTo(api, state, openid, "当前有任务在跑，先发 /cancel 取消，再选择。");
+    return true;
+  }
+  state.picker = null;
+  state.pickerOwner = openid;
+  state.bridgeReply = (text: string, keyboard?: InlineKeyboard) => {
+    void replyTo(api, state, openid, text, keyboard);
+  };
+  log("[cmd] 按钮选择编号", button.i, "kind=", picker.kind);
+  try {
+    void Promise.resolve(pi.sendUserMessage(`/qq pick ${button.i}`, { expandPromptTemplates: true })).catch(
+      (e) => log("[cmd] 按钮派发失败:", String(e)),
+    );
+  } catch (e) {
+    log("[cmd] 按钮派发异常:", String(e));
+  }
+  return true;
+}
+
+/**
+ * 按钮点击统一入口（INTERACTION_CREATE）：
+ * 按 button_data 顶层 t 字段路由到审批/选择；返回是否命中（命中 → ACK 0，未命中 → ACK 3）。
+ * 回复动作全部 fire-and-forget：本函数保持同步，保证 5 秒 ACK 窗口。
+ */
+export function handleInteraction(pi: ExtensionAPI, state: State, event: QQInteractionEvent): boolean {
+  const button = decodeButtonData(event.data?.resolved?.button_data);
+  const openid = String(event.user_openid ?? "");
+  if (!button || !openid) return false;
+  // 白名单校验与消息路径一致
+  if (state.cfg?.allowlist && state.cfg.allowlist.length > 0 && !state.cfg.allowlist.includes(openid)) {
+    return false;
+  }
+  if (button.t === "approval") return handleApprovalButton(state, openid, button);
+  if (button.t === "pick") return handlePickButton(pi, state, openid, button);
+  return false;
+}
+
 /** 用户问进度的表达（忙碌时用来区分「排队」和「问进度」） */
 // 忙碌时判断「这是在问进度」：只认句首的明确表达，避免把「帮我加个进度条」这类任务误当问询
 const RE_PROGRESS_QUERY = new RegExp(