企业官网建设流程全解析

OmX 受约束发布实战：用 Ultragoal 工作流决策、验证并安全交接 oh-my-codex 0.18.13

【免费下载链接】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（OmX）仓库 .gjc/ultragoal/brief.md 记录的 0.18.13 发布任务为完整案例，讲解如何借助 OmX 的 Ultragoal 工作流，在“不 tag、不 publish、不 push、不 merge，直到验证干净”的硬约束下，完成发布版本决策、发布产物准备、候选版本验证与 Dogfood，以及安全发布交接四个阶段。读完本文，你将掌握一套可复制的受约束发布决策方法：如何用证据判定 patch（0.18.13）还是 minor（0.19.0）、如何把每次验证固化为可审计的日志与票据，以及如何把不可逆操作安全地移交给维护者。

为什么发布决策需要“受约束的自动执行”

发布是不可逆操作：一旦推送 tag、触发 GitHub Release 工作流、发布 npm 包，回滚代价极高。OmX 仓库为此在 RELEASE_PROTOCOL.md 中建立了强制协议，而 .gjc/ultragoal/brief.md 正是将该协议固化为一份可执行任务简报（brief）的实例。

简报的开头一句话即定义了全局约束：

Release 0.18.13 after all verification and dogfooding are complete. Choose 0.19.0 only if repository evidence shows breaking/public API changes requiring a minor release; otherwise prepare and release 0.18.13 as the next patch after 0.18.12. Do not tag, publish, push, merge, or perform irreversible release actions until verification is clean and the final release action is explicitly safe from repository context.

这句话包含两个关键机制：

• 版本决策规则前置：默认发布 0.18.13（patch），只有当仓库证据显示存在破坏性/公共 API 变更需要 minor 版本时才升级为 0.19.0。决策依据是“repository evidence”，而非记忆或直觉。
• 不可逆操作红线：tag / publish / push / merge 均被明令禁止，直到验证干净且最终发布动作从仓库上下文中被明确判定为安全。

这份 brief 随后被拆解为四个@goal段落（G001–G004），由 Ultragoal 工作流逐项执行并留痕。这正是 OmX“Your codex is not alone”理念在发布场景的体现：让 Codex 目标模式（goal mode）配合仓库本地持久化产物，形成可审计的多目标执行闭环。

Ultragoal 工作流与三件套持久化产物

Ultragoal 是 OmX 内置的“仓库原生多目标工作流”，定义于 skills/ultragoal/SKILL.md：在 Codex/goal目标模式之上，将复杂任务拆成多个 story，并落盘到仓库内形成持久、可审计的执行计划。本案例对应的持久化产物正是.gjc/下的三件套：

从 src/cli/ultragoal.ts 的帮助文本可以看到完整的命令面：

• omx ultragoal create-goals --brief "<text>"/--brief-file <path>/--from-stdin：从简报创建计划，默认使用 aggregate 目标模式（一个 Codex 目标覆盖整个 run，OMX 在账本中逐个 checkpoint story）。
• omx ultragoal complete-goals [--retry-failed]：推进执行并输出面向模型的手交接说明（何时安全调用get_goal/create_goal/update_goal）。
• omx ultragoal checkpoint --goal-id <id> --status complete|failed|blocked --evidence "<text>"：在账本中为单个 story 打点。
• omx ultragoal steer --kind <add_subgoal|split_subgoal|...>：结构化显式转向，普通自然语言不会改动计划。
• omx ultragoal status --json：查看聚合完成度。

执行节奏遵循 skills/ultragoal/SKILL.md 的循环：运行complete-goals→ 读取交接 → 完成一个 story → 用真实产物与验证证据审计目标 → checkpoint；被阻塞的 story 以--status blocked记录，失败任务用--retry-failed续跑；最终 story 必须先通过最终质量门（ai-slop-cleaner、验证、code-review 独立评审、架构不变量审计），再用--quality-gate-json固化证据后 checkpoint。本案例的 .gjc/ultragoal/quality-gate-g001.json 正是这类质量门证据的实例。

