codex-autoresearch-skill

用途

Codex Autoresearch 是面向 Codex 的自主目标驱动实验系统，持续循环执行：修改代码 → 验证结果 → 保留（若改善）或丢弃（若变差）→ 无限重复。用户只需告诉 Codex 想改进什么，即可离开，回来时获得实验日志和更好的代码库。

主要能力

自主迭代循环（前台或后台）
基于 Git 的实验追踪，失败时自动回滚
双重门控验证（是否改善？是否破坏其他功能？）
升级式重试策略（REFINE → PIVOT → 网络搜索 → 停止）
跨运行学习（从过往实验中积累经验）
多种模式：loop、plan、debug、fix、security、ship、exec

安装

推荐使用 Skill Installer：

# In Codex
$skill-installer install https://github.com/leo-lilinxiao/codex-autoresearch

然后重启 Codex。

手动安装：

# Clone to Codex skills directory
cd ~/.config/codex/skills
git clone https://github.com/leo-lilinxiao/codex-autoresearch

# Or create a symlink
ln -s /path/to/codex-autoresearch ~/.config/codex/skills/codex-autoresearch

完整功能的前置条件（后台运行与无人值守执行）：

# Start Codex with Goals, hooks, and Full Access enabled
codex --enable goals --enable hooks --dangerously-bypass-approvals-and-sandbox

仅前台使用：标准 Codex 工作区权限即可。

使用方式

核心命令：

$codex-autoresearch

这是唯一入口。Codex 会根据自然语言目标推断模式和配置。

基本用法示例

提升测试覆盖率：

You:   $codex-autoresearch
       I want to improve test coverage to at least 80%

Codex 会识别未测试的文件/函数，编写或改进测试，提交每次变更，运行覆盖率检查，覆盖率上升则保留，下降或测试失败则回滚，重复直到达标或被中断。

消除 TypeScript any 类型：

You:   $codex-autoresearch
       Get rid of all the any types in my TypeScript code

后台模式会以分离进程运行，日志写入 autoresearch-results/results.tsv，可停止/恢复，用 tail -f autoresearch-results/results.tsv 查看进度。

修复失败测试：

You:   $codex-autoresearch
       Fix the 12 failing tests

优化性能：

You:   $codex-autoresearch
       Reduce API latency below 100ms

安全审计：

You:   $codex-autoresearch
       Is this code secure?

模式参考

Codex 从自然语言推断模式：

loop：触发词“improve X”“reduce Y”“optimize Z”，迭代改进直到达标或中断
plan：触发词“analyze”“what should I improve?”“suggest metrics”，扫描仓库并提出目标与指标
debug：触发词“why is X happening?”“diagnose”“root cause”，假设驱动的调试与可证伪测试
fix：触发词“fix the N failing tests”“repair”“make tests pass”，顺序修复已知失败
security：触发词“is this secure?”“audit”“STRIDE”“OWASP”，结构化安全分析
ship：触发词“ship it”“ready to release?”“pre-deploy check”，发布就绪验证
exec：CI/CD 非交互自动化模式

配置

通常无需手写配置，Codex 会从仓库和目标推断。如需显式控制，Codex 会展示推断配置并允许调整。高级用法可提供 JSON 配置：

{
  "goal": "Reduce bundle size",
  "metric": "bundle_kb",
  "current_value": 487,
  "target_value": 300,
  "direction": "lower",
  "verify_cmd": "npm run build && du -k dist/bundle.js | cut -f1",
  "guard_cmd": "npm test",
  "scope": "src/**/*.{ts,tsx}",
  "max_iterations": 50
}

# Save to file, then:
codex exec -f autoresearch_config.json

结果与状态文件

所有运行会在工作区根目录创建 autoresearch-results/ 目录：

autoresearch-results/
├── results.tsv          # Full experiment log (audit trail)
├── state.json           # Resume state (last consistent checkpoint)
├── lessons.json         # Cross-run learning (what worked/failed)
└── sessions/
    └── 2026-05-16_14-23-01/
        ├── experiment_1_keep.diff
        ├── experiment_2_discard.diff
        └── ...

查看日志：

# View all experiments
cat autoresearch-results/results.tsv

# Watch live (during background run)
tail -f autoresearch-results/results.tsv

# Filter successful improvements
grep "keep" autoresearch-results/results.tsv

升级策略（卡住时）

循环不会盲目重试，而是升级：

连续 3 次失败 → REFINE：在当前策略内调整
连续 5 次失败 → PIVOT：尝试根本不同的方法
2 次 PIVOT 无进展 → 网络搜索：寻找外部解决方案
3 次 PIVOT 无进展 → STOP：报告需要人工介入

一次成功会重置所有计数器。

停止与恢复

前台运行可中断，状态保存到 autoresearch-results/state.json，用 $codex-autoresearch 恢复。后台运行可检测 PID 并停止，最终状态保存后可随时恢复。恢复时 Codex 自动检测 state.json 并提供续跑选项。

双重门控验证

每次迭代运行两项检查：Verify（指标是否改善）与 Guard（是否破坏其他功能）。伪代码：

git checkout -b experiment_N
modify_code()
git commit -m "experiment N: {hypothesis}"

verify_result = run(verify_cmd)
guard_result = run(guard_cmd)

if verify_result.improved and guard_result.passed:
    git merge experiment_N
    log("keep")
else:
    git reset --hard HEAD~1
    log("discard")

提升覆盖率但破坏测试的变更会被丢弃。

CI/CD 模式（exec）

# Non-interactive, JSON output, exit codes
codex exec -f config.json --max-iterations 20 --timeout 3600

退出码：0 达标；1 达到最大迭代未达标；2 错误或 guard 失败。

高级功能

并行实验（Git Worktrees）：最多同时测试 3 个假设
跨运行学习：lessons.json 累积成功与失败模式，未来运行偏向已验证方法
会话钩子（自动持久化）：每次 Codex 会话结束时保存状态、提交结果日志、备份经验

适用场景

提升测试覆盖率、类型提示覆盖率
消除 TypeScript any 类型、Rust clippy 警告、ESLint 警告
修复失败测试
降低 API 延迟、减小打包体积
安全审计（STRIDE + OWASP Top 10）
发布前就绪检查
CI/CD 自动化流水线

限制

后台运行与无人值守执行需要以 --enable goals --enable hooks --dangerously-bypass-approvals-and-sandbox 启动 Codex
仅前台使用则标准工作区权限即可
若 guard 过严（如测试不稳定）或目标不可达，可能导致所有实验被丢弃、无进展
未设置目标值或指标不稳定时可能无限循环，需设置 max_iterations 或明确目标
状态文件在 JSON 写入期间被中断可能损坏
验证命令需可执行且输出格式可解析
资料未提供收费、价格、平台支持范围等信息