oh-my-codex 发布副作用守卫实践以 0.15.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 仓库中的发布副作用守卫Release Side-Effect Guard验证记录 release-no-publish-0.15.0.md完整讲解在发布准备阶段如何证明代码已经准备好了但没有任何副作用被提前触发。你将掌握一套可复制的检查方法用 git 命令审计标签状态、用文件存在性校验残留产物、用日志审计确认没有执行发布命令并用 lint、类型检查、构建与定向测试构成验证门verification gates。这套方法适用于任何采用tag 触发发布模式的 npm GitHub Actions 项目。一、为什么要做发布副作用守卫在 oh-my-codex 的发布流程中真正的发布动作npm publish、GitHub Release 附件上传不是由本地命令触发的而是由仓库根目录的 .github/workflows/release.yml 通过push.tags: v*条件触发的。这意味着只要没有推送 v 开头的 tag发布工作流就不会运行。发布准备release prep阶段的工作通常包括修改版本号、更新 CHANGELOG、生成发布说明、跑验证门。这个阶段最大的风险是准备过程中顺手做了发布动作例如本地误打 tag、误执行npm publish、遗留打包产物。0.15.0 发布准备记录正是针对这一风险设立的一次专项守卫验证由worker-4执行目标明确验证发布准备没有创建 tag也没有发布 npm/GitHub 发布产物。仓库内的发布协议 RELEASE_PROTOCOL.md 也印证了这一点协议第 5 节明确要求只有当发布物料release collateral完成后才能创建并推送 tag且docs/qa/release-readiness-0.15.0.md的结论写明不要打 tag 或发布v0.15.0直到 GitHub CI 变绿且维护者有意执行 tag/publish 流程。副作用守卫就是这一协议的落地执行证明。二、证据清单逐项验证无发布副作用0.15.0 副作用守卫的第一部分是证据表用可复现的命令逐项证明发布准备期间没有产生副作用。每一项都是先记录观察到的前置证据再运行只读检查命令最后给出 PASS 结论。1. 前置提交基线git rev-parse HEAD执行结果b5b6d13134eb86ecda2d9021cc83c0995f943ebe这是发布准备开始前的工作树提交。它和 release-readiness-0.15.0.md 中记录的候选源 SHAcandidate source SHA完全一致说明后续所有验证都是基于同一个明确的提交基线展开的。记录基线是副作用审计的第一步没有基线就无法判断哪些操作是我做的、哪些是原本就存在的。2. 候选提交上没有指向的 release taggit tag --points-at HEAD结果PASS无任何 tag 输出。这条命令检查是否有 tag 恰好指向当前 HEAD。在 tag 触发发布的模式下如果候选提交上已经存在 tag一旦推送就可能直接触发发布工作流因此这是最关键的守卫项。3. 不存在本地v0.15.0taggit tag -l v0.15.0结果PASS无任何 tag 输出。-l是列表匹配模式精确匹配目标版本号。即使候选提交上没有 tag仓库中如果存在同名 tag 也会构成风险可能被误推送或误导发布范围。4. 根目录打包产物未残留test ! -e oh-my-codex-0.15.0.tgz结果PASS根目录生成的 tarball 已从受跟踪的发布准备中移除。这条值得展开npm 打包npm pack会在包根目录生成oh-my-codex-version.tgz文件。发布准备过程中npm pack --json的产物如果留在工作树中就可能被误提交或被后续流程当作发布证据。test ! -e用退出码表示文件不存在存在则退出码为 1检查失败。在 release-readiness-0.15.0.md 的已知限制中也明确记录Ralph 于 2026-04-26 修复了npm pack --json解析问题prepack 的sync-plugin-mirror日志行会混入最终 JSON 数组之前并删除了生成的根目录oh-my-codex-0.15.0.tgztarball。这解释了为什么守卫检查中这个文件必须不存在。5. 发布工作流保持 tag 触发未被本地调用grep -RIn npm publish\|softprops/action-gh-release\|on:\|tags: .github/workflows/release.yml结果PASSpublish/release 步骤仍位于 tag 触发的发布工作流内且没有任何工作流被本地执行过。从仓库当前内容看release.yml 的触发条件确实是on: push: tags: - v*其中softprops/action-gh-releasev3第 222 行负责把原生资产附加到 GitHub Release而 npm 发布依赖npm publish命令两者都被约束在这个 tag 触发的工作流内。守卫检查确认 grep 结果中这些步骤仍然待在工作流内部而不是被抽出来单独执行。6. 本地命令审计检查 Worker/Ralph 命令日志结果 PASS没有执行过git tag、git push --tags或npm publish。这是最后一道兜底防线。即使文件系统状态看起来干净也要从命令执行日志确认操作者没有跑过发布命令。它和前面 5 项形成了状态检查 行为审计的闭环。三、验证门发布准备本身要过的质量关卡副作用守卫只证明没乱发布但不能证明代码是好的。因此worker-4还跑了一组验证门确保发布准备提交本身是可发布的门命令结果Lintnpm run lintPASSChecked 553 files in 801ms. No fixes applied.类型检查npm run check:no-unusedPASS构建npm run buildPASS发布工作流定向测试node --test dist/verification/__tests__/explore-harness-release-workflow.test.jsPASS3 个测试通过全量测试套件npm testFAIL/INCOMPLETE1. Lint 与类型检查npm run lint对应 package.json 中的biome lint src检查 553 个文件、无修复项npm run check:no-unused对应tsc -p tsconfig.no-unused.json在常规编译之外额外开启 noUnusedLocals/noUnusedParameters 类检查。两者都干净通过说明发布准备的代码改动没有引入风格或死代码问题。2. 构建npm run build在 package.json 中的定义是先rm -rf dist清理旧产物再执行tsc编译最后chmod 755赋予 CLI 入口可执行权限。构建通过意味着dist/下的产物与源码一致这也是后续所有node --test dist/...测试能够运行的前提。3. 发布工作流定向测试这是本守卫文档最有价值的验证门node --test dist/verification/__tests__/explore-harness-release-workflow.test.js3 个测试全部通过。对应的源码测试位于 src/verification/tests/explore-harness-release-workflow.test.ts。这个测试文件通过读取真实的.github/workflows/release.yml文本并做断言assert.match / assert.doesNotMatch从源码层面固化了发布工作流不允许 npm 发布的契约必须匹配push:\n tags:的 tag 触发结构必须包含verify-version-sync、publish-native-assets、smoke-verify-native、smoke-packed-install等阶段明确禁止出现npm publish、NODE_AUTH_TOKEN、NPM_TOKEN、publish-npm:等 npm 发布痕迹第 71-75 行断言资产上传Attach native assets to GitHub Release必须位于验证Verify release archives and manifest之后且默认success()条件不被改写——即验证失败时不得上传发布资产第 111-114 行。这个测试的存在意味着发布流程不发布 npm 包、只发布原生资产不是一个口头约定而是被持续集成守护的代码事实。副作用守卫文档中单列此测试作为验证门正是用它来确认发布工作流的结构没有被发布准备过程意外破坏。4. 全量测试套件的失败分析npm test出现 FAIL/INCOMPLETE原因被明确标注为与环境敏感的无关失败omx ask、explore harness 水合/路由、detached tmux、cross-rebase、mailbox bridge 等测试出现失败随后工具输出丢失。文档强调worker-4 没有改动这些区域。这是副作用守卫记录中很重要的一点它不是隐瞒失败而是区分失败是否由本次发布准备的改动引起。这类环境敏感失败tmux 会话隔离、活跃本地 Ralph 干扰等在 release-readiness-0.15.0.md 中被同样记录为剩余风险是全量套件在活跃本地 Ralph 下的 tmux/session 隔离并明确远程 CI 仍是全量套件的最终仲裁者。也就是说本地全量套件受环境干扰失败不应被误读为发布准备本身的质量问题但也不意味着可以直接忽略——最终发布前仍需远程 CI 作为仲裁。四、结论Verdict 与发布边界文档最终给出明确裁决发布准备保持无副作用没有创建本地发布 tag工作树中不存在v0.15.0tag没有 tag 指向候选提交没有执行 npm publish 命令生成的根目录打包 tarball 已从受跟踪的发布准备中移除。这段结论与 RELEASE_PROTOCOL.md 第 5 节发布顺序完全对齐合并候选到main→ 等待mainCI 变绿 → 完成发布物料后创建并推送 annotated tag → 等待 tag 触发的发布工作流通过 → 验证 GitHub Release 与 npm 版本。副作用守卫证明的是准备工作完成了前半段而 tag/publish 是维护者后续有意执行的独立步骤。五、把副作用守卫沉淀为可复用清单从这次 0.15.0 的实践可以提炼出一套通用的发布准备副作用守卫检查清单任何 npm GitHub Actions 项目都适用固定基线git rev-parse HEAD记录准备前的提交 SHA并与发布就绪文档中的候选 SHA 交叉核对。状态审计只读命令git tag --points-at HEAD候选提交上无 taggit tag -l v版本号目标版本无同名 tagtest ! -e 包名-版本.tgz无打包产物残留git status --short工作树无意外改动。工作流结构审计grep 发布工作流确认npm publish、softprops/action-gh-release等步骤仍位于 tag 触发的on.push.tags内部。行为审计检查命令日志确认未执行git tag、git push --tags、npm publish。质量验证门跑 lint、类型检查、构建、以及发布工作流的定向契约测试如果仓库中存在类似explore-harness-release-workflow.test.ts的测试全量测试失败时先判断是否属于环境敏感区域最终以远程 CI 为仲裁。留下结论把证据表、验证门与 Verdict 写入docs/qa/下的记录文档形成可追溯的审计痕迹。这套方法的核心思想是发布准备与发布执行是两件必须分开的事情。准备工作负责代码和物料到位发布动作则完全交给 tag 触发的 CI 工作流。副作用守卫不是不信任开发者而是用可复现的证据让没有副作用这件事本身变得可验证、可追溯。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 oh-my-codex 发布副作用守卫实践：以 0.15.0 发布准备为例验证“只准备、不发布“
oh-my-codex 发布副作用守卫实践以 0.15.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 仓库中的发布副作用守卫Release Side-Effect Guard验证记录 release-no-publish-0.15.0.md完整讲解在发布准备阶段如何证明代码已经准备好了但没有任何副作用被提前触发。你将掌握一套可复制的检查方法用 git 命令审计标签状态、用文件存在性校验残留产物、用日志审计确认没有执行发布命令并用 lint、类型检查、构建与定向测试构成验证门verification gates。这套方法适用于任何采用tag 触发发布模式的 npm GitHub Actions 项目。一、为什么要做发布副作用守卫在 oh-my-codex 的发布流程中真正的发布动作npm publish、GitHub Release 附件上传不是由本地命令触发的而是由仓库根目录的 .github/workflows/release.yml 通过push.tags: v*条件触发的。这意味着只要没有推送 v 开头的 tag发布工作流就不会运行。发布准备release prep阶段的工作通常包括修改版本号、更新 CHANGELOG、生成发布说明、跑验证门。这个阶段最大的风险是准备过程中顺手做了发布动作例如本地误打 tag、误执行npm publish、遗留打包产物。0.15.0 发布准备记录正是针对这一风险设立的一次专项守卫验证由worker-4执行目标明确验证发布准备没有创建 tag也没有发布 npm/GitHub 发布产物。仓库内的发布协议 RELEASE_PROTOCOL.md 也印证了这一点协议第 5 节明确要求只有当发布物料release collateral完成后才能创建并推送 tag且docs/qa/release-readiness-0.15.0.md的结论写明不要打 tag 或发布v0.15.0直到 GitHub CI 变绿且维护者有意执行 tag/publish 流程。副作用守卫就是这一协议的落地执行证明。二、证据清单逐项验证无发布副作用0.15.0 副作用守卫的第一部分是证据表用可复现的命令逐项证明发布准备期间没有产生副作用。每一项都是先记录观察到的前置证据再运行只读检查命令最后给出 PASS 结论。1. 前置提交基线git rev-parse HEAD执行结果b5b6d13134eb86ecda2d9021cc83c0995f943ebe这是发布准备开始前的工作树提交。它和 release-readiness-0.15.0.md 中记录的候选源 SHAcandidate source SHA完全一致说明后续所有验证都是基于同一个明确的提交基线展开的。记录基线是副作用审计的第一步没有基线就无法判断哪些操作是我做的、哪些是原本就存在的。2. 候选提交上没有指向的 release taggit tag --points-at HEAD结果PASS无任何 tag 输出。这条命令检查是否有 tag 恰好指向当前 HEAD。在 tag 触发发布的模式下如果候选提交上已经存在 tag一旦推送就可能直接触发发布工作流因此这是最关键的守卫项。3. 不存在本地v0.15.0taggit tag -l v0.15.0结果PASS无任何 tag 输出。-l是列表匹配模式精确匹配目标版本号。即使候选提交上没有 tag仓库中如果存在同名 tag 也会构成风险可能被误推送或误导发布范围。4. 根目录打包产物未残留test ! -e oh-my-codex-0.15.0.tgz结果PASS根目录生成的 tarball 已从受跟踪的发布准备中移除。这条值得展开npm 打包npm pack会在包根目录生成oh-my-codex-version.tgz文件。发布准备过程中npm pack --json的产物如果留在工作树中就可能被误提交或被后续流程当作发布证据。test ! -e用退出码表示文件不存在存在则退出码为 1检查失败。在 release-readiness-0.15.0.md 的已知限制中也明确记录Ralph 于 2026-04-26 修复了npm pack --json解析问题prepack 的sync-plugin-mirror日志行会混入最终 JSON 数组之前并删除了生成的根目录oh-my-codex-0.15.0.tgztarball。这解释了为什么守卫检查中这个文件必须不存在。5. 发布工作流保持 tag 触发未被本地调用grep -RIn npm publish\|softprops/action-gh-release\|on:\|tags: .github/workflows/release.yml结果PASSpublish/release 步骤仍位于 tag 触发的发布工作流内且没有任何工作流被本地执行过。从仓库当前内容看release.yml 的触发条件确实是on: push: tags: - v*其中softprops/action-gh-releasev3第 222 行负责把原生资产附加到 GitHub Release而 npm 发布依赖npm publish命令两者都被约束在这个 tag 触发的工作流内。守卫检查确认 grep 结果中这些步骤仍然待在工作流内部而不是被抽出来单独执行。6. 本地命令审计检查 Worker/Ralph 命令日志结果 PASS没有执行过git tag、git push --tags或npm publish。这是最后一道兜底防线。即使文件系统状态看起来干净也要从命令执行日志确认操作者没有跑过发布命令。它和前面 5 项形成了状态检查 行为审计的闭环。三、验证门发布准备本身要过的质量关卡副作用守卫只证明没乱发布但不能证明代码是好的。因此worker-4还跑了一组验证门确保发布准备提交本身是可发布的门命令结果Lintnpm run lintPASSChecked 553 files in 801ms. No fixes applied.类型检查npm run check:no-unusedPASS构建npm run buildPASS发布工作流定向测试node --test dist/verification/__tests__/explore-harness-release-workflow.test.jsPASS3 个测试通过全量测试套件npm testFAIL/INCOMPLETE1. Lint 与类型检查npm run lint对应 package.json 中的biome lint src检查 553 个文件、无修复项npm run check:no-unused对应tsc -p tsconfig.no-unused.json在常规编译之外额外开启 noUnusedLocals/noUnusedParameters 类检查。两者都干净通过说明发布准备的代码改动没有引入风格或死代码问题。2. 构建npm run build在 package.json 中的定义是先rm -rf dist清理旧产物再执行tsc编译最后chmod 755赋予 CLI 入口可执行权限。构建通过意味着dist/下的产物与源码一致这也是后续所有node --test dist/...测试能够运行的前提。3. 发布工作流定向测试这是本守卫文档最有价值的验证门node --test dist/verification/__tests__/explore-harness-release-workflow.test.js3 个测试全部通过。对应的源码测试位于 src/verification/tests/explore-harness-release-workflow.test.ts。这个测试文件通过读取真实的.github/workflows/release.yml文本并做断言assert.match / assert.doesNotMatch从源码层面固化了发布工作流不允许 npm 发布的契约必须匹配push:\n tags:的 tag 触发结构必须包含verify-version-sync、publish-native-assets、smoke-verify-native、smoke-packed-install等阶段明确禁止出现npm publish、NODE_AUTH_TOKEN、NPM_TOKEN、publish-npm:等 npm 发布痕迹第 71-75 行断言资产上传Attach native assets to GitHub Release必须位于验证Verify release archives and manifest之后且默认success()条件不被改写——即验证失败时不得上传发布资产第 111-114 行。这个测试的存在意味着发布流程不发布 npm 包、只发布原生资产不是一个口头约定而是被持续集成守护的代码事实。副作用守卫文档中单列此测试作为验证门正是用它来确认发布工作流的结构没有被发布准备过程意外破坏。4. 全量测试套件的失败分析npm test出现 FAIL/INCOMPLETE原因被明确标注为与环境敏感的无关失败omx ask、explore harness 水合/路由、detached tmux、cross-rebase、mailbox bridge 等测试出现失败随后工具输出丢失。文档强调worker-4 没有改动这些区域。这是副作用守卫记录中很重要的一点它不是隐瞒失败而是区分失败是否由本次发布准备的改动引起。这类环境敏感失败tmux 会话隔离、活跃本地 Ralph 干扰等在 release-readiness-0.15.0.md 中被同样记录为剩余风险是全量套件在活跃本地 Ralph 下的 tmux/session 隔离并明确远程 CI 仍是全量套件的最终仲裁者。也就是说本地全量套件受环境干扰失败不应被误读为发布准备本身的质量问题但也不意味着可以直接忽略——最终发布前仍需远程 CI 作为仲裁。四、结论Verdict 与发布边界文档最终给出明确裁决发布准备保持无副作用没有创建本地发布 tag工作树中不存在v0.15.0tag没有 tag 指向候选提交没有执行 npm publish 命令生成的根目录打包 tarball 已从受跟踪的发布准备中移除。这段结论与 RELEASE_PROTOCOL.md 第 5 节发布顺序完全对齐合并候选到main→ 等待mainCI 变绿 → 完成发布物料后创建并推送 annotated tag → 等待 tag 触发的发布工作流通过 → 验证 GitHub Release 与 npm 版本。副作用守卫证明的是准备工作完成了前半段而 tag/publish 是维护者后续有意执行的独立步骤。五、把副作用守卫沉淀为可复用清单从这次 0.15.0 的实践可以提炼出一套通用的发布准备副作用守卫检查清单任何 npm GitHub Actions 项目都适用固定基线git rev-parse HEAD记录准备前的提交 SHA并与发布就绪文档中的候选 SHA 交叉核对。状态审计只读命令git tag --points-at HEAD候选提交上无 taggit tag -l v版本号目标版本无同名 tagtest ! -e 包名-版本.tgz无打包产物残留git status --short工作树无意外改动。工作流结构审计grep 发布工作流确认npm publish、softprops/action-gh-release等步骤仍位于 tag 触发的on.push.tags内部。行为审计检查命令日志确认未执行git tag、git push --tags、npm publish。质量验证门跑 lint、类型检查、构建、以及发布工作流的定向契约测试如果仓库中存在类似explore-harness-release-workflow.test.ts的测试全量测试失败时先判断是否属于环境敏感区域最终以远程 CI 为仲裁。留下结论把证据表、验证门与 Verdict 写入docs/qa/下的记录文档形成可追溯的审计痕迹。这套方法的核心思想是发布准备与发布执行是两件必须分开的事情。准备工作负责代码和物料到位发布动作则完全交给 tag 触发的 CI 工作流。副作用守卫不是不信任开发者而是用可复现的证据让没有副作用这件事本身变得可验证、可追溯。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考