OmX autoresearch 候选交接candidate.json契约thin-supervisor 决策边界与 Parity 测试实战【免费下载链接】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/candidate-handoff这一 autoresearch 试点任务系统拆解其核心目标实现并验证以仓库根目录为锚点的candidate.json候选交接handoff机制让薄监督器thin-supervisor能够依据一个显式的、可测试的候选工件做出 keep / discard / reset 决策。读完本文你将掌握 candidate 工件契约的全部字段与取值语义、supervisor 决策状态机的分支规则、score_improvement与pass_only两种保留策略的区别以及如何用仓库中的 parity 测试验证整条链路。一、任务背景thin-supervisor autoresearch 循环需要什么样的交接missions/candidate-handoff/mission.md描述了一项明确的工程任务Implement and validate repo-rootcandidate.jsonhandoff for the thin-supervisor autoresearch cycle.其两个主要目标分别是每次运行的候选工件契约per-run candidate artifact contract和keep/discard/reset 决策入口keep/discard/reset decision entrypoint成功标准有三条候选交接工件是显式explicit且被测试覆盖的运行时能够区分candidate / noop / abort / interrupted四种状态parity 运行时测试全部通过。所谓thin-supervisor指的是监督者本身不负责实现实验逻辑它只负责编排准备 git worktree、注入指令、等待实验会话写回候选工件、运行 evaluator、根据结果决定保留或回滚。会话与监督者之间的唯一信息通道就是candidate.json这个候选工件——这正是一个典型的控制面与执行面解耦设计执行会话在一个隔离的 git worktree 中工作监督者在仓库根目录下读取并裁决结果。二、运行产物结构candidate.json 在哪个位置、与哪些文件协同从src/autoresearch/runtime.ts的prepareAutoresearchRuntimeruntime.ts可以看到每次运行会在仓库根目录下建立如下目录与文件runId形如missions-demo-20260314t000000z由 mission slug 与运行时间戳拼接而成文件路径相对仓库根目录作用manifest.json.omx/logs/autoresearch/run-id/manifest.json运行清单baseline/last_kept commit、keep_policy、evaluator 契约、运行状态bootstrap-instructions.md.omx/logs/autoresearch/run-id/bootstrap-instructions.md注入给执行会话的指令含候选工件契约与 supervisor 语义candidate.json.omx/logs/autoresearch/run-id/candidate.json核心交接工件会话写回监督者读取裁决iteration-ledger.json.omx/logs/autoresearch/run-id/iteration-ledger.json迭代账本baseline 与每次迭代的决策记录latest-evaluator-result.json.omx/logs/autoresearch/run-id/latest-evaluator-result.json最近一次 evaluator 的原始结果results.tsvworktree 根目录下面向人读的 TSV 汇总iteration commit pass score status descriptionmissions/README.md也明确建议运行完成后检查.omx/logs/autoresearch/run-id/下的manifest.json、candidate.json、iteration-ledger.json三个文件来观察 supervisor 的 keep/discard/stop 决策——这与源码中的落盘路径完全一致。三、candidate.json 工件契约字段与取值语义候选工件的类型定义位于 runtime.ts 的AutoresearchCandidateArtifactexport interface AutoresearchCandidateArtifact { status: AutoresearchCandidateStatus; // candidate | noop | abort | interrupted candidate_commit: string | null; base_commit: string; description: string; notes: string[]; created_at: string; }各字段语义如下字段类型必填语义与约束status枚举字符串是必须是candidate、noop、abort、interrupted之一candidate_commitstring | null是当statuscandidate时必须为非空 commit须能在 git 中解析且与退出时 worktree HEAD 一致base_commitstring是会话开始编辑前的基线 commit必须与 supervisor 提供的 last_kept_commit 一致descriptionstring是一行简短摘要notesstring[]是短字符串数组用于携带额外说明created_atstring是ISO 时间戳prepareAutoresearchRuntime在启动时会先写入一个占位工件runtime.ts保证文件在会话真正写入前就存在{ status: noop, candidate_commit: null, base_commit: baseline-short-commit, description: not-yet-written, notes: [candidate artifact will be overwritten by the launched session], created_at: ISO timestamp }这份占位 JSON 会被注入指令文件明确告知执行会话候选工件稍后将被覆盖。四、四种候选状态与 supervisor 语义buildAutoresearchInstructionsruntime.ts把候选工件的契约逐条写入bootstrap-instructions.md其中 supervisor 侧语义如下statuscandidate→ 运行 evaluator随后 supervisor 决定keep 或 discarddiscard 时可能对 worktree 执行 resetstatusnoop→ supervisor 记录一次 noop 迭代并重新启动下一轮statusabort→ supervisor停止整个运行statusinterrupted→ supervisor先检查 worktree 安全性再决定如何继续。这四种状态在processAutoresearchCandidateruntime.ts中分派noop写入 ledger更新 manifest重新生成指令返回noop循环继续countTrailingAutoresearchNoops会统计末尾连续 noop 次数供上层决定何时收敛abort写入 ledger 后调用finalizeRun将 manifest 置为stoppedstop_reasoncandidate abort返回abortinterrupted先调用assertResetSafeWorktree校验 worktree 干净程度——若被脏文件阻塞则运行进入failedstop_reasoninterrupted dirty worktree requires operator intervention若干净则记录一次interrupted迭代并继续等待下一轮。五、工件完整性校验防伪造、防错位监督者不会盲信会话写回的 JSON。在processAutoresearchCandidate中读取工件后先经过两层校验第一层结构解析。parseAutoresearchCandidateArtifactruntime.ts要求工件必须是合法 JSON 对象status必须是四种枚举之一candidate_commit为 string|nullbase_commit、description、created_at为非空字符串notes必须是字符串数组任何一项不满足都会抛错并使本轮进入error失败态。第二层git 完整性。validateAutoresearchCandidateruntime.ts做三重核对base_commit必须在 git 中可解析git rev-parse --verify解析后的base_commit必须等于 manifest 中的last_kept_commit——防止会话从错误基线出发当statuscandidate时candidate_commit必须非空、可解析且必须等于 worktree 当前 HEAD——防止会话虚报 commit。任何一项失败都会调用failAutoresearchIteration记录error行到 results.tsv 与 ledger并将整个运行置为failedstop_reason给出可行动的诊断信息如candidate base_commit does not match last kept commit、candidate status requires a non-null candidate_commit等。测试runtime-parity-extra.test.ts专门覆盖了缺失候选文件、候选 commit 为空、base_commit 不匹配三类失败路径。六、决策入口decideAutoresearchOutcome 的完整分支决策核心函数是decideAutoresearchOutcomeruntime.ts它把候选状态 evaluator 结果 keep_policy折叠为一个最终决策。完整分支如下条件决策keep?决策理由示例statusabortabort否candidate requested abortstatusnoopnoop否candidate reported noopstatusinterruptedinterrupted否candidate session was interruptedevaluator 缺失或statuserrordiscard否evaluator error / 崩溃或解析失败passfalsediscard否evaluator reported failurekeep_policypass_only且 passtruekeep是pass_only 策略直接接受score_improvement且无可比分数ambiguous否pass 但无数值分数无法比较score_improvement且新分数更高keep是score improved over last kept scorescore_improvement且分数未提升discard否score did not improve关键设计在于score_improvement策略对可比分数的坚持只有当last_kept_score与本次score都是数值时才可比较comparableScore否则即便 evaluator 报了passtrue也会判为ambiguous并丢弃——这避免了无基准的分数被误认为改进。keep_policy 的两种取值AutoresearchKeepPolicy定义于 contracts.ts由 sandbox.md frontmatter 的evaluator.keep_policy声明缺省值为score_improvement见 runtime.tsscore_improvement默认要求新分数严格高于最近保留分数强调可量化改进pass_only只要 evaluatorpasstrue即保留适合无连续分数语义的布尔验证。contracts.ts的parseKeepPolicy会做大小写与空白归一化非法取值直接报错keep_policy must be one of: score_improvement, pass_only。keep 之后的 reset 语义决策为discard或ambiguous时监督者调用resetToLastKeptCommitruntime.ts执行git reset --hard last_kept_commit但在 reset 前必须通过assertResetSafeWorktreeruntime.ts它只容忍四类未跟踪的运行时文件results.tsv、run.log、node_modules、.omx/见AUTORESEARCH_WORKTREE_EXCLUDES任何其它脏文件都会以autoresearch_reset_requires_clean_worktree:worktree:文件列表抛错防止静默丢失会话产物。七、evaluator 契约sandbox.md 与结果解析候选是否被保留最终由 mission 的sandbox.md中声明的 evaluator 说了算。missions/candidate-handoff/sandbox.md的 frontmatter 即是一个规范示例--- evaluator: command: node scripts/eval-candidate-handoff.js format: json ---contracts.ts 的parseSandboxContract对 frontmatter 有硬性校验必须以 YAML frontmatter 开头---包裹evaluator块必须存在evaluator.command必填evaluator.format必填且 v1 中只能是jsonevaluator.keep_policy可选取值限定为score_improvement | pass_only。evaluator 的输出由parseEvaluatorResultcontracts.ts解析必须是合法 JSON 对象pass必须为布尔值score可选出现时必须是数值。{ pass: true, score: 87.5 }运行时通过runAutoresearchEvaluatorruntime.ts以 shell 方式在 worktree 内执行 evaluator 命令捕获 stdout/stderr 与退出码退出码非 0、输出非 JSON、pass缺失、score非数值都会归一化为statuserror的记录并最终映射为discardevaluator error决策。八、测试覆盖三份测试如何锁定契约任务成功标准的第三条parity runtime tests pass对应src/autoresearch/__tests__/下的三份测试runtime.test.ts—— 运行时主链路验证 bootstrap 指令包含exactly one experiment cycle、evaluator 契约required output field: pass、optional output field: score与迭代状态快照验证.omx运行时文件被视为 reset-safe验证prepareAutoresearchRuntime落盘全部产物mission/sandbox/manifest/ledger/results/instructions、manifest 字段mission_slug、branch_name、worktree_path以及 baseline 行写入keep/discard 端到端构造分数从 1 提升到 2 的候选 → 决策keep且last_kept_commit前移再构造分数回落的候选 → 决策discard且 worktree HEAD 被 reset 回改进 commitledger 顺序为baseline → keep → discard。runtime-parity-extra.test.ts—— 边界与异常分支并发锁第二次prepareAutoresearchRuntime因autoresearch_active_run_exists被拒resumeresumeAutoresearchRuntime可恢复 running 态 manifest缺失 worktree 报autoresearch_resume_missing_worktree终态 manifest 报autoresearch_resume_terminal_runambiguousvskeep无基线分数 score_improvement→ambiguouspass_only→keepnoop/abort分支分别记录并最终停运行三例完整性失败candidate_commit 为空、base_commit 不匹配、候选文件缺失均进入failed状态并带可读 stop_reasoninterrupted、evaluatorpassfalse、evaluator 输出非 JSON解析错误三条分支的 results.tsv / ledger 记录断言。contracts.test.ts—— 契约解析单元测试slugifyMissionName的确定性sandbox frontmatter 的解析与各类非法输入无 frontmatter、缺 command、缺 format、format 非 json、非法 keep_policy的拒绝evaluator 结果解析接受{pass:true}与{pass:false,score:61}拒绝缺pass或score非数值mission 目录必须位于 git 仓库内、必须同时存在mission.md与sandbox.md。这三份测试共同构成工件契约显式化 状态可区分 parity 通过的可执行证据。九、从 mission 到实战如何查看与运行missions/README.md说明这些 mission 目录是autoresearch-ready pilots每个目录包含mission.md目标、范围与预期交付物与sandbox.mdevaluator 契约与运行边界。运行后可在.omx/logs/autoresearch/run-id/下观察manifest.json、candidate.json、iteration-ledger.json来核对 supervisor 的每次决策。需要说明当前仓库 CLI 的约束src/cli/autoresearch.ts表明omx autoresearch命令面已进入hard-deprecated状态直接 CLI 启动 / resume / run 均会刻意失败迁移路径是改用$autoresearchskillhook 原生持久循环见 skills/autoresearch/SKILL.md以及$deep-interview --autoresearch用于在编写 mission 工件前澄清目标。因此阅读本仓库时建议以 src/autoresearch/runtime.ts 与 src/autoresearch/contracts.ts 的纯运行时逻辑为准理解契约以三份测试文件作为可执行的行为规范。十、小结候选交接契约的要点清单交接载体仓库根目录.omx/logs/autoresearch/run-id/candidate.json会话写、监督者读是执行面与控制面的唯一信息通道。四态语义candidate进入 evaluator 评估noop记录后重开abort停运行interrupted先验 worktree 安全性。双重校验结构校验字段类型与枚举 git 完整性校验base_commit 必须等于 last_kept_commitcandidate_commit 必须等于 HEAD。决策收敛score_improvement默认需要可比分数提升与pass_only布尔通过即保留两种保留策略discard 前必须 reset-safe。可测试性基线、keep、discard、noop、abort、interrupted、evaluator 失败/解析错误、完整性伪造全部有端到端测试断言构成契约的活文档。理解了candidate.json这份契约就等于掌握了 OmX 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），仅供参考