Document X-ASR experiment branch

Ariver

2026-06-07 c721471f3778334f0cdcfdd3a098e1353652762a

Document X-ASR experiment branch

 02-P-NBL/engineering-plan.md

@@ -253,6 +253,34 @@
- 体积大于 Moonshine English。
- 用户主动下载后可切换。

### 6.5 X-ASR-zh-en（未来候选）

```text
id: x-asr-zh-en
backendKind: zipformer_transducer_streaming
tier: experimental
recommendedFor: zh-CN, en
installDirName: x-asr-zh-en
requiredFiles:
  - encoder-<chunk>.onnx
  - decoder-<chunk>.onnx
  - joiner-<chunk>.onnx
  - tokens.txt
```

初始策略：

- 只做实验性 profile，不进入第一阶段普通模型列表。
- 不同时下载四个 chunk 变体；先选 `480 ms` 或 `960 ms` 之一做 Apple Silicon 真机 spike。
- 如果当前 Go 绑定不能稳定支持 streaming `OnlineRecognizer`，先做独立 prototype，不接入正式 EngineFactory。

备注：

- X-ASR-zh-en 是 Zipformer transducer，基于 sherpa-onnx，技术栈方向与当前项目一致。
- 主要价值是低延迟流式识别和中英混输，不是单纯追求最高离线准确率。
- benchmark 显示其离线平均结果接近但低于 Qwen3-ASR 0.6B，高于/接近 SenseVoice-small；因此更适合作为“实时输入候选”，而不是 Qwen3-ASR 替代品。
- 进入产品前必须复核 Apache-2.0 license、模型卡、技术报告和训练数据说明。

## 7. 配置文件扩展

当前 config 需要新增字段。
@@ -406,6 +434,8 @@
    buildNemoTransducerConfig(profile)
case "qwen3_asr":
    buildQwen3ASRConfig(profile)
case "zipformer_transducer_streaming":
    buildXASRStreamingConfig(profile)
}
```


 02-P-NBL/freeze/20260607-x-asr-experiment-branch.md

New file
@@ -0,0 +1,53 @@
# 2026-06-07 X-ASR 实验分支与回滚基线

## 目的

为 X-ASR 效果实验创建独立开发线，同时固定 2.1.28 App Store 上传包的可回滚基线。实验失败时不得覆盖已验证的 2.1.28 上架包源码与 tag。

## 已冻结基线

- App Store 上传包版本：`2.1.28`
- App Store 上传包 build：`20260605.0353`
- 发布 tag：`v2.1.28-build20260605.0353-appstore-upload`
- 源码 commit：`82ce4aa571dfa74032d4697984cc932257cfa35b`
- 回滚分支：`codex/freeze-2.1.28-appstore-20260605.0353`
- 上传包 SHA256：`2d0e4fa7b79b70cc771086bbb124329fd4bb923849061f441d03b7391074d4cc`

上传包路径：

```text
/Users/ar/Desktop/PrivateVoice-26.0604上架/02-上传包/PrivateVoice-Dictation-2.1.28-build20260605.0353-universal-macappstore.pkg
```

## 实验分支

- 分支：`codex/x-asr-experiment-2.1.29`
- 分支起点：`793682b82812d3e89adcc354dd8b844af094ce13`
- 用途：只做 X-ASR 技术 spike、模型接入验证、性能/体积评估和必要的实验构建。

## 回滚方式

回到已上传 2.1.28 源码基线：

```bash
git switch codex/freeze-2.1.28-appstore-20260605.0353
```

或直接回到发布 tag：

```bash
git switch --detach v2.1.28-build20260605.0353-appstore-upload
```

## 今晚新版本门禁

- 如果实验要生成可给用户测试的包，版本必须递增到 `2.1.29`。
- 每次可分发包必须使用新的 `YYYYMMDD.HHMM` build 编号。
- 打包前必须提交所有会影响构建的源码改动。
- 新包必须生成 `.dmg`、SHA256、manifest、QA 记录和 release tag。
- 不得把实验包混称为 App Store 正式包；未通过 QA 前只称为实验/候选测试包。
- Mac App Store 构建必须检查 `ITSAppUsesNonExemptEncryption=false`、Bundle ID、entitlements、category、universal 架构和 quarantine。

## 当前注意事项

创建实验分支时，工作区已经存在若干历史 release 文件、构建产物和计划文档改动。它们不属于 2.1.28 已冻结源码基线；后续进入正式 2.1.29 打包前，必须只提交本轮有意纳入的源码、配置和文档。

 02-P-NBL/plan.md

@@ -28,6 +28,7 @@
Round 4：接英文高级 Parakeet
Round 5：接中文高级 Qwen3-ASR
Round 6：完善模型管理和未来欧洲语言扩展
Round 7：X-ASR 流式中英混输候选模型评估
```

