made-bridge 0.0.0-stage → 0.2.0

package/src/config.mjs

@@ -0,0 +1,196 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import { loadLanguageSettings } from './language-settings.mjs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadOpenAIKey } from './openai-key.mjs';
+import { pluginRuntime } from './plugin-runtime.mjs';
+import { DEFAULT_CODEX_MODEL, loadModelSettings, validateModelSettings, validateStoredModels } from './model-settings.mjs';
+import { DEFAULT_TRANSCRIBE_MODEL, DEFAULT_TRANSCRIBE_URL, loadVoiceSettings, validateTranscribeModel, validateTranscribeUrl } from './voice-settings.mjs';
+
+export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const PLUGIN_ID = /^[a-z0-9][a-z0-9_-]{0,39}$/;
+
+/** 随代码发布的内置包目录：bridge/builtin/{plugins,themes}。升级代码即升级内置包。 */
+export const BUILTIN_ROOT = path.join(ROOT, 'builtin');
+
+/**
+ * 用户数据目录（配置、状态、工作区）：~/.made-bridge。
+ *
+ * 为什么不放在包目录里：源码仓库运行时 ROOT 可写没问题；但 `npx made-bridge`
+ * 把包装在 npm 缓存里运行，缓存随时可能被清——配置、配对、会话写在那里等于
+ * 随时丢。所以可写数据一律落到用户家目录下的固定位置，代码目录保持只读。
+ */
+export function dataHome(env = process.env) {
+  return path.resolve(env.VIBE_DATA_DIR || path.join(os.homedir(), '.made-bridge'));
+}
+
+/**
+ * 用户配置文件路径解析：
+ * ① 显式 VIBE_CONFIG；② 源码仓库里的 ROOT/config.local.json（老用法，向后兼容）；
+ * ③ ~/.made-bridge/config.local.json（npx / 全局安装的默认位置）。
+ */
+export function resolveConfigPath(env = process.env) {
+  if (env.VIBE_CONFIG) return path.resolve(env.VIBE_CONFIG);
+  const repoConfig = path.join(ROOT, 'config.local.json');
+  if (fs.existsSync(repoConfig)) return repoConfig;
+  return path.join(dataHome(env), 'config.local.json');
+}
+
+/**
+ * 首次运行引导：用户目录里还没有配置时，把包内示例复制过去，让 `npx made-bridge`
+ * 开箱即得一份**可编辑且持久**的配置（直接读包内示例的话，编辑会随缓存蒸发）。
+ * 返回 { created, path }；created 为 true 时调用方应提示用户去编辑。
+ */
+export function ensureUserConfig(env = process.env) {
+  if (env.VIBE_CONFIG) return { created: false, path: path.resolve(env.VIBE_CONFIG) };
+  const repoConfig = path.join(ROOT, 'config.local.json');
+  if (fs.existsSync(repoConfig)) return { created: false, path: repoConfig };
+  const target = path.join(dataHome(env), 'config.local.json');
+  if (fs.existsSync(target)) return { created: false, path: target };
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.copyFileSync(path.join(ROOT, 'config.example.json'), target);
+  // 示例里的相对路径（./demo-project）是相对包目录的；落到用户目录后要改写成
+  // 绝对路径指向包内的演示项目，否则 npx 首次运行的默认项目找不到目录。
+  try {
+    const seeded = JSON.parse(fs.readFileSync(target, 'utf8'));
+    if (Array.isArray(seeded.projects)) {
+      for (const project of seeded.projects) {
+        if (typeof project.path === 'string' && !path.isAbsolute(project.path)) {
+          project.path = path.join(ROOT, project.path);
+        }
+      }
+      fs.writeFileSync(target, `${JSON.stringify(seeded, null, 2)}\n`, { mode: 0o600 });
+    }
+  } catch { /* 改写失败不致命：读不到就按原样用，任务报错时用户自然会去编辑配置 */ }
+  return { created: true, path: target };
+}
+
+/**
+ * 用户包目录根：默认 ~/made，可用 MADE_HOME 环境变量或配置里的 madeHome 覆盖。
+ *
+ * 这是一个固定位置，不跟着配置文件走：市场把包装到 <root>/plugins 与 <root>/themes，
+ * 桥接器每次启动自动扫描，换一个工作目录也不需要重新安装。
+ */
+export function packagesHome(config = {}) {
+  return path.resolve(config.madeHome || process.env.MADE_HOME || path.join(os.homedir(), 'made'));
+}
+
+/**
+ * 包目录的查找顺序：内置在前、用户目录在后，同名时用户目录覆盖内置。
+ *
+ * 内置目录只读，移除与改配置只作用于用户目录。
+ */
+export function packageRoots(config = {}) {
+  return [BUILTIN_ROOT, packagesHome(config)];
+}
+
+/**
+ * 校验 VIBE_USB_PORT。允许两类写法：绝对路径（/dev/cu.usbmodem1101、
+ * \\.\COM10），以及 Windows 上用户真正会写的 COM 端口名（COM3）。
+ *
+ * 为什么要特判 COM3：Windows 上「COM3」既没有盘符也没有 UNC 根，
+ * path.isAbsolute 判 false，只用绝对路径规则会把 Windows 唯一的手动兜底
+ * 直接拦掉，而那个兜底正是 USB 在这套系统上唯一能走的路。
+ */
+export function validateUsbPort(value, platform = process.platform) {
+  const port = String(value || '');
+  if (!port) return '';
+  if (/[\r\n\x00]/.test(port)) throw new Error('VIBE_USB_PORT 不能包含控制字符');
+  if (path.isAbsolute(port)) return port;
+  if (platform === 'win32' && /^\\{0,2}(?:\.\\)?COM\d+$/i.test(port)) return port;
+  throw new Error('VIBE_USB_PORT 必须是 USB 串口的绝对路径，或 Windows 上的 COM 端口名');
+}
+
+export function loadConfig(env = process.env) {
+  const configPath = resolveConfigPath(env);
+  // 有用户配置就用用户配置（projects/workspaces 相对它解析）；完全没有时回落包内
+  // 示例，让首次 npx 也能起服务——但状态目录仍走数据目录，绝不写进包内。
+  const hasUserConfig = fs.existsSync(configPath);
+  const selected = hasUserConfig ? configPath : path.join(ROOT, 'config.example.json');
+  const fallback = path.join(ROOT, 'config.example.json');
+  const raw = JSON.parse(fs.readFileSync(selected, 'utf8'));
+  const base = path.dirname(selected);
+  if (!Array.isArray(raw.projects) || raw.projects.length === 0) {
+    throw new Error('配置需要至少一个 projects 项目');
+  }
+  const seen = new Set();
+  const projects = raw.projects.map((project) => {
+    if (!/^[a-z0-9_-]{1,40}$/.test(project.id) || seen.has(project.id)) {
+      throw new Error(`项目 ID 无效或重复：${project.id}`);
+    }
+    seen.add(project.id);
+    return {
+      id: project.id,
+      label: String(project.label || project.id),
+      path: path.resolve(base, project.path),
+    };
+  });
+  const defaultProject = raw.defaultProject || projects[0].id;
+  const defaultProvider = raw.defaultProvider || 'codex';
+  if (!seen.has(defaultProject) || !PLUGIN_ID.test(defaultProvider)) {
+    throw new Error('默认项目或默认编程工具不在配置中');
+  }
+  const port = Number(raw.port || 8787);
+  const devicePort = Number(raw.devicePort || 8788);
+  if (![port, devicePort].every((p) => Number.isInteger(p) && p > 0 && p < 65536)) {
+    throw new Error('端口号必须在 1 到 65535 之间');
+  }
+  // 同时执行的会话数。同一会话恒为串行（编程工具按会话线程加写锁，并行必然冲突），
+  // 所以这里限制的是"能同时跑几个会话"，不是"一个会话里能同时跑几条指令"。
+  const maxParallelJobs = Number(env.VIBE_MAX_PARALLEL || raw.maxParallelJobs || 2);
+  if (!Number.isInteger(maxParallelJobs) || maxParallelJobs < 1 || maxParallelJobs > 4) {
+    throw new Error('并行任务数必须是 1 到 4 之间的整数');
+  }
+  const stateDir = path.resolve(env.VIBE_STATE_DIR
+    || (hasUserConfig ? path.join(path.dirname(configPath), 'state') : dataHome(env)));
+  const usbPort = validateUsbPort(env.VIBE_USB_PORT || '');
+  const models = { ...validateModelSettings({
+    codex: env.VIBE_CODEX_MODEL || raw.codexModel || DEFAULT_CODEX_MODEL,
+    cursor: env.VIBE_CURSOR_MODEL || raw.cursorModel || '',
+    qoder: env.VIBE_QODER_MODEL || raw.qoderModel || '',
+  }), ...validateStoredModels(raw.models || {}), ...(loadModelSettings(stateDir) || {}) };
+  const asrMode = env.VIBE_ASR_MODE || 'openai';
+  if (!PLUGIN_ID.test(asrMode)) throw new Error('VIBE_ASR_MODE 必须是语音插件 ID');
+  if (raw.plugins !== undefined && (!Array.isArray(raw.plugins) || raw.plugins.some(p => typeof p !== 'string'))) throw new Error('plugins 必须是本地模块路径数组');
+  if (raw.madeHome !== undefined && (typeof raw.madeHome !== 'string' || !raw.madeHome.trim())) throw new Error('madeHome 必须是非空字符串');
+  if (raw.disabledPlugins !== undefined && (!Array.isArray(raw.disabledPlugins) || raw.disabledPlugins.some(p => !PLUGIN_ID.test(p)))) throw new Error('disabledPlugins 必须是插件 ID 数组');
+  if (raw.pluginSettings !== undefined && (!raw.pluginSettings || typeof raw.pluginSettings !== 'object' || Array.isArray(raw.pluginSettings))) throw new Error('pluginSettings 必须是对象');
+  const savedVoiceSettings = loadVoiceSettings(stateDir);
+  const environmentOpenaiKey = env.OPENAI_API_KEY || '';
+  const savedOpenaiKey = loadOpenAIKey(stateDir);
+  return {
+    configDirectory: base,
+    madeHome: packagesHome({ madeHome: env.MADE_HOME || raw.madeHome }),
+    locale: loadLanguageSettings(stateDir, raw.locale ?? 'zh-CN'),
+    plugins: raw.plugins || [],
+    disabledPlugins: raw.disabledPlugins || [],
+    pluginSettings: raw.pluginSettings || {},
+    projects,
+    workspaceRoot: path.resolve(base, raw.workspaceRoot || './workspaces'),
+    defaultProject,
+    defaultProvider,
+    port,
+    devicePort,
+    maxParallelJobs,
+    codexModel: models.codex,
+    models,
+    asrMode,
+    whisperModel: env.VIBE_WHISPER_MODEL || '',
+    whisperCli: env.VIBE_WHISPER_CLI || 'whisper-cli',
+    openaiKey: savedOpenaiKey || environmentOpenaiKey,
+    openaiKeySource: savedOpenaiKey ? 'saved' : environmentOpenaiKey ? 'environment' : 'none',
+    environmentOpenaiKey,
+    transcribeUrl: savedVoiceSettings?.url || validateTranscribeUrl(env.VIBE_TRANSCRIBE_URL || DEFAULT_TRANSCRIBE_URL),
+    transcribeModel: savedVoiceSettings?.model || validateTranscribeModel(env.VIBE_TRANSCRIBE_MODEL || DEFAULT_TRANSCRIBE_MODEL),
+    workbuddyToken: env.WORKBUDDY_ACCESS_TOKEN || '',
+    workbuddy: {
+      allowUnscopedDispatch: raw.workbuddy?.allowUnscopedDispatch === true,
+    },
+    stateDir,
+    usbPort,
+    configFile: selected,
+    // 插件可用的跨平台助手（命令查找、子进程、npm）。见 plugin-runtime.mjs。
+    runtime: pluginRuntime,
+  };
+}

