@tencent-connect/openclaw-qqbot 1.7.0 → 1.7.1

package/dist/src/channel.js

@@ -6,6 +6,24 @@ import { qqbotOnboardingAdapter } from "./onboarding.js";
 import { getQQBotRuntime } from "./runtime.js";
 import { saveCredentialBackup, loadCredentialBackup } from "./credential-backup.js";
 import { initApiConfig } from "./api.js";
+import { getApprovalHandler } from "./approval-handler.js";
+/** 检查 payload 是否为审批消息（与 getExecApprovalReplyMetadata 等效，内联避免版本兼容问题） */
+function isApprovalPayload(payload) {
+    if (!payload || typeof payload !== "object")
+        return false;
+    const p = payload;
+    // channelData.execApproval 存在 → exec/plugin approval pending/resolved
+    const cd = p.channelData;
+    if (cd && typeof cd === "object" && !Array.isArray(cd)) {
+        const execApproval = cd.execApproval;
+        if (execApproval && typeof execApproval === "object" && !Array.isArray(execApproval)) {
+            return true;
+        }
+    }
+    // text 匹配兜底：框架渲染的审批纯文本通知
+    const text = typeof p.text === "string" ? p.text : "";
+    return /(?:Plugin|Exec) approval (?:required|allowed|denied|expired)/i.test(text);
+}
 /** QQ Bot 单条消息文本长度上限 */
 export const TEXT_CHUNK_LIMIT = 5000;
 /**
@@ -251,6 +269,9 @@ export const qqbotPlugin = {
         chunker: (text, limit) => getQQBotRuntime().channel.text.chunkMarkdownText(text, limit),
         chunkerMode: "markdown",
         textChunkLimit: 5000,
+        // 3.31+ outbound 路径：dispatch-from-config → shouldSuppressLocalExecApprovalPrompt → outbound.shouldSuppressLocalPayloadPrompt
+        shouldSuppressLocalPayloadPrompt: ({ accountId, payload }) => getApprovalHandler(accountId ?? "") != null &&
+            isApprovalPayload(payload),
         sendText: async ({ to, text, accountId, replyToId, cfg }) => {
             console.log(`[qqbot:channel] sendText called — accountId=${accountId}, to=${to}, replyToId=${replyToId}, text.length=${text?.length ?? 0}`);
             console.log(`[qqbot:channel] sendText text preview: ${text?.slice(0, 100)}${(text?.length ?? 0) > 100 ? "..." : ""}`);
@@ -412,6 +433,57 @@ export const qqbotPlugin = {
             lastOutboundAt: runtime?.lastOutboundAt ?? null,
         }),
     },
+    // QQBot approval-handler 通过独立 WS 连接自行处理 exec + plugin 审批消息投递（带 Inline Keyboard），
+    // 完全屏蔽框架 Forwarder 的纯文本通知。
+    //
+    // ── 3.28 扁平结构 ──
+    execApprovals: {
+        // 3.28 框架通过此方法判断 channel 是否支持审批
+        getInitiatingSurfaceState: ({ accountId }) => {
+            return getApprovalHandler(accountId ?? "") != null
+                ? { kind: "enabled" }
+                : { kind: "disabled" };
+        },
+        shouldSuppressForwardingFallback: (...args) => {
+            console.log("[QQBot] shouldSuppressForwardingFallback called", JSON.stringify(args?.[0]?.target ?? null));
+            return true;
+        },
+        shouldSuppressLocalPrompt: ({ accountId, payload }) => getApprovalHandler(accountId ?? "") != null &&
+            isApprovalPayload(payload),
+        buildPendingPayload: () => null,
+        buildResolvedPayload: () => null,
+    },
+    // ── 3.31+ 嵌套结构 ──
+    // auth 和 approvals 是 ChannelPlugin 顶层平级字段
+    //
+    // QQBot 审批模型：
+    //   - QQBotApprovalHandler 通过独立 WS 自行投递带 Inline Keyboard 的审批消息
+    //   - 用户点击按钮 → INTERACTION_CREATE → resolveApproval → gateway RPC
+    //   - /approve 文本命令作为 URGENT_COMMAND 直接入队交给框架处理
+    auth: {
+        authorizeActorAction: () => ({ authorized: true }),
+        getActionAvailabilityState: ({ accountId }) => {
+            return getApprovalHandler(accountId ?? "") != null
+                ? { kind: "enabled" }
+                : { kind: "disabled" };
+        },
+    },
+    approvals: {
+        delivery: {
+            hasConfiguredDmRoute: () => true,
+            shouldSuppressForwardingFallback: () => true,
+        },
+        render: {
+            exec: {
+                buildPendingPayload: () => null,
+                buildResolvedPayload: () => null,
+            },
+            plugin: {
+                buildPendingPayload: () => null,
+                buildResolvedPayload: () => null,
+            },
+        },
+    },
 };
 // ============ 独立的 mention 工具函数（供 gateway.ts 等直接调用） ============
 /** 清理 @mention：替换 <@openid> 为 @用户名，去除 @机器人自身 */

