如何理解 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-autoresearch
想让 AI 编程助手像真正的研究员一样工作——反复尝试、用数据说话、失败就回滚？Codex Autoresearch 核心循环正是为此而生：它让 Codex 在 Git 仓库中持续执行「修改 → 验证 → 保留或回滚」的无限迭代，直到达成你设定的数值目标。本文将用通俗的语言，完整拆解这套自主实验系统的迭代原理、Git 回滚机制与验证设计，帮你快速看懂 Codex Autoresearch 的核心循环是如何运转的。
什么是 Codex Autoresearch 核心循环？30 秒看懂
Codex Autoresearch 是一个面向 Codex 的自主实验技能（受 Karpathy 的 autoresearch 概念启发）。它的用法非常直白：
你告诉它一个可测量的结果（比如"把报错数降到 0"），它就开始自动循环：观察仓库 → 修改一个点 → 验证 → 保留改进或回滚失败 → 重复，直到目标达成。
整个系统由两个角色分工协作，这是理解核心循环的关键前提：
| 角色 | 负责什么 |
|---|---|
| Codex（AI） | 工程判断：分析代码、提出假设、编写修改 |
| 控制脚本 | 严格执行 Git 边界、测量指标、回滚、记录状态与日志 |
也就是说，AI 只负责"聪明地改代码"，而提交、测量、保留/回滚、状态记录这些容易出错的环节，全部交给一个确定性的脚本来完成。这种"AI 出想法、脚本管纪律"的架构，正是核心循环能长期可信运行的基础。🔁
完整的循环定义写在 SKILL.md 中：inspect -> change one thing -> verify -> keep or revert -> repeat。
核心循环五步走：修改-验证-保留/回滚如何运转
核心循环的每一轮迭代，都可以拆解为五个步骤。下面用一个"降低报错数"的例子说明：
🔍 观察证据（Inspect）Codex 读取已验证的运行状态和最近的实验记录，检查代码、日志等证据，明确"上一次尝试为什么失败"。
✏️ 只改一处（Change One Thing）在预先确认的范围内（比如
src/），只做一个聚焦的、完整的假设性修改。比如"修复嵌套解析分支"。📏 提交并测量（Commit & Measure）控制脚本自动创建一个"试验提交"（trial commit），然后运行你指定的验证命令，得到一个数值（如报错数从 2 变成 3）。
✅/⏪ 保留或回滚（Keep or Revert）
- 指标变好且守卫检查通过 →保留这次提交，在下一次迭代中继续；
- 指标没变好或守卫失败 → 用
git revert回滚这次试验，换一个假设再来。
📝 记录并重复（Log & Repeat）每轮结果都被追加写入事件日志，然后立即开始下一轮，直到指标达到目标值。
README 中对循环的原始描述非常精炼：
观察证据 | 修改一个聚焦的点 | 提交并测量 | +-- 改进 + 守卫通过 --> 保留 | +-- 否则 -------------> 回滚 | 追加一条审计事件 | 重复直到达成目标为什么"每轮只改一处"是核心循环的灵魂？
这是核心循环最反直觉、也最关键的设计：一次finish只允许一个完整实验。
它遵循的是科学实验的"单一变量"原则：
- 如果一轮里改了 5 个地方，指标下降了——你不知道是哪一处起的作用；
- 如果一轮里改了很多，指标变差了——你无法回滚"那一个"有用的改动。
只改一处，每个实验都独立可测量、可逆：
- 成功 → 这次提交就是净收益，进入下一轮；
- 失败 →
git revert完整撤销，仓库回到干净基线，AI 换一条路。
项目明确要求回滚使用git revert而不是破坏性的 reset（详见 references/experiment.md），这样 Git 历史中永远保留着每一次尝试的"足迹"——包括失败的。这既是审计轨迹，也是 AI 下一轮观察的证据来源。
验证（Verify）与守卫（Guard）：两道关卡如何分工
核心循环的"验证"阶段其实有两个角色，理解它们的分工是理解整个机制的钥匙：
| 验证 Verify | 守卫 Guard | |
|---|---|---|
| 回答的问题 | 目标指标改进了吗？ | 试验是否守住了必要行为？ |
| 输出形式 | 一个数值（越低/越高越好） | 通过 / 不通过（退出码） |
| 例子 | python3 scripts/score.py输出报错数 | python3 -m pytest -q全部测试通过 |
| 是否必需 | 必需（核心循环只认这一个指标） | 可选 |
| 特殊要求 | — | 必须在基线时就通过 |
判断规则很简单：指标改进了但守卫失败 → 照样回滚。⏪
典型例子：你在优化接口延迟（指标是 p95 毫秒数），如果某次修改让延迟降低了却导致功能测试挂了，这次试验会被丢弃——因为"更快"不能用"更坏"来换。守卫保护的是指标管不到的行为，两者配合才能让核心循环"只进不退"。
指标输出也有明确契约：验证命令必须正常退出（哪怕测出来的数值很差），并把一个有限数值放在最后一行输出；也可以用 JSON 加一个显式指定的数值键。更多指标模式可以查看 docs/GUIDE.md 的 "Verify And Guard" 章节与 docs/EXAMPLES.md 中的实用示例。
保留还是回滚？Git 就是核心循环的实验记忆
很多人会问：AI 自动跑几十轮，中间乱改了一堆东西怎么办？
Codex Autoresearch 的答案是：Git 就是整个系统的记忆和回滚边界。🧠
- 每一次试验都是一个 Git 提交——没有"悄悄改文件"这回事；
- 非改进或守卫失败的试验，立即
git revert，仓库回到上一个被保留的提交； - 越界修改、分支漂移、指标格式错误、命令超时等任何异常，都会立即停止运行并给出精确的报错和日志路径，绝不"猜着继续"。
所有的运行状态都保存在一个独立、不入库的autoresearch-results/目录中：
| 文件 | 作用 |
|---|---|
run.json | 已确认的、不可变的运行配置 |
events.jsonl | 只追加的事件历史（基线、每轮保留/回滚、终止），是状态的唯一事实来源 |
logs/ | 指标命令、守卫命令、后台 worker 的完整输出 |
特别值得新手注意的是events.jsonl的"只追加"设计：系统只信任这份经过校验的事件日志，绝不从对话记忆或旧文件里"推测"当前状态。这种严格的失败语义（宁停勿猜）看起来苛刻，但它正是长时间自主运行能够被信任的前提。
前台 vs 后台：核心循环的两种运行方式
同一个核心循环，Codex Autoresearch 提供两种运行模式，规则完全一致，只是"谁来推进循环"不同：
| 前台 Foreground | 后台 Background | |
|---|---|---|
| 运行位置 | 当前 Codex 任务中 | 独立的分离控制器 |
| 推进机制 | Codex 官方 Goal 持续续跑 | 每轮启动一个独立的codex execworker |
| 适合场景 | 实时观察、随时指导 | 长时间任务、"跑一夜" |
| 控制方式 | Goal 的暂停 / 恢复 | 用$codex-autoresearch询问状态、停止、恢复 |
- 前台适合想盯着 AI 干活、中途插话调整策略的场景；
- 后台适合"睡前启动，早上看结果"的场景，控制器按序拉起 worker，每个 worker 恰好完成一个实验后退出（架构细节见 references/background.md）。
两种模式共用同一套实验规则与 Git 边界，选哪种不影响核心循环本身的行为。
看懂核心循环结果：HTML 实验报告详解
循环跑完后，你可以直接对技能说"生成 HTML 报告"，它会基于校验后的事件日志生成一份可视化快照（写入autoresearch-results/report.html）。📊
以这份报告为例，核心循环的完整旅程一目了然：
- 基线 2：初始测量，报错数为 2；
- 第 1 轮（红色 discard）：尝试"扩大解析器兜底"，指标升到 3 → 被回滚，保留值仍是 2；
- 第 2 轮（绿色 keep）：修复嵌套解析分支，指标降到 1 → 提交被保留；
- 第 3 轮（绿色 keep）：消除最后一处解析错误，指标归 0 → 达成目标，状态变为
complete。
注意那条蓝色"保留指标"曲线：它只记录被保留的试验，所以只降不升——这正是核心循环"只进不退"特性的直观体现。红色空心点则代表被丢弃的试验，失败也清清楚楚。
除了 HTML 报告，还可以说"查看实验历史"获得表格视图，或"导出为 TSV"用于分析。
新手三步上手：启动你的第一个 Codex Autoresearch 循环
理解了原理，实际使用只有三步（安装步骤见 docs/INSTALL.md）：
第 1 步：准备好一个干净的 Git 仓库
核心循环依赖 Git 做提交与回滚，所以要求：一个干净的具名分支、工作区无未提交改动。
第 2 步：给 Codex 一个可测量的目标
在 Codex 中调用技能，直接描述你想要的结果，例如：
把
scripts/score.py输出的 error_count 降到 0，同时保持 pytest 通过。
第 3 步：确认七项配置后说 "Go"
首次写入之前，Codex 会向你确认这些值（完整定义见 references/workflow.md）：
| 配置项 | 含义 | 示例 |
|---|---|---|
| 目标 Goal | 期望的仓库结果 | 消除解析错误 |
| 范围 Scope | 允许修改的路径前缀 | src |
| 指标 Metric | 数值结果 | 报错数 |
| 方向 Direction | 越低越好还是越高越好 | lower |
| 验证 Verify | 输出指标的命令行 | python3 scripts/score.py |
| 目标值 Target | 达到即"完成"的数值 | 0 |
| 守卫 Guard | 可选的回归检查 | python3 -m pytest -q |
确认后选择前台或后台，核心循环就开始自动运转——每轮试验提交、失败回滚，直到指标达标。中途想停？前台可随时暂停，后台用技能入口请求 stop 即可。
核心循环适合哪些任务？边界在哪里
✅ 非常适合：任何有可重复数值结果的任务——
- 测试失败数、类型错误数、Lint 告警数 → 降到 0
- 代码覆盖率、评分函数 → 提升到某阈值
- 基准延迟（p95）、二进制体积 → 压到目标以下
- 可复现的安全问题数量 → 清零
❌ 不太适合：一次性的小改动、主观的设计评审、部署发布，以及成功与否无法被命令反复度量的任务。对这类任务，更好的做法是先帮它定义一个可复现的指标，再启动核心循环。
另外记住三条边界：一次运行只管理一个仓库、一个主指标、一个目标值；验证命令必须确定性足够高（跑两次能得到可比较的结果）；基准测试如果噪声大，先稳定测试方法再启动，否则噪声会决定哪些实验被保留或丢弃。
一文总结：Codex Autoresearch 核心循环的 5 个关键点
| # | 关键点 | 一句话记忆 |
|---|---|---|
| 1 | 循环结构 | 修改 → 验证 → 保留/回滚 → 无限重复，直到达标 |
| 2 | 单一假设 | 每轮只改一处，成功即净收益，失败可完整撤销 |
| 3 | Git 是记忆 | 每次试验都是提交，失败用git revert，全程可审计 |
| 4 | 双关卡验证 | 指标管"有没有变好"，守卫管"有没有变坏" |
| 5 | 宁停勿猜 | 任何异常立即停止并给出日志路径，绝不猜测状态 |
Codex Autoresearch 的核心循环本质上就是把科学实验的方法论移植到了 AI 编程流程里：提出假设、控制变量、用数据裁决、保留可复现的改进。理解了这个"修改-验证-保留/回滚"的无限迭代机制，你就能把报错清零、覆盖率提升、性能优化这类棘手的仓库级任务，放心地交给 AI 自主完成了。🚀
【免费下载链接】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），仅供参考
