feat(local-asr): 加本地 Qwen3-ASR 引擎（macOS 优先）

[appergb]

User description

这个 PR 做什么

加一条全新的 ASR 后端选项：本地 Qwen3-ASR。模型从 HuggingFace 下载到本机后离线推理；不需要 API key、不上传音频；选项藏在左侧抽屉新页「模型设置」里。

引擎选用 antirez/qwen-asr（Salvatore Sanfilippo 的纯 C 实现，Apple Accelerate 加速），通过 git submodule vendored 到 src-tauri/vendor/qwen-asr/，build.rs 用 cc 直链。

用户体验

流程	行为
设置 → ASR 选「本地 Qwen3-ASR」	不让填 API key，引导到「模型设置」页；后台自动 preload 模型
模型设置页	镜像源切换（HF 官方 / hf-mirror）+ 0.6B / 1.7B 模型下载 + 「加载并测试」+ 已下载模型管理
内存	默认 5 分钟驻留，用户可改：说完即释放 / 1min / 5min / 30min / 始终保留；可手动「立即加载」/「立即释放」
警告	两处显著 ⚠️：本地比云端慢、中文准确率通常不如火山/turbo；建议离线/隐私场景使用

平台支持

• macOS (Apple Silicon)：完整支持，Accelerate (AMX/NEON) 加速，不走 Metal/MPS（antirez 引擎设计选择）
• Windows：本期 UI 灰掉，跟踪 issue 本地 ASR (Qwen3-ASR)：Windows 端流式方案待解 (M1) #256（antirez 不支持 Win + qwen3-asr-rs candle 路径不支持流式）

关键技术点

下载（参考 hfd / aria2 / hf_xet 实测参数）

• HTTP Range 8MB chunk + 单文件 8 并发 + 3 文件并行
• User-Agent: aria2/1.36.0 走 HF 反滥用白名单
• sparse 文件 + seek+write，.partial.idx 索引落盘
• per-chunk 4 次指数退避（1s/4s/16s）
• 中途断流只丢一个 chunk，重启 app 继续断点续传
• 取消标志在每 chunk + 每流块边界检查，秒级响应

模型管理

• 文件清单不硬编码，每次从 https://<mirror>/api/models/<repo>/tree/main 实时拉
• 哨兵 .openless-asr-ready 标记完整下载，不靠"应有文件名都在"判断
• 残留可删（partial 状态显示 [继续下载] [删除] 两键）

Coordinator 集成

• ActiveAsr::Local(Arc<LocalQwenAsr>) 第三分支，与 Volcengine/Whisper 平行
• LocalAsrCache：引擎驻留内存跨会话复用，end_session 后按设置 schedule release
• 切到本地 provider 时 set_active_asr_provider 触发 preload_in_background
• 失败静默回退（CLAUDE.md invariant）

测试入口

• 内嵌 antirez 项目 samples/test_speech.wav (120KB)
• 「加载并测试」按钮跑一次完整 load + transcribe，UI 显示原文/识别/各阶段耗时/后端
• WAV 严格按 RIFF chunk 链解析（fmt 后面有 LIST/INFO 不能 +44 硬偏移）

文件变更概览

12 commits, 28 files changed, 3204 insertions(+), 5 deletions(-)

主要新文件：

• src-tauri/src/asr/local/{cache,download,local_provider,models,qwen_engine,qwen_ffi,test_run}.rs
• src-tauri/vendor/qwen-asr/ (submodule, pin commit b00b789)
• src-tauri/build.rs 重写（macOS 编 antirez C + 链 Accelerate）
• src/pages/LocalAsr.tsx (新页)
• src/lib/localAsr.ts (IPC 包装)

修改：

• src-tauri/src/coordinator.rs 加 ActiveAsr::Local 分支 + cache 字段
• src-tauri/src/commands.rs 加 11 个 local_asr_* IPC
• src-tauri/src/types.rs UserPreferences 加 3 字段（activeModel / mirror / keepLoadedSecs）
• src/pages/Settings.tsx 加 LocalAsrProviderHint 替代 API key 填空 + 已下载列表 + 性能警告
• src/components/FloatingShell.tsx 加 'localAsr' tab
• i18n zh + en 同步全部新文案

Test plan

macOS Apple Silicon 实测路径：

