openinterpreter（Codex）V8 版本升级实战：从 pin 修改、checksum 一致性到 v8-canary 金丝雀验证

本文基于 openinterpreter 仓库内置的 Agent 技能文档 update-v8-version/SKILL.md 展开，完整讲解该项目升级内置 V8（rusty_v8 / v8 crate）的标准工作流：需要改动哪些 pin 载体文件、如何用仓库自带脚本保证 checksum 与 MODULE.bazel 同步、如何用 v8-canary 金丝雀流水线验证发布候选，以及在 canary 构建失败时如何沿构建图定位上游差异并修复。读完本文，你可以独立完成一次受控的 V8 版本升级，并具备对 V8 canary / 产物构建失败的诊断能力。

为什么 V8 版本升级是一个"受控工程"

openinterpreter 的 Rust 代码库通过 v8 crate（封装 Google V8 引擎的 rusty_v8 生态）提供 JS 执行能力。项目对 V8 采取的是**精确版本锁定（exact pin）**策略，而不是开放区间：

• Rust 侧在 codex-rs/Cargo.toml 中声明 v8 = "=150.4.0"（当前仓库实测值），并在 codex-rs/Cargo.lock 中固化了 v8 150.4.0 的 registry checksum；
• Bazel 侧在 MODULE.bazel 中同时锁定了两套版本：上游 V8 引擎源码 bazel_dep(name = "v8", version = "15.0.245.2")（配合 patches/v8_*.patch 补丁集），以及 v8_targets crate 仓库的 RUSTY_V8_ARCHIVE / RUSTY_V8_SRC_BINDING_PATH 环境变量注入。

这种"双版本"结构是理解整个升级流程的钥匙：

版本载体	含义	载体文件
Rust crate 版本（如 150.4.0）	v8 crate / rusty_v8 预编译产物版本，决定 Cargo 构建下载哪份静态库与 binding	codex-rs/Cargo.toml、codex-rs/Cargo.lock
上游 V8 引擎版本（如 15.0.245.2）	Bazel 源码构建使用的 V8 引擎源码 tag	MODULE.bazel
checksum 清单	仍走 http_file 的预编译产物（当前仅剩 Windows MSVC 两平台）的 SHA-256	third_party/v8/rusty_v8_150_4_0.sha256

当前仓库的完整 pin 状态可以在 third_party/v8/README.md 的 "Current pinned versions" 一节直接核对：Rust crate v8 = =150.4.0，Bazel 嵌入的上游 V8 源码 15.0.245.2。SKILL.md 明确要求：任何版本升级，都以 third_party/v8/README.md 为发布流程的唯一事实来源（release-process source of truth），技能文档本身只定义操作顺序与验证/失败处理路径。

升级工作流（Core Workflow）：六个必须触碰的仓库面

SKILL.md 的 Core Workflow 规定升级要"检查并更新所有承载 pin 的具体仓库面"，共六处：

1. codex-rs/Cargo.toml：把 v8 = "=<新版本>" 提升到目标 crate 版本；
2. codex-rs/Cargo.lock：刷新 lock 文件，使解析出的 v8 版本唯一且与新 pin 一致；
3. MODULE.bazel：更新 Bazel 侧的版本化输入（v8 crate 仓库、http_file 预编译产物 URL）；
4. third_party/v8/BUILD.bazel：承载 //third_party/v8:rusty_v8_archive_for_target、//third_party/v8:rusty_v8_binding_for_target 两个面向消费者的选择器目标；
5. third_party/v8/README.md：同步文档中声明的当前 pin 版本；
6. 若仍保留的预编译 http_file 输入发生变化，还需更新配套的 third_party/v8/rusty_v8_<version>.sha256 checksum 清单（文件名中版本号的点号替换为下划线，如 rusty_v8_150_4_0.sha256）。

checksum 一致性助手：让 MODULE.bazel 与清单互锁

修改上述 http_file 输入后，SKILL.md 要求把仓库自带的 checksum 助手"保持在环内"：

python3 .github/scripts/rusty_v8_bazel.py update-module-bazel
python3 .github/scripts/rusty_v8_bazel.py check-module-bazel
python3 -m unittest discover -s .github/scripts -p test_rusty_v8_bazel.py

这三条命令的底层实现值得展开：

