# 2026-06-14 X-ASR 首字修复

## 用户目标

- 修复 X-ASR 实验分支中短句首字偶发丢失问题，例如实际说“你看看”但识别为“看看”。
- 修复完成后必须拉两个代码审核员审核，并拉 QA 做回归测试。
- QA 过程不得临时拼 GUI/AX/cliclick/screencapture 命令，应收敛到项目内稳定脚本入口或常规测试/构建命令。

## 已完成事项

- 暂停正式打包，先排查首字问题。
- 通过本机 app 日志确认缺字发生在 `Recognized:` 阶段，排除剪贴板/上屏链路。
- 定位主要原因：hold 模式存在约 180-210ms 启动延迟，用户按下热键后立即说话时，短句首字可能落在未录音窗口。
- 在 `codex/x-asr-experiment-2.1.29` 实现 X-ASR-only 首字保护：
  - X-ASR 引擎新增 `HoldPreCaptureEngine` 能力。
  - App 在 X-ASR hold 模式按下热键时立即预采集音频。
  - 确认不是组合键后再显示浮窗并进入正式录音。
  - 组合键或短按会丢弃预采集音频，不进入识别。
  - X-ASR streaming session 首次接收音频时补 250ms 前置静音。
  - Escape 取消会停止 live caption，并阻止同一次按住手势重启录音。
  - 引擎不可用时仍允许已有录音释放/取消清理，但不会启动或确认新录音。
- 递增测试包版本至 `2.1.31`，build `20260614.2056`。
- 创建源码冻结 commit：`e86df221fa8f9d6796fb7fe59020767d7c806fac`。
- 创建 tag：`v2.1.31-build20260614.2056-xasr-hold-precapture`。
- 生成 arm64 本地测试 DMG：
  - `/Users/ar/Projects/PrivateVoice/Release/PrivateVoice-Dictation-2.1.31-build20260614.2056-xasr-hold-precapture-arm64/PrivateVoice Dictation-2.1.31-build20260614.2056-arm64-local.dmg`
  - SHA256：`ba7ced3706bfc1a4557961c21c22eee1bc92d12cbcbd16b39f0d78c4b20175d8`

## 文件变更

- `privatevoice.src/app.go`
- `privatevoice.src/internal/engine/engine.go`
- `privatevoice.src/internal/engine/engine_darwin.go`
- `privatevoice.src/app_live_caption_test.go`
- `privatevoice.src/internal/engine/engine_darwin_test.go`
- `privatevoice.src/build/darwin/Info.plist`
- `privatevoice.src/frontend/package.json`
- `privatevoice.src/frontend/package-lock.json`
- `CHANGELOG.md`
- 本地 release 证据目录：
  - `Release/PrivateVoice-Dictation-2.1.31-build20260614.2056-xasr-hold-precapture-arm64/`

## 审核与 QA

- 两位代码审核员首轮发现 P2：
  - Escape 取消未停止 live caption。
  - Escape 后同一次 hold 按住可能重启录音。
  - 引擎变 nil 时 pending 预采集释放路径可能被 guard 阻断。
- 已修复上述问题。
- 两位代码审核员二审均未发现新的 P1/P2。
- QA 结论通过：
  - `go test -count=1 ./...` 通过。
  - `go test -race -count=1 . ./internal/engine` 通过。
  - `PRIVATEVOICE_XASR_SMOKE=1 go test -v -count=1 -run TestXASRRealModelSmoke ./internal/engine` 通过。
  - `npm run build -- --outDir /tmp/privatevoice-frontend-qa-20260614-xasr` 通过。
  - `GOOS=darwin CGO_ENABLED=1 GOARCH=arm64 PRODUCTION=true go build -buildvcs=false -gcflags=all="-l" -o /tmp/privatevoice-input-qa-20260614-xasr .` 通过。
- 本地自测也通过：
  - `/opt/homebrew/bin/go test ./...`
  - `/opt/homebrew/bin/go test -race . ./internal/engine ./internal/audio ./internal/input`
  - `npm run build`
  - `PATH="/opt/homebrew/bin:$PATH" ./scripts/build-local-macos.sh arm64`
  - `codesign --verify --deep --strict --verbose=2`
  - `hdiutil verify`
  - `shasum -a 256 -c SHA256SUMS.txt`

## 未决问题与后续建议

- 未做 GUI/AX/真实热键/真实麦克风端到端自动化验证，符合本轮 QA 收敛要求。
- 用户仍需安装新 DMG 后用真实语音验证短句：
  - `你看看`
  - `你看一下`
  - `确认一下`
  - `可以了`
  - `好了呀`
  - `技术总监让我问你一下`
- Release 目录下 `.dmg` 按 `.gitignore` 不进入 git；manifest/SHA 文件已生成在本地 release 目录。