• cargo build + npm run build 全绿 ✅（已验证，cargo check 0 error，tsc exit 0）
• 设置 → ASR 选「本地 Qwen3-ASR」→ 看到引导卡而非 API key 填空
• 点「前往模型设置下载」→ 跳转 + Settings 关闭
• 模型设置 → 选 hf-mirror → 下载 0.6B → 进度持续推进、不卡 5%、不大量 EOF retry
• 下载中点取消 → 立即停（不再不响应）
• 关 app 重开 → 进度条保留 → 看到 [继续下载] [删除] 两按钮
• 完成后「加载并测试」→ 输出 "Hello. This is a test of the Voxtrail speech-to-text system."
• hotkey 录音 → token 实时插入光标位置
• 闲置 5 分钟 → 「内存中的引擎」状态自动从「已加载」回到「未加载」
• 修改保持加载时长设置 → 下次会话遵循新值
• 切回 Volcengine → 现有路径不受影响（回归）
• Windows build (CI) → local-asr 模块整体 cfg 门关闭，不影响其它模块

已知限制

• macOS 平台才编入引擎；Win UI 把本地选项灰掉，文案指向 本地 ASR (Qwen3-ASR)：Windows 端流式方案待解 (M1) #256
• 不支持 Metal GPU（antirez 上游设计选择，使用 AMX/NEON 替代）
• 安装包体积 +0.5 MB（antirez C 静态库 ~434 KB）

关联 issue

• 跟踪 Windows 支持：本地 ASR (Qwen3-ASR)：Windows 端流式方案待解 (M1) #256

🤖 Generated with Claude Code

---

PR Type

Enhancement

---

Description

• 集成 antirez/qwen-asr 纯 C 引擎（macOS Accelerate 加速）

• 实现分块并发下载管理器（断点续传、取消、进度事件）

• 添加本地 ASR 引擎缓存与内存驻留策略（可配置释放时长）

• 提供模型管理 UI 页面（镜像切换、下载/测试/删除、引擎状态）

• 对接 dictation 流程，支持流式 token 实时推送

• Windows 平台暂时灰掉，引导用户跟踪 issue 本地 ASR (Qwen3-ASR)：Windows 端流式方案待解 (M1) #256

---

Diagram Walkthrough

flowchart LR
  A["LocalAsr.tsx UI"] -- "local-asr-* commands" --> B["commands.rs"]
  B -- "Coordinator" --> C["coordinator.rs"]
  C -- "build_local_qwen3" --> D["LocalAsrCache (cache.rs)"]
  D -- "get_or_load" --> E["QwenAsrEngine (qwen_engine.rs)"]
  E -- "FFI" --> F["qwen-asr C lib (vendor/qwen-asr)"]
  C -- "transcribe" --> G["LocalQwenAsr (local_provider.rs)"]
  G -- "stream token" --> H["Capsule UI"]
  I["DownloadManager (download.rs)"] -- "chunk+retry" --> J["HuggingFace CDN"]
  B -- "download model" --> I
  I -- "progress events" --> K["Frontend state"]

Loading

File Walkthrough

	Relevant files
