@jerryliang122/openclaw-qqbot 1.0.9 → 2.1.0

package/README.md

@@ -810,44 +810,36 @@ The plugin processes messages through a carefully ordered middleware chain:
 
 #### STT (Speech-to-Text) — Transcribe Incoming Voice Messages
 
-STT supports two-level configuration with priority fallback:
-
-| Priority | Config Path | Scope |
-|----------|------------|-------|
-| 1 (highest) | `channels.qqbot.stt` | Plugin-specific |
-| 2 (fallback) | `tools.media.audio.models[0]` | Framework-level |
+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
 {
-  "channels": {
-    "qqbot": {
-      "stt": {
-        "provider": "your-provider",
-        "model": "your-stt-model"
-      }
+  "tools": {
+    "media": {
+      "models": [
+        {
+          "type": "cli",
+          "command": "your-asr-cli",
+          "args": ["-m", "your-model", "{{AttachmentPath}}"],
+          "maxBytes": 52428800,
+          "timeoutSeconds": 120,
+          "capabilities": ["audio"]
+        }
+      ]
     }
   }
 }
 ```
 
-- `provider` — references a key in `models.providers` to inherit `baseUrl` and `apiKey`
-- Set `enabled: false` to disable
-- When configured, incoming voice messages are automatically converted (SILK→WAV) and transcribed
-- `asrFallback` — platform ASR (`asr_refer_text`) participation switch. Unless explicitly set to `true`, QQ's built-in platform transcript is **discarded in all cases**: not used as a fallback when your STT fails or returns empty, and not used as the sole source when STT is not configured at all (voice messages then render as `[Voice message - transcription unavailable]`; the audio URL is still referenced via the `- Voice:` line). The flag is read from `channels.qqbot.stt.asrFallback` regardless of whether STT credentials resolve — `stt: { "asrFallback": true }` alone restores the legacy platform-transcript behavior:
+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.
 
-```json
-{
-  "channels": {
-    "qqbot": {
-      "stt": {
-        "provider": "your-provider",
-        "model": "your-stt-model",
-        "asrFallback": true
-      }
-    }
-  }
-}
-```
+Voice message handling order (hardcoded since 2026-10; no plugin-level switches):
+
+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.
+
+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,44 +631,36 @@ openclaw message send --channel "qqbot" \
 
 #### STT（语音转文字）— 自动转录用户发来的语音消息
 
-STT 支持两级配置，按优先级查找：
-
-| 优先级 | 配置路径 | 作用域 |
-|--------|----------|--------|
-| 1（highest） | `channels.qqbot.stt` | 插件专属 |
-| 2（fallback） | `tools.media.audio.models[0]` | 框架级 |
+转录统一走**框架音频理解管线**（`openclaw/plugin-sdk/media-understanding-runtime`），STT 配置只认框架级 `tools.media.models`（与内置 Telegram 通道一致）——插件不再自带 OpenAI 兼容 HTTP 调用：
 
 ```json
 {
-  "channels": {
-    "qqbot": {
-      "stt": {
-        "provider": "your-provider",
-        "model": "your-stt-model"
-      }
+  "tools": {
+    "media": {
+      "models": [
+        {
+          "type": "cli",
+          "command": "your-asr-cli",
+          "args": ["-m", "your-model", "{{AttachmentPath}}"],
+          "maxBytes": 52428800,
+          "timeoutSeconds": 120,
+          "capabilities": ["audio"]
+        }
+      ]
     }
   }
 }
 ```
 
-- `provider` — 引用 `models.providers` 中的 key，自动继承 `baseUrl` 和 `apiKey`
-- 设置 `enabled: false` 可禁用
-- 配置后，用户发来的语音消息会自动转换（SILK→WAV）并转录为文字
-- `asrFallback` — 平台转写（`asr_refer_text`）参与开关。**未显式设为 `true` 时，平台转写在所有场景下都被丢弃**：自有 STT 失败或返回空时不作兜底，STT 未配置时也不作为唯一来源（此时语音消息渲染为 `[Voice message - transcription unavailable]` 占位文本，音频 URL 仍通过 `- Voice:` 行引用）。该开关从 `channels.qqbot.stt.asrFallback` 读取，与 STT 凭证是否解析成功无关——仅写 `stt: { "asrFallback": true }` 即可恢复平台转写参与旧行为：
+也支持 provider 形态（如 `{ "provider": "openai", "model": "whisper-1", "capabilities": ["audio"] }`）。**`capabilities` 必须包含 `"audio"`**——模型列表按能力标签选择，无标签条目不参与语音转录。
 
-```json
-{
-  "channels": {
-    "qqbot": {
-      "stt": {
-        "provider": "your-provider",
-        "model": "your-stt-model",
-        "asrFallback": true
-      }
-    }
-  }
-}
-```
+语音消息处理顺序（2026-10 起硬编码，无插件级开关）：
+
+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:` 行引用。
+
+`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 ? "1.0.9" : "unknown";
+  return true ? "2.1.0" : "unknown";
 }
 function getOpenclawVersion(runtimeVersion) {
   return runtimeVersion && runtimeVersion !== "unknown" ? runtimeVersion : "unknown";
@@ -12904,70 +12904,41 @@ init_webhook_server_node();
 init_webhook_verify();
 
 // src/utils/stt.ts
-var fs18 = __toESM(require("fs"), 1);
 var path16 = __toESM(require("path"), 1);
-function shouldUsePlatformAsr(cfg) {
-  const channels = asRecord(cfg.channels);
-  const qqbot = asRecord(channels?.qqbot);
-  return asRecord(qqbot?.stt)?.asrFallback === true;
-}
-function resolveSTTConfig(cfg) {
-  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);
-  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 };
-    }
-  }
+var import_media_understanding_runtime = require("openclaw/plugin-sdk/media-understanding-runtime");
+function isFrameworkSttConfigured(cfg) {
   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]) : void 0;
-  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 };
-    }
+  if (asRecord(media?.audio)?.enabled === false) {
+    return false;
   }
-  return null;
-}
-async function transcribeAudio(audioPath, cfg) {
-  const sttCfg = resolveSTTConfig(cfg);
-  if (!sttCfg) {
-    return null;
+  const models = media?.models;
+  if (!Array.isArray(models)) {
+    return false;
   }
-  const fileBuffer = fs18.readFileSync(audioPath);
-  const fileName = sanitizeFileName2(path16.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
+  return models.some((entry) => {
+    const capabilities = asRecord(entry)?.capabilities;
+    return Array.isArray(capabilities) && capabilities.includes("audio");
+  });
+}
+function hasLegacySttConfig(cfg) {
+  const channels = asRecord(cfg.channels);
+  const qqbot = asRecord(channels?.qqbot);
+  const stt = asRecord(qqbot?.stt);
+  if (!stt) return false;
+  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)({
+    filePath: audioPath,
+    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();
   return result.text?.trim() || null;
 }
 function asRecord(value) {
@@ -12976,16 +12947,6 @@ function asRecord(value) {
   }
   return void 0;
 }
-function readString(obj, key2) {
-  const val = obj?.[key2];
-  if (typeof val === "string" && val.trim()) {
-    return val.trim();
-  }
-  return void 0;
-}
-function sanitizeFileName2(name) {
-  return name.replace(/[^a-zA-Z0-9._-]/g, "_");
-}
 function guessMimeType(fileName) {
   const ext = path16.extname(fileName).toLowerCase();
   const mimeMap = {
@@ -13061,8 +13022,8 @@ function attachmentProcessor(opts) {
   };
 }
 async function processAttachments(attachments, cfg, log5) {
-  const sttCfg = resolveSTTConfig(cfg);
-  const usePlatformAsr = shouldUsePlatformAsr(cfg);
+  const sttConfigured = isFrameworkSttConfigured(cfg);
+  warnLegacySttConfig(cfg, log5);
   const audioPolicy = resolveAudioPolicy(cfg);
   const imageUrls = [];
   const otherParts = [];
@@ -13080,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, sttCfg, usePlatformAsr, audioPolicy, log5);
+      const transcript = await processVoiceAttachment(att, cfg, sttConfigured, audioPolicy, log5);
       return { type: "voice", transcript };
     }
     if (url) {
@@ -13153,22 +13114,26 @@ function kindFromContentType(contentType) {
   if (contentType?.startsWith("audio/")) return "audio";
   return "document";
 }
-async function processVoiceAttachment(att, sttCfg, usePlatformAsr, audioPolicy, log5) {
-  const rawAsrText = att.asr_refer_text?.trim() || void 0;
-  const asrReferText = usePlatformAsr ? rawAsrText : void 0;
+var legacySttWarned = false;
+function warnLegacySttConfig(cfg, log5) {
+  if (!legacySttWarned && hasLegacySttConfig(cfg)) {
+    legacySttWarned = true;
+    log5?.info(
+      "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, sttConfigured, audioPolicy, log5) {
   const remoteUrl = normalizeUrl(att.voice_wav_url) || normalizeUrl(att.url) || void 0;
-  if (!sttCfg) {
-    if (!usePlatformAsr && rawAsrText) {
-      log5?.info(`Voice: STT not configured; platform asr_refer_text discarded (asrFallback not enabled)`);
-    }
+  if (!sttConfigured) {
+    const asrReferText = att.asr_refer_text?.trim() || void 0;
     if (asrReferText) {
-      log5?.debug?.(`Voice: using asr_refer_text (STT not configured, asrFallback enabled)`);
+      log5?.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
     };
   }
@@ -13209,25 +13174,21 @@ async function processVoiceAttachment(att, sttCfg, usePlatformAsr, audioPolicy,
   }
   if (localPath) {
     try {
-      const transcript = await transcribeAudio(localPath, cfg2stt(sttCfg));
+      const transcript = await transcribeAudioViaFramework(localPath, cfg);
       if (transcript) {
-        log5?.debug?.(`Voice STT: ${transcript.slice(0, 80)}...`);
-        return { text: transcript, source: "stt", duration, localPath, remoteUrl, asrReferText };
+        log5?.debug?.(`Voice STT (framework): ${transcript.slice(0, 80)}...`);
+        return { text: transcript, source: "stt", duration, localPath, remoteUrl };
       }
     } catch (err) {
-      log5?.error(`Voice STT failed: ${err instanceof Error ? err.message : String(err)}`);
+      log5?.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
+    remoteUrl
   };
 }
 function resolveAudioPolicy(cfg) {
@@ -13248,9 +13209,6 @@ function normalizeFormats(formats) {
     return lower.startsWith(".") ? lower : `.${lower}`;
   });
 }
-function cfg2stt(sttCfg) {
-  return { channels: { qqbot: { stt: sttCfg } } };
-}
 function normalizeUrl(url) {
   if (!url) return "";
   return url.startsWith("//") ? `https:${url}` : url;
@@ -13352,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(" | ")}`);
@@ -15891,7 +15849,7 @@ function getQQBotApprovalCapability() {
 
 // src/features/proactive.ts
 init_plugin_logger();
-var fs19 = __toESM(require("fs"), 1);
+var fs18 = __toESM(require("fs"), 1);
 var path20 = __toESM(require("path"), 1);
 init_bot_instance();
 init_config();
@@ -15902,8 +15860,8 @@ var KNOWN_USERS_FILE = path20.join(STORAGE_DIR, "known-users.json");
 var knownUsersCache = null;
 var cacheLastModified = 0;
 function ensureStorageDir() {
-  if (!fs19.existsSync(STORAGE_DIR)) {
-    fs19.mkdirSync(STORAGE_DIR, { recursive: true });
+  if (!fs18.existsSync(STORAGE_DIR)) {
+    fs18.mkdirSync(STORAGE_DIR, { recursive: true });
   }
 }
 function getUserKey(type, openid, accountId) {
@@ -15912,7 +15870,7 @@ function getUserKey(type, openid, accountId) {
 function loadKnownUsers() {
   if (knownUsersCache !== null) {
     try {
-      const stat = fs19.statSync(KNOWN_USERS_FILE);
+      const stat = fs18.statSync(KNOWN_USERS_FILE);
       if (stat.mtimeMs <= cacheLastModified) {
         return knownUsersCache;
       }
@@ -15922,14 +15880,14 @@ function loadKnownUsers() {
   }
   const users = /* @__PURE__ */ new Map();
   try {
-    if (fs19.existsSync(KNOWN_USERS_FILE)) {
-      const data = fs19.readFileSync(KNOWN_USERS_FILE, "utf-8");
+    if (fs18.existsSync(KNOWN_USERS_FILE)) {
+      const data = fs18.readFileSync(KNOWN_USERS_FILE, "utf-8");
       const parsed = JSON.parse(data);
       for (const user of parsed) {
         const key2 = getUserKey(user.type, user.openid, user.accountId);
         users.set(key2, user);
       }
-      cacheLastModified = fs19.statSync(KNOWN_USERS_FILE).mtimeMs;
+      cacheLastModified = fs18.statSync(KNOWN_USERS_FILE).mtimeMs;
     }
   } catch (err) {
     log3.error(`Failed to load known users: ${err}`);
@@ -15941,7 +15899,7 @@ function saveKnownUsers(users) {
   try {
     ensureStorageDir();
     const data = Array.from(users.values());
-    fs19.writeFileSync(KNOWN_USERS_FILE, JSON.stringify(data, null, 2), "utf-8");
+    fs18.writeFileSync(KNOWN_USERS_FILE, JSON.stringify(data, null, 2), "utf-8");
     cacheLastModified = Date.now();
     knownUsersCache = users;
   } catch (err) {