@jerryliang122/openclaw-qqbot 1.0.0

package/src/dispatch/envelope-builder.ts

@@ -0,0 +1,112 @@
+/**
+ * 信封构建器
+ *
+ * 将 SDK MiddlewareContext 中由各中间件填充的 state 数据
+ * 转换为 OpenClaw 框架标准的 InboundMessage 结构。
+ */
+import type { MiddlewareContext, QQBotInboundMessage, HistoryEntry, ResolvedQuote } from '@tencent-connect/qqbot-nodejs';
+import type { ResolvedQQBotAccount } from '../types.js';
+
+/**
+ * OpenClaw 入站消息结构（传递给 runtime.channel.dispatch）
+ */
+export interface OpenClawInboundMessage {
+  channelId: string;
+  accountId: string;
+  targetId: string;
+  chatScope: 'direct' | 'group';
+  senderId: string;
+  senderName?: string;
+  messageId: string;
+  content: string;
+  history?: Array<{ role: string; content: string; senderId?: string; senderName?: string }>;
+  quote?: { content: string; senderId: string; attachments?: unknown[] };
+  attachments?: unknown[];
+  /** 入站图片 URL 列表（从附件中提取） */
+  imageUrls?: string[];
+  groupId?: string;
+  systemPrompt?: string;
+}
+
+/**
+ * 将 HistoryEntry 转换为 OpenClaw 历史格式
+ */
+function mapHistory(
+  entries: HistoryEntry[] | undefined,
+): OpenClawInboundMessage['history'] {
+  if (!entries || entries.length === 0) return undefined;
+  return entries.map((e) => ({
+    role: 'user',
+    content: e.content,
+    senderId: e.senderId,
+    senderName: e.senderName,
+  }));
+}
+
+/**
+ * 将 ResolvedQuote 转换为 OpenClaw quote 格式
+ */
+function mapQuote(
+  quote: ResolvedQuote | undefined,
+): OpenClawInboundMessage['quote'] {
+  if (!quote) return undefined;
+  return {
+    content: quote.text,
+    senderId: quote.entry?.senderId ?? '',
+    attachments: quote.attachments as unknown[],
+  };
+}
+
+/**
+ * 从 SDK 中间件上下文构建 OpenClaw InboundMessage
+ */
+export function buildEnvelope(
+  ctx: MiddlewareContext,
+  msg: QQBotInboundMessage,
+  account: ResolvedQQBotAccount,
+): OpenClawInboundMessage {
+  const scope = msg.replyTarget.scope;
+  const targetId = scope === 'group'
+    ? `qqbot:group:${msg.replyTarget.targetId}`
+    : `qqbot:c2c:${msg.replyTarget.targetId}`;
+
+  // envelope 是 string 类型，直接作为 content 使用；回退到原始消息内容
+  const envelope = ctx.state.envelope as string | undefined;
+  let content = envelope ?? msg.content;
+
+  // 将语音转录文本和附件信息注入到 content 中
+  const processed = ctx.state.processedAttachments as
+    | { voiceText?: string; imageUrls?: string[]; otherInfo?: string }
+    | undefined;
+
+  if (processed) {
+    const parts: string[] = [];
+    if (processed.voiceText) {
+      parts.push(processed.voiceText);
+    }
+    if (content) {
+      parts.push(content);
+    }
+    if (processed.otherInfo) {
+      parts.push(processed.otherInfo);
+    }
+    content = parts.join('\n');
+  }
+
+  return {
+    channelId: 'qqbot',
+    accountId: account.accountId,
+    targetId,
+    chatScope: scope === 'group' ? 'group' : 'direct',
+    senderId: msg.senderId,
+    senderName: msg.senderName,
+    messageId: msg.messageId,
+    content,
+    history: mapHistory(ctx.state.history as HistoryEntry[] | undefined),
+    quote: mapQuote(ctx.state.quote as ResolvedQuote | undefined),
+    attachments: msg.attachments,
+    imageUrls: processed?.imageUrls,
+    groupId: scope === 'group' ? msg.replyTarget.targetId : undefined,
+    systemPrompt: account.systemPrompt,
+  };
+}

package/src/dispatch/index.ts

