run.json 与 events.jsonl 揭秘Codex Autoresearch 事件驱动状态机源码解析【免费下载链接】codex-autoresearchCodex Autoresearch Skill — A self-directed iterative system for Codex that continuously cycles through: modify, verify, retain or discard, and repeat indefinitely. Inspired by Karpathy’s autoresearch concept.项目地址: https://gitcode.com/gh_mirrors/co/codex-autoresearchCodex Autoresearch 是一个面向 Codex 的自主迭代实验系统它围绕run.json与events.jsonl两个核心文件构建事件驱动状态机自动完成修改 → 验证 → 保留或回滚 → 重复的循环直到达成数值目标。本文带你读懂这两个文件各自的角色以及状态机是如何从一条条事件记录中推导出来的——无需深入阅读全部源码也能理解它为何如此可信。两个文件两种职责Autoresearch 的所有运行产物都放在目标仓库的autoresearch-results/目录中其中最关键的两个文件分工极其清晰文件角色特性run.json运行配置目标、范围、指标、目标值不可变初始化后不再修改events.jsonl状态历史基线、迭代、完成等事件只追加永远不删改一句话概括run.json回答这次实验要做什么events.jsonl回答实验进行到哪一步了。官方文档 SKILL.md 在不变量条款中明确写道保持一份权威配置在run.json一份只追加的状态历史在events.jsonl。references/experiment.md 进一步强调当前状态由按顺序校验全部事件推导得出没有任何缓存或对话摘要可以覆盖它——这就是事件驱动状态机的核心思想。run.json一份被严格校验的实验合同初始化时init或launch命令控制脚本会把确认过的配置写入run.json。其字段在 scripts/autoresearch_core.py 中被精确定义goal/scope目标与允许修改的仓库相对路径禁止 glob 通配符metric指标名称、方向lower/higher、验证命令、可选的 JSON 取值键target数值目标guard可选的回归守卫命令max_iterations可选迭代上限branch初始化的 Git 分支它不是宽松读取的而是逐字段强校验的缺字段或多出未知字段都会直接报错见 require_exact_keys禁止重复 JSON 键、禁止NaN等非有限数值指标数值一律用Decimal解析杜绝浮点精度陷阱parse_decimalrun.json中记录的仓库路径必须与当前仓库一致防止张冠李戴load_run这种宁可报错、绝不猜测的风格贯穿了整个项目。events.jsonl每行一个事件的追加日志events.jsonl是状态机的记忆。每一行是一条独立的 JSON 事件由 append_event 写入先按行追加、全程fsync刷盘确保断电也不会留下半截记录。读取时甚至要求文件必须以换行符结尾——最后一行不完整就判定为部分记录并报错load_events。事件类型在 EVENT_FIELDS 中枚举每种类型都有严格的字段契约事件含义关键字段baseline基线测量必须是第一条事件head、metric、验证日志路径iteration一次实验迭代outcomekeep/discard、试验指标、试验提交、回滚提交complete达成目标运行完成reason、metricstopped达到迭代上限或用户停止reason、headblocked真正的外部阻塞缺数据/权限等reasonerror不可恢复的错误reason、日志路径resumed从 blocked/error/stopped 恢复note每条事件还携带run_id和自增序号seq校验时要求seq必须等于行号——任何插入、删改或乱序都会在下次校验时暴露。状态机如何从事件流中长出来核心函数 derive_state 把run.json与完整事件流重放一遍推导出当前状态。它的规则可以归纳为一张简单的状态迁移图baseline ──► active ──keep/discard──► active迭代累加 │ ├─ 指标达标 ─────────► complete唯一出口不可恢复 ├─ 迭代上限/用户停止 ─► stopped ──resumed──► active ├─ 外部阻塞 ─────────► blocked ──resumed──► active └─ 异常 ─────────────► error ──resumed──► active值得注意的几条铁律首条事件必须是baseline否则整个历史无效。终态后不能直接继续只有resumed事件能接在blocked/error/stopped之后而complete永远不可恢复状态校验逻辑。keep 必须名副其实试验指标确实优于保留指标、守卫通过、HEAD 恰好指向试验提交三者缺一不可。discard 必须留下痕迹必须存在revert_commit且 HEAD 指向回滚提交——回滚用的是git revert而非破坏性reset审计线索完整可见。矛盾即错误若active状态下指标已达标却没有complete事件或达到迭代上限却没有stopped事件都会直接抛错。也就是说状态不是被写下来的而是被验证出来的。任何一份不一致的events.jsonl都不可能被误读成正常。失败语义错误本身就是状态references/experiment.md 的Failure Semantics一节点明了设计哲学畸形 JSON、未知字段、事件断号、超时、非 UTF-8 输出、意外 Git 状态……任何一类问题都立即失败并给出精确的错误信息与日志路径。项目明确拒绝用回退解析、旧布局恢复或合成成功来掩盖失败SKILL.md 不变量第 8 条。完整的验证输出保存在autoresearch-results/logs/后台运行的控制器生命周期记录在runtime.log全部可通过 references/background.md 描述的status/stop/resume命令管理。用只读视图检查运行状态理解了状态机查看它就变得简单了。三个命令都会先完整校验run.json与events.jsonl再渲染结果autoresearch.pystatus当前状态、指标进度、控制器存活情况history人类可读的事件表格也可--format tsv导出report生成自包含的 HTML 可视化报告autoresearch-results/report.html报告会把指标轨迹画成曲线每一轮迭代的 keep/discard 结果一目了然——下面这张截图正是一次把解析器错误数降到 0的运行报告你可以看到第 1 轮 discard红色圆点、第 2/3 轮 keep 的完整轨迹小结要点说明单一事实来源配置在run.json不可变历史在events.jsonl只追加状态可推导derive_state按序校验全部事件无缓存、不猜状态状态可审计每次迭代都有试验提交/回滚提交与日志路径失败即停止任何不一致都以精确错误终止而非静默修复如果你想继续深入推荐阅读 docs/GUIDE.md配置与生命周期、references/workflow.md完整工作流以及 tests/test_autoresearch.py状态机规则的测试用例——它们与本文描述的源码行为一一对应。【免费下载链接】codex-autoresearchCodex Autoresearch Skill — A self-directed iterative system for Codex that continuously cycles through: modify, verify, retain or discard, and repeat indefinitely. Inspired by Karpathy’s autoresearch concept.项目地址: https://gitcode.com/gh_mirrors/co/codex-autoresearch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考