made-bridge 0.0.0-stage → 0.2.0

package/src/sessions.mjs

@@ -0,0 +1,134 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { builtinAgent } from './agents/index.mjs';
+
+export const VIBE_SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export const CLI_SESSION_ID = /^[A-Za-z0-9_-]{6,128}$/;
+const PROVIDER_ID = /^[a-z0-9][a-z0-9_-]{0,39}$/;
+const OPAQUE_SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,255}$/;
+
+export function validAgentSessionId(plugin, value) {
+  if (typeof value !== 'string' || value.length > 256) return false;
+  const pattern = plugin?.sessionIdPattern || OPAQUE_SESSION_ID;
+  pattern.lastIndex = 0;
+  return pattern.test(value);
+}
+const DEFAULT_TITLE = '新任务';
+
+function now() { return new Date().toISOString(); }
+
+function titleFrom(value) {
+  if (typeof value !== 'string') throw new Error('任务标题必须是文字');
+  const title = value.replace(/[\x00-\x1f\x7f]+/g, ' ').trim();
+  if (!title || Array.from(title).length > 60) throw new Error('任务标题需在 1 到 60 字之间');
+  return title;
+}
+
+function firstTurnTitle(instruction) {
+  const compact = String(instruction).replace(/\s+/g, ' ').trim();
+  const chars = Array.from(compact);
+  return chars.slice(0, 24).join('') + (chars.length > 24 ? '…' : '');
+}
+
+export class SessionStore {
+  constructor({ file, projects, defaultProject, defaultProvider, pluginsRuntime, agent }) {
+    this.agent = agent || (pluginsRuntime ? (id) => pluginsRuntime.agent(id) : builtinAgent);
+    this.file = file;
+    this.projects = projects;
+    this.defaultProject = defaultProject;
+    this.defaultProvider = defaultProvider;
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const parsed = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : [];
+    this.sessions = Array.isArray(parsed) ? parsed : [];
+    let migrated = false;
+    for (const session of this.sessions) {
+      if (session.autoTitlePending && session.title === '新会话') {
+        session.title = DEFAULT_TITLE;
+        migrated = true;
+      }
+    }
+    if (migrated) this.save();
+  }
+
+  save() {
+    const temp = `${this.file}.${process.pid}.tmp`;
+    fs.writeFileSync(temp, JSON.stringify(this.sessions, null, 2), { mode: 0o600 });
+    fs.renameSync(temp, this.file);
+  }
+
+  list(provider) {
+    return this.sessions.filter((session) => !provider || session.provider === provider)
+      .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+  }
+
+  get(id) { return this.sessions.find((session) => session.id === id); }
+
+  create({ provider, projectId, title, legacy = false, cliSessionId = '' } = {}) {
+    const selectedProvider = provider || this.defaultProvider;
+    const selectedProject = projectId || this.defaultProject;
+    const plugin = this.agent(selectedProvider);
+    if (!plugin && !(legacy && PROVIDER_ID.test(selectedProvider))) throw new Error('不支持的编程工具');
+    if (!this.projects.some((project) => project.id === selectedProject)) {
+      throw new Error('项目不在本机允许列表中');
+    }
+    const explicitTitle = title !== undefined && title !== null;
+    const timestamp = now();
+    const session = {
+      id: randomUUID(), provider: selectedProvider, projectId: selectedProject,
+      title: explicitTitle ? titleFrom(title) : DEFAULT_TITLE,
+      autoTitlePending: !explicitTitle,
+      contextMode: plugin?.capabilities.session || 'native',
+      cliSessionId: validAgentSessionId(plugin, cliSessionId) ? cliSessionId : '',
+      legacy, createdAt: timestamp, updatedAt: timestamp,
+    };
+    this.sessions.push(session);
+    this.save();
+    return session;
+  }
+
+  rename(id, title) {
+    const session = this.get(id);
+    if (!session) throw new Error('任务不存在');
+    session.title = titleFrom(title);
+    session.autoTitlePending = false;
+    session.updatedAt = now();
+    this.save();
+    return session;
+  }
+
+  delete(id) {
+    const index = this.sessions.findIndex((session) => session.id === id);
+    if (index < 0) throw new Error('任务不存在');
+    this.sessions.splice(index, 1);
+    this.save();
+  }
+
+  recordTurn(id, instruction) {
+    const session = this.get(id);
+    if (!session) throw new Error('任务不存在');
+    if (session.autoTitlePending) {
+      session.title = firstTurnTitle(instruction);
+      session.autoTitlePending = false;
+    }
+    session.updatedAt = now();
+    this.save();
+    return session;
+  }
+
+  setCliSession(id, cliSessionId) {
+    const session = this.get(id);
+    if (!session || !validAgentSessionId(this.agent(session.provider), cliSessionId)) return;
+    session.cliSessionId = cliSessionId;
+    session.updatedAt = now();
+    this.save();
+  }
+
+  setGitSnapshot(id, snapshot) {
+    const session = this.get(id);
+    if (!session || typeof snapshot !== 'string') return;
+    session.gitSnapshot = snapshot;
+    session.updatedAt = now();
+    this.save();
+  }
+}

