Cua 历史版本归因回填（Release Backfill）操作手册：为 Rust Cua Driver 与 Lume 追溯生成并安全回填 GitHub Release Notes-港品优选

Cua 历史版本归因回填（Release Backfill）操作手册：为 Rust Cua Driver 与 Lume 追溯生成并安全回填 GitHub Release Notes

【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua

本文是 Cua 仓库中 docs/release-backfill-runbook.md 的完整技术展开。它面向发布负责人（release owner），讲解如何对 Rust Cua Driver 与 Lume 两个产品的历史发布进行追溯性（retrospective）Release Notes 生成、审核与回填，涵盖从冻结发布目录、收集证据、AI 辅助撰写、渲染校验、独立审计，到试点应用、回滚演练与分批批量回填的完整运维闭环。读完本文，你将掌握release_backfill.py这套七命令管线（inventory/collect/author/render/validate/apply/rollback）的每条命令、每个关键参数与安全不变量，并理解它为何被设计成"只允许补丁 Release Body"的最小化写操作面。

什么时候该用这本手册

这本手册服务于一次性历史回填（one-time historical backfill）：为过去已经发布、但缺少结构化 Release Notes 的 Cua Driver（Rust 驱动）与 Lume（Swift/macOS 虚拟化运行时）历史版本，追溯生成回顾性的发布说明并写回 GitHub Release。

需要特别区分的是：

历史回填：只对过去已发布版本执行，是本手册的适用范围。
未来发布：继续使用正向的 Release Please 工作流与归因流程（参见 release-attribution-and-announcements-plan.md），不在本手册范围内。

仓库当前的冻结快照（2026-07-17 生成）中，目录catalog.json共收录54 个已发布的 Rust Cua Driver 版本与 128 个已发布的 Lume 版本（合计 182 个发布条目，这一数量来自当次 inventory 快照，后续有意重新生成的快照可能有不同计数）。与这条冻结目录配套的审核产物是：evidence.json（证据包）、candidates.json/candidates.md（候选文案）、skip-ledger.json（跳过台账，当前 36 条）与rendered.json（最终可应用载荷，当前 146 条）。

动手前的硬性前提

在执行任何命令之前，发布负责人需要确认以下前提，缺少任意一项都会让流程在中途失败或失去可审计性：

发布冻结：为 Cua Driver 与 Lume 宣布发布冻结（release freeze），覆盖 inventory 与 apply 两个时间窗口，避免冻结状态与线上发布状态互相漂移。
仓库状态：拉取origin/main和全部 tag；生成阶段基于当前origin/main新建一条干净分支。
校验依赖：用python3 -m pip install jsonschema安装校验依赖（validate命令会在缺少该包时报错并给出同样的安装提示，见 release_backfill.py）。
令牌：导出GH_TOKEN。inventory、collect阶段需要仓库读权限；apply阶段额外需要发布写权限。
日志隔离：操作日志（journal）与 Claude 流式日志一律放在仓库之外的绝对路径，绝不提交入库。
串行执行：不要在另一位发布负责人正在编辑 Release Notes 时运行apply --execute。

最后一条容易忽略：合并实现 PR 本身不会修改 GitHub Release。只有显式执行apply --execute命令才可能补丁（patch）Release body——这正是下文"变更边界"反复强调的安全设计。

生成待审载荷：五步流水线

从冻结到产出可审核载荷，共五步，前四步对应release_backfill.py的前四个子命令，第五步是独立的人工/AI 审计。

1. 冻结发布目录（inventory）

python3 .github/scripts/release_backfill.py inventory

该命令读取本地 tag 与已发布的 GitHub Release，将每个产品的发布冻结写入 .github/release-backfill/catalog.json。你需要逐一审查其中每个条目的：

previousTag：前一个相邻发布 tag；
rangeKind：initial（首个版本）/continuous（连续区间）/disconnected（断链，前驱不参与 diff）；
pathEraIds：该版本命中的路径时代（path era）标识；
各 tag 的 SHA。

