一次“GO”是怎么挣来的：oh-my-codex 0.9.0 发布就绪验证与原生资产分发实践

一次“GO”是怎么挣来的：oh-my-codex 0.9.0 发布就绪验证与原生资产分发实践

【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex

本文以 oh-my-codex 仓库中 0.9.0 发布就绪评审文档 为主线，完整还原一个携带 Rust 原生二进制的 CLI 项目在打 tag 前的验证闭环：评审范围界定、20 项冒烟与测试证据、版本同步机制、打包分发契约与风险注记。读完后你可以掌握一套可复用的“发布就绪（release readiness）”核查方法，并理解该项目“npm 包不带原生二进制、由 GitHub Release 资产按需水合（hydration）”的原生资产分发设计。

背景：0.9.0 要带什么上发布列车

就绪文档的头部信息给出了基本盘：日期 2026-03-12、目标版本0.9.0、本地结论GO，且版本 bump 完成后已在dev分支重跑通过发布门禁。文档的“评审范围（Scope reviewed）”列出了四个板块：

• v0.8.15之后未发布的dev工作；
• Spark Initiative相关能力面：
  • omx explore：默认只读探索入口；
  • omx sparkshell：Rust 驱动的 shell 检查 sidecar；
  • 符合条件的只读 shell 任务从 explore 路由到 sparkshell；
• 原生发布流水线工作：跨平台原生资产发布、发布清单（release manifest）生成、packed-install 冒烟门禁、build:full工作流验证；
• 0.9.0的发布说明与 QA 草稿产出（对应 docs/release-notes-0.9.0.md）。

这个范围不是空话，它直接对应仓库里的构建脚本。package.json 中的build:full定义为：

"build:full": "npm run build && npm run build:explore:release && npm run build:sparkshell && npm run build:api"

即 TypeScript 主构建、explore harness 发布构建、sparkshell 构建、api 构建四段串联——这正是文档中“build:fullworkflow validation”一项检查的落地对象。crates/omx-explore、crates/omx-sparkshell 等 Cargo 工作区成员则是cargo build -p omx-explore-harness、cargo build -p omx-runtime的构建目标。

验证证据清单：20 项检查全量继承

就绪文档的核心是一张 20 行的验证证据表，每一行都给出检查名、可复制命令和结果。下表完整保留原文档内容：

说明：表中命令为 0.9.0 评审时点的原始记录（入口为bin/omx.js、同步脚本为.mjs形式）；当前仓库中对应物已演进为dist/cli/omx.js入口与 src/scripts/check-version-sync.ts（编译后运行），检查语义保持一致。

版本同步检查到底查了什么

check-version-sync --tag v0.9.0这一项不是形式检查。从当前源码 src/scripts/check-version-sync.ts 可以看到它的完整判定逻辑：

1. 读取根目录package.json的version；
2. 用 TOML 解析根 Cargo.toml 的[workspace.package].version，要求两者相等；
3. 逐个检查omx-api、omx-explore、omx-runtime-core、omx-mux、omx-runtime、omx-sparkshell六个 crate 的Cargo.toml，必须声明version.workspace = true（防止某个 crate 的版本号被单独漂移）；
4. 若传了--tag v0.9.0，则断言 tag 必须精确等于v${package.json version}。

任何一条不满足都会打印[version-sync] ...并以非零码退出。这条门禁的意义在于：TS 侧包版本与 Rust 工作区版本、git tag 三者强绑定，杜绝“npm 装到 0.9.0、原生资产却按 0.8.x 清单解析”的错位。

打包冒烟：为什么npm pack --dry-run是发布级检查

