安装程序提案：单一获批方案与可恢复进度¶

仅为提案设计。 源码审阅基线（2026-10-04）： fb9a960c88744edc36daf2cf38d48df0971ee713 （应用 0.5.6）。本次仅涉及文档变更，未实现下述任何行为。 该分支已于 2026-10-05 与 main 集成；已落地的变更及当前重叠情况请参阅集成刷新。 历史探针仍固定在其原始基线上。

• 剩余发现、已合并修复及开放 PR 重叠情况
• 当前行为：运行时、模型下载、 修复、卸载

范围及需保留的现有行为¶

保留 Electron、受管 Python/uv、现有引擎、固定模型修订版本、 分段下载、完整性校验、缓存字节复用、针对性修复以及感知所有权的清理。 保留显式安装同意、选择加入的分析以及拒绝遥测时的本地运行模式。 本提案不涉及版本号提升、Tauri 复活、强制云服务、缓存迁移或替换安装程序框架。

已在 #2500 中随附仅 CPU 的 x64 打包引导程序。 Electron 安装/卸载指南及仅稳定版更新策略已在 #2578 中对齐。 包管理的安装可通过 VOICESTUDIO_DISABLE_UPDATER=1 禁用更新器 （#2557）。请保留这些变更。 请勿恢复已移除的 Preview 更新渠道，也不要重复审阅中列出的已落地及开放工作。 #2602 的磁盘余量、Rosetta 及运行时包进度变更，以及 #2605 的 源码 CPU 选择/无同步重启与启动修复均已合并。草稿 #2607 在 #2600 的 源码配方基础上构建 Windows AMD/ROCm 桌面集成。在实现运行时切片前，请先协调其选择器、解释器及测试与已落地的 源码/运行时变更之间的重叠；该草稿并不构成已发布或已合格的 Windows AMD 支持。

建议的用户流程¶

1. 选择结果与目标。 提供语音、语音克隆、转录或配音选项，并给出保守的兼容性建议。 保持执行计算机可见。仅语音的模型不得宣传为语音克隆。 将 Fast/Balanced/Quality/Max 保留为可选的资源选择，并说明各自带来的增益。 浏览操作绝不会启动安装或更改当前配置文件。
2. 审阅方案。 列出每个选定的模型、依赖、运行时、许可证、 目标位置和端点。在每个卷上分别标明可复用字节、剩余下载、 最终占用空间和临时峰值。需要时注明“估算/未知”；切勿将未知显示为零。 除非必需或被选定，否则排除无关的 ASR/听写/翻译内容。在开始前重新检查空间和目标。
3. 可视化控制安装。 在默认视图中显示准备 → 下载 → 安装 → 验证、 稳定的组件行、已完成的字节数、取消和详情。 隐藏过期的速率/预计剩余时间。当传输只能在当前传输结束后停止时，明确说明； 切勿承诺可立即暂停。渲染器重新加载会重新连接到该操作。 应用重启会在恢复网络工作前报告中断情况。
4. 就地恢复。 保留失败的组件、原因、目标、已保存字节数和下一步操作。 重试会复用兼容的已验证/部分数据。磁盘已满、访问受限、 不兼容的 wheel、损坏的工件和丢失的远程目标分别获得明确的指引。 切勿静默选择其他目标或更大的模型包。
5. 验证所选能力。 保持隐私同意独立于就绪状态。 语音/克隆目标使用简短的原创样本和经批准的兼容模型； ASR 使用小型随附语音固定样本；配音使用受限的本地固定样本。 检查过程不会下载额外资源、要求麦克风或覆盖草稿。 生成的音频通过 mark_synthetic 处理，播放以暂停状态开始。 提供“重试”或“不测试直接进入工作室”的选项；跳过并不等于已验证。

分别持久化以下独立事实：引导完成状态、资源完整性、 所选能力就绪状态以及首次输出验证状态。缓存目录为正大小或向导已完成 并不能证明模型可用。已安装的引擎可以保持可用，而某个无关的可选组件需要修复。

建议的合约与所有权¶

这是与现有执行器共用的通用词汇，并不是必须在 Python 存在之前就绪的 Python 服务。 Electron 拥有其引导程序；所选后端拥有其模型/辅助任务。 保留当前端点作为兼容适配器。

