@zxh126/pi-qqbot 2.4.0 → 2.6.0

package/CHANGELOG.md

@@ -3,6 +3,87 @@
 本文件记录 pi-qqbot 的版本变更。格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
 
+## [2.6.0] - 2026-11-01
+
+### Added
+
+- **审批与单选列表支持内联按钮**：审批卡片附带「✅ 允许一次 / ❌ 拒绝 / 🚀 以后都同意」按钮
+  （强制审批工具只有前两个）；/tree、/fork、/resume 与模型选择列表附带选项按钮（2 列、最多 5 行，
+  label 超 10 字符截断，正文仍保留完整列表）。按钮只在 markdown 回复（`markdownReply=true`）时附带。
+- **`INTERACTION_CREATE` 事件链路**：网关新增 `1<<26` 意图订阅与互动事件分发；`QQApi.acknowledgeInteraction`
+  在 5 秒窗口内 `PUT /interactions/{id}` 回应（命中 ACK 0，过期/越权/越界 ACK 3 重复操作）。
+- **`qq/keyboard.ts`**：键盘构建与 `button_data` 编解码（顶层 `t` 字段路由 approval / pick）。
+
+### Changed
+
+- `QQApi.sendC2C` 的 `SendOptions.keyboard` 只随 markdown 消息发送；markdown 失败回退纯文本时自动丢弃键盘。
+- `replyTo` / `bridgeReply` 增加可选 `keyboard` 透传；选择按钮点击复用「回复编号」的 `/qq pick` 派发路径，
+  审批按钮点击复用 `Approver.confirm` / `allowAll`，文本回复（同意/拒绝 N、编号）全部保留为兜底。
+
+### Compatibility
+
+- `markdownReply=false` 时行为与之前完全一致（键盘不附带、纯文本回复）。
+- 自定义按钮需 QQ 开放平台「内邀开通」；未开通时按钮不渲染，编号/文本回复不受影响。
+
+## [2.5.0] - 2026-11-01
+
+### Added
+
+- **`markdownReply` 配置生效**：置 `true` 后回复统一走 QQ markdown 消息（`msg_type=2`），GFM 表格、
+  代码块等由 QQ 客户端渲染。此前该配置只被解析、从未被消费。发送失败（如无 markdown 权限）由
+  `qq/api.ts` 自动回退纯文本，行为安全。
+- **`util/chunk.ts` 切分器防拆表格**：`splitText` 把 GFM 表格整块保留（表格行先入缓冲、遇到非表格行
+  再整块提交），代码块边界不作切分点；长回复不再出现被拦腰截断的破表。
+
+### Changed
+
+- 回复格式由 `state.cfg.markdownReply` 决定：`replyTo` 的 `format` 默认值改为 `auto`，最终答案、
+  错误通知、审批提示与各回执统一生效；仍可显式传 `"text"` 强制纯文本。
+
+### Compatibility
+
+- `markdownReply` 默认仍为 `false`，未开启时行为与之前完全一致。
+
+## [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 +177,6 @@
   `source=extension` 的 input 不算接管。
 - `test/remote-notice.test.mjs` 加 `qq-local-handoff` 的 tag 与文案断言。
 
