release

技能：release

发布 OpenWork。 “Release App” 工作流 （.github/workflows/release-macos-aarch64.yml）会构建、签名并在 GitHub release 上发布 桌面应用资源。完整操作手册： docs/RELEASING.md。

版本只存在于 git 标签中。 每个已提交的 package.json 都保留 永久的 0.0.0-dev 占位符；CI 会在构建时将从标签推导出的版本写入工作区 （scripts/release/stamp-version.mjs）。发布时不会向此仓库提交任何内容——没有版本更新提交、没有补录 PR，也没有打包 PR。

只有当运行成功且 GitHub release 已发布 （不是草稿）时，发布才算完成——而不是创建标签时。

---

打标签前：处理修复 PR 和 fork PR

在运行 release:cut 或手动打任何标签前，先执行此步骤。这样做是因为一个 包含修复启动时空白窗口回归问题的确切补丁的 fork PR 曾经开放了一整天，受影响的版本就被打了标签（事件：2026-09-09）：fork PR 永远无法获得 Warden 批准（warden.yml 会跳过它们，而 warden-clearance.yml 要求 head_repository == repository），因此除非有人查看，否则这些 PR 不会显现。

针对 dev，列出自上一个稳定标签以来创建的所有未关闭 PR：其标题或正文匹配 fix(app)|crash|blank|white screen|regression|first launch，以及此时间段内创建或更新的所有未关闭 fork PR：

export R=different-ai/openwork
PREV=$(gh release list -R $R --exclude-drafts --exclude-pre-releases --limit 1 --json tagName --jq '.[0].tagName')
SINCE=$(gh release view "$PREV" -R $R --json createdAt --jq '.createdAt')
echo "previous tag $PREV created $SINCE"
gh pr list -R $R --state open --base dev --limit 300 --search "sort:created-asc" \
  --json number,title,body,isCrossRepository,createdAt,updatedAt,url \
  | jq -r --arg since "$SINCE" '.[]
      | select((.createdAt >= $since
                and ((.title + " " + .body) | test("fix\\(app\\)|crash|blank|white screen|regression|first launch"; "i")))
               or (.isCrossRepository and .updatedAt >= $since))
      | "#\(.number)\(if .isCrossRepository then " [FORK]" else "" end) \(.title) \(.url)"'

然后检查 fork 积压：列出任何时间创建、描述崩溃或启动失败的未关闭 fork PR。检查标题；若与本次发布所修复的 bug 类别匹配 （或属于任何空白屏幕／白屏／首次启动修复），则同样必须先处理。

gh pr list -R $R --state open --base dev --limit 300 \
  --json number,title,body,isCrossRepository,url \
  | jq -r '.[] | select(.isCrossRepository
      and ((.title + " " + .body) | test("crash|blank|white screen|first launch|regression"; "i")))
      | "#\(.number) \(.title) \(.url)"'

对于列出的每个 PR，决定以下其中一项：

• 先合并——审查该 PR（fork PR：使用 review-a-contributor-pr 技能）， 合并到 dev，然后打标签。
• 照常发布——此次发布不包含该修复。只有明确记录决策后才允许这样做：将 PR 编号列表、决策人以及一句话原因，粘贴到发布后由 changelog.yml 打开的 release notes PR（docs(changelog): release notes for vX.Y.Z，分支 automation/changelog-vX.Y.Z-*）中的 Known open fixes 标题下。如果 notes PR 尚未出现，就将相同内容写入 GitHub release 正文（gh release edit vX.Y.Z -R $R --notes-file ...），等 PR 打开后再移过去。
• 不是修复／不相关——在同一列表中说明；即使是误报，也要写一行，避免下次发布时不经意间重新分诊。

空列表也要记录（Known open fixes: none matched）。带有非空列表却没有记录决策就打标签，正是此步骤要避免的失败情形；请勿继续。

---

发布（默认流程）

pnpm release:cut            # dispatches Release App with bump=patch
pnpm release:cut minor      # or major
pnpm release:cut --version 0.19.0
pnpm release:cut:watch      # same as release:cut, then tails the run

手动执行的等效操作：

gh workflow run "Release App" --repo different-ai/openwork -f bump=patch

此运行会根据现有 v* 标签确定下一个版本，在 origin/dev HEAD 上创建标签并验证标签（scripts/release/verify-tag.mjs：格式稳定，且严格高于所有其他稳定标签），将版本写入 CI 工作区，构建全部 18 个 electron 矩阵任务，发布 npm、 Daytona 和 AUR，然后将草稿 release 公开。