package/dist/src/gateway.js

@@ -8,6 +8,7 @@ import { recordKnownUser, flushKnownUsers } from "./known-users.js";
 import { getQQBotRuntime } from "./runtime.js";
 import { isGroupAllowed, resolveGroupName, resolveGroupPrompt, resolveHistoryLimit, resolveGroupPolicy, resolveGroupConfig, resolveIgnoreOtherMentions, resolveMentionPatterns } from "./config.js";
 import { qqbotPlugin, stripMentionText, detectWasMentioned } from "./channel.js";
+import { QQBotApprovalHandler, registerApprovalHandler, unregisterApprovalHandler, getApprovalHandler } from "./approval-handler.js";
 import { recordPendingHistoryEntry, buildPendingHistoryContext, buildMergedMessageContext, clearPendingHistory, formatAttachmentTags, formatMessageContent, toAttachmentSummaries, } from "./group-history.js";
 import { setRefIndex, getRefIndex, formatRefEntryForAgent, formatMessageReferenceForAgent, flushRefIndex } from "./ref-index-store.js";
 import { matchSlashCommand, getFrameworkVersion, parseFrameworkDateVersion } from "./slash-commands.js";
@@ -135,9 +136,27 @@ async function handleInteractionCreate(params) {
         log?.info(`[qqbot:${account.accountId}] Interaction ACK (type=${INTERACTION_TYPE_CONFIG_UPDATE}) sent: ${event.id}, claw_cfg=${JSON.stringify(ackClawCfg)}`);
     }
     else {
-        // 其他类型：普通 ACK
+        // 普通按钮交互：先 ACK
         await acknowledgeInteraction(token, event.id);
         log?.debug?.(`[qqbot:${account.accountId}] Interaction ACK sent: ${event.id}`);
+        // Inline Keyboard 审批按钮（type=1 Callback）
+        // button_data 格式：approve:<approvalId>:<decision>
+        // approvalId 可能是 "exec:uuid" / "plugin:uuid"（带前缀）或纯 "uuid"（无前缀）
+        const buttonData = event.data?.resolved?.button_data ?? "";
+        const m = buttonData.match(/^approve:((?:(?:exec|plugin):)?[0-9a-f-]+):(allow-once|allow-always|deny)$/i);
+        if (m) {
+            const approvalId = m[1];
+            const decision = m[2];
+            const userId = event.group_member_openid || event.user_openid || event.data?.resolved?.user_id || "unknown";
+            log?.info(`[qqbot:${account.accountId}] Approval button clicked: approvalId=${approvalId}, decision=${decision}, user=${userId}, buttonData=${buttonData}`);
+            const handler = getApprovalHandler(account.accountId);
+            if (handler) {
+                void handler.resolveApproval(approvalId, decision);
+            }
+            else {
+                log?.error(`[qqbot:${account.accountId}] Approval button: no handler found for accountId=${account.accountId}`);
+            }
+        }
     }
 }
 /** 解析 session store 文件路径 */