• 核心逻辑在 rusty_v8_module_bazel.py。它以正则 ^rusty_v8_([0-9]+)_([0-9]+)_([0-9]+)_ 解析 MODULE.bazel 中所有 http_file(...) 块，提取每个块的 name、downloaded_file_path、sha256，再与 third_party/v8/rusty_v8_<version>.sha256 清单逐条比对。清单格式严格为 <sha256> <filename>（要求裸文件名、64 位十六进制摘要、不允许重复条目），任何不一致都会抛出 RustyV8ChecksumError；
• rusty_v8_bazel.py 提供 CLI 封装：update-module-bazel 用清单重写 MODULE.bazel 中对应 http_file 的摘要，check-module-bazel 只读校验。两者都默认取 MODULE.bazel 中当前存留的唯一 rusty_v8_* http_file 版本，若发现多于一个版本会直接报错要求显式传 --version——这个设计防止了升级中途"新旧两套预编译输入并存"导致的静默漂移；
• 同一脚本的 resolved-v8-crate-version 子命令（实现见 rusty_v8_bazel.py#L142-L170）是全局的"单一事实解析器"：优先从 codex-rs/Cargo.lock 中解析名为 v8 的包版本，且要求有且仅有一个；若 lock 中没有，则回退到正则匹配 MODULE.bazel 中 https://static.crates.io/crates/v8/v8-<version>.crate 的唯一 pin。CI 的 v8-canary 与 rusty-v8-release 工作流的 metadata 阶段都调用它来解析精确版本，因此 Cargo 与 Bazel 两侧的 pin 一致性在流水线上被反复交叉验证。

CI 会运行 check 命令来阻断 checksum 漂移（README 原文："CI runs the check command to block checksum drift"），这也是为什么本地升级时必须先跑 update 再跑 check 的顺序——先刷新，再自证。

发布候选的验证：v8-canary 是终点线

SKILL.md 的核心流程第 4 步规定：先把发布候选（release candidate）路径验证通过，再扩大工作范围。具体分两种情形：

1. 优先检查 v8-canary CI 结果：对候选分支或 PR，使用 GitHub check 工具或 gh 查看 canary 是否通过；
2. CI 不可用或用户要求本地检查时：运行对应变动面上最接近的本地验证，并且必须明确声明这是本地替代（local substitute），不是完整的托管 canary。

.github/workflows/v8-canary.yml 的实际覆盖范围是判断"本地替代够不够"的标尺：

