引导页配置向导

5 步走完，把麦克风、快捷键、模型、API 与使用心法一次搞清楚。

• 首装自动弹出
• 支持版本变更后再弹
• 所有参数写入 ~/.zimablueai_config/config.json
• 主面板「配置引导页」可随时重开

整体认知

引导页是一张铺满当前应用窗口的「全屏向导」。打开时窗口会自动调整为合适大小（约当前显示器 85% × 88%，最大 1240 × 840 逻辑像素）并居中；左侧 5 个步骤胶囊导航，右侧主区显示当前步骤的卡片，所有非交互区域均可拖动以移动窗口。

触发与跳过逻辑

引导页是否自动弹出，取决于配置文件中 onboarding.completed 与 onboarding.appVersion 两个字段。

场景	触发条件	结果
首次安装 / 清空配置	config.json 不存在	启动后自动打开引导页
升级安装（版本变化）	onboarding.appVersion ≠ 当前应用版本	自动打开（迁移、补差异）
已完成且版本匹配	completed: true 且版本一致	不打开（静默启动）
用户主动重新配置	主面板点击「配置引导页」按钮	从最新配置预填表单并打开
用户跳过	点击「跳过」	写入 skipped: true，本版本不再弹

Step 1 · 系统麦克风

这一步把"录音是否能用"先做掉。

• 系统输入设备：下拉框列出 list_audio_input_devices 后端返回的所有麦克风，默认设备会标注「默认」。
• 已检测设备 / 已选择 / 权限状态：三块状态卡，权限状态可为「未检测 / 已允许 / 未授权」。
• 重新扫描设备：调用一次后端 API，热插拔的耳机/麦克风会被刷新进来。
• 请求麦克风权限：调用 getUserMedia，授权成功后进入实时波形测试；如果失败，权限状态会切到「未授权」并提示。
• 实时波形测试：Canvas 上 64 条频带条实时显示麦克风能量条。能看到条形跳动即说明麦克风可用。

Step 2 · 快捷键

用一个稳定的「物理按键」来开启 / 停止录音。当前仅支持 6 种推荐键位，不接受任意字母组合（避免与全局快捷键冲突）。

键位	Mac 等价	说明
Right Alt ★ 推荐	⌥ Right Option	单手不冲突，是默认值
Left Alt	⌥ Left Option	左手习惯
Right Ctrl	⌃ Right Control	右手区低冲突
Left Ctrl	⌃ Left Control	可能与编辑器冲突
Right Shift	⇧ Right Shift	与输入法可能冲突
Left Shift	⇧ Left Shift	与输入法可能冲突

实时按键预览：把鼠标点到深色面板里，按下任意键即可在底部预览。使用 KeyboardEvent.code（AltLeft/AltRight/ControlLeft/...）精确区分左右键；如果按下不支持的键（例如 Win/⌘ 或字母键），只会显示 "(unsupported)"，不会写入状态。

Step 3 · 模型与参数

三块基础模型一次配齐，后续在主面板还能精细调整：

Step 4 · API 提供商

11 个开箱即用的 Provider，每个卡片展开后填 Base URL、API Key、以及该 Provider 支持的能力（LLM / ASR / TTS / Realtime）对应的模型名。填了 API Key 视为「启用」。

能力填写要点

• LLM 模型字段 自动写入 translateApiBaseUrl / translateApiKey / translateModel，主面板"翻译"模块即时可用
• TTS 模型字段 自动写入 cfg.tts.cloudTtsModel，作为云端 TTS 备用通道（不会覆盖你 Step 3 设的本地 TTS）
• ASR / Realtime 暂存在 cfg.onboarding.providers，等主面板对应模块读取
• 所有字段可逗号分隔多模型，留空时使用 Provider 的默认值

Step 5 · 使用说明

3 张 SVG 动效卡片帮你 30 秒了解三大场景：

1. 一键录音 → 转写：按下 Right Alt 开录，再按结束，识别结果实时跟随光标输出。
2. 语音合成 TTS：在主面板输入文本或选择历史片段，一键朗读，支持声纹克隆。
3. 同声传译 STS：工作台模式，源语音 → 实时识别 → 目标语言 → TTS 朗读，可保留原始音色。

配置文件结构参考

引导页保存后会写入 ~/.zimablueai_config/config.json，关键字段：

{
  "stt": {
    "inputDeviceName": "耳机式麦克风 (MCP01)",
    "backend": "sensevoice",
    "modelDir": "D:/models/SenseVoiceSmall",
    "hotkey": "RightAlt"
  },
  "tts": {
    "ttsModel": "qwen3_tts",
    "modelDir": "D:/models/qwen3-tts",
    "cloudTtsModel": "speech-01-v2"
  },
  "sts": {
    "sourceLanguage": "zh",
    "targetLanguage": "en"
  },
  "translateApiBaseUrl": "https://api.openai.com/v1",
  "translateApiKey": "sk-***",
  "translateModel": "gpt-4o-mini",
  "translateEnabled": true,
  "onboarding": {
    "completed": true,
    "skipped": false,
    "version": 1,
    "appVersion": "0.4.0",
    "completedAt": "2026-05-11T08:42:13.000Z",
    "providers": {
      "openai": {
        "enabled": true,
        "baseUrl": "https://api.openai.com/v1",
        "apiKey": "sk-***",
        "models": { "llm": "gpt-4o-mini", "tts": "tts-1" }
      }
    }
  }
}