# 2026-06-29 双构建线

## 用户目标

- 解决 2.1.36 本地验证包在 macOS Monterey 12.7.4 M1 上无法打开的问题。
- 必须采用双构建线：
  - macOS 14+ 默认构建继续支持 Qwen3-ASR。
  - macOS 14 以下兼容构建禁用 Qwen3-ASR。
- 为保证 UI 一致性，Monterey 兼容包中 Qwen3-ASR 不隐藏，只置灰禁用并说明需要 macOS 14+。

## 已完成事项

- 确认根因：默认依赖 `github.com/k2-fsa/sherpa-onnx-go-macos@v1.13.2` 内置 `libonnxruntime.1.24.4.dylib`，最低系统版本为 macOS 14.0，导致 Monterey 不能启动。
- 新增 Monterey 兼容构建线：
  - `privatevoice.src/go.monterey.mod`
  - `privatevoice.src/go.monterey.sum`
  - `privatevoice.src/scripts/build-local-macos-monterey.sh`
- 保持主 `go.mod` 不降级，默认 macOS 14+ 构建继续使用 sherpa `v1.13.2` 并支持 Qwen3-ASR。
- 默认 macOS 14+ 构建声明 `LSMinimumSystemVersion=14.0`；Monterey 兼容脚本覆盖为 `LSMinimumSystemVersion=11.0`。
- 用 `monterey_compat` build tag 隔离 Qwen3-ASR 编译路径：
  - 默认构建编译 Qwen3-ASR 配置。
  - Monterey 构建编译 Qwen3-ASR 拒绝路径。
- 后端新增模型构建能力状态：
  - 默认构建：`qwen3-asr-0.6b` 支持。
  - Monterey 构建：`qwen3-asr-0.6b` 返回 `supportedInBuild=false` 与 `unsupportedReason=requires_macos_14`。
- 前端输入配置页保留 Qwen3-ASR 条目，但在 Monterey 兼容包里置灰、禁用按钮，并提示“Qwen3-ASR 需要 macOS 14 或更高版本，本兼容包暂不支持下载。”
- 版本更新为 `2.1.37 (build 20260629.0059)`，并更新 `CHANGELOG.md`。

## 关键决策

- 不再把整个项目依赖降级到旧 sherpa；改为双构建线，避免牺牲 macOS 14+ 用户的 Qwen3-ASR 能力。
- Monterey 兼容线使用 sherpa `v1.12.20`，因为该线的 onnxruntime 最低系统版本为 macOS 11.0，且比 v1.11.4 更新。
- Qwen3-ASR 在 Monterey 包中不隐藏，只置灰禁用，避免 UI 列表结构在不同包中跳变。

## 文件变更

- Commit: `4f52723 Add Monterey compatibility build line`
- 主要文件：
  - `privatevoice.src/internal/engine/engine_darwin_qwen3.go`
  - `privatevoice.src/internal/engine/engine_darwin_qwen3_monterey.go`
  - `privatevoice.src/internal/model/build_capabilities*.go`
  - `privatevoice.src/internal/modelselection/selection.go`
  - `privatevoice.src/services/engine_service.go`
  - `privatevoice.src/frontend/src/components/settings/LanguagePage.svelte`
  - `privatevoice.src/scripts/build-local-macos.sh`
  - `privatevoice.src/scripts/build-local-macos-monterey.sh`
  - `privatevoice.src/go.monterey.mod`
  - `privatevoice.src/go.monterey.sum`
  - `CHANGELOG.md`

## 验证结果

- `go test ./...` 通过。
- `go test -modfile=go.monterey.mod -tags=monterey_compat ./...` 通过。
- `npm run build` 通过；仍有既有 Svelte a11y warning，非本轮新增。
- 默认 macOS 14+ DMG 与 Monterey 兼容 DMG 均构建通过，签名和 `hdiutil verify` 通过。
- 构建产物：
  - 默认 macOS 14+ 包：`/Users/ar/Projects/PrivateVoice/privatevoice.src/build/local/arm64/PrivateVoice Dictation-2.1.37-build20260629.0059-arm64-local.dmg`
  - `/Users/ar/Projects/PrivateVoice/privatevoice.src/build/local/arm64/PrivateVoice Dictation-2.1.37-build20260629.0059-arm64-monterey-local.dmg`
  - 兼容短名：`/Users/ar/Projects/PrivateVoice/privatevoice.src/build/local/arm64/PrivateVoice Dictation-2.1.37-arm64-monterey-local.dmg`
- SHA256：
  - 默认 macOS 14+ 包：`8ebdcbbc7f25a8dc1e30bd9289a705b180ff47bdc68532f20678c63ec6007073`
  - Monterey 兼容包：`fb930fdc279773f9431649f0655fa4a3582be5f31d2f1a0922c1ee20d4097e63`
- 最低系统版本校验：
  - 默认 macOS 14+ 包：`Info.plist LSMinimumSystemVersion=14.0`，`libonnxruntime.1.24.4.dylib minos 14.0`
  - Monterey 兼容包：`Info.plist LSMinimumSystemVersion=11.0`
  - `libonnxruntime.1.17.1.dylib`：`minos 11.0`
  - `libsherpa-onnx-c-api.dylib`：`minos 11.0`
- Monterey 包内 Frameworks 只包含：
  - `libonnxruntime.1.17.1.dylib`
  - `libsherpa-onnx-c-api.dylib`
- 未发现 `com.apple.quarantine` 扩展属性。

## 未决问题

- 仍需用户在真实 macOS Monterey 12.7.4 M1 上安装打开验证。
- 默认 macOS 14+ 包尚未重新打包，本轮只交付 Monterey 兼容验证包。
- Go 链接阶段在当前机器上会输出“object file built for newer macOS version”的 warning，但最终 Monterey 兼容包的主程序和 dylib `minos` 均为 11.0。

## 后续建议

- 若 Monterey 真实机验证通过，可以保留两个分发入口：
  - macOS 14+：默认包，支持 Qwen3-ASR。
  - macOS 11-13：Monterey 兼容包，禁用 Qwen3-ASR。
- 发布文案或下载页需要明确说明 Qwen3-ASR 需要 macOS 14 或更高版本。