第一关：版本与范围决策（G001）

G001 的目标是“确定发布版本与范围”，对应简报中的第一个@goal：

Inspect package metadata, changelog/release notes history, current repository changes, and recent commits/PR evidence to decide whether this is 0.18.13 or 0.19.0, and define the release scope.

决策规则与证据面

从 .gjc/ultragoal/goals.json 的 G001 记录可以看到，决策围绕四个证据面（surface）展开：

1. 包元数据基线：读取package.json、Cargo.toml，并与v0.18.12对比，确认当前基线版本。
2. 发布历史：阅读 CHANGELOG.md、docs/release-notes-0.18.12.md、docs/qa/release-readiness-0.18.12.md，对 patch 与 minor 范围分类。
3. 仓库差异：git log / diff / tag拓扑检查，划定v0.18.12..HEAD的实际变更。
4. 开放 PR / Issue 清单：检查当前开放的 PR 与 Issue，判断是否存在升级为 minor 或阻塞 patch 的内容。

RELEASE_PROTOCOL.md 给出了配套的命令级方法：用git merge-base --is-ancestor "$PREV" "$CANDIDATE"验证前一 tag 是候选提交的祖先；用git log --oneline --decorate "$PREV..$CANDIDATE"生成提交清单；再交叉核对 compare 范围内每个合并提交 / PR 是否进入发布说明或被显式标记为内部-only。

反例（adversarial）测试思维

G001 最值得借鉴的是它的“证伪”机制——用四个反例用例反向检验决策：

• breaking-contract：寻找 package bin/engine 变更、被移除的活跃命令、不兼容 schema 或破坏性公共 API；只要出现任一，就应推荐 0.19.0 或阻止 patch 决策。
• major-feature：评估新增的会话发现与 geobench 文档/spec 是否构成新的主工作流或不兼容公共契约；只有构成时才升级 minor。
• open-pr-escalation：检查开放 PR/Issue 是否改变发布范围或阻塞 0.18.13。
• topology-hazard：由于v0.18.12指向 main 的 promotion 提交而dev与origin/main共享更早的 merge-base，需要用--cherry-pick视角避免把 cherry 等价的 0.18.12 准备提交误算为 0.18.13 的新功能。

最终结论

G001 的结论是选择0.18.13：包元数据停留在 0.18.12、最新发布 tag 为v0.18.12、发布后 dev 差异均为保持兼容的修复 / CI / 文档 / 依赖升级 / 增量会话与 setup 工作、未发现破坏性 package/bin/engine/schema 或已移除的活跃命令、开放 Issue 清单为空、开放 PR 均为 fix/docs/warning/safety 范围。执行端 QA/红队子代理1-ReleaseScopeQa与架构师评审子代理2-ReleaseScopeArchitectFast独立批准 0.18.13 而非 0.19.0。整个过程记录在 .gjc/ultragoal/ledger.jsonl 的goal_checkpointed事件中，含完整的e2eCommands、redTeamCommands、surfaceEvidence与adversarialCases结构。

第二关：发布产物准备（G002）

G002 的目标是“为选定版本更新所有版本化发布产物”，对应简报第二个@goal：

Update versioned release artifacts for the selected version, including package metadata, changelog, release notes, readiness evidence, and any generated catalogs or mirrored bundles required by repository conventions.

版本元数据同步

G002 通过npm version --no-git-tag-version 0.18.13并手工同步 Rust 与插件版本，将以下文件对齐到 0.18.13：

• 根package.json与package-lock.json；
• 根 Cargo.toml 工作区包版本与根 Cargo.lock（涉及omx-api、omx-explore-harness、omx-mux、omx-runtime、omx-runtime-core、omx-sparkshell）；
• 插件元数据（plugins/oh-my-codex/.codex-plugin/plugin.json）；
• 生成目录镜像：src/catalog/manifest.json 与 templates/catalog-manifest.json。

