@tencent-connect/openclaw-qqbot 1.7.0 → 1.7.1

package/src/gateway.ts

@@ -9,6 +9,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,
@@ -21,7 +22,7 @@ import {
 } from "./group-history.js";
 
 import { setRefIndex, getRefIndex, formatRefEntryForAgent, formatMessageReferenceForAgent, flushRefIndex, type RefAttachmentSummary } from "./ref-index-store.js";
-import { matchSlashCommand, getFrameworkVersion, parseFrameworkDateVersion, type SlashCommandContext, type SlashCommandFileResult } from "./slash-commands.js";
+import { matchSlashCommand, getFrameworkVersion, parseFrameworkDateVersion, type SlashCommandContext, type SlashCommandFileResult, type SlashCommandDelegateResult } from "./slash-commands.js";
 import { createMessageQueue, type QueuedMessage } from "./message-queue.js";
 import { triggerUpdateCheck } from "./update-checker.js";
 import { startImageServer, isImageServerRunning, type ImageServerConfig } from "./image-server.js";
@@ -174,9 +175,27 @@ async function handleInteractionCreate(params: {
     await acknowledgeInteraction(token, event.id, 0, { claw_cfg: ackClawCfg });
     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] as "allow-once" | "allow-always" | "deny";
+      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}`);
+      }
+    }
   }
 }
 
@@ -517,6 +536,17 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
     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 as any,
+    log,
+  });
+  registerApprovalHandler(account.accountId, approvalHandler);
+  void approvalHandler.start();
+
   // ============ 消息队列（复用 createMessageQueue，内置群消息合并/淘汰策略） ============
   const msgQueue = createMessageQueue({
     accountId: account.accountId,
@@ -526,7 +556,9 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
 
   // 斜杠指令拦截：在入队前匹配插件级指令，命中则直接回复，不入队
   // 紧急命令列表：这些命令会立即执行，不进入斜杠匹配流程
-  const URGENT_COMMANDS = ["/stop"];
+  // /stop   — 停止当前 agent run，清空队列
+  // /approve — 审批决策，必须在 agent 等待审批时立即执行，否则死锁
+  const URGENT_COMMANDS = ["/stop", "/approve"];
 
   const trySlashCommandOrEnqueue = async (msg: QueuedMessage): Promise<void> => {
     const content = (msg.content ?? "").trim();
@@ -577,6 +609,16 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
         return;
       }
 
+      // 委托给 AI 模型：用加工后的 prompt 替换原始消息入队
+      const isDelegateResult = typeof reply === "object" && reply !== null && "delegatePrompt" in reply;
+      if (isDelegateResult) {
+        const delegatePrompt = (reply as SlashCommandDelegateResult).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);
@@ -635,6 +677,9 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
     flushKnownUsers();
     // P1-4: 保存引用索引数据
     flushRefIndex();
+    // 停止审批 handler
+    void approvalHandler.stop();
+    unregisterApprovalHandler(account.accountId);
   });
 
   const cleanup = () => {
@@ -1457,7 +1502,6 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
             });
           }
 
-
           const dispatchPromise = pluginRuntime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
             ctx: ctxPayload,
             cfg,

package/src/openclaw-plugin-sdk.d.ts

@@ -369,19 +369,34 @@ declare module "openclaw/plugin-sdk" {
   /** 群消息策略适配器（resolveRequireMention / resolveToolPolicy / resolveGroupIntroHint） */
   export interface ChannelGroupAdapter {
     /** 是否需要 @机器人才响应 */
-    resolveRequireMention?: (ctx: { cfg: OpenClawConfig; accountId?: string; groupId: string }) => boolean;
+    resolveRequireMention?: (ctx: { cfg: OpenClawConfig; accountId?: string; groupId: string }) => boolean | undefined;
     /** 群聊 AI 工具使用范围 */
-    resolveToolPolicy?: (ctx: { cfg: OpenClawConfig; accountId?: string; groupId: string; senderId?: string }) => "full" | "restricted" | "none";
+    resolveToolPolicy?: (
+      ctx: { cfg: OpenClawConfig; accountId?: string; groupId: string; senderId?: string }
+    ) =>
+      | "full"
+      | "restricted"
+      | "none"
+      | GroupToolPolicyConfig
+      | undefined;
     /** 平台特有的群聊行为提示 */
     resolveGroupIntroHint?: (ctx: { cfg: OpenClawConfig; accountId?: string; groupId: string }) => string | undefined;
     /** 其他适配器方法 */
     [key: string]: unknown;
   }
 
+  /** 工具策略配置（用于把 none/restricted/full 映射为 allow/deny） */
+  export type GroupToolPolicyConfig = {
+    allow: string[];
+    deny?: string[];
+  };
+
   /** @mention 检测与清理适配器（stripMentionText / detectWasMentioned） */
   export interface ChannelMentionAdapter {
     /** 清理 @mention 文本：平台格式→可读格式，去除 @机器人自身 */
     stripMentionText?: (text: string, mentions?: Array<{ member_openid?: string; nickname?: string; is_you?: boolean }>) => string;
+    /** stripMentions：框架回调型（一次性拿到 text + ctx） */
+    stripMentions?: (params: { text: string; ctx: unknown }) => string;
     /** 检测当前消息是否 @了机器人 */
     detectWasMentioned?: (ctx: {
       eventType?: string;
@@ -393,6 +408,14 @@ declare module "openclaw/plugin-sdk" {
     [key: string]: unknown;
   }
 
+  /** 状态摘要构建（仅覆盖当前项目用到的字段） */
+  export interface ChannelPluginStatus {
+    defaultRuntime: Record<string, unknown>;
+    buildChannelSummary?: (ctx: { snapshot: any }) => Record<string, unknown>;
+    buildAccountSnapshot?: (ctx: { account: any; runtime: any }) => Record<string, unknown>;
+    [key: string]: unknown;
+  }
+
   /**
    * 频道插件接口（泛型）
    */
@@ -423,6 +446,8 @@ declare module "openclaw/plugin-sdk" {
     groups?: ChannelGroupAdapter;
     /** @mention 检测与清理适配器 */
     mentions?: ChannelMentionAdapter;
+    /** 状态摘要构建（可选） */
+    status?: ChannelPluginStatus;
     /** 启动函数 */
     start?: (runtime: PluginRuntime) => void | Promise<void>;
     /** 停止函数 */
@@ -579,6 +604,54 @@ declare module "openclaw/plugin-sdk" {
     hasMatchInput?: boolean;
   }): MatchedGroupAccessDecision;
 
+  // ============ 审批运行时类型（minimal） ============
+  // 这些类型只覆盖本项目真实使用到的字段，
+  // 用来消除 strict/noImplicitAny 下的连锁报错。
+
+  export interface ExecApprovalRequest {
+    id: string;
+    expiresAtMs: number;
+    request: {
+      commandPreview?: string;
+      command?: string;
+      cwd?: string;
+      agentId?: string;
+      turnSourceAccountId?: string;
+      sessionKey?: string;
+      turnSourceTo?: string;
+      [key: string]: unknown;
+    };
+  }
+
+  export interface ExecApprovalResolved {
+    id: string;
+    decision: string;
+    [key: string]: unknown;
+  }
+
+  export interface PluginApprovalRequest {
+    id: string;
+    request: {
+      timeoutMs?: number;
+      severity?: "critical" | "info" | string;
+      title: string;
+      description?: string;
+      toolName?: string;
+      pluginId?: string;
+      agentId?: string;
+      turnSourceAccountId?: string;
+      sessionKey?: string;
+      turnSourceTo?: string;
+      [key: string]: unknown;
+    };
+  }
+
+  export interface PluginApprovalResolved {
+    id: string;
+    decision: string;
+    [key: string]: unknown;
+  }
+
   // ============ 其他导出 ============
 
   /** 默认账户 ID 常量 */
@@ -587,3 +660,55 @@ declare module "openclaw/plugin-sdk" {
   /** 规范化账户 ID */
   export function normalizeAccountId(accountId: string | undefined | null): string;
 }
+
+declare module "openclaw/plugin-sdk/approval-runtime" {
+  export interface ExecApprovalReplyMetadata {
+    approvalId: string;
+    approvalSlug: string;
+    allowedDecisions?: string[];
+  }
+  export type ExecApprovalRequest = import("openclaw/plugin-sdk").ExecApprovalRequest;
+  export type ExecApprovalResolved = import("openclaw/plugin-sdk").ExecApprovalResolved;
+  export type PluginApprovalRequest = import("openclaw/plugin-sdk").PluginApprovalRequest;
+  export type PluginApprovalResolved = import("openclaw/plugin-sdk").PluginApprovalResolved;
+  export function getExecApprovalReplyMetadata(payload: { channelData?: unknown }): ExecApprovalReplyMetadata | null;
+}
+
+declare module "openclaw/plugin-sdk/core" {
+  export type OpenClawConfig = import("openclaw/plugin-sdk").OpenClawConfig;
+  export type ChannelPlugin<TAccount = unknown> =
+    import("openclaw/plugin-sdk").ChannelPlugin<TAccount>;
+
+  export const applyAccountNameToChannelSection: typeof import("openclaw/plugin-sdk")
+    .applyAccountNameToChannelSection;
+  export const deleteAccountFromConfigSection: typeof import("openclaw/plugin-sdk")
+    .deleteAccountFromConfigSection;
+  export const setAccountEnabledInConfigSection: typeof import("openclaw/plugin-sdk")
+    .setAccountEnabledInConfigSection;
+
+  // 允许其它 core 导出被逐步补齐（避免引入大量严格类型时频繁改代码）
+  export * from "openclaw/plugin-sdk";
+}
+
+declare module "openclaw/plugin-sdk/gateway-runtime" {
+  export interface EventFrame {
+    event: string;
+    payload: unknown;
+  }
+
+  export interface GatewayClient {
+    start: () => void | Promise<void>;
+    stop: () => void | Promise<void>;
+    request: (method: string, params: unknown) => Promise<unknown>;
+  }
+
+  export function createOperatorApprovalsGatewayClient(options: {
+    config: import("openclaw/plugin-sdk").OpenClawConfig;
+    gatewayUrl?: string;
+    clientDisplayName?: string;
+    onEvent: (evt: EventFrame) => void;
+    onHelloOk?: () => void;
+    onConnectError?: (err: { message: string }) => void;
+    onClose?: (code: number, reason: string) => void;
+  }): Promise<GatewayClient>;
+}

package/src/slash-commands.ts

@@ -22,6 +22,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);
@@ -216,8 +217,8 @@ export interface QueueSnapshot {
   senderPending: number;
 }
 
-/** 斜杠指令返回值：文本、带文件的结果、或 null（不处理） */
-export type SlashCommandResult = string | SlashCommandFileResult | null;
+/** 斜杠指令返回值：文本、带文件的结果、委托给模型、或 null（不处理） */
+export type SlashCommandResult = string | SlashCommandFileResult | SlashCommandDelegateResult | null;
 
 /** 带文件的指令结果（先回复文本，再发送文件） */
 export interface SlashCommandFileResult {
@@ -226,6 +227,12 @@ export interface SlashCommandFileResult {
   filePath: string;
 }
 
+/** 委托给 AI 模型处理：用加工后的 prompt 替换原始消息入队 */
+export interface SlashCommandDelegateResult {
+  /** 替换原始消息内容的 prompt，交给 AI 模型执行 */
+  delegatePrompt: string;
+}
+
 /** 斜杠指令定义 */
 interface SlashCommand {
   /** 指令名（不含 /） */
@@ -2008,6 +2015,250 @@ 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: Record<string, { security: string; ask: string; desc: string }> = {
+        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 as {
+      loadConfig: () => Record<string, unknown>;
+      writeConfigFile: (cfg: unknown) => Promise<void>;
+    };
+
+    const loadExecConfig = () => {
+      const cfg = configApi.loadConfig() as Record<string, unknown>;
+      const tools = (cfg.tools ?? {}) as Record<string, unknown>;
+      const exec = (tools.exec ?? {}) as Record<string, unknown>;
+      return {
+        security: String(exec.security ?? "deny"),
+        ask: String(exec.ask ?? "on-miss"),
+      };
+    };
+
+    const writeExecConfig = async (security: string, ask: string) => {
+      const cfg = structuredClone(configApi.loadConfig()) as Record<string, unknown>;
+      const tools = ((cfg.tools ?? {}) as Record<string, unknown>);
+      const exec = ((tools.exec ?? {}) as Record<string, unknown>);
+      exec.security = security;
+      exec.ask = ask;
+      tools.exec = exec;
+      cfg.tools = tools;
+      await configApi.writeConfigFile(cfg);
+    };
+
+    const formatStatus = (security: string, ask: string) => {
+      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()) as Record<string, unknown>;
+        const tools = (cfg.tools ?? {}) as Record<string, unknown>;
+        const exec = (tools.exec ?? {}) as Record<string, unknown>;
+        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/src/types.ts

@@ -339,6 +339,84 @@ export interface InteractionEvent {
   };
 }
 
+// ---- Keyboard 类型 ----
+
+/**
+ * 按钮 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 事件负载
  */