ZeroClaw 发布操作手册从 CHANGELOG 到版本化文档的七步稳定发布实战指南【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclawZeroClaw 是一个跨平台的 AI 个人助手基础设施项目其稳定版本发布目前仍由维护者通过release-stable-manual.yml工作流手工驱动。本文是发布 Runbookdocs/book/src/maintainers/release-runbook.md的完整技术指南你将从零走完「生成 CHANGELOG → 版本号 PR → act 本地预演 → 手动触发 → 审批环境门禁 → 验证产物 → 部署版本化文档」的七步全流程并理解每一步背后的脚本、工作流与 CI 门禁实现从而具备独立裁剪一次 ZeroClaw 稳定版的能力。本文以仓库当前真实状态为准发布流程验证于v0.8.2发布周期仓库当前版本为v0.8.5见 Cargo.toml 的[workspace.package] version与 docs/book/stable-version.txt。这是一个过渡期人工流程在 release-plz 落地并取代它之前该迁移尚未发生它仍然是事实上的线上发布过程。如果流程中的某些环节显得笨重那是刻意保留的摩擦——团队还没有足够的自动化纪律去安全地移除它。一、整体流程七步概览整个稳定发布过程可以压缩为七个步骤其余一切crates.io、Docker、网站重新部署、Scoop、AUR、Discord、推文都在发布成功之后作为下游作业自动运行使用 changelog skill 生成CHANGELOG-next.md打开并合并版本号 PR用act在本地预演发布工作流通过手动调度触发Release Stable工作流按提示审批两个环境门禁验证发布存在且产物可下载版本化文档部署Homebrew Core 通过其自身的 autobump 服务检测稳定版 GitHub Release无需维护者做任何事——除非某个作业显式失败或 Homebrew 的外部 bump 长期停滞。Step 1生成 CHANGELOG-next.md第一步是运行changelog-generationskill 产出CHANGELOG-next.md其完整流程定义在.claude/skills/changelog-generation/SKILL.md。该 skill 的工作方式从上一次稳定 tag 到 HEAD 之间的 git log 生成 changelog通过 GitHub GraphQL 解析贡献者将结果写入CHANGELOG-next.md。产物处理有两种方式直接把结果提交到短生命周期分支并纳入步骤 2 的版本号 PR如果 diff 过大也可以先开一个独立的 PR。如果CHANGELOG-next.md已从上一次中止的发布周期残留先复核其准确性再复用。## In brief章节是公告的必需输入文件在序言之后必须携带## In brief章节两段短文字合计至多 255 个字符说明本次发布是什么。XTwitter和 Discord 公告工作流会发布这一章节后面紧跟序言中的提交数与贡献者数以及网站发布帖的链接尚无发布帖时退化为 GitHub Release 链接。缺少它时公告会回退到 Highlights 的首批条目再缺则回退到原始提交列表。发布前可以无副作用地预览任一已发布 tag 的公告文案gh workflow run tweet-release.yml -f release_tagvX.Y.Z -f dry_runtrue gh workflow run discord-release.yml -f release_tagvX.Y.Z -f dry_runtrue合成后的文案会出现在该次运行的 job summary 中。仓库当前 CHANGELOG-next.md 即为v0.8.5的待发布 changelog开头即包含 ZeroClaw v0.8.5 is a security, connectivity, and operator-experience release spanning454 commitsfrom73 contributors 这样的序言与 8 条 Highlights可作为格式参考。Step 2版本号 PRbump-version2.1 同步全仓库版本引用先在 workspace 根 Cargo.toml 中提升workspace.package.version然后按顺序运行两个发布脚本。首先同步全仓库的版本引用./scripts/release/bump-version.sh # version from Cargo.tomlscripts/release/bump-version.sh 是这一步的核心它从Cargo.toml读取版本也可用显式参数./scripts/release/bump-version.sh 0.7.0覆盖校验 semver 格式随后以bump()辅助函数对每个目标文件做正则替换。从源码看它覆盖的面非常广README 版本徽章更新README.md与docs/i18n/*/README.md中的version-vX.Y.Z-blue徽章Tauri 桌面端配置用jq或 sed 回退更新 apps/tauri/tauri.conf.json 的version字段Windows 安装器同步setup.bat的VERSION与RUST_MIN_VERSION后者取自Cargo.toml的[workspace.package] rust-version两个变量分别用sed独立更新Workspace Cargo.toml提升[workspace.package] version所有子 crate 通过version.workspace true继承并同步[workspace.dependencies]中所有path crates|apps/...依赖的版本钉——脚本注释明确指出漏掉 apps/ 下的 pin 会让 lockfile 无法解析、在 bump 中途破坏cargo metadataCargo.lockcargo update --workspace仅重解析 workspace 成员条目Marketplace 模板Dokploy 的meta-entry.json与 docker-compose 镜像 tag、EasyPanel 的meta.yaml镜像 tag工作流描述示例discord-release.yml的示例 tag、publish-crates.sh的--execute断言版本文档书示例扫描docs/book/src/**/*.md只替换两种锚定模式——容器镜像 tagzeroclawlabs/zeroclaw:vX.Y.Z与/health响应示例中的version:X.Y.Z/ RPC 握手中的serverVersion:X.Y.Z兼容紧凑与带空格的 JSON 两种风格历史版本叙述文本被刻意跳过Docs 稳定指针把vX.Y.Z写入 docs/book/stable-version.txt这是「哪个已部署文档版本是 Stable」的唯一事实来源Nix git 依赖哈希通过 scripts/dev/refresh-nix-hashes.sh 刷新nix/hashes.json缺nix-prefetch-git/jq时优雅跳过生成的安装面运行cargo generate installers重新生成install.sh、setup.bat、dist/aur/PKGBUILD、dist/aur/.SRCINFO、dist/scoop/zeroclaw.json、flake.nix、Dockerfile/Containerfile 特性集、dev/ci/docker-tags.toml、docs/book/src/_snippets/install.md、README/platform 文档中的 Unix 快速路径块以及docs/book/src/setup/windows.md的 Windows 预编译块。关键设计版本、特性与应用打包值全部来自Cargo.toml与[package.metadata.zeroclaw]四个稳定安装路由来自xtask/src/generate/spec.rs中的类型化契约。永远不要手工编辑生成区域——CI 的 Installer Drift 门禁会在生成面与 spec 不同步时让 PR 失败漏掉一次重新生成就无法合入。2.2 刷新并钉住翻译目录bump-version.sh设置发布版本后刷新文档翻译目录并钉到对应 tag。如果目录是分开准备的先在 cut tag 之前检查覆盖率并校验cargo mdbook stats cargo mdbook check然后运行发布包装脚本./scripts/release/refresh-translations.sh --model-provider anthropic.releasescripts/release/refresh-translations.sh 从Cargo.toml读取版本无手工输入然后依次完成若docs/book/po子模块未检出则自动初始化git submodule update --init docs/book/po校验工作区目录基于子模块当前origin/maindirty 且 head 不一致时直接报错退出检查本地与远端均不存在v{version}tag存在则报错拒绝运行cargo mdbook sync --model-provider alias执行翻译随后cargo mdbook check校验--no-translate可跳过翻译提交并推送目录到zeroclaw-labs/zeroclaw-docs-translations子模块的main在子模块 cutv{version}tag 并推送检出该 tag把主仓库 gitlink 钉到该 tag 并git add docs/book/po。要求显式传入--model-provider别名使发布不依赖硬编码后端别名从providers.models.kind.alias解析。需要覆盖Cargo.toml默认版本时可在--model-provider前传显式版本./scripts/release/refresh-translations.sh 0.8.2 --model-provider anthropic.release关于docs/book/po子模块与cargo mdbook sync的 extract → merge → AI-fill 三段管线详见 Docs Translations。2.3 提交、PR 与门禁把一切提交在一起提交信息为chore: bump version to vX.Y.Z如果 PR 同时改动[workspace.package] rust-version或钉住的 Rust 工具链要把它当作兼容性变更而非纯发布管道改动PR 应写明新的 MSRV、解释源码构建升级路径并证明 CI、Docker、安装器与生成面在新下限上达成一致再合入。打开 PR 后打标签type:ci、size:XS以及 PR labeler 自动添加的路径标签若提升工具链下限追加risk:high并走 lane D需要两位独立 Core Team 成员审批CI 全绿才合入CI 的Installer Drift门禁在生成面与 spec 失同步时使 PR 失败Validate Translations Pin门禁会解析钉住提交处的子模块并校验目录格式与 msgid 一致性——坏 pin 也无法合入。确认合入正确落地git fetch origin git show origin/master:Cargo.toml | grep ^version # Must show: version X.Y.ZStep 3用 act 本地预演发布工作流Release Stable是一个 GitHub Actions 作业图在你点击 Run workflow 的那一刻就开始消耗环境门禁的审批窗口。如果某个工作流步骤坏了缺少构建产物、陈旧路径、有人删了 codegen 步骤却没更新 CI故障会在你已承诺发布窗口、版本 PR 已合入、master 已处于新版本号之后才浮出水面——恢复意味着要紧急修分支、重跑 CI、在一棵已自我宣告为「完整发布版本」的树上赶时间发布。廉价的保险是在打开 GitHub Actions 表单之前先在精确的已合入 master commit上本地跑同一作业图。actnektosact在 Docker 容器内执行 GitHub Actions 工作流使用与 GitHub 相同的actions/*生态。它无法完美镜像云端 runner无法触达 artifact 上传运行时、GitHub 签发的 OIDC token、环境 secret或依赖真实发布 tag 的作业但它能跑那些覆盖了我们历史上几乎所有发布期 CI 故障的构建与测试步骤。这一步每次发布投入 15–20 分钟且确实抓到过常规 per-PR CI 发现不了的真实缺陷因为出故障的工作流只在workflow_dispatch上跑push不触发。3.1 一次性安装act运行工作流。最干净的安装路径是 GitHub CLI 扩展因为它继承你的gh认证并把真实GITHUB_TOKEN暴露给每次工作流运行从 https://cli.github.com 安装 GitHub CLILinux/macOS/Windows认证一次gh auth login。安装act扩展gh extension install nektos/gh-actartifact 兼容性红线产出 artifact 的作业需要act实现actions/upload-artifactv7 与actions/download-artifactv8 所要求的 artifact-service 协议而目前没有任何已发布的 act 版本实现它。助手脚本会在启动使用钉住 artifact actions 的作业前预检已装act版本并 fail-closed在未验证版本上不会尝试该作业。在兼容的act版本发布并通过真实 artifact 往返验证之前artifact 相关作业一律走下面的 GitHub 托管兜底路径——这是当前推荐路径而非罕见例外。从 https://docs.docker.com/engine/install/ 安装 Docker Engine 或 Docker Desktop。Linux 上把自己加入docker组以避免sudo。act也兼容 Podman 与 Colima。就这些。仓库的.actrc与 scripts/dev/act-local.sh 处理其余一切runner 镜像、secrets 文件、artifact server、action SHA 预取。3.2 每次发布的预演确保工作树与步骤 2 的已合入 master 尖端一致git fetch upstream git checkout upstream/master列出所有工作流文件中可运行的作业./scripts/dev/act-local.sh --list运行单个作业、交互选择或运行全部可安全预演的作业./scripts/dev/act-local.sh release-stable-manual:web # one job ./scripts/dev/act-local.sh # interactive picker ./scripts/dev/act-local.sh --all # every dry-run-safe job首次运行会拉取 runner 镜像约 1.5 GB并通过Swatinem/rust-cache预热 Rust 构建缓存之后快得多。脚本自动创建 gitignored 的.secrets文件、把每个钉住的 action SHA 预取进~/.cache/act/act 的浅克隆无法解析任意 commit、通过父进程环境把gh认证的GITHUB_TOKEN传入运行token 值从不进入 argv、并设置--artifact-server-path让actions/upload-artifact与actions/download-artifact能在作业间工作。底层全是普通act脚本只是去掉了 flag 汤。从 scripts/dev/act-local.sh 源码可见其工程细节GoGitActionCache--use-new-action-cache选择 act 的 GoGitActionCache唯一能解析非 tip 钉住 SHA 的后端默认磁盘缓存做浅克隆并在这些 SHA 上 400 报错--action-offline-mode在--all扫描中复用已缓存 action版本自动推导若工作流有version:的workflow_dispatch输入自动从Cargo.toml的[workspace.package] version推导并作为--input version...传入artifact 兼容预检preflight_artifact_service解析已发布 act 版本并与内部阈值ACT_ARTIFACT_MIN_VERSION999.0.0比较——这是一个不可达哨兵不是让你去安装的版本没有任何已发布 act 版本满足它只有在对某个版本完成真实 artifact 往返验证后才会降为具体版本号。因此任何 artifact 产出或消费作业在构建开始前就会预检失败并指向 GitHub 托管 Actions——不要降级钉住的 artifact actions 来让本地 runner 通过。对于--all兼容性会在第一个作业启动前跨完整选中作业集检查任一选中作业需要 artifact 服务则整体 fail-closed 退出绝不跑部分子集。本地 artifact 预检失败是当前每个已发布 act 上的预期行为不是偶发故障。把精确 commit 推上 GitHub用托管工作流作为 artifact 承载作业的验证兜底。只读的跨平台构建可以安全调度并从 CLI 观察gh workflow run cross-platform-build-manual.yml --ref validation-branch gh run list --workflow cross-platform-build-manual.yml --branch validation-branch --limit 1 gh run watch run-id --exit-status不要提前触发release-stable-manual.yml作为 dry-run 替代品——该工作流在环境审批后会真正发布。本地 artifact 作业记为因版本策略跳过用托管跨平台构建做 artifact 往返把受保护的 stable-release 运行留给 Step 4。3.3--all只运行 dry-run-safe 白名单上的作业act不遵守 GitHub 的环境保护门禁。当维护者的真实GITHUB_TOKEN被传入运行一个向 GitHub 写入的作业本地成功调用gh release create的publish、推送 GHCR 的docker作业、force-pushgh-pages的docs-deploy、开 issue 的daily-audit、发 webhook 的tweet-release/discord-release可能在第一次尝试时就执行了真实副作用。因此--all强制一份硬编码白名单只跑已被证明本地安全的作业——目前是release-stable-manual.yml与cross-platform-build-manual.yml中的纯 artifact 构建步骤validate、web、release-notes、build、build-desktop。其余全部跳过并记录原因 skip release-stable-manual:publish (not on dry-run-safe allowlist) skip release-stable-manual:docker (not on dry-run-safe allowlist) skip release-stable-manual:crates (not on dry-run-safe allowlist) skip release-stable-manual:redeploy-website (not on dry-run-safe allowlist) skip docs-deploy:deploy (not on dry-run-safe allowlist) skip daily-audit:advisories (not on dry-run-safe allowlist) skip tweet-release:tweet (not on dry-run-safe allowlist)白名单是fail-closed的仓库新增的工作流在维护者审阅并将其安全作业 ID 加入scripts/dev/act-local.sh的DRY_RUN_SAFE_JOBS之前一律视为潜在可变。这很重要因为discover_jobs遍历的是.github/workflows/*.yml下的所有工作流而非仅发布工作流denylist 会让未来的写入面工作流悄悄溜过。两个逃生口用于确有理由本地尝试非白名单作业的罕见情况./scripts/dev/act-local.sh release-stable-manual:publish显式wf:job形式运行你指定的作业若目标不在白名单上调用act前会打印响亮的警告./scripts/dev/act-local.sh --all --no-allowlist为整个--all运行关闭白名单过滤仅当你已验证工作流步骤不会触达变更面时使用例如在无真实注册表凭据、.secrets文件为空的 fork 上。3.4 在 act 下预期失败且无妨的部分act无法模拟几个 GitHub 专属表面这些失败不是真实缺陷依赖真实发布 tag 的作业publish创建 GitHub Release环境门禁作业publish、docker与 crates 发布器本地不存在审批 UIOIDC 联邦身份 token。其余一切——tsc错误、缺文件、Rust 编译失败、cargolockfile 不匹配——都是真实缺陷。在通过标准 PR基于 master修复这些之前不要在 GitHub Actions 表单上点击 Run workflow。Step 4触发 Release Stable 工作流前往 Release Stable 工作流页面点击Run workflow填写Branch:masterStable version to release:X.Y.Z不带v前缀第一个作业validate检查版本与Cargo.toml一致、且vX.Y.Ztag 尚不存在。若失败修复不匹配后重新触发不要试图绕过它。Step 5审批环境门禁三个作业受 GitHub 环境保护规则门控。各自进入 pending 时工作流运行中会出现Waiting for review横幅。三个都出现后逐一审批仅当crates-io的无 token 包预检通过后才审批它环境作业作用github-releasespublish创建 GitHub Release 并上传产物dockerdocker推送镜像到 GHCRcrates-iocrates / Publish to crates.io按依赖顺序发布已验证的 23-crate workspace错过审批窗口导致作业超时时只需从工作流运行页重跑失败的作业无需从头重启。Step 6验证发布产物publish完成后逐项确认[ ] GitHub Release 存在于 /releases/tag/vX.Y.Z 且标记为 Latest [ ] Release notes 非空 [ ] SHA256SUMS 产物存在且非空 [ ] SPDX 与 CycloneDX 两份 SBOM 产物均存在 [ ] 恰好一个 zeroclaw-vX.Y.Z-verification.tar.gz 产物存在 [ ] 无松散的 *.bundle、*.attestation.jsonl 或 *.intoto.jsonl 产物 [ ] 至少一个二进制归档可下载抽查 linux x86_64 [ ] 预编译 Docker 与生成的 Docker matrix 作业全绿CHANGELOG-next.md在发布后刻意留在 master 上publish作业只把它当作 release body 读取不会删除它。下一个发布周期会覆盖它无需手工清理。对于常规workflow_dispatch路径Docker Publish 在 stable release 工作流内部同步运行全部发布作业变绿即无需单独检查 Docker。若维护者改为推送vX.Y.Ztag 启动发布Docker Publish 会作为独立的 tag 触发运行启动——在把容器发布视为完成前先确认那个兄弟运行是绿的。crates.io、Scoop、AUR 只有在各自作业变红时才需单独关注。Homebrew Core 在此工作流之外其 autobump 服务按自己的节奏检查符合条件的分支公式。需要验证签名、SBOM 或 SLSA 来源的消费者可参考 Release artifact verification可下载产物使用 GitHub 托管的 Build Level 2 认证记录产物摘要、源 commit 与发布工作流身份支持gh attestation verify在线验证也支持通过zeroclaw-vX.Y.Z-verification.tar.gz归档内含artifact.attestation.jsonl包、trusted_root.jsonl与ATTESTATION-BUNDLES.md索引做断网验证另有zeroclaw-vX.Y.Z-sbom.spdx.json/-sbom.cdx.json两份 SBOM 与 cosign 签名的 GHCR 镜像。此外任何发布认证工作流变更之后人工维护者必须在关闭跟踪 issue 前运行 docs/maintainers/release-attestation-runbook.md 中的在线与断网验证演练。本地工作流 lint 或act运行不能替代这一发布级检查——两者都无法铸造 GitHub 的生产 OIDC 认证。Step 7版本化文档部署ZeroClaw 文档在gh-pages分支上使用版本化结构。Release Stable工作流的deploy-docs作业在publish成功后为发布 tag 调度Deploy mdBook docs to Pages工作流被调度的运行异步构建并发布该版本文档到/vX.Y.Z/调度作业不等待它。为什么是显式调度而不是 tag-push 触发器。docs-deploy.yml声明了tags: [v*]但发布 tag 是publish作业通过gh release create用GITHUB_TOKEN创建的。GitHub 不会为用GITHUB_TOKEN创建的 tag push 启动新的工作流运行所以tags: [v*]触发器对这种方式 cut 的发布永不触发。deploy-docs作业因此通过workflow_dispatch在GITHUB_TOKEN下也运行的文档化例外以 tag 为输入调用docs-deploy.yml。若未来用手持个人 token 手工 cut tagtags: [v*]push 触发器会触发发布工作流的调度成为同一部署的无操作重跑两条路径收敛于/vX.Y.Z/。自动发生的事deploy-docs作业调度一个落在/vX.Y.Z/的构建。Stable 是指针不是副本。发布 tag 部署如v0.8.0才构建并发布该版本的文档目录。bump-version.sh把发布版本写入docs/book/stable-version.txt该变更落在 master 上只刷新 stable 元数据。master 部署不会重建或重新发布 release tag 的文档它把stable-version.txt复制到gh-pages根并重新生成根/重定向与版本选择器的 Stable (latest release) 条目让两者解析到该发布已经发布的版本目录。若所指版本目录不在gh-pages上部署会大声失败。不存在重复的/stable/树。顺序至关重要tag 部署必须先让/vX.Y.Z/出现在gh-pages上master 部署才能把 stable 指针翻到它。常规发布序列中版本号 PR 先合入Step 2所以它的 master 文档部署通常先于Release Stable创建并部署 tag。那次较早的 master 部署发现/vX.Y.Z/不存在会刻意保留旧指针翻转被推迟见docs-deploy.yml的 deferred-flip 逻辑。deploy-docs作业随后创建/vX.Y.Z/翻转在目录上线后的下一次master 部署上发布。注意deploy-docs只调度 tag 构建而不等待它绿色的deploy-docs作业只代表调度被接受不代表文档运行结束。/vX.Y.Z/上线后用tagmaster调度docs-deploy.yml来发布 stable 指针翻转并在 Actions 页确认被调度的运行确实成功。gh-pages是临时的每次部署 force-push 单个孤儿 commit无累积历史通过DOCS_KEEP_VERSIONSmaster 加上最新的 N 个正式版预发布与更旧的正式版被裁剪执行保留策略控制克隆体积。_shared/目录UI CSS、JS 与 favicon随构建更新主题会级联到所有已部署版本。翻译 localees、fr、ja、zh-CN从docs/book/po子模块渲染部署通过submodules: recursive解析已部署 ref 钉住的任意 commit。该 pin 在版本号 bump 时设置见 Step 2 的刷新、tag、pin 流程。英文不需要子模块。引导gh-pages若gh-pages被删除或需完全重建按此顺序播种版本最旧的支持发布workflow_dispatchtagv0.7.5后续发布workflow_dispatchtagv0.8.0-beta-1等当前 masterworkflow_dispatchtagmaster重要引导期间master必须最后部署。它写入所有其他版本使用的权威_shared/chrome 层。注意Stable 由docs/book/stable-version.txt源码中提交、发布到 gh-pages 根的stable-version.txt解析。引导后确认该文件指向预期的 GA 发布根重定向与 Stable (latest release) 选择器条目跟随它。不创建/stable/目录。手动重新部署与版本下限手动重新部署特定版本前往Actions→Deploy mdBook docs to Pages点击Run workflow输入 tag如v0.7.5或masterDOCS_MIN_VERSION下限为防止意外部署很旧或不支持的版本工作流强制最小版本下限当前v0.7.5。早于DOCS_MIN_VERSION的 tag如v0.7.4被工作流拒绝。cargo mdbook gen-versionsxtask 助手忽略gh-pages上低于该下限的任何目录使其不出现在版本下拉框中。需要抬高下限以放弃旧版本支持时更新.github/workflows/docs-deploy.yml中的DOCS_MIN_VERSION环境变量。旧版本目录会在下次部署时被DOCS_KEEP_VERSIONS保留清理自动裁剪无需手工编辑gh-pages回收空间。出问题怎么办故障排查速查表运行瞬间死于startup_failure零作业创建把它当作症状而非白名单诊断。检查运行摘要与仓库 Actions 策略。若 GitHub 报告 selected-actions 拒绝且发布工作流最近增改过uses:refs把这些 refs 与 Allowed actions 对比在 Settings → Actions → General 只添加被拒的模式等设置传播几分钟再调度一次全新运行。若 GitHub 未报告策略拒绝则调查工作流定义或其他仓库策略。validate 失败版本不匹配版本号 PR 未合入或输入了错误版本。修复不匹配后重新触发。环境门禁超时只重跑超时的作业无需重启工作流。Scoop 或 AUR 分发作业失败各自有对应的手动可触发子工作流。先用dry_run: true重跑对应子工作流确认修复再dry_run: false。这些是锦上添花分发作业失败不使发布本身失效。Scoop 凭据失败时用 Scoop Bucket Canary 而非把通用 dry run 当作凭据证明canary 启用 fail-closed 的credential_canary路径。crates.io 发布器上传部分 crate 后停止不要提升版本或开始第二次发布。crates.io 版本无法替换或删除。在同一发布 commit 修复失败 crate然后用dry_run: false对同一 tag 重跑Pub crates.io发布器先查询每个crateversion并跳过已落地的版本。读取最后一个成功 crate 的 Publish 步骤。若预检失败则未尝试任何上传问题仍可逆。scoop作业报remote: Permission ... denied to account(403)是权限问题而非 manifest 问题bucket token 失效或权限不足。按 RotatingSCOOP_BUCKET_TOKEN轮换 token然后调度 Scoop Bucket Canary 确认修复不写入 bucket。用dry_run: false重跑 Scoop 发布器并确认 bucket 落地新版本。Bucket 侧 Excavator 恢复仍待定依赖zeroclaw-labs/scoop-zeroclaw#1、仓库工作流写权限与维护者冒烟测试在这些步骤完成前不要指望它修复发布。每周Scoop Bucket Canary变红token 过期或失去写权限。同一轮换路径。在下次发布前修复。Homebrew Core 停滞Homebrew 不是发布工作流作业。查阅 Homebrew autobump 状态与文档化手动 bump 路径而不是添加仓库 fork token。AUR 作业报The AUR is down due to maintenance上游故障而非凭据问题。若日志在SSH key diagnostics下显示 key 指纹、失败来自服务器而非 SSH则AUR_SSH_KEY无恙。发布器在约七分钟内重试五次硬作业超时。每次尝试重克隆当前包若另一运行已发布更新版本则停止而非降级。到达维护错误意味着故障窗口超过了重试预算。等待aur.archlinux.org恢复然后在发布 tag 上重新调度 Pub AUR Package先dry_run: true再dry_run: false。用curl -fsS https://aur.archlinux.org/rpc/v5/info?arg%5B%5Dzeroclawlabs确认结果或直接调度 AUR Freshness Check。跳过此步会让 AUR 静默落后直到每周检查发现它。AUR 比刻意回滚的稳定发布更新验证回滚 tag 与包内容。若已发布包含有回滚 tag 不含的非零epoch不要重新调度旧 tag发布元数据来自不可变 tag默认分支编辑无法改变该运行。改为准备一个包含回滚代码的前向编号稳定发布在dist/aur/PKGBUILD添加匹配的epoch赋值运行cargo generate installers重新生成dist/aur/.SRCINFO审阅两个文件合入并 cut 新发布 tag。新鲜度检查在 tag 发布前保持红色。绝不用allow_downgrade跨越 epoch 边界。同一 epoch 内回滚时手动 Pub AUR Package 工作流先跑一次dry_run: true验证元数据生成与版本守卫的目标侧再以dry_run: false和allow_downgrade: true运行。非 dry-run 守卫额外比较新鲜 AUR 克隆。该覆盖只存在于手动调度可复用接口不声明该输入因此无法请求它。绝不用它绕过畸形 AUR 元数据或无法解释的版本不匹配。发布因同一版本包文件不同而停止发布器有意拒绝在现有epoch:pkgver-pkgrel元组上替换不同文件。检查 diff。授权 AUR 维护者必须恢复从该发布 tag 生成的规范 PKGBUILD 与.SRCINFO或合入修正的源码变更并在新稳定 tag 下发布。编辑默认分支并重新调度旧 tag 无效因为发布器从不可变 tag 读取元数据。发布报告当前 AUR 版本非数值或畸形自动化发布器有意 fail-closedallow_downgrade无法绕过畸形元数据。授权 AUR 维护者必须手工 AUR push 修复为良构的epoch:pkgver-pkgrel通过 AUR RPC 验证再重新调度正常发布器。不要削弱守卫来让畸形已发布状态可比较。被移除的遗留工作流.github/workflows/中若干此前存在的自动发布工作流已被删除因为它们绕过审阅或不可逆地发布。它们不再存在若在 PR 中再次出现视为回归并阻止工作流移除原因release-beta-on-push.yml每次推送到 master 都自动发布publish-crates-auto.yml任何版本变更自动发布到 crates.io不可逆version-sync.yml以 bot 身份直接提交 master绕过审阅checks-on-pr.yml重复 CI产生令人困惑的冲突状态pre-release-validate.yml未使用的生成清单本 runbook 取代了它剩余工作流自动与手动的完整清单见 CI Actions。其中与发布直接相关的关键条目包括Release Stablerelease-stable-manual.yml手动触发的完整发布管线——构建全部目标、创建 GitHub Release、推送预编译的latest/版本化/debianDocker 镜像到 GHCR、在 release tag 调用生成的 Docker 变体矩阵、触发网站重新部署、调用分发子工作流Scoop、AUR、Discord、推文。github-releases与docker两个环境门禁需要维护者中途审批crates-io环境还门控 crates 发布器Docker Publishdocker-publish.yml构建、签名、扫描dev/ci/docker-tags.toml生成的四变体矩阵minimal、default-features、dist、all-features人工v*tag 直接启动它而workflow_dispatch启动的稳定发布因其 tag 由GITHUB_TOKEN创建、不会触发 tag-push 事件由release-stable-manual.yml在不可变 release tag 上同步调用它Discord Release / Tweet Release稳定发布成功后分别发布公告Scoop Bucket Canary每周用dry_run: true加credential_canary: true预演 Scoop 发布路径检测SCOOP_BUCKET_TOKEN凭据腐化——它刻意不接入 Release Stable死掉的包管理器凭据绝不应阻塞或延迟发布AUR Freshness Check每周对比已发布zeroclawlabsAUR 版本与当前稳定 GitHub ReleaseAUR 落后则失败AUR RPC 不可达时警告并通过因为那是上游可用性问题而非包停滞。未来方向Runbook 是桥梁而非终点本 runbook 与release-stable-manual.yml是过渡方案不是目的地。目标终态release-plz 自动管理版本号提升与 changelog单个release.yml取代当前子工作流的拼凑SLSA 来源证明内建进管线团队通过合入一个发布 PR 来 cut 发布而不是遵循 runbook。在那一刻到来之前请使用本流程。你用本 runbook 手工 cut 的每一次发布都是为自动化最终需要做什么积累的实践依据。【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考