package/src/doctor.mjs

@@ -0,0 +1,146 @@
+/**
+ * 桥接器自检：node src/server.mjs --doctor
+ *
+ * 为什么要有它：平台差异不该让用户去读代码。这里在真机上逐项检查哪些能力可用、
+ * 缺什么、缺了怎么办，并把与平台相关的限制明说——与 AGENTS.md 的约定一致：
+ * 功能不可用时必须给出原因，不能静默失败。模块化拆分是为了能直接测，
+ * 不用把桥接器真的跑起来。
+ */
+import { ROOT, loadConfig } from './config.mjs';
+import { findCommand, isWindows, platform } from './plugin-runtime.mjs';
+import { discoverUsbSerialPorts } from './usb-receiver.mjs';
+import { loadConfiguredPlugins } from './plugins/registry.mjs';
+import { providerStates } from './providers.mjs';
+
+const LEVEL = { ok: '✓', warn: '!', fail: '✗' };
+const PLATFORM_LABEL = { darwin: 'macOS', linux: 'Linux', win32: 'Windows' };
+const TUNNEL_TOOLS = ['tailscale', 'ngrok', 'cloudflared'];
+
+const platformLabel = () => `${PLATFORM_LABEL[platform] || platform}（${platform}）`;
+
+/** 串口发现失败不该让自检整体失败：拿不到就当没发现。 */
+async function safePorts() {
+  try {
+    return await discoverUsbSerialPorts();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 收集自检项。返回 { checks, code }：
+ *   checks —— { level, label, detail } 或 { raw } 的纯数据，便于测试与二次渲染
+ *   code   —— 进程退出码，1 表示有阻断性缺项
+ */
+export async function collectDoctor({ config: provided } = {}) {
+  const checks = [];
+  const add = (level, label, detail = '') => checks.push({ level, label, detail });
+  const raw = (text = '') => checks.push({ raw: text });
+
+  raw('码得桥接器自检');
+  raw();
+
+  raw('运行环境');
+  add('ok', `${platformLabel()} · Node ${process.version}`);
+  add('ok', `桥接器目录 ${ROOT}`);
+
+  let config = provided;
+  if (!config) {
+    try {
+      config = loadConfig();
+    } catch (error) {
+      add('fail', '配置无法加载', error.message);
+    }
+  }
+  if (config) {
+    add('ok', `配置文件 ${config.configFile}`);
+    add('ok', `包目录 ${config.madeHome}（plugins/、themes/）`);
+    add('ok', `状态目录 ${config.stateDir}`);
+    add('ok', `端口：电脑面板 ${config.port}，设备接口 ${config.devicePort}`);
+  }
+
+  raw();
+  raw('依赖命令');
+  const git = findCommand('git');
+  if (git) add('ok', `git ${git}`, '任务前后改动对比依赖它');
+  else add('fail', '未找到 git', '任务的前后改动对比依赖它，请先安装 Git 并加入 PATH');
+
+  const npm = findCommand('npm');
+  if (npm) add('ok', `npm ${npm}`, '需要自装依赖的插件（如 Pi 智能体）首次运行时用它');
+  else add('warn', '未找到 npm', '安装 Node.js 时自带 npm；缺了它，首次运行需要自动装依赖的插件会起不来');
+
+  const esptool = findCommand('esptool') || findCommand('esptool.py');
+  if (esptool) add('ok', `esptool ${esptool}`, '只给刷机工具用，桥接器运行不需要');
+  else add('warn', '未找到 esptool', '只影响 npm run flash 刷机，不影响桥接器运行');
+
+  raw();
+  raw('接入方式');
+  const ports = config ? await safePorts() : [];
+  if (isWindows) {
+    // Windows 侧没有 /dev，也没有 VID/PID 枚举，实话实说。
+    add('warn', 'USB 线直连 / 接收器转发：不能自动发现串口',
+      '需手动设 VIBE_USB_PORT=<COM 口>（设备管理器里可查）；接收器只支持原生 USB 变体，'
+      + 'WCH 转串口变体在 Windows 上不支持（不设波特率），请用 macOS / Linux');
+  } else if (ports.length) {
+    add('ok', `USB 线直连 / 接收器转发：已发现串口 ${ports.join('、')}`);
+  } else {
+    add('warn', 'USB 线直连 / 接收器转发：没有发现串口',
+      '插上码得或接收器后重试；也可以直接用 VIBE_USB_PORT 指定端口');
+  }
+  if (config?.usbPort) add('ok', `已用 VIBE_USB_PORT 指定 ${config.usbPort}`);
+
+  add('ok', '局域网 Wi-Fi 直连：设备与电脑同网即可，无需额外配置');
+  const tunnels = TUNNEL_TOOLS.filter((name) => findCommand(name));
+  if (tunnels.length) add('ok', `公网地址：本机有 ${tunnels.join('、')}`);
+  else add('warn', '公网地址：未检测到内网穿透工具',
+    `装了 ${TUNNEL_TOOLS.join(' / ')} 之一才能在桥接页配置公网地址`);
+
+  if (esptool) {
+    add('ok', '烧录：npm run flash 可用（先停掉占用串口的桥接器）');
+  } else {
+    add('warn', '烧录：npm run flash 需要 esptool，当前不可用');
+  }
+
+  if (config) {
+    raw();
+    raw('插件');
+    try {
+      const registry = await loadConfiguredPlugins(config);
+      const states = providerStates({ ...config, pluginsRuntime: registry });
+      if (!states.length) add('warn', '没有加载到任何助手插件', '插件目录见上方的包目录');
+      for (const state of states) {
+        add(state.available ? 'ok' : 'warn', `${state.label}（${state.id}）`, state.reason || '可用');
+      }
+    } catch (error) {
+      add('fail', '插件加载失败', error.message);
+    }
+  }
+
+  const fails = checks.filter((item) => item.level === 'fail').length;
+  const warns = checks.filter((item) => item.level === 'warn').length;
+  raw();
+  raw(fails
+    ? `自检未通过：${fails} 项需要处理${warns ? `，另有 ${warns} 项受限` : ''}。详见上方 ✗ 项。`
+    : warns
+      ? `自检通过：${warns} 项受限（上方 ! 项），不影响其余功能。`
+      : '自检通过：本机没有发现问题。');
+
+  return { checks, code: fails ? 1 : 0 };
+}
+
+/** 把自检项渲染成给人看的文本。 */
+export function formatDoctor(checks) {
+  return checks
+    .map((item) => (item.raw !== undefined
+      ? item.raw
+      : `${LEVEL[item.level]} ${item.label}${item.detail ? `\n    ${item.detail}` : ''}`))
+    .join('\n');
+}
+
+/** 命令行入口：打印自检结果并返回进程退出码。 */
+export async function runDoctor(options = {}) {
+  const { out = console.log, ...rest } = options;
+  const { checks, code } = await collectDoctor(rest);
+  out(formatDoctor(checks));
+  return code;
+}

package/src/i18n.mjs

@@ -0,0 +1,257 @@
+/** Translate bridge-owned messages only, at explicit output boundaries. Never
+ * walk arbitrary JSON or translate instructions, titles, paths, credentials,
+ * model names, plugin-defined metadata, or assistant replies. Unknown messages
+ * remain verbatim; anchored templates preserve their dynamic parameters. */
+const messages = new Map([
+  ['语言仅支持 zh-CN 或 en', 'Language must be zh-CN or en'],
+  ['语言设置文件无效', 'Invalid language settings file'],
+  ['语言设置格式无效', 'Invalid language settings'],
+  ['请求过大', 'Request is too large'],
+  ['录音超过 30 秒上限', 'Recording exceeds the 30-second limit'],
+  ['只允许从本机访问电脑面板', 'The dashboard is only accessible from this computer'],
+  ['缺少本机操作令牌', 'Local operation token is missing'],
+  ['密钥请求格式无效', 'Invalid API key request'],
+  ['clearKey 必须为布尔值', 'clearKey must be a boolean'],
+  ['不能同时设置和清除语音 API Key', 'Cannot set and clear the speech API key together'],
+  ['未找到接口', 'Endpoint not found'],
+  ['插件设置无效', 'Invalid plugin setting'],
+  ['插件配置无效', 'Invalid plugin settings'],
+  ['插件配置规范无效', 'Invalid plugin settings spec'],
+  ['插件配置过大', 'Plugin settings are too large'],
+  ['插件配置规范与插件 ID 不一致', 'The settings spec does not match the plugin ID'],
+  ['插件没有可保存的配置', 'This plugin has no settings to save'],
+  ['插件不存在', 'Plugin not found'],
+  ['主题不存在', 'Theme not found'],
+  ['没有已配对的码得', 'No made device is paired'],
+  ['主题未能下发', 'Could not send the theme'],
+  ['请先复制 config.example.json 为 config.local.json', 'Copy config.example.json to config.local.json first'],
+  ['USB 接入仅允许本机串口转发', 'USB access requires the local serial relay'],
+  ['探针格式无效', 'Invalid probe request'],
+  ['校验请求格式无效', 'Invalid verification request'],
+  ['接入地址未获桥接器授权', 'The bridge has not authorized this address'],
+  ['设备未配对', 'Device is not paired'],
+  ['设备未授权', 'Device is not authorized'],
+  ['未知编程工具', 'Unknown coding assistant'],
+  ['任务不存在', 'Task not found'],
+  ['码得配置超过 32 KB，请检查助手元数据', 'Device configuration exceeds 32 KB; check assistant metadata'],
+  ['另一段录音正在识别，请稍后再试', 'Another recording is being transcribed; try again shortly'],
+  ['请上传 WAV 录音', 'Upload a WAV recording'],
+  ['语音不存在', 'Voice clip is missing'],
+  ['语音超过 256KB', 'Voice clip exceeds 256 KB'],
+  ['请先新建任务', 'Create a task first'],
+  ['项目不在本机允许列表中', 'Project is not in the local allowlist'],
+  ['任务与编程工具或项目不匹配', 'Task does not match the assistant or project'],
+  ['任务内容需在 3 到 2000 字之间', 'Instructions must contain 3 to 2000 characters'],
+  ['不支持的编程工具', 'Unsupported coding assistant'],
+  ['请先完成或取消当前任务的上一条指令', 'Complete or cancel the previous instruction first'],
+  ['编程工具未返回可恢复的会话 ID，无法继续此任务；请新建任务', 'The assistant did not return a resumable session ID; create a new task'],
+  ['当前任务不能确认', 'This task cannot be confirmed now'],
+  ['编程工具尚未就绪', 'The coding assistant is not ready'],
+  ['当前任务不能取消', 'This task cannot be cancelled now'],
+  ['这个编程工具不支持撤回正在执行的任务，请在工具中处理', 'This assistant cannot cancel a running task; handle it in the assistant'],
+  ['这个编程工具不支持撤回正在执行的任务，请先在工具中结束执行', 'This assistant cannot cancel a running task; finish it in the assistant before deleting this task'],
+  ['编程工具插件返回了无效的任务状态', 'The assistant plugin returned an invalid task status'],
+  ['桥接客户端重启，任务执行已中断。请检查代码目录后重新提交。', 'The bridge restarted and interrupted this task. Check the project before submitting again.'],
+  ['任务标题必须是文字', 'Task title must be text'],
+  ['任务标题需在 1 到 60 字之间', 'Task title must contain 1 to 60 characters'],
+  ['新任务', 'New task'],
+  ['编程工具插件未加载，请先安装或启用对应插件', 'The assistant plugin is not loaded; install or enable it first'],
+  ['插件状态检查必须同步返回', 'The plugin status check must return synchronously'],
+  ['任务已取消', 'Task cancelled'],
+  ['默认编程助手未安装或已禁用', 'The default assistant is not installed or is disabled'],
+  ['配对请求格式无效', 'Invalid pairing request'],
+  ['设备名称无效', 'Invalid device name'],
+  ['电脑配对窗口未开启', 'Pairing is not open on the computer'],
+  ['待配对设备过多', 'Too many pending devices'],
+  ['配对尝试过于频繁', 'Too many pairing attempts'],
+  ['配对请求已失效', 'Pairing request has expired'],
+  ['校验请求过于频繁', 'Too many verification requests'],
+  ['语音 API Key 格式无效', 'Invalid speech API key'],
+  ['密钥存储文件无效', 'Invalid API key storage file'],
+  ['本机保存的 OpenAI 密钥格式无效', 'The locally saved OpenAI API key is invalid'],
+  ['请填写当前已安装助手的模型设置', 'Enter model settings for installed assistants'],
+  ['模型设置格式无效', 'Invalid model settings'],
+  ['模型设置文件无效', 'Invalid model settings file'],
+  ['录音大小不符合要求（最多约 30 秒）', 'Invalid recording size (up to approximately 30 seconds)'],
+  ['录音必须是 16 kHz、16 bit、单声道 PCM WAV', 'Recording must be 16 kHz, 16-bit, mono PCM WAV'],
+  ['录音内容长度无效（需 0.5 到 30 秒）', 'Recording must be 0.5 to 30 seconds long'],
+  ['所选语音识别插件尚未安装', 'The selected speech recognizer is not installed'],
+  ['语音识别超时，请重试', 'Speech recognition timed out; try again'],
+  ['语音识别插件必须返回文字', 'The speech recognizer must return text'],
+  ['识别文字过长或过短，请重试', 'The transcript is too long or too short; try again'],
+  ['语音识别尚未配置或未听清内容', 'Speech recognition is not configured or no clear speech was detected'],
+  ['语音接口 URL 无效', 'Invalid transcription URL'],
+  ['语音接口必须使用 HTTPS；仅本机代理允许 HTTP', 'The speech endpoint must use HTTPS; HTTP is allowed only for a local proxy'],
+  ['语音接口 URL 不能包含账号、密码或片段，且须包含接口路径', 'The speech URL must include an API path and no credentials or fragment'],
+  ['语音模型名称无效', 'Invalid speech model name'],
+  ['语音设置文件无效', 'Invalid speech settings file'],
+  ['语音插件设置格式无效', 'Invalid speech settings'],
+  ['语音插件设置文件无效', 'Invalid speech settings file'],
+  ['语音插件设置文件格式无效', 'Invalid speech settings file format'],
+  ['请选择语音识别插件', 'Select a speech recognizer'],
+  ['未安装所选语音识别插件', 'The selected speech recognizer is not installed'],
+  ['要清除的语音密钥字段无效', 'Invalid speech secret field to clear'],
+  ['不能同时设置和清除同一语音密钥', 'Cannot set and clear the same speech secret together'],
+  ['语音识别插件执行失败', 'Speech recognition failed'],
+  ['语音插件 probe 必须同步返回 available', 'The speech status check must synchronously return available'],
+  ['所选语音插件尚未安装', 'The selected speech recognizer is not installed'],
+  ['OpenAI 兼容语音接口', 'OpenAI-compatible speech API'],
+  ['转写接口 URL', 'Transcription URL'],
+  ['模型名', 'Model'],
+  ['硅基流动', 'SiliconFlow'],
+  ['请在电脑页面配置语音 API Key', 'Configure the speech API key on the computer'],
+  ['无法连接语音识别服务，请检查电脑侧接口 URL 和网络', 'Cannot reach the speech service; check the endpoint URL and computer network'],
+  ['语音识别服务未返回 JSON 结果', 'The speech service did not return JSON'],
+  ['关闭语音识别', 'Speech recognition off'],
+  ['语音识别已关闭', 'Speech recognition is off'],
+  ['本机 Whisper', 'Local Whisper'],
+  ['Whisper 程序', 'Whisper executable'],
+  ['本机模型路径', 'Local model path'],
+  ['请先选择已下载到电脑的 Whisper 模型', 'Select a Whisper model downloaded to this computer'],
+  ['本地识别未生成文字', 'Local speech recognition returned no transcript'],
+  ['本地识别文字过长，请重试', 'The local transcript is too long; try again'],
+  ['无法配置 USB 串口，请检查端口权限', 'Cannot configure USB serial; check port permissions'],
+  ['设备接口响应过大', 'Device API response is too large'],
+  ['USB 帧过长', 'USB frame is too long'],
+  ['USB 帧格式无效', 'Invalid USB frame format'],
+  ['USB 请求重叠', 'Overlapping USB requests'],
+  ['USB 请求格式无效', 'Invalid USB request'],
+  ['USB 数据帧无效', 'Invalid USB data frame'],
+  ['USB 数据长度无效', 'Invalid USB data length'],
+  ['USB 请求长度不符', 'USB request length does not match'],
+  ['USB 请求超时', 'USB request timed out'],
+  ['电脑设备接口暂不可用', 'The computer device API is temporarily unavailable'],
+  ['USB 帧类型无效', 'Invalid USB frame type'],
+  ['此系统需手动配置 VIBE_USB_PORT', 'Set VIBE_USB_PORT manually on this system'],
+  ['USB 握手心跳超时', 'USB handshake heartbeat timed out'],
+  ['USB 设备未连接', 'USB device is not connected'],
+  ['未发现受支持的 USB 设备；可设置 VIBE_USB_PORT', 'No supported USB device found; you can set VIBE_USB_PORT'],
+  ['USB 响应帧过长', 'USB response frame is too long'],
+  ['USB 设备已断开', 'USB device disconnected'],
+  ['USB 写入超时', 'USB write timed out'],
+  ['USB 已连接，等待打开码得应用的 USB 直连', 'USB connected; open made and enable USB direct mode'],
+  ['无法打开 USB 串口，请检查端口权限或占用情况', 'Cannot open USB serial; check permissions and whether the port is in use'],
+  ['ngrok Authtoken 格式无效', 'Invalid ngrok Authtoken'],
+  ['固定地址必须是 HTTPS 公网域名', 'The fixed address must be a public HTTPS domain'],
+  ['固定地址须为 HTTPS 域名，不含路径、端口或参数', 'Use an HTTPS domain without a path, port, or query'],
+  ['Cloudflare Tunnel 令牌格式无效', 'Invalid Cloudflare Tunnel token'],
+  ['请先关闭当前穿透，再修改设置', 'Stop the current tunnel before changing settings'],
+  ['请选择有效的公网接入方式', 'Select a valid public connection method'],
+  ['清除令牌参数无效', 'Invalid clear-token parameter'],
+  ['不能同时设置和清除令牌', 'Cannot set and clear a token together'],
+  ['固定地址模式需要 HTTPS 域名和 Cloudflare Tunnel 令牌', 'Fixed-address mode requires an HTTPS domain and Cloudflare Tunnel token'],
+  ['ngrok 需要先填写 Authtoken', 'Enter an ngrok Authtoken first'],
+  ['请填写花生壳 HTTPS 映射域名', 'Enter the Oray HTTPS mapping domain'],
+  ['请填写花生壳 API Key', 'Enter the Oray API key'],
+  ['桥接器未配置状态目录', 'The bridge state directory is not configured'],
+  ['请先保存固定域名和 Cloudflare Tunnel 令牌。', 'Save the fixed domain and Cloudflare Tunnel token first.'],
+  ['请先在电脑端保存 ngrok Authtoken。', 'Save the ngrok Authtoken on the computer first.'],
+  ['检测到指向本机码得接口的 Tailscale 公网路由。请点击“清理残留路由”后重试。', 'A Tailscale public route points to this made API. Clear the remaining route and try again.'],
+  ['Tailscale 的 443 端口已有服务；请检查 tailscale funnel status，勿覆盖原有 Serve/Funnel。', 'Tailscale port 443 already has a service. Check tailscale funnel status without overwriting existing Serve/Funnel settings.'],
+  ['未安装 tailscale，请先在电脑上安装并登录。', 'Install Tailscale on the computer and sign in first.'],
+  ['无法读取 Tailscale 状态，请检查登录、运行状态与 Funnel 权限。', 'Cannot read Tailscale status; check sign-in, running state, and Funnel permissions.'],
+  ['无法准备 ngrok 本机配置，请检查状态目录。', 'Cannot prepare ngrok configuration; check the state directory.'],
+  ['无法启动内网穿透。', 'Cannot start the tunnel.'],
+  ['内网穿透启动失败。', 'Tunnel startup failed.'],
+  ['内网穿透连接已断开，请重新开启。', 'The tunnel disconnected; start it again.'],
+  ['Tailscale Funnel 未能建立，请检查登录和 Funnel 权限。', 'Tailscale Funnel failed; check sign-in and Funnel permissions.'],
+  ['ngrok 未能建立，请检查 Authtoken、域名与网络连接。', 'ngrok failed; check the Authtoken, domain, and network.'],
+  ['未能建立内网穿透，请检查 cloudflared 与网络连接。', 'The tunnel failed; check cloudflared and the network.'],
+  ['Tailscale 公网路由已失效，请关闭后重新开启。', 'The Tailscale public route is no longer valid; stop and restart it.'],
+  ['无法核实 Tailscale 公网路由，请检查客户端状态。', 'Cannot verify the Tailscale public route; check the client status.'],
+  ['ngrok 公网路由已失效或转发目标不符。', 'The ngrok public route is invalid or has an unexpected target.'],
+  ['无法核实 ngrok 公网路由，已关闭穿透。', 'Cannot verify the ngrok public route; the tunnel was stopped.'],
+  ['ngrok 启动超时，请检查 Authtoken、域名与网络连接。', 'ngrok startup timed out; check the Authtoken, domain, and network.'],
+  ['Tailscale Funnel 启动超时，请检查登录和 Funnel 权限。', 'Tailscale Funnel startup timed out; check sign-in and Funnel permissions.'],
+  ['内网穿透连接超时，请检查 cloudflared、令牌与网络连接。', 'Tunnel connection timed out; check cloudflared, the token, and network.'],
+  ['无法确认 Tailscale 公网路由已关闭，请在电脑上运行 tailscale funnel status 检查。', 'Cannot confirm that the Tailscale public route is closed; run tailscale funnel status on the computer.'],
+  ['花生壳 API Key 格式无效', 'Invalid Oray API key'],
+  ['请输入花生壳 HTTPS 域名', 'Enter an Oray HTTPS domain'],
+  ['花生壳地址须为 HTTPS 域名，不含端口、路径或参数', 'Use an Oray HTTPS domain without a port, path, or query'],
+  ['设备接口端口无效', 'Invalid device API port'],
+  ['请先停用已选花生壳映射，再修改设置', 'Disable the selected Oray mapping before changing settings'],
+  ['API Key 设置冲突', 'Conflicting API key settings'],
+  ['请先保存花生壳 API Key', 'Save the Oray API key first'],
+  ['无法连接花生壳开放 API，请检查网络', 'Cannot reach the Oray API; check the network'],
+  ['花生壳 API Key 无效或无权限', 'The Oray API key is invalid or lacks permission'],
+  ['花生壳开放 API 返回的数据无效', 'The Oray API returned invalid data'],
+  ['花生壳映射列表格式无效', 'Invalid Oray mapping list'],
+  ['请先选择花生壳 HTTPS 域名', 'Select an Oray HTTPS domain first'],
+  ['未找到唯一的 HTTPS/443 映射，请先在花生壳创建并选择该域名', 'No unique HTTPS/443 mapping found; create it in Oray and select its domain'],
+  ['无法读取花生壳账号 ID', 'Cannot read the Oray account ID'],
+  ['花生壳映射状态尚未更新，请稍后刷新状态', 'The Oray mapping state has not updated; refresh shortly'],
+  ['桥接器身份尚未准备好', 'The bridge identity is not ready'],
+  ['映射已启用，但无法验证公网地址指向本桥接器；请检查花生壳客户端已登录且映射保留公网 Host', 'Mapping enabled, but its public address could not be verified; check Oray sign-in and preserve the public Host header'],
+  ['编程工具报告任务失败', 'The coding assistant reported a task failure'],
+  ['正在分析任务', 'Analyzing task'],
+  ['正在整理结果', 'Preparing results'],
+  ['资料检索完成', 'Research complete'],
+  ['正在查找资料', 'Researching'],
+  ['已更新任务步骤', 'Task steps updated'],
+  ['正在整理答复', 'Preparing reply'],
+  ['文件读取完成', 'File read complete'],
+  ['正在读取文件', 'Reading files'],
+  ['文件修改完成', 'File changes complete'],
+  ['正在修改文件', 'Editing files'],
+  ['命令执行完成', 'Command complete'],
+  ['正在运行命令', 'Running command'],
+  ['代码检索完成', 'Code search complete'],
+  ['正在检索代码', 'Searching code'],
+  ['工具操作完成', 'Tool operation complete'],
+  ['正在使用工具', 'Using tool'],
+  ['已连接编程工具', 'Coding assistant connected'],
+  ['Codex 对话正被使用，项目文件也发生变化。请先检查改动。', 'This Codex session is in use and the project has changed. Review the changes first.'],
+  ['此 Codex 对话正在另一窗口或进程使用；结束后再次确认即可继续', 'This Codex session is in use in another window or process; confirm again after it finishes'],
+  ['Codex 当前模型不能用于这个登录账号。请在电脑桥接页面的“编程助手模型”中选择该账号可用的模型。', 'This Codex model is unavailable for the signed-in account. Choose an available model in the bridge assistant settings.'],
+  ['WorkBuddy 开放平台尚未授权或未开启转交模式', 'WorkBuddy authorization or dispatch mode is not enabled'],
+  ['WorkBuddy 消息历史格式无效', 'Invalid WorkBuddy message history'],
+  ['可转交任务；如获消息读取授权可回显回复，无法保证指定代码目录或撤回', 'Dispatch available; reply access requires permission. Project targeting and cancellation are not guaranteed'],
+  ['需 WorkBuddy 开放平台授权，并显式允许无项目目录保证的转交模式', 'WorkBuddy authorization and explicit permission for dispatch without project targeting are required'],
+  ['无法检查项目改动状态', 'Cannot check project changes'],
+  ['目标项目必须是 Git 仓库，以便查看和恢复改动', 'The project must be a Git repository so changes can be reviewed and restored'],
+  ['请把项目路径设为 Git 仓库根目录', 'Set the project path to the Git repository root'],
+  ['项目文件自上一轮会话后发生变化，请先检查改动再继续', 'Project files changed after the previous turn; review them before continuing'],
+  ['项目已有未提交改动。请先保存或提交，再确认语音任务', 'The project has uncommitted changes. Save or commit them before confirming the voice task'],
+  ['任务运行超过 20 分钟，已停止', 'Task exceeded 20 minutes and was stopped'],
+  ['请在电脑端检查 CLI 登录和权限设置', 'Check CLI sign-in and permissions on the computer'],
+  ['请只修改当前仓库中的文件；不要提交、推送、发布或删除仓库。完成后说明改动与已运行的验证。', 'Only modify files in the current repository. Do not commit, push, publish, or delete the repository. When finished, describe the changes and the checks you ran.'],
+  ['改动文件：', 'Changed files:'],
+  ['没有检测到代码改动。', 'No code changes detected.'],
+  ['任务已执行，未返回文字摘要。', 'Task executed without a text summary.'],
+  ['当前授权不能读取 WorkBuddy 消息；需 user.localassistant.readable 权限。请在 WorkBuddy 中查看回复。', 'Current authorization cannot read WorkBuddy messages; user.localassistant.readable is required. View replies in WorkBuddy.'],
+  ['出现其他 WorkBuddy 用户消息；后续回复无法可靠归属此任务，请在 WorkBuddy 中查看。', 'Another WorkBuddy user message appeared. Further replies cannot be reliably assigned to this task; view them in WorkBuddy.'],
+  ['助理请求进一步确认，请在 WorkBuddy 中处理。', 'The assistant requests confirmation; handle it in WorkBuddy.'],
+  ['助理有一条新消息，请在 WorkBuddy 中查看详情。', 'The assistant has a new message; view it in WorkBuddy.'],
+  ['WorkBuddy 后续助理消息（任务关联未验证）：', 'Further WorkBuddy assistant message (task association unverified):'],
+]);
+const templates = [
+  [/^(Codex|Cursor|Qoder)：编程工具报告任务失败$/, (_, label) => `${label}: The coding assistant reported a task failure`],
+  [/^请先在本机登录 (.+)$/s, (_, command) => `Sign in to ${command} on this computer first`],
+  [/^本机未找到 (.+) 命令$/s, (_, command) => `${command} was not found on this computer`],
+  [/^(.+) 状态检查失败$/s, (_, label) => `${label} status check failed`],
+  [/^(.+) 模型名称无效$/s, (_, provider) => `Invalid model name for ${provider}`],
+  [/^语音识别服务返回 (\d+)；请检查电脑侧 URL、API Key 和模型$/, (_, status) => `Speech service returned ${status}; check the URL, API key, and model on the computer`],
+  [/^花生壳开放 API 返回 (\d+)，请检查账号服务及映射配置$/, (_, status) => `Oray API returned ${status}; check the account service and mapping settings`],
+  [/^花生壳映射须指向本机 127\.0\.0\.1:(\d+)，已拒绝操作其他服务$/, (_, port) => `The Oray mapping must target 127.0.0.1:${port}; other services will not be changed`],
+  [/^未安装 (tailscale|ngrok|cloudflared)，请先在电脑上安装。$/, (_, command) => `Install ${command} on this computer first.`],
+  [/^代码目录不存在：([\s\S]*)$/, (_, directory) => `Project directory does not exist: ${directory}`],
+  [/^(.+) 退出码 (null|-?\d+)：([\s\S]*)$/, (_, label, code, detail) => `${label} exited with code ${code}: ${detail}`],
+  [/^本地语音识别失败（退出码 (null|-?\d+)）：([\s\S]*)$/, (_, code, detail) => `Local speech recognition failed (exit code ${code}): ${detail}`],
+  [/^WorkBuddy 转交失败：([\s\S]*)$/, (_, detail) => `WorkBuddy dispatch failed: ${detail}`],
+  [/^WorkBuddy 消息读取失败：([\s\S]*)$/, (_, detail) => `WorkBuddy message read failed: ${detail}`],
+  [/^语音插件不支持设置项：(.+)$/, (_, field) => `Unsupported speech setting: ${field}`],
+  [/^(转写接口 URL|API Key|模型名|Whisper 程序|本机模型路径) 格式无效$/, (_, label) => `Invalid ${translateKnownMessage(label, 'en')}`],
+  [/^请先填写(转写接口 URL|API Key|模型名|Whisper 程序|本机模型路径)$/, (_, label) => `Enter ${translateKnownMessage(label, 'en')} first`],
+];
+export function translateKnownMessage(message, locale = 'zh-CN') {
+  if (locale !== 'en' || typeof message !== 'string' || !message) return message;
+  if (messages.has(message)) return messages.get(message);
+  for (const [pattern, render] of templates) {
+    const match = pattern.exec(message);
+    if (match) return render(...match);
+  }
+  return message;
+}
+export function localizeStatus(value, locale) {
+  return { ...value, ...(typeof value?.error === 'string' ? { error: translateKnownMessage(value.error, locale) } : {}) };
+}