package-patch-release

name	package-patch-release
description	为 DeepWrite 桌面端递增一个 SemVer 补丁版本，安全清理上一个版本的测试打包残留，使用项目规定的 pnpm pack:test 命令构建并验证新安装包，按用户要求决定是否创建并发布 GitHub Release；Release 完整可下载后更新根目录 update.json，并通过路径限定提交和推送，保证该提交只包含 update.json。用于用户提出“打包新版本”“提高一小个版本并打包”“清理旧包后发 Release”“更新 update.json 并只提交该文件”等版本交付请求。

打包补丁版本并按需发布

从仓库根目录执行 DeepWrite 测试版交付。把“提高一小个版本”解释为 SemVer 补丁位加一，例如 1.2.0 -> 1.2.1。不得把测试包描述为正式签名、公证后的发布包。

不可破坏的边界

• 先读 .codex/skills/windows-macos-test-package/SKILL.md 和 docs/GitHub-Release测试版自动更新发布说明.md；测试安装包规则与本技能冲突时，以测试安装包技能为准。
• 当前工作树可以很脏。把已有修改全部视为用户资产，不得还原、覆盖、删除、暂存或混入提交。
• 只修改版本交付所需的 package.json、apps/desktop/package.json 和发布成功后的 update.json。不得顺手修改业务代码或打包配置。
• 最终 Git 提交只能包含根目录 update.json。两个 package.json 的版本修改留在工作树中，不得暂存或提交；这是本技能的明确交付约束。
• 不得使用 git add .、git add -A、git commit -a、git stash、git reset、git checkout -- 或 git clean。
• GitHub Release 是外部发布动作。用户已明确说“发布、上传 Release、发 GitHub”时执行；用户明确说不发布时不执行；用户未表态时必须在打包完成后询问，不得自行发布。
• 没有已发布且资产完整可下载的对应 Release 时，不得提高、提交或推送 update.json，否则客户端会发现一个无法下载的版本。用户要求“不发 Release 但更新清单”时，说明矛盾并等待决定。

1. 建立基线

1. 读取 Git 状态、当前分支、远端、根目录 package.json、apps/desktop/package.json、update.json、现有 tag 和 apps/desktop/release/ 清单。
2. 记录开始前每个允许修改文件的内容或 diff，以便区分本轮修改与用户已有修改；不得用恢复命令回滚用户内容。
3. 要求两个 package.json 的 version 一致且为三段 SemVer。若不一致，先判断是否存在一次尚未完成的版本准备；无法可靠判断时停止并询问，禁止盲目覆盖。
4. 以两个 package.json 的共同版本为旧版本，将补丁位加一得到新版本。确认新版本大于 update.json.version，并确认远端不存在冲突的 v<新版本> Release/tag；存在冲突时不得覆盖或删除，报告并等待用户决定。
5. 用户指定了明确版本时优先使用该版本，但仍要求它大于当前版本，并说明这不再是默认的补丁递增。

2. 清理旧版本打包残留

只处理固定目录 apps/desktop/release/ 内可证明属于旧版本或 electron-builder 的生成物。

1. 先列出候选项并解析为绝对路径，确认目录没有越界、候选不含源码或用户文档。
2. 删除名称含旧版本的 DeepWrite-<旧版本>-* 产物，以及本次目标会重建的已知中间输出：mac/、mac-arm64/、win-unpacked/、.icon-icns/、latest.yml、latest-mac.yml、builder-debug.yml、builder-effective-config.yaml。
3. 对随机名、未知名或无法证明来源的条目不做删除，只报告。不得对仓库根目录、工作区或未解析的变量执行递归删除，也不得使用 git clean。
4. 删除后再次列目录，确认旧版本安装包和旧更新清单不再残留。说明删除了什么，以及生成物只能通过重新打包恢复。

3. 提高版本并打包

1. 只把两个 package.json 的顶层 version 同步改为新版本，保持其他内容和格式不变。暂时不要修改 update.json。
2. 重新读取两个值并确认一致。打包命令必须从仓库根目录运行，不能直接调用 electron-builder，也不能跳过内置的 pnpm verify：
   • 未指定平台或要求全部：pnpm pack:test
   • Windows x64：pnpm pack:test:win
   • macOS arm64：pnpm pack:test:mac:arm64
   • macOS x64：pnpm pack:test:mac:x64
   • 两种 macOS 架构：pnpm pack:test:mac
