@jerryliang122/openclaw-qqbot 2.0.0 → 2.1.0

package/README.md

@@ -810,31 +810,36 @@ The plugin processes messages through a carefully ordered middleware chain:
 
 #### STT (Speech-to-Text) — Transcribe Incoming Voice Messages
 
-Transcription runs through the **framework audio-understanding pipeline** (`openclaw/plugin-sdk/media-understanding-runtime`), so STT credentials come from the framework-level config (same as the built-in Telegram channel) — the plugin no longer ships its own OpenAI-compatible HTTP call:
+Transcription runs through the **framework audio-understanding pipeline** (`openclaw/plugin-sdk/media-understanding-runtime`), so STT config comes from the framework-level `tools.media.models` (same as the built-in Telegram channel) — the plugin no longer ships its own OpenAI-compatible HTTP call:
 
 ```json
 {
   "tools": {
     "media": {
-      "audio": {
-        "models": [{ "provider": "your-provider", "model": "your-stt-model" }]
-      }
+      "models": [
+        {
+          "type": "cli",
+          "command": "your-asr-cli",
+          "args": ["-m", "your-model", "{{AttachmentPath}}"],
+          "maxBytes": 52428800,
+          "timeoutSeconds": 120,
+          "capabilities": ["audio"]
+        }
+      ]
     }
   }
 }
 ```
 
-Voice message handling order:
+A provider-form entry also works (e.g. `{ "provider": "openai", "model": "whisper-1", "capabilities": ["audio"] }`). **`capabilities` must include `"audio"`** — the shared model list is selected by capability tags; untagged entries never take part in voice transcription.
 
-1. **Framework STT configured** (`tools.media.audio.models` non-empty) → voice is downloaded, converted (SILK→WAV), and transcribed through the framework pipeline. On failure or empty transcript, falls back to the platform transcript.
-2. **Framework STT not configured** → the **QQ platform transcript (`asr_refer_text`)** — QQ auto-STTs voice messages and ships the text in the event JSON — is used directly as the sole source, no download and no external call needed.
-3. Neither available → placeholder text (`[Voice message - transcription unavailable]`); the audio URL is still referenced via the `- Voice:` line.
+Voice message handling order (hardcoded since 2026-10; no plugin-level switches):
 
-Plugin-level behavior switches under `channels.qqbot.stt`:
+1. **Framework STT configured** (a `tools.media.models` entry whose `capabilities` includes `"audio"`) → voice is downloaded, converted (SILK→WAV), and transcribed through the framework pipeline. **The framework is trusted strictly** — on failure or empty transcript a placeholder (`[Voice message - transcription failed]`) is emitted; there is **no** fallback to the platform transcript.
+2. **Framework STT not configured** → the **QQ platform transcript (`asr_refer_text`)** — QQ auto-STTs voice messages and ships the text in the event JSON — is used directly as the sole source, no download and no external call needed.
+3. Not configured and no platform transcript → placeholder text (`[Voice message - transcription unavailable]`); the audio URL is still referenced via the `- Voice:` line.
 
-- `enabled: false` — never call external STT; use only the platform transcript (or the placeholder)
-- `asrFallback: false` — strict mode: discard the platform transcript in **all** cases (restores the pre-2026-10 behavior)
-- `provider` / `baseUrl` / `apiKey` / `model` — **deprecated and ignored** (2026-10); a one-time migration notice is logged if still present. Move credentials to `tools.media.audio.models`.
+The whole `channels.qqbot.stt` block is **deprecated and ignored** (legacy credential keys plus the historical `enabled`/`asrFallback` switches, removed 2026-10-04); a one-time migration notice is logged if any key is present. STT is controlled solely by the framework config — remove the audio entry from `tools.media.models` (or set `tools.media.audio.enabled: false`) to disable framework transcription.
 
 #### TTS (Text-to-Speech) — Send Voice Messages
 

package/README.zh.md

@@ -631,31 +631,36 @@ openclaw message send --channel "qqbot" \
 
 #### STT（语音转文字）— 自动转录用户发来的语音消息
 
