@tencent-connect/openclaw-qqbot 1.7.0-alpha.1 → 1.7.1

package/README.md

@@ -10,7 +10,7 @@
 
 **Connect your AI assistant to QQ — private chat, group chat, and rich media, all in one plugin.**
 
-### 🚀 Current Version: `v1.7.0`
+### 🚀 Current Version: `v1.7.1`
 
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![QQ Bot](https://img.shields.io/badge/QQ_Bot-API_v2-red)](https://bot.q.qq.com/wiki/)
@@ -47,45 +47,7 @@ Scan to join the QQ group chat
 | 🛠️ **Commands** | Native OpenClaw command integration |
 | 💬 **Quoted Context** | Parses the original message a user is replying to and injects it into AI context, so the model always knows exactly which message is being referenced |
 | 📦 **Large File Support** | Auto chunked upload for large files (parallel upload with retry), up to 100 MB |
-
----
-
-## 🆚 Standalone Plugin vs OpenClaw Built-in: Which to Choose?
-
-Starting from **OpenClaw 2026.3.31**, a QQBot plugin is bundled with OpenClaw. The two plugins **cannot run at the same time** — choose one based on your needs.
-
-| Feature | This Plugin (Standalone) | OpenClaw Built-in |
-|---------|:------------------------:|:-----------------:|
-| 🔒 Multi-scene (C2C / Group) | ✅ | ✅ |
-| 🖼️ Rich media (image / voice / video / file) | ✅ | ✅ |
-| 🎙️ Voice STT / TTS | ✅ | ✅ |
-| 🔥 One-click hot upgrade (`/bot-upgrade`) | ✅ | ❌ |
-| ⏰ Scheduled push (proactive messages) | ✅ | ✅ |
-| 🔗 URL support | ✅ | ✅ |
-| ⌨️ Typing indicator | ✅ | ✅ |
-| 📝 Markdown | ✅ | ✅ |
-| 🛠️ Slash commands / native commands | ✅ | ✅ |
-| 💬 Quoted context (injected into AI) | ✅ | ✅ |
-| 📦 Large file support (up to 100MB) | ✅ | ❌ |
-| Installation | Requires separate install | Bundled, zero setup |
-| Update cadence | Independent releases, faster iteration | Ships with OpenClaw |
-
-### Which should I pick?
-
-**Choose the OpenClaw built-in plugin if you:**
-
-- Want zero-setup out of the box
-- Are just getting started and want to try QQ Bot quickly
-
-**Choose this plugin (standalone) if you:**
-
-- Want faster feature iteration and more capabilities
-
-> ⚠️ Both plugins cannot run simultaneously. If you've upgraded to OpenClaw 2026.3.31+, run the following command to install this plugin — the built-in version will be disabled automatically:
-> ```bash
-> curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh | bash
-> ```
-> After upgrading, you'll unlock large file transfers, message reference context, and all other advanced features.
+| 🔐 **Command Execution Approval** | AI requests approval via Inline Keyboard buttons before executing commands — tap to allow or deny |
 
 ---
 
@@ -93,13 +55,9 @@ Starting from **OpenClaw 2026.3.31**, a QQBot plugin is bundled with OpenClaw. T
 
 > **Note:** This plugin serves as a **message channel** only — it relays messages between QQ and OpenClaw. Capabilities like image understanding, voice transcription, drawing, etc. depend on the **AI model** you configure and the **skills** installed in OpenClaw, not on this plugin itself.
 
-### 💬 Quoted Message Context (REFIDX)
-
-QQ quote events carry index keys (e.g. `REFIDX_xxx`) instead of full original message body. The plugin now resolves these indices from a local persistent store and injects quote context into AI input, so replies better understand “which message is being quoted”.
+### 💬 Quoted Message Context
 
-- Inbound and outbound messages with `ref_idx` are automatically indexed.
-- Store path: `~/.openclaw/qqbot/data/ref-index.jsonl` (survives gateway restart).
-- Quote body may include text + media summary (image/voice/video/file).
+When a user quotes a message in QQ, the plugin automatically parses the quoted message content and injects it into the AI context, so the model clearly knows "which message the user is replying to" and gives more accurate responses. Supports text and media messages (image/voice/video/file), and works across devices.
 
 <img width="360" src="docs/images/ref-msg.png" alt="Quoted Message Context Demo" />
 
@@ -177,6 +135,14 @@ Since v1.6.6, large file transfer is supported: images up to 20MB, videos up to
 
 <img width="360" src="docs/images/large-file-transfer.jpg" alt="Large File Transfer Demo" />
 
+### 🔐 Command Execution Approval
+
+When the AI needs to execute a command, the plugin sends an approval request via QQ message with interactive buttons — tap **✅ Allow Once**, **⭐ Always Allow**, or **❌ Deny** to control whether the command runs. 
+
+Use the `/bot-approve` command to manage the approval mode (allowlist / off / strict).
+
+<img width="360" src="docs/images/approve.png" alt="Command Execution Approval Demo" />
+
 ### 🎬 Video Sending
 
 > **You**: Send me a demo video
@@ -256,6 +222,22 @@ All commands support a `?` suffix to show usage:
 >
 > **QQBot**: 📖 /bot-upgrade usage: …
 
+#### `/bot-approve` — Approval Configuration
+
+> **You**: `/bot-approve`
+>
+> **QQBot**: 🔐 Command Execution Approval — Enable / Disable / Strict mode / Reset / View current config
+
+Manage the AI command execution approval policy. Supported subcommands:
+
+| Subcommand | Description |
+|------------|-------------|
+| `/bot-approve on` | Enable approval (allowlist mode, recommended) |
+| `/bot-approve off` | Disable approval — commands execute directly |
+| `/bot-approve always` | Strict mode — every execution requires approval |
+| `/bot-approve reset` | Restore framework defaults |
+| `/bot-approve status` | View current approval config |
+
 #### `/bot-clear-storage` — Clear files generated through QQBot conversations and downloaded resources (stored on the host running OpenClaw)
 
 `/bot-clear-storage` lists files generated by the conversation and files in the downloaded resources directory. Use `/bot-clear-storage --force` to confirm deletion.

package/README.zh.md

@@ -9,7 +9,7 @@
 
 **让你的 AI 助手接入 QQ — 私聊、群聊、富媒体，一个插件全搞定。**
 
-### 🚀 当前版本： `v1.7.0`
+### 🚀 当前版本： `v1.7.1`
 
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![QQ Bot](https://img.shields.io/badge/QQ_Bot-API_v2-red)](https://bot.q.qq.com/wiki/)
@@ -42,6 +42,7 @@
 | 🛠️ **原生命令** | 支持 OpenClaw 原生命令 |
 | 💬 **引用上下文** | 解析用户回复的原始消息内容，注入 AI 上下文，让模型准确理解"在回复哪条消息" |
 | 📦 **大文件支持** | 大文件自动分片并行上传，最大支持 100 MB |
+| 🔐 **命令执行审批** | AI 执行命令前通过按钮消息请求审批，点击即可允许或拒绝 |
 
 ---
 
@@ -129,6 +130,14 @@ v1.6.6 起支持大文件传输：图片最大 20MB，视频最大 30MB，附件
 
 <img width="360" src="docs/images/large-file-transfer.jpg" alt="大文件传输演示" />
 
+### 🔐 命令执行审批
+
+当 AI 需要执行命令时，插件会通过 QQ 消息发送带按钮的审批请求，你可以点击 **✅ 允许一次**、**⭐ 始终允许** 或 **❌ 拒绝** 来控制命令是否执行。
+
+通过 `/bot-approve` 指令可以管理审批模式（白名单 / 关闭 / 严格模式）。
+
+<img width="360" src="docs/images/approve.png" alt="命令执行审批演示" />
+
 ### 🎬 视频发送
 
 > **你**：发一个演示视频给我
@@ -208,6 +217,22 @@ AI 可直接发送视频，支持本地文件和公网 URL。
 >
 > **QQBot**：📖 /bot-upgrade 用法：…
 
+#### `/bot-approve` — 审批配置管理
+
+> **你**：`/bot-approve`
+>
+> **QQBot**：🔐 命令执行审批配置 — 开启审批 / 关闭审批 / 严格模式 / 恢复默认 / 查看当前配置
+
+管理 AI 命令执行审批策略，支持以下子命令：
+
+| 子命令 | 说明 |
+|--------|------|
+| `/bot-approve on` | 开启审批（白名单模式，推荐） |
+| `/bot-approve off` | 关闭审批，命令直接执行 |
+| `/bot-approve always` | 严格模式，每次执行都需审批 |
+| `/bot-approve reset` | 恢复框架默认值 |
+| `/bot-approve status` | 查看当前审批配置 |
+
 #### `/bot-clear-storage` — 清理通过 QQBot 对话产生的文件以及下载的资源（保存在 OpenClaw 运行环境的主机上）
 
 `/bot-clear-storage` 列出对话产生的文件以及下载的资源目录里的文件，使用`/bot-clear-storage -- force`确定删除。

package/dist/src/api.d.ts

@@ -132,6 +132,10 @@ export declare function sendDmMessage(accessToken: string, guildId: string, cont
     timestamp: string;
 }>;
 export declare function sendGroupMessage(accessToken: string, groupOpenid: string, content: string, msgId?: string, messageReference?: string): Promise<MessageResponse>;
+/** 发送带 Inline Keyboard 的 C2C 消息（回调型按钮，触发 INTERACTION_CREATE） */
+export declare function sendC2CMessageWithInlineKeyboard(accessToken: string, openid: string, content: string, inlineKeyboard: import("./types.js").InlineKeyboard, msgId?: string): Promise<MessageResponse>;
+/** 发送带 Inline Keyboard 的 Group 消息（回调型按钮，触发 INTERACTION_CREATE） */
+export declare function sendGroupMessageWithInlineKeyboard(accessToken: string, groupOpenid: string, content: string, inlineKeyboard: import("./types.js").InlineKeyboard, msgId?: string): Promise<MessageResponse>;
 export declare function sendProactiveC2CMessage(accessToken: string, openid: string, content: string): Promise<MessageResponse>;
 export declare function sendProactiveGroupMessage(accessToken: string, groupOpenid: string, content: string): Promise<{
     id: string;

package/dist/src/api.js

@@ -495,7 +495,7 @@ async function sendAndNotify(accessToken, method, path, body, meta) {
     }
     return result;
 }
-function buildMessageBody(content, msgId, msgSeq, messageReference) {
+function buildMessageBody(content, msgId, msgSeq, messageReference, inlineKeyboard) {
     const body = currentMarkdownSupport
         ? {
             markdown: { content },
@@ -513,6 +513,10 @@ function buildMessageBody(content, msgId, msgSeq, messageReference) {
     if (messageReference && !currentMarkdownSupport) {
         body.message_reference = { message_id: messageReference };
     }
+    // Inline Keyboard（内嵌按钮，需审核）：字段名 keyboard，结构 { content: { rows } }
+    if (inlineKeyboard) {
+        body.keyboard = inlineKeyboard;
+    }
     return body;
 }
 export async function sendC2CMessage(accessToken, openid, content, msgId, messageReference) {
@@ -556,6 +560,18 @@ export async function sendGroupMessage(accessToken, groupOpenid, content, msgId,
     const body = buildMessageBody(content, msgId, msgSeq, messageReference);
     return sendAndNotify(accessToken, "POST", `/v2/groups/${groupOpenid}/messages`, body, { text: content });
 }
+/** 发送带 Inline Keyboard 的 C2C 消息（回调型按钮，触发 INTERACTION_CREATE） */
+export async function sendC2CMessageWithInlineKeyboard(accessToken, openid, content, inlineKeyboard, msgId) {
+    const msgSeq = msgId ? getNextMsgSeq(msgId) : 1;
+    const body = buildMessageBody(content, msgId, msgSeq, undefined, inlineKeyboard);
+    return sendAndNotify(accessToken, "POST", `/v2/users/${openid}/messages`, body, { text: content });
+}
+/** 发送带 Inline Keyboard 的 Group 消息（回调型按钮，触发 INTERACTION_CREATE） */
+export async function sendGroupMessageWithInlineKeyboard(accessToken, groupOpenid, content, inlineKeyboard, msgId) {
+    const msgSeq = msgId ? getNextMsgSeq(msgId) : 1;
+    const body = buildMessageBody(content, msgId, msgSeq, undefined, inlineKeyboard);
+    return sendAndNotify(accessToken, "POST", `/v2/groups/${groupOpenid}/messages`, body, { text: content });
+}
 function buildProactiveMessageBody(content) {
     if (!content || content.trim().length === 0) {
         throw new Error("主动消息内容不能为空 (markdown.content is empty)");

package/dist/src/approval-handler.d.ts

@@ -0,0 +1,47 @@
+/**
+ * QQBot Approval Handler
+ *
+ * 监听 Gateway 的 exec/plugin approval 事件，
+ * 直接调用 QQ API 发送带 Inline Keyboard 的审批消息。
+ * 参考 DiscordExecApprovalHandler 的实现模式。
+ *
+ * 兼容性：gateway-runtime / approval-runtime 模块在 openclaw < 3.22 上不存在，
+ * 使用动态 import 避免插件整体加载失败，旧版框架上审批功能自动降级（不可用）。
+ */
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+export interface QQBotApprovalHandlerOpts {
+    accountId: string;
+    appId: string;
+    clientSecret: string;
+    cfg: OpenClawConfig;
+    gatewayUrl?: string;
+    log?: {
+        info: (msg: string) => void;
+        error: (msg: string) => void;
+        debug?: (msg: string) => void;
+    };
+}
+export declare class QQBotApprovalHandler {
+    private gatewayClient;
+    private pending;
+    private requestCache;
+    private opts;
+    private started;
+    constructor(opts: QQBotApprovalHandlerOpts);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** 检查是否有指定 shortId 对应的 pending 审批 */
+    hasShortId(shortId: string): boolean;
+    /** 解析审批请求（供 Interaction 回调或 /approve 命令调用） */
+    resolveApproval(approvalId: string, decision: "allow-once" | "allow-always" | "deny"): Promise<boolean>;
+    private handleGatewayEvent;
+    private handleRequested;
+    private handleResolved;
+    private handleTimeout;
+}
+export declare function isApprovalFeatureAvailable(): boolean;
+export declare function setApprovalFeatureAvailable(available: boolean): void;
+export declare function registerApprovalHandler(accountId: string, handler: QQBotApprovalHandler): void;
+export declare function unregisterApprovalHandler(accountId: string): void;
+export declare function getApprovalHandler(accountId: string): QQBotApprovalHandler | undefined;
+export declare function findApprovalHandlerForShortId(shortId: string): QQBotApprovalHandler | undefined;

package/dist/src/approval-handler.js

@@ -0,0 +1,372 @@
+/**
+ * QQBot Approval Handler
+ *
+ * 监听 Gateway 的 exec/plugin approval 事件，
+ * 直接调用 QQ API 发送带 Inline Keyboard 的审批消息。
+ * 参考 DiscordExecApprovalHandler 的实现模式。
+ *
+ * 兼容性：gateway-runtime / approval-runtime 模块在 openclaw < 3.22 上不存在，
+ * 使用动态 import 避免插件整体加载失败，旧版框架上审批功能自动降级（不可用）。
+ */
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { getAccessToken, sendC2CMessageWithInlineKeyboard, sendGroupMessageWithInlineKeyboard, } from "./api.js";
+// ─── 动态加载 gateway-runtime（兼容不同安装环境） ────────
+function loadGatewayRuntime() {
+    const req = createRequire(import.meta.url);
+    const currentFile = fileURLToPath(import.meta.url);
+    const pluginRoot = path.resolve(path.dirname(currentFile), "..", "..");
+    const fs = req("node:fs");
+    // 尝试从找到的 openclaw 根目录加载 gateway-runtime.js
+    const tryLoadFromRoot = (root) => {
+        for (const rel of ["dist/plugin-sdk/gateway-runtime.js", "plugin-sdk/gateway-runtime.js"]) {
+            const p = path.join(root, rel);
+            try {
+                if (fs.existsSync(p))
+                    return req(p);
+            }
+            catch { /* try next */ }
+        }
+        return null;
+    };
+    // 策略 1: link-sdk-core.cjs findOpenclawRoot
+    try {
+        const { findOpenclawRoot } = req(path.join(pluginRoot, "scripts", "link-sdk-core.cjs"));
+        const root = findOpenclawRoot(pluginRoot);
+        if (root) {
+            const mod = tryLoadFromRoot(root);
+            if (mod)
+                return mod;
+        }
+    }
+    catch { /* fallback */ }
+    // 策略 2: process.argv[1] 反推（当前进程就是 openclaw）
+    try {
+        const entry = process.argv[1];
+        if (entry) {
+            const realEntry = fs.realpathSync(entry);
+            let dir = path.dirname(realEntry);
+            for (let i = 0; i < 6; i++) {
+                const mod = tryLoadFromRoot(dir);
+                if (mod)
+                    return mod;
+                const parent = path.dirname(dir);
+                if (parent === dir)
+                    break;
+                dir = parent;
+            }
+        }
+    }
+    catch { /* fallback */ }
+    throw new Error("Cannot find openclaw/plugin-sdk/gateway-runtime (all strategies failed)");
+}
+// ─── 辅助函数 ───────────────────────────────────────────────
+function toShortId(approvalId) {
+    return approvalId.replace(/^(exec|plugin):/, "").slice(0, 8);
+}
+function resolveApprovalKind(approvalId) {
+    return approvalId.startsWith("plugin:") ? "plugin" : "exec";
+}
+function buildExecApprovalText(request) {
+    const expiresIn = Math.max(0, Math.round((request.expiresAtMs - Date.now()) / 1000));
+    const lines = ["🔐 命令执行审批", ""];
+    const cmd = request.request.commandPreview ?? request.request.command ?? "";
+    if (cmd)
+        lines.push(`\`\`\`\n${cmd.slice(0, 300)}\n\`\`\``);
+    if (request.request.cwd)
+        lines.push(`📁 目录: ${request.request.cwd}`);
+    if (request.request.agentId)
+        lines.push(`🤖 Agent: ${request.request.agentId}`);
+    lines.push("", `⏱️ 超时: ${expiresIn} 秒`);
+    return lines.join("\n");
+}
+function buildPluginApprovalText(request) {
+    const timeoutSec = Math.round((request.request.timeoutMs ?? 120_000) / 1000);
+    const severityIcon = request.request.severity === "critical" ? "🔴"
+        : request.request.severity === "info" ? "🔵"
+            : "🟡";
+    const lines = [`${severityIcon} 审批请求`, ""];
+    lines.push(`📋 ${request.request.title}`);
+    if (request.request.description)
+        lines.push(`📝 ${request.request.description}`);
+    if (request.request.toolName)
+        lines.push(`🔧 工具: ${request.request.toolName}`);
+    if (request.request.pluginId)
+        lines.push(`🔌 插件: ${request.request.pluginId}`);
+    if (request.request.agentId)
+        lines.push(`🤖 Agent: ${request.request.agentId}`);
+    lines.push("", `⏱️ 超时: ${timeoutSec} 秒`);
+    return lines.join("\n");
+}
+/**
+ * Inline Keyboard（内嵌回调型按钮）
+ * type=1(Callback)：点击触发 INTERACTION_CREATE，button_data = data 字段
+ * group_id 相同 → 点一个后其余变灰（三选一语义）
+ * click_limit=1 → 每人只能点一次
+ * permission.type=2 → 所有人可操作
+ */
+function buildApprovalKeyboard(approvalId) {
+    const makeBtn = (id, label, visitedLabel, data, style) => ({
+        id,
+        render_data: { label, visited_label: visitedLabel, style },
+        action: {
+            type: 1,
+            data,
+            permission: { type: 2 },
+            click_limit: 1,
+        },
+        group_id: "approval",
+    });
+    return {
+        content: {
+            rows: [
+                {
+                    buttons: [
+                        makeBtn("allow", "✅ 允许一次", "已允许", `approve:${approvalId}:allow-once`, 1),
+                        makeBtn("always", "⭐ 始终允许", "已始终允许", `approve:${approvalId}:allow-always`, 1),
+                        makeBtn("deny", "❌ 拒绝", "已拒绝", `approve:${approvalId}:deny`, 0),
+                    ],
+                },
+            ],
+        },
+    };
+}
+/** 从 sessionKey 或 turnSourceTo 提取投递目标 */
+function resolveTarget(sessionKey, turnSourceTo) {
+    // 优先从 sessionKey 解析（如 agent:main:qqbot:direct:OPENID）
+    const sk = sessionKey ?? turnSourceTo;
+    if (!sk)
+        return null;
+    const m = sk.match(/qqbot:(c2c|direct|group):([A-F0-9]+)/i);
+    if (!m)
+        return null;
+    const type = m[1].toLowerCase() === "group" ? "group" : "c2c";
+    return { type, id: m[2] };
+}
+// ─── Handler 类 ──────────────────────────────────────────────
+export class QQBotApprovalHandler {
+    gatewayClient = null;
+    pending = new Map();
+    requestCache = new Map();
+    opts;
+    started = false;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async start() {
+        if (this.started)
+            return;
+        this.started = true;
+        const { log } = this.opts;
+        log?.info(`[qqbot:${this.opts.accountId}] approval-handler: starting`);
+        // 动态加载 gateway-runtime（兼容旧版框架 / pnpm 环境）
+        let gatewayRuntime;
+        try {
+            gatewayRuntime = loadGatewayRuntime();
+        }
+        catch (err) {
+            log?.error(`[qqbot:${this.opts.accountId}] approval-handler: gateway-runtime module not available, approval feature disabled. Error: ${err}`);
+            this.started = false;
+            return;
+        }
+        try {
+            this.gatewayClient = await gatewayRuntime.createOperatorApprovalsGatewayClient({
+                config: this.opts.cfg,
+                gatewayUrl: this.opts.gatewayUrl,
+                clientDisplayName: "QQBot Approval Handler",
+                onEvent: (evt) => this.handleGatewayEvent(evt),
+                onHelloOk: () => log?.info(`[qqbot:${this.opts.accountId}] approval-handler: connected to gateway`),
+                onConnectError: (err) => log?.error(`[qqbot:${this.opts.accountId}] approval-handler: connect error: ${err.message}`),
+                onClose: (code, reason) => log?.debug?.(`[qqbot:${this.opts.accountId}] approval-handler: gateway closed: ${code} ${reason}`),
+            });
+            this.gatewayClient.start();
+            setApprovalFeatureAvailable(true);
+        }
+        catch (err) {
+            log?.error(`[qqbot:${this.opts.accountId}] approval-handler: failed to create gateway client: ${err}`);
+            this.started = false;
+        }
+    }
+    async stop() {
+        if (!this.started)
+            return;
+        this.started = false;
+        for (const entry of this.pending.values())
+            clearTimeout(entry.timeoutId);
+        this.pending.clear();
+        this.requestCache.clear();
+        this.gatewayClient?.stop();
+        this.gatewayClient = null;
+        this.opts.log?.info(`[qqbot:${this.opts.accountId}] approval-handler: stopped`);
+    }
+    /** 检查是否有指定 shortId 对应的 pending 审批 */
+    hasShortId(shortId) {
+        for (const id of this.pending.keys()) {
+            if (toShortId(id) === shortId)
+                return true;
+        }
+        return false;
+    }
+    /** 解析审批请求（供 Interaction 回调或 /approve 命令调用） */
+    async resolveApproval(approvalId, decision) {
+        if (!this.gatewayClient)
+            return false;
+        // 查找完整 ID：支持完整 ID（exec:uuid / plugin:uuid）、纯 UUID、或 shortId（8位）
+        let fullId = approvalId;
+        if (this.pending.has(approvalId)) {
+            fullId = approvalId;
+        }
+        else {
+            // 尝试在 pending keys 中匹配：纯 UUID 可能对应 exec:uuid 或 plugin:uuid
+            for (const id of this.pending.keys()) {
+                if (id === approvalId) {
+                    fullId = id;
+                    break;
+                }
+                // 纯 UUID 匹配：pending key 的 uuid 部分等于传入值
+                if (id.replace(/^(exec|plugin):/, "") === approvalId) {
+                    fullId = id;
+                    break;
+                }
+                // shortId 匹配
+                if (toShortId(id) === approvalId) {
+                    fullId = id;
+                    break;
+                }
+            }
+            // 也在 requestCache 中查找（handleResolved 可能已清除 pending）
+            if (fullId === approvalId && !this.requestCache.has(approvalId)) {
+                for (const id of this.requestCache.keys()) {
+                    if (id.replace(/^(exec|plugin):/, "") === approvalId) {
+                        fullId = id;
+                        break;
+                    }
+                }
+            }
+        }
+        const kind = resolveApprovalKind(fullId);
+        const method = kind === "plugin" ? "plugin.approval.resolve" : "exec.approval.resolve";
+        const isPending = this.pending.has(fullId);
+        const isCached = this.requestCache.has(fullId);
+        this.opts.log?.info(`[qqbot:${this.opts.accountId}] approval-handler: resolving ${fullId} (input=${approvalId}) kind=${kind} → ${decision}, pending=${isPending}, cached=${isCached}`);
+        try {
+            await this.gatewayClient.request(method, { id: fullId, decision });
+            this.opts.log?.info(`[qqbot:${this.opts.accountId}] approval-handler: RPC success ${toShortId(fullId)} → ${decision} (method=${method})`);
+            return true;
+        }
+        catch (err) {
+            this.opts.log?.error(`[qqbot:${this.opts.accountId}] approval-handler: resolve failed: ${err}`);
+            return false;
+        }
+    }
+    handleGatewayEvent(evt) {
+        if (evt.event === "exec.approval.requested") {
+            void this.handleRequested(evt.payload, "exec");
+        }
+        else if (evt.event === "plugin.approval.requested") {
+            void this.handleRequested(evt.payload, "plugin");
+        }
+        else if (evt.event === "exec.approval.resolved") {
+            void this.handleResolved(evt.payload);
+        }
+        else if (evt.event === "plugin.approval.resolved") {
+            void this.handleResolved(evt.payload);
+        }
+    }
+    async handleRequested(request, kind) {
+        const { log, appId, clientSecret, accountId } = this.opts;
+        const shortId = toShortId(request.id);
+        // 只处理本账号的请求
+        const reqAccountId = request.request.turnSourceAccountId?.trim();
+        if (reqAccountId && reqAccountId !== accountId)
+            return;
+        // 解析投递目标
+        const sessionKey = request.request.sessionKey;
+        const turnSourceTo = request.request.turnSourceTo;
+        const target = resolveTarget(sessionKey, turnSourceTo);
+        if (!target) {
+            log?.info(`[qqbot:${accountId}] approval-handler: no QQ target for ${shortId} (session=${sessionKey})`);
+            return;
+        }
+        // 缓存请求
+        this.requestCache.set(request.id, kind === "plugin"
+            ? { kind: "plugin", request: request }
+            : { kind: "exec", request: request });
+        log?.info(`[qqbot:${accountId}] approval-handler: sending ${kind} approval ${shortId} to ${target.type}:${target.id}`);
+        const text = kind === "plugin"
+            ? buildPluginApprovalText(request)
+            : buildExecApprovalText(request);
+        const keyboard = buildApprovalKeyboard(request.id);
+        const timeoutMs = kind === "plugin"
+            ? (request.request.timeoutMs ?? 120_000)
+            : Math.max(0, request.expiresAtMs - Date.now());
+        // 短暂延迟，确保框架侧 waitDecision 已就绪，避免时序竞争
+        await new Promise((r) => setTimeout(r, 2000));
+        try {
+            const token = await getAccessToken(appId, clientSecret);
+            if (target.type === "c2c") {
+                await sendC2CMessageWithInlineKeyboard(token, target.id, text, keyboard);
+            }
+            else {
+                await sendGroupMessageWithInlineKeyboard(token, target.id, text, keyboard);
+            }
+            log?.info(`[qqbot:${accountId}] approval-handler: sent ${kind} approval ${shortId}`);
+            const timeoutId = setTimeout(() => {
+                this.handleTimeout(request.id, target);
+            }, timeoutMs + 2_000);
+            this.pending.set(request.id, { targets: [target], timeoutId });
+        }
+        catch (err) {
+            this.requestCache.delete(request.id);
+            log?.error(`[qqbot:${accountId}] approval-handler: failed to send approval ${shortId}: ${err}`);
+        }
+    }
+    async handleResolved(resolved) {
+        const entry = this.pending.get(resolved.id);
+        const resolvedBy = resolved.resolvedBy ?? "unknown";
+        const kind = resolveApprovalKind(resolved.id);
+        this.opts.log?.info(`[qqbot:${this.opts.accountId}] approval-handler: gateway confirmed ${toShortId(resolved.id)} → ${resolved.decision} (kind=${kind}, resolvedBy=${resolvedBy}, wasPending=${!!entry})`);
+        if (!entry)
+            return;
+        clearTimeout(entry.timeoutId);
+        this.pending.delete(resolved.id);
+        this.requestCache.delete(resolved.id);
+        // 框架 Forwarder 负责发送 resolved 通知（已通过 buildResolvedPayload=null 抑制），此处不重复发送
+    }
+    async handleTimeout(approvalId, target) {
+        const { log, accountId } = this.opts;
+        if (!this.pending.has(approvalId))
+            return;
+        this.pending.delete(approvalId);
+        this.requestCache.delete(approvalId);
+        log?.info(`[qqbot:${accountId}] approval-handler: timeout ${toShortId(approvalId)}`);
+        // 超时由框架处理，此处仅清理状态，不重复发消息
+    }
+}
+// ─── 模块级 handler 注册 ────────────────────────────────────
+const _handlers = new Map();
+/** 审批功能是否可用（gateway-runtime 模块加载成功则为 true） */
+let _approvalFeatureAvailable = false;
+export function isApprovalFeatureAvailable() {
+    return _approvalFeatureAvailable;
+}
+export function setApprovalFeatureAvailable(available) {
+    _approvalFeatureAvailable = available;
+}
+export function registerApprovalHandler(accountId, handler) {
+    _handlers.set(accountId, handler);
+}
+export function unregisterApprovalHandler(accountId) {
+    _handlers.delete(accountId);
+}
+export function getApprovalHandler(accountId) {
+    return _handlers.get(accountId);
+}
+export function findApprovalHandlerForShortId(shortId) {
+    for (const handler of _handlers.values()) {
+        if (handler.hasShortId(shortId))
+            return handler;
+    }
+    return undefined;
+}