企业官网建设流程全解析

Codex Autoresearch 架构全景：SKILL.md、references 与三大核心脚本如何分工协作

【免费下载链接】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

Codex Autoresearch 是一个让 Codex 自主迭代的技能包：修改代码、验证数值指标、保留改进或回滚失败，循环往复直到达标。本文带你从架构视角看懂它的三大组成——SKILL.md、references/协议文档与三大核心脚本——是如何分工协作的。

30 秒理解 Codex Autoresearch：一个带 Git 边界的实验循环

核心思想只有一句话：

inspect -> change one thing -> verify -> keep or revert -> repeat

Codex 负责"工程判断"——提出假设、改代码；随附的控制脚本负责"严格边界"——测量、回滚、状态与日志。一次实验循环（The Loop）长这样：

inspect evidence | change one focused thing | commit and measure +-- improved + guard passes --> keep +-- otherwise ---------------> revert | append an audit event | repeat until target

适合它任务都有一个共同点：存在一个可重复测量的数值指标——失败测试数、覆盖率、警告数、延迟、二进制体积等。

架构全景：一个入口、三层分工

整个技能可以理解为三层，职责边界非常清晰：

这种设计的妙处：Codex 每次被唤起时只需要读 SKILL.md，再按指引"按需加载"协议文档，既省上下文又保证规则完整。

SKILL.md：技能的前台与命令地图

打开 SKILL.md，你会看到三段关键内容：

• Load（加载规则）：每次调用必读 references/workflow.md；开始活动实验前读 references/experiment.md；后台运行才读 references/background.md。
• Start（启动流程）：前台用init初始化并挂接官方 Codex Goal；后台用launch启动分离控制器。且首次写入前必须获得用户明确确认。
• Invariants（10 条不变量）：比如"初始化要求干净的命名 Git 分支"、"一次finish只做一个聚焦实验"、"绝不隐藏失败、绝不用兜底解析伪造成功"。

可以把它理解为指挥手册：它不写业务逻辑，而是规定 Codex 什么时候做什么、绝对不能做什么。

references/ 目录：按需加载的实验协议库

references/下的 3 个文档各司其职，是典型的"渐进式披露"设计：

其中 references/experiment.md 定义了最关键的两个概念：

• autoresearch-results/run.json—— 不可变的运行配置；
• autoresearch-results/events.jsonl—— 只追加的状态历史。

当前状态永远是"逐条验证全部事件"推导出来的，没有缓存、没有对话记忆。这就是为什么status命令如此权威。

三大核心脚本：执行层的控制平面

scripts/ 目录下的 3 个 Python 脚本是真正的"发动机"，分工如下：

autoresearch.py：命令入口与后台控制器

scripts/autoresearch.py（约 1584 行）是唯一的 CLI 控制平面，提供全套子命令：

• 生命周期：init（前台初始化）、launch（后台启动）、stop、resume、archive
• 实验收尾：finish（提交、测量、保留或回滚一次实验的唯一路径）、block
• 只读视图：status、history、report

后台模式下它还包含一个内部入口_controller：控制器一次只启动一个codex execworker，每个 worker 恰好完成一次实验后退出，控制器验证事件日志后决定是否启动下一个 worker——不轮询、不装 hook、不碰 Codex 配置。

autoresearch_core.py：状态机与 Git 边界

scripts/autoresearch_core.py（约 1213 行）是被上层复用的"规则引擎"，核心能力包括：

• 严格校验：validate_run/validate_event逐条验证 schema，拒绝未知字段、重复键、非 UTF-8 输出；
• 状态推导：derive_state从事件序列推导出当前 status、指标与迭代数；
• Git 操作：commit_trial创建试验提交，revert_trial用git revert回滚（保留可审计痕迹，而非破坏性 reset）；
• 命令执行：run_command带超时并落盘完整输出到autoresearch-results/logs/；
• 指标解析：parse_metric_output支持"末行标量"与"JSON 键"两种显式解析方式。

autoresearch_report.py：只读渲染视图

scripts/autoresearch_report.py（约 524 行）不碰任何状态，只做三件事：终端表格（history）、TSV 导出、以及自包含的静态 HTML 报告（report）。渲染前同样会验证完整的run.json与events.jsonl。

它们如何协作：一次完整迭代的数据流

把三层串起来，一次finish的协作过程是这样的：

1. Codex 依 SKILL.md 指引读取 references/experiment.md，确认迭代契约；
2. Codex 只修改确认范围内的文件，不手动提交，然后调用finish；
3. scripts/autoresearch.py 的finish_iteration校验分支、HEAD、scope 后，调用 core 层commit_trial创建试验提交；
4. 运行 verify 与 guard 命令，core 层解析指标并快照对比控制文件是否被篡改；
5. 指标改进且 guard 通过 → 保留提交；否则revert_trial回滚；
6. 追加一条iteration事件到events.jsonl，目标达成则追加complete。

Codex 改代码，脚本管提交、测量与回滚——双方谁也不越界，这是整个架构的安全基石。

最终交付：一份可追溯的 HTML 实验报告

运行结束后，report命令会基于验证通过的事件历史生成静态报告，存放在autoresearch-results/report.html。报告包含指标轨迹图、逐次实验的 keep/discard 明细、提交哈希与完整日志链接：

红色 discard 点被自动回滚，绿色 keep 点被保留进 Git 历史——每一轮实验的去留都有据可查。

总结：一套值得借鉴的"人机分工"架构

Codex Autoresearch 的架构本质是把"聪明"和"严谨"拆开：

• SKILL.md管"何时做什么"——入口与指挥；
• references/管"规则是什么"——按需加载的协议库；
• scripts/ 三大脚本](scripts/autoresearch.py)管"如何不可错"——CLI 入口、状态机、Git 边界、报告渲染。

想深入细节，推荐阅读这三份文档：references/workflow.md（完整工作流）、references/experiment.md（实验契约）、references/background.md（后台运行时）。🚀

【免费下载链接】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