在需要无人值守迭代优化可衡量代码指标时，用 Codex…

适用于 Codex 项目中，用一个可量化 verify command 驱动自动修改、验证、保留或回滚，持续改善覆盖率、类型错误、bundle size、lint 等指标。

适用场景

解决思路

1. 安装方式 A：在项目内手动复制技能，先执行 `git clone https://github.com/leo-lilinxiao/codex-autoresearch.git`，再执行 `cp -r codex-autoresearch your-project/.agents/skills/codex-autoresearch`。
2. 安装方式 B：用 Codex 技能安装器，执行 `$skill-installer install https://github.com/leo-lilinxiao/codex-autoresearch`。
3. 技能位于 `.agents/skills/codex-autoresearch/`，首次使用无需配置文件。
4. 在项目目录打开 Codex，用 `$codex-autoresearch` 前缀加一句话目标来激活，例如 `$codex-autoresearch I want to get rid of all any types in my TypeScript code`。
5. Codex 会扫描仓库并推断 scope、metric、verify command、guard command；无需手写配置。
6. Codex 展示确认摘要；回复 `go` 或纠正问题；最多 5 轮确认，之后自动继续。
7. 确认时可选择运行到全部完成，或设置 `Iterations: N` 作为上限。
8. PHASE 0：探测环境（CPU/GPU/RAM/toolchains），并检查是否有 session resume。
9. PHASE 1：读取上下文，以及上次运行留下的 lessons 文件（如果有）。
10. 每轮先回顾当前状态、git 历史、results log、lessons。
11. 每轮选择一个假设（ONE hypothesis），应用不同视角，并按环境过滤；并行模式下可选 N 个假设。
12. 每轮只做一个原子修改（ONE atomic change）。
13. 修改后在验证前先执行 `git commit`。
14. 运行 verify command 判断目标指标是否改善；运行 guard command 判断是否破坏其他东西。
15. 若指标改善则保留并提取 lesson；若变差则按批准的 rollback 策略执行 `git revert`；若崩溃则修复或跳过。
16. 将结果记录到 results log。
17. 执行健康检查：disk、git、verify health。
18. 若连续 3+ 次 discard 则 REFINE；5+ 次则 PIVOT；2 次 PIVOT 后执行 web search。
19. 重复循环；除非设置 `Iterations: N`，否则无界运行，不停止、不询问。
20. 双门验证：Verify 门判断目标指标是否改善，失败则丢弃并回滚；Guard 门判断其他是否破坏，失败则最多重做 2 次，然后回滚。
21. Guard 文件绝不被循环修改。
22. 模式 `loop`：默认模式，迭代到可衡量的目标，例如提高覆盖率或降低 bundle size。
23. 模式 `plan`：把模糊目标转成经过验证的 loop config，Codex 会提问，例如 p95 latency 还是 throughput、哪个 endpoint。
24. 模式 `fix`：修复错误直到数量为零，例如修复 12 个 pytest 失败。
25. 模式 `debug`：证据驱动根因寻找；每轮测试一个可证伪假设，展示证据而非猜测。
26. 模式 `security`：只读 STRIDE + OWASP 审计。
27. 模式 `ship`：发布准备验证和 release gating。
28. 模式 `exec`：一次性执行，不进入循环。
29. 内联覆盖：在确认步骤说 `Iterations: 20` 限制 20 轮；`Parallel: 3` 每轮并发测试 3 个假设；`Guard: npm test` 覆盖 guard；`Verify: <command>` 覆盖 verify；`Scope: src/api/` 限制修改子目录。
30. 跨运行学习：每轮结束把结构化 lesson 写入 `.agents/skills/codex-autoresearch/lessons.md`，字段包括 Iteration、Hypothesis、Change、Result、Lesson。
31. 恢复中断运行：执行 `$codex-autoresearch` 后输入 `Resume`；Codex 重新读取 lessons 文件、检查 git 状态、重建 baseline 并继续。
32. 并行实验：确认时或之后说 `Go, parallel 4`；Codex 并发运行四个假设，保留最佳结果，丢弃其余。
33. Pivot 协议自动升级：3 次连续 discard 后 REFINE 收窄假设并尝试更小原子修改；5 次后 PIVOT 完全改变策略；2 次 PIVOT 后让 Codex 进行 web search 获取外部参考；升级期间不请求许可。
34. 示例 TypeScript any 消除：创建 `scripts/count_any.py`，用 `grep -r "any" --include="*.ts" src/` 统计行数，始终 `sys.exit(0)`，只输出数字；确认时配置 `Verify: python scripts/count_any.py` 和 `Guard: npx tsc --noEmit`。
35. 示例 pytest coverage：创建 `scripts/coverage_pct.py`，运行 `pytest --cov=src --cov-report=term -q`，用正则匹配 `TOTAL` 百分比，始终 exit 0；配置 `Verify: python scripts/coverage_pct.py`、`Guard: python -m mypy src`、`Direction: higher`、`Target: 85`、`Iterations: 50`。
36. 示例 bundle size：创建 `scripts/bundle_size.sh`，运行 `npm run build --silent`，用 `du -k dist/bundle.js | awk '{print $1}'` 输出 KB；配置 `Verify: bash scripts/bundle_size.sh`、`Guard: npm test`、`Direction: lower`、`Target: 900`。
37. 示例 lint warning 计数：创建 `scripts/lint_count.sh`，运行 `npx eslint src/ --format json`，用 Python 解析 JSON 并统计所有 `messages` 数量；配置 `Verify: bash scripts/lint_count.sh`、`Direction: lower`、`Target: 0`。
38. 无人值守运行：确保 Codex CLI 审批设置不会打断 `git commit` 或 `git revert`；最简单是在一次性或沙箱仓库克隆中运行：`git clone . /tmp/autoresearch-sandbox`，`cd /tmp/autoresearch-sandbox`，然后在此以完整权限启动 Codex。
39. 完成后把获胜提交拉回主仓库：在主仓库执行 `git fetch /tmp/autoresearch-sandbox main`，再执行 `git cherry-pick <winning-commit-sha>`。
40. 会话产物：`.agents/skills/codex-autoresearch/lessons.md` 存结构化 lesson；`.agents/skills/codex-autoresearch/results.log` 存每轮完整日志，包括指标值、kept/reverted、elapsed；`.agents/skills/codex-autoresearch/session.json` 存当前 session 状态用于 resume；这些文件跨 Codex session 持久，删除可重新开始。
41. 故障排查：循环回滚每次更改时，手动测试 verify command，执行 `bash -c "<your verify command>"` 应打印单个数字；确认 `Direction: lower` 或 `Direction: higher`。
42. Guard 对无关文件触发时，缩小 scope：`Scope: src/specific-module/`，或在确认时明确说 `Do not touch tests/`。
43. Session resume 基线错误时，删除 `session.json` 强制新基线：`rm .agents/skills/codex-autoresearch/session.json`。
44. 并行模式产生 merge conflicts 时，减少并行度：`Parallel: 2`；Codex 会通过 pivot protocol 内部处理冲突。
45. Codex 在 loop 中提问时，通常表示 guard crash 产生歧义输出；可指定 `Guard: <command> || true` 让 guard 失败非致命，或给 Codex 更完整沙箱权限。
46. 命中 PIVOT 但无进展时，在确认时提供 seed hypothesis：`Hint: try tree-shaking unused imports first`；或先运行 `plan` 模式生成更丰富假设列表，再切到 `loop`。
47. 快速参考：启动循环用 `$codex-autoresearch` 加一句话目标；恢复用 `$codex-autoresearch` 加 `Resume`；有界运行加 `Iterations: 25`；并行假设加 `Parallel: 4`；强制模式用 `$codex-autoresearch fix` 加错误；只读审计用 `$codex-autoresearch security` 加审计目标。

适用边界 · 注意事项

• 目标不可测量、verify command 无法输出单个数字指标时，不适合启动该循环。
• 无法允许 Codex 自动执行 git commit、git revert 或不能提供沙箱/完整权限时，不适合长时间无人值守运行。
• 只需要一次性执行、只读审计或发布检查时，不应使用持续 loop，可改用 exec、security 或 ship 模式。