release-openclaw-nightly

Nightly 发布

用于 Tideclaw/OpenClaw alpha/nightly 发布自动化、手动 alpha 触发、beta 准备、发布分支修复以及发布后的向前移植。在使用 Tideclaw 主机路径、cron id 或 Discord 路由 id 之前，如果 $release-private 存在，请先加载它。

策略

• Alpha/nightly 每 12 小时运行一次，也可手动触发。
• Beta 由人工在 Discord 中触发，且必须基于已验证的 alpha/发布分支。
• Stable/latest 始终需要明确的人工确认。
• 绝不要从脏工作区或直接从 main 发布。
• Main 可能繁忙或损坏；alpha 工作必须隔离，以免 main 的临时故障阻塞可用的 nightly。
• 仅在发布分支验证通过后发布。
• Alpha 成功后，将发布分支的提交向前移植回 main，并验证 main CI 通过。
• 向前移植 PR 只能包含使 nightly/发布检查通过所需的可复用修复。不得包含 alpha 版本升级、发布说明、变更日志发布条目、标签、生成的构件或状态文件更新。
• 仅保留最近 3 天的 alpha/nightly 分支，以及任何存在活动运行、开放 PR 或发布标签的分支。
• 绝不运行大范围环境变量/令牌转储。在 Tideclaw 主机上进行 GitHub 写入操作时，请使用下方的 Tideclaw gh 写入包装器。
• 如果 alpha、beta 或修复分支需要发现或复用超出其固定基线的向后移植提交， 则在修改候选分支之前，完成下方的独立审计。 直接从当前固定的 origin/main 启动 alpha，本身不会触发向后移植审计。

审计 Nightly 向后移植

对于任何向后移植发现工作，固定确切的发布基线和源 main SHA。 从上次已接受的审计游标开始；如果没有，则从二者的合并基础开始。 列出所有不等效于补丁的源提交，对照已授权的公开和私有公告逐一核查，并在现有 alpha 状态文件中记录范围、数量、筛选条件、适用性结果、决策、排除项、依赖项和受阻事项。

标题只能作为信号，不能作为门槛。对完整清单进行分类，检查每个带有安全或可靠性信号的生产代码差异，并单独审查执行、身份验证、沙箱、网络、持久化、交付、网关、配置、插件和主要渠道路径中的常规 fix、perf 和 doctor 提交。对每个此类差异，在分离的基线工作树中机械地尝试应用，并记录结果是干净、冲突、为空/已涵盖，还是失败。补丁可干净应用只是分流证据，并不意味着自动向后移植。

还要在固定的源 SHA 上快照带有 maturity:stable 标签的 OpenClaw issue，并将标签查询时间与审计范围一并记录。对于所有带标签的 issue，无论开放还是已关闭，只要其修复 PR 或提交确实落在扫描范围内，就必须通过提交台账决策逐一核查；对于每个开放的 P0/P1 标签 issue，都必须明确给出已修复、不受影响、维护者延期或发布受阻的处置结论。仅将该标签视为完整性和优先级信号：验证其审查理由，将功能、新配置或策略、文档/支持以及较低成熟度的匹配项记录为 label-drift，绝不要仅凭标签推断修复已完成、向后移植已获批准或发布受阻。

对于每个拟议事项，检查完整变更、基线行为、调用方、被调用方、同类项、测试、依赖契约、安全影响和发布表面。将重叠或相互依赖的提交合并为最小的最终修复。除非维护者明确批准，否则排除功能、迁移、新配置或运行时要求，以及大范围重新设计。在更改候选分支之前，提交完整的分类集合供批准；随后在该状态文件中保留来源信息，运行有针对性的验证和发布验证，并且仅在规范分支/标签具有确切的最终版本和 SHA 后，才分派 npm 预检。

身份标识

Tideclaw 应在发布分支和前向移植分支上使用自身的机器身份提交：

git config user.name "Tideclaw"
git config user.email "[email protected]"

如果提交明确标识为机器生成且由 CI 把关，则有利于审计。避免直接推送到受保护的 main；除非仓库策略明确允许机器人在所有检查通过后推送，否则应通过 PR/automerge 进行前向移植。仅当人工提供了补丁或明确的提交文本时，才添加人工 Co-authored-by。

分支结构