package/src/speech/index.mjs

@@ -0,0 +1,10 @@
+import openai from './openai.mjs';
+import whisper from './whisper.mjs';
+
+const off = {
+  apiVersion: 1, kind: 'speech-recognizer', id: 'off', label: '关闭语音识别', fields: [],
+  probe: () => ({ available: false, reason: '语音识别已关闭' }),
+  transcribe: async () => '',
+};
+
+export const builtinSpeechRecognizers = [openai, whisper, off];

package/src/speech/openai.mjs

@@ -0,0 +1,48 @@
+import { DEFAULT_TRANSCRIBE_MODEL, DEFAULT_TRANSCRIBE_URL, validateTranscribeModel, validateTranscribeUrl } from '../voice-settings.mjs';
+import { validateOpenAIKey } from '../openai-key.mjs';
+
+export default {
+  apiVersion: 1,
+  kind: 'speech-recognizer',
+  id: 'openai',
+  label: 'OpenAI 兼容语音接口',
+  fields: [
+    { key: 'url', label: '转写接口 URL', type: 'url', required: true, default: DEFAULT_TRANSCRIBE_URL },
+    { key: 'apiKey', label: 'API Key', type: 'secret', required: true },
+    { key: 'model', label: '模型名', type: 'model', required: true, default: DEFAULT_TRANSCRIBE_MODEL },
+  ],
+  presets: [
+    { id: 'openai', label: 'OpenAI', values: { url: DEFAULT_TRANSCRIBE_URL, model: DEFAULT_TRANSCRIBE_MODEL } },
+    { id: 'siliconflow', label: '硅基流动', values: { url: 'https://api.siliconflow.cn/v1/audio/transcriptions', model: 'FunAudioLLM/SenseVoiceSmall' } },
+  ],
+  validateSettings(settings) {
+    return { ...settings, url: validateTranscribeUrl(settings.url),
+      model: validateTranscribeModel(settings.model), apiKey: validateOpenAIKey(settings.apiKey || '') };
+  },
+  probe(settings) {
+    return { available: Boolean(settings.apiKey), reason: settings.apiKey ? '' : '请在电脑页面配置语音 API Key' };
+  },
+  async transcribe({ wav, settings, signal }) {
+    if (!settings.apiKey) throw new Error('请在电脑页面配置语音 API Key');
+    const data = new FormData();
+    data.set('model', settings.model);
+    // Let the service detect speech language; interface locale is independent.
+    data.set('file', new Blob([wav], { type: 'audio/wav' }), 'voice.wav');
+    let response;
+    try {
+      response = await fetch(settings.url, {
+        method: 'POST', signal: AbortSignal.any([AbortSignal.timeout(90000), signal]),
+        headers: { Authorization: `Bearer ${settings.apiKey}` }, body: data, redirect: 'error',
+      });
+    } catch {
+      signal.throwIfAborted();
+      throw new Error('无法连接语音识别服务，请检查电脑侧接口 URL 和网络');
+    }
+    if (!response.ok) throw new Error(`语音识别服务返回 ${response.status}；请检查电脑侧 URL、API Key 和模型`);
+    let result;
+    try { result = await response.json(); }
+    catch { throw new Error('语音识别服务未返回 JSON 结果'); }
+    // The host checks type and transcript bounds for every recognizer.
+    return result?.text;
+  },
+};

package/src/speech/whisper.mjs

