OmX autoresearch 全量对齐（Parity Sweep）工程解析：run-tag 泳道、candidate.json 交接与 keep/discard/reset 薄监督循环

OmX autoresearch 全量对齐Parity Sweep工程解析run-tag 泳道、candidate.json 交接与 keep/discard/reset 薄监督循环【免费下载链接】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-codexomx autoresearch是 OmXOh My codeX中的实验性研究监督命令它作为一个薄监督器thin supervisor每一轮只驱动一次 Codex 实验会话而把持久化的 keep/discard/reset 循环交给 OMX 自身管理。本文以仓库中 missions/parity-sweep/mission.md 这份对齐任务文档为骨架结合 docs/contracts/autoresearch-command-contract.md 的完整契约与 src/autoresearch/runtime.ts、src/autoresearch/contracts.ts 的源码实现逐层拆解一次有界bounded对齐扫荡需要覆盖的全部技术点fresh run-tagged 泳道、显式--resume run-id、repo-root 活跃运行指针/锁、权威 per-run manifest、candidate.json交接、keep/discard/ambiguous/error 决策策略、reset-safe 的 worktree 局部运行时文件以及文档/帮助/契约/测试的四位一体对齐。读完本文你将掌握这套监督循环的完整架构与验收标准并能将其作为实现或审计同类实验编排系统的参考蓝图。一、Mission 总览一次有界对齐扫荡要交付什么missions/parity-sweep/mission.md 定义了本次任务的唯一目标在单次有界扫荡one bounded sweep内把omx autoresearch对齐到已批准的 full-parity 方案。其 primary targets 逐条列出如下fresh run-tagged lanes全新启动必须创建带 run 标签的新泳道而不是静默复用旧的干净泳道explicit--resume run-idbehavior显式恢复指定 run 的完整行为repo-root active-run pointer/lock仓库根目录下的活跃运行指针/锁authoritative per-run manifest state每次 run 的权威 manifest 状态repo-rootcandidate.jsonhandoff仓库根目录的候选交接产物keep / discard / ambiguous / error handling完整的决策分类处理reset-safe worktree-local runtime files可安全重置的 worktree 局部运行时文件aligned docs/help/contracts/tests文档、帮助、契约、测试描述同一行为。成功标准Success means同样明确共四条构建通过build passes聚焦的 parity 测试通过focused parity tests pass帮助/文档/契约描述同一行为help/docs/contracts describe the same behavior当前 PRD/test-spec 中不存在未实现的对齐阻塞项no remaining known parity blocker。配套的 missions/parity-sweep/sandbox.md 则划定了改动边界只允许动src/cli/autoresearch.ts、src/autoresearch/*、src/team/worktree.ts、src/modes/base.ts及相关测试、README.md、docs/contracts/autoresearch-command-contract.md和帮助 fixtures并明确避免无关重构或大范围文档扰动。这种评估器 白名单文件的沙箱结构本身正是后面要讲的 mission/sandbox 契约的一次真实应用。二、CLI 表面fresh 启动、--resume与帮助路由契约文档 docs/contracts/autoresearch-command-contract.md 定义了三条 CLI 形式omx autoresearch mission-dir [codex-args...] omx autoresearch --resume run-id [codex-args...] omx autoresearch --help三条语义约束Fresh 启动永远创建新的 run-tagged lane--resume run-id从.omx/logs/autoresearch/run-id/manifest.json加载状态当 repo-root 的.omx/state/autoresearch-state.json指向一个活跃 run 时第二次启动必须被拒绝并发锁。从源码看src/cli/autoresearch.ts 中的parseAutoresearchArgs()第 72–98 行正是这套路由的落地无参数进入 guided 模式init携带初始参数--help/-h/help输出帮助--resume run-id或--resumerun-id解析 runIdrun子命令与裸mission-dir则走直接启动路径。它还会对透传给 Codex 的参数做归一化——normalizeAutoresearchCodexArgs()第 43–70 行会去重并兜底注入 bypass 标志保证启动的会话行为一致。需要特别留意的是在当前仓库后续演进版本中这个直接启动命令表面已被标记为hard-deprecated。src/cli/autoresearch.ts 第 4–9 行的AUTORESEARCH_DEPRECATION_MESSAGE明确说明直接 CLI 启动、resume、run、裸 mission-dir 别名以及 tmux 分屏启动都不再受支持取而代之的是$autoresearchskillhook 原生的持久循环与$deep-interview --autoresearch在执行前创建/精炼 mission 产物。本文讨论的 parity 契约属于该功能线在 parity 扫荡阶段的目标形态读者应结合这一演进背景理解。三、Mission/Sandbox 契约mission-dir 与 sandbox.md frontmattermission-dir必须满足两个硬性条件docs/contracts/autoresearch-command-contract.md位于一个 git 仓库内包含mission.md和sandbox.md。sandbox.md的 YAML frontmatter 必须定义evaluator.commandevaluator.format: json可选evaluator.keep_policy: score_improvement | pass_onlyEvaluator 的 stdout 必须是 JSON包含必需的布尔pass和可选的数值score。这些约束在 src/autoresearch/contracts.ts 中有完整的解析与校验实现parseSandboxContract()第 147–184 行提取 frontmatter 与正文校验evaluator块存在、command非空、format必须为jsonkeep_policy只接受score_improvement与pass_only两个值parseKeepPolicy()第 135–145 行。parseEvaluatorResult()第 186–210 行校验 evaluator 输出必须是 JSON 对象pass必须是布尔score若出现必须是数值。loadAutoresearchMissionContract()第 212–247 行解析mission-dir绝对路径、确认目录存在、通过git rev-parse --show-toplevel求 repo root 并确保 mission-dir 位于仓库内ensurePathInside()第 76–80 行随后强制要求mission.md与sandbox.md存在并生成 mission slugslugifyMissionName()第 67–74 行小写化、非字母数字折叠为-、去首尾连字符、截断到 48 字符、空串兜底为mission。仓库中的真实案例可参见 missions/parity-sweep/sandbox.md其 frontmatter 即声明了evaluator.command: node scripts/eval-parity-sweep.js与evaluator.format: json。四、运行时模型run-tagged 泳道与 repo-root / worktree 职责分离4.1 Fresh 启动创建什么契约规定 fresh 启动创建三样东西docs/contracts/autoresearch-command-contract.md分支autoresearch/mission-slug/run-tagworktreerepo.omx-worktrees/autoresearch-mission-slug-run-tagrepo-root 下的 run 产物目录.omx/logs/autoresearch/run-id/run 标识的生成逻辑在 src/autoresearch/runtime.tsbuildAutoresearchRunTag()第 139–145 行把 ISO 时间戳中的-/:去掉、毫秒段压缩成Z结尾得到紧凑 run tagbuildRunId()第 147–149 行拼出${missionSlug}-${runTag.toLowerCase()}形式的 run id。配套的子任务文档 missions/fresh-run-tagging/mission.md 专门锁定了这一点重复的 fresh 启动必须默认产生不同的 run 标识测试必须证明先前干净的泳道不会被静默复用于新的 fresh run。4.2 职责分离repo-root 权威 vs worktree 局部契约把状态明确分成两层源码中的文件路径也一一对应Repo-root 状态职责文件职责.omx/state/autoresearch-state.json仅作为活跃 run 的指针/锁.omx/logs/autoresearch/run-id/manifest.json权威 per-run 状态.omx/logs/autoresearch/run-id/candidate.json刚结束的 Codex 会话交出的候选产物.omx/logs/autoresearch/run-id/iteration-ledger.json持久化迭代历史.omx/logs/autoresearch/run-id/latest-evaluator-result.json最新 evaluator 输出Worktree 局部状态职责results.tsv可选的 evaluator 日志如run.log这些运行时生成文件必须通过 worktree 局部的.git/info/exclude排除从而保证reset-safe。在 src/autoresearch/runtime.ts 中activeRunStateFile()第 151–153 行指向.omx/state/autoresearch-state.jsonAUTORESEARCH_WORKTREE_EXCLUDES第 133 行定义[results.tsv, run.log, node_modules, .omx/]ensureRuntimeExcludes()第 201–205 行通过writeGitInfoExclude()第 189–199 行把这些模式写入 worktree 的info/excludeassertResetSafeWorktree()第 258–263 行读取git status --porcelain --untracked-filesall仅放行isAllowedRuntimeDirtyLine()第 249–256 行识别出的允许运行时脏行其余任何变更都会抛出autoresearch_reset_requires_clean_worktree:path:blocking错误锁语义由assertAutoresearchLockAvailable()第 288–293 行实现若 state 文件标记active且带 run_id直接抛出autoresearch_active_run_exists:run-id从而拒绝并发启动。4.3 Baseline 播种与指令快照prepareAutoresearchRuntime()第 828–965 行是 fresh 启动的核心编排先取锁 → 写 worktree excludes → 链接依赖ensureAutoresearchWorktreeDependencies()第 207–214 行把 repo-root 的node_modules以符号链接方式提供给 worktree避免重复安装→ 校验 worktree 可重置 → 生成 run tag/run id → 初始化 results/manifest/ledger/evaluator/candidate 文件 → 启动 mode → 激活 run 锁 →seedBaseline()第 793–826 行执行一次基线评估并把baseline 行永远记录baseline row is always recorded写入results.tsv与 ledger随后写出首次指令文件。buildAutoresearchInstructions()第 635–717 行生成的指令快照包含run id、mission 路径、iteration 号、baseline commit、last kept commit、last kept score、results/candidate 文件路径、keep policy、最近的 ledger 摘要formatAutoresearchInstructionSummary()第 437–453 行默认最近 3 条以及前一轮结果buildAutoresearchInstructionContext()第 455–467 行。指令会明确告知 Codex 会话恰好执行一个实验周期最多产生一个候选提交然后写入 candidate 产物 JSON 并退出禁止在会话内无限循环。五、candidate.json交接产物的 schema 与完整性规则被启动的会话必须在 repo-root 写入candidate.jsonschema 如下docs/contracts/autoresearch-command-contract.md{ status: candidate | noop | abort | interrupted, candidate_commit: string | null, base_commit: string, description: string, notes: [string], created_at: ISO timestamp }对应的 TypeScript 类型为AutoresearchCandidateArtifactsrc/autoresearch/runtime.ts 第 45–52 行。完整性规则有三条statuscandidate时candidate_commit必须非空candidate_commit必须在 git 中可解析且与退出时 worktree 的HEAD提交一致base_commit必须在 git 中可解析且与监督器提供的last_kept_commit一致。这三条在validateAutoresearchCandidate()第 1090–1140 行中逐项落实tryResolveGitCommit()第 179–187 行用git rev-parse --verify ref^{commit}解析引用base commit 必须精确等于 manifest 的last_kept_commitcandidate commit 必须等于 worktree 当前HEAD。任何不符都会走failAutoresearchIteration()第 1142–1179 行把本次迭代记为 error、终止 run。解析入口parseAutoresearchCandidateArtifact()第 1020–1058 行负责把原始 JSON 变成强类型对象必须是 JSON 对象、status必须属于四值枚举、candidate_commit必须是string|null、base_commit/description/created_at必须是非空字符串、notes必须是字符串数组。若 run 开始时会话尚未写入prepareAutoresearchRuntime()会先落一个status: noop、description: not-yet-written的占位产物第 856–863 行确保候选文件路径始终存在。配套子任务 missions/candidate-handoff/mission.md 要求候选交接产物必须显式且被测试覆盖运行时必须能区分 candidate / noop / abort / interrupted 四种状态parity 运行时测试通过。六、决策策略keep / discard / ambiguous / error 的完整分支6.1 规则全集decideAutoresearchOutcome()src/autoresearch/runtime.ts 第 549–633 行实现了契约中 Decision policy 的全部规则输入条件决策说明statusabortabort候选要求停止run 不重置、直接终止statusnoopnoop无代码变更提议默认记录后继续下一轮statusinterruptedinterrupted会话被中断若 worktree 脏则停等操作者介入若干净则按 noop 类结果记录evaluator error / crashdiscard评估器出错即丢弃passfalsediscard评估失败即丢弃keep_policypass_only且passtruekeep任何通过都保留score_improvement且 pass 但无可比分数ambiguous并丢弃无 last kept score 或本次无 score 时无法比较score_improvement且分数提升keep分数严格大于 last kept scorescore_improvement且分数未提升discard未超过基线即丢弃三条结构性保证baseline 行总是被记录seedBaseline()中强制写 iteration 0Discard / ambiguous / error 路径必须 reset 到 last kept commit——resetToLastKeptCommit()第 1085–1088 行先assertResetSafeWorktree()再执行git reset --hard last_kept_commitkeep 时更新last_kept_commit与last_kept_scoreprocessAutoresearchCandidate()第 1232–1293 行。6.2 非评估路径的分流recordNonEvaluatedCandidateStatus()第 1181–1230 行处理三种不走评估器的状态abort记录后finalizeRun()终止interrupted先尝试assertResetSafeWorktree()脏则直接以 failed 终止并要求操作者介入干净则记录为 interrupted 并继续noop记录后继续。finalizeRun()第 1067–1083 行统一把 manifest 标记为终态、关闭 mode、释放活跃 run 锁。6.3 决策如何落盘每次迭代通过recordAutoresearchIteration()第 358–397 行同时追加两处持久化results.tsv一行appendAutoresearchResultsRow()第 337–356 行表头固定为iteration\tcommit\tpass\tscore\tstatus\tdescription第 132 行commit 取短哈希ledger 一条记录appendAutoresearchLedgerEntry()第 399–418 行包含 iteration、decision、reason、candidate/base/kept commit、keep_policy、完整 evaluator 记录、notes 等字段。ledger 还支撑两个运维能力countTrailingAutoresearchNoops()第 426–435 行统计尾部连续 noop 数用于判断 run 是否空转以及formatAutoresearchInstructionSummary()为下一轮指令生成近期摘要。七、Resume 语义显式--resume run-id的四重守卫契约规定--resume run-id在以下四种情况必须以可操作的错误失败docs/contracts/autoresearch-command-contract.mdmanifest 缺失引用的 worktree 缺失worktree 脏超出白名单运行时产物之外manifest 已是终态terminal。resumeAutoresearchRuntime()src/autoresearch/runtime.ts 第 967–1018 行依次实现loadAutoresearchRunManifest()第 754–760 行找不到 manifest 时抛autoresearch_resume_manifest_missing:runIdmanifest.status ! running抛autoresearch_resume_terminal_run:runIdworktree 路径不存在抛autoresearch_resume_missing_worktree:pathassertResetSafeWorktree()拒绝白名单之外的脏状态。恢复成功后run 从last kept commit 与既有 results 历史继续这正是 missions/resume-dirty-guard/mission.md 的成功标准resume 拒绝脏 worktree 并给出可操作错误、不静默 reset、不进行不安全续跑、聚焦的 resume-guard 测试通过。八、迭代交接上下文每轮指令快照的内容每次启动的 worker 会话都会收到监督器写好的指令快照docs/contracts/autoresearch-command-contract.md 的 Iteration handoff context包含当前 iteration 号baseline commitlast kept commit已知的 last kept score上一轮结果previous iteration outcome有界长度的近期 ledger 摘要默认最近 3 条reason 截断到 160 字符、description 截断到 120 字符keep policy这些字段由buildAutoresearchInstructions()第 635–717 行拼装成 Markdown JSON 快照Iteration state snapshot内嵌一个包含上述字段的 JSON 对象再与 mission 正文、sandbox 策略、evaluator 契约command / format / pass / score 约定一起写入bootstrap-instructions.md。writeInstructionsFile()第 767–791 行在每次迭代决策落盘后都会重新生成确保下一轮 worker 看到的是最新状态它还通过resolveWorktreeToolContext()附加代码图code graph工具上下文供会话按需调用。九、验证目标与对齐证据契约的 Verification targetsdocs/contracts/autoresearch-command-contract.md要求实现能够证明六点fresh 启动创建互不相同的 run-tagged 泳道repo-root 活跃 run 锁拒绝并发启动candidate 交接产物驱动 keep/discard/reset 决策被丢弃的候选 reset 到last_kept_commit--resume run-id重新加载权威 manifest/worktree 状态README/help/contracts 描述同一套薄监督 parity 循环。仓库中的评审记录 docs/contracts/autoresearch-command-review.md评审日期 2026-03-14逐条给出了该扫荡的验收证据构建npm run build通过聚焦测试node --test dist/autoresearch/__tests__/runtime.test.js dist/cli/__tests__/autoresearch.test.js dist/cli/__tests__/index.test.js dist/cli/__tests__/nested-help-routing.test.js dist/team/__tests__/worktree.test.js dist/modes/__tests__/base-autoresearch-contract.test.js通过代码/文档一致性CLI 帮助覆盖 fresh 与--resumesrc/cli/autoresearch.ts顶层帮助宣传薄监督 parity 语义src/cli/index.ts、src/compat/fixtures/help.stdout.txtREADME 解释 baseline 播种、repo-root per-run 产物、candidate 交接、keep/discard/reset、重启循环与 resume 行为README.md契约文档定义 run-tagged 泳道、repo-root 权威分工、候选产物 schema、决策策略与 resume 失败条件docs/contracts/autoresearch-command-contract.md运行时实现活跃锁、per-run manifest、白名单 excludes、候选解析、评估器决策、reset-to-last-kept 与 resume 校验src/autoresearch/runtime.tsworktree 规划测试锁定了 run-tagged 分支/路径命名src/team/tests/worktree.test.ts。评审的 Parity checklist 六项全部Pass薄监督迭代模型、repo-root 状态权威、fresh-run 语义、resume 契约、keep/discard/reset 决策策略、文档/帮助/契约对齐。剩余的只是可选的清理项如迭代中通过cat回读 manifest 的实现细节以及 noop/abort/interrupted/pass_only 分支的测试覆盖率扩充空间。十、演进现状从 parity 到 hard-deprecation 的迁移路径需要向读者说明的是parity 扫荡达成的是该命令线在 parity 形态下的正确性而当前仓库源码显示该命令表面已经进一步演进为hard-deprecated。src/cli/autoresearch.ts 第 4–9 行的弃用消息给出了官方迁移路径使用$autoresearchskill 承载 hook 原生的持久循环stateful、validator-gated 的执行循环完成条件取决于 validator 证据而非重复 noop 或 tmux 启动 parity使用$deep-interview --autoresearch在执行前创建或精炼 mission 产物并把规范产物写到.omx/specs/autoresearch-{slug}/初始化时二选一选择校验模式mission-validator-script或prompt-architect-artifact。也就是说本文拆解的薄监督 parity 循环run-tag 泳道、active-run 锁、per-run manifest、candidate.json 交接、keep/discard/reset 决策是理解omx autoresearch历史演进的关键架构层它确立了 OMX 作为权威状态持有者、Codex 会话作为单周期实验 worker的职责边界这套边界被后来的$autoresearchskill 持久循环与$deep-interview精炼流程所继承。无论你是在阅读旧版代码、迁移既有 mission还是设计自己的监督式实验编排器本节与前述九节合起来都能提供一份完整、可校验的架构蓝图。十一、小结一次成功的 parity sweep本质上是把行为一致性变成可验证的工程事实fresh 启动的泳道必须互不相同repo-root 锁必须拒绝并发candidate 交接必须携带完整的完整性证据决策策略必须覆盖 keep/discard/ambiguous/error/noop/abort/interrupted 全部分支discard 必须 reset 到 last kept commitresume 必须在四类失败前给出可操作错误而帮助、文档、契约与测试必须描述同一套语义。本文以 missions/parity-sweep/mission.md 的八项 primary target 为主线用 docs/contracts/autoresearch-command-contract.md 的契约条款与 src/autoresearch/runtime.ts、src/autoresearch/contracts.ts 的源码逐一印证并以 docs/contracts/autoresearch-command-review.md 的验收证据说明了该扫荡如何达成build passes focused tests pass 文档契约同语 无遗留阻塞项的成功标准——这套方法论同样适用于其他需要行为对齐的复杂 CLI 演进工程。【免费下载链接】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），仅供参考