第一期可交付版本建议至少做到：
@@ -48,6 +49,7 @@
| Round 4 | Parakeet 高级模型 | 英文用户可下载 Parakeet | 中 |
| Round 5 | Qwen3-ASR 高级模型 | 中文用户可下载 Qwen3-ASR | 高 |
| Round 6 | 模型管理成熟化 + 欧洲语言准备 | 删除、回滚、未来多语言 | 中 |
| Round 7 | X-ASR 流式候选模型评估 | 未来可能支持实时边说边出字和中英混输 | 中高 |

## 3. Round 1：模型 Profile 基础设施

@@ -431,9 +433,56 @@
中等。
建议 4-8 个研发日。

## 9. 推荐发布组合
## 9. Round 7：X-ASR 流式中英混输候选模型评估

### 9.1 内部技术版本
### 9.1 目标

评估 `Gilgamesh-J/X-ASR` 的 `X-ASR-zh-en` 是否值得纳入未来模型选项，重点不是“再加一个模型”，而是判断它能否带来当前模型没有覆盖好的实时输入价值。

### 9.2 产品假设

X-ASR 的价值主要来自：

- 中文/英文双语和中英混输。
- true streaming decoding，可支撑未来“边说边出字”。
- 基于 sherpa-onnx，和当前模型技术栈方向一致。
- 相比 Qwen3-ASR，可能牺牲一部分离线准确率，换取更小模型规模和更强低延迟交互能力。

### 9.3 范围

评估项：

- 下载并整理 `X-ASR-zh-en` 单个 chunk 变体。
- 初始只选一个 chunk，不带四个 chunk 全量包。
- 优先测试 `480 ms` 或 `960 ms`：前者偏低延迟，后者偏准确率。
- 新增实验性 `x-asr-zh-en` profile，但默认隐藏在普通用户 UI 之外。
- 验证 sherpa-onnx Go 绑定是否支持当前所需 streaming API。
- 如当前离线 Engine 接口不适合，先做独立 streaming prototype，不直接接入正式录音上屏链路。

### 9.4 不做

- 不替换 SenseVoice 中文默认模型。
- 不替换 Qwen3-ASR 中文高级模型。
- 不替换 Moonshine/Parakeet English 路线。
- 不把四个 chunk 一起发布。
- 不在技术报告和合规材料补齐前作为正式推荐模型。

### 9.5 验收标准

- 明确 X-ASR 与 SenseVoice、Qwen3-ASR、Moonshine、Parakeet 的定位差异。
- 至少完成 Apple Silicon 真机延迟、内存、发热、识别质量 smoke test。
- 覆盖中文、中英混输、英文技术词、长句口述和噪声样本。
- 输出是否进入产品路线的决策：`放弃 / 保留研究 / 实验入口 / 正式候选`。
- 如果进入产品路线，补齐模型 profile、下载、校验、删除、失败回退和 license notice 方案。

### 9.6 预估工作量

中高。
建议 3-5 个研发日做技术 spike；如果进入正式产品化，再单独拆 Round。

## 10. 推荐发布组合

### 10.1 内部技术版本