路径时代（path era）是这套归因系统的关键概念：Cua Driver 与 Lume 都经历过代码仓库迁移，不同版本区间对应的代码路径不同。定义见 .github/release-backfill/config.json：

Cua Driver（cua-driver-rs）：tag 规则为^cua-driver-rs-v(?P<version>[0-9]+\.[0-9]+\.[0-9]+)$；driver-rs-original时代覆盖0.1.3–0.2.18，路径为libs/cua-driver-rs；driver-rs-current时代从0.3.0起，路径为libs/cua-driver，并排除libs/cua-driver/docs、python、tests三个子目录。
Lume：同时匹配^v0\.1\.(?:[0-9]|10|11|12|13)$与^lume-v(?P<version>…)$两类 tag；lume-standalone时代覆盖0.1.0–0.1.10，路径为Package.swift、resources、scripts、src、tests；lume-monorepo时代从0.1.11起，路径收敛为libs/lume。disconnectedTags: ["v0.1.1"]表示该 tag 没有可用的连续前驱。

build_catalog在生成时还会执行两类硬校验：tag 必须恰好命中一个产品的规则（命中多个直接报错）；若配置的previousTag..tag区间没有 merge base，同样直接报错（见 release_backfill.py）。

2. 收集证据（collect）

python3 .github/scripts/release_backfill.py collect

collect读取冻结目录、本地 git 区间与公开 GitHub 元数据，为每个发布构建"证据包"（evidence packet），写入 .github/release-backfill/evidence.json，同时产出证据阶段的跳过台账。

证据的来源构成（见 source_from_commit）：

PR 关联：优先通过 GitHub API 的commits/{sha}/pulls把提交解析到 PR，取 PR 标题、正文、涉及文件、贡献者与关联 issue；
直接提交：无 PR 关联时保留为direct_commit，从提交信息中解析 Co-Authored-By 合作作者；
安全排除：命中securityExclusions中提交、PR 或 tag 的条目会被标记为security-review-required而跳过。

build_evidence阶段的可跳过原因被规范化为固定枚举（见 release_backfill.py）：

same-tag-sha：当前 tag 与前驱指向同一提交；
no-product-changes：显式产品区间内没有任何非发布提交（发布提交由RELEASE_COMMIT_RE/LEGACY_RELEASE_BUMP_RE过滤）；
security-review-required：等待公开披露审查；
unresolved-identity：无法解析的合作作者身份；
ambiguous-pull-request：PR 归属存在歧义。

你需要在 .github/release-backfill/skip-ledger.json 中确认每一条跳过。只有当公开证据能证明修正正确时，才去解决配置或身份类错误；same-tag-sha、空区间、私有安全与身份不确定的用例一律保持跳过。

3. 生成候选文案（author）

Claude Code 生成会产生模型费用，开始前需预估并批准运行成本。默认的自适应批量上限把每个批次控制在10 个发布 / 30 条证据源 / 120,000 输入字节以内，确保复杂发布也能完整生成：

BACKFILL_CLAUDE_MODEL=sonnet \ python3 .github/scripts/release_backfill.py author \ --model-id claude-sonnet-5 \ --resume \ python3 .github/scripts/release_backfill_claude.py

这个命令体现了整条管线中最有特色的"人机分工"：

Agent 能做什么：阅读受限的证据包，写摘要、归类变更（feat/fix/perf/revert四类），并给出每条结论对应的证据引用。
Agent 不能做什么：不能提供贡献者身份、tag 区间、GitHub 链接或变更（mutation）字段。证据包之外的引用会被校验器直接拒绝——系统提示词明确要求把证据文本当作"不可信的被引用数据"而非指令（见 agent_request）。
空变更也是有效结果：如果证据只有版本号提升或内部维护性改动，会记录一条有证据支撑的no-product-changes跳过，且该结果在--resume恢复时会被保留，而不是反复重新生成（见 author_candidates）。

