跳转至

商店发布交接计划

目标

通过 Microsoft Store、Snap Store 和 Mac App Store 发布 Electron 应用程序，而不改变直接下载产品，也不复活 Tauri。

共享基础已在 feat/store-publishing-foundation 分支上完成，提交为 903d9aa9。平台工作必须从该提交开始，或者在本分支经过评审并合并后从 main 开始。

工作顺序与负责人

  1. Windows：feat/microsoft-store
  2. Linux：feat/snap-store
  3. macOS：feat/mac-app-store

Windows 使用现有的 NSIS 包建立首个商店列表。Linux 随后提供受限（confined）包。macOS 最后进行，因为其沙盒和仅捆绑可执行文件策略要求最大的打包改动。

为每个平台分支分配一名工作人员。在基础合并后，工作人员可以独立准备，但按上述顺序发布，以便在下一个商店之前纳入共享的列表、支持和发布经验。

共享契约

每位工作人员必须保留：

  • Electron 作为唯一的桌面和 UI 外壳。
  • store/metadata.json 中的 com.voicestudio.desktop、VoiceStudio 和合法发布者，除非商店强制要求使用某个已记录的标识符。
  • store/privacy.json 中的隐私披露内容。
  • config/distributions.mjs 中的能力和更新器策略。
  • 本地优先的行为，以及运行时/模型下载需由用户明确操作。
  • 现有的直接安装程序、数据路径和更新源。
  • 以根目录 package.json 作为版本来源；未经所有者批准不得提升版本。
  • 未经所有者批准，不得进行提交、列表发布或凭证更改。

如果商店要求更改身份、隐私、权限、捆绑组件或用户可见行为，应首先更新共享基础，并让所有工作人员基于该决定进行 rebase。

每位工作人员的入口检查

  1. 确认基础分支已合并，或使用提交 903d9aa9 作为公共基线。
  2. 阅读 AGENTS.md、CLAUDE.md、docs/STORE-PUBLISHING.md 和 docs/RELEASING.md。
  3. 在实现相关的社区修复之前，先检查开放的 PR 队列。
  4. 运行：
node scripts/validate_store_foundation.mjs --distribution=<target>
bun run --cwd electron typecheck
  1. 将任何验证器失败记录为阻塞任务。不要绕过该策略。
  2. 在提交前根据官方文档核实当前商店规则；要求可能会在本交接之后发生变化。

Windows 工作人员 — Microsoft Store

目标：microsoft-store

范围：

  1. 确认 Partner Center 支持现有的已签名 NSIS EXE 提交，并与所有者一起预留产品标识。
  2. 添加一个 Microsoft Store 打包/提交工作流，设置 VOICESTUDIO_DISTRIBUTION=microsoft-store，且不影响直接构建。
  3. 为这个 EXE 发行版在专用的 electron-microsoft-store-stable-* 更新源上保持 VoiceStudio 的应用内更新器启用；绝不通过直接下载的 electron-stable-* 更新源发布商店包。商店构建会选取包含其专用更新源的最新 GitHub 发布，因此较新的仅直接下载的发布不会隐藏最后发布的商店更新。
  4. 验证静默安装/卸载行为、从上一个直接发布的升级、全新安装、首次运行设置和应用程序启动。
  5. 从 store/assets.json 生成所需的图标和截图衍生文件；不要复制规范元数据之外的列表文案。
  6. 在获得所有者批准后，完成权限、生成式 AI、语音克隆、年龄分级和隐私声明。
  7. 生成工件来源清单，并记录 Authenticode 验证证据。
  8. 私下提交，在分支上解决认证发现的问题，然后请求所有者批准以进行生产发布。

退出标准：

  • Partner Center 认证通过。
  • 已签名安装程序的身份与列表发布者匹配。
  • 在支持的 Windows 架构上，全新安装和升级测试通过。
  • 直接 GitHub 安装和更新保持不变。
  • 生产列表已发布，并经过独立安装验证。

Linux 工作人员 — Snap Store

目标：snap-store

