# Round 4 研发任务拆解：Parakeet English 高级模型

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

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

## 1. 研发目标

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

## 2. 交付边界

### 2.1 必须交付

- `parakeet-en` model profile。
- `BackendNemoTransducer` backend kind。
- Parakeet required files 校验。
- Parakeet sherpa config builder。
- 模型选择 API：
  - 列出当前语言可用模型。
  - 获取每个模型安装状态。
  - 选择已安装模型。
  - 下载并选择未安装模型。
- English 设置页模型选择 UI。
- Moonshine 和 Parakeet 互相切换。
- 下载失败保护。
- 开发自查、代码复审、QA handoff。

### 2.2 明确不交付

- Qwen3-ASR。
- 欧洲语言 UI。
- 多 Parakeet 变体选择。
- 自动删除模型。
- 正式签名和 notarization。

## 3. 推荐任务顺序

```text
T0 现状确认
T1 Parakeet profile
T2 Nemo transducer backend builder
T3 模型选择服务 API
T4 设置页模型选择 UI
T5 下载/切换状态处理
T6 单元测试和前端构建
T7 代码复审
T8 QA handoff
T9 测试包准备
```

## 4. 任务明细

### T0：现状确认

重点文件：

- `privatevoice.src/internal/model/profile.go`
- `privatevoice.src/internal/model/registry.go`
- `privatevoice.src/internal/model/resolver.go`
- `privatevoice.src/internal/engine/engine.go`
- `privatevoice.src/internal/engine/engine_darwin.go`
- `privatevoice.src/services/engine_service.go`
- `privatevoice.src/frontend/src/components/settings/GeneralPage.svelte`

完成标准：

- 明确 Round 3 current model resolver 行为。
- 明确设置页现有语言切换路径。
- 明确前端能否复用 `EngineService.DownloadCurrentModel()`。

### T1：Parakeet profile

工作内容：

- 新增常量：
  - `ParakeetModelID = "parakeet-en"`
  - `BackendNemoTransducer = "nemo_transducer"`
- 新增 `parakeet-en` profile。
- 配置 required files：
  - `encoder.int8.onnx`
  - `decoder.int8.onnx`
  - `joiner.int8.onnx`
  - `tokens.txt`
- `ProviderOrder` 使用 `cpu`。
- `DownloadURLs` 使用官方 unified-en 0.6b int8 URL。

完成标准：

- `GetModelProfile("parakeet-en")` 可返回完整 profile。
- `ValidateModelDir(parakeet-en)` 校验准确。
- profile 不改变 English 默认模型，English 默认仍是 `moonshine-en`。

### T2：Nemo transducer backend builder

工作内容：

- `NewWithResolvedModel` 支持 `BackendNemoTransducer`。
- 新增 `buildNemoTransducerConfig`。
- 设置：

```go
Transducer.Encoder = resolved.Files["encoder"]
Transducer.Decoder = resolved.Files["decoder"]
Transducer.Joiner = resolved.Files["joiner"]
Tokens = resolved.Files["tokens"]
ModelType = "nemo_transducer"
Provider = "cpu"
```

完成标准：

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

### T3：模型选择服务 API

工作内容：

- 新增或扩展服务 API：
  - `ListModelOptions()`
  - `SelectModel(modelID string)`
  - `DownloadModelByID(modelID string)`
  - `DeleteModel(modelID string)` 可暂缓，不作为本轮强制交付。
- 选择模型时：
  - 合法性校验。
  - 语言兼容性校验。
  - 未安装模型不能直接选择，应提示下载。
  - 已安装模型选择后设置 `ModelSelectionMode=manual`。
  - 更新 `SelectedModelID`。
  - 触发 engine reload。

完成标准：

- English 可选 Moonshine/Parakeet。
- 中文不自动选择 Parakeet。
- 选择非法模型返回错误，不写坏配置。

### T4：设置页模型选择 UI

工作内容：

- 在设置页语言区域附近新增模型选择区域。
- English 显示 Moonshine 和 Parakeet。
- 中文至少显示 SenseVoice。
- UI 显示：
  - 当前使用。
  - 已安装/未安装。
  - 下载大小。
  - 下载/使用按钮。
  - 下载中进度。

完成标准：

- English 用户能从 UI 下载 Parakeet。
- 下载完成后能使用 Parakeet。
- 能切回 Moonshine。
- UI 不显示误导性默认策略。

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

工作内容：

- 下载期间禁用重复点击。
- 下载失败后保留原模型。
- 下载成功后切换到目标模型。
- 切换失败时回到原模型或显示 error，不破坏配置。

完成标准：

- Parakeet 下载失败不破坏 Moonshine。
- Parakeet 初始化失败不破坏 SenseVoice。
- `.downloads`、`.staging` 不被判定为可用模型。

### T6：测试

后端：

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

前端：

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

检查：

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

完成标准：

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

### T7：代码复审

复审重点：

- 是否保持 Moonshine 默认。
- 是否存在未安装模型直接切换。
- 是否存在下载失败破坏旧模型。
- 是否在中文路径误触发 Parakeet。
- UI 状态是否会误导用户。

### T8：QA handoff

交付：

- QA handoff 文档。
- 开发自查日志。
- 已知风险。
- Parakeet 真实下载 URL 和大小。

### T9：测试包准备

若 QA 预检通过：

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