@@ -0,0 +1,59 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+function run(command, args, signal) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: ['ignore', 'ignore', 'pipe'], signal });
+    let stderr = '';
+    let killTimer;
+    const killEventually = () => {
+      killTimer = setTimeout(() => child.kill('SIGKILL'), 2000);
+      killTimer.unref();
+    };
+    signal.addEventListener('abort', killEventually, { once: true });
+    child.stderr.on('data', (chunk) => { stderr = `${stderr}${chunk}`.slice(-1500); });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      clearTimeout(killTimer);
+      signal.removeEventListener('abort', killEventually);
+      if (signal.aborted) reject(signal.reason);
+      else if (code === 0) resolve();
+      else reject(new Error(`本地语音识别失败（退出码 ${code}）：${stderr}`));
+    });
+  });
+}
+
+export default {
+  apiVersion: 1,
+  kind: 'speech-recognizer',
+  id: 'whisper',
+  label: '本机 Whisper',
+  fields: [
+    { key: 'command', label: 'Whisper 程序', type: 'path', required: true, default: 'whisper-cli' },
+    { key: 'modelPath', label: '本机模型路径', type: 'path', required: true, placeholder: '/path/to/ggml-model.bin' },
+  ],
+  probe(settings) {
+    const available = Boolean(settings.modelPath && fs.existsSync(settings.modelPath));
+    return { available, reason: available ? '' : '请先选择已下载到电脑的 Whisper 模型' };
+  },
+  async transcribe({ wav, settings, signal }) {
+    if (!settings.modelPath || !fs.existsSync(settings.modelPath)) throw new Error('请先选择已下载到电脑的 Whisper 模型');
+    const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'vibe-voice-'));
+    const audioPath = path.join(directory, 'voice.wav');
+    const outputBase = path.join(directory, 'transcript');
+    try {
+      fs.writeFileSync(audioPath, wav, { mode: 0o600 });
+      await run(settings.command || 'whisper-cli', [
+        '-m', settings.modelPath, '-f', audioPath, '-l', 'auto', '-nt', '-otxt', '-of', outputBase,
+      ], signal);
+      const transcriptPath = `${outputBase}.txt`;
+      if (!fs.existsSync(transcriptPath)) throw new Error('本地识别未生成文字');
+      if (fs.statSync(transcriptPath).size > 16000) throw new Error('本地识别文字过长，请重试');
+      return fs.readFileSync(transcriptPath, 'utf8');
+    } finally {
+      fs.rmSync(directory, { recursive: true, force: true });
+    }
+  },
+};

package/src/speech-settings.mjs

