Electron 增量更新 · Electron Delta Updates

为现有 Electron 应用交付可验证的增量更新链路；以用户实际安装包、公开更新源和安装结果为准，而不是以 CI 成功为准。

Triggers

Activate when

• 用户说“给这个 Electron App 加增量自动更新”或“检查更新一直转圈”。
• 用户提到 macOS Sparkle、appcast、DMG、blockmap、签名、公证或 delta 更新包。
• User asks to “add a delta updater”, “ship Sparkle updates”, or “verify an Electron update release”.

Do not activate when

• 用户只想修改版本号、更新日志或普通下载页；使用版本管理或发布工作流。
• 用户要做网页热更新、PWA 缓存更新或移动端 OTA；使用相应平台的更新机制。

Workflow (MANDATORY)

Follow these steps in order.

Step 0: Establish the update contract

• 确认目标平台、包格式、当前更新器、更新源、签名责任方、发布渠道和回滚预期。
• 只有在明确排除完整包时，才把 macOS delta-only 作为发布承诺。
• 将检查、下载/暂存、安装交接、重启后验证拆成四个状态。
• 处理 macOS Sparkle 时读取 references/electron-macos-delta.md；修改发布流水线前读取 references/release-verification.md。

Step 1: Make checks bounded and recoverable

• 每个更新服务只保留一个进行中的检查。
• 将 AbortSignal 传入包含 appcast 请求在内的每一层网络调用。
• 超时后终止请求，等待旧更新状态和连接收敛，再允许后续重试。
• 配置更新器自己的网络会话，避免把开发者终端代理当作运行时配置。
• 每次超时、下载失败或 feed 格式错误后，界面都保留可重试状态。

Step 2: Enforce the artifact policy

• 生成按架构区分的 feed 条目，并让每个 delta 对应明确的源版本和目标版本。
• 暂存前核对签名、长度、架构和 URL。
• delta-only 模式遇到完整包回退时停止当前链路，展示手动安装路径，避免静默下载更大的归档。
• 需要本地 feed 代理时，仅绑定 loopback，限制为已核验的 delta URL，保留 HTTP Range 行为，并确保资源 URL 以 .delta 结尾。

Step 3: Coordinate install and restart

• 将应用清理完成后再交给原生更新器。
• 在确认异步安装交接前保持进程存活。
• 使用 references/release-verification.md 验证暂存更新和重启后的已安装版本。
• 普通的用户主动重启使用 lov-electron-app-relaunch。

Step 4: Validate the deliverable

• 为单飞检查、超时终止、旧检查恢复、完整包回退拦截、feed 代理 Range 和异步安装交接补充测试。
• 执行项目适用的格式化、lint、类型检查、测试、打包、签名和公证门禁。
• 验证公开发布页以及 appcast、delta 资源的直接响应；对照最终产物的版本、摘要、大小、签名和公证状态。
• 报告更新后端、支持平台、核对过的 URL、已安装版本证据和任何手动安装条件。

Runtime context

运行前读取同目录 skill.yaml，由宿主的 skill-runtime 按“当前请求、项目上下文、个人配置、品牌 Profile、安全默认值”的顺序注入，只使用 manifest 声明的字段。

• 缺少 required: true 字段时，按 questions 向用户提出一个聚焦问题；回答只用于本次运行，除非用户明确要求保存。
• Profile 只用于公开品牌事实；个人配置只用于决策，不自动写入产物或源码。
• 调试报错提供可复制的 context_id、字段路径和来源，不输出秘密、完整私人路径或原始内容。

Dependencies

• An Electron project with a defined packaging and signing owner.
• Sparkle tooling only for macOS Sparkle paths.

---

Runtime context (shared)

运行前读取本 Skill 包的 skill.yaml，由宿主提供 skill-runtime/v1 上下文。字段解析顺序为：当前请求、项目上下文、个人 Preferences、品牌 Profile、通用默认值。

• 只使用 Manifest 声明的字段；Profile 保存公开品牌事实，Preferences 保存个人工作偏好。
• required: true 字段缺失时，按 Manifest 的问题配置向用户提出一个聚焦问题；用户明确同意后再保存回答。
• 报错提供可复制的 context_id、字段路径与来源，诊断内容避开秘密、完整私人路径和原始配置。

通用反馈闭环

用户在 Skill 驱动任务中提出修改意见时，继续当前产物前必须执行：

1. 先判断意见是 task-specific（仅本次）还是 reusable（可跨任务复用）。
2. task-specific 只修改当前任务，不改 Skill。
3. reusable 先确定作用域：领域规则先更新对应 canonical Skill；适用于所有 Skill 的规则先更新共享规范。
4. 完成规则更新、版本、lint 与分发核验后，再把修改应用到当前任务。
5. reusable 修改会使此前的“确认”“继续”“发吧”失效；完成当前产物修改和回读后必须停下，等待用户下一步指示，不自动进入发布、提交或其他外部写入。