```text
Round 1
@@ -443,7 +492,7 @@

- 验证 profile 抽象不会破坏现有 SenseVoice。

### 9.2 English MVP
### 10.2 English MVP

```text
Round 1 + Round 2 + Round 3
@@ -455,7 +504,7 @@
- 默认 Moonshine English。
- 形成英文用户可用版本。

### 9.3 English Pro
### 10.3 English Pro

```text
Round 4
@@ -465,7 +514,7 @@

- 为英文用户提供 Parakeet 高级模型。

### 9.4 Chinese Pro
### 10.4 Chinese Pro

```text
Round 5
@@ -475,7 +524,7 @@

- 为中文用户提供 Qwen3-ASR 高级模型。

### 9.5 多语言准备版
### 10.5 多语言准备版

```text
Round 6
@@ -486,9 +535,20 @@
- 稳定模型管理。
- 为未来欧洲语言版本做技术准备。

## 10. 关键依赖
### 10.6 实时输入探索版

### 10.1 模型包确认
```text
Round 7
```

目的：

- 验证 X-ASR 是否能支撑实时中英混输输入体验。
- 在不影响当前正式模型路线的前提下，为未来“边说边出字”做技术判断。

## 11. 关键依赖

### 11.1 模型包确认

每个模型需要确认：

@@ -500,16 +560,16 @@
- macOS 可运行性。
- sherpa-onnx 当前 Go 绑定支持情况。

### 10.2 sherpa-onnx 版本
### 11.2 sherpa-onnx 版本

当前项目使用 `v1.12.24`。
Qwen3-ASR 在较新版本中支持更完整。建议在 Round 1 或 Round 5 前评估是否升级到较新 `sherpa-onnx-go`。

### 10.3 UI 文案
### 11.3 UI 文案

English 分支需要完整英文 UI 文案，不只是模型页面。

### 10.4 回归测试音频
### 11.4 回归测试音频

需要准备：

@@ -518,8 +578,9 @@
- 英文短句。
- 英文技术词。
- Parakeet 支持语言样例，后续使用。
- X-ASR 中英混输和实时 partial 输出样例，后续使用。

### 10.5 后续 UI 与品牌命名调整
### 11.5 后续 UI 与品牌命名调整

以下需求已进入 `v2.1.24 build 20260603.1934` 品牌命名调整：

@@ -527,7 +588,7 @@
- App 正式名称从 `PrivateVoice Input` 改为 `PrivateVoice Dictation`。
- 本轮不迁移用户数据目录，继续使用既有 `Application Support/PrivateVoice Input`，避免影响历史记录、模型文件和系统权限。

## 11. 总体建议
## 12. 总体建议

最稳的执行策略：

@@ -538,8 +599,10 @@
发布 English MVP
再做 Round 4 和 Round 5
最后做 Round 6
单独做 Round 7 X-ASR 技术 spike
```

不要在 Round 1 里同时接 Moonshine、Parakeet、Qwen3-ASR。
不要在 English MVP 之前先做 30 种语言 UI。
不要把 Parakeet 和 Qwen3-ASR 作为默认模型自动下载。
不要把 X-ASR 混入当前正式模型发布链路；先证明实时输入价值。

 02-P-NBL/product-plan.md

@@ -296,6 +296,48 @@
- 用户主动下载后可切换。
- Moonshine English 保留作为 fallback。

### 8.5 X-ASR-zh-en（未来候选）

产品定位：

- 未来候选的中文/英文低延迟流式模型。
- 适合“边说边出字”、中英自由混输、长句口述、代码/写作实时输入等交互方向。
- 不替代当前第一阶段四模型，不作为默认模型；先作为研究和原型验证项。

相对现有模型的潜在用户价值：

- 相对 SenseVoice：更明确面向中文/英文流式识别和低延迟部署，可能提升中英混输、长句、实时反馈体验。
- 相对 Qwen3-ASR：质量指标整体低于 Qwen3-ASR 0.6B/1.7B，但模型规模更小、流式能力更强，可能成为“实时输入模式”的更合适选择。
- 相对 Moonshine/Parakeet：覆盖中文和英文双语，能减少用户在中文/英文之间手动切换模型的频率。

