《Codex 使用手册》· 第 11 章｜接手并改好一个已有小项目

CHAPTER 11 · 连续实战

接手不是先改代码。你会先让“待确认必须独立统计和筛选”在 v1.0 上确定失败，把直接退出码写入 red.log；再只改状态列表、页面选项、统计卡和布局，得到可回退的 v1.1。

打开第 11 章练习入口。完整任务位于练习包内 tasks/chapter-11.md；网站只提供下载与阅读，不会替你执行本地文件。

1. 起点

记录页 v1.0 已通过旧检查。新需求只增加“待确认”状态，并要求它独立统计，不计入“进行中”。

先理解问题

没有 RED 的 GREEN 只能说明某段代码当前没报错，不能说明新测试抓住了需求缺口。这里用同一探针打旧版和新版，让失败原因、最小差异与回归边界都能被第三方复查。

2. 只读输入

• 第 10 章检查通过后，由学习者运行冻结脚本生成的 workbench/chapter-11/v1.0-baseline/tracker-app/
• inputs/chapter-11/change-card.md
• 第 10 章行为基线和通过记录

建议阅读顺序

先读变更卡和第 10 章行为基线，再读探针要验证什么；只有确认“待确认不受支持”是预期失败，才打开工作副本准备修改。

3. 唯一写入位置

只修改 workbench/tracker-app/，并把证据写入 workbench/chapter-11/。其中 v1.0-baseline/ 是学习者自己冻结的只读子目录，永远不得覆盖。

写入位置是本章的安全边界。Codex 可以创建目录，但不能扩大到 inputs、checkpoint 或别章输出。

4. 本章唯一成果

交付记录页 v1.1，以及 change-card.md、red.log、green.log、regression.md、rollback.md。

成果必须能打开、能回查、能由本章检查验证。只有一句“已经完成”不算交付。

5. 可复制给 Codex 的任务

先确认第 10 章已经通过，并存在由 `node scripts/freeze-chapter-10-baseline.mjs` 从你自己的成果生成的 `workbench/chapter-11/v1.0-baseline/`；如果没有，返回第 10 章，不要从公开资料复制完成文件。再读 inputs/chapter-11/change-card.md 和这份基线。不要先修改代码：先用 scripts/run-change-test.mjs 在只读 v1.0 基线上运行新需求测试，必须因不支持“待确认”而失败，并把命令、直接退出码和失败原因写入 workbench/chapter-11/red.log。`run-change-test.mjs` 是外层命令封装器；日志中的 `COMMAND` 会记录它实际调用的底层探针，所以两行命令不同是预期，不是证据错位。确认基线哈希未变后，只在 workbench/tracker-app 修改状态集合、表单选项、筛选和统计，增加独立“待确认”计数。不要改字段或无关样式。旧版合同必须用 `node checks/chapter-10.mjs workbench/chapter-11/v1.0-baseline` 对学习者自建基线运行；不要在已经升级为 v1.1 的 workbench 上执行默认 `npm run check:10`。workbench 中的 v1.1 和四状态回归由 `npm run check:11` 验证。把 GREEN 与回归结果写入对应文件。

把代码块整段复制，不要拆掉输入范围、停止条件和检查命令。Codex 的总结不能代替产出文件。

6. 你必须亲手完成

先打开 red.log，判断它是否真的因“待确认不受支持”失败，而不是路径或语法错误。GREEN 后在页面新增一条“待确认”，确认该卡只进入待确认统计；再筛选“进行中”，确认它没有混入。

人工动作为什么不能省

你要亲手判断 red.log 是否因正确原因退出 1。GREEN 后，在 v1.1 新增“确认下一轮维护频率／待确认”，筛选待确认只见 T-004，并确认它没有混入进行中。

7. 你应该看到

• RED 的直接退出码为 1，错误明确指向未支持的新状态。
• 学习者自建 v1.0 基线前后哈希一致。
• GREEN 后有四个独立状态计数。
• 第 10 章的新增、三种旧筛选和空标题检查仍通过。
• node checks/chapter-10.mjs workbench/chapter-11/v1.0-baseline 退出 0；workbench 的 v1.1 由 check:11 退出 0 证明。

跟着做：从输入到可观察结果

