OmXomx autoresearch命令全面校验Thin-Supervisor 平价运行模型剖析【免费下载链接】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中用于驱动“多轮 Codex 实验迭代”的命令面其核心设计是薄监督器thin supervisor模式每次迭代只启动一个 Codex 实验会话而保持keep、丢弃discard、回滚reset的决策闭环由 OmX 运行时自己持久化。本指南以 docs/contracts/autoresearch-command-review.md 的校验记录为主线结合 docs/contracts/autoresearch-command-contract.md 的契约、src/autoresearch/runtime.ts 的实现与配套测试完整还原这条命令的 CLI 形态、运行时状态权威分层、决策策略、恢复语义与验证方法帮助你在自己的仓库里复现这套“一个会话一次实验、监督器掌管持久循环”的平价模型。背景为什么需要 Thin-Supervisor 模型在 Agent 驱动的自动化研究中最典型的失控场景是启动一个长期存活的 Codex 会话让它“一直改进”会话内部反复自我循环既没有明确的停止条件也没有可审计的迭代记录。OmX 的 autoresearch 采用相反的思路——把循环的控制权从 Agent 会话手里拿回运行时。其核心约定一句话可以概括每一次迭代Codex 会话只做一轮实验并写一个候选产物candidate artifact随后立即退出是否保留这次改动、是否回滚、是否启动下一轮全部由 OmX 运行时依据持久化的账本和评估器evaluator的 JSON 输出决定。这条命令面由两份文档共同锚定docs/contracts/autoresearch-command-contract.md定义 CLI、mission/sandbox 契约、运行时模型、候选产物契约、决策策略与 resume 语义docs/contracts/autoresearch-command-review.md2026-03-14 由 worker-3 评审车道完成的全面校验记录确认实现与 PRD/测试规格在平价语义上已对齐并给出剩余的可选优化点。CLI 形态与参数面命令形式契约文档定义了三种入口omx autoresearch mission-dir [codex-args...] omx autoresearch --resume run-id [codex-args...] omx autoresearch --help参数解析逻辑位于 src/cli/autoresearch.ts 的parseAutoresearchArgs其解析分支如下首个参数行为空进入 guided 引导流程guided: true不直接启动init解析为 guided 引导 透传initArgs--help/-h/help输出帮助文本--resume run-id恢复指定 run-id其余参数作为 codex 透传参数--resumerun-id等价于上者run mission-dir显式 run 子命令形态以-开头按引导参数解析seed args其他首参作为missionDir其余作为 codex 透传参数值得注意的是normalizeAutoresearchCodexArgssrc/cli/autoresearch.ts会做 codex 参数规整把MADMAX_FLAG与CODEX_BYPASS_FLAG去重并确保最终一定注入 bypass 标志——这保证了每次启动的会话都是受控的独立实验会话而不是递归触发外部钩子。关于命令面的现状说明需要澄清一个容易混淆的时点问题评审文档2026-03-14记录的是一次已完成的平价校验当时的命令面处于活跃可用状态而在当前仓库的源码里src/cli/autoresearch.ts顶部已经带有 hard-deprecation 消息src/cli/autoresearch.ts指向迁移路径用$autoresearchskill 使用 hook-native 的持久循环用$deep-interview --autoresearch在执行前创建/打磨 mission 产物规范产物写入.omx/specs/autoresearch-{slug}/。因此本文描述的命令形态属于该功能的历史契约与实现语义可用于理解底层运行时模型与迁移背景新项目应优先采用 skill 入口。这与评审文档“reviewer lane 校验通过、后续仅剩可选清理项”的结论并不冲突——它正是平价模型曾被打通的证据。Mission / Sandbox 契约一次迭代的实验边界mission-dir必须位于 git 仓库内且必须包含两个文件mission.md任务说明随每次迭代写入会话指令sandbox.md沙箱策略 评估器契约YAML frontmatter 必须定义--- evaluator: command: node scripts/eval.js format: json keep_policy: score_improvement # 可选score_improvement | pass_only --- 沙箱边界说明契约与解析逻辑在 src/autoresearch/contracts.tsevaluator.command必填评估器命令行以 shell 方式在 worktree 内执行evaluator.format必填且当前版本只接受jsonsrc/autoresearch/contracts.ts 定义format: json常量校验evaluator.keep_policy可选取值score_improvement默认或pass_only由parseKeepPolicy严格校验src/autoresearch/contracts.ts。评估器的 stdout 必须是合法 JSON 对象包含必填布尔pass与可选数值score。parseEvaluatorResultsrc/autoresearch/contracts.ts会逐项校验必须是 JSON 对象、pass必须是布尔、score出现则必须是数字任何一项不满足都会抛出带明确诊断信息的错误。从源码结构看frontmatter 解析采用轻量的逐行 YAML 子集实现parseSimpleYamlFrontmattersrc/autoresearch/contracts.ts支持顶层键与二级 section如evaluator块不支持数组等复杂结构这提醒你在编写sandbox.md时保持 frontmatter 的扁平简单。运行时模型Repo-Root 权威 vs Worktree 本地状态运行时实现位于 src/autoresearch/runtime.ts采用清晰的“状态权威分层”一次全新启动创建的结构对象位置职责分支autoresearch/mission-slug/run-tagrun-tagged 实验分支worktreerepo.omx/worktrees/autoresearch-mission-slug-run-tag隔离实验工作区活跃运行锁.omx/state/autoresearch-state.json仅作为 active-run 指针/锁run 目录.omx/logs/autoresearch/run-id/权威 per-run 产物run 目录内包含见prepareAutoresearchRuntime中 src/autoresearch/runtime.ts 的路径构造manifest.json权威 per-run 状态schema_version、run_id、mission 路径、baseline/last_kept commit、keep_policy、status 等完整字段见 src/autoresearch/runtime.ts 的AutoresearchRunManifestcandidate.json刚结束的 Codex 会话写回的候选产物交接点iteration-ledger.json可持久化的迭代历史账本entries数组schema_version: 1latest-evaluator-result.json最近一次评估器输出bootstrap-instructions.md每次启动/恢复时生成的会话指令快照。worktree 本地则只保留两类运行时产物results.tsv与可选评估日志如run.log且这些运行时生成的文件必须通过 worktree 本地的.git/info/exclude排除AUTORESEARCH_WORKTREE_EXCLUDES [results.tsv, run.log, node_modules, .omx/]src/autoresearch/runtime.ts。ensureRuntimeExcludessrc/autoresearch/runtime.ts会在启动与恢复时把上述模式写入git info/exclude确保 reset 安全检查不会把运行时产物误判为污染。results.tsv 的格式AUTORESEARCH_RESULTS_HEADER iteration\tcommit\tpass\tscore\tstatus\tdescription\nsrc/autoresearch/runtime.ts。每一轮迭代追加一行其中 iteration 从 0 开始第 0 行是 baseline 记录后续行对应各次候选评估。模式状态mode state集成autoresearch 是 OmX 模式生命周期体系的一员——src/modes/base.ts 的ModeName类型明确列出autoresearch。prepareAutoresearchRuntime会调用startMode(autoresearch, taskDescription, 1, projectRoot)并把current_phase依次置为evaluating-baseline→running同时把 mission、run、各产物路径、keep_policy 等写入模式状态src/autoresearch/runtime.ts。模式状态记录在仓库根的.omx/state下与 active-run 锁配合实现互斥。单次迭代的指令快照每次启动或恢复都会由writeInstructionsFile生成bootstrap-instructions.md内容由buildAutoresearchInstructionssrc/autoresearch/runtime.ts拼装包含Run ID、mission/sandbox 文件路径、mission slug、迭代号baseline commit、last kept commit、last kept scoreresults 文件与 candidate 产物路径keep policy迭代状态快照JSONiteration、baseline_commit、last_kept_commit、last_kept_score、previous_iteration_outcome、recent_ledger_summary、keep_policy明确的“薄监督器”操作指令“恰好执行一轮实验周期exactly one experiment cycle最多产生一个候选 commit写完 candidate artifact JSON 后退出禁止在会话内无限循环”候选产物契约字段说明评估器契约command、formatjson、输出 pass 布尔与可选 scoremission 内容与 sandbox 策略正文超长内容被截断到 4000 字符trimContentsrc/autoresearch/runtime.ts。previous_iteration_outcome与recent_ledger_summary由buildAutoresearchInstructionContext从账本读取最近最多 3 条reason 截断 160 字符、description 截断 120 字符保证每个新会话都知道上一轮发生了什么。候选产物契约会话与监督器的交接点Codex 会话退出前必须把 JSON 写到candidate.json字段契约src/autoresearch/runtime.ts字段类型说明statuscandidate \| noop \| abort \| interrupted会话侧结论candidate_commitstring \| nullstatuscandidate 时必填非 nullbase_commitstring编辑前的基线提交descriptionstring一句话摘要notesstring[]备注数组created_atISO 时间戳创建时间完整性校验由parseAutoresearchCandidateArtifact与validateAutoresearchCandidatesrc/autoresearch/runtime.ts双重把关核心不变量candidate_commit必须在 git 中可解析git rev-parse --verify ref^{commit}且必须等于会话退出时 worktree 的HEADbase_commit必须在 git 中可解析且必须等于监督器提供的last_kept_commit。这两条规则杜绝了“谎报 commit”与“在错误基线上提交”两类作弊路径。决策策略keep / discard / reset 闭环decideAutoresearchOutcomesrc/autoresearch/runtime.ts是决策核心完整策略如下输入决策行为statusabortabort停止运行不 resetrun 状态置为stoppedstatusnoopnoop记录 noop 迭代默认继续启动下一轮statusinterruptedinterrupted检查 worktree脏则停止等待人工介入干净则记录后继续评估器 error/崩溃discard回滚passfalsediscard回滚pass_only且passtruekeep直接保留score_improvement且 pass 无可比数值 scoreambiguous回滚要求可比数值分数score_improvement且 score 提升keep保留并更新last_kept_commit/last_kept_scorescore_improvement且 score 未提升discard回滚关键点baseline 行永远被记录seedBaselinesrc/autoresearch/runtime.ts在启动时对初始提交跑一次评估器写入results.tsv第 0 行与账本 baseline 条目last_kept_score只在 baseline pass 且带数值时记录所有 discard / ambiguous / error 路径都reset --hard到last_kept_commitresetToLastKeptCommitsrc/autoresearch/runtime.ts在 reset 前先执行assertResetSafeWorktree只允许排除清单内的运行时产物存在否则报autoresearch_reset_requires_clean_worktree:path:blocking lines并终止。processAutoresearchCandidatesrc/autoresearch/runtime.ts串起完整流程读候选 → 校验 → 非 candidate 状态走recordNonEvaluatedCandidateStatus→ candidate 状态跑评估器 → 决策 → keep 则推进 last_kept否则 reset → 写 results/ledger → 写回 manifest → 生成下一轮指令。并发锁与 Fresh-Run 语义活跃运行锁.omx/state/autoresearch-state.json保存{active, run_id, mission_slug, ...}。assertAutoresearchLockAvailablesrc/autoresearch/runtime.ts在启动与恢复前都会检查若state.active state.run_id存在则直接抛autoresearch_active_run_exists:run-id阻止并发二次启动fresh-run 语义每次全新启动都会由buildAutoresearchRunTagsrc/autoresearch/runtime.tsISO 时间戳去符号化生成 run-tag再由buildRunId组合成${missionSlug}-${runTag.toLowerCase()}。run 目录、分支、worktree 全部按 run-id/run-tag 命名因此不会静默复用一条长期存活的 lane命名规划的统一入口src/team/worktree.ts的规划函数按 scope 区分命名src/team/worktree.tsscope autoresearch时分支为autoresearch/sanitized-name/runTag、worktree 为.omx/worktrees/autoresearch-sanitized-name-runTag。配套测试 src/team/tests/worktree.test.ts 明确断言分支名autoresearch/demo-mission/20260314t000000z与 worktree 路径后缀autoresearch-demo-mission-20260314t000000z模式互斥启动前还会检查readModeState(autoresearch, projectRoot)若已有 active 模式则抛autoresearch_active_mode_exists:run-id与锁文件形成双重保护。Resume 契约与失败条件resumeAutoresearchRuntimesrc/autoresearch/runtime.ts从--resume run-id恢复运行先加载manifest.jsonloadAutoresearchRunManifestsrc/autoresearch/runtime.ts随后必须通过以下失败检查每种都给出可操作的错误码失败条件错误manifest 缺失autoresearch_resume_manifest_missing:run-idworktree 缺失autoresearch_resume_missing_worktree:pathworktree 在排除清单外存在脏改动autoresearch_reset_requires_clean_worktree:...manifest 已终结非runningautoresearch_resume_terminal_run:run-id恢复成功后从last_kept_commit与既有 results 历史继续推进并重新生成带最新账本摘要的指令文件。运行终结统一走finalizeRunsrc/autoresearch/runtime.ts写回status/stop_reason/completed_at模式状态置非活跃active-run 锁解除deactivateAutoresearchRun。测试验证平价语义如何被钉死评审记录列出的验证命令如下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.jssrc/autoresearch/tests/runtime.test.ts 是核心覆盖值得重点阅读的用例指令构建断言buildAutoresearchInstructions包含“exactly one experiment cycle”、pass/score输出契约、迭代状态快照等关键语义src/autoresearch/tests/runtime.test.tsreset 安全检查验证.omx下的 untracked 运行时文件不会阻断 reset-safe 检查src/autoresearch/tests/runtime.test.ts运行时产物与模式状态验证 manifest、ledger、latest-evaluator、results、指令文件全部落盘baseline 行0\t...\ttrue\t1\tbaseline\tinitial baseline evaluation正确写入模式状态activetrue / current_phaserunningsrc/autoresearch/tests/runtime.test.tskeep/discard 闭环最关键的端到端用例src/autoresearch/tests/runtime.test.ts先提交 score2 的改进候选 →processAutoresearchCandidate返回keeplast_kept_commit前进到改进提交再提交 score1 的回退候选 → 返回discardworktreeHEAD被reset --hard回改进提交最终 results 出现1\t...\ttrue\t2\tkeep\timproved score与2\t...\ttrue\t1\tdiscard\tworse score两行账本顺序为baseline → keep → discard且下一轮指令的previous_iteration_outcome正确携带discard:score did not improve。此外还有src/autoresearch/__tests__/runtime-parity-extra.test.ts、src/autoresearch/__tests__/contracts.test.ts以及 eval 脚本src/scripts/eval/eval-parity-smoke.ts、src/scripts/eval/eval-candidate-handoff.ts、src/scripts/eval/eval-fresh-run-tagging.ts、src/scripts/eval/eval-resume-dirty-guard.ts等覆盖 fresh-run 标签、候选交接、恢复脏保护等平价面。评审结论与遗留风险评审记录docs/contracts/autoresearch-command-review.md给出的结论是实现已不再是早期 v1 scaffold与 thin-supervisor 平价模型大体一致共享的 help/测试措辞不一致问题已解决。同时留下三条可选跟进项runAutoresearchLoop()每轮迭代通过execFileSync(cat, ...)JSON.parse从 manifest 回读 run-id功能正确但略显笨拙可简化以避免 shell 调cat焦点测试覆盖了主要平价面但noop、abort、interrupted与显式pass_only策略分支仍有扩展空间该车道只验证了焦点平价覆盖与构建状态未跑完整仓库级测试/lint 套件。对照当前源码第一点在现有processAutoresearchCandidate流程中已通过函数参数直传 manifest 的方式得到缓解不再依赖 shell 回读说明这些遗留项属于演进中的常规打磨。结语平价模型的三条启示omx autoresearch的完整评审链条契约 → 评审 → 实现 → 测试对设计任何 Agent 自动化循环都有借鉴价值循环归监督器会话只负责“一轮实验 写产物”循环、决策、回滚全部由外部运行时掌控天然可审计、可中断、可恢复状态权威分层repo-root 的manifest.json是权威真相autoresearch-state.json只是锁worktree 只留运行时产物并显式排除——层次清晰冲突面最小决策可验证候选产物有完整性校验commit 可解析、与 HEAD/last_kept 对齐决策策略有显式表格keep/discard/ambiguous/noop/abort/interrupted每轮结果都落进results.tsv与账本形成可回放的历史。若要继续深入建议阅读 docs/contracts/autoresearch-command-contract.md 获取契约原文配合 src/autoresearch/runtime.ts 与 src/autoresearch/tests/runtime.test.ts 逐行对照迁移到新命令面时参考 src/cli/autoresearch.ts 顶部的弃用指引改用$autoresearchskill 与$deep-interview --autoresearch。【免费下载链接】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），仅供参考