edit | blame | history | raw

2026-07-02 粤语开发实现

用户目标

基于 /Users/ar/Projects/PrivateVoice/02-P-NBL/round-6/requirements-dev.md 落地粤语版需求，开发版本记录为 2.2.0，并完成 Todo、两位代码审核员审核和 QA 回归测试。

已完成事项

  • 新建并完成 Round 6 Todo：/Users/ar/Projects/PrivateVoice/02-P-NBL/round-6/todo-dev.md。
  • 新增粤语语言 profile：yue-HK / 粤语，顺序位于中文之后、English 之前。
  • 新增 SenseVoice Yue 模型 profile：sensevoice-yue-2025-09-09。
  • SenseVoice Yue 加载时传入 sense_voice.language = yue。
  • 粤语模型列表只展示 SenseVoice Yue，不把 Qwen3-ASR / X-ASR 作为粤语专项模型展示。
  • 修复语言切换安全语义：未安装目标语言只在输入页本地预览，不持久化语言、不 reload engine；下载或选择成功后才正式写入目标语言并 reload。
  • 修复 reload 失败兜底：如果已有 engine，initEngine 失败时保留旧 engine。
  • Windows preview 支持 SenseVoice backend，包括中文与粤语；非 SenseVoice 模型仍禁用。
  • 版本元数据更新为 2.2.0 / 20260702.0236。
  • 两位代码审核员最终 APPROVE，QA 最终 PASS。

核心事实 / 变更快照

  • 变更对象：PrivateVoice 输入语言与离线模型 registry。
  • 事实来源：
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/internal/model/profile.go
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/internal/model/registry.go
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/internal/engine/engine_darwin.go
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/internal/engine/engine_windows.go
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/internal/engine/engine_linux.go
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/services/engine_service.go
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/frontend/src/components/settings/LanguagePage.svelte
  • 变更前：无独立粤语语言项；粤语不能作为单独输入配置中心语言选择；SenseVoice 默认中文模型不固定 language=yue。
  • 变更后：
  • Language ID：yue-HK
  • Display：Cantonese / 粤语
  • UI locale：zh
  • System matchers：yue, yue-HK
  • Default model：sensevoice-yue-2025-09-09
  • Model display：SenseVoice Yue
  • Backend：sensevoice
  • Required files：model.int8.onnx, tokens.txt
  • Download URL：https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models/sherpa-onnx-sense-voice-zh-en-ja-ko-yue-int8-2025-09-09.tar.bz2
  • Engine parameter：LanguageParam = "yue"
  • 粤语 UpgradeModelIDs 为空，因此 Qwen3-ASR / X-ASR 不作为粤语模型选项出现。
  • 映射 / 归并 / 删除：
  • NormalizeLanguageID("yue") -> "yue-HK"。
  • zh-HK 未自动映射到粤语，继续按保守策略落到中文，避免误判香港用户默认粤语。
  • Qwen3-ASR / X-ASR 保留在中文/英文相关路径，不迁移为粤语专项模型。
  • 范围边界：
  • 本轮不做独立 App 包、不做官网销售页、不做授权/支付/自动更新、不接入 Fun-ASR-Nano。
  • 未安装目标语言只在当前输入页预览；下载失败或取消不改变正式语言配置和旧 engine。
  • 真实粤语语音质量和 Windows 真机运行仍需后续实机 smoke。
  • 验证证据：
  • Ptolemy：最终 APPROVE。
  • Helmholtz：最终 APPROVE。
  • Nietzsche：最终 QA PASS。
  • go test ./... -count=1 通过。
  • npm --prefix frontend run build 通过。
  • Windows cross go test -exec=/usr/bin/true ./... 通过。
  • git diff --check 通过。

文件变更

  • /Users/ar/Projects/PrivateVoice/02-P-NBL/round-6/todo-dev.md
  • /Users/ar/Projects/PrivateVoice/CHANGELOG.md
  • /Users/ar/Projects/PrivateVoice/CODEGRAPH.md
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/app.go
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/app_live_caption_test.go
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/build/config.yml
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/build/darwin/Info.plist
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/frontend/package.json
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/frontend/package-lock.json
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/frontend/src/components/settings/LanguagePage.svelte
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/frontend/src/lib/i18n/en.json
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/frontend/src/lib/i18n/zh.json
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/internal/engine/engine_darwin.go
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/internal/engine/engine_darwin_test.go
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/internal/engine/engine_linux.go
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/internal/engine/engine_windows.go
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/internal/language/language_test.go
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/internal/model/build_capabilities_windows.go
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/internal/model/model_test.go
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/internal/model/profile.go
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/internal/model/registry.go
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/internal/modelselection/selection_test.go
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/scripts/build-windows-preview.sh
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/services/engine_service.go
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/services/engine_service_test.go
  • /Users/ar/Projects/PrivateVoice/privatevoice.src/services/engine_service_windows_test.go

关键决策

  • 粤语不做独立 App 包，先作为同一 App 的一个输入语言 profile。
  • 粤语默认模型使用 SenseVoice Yue 2025-09-09，不是 Qwen3-ASR / X-ASR。
  • zh-HK 不默认映射到粤语。
  • 未安装语言切换采用 pending preview 语义，避免 UI 显示已切换但实际仍用旧模型。
  • 下载成功后，如果下载的是目标语言默认模型，使用 ModelSelectionMode=auto，不强写 SelectedModelID。

可复用命令 / Runbook

用途：复查 Round 6 粤语语言版本的后端、前端、Windows cross 和 diff 基础质量。

前置条件：在 /Users/ar/Projects/PrivateVoice/privatevoice.src 下执行；Windows cross test 需要本机存在 x86_64-w64-mingw32-gcc / x86_64-w64-mingw32-g++。

cd /Users/ar/Projects/PrivateVoice/privatevoice.src
go test ./services -count=1
npm --prefix frontend run build
go test ./... -count=1
GOOS=windows GOARCH=amd64 CGO_ENABLED=1 CC=x86_64-w64-mingw32-gcc CXX=x86_64-w64-mingw32-g++ go test -exec=/usr/bin/true ./...
git -C /Users/ar/Projects/PrivateVoice diff --check

验证步骤：所有命令退出码应为 0。当前存在既有 macOS linker warning 和既有 Svelte a11y warning，不作为 Round 6 阻塞。

清理 / 恢复：无临时项目文件需要清理；QA 子代理使用的 /tmp/privatevoice-qa-* 构建目录可由系统临时目录回收。

搜索关键词：Round 6、粤语、SenseVoice Yue、yue-HK、pendingLanguageID、SelectModelForLanguage、ListModelOptionsForLanguage。

未决问题

  • 尚未下载并解包真实 SenseVoice Yue 模型做 macOS 实机初始化 smoke。
  • 尚未在 Windows 真机验证粤语模型下载、加载、录音、识别和上屏。
  • CHANGELOG.md 历史中已存在旧的 v2.2.0 (2026-02-26) 条目；本轮按用户要求新增 v2.2.0 (2026-07-02)，对外发布前建议确认版本叙事。

后续建议

  • 下一轮先做真实模型 smoke：下载 SenseVoice Yue，验证文件校验、engine 初始化、粤语短句识别和上屏。
  • 若要交付测试包，再按发布规则生成新的可安装包；本轮只完成源码实现、审核和 QA，不默认打包。