@tencent-connect/openclaw-qqbot 1.7.1 → 2.0.0

package/src/middleware/access-control.ts

@@ -0,0 +1,130 @@
+/**
+ * 动态访问控制中间件。
+ *
+ * 从 ctx.state.policy（由 policy-injector 注入）动态读取策略，支持配置热更新。
+ * 模式：disabled | open | allowlist | pairing（仅 c2c）
+ */
+import type { Middleware } from '@tencent-connect/qqbot-nodejs';
+import { getPairingApi } from '../adapter/pairing.js';
+
+
+/**
+ * 创建动态访问控制中间件。
+ *
+ * 决策优先级：
+ *   1. disabled → 拒绝
+ *   2. open → 放行
+ *   3. allowlist → allowFrom 匹配（默认模式）
+ *   4. pairing → allowFrom + pairing store，未配对发起挑战
+ */
+export function dynamicAccessControl(params: {
+  accountId: string;
+  getRuntime: () => any;
+}): Middleware {
+  const { accountId, getRuntime } = params;
+
+  return async (ctx, next) => {
+    const p = ctx.state.policy as Record<string, unknown> | undefined;
+    const isGroup = ctx.message.kind === 'group';
+    const mode: string = isGroup
+      ? (p?.groupMode as string) ?? 'open'
+      : (p?.c2cMode as string) ?? 'allowlist';
+
+    if (mode === 'disabled') {
+      ctx.log?.info?.(`[access] blocked ${isGroup ? 'group' : 'c2c'} from ${ctx.message.senderId}: policy disabled`);
+      ctx.stop('access:policy_disabled');
+      return;
+    }
+    if (mode === 'open') {
+      await next();
+      return;
+    }
+
+    // allowlist / pairing：c2c 用 allowFrom，group 用 groupAllowFrom
+    const allowList = isGroup
+      ? ((p?.groupAllowFrom as string[]) ?? [])
+      : ((p?.allowFrom as string[]) ?? []);
+    if (!allowList.length || allowList.includes('*')) {
+      await next();
+      return;
+    }
+
+    const id = isGroup
+      ? (ctx.message.groupOpenid ?? '')
+      : (ctx.message.senderId as string);
+    if (allowList.includes(id)) {
+      await next();
+      return;
+    }
+
+    // allowlist 未匹配 → pairing 模式尝试 pairing store（仅 c2c）
+    if (mode === 'pairing' && !isGroup) {
+      await checkPairingMode(ctx, next, {
+        accountId,
+        getRuntime,
+        senderId: ctx.message.senderId as string,
+      });
+      return;
+    }
+
+    // 未匹配 → 拒绝
+    const listLabel = isGroup ? 'groupAllowFrom' : 'allowFrom';
+    ctx.log?.info?.(
+      `[access] blocked ${isGroup ? 'group' : 'c2c'} from ${id}: not in ${listLabel}`,
+    );
+    ctx.stop('access:not_allowlisted');
+  };
+}
+
+/**
+ * pairing 模式：检查 pairing store + 发起配对挑战。
+ */
+async function checkPairingMode(
+  ctx: any,
+  next: () => Promise<void>,
+  opts: { accountId: string; getRuntime: () => any; senderId: string },
+): Promise<void> {
+  const api = getPairingApi();
+  if (!api) {
+    ctx.log?.info?.(`[access] pairing unavailable for ${opts.senderId}`);
+    ctx.stop('access:pairing_unavailable');
+    return;
+  }
+
+  try {
+    const storeIds = await api.readAllowFromStore({
+      channel: 'qqbot',
+      accountId: opts.accountId,
+    });
+    if (storeIds.includes(opts.senderId) || storeIds.includes('*')) {
+      await next();
+      return;
+    }
+
+    const challenge = await api.issueChallenge({
+      channel: 'qqbot',
+      id: opts.senderId,
+      accountId: opts.accountId,
+    });
+    const frameworkReply = api.buildReply({
+      code: challenge.code,
+      channel: 'qqbot',
+    });
+    const reply = [
+      frameworkReply,
+      '',
+      'QQ 管理员可直接执行：',
+      '',
+      '```',
+      `/bot-pairing approve ${challenge.code}`,
+      '```',
+    ].join('\n');
+
+    ctx.log?.info?.(`[access] pairing required for ${opts.senderId}`);
+    await ctx.bot.sendText(ctx.replyTarget, reply).catch(() => {/* ignore */});
+    ctx.stop('access:pairing_required');
+  } catch (err) {
+    ctx.log?.error?.(`[access] pairing error: ${(err as Error).message}`);
+    ctx.stop(`access:pairing_error: ${(err as Error).message}`);
+  }
+}

