OpenWork 发布流程实战指南Tag 驱动的零提交 GitHub Actions 发布管线【免费下载链接】openworkThe open-source alternative to Claude Cowork (powered by opencode)项目地址: https://gitcode.com/GitHub_Trending/ope/openworkOpenWork基于 opencode 的开源 Claude Cowork 替代品的发布流程完全由GitHub Actions GitHub Releases驱动版本只存在于 git tag 中仓库内所有package.json永久保留0.0.0-dev占位符CI 在构建时把 tag 派生的版本号盖章进工作区——发一次版对仓库做零提交。本文以仓库内.opencode/commands/release.md命令文档为主体结合.opencode/skills/release/SKILL.md技能文档与docs/RELEASING.md完整 runbook并深入scripts/release/*.mjs与.github/workflows/release-macos-aarch64.yml源码完整讲解 OpenWork 发布流程的触发方式、内部机制、验证清单、故障恢复与回滚方案。核心原则一次发布 一个 tag零提交在动手前先建立三个基本认知它们是整个发布流程设计的基石版本只存在于 git tag发布的唯一事实来源是vX.Y.Z形式的稳定 tag。所有已提交的package.jsonapps/app/package.json、apps/desktop/package.json、apps/server/package.json一律持有永久的0.0.0-dev占位符由 CI 在构建时通过 stamp-version.mjs 写入真实版本。发布对仓库零改动没有 bump 提交、没有 backfill PR、没有打包 PR——切一个版本不会在仓库留下任何提交docs/RELEASING.md明确Cutting a release makes zero commits to this repo。发布的完成标准不是 tag 创建成功而是Release App工作流运行全绿且Publish GitHub Release步骤把 draft 翻转成公开 release。命令入口与参数release.md命令文档定义了$ARGUMENTS的语义为空默认打一个 patch 版本X.Y.Z的Z1为minorX.(Y1).0为major(X1).0.0。命令运行器会据此加载并遵循 .opencode/skills/release/SKILL.md完整 runbook 见 docs/RELEASING.md默认走tag-firsttag 优先路径除非用户明确要求 PR-first。当前仓库根目录 package.json 实际暴露的发布脚本为pnpm release:cut # dispatch Release Appbumppatch pnpm release:cut minor # 或 major pnpm release:cut:watch # dispatch 后实时 tail 运行日志 pnpm release:review # 健康检查占位符完好、opencode pin 存在 pnpm release:rollback # 回滚已发布的版本release:cut对应 scripts/release/cut.mjs其参数解析逻辑cut.mjs#L20-L24确认默认 bump 类型是patch支持--version X.Y.Z显式指定版本支持--dry-run与--watch。脚本先检查gh auth status然后执行gh workflow run Release App --repo repo -f bumppatch或-f versionX.Y.Z完成 dispatch。发布前的闸门先处理 open fix PR 与 fork PR发布前有一个强制前置步骤来自SKILL.md其起因是 2026-09-09 一次空白窗口回归修复 PR 滞留一天后才被 tag 的事故fork 分支的 PR 永远不会获得 Warden 清障warden.yml跳过 fork PR而warden-clearance.yml要求head_repository repository因此必须主动列出上一个稳定 tag 之后、针对dev打开、标题或正文匹配fix(app)|crash|blank|white screen|regression|first launch的 PR该时间窗口内创建或更新的所有 fork PR任意历史的、描述崩溃或启动失败类 bug 的 open fork PR。对每一个命中的 PR必须明确三选一并记录在案先合并再 tag、照常发布但记录已知未合并修复清单放入 changelog 自动打开的 release notes PR 的Known open fixes小节或临时写入 release body、判定与本次无关也要占一行避免下次发布重复排查。空清单也要记录Known open fixes: none matched。带着非空清单且无记录决定就 tag正是这一步要阻止的失败模式。完整发布流程六步走release.md给出了端到端的六步流程第 1 步基于干净的origin/dev工作先git fetch origin/dev且只从基于其当前 tip 的干净 checkout 工作。如果当前 checkout 是脏的或dev已经被检出就创建一个隔离的 release worktree原 checkout 保持不动。这条纪律保证了发布操作永远不会污染开发者自己的工作区。第 2 步准备发布prepare依次执行pnpm release:prepare:dry -- bump pnpm release:prepare -- bump在隔离分支 worktree 中只有独立确认该分支基于当前origin/dev且 worktree 干净后才可加--ci。与当前仓库脚本的关系release.md中描述的release:prepare/release:ship及其伴随的 backfill PR 属于提交式发布流程。而 docs/RELEASING.md 的 History 小节说明自 2026-08 起发布已演进为commit-freetag 驱动模式当前仓库以release:cutdispatch为主线不再需要 bump 提交与 backfill PR。阅读本文时可将第 2、3 步理解为命令文档对发布准备动作的完整描述实际执行以仓库当前的pnpm release:cut为准。第 3 步执行发布ship执行pnpm release:ship。其中一步——向受保护的dev直接推送被拒绝——是预期行为release:ship必须推送release/vX.Y.Z-dev-sync分支并打开 backfill PR。任何情况下不得绕过或强推dev。第 4 步盯到 Release App 跑完Release App工作流必须完整跑完。在Publish GitHub Release成功且 release 变为公开之前发布不算完成——draft 状态下的 release 对组织安装入口和更新门禁都是不可见的。第 5 步合并 backfill PR处理 AUR PR让版本 backfill PR 获得批准并合并。若工作流打开了 AUR 打包 PR报告其 URL、等待其合并然后按 release 技能描述的规则用同一个 tag 重跑Release App。第 6 步验证公开资产验证公开 release 资产可解析、npm view openwork-server version与 tag 一致、最新的 Daytona snapshot 运行是绿的。最后报告以下信息tag、release URL、workflow 判定、已合并的 backfill PR、npm 版本、公开资产检查结果以及任何非阻塞渠道的状态。不要把 Node 运行时弃用警告或预期的受保护分支拒绝当作发布失败去诊断——它们属于正常现象。分支保护两条发布路径docs/RELEASING.md详细说明了保护机制的实际形态dev分支对所有人包括 admin受保护要求 PR、1 个 approval、approval 必须来自非最后推送者、提交签名、线性历史。tag 驱动发布根本不触碰dev因此没有 backfill 需求。v*tag 创建受限admin 与 GitHub Actions 主体创建 tag 的工作流可以创建。由此形成两条进入路径路径 ADispatch默认——pnpm release:cut。tag 创建在origin/devHEAD 上所以发布出去的代码一定是经过评审的代码。路径 BTag-first紧急仅 admin——当必须立即发布一个尚未上dev的提交如 incident response时git tag vX.Y.Z sha git push origin vX.Y.Ztag 精确指向实际发布的代码没有 bump 提交。Expedited Release Audit工作流会在已发布 tag 的提交不在dev上时自动打开事后评审 issue之后应通过正常评审 PR 把相同改动落到dev闭环。Release App 工作流内部机制源码级Release App定义在 .github/workflows/release-macos-aarch64.yml1288 行触发方式包括v*tag 推送与workflow_dispatchdispatch 输入包括bumppatch/minor/major默认 patch、version显式版本覆盖 bump、tag恢复重跑已存在 tag、draft默认 true、prerelease、notarize、publish_npm、publish_daytona_snapshot、build_electron、sign_windows、benchmark_only等。其核心作业链如下resolve-release版本计算与 tag 创建版本计算使用 scripts/release/versions.mjsreadStableTagVersions()读取全部v*taghighestStableVersion()取最高稳定版本bumpStableVersion(version, type)按 patch/minor/major 递增versions.mjs#L57-L65。tag 创建在origin/devHEAD 上。关键在于GitHub 内置的 Actions app不能作为 ruleset bypass actorGitHub 会拒绝所以工作流用 org 拥有的diff-wardenGitHub Appv*tag ruleset 的 bypass 名单成员通过REST API创建 tag ref——token 来自WARDEN_APP_IDWARDEN_PRIVATE_KEYwarden-clearanceenvironment。该 environment 的部署策略dev v* tag保证 key 只能被已评审代码触达feature 分支上的工作流改版既不能删掉权限检查也拿不到 key。app 创建的 tag 会再次触发本工作流push事件但重复运行被 actor 守卫github.actor ! diff-warden[bot]跳过——dispatch 运行才是发布运行。dispatch 还受权限门禁约束Require release permission步骤workflow#L123-L143要求 dispatch 者是 repo admin或在RELEASE_MANAGERS变量逗号分隔的登录名中。若 app token 不可用回退到GITHUB_TOKENpush tag通常会被 ruleset 拒绝并给出明确失败指引。verify-releasetag 与占位符校验scripts/release/verify-tag.mjs 校验严格稳定格式vX.Y.Zprerelease 永远不会通过 Release App 发布、tag 在 clone 中存在需要 fetch-depth: 0且 fresh 模式下必须严格大于其它所有稳定 tagverify-tag.mjs#L41-L53。恢复重跑使用--mode recovery跳过单调性检查。node scripts/release/review.mjs --strict守卫占位符三个package.json必须仍是0.0.0-dev并检查constants.json中的 opencode 版本 pin 存在review.mjs。构建矩阵版本盖章与 18 个 electron legs构建作业 checkouttag 本身源码永远 pin 到 tag恢复重跑时 workflow 定义从 dispatch ref 运行因此工作流文件的修复会自动生效而 shipped 代码保持 tag 所指向的内容不变。scripts/release/stamp-version.mjs 把版本写入 CI 工作区内的apps/{app,desktop,server}/package.jsonSTAMPED_PACKAGE_PATHSstamp-version.mjs#L17-L21这就是 electron-builder、app.getVersion()、Vite renderer bundle 与openwork-servernpm 发布共同读取的版本来源。构建矩阵包含 macOS/Linux/Windows 三平台 × x64/arm64 两种架构 × public/cloud/enterprise 三种分发配置共 18 个 leg分别使用 electron-builder.yml、electron-builder.cloud.yml、electron-builder.enterprise.yml。macOS 强制 notarize未配置 Apple 签名密钥直接失败Windows 安装包经 Azure Artifact Signing 签名sign_windows开关签名后用 refresh-signed-windows-artifacts.mjs 刷新 blockmap 与 manifest。每个 leg 有belt-and-braces断言产物文件名必须携带$RELEASE_VERSION防止盖章失败导致0.0.0-dev产物被静默发布。public 分发之外的 custom 分发cloud/enterprise会把latest*.yml归一化为cloud*.yml/enterprise*.yml避免更新通道串味。publish-release翻转 draft 即发布时刻Publish Electron Assets GitHub Release作业workflow#L973-L1048在 electron 矩阵、electron 资产、npm 发布全部就绪后将 release 从 draft 翻转为--latest或--prerelease并输出published_stabletrue随后 dispatchchangelog.yml生成 changelog PR 与 release notes。发布门禁放行/阻塞清单条件是否阻塞发布electron 矩阵18 legs构建上传阻塞electron 资产与 updater manifest 存在阻塞latest*.yml未发布时桌面 updater 404 是预期的自愈openwork-servernpm 发布阻塞Publish AURcontinue-on-error不阻塞aur.archlinux.org 故障不算发布失败AUR 发布用 CI 工作区渲染提交的 packaging/aur 模板pkgver0.0.0 真实版本与校验和只推送到 AUR remote仓库零改动Build Push Daytona Snapshot不阻塞快照事后可用同一 tag 重跑重建den-api 的运行时版本发现发布公开后组织侧如何拿到新版本ee/apps/den-api/src/desktop-releases.ts 在运行时读取 GitHub Releases API缓存 TTL 5 分钟desktop-releases.ts#L7排除 draft 与 prerelease——因此回滚降级会立即把版本从发布列表移除。提交的 generated/desktop-versions.ts 只是冷启动/离线回退快照可偶尔用node scripts/release/generate-desktop-versions.mjs --version latest刷新MIN_SUPPORTED_DESKTOP_VERSION策略常量定义在 generate-desktop-versions.mjs。org 安装门/v1/install/:platform302 到带版本的资产因此桌面安装包的修复只有通过新 release 才能触达用户。发布后验证清单gh run list --repo repo --workflow Release App --limit 3 gh release view vX.Y.Z --repo repo # 必须是 published不是 draft gh release view vX.Y.Z --repo repo --json assets --jq .assets[].name核对要点Release非 draft且标记为 Latest资产数量正确macOS Linux Windows updaterlatest*.ymlmanifestmanifest 未发布时桌面 updater 会 404npm view openwork-server version显示新版本curl -s https://api.openworklabs.com/v1/app-version在 den-api 缓存刷新后≤5 分钟列出新版本资产抽查curl -sIrelease 下载 URL 返回 302指向 release-assets CDN期望出现的典型资产openwork-mac-arm64-X.Y.Z.dmg、openwork-mac-x64-X.Y.Z.dmg、openwork-win-x64-X.Y.Z.exe。故障恢复与重跑重跑已存在 tag基础设施故障、回放 AUR/Daytonagh workflow run Release App --repo repo -f tagvX.Y.Z恢复运行跳过 tag 创建与单调性检查源码 pin 到 tag工作流文件修复自动从dev生效workflow 定义从 dispatch ref 运行。已 tag 但发布前发现缺陷保持 release 为 draft 或删除gh release delete vX.Y.Z在dev上修复后切下一个 patch。若坏版本已到 npm执行npm deprecate openwork-serverX.Y.Z reason — use X.Y.Z1。回滚已发布的版本当坏版本已published且标记 Latest 时使用release:rollback流程第 1 步止血stop the bleedpnpm release:rollback pnpm release:rollback --bad vX.Y.Z --execute先 dry-run 再执行。执行时必须 pin--bad——成功回滚后goodrelease 成为 Latest裸跑会把 good 误选为 bad。脚本逻辑在 scripts/release/rollback.mjs自动选择低于坏版本的最高已发布稳定 release 作为目标selectRollbackTarget把 Latest 从坏版本重指向目标版本把坏版本降级为 prerelease资产与 tag 保留——这同时把版本从 den-api 的运行时发布列表移除org 安装与更新门禁在缓存窗口内停止提供它在坏版本 release notes 前置回滚横幅 ⚠️ Rolled back on date. Do not install; use target instead.rollback.mjs#L120-L123重复执行幂等hasRollbackBanner检测已存在横幅。第 2 步为已更新客户端重新发布Updater 拒绝降级。把最后 good 提交打一个高于坏版本的 tag 即可——无需提交、无需 worktreegit tag vX.Y.Z1 last-good-tag git push origin vX.Y.Z1第 3 步deprecate npmnpm deprecate openwork-serverbad-version rolled back — use next客户端状态恢复手段尚未更新第 1 步即可修复已更新只有第 2 步能修复撤销出问题的 PR 走dev上的正常评审 PR 流程该清理不在用户恢复的关键路径上。版本信息速查问题答案存在哪些版本git tag --list v*/ GitHub Releases最新版本gh release view --json tagNamevX.Y.Z 是哪个提交git rev-parse vX.Y.Z当前 checkout 是什么版本git describe --tagspackage.json 故意显示0.0.0-dev受支持的最老桌面版本MIN_SUPPORTED_DESKTOP_VERSIONgenerate-desktop-versions.mjs 中的提交策略唯一的例外pull-only 评估栈packaging/docker/docker-compose.eval.yml 按versiondigestpin 了 den-api 与 den-web 镜像。在Publish EE Artifacts推送稳定 tag 镜像后用 pin-compose-images.mjs 更新 pin含 docs 提交 sha 校验和check-compose-pins.mjs 在 tag 存在后校验{ok:true,...}——pin PR 与 changelog PR 一样跟随发布不属于切版本本身。Troubleshooting 速查表症状原因修复运行在推送 tag 时失败diff-warden app 不在v*ruleset bypass 名单或其 secrets 未设置重新添加 appSettings → Rules/ 恢复WARDEN_APP_IDWARDEN_PRIVATE_KEY或 admin 手动 push tag 后重跑全新 cut 报Tag vX.Y.Z already exists版本已发布用-f tagvX.Y.Zrecovery重跑或选更高版本verify-release单调性失败手动 tag 低于已存在 release选择高于当前最高稳定 tag 的版本release:review占位符检查失败有人把真实版本提交进了 package.json恢复0.0.0-dev——CI 从 tag 盖章版本桌面应用对新版本 updater 404tag 存在但 release 仍是运行中的 draft等待Publish GitHub Release自愈仅 AUR / Daytona 标红外部渠道故障release 照常发布渠道恢复后用同一 tag 重跑全部electron-linux-*编译原生模块失败原生模块需适配新 Electron 头文件raw-V8全 workspace 的原生依赖收敛到同一个基于 N-API 的大版本见 #3561/#3563 的教训Electron 35→43 升级时apps/server停在 better-sqlite3 v12 而 desktop 已到 v13electron-builder 会重建找到的每一份原生模块副本导致三次发布标红最终收敛到 v13 并用bun:sqlite解决Windows afterPack 报Missing staged MCP runtime packageasar 路径分隔符不匹配已修复——normalizeAsarEntryPathelectron-after-pack.cjs发布成功后的最后一道关validate-a-release资产公开后、对外宣布版本安全可铺开之前运行 .opencode/skills/validate-a-release/SKILL.md 技能用已发布 mac-arm64 zip 启动 enterprise 与 cloud 二进制覆盖packaged-first-launch全新安装与released-enterprise-activated激活安装、旧版本 profile 被新构建打开等场景核对 updater manifest 的 sha512并验证签名/notarization。历史演进为什么是现在这套设计2026-08发布变成 commit-free——tag 是唯一版本来源CI 盖章工作区den-api 运行时读取已发布 releaseAUR 渲染已提交模板。此前每次发布都需要版本 bump 提交、dev backfill PR 和 AUR 打包 PR。2026-08-05v0.18.15/v0.18.16Electron 35→43 升级引发三次发布标红根源是原生依赖版本分裂最终通过 workspace 收敛统一 N-API 大版本并让opencode-db在 Bun 下使用bun:sqlite解决。这套 tag 驱动的设计把发版收敛为一个不可变的 tag 一条可观测的 CI 管线版本语义由versions.mjs单点计算发布完整性由verify-tag.mjs与review.mjs --strict把关公开与否由publish-release一个作业决定回滚则是重指 Latest 降级 横幅三个 gh 调用。理解这条链路就能在 OpenWork 上安全地执行从 patch 到回滚的每一次发布操作。【免费下载链接】openworkThe open-source alternative to Claude Cowork (powered by opencode)项目地址: https://gitcode.com/GitHub_Trending/ope/openwork创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
OpenWork 发布流程实战指南Tag 驱动的零提交 GitHub Actions 发布管线【免费下载链接】openworkThe open-source alternative to Claude Cowork (powered by opencode)项目地址: https://gitcode.com/GitHub_Trending/ope/openworkOpenWork基于 opencode 的开源 Claude Cowork 替代品的发布流程完全由GitHub Actions GitHub Releases驱动版本只存在于 git tag 中仓库内所有package.json永久保留0.0.0-dev占位符CI 在构建时把 tag 派生的版本号盖章进工作区——发一次版对仓库做零提交。本文以仓库内.opencode/commands/release.md命令文档为主体结合.opencode/skills/release/SKILL.md技能文档与docs/RELEASING.md完整 runbook并深入scripts/release/*.mjs与.github/workflows/release-macos-aarch64.yml源码完整讲解 OpenWork 发布流程的触发方式、内部机制、验证清单、故障恢复与回滚方案。核心原则一次发布 一个 tag零提交在动手前先建立三个基本认知它们是整个发布流程设计的基石版本只存在于 git tag发布的唯一事实来源是vX.Y.Z形式的稳定 tag。所有已提交的package.jsonapps/app/package.json、apps/desktop/package.json、apps/server/package.json一律持有永久的0.0.0-dev占位符由 CI 在构建时通过 stamp-version.mjs 写入真实版本。发布对仓库零改动没有 bump 提交、没有 backfill PR、没有打包 PR——切一个版本不会在仓库留下任何提交docs/RELEASING.md明确Cutting a release makes zero commits to this repo。发布的完成标准不是 tag 创建成功而是Release App工作流运行全绿且Publish GitHub Release步骤把 draft 翻转成公开 release。命令入口与参数release.md命令文档定义了$ARGUMENTS的语义为空默认打一个 patch 版本X.Y.Z的Z1为minorX.(Y1).0为major(X1).0.0。命令运行器会据此加载并遵循 .opencode/skills/release/SKILL.md完整 runbook 见 docs/RELEASING.md默认走tag-firsttag 优先路径除非用户明确要求 PR-first。当前仓库根目录 package.json 实际暴露的发布脚本为pnpm release:cut # dispatch Release Appbumppatch pnpm release:cut minor # 或 major pnpm release:cut:watch # dispatch 后实时 tail 运行日志 pnpm release:review # 健康检查占位符完好、opencode pin 存在 pnpm release:rollback # 回滚已发布的版本release:cut对应 scripts/release/cut.mjs其参数解析逻辑cut.mjs#L20-L24确认默认 bump 类型是patch支持--version X.Y.Z显式指定版本支持--dry-run与--watch。脚本先检查gh auth status然后执行gh workflow run Release App --repo repo -f bumppatch或-f versionX.Y.Z完成 dispatch。发布前的闸门先处理 open fix PR 与 fork PR发布前有一个强制前置步骤来自SKILL.md其起因是 2026-09-09 一次空白窗口回归修复 PR 滞留一天后才被 tag 的事故fork 分支的 PR 永远不会获得 Warden 清障warden.yml跳过 fork PR而warden-clearance.yml要求head_repository repository因此必须主动列出上一个稳定 tag 之后、针对dev打开、标题或正文匹配fix(app)|crash|blank|white screen|regression|first launch的 PR该时间窗口内创建或更新的所有 fork PR任意历史的、描述崩溃或启动失败类 bug 的 open fork PR。对每一个命中的 PR必须明确三选一并记录在案先合并再 tag、照常发布但记录已知未合并修复清单放入 changelog 自动打开的 release notes PR 的Known open fixes小节或临时写入 release body、判定与本次无关也要占一行避免下次发布重复排查。空清单也要记录Known open fixes: none matched。带着非空清单且无记录决定就 tag正是这一步要阻止的失败模式。完整发布流程六步走release.md给出了端到端的六步流程第 1 步基于干净的origin/dev工作先git fetch origin/dev且只从基于其当前 tip 的干净 checkout 工作。如果当前 checkout 是脏的或dev已经被检出就创建一个隔离的 release worktree原 checkout 保持不动。这条纪律保证了发布操作永远不会污染开发者自己的工作区。第 2 步准备发布prepare依次执行pnpm release:prepare:dry -- bump pnpm release:prepare -- bump在隔离分支 worktree 中只有独立确认该分支基于当前origin/dev且 worktree 干净后才可加--ci。与当前仓库脚本的关系release.md中描述的release:prepare/release:ship及其伴随的 backfill PR 属于提交式发布流程。而 docs/RELEASING.md 的 History 小节说明自 2026-08 起发布已演进为commit-freetag 驱动模式当前仓库以release:cutdispatch为主线不再需要 bump 提交与 backfill PR。阅读本文时可将第 2、3 步理解为命令文档对发布准备动作的完整描述实际执行以仓库当前的pnpm release:cut为准。第 3 步执行发布ship执行pnpm release:ship。其中一步——向受保护的dev直接推送被拒绝——是预期行为release:ship必须推送release/vX.Y.Z-dev-sync分支并打开 backfill PR。任何情况下不得绕过或强推dev。第 4 步盯到 Release App 跑完Release App工作流必须完整跑完。在Publish GitHub Release成功且 release 变为公开之前发布不算完成——draft 状态下的 release 对组织安装入口和更新门禁都是不可见的。第 5 步合并 backfill PR处理 AUR PR让版本 backfill PR 获得批准并合并。若工作流打开了 AUR 打包 PR报告其 URL、等待其合并然后按 release 技能描述的规则用同一个 tag 重跑Release App。第 6 步验证公开资产验证公开 release 资产可解析、npm view openwork-server version与 tag 一致、最新的 Daytona snapshot 运行是绿的。最后报告以下信息tag、release URL、workflow 判定、已合并的 backfill PR、npm 版本、公开资产检查结果以及任何非阻塞渠道的状态。不要把 Node 运行时弃用警告或预期的受保护分支拒绝当作发布失败去诊断——它们属于正常现象。分支保护两条发布路径docs/RELEASING.md详细说明了保护机制的实际形态dev分支对所有人包括 admin受保护要求 PR、1 个 approval、approval 必须来自非最后推送者、提交签名、线性历史。tag 驱动发布根本不触碰dev因此没有 backfill 需求。v*tag 创建受限admin 与 GitHub Actions 主体创建 tag 的工作流可以创建。由此形成两条进入路径路径 ADispatch默认——pnpm release:cut。tag 创建在origin/devHEAD 上所以发布出去的代码一定是经过评审的代码。路径 BTag-first紧急仅 admin——当必须立即发布一个尚未上dev的提交如 incident response时git tag vX.Y.Z sha git push origin vX.Y.Ztag 精确指向实际发布的代码没有 bump 提交。Expedited Release Audit工作流会在已发布 tag 的提交不在dev上时自动打开事后评审 issue之后应通过正常评审 PR 把相同改动落到dev闭环。Release App 工作流内部机制源码级Release App定义在 .github/workflows/release-macos-aarch64.yml1288 行触发方式包括v*tag 推送与workflow_dispatchdispatch 输入包括bumppatch/minor/major默认 patch、version显式版本覆盖 bump、tag恢复重跑已存在 tag、draft默认 true、prerelease、notarize、publish_npm、publish_daytona_snapshot、build_electron、sign_windows、benchmark_only等。其核心作业链如下resolve-release版本计算与 tag 创建版本计算使用 scripts/release/versions.mjsreadStableTagVersions()读取全部v*taghighestStableVersion()取最高稳定版本bumpStableVersion(version, type)按 patch/minor/major 递增versions.mjs#L57-L65。tag 创建在origin/devHEAD 上。关键在于GitHub 内置的 Actions app不能作为 ruleset bypass actorGitHub 会拒绝所以工作流用 org 拥有的diff-wardenGitHub Appv*tag ruleset 的 bypass 名单成员通过REST API创建 tag ref——token 来自WARDEN_APP_IDWARDEN_PRIVATE_KEYwarden-clearanceenvironment。该 environment 的部署策略dev v* tag保证 key 只能被已评审代码触达feature 分支上的工作流改版既不能删掉权限检查也拿不到 key。app 创建的 tag 会再次触发本工作流push事件但重复运行被 actor 守卫github.actor ! diff-warden[bot]跳过——dispatch 运行才是发布运行。dispatch 还受权限门禁约束Require release permission步骤workflow#L123-L143要求 dispatch 者是 repo admin或在RELEASE_MANAGERS变量逗号分隔的登录名中。若 app token 不可用回退到GITHUB_TOKENpush tag通常会被 ruleset 拒绝并给出明确失败指引。verify-releasetag 与占位符校验scripts/release/verify-tag.mjs 校验严格稳定格式vX.Y.Zprerelease 永远不会通过 Release App 发布、tag 在 clone 中存在需要 fetch-depth: 0且 fresh 模式下必须严格大于其它所有稳定 tagverify-tag.mjs#L41-L53。恢复重跑使用--mode recovery跳过单调性检查。node scripts/release/review.mjs --strict守卫占位符三个package.json必须仍是0.0.0-dev并检查constants.json中的 opencode 版本 pin 存在review.mjs。构建矩阵版本盖章与 18 个 electron legs构建作业 checkouttag 本身源码永远 pin 到 tag恢复重跑时 workflow 定义从 dispatch ref 运行因此工作流文件的修复会自动生效而 shipped 代码保持 tag 所指向的内容不变。scripts/release/stamp-version.mjs 把版本写入 CI 工作区内的apps/{app,desktop,server}/package.jsonSTAMPED_PACKAGE_PATHSstamp-version.mjs#L17-L21这就是 electron-builder、app.getVersion()、Vite renderer bundle 与openwork-servernpm 发布共同读取的版本来源。构建矩阵包含 macOS/Linux/Windows 三平台 × x64/arm64 两种架构 × public/cloud/enterprise 三种分发配置共 18 个 leg分别使用 electron-builder.yml、electron-builder.cloud.yml、electron-builder.enterprise.yml。macOS 强制 notarize未配置 Apple 签名密钥直接失败Windows 安装包经 Azure Artifact Signing 签名sign_windows开关签名后用 refresh-signed-windows-artifacts.mjs 刷新 blockmap 与 manifest。每个 leg 有belt-and-braces断言产物文件名必须携带$RELEASE_VERSION防止盖章失败导致0.0.0-dev产物被静默发布。public 分发之外的 custom 分发cloud/enterprise会把latest*.yml归一化为cloud*.yml/enterprise*.yml避免更新通道串味。publish-release翻转 draft 即发布时刻Publish Electron Assets GitHub Release作业workflow#L973-L1048在 electron 矩阵、electron 资产、npm 发布全部就绪后将 release 从 draft 翻转为--latest或--prerelease并输出published_stabletrue随后 dispatchchangelog.yml生成 changelog PR 与 release notes。发布门禁放行/阻塞清单条件是否阻塞发布electron 矩阵18 legs构建上传阻塞electron 资产与 updater manifest 存在阻塞latest*.yml未发布时桌面 updater 404 是预期的自愈openwork-servernpm 发布阻塞Publish AURcontinue-on-error不阻塞aur.archlinux.org 故障不算发布失败AUR 发布用 CI 工作区渲染提交的 packaging/aur 模板pkgver0.0.0 真实版本与校验和只推送到 AUR remote仓库零改动Build Push Daytona Snapshot不阻塞快照事后可用同一 tag 重跑重建den-api 的运行时版本发现发布公开后组织侧如何拿到新版本ee/apps/den-api/src/desktop-releases.ts 在运行时读取 GitHub Releases API缓存 TTL 5 分钟desktop-releases.ts#L7排除 draft 与 prerelease——因此回滚降级会立即把版本从发布列表移除。提交的 generated/desktop-versions.ts 只是冷启动/离线回退快照可偶尔用node scripts/release/generate-desktop-versions.mjs --version latest刷新MIN_SUPPORTED_DESKTOP_VERSION策略常量定义在 generate-desktop-versions.mjs。org 安装门/v1/install/:platform302 到带版本的资产因此桌面安装包的修复只有通过新 release 才能触达用户。发布后验证清单gh run list --repo repo --workflow Release App --limit 3 gh release view vX.Y.Z --repo repo # 必须是 published不是 draft gh release view vX.Y.Z --repo repo --json assets --jq .assets[].name核对要点Release非 draft且标记为 Latest资产数量正确macOS Linux Windows updaterlatest*.ymlmanifestmanifest 未发布时桌面 updater 会 404npm view openwork-server version显示新版本curl -s https://api.openworklabs.com/v1/app-version在 den-api 缓存刷新后≤5 分钟列出新版本资产抽查curl -sIrelease 下载 URL 返回 302指向 release-assets CDN期望出现的典型资产openwork-mac-arm64-X.Y.Z.dmg、openwork-mac-x64-X.Y.Z.dmg、openwork-win-x64-X.Y.Z.exe。故障恢复与重跑重跑已存在 tag基础设施故障、回放 AUR/Daytonagh workflow run Release App --repo repo -f tagvX.Y.Z恢复运行跳过 tag 创建与单调性检查源码 pin 到 tag工作流文件修复自动从dev生效workflow 定义从 dispatch ref 运行。已 tag 但发布前发现缺陷保持 release 为 draft 或删除gh release delete vX.Y.Z在dev上修复后切下一个 patch。若坏版本已到 npm执行npm deprecate openwork-serverX.Y.Z reason — use X.Y.Z1。回滚已发布的版本当坏版本已published且标记 Latest 时使用release:rollback流程第 1 步止血stop the bleedpnpm release:rollback pnpm release:rollback --bad vX.Y.Z --execute先 dry-run 再执行。执行时必须 pin--bad——成功回滚后goodrelease 成为 Latest裸跑会把 good 误选为 bad。脚本逻辑在 scripts/release/rollback.mjs自动选择低于坏版本的最高已发布稳定 release 作为目标selectRollbackTarget把 Latest 从坏版本重指向目标版本把坏版本降级为 prerelease资产与 tag 保留——这同时把版本从 den-api 的运行时发布列表移除org 安装与更新门禁在缓存窗口内停止提供它在坏版本 release notes 前置回滚横幅 ⚠️ Rolled back on date. Do not install; use target instead.rollback.mjs#L120-L123重复执行幂等hasRollbackBanner检测已存在横幅。第 2 步为已更新客户端重新发布Updater 拒绝降级。把最后 good 提交打一个高于坏版本的 tag 即可——无需提交、无需 worktreegit tag vX.Y.Z1 last-good-tag git push origin vX.Y.Z1第 3 步deprecate npmnpm deprecate openwork-serverbad-version rolled back — use next客户端状态恢复手段尚未更新第 1 步即可修复已更新只有第 2 步能修复撤销出问题的 PR 走dev上的正常评审 PR 流程该清理不在用户恢复的关键路径上。版本信息速查问题答案存在哪些版本git tag --list v*/ GitHub Releases最新版本gh release view --json tagNamevX.Y.Z 是哪个提交git rev-parse vX.Y.Z当前 checkout 是什么版本git describe --tagspackage.json 故意显示0.0.0-dev受支持的最老桌面版本MIN_SUPPORTED_DESKTOP_VERSIONgenerate-desktop-versions.mjs 中的提交策略唯一的例外pull-only 评估栈packaging/docker/docker-compose.eval.yml 按versiondigestpin 了 den-api 与 den-web 镜像。在Publish EE Artifacts推送稳定 tag 镜像后用 pin-compose-images.mjs 更新 pin含 docs 提交 sha 校验和check-compose-pins.mjs 在 tag 存在后校验{ok:true,...}——pin PR 与 changelog PR 一样跟随发布不属于切版本本身。Troubleshooting 速查表症状原因修复运行在推送 tag 时失败diff-warden app 不在v*ruleset bypass 名单或其 secrets 未设置重新添加 appSettings → Rules/ 恢复WARDEN_APP_IDWARDEN_PRIVATE_KEY或 admin 手动 push tag 后重跑全新 cut 报Tag vX.Y.Z already exists版本已发布用-f tagvX.Y.Zrecovery重跑或选更高版本verify-release单调性失败手动 tag 低于已存在 release选择高于当前最高稳定 tag 的版本release:review占位符检查失败有人把真实版本提交进了 package.json恢复0.0.0-dev——CI 从 tag 盖章版本桌面应用对新版本 updater 404tag 存在但 release 仍是运行中的 draft等待Publish GitHub Release自愈仅 AUR / Daytona 标红外部渠道故障release 照常发布渠道恢复后用同一 tag 重跑全部electron-linux-*编译原生模块失败原生模块需适配新 Electron 头文件raw-V8全 workspace 的原生依赖收敛到同一个基于 N-API 的大版本见 #3561/#3563 的教训Electron 35→43 升级时apps/server停在 better-sqlite3 v12 而 desktop 已到 v13electron-builder 会重建找到的每一份原生模块副本导致三次发布标红最终收敛到 v13 并用bun:sqlite解决Windows afterPack 报Missing staged MCP runtime packageasar 路径分隔符不匹配已修复——normalizeAsarEntryPathelectron-after-pack.cjs发布成功后的最后一道关validate-a-release资产公开后、对外宣布版本安全可铺开之前运行 .opencode/skills/validate-a-release/SKILL.md 技能用已发布 mac-arm64 zip 启动 enterprise 与 cloud 二进制覆盖packaged-first-launch全新安装与released-enterprise-activated激活安装、旧版本 profile 被新构建打开等场景核对 updater manifest 的 sha512并验证签名/notarization。历史演进为什么是现在这套设计2026-08发布变成 commit-free——tag 是唯一版本来源CI 盖章工作区den-api 运行时读取已发布 releaseAUR 渲染已提交模板。此前每次发布都需要版本 bump 提交、dev backfill PR 和 AUR 打包 PR。2026-08-05v0.18.15/v0.18.16Electron 35→43 升级引发三次发布标红根源是原生依赖版本分裂最终通过 workspace 收敛统一 N-API 大版本并让opencode-db在 Bun 下使用bun:sqlite解决。这套 tag 驱动的设计把发版收敛为一个不可变的 tag 一条可观测的 CI 管线版本语义由versions.mjs单点计算发布完整性由verify-tag.mjs与review.mjs --strict把关公开与否由publish-release一个作业决定回滚则是重指 Latest 降级 横幅三个 gh 调用。理解这条链路就能在 OpenWork 上安全地执行从 patch 到回滚的每一次发布操作。【免费下载链接】openworkThe open-source alternative to Claude Cowork (powered by opencode)项目地址: https://gitcode.com/GitHub_Trending/ope/openwork创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