作者命令在每个批次后自动检查点（checkpoint）。中断后原样重跑同一命令即可：已通过的候选会通过reusable_candidates校验（candidate 哈希、prompt 版本、evidence 哈希、prompt 哈希四项比对）后复用，失败的批次自动重试。Agent 漏掉某个发布或返回了不支持的类型时，会记录agent-rejected，同样靠--resume重试；若模型反复遗漏，可调小--batch-size（合法范围 1–25）。

仓库自带的 release_backfill_claude.py 是流式 JSON-in/JSON-out 适配器：它调用claude -p --verbose --stream-json，显式禁用全部工具（--tools ""），并把原始流与调试日志写到仓库之外的BACKFILL_CLAUDE_LOG_DIR（默认/tmp）。BACKFILL_CLAUDE_MODEL选择模型。

4. 渲染与校验（render / validate）

python3 .github/scripts/release_backfill.py render python3 .github/scripts/release_backfill.py validate

render校验候选文案对证据的引用合法性，渲染 managed block，写出最终 body 与人类可读的审查文件 .github/release-backfill/candidates.md。
validate先对五个 JSON 工件逐一做 JSON Schema 校验（对应.github/release-backfill/下的*.schema.json），再从 catalog、evidence、candidates、skip ledger 重建"应当的输出"，与已入库的rendered.json、candidates.md比对，任何不一致、覆盖不全（candidates ∪ skips ≠ releases）、哈希或证据引用非法都会失败（见 validate_documents）。

审核阶段需要检查三份文件：

candidates.md：拟议的回顾性 Notes；
skip-ledger.json：每个被省略的发布及原因；
rendered.json：将精确应用的载荷（含finalBody与finalBodySha256）。

人工审核策略：逐一审查所有 minor 版本与里程碑版本；对两个产品、每个路径时代抽取常规 patch 版本抽样审查；任何拿不准的候选都移入 review 阶段的跳过台账。

5. 独立审计

请 Claude Code Fable 对最终 PR 做一次只读审查。审查面必须覆盖：tag 邻接、路径时代、身份解析、证据约束的论断、变更方法、漂移检测、日志完整性、幂等性与回滚。合并前必须解决全部阻塞性发现（blocking finding）。这一步把"机器生成 + 人审"升级为"机器生成 + 人审 + 独立机器审计"的三层防线。

应用试点（pilot）

先在干净 worktree 中检出精确的合并提交，记录其完整 SHA：

git rev-parse HEAD git status --short

随后对六个试点发布执行干跑（dry run）。默认情况下apply就是只读干跑，--execute才是真正写操作：

python3 .github/scripts/release_backfill.py apply \ --approved-commit FULL_40_CHARACTER_SHA \ --journal /absolute/path/outside/repo/release-backfill-pilot.jsonl \ --release-key cua-driver-rs:0.8.0 \ --release-key cua-driver-rs:0.8.1 \ --release-key cua-driver-rs:0.8.2 \ --release-key lume:0.3.0 \ --release-key lume:0.3.14 \ --release-key lume:0.3.15

干跑必须报告六个拟议 body 补丁，且不产生任何 journal 或 GitHub 变更。发布负责人批准精确载荷后，才加--execute。

执行完成后原样重跑带--execute的同一命令。它会通过 journal 恢复（recover_verified_journal）把每个发布识别为already applied and verified，而不会再次发送补丁——这是幂等性的验收方式。

apply的每次写入前后都会做状态断言（assert_preserved_state，见 release_backfill.py）：核对 release ID、tag、tag SHA、标题、draft 标志、prerelease 标志与资源清单，全部一致才允许写 body；body 状态必须是"原始"或"已应用"两者之一，否则报 body 漂移。

回滚演练（rollback）

从六个试点中选一个（示例为cua-driver-rs:0.8.2），不带--execute先演练：