已知资料摘要：

- 项目：`Gilgamesh-J/X-ASR`
- 模型：`X-ASR-zh-en`
- 架构：Zipformer transducer
- 运行时：sherpa-onnx
- 语言：Chinese + English
- 模式：offline decoding + true streaming decoding
- chunk 选项：160 ms、480 ms、960 ms、1920 ms
- License：Apache-2.0
- 技术报告：Coming Soon

产品策略：

- 不随 App 默认打包。
- 不一次性带四个 chunk 变体；先选一个候选 chunk 做真机评估。
- 初始评估优先 `480 ms` 或 `960 ms`：`480 ms` 偏实时反馈，`960 ms` 偏准确率和稳定性。是否采用 `160 ms` 或 `1920 ms` 由真机延迟/准确率测试决定。
- 如果只服务当前“说完再上屏”模式，X-ASR 优先级低于 Qwen3-ASR；如果要做“实时边说边出字”，X-ASR 优先级升高。

进入产品前必须验证：

- Go 端是否能用现有 sherpa-onnx 绑定稳定加载 Zipformer transducer streaming 模型。
- 是否需要新增 `OnlineRecognizer`/streaming engine，而不是复用当前离线 `Engine` 接口。
- Apple Silicon 上 CPU 延迟、内存占用、发热和长时间运行稳定性。
- 中英混输、中文标点、英文大小写、技术词和噪声场景的真机样本效果。
- 模型文件体积、下载速度、断点续传和磁盘占用。
- Apache-2.0 license、模型卡、训练数据说明和后续技术报告发布后的合规复核。

## 9. 推荐用户流程

### 9.1 中文用户首次使用
@@ -397,3 +439,5 @@
- sherpa-onnx Qwen3-ASR: https://k2-fsa.github.io/sherpa/onnx/qwen3-asr/index.html
- sherpa-onnx Qwen3-ASR pretrained model: https://k2-fsa.github.io/sherpa/onnx/qwen3-asr/pretrained.html
- SenseVoice 2025-09-09 model files: https://huggingface.co/csukuangfj/sherpa-onnx-sense-voice-zh-en-ja-ko-yue-int8-2025-09-09/tree/main
- X-ASR GitHub project: https://github.com/Gilgamesh-J/X-ASR
- X-ASR-zh-en model artifacts: https://huggingface.co/GilgameshWind/X-ASR-zh-en

 TODO.md

@@ -13,7 +13,16 @@

## Todo

- 无
- [2026-06-05] 将 X-ASR 列为未来候选模型并做技术 spike。
  - 定位: 不是替换现有首批四模型，而是评估 `X-ASR-zh-en` 对实时中英混输、“边说边出字”的价值。
  - 初始策略: 只选一个 chunk 变体做 Apple Silicon 真机测试，优先 `480 ms` 或 `960 ms`，不把四个 chunk 全量打包。
  - 技术验证: sherpa-onnx Go streaming API、Zipformer transducer config、CPU 延迟、内存、发热、VAD/endpointing、partial/final 上屏链路。
  - 产品验证: 与 SenseVoice、Qwen3-ASR、Moonshine、Parakeet 对比，确认是否进入 `实验入口 / 正式候选 / 放弃`。
  - 合规验证: Apache-2.0 license notice、模型卡、技术报告和训练数据说明补齐后再产品化。
- [2026-06-05] 在 Mac App Store 构建配置中写入 `ITSAppUsesNonExemptEncryption=false`。
  - 目的: 避免 App Store Connect 每次上传 build 后显示 `Missing Compliance` 并要求手动填写 App Encryption Documentation。
  - 前提: 当前 App 不实现、打包或接入非 Apple 操作系统提供的加密算法。
  - 验收: 生成的 Mac App Store `.app` 内 `Info.plist` 包含 `ITSAppUsesNonExemptEncryption`，值为 `false`；如后续引入第三方/自实现加密库，需重新评估出口合规。

## Done