# Round 5 研发任务拆解：Qwen3-ASR 中文高级模型

状态：v0.1 研发拆解稿
所属子项目：`02-P-NBL`
Round：Round 5
日期：2026-06-03
输入文档：

- [`prd.md`](prd.md)
- [`../engineering-plan.md`](../engineering-plan.md)
- [`../plan.md`](../plan.md)

## 1. 研发目标

让中文用户可以主动下载并切换到 Qwen3-ASR，同时保持 SenseVoice 默认路径、English Moonshine/Parakeet 路径和用户数据不退化。

## 2. 交付边界

### 2.1 必须交付

- `sherpa-onnx-go*` 依赖升级到支持 Qwen3-ASR 的版本。
- 构建脚本兼容新版 `libonnxruntime` dylib。
- `qwen3-asr-0.6b` model profile。
- `BackendQwen3ASR = "qwen3_asr"` backend kind。
- Qwen3-ASR required files 与 tokenizer 目录校验。
- Qwen3-ASR sherpa config builder。
- 中文设置页模型选择 UI 显示 SenseVoice 和 Qwen3-ASR。
- SenseVoice 和 Qwen3-ASR 互相切换。
- 下载失败和初始化失败保护。
- SenseVoice、Moonshine、Parakeet 回归。
- 开发自查、代码复审、QA handoff。

### 2.2 明确不交付

- Qwen3-ASR 作为默认模型。
- Qwen3-ASR 删除 UI。
- 粤语独立语言 UI。
- 欧洲语言 UI。
- 多 Qwen3-ASR 变体选择。
- 正式 Developer ID notarization。

## 3. 推荐任务顺序

```text
T0 现状和官方资料确认
T1 sherpa-onnx-go* 依赖升级
T2 构建脚本 dylib 适配
T3 Qwen3-ASR profile
T4 tokenizer 目录校验增强
T5 Qwen3-ASR backend builder
T6 中文模型选择 UI
T7 下载/切换状态处理
T8 单元测试和前端构建
T9 代码复审
T10 QA handoff
T11 真机 QA 和测试包准备
```

## 4. 任务明细

### T0：现状和官方资料确认

完成标准：

- 明确当前 `v1.12.24` 不支持 `OfflineQwen3ASRModelConfig`。
- 明确目标依赖版本，初选 `v1.13.2`。
- 明确模型包 URL、大小、last-modified、required files。

### T1：sherpa-onnx-go* 依赖升级

工作内容：

- 升级：
  - `github.com/k2-fsa/sherpa-onnx-go`
  - `github.com/k2-fsa/sherpa-onnx-go-macos`
  - `github.com/k2-fsa/sherpa-onnx-go-linux`
  - `github.com/k2-fsa/sherpa-onnx-go-windows`
- 目标版本：`v1.13.2`。
- 更新 `go.mod`、`go.sum`。

完成标准：

- `go test ./... -count=1` 可通过。
- SenseVoice/Moonshine/Parakeet 现有 builder 编译通过。
- 没有 API 字段名不兼容。

### T2：构建脚本 dylib 适配

工作内容：

- 当前脚本写死：

```text
libonnxruntime.1.23.2.dylib
```

- 升级后 macOS module 提供：

```text
libonnxruntime.1.24.4.dylib
```

- 修改本地和 release 构建脚本：
  - 自动发现 `libonnxruntime.*.dylib`。
  - 或统一改为复制 `libonnxruntime.dylib` 并保留版本 dylib。
  - `install_name_tool` 逻辑必须适配新版文件名。

完成标准：

- arm64 本地构建通过。
- x86_64 本地构建通过，若本机工具链支持。
- App 签名验证通过。
- DMG 可生成并通过 `hdiutil verify`。

### T3：Qwen3-ASR profile

工作内容：

- 新增常量：
  - `Qwen3ASRModelID = "qwen3-asr-0.6b"`
  - `BackendQwen3ASR = "qwen3_asr"`