标签引用通过组织所有的 diff-warden 应用令牌创建（该令牌是 v* ruleset 的绕过主体；WARDEN_APP_ID 和 WARDEN_PRIVATE_KEY 位于 warden-clearance 环境中）。应用创建的标签会重新触发工作流；重复运行会被 actor 守卫跳过。如果标签推送遭拒，运行会失败并给出说明——请修复 ruleset 绕过配置，或改用管理员手动推送标签。

先打标签（加急，仅限管理员）

若要发布尚未审查并合并到 dev 的提交（用于事件响应），请手动推送标签——标签名称必须准确对应将要发布的代码：

git tag vX.Y.Z <sha>
git push origin vX.Y.Z     # v* ruleset grants admins bypass

如果被打标签的提交不在 dev 上，Expedited Release Audit 工作流会打开一条事后审查 issue。绝不要直接推送 dev，也不要绕过其分支规则。

---

监控

gh run list --repo different-ai/openwork --workflow "Release App" --limit 1
gh run watch <run-id> --repo different-ai/openwork --exit-status --interval 90

发布以 electron 矩阵、electron 资源和 npm 发布为门控条件。 Publish AUR（继续运行，不因失败而中断）和 Build + Push Daytona Snapshot 是 非阻塞渠道：它们失败不会阻止发布——渠道恢复后，使用同一标签重新运行 工作流即可。

重新运行现有标签（恢复）——用于处理瞬时故障或重放 非阻塞渠道：

gh workflow run "Release App" --repo different-ai/openwork -f tag=vX.Y.Z

如果版本已经发布，恢复运行会跳过所有桌面 构建步骤和更新器清单合并；只会重放 npm、AUR 和 Daytona。重新构建会重新签署安装程序，而在 publish-release 之前失败的运行会导致 latest*.yml 指向 已不存在的文件。所有自动更新都会因此失败，报错为 sha512 checksum mismatch（v0.18.52）。 应在下一个补丁版本中发布新的桌面文件。

恢复运行会跳过标签创建和单调性检查，从标签检出固定版本的源代码， 并自动获取 dev 上的工作流文件修复（工作流定义来自触发运行的 ref；只有检出的源代码固定到标签）。

如果运行在发布版本之前失败： 通过常规受保护分支 PR 将修复合入 dev， 然后发布下一个补丁版本（pnpm release:cut）。 只有在确认 GitHub Release 仍处于仅草稿状态后，才能删除并重新创建标签：

git push --delete origin vX.Y.Z

---

验证

gh release view vX.Y.Z --repo different-ai/openwork --json assets --jq '.assets[].name'

应能看到应用资源（openwork-<platform>-X.Y.Z.*、latest*.yml 更新器 清单），包括：

• openwork-mac-arm64-X.Y.Z.dmg
• openwork-mac-x64-X.Y.Z.dmg
• openwork-win-x64-X.Y.Z.exe

在发布版本之前，桌面更新器访问 latest*.yml 会返回 404—— 在构建期间运行的应用中出现此错误是预期现象， 并且会自动恢复。抽查一个下载 URL，确认其可正常解析（302 重定向到 release-assets CDN）：

curl -sI "https://github.com/different-ai/openwork/releases/download/vX.Y.Z/openwork-mac-arm64-X.Y.Z.dmg" | head -2

确认 npm view openwork-server version 的结果一致。

---

验证已发布版本

资源发布后，在告知任何人该版本可以安全推广之前，先对已发布版本的 mac-arm64 压缩包运行 validate-a-release 技能 （.opencode/skills/validate-a-release/SKILL.md）：它会检查更新器清单的 sha512，并验证签名和公证。

---

备注

• 桌面安装程序的修复只能通过新版本发布给用户——组织 安装入口（/v1/install/:platform）会 302 重定向到带版本号的资源。
• den-api 在运行时通过 GitHub Releases API 发现已发布版本 （ee/apps/den-api/src/desktop-releases.ts）：版本一经发布， 组织即可使用——无需部署 den。 已提交的 generated/desktop-versions.ts 仅用作冷启动/离线 回退方案。
• AUR 发布时会在 CI 工作区中渲染已提交的 packaging/aur 模板 （pkgver=0.0.0），并推送到 aur.archlinux.org——AUR 端的提交就是 该渠道的发布协议；此仓库保持不变。
• 所有应用中的原生工作区依赖必须保持在同一个主版本—— electron-builder 会重建找到的每个副本（参见 #3561/#3563，了解这导致的 三次发布故障）。