@jerryliang122/openclaw-qqbot 1.0.9 → 2.1.0

package/dist/index.d.cts

@@ -203,8 +203,7 @@ interface QQBotAccountConfig {
         sendMode?: 'stream' | 'static';
     };
     /**
-     * STT (语音转文字) 配置
-     * 配置后，收到语音消息时会自动调用 STT 服务转录为文字
+     * STT (语音转文字) 历史遗留配置块（整块被忽略，详见 STTChannelConfig）
      */
     stt?: STTChannelConfig;
     /**
@@ -288,18 +287,21 @@ interface AudioFormatPolicy {
     transcodeEnabled?: boolean;
 }
 /**
- * STT (语音转文字) 配置
+ * STT (语音转文字) 配置块——历史遗留形状
+ *
+ * 2026-10-04 起整块被忽略（含历史行为开关 enabled/asrFallback 与旧凭证
+ * 键）：STT 启停只由框架 `tools.media.models`（capabilities 含 "audio" 的
+ * 条目）+ `tools.media.audio.enabled` 控制。本接口仅为遗留检测
+ * （hasLegacySttConfig + 一次性迁移提示）保留键的类型形状。
  */
 interface STTChannelConfig {
-    /** 是否启用 STT（默认 true，配置了 baseUrl+apiKey 即自动启用） */
-    enabled?: boolean;
-    /** STT 服务提供商 ID（对应 models.providers 中的 key，默认 "openai"） */
+    /** @deprecated 2026-10 起忽略——STT 配置统一走框架 tools.media.models */
     provider?: string;
-    /** STT API 地址（如 https://api.openai.com/v1） */
+    /** @deprecated 同上 */
     baseUrl?: string;
-    /** STT API 密钥 */
+    /** @deprecated 同上 */
     apiKey?: string;
-    /** STT 模型名称（默认 "whisper-1"） */
+    /** @deprecated 同上 */
     model?: string;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jerryliang122/openclaw-qqbot",
-  "version": "1.0.9",
+  "version": "2.1.0",
   "description": "QQ Bot channel plugin for OpenClaw (independently maintained fork)",
   "publishConfig": {
     "access": "public",

package/src/dispatch/body-assembler.ts

@@ -164,10 +164,12 @@ function buildDynamicCtx(
     lines.push(`- Voice: ${voiceRefs.join(', ')}`);
   }
 
-  // ASR：source==='asr' 的 text，或任意 transcript 上的 asrReferText
+  // ASR：仅平台转写来源（source==='asr'）——严格信框架后 stt/fallback
+  // transcript 不再携带 asrReferText
   const asrTexts = unique(
     transcripts
-      .map((t) => (t.source === 'asr' ? t.text : t.asrReferText))
+      .filter((t) => t.source === 'asr')
+      .map((t) => t.text)
       .filter(isNonEmpty),
   );
   if (asrTexts.length > 0) {

package/src/middleware/attachment.ts

@@ -15,7 +15,7 @@ import {
   isVoiceAttachment,
 } from '@tencent-connect/qqbot-nodejs/protocol';
 import type { MessageAttachment } from '../types.js';
-import { transcribeAudio, resolveSTTConfig, shouldUsePlatformAsr } from '../utils/stt.js';
+import { isFrameworkSttConfigured, hasLegacySttConfig, transcribeAudioViaFramework } 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';
@@ -96,8 +96,8 @@ export async function processAttachments(
   cfg: Record<string, unknown>,
   log?: Log,
 ): Promise<ProcessedAttachments> {
-  const sttCfg = resolveSTTConfig(cfg);
-  const usePlatformAsr = shouldUsePlatformAsr(cfg);
+  const sttConfigured = isFrameworkSttConfigured(cfg);
+  warnLegacySttConfig(cfg, log);
   const audioPolicy = resolveAudioPolicy(cfg);
 
   const imageUrls: string[] = [];
@@ -120,7 +120,7 @@ export async function processAttachments(
     }
 
     if (isVoice) {
-      const transcript = await processVoiceAttachment(att, sttCfg, usePlatformAsr, audioPolicy, log);
+      const transcript = await processVoiceAttachment(att, cfg, sttConfigured, audioPolicy, log);
       return { type: 'voice' as const, transcript };
     }
 
@@ -208,39 +208,46 @@ function kindFromContentType(contentType: string | undefined): InboundMediaEntry
 
 // ── 语音处理 ──
 
+/** 废弃 channels.qqbot.stt 配置块的一次性迁移提示（每进程一条，避免每条语音刷屏） */
+let legacySttWarned = false;
+
+function warnLegacySttConfig(cfg: Record<string, unknown>, log?: Log): void {
+  if (!legacySttWarned && hasLegacySttConfig(cfg)) {
+    legacySttWarned = true;
+    log?.info(
+      'Voice: channels.qqbot.stt is deprecated and ignored entirely (credentials + enabled/asrFallback); ' +
+        'configure an audio-capable tools.media.models entry for STT — platform asr_refer_text is used only when framework STT is absent',
+    );
+  }
+}
+
 async function processVoiceAttachment(
   att: MessageAttachment,
-  sttCfg: ReturnType<typeof resolveSTTConfig>,
-  usePlatformAsr: boolean,
+  cfg: Record<string, unknown>,
+  sttConfigured: boolean,
   audioPolicy: AudioPolicyResolved,
   log?: Log,
 ): Promise<VoiceTranscript> {
-  // 平台转写（asr_refer_text）仅在显式 asrFallback: true 时参与；
-  // 缺省/false 时在所有场景下丢弃——包括 STT 未配置（语音落占位文本）
-  // 与 STT 失败（不当兜底），三条泄漏路径（转写成功携带 / 转写失败回退 /
-  // 下载失败回退）一并堵死。
-  const rawAsrText = att.asr_refer_text?.trim() || undefined;
-  const asrReferText = usePlatformAsr ? rawAsrText : undefined;
   // 远端 URL 兜底：优先 wav_url，其次原始 url
   const remoteUrl = normalizeUrl(att.voice_wav_url) || normalizeUrl(att.url) || undefined;
 
-  // STT 未配置：占位文本；显式 asrFallback: true 时退回平台转写
-  if (!sttCfg) {
-    if (!usePlatformAsr && rawAsrText) {
-      log?.info(`Voice: STT not configured; platform asr_refer_text discarded (asrFallback not enabled)`);
-    }
+  // 框架 STT 未配置 → 平台转写（asr_refer_text，QQ 平台自动 STT 随事件
+  // JSON 下发）直接作为唯一来源（无下载、零外部调用）；无平台转写 → 占位。
+  if (!sttConfigured) {
+    const asrReferText = att.asr_refer_text?.trim() || undefined;
     if (asrReferText) {
-      log?.debug?.(`Voice: using asr_refer_text (STT not configured, asrFallback enabled)`);
+      log?.debug?.(`Voice: using platform asr_refer_text (framework STT not configured)`);
       return { text: asrReferText, source: 'asr', asrReferText, remoteUrl };
     }
     return {
       text: '[Voice message - transcription unavailable]',
       source: 'fallback',
-      asrReferText,
       remoteUrl,
     };
   }
 
+  // 框架 STT 已配置 → 严格信框架：下载/转码后提交框架转录，
+  // 失败/为空/下载失败一律占位文本，不回退平台转写。
   let localPath: string | undefined;
   let duration: number | undefined;
 
@@ -281,27 +288,22 @@ async function processVoiceAttachment(
 
   if (localPath) {
     try {
-      const transcript = await transcribeAudio(localPath, cfg2stt(sttCfg));
+      const transcript = await transcribeAudioViaFramework(localPath, cfg);
       if (transcript) {
-        log?.debug?.(`Voice STT: ${transcript.slice(0, 80)}...`);
-        return { text: transcript, source: 'stt', duration, localPath, remoteUrl, asrReferText };
+        log?.debug?.(`Voice STT (framework): ${transcript.slice(0, 80)}...`);
+        return { text: transcript, source: 'stt', duration, localPath, remoteUrl };
       }
     } catch (err) {
-      log?.error(`Voice STT failed: ${err instanceof Error ? err.message : String(err)}`);
+      log?.error(`Voice STT (framework) 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,
   };
 }
 
@@ -334,10 +336,6 @@ function normalizeFormats(formats: string[]): string[] {
   });
 }
 
-function cfg2stt(sttCfg: NonNullable<ReturnType<typeof resolveSTTConfig>>): Record<string, unknown> {
-  return { channels: { qqbot: { stt: sttCfg } } };
-}
-
 // ── 文件工具 ──
 
 function normalizeUrl(url: string | undefined): string {

package/src/types.ts

@@ -211,8 +211,7 @@ export interface QQBotAccountConfig {
     sendMode?: 'stream' | 'static';
   };
   /**
-   * STT (语音转文字) 配置
-   * 配置后，收到语音消息时会自动调用 STT 服务转录为文字
+   * STT (语音转文字) 历史遗留配置块（整块被忽略，详见 STTChannelConfig）
    */
   stt?: STTChannelConfig;
   /**
@@ -300,18 +299,21 @@ export interface AudioFormatPolicy {
 }
 
 /**
- * STT (语音转文字) 配置
+ * STT (语音转文字) 配置块——历史遗留形状
+ *
+ * 2026-10-04 起整块被忽略（含历史行为开关 enabled/asrFallback 与旧凭证
+ * 键）：STT 启停只由框架 `tools.media.models`（capabilities 含 "audio" 的
+ * 条目）+ `tools.media.audio.enabled` 控制。本接口仅为遗留检测
+ * （hasLegacySttConfig + 一次性迁移提示）保留键的类型形状。
  */
 export interface STTChannelConfig {
-  /** 是否启用 STT（默认 true，配置了 baseUrl+apiKey 即自动启用） */
-  enabled?: boolean;
-  /** STT 服务提供商 ID（对应 models.providers 中的 key，默认 "openai"） */
+  /** @deprecated 2026-10 起忽略——STT 配置统一走框架 tools.media.models */
   provider?: string;
-  /** STT API 地址（如 https://api.openai.com/v1） */
+  /** @deprecated 同上 */
   baseUrl?: string;
-  /** STT API 密钥 */
+  /** @deprecated 同上 */
   apiKey?: string;
-  /** STT 模型名称（默认 "whisper-1"） */
+  /** @deprecated 同上 */
   model?: string;
 }
 

package/src/utils/stt.ts

@@ -1,114 +1,88 @@
 /**
- * STT (Speech-to-Text) 语音转文字服务
+ * STT (Speech-to-Text) 语音转文字 — 框架音频理解管线
  *
- * 支持 OpenAI 兼容的 /audio/transcriptions 接口。
- * 配置优先级：
- *   1. channels.qqbot.stt（插件级）
- *   2. 框架级 audio model 配置
+ * 转录统一委托给 openclaw/plugin-sdk/media-understanding-runtime 的
+ * `transcribeAudioFile`（provider 注册表、附件缓存、SSRF 策略与错误语义
+ * 均由框架维护），插件不自带 OpenAI 兼容 HTTP 调用；STT 配置只认框架级
+ * `tools.media.models` 的 audio 能力条目（与内置 telegram 通道一致）。
+ *
+ * 硬编码两分支策略（2026-10-04 起，无插件级开关）：
+ * - 框架 STT 未配置 → QQ 平台转写（asr_refer_text，随事件 JSON 下发）直
+ *   接作为唯一来源（零下载、零外部调用）；无平台转写 → 占位文本。
+ * - 框架 STT 已配置 → 下载语音提交框架转录；**严格信框架**——失败/为空/
+ *   下载失败一律占位文本，不回退平台转写。
  */
-import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { transcribeAudioFile } from 'openclaw/plugin-sdk/media-understanding-runtime';
 
-export interface STTConfig {
-  enabled: boolean;
-  baseUrl: string;
-  apiKey: string;
-  model: string;
-}
+type TranscribeParams = Parameters<typeof transcribeAudioFile>[0];
 
 /**
- * 平台转写（asr_refer_text）参与判定。
- * 仅当显式配置 channels.qqbot.stt.asrFallback: true 时保留平台转写；
- * 缺省、false 或 stt 块整体不存在时一律丢弃——包括 STT 未配置的场景
- * （此时语音消息落占位文本，而不是退回平台转写）。
- * 读取独立于 STT 凭证解析成败：stt 块无凭证但 asrFallback: true 仍生效。
+ * 框架 STT（语音转录）是否可用：
+ * - `tools.media.audio.enabled === false` → 框架级 per-capability 关闭
+ * - `tools.media.models` 无显式 `capabilities` 含 `"audio"` 的条目 → 未配置
+ *
+ * 规范路径是 `tools.media.models`——openclaw 2026.9.1 schema 中模型列表只
+ * 存在于此（`tools.media.audio` 块的类型为 `Omit<…, "models">`，不含
+ * models 键）。**只认显式 `capabilities` 标签**（有意保守）：无标签 CLI
+ * 条目按框架语义本就不参与共享列表的 audio 匹配；无标签 provider 条目框
+ * 架会从 provider 注册表推断能力，但插件侧无法廉价复刻注册表——宁可漏判
+ * （降级走平台转写，功能仍可用）也不误判（严格模式下误判会变成彻底无转
+ * 写）。
+ *
+ * 仅做存在性探测控制流程；provider 解析与实际调用由 transcribeAudioFile
+ * 完成（错误在调用点捕获处理）。
  */
-export function shouldUsePlatformAsr(cfg: Record<string, unknown>): boolean {
-  const channels = asRecord(cfg.channels);
-  const qqbot = asRecord(channels?.qqbot);
-  return asRecord(qqbot?.stt)?.asrFallback === true;
+export function isFrameworkSttConfigured(cfg: Record<string, unknown>): boolean {
+  const tools = asRecord(cfg.tools);
+  const media = asRecord(tools?.media);
+  if (asRecord(media?.audio)?.enabled === false) {
+    return false;
+  }
+  const models = media?.models;
+  if (!Array.isArray(models)) {
+    return false;
+  }
+  return models.some((entry) => {
+    const capabilities = asRecord(entry)?.capabilities;
+    return Array.isArray(capabilities) && capabilities.includes('audio');
+  });
 }
 
 /**
- * 从 OpenClaw 配置中解析 STT 设置
+ * 检测已废弃的 `channels.qqbot.stt` 配置块：旧凭证键
+ * （provider/baseUrl/apiKey/model）与历史行为开关（enabled/asrFallback）。
+ * 2026-10-04 起整块被忽略——STT 启停只由框架 `tools.media.models`（audio
+ * 能力条目）+ `tools.media.audio.enabled` 控制；返回 true 时调用方打一次
+ * 性迁移提示。
  */
-export function resolveSTTConfig(cfg: Record<string, unknown>): STTConfig | null {
+export function hasLegacySttConfig(cfg: Record<string, unknown>): boolean {
   const channels = asRecord(cfg.channels);
   const qqbot = asRecord(channels?.qqbot);
-  const sttCfg = asRecord(qqbot?.stt);
-
-  // 显式禁用
-  if (sttCfg?.enabled === false) {
-    return null;
-  }
-
-  const models = asRecord(cfg.models);
-  const providers = asRecord(models?.providers);
-
-  // 1. 插件级 STT 配置
-  if (sttCfg) {
-    const providerId = readString(sttCfg, 'provider') ?? 'openai';
-    const providerCfg = asRecord(providers?.[providerId]);
-    const baseUrl = readString(sttCfg, 'baseUrl') ?? readString(providerCfg, 'baseUrl');
-    const apiKey = readString(sttCfg, 'apiKey') ?? readString(providerCfg, 'apiKey');
-    const model = readString(sttCfg, 'model') ?? 'whisper-1';
-    if (baseUrl && apiKey) {
-      return { enabled: true, baseUrl: baseUrl.replace(/\/+$/, ''), apiKey, model };
-    }
-  }
-
-  // 2. 框架级 audio model fallback
-  const tools = asRecord(cfg.tools);
-  const media = asRecord(tools?.media);
-  const audio = asRecord(media?.audio);
-  const audioModels = audio?.models;
-  const audioModelEntry = Array.isArray(audioModels) ? asRecord(audioModels[0]) : undefined;
-  if (audioModelEntry) {
-    const providerId = readString(audioModelEntry, 'provider') ?? 'openai';
-    const providerCfg = asRecord(providers?.[providerId]);
-    const baseUrl = readString(audioModelEntry, 'baseUrl') ?? readString(providerCfg, 'baseUrl');
-    const apiKey = readString(audioModelEntry, 'apiKey') ?? readString(providerCfg, 'apiKey');
-    const model = readString(audioModelEntry, 'model') ?? 'whisper-1';
-    if (baseUrl && apiKey) {
-      return { enabled: true, baseUrl: baseUrl.replace(/\/+$/, ''), apiKey, model };
-    }
-  }
-
-  return null;
+  const stt = asRecord(qqbot?.stt);
+  if (!stt) return false;
+  const legacyKeys = ['provider', 'baseUrl', 'apiKey', 'model', 'enabled', 'asrFallback'] as const;
+  return legacyKeys.some((key) => {
+    const value = stt[key];
+    if (typeof value === 'string') return value.trim().length > 0;
+    return value != null;
+  });
 }
 
 /**
- * 调用 STT 服务转录音频文件
+ * 经框架音频理解管线转录本地音频文件。
+ * 返回修剪后的转录文本；无文本返回 null。
+ * provider 缺失/调用失败会抛错，由调用方捕获后输出失败占位文本。
  */
-export async function transcribeAudio(
+export async function transcribeAudioViaFramework(
   audioPath: string,
   cfg: Record<string, unknown>,
 ): Promise<string | null> {
-  const sttCfg = resolveSTTConfig(cfg);
-  if (!sttCfg) {
-    return null;
-  }
-
-  const fileBuffer = fs.readFileSync(audioPath);
-  const fileName = sanitizeFileName(path.basename(audioPath));
-  const mime = guessMimeType(fileName);
-
-  const form = new FormData();
-  form.append('file', new Blob([fileBuffer], { type: mime }), fileName);
-  form.append('model', sttCfg.model);
-
-  const resp = await fetch(`${sttCfg.baseUrl}/audio/transcriptions`, {
-    method: 'POST',
-    headers: { Authorization: `Bearer ${sttCfg.apiKey}` },
-    body: form,
+  const result = await transcribeAudioFile({
+    filePath: audioPath,
+    cfg: cfg as unknown as TranscribeParams['cfg'],
+    mime: guessMimeType(audioPath),
   });
-
-  if (!resp.ok) {
-    const detail = await resp.text().catch(() => '');
-    throw new Error(`STT failed (HTTP ${resp.status}): ${detail.slice(0, 300)}`);
-  }
-
-  const result = (await resp.json()) as { text?: string };
   return result.text?.trim() || null;
 }
 
@@ -121,18 +95,6 @@ function asRecord(value: unknown): Record<string, unknown> | undefined {
   return undefined;
 }
 
-function readString(obj: Record<string, unknown> | undefined, key: string): string | undefined {
-  const val = obj?.[key];
-  if (typeof val === 'string' && val.trim()) {
-    return val.trim();
-  }
-  return undefined;
-}
-
-function sanitizeFileName(name: string): string {
-  return name.replace(/[^a-zA-Z0-9._-]/g, '_');
-}
-
 function guessMimeType(fileName: string): string {
   const ext = path.extname(fileName).toLowerCase();
   const mimeMap: Record<string, string> = {