• 分支前缀：tideclaw/alpha/
• 分支名称：tideclaw/alpha/YYYY-MM-DD-HHMMZ
• 基准：触发时当前的 origin/main SHA。
• 状态文件：在 Tideclaw 主机上从 $release-private 解析。
• 发布标签：vYYYY.M.PATCH-alpha.N
• npm 分发标签：alpha

PATCH 是按月递增的发布列车编号，绝不使用日历日期。根据 stable 和 beta 发布确定 alpha 发布列车；选择下一个发布列车时，忽略 alpha 专用补丁号。使用比当月最高 stable/beta 补丁号大 1 的编号，然后在该发布列车上重复运行夜间构建时，仅递增 alpha.N。如果下一个补丁号已有 beta，则将 alpha 移至下一个发布列车。补丁号虚高的旧版 alpha 专用标签不会推进 beta/stable 编号。

新运行时不要复用旧的 alpha 分支。如果基于同一基准 SHA 重新运行，请创建新的带时间戳分支并记录原因。

启动

1. 在 Tideclaw 主机上，从 $release-private 检出的工作目录中操作。
2. 先拉取：

git fetch origin main --tags --prune
git switch main
git merge --ff-only origin/main
BASE_SHA="$(git rev-parse origin/main)"
BRANCH="tideclaw/alpha/$(date -u +%Y-%m-%d-%H%MZ)"
git switch -c "$BRANCH" "$BASE_SHA"