同步后用node dist/scripts/check-version-sync.js --tag v0.18.13校验，输出package=0.18.13 workspace=0.18.13 tag=v0.18.13即为 PASS。

发布配套产物

按 RELEASE_PROTOCOL.md 的要求，必须更新四份文件：CHANGELOG.md、docs/release-notes-<version>.md、docs/qa/release-readiness-<version>.md、RELEASE_BODY.md。本案例对应产出为 docs/release-notes-0.18.13.md 与 docs/qa/release-readiness-0.18.13.md。发布说明至少包含五个板块：Highlights、Fixes/compatibility、合并 PR 清单（含 PR 编号）、验证证据、完整 changelog 对比范围。若发布涉及$ultragoal、$ralph、$team、wiki、setup、原生 hooks、MCP 状态或 Codex goal 模式等主要工作流变更，即使最终阻塞修复无关，也必须出现在 Highlights。

G002 的反例用例包括：stale-version（扫描版本承载文件中残留的 0.18.12 当前版本）、publication-claim（发布配套不得暗示 GitHub Release 或 npm 发布已完成）、generated-mismatch（插件镜像与生成目录必须与 SSOT 元数据一致）、readiness-claims（所有 PASS 勾选必须有持久化日志支撑）。其中npm run build、verify:native-agents、verify:plugin-bundle、generate-catalog-docs.js --check、git diff --check的完整转录被固化到artifacts/release-0.18.13/logs/下，构成可复查的验证日志。

第三关：候选版本验证与 Dogfood（G003）

G003 的目标是“运行发布就绪所需的聚焦与全量验证通道，并 dogfood 构建产物”，对应简报：

Run the focused and full verification lanes required for release readiness, including dogfooding the built CLI/package surfaces enough to prove the release candidate works.

全量与聚焦验证通道

从 .gjc/ultragoal/goals.json 的 G003 记录可见，验证分为四组：

• 全量编译 CI 等价门：npm run test:ci:compiled完整跑通原生 agent 验证、插件 bundle 验证、全量编译 node 测试套件与目录文档检查。首次运行曾出现一次时序敏感的 process-tree 失败，随后隔离复跑 process-tree 套件通过，再干净重跑全量门，最终日志test-ci-compiled-rerun.log无失败标记。
• 聚焦变更面测试：node dist/scripts/run-test-files.js focused release files，覆盖 session/setup/hook/workflow 变更面，并修复了 session-search 测试的隔离性泄漏。
• 静态与打包门：npm run check:no-unused（tsc -p tsconfig.no-unused.json）、npm pack --dry-run（产出oh-my-codex-0.18.13.tgz）、git diff --check（无空白错误）。
• Dogfood：用构建产物实测node dist/cli/omx.js --version、node dist/cli/omx.js session search --help、包元数据版本导入，以及npm run smoke:packed-install打包安装冒烟。

G003 的反例用例尤其体现了诚实边界：full-suite-flake（早期 process-tree 抖动不得让全量门“非绿放行”）、focused-tests（聚焦日志必须显示 fail 0）、doctor-caveat（omx doctordogfood 暴露的 user-home hook 迁移问题被如实归类为环境状态而非候选版本缺陷，不宣称 doctor 全绿）、publication-overclaim（本地验证不得冒充 PR/tag/GitHub/npm 证明）。

第四关：安全发布交接（G004）

G004 的目标是“产出最终发布就绪交接，列出剩余不可逆发布动作”，对应简报：

Produce the final release readiness handoff with exact verification evidence and identify the remaining irreversible release command(s) that require maintainer execution or explicit approval.

交接内容与证据映射

最终交接以 docs/qa/release-readiness-0.18.13.md 为主记录，包含：

