全流程发布验证与 CI 监控技能

一、技能概述

该技能是 OpenClaw 发布流程中的 CI 验证与监控层。当发布候选版本（release candidate）需要进行完整验证时，它负责：

• 启动 full-release-validation.yml 工作流，执行全矩阵发布验证

• 启动 openclaw-performance.yml 性能测试工作流，并行获取性能证据

• 监控运行状态，汇总子任务结果

• 对失败作业进行定向排查，而非盲目重跑

• 记录完整的发布证据链（SHA、run URL、子任务结论、provider 预检结果等）

关键原则：该技能是验证者而非执行者——它不执行版本 bump、打 tag、npm publish 或 GitHub release，所有这些操作都需要明确的 operator 批准。

二、核心功能

1. 发布前预检（Preflight）

在启动完整发布验证之前，技能会执行一系列预检：

# 验证必需的 provider secrets
node .agents/skills/release-openclaw-ci/scripts/verify-provider-secrets.mjs --required openai,anthropic,fireworks

# 检查 GitHub API 速率限制
gh api rate_limit --jq '.resources.core'

# 检查 git 状态
git status --short --branch
git rev-parse HEAD

关键要求：

• 在调度昂贵的全矩阵发布之前，必须先验证 provider secrets

• 1Password service-account 值是 release provider 预检的首要来源

• 优先注入这些精确的 key，然后运行验证器

• Anthropic 检查会执行一次 tiny message completion，因此已耗尽或不可计费的凭证会在昂贵的 release matrix 之前就失败

• 验证器只打印 provider 状态和 HTTP 类别，绝不输出 token

2. 性能证据启动（Performance Evidence）

在发布 SHA 存在后，尽早启动性能测试工作流，与其他发布工作并行：

gh workflow run openclaw-performance.yml \
  --repo openclaw/openclaw \
  --ref main \
  -f target_ref=<SHA> \
  -f profile=release \
  -f repeat=3 \
  -f deep_profile=false \
  -f live_openai_candidate=false \
  -f fail_on_regression=true

关键要求：

• 不要等待完整发布验证完成再启动性能信号

• 对比 Kova、gateway 启动和 CLI 启动指标与早期发布证据

• 将重大性能回归视为发布阻塞项，直到修复、被 operator 豁免或被证明是基础设施噪音

3. 完整发布验证调度（Full Release Validation）

gh workflow run full-release-validation.yml \
  --repo openclaw/openclaw \
  --ref main \
  -f ref=<SHA> \
  -f provider=openai \
  -f mode=both \
  -f release_profile=full \
  -f rerun_group=all

关键要求：