@@ -0,0 +1,2 @@
+export { dispatchToOpenClaw } from './dispatch.js';
+export { buildEnvelope } from './envelope-builder.js';

package/src/features/approval-capability.ts

@@ -0,0 +1,302 @@
+/**
+ * QQ Bot Approval Capability — SDK-native approval handling.
+ *
+ * Replaces the former hand-rolled QQBotApprovalHandler. The framework
+ * auto-bootstraps a native approval handler from this capability (registered
+ * on qqbotPlugin.approvalCapability + the "approval.native" runtime context
+ * declared in gateway/lifecycle.ts), and feeds exec/plugin approval requests
+ * back to the availability / presentation / transport callbacks below.
+ *
+ * Model: QQBot has no separate `execApprovals` approver config — it uses the
+ * account `allowFrom` list. With no allowFrom, any participant in the
+ * originating conversation may approve (open mode). This is the "fallback"
+ * path from the in-tree extension, intentionally simpler than the profile
+ * path.
+ */
+
+import { createChannelApprovalCapability } from "openclaw/plugin-sdk/approval-delivery-runtime";
+import { resolveApprovalRequestSessionConversation } from "openclaw/plugin-sdk/approval-native-runtime";
+import {
+  createChannelApprovalNativeRuntimeAdapter,
+  createLazyChannelApprovalNativeRuntimeAdapter,
+  CHANNEL_APPROVAL_NATIVE_RUNTIME_CONTEXT_CAPABILITY,
+} from "openclaw/plugin-sdk/approval-handler-runtime";
+import type {
+  ChannelApprovalNativeRuntimeAdapter,
+} from "openclaw/plugin-sdk/approval-handler-runtime";
+import type {
+  ChannelApprovalCapability,
+} from "openclaw/plugin-sdk/channel-contract";
+import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
+import { DEFAULT_ACCOUNT_ID, resolveQQBotAccount } from "../config.js";
+import { tryGetBotForAccount } from "../bot-instance.js";
+import { getQQBotRuntime } from "../runtime.js";
+import { getAdapters } from "../adapter/resolve.js";
+import type { InlineKeyboard, ResolvedQQBotAccount } from "../types.js";
+import {
+  buildApprovalKeyboard,
+  buildExecApprovalText,
+  buildPluginApprovalText,
+  buildSystemAgentApprovalText,
+  resolveApprovalTarget,
+} from "./approval-helpers.js";
+
+export { CHANNEL_APPROVAL_NATIVE_RUNTIME_CONTEXT_CAPABILITY };
+
+// ─── helpers ────────────────────────────────────────────────
+
+function resolveActiveConfig(): OpenClawConfig {
+  // Prefer the live runtime config snapshot (reflects config reloads); fall
+  // back to an empty object if the runtime is not yet registered.
+  const rt = getQQBotRuntime();
+  const cfg = getAdapters(rt).getConfig?.();
+  return (cfg ?? {}) as OpenClawConfig;
+}
+
+function resolveAccountById(cfg: OpenClawConfig, accountId?: string | null): ResolvedQQBotAccount {
+  return resolveQQBotAccount(cfg, accountId && accountId !== DEFAULT_ACCOUNT_ID ? accountId : undefined);
+}
+
+/** account is enabled and has usable credentials → can deliver native approvals */
+function isNativeDeliveryEnabled(cfg: OpenClawConfig, accountId?: string | null): boolean {
+  const account = resolveAccountById(cfg, accountId);
+  return account.enabled && account.secretSource !== "none";
+}
+
+/** Resolve the QQ delivery target for an approval request. */
+function resolveQQTarget(request: {
+  request: { sessionKey?: string | null; turnSourceTo?: string | null };
+}): { type: "c2c" | "group"; id: string } | null {
+  const sessionKey = request.request.sessionKey ?? null;
+  const turnSourceTo = request.request.turnSourceTo ?? null;
+
+  const target = resolveApprovalTarget(sessionKey, turnSourceTo);
+  if (target) return target;
+
+  const sessionConversation = resolveApprovalRequestSessionConversation({
+    request: request as never,
+    channel: "qqbot",
+    bundledFallback: true,
+  });
+  if (sessionConversation?.id) {
+    const kind = sessionConversation.kind;
+    return { type: kind === "group" ? "group" : "c2c", id: sessionConversation.id };
+  }
+  return null;
+}
+
+/**
+ * Per-account ownership: only the account that originated the turn should
+ * deliver (openids are account-scoped — cross-account delivery fails with
+ * HTTP 500 on the QQ Bot API).
+ */
+function matchesAccount(
+  cfg: OpenClawConfig,
+  accountId: string | null | undefined,
+  request: { request: { turnSourceAccountId?: string | null } },
+): boolean {
+  const reqAccountId = normalizeOptionalString(request.request.turnSourceAccountId);
+  if (!reqAccountId) return true; // no account hint → accept (ownership left to caller)
+  const normalized = (accountId && accountId !== DEFAULT_ACCOUNT_ID) ? accountId : DEFAULT_ACCOUNT_ID;
+  return reqAccountId === normalized;
+}
+
+// ─── authorization (allowFrom) ──────────────────────────────
+
+/**
+ * Decide whether a button-clicker may approve. Mirrors the legacy
+ * isApprovalAuthorized rule: empty allowFrom (or ["*"]) → open; otherwise the
+ * operator must be in the account's allowFrom list.
+ */
+export function authorizeQQBotApprovalAction(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+  senderId?: string | null;
+}): { authorized: boolean; reason?: string } {
+  const operatorId = normalizeOptionalString(params.senderId);
+  if (!operatorId) {
+    return { authorized: false, reason: "Could not identify the operator." };
+  }
+  const account = resolveAccountById(params.cfg, params.accountId);
+  const allowFrom = account.config?.allowFrom ?? [];
+  if (!allowFrom.length || allowFrom.includes("*")) {
+    return { authorized: true };
+  }
+  if (allowIncludes(allowFrom, operatorId)) {
+    return { authorized: true };
+  }
+  return { authorized: false, reason: "You are not authorized to approve this request." };
+}
+
+function allowIncludes(allowFrom: Array<string | number>, operatorId: string): boolean {
+  const normalized = operatorId.toUpperCase().replace(/^qqbot:/i, "");
+  return allowFrom.some((entry) => {
+    const e = String(entry).trim().toUpperCase().replace(/^qqbot:/i, "");
+    return e === normalized;
+  });
+}
+
+// ─── native runtime spec (availability / presentation / transport) ──
+
+type QQBotPendingPayload = { text: string; keyboard: InlineKeyboard };
+type QQBotPreparedTarget = { type: "c2c" | "group"; id: string };
+type QQBotPendingEntry = { messageId?: string; targetType: "c2c" | "group"; targetId: string };
+
+const qqbotApprovalNativeRuntime = createChannelApprovalNativeRuntimeAdapter<
+  QQBotPendingPayload,
+  QQBotPreparedTarget,
+  QQBotPendingEntry
+>({
+  eventKinds: ["exec", "plugin", "system-agent"],
+
+  availability: {
+    isConfigured: ({ cfg, accountId }) =>
+      isNativeDeliveryEnabled(cfg, accountId),
+
+    shouldHandle: ({ cfg, accountId, request }) => {
+      const target = resolveQQTarget(request as never);
+      if (!target) return false;
+      return matchesAccount(cfg, accountId, request as never);
+    },
+  },
+  presentation: {
+    buildPendingPayload: ({ view, nowMs }) => {
+      const text =
+        view.approvalKind === "exec"
+          ? buildExecApprovalText(view, nowMs)
+          : view.approvalKind === "system-agent"
+            ? buildSystemAgentApprovalText(view, nowMs)
+            : buildPluginApprovalText(view, nowMs);
+      const keyboard = buildApprovalKeyboard(
+        view.approvalId,
+        view.approvalKind,
+        view.actions.map((action) => action.decision),
+      );
+      return { text, keyboard };
+    },
+    buildResolvedResult: () => ({ kind: "leave" }),
+    buildExpiredResult: () => ({ kind: "leave" }),
+  },
+
+  transport: {
+    prepareTarget: ({ request }) => {
+      const target = resolveQQTarget(request as never);
+      if (!target) return null;
+      return { target, dedupeKey: `${target.type}:${target.id}` };
+    },
+
+    deliverPending: async ({ accountId, preparedTarget, pendingPayload }) => {
+      // Resolve the bot for this account (gateway must be running — it is, because
+      // the "approval.native" runtime context only exists while the account is started).
+      const resolvedAccountId =
+        accountId && accountId !== DEFAULT_ACCOUNT_ID ? accountId : DEFAULT_ACCOUNT_ID;
+      const bot = tryGetBotForAccount(resolvedAccountId);
+      if (!bot) {
+        throw new Error(
+          `QQ Bot gateway not running for account "${resolvedAccountId}" — cannot deliver approval`,
+        );
+      }
+
+      const replyTarget = {
+        scope: preparedTarget.type as "c2c" | "group",
+        targetId: preparedTarget.id,
+      };
+      const result = await bot.sendTextWithKeyboard(
+        replyTarget,
+        pendingPayload.text,
+        pendingPayload.keyboard as never,
+      );
+      const messageId = (result as { id?: string } | undefined)?.id;
+      return {
+        messageId,
+        targetType: preparedTarget.type,
+        targetId: preparedTarget.id,
+      };
+    },
+  },
+});
+
+// ─── capability assembly ────────────────────────────────────
+
+function createQQBotApprovalCapability(): ChannelApprovalCapability {
+  return createChannelApprovalCapability({
+    authorizeActorAction: ({ cfg, accountId, senderId }) =>
+      authorizeQQBotApprovalAction({ cfg, accountId, senderId }),
+
+    getActionAvailabilityState: ({ cfg, accountId }) =>
+      isNativeDeliveryEnabled(cfg, accountId)
+        ? { kind: "enabled" as const }
+        : { kind: "disabled" as const },
+
+    getExecInitiatingSurfaceState: ({ cfg, accountId }) =>
+      isNativeDeliveryEnabled(cfg, accountId)
+        ? { kind: "enabled" as const }
+        : { kind: "disabled" as const },
+
+    describeExecApprovalSetup: ({ accountId }: { accountId?: string | null }) => {
+      const prefix =
+        accountId && accountId !== DEFAULT_ACCOUNT_ID
+          ? `channels.qqbot.accounts.${accountId}`
+          : "channels.qqbot";
+      return `QQBot native approvals are enabled by default. To restrict who can approve, configure \`${prefix}.allowFrom\` with QQ user OpenIDs.`;
+    },
+
+    delivery: {
+      hasConfiguredDmRoute: () => true,
+      shouldSuppressForwardingFallback: (input) => {
+        const channel = normalizeOptionalString(input.target?.channel);
+        if (channel !== "qqbot") return false;
+        const accountId =
+          normalizeOptionalString(input.target?.accountId) ??
+          normalizeOptionalString(input.request?.request?.turnSourceAccountId);
+        return isNativeDeliveryEnabled(resolveActiveConfig(), accountId);
+      },
+    },
+
+    native: {
+      describeDeliveryCapabilities: ({ cfg, accountId }) => ({
+        enabled: isNativeDeliveryEnabled(cfg, accountId),
+        preferredSurface: "origin" as const,
+        supportsOriginSurface: true,
+        supportsApproverDmSurface: false,
+        notifyOriginWhenDmOnly: false,
+      }),
+      resolveOriginTarget: ({ request }) => {
+        const sessionKey = request.request.sessionKey ?? null;
+        const turnSourceTo = request.request.turnSourceTo ?? null;
+        const target = resolveApprovalTarget(sessionKey, turnSourceTo);
+        if (target) return { to: `${target.type}:${target.id}` };
+        const sessionConversation = resolveApprovalRequestSessionConversation({
+          request: request as never,
+          channel: "qqbot",
+          bundledFallback: true,
+        });
+        if (sessionConversation?.id) {
+          const kind = sessionConversation.kind === "group" ? "group" : "c2c";
+          return { to: `${kind}:${sessionConversation.id}` };
+        }
+        return null;
+      },
+    },
+
+    nativeRuntime: createLazyChannelApprovalNativeRuntimeAdapter({
+      eventKinds: ["exec", "plugin", "system-agent"],
+      isConfigured: ({ cfg, accountId }) => isNativeDeliveryEnabled(cfg, accountId),
+      shouldHandle: ({ cfg, accountId, request }) => {
+        const target = resolveQQTarget(request as never);
+        if (!target) return false;
+        return matchesAccount(cfg, accountId, request as never);
+      },
+      load: async () =>
+        qqbotApprovalNativeRuntime as unknown as ChannelApprovalNativeRuntimeAdapter,
+    }),
+  });
+}
+
+let cachedCapability: ChannelApprovalCapability | undefined;
+
+export function getQQBotApprovalCapability(): ChannelApprovalCapability {
+  cachedCapability ??= createQQBotApprovalCapability();
+  return cachedCapability;
+}

