OmX autoresearch Parity Smoke用轻量验证守护核心契约的工程实践【免费下载链接】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导读本文围绕 OmXOh My codeX仓库中 missions/parity-smoke/mission.md 这份验证型任务文档展开介绍 OmX 如何通过一个极轻量的 autoresearch smoke 任务parity smoke来快速确认核心契约在代码改动后依然成立而无需运行耗时的全量 parity sweep。读完本文你将掌握 mission/sandbox 双文件任务契约的写法、pass_only保留策略的含义、parity smoke 成功标准的底层实现路径构建、runtime/contracts 测试、CLI help 路由以及它与全量 parity sweep 的边界。一、什么是 parity smoke它验证什么在 OmX 的 autoresearch 体系中parity对齐/一致性指的是CLI 帮助文本、运行时行为、契约定义、测试用例之间描述与执行的是同一套语义。每当源码发生编辑后最理想的做法是跑一次完整的 parity sweep但它的成本明显更高。missions/parity-smoke/mission.md 定义的正是一次小成本、快反馈的冒烟验证Run a very small autoresearch smoke task against the current parity surfaces. Validate that the core autoresearch contract still holds after edits without running the entire parity sweep.即在不运行全量 parity sweep的前提下用一次小型 smoke 任务确认autoresearch 核心契约仍然成立。这种先冒烟、后全量的分层验证策略保证日常迭代时能第一时间捕获契约漂移把昂贵的全量回归留给需要它的场合。成功标准Success means原文档给出了三条清晰、可判定的成功标准全部为可执行验证the project builds—— 项目能够成功构建autoresearch runtime/contracts smoke tests pass—— autoresearch 运行时与契约的冒烟测试通过CLI help routing for autoresearch still works——omx autoresearch的 CLI 帮助路由仍然工作。这三条恰好分别对应编译层、逻辑层、交互层三个表面parity surfaces与任务名中的 parity surfaces 一一对应。二、mission 双文件结构任务与沙箱契约parity-smoke 任务遵循 OmX autoresearch 的 mission bundle 约定。正如 missions/README.md 所述每个 mission 目录都包含两个文件mission.md—— 目标、范围与预期交付物objective, scope, expected deliverablesandbox.md—— 评估器契约加安全/操作规则evaluator contract plus safety/operating rules。因此本任务实际由两份文件共同定义文件职责关键内容missions/parity-smoke/mission.md定义任务目标与成功标准三条成功标准build、smoke tests、CLI help routingmissions/parity-smoke/sandbox.md定义评估器与操作边界YAML frontmatter 声明 evaluator 命令、输出格式、保留策略sandbox.md 的评估器契约missions/parity-smoke/sandbox.md 的完整 frontmatter 如下--- evaluator: command: node scripts/eval-parity-smoke.js format: json keep_policy: pass_only ---这是 autoresearch v1 契约中sandbox.md的标准三段式声明command评估器执行命令。它声明为node scripts/eval-parity-smoke.js对应仓库中的真实实现源码为 src/scripts/eval/eval-parity-smoke.ts经构建后映射到dist下的同名 JS 产物format: json评估器必须以 JSON 输出结果keep_policy: pass_only保留策略为仅通过即保留——只要评估器输出pass: true该候选提交即被保留不要求数值分数超越基线。此外sandbox 正文还明确了操作约束Keep this mission lightweight and fast. Prefer minimal changes only if needed to restore the smoke path.即保持任务轻量与快速仅当需要恢复 smoke 路径时才做最小改动。这决定了 parity smoke 天然是验证型任务而非优化型任务——它不追求改进分数只追求确认契约完好。三、契约解析的底层实现sandbox frontmatter 如何被读取evaluator.command、format、keep_policy这三个字段并不是任意的文档装饰而是由运行时强校验解析的。解析逻辑位于 src/autoresearch/contracts.tsparseSandboxContract()要求 sandbox.md 必须以 YAML frontmatter 开头^---\r?\n...\r?\n---否则抛出sandbox.md must start with YAML frontmatter...错误evaluator块缺失、evaluator.command为空、evaluator.format缺失或不为json都会触发对应契约错误见EVALUATOR_COMMAND_ERROR、EVALUATOR_FORMAT_JSON_ERROR等常量parseKeepPolicy()只接受两个合法值score_improvement与pass_only其余值直接抛错——这从源码层面锁死了 keep policy 的取值域format被统一归一化为小写后校验v1 契约中强制为json。keep_policy缺省时运行时在 src/autoresearch/runtime.ts 的prepareAutoresearchRuntime()中会回退到score_improvementconst keepPolicy contract.sandbox.evaluator.keep_policy ?? score_improvement;而 parity-smoke 显式声明了pass_only因此它的决策路径会命中decideAutoresearchOutcome()中的if (manifest.keep_policy pass_only) { return { decision: keep, decisionReason: pass_only keep policy accepted evaluator passtrue, ... }; }即评估器输出pass: true即直接keep无需比较分数——这正是 smoke 任务快、准、省在运行时语义上的体现。四、成功标准一项目构建buildparity-smoke 的第一条成功标准是the project builds。这一检查被直接编码进评估器实现 src/scripts/eval/eval-parity-smoke.tsconst build spawnSync(npm, [run, build], { encoding: utf-8 }); if (build.stdout) process.stderr.write(build.stdout); if (build.stderr) process.stderr.write(build.stderr); if (build.status ! 0) { process.stdout.write(JSON.stringify({ pass: false })); process.exit(build.status ?? 1); }构建失败时评估器立即输出{pass: false}并以非零码退出——构建失败 smoke 失败没有任何中间态。构建成功后才继续执行测试阶段。五、成功标准二runtime/contracts 冒烟测试构建通过后评估器进入测试阶段运行三个与 autoresearch 直接相关的测试文件编译后路径const test spawnSync(node, [ dist/scripts/run-test-files.js, dist/autoresearch/__tests__/contracts.test.js, dist/autoresearch/__tests__/runtime.test.js, dist/cli/__tests__/autoresearch.test.js, ], { encoding: utf-8 }); process.stdout.write(JSON.stringify({ pass: test.status 0 }));三个测试文件的源码位置分别对应src/autoresearch/tests/contracts.test.ts —— 契约解析与校验测试验证 sandbox frontmatter 解析、evaluator 结果解析parseEvaluatorResult要求 JSON 必须含布尔pass可选数值score、keep policy 合法性等src/autoresearch/tests/runtime.test.ts —— 运行时测试覆盖prepareAutoresearchRuntime、decideAutoresearchOutcome、候选产物解析parseAutoresearchCandidateArtifact等核心逻辑src/cli/tests/autoresearch.test.ts —— CLI 层测试与成功标准三直接相关。测试命令全部成功退出码 0时评估器输出{pass: true}否则输出{pass: false}。整个评估器最终只输出一个 JSON 对象严格符合format: json契约。六、成功标准三CLI help 路由仍然工作第三项成功标准 CLI help routing for autoresearch still works 需要结合当前仓库的 CLI 现状来理解omx autoresearch在较新版本中已被hard-deprecated硬弃用见 src/cli/autoresearch.ts 中的AUTORESEARCH_DEPRECATION_MESSAGE与AUTORESEARCH_HELP。因此help routing still works 的含义是尽管直接启动、--resume、run mission-dir、裸 mission-dir 别名等旧形式均已移除但帮助路由本身必须保留且行为正确——具体表现为顶层帮助中omx autoresearch被标注为[DEPRECATED] Use $autoresearch; direct CLI launch removedomx autoresearch --help仍能正确路由到本地弃用帮助页其中明确指引迁移路径用$deep-interview --autoresearch澄清 mission 并产出规范产物.omx/specs/autoresearch-{slug}/用$autoresearch your mission进入有状态、带验证器门控的执行循环完成判定依赖验证器证据validator evidence而非重复 noop 或 detached tmux 启动对齐。这些行为均有测试锁定。在 src/cli/tests/autoresearch.test.ts 的describe(omx autoresearch hard deprecation)中可以看到测试断言顶层帮助输出包含/omx autoresearch\s\[DEPRECATED\] Use \$autoresearch; direct CLI launch removed/i断言autoresearch --help输出包含/\$deep-interview --autoresearch/i与/\$autoresearch/i并逐项验证autoresearch、autoresearch init、autoresearch run missions/demo、autoresearch missions/demo、autoresearch --resume run-123、--topic等旧形式全部有意失败fail intentionally。这意味着 smoke 的成功标准三本质上是回归防护确保未来任何改动不会意外破坏这个弃用但可发现的交互表面——用户输入omx autoresearch --help时永远能得到明确的迁移指引。七、smoke 与 sweep 的边界何时用哪个仓库中同时存在两个配套评估器src/scripts/eval/eval-parity-smoke.ts本任务与 src/scripts/eval/eval-parity-sweep.ts全量 sweep。对照两者的测试清单可以清晰看到边界parity smoke本文仅构建 3 个测试文件contracts、runtime、CLI autoresearch聚焦核心契约是否仍成立parity sweep全量在构建基础上运行 8 个测试文件除上述外还包含index、nested-help-routing、session-search-help、team/worktree、modes/base-autoresearch-contract等覆盖更广的 help 路由、worktree 与 mode 契约。missions/parity-sweep/mission.md中的目标列表fresh run-tagged lanes、显式--resume run-id、repo-root 活跃运行指针/锁、权威 per-run manifest 状态、candidate.json交接、keep/discard/ambiguous/error 处理、reset-safe 工作区运行时文件、对齐的 docs/help/contracts/tests对应的是完整的全量对齐任务而 parity-smoke 的任务定位则明确写在 mission 标题里——在编辑后先做最小验证再决定是否需要进入全量 sweep。这是一种典型的快速失败、分级回归工程节奏。八、如何理解并复现这次 smoke虽然omx autoresearch的直接 CLI 启动已被硬弃用但 parity-smoke 所依赖的验证链路仍可直接观察与复现阅读契约missions/parity-smoke/mission.md 定义目标与成功标准missions/parity-smoke/sandbox.md 声明评估器node scripts/eval-parity-smoke.js、format: json、keep_policy: pass_only阅读评估器实现src/scripts/eval/eval-parity-smoke.ts 展示了完整判定流水线——先npm run build失败即输出{pass: false}成功后运行 contracts/runtime/CLI 三个测试文件全部通过输出{pass: true}对照全量版本src/scripts/eval/eval-parity-sweep.ts 展示更广的测试面帮助理解 smoke 有意裁剪掉的部分理解运行时语义src/autoresearch/contracts.ts 中的 frontmatter 强校验与 src/autoresearch/runtime.ts 中的decideAutoresearchOutcomepass_only直接 keep解释了为什么声明pass_only就能得到轻量快速的 smoke 判定理解 CLI 现状src/cli/autoresearch.ts 的弃用帮助与 src/cli/tests/autoresearch.test.ts 的回归断言解释了CLI help routing still works的真实含义。如果需要在当前仓库快照中真实跑一次完整端到端的 autoresearch 流程可参考 missions/README.md 中其他 pilot 的启动方式如omx autoresearch missions/in-action-cat-shellout-demo并观察.omx/logs/autoresearch/run-id/manifest.json、candidate.json、iteration-ledger.json中监督者的 keep/discard/stop 决策记录。结语parity-smoke 是 OmX 工程实践中的一个精妙缩影一份三行的 mission 文档 一份四行的 sandbox 契约背后却串联起完整的契约强校验、运行时决策语义、构建/测试流水线与 CLI 弃用回归保护。它证明了一件事——验证任务的小不是内容的贫瘠而是刻意设计的边界把全量对齐留给 sweep把高频守护交给 smoke让每一次编辑都能在秒级得到核心契约是否仍成立的明确答案。【免费下载链接】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），仅供参考