python3 .github/scripts/release_backfill.py rollback \ --approved-commit FULL_40_CHARACTER_SHA \ --journal /absolute/path/outside/repo/release-backfill-pilot.jsonl \ --release-key cua-driver-rs:0.8.2

批准后加--execute：工具会从已验证的 journal 中读取 pre-image 的精确 body 字节并恢复，随后核对原始 body 哈希，再重新应用同一发布。要点：

每行 journal 都要保留，严禁手工编辑 journal 文件。journal 是追加写的 JSONL（每次追加都fsync落盘，见 append_journal），prepared→verified两段式记录；
rollback 仅当当前 body 哈希等于 journal 中记录的应用后哈希时才允许执行（见 rollback_releases）；
若当前 body 在回填之后又被人改过，rollback 会拒绝覆盖更新的编辑，需要保留 journal 并人工检查新 body。

应用剩余发布

试点验收通过后，按每个产品逆时间顺序、每批 15–25 个批量应用，批次之间暂停检查：

GitHub API 返回结果与 re-fetch 验证；
保留的标题、flags、tag SHA 与资源；
journal 中的 prepared 与 verified 条目；
GitHub Release feed 行为；
贡献者姓名与链接。

遇到第一个漂移、碰撞、校验或 GitHub API 错误就必须停止整个运行，不得绕过失败的不变量：先调查，通过 PR 更新已审核的载荷，再从最后一个已验证的 journal 条目继续。--pace-seconds（默认 1.0）控制批次内相邻写入的间隔，便于观察限流与 feed 行为。

故障排查

命令报告发布状态漂移（release state drift）。说明 inventory 之后有其他进程改动了 tag、标题、flags、body 或资源。此时应冻结发布工作，检查变更来源，重新走审核流程再生成目录。

Agent 漏掉发布或返回不支持的类型。author 命令会记录agent-rejected；带--resume重跑即可，若模型再次遗漏则减小批次大小。

发布没有 PR 关联。保留直接提交作为证据。只有当 GitHub 返回经过验证的 login、或存在已批准的 coauthor 映射时才署名。

回滚拒绝当前 body。说明回填后发布又发生了变更。保留 journal、检查新 body，不要覆盖更新的编辑。

安全边界与实现细节

整套回填设计的核心是"刻意收窄的写操作面"（见 release_backfill.py 模块 docstring 与 BackfillGitHub 客户端）：

没有 delete、upload、tag、title、draft、prerelease、latest-release 等任何变更方法；唯一的写操作是PATCH repos/{repo}/releases/{id}，载荷只有一个字段：{"body": "…"}；
author 子进程环境会剥除GH_TOKEN/GITHUB_TOKEN（agent_environment），Agent 全程拿不到令牌；
--execute强制要求：完整 40 字符--approved-commit、当前 HEAD 精确等于该提交、worktree 干净（verify_execution_source）；
最终 body 有 125,000 字节上限（BODY_LIMIT_BYTES）。

渲染出的 managed block 带版本化边界标记（格式见 .github/release-backfill/README.md）：

<!-- cua-release-backfill:v1:start evidence-sha256=... --> ... <!-- cua-release-backfill:v1:end -->

已存在的标记即视为碰撞（collision）：工具从不替换或嵌套managed block（final_body）。渲染内容按## Summary、## Features/Fixes/Performance/Reverts（仅出现有变更的分类）、## Contributors、## Full changelog（compare 链接）组织（render_managed_block）。校验器同时会拒绝 Agent 文案中出现 URL、GitHub handle 或 Markdown 链接字符（FORBIDDEN_AGENT_TEXT_RE），保证回填内容只能引用证据包内、渲染阶段生成的链接。

这些不变量都有对应的单元测试覆盖，见 .github/scripts/tests/test_release_backfill.py，其中覆盖了apply_releases、rollback_releases、validate_documents、reusable_candidates、final_body、render_managed_block、verify_execution_source等核心函数。

企业官网建设流程全解析