# Windows 桌面包、安装与升级

当前源码0.12需要moonc≥0.10.16和Node≥22.16；本轮运行包仅可本地验证，不公开发布。新增`bundle-copy-verified`白名单并排复制、带外清单摘要及`bundle-transition-preview`格式交集/回退状态门禁，见[0.12指南](RELIABILITY_0_12.md)。已有C#安装器仍为显式当前用户安装，未获得可信代码签名；下面0.3段落描述历史功能。

0.3.0 提供内置 Node 的 Windows x64 包，与需要外部 Node 的普通便携包区分。桌面包双击 `MoonRestore.exe` 或 `打开工作台.cmd`，在托盘提供重新打开工作台、安全停止。只监听回环，浏览器链接含临时会话授权；不把链接写到磁盘或安装参数。

构建环境需要 Node ≥22、moonc ≥0.10.15、Windows .NET Framework C# 编译器。执行 `npm run package:desktop`。打包脚本从 Node 官方精确版本下载 Windows 运行时，核对官方 SHA-256，保留完整上游 LICENSE 和来源摘要。不会要求用户关闭执行策略、SmartScreen 或杀毒软件；自研 EXE 尚未代码签名，不把清单哈希称为发布者签名。Node 发布者 GPG 签名未独立验证。

## 首次配置

1. 启动后填写任务，或用“路径选择”选源目录及已有仓库。新仓库父目录选择器仅建议 `MoonRestoreVault` 路径；真正初始化仍需确认且要求目标不存在。
2. 加密仓库在“加密与换机恢复准备”中创建，再单独导出私有恢复密钥并用该密钥演练。
3. 保存任务、预检容量、立即备份；查看分别记录的备份/校验/演练/副本时间。
4. 仅明确勾选“工作台运行时执行到期任务”才会在托盘/CLI 工作台运行时自动执行。未勾选的任务不会因打开工作台而启动；没有注册系统服务或系统计划。
5. 关闭浏览器不停止托盘进程。通过托盘“Stop safely and exit”请求取消并退出。强制杀进程可能留下锁/暂存，需要按恢复说明处理。

“安装到当前用户”显式确认后，将已校验白名单复制到 `%LOCALAPPDATA%/MoonRestore/版本号/`，创建桌面快捷方式；不需要管理员、不覆盖同版本或已有同名快捷方式。复制时忽略包中任何 `.local`、报告、备份或未列入清单的文件。安装不创建备份、计划任务或磁盘快照。

原生托盘默认私有状态目录为 `%LOCALAPPDATA%/MoonRestoreState/`；源代码/普通 CLI 默认是工程或运行包的 `.local/state/`，不是同一个位置。要让 CLI 操作桌面任务，先在 PowerShell 设置 `$env:MOONRESTORE_HOME = Join-Path $env:LOCALAPPDATA 'MoonRestoreState'`，或显式使用前置 `--home`。迁移配置由用户选择同一私有目录，不擅自搬运密钥或覆盖其他安装配置。

## 升级和回退

- 版本分目录安装，不原地覆盖运行文件；切换之前先停止原有实例和系统计划。快捷方式已存在时安装器拒绝覆盖，由用户确认并自行调整到新版本。
- 0.3 可读原有格式 1/3；时间/权限元数据是受同一清单哈希保护的可选扩展，不改旧快照。真实 0.2.0 运行包与 0.3 做过双向内容校验和恢复；0.2 会忽略新的属性扩展，不能据此宣称它能恢复属性。
- 0.3 任务加入新字段，旧程序不认识；首次改写纯 0.2 配置时，在私有目录保存 `jobs-v02-before-upgrade.json`。回退前停止所有新旧进程，由用户保留当前配置副本并恢复旧配置，不能直接让旧程序读取新字段。新建的 0.3 任务没有伪造的 0.2 配置备份。
- 卸载应用只处理已核对的版本目录和指向它的快捷方式。私有状态、恢复密钥及资料仓库不自动删除；不要递归删除整个 LOCALAPPDATA 或备份盘。

## 验证范围

非交互 `--check` 校验发行包，`--install-check` 只预检不安装，`--host-check` 使用内置运行时启动/授权访问/停止实际后端。`scripts/desktop-qa.mjs` 在受控私有目录、屏蔽全局 Node 的环境执行这些检查，不向用户桌面安装。托盘菜单、默认浏览器唤起及安装确认窗口的人工交互验收仍需用户实际检查；不把非交互测试写成已点击所有原生窗口。

不提供无人登录的 Windows 服务；默认提醒仅在本机，Windows 通知投递受系统设置影响。真实独立设备、NAS、断电及长期生产验证仍未完成。