# 2026-06-30 Windows 预览版

## 用户目标

以 `2.1.38` 为基线，启动一个 Windows 技术预览版分支，先验证应用能在 Windows 上启动、录音、中文识别，并把识别文字上屏；不影响现有 macOS 分支和上架线。

## 当前起点

- 基线 tag: `v2.1.38-build20260629.2014-diagnostic`
- 基线 commit: `9d4f977`
- 新分支: `codex/windows-preview-2.1.38`
- 新 worktree: `/Users/ar/Projects/PrivateVoice/.worktrees/windows-preview-2.1.38`

## 已完成事项

- 从 `2.1.38` tag 创建隔离 Windows preview worktree。
- 运行 Windows cgo 交叉编译，确认项目可以生成 Windows x64 可执行文件。
- 新增稳定脚本 `privatevoice.src/scripts/build-windows-preview.sh`，生成完整 Windows preview 目录和 zip。
- 新增 `privatevoice.src/scripts/QA-WINDOWS-PREVIEW.ps1`，打进预览包，用于 Windows 真机启动 App、提示完成一次听写，并收集进程、日志、配置和 QA 结果。
- 增强 `QA-WINDOWS-PREVIEW.ps1`：脚本会自动创建并打开 Notepad 目标文件 `qa-target.txt`，要求测试者把识别结果输入并保存，然后采集 `qa-target-dictation-text.txt` 作为上屏证据。
- 新增 `privatevoice.src/scripts/verify-windows-qa-evidence.sh`，用于验证 Windows 返回的 `qa-evidence-*.zip` 是否同时证明启动、引擎就绪、录音、识别、上屏和 Windows 系统信息。
- 增强 `QA-WINDOWS-PREVIEW.ps1`：收集 WebView2 Runtime 注册表信息到 `webview2-runtime.txt`，收集音频端点清单到 `audio-endpoints.txt`，帮助定位 Windows 启动或录音失败原因。
- Windows preview 包含:
  - `PrivateVoice Dictation.exe`
  - `onnxruntime.dll`
  - `sherpa-onnx-c-api.dll`
  - `sherpa-onnx-cxx-api.dll`
  - `RUN-WINDOWS-QA.cmd`
  - `QA-WINDOWS-PREVIEW.ps1`
  - `README-WINDOWS-PREVIEW.txt`
- 新增 `privatevoice.src/scripts/RUN-WINDOWS-QA.cmd`，作为 Windows 用户可双击运行的 QA 启动器，内部调用 `QA-WINDOWS-PREVIEW.ps1` 并保留退出提示。
- Windows build 下只开放 `SenseVoice`，其他模型仍可见但置灰禁用，避免用户在 PC 上选择未验证模型。
- 新增 Windows build capability 测试。
- 新增 `CODEGRAPH.md`，记录核心平台入口、Windows preview 范围和标准验证命令。
- 更新 `CHANGELOG.md`，说明 Windows 技术预览边界。

## 代码变更

- `privatevoice.src/internal/model/build_capabilities.go`
- `privatevoice.src/internal/model/build_capabilities_default.go`
- `privatevoice.src/internal/model/build_capabilities_monterey.go`
- `privatevoice.src/internal/model/build_capabilities_windows.go`
- `privatevoice.src/services/engine_service.go`
- `privatevoice.src/services/engine_service_qwen3_default_test.go`
- `privatevoice.src/services/engine_service_windows_test.go`
- `privatevoice.src/frontend/src/components/settings/LanguagePage.svelte`
- `privatevoice.src/frontend/src/lib/i18n/zh.json`
- `privatevoice.src/frontend/src/lib/i18n/en.json`
- `privatevoice.src/scripts/build-windows-preview.sh`
- `privatevoice.src/scripts/RUN-WINDOWS-QA.cmd`
- `privatevoice.src/scripts/QA-WINDOWS-PREVIEW.ps1`
- `privatevoice.src/scripts/verify-windows-qa-evidence.sh`
- `CODEGRAPH.md`
- `CHANGELOG.md`

## 固定点