按目标使用原子状态转换和所有权检查锁。取消只有在工作器/进程树停止写入后才变为终止状态。消失的工作器被视为中断，绝不算成功。保留终结性失败详细信息，直到解决/关闭，而不是将其与重试冷却绑定。轮询返回完整快照；事件重放必须协调或显式重置快照。恢复时重新检查工件标识、修订、范围和完整性。保留回环、CSRF 和远程授权；仅凭 ID 不能授予访问权限。

在确认之前解析模型元数据。在 Python 可用之前，运行时计划加上带标签的模型估算是诚实的；而凭空捏造的合并精确总数则不是。按文件系统对唯一工件、提取/复制、旧运行时保留和余量进行分组，包括并发作业。在替代策略经过测量之前，保留现有的 10 GiB 模型预留空间。未知容量与零容量是不同的。

运行时配方应在网络工作之前验证操作系统/架构/加速器组合，并避免在替换为 CPU/ROCm 之前下载 CUDA。历史配方边界及 #2605/#2607 的重叠已在评审中标识；请对照集成刷新重新验证它们，并复用已落地的 CPU 路径。对于 Rosetta/Windows 模拟，保持主机、进程和 Python 架构相互分离。

平台边界¶

这些是源码层面的分发/运行时事实，而非新硬件验收。

保持支持层级与证据分离：supported/experimental/remote-only 与 not-run/fixture-only/native-verified 是不同的。记录确切的构建、配方和已测试主机。浏览器/Docker 客户端不得意外安装到正在观看的计算机上。

生命周期与安全¶

• 对于配方不变的 shell 更新，复用运行时和权重。保持仅稳定版、架构特定的 Electron 源以及不可变的旧版源
• 分阶段替换是一个提案：在其最终的版本化目录中创建 venv，验证它，然后切换一个经过所有权检查的指针。不要在验证之前移动已构建的 venv 或擦除健康的运行时
• 二进制回滚无法逆转任意的数据库更改。在提供回滚之前验证备份和 schema 兼容性；失败/跳过的备份不构成保护
• 在移除预览中区分应用、运行时、共享缓存和个人数据。保留所有权保护和现有确认。失败的删除必须保留其恢复状态，且不得报告为成功
• 保持诊断导出为本地且可预览；对令牌、路径、用户内容和 URL 机密进行脱敏。共享和可选的代理升级保留明确同意
• 使用现有组件和 SearchableSelect；将所有面向用户的文本翻译到全部 21 个区域设置。在 200% 缩放 / 640×480 视口下测试键盘/焦点、屏幕阅读器、减少动态效果、长翻译文本以及可触达的恢复操作

小型实现切片与验收¶

1. 正确性优先： 统一完整性与就绪性；区分零/未知磁盘容量；报告实际的 sidecar 删除；在简单视图中保留失败的模型行和“取消”。这些修复不需要新的协调器
2. 计划/进度： 在确认之前解析所选组件，保留完整分母和终结性结果，并在重载之间协调单个操作
3. 持久恢复： 增量添加目标所有的日志/回执、安全中断和分阶段运行时切换，同时保持公共兼容性
4. 基于目标的 UI： 在底层事实/恢复契约可靠之后，添加预设和基于特定能力的首次输出

必需的回归测试：仅有配置/缺少分片的缓存；零/未知/满磁盘；锁定文件移除；两个同时运行的作业，其中一个完成或失败；60 秒后的终结性错误和进程重启；双重启动/取消；目标变更；网络中断和损坏的工件；跨重启的“不，谢谢”状态；首次输出的跳过/失败；配方不变的更新和仅限自有文件的卸载。

契约测试在模型缓存为空的情况下离线运行。另外，在 macOS、Windows 和 Linux 上分别记录打包的全新安装、首次输出、重新启动/更新/卸载，以及具有代表性的 CPU/CUDA/MPS/ROCm 和实验性 ARM 硬件。夹具、源码探测和 WSL 不能替代原生验收。在引用改进之前，先测量时间和缓存状态。未提议新的 RC 或发布仪式。