package.json 的files字段显式列出打包内容（dist/、crates/、skills/、prompts/、templates/、src/scripts/、plugins/等），并带有!crates/**/.omx/**排除规则；同时prepack链最后一步是clean:native-package-assets，postpack再次执行清理。也就是说，npm 包刻意不包含已暂存的原生二进制——这解释了文档风险注记中“npm pack --dry-run保持绿色很重要，因为打包安装会故意排除 staged 原生二进制，真正的二进制必须由发布工作流以 GitHub Release 资产形式补齐”这句话。

配套的 packed-install 冒烟脚本是 src/scripts/smoke-packed-install.ts，其核心命令集定义为：

export const PACKED_INSTALL_SMOKE_CORE_COMMANDS = [ ['--help'], ['version'], ['api', '--help'], ['sparkshell', '--help'], ] as const;

即把真实 tarball 安装到隔离目录后，逐条执行核心命令验证产物可用。文档中npm pack --dry-run产出oh-my-codex-0.9.0.tgz这一行，与该脚本共同构成“打包形态”的双重验证：干跑验证清单完整性，冒烟脚本验证安装后行为。

分泳道测试：explore 与 sparkshell 为什么单独立道

npm run test:explore与npm run test:sparkshell在文档中各自独立报数（39 pass；Rust 套件32 + 11 + 5）。对照 package.json 脚本定义可以印证“泳道”的构成：

• test:explore=cargo test -p omx-explore-harness加三个 Node 测试文件（explore CLI、explore 路由、explore→sparkshell 引导契约）；
• test:sparkshell委托给 src/scripts/test-sparkshell.ts，驱动 crates/omx-sparkshell 下的 Rust 测试套件。

这种“Rust 套件 + 契约级 Node 测试”组合的方式，使得文档中 Explore 泳道 39 个用例、Sparkshell 泳道三组 Rust 套件通过这类精确数字成为可信的发布证据，而不是笼统的一句“测试通过”。

发布形态证据：用数字描述这次发布

文档的“Current release-shape evidence”一节用五个事实固化了发布形态：

• 当前包版本：0.9.0；
• 仓库内最新已有 git tag：v0.8.15；
• 当前分支：dev；
• 未发布头与 tag 的差距：55 个非合并提交；
• 未发布 diff：149 个文件变更，+12,325 / -254。

同窗口的 docs/release-notes-0.9.0.md 给出了相互印证的口径：提交窗口 2026-03-10 至 2026-03-12 的 55 个非合并提交、同样的 149 文件 / +12,325 / -254 快照，并列出代表性提交（如e8e7594只读 shell 任务经 sparkshell 路由、23d1cf5统一跨平台原生发布、559089f增加 packed install 冒烟门禁）。QA 草稿与发布说明使用同一组统计数字，本身就是“发布物料一致性”的证据。

原生分发契约：0.9.0 的第一风险面

文档风险注记第一条直言：“首要回归面是新的原生分发契约：hydration、fallback 顺序、跨平台资产解析。”结合源码可以把这句话展开成具体机制。

二进制解析的 fallback 顺序

src/cli/sparkshell.ts 定义了 sparkshell 原生二进制的候选路径族：

• 打包路径：bin/native/<platform>-<arch>[-<libc>]/omx-sparkshell（Linux 下按 musl/glibc 偏好展开多个候选）；
• 仓库本地构建路径：target/release/omx-sparkshell以及嵌套的native/omx-sparkshell/target/release/...；
• 环境覆盖：OMX_SPARKSHELL_BIN直接指定二进制（绝对路径或相对cwd解析）。

resolveSparkShellBinaryPath的判定顺序是：先看OMX_SPARKSHELL_BIN覆盖，再依次尝试水合缓存候选、打包产物、仓库本地构建。这与 docs/release-notes-0.9.0.md 中“运行时 fallback 顺序在 env 覆盖、水合缓存、打包产物、仓库本地构建之间保持显式”的表述一一对应。

水合（hydration）从哪里来

发布说明明确：npm 包不直接捆绑全部原生二进制；带 tag 的发布会发布omx-explore-harness与omx-sparkshell的跨平台原生归档；打包安装通过native-release-manifest.json从 GitHub Release 资产中水合匹配的二进制。package.json 中的verify:native-agents（对应 src/scripts/verify-native-agents.ts）与build:explore:release/build:sparkshell脚本，则分别承担清单校验与归档构建两端。文档“剩余发布动作”一节列出的 GitHub Actions 校验项——原生资产发布、原生资产清单校验、packed install 冒烟校验、npm publish——正是这条链路的四个闸门。

tmux-pane 摘要：操作者关键特性而非内部细节

风险注记第三条把omx sparkshell --tmux-pane定性为“团队调试的操作者关键特性”。从 src/cli/sparkshell.ts 的用法文案可以确认其参数契约：

Usage: omx sparkshell <command> [args...] or: omx sparkshell [--json] [--budget <chars>] <command> [args...] or: omx sparkshell --shell '<shell command>' or: omx sparkshell --tmux-pane <pane-id> [--tail-lines <100-1000>]

要点包括：shell 元字符仅在显式--shell时才被解释（默认走直接 argv 执行）；tmux pane 模式是显式 opt-in，先抓取更大的 pane 尾部再做原始/摘要处理；--tail-lines取值范围 100–1000（文档冒烟用例中的--tail-lines 120正落在该区间内）。此外还有相关环境变量：OMX_SPARKSHELL_MODEL/OMX_SPARKSHELL_FALLBACK_MODEL选择摘要与重试模型，OMX_SPARKSHELL_MODEL_INSTRUCTIONS_FILE覆盖打包摘要指令，OMX_SPARKSHELL_SUMMARY_TIMEOUT_MS控制本地 API 摘要超时。这些细节说明该命令被当作面向操作者的正式接口来维护，与文档风险注记的定位一致。

explore 的刻意约束

风险注记第二条要求“在 sparkshell 路由启用期间，持续检查 shell-only / read-only 边界保持完整”。从当前仓库的 src/cli/explore.ts 结构可以看到这条约束的最终走向：在后续版本中omx explore的直接命令面已被硬弃用（hard-deprecated），帮助文案明确引导用户“对只读仓库查找使用常规 Codex 检查工具，仅在显式 shell 只读取证或--tmux-pane摘要时使用omx sparkshell -- <command>”。可以推断，0.9.0 评审时“保持边界完整”的要求，正是该表面最终收敛为 sparkshell 单一路径的伏笔；同时该文件中的 Windows 说明也印证了原生 harness 依赖 POSIX sh/bash 包装这一跨平台限制，与文档中“Linux 冒烟无法直接验证 Windows 运行时行为”的注记同源。

剩余发布动作与风险注记

文档在给出 GO 结论前，仍单列了“剩余发布动作（Remaining release actions）”，即本地验证之外、必须在 tag 之后完成的闭环：

• 打 tagv0.9.0，并确认 GitHub Actions 发布任务全部完成：
  • 原生资产发布；
  • 原生资产清单校验；
  • packed install 冒烟校验；
  • npm publish；
• 使用 docs/release-notes-0.9.0.md 发布 GitHub Release。

对应的五条风险注记原文如下，它们构成该版本发布后的观察清单：

1. 首要回归面是新的原生分发契约：hydration、fallback 顺序、跨平台资产解析；
2. omx explore是刻意受限的，发布验证应持续确认 shell-only / read-only 边界在 sparkshell 路由启用下依然完整；
3. omx sparkshell --tmux-pane是团队调试的操作者关键项，pane 摘要行为应按“面向发布的特性”对待，而非隐藏内部细节；
4. npm pack --dry-run保持绿色很重要，因为打包安装刻意排除 staged 原生二进制，发布工作流必须通过 GitHub Release 资产补齐这些二进制；
5. 跨平台 Windows 专项修复已落在发布窗口内，但 Linux 冒烟无法直接验证 Windows 运行时行为，仍需 CI / 发布矩阵确认。

其中第 4 条与前文打包分析呼应，第 5 条则明确了“本地证据边界”：本地冒烟只覆盖当前平台，Windows 结论被显式外推给 CI 矩阵，避免了把单平台绿灯误读为全平台绿灯。

最终结论与可复用的核查清单

文档的“Final local verdict”只有一句话：基于上述本地 post-bump 验证，0.9.0 已具备 tag 与发布条件。把它拆开看，这份就绪文档示范了一个可复用的发布核查骨架：

1. 范围先行：明确评审的是哪个 tag 到 dev 的窗口（v0.8.15..dev），并点名新特性面与流水线工作，避免“全量泛查”；
2. 证据可复制：每项验证都给出精确命令与精确结果数字（2375 pass / 0 fail、39 pass、32 + 11 + 5），让第三方可原样复跑；
3. 形态固化：用包版本、最新 tag、分支、非合并提交数、diff 统计五个数字钉死发布形态，并与发布说明共享同一数据源；
4. 风险显式化：把“本地验证覆盖不到的部分”（Windows 运行时、发布后 CI 闸门）写成风险注记而非默认安全；
5. 动作与结论分离：GO 结论只覆盖本地验证，tag 之后的原生资产发布、清单校验、冒烟校验、npm publish 单列为剩余动作，不被结论提前吞并。

对维护者而言，这套流程的适用前提是项目同时存在 TypeScript 与 Cargo 双栈（需要版本三同步）、且 npm 包依赖外部 Release 资产提供原生二进制（需要 packed-install 冒烟与水合链路验证）；oh-my-codex 0.9.0 的这次评审恰好完整覆盖了这两个前提下的全部检查点。

【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex