CI 红了，先别让 Codex 改代码：从失败步骤到最小修复
先分清测试失败、环境失败和生成文件未同步；用本站可运行实验，把报错、根因假设和验收证据连起来。
内容核对
适合遇到“本地能跑，提交后检查却失败”，准备把日志交给 Codex 的开发者。你需要失败运行的链接或日志、对应提交，以及仓库的工作流配置；不需要先升级模型或开放更多权限。
读完应能交付一份很短的诊断：哪个提交的哪一步失败、证据支持什么原因、最小修改是什么、怎样证明修复有效。 下面附本站可以直接运行的隔离实验，不需要把生产分支故意弄坏。
1. 先交给 Codex 五条信息
从失败的运行详情取得以下信息，缺项就标“未知”。日志先脱敏，保留真正失败步骤附近的上下文即可，不必一上来粘贴所有任务的输出。
运行链接与 attempt：
对应 commit SHA、分支或 PR：
失败 job / step 与实际命令：
首个与失败直接相关的错误及上下文：
本地环境、复现结果、已有未提交改动：
不要只截最后一行 Process completed with exit code 1。它告诉你进程失败了，不能单独说明该改应用代码、配置还是生成文件。日志里的 warning、后续取消的步骤、另一个提交的成功记录，也不能替代这次失败原因。
如果使用 GitHub CLI，先用 gh run view 查看指定运行的 job、step、SHA；--log-failed 可读取失败步骤日志。参数与限制见 GitHub 官方命令说明（2026-10-07 核对）。运行仍在进行、日志过期或没有权限时，保留“日志不可得”，不要编造根因。
2. 按失败步骤分流，不按报错气氛猜
| 失败位置与证据 | 先核对什么 | 暂时不能得出的结论 |
|---|---|---|
| 安装依赖：下载超时、认证失败或锁文件不匹配 | 原始错误、锁文件、运行环境与依赖源 | 不能直接证明业务代码有 Bug |
| Lint / 类型检查 / 测试 | 具体规则、文件位置、失败断言和触发输入 | 不能通过删测试或关闭规则来宣称修复 |
| 构建成功，生成文件差异检查失败 | 源内容与生成快照是否一起更新 | 不一定需要改页面组件 |
| 页面检查报连接失败 | 服务是否启动、地址端口与服务日志 | 不能直接当作页面 404 |
| 同一检查时好时坏 | 同一 SHA、环境和多次运行的差异 | 单次重跑变绿不能证明根因消失 |
本站工作流保存在 quality.yml。请读自己仓库的配置，不能把本站命令原样当成所有项目的验收标准。
3. 可运行案例：文章改了，生成快照没跟上
本站把 content/ 源内容生成到 lib/generated-content.json，页面使用这个快照。只交源文而漏掉生成结果，会造成内容与快照不一致。
本次维护前，检查位于生产构建之后：先重新生成，再用 Git 差异发现遗漏。本次增加 npm run check:content，在不写文件的情况下比较当前源内容与快照，并把它接到 CI 构建前。原来的构建后 Git 差异检查仍保留。
在已安装锁定依赖的本站仓库运行：
npm run test:content
npm run check:content
test:content 在独立临时目录执行四项实验，结束后清理夹具，不修改你的文章或生成文件：
| 实验 | 实际断言 |
|---|---|
| 快照与源内容一致 | 预检退出 0，快照字节与修改时间保持不变 |
| 修改源文，保留旧快照 | 预检退出 1，旧快照字节不变；重新生成后预检退出 0 |
| 缺失快照 | 预检退出 1，不偷偷创建文件 |
| Frontmatter 无效 | 命令失败，保留原快照 |
2026-10-07 本站本地执行上述测试，4 项通过、0 失败；Node.js v25.8.0，npm 11.11.0。CI 配置使用 Node.js 24，本地版本通过不代替远端检查。实现与可复现断言见 测试文件。
旧快照场景的错误提示是：
Content snapshot is missing or stale: lib/generated-content.json
Run npm run generate:content, review the diff, and commit the intended content and snapshot together.
这时最小修复是核对源文、重新生成并审查差异，不是重写应用：
npm run generate:content
npm run check:content
git diff -- content/ lib/generated-content.json
npm run lint
npm run build
只把确认属于本次任务的源文和生成结果一起提交。check:content 只检查工作区内容是否一致，不证明文件已经提交、远端 CI 已通过或生产已更新。不要手改生成 JSON 来掩盖源内容错误，也不要为让预检变绿而恢复或删除用户原有修改。
4. 两段任务描述，把“修好 CI”缩到有证据的一步
先诊断，要求区分事实和假设：
请先只读检查这次 CI 失败：[运行链接、attempt、SHA]。
读取工作流配置和失败步骤日志，结合我提供的本地环境与已有改动。
列出：失败的实际命令、关键错误、证据支持的原因、尚未确认的假设。
提出一个最小复现或验证动作；不要改代码、删测试、扩大权限或重跑部署。
日志不足时明确指出缺哪一项，不要把最后的 exit code 当作根因。
确认原因后再约束修改与验收：
已确认的问题是：[证据与原因]。只修复这一项，保留原有改动。
先运行与失败步骤一致的最小检查，再审查差异；不要降低测试或规则要求。
必要检查通过后给出：改了什么、实际命令和退出码、仍未验证的环境。
远端运行请按本次提交 SHA 核验；将本地通过、远端 CI、部署、线上效果分开。
未确认前一次外部操作状态时，不重复提交或部署。
这些是本站整理的任务模板，未在读者仓库实测。其“复现、最小修改、重新验证”的安排参考当日读取的 OpenAI Prompting，不能保证每种 CI 故障都能恢复。
5. 最后验收什么
- 初始失败有可回看的证据；若只在 CI 出现，说明本地未复现以及环境差异。
- 修复针对已证实的原因；没有混入无关改动、删除失败断言或降低检查要求。
- 记录实际运行的命令、结果与适用提交。缺少权限、日志或对应环境时标未验证。
- 提交后查询同一 SHA 的远端检查；不要拿前一个提交的绿色状态作证。
- 需要上线时，再独立检查发布记录和实际页面。CI 通过不等于用户问题已解决。
本例验证的是检查器能发现受控的不一致、保持文件不变，并在正确生成后恢复通过；没有制造远端失败运行，没有测量 Codex 节省了多少时间。更多记录方法见进展与验收记录表，页面链接问题见从复现到回归检查。