• metadata job：先调用 resolved-v8-crate-version 拿到精确 crate 版本，再运行 v8_canary_changes.py 做变更检测。该脚本内置 CANARY_PATH_PATTERNS 路径集合（MODULE.bazel、codex-rs/Cargo.toml、third_party/v8/**、patches/v8_*.patch、.bazelrc、相关 workflow 等），只有变更命中集合、或 base/head 的 V8 版本不一致、或手动 --force 时，才会触发昂贵的大矩阵构建；注释明确说明"缺失的输出必须意味着 run"，防止陈旧分支上的旧检测器静默跳过 V8 覆盖并报成功；
• build 矩阵：12 个组合，覆盖 x86_64/aarch64 × linux-gnu/linux-musl（ubuntu-24.04 与 ubuntu-24.04-arm）以及 x86_64/aarch64 的 Darwin（macos-15-xlarge），每个平台各跑 release 与 ptrcomp-sandbox 两个变体。构建命令形如 bazel build --platforms=@llvm//platforms:<platform> --config=rusty-v8-upstream-libcxx --config=v8-target-<cpu> //third_party/v8:rusty_v8_(sandbox_)release_pair_<target>；随后 stage-release-pair 产出 gzip 静态库 + binding，并在原生平台用 cargo test -p codex-v8-poc（sandbox 变体追加 --features sandbox）做链接冒烟，验证 staged 产物能被 v8 crate 消费；
• build-windows-source job：Windows MSVC（x86_64/aarch64-pc-windows-msvc）的 sandbox 产物无法由仓库的 Bazel Windows GNU 工具链产生（见下文），因此 canary 会 checkout 上游 denoland/rusty_v8 在 v<crate_version> tag 的源码，以 V8_FROM_SOURCE=1 与 --features v8_enable_sandbox 从零构建，再用 stage-upstream-release-pair 打包并对 codex-v8-poc 做跨目标链接冒烟。

当 canary 通过时，SKILL.md 的规定是到此为止（stop there）：总结结果，提示用户提交候选变更或继续其请求的发布流程；除非用户明确要求，不要发布 tag、release 或 push。这界定了"版本升级完成"与"发布已产出"两个状态的责任边界。

失败路径（Failure Path）：canary 挂掉时的诊断方法

只有当 canary 或本地构建路径失败时，才进入 SKILL.md 的 Failure Path。它给出的是一条六步排查链，本质是"锁定失败面 → 对齐上游 → 追踪构建相关 delta → 回映到本仓库构建图 → 最小修复 → 复验"：

1. 捕获失败现场：记录失败的具体 target、workflow job 以及第一条可操作（actionable）的错误，而不是笼统的构建失败；
2. 双仓库对齐：在相关上游 tag 或 SHA 上，对比当前 pin 版本与目标版本，同时检查两处——denoland/rusty_v8（crate 与产物侧）和 Bazel pin 版本的 V8 引擎源码（引擎侧）；
3. 只追踪构建相关的 delta，忽略宽泛的源码 churn。SKILL.md 列出的关键差异类别，恰好覆盖了本仓库对上游的全部接触面：
   • 生成的 binding 布局变化（对应 src_binding_*.rs 与 third_party/v8/v8_crate.BUILD.bazel 的消费方式）；
   • 归档或资产命名变化（对应 librusty_v8_<profile>_<target>.a.gz / rusty_v8_<profile>_<target>.lib.gz 命名约定与 rusty_v8_bazel.py#L201-L212 的 staged_archive_name/staged_checksums_name）；
   • GN / Bazel target 变化（对应 patches/v8_bazel_rules.patch、patches/v8_module_deps.patch 等 MODULE.bazel 中挂到 v8 bazel_dep 上的补丁）;
   • 自定义 libc++ / libc++abi / llvm-libc 输入变化（对应 rusty_v8_libcxx、rusty_v8_libcxxabi、rusty_v8_llvm_libc 三个 Bazel 仓库与 patches/llvm_rusty_v8_custom_libcxx.patch、patches/rules_cc_rusty_v8_custom_libcxx.patch）；
   • sandbox 或 pointer-compression feature 关系变化（对应 v8_enable_sandbox feature 映射与 ptrcomp_sandbox 产物 profile）；
   • patches/ 中不再适用或不再匹配上游的 patch hunk；
4. 把每个失败 delta 回溯到 Codex 构建图中的具体文件：MODULE.bazel、third_party/v8/BUILD.bazel、.github/scripts/rusty_v8_bazel.py、.github/workflows/v8-canary.yml、.github/workflows/rusty-v8-release.yml；
5. 只更新恢复目标版本构建与产物契约所必需的部分，patch 说明与文档改动紧贴受影响文件，不顺手重构；
6. 重跑聚焦验证：转绿后回到正常工作流，以"简洁总结 + 剩余的发布步骤"收尾。

从源码结构看，这套失败路径并非泛泛而谈，它与本仓库 Bazel 图中最脆弱的几个点一一对应。例如 third_party/v8/README.md 明确记录了 libc++ 约束：Bazel 图 pin 了与 rusty_v8 v150.4.0 相同的 libc++、libc++abi、llvm-libc 源码修订，产物目标以 --config=rusty-v8-upstream-libcxx 编译，并把匹配的运行时对象折叠进最终静态归档，以便消费者以 v8 crate 默认的 use_custom_libcxx feature 链接；该 config 刻意让对象文件与捆绑运行时保持在 Chromium 的 std::__Cr ABI 命名空间，避免与工具链默认 libc++ 命名空间混用。任何升级若改变了上游 libc++ 修订，这条链就是首先要核对的差异面。

发布流程与产物契约（canary 绿之后）

canary 通过不等于发布完成。third_party/v8/README.md 的维护者流程给出完整闭环：

1. 提升 v8 crate 版本并刷新 codex-rs/Cargo.lock；
2. 更新 MODULE.bazel 的 Bazel 版本化输入，刷新配套 checksum 清单与生成摘要；
3. 提交发布候选 PR，验证 v8-canary 通过；
4. canary 绿后，发布 release tag 与 release 构建；
5. release 构建完成后，在候选分支上重跑构建，验证最终产物可构建且测试通过。

发布的执行者是 rusty-v8-release.yml，其契约要点包括：

• tag 命名强校验：workflow 的 metadata 阶段会断言当前 ref 名必须等于 rusty-v8-v<crate_version>（crate 版本仍由 resolved-v8-crate-version 解析），不匹配直接失败。这是刻意设计——v8 crate 上游 build.rs 硬编码了 v<crate_version> 的 tag 布局，而本项目资产发布在 rusty-v8-v<crate_version> 下，因此 README 同时说明"不使用 RUSTY_V8_MIRROR"，Darwin/Linux 的 release 与 CI Cargo 构建改用 RUSTY_V8_ARCHIVE + 下载的 RUSTY_V8_SRC_BINDING_PATH 直接指向发布资产；
• 产物命名契约：常规资产为 librusty_v8_release_<target>.a.gz 与 src_binding_release_<target>.rs（Windows MSVC 为 .lib.gz）；sandbox 推广期间，同一 tag 下并列发布带 crate sandbox feature 后缀的资产 librusty_v8_ptrcomp_sandbox_release_<target>.a.gz、rusty_v8_ptrcomp_sandbox_release_<target>.lib.gz、src_binding_ptrcomp_sandbox_release_<target>.rs；
• Bazel 产物矩阵：tag 触发的运行从 Bazel 图本身构建 //third_party/v8:rusty_v8_release_pair_{x86_64,aarch64}_{apple_darwin,unknown_linux_gnu,unknown_linux_musl} 六个目标及其 rusty_v8_sandbox_release_pair_* 对应物；Windows MSVC 的 sandbox 归档/binding 对则从上游 rusty_v8 源码构建，因为仓库当前的 hermetic Windows C++ 平台是 windows-gnullvm/x86_64-w64-windows-gnu，在补齐真正的 MSVC 目标 C++ 工具链之前无法复现上游的 *-pc-windows-msvc 归档；
• 平台 feature 映射：从 MODULE.bazel 看，v8_targets 的 per-target feature 已把 v8_enable_sandbox 映射到 Darwin、Linux gnu/musl 与 Windows 双 ABI 的目标上，Bazel 消费者构建使用源码构建的本地归档，Windows MSVC 消费者则命中 http_file 拉取的 sandbox 资产（如 MODULE.bazel#L521-L534 中指向 rusty-v8-v150.4.0 tag 的两条 MSVC 归档），其摘要由 checksum 清单守护；
• 铁律：不要跨 crate 版本混用产物——归档与 binding 必须与 codex-rs/Cargo.lock 中解析出的精确 v8 版本完全匹配。

汇报规范：如何报告一次 V8 升级

SKILL.md 的 Reporting 一节定义了交付汇报的三条硬性要求，这些要求直接影响升级工作的可信度：

• 说明验证来源：验证来自托管的 v8-canary 还是本地替代（local substitute），必须显式声明，不允许含糊其辞；
• 区分两种完成态："version bump complete"（版本升级完成，候选已验证）与"release published"（发布已产出，tag/资产已对外可见）是两个不同状态，汇报时必须分开；
• 受阻时的报告格式：当被阻塞，要报告三样东西——上游的关键 delta 是什么、它击中的是仓库里的哪个文件、下一步具体该尝试什么修复。这与 Failure Path 第 3、4 步的"delta → 构建图文件"回溯完全同构。

技能的元信息（展示名 "Update V8 Version"、默认提示词）见 .codex/skills/update-v8-version/agents/openai.yaml，与 SKILL.md 的 description 一致：该技能面向"被要求 bump V8、更新 rusty_v8 产物、准备或验证 V8 发布候选、检查 v8-canary、诊断为何某次 V8 版本更新不再可构建"这些场景。

速查表：升级时逐项核对

检查项	文件/命令	判定标准
Rust 侧 pin	codex-rs/Cargo.toml、codex-rs/Cargo.lock	v8 = "=X.Y.Z" 与 lock 中唯一 v8 包版本一致
Bazel 侧 pin	MODULE.bazel	v8 crate 仓库、上游 V8 bazel_dep、http_file 输入均指向目标版本
checksum 清单	third_party/v8/rusty_v8_150_4_0.sha256	文件名版本与新 crate 版本一致（点号转下划线）
一致性检查	python3 .github/scripts/rusty_v8_bazel.py update-module-bazel && python3 .github/scripts/rusty_v8_bazel.py check-module-bazel	退出码 0，无 RustyV8ChecksumError
单元测试	python3 -m unittest discover -s .github/scripts -p test_rusty_v8_bazel.py	全部通过
金丝雀验证	.github/workflows/v8-canary.yml 的 PR 检查结果	全部 build / build-windows-source job 绿
版本解析交叉验证	python3 .github/scripts/rusty_v8_bazel.py resolved-v8-crate-version	输出版本 = 目标 crate 版本
文档同步	third_party/v8/README.md	"Current pinned versions" 与代码 pin 一致

需要强调的适用前提：以上流程与产物契约均以当前仓库状态为准（v8 = =150.4.0、上游 V8 15.0.245.2、Bazel 消费构建默认走源码构建归档、Windows MSVC 仍为 http_file 预编译输入）。若未来 Windows MSVC 加入 Bazel 工具链矩阵、或 http_file 输入被完全移除，checksum 清单与 check-module-bazel 的适用面会随之变化——届时仍应以 third_party/v8/README.md 的最新描述为发布流程事实来源。