3. 命令失败时保留终端关键输出，报告失败的平台、架构和步骤；不得继续发布，也不得声称包可用。
4. 成功后检查请求平台对应的安装包、ZIP、blockmap 和 latest*.yml 均存在且非空。核对文件名版本、更新清单版本和清单内引用文件名一致。
5. Mac 产物还要确认 DMG 校验通过、App 为完整 ad-hoc 签名，并检查本地 DMG 是否意外带有 com.apple.quarantine；存在时仅从明确的新 DMG 发布产物移除该属性。不得声称接收端不会重新添加隔离属性。
6. 记录打包脚本的冒烟结果。受主机系统限制跳过目标平台运行时，明确写“只完成构建，未完成目标平台运行验证”。

4. 按用户要求处理 GitHub Release

用户不发布时，到本地打包交付为止，不修改 update.json，也不创建 tag、Release 或提交。

用户要求发布时：

1. 使用仓库 swjybky/deepwrite 和 tag v<新版本>。先检查 gh auth status、远端仓库、同名 tag/Release 和待上传资产，禁止覆盖已有 Release。
2. 根据用户提供的说明编写 Release notes；用户未提供时，从本轮实际变更生成简洁中文说明，不虚构功能。
3. 先创建 Draft Release，标题为 DeepWrite <新版本>，稳定版不得标为 prerelease。只上传本次请求平台实际成功构建且被更新清单引用的资产：
   • Windows x64：EXE、EXE blockmap、latest.yml。
   • macOS：各目标架构的 DMG、ZIP、ZIP blockmap，以及最终 latest-mac.yml。
4. 同时发布两种 Mac 架构时，先检查最终 latest-mac.yml 是否同时正确引用两个 ZIP 及各自 SHA-512。若清单只包含一个架构，保持 Draft 并停止，不得发布残缺自动更新。
5. 用 GitHub 返回的资产列表逐项核对名称、数量和非零大小；确认 Draft 完整后再发布，并确认不是 prerelease。
6. 发布后再次读取 Release，确认 tag、标题、公开状态和每个下载 URL 可访问。任何检查失败时不更新 update.json。

5. 最后更新并只提交 update.json

仅在 Release 已公开且资产验证全部通过后执行：

1. 保持 schemaVersion、enabled、channel、mandatory、minimumSupportedVersion 和 feedUrl 的既有语义，更新：
   • version 为新版本。
   • title 为 DeepWrite <新版本>。
   • publishedAt 为发布完成时的 Asia/Shanghai ISO 8601 时间。
   • releaseNotes 为与 Release 一致的真实说明。
   • releasePage 为 https://github.com/swjybky/deepwrite/releases/tag/v<新版本>。
2. 校验 update.json 是合法 JSON，且其版本与两个 package.json、Git tag、latest.yml / latest-mac.yml 一致。
3. 不改动现有暂存区。使用路径限定提交，例如 git commit --only -m "chore: update release manifest to v<新版本>" -- update.json；即使暂存区已有其他文件，也不得把它们带入该提交。
4. 立即运行 git show --name-only --format= HEAD。结果必须恰好只有 update.json；若不是，停止且不得推送。
5. 推送前获取远端并比较目标分支。origin/main..HEAD 必须恰好只有本次 update.json 提交；若还包含其他未推送提交，或当前历史不能快进目标分支，停止并询问，不得把额外历史一起推送。
6. 推送当前提交到用户指定远端/分支。未指定时按项目发布约定推送到 origin/main；不得为此切换或清理脏工作树，禁止 force push。
7. 推送后读取远程 main/update.json，确认版本和内容已生效；再报告提交 SHA、Release URL、产物清单与未被提交的两个 package.json 版本修改。

完成检查

• 补丁版本只增加一次，两个 package.json 一致。
• 旧版生成物已按明确清单清理，未知文件未动。
• 使用规定的 pnpm pack:test:* 命令且验证结果真实。
• 只有用户授权时才发布 GitHub Release。
• Release 未完成时绝不提前更新更新清单。
• Git 提交文件列表恰好是 update.json，其他工作树和暂存区内容保持原状。
• 推送范围恰好只有该清单提交，不夹带当前分支的其他未推送提交。
• 对签名、公证、跨平台运行验证和 Gatekeeper 限制作出准确说明。