v0.2.0 to v0.2.1

43 added, 25 removed. Audit A to A.

---

- name: sgc-electron-delta-updater

+ name: lov-electron-delta-updater

description: >

为 Electron 桌面应用设计、实现和验证增量自动更新，覆盖 macOS Sparkle、签名、appcast、发布产物与失败拦截。用户提到增量更新、Sparkle、检查更新、appcast、DMG 更新或 delta updater 时使用。

license: MIT

metadata:

- author: lovstudio

- version: "0.2.0"

+ author: contributors

+ version: "0.2.1"

tags:

- electron

- auto-update

- sparkle

- delta

compatibility: "Electron projects; macOS delta mode requires Sparkle-compatible packaging and signing."

dependencies: []

---

# 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)

- **You MUST follow these steps in order.**

+ **Follow these steps in order.**

### Step 0: Establish the update contract

- - Identify target platforms, package format, current updater library, update feed, signing owner, release channel, and rollback expectation.

- - Treat macOS delta-only behavior as an explicit product promise only when complete archives are intentionally excluded.

- - Separate four states: check, download/stage, install handoff, and post-restart verification.

- - Read [references/electron-macos-delta.md](references/electron-macos-delta.md) for macOS Sparkle work and [references/release-verification.md](references/release-verification.md) before modifying a release pipeline.

+ - 确认目标平台、包格式、当前更新器、更新源、签名责任方、发布渠道和回滚预期。

+ - 只有在明确排除完整包时，才把 macOS delta-only 作为发布承诺。

+ - 将检查、下载/暂存、安装交接、重启后验证拆成四个状态。

+ - 处理 macOS Sparkle 时读取 `references/electron-macos-delta.md`；修改发布流水线前读取 `references/release-verification.md`。

### Step 1: Make checks bounded and recoverable

- - Use one in-flight check per update service.

- - Pass an `AbortSignal` through every network layer, including appcast fetches.

- - On timeout, abort the request, wait for stale updater state and connections to settle, then allow a later retry.

- - Configure the updater's own network session; do not assume it inherits a developer shell proxy.

- - Keep the UI state retryable after every timeout, download failure, or malformed feed.

+ - 每个更新服务只保留一个进行中的检查。

+ - 将 `AbortSignal` 传入包含 appcast 请求在内的每一层网络调用。

+ - 超时后终止请求，等待旧更新状态和连接收敛，再允许后续重试。

+ - 配置更新器自己的网络会话，避免把开发者终端代理当作运行时配置。

+ - 每次超时、下载失败或 feed 格式错误后，界面都保留可重试状态。

### Step 2: Enforce the artifact policy

- - Generate architecture-specific feed entries and match each delta to its source and target version.

- - Verify signature, length, architecture, and URL before staging an update.

- - In delta-only mode, stop on any complete-package fallback; surface a manual-install path instead of silently downloading a larger archive.

- - If a local feed proxy is required, bind it to loopback, permit only the verified delta URL, preserve HTTP range behavior, and keep the served artifact URL ending in `.delta`.

+ - 生成按架构区分的 feed 条目，并让每个 delta 对应明确的源版本和目标版本。

+ - 暂存前核对签名、长度、架构和 URL。

+ - delta-only 模式遇到完整包回退时停止当前链路，展示手动安装路径，避免静默下载更大的归档。

+ - 需要本地 feed 代理时，仅绑定 loopback，限制为已核验的 delta URL，保留 HTTP Range 行为，并确保资源 URL 以 `.delta` 结尾。

### Step 3: Coordinate install and restart

- - Complete application cleanup before giving control to the native updater.

- - Keep the process alive until asynchronous install handoff is confirmed.

- - Use [references/release-verification.md](references/release-verification.md) to verify the staged update and the installed version after relaunch.

- - For a normal user-invoked app restart without an update, use `sgc-electron-app-relaunch` instead.

+ - 将应用清理完成后再交给原生更新器。

+ - 在确认异步安装交接前保持进程存活。

+ - 使用 `references/release-verification.md` 验证暂存更新和重启后的已安装版本。

+ - 普通的用户主动重启使用 `lov-electron-app-relaunch`。

### Step 4: Validate the deliverable

- - Add tests for single-flight checks, timeout abort, stale-check recovery, rejected full fallback, feed proxy ranges, and asynchronous install handoff.

- - Run the project's format, lint, typecheck, test, package, signing, and notarization checks that apply.

- - Verify the public release page plus direct appcast and delta asset responses; compare the final artifact's version, digest, size, signature, and notarization state.

- - Report the updater backend, supported platforms, checked URLs, installed-version proof, and any manual-install condition.

+ - 为单飞检查、超时终止、旧检查恢复、完整包回退拦截、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` 修改会使此前的“确认”“继续”“发吧”失效；完成当前产物修改和回读后必须停下，等待用户下一步指示，不自动进入发布、提交或其他外部写入。