范围：

  1. 与所有者一起注册 Snap 名称，并记录所选的 confinement 级别和接口。
  2. 添加 Snap 打包，而不替换 AppImage 或 Debian 打包。
  3. 设置 VOICESTUDIO_DISTRIBUTION=snap-store；Snap Store 负责应用更新，因此应用内更新器必须保持不可用。
  4. 将可写数据、缓存、模型、运行时和项目路径映射到允许的 Snap 位置，同时保留用户选择的文件访问权限。
  5. 验证在 confinement 下的麦克风、音频播放、GPU 发现、文件导入/导出、托管运行时安装、模型安装和离线重新启动。
  6. 通过最小权限解决所需的接口，并记录任何人工审查请求。
  7. 生成工件来源清单，并记录 Snap 断言（assertion）/修订（revision）证据。
  8. 通过内部或候选渠道发布，验证刷新/回滚，然后请求所有者批准以提升到稳定版。

退出标准：

  • 严格 confinement（strict confinement）或明确批准的例外通过审查。
  • 核心的用户可见工作流与直接 Linux 行为一致。
  • 商店刷新替换应用程序，但不启用应用内更新器。
  • AppImage 和 Debian 包保持不变。
  • 稳定渠道已发布，并经过独立安装验证。

macOS 工作人员 — Mac App Store

目标：mac-app-store

范围：

  1. 在打包前解决未决的合规清单：精确的 uv 来源、锁定的 Python/wheel 再分发，以及所有捆绑可执行文件的许可证。
  2. 用经批准的捆绑运行时替换运行时可执行文件下载，或重新设计受影响的能力。不要放宽 bundled-only 策略。
  3. 添加 MAS 打包、沙盒 entitlements 和继承的 helper entitlements，而不改变 Developer ID 直接构建。
  4. 实现 security-scoped 的用户所选文件访问，并仅验证用户期望位置的持久性。
  5. 设置 VOICESTUDIO_DISTRIBUTION=mac-app-store；App Store 负责更新，因此应用内更新器必须保持不可用。
  6. 在已签名的沙盒构建中验证麦克风、辅助功能、文件导入/导出、音频/视频工具、子进程、模型使用和离线重新启动。
  7. 从规范输入生成 App Store 资源和隐私声明。
  8. 生成工件来源清单，并记录 Apple Distribution 签名、预置（provisioning）和收据（receipt）证据。
  9. 通过 TestFlight 分发，在分支上解决 App Review 发现的问题，然后请求所有者批准进行生产发布。

退出标准

  • node scripts/validate_store_foundation.mjs --distribution=mac-app-store 无异常通过。
  • MAS 沙盒构建通过所有受维护的用户可见工作流，或已一致地应用经所有者批准且有文档记录的范围缩减。
  • Developer ID 直连构建继续保持已公证（notarized）且不变。
  • App Review 通过，且生产环境商品详情已独立安装测试。

共享验证与审查门槛

在每个平台 PR 具备合并资格之前：

  1. 为新的打包行为添加 fail-before/pass-after 测试。
  2. 运行针对性测试，然后在受支持的 CI runner 上运行完整的 Electron CI 门槛检查。
  3. 生成并检查 store-artifact-manifest-<platform>-<arch>.json。
  4. 确认包中嵌入了预期的发行渠道与更新所有者。
  5. 在同一 PR 中更新商店说明和 docs/RELEASING.md。
  6. 合并当前的 main，阅读所有 CodeRabbit/Greptile 发现，并解决每一条 Critical/P1 发现。
  7. 要求 Tests (backend + frontend) 通过且 PR 处于可合并（MERGEABLE）状态。
  8. 合并后，先观察 main 的 CI 转为通过，再开始下一次发布。

所有者输入

Worker 可以在没有这些输入的情况下完成构建和验证，但在所有者提供或批准以下内容之前，无法完成发布：

  • Microsoft Partner Center、Snapcraft 和 App Store Connect 的访问权限。
  • 产品名称预留以及发布者/卖家身份。
  • 法律协议、付款和税务设置。
  • 通过仓库 secrets 提供 Windows 和 Apple 签名/预置（provisioning）凭据——绝不要通过聊天或提交文件传递。
  • 商店调查问卷、年龄分级、销售区域、定价和上架/可用性。
  • 任何版本提升、提审操作、分阶段发布和最终发布操作。

状态报告

每个 worker 应留下一份简短的平台运行手册（runbook），其中包含：

  • 分支和最终提交；
  • 包/修订标识符；
  • 用于验证的命令和 CI 运行记录；
  • 签名和来源（provenance）证据的位置；
  • 商店提审状态和审核者发现；
  • 剩余的所有者操作；
  • 回滚或下架流程。

一致地使用生命周期：

built -> validated -> submitted -> approved -> scheduled -> published -> verified

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 om/VoiceStudio