@@ -425,6 +444,16 @@ export async function startGateway(ctx) {
         lastSeq = savedSession.lastSeq;
         log?.info(`[qqbot:${account.accountId}] Restored session from storage: sessionId=${sessionId}, lastSeq=${lastSeq}`);
     }
+    // ============ 审批 Handler ============
+    const approvalHandler = new QQBotApprovalHandler({
+        accountId: account.accountId,
+        appId: account.appId,
+        clientSecret: account.clientSecret,
+        cfg: cfg,
+        log,
+    });
+    registerApprovalHandler(account.accountId, approvalHandler);
+    void approvalHandler.start();
     // ============ 消息队列（复用 createMessageQueue，内置群消息合并/淘汰策略） ============
     const msgQueue = createMessageQueue({
         accountId: account.accountId,
@@ -433,7 +462,9 @@ export async function startGateway(ctx) {
     });
     // 斜杠指令拦截：在入队前匹配插件级指令，命中则直接回复，不入队
     // 紧急命令列表：这些命令会立即执行，不进入斜杠匹配流程
-    const URGENT_COMMANDS = ["/stop"];
+    // /stop   — 停止当前 agent run，清空队列
+    // /approve — 审批决策，必须在 agent 等待审批时立即执行，否则死锁
+    const URGENT_COMMANDS = ["/stop", "/approve"];
     const trySlashCommandOrEnqueue = async (msg) => {
         const content = (msg.content ?? "").trim();
         if (!content.startsWith("/")) {
@@ -478,6 +509,15 @@ export async function startGateway(ctx) {
                 msgQueue.enqueue(msg);
                 return;
             }
+            // 委托给 AI 模型：用加工后的 prompt 替换原始消息入队
+            const isDelegateResult = typeof reply === "object" && reply !== null && "delegatePrompt" in reply;
+            if (isDelegateResult) {
+                const delegatePrompt = reply.delegatePrompt;
+                log?.info(`[qqbot:${account.accountId}] Slash command delegated to AI: ${content.slice(0, 40)}`);
+                msg.content = delegatePrompt;
+                msgQueue.enqueue(msg);
+                return;
+            }
             // 命中插件级指令，直接回复
             log?.info(`[qqbot:${account.accountId}] Slash command matched: ${content}, replying directly`);
             const token = await getAccessToken(account.appId, account.clientSecret);
@@ -537,6 +577,9 @@ export async function startGateway(ctx) {
         flushKnownUsers();
         // P1-4: 保存引用索引数据
         flushRefIndex();
+        // 停止审批 handler
+        void approvalHandler.stop();
+        unregisterApprovalHandler(account.accountId);
     });
     const cleanup = () => {
         if (heartbeatInterval) {

package/dist/src/slash-commands.d.ts

@@ -59,14 +59,19 @@ export interface QueueSnapshot {
     /** 当前发送者在队列中的待处理消息数 */
     senderPending: number;
 }
-/** 斜杠指令返回值：文本、带文件的结果、或 null（不处理） */
-export type SlashCommandResult = string | SlashCommandFileResult | null;
+/** 斜杠指令返回值：文本、带文件的结果、委托给模型、或 null（不处理） */
+export type SlashCommandResult = string | SlashCommandFileResult | SlashCommandDelegateResult | null;
 /** 带文件的指令结果（先回复文本，再发送文件） */
 export interface SlashCommandFileResult {
     text: string;
     /** 要发送的本地文件路径 */
     filePath: string;
 }
+/** 委托给 AI 模型处理：用加工后的 prompt 替换原始消息入队 */
+export interface SlashCommandDelegateResult {
+    /** 替换原始消息内容的 prompt，交给 AI 模型执行 */
+    delegatePrompt: string;
+}
 /**
  * 尝试匹配并执行插件级斜杠指令
  *

package/dist/src/slash-commands.js

@@ -20,6 +20,7 @@ import { saveCredentialBackup } from "./credential-backup.js";
 import { fileURLToPath } from "node:url";
 import { getPackageVersion } from "./utils/pkg-version.js";
 import { getQQBotRuntime } from "./runtime.js";
+import { isApprovalFeatureAvailable } from "./approval-handler.js";
 const require = createRequire(import.meta.url);
 let PLUGIN_VERSION = getPackageVersion(import.meta.url);
 // 获取 openclaw 框架版本（不缓存，每次实时获取）
@@ -1848,6 +1849,240 @@ registerCommand({
         }
     },
 });
+// ============ /bot-approve 审批配置管理 ============
+/**
+ * /bot-approve — 管理命令执行审批配置
+ *
+ * 修改 openclaw.json 中 tools.exec.security / tools.exec.ask 字段。
+ *
+ * security: deny | allowlist | full
+ * ask: off | on-miss | always
+ */
+registerCommand({
+    name: "bot-approve",
+    description: "管理命令执行审批配置",
+    usage: [
+        `/bot-approve            查看操作指引`,
+        `/bot-approve on         开启审批（白名单模式，推荐）`,
+        `/bot-approve off        关闭审批，命令直接执行`,
+        `/bot-approve always     始终审批，每次执行都需审批`,
+        `/bot-approve reset      恢复框架默认值`,
+        `/bot-approve status     查看当前审批配置`,
+    ].join("\n"),
+    handler: async (ctx) => {
+        const arg = ctx.args.trim().toLowerCase();
+        // 审批功能需要 openclaw >= 3.22（gateway-runtime 模块）
+        if (!isApprovalFeatureAvailable()) {
+            return `❌ 当前 OpenClaw 版本不支持审批功能，请升级至最新版本后重试。`;
+        }
+        let runtime;
+        try {
+            runtime = getQQBotRuntime();
+        }
+        catch {
+            // runtime 不可用，构造 prompt 委托给 AI 模型通过 CLI 完成
+            const presetMap = {
+                on: { security: "allowlist", ask: "on-miss", desc: "开启审批（白名单模式）" },
+                off: { security: "full", ask: "off", desc: "关闭审批" },
+                always: { security: "allowlist", ask: "always", desc: "严格模式（每次都审批）" },
+                strict: { security: "allowlist", ask: "always", desc: "严格模式（每次都审批）" },
+            };
+            const preset = presetMap[arg];
+            if (preset) {
+                return {
+                    delegatePrompt: [
+                        `请帮我${preset.desc}。执行以下单条命令（不要拆开）：`,
+                        `openclaw config set tools.exec.security ${preset.security} && openclaw config set tools.exec.ask ${preset.ask}`,
+                        `执行完成后告诉用户审批配置已更新为 security=${preset.security}, ask=${preset.ask}。`,
+                    ].join("\n"),
+                };
+            }
+            if (arg === "reset") {
+                return {
+                    delegatePrompt: [
+                        `请帮我重置审批配置。执行以下单条命令（不要拆开）：`,
+                        `openclaw config unset tools.exec.security && openclaw config unset tools.exec.ask`,
+                        `执行完成后告诉用户审批配置已重置为框架默认值。`,
+                    ].join("\n"),
+                };
+            }
+            if (arg === "status") {
+                return {
+                    delegatePrompt: [
+                        `请帮我查看当前命令执行审批配置。执行以下单条命令（不要拆开）：`,
+                        `echo "security=$(openclaw config get tools.exec.security)" && echo "ask=$(openclaw config get tools.exec.ask)"`,
+                        `然后告诉用户当前 security 和 ask 的值，以及可用的操作选项：`,
+                        `- /bot-approve on    开启审批（白名单模式）`,
+                        `- /bot-approve off   关闭审批`,
+                        `- /bot-approve always 严格模式`,
+                        `- /bot-approve reset 恢复默认`,
+                    ].join("\n"),
+                };
+            }
+            // 无参数或未知参数：直接返回操作指引
+            return [
+                `🔐 命令执行审批配置`,
+                ``,
+                `<qqbot-cmd-input text="/bot-approve on" show="/bot-approve on"/> 开启审批（白名单模式）`,
+                `<qqbot-cmd-input text="/bot-approve off" show="/bot-approve off"/> 关闭审批`,
+                `<qqbot-cmd-input text="/bot-approve always" show="/bot-approve always"/> 严格模式`,
+                `<qqbot-cmd-input text="/bot-approve reset" show="/bot-approve reset"/> 恢复默认`,
+                `<qqbot-cmd-input text="/bot-approve status" show="/bot-approve status"/> 查看当前配置`,
+            ].join("\n");
+        }
+        const configApi = runtime.config;
+        const loadExecConfig = () => {
+            const cfg = configApi.loadConfig();
+            const tools = (cfg.tools ?? {});
+            const exec = (tools.exec ?? {});
+            return {
+                security: String(exec.security ?? "deny"),
+                ask: String(exec.ask ?? "on-miss"),
+            };
+        };
+        const writeExecConfig = async (security, ask) => {
+            const cfg = structuredClone(configApi.loadConfig());
+            const tools = (cfg.tools ?? {});
+            const exec = (tools.exec ?? {});
+            exec.security = security;
+            exec.ask = ask;
+            tools.exec = exec;
+            cfg.tools = tools;
+            await configApi.writeConfigFile(cfg);
+        };
+        const formatStatus = (security, ask) => {
+            const secIcon = security === "full" ? "🟢" : security === "allowlist" ? "🟡" : "🔴";
+            const askIcon = ask === "off" ? "🟢" : ask === "always" ? "🔴" : "🟡";
+            return [
+                `🔐 当前审批配置`,
+                ``,
+                `${secIcon} 安全模式 (security): **${security}**`,
+                `${askIcon} 审批模式 (ask): **${ask}**`,
+                ``,
+                security === "deny" ? `⚠️ 当前为 deny 模式，所有命令执行被拒绝` :
+                    security === "full" && ask === "off" ? `✅ 所有命令无需审批直接执行` :
+                        security === "allowlist" && ask === "on-miss" ? `🛡️ 白名单命令直接执行，其余需审批` :
+                            ask === "always" ? `🔒 每次命令执行都需要人工审批` :
+                                `ℹ️ security=${security}, ask=${ask}`,
+            ].join("\n");
+        };
+        // 无参数：操作指引
+        if (!arg) {
+            return [
+                `🔐 命令执行审批配置`,
+                ``,
+                `<qqbot-cmd-input text="/bot-approve on" show="/bot-approve on"/> 开启审批（白名单模式）`,
+                `<qqbot-cmd-input text="/bot-approve off" show="/bot-approve off"/> 关闭审批`,
+                `<qqbot-cmd-input text="/bot-approve always" show="/bot-approve always"/> 严格模式`,
+                `<qqbot-cmd-input text="/bot-approve reset" show="/bot-approve reset"/> 恢复默认`,
+                `<qqbot-cmd-input text="/bot-approve status" show="/bot-approve status"/> 查看当前配置`,
+            ].join("\n");
+        }
+        // status: 查看当前配置
+        if (arg === "status") {
+            const { security, ask } = loadExecConfig();
+            return [
+                formatStatus(security, ask),
+                ``,
+                `<qqbot-cmd-input text="/bot-approve on" show="/bot-approve on"/> 开启审批`,
+                `<qqbot-cmd-input text="/bot-approve off" show="/bot-approve off"/> 关闭审批`,
+                `<qqbot-cmd-input text="/bot-approve always" show="/bot-approve always"/> 严格模式`,
+                `<qqbot-cmd-input text="/bot-approve reset" show="/bot-approve reset"/> 恢复默认`,
+            ].join("\n");
+        }
+        // on: 开启审批（白名单 + 未命中审批）
+        if (arg === "on") {
+            try {
+                await writeExecConfig("allowlist", "on-miss");
+                return [
+                    `✅ 审批已开启`,
+                    ``,
+                    `• security = allowlist（白名单模式）`,
+                    `• ask = on-miss（未命中白名单时需审批）`,
+                    ``,
+                    `已批准的命令自动加入白名单，下次直接执行。`,
+                ].join("\n");
+            }
+            catch (err) {
+                return `❌ 配置更新失败: ${err}`;
+            }
+        }
+        // off: 关闭审批
+        if (arg === "off") {
+            try {
+                await writeExecConfig("full", "off");
+                return [
+                    `✅ 审批已关闭`,
+                    ``,
+                    `• security = full（允许所有命令）`,
+                    `• ask = off（不需要审批）`,
+                    ``,
+                    `⚠️ 所有命令将直接执行，不会弹出审批确认。`,
+                ].join("\n");
+            }
+            catch (err) {
+                return `❌ 配置更新失败: ${err}`;
+            }
+        }
+        // always: 始终审批（每次都审批）
+        if (arg === "always") {
+            try {
+                await writeExecConfig("allowlist", "always");
+                return [
+                    `✅ 已切换为严格审批模式`,
+                    ``,
+                    `• security = allowlist`,
+                    `• ask = always（每次执行都需审批）`,
+                    ``,
+                    `每个命令都会弹出审批按钮，需手动确认。`,
+                ].join("\n");
+            }
+            catch (err) {
+                return `❌ 配置更新失败: ${err}`;
+            }
+        }
+        // reset: 删除配置，恢复框架默认值
+        if (arg === "reset") {
+            try {
+                const cfg = structuredClone(configApi.loadConfig());
+                const tools = (cfg.tools ?? {});
+                const exec = (tools.exec ?? {});
+                delete exec.security;
+                delete exec.ask;
+                if (Object.keys(exec).length === 0) {
+                    delete tools.exec;
+                }
+                else {
+                    tools.exec = exec;
+                }
+                if (Object.keys(tools).length === 0) {
+                    delete cfg.tools;
+                }
+                else {
+                    cfg.tools = tools;
+                }
+                await configApi.writeConfigFile(cfg);
+                return [
+                    `✅ 审批配置已重置`,
+                    ``,
+                    `已移除 tools.exec.security 和 tools.exec.ask`,
+                    `框架将使用默认值（security=deny, ask=on-miss）`,
+                    ``,
+                    `如需开启命令执行，请使用 /bot-approve on`,
+                ].join("\n");
+            }
+            catch (err) {
+                return `❌ 配置更新失败: ${err}`;
+            }
+        }
+        return [
+            `❌ 未知参数: ${arg}`,
+            ``,
+            `可用选项: on | off | always | reset`,
+            `输入 /bot-approve ? 查看详细用法`,
+        ].join("\n");
+    },
+});
 // ============ 匹配入口 ============
 /**
  * 尝试匹配并执行插件级斜杠指令

package/dist/src/types.d.ts

@@ -323,6 +323,72 @@ export interface InteractionEvent {
         };
     };
 }
+/**
+ * 按钮 Action 类型
+ * 0=跳转链接  1=回调型(INTERACTION_CREATE)  2=指令型(直接发文本)  3=mqqapi
+ */
+export type KeyboardActionType = 0 | 1 | 2 | 3;
+/** 按钮权限 */
+export interface KeyboardPermission {
+    /** 0=全体  1=管理员  2=按钮指定  3=身份组 */
+    type: 0 | 1 | 2 | 3;
+    specify_role_ids?: string[];
+    specify_user_ids?: string[];
+}
+/** 二次确认弹窗 */
+export interface KeyboardModal {
+    content: string;
+    confirm_text?: string;
+    cancel_text?: string;
+}
+/** 按钮 Action */
+export interface KeyboardAction {
+    type: KeyboardActionType;
+    data?: string;
+    /** true = 点击后直接发出（Enter）*/
+    enter?: boolean;
+    /** 仅指令型（type=2）：是否把指令发到输入框（reply=true）还是静默发出 */
+    reply?: boolean;
+    permission?: KeyboardPermission;
+    click_limit?: number;
+    unsupport_tips?: string;
+    modal?: KeyboardModal;
+}
+/** 按钮渲染数据 */
+export interface KeyboardRenderData {
+    label: string;
+    visited_label?: string;
+    /** 0=灰色线框  1=蓝色线框  2=推荐回复专用  3=红色字体  4=蓝色背景 */
+    style?: 0 | 1 | 2 | 3 | 4;
+}
+/** 单个按钮 */
+export interface KeyboardButton {
+    id: string;
+    render_data?: KeyboardRenderData;
+    action?: KeyboardAction;
+    group_id?: string;
+}
+/** 一行按钮 */
+export interface KeyboardRow {
+    buttons: KeyboardButton[];
+}
+/** CustomKeyboard（自定义按钮内容） */
+export interface CustomKeyboard {
+    rows: KeyboardRow[];
+}
+/** MessageKeyboard（keyboard / prompt_keyboard.keyboard 共用） */
+export interface MessageKeyboard {
+    /** 模板 ID（与 content 二选一） */
+    id?: string;
+    /** 自定义内容 */
+    content?: CustomKeyboard;
+}
+/**
+ * Inline Keyboard（消息内嵌按钮，需平台审核）
+ * 发送字段：keyboard
+ * JSON: { "keyboard": { "id": "...", "content": { "rows": [...] } } }
+ */
+export type InlineKeyboard = MessageKeyboard;
 /**
  * WebSocket 事件负载
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencent-connect/openclaw-qqbot",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "publishConfig": {
     "access": "public"
   },

package/src/api.ts

@@ -639,7 +639,8 @@ function buildMessageBody(
   content: string,
   msgId: string | undefined,
   msgSeq: number,
-  messageReference?: string
+  messageReference?: string,
+  inlineKeyboard?: import("./types.js").InlineKeyboard
 ): Record<string, unknown> {
   const body: Record<string, unknown> = currentMarkdownSupport
     ? {
@@ -659,6 +660,10 @@ function buildMessageBody(
   if (messageReference && !currentMarkdownSupport) {
     body.message_reference = { message_id: messageReference };
   }
+  // Inline Keyboard（内嵌按钮，需审核）：字段名 keyboard，结构 { content: { rows } }
+  if (inlineKeyboard) {
+    body.keyboard = inlineKeyboard;
+  }
   return body;
 }
 
@@ -735,6 +740,32 @@ export async function sendGroupMessage(
   return sendAndNotify(accessToken, "POST", `/v2/groups/${groupOpenid}/messages`, body, { text: content });
 }
 
+/** 发送带 Inline Keyboard 的 C2C 消息（回调型按钮，触发 INTERACTION_CREATE） */
+export async function sendC2CMessageWithInlineKeyboard(
+  accessToken: string,
+  openid: string,
+  content: string,
+  inlineKeyboard: import("./types.js").InlineKeyboard,
+  msgId?: string,
+): Promise<MessageResponse> {
+  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: string,
+  groupOpenid: string,
+  content: string,
+  inlineKeyboard: import("./types.js").InlineKeyboard,
+  msgId?: string,
+): Promise<MessageResponse> {
+  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: string): Record<string, unknown> {
   if (!content || content.trim().length === 0) {
     throw new Error("主动消息内容不能为空 (markdown.content is empty)");