• 对于在移动的 main 分支上的不可变工作流证明，使用 pnpm ci:full-release --sha <SHA>——其规范化的 release-ci/* ref 在证明工作流提交仍位于可信的 main 分支上后，可保持精确目标证据重用

• 使用 release_profile=stable，除非 operator 明确要求 broader advisory provider/media matrix

• stable 和 full profile 强制 release soak；beta profile 可通过 run_release_soak=true 选择加入

• 发布使用 openclaw-release-publish.yml，release_profile=from-validation，发布工作流从 full-validation manifest 读取有效 profile

4. 监控与汇总（Watch & Summarize）

使用过渡性摘要监控器，而非重复的原始轮询：

# 持续监控
node scripts/release-ci-summary.mjs --watch

# 一次性快照
node scripts/release-ci-summary.mjs

关键要求：

• 监控一个父运行 + 紧凑的子任务摘要

• 避免广泛的 gh run view 轮询循环；REST 配额很容易耗尽

• 仅在失败或当前阻塞的 job 上获取日志

• 如果配额不足，停止轮询并等待重置

5. 故障分类与排查（Failure Triage）

当 full-release-validation 失败时，技能按以下步骤进行排查：

第一步：列出失败 job

gh run view <run-id> --repo openclaw/openclaw --json jobs \
  --jq '.jobs[] | select(.conclusion=="failure" or .conclusion=="timed_out" or .conclusion=="cancelled") | [.databaseId,.name,.conclusion,.url] | @tsv'

第二步：获取一个失败 job 的日志（如果被限流，记录 reset 时间并避免更多 REST 调用）

第三步：根据失败类型分类处理：

• Secret 相关失败：在编辑代码前，用同一个 secret 验证真实的 completion。成功的 model-list 请求不足够——Claude CLI subscription credentials 是独立的 native auth 路径，必须用 clean-home CLI probe 证明，不能作为必需的 Anthropic API-key lane 的替代品

• Live-cache 失败：检查是 missing/invalid key、空文本、provider 拒绝、超时还是 baseline miss

• Live-provider flake：与代码失败分开处理——证明 key 有效性、provider HTTP 状态、重试证据和确切的失败 lane，然后再编辑代码

• Full Release Validation parent：一旦必需的 child job 失败，parent 会取消剩余的 child matrix 并打印失败 job 摘要——首先检查第一个红色 job，而不是等待无关的 matrix tails

修复原则：窄修复 → 运行 local/changed proof → commit → push → rerun 最小的匹配 group

6. 源码同步与 Testbox 管理

在稀疏工作树或 Testbox 源码同步中，技能有严格的校验规则：

• 首先确认 package.json、pnpm-lock.yaml 以及所选 check 读取的每个源码路径是否存在。如果缺失，该 checkout 无法验证 release dependency 或 Docker lane——停止并使用 repo remote changed gate 或 full task worktree

• 当输入存在且 release fix 修改了 package.json 或 pnpm-lock.yaml 时，仅重建 task-owned disposable box，使用 CI=true pnpm install --frozen-lockfile，然后运行显式的 require.resolve() probe

• CI flag 允许 pnpm 重新创建预热 modules 目录而无需交互确认，但不能 weaken lockfile 或将 sparse-checkout 失败标记为 product/Docker 失败

• 如果候选版本在 warmup 后 rebase 或其 base SHA 发生变化，停止 task-owned box 并在测试前预热一个新的

• 重用 Testbox 是 provenance-gated 的——source-only edits 可重用 lease；base、dependency、wrapper 或 Testbox workflow drift 需要 fresh lease。不要为 release evidence 设置 OPENCLAW_TESTBOX_ALLOW_STALE=1

• 对于已提交的 release candidate，使用 blacksmith testbox warmup ... --ref . 预热 box，不要依赖 source sync 将 committed branch changes 覆盖到 workflow 的 default ref 上

7. PR CI 卡住时的 fallback 处理

当必需的 PR CI 运行因队列阻塞且没有活跃 job 而卡住时：

• 不要取消无关工作或接受 generic manual dispatch

• 从 PR head branch，调度显式的 exact-SHA fallback：

  gh workflow run ci.yml --repo openclaw/openclaw --ref <head-sha> \
    -f target_ref=<head-sha> \
    -f include_android=true \
    -f release_gate=true

• 该 fallback 在 GitHub-hosted runners 上运行，仅当其 run title 为 "CI release gate" 时才被接受

• 在 release evidence 中记录 stalled Blacksmith run 和 fallback run

• 如果 Blacksmith Build Artifacts Testbox 是唯一剩余的必需 gate 且一直排队没有 runner，completed exact fallback 可能覆盖它——但不要在 artifact workflow 启动或非成功完成后使用此覆盖

三、主要用途

1. 发布候选版本的完整验证
   在每次 beta 版、稳定版发布或重新发布之前，启动全矩阵发布验证工作流，确保所有必需的 CI 检查、provider 集成和性能指标通过。

2. 发布 CI 失败排查与恢复
   当 full-release-validation 失败时，系统化地定位第一个失败的 job、获取日志、分类根因（secret 问题、live-provider flake、源码同步问题等），并执行窄修复后 rerun。

3. 性能回归检测
   在发布流程早期并行启动性能测试，对比历史数据，将重大性能回归标记为发布阻塞项。

4. Provider Secret 预检
   在昂贵的发布矩阵之前验证所有必需的 provider credentials（OpenAI、Anthropic、Fireworks 等），避免因 credential 问题浪费 CI 资源。

5. CI 配额管理
   通过限制轮询频率、仅获取失败 job 日志、使用摘要监控器等方式，避免耗尽 GitHub API REST 配额。

四、与相关技能的协作

五、重要原则

1. 不执行发布操作：不执行 version bump、tag、npm publish、GitHub release 或 release promotion，所有这些都需要明确的 operator 批准

2. 先验证 secret，再调度矩阵：在调度昂贵的 full release matrix 之前，必须验证 provider secrets

3. 不设置未验证的 secret：如果候选 secret 返回 401/403，保留现有 secret 不变，报告确切缺失的 provider

4. 不轮询耗尽配额：监控一个父运行 + 紧凑的子任务摘要；避免广泛的 gh run view 轮询循环

5. 先检查第一个红色 job：Full Release Validation parent 在 child job 失败时会取消剩余的 child matrix——首先检查第一个红色 job

6. Testbox 严格 provenance：不设置 OPENCLAW_TESTBOX_ALLOW_STALE=1 用于 release evidence

7. A model-list response 证明认证，而非计费或推理 entitlement：必需的 live providers 必须在 release dispatch 之前通过真实的 completion probe

六、证据记录要求

每次发布验证完成后，必须记录：

• release SHA

• full parent run URL

• child run IDs 和结论：CI、Release Checks、Plugin Prerelease、NPM Telegram、Product Performance

• performance comparison result（与早期发布对比，如有）

• targeted local proof commands

• provider-secret preflight result

• known gaps 或 unrelated failures

七、总结

Release OpenClaw CI 是 OpenClaw 发布流程中的 CI 验证与监控中枢，负责启动全矩阵发布验证、并行获取性能证据、监控运行状态、定向排查失败 job，并记录完整的发布证据链。它不执行版本 bump、打 tag 或 publish 等操作——这些由 release-openclaw-maintainer 在 CI 验证通过后执行。该技能适用于 OpenClaw 项目在 beta/stable 发布周期中进行完整的 CI 验证、provider 集成测试和性能回归检测的场景，是保障发布质量的关键环节。