| 02-P-NBL/freeze/20260605-mac-app-store-quarantine-hotfix.md | ●●●●● patch | view | raw | blame | history | |
| 02-P-NBL/freeze/20260605-mac-app-store-upload-preflight.md | ●●●●● patch | view | raw | blame | history | |
| Docs/KM2.项目管理-非业务直接相关/QA工作-经验与教训.md | ●●●●● patch | view | raw | blame | history | |
| Release/PrivateVoice-Dictation-2.1.28-build20260605.0236/APP_STORE_CONNECT_SUBMISSION.md | ●●●●● patch | view | raw | blame | history | |
| Release/PrivateVoice-Dictation-2.1.28-build20260605.0236/RELEASE_MANIFEST.md | ●●●●● patch | view | raw | blame | history | |
| Release/PrivateVoice-Dictation-2.1.28-build20260605.0236/SHA256SUMS.txt | ●●●●● patch | view | raw | blame | history |
02-P-NBL/freeze/20260605-mac-app-store-quarantine-hotfix.md
New file @@ -0,0 +1,39 @@ # 2026-06-05 Mac App Store quarantine xattr 修复 ## 结论 - 版本: `2.1.28` - 新 build: `20260605.0236` - 源码 commit: `8cd205ee7e12a2b46d6beff6e5a6434c4862af24` - 修复原因: Transporter/TestFlight validation failed 91109。 - 修复内容: 在 App Store 打包脚本中对 `.app` 递归执行 `xattr -cr`，并在 packaging 前断言不存在 `com.apple.quarantine`。 ## 产物 - `/Users/ar/Desktop/PrivateVoice-26.0604上架/02-上传包/PrivateVoice-Dictation-2.1.28-build20260605.0236-universal-macappstore.pkg` - `/Users/ar/Projects/PrivateVoice/X-运营资料/PrivateVoice-26.0604上架/02-上传包/PrivateVoice-Dictation-2.1.28-build20260605.0236-universal-macappstore.pkg` - `/Users/ar/Projects/PrivateVoice/Release/PrivateVoice-Dictation-2.1.28-build20260605.0236/PrivateVoice-Dictation-2.1.28-build20260605.0236-universal-macappstore.pkg` SHA256: ```text a0d01edf950ea69892b14c0f9cd989fc31d6927be4b26d31a4168526fdddd190 PrivateVoice-Dictation-2.1.28-build20260605.0236-universal-macappstore.pkg ``` ## 验证 - `go test ./internal/startup ./internal/model ./internal/modelselection`: PASS - `bash -n privatevoice.src/scripts/build-macappstore-pkg-macos.sh`: PASS - arm64 App Store signed package build: PASS - x86_64 App Store signed package build: PASS - universal app merge and re-sign: PASS - `codesign -vvv --deep --strict` universal app: PASS - `pkgutil --check-signature` universal pkg: PASS - 展开 pkg 后读取 `Info.plist`，`LSApplicationCategoryType=public.app-category.productivity`: PASS - 展开 pkg 后读取签名 entitlements，`com.apple.application-identifier=CR3J54M8BQ.com.shanghai3168.privatevoicedictation`: PASS - 展开 pkg 后检查 `com.apple.quarantine`: PASS，无输出 - 三处 `.pkg` SHA256 一致: PASS ## 上传提示 请在 Transporter 中上传 `20260605.0236` 这个新包，不要再上传 `20260605.0216`。 02-P-NBL/freeze/20260605-mac-app-store-upload-preflight.md
New file @@ -0,0 +1,97 @@ # 2026-06-05 Mac App Store 上传教训与预检清单 ## 这次的问题 今天上传成功前反复踩了三个坑： 1. `CFBundleIdentifier` 与 Apple Developer profile 的 Bundle ID 不一致。 2. `Info.plist` 缺少 Mac App Store 必填的 `LSApplicationCategoryType`。 3. `.app` 嵌入的 provisioning profile 有 `com.apple.application-identifier`，但签名 entitlements 没有同一个值，触发 Transporter/TestFlight `90886`。 4. 下载得到的 provisioning profile 带 `com.apple.quarantine` 扩展属性，复制进 `.app` 后被打进 `.pkg`，触发 Transporter/TestFlight `91109`。 这些都不是业务功能问题，而是 Mac App Store 上传包的元数据和签名验收不完整。 ## 必须记住的规则 - Transporter 不是完整的本地 QA 工具；不能把用户上传失败当成检查方式。 - `pkgutil --check-signature` 只能证明 `.pkg` 被 Installer 证书签了，不能证明 App Store 会接受。 - `codesign -vvv --deep --strict` 只能证明签名结构有效，不能证明 entitlements 与 embedded profile 一致。 - 每次重传必须换新的 `CFBundleVersion` build 号。 - 同一个 App Store 版本可以保持 `CFBundleShortVersionString=2.1.28`，但每个新上传包必须有新的 build。 - 最终给用户上传的只能是 `*-universal-macappstore.pkg`，不能是 sandbox POC DMG，也不能是旧 build。 ## 上传前硬性预检 在把 `.pkg` 交给用户上传前，必须对最终 `.pkg` 展开检查，而不是只检查 build 目录里的 `.app`。 必须检查： - `CFBundleIdentifier=com.shanghai3168.privatevoicedictation` - `CFBundleShortVersionString` 与本次发布版本一致 - `CFBundleVersion` 是本次新 build - `LSApplicationCategoryType=public.app-category.productivity` - embedded provisioning profile 的 App ID 是 `CR3J54M8BQ.com.shanghai3168.privatevoicedictation` - signed entitlements 的 `com.apple.application-identifier` 是 `CR3J54M8BQ.com.shanghai3168.privatevoicedictation` - signed entitlements 的 `com.apple.developer.team-identifier` 是 `CR3J54M8BQ` - signed entitlements 包含 `com.apple.security.app-sandbox=true` - app 主程序是 universal `arm64 + x86_64` - `libsherpa-onnx-c-api.dylib` 是 universal `arm64 + x86_64` - `libonnxruntime.1.24.4.dylib` 是 universal `arm64 + x86_64` - `codesign -vvv --deep --strict` 对最终 app PASS - `pkgutil --check-signature` 对最终 pkg PASS - 最终 `.pkg` 展开后的 `.app` 内没有 `com.apple.quarantine` 扩展属性 - release、桌面上传目录、运营资料目录里的 pkg SHA256 完全一致 ## 参考检查命令 ```bash PKG="/path/to/PrivateVoice-Dictation-2.1.28-buildYYYYMMDD.HHMM-universal-macappstore.pkg" TMP="/tmp/privatevoice-pkg-check" rm -rf "$TMP" pkgutil --expand-full "$PKG" "$TMP" APP="$(find "$TMP" -name 'PrivateVoice Dictation.app' -type d -print -quit)" /usr/libexec/PlistBuddy -c 'Print :CFBundleIdentifier' "$APP/Contents/Info.plist" /usr/libexec/PlistBuddy -c 'Print :CFBundleShortVersionString' "$APP/Contents/Info.plist" /usr/libexec/PlistBuddy -c 'Print :CFBundleVersion' "$APP/Contents/Info.plist" /usr/libexec/PlistBuddy -c 'Print :LSApplicationCategoryType' "$APP/Contents/Info.plist" PROFILE_PLIST="$TMP/profile.plist" security cms -D -i "$APP/Contents/embedded.provisionprofile" > "$PROFILE_PLIST" /usr/libexec/PlistBuddy -c 'Print :Entitlements:com.apple.application-identifier' "$PROFILE_PLIST" /usr/libexec/PlistBuddy -c 'Print :Entitlements:com.apple.developer.team-identifier' "$PROFILE_PLIST" SIGNED_ENTITLEMENTS="$TMP/signed-entitlements.plist" codesign -d --entitlements :- "$APP" > "$SIGNED_ENTITLEMENTS" 2>/dev/null /usr/libexec/PlistBuddy -c 'Print :com.apple.application-identifier' "$SIGNED_ENTITLEMENTS" /usr/libexec/PlistBuddy -c 'Print :com.apple.developer.team-identifier' "$SIGNED_ENTITLEMENTS" /usr/libexec/PlistBuddy -c 'Print :com.apple.security.app-sandbox' "$SIGNED_ENTITLEMENTS" file "$APP/Contents/MacOS/PrivateVoice Dictation" file "$APP/Contents/Frameworks/libsherpa-onnx-c-api.dylib" file "$APP/Contents/Frameworks/libonnxruntime.1.24.4.dylib" codesign -vvv --deep --strict "$APP" pkgutil --check-signature "$PKG" xattr -lr "$APP" | grep -F 'com.apple.quarantine' && exit 1 || true shasum -a 256 "$PKG" ``` ## 今天形成的修复 - 正式 Bundle ID 固定为 `com.shanghai3168.privatevoicedictation`。 - Mac App Store 分类固定为 `public.app-category.productivity`。 - 打包脚本必须从 provisioning profile 合并以下 entitlements 后再签名： - `com.apple.application-identifier` - `com.apple.developer.team-identifier` - `keychain-access-groups` - 当前可上传包是 `20260605.0216`，不要再上传 `20260604.0049` 或 `20260604.2353`。 - 如果遇到 `91109`，必须在组装 app 后、签名后、productbuild 前对 `.app` 执行 `xattr -cr`，并展开最终 `.pkg` 检查没有 `com.apple.quarantine`。 ## 上传后还要检查 - App Store Connect 里选择最新 build。 - 付费应用必须确认 Paid Apps Agreement、税务和银行信息已生效。 - 价格不在 Transporter 设置；在 App Store Connect 的 `Monetization / Pricing and Availability` 设置。 - 提交审核前确认截图、隐私政策、支持 URL、审核备注、隐私问卷和价格都已填完。 Docs/KM2.项目管理-非业务直接相关/QA工作-经验与教训.md
New file @@ -0,0 +1,7 @@ ## 2026-06-05｜Mac App Store 上传前必须做包内验收 - 触发：用户指出 App Store 上传反复失败，先后缺少分类键、签名 application identifier 等项，导致多次重新上传。 - 失误：AI 只做了本地构建、签名和 pkg 签名校验，没有把最终 `.pkg` 展开后按 App Store/TestFlight 规则逐项核对 `Info.plist`、embedded profile 和 signed entitlements。 - 原因：发布前 QA 门禁没有覆盖 Apple Transporter 的关键校验项，也没有形成固定预检清单。 - 改进：以后 Mac App Store 上传包交付前，必须展开最终 `.pkg`，检查 Bundle ID、版本/build、`LSApplicationCategoryType`、profile App ID、signed `com.apple.application-identifier`、Team ID、sandbox entitlements、universal 架构、pkg 签名和包内无 `com.apple.quarantine` 扩展属性全部通过后，才交给用户上传。 - 关联：`privatevoice.src/scripts/build-macappstore-pkg-macos.sh`、`02-P-NBL/freeze/20260605-mac-app-store-upload-preflight.md`。 Release/PrivateVoice-Dictation-2.1.28-build20260605.0236/APP_STORE_CONNECT_SUBMISSION.md
New file @@ -0,0 +1,37 @@ # App Store Connect Submission Prep ## Build - App: 私语输入法 / PrivateVoice Dictation - Bundle ID: `com.shanghai3168.privatevoicedictation` - Version: `2.1.28` - Build: `20260605.0236` - Platform: macOS - Primary category: Productivity - `LSApplicationCategoryType`: `public.app-category.productivity` - Signed application identifier: `CR3J54M8BQ.com.shanghai3168.privatevoicedictation` - Team ID: `CR3J54M8BQ` - Minimum macOS for App Store sandbox build: `13.4` - Support URL: `https://shanghai3168.github.io/privatevoice-dictation-support/support.html` - Privacy Policy URL: `https://shanghai3168.github.io/privatevoice-dictation-support/privacy.html` ## Current Upload Package ```text /Users/ar/Desktop/PrivateVoice-26.0604上架/02-上传包/PrivateVoice-Dictation-2.1.28-build20260605.0236-universal-macappstore.pkg ``` This replaces the failed `20260605.0216` package. The new package removes `com.apple.quarantine` extended attributes from the app bundle before packaging. ## Validation Evidence - Universal `arm64` + `x86_64` app executable and bundled dylibs: PASS. - App code signature: PASS. - Installer package signature: PASS. - Expanded package signed app entitlements include `com.apple.application-identifier=CR3J54M8BQ.com.shanghai3168.privatevoicedictation`: PASS. - Expanded package contains no `com.apple.quarantine` extended attribute: PASS. - SHA256: `a0d01edf950ea69892b14c0f9cd989fc31d6927be4b26d31a4168526fdddd190`. ## Upload Open Transporter, remove the failed previous package, drag in the package above, and click `Deliver`. Release/PrivateVoice-Dictation-2.1.28-build20260605.0236/RELEASE_MANIFEST.md
New file @@ -0,0 +1,77 @@ # Release Manifest: PrivateVoice Dictation 2.1.28 build 20260605.0236 ## Package Type - Type: Mac App Store signed universal upload package - Platform: macOS universal, `arm64` + `x86_64` - Signing: Apple App Store distribution signing with embedded Mac App Store provisioning profile - Generated at: 2026-06-04T18:42:19Z - Operator: Codex ## Source - Repository: `/Users/ar/Projects/PrivateVoice` - Branch: `codex/privatevoice-freeze-2.1.25` - Build source commit: `8cd205ee7e12a2b46d6beff6e5a6434c4862af24` - Version: `2.1.28` - Build: `20260605.0236` - Bundle ID: `com.shanghai3168.privatevoicedictation` - App Store category UTI: `public.app-category.productivity` ## Scope - Fixed Transporter/TestFlight validation failure 91109. - The downloaded provisioning profile carried `com.apple.quarantine`, which was copied into the app bundle and then into the package. - Updated `privatevoice.src/scripts/build-macappstore-pkg-macos.sh` to recursively clear extended attributes from the app bundle before and after signing. - Added build-time assertion that no `com.apple.quarantine` attributes remain before packaging. - Rebuilt the Mac App Store upload package with a new build number. ## Build Commands ```bash git diff --check -- privatevoice.src/scripts/build-macappstore-pkg-macos.sh privatevoice.src/app.go privatevoice.src/build/darwin/Info.plist bash -n privatevoice.src/scripts/build-macappstore-pkg-macos.sh go test ./internal/startup ./internal/model ./internal/modelselection ./privatevoice.src/scripts/build-macappstore-pkg-macos.sh arm64 ./privatevoice.src/scripts/build-macappstore-pkg-macos.sh x86_64 ``` The final universal app was assembled from the signed arm64 and x86_64 app bundles with `lipo`, then re-signed with the merged App Store entitlements, stripped of extended attributes, and packaged with `productbuild`. ## Verification - `go test ./internal/startup ./internal/model ./internal/modelselection`: PASS. - `bash -n privatevoice.src/scripts/build-macappstore-pkg-macos.sh`: PASS. - `npm run build`: PASS, with existing Svelte a11y warnings in `UpdateDialog.svelte` and `ToggleSwitch.svelte`. - arm64 Mac App Store package build and signature verification: PASS. - x86_64 Mac App Store package build and signature verification: PASS. - Universal app executable contains `arm64` and `x86_64`: PASS. - Bundled `libsherpa-onnx-c-api.dylib` contains `arm64` and `x86_64`: PASS. - Bundled `libonnxruntime.1.24.4.dylib` contains `arm64` and `x86_64`: PASS. - Universal app `codesign -vvv --deep --strict`: PASS. - Universal package `pkgutil --check-signature`: PASS. - Expanded package app `Info.plist` contains `CFBundleVersion=20260605.0236`: PASS. - Expanded package app `Info.plist` contains `LSApplicationCategoryType=public.app-category.productivity`: PASS. - Expanded package app signed entitlements contain `com.apple.application-identifier=CR3J54M8BQ.com.shanghai3168.privatevoicedictation`: PASS. - Expanded package app signed entitlements contain `com.apple.developer.team-identifier=CR3J54M8BQ`: PASS. - Expanded package app signed entitlements contain `com.apple.security.app-sandbox=true`: PASS. - Expanded package app contains no `com.apple.quarantine` extended attribute: PASS. - Release, desktop, and operations package SHA256 match: PASS. ## Artifact ```text Release/PrivateVoice-Dictation-2.1.28-build20260605.0236/PrivateVoice-Dictation-2.1.28-build20260605.0236-universal-macappstore.pkg /Users/ar/Desktop/PrivateVoice-26.0604上架/02-上传包/PrivateVoice-Dictation-2.1.28-build20260605.0236-universal-macappstore.pkg /Users/ar/Projects/PrivateVoice/X-运营资料/PrivateVoice-26.0604上架/02-上传包/PrivateVoice-Dictation-2.1.28-build20260605.0236-universal-macappstore.pkg ``` SHA256: ```text a0d01edf950ea69892b14c0f9cd989fc31d6927be4b26d31a4168526fdddd190 PrivateVoice-Dictation-2.1.28-build20260605.0236-universal-macappstore.pkg ``` ## Upload Note Use the `20260605.0236` package for Transporter. Do not upload the previous `20260605.0216` package, because it contains `com.apple.quarantine` extended attributes inside the app payload. Release/PrivateVoice-Dictation-2.1.28-build20260605.0236/SHA256SUMS.txt
New file @@ -0,0 +1 @@ a0d01edf950ea69892b14c0f9cd989fc31d6927be4b26d31a4168526fdddd190 PrivateVoice-Dictation-2.1.28-build20260605.0236-universal-macappstore.pkg