-转录统一走**框架音频理解管线**（`openclaw/plugin-sdk/media-understanding-runtime`），STT 凭证只认框架级配置（与内置 Telegram 通道一致）——插件不再自带 OpenAI 兼容 HTTP 调用：
+转录统一走**框架音频理解管线**（`openclaw/plugin-sdk/media-understanding-runtime`），STT 配置只认框架级 `tools.media.models`（与内置 Telegram 通道一致）——插件不再自带 OpenAI 兼容 HTTP 调用：
 
 ```json
 {
   "tools": {
     "media": {
-      "audio": {
-        "models": [{ "provider": "your-provider", "model": "your-stt-model" }]
-      }
+      "models": [
+        {
+          "type": "cli",
+          "command": "your-asr-cli",
+          "args": ["-m", "your-model", "{{AttachmentPath}}"],
+          "maxBytes": 52428800,
+          "timeoutSeconds": 120,
+          "capabilities": ["audio"]
+        }
+      ]
     }
   }
 }
 ```
 
-语音消息处理顺序：
+也支持 provider 形态（如 `{ "provider": "openai", "model": "whisper-1", "capabilities": ["audio"] }`）。**`capabilities` 必须包含 `"audio"`**——模型列表按能力标签选择，无标签条目不参与语音转录。
 
-1. **框架 STT 已配置**（`tools.media.audio.models` 非空）→ 下载语音、转换（SILK→WAV）后经框架管线转录；转录失败或为空时兜底用平台转写。
-2. **框架 STT 未配置** → **直接采用 QQ 平台转写**（`asr_refer_text`，QQ 平台对语音消息自动 STT 并随事件 JSON 下发）作为唯一来源——无需下载、不发起任何外部调用。
-3. 两者都不可用 → 占位文本（`[Voice message - transcription unavailable]`），音频 URL 仍通过 `- Voice:` 行引用。
+语音消息处理顺序（2026-10 起硬编码，无插件级开关）：
 
-`channels.qqbot.stt` 下仅保留行为开关：
+1. **框架 STT 已配置**（`tools.media.models` 存在 `capabilities` 含 `"audio"` 的条目）→ 下载语音、转换（SILK→WAV）后经框架管线转录；**严格信框架**——转录失败或为空时输出占位文本（`[Voice message - transcription failed]`），不回退平台转写。
+2. **框架 STT 未配置** → **直接采用 QQ 平台转写**（`asr_refer_text`，QQ 平台对语音消息自动 STT 并随事件 JSON 下发）作为唯一来源——无需下载、不发起任何外部调用。
+3. 未配置且无平台转写 → 占位文本（`[Voice message - transcription unavailable]`），音频 URL 仍通过 `- Voice:` 行引用。
 
-- `enabled: false` — 不调用外部 STT，语音只用平台转写（或无转写时占位文本）
-- `asrFallback: false` — 严格模式：所有场景丢弃平台转写（恢复 2026-10 之前的旧行为）
-- `provider` / `baseUrl` / `apiKey` / `model` — **已废弃并被忽略**（2026-10）；检测到仍配置时会打一次性迁移提示日志，请把凭证迁移到 `tools.media.audio.models`。
+`channels.qqbot.stt` 整块**已废弃并被忽略**（旧凭证键 + 历史 `enabled`/`asrFallback` 开关，2026-10-04 移除）；检测到任何键时会打一次性迁移提示日志。STT 启停只由框架配置控制——删掉 `tools.media.models` 的 audio 条目、或设 `tools.media.audio.enabled: false` 即关闭框架转录。
 
 #### TTS（文字转语音）— 机器人发送语音消息
 

package/dist/index.cjs

