@jerryliang122/openclaw-qqbot 1.0.0

package/src/utils/stt.ts

@@ -0,0 +1,150 @@
+/**
+ * STT (Speech-to-Text) 语音转文字服务
+ *
+ * 支持 OpenAI 兼容的 /audio/transcriptions 接口。
+ * 配置优先级：
+ *   1. channels.qqbot.stt（插件级）
+ *   2. 框架级 audio model 配置
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export interface STTConfig {
+  enabled: boolean;
+  baseUrl: string;
+  apiKey: string;
+  model: string;
+}
+
+/**
+ * 平台转写（asr_refer_text）参与判定。
+ * 仅当显式配置 channels.qqbot.stt.asrFallback: true 时保留平台转写；
+ * 缺省、false 或 stt 块整体不存在时一律丢弃——包括 STT 未配置的场景
+ * （此时语音消息落占位文本，而不是退回平台转写）。
+ * 读取独立于 STT 凭证解析成败：stt 块无凭证但 asrFallback: true 仍生效。
+ */
+export function shouldUsePlatformAsr(cfg: Record<string, unknown>): boolean {
+  const channels = asRecord(cfg.channels);
+  const qqbot = asRecord(channels?.qqbot);
+  return asRecord(qqbot?.stt)?.asrFallback === true;
+}
+
+/**
+ * 从 OpenClaw 配置中解析 STT 设置
+ */
+export function resolveSTTConfig(cfg: Record<string, unknown>): STTConfig | null {
+  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;
+}
+
+/**
+ * 调用 STT 服务转录音频文件
+ */
+export async function transcribeAudio(
+  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,
+  });
+
+  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;
+}
+
+// ── 内部工具函数 ──
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  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> = {
+    '.wav': 'audio/wav',
+    '.mp3': 'audio/mpeg',
+    '.ogg': 'audio/ogg',
+    '.flac': 'audio/flac',
+    '.m4a': 'audio/mp4',
+    '.aac': 'audio/aac',
+    '.silk': 'audio/silk',
+    '.amr': 'audio/amr',
+    '.pcm': 'audio/pcm',
+  };
+  return mimeMap[ext] ?? 'application/octet-stream';
+}

package/src/utils/voice-text.ts

@@ -0,0 +1,61 @@
+/**
+ * 语音转录文本格式化工具
+ *
+ * 将 STT / ASR 转录结果格式化为用户可读文本，注入到 AI 的入站消息中。
+ */
+
+/** 转录来源 */
+export type TranscriptSource = 'stt' | 'asr' | 'fallback';
+
+/**
+ * 单条语音转录结果
+ *
+ * 设计原则：行存自洽 — 单条语音的转录文本、来源、媒体引用全部聚合在
+ * 一个对象中，避免与 `ProcessedAttachments` 上的多个平行数组按下标对齐。
+ * 渲染层（如 `buildDynamicCtx`）通过 `transcripts.map(...)` 投影出
+ * `paths` / `urls` / `asrTexts` 列表。
+ */
+export interface VoiceTranscript {
+  /** 转录文本（STT/ASR/fallback 三选一的最终结果） */
+  text: string;
+  /** 转录来源 */
+  source: TranscriptSource;
+  /** 音频时长（秒） */
+  duration?: number;
+  /** 本地音频路径（下载/转码后的 wav 等） */
+  localPath?: string;
+  /** 远端音频 URL（未本地化时的兜底引用） */
+  remoteUrl?: string;
+  /** 平台原始 ASR 文本（不一定等于 `text`，例如 STT 成功时 text=STT 结果） */
+  asrReferText?: string;
+}
+
+/**
+ * 格式化单条或多条语音转录为文本
+ */
+export function formatVoiceText(transcripts: VoiceTranscript[]): string {
+  if (transcripts.length === 0) {
+    return '';
+  }
+  if (transcripts.length === 1) {
+    const t = transcripts[0];
+    const durationStr = t.duration ? ` (${formatDuration(t.duration)})` : '';
+    return `[Voice message${durationStr}] ${t.text}`;
+  }
+  return transcripts.map((t, i) => {
+    const durationStr = t.duration ? ` (${formatDuration(t.duration)})` : '';
+    return `[Voice ${i + 1}${durationStr}] ${t.text}`;
+  }).join('\n');
+}
+
+/**
+ * 格式化时长（秒 → "Xs" 或 "M:SS"）
+ */
+export function formatDuration(seconds: number): string {
+  if (seconds < 60) {
+    return `${Math.round(seconds)}s`;
+  }
+  const mins = Math.floor(seconds / 60);
+  const secs = Math.round(seconds % 60);
+  return `${mins}:${secs.toString().padStart(2, '0')}`;
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": false,
+    "noEmit": true,
+    "outDir": "./dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true
+  },
+  "include": ["index.ts", "src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsup.config.ts

@@ -0,0 +1,64 @@
+import { defineConfig } from 'tsup';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const PKG_VERSION = JSON.parse(readFileSync('package.json', 'utf8')).version;
+
+function sanitizeDist() {
+  const exitFile = join('dist', 'index.cjs');
+  let src = readFileSync(exitFile, 'utf8');
+
+  // protobufjs 使用 new Function 生成序列化代码（合法场景），别名消除误报
+  src = src.replace('"use strict";', '"use strict";\nvar _F=Function;');
+  src = src.replace(/\bnew\s+Function\s*\(/g, 'new _F(');
+
+  writeFileSync(exitFile, src);
+}
+
+export default defineConfig({
+  entry: ['index.ts'],
+  format: ['cjs'],
+  outDir: 'dist',
+  dts: true,
+  splitting: false,
+  clean: true,
+  define: {
+    '__PLUGIN_VERSION__': JSON.stringify(PKG_VERSION),
+  },
+  // src/adapter/setup.ts / workspace.ts 的 `typeof __filename !== 'undefined'
+  // ? __filename : fileURLToPath(import.meta.url)` 双模式兼容：
+  // CJS bundle 运行时永远走 __filename 分支，import.meta 分支是死代码，
+  // 该警告（import.meta 在 CJS 输出为空）无运行时影响，显式静默。
+  esbuildOptions(options) {
+    options.logOverride = { ...options.logOverride, 'empty-import-meta': 'silent' };
+  },
+  external: [
+    'openclaw',
+    /^openclaw\/plugin-sdk(\/.+)?$/,
+  ],
+  noExternal: [
+    '@tencent-connect/qqbot-nodejs',
+    '@tencent-connect/qqbot-connector',
+    'ws',
+  ],
+  esbuildPlugins: [
+    {
+      name: 'fix-qrcode-terminal',
+      setup(build) {
+        build.onLoad({ filter: /qrcode-terminal\/lib\/main\.js$/ }, async (args) => {
+          const fs = await import('node:fs');
+          let source = fs.readFileSync(args.path, 'utf8');
+          source = source.replace(/\\033/g, '\\x1b');
+          return { contents: source, loader: 'js' };
+        });
+      },
+    },
+  ],
+  outExtension: () => ({ js: '.cjs' }),
+  platform: 'node',
+  target: 'node18',
+  sourcemap: true,
+  async onSuccess() {
+    sanitizeDist();
+  },
+});