-## [Unreleased]
-
 ## [2.2.1] - 2026-02-11
 
 ### Fixed

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 pi-qqbot contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 pi-qqbot contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -12,9 +12,9 @@ Bridge the **[Pi](https://pi.dev) coding agent** into QQ private (C2C) chats: se
 |---|---|
 | **Chat-driven agent** | QQ private messages are fed into the current pi session; the assistant's answer is sent back to QQ (long replies are split automatically). |
 | **Message queue** | While a task is running, further QQ messages are **queued** instead of rejected; each one starts automatically as soon as the current run settles. `/cancel` is the exception — it acts immediately and clears the queue. |
-| **Remote approval** | Before pi runs `bash` / `powershell` / `write` / `edit` — or any tool annotated `destructiveHint` — the bot asks in QQ first. |
+| **Remote approval** | Before pi runs `bash` / `powershell` / `write` / `edit` — or any tool annotated `destructiveHint` — the bot asks in QQ first. With `markdownReply: true` the card carries inline buttons; text replies work either way. |
 | **Remote-context notice** | The first QQ message of a session is really handed to pi (loading the extension or chatting locally in the TUI adds nothing), then the bot tells it the conversation comes from a remote QQ user and that the machine may be locked: desktop screenshots / screen OCR / UI automation / headed browsers are off by default, images must be rendered off-screen and sent with `qq_send_file`. Re-injected after context compaction. |
-| **Session-scoped "always allow"** | Reply 「以后都同意」 and every approval request in the **current session** is auto-approved, including the one already waiting. |
+| **Session-scoped "always allow"** | Tap 🚀 以后都同意 on the approval card (or 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, the half-written answer and the pending queue are all cleaned up. |
 | **Slash-command routing** | QQ messages starting with `/` are routed: pi extension commands, prompt templates and `/skill:name` are dispatched to pi; a set of pi built-ins (`/reload`, `/new`, `/compact`, `/session`, `/name`, `/model`, `/thinking`, `/quit`) is taken over; host-only commands are answered instead of being fed to the model. |
@@ -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
 
@@ -89,7 +90,7 @@ Then create `~/.pi/agent/pi-qqbot.json`:
 | `appId` / `appSecret` | required | Credentials of your QQ Open Platform bot |
 | `sandbox` | `false` | Set `true` while the bot is not yet published (sandbox environment) |
 | `allowlist` | `[]` | openid allowlist; empty means no restriction |
-| `markdownReply` | `false` | QQ private chat does not support markdown, keep `false` |
+| `markdownReply` | `false` | Reply with QQ markdown messages (msg_type=2) so GFM tables render; approval and selection lists then carry inline buttons (custom keyboards need platform enablement). Needs the bot's markdown permission; falls back to plain text on send failure |
 | `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) |
@@ -254,10 +255,10 @@ Any message that starts with `/` is routed before it can become a chat prompt:
 | `/name [name]` | get or set the session name | `commands.allowSession` |
 | `/model [provider/model]` | list available models or switch | `commands.allowSession` |
 | `/thinking [level]` | get or set the thinking level | `commands.allowSession` |
-| `/tree` | list branch points (numbered), answer with a number to jump there | `commands.allowSession` |
-| `/fork` | list earlier user messages (numbered), answer with a number to fork from it | `commands.allowSession` |
+| `/tree` | list branch points (numbered), answer with a number or tap the button to jump there | `commands.allowSession` |
+| `/fork` | list earlier user messages (numbered), answer with a number or tap the button 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` |
+| `/resume` | list the project's other sessions (numbered), answer with a number or tap the button to switch | `commands.allowSession` |
 | `/quit` | shuts the host pi down | `commands.allowQuit` (default **false**) |
 | `/update` | updates pi-qqbot from npm (`pi update`) and reloads itself — see [Self-update](#self-update-from-qq) | `commands.allowUpdate` (default **false**) |
 
@@ -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
@@ -288,7 +297,7 @@ Guards:
 - Prompt templates and `/skill:name` start an agent run, so while a task is in progress they are
   **queued** like ordinary messages (see [Queueing while busy](#queueing-while-busy)). Extension commands
   that manage their own LLM interaction still run immediately.
-- Selection commands (`/tree`, `/fork`, `/resume`) answer with a numbered list of at most 10 entries, scoped to
+- Selection commands (`/tree`, `/fork`, `/resume`) answer with a numbered list of at most 10 entries (with tap-to-select buttons when `markdownReply` is on), 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
@@ -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
 
@@ -468,7 +481,11 @@ This is pi's own update path, not a re-implementation: `npm view @zxh126/pi-qqbo
 要本会话内全部放行，回复「以后都同意」（可用「取消自动同意」关闭）。
 ```
 
-Reply vocabulary (approval keywords are Chinese, with English aliases):
+With `markdownReply: true` the card carries ✅ 允许一次 / ❌ 拒绝 / 🚀 以后都同意 buttons — tapping one
+is the same as replying. Strict tools (`qq_send_file`) show only the first two buttons. Text replies keep
+working either way.
+
+Reply vocabulary (approval keywords are Chinese, with English aliases; the card buttons are the faster path when they are shown):
 
 | Intent | Reply |
 |---|---|

package/approver.ts

@@ -99,8 +99,8 @@ export class Approver {
   render(seq: number, opts: { strict?: boolean } = {}): string {
     const item = this.pending.get(seq);
     const hint = opts.strict
-      ? `回「同意 ${seq}」或「拒绝 ${seq}」，需单独确认。`
-      : `回「同意 ${seq}」或「拒绝 ${seq}」；想全部放行回「以后都同意」。`;
+      ? `点下方按钮，或回「同意 ${seq}」/「拒绝 ${seq}」，需单独确认。`
+      : `点下方按钮，或回「同意 ${seq}」/「拒绝 ${seq}」；想全部放行回「以后都同意」。`;
     return [`[审批 #${seq}] ${item?.summary ?? ""}`, hint].join("\n");
   }