1. 得到正确 RED

确认第 10 章检查已通过并运行过冻结脚本，再执行 node scripts/run-change-test.mjs --expect-red workbench/chapter-11/v1.0-baseline/tracker-app/app-core.mjs workbench/chapter-11/red.log。这是外层命令封装器；red.log 的 COMMAND 记录它实际调用的底层探针，两行不同是预期。

你应看到：red.log 写有 UNSUPPORTED_STATUS: 待确认 与直接退出码 1。

2. 检查最小修改

比较 v1.0 与 v1.1，只应涉及状态集合、HTML 选项和统计卡、统计布局、README。

**你应看到：**字段、数据方式和无关界面没有被重构。

3. 用同一探针变绿

阅读 green.log，并在浏览器新增待确认记录。

**你应看到：**直接退出码 0，四种状态各为 1。

4. 回归与回退

筛选待确认和进行中，运行 npm run check:11，再读 rollback.md。

**你应看到：**旧三状态、自动 ID、空标题均通过，学习者自建基线哈希不变。

本章验收参考：自己核对结果

• red.log 保留旧版直接退出码 1，没有被 GREEN 覆盖。
• green.log 记录直接退出码 0。
• 浏览器中四状态各为 1，筛选待确认只显示 T-004。

这些验收信号帮助你检查自己的成果；它们不是可复制的完成文件，也不能替代实际操作。

8. 三个真实坑

坑 1：没读基线就改

新测试若没有先在学习者自己冻结的 v1.0 基线上失败，就无法证明它能抓住需求缺口。检查要求精确的 RED 原因和基线哈希。

坑 2：顺手重构无关部分

允许差异只涉及状态集合、选项、筛选和统计。检查器会验证学习者自建基线未变和 v1.1 行为，但不会自动判断所有无关重构；你必须亲手比较文件清单与差异。字段、数据方式或大段样式一旦超出变更卡，就停止并从只读基线重建工作副本。

坑 3：把 v1.0 检查指向 v1.1

默认 check:10 的目标是 workbench，但第 11 章完成后那里已经是四状态 v1.1，直接运行会预期退出 1。旧版合同要明确指向 workbench/chapter-11/v1.0-baseline；旧行为在 v1.1 上是否仍成立，则由 check:11 的回归探针判断。

这三个坑都由练习材料、代码或检查实际暴露，不是提醒语。

先看信号，再做补救

**识别信号：**RED 是路径或语法错误、文件差异扩出状态相关逻辑，或旧版检查被指向 v1.1，说明测试顺序或比较对象错了。**补救动作：**保留日志，恢复工作副本到学习者自己冻结的只读 v1.0 基线；先让同一需求探针因 UNSUPPORTED_STATUS 变红，再只改状态集合、选项、筛选和统计，并人工核对差异清单。

补救后仍不能让本章检查因正确原因通过，就按第 10 节停止并回退；不要手改日志或抄写别处的通过结果绕过。

9. 复选框验收

• RED 在学习者自己冻结且未改的 v1.0 基线上因正确原因出现。
• v1.0 基线哈希未变。
• v1.1 的待确认独立计数正确。
• 第 10 章全部旧行为仍通过。
• 旧版合同检查明确指向 workbench/chapter-11/v1.0-baseline，没有把 v1.1 的预期差异误报为回归失败。
• npm run check:11 通过。

每一项都要靠打开文件或完成动作后再勾选；不要只凭 Codex 报告的 PASS。

10. 停止、回退与交接

RED 因路径、语法或缺文件失败时停止，不进入修改；差异超出变更卡时也停止。回退按 rollback.md 用学习者自建 v1.0 基线重建工作副本。交给第 12 章的是 v1.1、RED/GREEN 和回归结论；第 12 章只读接收，不继续改记录页。

**停止条件：**第 10 章未通过或没有学习者自建基线、RED 原因不是新需求缺失、修改扩到变更卡外、旧行为回归失败，或基线哈希变化。

**回退动作：**移走 v1.1 工作副本，从学习者自己冻结的只读 v1.0 基线重建；保留 RED/GREEN 和失败现场。

**交接文件：**v1.1、red.log、green.log、regression.md、rollback.md；第 12 章只读接收，不继续改记录页。