@jerryliang122/openclaw-qqbot 1.0.9 → 2.0.0

package/README.md

@@ -810,44 +810,31 @@ 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 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:
 
 ```json
 {
-  "channels": {
-    "qqbot": {
-      "stt": {
-        "provider": "your-provider",
-        "model": "your-stt-model"
+  "tools": {
+    "media": {
+      "audio": {
+        "models": [{ "provider": "your-provider", "model": "your-stt-model" }]
       }
     }
   }
 }
 ```
 
-- `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:
+Voice message handling order:
 
-```json
-{
-  "channels": {
-    "qqbot": {
-      "stt": {
-        "provider": "your-provider",
-        "model": "your-stt-model",
-        "asrFallback": true
-      }
-    }
-  }
-}
-```
+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.
+
+Plugin-level behavior switches under `channels.qqbot.stt`:
+
+- `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`.
 
 #### TTS (Text-to-Speech) — Send Voice Messages
 

package/README.zh.md

@@ -631,44 +631,31 @@ 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 凭证只认框架级配置（与内置 Telegram 通道一致）——插件不再自带 OpenAI 兼容 HTTP 调用：
 
 ```json
 {
-  "channels": {
-    "qqbot": {
-      "stt": {
-        "provider": "your-provider",
-        "model": "your-stt-model"
+  "tools": {
+    "media": {
+      "audio": {
+        "models": [{ "provider": "your-provider", "model": "your-stt-model" }]
       }
     }
   }
 }
 ```
 
-- `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 }` 即可恢复平台转写参与旧行为：
+语音消息处理顺序：
 
-```json
-{
-  "channels": {
-    "qqbot": {
-      "stt": {
-        "provider": "your-provider",
-        "model": "your-stt-model",
-        "asrFallback": true
-      }
-    }
-  }
-}
-```
+1. **框架 STT 已配置**（`tools.media.audio.models` 非空）→ 下载语音、转换（SILK→WAV）后经框架管线转录；转录失败或为空时兜底用平台转写。
+2. **框架 STT 未配置** → **直接采用 QQ 平台转写**（`asr_refer_text`，QQ 平台对语音消息自动 STT 并随事件 JSON 下发）作为唯一来源——无需下载、不发起任何外部调用。
+3. 两者都不可用 → 占位文本（`[Voice message - transcription unavailable]`），音频 URL 仍通过 `- Voice:` 行引用。
+
+`channels.qqbot.stt` 下仅保留行为开关：
+
+- `enabled: false` — 不调用外部 STT，语音只用平台转写（或无转写时占位文本）
+- `asrFallback: false` — 严格模式：所有场景丢弃平台转写（恢复 2026-10 之前的旧行为）
+- `provider` / `baseUrl` / `apiKey` / `model` — **已废弃并被忽略**（2026-10）；检测到仍配置时会打一次性迁移提示日志，请把凭证迁移到 `tools.media.audio.models`。
 
 #### 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.0.0" : "unknown";
 }
 function getOpenclawVersion(runtimeVersion) {
   return runtimeVersion && runtimeVersion !== "unknown" ? runtimeVersion : "unknown";
@@ -12904,70 +12904,42 @@ init_webhook_server_node();
 init_webhook_verify();
 
 // src/utils/stt.ts
-var fs18 = __toESM(require("fs"), 1);
 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 === true;
+  return asRecord(qqbot?.stt)?.asrFallback !== false;
 }
-function resolveSTTConfig(cfg) {
+function isFrameworkSttConfigured(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 };
-    }
+  if (asRecord(qqbot?.stt)?.enabled === false) {
+    return false;
   }
   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 (!audio || audio.enabled === false) {
+    return false;
   }
-  return null;
+  return Array.isArray(audio.models) && audio.models.length > 0;
 }
-async function transcribeAudio(audioPath, cfg) {
-  const sttCfg = resolveSTTConfig(cfg);
-  if (!sttCfg) {
-    return null;
-  }
-  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
+function hasLegacySttCredentials(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
+  );
+}
+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 +12948,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 +13023,9 @@ function attachmentProcessor(opts) {
   };
 }
 async function processAttachments(attachments, cfg, log5) {
-  const sttCfg = resolveSTTConfig(cfg);
   const usePlatformAsr = shouldUsePlatformAsr(cfg);
+  const sttConfigured = isFrameworkSttConfigured(cfg);
+  warnLegacySttCredentials(cfg, log5);
   const audioPolicy = resolveAudioPolicy(cfg);
   const imageUrls = [];
   const otherParts = [];
@@ -13080,7 +13043,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, usePlatformAsr, sttConfigured, audioPolicy, log5);
       return { type: "voice", transcript };
     }
     if (url) {
@@ -13153,16 +13116,25 @@ function kindFromContentType(contentType) {
   if (contentType?.startsWith("audio/")) return "audio";
   return "document";
 }
-async function processVoiceAttachment(att, sttCfg, usePlatformAsr, audioPolicy, log5) {
+var legacySttWarned = false;
+function warnLegacySttCredentials(cfg, log5) {
+  if (!legacySttWarned && hasLegacySttCredentials(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"
+    );
+  }
+}
+async function processVoiceAttachment(att, cfg, usePlatformAsr, sttConfigured, audioPolicy, log5) {
   const rawAsrText = att.asr_refer_text?.trim() || void 0;
   const asrReferText = usePlatformAsr ? rawAsrText : void 0;
   const remoteUrl = normalizeUrl(att.voice_wav_url) || normalizeUrl(att.url) || void 0;
-  if (!sttCfg) {
+  if (!sttConfigured) {
     if (!usePlatformAsr && rawAsrText) {
-      log5?.info(`Voice: STT not configured; platform asr_refer_text discarded (asrFallback not enabled)`);
+      log5?.info(`Voice: framework STT not configured; platform asr_refer_text discarded (asrFallback: false)`);
     }
     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 {
@@ -13209,16 +13181,17 @@ 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)}...`);
+        log5?.debug?.(`Voice STT (framework): ${transcript.slice(0, 80)}...`);
         return { text: transcript, source: "stt", duration, localPath, remoteUrl, asrReferText };
       }
     } 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) {
+    log5?.debug?.(`Voice: falling back to platform asr_refer_text after framework STT failure`);
     return { text: asrReferText, source: "asr", duration, localPath, remoteUrl, asrReferText };
   }
   return {
@@ -13248,9 +13221,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;
@@ -15891,7 +15861,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 +15872,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 +15882,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 +15892,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 +15911,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) {