Enhancement	14 files download.rs 添加分块并发下载与断点续传管理器                                                                                  +866/-0  qwen_engine.rs 封装 antirez/qwen-asr 的安全 Rust 引擎                                                    +135/-0  cache.rs 实现本地 ASR 引擎缓存与按需释放                                                                              +132/-0  local_provider.rs 对接 dictation 流程的 AudioConsumer 适配器                                              +103/-0  models.rs 定义模型注册表与本地持久化状态哨兵                                                                                +130/-0  qwen_ffi.rs 声明 antirez/qwen-asr 最小 FFI 绑定                                                        +42/-0    coordinator.rs 集成本地 ASR 引擎与会话生命周期管理                                                                          +202/-0  commands.rs 新增本地 ASR 全部 Tauri 命令接口                                                                      +147/-2  types.rs 扩展用户偏好模型支持本地 ASR 选项                                                                            +27/-0    persistence.rs 新增本地模型存储根目录工具函数                                                                                    +9/-0      LocalAsr.tsx 实现模型管理前端页面（下载/测试/引擎状态）                                                                      +618/-0  mod.rs 注册本地 ASR 子模块到 ASR 模块树                                                                        +1/-0      localAsr.ts 前端本地 ASR IPC 客户端函数封装                                                                          +177/-0  Settings.tsx 在设置页面嵌入本地 ASR 选项入口                                                                              +149/-0
Tests	1 files test_run.rs 提供内嵌测试音频的一键加载与转写测速                                                                              +152/-0
Configuration changes	4 files mod.rs 本地 ASR 模块入口与平台条件编译                                                                              +32/-0    build.rs 添加 antirez/qwen-asr 编译配置（仅 macOS）                                                +53/-0    lib.rs 挂载下载管理器和本地 ASR 命令到 Tauri 应用                                                            +15/-0    .gitmodules 注册 qwen-asr 子模块追踪信息                                                                            +3/-0
Dependencies	1 files qwen-asr 添加 antirez/qwen-asr 作为 git 子模块                                                      +1/-0
Additional files	8 files Cargo.toml +5/-1      FloatingShell.tsx +13/-1    en.ts +52/-0    zh-CN.ts +52/-0    zh-TW.ts +52/-0    ipc.ts +3/-0      types.ts +7/-0      useAppState.ts +8/-1

---

[github-actions]

PR Reviewer Guide 🔍

(Review updated until commit 8c3e4ac)

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis 🔶 256 - Partially compliant Compliant requirements: Keep the macOS local Qwen3-ASR path moving forward. Disable the Windows local ASR option in the UI. Show a tooltip indicating Windows support is still in progress. Do not add Windows local ASR implementation work in this phase. Keep other Windows ASR choices available via cloud providers. Non-compliant requirements: Track the Windows port decision separately rather than shipping it here. Requires further human verification: Tooltip text and disabled-state behavior in the Windows UI should be verified in the running app.

⏱️ Estimated effort to review: 4 🔵🔵🔵🔵⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Retry Corruption Small-file downloads are retried by reopening the same .partial file in append mode. If the first attempt writes some bytes and then fails, the retry appends the full range again instead of overwriting from the beginning, which can produce duplicated bytes and a corrupted model file after the final rename. let mut file = tokio::fs::OpenOptions::new() .create(true) .append(true) .open(partial) .await .with_context(|| format!("open partial failed: {}", partial.display()))?; let mut stream = resp.bytes_stream(); let mut written: u64 = 0; while let Some(chunk) = stream.next().await { if cancel.load(Ordering::SeqCst) { file.flush().await.ok(); anyhow::bail!("cancelled"); } let bytes = chunk.context("read stream chunk failed")?; file.write_all(&bytes).await.context("write chunk failed")?; written += bytes.len() as u64; Timeout Leak The local ASR path times out the async wrapper, but the actual transcription work is started inside spawn_blocking. When the timeout fires, the blocking job keeps running in the background, so the session can still consume CPU and emit late token events after the UI has already reported a failure. let timeout_duration = std::time::Duration::from_secs(COORDINATOR_GLOBAL_TIMEOUT_SECS); let result = tokio::time::timeout(timeout_duration, local.transcribe()).await; inner.local_asr_cache.touch(); schedule_local_asr_release(inner); match result { Ok(Ok(r)) => r, Ok(Err(e)) => { log::error!("[coord] local Qwen3-ASR transcribe failed: {e:#}"); emit_capsule( inner, CapsuleState::Error, 0.0, elapsed, Some(format!("本地识别失败: {e}")), None, ); restore_prepared_windows_ime_session(inner, current_session_id); inner.state.lock().phase = SessionPhase::Idle; schedule_capsule_idle(inner, CAPSULE_AUTO_HIDE_DELAY_MS); return Err(e.to_string()); } Err(_) => { log::error!( "[coord] local Qwen3-ASR 全局超时 {} 秒", COORDINATOR_GLOBAL_TIMEOUT_SECS ); emit_capsule( inner, CapsuleState::Error, 0.0, elapsed, Some("识别超时".to_string()), None, ); restore_prepared_windows_ime_session(inner, current_session_id); inner.state.lock().phase = SessionPhase::Idle; schedule_capsule_idle(inner, CAPSULE_AUTO_HIDE_DELAY_MS); return Err("local global timeout".to_string()); }

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[github-actions]

Persistent review updated to latest commit 8c3e4ac