Codex Autoresearch故障排查清单：10个常见报错症状的诊断命令与修复策略
Codex Autoresearch故障排查清单：10个常见报错症状的诊断命令与修复策略
Codex Autoresearch 是一款为 Codex 提供优化循环（benchmark → 实验 → 记录 → 复盘）的插件，但在实际使用中，新手经常遇到各类报错：dist 缺失、benchmark 不输出指标、Dashboard 打不开、ledger 数据异常等。本文整理了一份 Codex Autoresearch 故障排查清单，针对 10 个最常见的报错症状，给出对应的诊断命令与修复策略，帮助你在重复执行命令之前先定位真正出错的层。
💡 核心原则：先定位出错的层，再决定动作。用同样的前置条件重试同一个命令，通常只会得到同样的混乱——只是更旧。官方排查文档见 troubleshooting.md。
一、通用快速诊断：4 条命令先跑一遍
在逐个排查之前，先用这套"快速诊断包"（troubleshooting.md 中的 Fast diagnostic packet）了解全局状态：
node scripts/autoresearch.mjs state --cwd <project> --compact
node scripts/autoresearch.mjs recommend-next --cwd <project> --compact --operator-checklist
node scripts/autoresearch.mjs doctor --cwd <project> --check-benchmark --explain
node scripts/autoresearch.mjs onboarding-packet --cwd <project> --compact
⚠️ 在执行任何可能 commit、revert 或切换分支的命令前，先运行 git status --short 确认工作区状态。
二、安装与运行时故障
1. 源码检出缺少 dist/ 目录
症状：从源码启动时报错，插件目录下没有 dist/。
诊断：确认是否安装了 gh 命令行工具，以及 GitHub 网络是否可达。
修复：在插件目录运行 node scripts/autoresearch.mjs --help 触发 hydration（运行时水合）。注意：如果校验和、release 签名或归档校验失败，hydration 会主动停止——不要跳过。
2. Hydration 报告保留了 rollback 目录
症状：运行时替换过程中报错，提示存在一个未清理的保留回滚（rollback）目录。
诊断：检查报错中点名的 active 与 rollback 目录。
修复：不要删除任何未标记或存在链接关系的路径。只有当 active 目标缺失时，才恢复已标记的 rollback；确认 active 目标有效后，再移除过期的标记 rollback。
3. 源码行为与 Codex 中安装版不一致（runtime drift）
症状：同一份改动，源码直接跑与通过 Codex 插件跑行为不同。
诊断命令：
node scripts/autoresearch.mjs doctor --check-installed --explain
修复：读取输出中的 installedRuntimePath、installedRuntimeShape、installedRuntimeProvenance 三个字段，判断是"水合一个 source 形态的包"、"刷新过期缓存"，还是"清理多个规范版本造成的歧义"。在改回源码行为之前，先消除这种漂移。
4. Setup wrapper 调用自己（递归包装器）
症状：setup 生成的 wrapper 脚本内部又调用了自己，导致递归。
修复：替换这个递归 wrapper，或者用真实的 --benchmark-command 重跑 setup。
三、基准测试与正确性检查故障
5. Benchmark 不输出主指标（no primary metric）
症状：实验跑完了，但解析不到主指标数值。
诊断命令：
node scripts/autoresearch.mjs benchmark-lint --cwd <project>
修复：Codex Autoresearch 要求基准命令至少打印一行 METRIC <primary>=<number>（例如 METRIC seconds=12.34）。修改 wrapper 使其输出该格式；如果是纯计时命令，可配置 --benchmark-prints-metric false。
6. benchmark-lint 超时
症状：连诊断探针都跑不完。
诊断：说明 benchmark wrapper 本身损坏或任务切片过大。
修复：修复 wrapper、预热缓存，或使用有界的任务切片（bounded task slice）。⚠️ 这属于基准修复，不是产品进展——不要把它当成优化成果记录。
7. Checks 失败（correctness 检查未通过）
症状：指标有提升，但 accuracy / 回归等正确性检查失败，状态为 checks_failed。
诊断命令：
node scripts/autoresearch.mjs checks-inspect --cwd <project> --command "<checks>"
修复：单独隔离并修复正确性命令，然后修复该 packet 或 reject 它。在 checks 通过之前，结果只能停留在 experimental 状态。
8. Packet 超时但已写入部分产物
症状：实验 packet 超时，但磁盘上已经留下了一些 artifact。
诊断命令：
node scripts/autoresearch.mjs partial-results --cwd <project> --from-last
修复：先取回部分结果，再决定是否重跑。注意：这些已记录的行只是诊断性的 measure 证据，不能因为"跑得很贵"就被提升为正式结论。
四、Git 与日志（ledger）故障
9. run 编号重复或 ledger 被手工编辑
症状：出现重复的 run 编号、分段错乱，或有人直接改过 autoresearch.jsonl。
诊断命令：
node scripts/autoresearch.mjs ledger-doctor --cwd <project> --json
修复：确认适合做 duplicate-run 归一化后，使用带备份的保护式修复：
node scripts/autoresearch.mjs ledger-doctor --repair --yes --cwd <project>
修复后务必确认返回的 backupPath。详见 operate.md 的 Repair 章节。
10. next_blocked_by_truncated_fingerprints / next_blocked_by_loop_contract
症状：运行 next 被拒绝，报指纹截断或循环契约阻塞。
修复策略：
next_blocked_by_truncated_fingerprints：脏文件无法安全指纹化。清理、提交或 stash 脏路径（或缩小脏文件集合）后重试next；next_blocked_by_loop_contract：决策胶囊或控制平面阻塞项占用了下一个动作。先运行它打印出的阻塞命令并确认，或开启新 segment（new-segment），而不是硬闯。
五、Dashboard 故障
11. 附加排查：Dashboard 打不开或没图表
症状与修复（常见三种）：
| 症状 | 原因 | 修复 |
|---|---|---|
Dashboard 以 file:// 打开 |
静态导出 | 运行 serve --cwd <project>，使用打印出的 loopback URL |
| 实时刷新返回 HTTP 409 | 刷新期间 session 被写入 | 等写入完成后重试，或等下一次自动刷新 |
| 没有图表 | 还没有记录任何 packet | 完整跑完一轮 next + log 循环 |
另外提醒一点常见"认知故障"：Dashboard 是只读的，setup、实验、记录、导出、收尾都必须走 CLI。如果浏览器和终端给出的结论不一致，停下来修好这个分歧，而不是选一个"看起来对"的答案。
六、收尾建议：排查前先记住的三句话
- 先诊断，后重试——用
benchmark-lint、benchmark-inspect、partial-results等便宜命令回答"上次到底哪里失败了"，再决定是否重跑昂贵 benchmark； - 先
git status --short，后写操作——任何可能变更 Git 状态的动作前都先看工作区； - ledger 是唯一记录——聊天历史只能解释上下文，
autoresearch.jsonl才是事实，出现分歧时以 ledger 为准。
更多细节可参考官方文档：Troubleshooting、Operate、Start，以及演示会话示例 demo.md。