package/src/features/approval-helpers.ts

@@ -0,0 +1,271 @@
+/**
+ * Approval helpers — pure functions shared by the approval capability and the
+ * interaction (button-click) handler.
+ *
+ * Ported from the in-tree openclaw qqbot extension so the external plugin stays
+ * byte-compatible with the framework's approval view model:
+ *   - buildApprovalKeyboard reads `allowedDecisions` from the SDK view (fixes
+ *     the hardcoded-3-button bug where skill_workshop approvals rejected
+ *     `allow-always`).
+ *   - button_data uses the v2 format `approve:v2:<kind>:<encodedId>:<decision>`
+ *     so the kind is recoverable at click time without ID-prefix sniffing.
+ */
+
+import type {
+  ExecApprovalPendingView,
+  PendingApprovalView,
+  PluginApprovalPendingView,
+} from "openclaw/plugin-sdk/approval-handler-runtime";
+import { resolveExecApprovalCommandDisplay } from "openclaw/plugin-sdk/approval-runtime";
+import { truncateUtf16Safe } from "openclaw/plugin-sdk/text-utility-runtime";
+import type { InlineKeyboard, KeyboardButton } from "../types.js";
+
+// ============ Types ============
+
+export type ApprovalKind = "exec" | "plugin" | "system-agent";
+
+// The SDK re-exports only the pending-view union, not the system-agent member.
+export type SystemAgentApprovalPendingView = Extract<
+  PendingApprovalView,
+  { approvalKind: "system-agent" }
+>;
+export type ApprovalDecision = "allow-once" | "allow-always" | "deny";
+
+export interface ApprovalTarget {
+  type: "c2c" | "group";
+  id: string;
+}
+
+export interface ParsedApprovalAction {
+  approvalId: string;
+  approvalKind: ApprovalKind;
+  decision: ApprovalDecision;
+}
+
+// ============ Text Builders ============
+
+const COMMAND_PREVIEW_MAX_LENGTH = 300;
+const COMMAND_PREVIEW_GRAPHEMES_PER_LINE = 24;
+const COMMAND_PREVIEW_WRAP_MARKER = "↩";
+const commandPreviewSegmenter =
+  typeof Intl !== "undefined" && "Segmenter" in Intl
+    ? new Intl.Segmenter(undefined, { granularity: "grapheme" })
+    : null;
+
+function splitCommandPreviewGraphemes(commandText: string): string[] {
+  return commandPreviewSegmenter
+    ? Array.from(commandPreviewSegmenter.segment(commandText), ({ segment }) => segment)
+    : Array.from(commandText);
+}
+
+function formatCommandPreview(commandText: string): string {
+  // QQ Desktop does not wrap fenced blocks. The sanitized view has already escaped real command
+  // newlines, so these grapheme-safe line breaks are presentation-only and unambiguous. Limiting
+  // each line to 24 graphemes also bounds common double-width text to roughly 48 columns.
+  const lines = [""];
+  const displayText = commandText.replaceAll(COMMAND_PREVIEW_WRAP_MARKER, "\\u{21A9}");
+  let previewLength = 0;
+  let lineGraphemes = 0;
+  let truncated = false;
+  let wrapped = false;
+  for (const grapheme of splitCommandPreviewGraphemes(displayText)) {
+    if (previewLength + grapheme.length > COMMAND_PREVIEW_MAX_LENGTH) {
+      if (previewLength === 0) {
+        lines[0] = truncateUtf16Safe(grapheme, COMMAND_PREVIEW_MAX_LENGTH);
+      }
+      truncated = true;
+      break;
+    }
+    previewLength += grapheme.length;
+    if (lineGraphemes === COMMAND_PREVIEW_GRAPHEMES_PER_LINE) {
+      lines[lines.length - 1] += COMMAND_PREVIEW_WRAP_MARKER;
+      lines.push("");
+      lineGraphemes = 0;
+      wrapped = true;
+    }
+    lines[lines.length - 1] += grapheme;
+    lineGraphemes += 1;
+  }
+  const preview = `${lines.join("\n")}${truncated ? "\n…[truncated]" : ""}`;
+  const longestBacktickRun = Math.max(0, ...(preview.match(/`+/g)?.map((run) => run.length) ?? []));
+  const fence = "`".repeat(Math.max(3, longestBacktickRun + 1));
+  const block = `${fence}\n${preview}\n${fence}`;
+  return wrapped
+    ? `${COMMAND_PREVIEW_WRAP_MARKER} = display wrap only; not command text\n${block}`
+    : block;
+}
+
+function formatApprovalMetadata(value: string): string {
+  const sanitized = resolveExecApprovalCommandDisplay({ command: value }).commandText;
+  return formatCommandPreview(sanitized);
+}
+
+export function buildExecApprovalText(view: ExecApprovalPendingView, nowMs = Date.now()): string {
+  const expiresIn = Math.max(0, Math.round((view.expiresAtMs - nowMs) / 1000));
+  const lines: string[] = ["🔐 命令执行审批", ""];
+  if (view.commandText) {
+    lines.push(formatCommandPreview(view.commandText));
+  }
+  if (view.cwd) {
+    lines.push(`📁 目录:\n${formatApprovalMetadata(view.cwd)}`);
+  }
+  if (view.agentId) {
+    lines.push(`🤖 Agent:\n${formatApprovalMetadata(view.agentId)}`);
+  }
+  lines.push("", `⏱️ 超时: ${expiresIn} 秒`);
+  return lines.join("\n");
+}
+
+export function buildPluginApprovalText(
+  view: PluginApprovalPendingView,
+  nowMs = Date.now(),
+): string {
+  const expiresIn = Math.max(0, Math.round((view.expiresAtMs - nowMs) / 1000));
+  const severityIcon =
+    view.severity === "critical" ? "🔴"
+    : view.severity === "info" ? "🔵"
+    : "🟡";
+
+  const lines: string[] = [`${severityIcon} 审批请求`, ""];
+  lines.push(`📋 ${view.title}`);
+  if (view.description) lines.push(`📝 ${view.description}`);
+  if (view.toolName) lines.push(`🔧 工具: ${view.toolName}`);
+  if (view.pluginId) lines.push(`🔌 插件: ${view.pluginId}`);
+  if (view.agentId) lines.push(`🤖 Agent: ${view.agentId}`);
+  lines.push("", `⏱️ 超时: ${expiresIn} 秒`);
+  return lines.join("\n");
+}
+
+export function buildSystemAgentApprovalText(
+  view: SystemAgentApprovalPendingView,
+  nowMs = Date.now(),
+): string {
+  const expiresIn = Math.max(0, Math.round((view.expiresAtMs - nowMs) / 1000));
+
+  const lines: string[] = ["🛡️ 系统变更审批", ""];
+  lines.push(`📋 ${view.title}`);
+  if (view.description) lines.push(`📝 ${view.description}`);
+  if (view.operationSummary) lines.push(`📊 ${view.operationSummary}`);
+  if (view.commandText) {
+    lines.push(formatCommandPreview(view.commandText));
+  }
+  if (view.cwd) {
+    lines.push(`📁 目录:\n${formatApprovalMetadata(view.cwd)}`);
+  }
+  if (view.host) lines.push(`🖥️ 主机: ${view.host}`);
+  if (view.agentId) lines.push(`🤖 Agent:\n${formatApprovalMetadata(view.agentId)}`);
+  lines.push("", `⏱️ 超时: ${expiresIn} 秒`);
+  return lines.join("\n");
+}
+
+// ============ Keyboard Builder ============
+
+/**
+ * Build the inline keyboard for approval messages.
+ *
+ * type=1 (Callback): click triggers INTERACTION_CREATE, button_data = data field.
+ * group_id "approval": clicking one button grays out the others (mutual exclusion).
+ * click_limit=1: each user can only click once.
+ * permission.type=2: all users can interact.
+ *
+ * Only buttons whose decision is in `allowedDecisions` are rendered — the SDK
+ * view drives this, so e.g. skill_workshop approvals (which restrict to
+ * ["allow-once","deny"]) no longer offer an invalid "allow-always" button.
+ */
+export function buildApprovalKeyboard(
+  approvalId: string,
+  approvalKind: ApprovalKind,
+  allowedDecisions: readonly ApprovalDecision[] = ["allow-once", "allow-always", "deny"],
+): InlineKeyboard {
+  const actionPrefix = `approve:v2:${approvalKind}:${encodeURIComponent(approvalId)}`;
+  const makeBtn = (
+    id: string,
+    label: string,
+    visitedLabel: string,
+    data: string,
+    style: 0 | 1,
+  ): KeyboardButton => ({
+    id,
+    render_data: { label, visited_label: visitedLabel, style },
+    action: {
+      type: 1,
+      data,
+      permission: { type: 2 },
+      click_limit: 1,
+    },
+    group_id: "approval",
+  });
+
+  const buttons: KeyboardButton[] = [];
+  if (allowedDecisions.includes("allow-once")) {
+    buttons.push(makeBtn("allow", "✅ 允许一次", "已处理", `${actionPrefix}:allow-once`, 1));
+  }
+  if (allowedDecisions.includes("allow-always")) {
+    buttons.push(makeBtn("always", "⭐ 始终允许", "已处理", `${actionPrefix}:allow-always`, 1));
+  }
+  if (allowedDecisions.includes("deny")) {
+    buttons.push(makeBtn("deny", "❌ 拒绝", "已处理", `${actionPrefix}:deny`, 0));
+  }
+
+  return {
+    content: {
+      rows: [{ buttons }],
+    },
+  };
+}
+
+// ============ Target Resolver ============
+
+/**
+ * Extract the delivery target from a sessionKey or turnSourceTo string.
+ *
+ * Expected formats:
+ *   agent:main:qqbot:c2c:OPENID     -> { type: "c2c", id: "OPENID" }
+ *   agent:main:qqbot:group:GROUPID  -> { type: "group", id: "GROUPID" }
+ *
+ * Returns null if neither field matches the expected pattern.
+ */
+export function resolveApprovalTarget(
+  sessionKey: string | null | undefined,
+  turnSourceTo: string | null | undefined,
+): ApprovalTarget | null {
+  const sk = sessionKey ?? turnSourceTo;
+  if (!sk) return null;
+  const m = sk.match(/qqbot:(c2c|group):([A-F0-9]+)/i);
+  if (!m) return null;
+  const scope = m[1];
+  const id = m[2];
+  if (scope === undefined || id === undefined) return null;
+  const type: "c2c" | "group" = scope.toLowerCase() === "group" ? "group" : "c2c";
+  return { type, id };
+}
+
+// ============ Interaction Parser ============
+
+/**
+ * Parse the button_data string from an INTERACTION_CREATE event.
+ *
+ * Expected format: `approve:v2:<approvalKind>:<encodedApprovalId>:<decision>`.
+ * The approvalKind is baked into the payload so the resolve path doesn't need
+ * to infer it from the ID prefix, and the ID is URL-encoded so colons in
+ * `exec:<uuid>` / `plugin:<uuid>` / `system-agent:<uuid>` IDs survive
+ * unambiguously.
+ *
+ * Returns null if the data does not match the approval button format.
+ */
+export function parseApprovalButtonData(buttonData: string): ParsedApprovalAction | null {
+  const m = buttonData.match(/^approve:v2:(exec|plugin|system-agent):([^:]+):(allow-once|allow-always|deny)$/);
+  if (!m || m[0] !== buttonData) return null;
+  const kind = m[1] as ApprovalKind;
+  const encodedId = m[2];
+  const decision = m[3] as ApprovalDecision;
+  if (!encodedId) return null;
+  let approvalId: string;
+  try {
+    approvalId = decodeURIComponent(encodedId);
+  } catch {
+    return null;
+  }
+  if (!approvalId) return null;
+  return { approvalId, approvalKind: kind, decision };
+}