@jerryliang122/openclaw-qqbot 2.0.0 → 2.1.0

package/dist/index.d.cts

@@ -203,9 +203,7 @@ interface QQBotAccountConfig {
         sendMode?: 'stream' | 'static';
     };
     /**
-     * STT (语音转文字) 行为开关
-     * 转录凭证统一走框架 tools.media.audio.models；
-     * 框架未配置时直接使用 QQ 平台转写（asr_refer_text）
+     * STT (语音转文字) 历史遗留配置块（整块被忽略，详见 STTChannelConfig）
      */
     stt?: STTChannelConfig;
     /**
@@ -289,25 +287,15 @@ interface AudioFormatPolicy {
     transcodeEnabled?: boolean;
 }
 /**
- * STT (语音转文字) 配置
+ * STT (语音转文字) 配置块——历史遗留形状
  *
- * 2026-10 起转录统一走框架音频理解管线（tools.media.audio.models 凭证），
- * 本块只保留行为开关；旧凭证键已废弃（检测到会打迁移提示日志）。
- * 框架 STT 未配置时，QQ 平台转写（asr_refer_text）直接作为唯一来源。
+ * 2026-10-04 起整块被忽略（含历史行为开关 enabled/asrFallback 与旧凭证
+ * 键）：STT 启停只由框架 `tools.media.models`（capabilities 含 "audio" 的
+ * 条目）+ `tools.media.audio.enabled` 控制。本接口仅为遗留检测
+ * （hasLegacySttConfig + 一次性迁移提示）保留键的类型形状。
  */
 interface STTChannelConfig {
-    /**
-     * 是否启用框架 STT 转录（默认 true）。
-     * false = 不调用外部 STT，语音只用平台转写（或无转写时占位文本）。
-     */
-    enabled?: boolean;
-    /**
-     * 平台转写（asr_refer_text）参与开关。默认参与：
-     * 框架 STT 未配置时直接作为唯一来源，STT 失败/为空时兜底。
-     * 设为 false 恢复严格模式——所有场景丢弃平台转写。
-     */
-    asrFallback?: boolean;
-    /** @deprecated 2026-10 起忽略——STT 凭证统一配置在框架 tools.media.audio.models */
+    /** @deprecated 2026-10 起忽略——STT 配置统一走框架 tools.media.models */
     provider?: string;
     /** @deprecated 同上 */
     baseUrl?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jerryliang122/openclaw-qqbot",
-  "version": "2.0.0",
+  "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 { shouldUsePlatformAsr, isFrameworkSttConfigured, hasLegacySttCredentials, transcribeAudioViaFramework } 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,9 +96,8 @@ export async function processAttachments(
   cfg: Record<string, unknown>,
   log?: Log,
 ): Promise<ProcessedAttachments> {
-  const usePlatformAsr = shouldUsePlatformAsr(cfg);
   const sttConfigured = isFrameworkSttConfigured(cfg);
-  warnLegacySttCredentials(cfg, log);
+  warnLegacySttConfig(cfg, log);
   const audioPolicy = resolveAudioPolicy(cfg);
 
   const imageUrls: string[] = [];
@@ -121,7 +120,7 @@ export async function processAttachments(
     }
 
     if (isVoice) {
-      const transcript = await processVoiceAttachment(att, cfg, usePlatformAsr, sttConfigured, audioPolicy, log);
+      const transcript = await processVoiceAttachment(att, cfg, sttConfigured, audioPolicy, log);
       return { type: 'voice' as const, transcript };
     }
 
@@ -209,15 +208,15 @@ function kindFromContentType(contentType: string | undefined): InboundMediaEntry
 
 // ── 语音处理 ──
 
-/** 废弃插件级 STT 凭证的一次性迁移提示（每进程一条，避免每条语音刷屏） */
+/** 废弃 channels.qqbot.stt 配置块的一次性迁移提示（每进程一条，避免每条语音刷屏） */
 let legacySttWarned = false;
 
-function warnLegacySttCredentials(cfg: Record<string, unknown>, log?: Log): void {
-  if (!legacySttWarned && hasLegacySttCredentials(cfg)) {
+function warnLegacySttConfig(cfg: Record<string, unknown>, log?: Log): void {
+  if (!legacySttWarned && hasLegacySttConfig(cfg)) {
     legacySttWarned = true;
     log?.info(
-      'Voice: channels.qqbot.stt credentials (provider/baseUrl/apiKey/model) are deprecated and ignored; ' +
-        'configure tools.media.audio.models instead — platform asr_refer_text is used when framework STT is absent',
+      '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',
     );
   }
 }
@@ -225,24 +224,17 @@ function warnLegacySttCredentials(cfg: Record<string, unknown>, log?: Log): void
 async function processVoiceAttachment(
   att: MessageAttachment,
   cfg: Record<string, unknown>,
-  usePlatformAsr: boolean,
   sttConfigured: boolean,
   audioPolicy: AudioPolicyResolved,
   log?: Log,
 ): Promise<VoiceTranscript> {
-  // 平台转写（asr_refer_text，QQ 平台自动 STT 随事件 JSON 下发）：
-  // 默认参与——框架 STT 未配置时直接作为唯一来源，STT 失败时兜底；
-  // 仅 asrFallback: false（严格模式）时在所有场景丢弃。
-  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 未配置 → 平台转写直接作为 transcript（无下载、无外部调用）
+  // 框架 STT 未配置 → 平台转写（asr_refer_text，QQ 平台自动 STT 随事件
+  // JSON 下发）直接作为唯一来源（无下载、零外部调用）；无平台转写 → 占位。
   if (!sttConfigured) {
-    if (!usePlatformAsr && rawAsrText) {
-      log?.info(`Voice: framework STT not configured; platform asr_refer_text discarded (asrFallback: false)`);
-    }
+    const asrReferText = att.asr_refer_text?.trim() || undefined;
     if (asrReferText) {
       log?.debug?.(`Voice: using platform asr_refer_text (framework STT not configured)`);
       return { text: asrReferText, source: 'asr', asrReferText, remoteUrl };
@@ -250,11 +242,12 @@ async function processVoiceAttachment(
     return {
       text: '[Voice message - transcription unavailable]',
       source: 'fallback',
-      asrReferText,
       remoteUrl,
     };
   }
 
+  // 框架 STT 已配置 → 严格信框架：下载/转码后提交框架转录，
+  // 失败/为空/下载失败一律占位文本，不回退平台转写。
   let localPath: string | undefined;
   let duration: number | undefined;
 
@@ -298,25 +291,19 @@ async function processVoiceAttachment(
       const transcript = await transcribeAudioViaFramework(localPath, cfg);
       if (transcript) {
         log?.debug?.(`Voice STT (framework): ${transcript.slice(0, 80)}...`);
-        return { text: transcript, source: 'stt', duration, localPath, remoteUrl, asrReferText };
+        return { text: transcript, source: 'stt', duration, localPath, remoteUrl };
       }
     } catch (err) {
       log?.error(`Voice STT (framework) failed: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
 
-  if (asrReferText) {
-    log?.debug?.(`Voice: falling back to platform asr_refer_text after framework STT failure`);
-    return { text: asrReferText, source: 'asr', duration, localPath, remoteUrl, asrReferText };
-  }
-
   return {
     text: '[Voice message - transcription failed]',
     source: 'fallback',
     duration,
     localPath,
     remoteUrl,
-    asrReferText,
   };
 }
 

package/src/types.ts

@@ -211,9 +211,7 @@ export interface QQBotAccountConfig {
     sendMode?: 'stream' | 'static';
   };
   /**
-   * STT (语音转文字) 行为开关
-   * 转录凭证统一走框架 tools.media.audio.models；
-   * 框架未配置时直接使用 QQ 平台转写（asr_refer_text）
+   * STT (语音转文字) 历史遗留配置块（整块被忽略，详见 STTChannelConfig）
    */
   stt?: STTChannelConfig;
   /**
@@ -301,25 +299,15 @@ export interface AudioFormatPolicy {
 }
 
 /**
- * STT (语音转文字) 配置
+ * STT (语音转文字) 配置块——历史遗留形状
  *
- * 2026-10 起转录统一走框架音频理解管线（tools.media.audio.models 凭证），
- * 本块只保留行为开关；旧凭证键已废弃（检测到会打迁移提示日志）。
- * 框架 STT 未配置时，QQ 平台转写（asr_refer_text）直接作为唯一来源。
+ * 2026-10-04 起整块被忽略（含历史行为开关 enabled/asrFallback 与旧凭证
+ * 键）：STT 启停只由框架 `tools.media.models`（capabilities 含 "audio" 的
+ * 条目）+ `tools.media.audio.enabled` 控制。本接口仅为遗留检测
+ * （hasLegacySttConfig + 一次性迁移提示）保留键的类型形状。
  */
 export interface STTChannelConfig {
-  /**
-   * 是否启用框架 STT 转录（默认 true）。
-   * false = 不调用外部 STT，语音只用平台转写（或无转写时占位文本）。
-   */
-  enabled?: boolean;
-  /**
-   * 平台转写（asr_refer_text）参与开关。默认参与：
-   * 框架 STT 未配置时直接作为唯一来源，STT 失败/为空时兜底。
-   * 设为 false 恢复严格模式——所有场景丢弃平台转写。
-   */
-  asrFallback?: boolean;
-  /** @deprecated 2026-10 起忽略——STT 凭证统一配置在框架 tools.media.audio.models */
+  /** @deprecated 2026-10 起忽略——STT 配置统一走框架 tools.media.models */
   provider?: string;
   /** @deprecated 同上 */
   baseUrl?: string;

package/src/utils/stt.ts

@@ -3,13 +3,14 @@
  *
  * 转录统一委托给 openclaw/plugin-sdk/media-understanding-runtime 的
  * `transcribeAudioFile`（provider 注册表、附件缓存、SSRF 策略与错误语义
- * 均由框架维护），插件不再自带 OpenAI 兼容 HTTP 调用；STT 凭证只认
- * 框架级 `tools.media.audio.models` 配置（与内置 telegram 通道一致）。
+ * 均由框架维护），插件不自带 OpenAI 兼容 HTTP 调用；STT 配置只认框架级
+ * `tools.media.models` 的 audio 能力条目（与内置 telegram 通道一致）。
  *
- * 平台转写（asr_refer_text）：QQ 平台对语音消息自动 STT 并随事件 JSON 下发。
- * 默认策略——框架 STT 未配置时**直接采用平台转写**；已配置时平台转写作为
- * 自有转录失败/为空的兜底。`channels.qqbot.stt.asrFallback: false` 可整体
- * 禁用平台转写（严格模式，恢复 2026-08-17 的丢弃行为）。
+ * 硬编码两分支策略（2026-10-04 起，无插件级开关）：
+ * - 框架 STT 未配置 → QQ 平台转写（asr_refer_text，随事件 JSON 下发）直
+ *   接作为唯一来源（零下载、零外部调用）；无平台转写 → 占位文本。
+ * - 框架 STT 已配置 → 下载语音提交框架转录；**严格信框架**——失败/为空/
+ *   下载失败一律占位文本，不回退平台转写。
  */
 import * as path from 'node:path';
 import { transcribeAudioFile } from 'openclaw/plugin-sdk/media-understanding-runtime';
@@ -17,57 +18,61 @@ import { transcribeAudioFile } from 'openclaw/plugin-sdk/media-understanding-run
 type TranscribeParams = Parameters<typeof transcribeAudioFile>[0];
 
 /**
- * 平台转写（asr_refer_text）是否参与（独立于框架 STT 配置读取）。
- * 默认 true；显式 `channels.qqbot.stt.asrFallback: false` 时关闭（严格模式）。
- */
-export function shouldUsePlatformAsr(cfg: Record<string, unknown>): boolean {
-  const channels = asRecord(cfg.channels);
-  const qqbot = asRecord(channels?.qqbot);
-  return asRecord(qqbot?.stt)?.asrFallback !== false;
-}
-
-/**
- * 框架 STT（tools.media.audio）是否可用：
- * - `channels.qqbot.stt.enabled === false` → 插件级显式关闭（只用平台转写）
- * - `tools.media.audio.enabled === false` → 框架级关闭
- * - `models` 为空 → 未配置
+ * 框架 STT（语音转录）是否可用：
+ * - `tools.media.audio.enabled === false` → 框架级 per-capability 关闭
+ * - `tools.media.models` 无显式 `capabilities` 含 `"audio"` 的条目 → 未配置
  *
- * 仅做存在性探测控制流程；provider 解析与实际调用由 transcribeAudioFile 完成。
+ * 规范路径是 `tools.media.models`——openclaw 2026.9.1 schema 中模型列表只
+ * 存在于此（`tools.media.audio` 块的类型为 `Omit<…, "models">`，不含
+ * models 键）。**只认显式 `capabilities` 标签**（有意保守）：无标签 CLI
+ * 条目按框架语义本就不参与共享列表的 audio 匹配；无标签 provider 条目框
+ * 架会从 provider 注册表推断能力，但插件侧无法廉价复刻注册表——宁可漏判
+ * （降级走平台转写，功能仍可用）也不误判（严格模式下误判会变成彻底无转
+ * 写）。
+ *
+ * 仅做存在性探测控制流程；provider 解析与实际调用由 transcribeAudioFile
+ * 完成（错误在调用点捕获处理）。
  */
 export function isFrameworkSttConfigured(cfg: Record<string, unknown>): boolean {
-  const channels = asRecord(cfg.channels);
-  const qqbot = asRecord(channels?.qqbot);
-  if (asRecord(qqbot?.stt)?.enabled === false) {
-    return false;
-  }
   const tools = asRecord(cfg.tools);
   const media = asRecord(tools?.media);
-  const audio = asRecord(media?.audio);
-  if (!audio || audio.enabled === false) {
+  if (asRecord(media?.audio)?.enabled === false) {
     return false;
   }
-  return Array.isArray(audio.models) && audio.models.length > 0;
+  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');
+  });
 }
 
 /**
- * 检测已废弃的插件级 STT 凭证（channels.qqbot.stt.provider/baseUrl/apiKey/model）。
- * 2026-10 起凭证统一走框架 `tools.media.audio.models`，旧键被忽略；
- * 返回 true 时调用方打一次性迁移提示。
+ * 检测已废弃的 `channels.qqbot.stt` 配置块：旧凭证键
+ * （provider/baseUrl/apiKey/model）与历史行为开关（enabled/asrFallback）。
+ * 2026-10-04 起整块被忽略——STT 启停只由框架 `tools.media.models`（audio
+ * 能力条目）+ `tools.media.audio.enabled` 控制；返回 true 时调用方打一次
+ * 性迁移提示。
  */
-export function hasLegacySttCredentials(cfg: Record<string, unknown>): boolean {
+export function hasLegacySttConfig(cfg: Record<string, unknown>): boolean {
   const channels = asRecord(cfg.channels);
   const qqbot = asRecord(channels?.qqbot);
   const stt = asRecord(qqbot?.stt);
   if (!stt) return false;
-  return ['provider', 'baseUrl', 'apiKey', 'model'].some(
-    (key) => typeof stt[key] === 'string' && (stt[key] as string).trim().length > 0,
-  );
+  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;
+  });
 }
 
 /**
  * 经框架音频理解管线转录本地音频文件。
  * 返回修剪后的转录文本；无文本返回 null。
- * provider 缺失/调用失败会抛错，由调用方捕获后走平台转写兜底。
+ * provider 缺失/调用失败会抛错，由调用方捕获后输出失败占位文本。
  */
 export async function transcribeAudioViaFramework(
   audioPath: string,