- 新增 `qwen3-asr-0.6b` profile。
- 将 `DefaultLanguageID` 的 `UpgradeModelIDs` 设置为 `[]string{Qwen3ASRModelID}`。
- 配置 required files。

完成标准：

- `GetModelProfile("qwen3-asr-0.6b")` 可返回完整 profile。
- 中文模型列表包含 SenseVoice 和 Qwen3-ASR。
- 中文默认仍是 SenseVoice。

### T4：tokenizer 目录校验增强

工作内容：

- 现有 required file rule 已支持 `AllOf` 相对路径。
- 需要确保 `tokenizer/merges.txt`、`tokenizer/vocab.json` 可以校验。
- 需要为 backend builder 提供 tokenizer 目录路径：
  - 可以新增 role `tokenizer` 指向目录。
  - 或在 builder 中从 `tokenizer_merges` 推导目录。

完成标准：

- 缺少 `tokenizer/merges.txt` 校验失败。
- 缺少 `tokenizer/vocab.json` 校验失败。
- `resolved.Files["tokenizer"]` 能得到 tokenizer 目录。

### T5：Qwen3-ASR backend builder

工作内容：

- `isSupportedBackend` 支持 `BackendQwen3ASR`。
- `offlineConfigForResolvedModel` 新增 Qwen3-ASR 分支。
- 设置：

```go
Qwen3ASR.ConvFrontend = resolved.Files["conv_frontend"]
Qwen3ASR.Encoder = resolved.Files["encoder"]
Qwen3ASR.Decoder = resolved.Files["decoder"]
Qwen3ASR.Tokenizer = resolved.Files["tokenizer"]
Qwen3ASR.MaxTotalLen = 1024
Qwen3ASR.MaxNewTokens = 256
Qwen3ASR.Temperature = 0.0
Qwen3ASR.TopP = 0.9
Qwen3ASR.Seed = 0
```

完成标准：

- Qwen3-ASR 引擎可初始化。
- `HardwareInfo()` 显示 `Qwen3-ASR · CPU`。
- 未知 backend 仍返回明确错误。

### T6：中文模型选择 UI

工作内容：

- 中文状态显示：
  - SenseVoice
  - Qwen3-ASR
- English 状态保持：
  - Moonshine English
  - Parakeet English
- UI 显示下载大小和下载进度。

完成标准：

- 中文用户能从 UI 下载 Qwen3-ASR。
- 下载完成后能使用 Qwen3-ASR。
- 能切回 SenseVoice。
- English 路径不出现错误模型切换。

### T7：下载/切换状态处理

工作内容：

- 下载期间禁用重复点击。
- 下载失败后保留原模型。
- 下载成功后切换到目标模型。
- 切换失败时原模型继续可用。
- `.downloads`、`.staging` 不被判定为可用模型。

完成标准：

- Qwen3-ASR 下载失败不破坏 SenseVoice。
- Qwen3-ASR 初始化失败不破坏 SenseVoice。
- English Moonshine/Parakeet 不受影响。

### T8：测试

后端：

```bash
cd privatevoice.src
go test ./... -count=1
```

前端：

```bash
cd privatevoice.src/frontend
npm run build
```

检查：

```bash
git diff --check
```

完成标准：

- 全部通过。
- 关键测试覆盖 profile、resolver、backend、服务 API。

### T9：代码复审

复审重点：

- 是否保持 SenseVoice 默认。
- 是否存在未安装 Qwen3-ASR 直接切换。
- 是否存在下载失败破坏旧模型。
- 是否在 English 路径误触发 Qwen3-ASR。
- sherpa 依赖升级是否破坏 Moonshine/Parakeet。
- 构建脚本是否不再硬编码旧 dylib。

### T10：QA handoff

交付：

- QA handoff 文档。
- 开发自查日志。
- 已知风险。
- Qwen3-ASR 真实下载 URL 和大小。
- 依赖升级说明。

### T11：测试包准备

若 QA 预检通过：

- 递增版本到 `2.1.23`。
- 生成新 build 编号。
- 构建 `.dmg`。
- 生成 `RELEASE_MANIFEST.md`。
- 验证 DMG。
- tag。