@@ -8259,7 +8259,7 @@ var init_outbound_service = __esm({
 
 // src/utils/pkg-version.ts
 function getPackageVersion() {
-  return true ? "2.0.0" : "unknown";
+  return true ? "2.1.0" : "unknown";
 }
 function getOpenclawVersion(runtimeVersion) {
   return runtimeVersion && runtimeVersion !== "unknown" ? runtimeVersion : "unknown";
@@ -12906,33 +12906,32 @@ init_webhook_verify();
 // src/utils/stt.ts
 var path16 = __toESM(require("path"), 1);
 var import_media_understanding_runtime = require("openclaw/plugin-sdk/media-understanding-runtime");
-function shouldUsePlatformAsr(cfg) {
-  const channels = asRecord(cfg.channels);
-  const qqbot = asRecord(channels?.qqbot);
-  return asRecord(qqbot?.stt)?.asrFallback !== false;
-}
 function isFrameworkSttConfigured(cfg) {
-  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");
+  });
 }
-function hasLegacySttCredentials(cfg) {
+function hasLegacySttConfig(cfg) {
   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(
-    (key2) => typeof stt[key2] === "string" && stt[key2].trim().length > 0
-  );
+  const legacyKeys = ["provider", "baseUrl", "apiKey", "model", "enabled", "asrFallback"];
+  return legacyKeys.some((key2) => {
+    const value = stt[key2];
+    if (typeof value === "string") return value.trim().length > 0;
+    return value != null;
+  });
 }
 async function transcribeAudioViaFramework(audioPath, cfg) {
   const result = await (0, import_media_understanding_runtime.transcribeAudioFile)({
@@ -13023,9 +13022,8 @@ function attachmentProcessor(opts) {
   };
 }
 async function processAttachments(attachments, cfg, log5) {
-  const usePlatformAsr = shouldUsePlatformAsr(cfg);
   const sttConfigured = isFrameworkSttConfigured(cfg);
-  warnLegacySttCredentials(cfg, log5);
+  warnLegacySttConfig(cfg, log5);
   const audioPolicy = resolveAudioPolicy(cfg);
   const imageUrls = [];
   const otherParts = [];
@@ -13043,7 +13041,7 @@ async function processAttachments(attachments, cfg, log5) {
       return { type: "image", localPath, url, contentType: att.content_type ?? "image/png", filename: att.filename };
     }
     if (isVoice) {
-      const transcript = await processVoiceAttachment(att, cfg, usePlatformAsr, sttConfigured, audioPolicy, log5);
+      const transcript = await processVoiceAttachment(att, cfg, sttConfigured, audioPolicy, log5);
       return { type: "voice", transcript };
     }
     if (url) {
@@ -13117,22 +13115,18 @@ function kindFromContentType(contentType) {
   return "document";
 }
 var legacySttWarned = false;
-function warnLegacySttCredentials(cfg, log5) {
-  if (!legacySttWarned && hasLegacySttCredentials(cfg)) {
+function warnLegacySttConfig(cfg, log5) {
+  if (!legacySttWarned && hasLegacySttConfig(cfg)) {
     legacySttWarned = true;
     log5?.info(
-      "Voice: channels.qqbot.stt credentials (provider/baseUrl/apiKey/model) are deprecated and ignored; configure tools.media.audio.models instead \u2014 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 \u2014 platform asr_refer_text is used only when framework STT is absent"
     );
   }
 }
-async function processVoiceAttachment(att, cfg, usePlatformAsr, sttConfigured, audioPolicy, log5) {
-  const rawAsrText = att.asr_refer_text?.trim() || void 0;
-  const asrReferText = usePlatformAsr ? rawAsrText : void 0;
+async function processVoiceAttachment(att, cfg, sttConfigured, audioPolicy, log5) {
   const remoteUrl = normalizeUrl(att.voice_wav_url) || normalizeUrl(att.url) || void 0;
   if (!sttConfigured) {
-    if (!usePlatformAsr && rawAsrText) {
-      log5?.info(`Voice: framework STT not configured; platform asr_refer_text discarded (asrFallback: false)`);
-    }
+    const asrReferText = att.asr_refer_text?.trim() || void 0;
     if (asrReferText) {
       log5?.debug?.(`Voice: using platform asr_refer_text (framework STT not configured)`);
       return { text: asrReferText, source: "asr", asrReferText, remoteUrl };
@@ -13140,7 +13134,6 @@ async function processVoiceAttachment(att, cfg, usePlatformAsr, sttConfigured, a
     return {
       text: "[Voice message - transcription unavailable]",
       source: "fallback",
-      asrReferText,
       remoteUrl
     };
   }
@@ -13184,23 +13177,18 @@ async function processVoiceAttachment(att, cfg, usePlatformAsr, sttConfigured, a
       const transcript = await transcribeAudioViaFramework(localPath, cfg);
       if (transcript) {
         log5?.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) {
       log5?.error(`Voice STT (framework) failed: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
-  if (asrReferText) {
-    log5?.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
+    remoteUrl
   };
 }
 function resolveAudioPolicy(cfg) {
@@ -13322,7 +13310,7 @@ function buildDynamicCtx(processed, msg, quote) {
     lines.push(`- Voice: ${voiceRefs.join(", ")}`);
   }
   const asrTexts = unique(
-    transcripts.map((t) => t.source === "asr" ? t.text : t.asrReferText).filter(isNonEmpty)
+    transcripts.filter((t) => t.source === "asr").map((t) => t.text).filter(isNonEmpty)
   );
   if (asrTexts.length > 0) {
     lines.push(`- ASR: ${asrTexts.join(" | ")}`);