• 范围与拓扑：前一 tagv0.18.12、候选分支dev、冻结候选提交、compare 范围v0.18.12..HEAD及 promotion 拓扑注意事项。
• 版本决策与 PR 清单：14 个合并 PR/提交（#2846 项目 resume/search 发现、#2845 CI 迁移 GitHub-hosted runners、#2843 hooks JSON 状态兼容、#2836 清理时保留项目 Codex 转录、#2833/#2832 依赖升级、#2824 sidecar 状态根对齐等）与 4 个开放 PR。
• 本地验证证据：从版本同步、构建、原生代理验证、插件 bundle、目录文档检查、聚焦测试、CLI/包 dogfood、npm pack --dry-run（含机器可读 JSON 指标）、git diff --check到全量编译 CI 等价门，全部映射到artifacts/release-0.18.13/logs/下的具体日志文件。
• 剩余不可逆动作清单：PR/push、CI、dev→main 提升、经批准的 tag push、tag 触发的 GitHub Release 工作流与原生资产清单、经批准的 npm 发布，以及发布后证明捕获。

发布边界纪律

G004 反复强调一个原则：发布边界不越权。本地 release-prep 证据 ≠ 已发布证明；PR CI、dev/main 提升 CI、tag 工作流、GitHub Release 证明、npm 证明在缺少外部证据前一律保持 pending，绝不勾选。反例用例publication-overclaim、missing-release-actions、log-mismatch、doctor-caveat分别对应“不冒充发布完成”“交接必须列全剩余动作”“PASS 声明必须有具体日志”“dogfood 缺陷必须如实披露”。最终架构师评审13-ReleaseHandoffReviewCorrected与执行 QA11-ReleaseHandoffQa均无阻塞，发布交接完成，但“发布动作本身仍留给维护者显式批准”。

仓库中的发布协议与工具支撑

Ultragoal 发布流程并非孤例，而是与仓库的发布基础设施深度咬合：

• RELEASE_PROTOCOL.md 七步协议：冻结 compare 范围 → 基于证据而非记忆写发布说明 → 在打 tag 前校验 GitHub Release body → 发布就绪门 → 发布序列（merge main → main CI 绿 → annotated tag → tag 触发工作流 → 验证 GitHub release / 原生资产 / npm 版本 → dev 快进 → 立即把 dev 元数据 bump 到下一个开发基线）→ 发布后修正规则 → 停止条件。
• src/scripts/generate-release-body.ts：消费 RELEASE_BODY.md 模板生成 GitHub Release body，要求包含## Contributors、完整的 compare 范围变更与正确的**Full Changelog**行，并审查贡献者名单与合并 PR 作者一致。
• package.json 验证脚本族：test:ci:compiled、verify:native-agents、verify:plugin-bundle、verify:capabilities-lock、verify:prompt-guidance、smoke:packed-install等，构成了发布就绪门可复用的命令面。

可复用的受约束发布决策方法论

以 0.18.13 为案例，可以将这套流程提炼为四步决策清单，适用于任何“不可逆操作受约束”的发布场景：

1. 规则前置：在 brief 中写清默认版本路径与升级触发条件（本案例为“无破坏性证据则 patch”），并明令禁止不可逆操作。
2. 证据驱动决策：按包元数据、发布历史、git 差异、开放 PR/Issue 四个证据面取证，并用反例用例主动证伪；QA 红队与架构师独立评审后再定版。
3. 产物与验证一体化：版本同步、发布配套、生成镜像三类产物与验证日志同步固化；每条 PASS 都对应持久化日志，每个 dogfood 发现都如实披露。
4. 安全交接：readiness 文档精确区分“已完成”与“pending”，把 tag push、GitHub Release、npm publish 等不可逆动作显式列给维护者，等待显式批准后再执行。

整个案例的完整审计轨迹可以在 .gjc/ultragoal/goals.json 与 .gjc/ultragoal/ledger.jsonl 中逐事件回放，验证证据则落在 docs/qa/release-readiness-0.18.13.md 与artifacts/release-0.18.13/logs/日志目录。这套“约束前置、证据决策、验证留痕、边界交接”的组合，正是 OmX 将 Codex 目标模式落地为可靠工程流程的缩影。

【免费下载链接】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