package/src/middleware/attachment.ts

@@ -0,0 +1,314 @@
+/**
+ * 入站附件处理中间件
+ *
+ * 处理入站消息中的语音/图片/视频附件：
+ * - 语音：下载 → SILK转WAV → STT转文字 → 写入 ctx.state.processedAttachments
+ * - 图片：提取 URL 列表
+ * - 其他：标记为附件描述
+ *
+ * 插入位置：envelopeFormatter 之前
+ */
+import * as path from 'node:path';
+import type { MiddlewareContext } from '@tencent-connect/qqbot-nodejs';
+import {
+  convertSilkToWav,
+  isVoiceAttachment,
+} from '@tencent-connect/qqbot-nodejs/protocol';
+import type { MessageAttachment } from '../types.js';
+import { transcribeAudio, resolveSTTConfig } from '../utils/stt.js';
+import { formatVoiceText, formatDuration, type VoiceTranscript, type TranscriptSource } from '../utils/voice-text.js';
+import { downloadRemoteMedia } from '../adapter/media.js';
+import { getAdapters } from '../adapter/resolve.js';
+
+export { formatVoiceText, formatDuration };
+export type { VoiceTranscript, TranscriptSource };
+
+/** 处理后的附件结果（写入 ctx.state.processedAttachments） */
+export interface ProcessedAttachments {
+  voiceText: string;
+  imageUrls: string[];
+  otherInfo: string;
+  transcripts: VoiceTranscript[];
+  /** 下载到本地的媒体路径（图片 + 语音，供 AI 引用） */
+  localMediaPaths: string[];
+  /** 对应 localMediaPaths 的 MIME type */
+  localMediaTypes: string[];
+  /** 远端 URL 列表（下载失败时的回退） */
+  remoteMediaUrls: string[];
+}
+
+interface AttachmentMiddlewareOptions {
+  /** 获取 runtime */
+  getRuntime: () => any;
+}
+
+/**
+ * 附件处理中间件
+ *
+ * SDK ctx 已提供 log 和 accountId，只需传入配置获取函数。
+ */
+export function attachmentProcessor(opts: AttachmentMiddlewareOptions) {
+  return async (ctx: MiddlewareContext, next: () => Promise<void>) => {
+    const msg = ctx.message;
+    const attachments = msg.attachments as MessageAttachment[] | undefined;
+
+    if (attachments?.length) {
+      const runtime = opts.getRuntime();
+      const adapters = getAdapters(runtime);
+      const cfg = (adapters.getConfig?.() ?? {}) as Record<string, unknown>;
+      const log = ctx.log;
+      const result = await processAttachments(attachments, cfg, log);
+
+      if (result.voiceText || result.imageUrls.length > 0 || result.otherInfo || result.localMediaPaths.length > 0) {
+        ctx.state.processedAttachments = result;
+      }
+    }
+
+    await next();
+  };
+}
+
+// ── 核心处理逻辑 ──
+
+type Log = { info: (m: string) => void; error: (m: string) => void; debug?: (m: string) => void };
+
+async function processAttachments(
+  attachments: MessageAttachment[],
+  cfg: Record<string, unknown>,
+  log?: Log,
+): Promise<ProcessedAttachments> {
+  const sttCfg = resolveSTTConfig(cfg);
+  const audioPolicy = resolveAudioPolicy(cfg);
+
+  const imageUrls: string[] = [];
+  const otherParts: string[] = [];
+  const transcripts: VoiceTranscript[] = [];
+  const localMediaPaths: string[] = [];
+  const localMediaTypes: string[] = [];
+  const remoteMediaUrls: string[] = [];
+
+  // 并行下载所有附件
+  const tasks = attachments.map(async (att) => {
+    const isVoice = isVoiceAttachment(att);
+    const isImage = att.content_type?.startsWith('image/');
+    const url = normalizeUrl(att.url);
+
+    if (isImage && url) {
+      const localPath = await downloadMediaFile(url, att.filename, log);
+      return { type: 'image' as const, localPath, url, contentType: att.content_type ?? 'image/png' };
+    }
+
+    if (isVoice) {
+      const transcript = await processVoiceAttachment(att, sttCfg, audioPolicy, log);
+      return { type: 'voice' as const, transcript };
+    }
+
+    // other 类型也尝试下载
+    if (url) {
+      const localPath = await downloadMediaFile(url, att.filename, log);
+      return { type: 'other' as const, localPath, url, filename: att.filename ?? att.content_type };
+    }
+    return { type: 'other' as const, localPath: null, url: '', filename: att.filename ?? att.content_type };
+  });
+
+  const results = await Promise.all(tasks);
+
+  // 按原始顺序收集结果
+  for (const result of results) {
+    if (result.type === 'image') {
+      if (result.localPath) {
+        imageUrls.push(result.localPath);
+        localMediaPaths.push(result.localPath);
+        localMediaTypes.push(result.contentType);
+      } else {
+        imageUrls.push(result.url);
+        remoteMediaUrls.push(result.url);
+      }
+    } else if (result.type === 'voice') {
+      transcripts.push(result.transcript);
+      if (result.transcript.localPath) {
+        localMediaPaths.push(result.transcript.localPath);
+        localMediaTypes.push('audio/wav');
+      } else if (result.transcript.remoteUrl) {
+        remoteMediaUrls.push(result.transcript.remoteUrl);
+      }
+    } else if (result.type === 'other') {
+      if (result.localPath) {
+        otherParts.push(`[Attachment: ${result.localPath}]`);
+        localMediaPaths.push(result.localPath);
+        localMediaTypes.push('application/octet-stream');
+      } else {
+        otherParts.push(`[Attachment: ${result.filename}]`);
+      }
+    }
+  }
+
+  return {
+    voiceText: formatVoiceText(transcripts),
+    imageUrls,
+    otherInfo: otherParts.join('\n'),
+    transcripts,
+    localMediaPaths,
+    localMediaTypes,
+    remoteMediaUrls,
+  };
+}
+
+// ── 语音处理 ──
+
+async function processVoiceAttachment(
+  att: MessageAttachment,
+  sttCfg: ReturnType<typeof resolveSTTConfig>,
+  audioPolicy: AudioPolicyResolved,
+  log?: Log,
+): Promise<VoiceTranscript> {
+  const asrReferText = att.asr_refer_text?.trim() || undefined;
+  // 远端 URL 兜底：优先 wav_url，其次原始 url
+  const remoteUrl = normalizeUrl(att.voice_wav_url) || normalizeUrl(att.url) || undefined;
+
+  // STT 未配置：直接走 ASR / fallback
+  if (!sttCfg) {
+    if (asrReferText) {
+      log?.debug?.(`Voice: using asr_refer_text (STT not configured)`);
+      return { text: asrReferText, source: 'asr', asrReferText, remoteUrl };
+    }
+    return {
+      text: '[Voice message - transcription unavailable]',
+      source: 'fallback',
+      asrReferText,
+      remoteUrl,
+    };
+  }
+
+  let localPath: string | undefined;
+  let duration: number | undefined;
+
+  try {
+    const wavUrl = normalizeUrl(att.voice_wav_url);
+    if (wavUrl) {
+      const downloaded = await downloadMediaFile(wavUrl, undefined, log);
+      if (downloaded) {
+        localPath = downloaded;
+        log?.debug?.(`Voice: downloaded WAV from voice_wav_url`);
+      }
+    }
+
+    if (!localPath) {
+      const silkUrl = normalizeUrl(att.url);
+      if (silkUrl) {
+        const silkPath = await downloadMediaFile(silkUrl, att.filename, log);
+        if (silkPath) {
+          const ext = path.extname(silkPath).toLowerCase();
+          if (audioPolicy.sttDirectFormats.includes(ext)) {
+            localPath = silkPath;
+          } else {
+            const wavResult = await convertSilkToWav(silkPath);
+            if (wavResult) {
+              localPath = wavResult.wavPath;
+              duration = wavResult.duration / 1000;
+              log?.debug?.(`Voice: SILK→WAV (${formatDuration(duration)})`);
+            } else {
+              localPath = silkPath;
+            }
+          }
+        }
+      }
+    }
+  } catch (err) {
+    log?.error(`Voice download/convert failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  if (localPath) {
+    try {
+      const transcript = await transcribeAudio(localPath, cfg2stt(sttCfg));
+      if (transcript) {
+        log?.debug?.(`Voice STT: ${transcript.slice(0, 80)}...`);
+        return { text: transcript, source: 'stt', duration, localPath, remoteUrl, asrReferText };
+      }
+    } catch (err) {
+      log?.error(`Voice STT failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  if (asrReferText) {
+    return { text: asrReferText, source: 'asr', duration, localPath, remoteUrl, asrReferText };
+  }
+
+  return {
+    text: '[Voice message - transcription failed]',
+    source: 'fallback',
+    duration,
+    localPath,
+    remoteUrl,
+    asrReferText,
+  };
+}
+
+// ── 配置 ──
+
+interface AudioPolicyResolved {
+  sttDirectFormats: string[];
+  uploadDirectFormats: string[];
+  transcodeEnabled: boolean;
+}
+
+function resolveAudioPolicy(cfg: Record<string, unknown>): AudioPolicyResolved {
+  const channels = cfg.channels as Record<string, unknown> | undefined;
+  const qqbot = channels?.qqbot as Record<string, unknown> | undefined;
+  const policy = qqbot?.audioFormatPolicy as Record<string, unknown> | undefined;
+
+  return {
+    sttDirectFormats: normalizeFormats((policy?.sttDirectFormats as string[]) ?? []),
+    uploadDirectFormats: normalizeFormats(
+      (policy?.uploadDirectFormats as string[]) ??
+      (qqbot?.voiceDirectUploadFormats as string[]) ??
+      ['.wav', '.mp3', '.silk'],
+    ),
+    transcodeEnabled: (policy?.transcodeEnabled as boolean) !== false,
+  };
+}
+
+function normalizeFormats(formats: string[]): string[] {
+  return formats.map((f) => {
+    const lower = f.toLowerCase().trim();
+    return lower.startsWith('.') ? lower : `.${lower}`;
+  });
+}
+
+function cfg2stt(sttCfg: NonNullable<ReturnType<typeof resolveSTTConfig>>): Record<string, unknown> {
+  return { channels: { qqbot: { stt: sttCfg } } };
+}
+
+// ── 文件工具 ──
+
+function normalizeUrl(url: string | undefined): string {
+  if (!url) return '';
+  return url.startsWith('//') ? `https:${url}` : url;
+}
+
+async function downloadMediaFile(
+  url: string,
+  filename?: string,
+  log?: Log,
+): Promise<string | null> {
+  // 仅允许 HTTPS（安全策略）
+  if (!url.startsWith('https://')) {
+    log?.debug?.(`Skipping non-HTTPS URL: ${url.slice(0, 80)}`);
+    return null;
+  }
+
+  try {
+    const result = await downloadRemoteMedia({
+      url,
+      subdir: 'qqbot/downloads',
+      originalFilename: filename,
+      maxBytes: 500 * 1024 * 1024,
+      timeoutMs: 120_000,
+    });
+    log?.debug?.(`Downloaded: ${result.path}`);
+    return result.path;
+  } catch (err) {
+    log?.error(`Download failed: ${url.slice(0, 80)} — ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+}

package/src/middleware/policy-injector.ts

@@ -0,0 +1,66 @@
+/**
+ * 动态策略注入中间件
+ *
+ * 每条消息到达时，按 groupId 解析群配置并注入 `ctx.state.policy`。
+ * SDK 内置中间件（mentionGate、historyBuffer 等）自动从 `ctx.state.policy`
+ * 读取动态策略作为 fallback，无需各自注册 `resolveConfig`。
+ *
+ * 优先级链（与旧版一致）：
+ *   具体群配置 > 通配符 "*" > defaultRequireMention > 硬编码默认值
+ */
+import type { Middleware } from '@tencent-connect/qqbot-nodejs';
+import type { ResolvedQQBotAccount } from '../types.js';
+import { resolveGroupConfigFromAccount } from '../config.js';
+
+/**
+ * 创建 policy injector 中间件。
+ *
+ * 注入的 `ctx.state.policy` 结构：
+ * ```
+ * {
+ *   scope: "c2c" | "group",
+ *   group: {
+ *     requireMention: boolean,
+ *     ignoreOtherMentions: boolean,
+ *     historyLimit: number,
+ *     // ... 可扩展任意字段
+ *   }
+ * }
+ * ```
+ *
+ * 使用者可在 `policy.group` 上添加自定义字段，如：
+ * ```
+ * ctx.state.policy.toolPolicy = "full";
+ * ```
+ * 自定义中间件通过 `ctx.state.policy` 读取即可。
+ */
+export function createPolicyInjector(account: ResolvedQQBotAccount): Middleware {
+  return async (ctx, next) => {
+    const msg = ctx.message as any;
+    const scope = msg.kind as 'c2c' | 'group' | 'dm' | 'channel';
+
+    const policy: Record<string, unknown> = {
+      scope,
+      accountId: account.accountId,
+      // 访问控制：dmPolicy（c2c） / groupPolicy（group），默认 allowlist
+      c2cMode: account.config?.dmPolicy ?? 'allowlist',
+      groupMode: account.config?.groupPolicy ?? 'allowlist',
+      allowFrom: account.config?.allowFrom ?? [],
+      groupAllowFrom: account.config?.groupAllowFrom ?? [],
+    };
+
+    if (scope === 'group') {
+      const groupOpenid = msg.groupOpenid ?? '';
+      const groupCfg = resolveGroupConfigFromAccount(account, groupOpenid);
+      policy.group = {
+        requireMention: groupCfg.requireMention,
+        ignoreOtherMentions: groupCfg.ignoreOtherMentions,
+        historyLimit: groupCfg.historyLimit,
+        prompt: groupCfg.prompt,
+      };
+    }
+
+    ctx.state.policy = policy;
+    await next();
+  };
+}

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

@@ -78,26 +78,41 @@ declare module "openclaw/plugin-sdk" {
   export interface PluginRuntime {
     /** OpenClaw 框架版本号，如 "2026.3.31" */
     version: string;
-    /** 获取当前配置 */
-    getConfig(): OpenClawConfig;
-    /** 更新配置 */
-    setConfig(config: OpenClawConfig): void;
-    /** 获取数据目录路径 */
-    getDataDir(): string;
-    /** Channel 接口 - 使用 any 类型以兼容 SDK 内部复杂类型 */
+    /** 配置访问（运行时 config 在 config.current()，非顶层 getConfig()） */
+    config?: {
+      /** 获取当前运行时配置快照（只读） */
+      current(): OpenClawConfig;
+    };
+    /** Channel 接口 */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     channel?: any;
-    /** 日志函数 */
+    /** 日志函数（旧版，建议使用 logging.getChildLogger） */
     log: {
       info: (message: string, ...args: unknown[]) => void;
       warn: (message: string, ...args: unknown[]) => void;
       error: (message: string, ...args: unknown[]) => void;
       debug: (message: string, ...args: unknown[]) => void;
     };
-    /** 其他运行时方法 */
+    /** 结构化日志（框架自动追加 channel 前缀） */
+    logging: {
+      shouldLogVerbose: () => boolean;
+      getChildLogger: (
+        bindings?: Record<string, unknown>,
+        opts?: { level?: string },
+      ) => RuntimeLogger;
+    };
+    /** 其他运行时方法（不要假设 getConfig/getDataDir/setConfig 可用） */
     [key: string]: unknown;
   }
 
+  /** 结构化日志器 */
+  export interface RuntimeLogger {
+    debug?: (message: string, meta?: Record<string, unknown>) => void;
+    info: (message: string, meta?: Record<string, unknown>) => void;
+    warn: (message: string, meta?: Record<string, unknown>) => void;
+    error: (message: string, meta?: Record<string, unknown>) => void;
+  }
+
   // ============ 插件 API ============
 
   /**
@@ -219,7 +234,6 @@ declare module "openclaw/plugin-sdk" {
     tokenFile?: string;
     useEnv?: boolean;
     name?: string;
-    imageServerBaseUrl?: string;
     [key: string]: unknown;
   }
 
@@ -661,6 +675,63 @@ declare module "openclaw/plugin-sdk" {
   export function normalizeAccountId(accountId: string | undefined | null): string;
 }
 
+declare module "openclaw/plugin-sdk/setup" {
+  export interface ChannelSetupWizardStatus {
+    channelLabel: string;
+    configuredLabel: string;
+    unconfiguredLabel: string;
+    configuredHint?: string;
+    unconfiguredHint?: string;
+    configuredScore?: number;
+    unconfiguredScore?: number;
+    includeStatusLine?: boolean;
+    resolveConfigured: (params: { cfg: unknown; accountId: string }) => boolean;
+  }
+
+  export interface ChannelSetupWizard {
+    channel: string;
+    status: ChannelSetupWizardStatus;
+    /** 解析配置时使用哪个账户 ID：无账户时默认 'default' */
+    resolveAccountIdForConfigure?: (params: {
+      cfg: unknown;
+      prompter: unknown;
+      options?: unknown;
+      accountOverride?: string;
+      shouldPromptAccountIds: boolean;
+      listAccountIds: (cfg: unknown) => string[];
+      defaultAccountId: string;
+    }) => string | Promise<string>;
+    resolveShouldPromptAccountIds?: (params: {
+      cfg: unknown;
+      options?: unknown;
+      shouldPromptAccountIds: boolean;
+    }) => boolean;
+    credentials?: Array<{ id: string; label: string }>;
+    textInputs?: Array<{ id: string; label: string; placeholder?: string }>;
+    onStatusChange?: (params: { cfg: unknown }) => void | Promise<void>;
+    configure?: (params: { cfg: unknown; accountId: string; prompter: unknown; runtime: unknown }) => Promise<unknown>;
+    finalize: (params: { cfg: unknown; accountId: string; prompter: unknown; runtime: unknown }) => Promise<unknown>;
+    enable?: (cfg: unknown) => unknown;
+    disable?: (cfg: unknown) => unknown;
+  }
+
+  export function createStandardChannelSetupStatus(
+    opts: ChannelSetupWizardStatus,
+  ): ChannelSetupWizardStatus;
+
+  export function setSetupChannelEnabled(
+    cfg: unknown,
+    channel: string,
+    enabled: boolean,
+  ): void;
+
+  export const DEFAULT_ACCOUNT_ID: string;
+}
+
+declare module "openclaw/plugin-sdk/setup-tools" {
+  export function formatDocsLink(href: string, text?: string): string;
+}
+
 declare module "openclaw/plugin-sdk/approval-runtime" {
   export interface ExecApprovalReplyMetadata {
     approvalId: string;