- Commit: `abdb22f7391d4128a4f89d8b668781061aedf86d`
- Tag: `v2.1.38-build20260629.2014-windows-preview`
- QA update commit: `58c6b963b81e07765d29cda9410399e9644c886f`
- QA update tag: `v2.1.38-build20260629.2014-windows-preview-qa`
- QA target text commit: `ac31349b32d89b2798cd20224fcdede91d6bfe05`
- QA target text tag: `v2.1.38-build20260629.2014-windows-preview-qa-target`
- Evidence verifier commit: `fdc5c43b2cf8ebc3d67099cfba9936c838281561`
- Evidence verifier tag: `v2.1.38-build20260629.2014-windows-preview-evidence-verifier`
- Runtime preflight commit: `913b25529de9fb28fe9d212cc13492430db5a7c6`
- Runtime preflight tag: `v2.1.38-build20260629.2014-windows-preview-preflight`
- QA launcher commit: `5b5cba7030b7f4dd519868fe310bb4fce893bf91`
- QA launcher tag: `v2.1.38-build20260629.2014-windows-preview-qa-launcher`

## 交付产物

- Release 目录: `/Users/ar/Projects/PrivateVoice/Release/PrivateVoice-Dictation-2.1.38-build20260629.2014-windows-preview/`
- Zip: `PrivateVoice-Dictation-2.1.38-build20260629.2014-windows-amd64-preview.zip`
- SHA256: `ad21649749ab4cea80bcbbebf16593b5ffb9c4535902bf5655435784764970c0`
- Manifest: `RELEASE_MANIFEST.md`

## 验证结论

- `./scripts/build-windows-preview.sh`: 通过。
- `go test ./...`: 通过，存在既有 macOS linker version warnings。
- `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 ./...`: 通过。
- `unzip -t`: 通过。
- 静态检查确认 `PrivateVoice Dictation.exe` 为 `PE32+ executable (GUI) x86-64, for MS Windows`。
- zip 内容检查确认包含 `QA-WINDOWS-PREVIEW.ps1`。
- zip 内容检查确认 QA 脚本包含 `qa-target.txt`、`DICTATION_RESULT:` 和 `qa-target-dictation-text.txt` 证据采集逻辑。
- 本机没有 `pwsh` / `powershell`，因此 PowerShell 脚本只能在 Windows 真机上做运行语法验证。
- `bash -n privatevoice.src/scripts/verify-windows-qa-evidence.sh`: 通过。
- 使用模拟 `qa-evidence-pass.zip` 运行 `verify-windows-qa-evidence.sh`: 输出 `WINDOWS_QA_EVIDENCE_PASS`。
- `./scripts/build-windows-preview.sh`: 重新构建通过，包内 QA 脚本确认包含 WebView2 和音频端点采集逻辑。
- `unzip -t`: 通过。
- `./scripts/build-windows-preview.sh`: 从 `5b5cba7030b7f4dd519868fe310bb4fce893bf91` 重新构建通过。
- `go test ./...`: 通过，存在既有 macOS linker version warnings。
- `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 ./...`: 通过。
- `unzip -t`: 通过，确认最终 zip 无压缩错误。
- zip 内容检查确认包含 `RUN-WINDOWS-QA.cmd`、`QA-WINDOWS-PREVIEW.ps1` 和 `README-WINDOWS-PREVIEW.txt`。
- 静态检查确认最终包内 `PrivateVoice Dictation.exe` 为 `PE32+ executable (GUI) x86-64, for MS Windows`。
- 2026-07-01 用户在真实 PC 上完成测试并反馈“测试通过了完全正常”。
- 测试机环境截图显示：Huawei MateBook 16s、Windows 11 家庭中文版 23H2、OS build `22631.6199`、x64、13th Gen Intel Core i9-13900H、32 GB RAM。
- 本轮 Windows runtime acceptance 以用户人工验收 PASS 记录；未收到自动 `qa-evidence-*.zip`，因此未运行真实日志证据验证脚本。
- 2026-07-01 后续验证确认：微信 PC 也把 `右 Alt` 绑定为“发语音消息”，所以微信中先发出语音、随后文字出现的现象是外部快捷键冲突，不是 PrivateVoice 的识别或上屏 bug。

## 未决问题

- 未收到自动 `qa-evidence-*.zip`，所以没有真实 PC 日志、`qa-results.tsv`、`qa-target-dictation-text.txt` 的脚本化证据包。
- 当前包未签名、不是安装器，Windows Defender / SmartScreen 拦截属于预期。

## 后续建议

- Windows 用户在微信 PC 中使用时，应避免微信“发语音消息”和 PrivateVoice 触发键同为 `右 Alt`；可改微信快捷键或改 PrivateVoice 触发键。
- 后续若继续做 Windows 方向，应优先补签名/安装器、SmartScreen 体验，以及真实 QA 证据包回收流程。