3. 更改任何内容前，先阅读仓库的发布文档/脚本：
   • AGENTS.md
   • docs/ 下的发布文档
   • scripts/ 下的发布脚本
   • .github/workflows/*release*
4. 将 $BASE_SHA 与最近一次成功的 alpha 状态以及当前的 git/npm/GitHub alpha 标签进行比较。如果已经发布，则报告跳过且不要发布。

手动触发：

CRON_ID="<from release-private>"
OPENCLAW_ALLOW_ROOT=1 openclaw cron run "$CRON_ID" --expect-final --timeout 21600000

Discord Alpha 触发

当维护者在 #releases 或 #maintainers 中提及 Tideclaw 时，Tideclaw 可以通过 Discord 立即运行 alpha。

可接受的形式：

@Tideclaw run alpha now
@Tideclaw alpha release from main now
@Tideclaw trigger alpha

规则：

1. 将其视为与 alpha 定时作业等效的手动 alpha 触发。
2. 从当前 origin/main 开始，并创建全新的 tideclaw/alpha/YYYY-MM-DD-HHMMZ 分支。
3. 遵循常规 alpha 工作流：复用先前的修复，运行本地检查，在 alpha 分支上修复，运行发布 CI，在所有质量门禁通过后发布 alpha，然后通过仅含修复的 PR 前向移植可复用的修复。
4. 如果另一个 alpha/beta/stable 发布运行已经进行中，请报告活动分支/运行并停止。
5. #maintainers 触发必须明确提及 Tideclaw；不要响应其中未提及 Tideclaw 的发布讨论。
6. 从 $release-private 解析 Discord 角色/用户 ID 和线上主机热修复说明。

Discord Beta 触发条件

只有在维护者发送明确的 beta 触发指令时，Tideclaw 才可依据 #releases 或所提及的 #maintainers 命令运行 beta 发布。将其视为对 beta 的人工批准，而非对稳定版或最新版的批准。

可接受的形式：

@Tideclaw beta release from vYYYY.M.PATCH-alpha.N
@Tideclaw beta release from tideclaw/alpha/YYYY-MM-DD-HHMMZ
@Tideclaw beta release from latest proven alpha

规则：

1. 必须包含 beta release 一词以及源 alpha 标签/分支，或 latest proven alpha。
2. 如果源不明确，请在 #releases 中提出一个澄清问题，然后停止。
3. 首先验证源 alpha：GitHub 发布、npm alpha 包、发布 CI、已记录的状态文件，以及分支/标签 SHA。
4. 从已验证的 alpha 源创建全新的 beta 分支 tideclaw/beta/YYYY-MM-DD-HHMMZ，不要直接从持续变动的 main 创建。
5. 仅复用或压缩已经在 alpha 上得到验证的稳定性修复。除非 beta 发布文档要求，否则不要导入无关的 alpha 发布机制。
6. 将 beta 计算为 vYYYY.M.PATCH-beta.N，与 npm --tag beta 匹配。选择 beta 发布序列时，忽略 alpha 专用的补丁号。
7. 运行 beta 发布验证、预检和完整发布 CI，并在 beta 分支上修复失败项。
8. 只有在所有 beta 门禁均通过后才发布 beta。使用 GitHub Actions/OIDC，绝不要从主机直接执行 npm publish。
9. 最终的 Discord 摘要必须包含源 alpha、beta 标签/版本、分支、修复提交、工作流运行 ID、npm/GitHub 证据，以及任何跳过或受阻的原因。
10. beta 发布后，使用下述仅包含修复的 PR 规则，将可复用的修复前向移植到 main。

复用之前的修复

运行检查之前，从最近的 Tideclaw alpha 分支中查找以往发布尝试期间已经完成的修复：

1. 从 $release-private 读取 Tideclaw 状态文件，获取最后一次成功的 alpha 分支及修复提交 SHA。
2. 列出最近的远程分支：

git for-each-ref refs/remotes/origin/tideclaw/alpha --format='%(refname:short) %(committerdate:iso-strict)'

3. 仅考虑最近 3 天内的 Tideclaw alpha 分支，以及最后一次成功的 alpha 分支。
4. 对于每个候选分支，检查不在当前 origin/main 中的提交：

git log --no-merges --reverse --format='%H%x09%s' origin/main..origin/tideclaw/alpha/YYYY-MM-DD-HHMMZ

5. 仅 cherry-pick 确实有效且仍可应用于新 alpha 分支的稳定性修复。如果这是发现新修复，而不是复用状态文件中已经批准的 修复，则在选择前执行夜间回移审计； cherry-pick 无冲突或标题看似无害均不构成批准。优先 使用状态文件中记录为 fixCommitShas 的提交。
6. 跳过版本号递增、变更日志发布条目、标签产物、生成的发布说明、仅涉及状态文件的提交，以及一次性调试插桩。
7. 如果 cherry-pick 发生冲突，检查当前 main 是否已包含等效修复。如果没有，则进行最小化解决，并保持提交信息清晰。
8. 在 alpha 状态和最终 Discord 摘要中，将复用的提交 SHA 与新编写的修复提交 SHA 分开记录。

使用 git cherry、git range-diff 和定向测试重跑，避免重复应用 main 中已有的修复。

修复循环

将该分支用作发布候选版本的修复工作区：

1. 首先运行范围较窄的本地检查：改动涉及的测试、发布预检，以及发布文档要求的类型检查、代码规范检查和构建门禁。
2. 如果本地检查失败，则在 alpha 分支上修复，并使用最小化的提交。
3. 以 Tideclaw 身份提交每个逻辑完整的修复。
4. 每次修复后，重新运行失败的本地检查。
5. 除非发布文档明确要求且差异有充分依据，否则不要通过编辑基线、预期失败列表、忽略文件或发布清单来掩盖失败。
6. 如果失败是偶发问题，则重跑一次；如果仍然失败，则视为真实失败。
7. 如果修复明显对 main 有用，请保持小巧且易于前向移植。alpha 稳定期间避免大范围重构。

提交示例：

git add <files>
git commit -m "fix: stabilize alpha release preflight"
git push -u origin "$BRANCH"

发布 CI

本地验证完成后：

1. 根据现有 git 标签、npm 版本和 GitHub 发布记录计算下一个 vYYYY.M.PATCH-alpha.N。从稳定版/beta 发布线中选择 PATCH，而不是按日期或仅 alpha 补丁版本的最高值确定。沿用同一 alpha 发布线并递增 alpha.N，直至该补丁版本已有 beta；已有 beta 后，新的 alpha 构建应使用下一个补丁版本。
2. 使 alpha 分支的软件包版本和发布元数据与该标签一致，提交更改并推送分支。
3. 从 alpha 分支运行发布验证，使用 GitHub CLI，而不是浏览器/fetch 工具。在 Tideclaw 主机上，gh 本身是只读的 Codex 沙箱包装器；对于 workflow run、run cancel 和发布调度等可写命令，请使用 /usr/local/bin/gh-tideclaw-write：

GH="/usr/local/bin/gh-tideclaw-write"
SHA="$(git rev-parse HEAD)"
TAG="v$(node -p "require('./package.json').version")"
BRANCH="$(git branch --show-current)"
PUBLICATION_SELECTION='{"route":"alpha","npmDistTag":"alpha","publishOpenclawNpm":true,"pluginPublishScope":"all-publishable","plugins":[]}'
FRV_ENVELOPE="$(jq -cn --arg ref "$BRANCH" --arg sha "$SHA" \
  --argjson selection "$PUBLICATION_SELECTION" \
  '{trustedWorkflow:{ref:$ref,fullRef:("refs/heads/"+$ref),sha:$sha},validationPurpose:"publish",publicationSelection:$selection}')"

"$GH" workflow run full-release-validation.yml --repo openclaw/openclaw --ref "$BRANCH" \
  -f ref="$BRANCH" \
  -f expected_sha="$SHA" \
  -f trusted_workflow_json="$FRV_ENVELOPE" \
  -f release_profile=beta \
  -f rerun_group=all

"$GH" workflow run openclaw-npm-release.yml --repo openclaw/openclaw --ref "$BRANCH" \
  -f tag="$SHA" \
  -f preflight_only=true \
  -f npm_dist_tag=alpha

4. 使用 gh run list、gh run view 和 gh api 监控确切的工作流运行 ID 和头 SHA。轮询时可使用只读的 gh；仅当命令会修改 GitHub 时，才使用 $GH。不要使用 Codex 浏览器/fetch 工具来轮询 GitHub API；此前 Tideclaw 的运行在预检成功后因该方式失败。
5. 每个选定的验证任务失败时都会阻止 alpha 发布，包括跨操作系统、实时通道、QA Lab、软件包验收、Docker E2E 和 Telegram 软件包 E2E。报告实际结果，并在发布前解决选定任务中的失败。
   • 聚焦的完整发布验证组可用于针对完全相同的头提交和发布选择，诊断或刷新单个验证任务。聚焦的 install-smoke 运行成功也无法替代失败的 rerun_group=all 发布证据；发布前必须完成并封存所需的全组验证。
6. 如果选定的关卡失败，请在 alpha 分支上修复、推送，并重新运行失败项或所需的发布 CI。如果提交发生变化，则废弃旧的预检/完整验证运行 ID，并针对新的头提交重新运行。
7. 完整验证和 npm 预检在同一分支头提交上均通过后， 请审查 npm 预检的 Plugin SDK API diff 摘要。如果其中报告了 更改，请下载 plugin-sdk-api-release-diff-<npm-preflight-run-id>-<run-attempt> 制品， 检查发生更改的声明，并将 PLUGIN_SDK_API_ACKNOWLEDGEMENT 设置为其 digest 的前 8 个字符。 否则，将其设置为空字符串。然后从该确切提交创建并推送发布标签：

NPM_PREFLIGHT_RUN_ATTEMPT="$(gh api \
  "repos/openclaw/openclaw/actions/runs/${NPM_PREFLIGHT_RUN_ID}" \
  --jq .run_attempt)"
plugin_sdk_diff_dir="$(mktemp -d)"
gh run download "$NPM_PREFLIGHT_RUN_ID" --repo openclaw/openclaw \
  --name "plugin-sdk-api-release-diff-${NPM_PREFLIGHT_RUN_ID}-${NPM_PREFLIGHT_RUN_ATTEMPT}" \
  --dir "$plugin_sdk_diff_dir"
jq '{digest, entrypointsAdded, entrypointsRemoved, exports}' \
  "$plugin_sdk_diff_dir/plugin-sdk-api-release-diff.json"

PLUGIN_SDK_API_ACKNOWLEDGEMENT=""
# After reviewing a nonempty diff, use its printed digest:
# PLUGIN_SDK_API_ACKNOWLEDGEMENT="$(jq -r '.digest[0:8]' \
#   "$plugin_sdk_diff_dir/plugin-sdk-api-release-diff.json")"

git tag -a "$TAG" "$SHA" -m "openclaw ${TAG#v}"
git push origin "$TAG"
rm -rf "$plugin_sdk_diff_dir"

8. 发布目前被阻止：npm 子任务需要受保护的 release-publish/* 工具标签，但 alpha 分支的 SHA 不在 main 上，因此 ensureReleasePublishToolingTag 无法为其生成标签。父级的 审批回执 create 也会拒绝 tideclaw/alpha/* 引用。保留 候选版本和验证证据，报告此工具链阻塞问题，并且不要 放宽环境策略。下面的历史调度记录了 alpha 输入，以便在该发布路径修复后进行恢复；现在不要运行：

FULL_RELEASE_VALIDATION_RUN_ATTEMPT="$(gh api \
  "repos/openclaw/openclaw/actions/runs/${FULL_RELEASE_VALIDATION_RUN_ID}" \
  --jq .run_attempt)"
"$GH" workflow run openclaw-release-publish.yml --repo openclaw/openclaw --ref "$BRANCH" \
  -f tag="$TAG" \
  -f preflight_run_id="$NPM_PREFLIGHT_RUN_ID" \
  -f full_release_validation_run_id="$FULL_RELEASE_VALIDATION_RUN_ID" \
  -f full_release_validation_run_attempt="$FULL_RELEASE_VALIDATION_RUN_ATTEMPT" \
  -f plugin_sdk_api_acknowledgement="$PLUGIN_SDK_API_ACKNOWLEDGEMENT" \
  -f npm_dist_tag=alpha \
  -f plugin_publish_scope=all-publishable \
  -f publish_openclaw_npm=true \
  -f release_profile=beta \
  -f wait_for_clawhub=false

9. 发布路径修复后，监控发布包装器及其子运行并核实结果；发布仍被阻止时，不要将发布标记为完成。
10. 不要直接从主机发布 npm；请使用 GitHub Actions/OIDC。

重要：使用 preflight_only=true 运行 openclaw-npm-release.yml 时，只会准备制品，不会发布。alpha 发布成功需要后续的 openclaw-release-publish.yml 包装器、已推送的 git 标签、npm alpha dist-tag 证据和 GitHub 预发布。

验证已发布的 Alpha 版本

满足以下所有条件后，发布才算完成：

• GitHub 标签已存在。
• GitHub Release 已存在，且标记为预发布。
• Release 正文包含指向 npm 版本页面、registry tarball、完整性信息和 CI/证明的链接。
• npm view openclaw@<version> 显示准确的版本、dist-tag alpha、tarball、完整性信息和发布时间。
• 安装/软件包冒烟测试遵循仓库发布文档。
• $release-private 中的 Tideclaw 状态文件记录了版本、标签、基础 SHA、分支、修复提交 SHA、工作流运行 ID、npm 完整性信息和时间戳。

在 #releases 中发送最终 Discord 摘要：

• 标签/版本
• 基础 SHA
• 分支
• 修复提交
• 工作流运行 ID
• npm/GitHub 证明
• 如果未发布，说明跳过/阻止原因

使用适用于 Discord 的 Markdown 链接，并将目标 URL 放在尖括号中。切勿输出机密信息。

向前移植

Alpha 版本成功发布后，向 main 提交仅包含修复的 PR：

1. 从当前的 origin/main 创建/更新向前移植分支：

git fetch origin main --prune
git switch -c "tideclaw/forward-port/$(date -u +%Y-%m-%d-%H%MZ)" origin/main

2. 仅挑选发布分支中为通过 nightly/发布检查所必需的实际修复提交。
3. 排除 Alpha 版本号变更、变更日志中的发布条目、发布说明、标签产物、生成的发布资源、仅涉及状态文件的提交，以及唯一目的是发布 Alpha 的任何提交。
4. 如果某个提交同时包含实际修复和发布/版本变更，则将其拆分：仅将修复部分应用到向前移植分支，并创建新提交。
5. 以最小且兼容 main 的修复方式解决冲突。
6. 运行相关的变更/本地检查。
7. 推送并创建 PR，或使用仓库允许的机器人合并流程。
8. 等待必需的 main CI 全部通过。如果 CI 失败，在向前移植分支上修复并重新运行。
9. 报告 PR/合并 SHA，以及有意不向前移植的任何提交。

如果向前移植前 origin/main 已独立出现失败，则记录无关的失败检查；条件允许时，仍应确保向前移植 PR 在其目标分支最新提交上通过检查。

分支保留

每次运行前后都清理旧的 Alpha 分支：

1. 列出 origin/tideclaw/alpha/*。
2. 保留 UTC 时间在最近 3 天内的分支。
3. 保留被正在运行的工作流、开放的 PR、发布标签或状态文件引用的分支。
4. 仅删除 Tideclaw 所有的 Alpha 分支：

git push origin --delete tideclaw/alpha/YYYY-MM-DD-HHMMZ

切勿删除个人分支、Beta 分支、稳定版分支或前缀未知的分支。

停止条件

遇到以下情况时停止并明确报告：

• 发布文档/脚本对版本管理或发布路径的说明不一致
• 所需机密信息/身份验证不可用
• 无法触发或查看 GitHub Actions
• 尝试实际修复后，必需的发布检查仍未通过
• 发布后 npm/GitHub 状态不一致
• 若不进行更大的产品决策，就无法让向前移植通过检查