OmX autoresearch Parity Smoke：用轻量验证守护核心契约的工程实践

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

导读

本文围绕 OmX（Oh 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）

原文档给出了三条清晰、可判定的成功标准，全部为可执行验证：

1. the project builds—— 项目能够成功构建；
2. autoresearch runtime/contracts smoke tests pass—— autoresearch 运行时与契约的冒烟测试通过；
3. 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 deliverable）；
• sandbox.md—— 评估器契约加安全/操作规则（evaluator contract plus safety/operating rules）。

因此本任务实际由两份文件共同定义：

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.ts：

• parseSandboxContract()要求 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_improvement'：

const 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 pass=true', ... }; }

即：评估器输出pass: true即直接keep，无需比较分数——这正是 smoke 任务"快、准、省"在运行时语义上的体现。

四、成功标准一：项目构建（build）

parity-smoke 的第一条成功标准是"the project builds"。这一检查被直接编码进评估器实现 src/scripts/eval/eval-parity-smoke.ts：

const 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 removed；
• omx 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 所依赖的验证链路仍可直接观察与复现：

1. 阅读契约：missions/parity-smoke/mission.md 定义目标与成功标准，missions/parity-smoke/sandbox.md 声明评估器（node scripts/eval-parity-smoke.js、format: json、keep_policy: pass_only）；
2. 阅读评估器实现：src/scripts/eval/eval-parity-smoke.ts 展示了完整判定流水线——先npm run build，失败即输出{"pass": false}；成功后运行 contracts/runtime/CLI 三个测试文件，全部通过输出{"pass": true}；
3. 对照全量版本：src/scripts/eval/eval-parity-sweep.ts 展示更广的测试面，帮助理解 smoke 有意裁剪掉的部分；
4. 理解运行时语义：src/autoresearch/contracts.ts 中的 frontmatter 强校验与 src/autoresearch/runtime.ts 中的decideAutoresearchOutcome（pass_only直接 keep）解释了"为什么声明pass_only就能得到轻量快速的 smoke 判定"；
5. 理解 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