@@ -0,0 +1,209 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { builtinSpeechRecognizers } from './speech/index.mjs';
+import { DEFAULT_TRANSCRIBE_MODEL, DEFAULT_TRANSCRIBE_URL, saveVoiceSettings } from './voice-settings.mjs';
+import { saveOpenAIKey } from './openai-key.mjs';
+
+const SETTINGS_VERSION = 1;
+const own = (object, key) => Object.prototype.hasOwnProperty.call(object || {}, key);
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const settingsPath = (stateDir) => path.join(stateDir, 'secrets', 'speech-settings.json');
+
+export function speechRecognizers(config) {
+  return config.pluginsRuntime?.speechRecognizers() || builtinSpeechRecognizers;
+}
+
+export function speechRecognizer(config, id) {
+  return config.pluginsRuntime ? config.pluginsRuntime.speechRecognizer(id) : builtinSpeechRecognizers.find((plugin) => plugin.id === id);
+}
+
+function legacySettings(config) {
+  return {
+    openai: {
+      url: config.transcribeUrl || DEFAULT_TRANSCRIBE_URL,
+      model: config.transcribeModel || DEFAULT_TRANSCRIBE_MODEL,
+      apiKey: config.openaiKeySource === 'environment' ? '' : (config.openaiKey || ''),
+    },
+    whisper: { command: config.whisperCli || 'whisper-cli', modelPath: config.whisperModel || '' },
+    off: {},
+  };
+}
+
+function defaultSettings(plugin) {
+  return Object.fromEntries(plugin.fields.map((field) => [field.key, field.default ?? '']));
+}
+
+function validateFields(plugin, settings, required) {
+  if (!isRecord(settings)) throw new Error('语音插件设置格式无效');
+  const keys = new Set(plugin.fields.map((field) => field.key));
+  for (const key of Object.keys(settings)) if (!keys.has(key)) throw new Error(`语音插件不支持设置项：${key}`);
+  for (const field of plugin.fields) {
+    const value = settings[field.key];
+    if (typeof value !== 'string' || value.length > (field.type === 'model' ? 256 : 4096) || /[\x00-\x1f\x7f]/.test(value)) {
+      throw new Error(`${field.label} 格式无效`);
+    }
+    if (required && field.required && !value.trim()) throw new Error(`请先填写${field.label}`);
+    if (field.type === 'url' && value) {
+      let parsed;
+      try { parsed = new URL(value); } catch { throw new Error(`${field.label} URL 无效`); }
+      if (value !== value.trim() || !['https:', 'http:'].includes(parsed.protocol) || parsed.username || parsed.password || parsed.hash) {
+        throw new Error(`${field.label} 须使用不含账号、密码和片段的 HTTP 或 HTTPS 地址`);
+      }
+    }
+  }
+  return settings;
+}
+
+export function normalizeSpeechSettings(plugin, values, { required = false } = {}) {
+  let settings;
+  let normalized;
+  try {
+    if (!isRecord(values)) throw new Error('语音插件设置格式无效');
+    settings = validateFields(plugin, { ...defaultSettings(plugin), ...values }, required);
+    if (!plugin.validateSettings) return settings;
+    normalized = plugin.validateSettings({ ...settings });
+    // A plugin can normalize its fields, but cannot bypass host bounds or add fields.
+    return validateFields(plugin, normalized, required);
+  } catch (error) {
+    const message = redactSpeechError(error, plugin, settings || values || {});
+    throw new Error(redactSpeechError(new Error(message), plugin, normalized || {}));
+  }
+}
+
+export function initializeSpeechSettings(config) {
+  let saved;
+  try {
+    const file = settingsPath(config.stateDir);
+    if (!fs.lstatSync(file).isFile()) throw new Error('语音插件设置文件无效');
+    saved = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (saved.version !== SETTINGS_VERSION || typeof saved.pluginId !== 'string' || !isRecord(saved.settingsByPlugin)) {
+      throw new Error('语音插件设置文件格式无效');
+    }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  const settingsByPlugin = { ...legacySettings(config), ...(saved?.settingsByPlugin || {}) };
+  // Keep settings of temporarily uninstalled plugins so reinstalling is lossless.
+  for (const plugin of speechRecognizers(config)) {
+    if (own(settingsByPlugin, plugin.id)) settingsByPlugin[plugin.id] = normalizeSpeechSettings(plugin, settingsByPlugin[plugin.id]);
+  }
+  config.speech = { pluginId: saved?.pluginId || config.asrMode || 'openai', settingsByPlugin };
+  syncLegacyFields(config);
+  return config.speech;
+}
+
+export function speechSelection(config, pluginId = config.speech?.pluginId || config.asrMode || 'openai') {
+  const plugin = speechRecognizer(config, pluginId);
+  if (!plugin) return { pluginId, plugin: null, settings: {} };
+  const stored = config.speech?.settingsByPlugin?.[pluginId] || legacySettings(config)[pluginId] || {};
+  const settings = { ...defaultSettings(plugin), ...stored };
+  if (pluginId === 'openai' && !settings.apiKey) {
+    settings.apiKey = config.environmentOpenaiKey || (!config.speech && config.openaiKey) || '';
+  }
+  return { pluginId, plugin, settings };
+}
+
+function syncLegacyFields(config) {
+  const openai = speechSelection(config, 'openai').settings;
+  const whisper = speechSelection(config, 'whisper').settings;
+  config.asrMode = config.speech.pluginId;
+  config.transcribeUrl = openai.url || DEFAULT_TRANSCRIBE_URL;
+  config.transcribeModel = openai.model || DEFAULT_TRANSCRIBE_MODEL;
+  config.openaiKey = openai.apiKey || '';
+  config.openaiKeySource = config.speech.settingsByPlugin.openai?.apiKey ? 'saved' : config.openaiKey ? 'environment' : 'none';
+  config.whisperCli = whisper.command || 'whisper-cli';
+  config.whisperModel = whisper.modelPath || '';
+}
+
+export function saveSpeechSettings(config, payload) {
+  if (!isRecord(payload) || typeof payload.pluginId !== 'string') throw new Error('请选择语音识别插件');
+  const plugin = speechRecognizer(config, payload.pluginId);
+  if (!plugin) throw new Error('未安装所选语音识别插件');
+  if (!isRecord(payload.settings || {})) throw new Error('语音插件设置格式无效');
+  const clearSecrets = payload.clearSecrets || [];
+  if (!Array.isArray(clearSecrets) || clearSecrets.some((key) => !plugin.fields.some((field) => field.key === key && field.type === 'secret'))) {
+    throw new Error('要清除的语音密钥字段无效');
+  }
+  const current = config.speech || { pluginId: config.asrMode || 'openai', settingsByPlugin: legacySettings(config) };
+  const updated = { ...defaultSettings(plugin), ...(current.settingsByPlugin[payload.pluginId] || {}) };
+  for (const [key, value] of Object.entries(payload.settings || {})) {
+    const field = plugin.fields.find((entry) => entry.key === key);
+    if (!field) throw new Error(`语音插件不支持设置项：${key}`);
+    // Blank passwords are placeholders in the UI, not requests to erase them.
+    if (field.type === 'secret' && value === '') continue;
+    updated[key] = value;
+  }
+  for (const key of clearSecrets) {
+    if (payload.settings?.[key]) throw new Error('不能同时设置和清除同一语音密钥');
+    updated[key] = '';
+  }
+  const normalized = normalizeSpeechSettings(plugin, updated);
+  const next = { pluginId: payload.pluginId, settingsByPlugin: { ...current.settingsByPlugin, [payload.pluginId]: normalized } };
+  const directory = path.join(config.stateDir, 'secrets');
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  fs.chmodSync(directory, 0o700);
+  const file = settingsPath(config.stateDir);
+  const temporary = path.join(directory, `.speech-settings-${process.pid}-${randomUUID()}`);
+  try {
+    fs.writeFileSync(temporary, JSON.stringify({ version: SETTINGS_VERSION, ...next }), { flag: 'wx', mode: 0o600 });
+    fs.renameSync(temporary, file);
+    fs.chmodSync(file, 0o600);
+  } finally {
+    fs.rmSync(temporary, { force: true });
+  }
+  config.speech = next;
+  syncLegacyFields(config);
+  // Preserve compatibility with existing integrations and older bridge versions.
+  if (payload.pluginId === 'openai') {
+    saveVoiceSettings(config.stateDir, { url: normalized.url, model: normalized.model });
+    saveOpenAIKey(config.stateDir, normalized.apiKey || '');
+  }
+  return speechSettingsState(config);
+}
+
+export function redactSpeechError(error, plugin, settings) {
+  let message = error instanceof Error ? error.message : '语音识别插件执行失败';
+  for (const field of plugin?.fields || []) {
+    if (field.type === 'secret' && typeof settings[field.key] === 'string' && settings[field.key]) message = message.split(settings[field.key]).join('[已隐藏密钥]');
+  }
+  return message.slice(0, 500);
+}
+
+function pluginState(config, plugin) {
+  const { settings } = speechSelection(config, plugin.id);
+  const publicSettings = {};
+  const secretConfigured = {};
+  for (const field of plugin.fields) {
+    if (field.type === 'secret') secretConfigured[field.key] = Boolean(settings[field.key]);
+    else publicSettings[field.key] = settings[field.key];
+  }
+  let probe;
+  try {
+    normalizeSpeechSettings(plugin, settings, { required: true });
+    probe = plugin.probe(settings, { config });
+    if (probe && typeof probe.then === 'function') {
+      Promise.resolve(probe).catch(() => {});
+      throw new Error('语音插件 probe 必须同步返回 available');
+    }
+    if (!probe || typeof probe.available !== 'boolean') throw new Error('语音插件 probe 必须同步返回 available');
+  } catch (error) {
+    probe = { available: false, reason: redactSpeechError(error, plugin, settings) };
+  }
+  return {
+    id: plugin.id, label: plugin.label,
+    fields: plugin.fields.map(({ key, label, type, required, default: defaultValue, placeholder }) => ({ key, label, type, required, ...(type === 'secret' ? {} : { default: defaultValue }), placeholder })),
+    presets: (plugin.presets || []).map(({ id, label, values }) => ({ id, label, values: Object.fromEntries(Object.entries(values).filter(([key]) => plugin.fields.some((field) => field.key === key && field.type !== 'secret'))) })),
+    settings: publicSettings, secretConfigured,
+    available: probe.available,
+    reason: typeof probe.reason === 'string' ? redactSpeechError(new Error(probe.reason), plugin, settings) : '',
+  };
+}
+
+export function speechSettingsState(config) {
+  const pluginId = config.speech?.pluginId || config.asrMode || 'openai';
+  const plugins = speechRecognizers(config).map((plugin) => pluginState(config, plugin));
+  const selected = plugins.find((plugin) => plugin.id === pluginId);
+  return { pluginId, plugins, settings: selected?.settings || {}, secretConfigured: selected?.secretConfigured || {},
+    available: selected?.available || false, reason: selected?.reason || (selected ? '' : '所选语音插件尚未安装') };
+}

package/src/transcribe.mjs

@@ -0,0 +1,85 @@
+import { DEFAULT_TRANSCRIBE_MODEL, DEFAULT_TRANSCRIBE_URL } from './voice-settings.mjs';
+import { normalizeSpeechSettings, redactSpeechError, speechSelection, speechSettingsState } from './speech-settings.mjs';
+
+const MAX_WAV_BYTES = 1_100_000;
+
+export function validateVoiceWav(wav) {
+  if (!Buffer.isBuffer(wav) || wav.length < 44 || wav.length > MAX_WAV_BYTES) {
+    throw new Error('录音大小不符合要求（最多约 30 秒）');
+  }
+  if (wav.toString('ascii', 0, 4) !== 'RIFF' ||
+      wav.readUInt32LE(4) !== wav.length - 8 ||
+      wav.toString('ascii', 8, 12) !== 'WAVE' ||
+      wav.toString('ascii', 12, 16) !== 'fmt ' ||
+      wav.readUInt32LE(16) !== 16 ||
+      wav.readUInt16LE(20) !== 1 ||
+      wav.readUInt16LE(22) !== 1 ||
+      wav.readUInt32LE(24) !== 16000 ||
+      wav.readUInt32LE(28) !== 32000 ||
+      wav.readUInt16LE(32) !== 2 ||
+      wav.readUInt16LE(34) !== 16 ||
+      wav.toString('ascii', 36, 40) !== 'data') {
+    throw new Error('录音必须是 16 kHz、16 bit、单声道 PCM WAV');
+  }
+  const size = wav.readUInt32LE(40);
+  if (size !== wav.length - 44 || size < 16000 || size > 16000 * 2 * 30) {
+    throw new Error('录音内容长度无效（需 0.5 到 30 秒）');
+  }
+  return wav;
+}
+
+
+export function transcriptionState(config) {
+  return {
+    ...speechSettingsState(config),
+    mode: config.speech?.pluginId || config.asrMode || 'openai',
+    keySource: config.openaiKeySource || (config.openaiKey ? 'environment' : 'none'),
+    url: config.transcribeUrl || DEFAULT_TRANSCRIBE_URL,
+    model: config.transcribeModel || DEFAULT_TRANSCRIBE_MODEL,
+  };
+}
+
+// A plugin receives an abort signal, and cancellation also stops waiting even if
+// an extension accidentally ignores it. The extension must release its own I/O.
+async function invoke(plugin, options) {
+  options.signal.throwIfAborted();
+  let aborted;
+  const cancellation = new Promise((_resolve, reject) => {
+    aborted = () => reject(options.signal.reason);
+    options.signal.addEventListener('abort', aborted, { once: true });
+  });
+  try {
+    return await Promise.race([Promise.resolve().then(() => {
+      options.signal.throwIfAborted();
+      return plugin.transcribe(options);
+    }), cancellation]);
+  } finally {
+    options.signal.removeEventListener('abort', aborted);
+  }
+}
+
+export async function transcribe(wav, config, signal) {
+  signal?.throwIfAborted();
+  validateVoiceWav(wav);
+  const selection = speechSelection(config);
+  if (!selection.plugin) throw new Error('所选语音识别插件尚未安装');
+  const { plugin } = selection;
+  let settings;
+  let transcript;
+  try {
+    settings = normalizeSpeechSettings(plugin, selection.settings, { required: true });
+    const boundedSignal = AbortSignal.any([AbortSignal.timeout(120000), ...(signal ? [signal] : [])]);
+    transcript = await invoke(plugin, { wav, settings, signal: boundedSignal, config });
+  } catch (error) {
+    signal?.throwIfAborted();
+    if (error?.name === 'TimeoutError') throw new Error('语音识别超时，请重试');
+    throw new Error(redactSpeechError(error, plugin, settings || selection.settings));
+  }
+  signal?.throwIfAborted();
+  if (typeof transcript !== 'string') throw new Error('语音识别插件必须返回文字');
+  transcript = transcript.trim();
+  if (transcript.length < 3 || transcript.length > 2000) {
+    throw new Error(transcript ? '识别文字过长或过短，请重试' : '语音识别尚未配置或未听清内容');
+  }
+  return transcript;
+}