《Codex 使用手册》· 第 10 章｜做一个自己会用的小工具

CHAPTER 10 · 连续实战

这一章不讨论“以后可以做什么系统”。你会拿到一个真实离线页面，亲手新增 T-004、观察统计变化、按状态筛选，再刷新确认数据不会假装永久保存。

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

1. 起点

你有一张五字段需求卡和三条虚构记录，需要做一个本地网页。目标只是“能记录、能筛选、能统计”，不是完整管理系统。

先理解问题

页面“能打开”只证明 HTML 存在。可用工具至少要完成一次输入—结果闭环，并诚实说明数据边界。本章把范围压到四个输入字段、三种状态和四个可观察行为，避免一上来造完整系统。

2. 只读输入

• inputs/chapter-10/field-card.md
• inputs/chapter-10/records.json
• 第 9 章已验收内容包的用途说明

建议阅读顺序

先读字段卡中的“做什么／不做什么”，再读三条样本；不要寻找现成页面，也不要从完成结果反推需求。第 10 章检查通过后，再把你自己的成果冻结成第 11 章基线。

3. 唯一写入位置

先只写 workbench/tracker-app/。本章检查通过后，冻结脚本才可创建 workbench/chapter-11/v1.0-baseline/；不要手工改写该基线。

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

4. 本章唯一成果

完成 index.html、styles.css、app-core.mjs、app.js、records.json 和 README.md 的记录页 v1.0，并从这份通过验收的成果冻结第 11 章只读基线。

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

5. 可复制给 Codex 的任务

根据 inputs/chapter-10 的字段卡和三条虚构记录，在 workbench/tracker-app 建一个不联网的本地记录页 v1.0。字段只有自动 ID、任务名称、状态、下一步、待确认问题；状态只有未开始、进行中、已完成。实现新增、全部查看、按状态筛选和三个独立统计；空任务名称必须拒绝，也必须拒绝任何不在三种允许值中的状态并明确指出它不受支持。数据只保存在页面内存，刷新后恢复三条样本，并在页面明确提示这一点。不得读取其他资料或增加账号、同步、权限、数据库。完成后先运行 npm run check:10；只有检查通过，才运行 node scripts/freeze-chapter-10-baseline.mjs，把自己的成果冻结成第 11 章基线。

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

6. 你必须亲手完成

启动 npm run preview，打开终端打印的根地址，再把路径切换到 /workbench/tracker-app/index.html。在浏览器新增一条有标题的虚构记录；切换到一个状态筛选并核对列表；再切回全部，核对三个统计。刷新页面，确认它恢复为三条起始样本。第 10 章检查通过后，运行 node scripts/freeze-chapter-10-baseline.mjs，确认终端输出 CH10_BASELINE_FROZEN 或 CH10_BASELINE_UNCHANGED。

人工动作为什么不能省

你要亲手新增“复查第九章五条陈述”，确认 T-004 和 2／1／1 统计；再筛选、提交一次空标题并刷新页面。页面内存边界只有经过刷新才真正被理解。

7. 你应该看到

• 空标题提交时出现明确错误且列表不增加。
• 直接向核心逻辑提交“待确认”等第四种状态时被明确拒绝；这样第 11 章才能因同一缺口得到正确 RED。
• 有效记录得到自动 ID 并立即进入列表。
• 筛选后只显示所选状态，统计仍按全部内存记录计算。
• 刷新后回到三条样本，页面说明没有持久保存。

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

1. 建立 v1.0 副本

把第 5 节任务整段交给 Codex，让它只在 workbench/tracker-app/ 建立页面。

**你应看到：**工作台出现 HTML、CSS、核心逻辑、页面脚本、三条样本和说明。

2. 完成一次有效新增

启动 npm run preview，填写任务名称、未开始、下一步和待确认问题后提交。

**你应看到：**自动生成 T-004；未开始由 1 变 2，其他统计仍为 1。

3. 筛选并制造无效输入

筛选未开始，再清空任务名称提交；随后用检查器向核心逻辑提交“待确认”状态。

**你应看到：**列表只显示匹配行；空标题不会增加记录；第四种状态被明确判为不支持。

4. 刷新、验证并冻结

刷新页面后运行 npm run check:10；只有检查通过，才运行 node scripts/freeze-chapter-10-baseline.mjs。

**你应看到：**恢复三条虚构样本；检查输出包含 add、filter、3 counts、blank title rejected，并生成你自己的只读 v1.0 基线。

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

• 浏览器实际新增 T-004，页面快照显示 2／1／1。
• 空标题和不在三种允许值中的状态都由核心逻辑拒绝。
• 刷新恢复三条样本；检查通过后，学习者自己的 v1.0 基线已冻结且哈希可核对。

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

8. 三个真实坑

坑 1：把小工具扩成完整系统

字段和状态由输入卡冻结。若增加登录、同步、优先级或数据库，范围检查会拒绝这些未授权能力。

坑 2：读取现实数据

页面只能加载本地 records.json。代码扫描会拒绝外部请求、浏览器存储和不在练习包内的数据地址。

坑 3：页面能开却不能完成动作

检查直接调用核心函数验证新增、过滤、统计、空标题和未知状态拒绝，不接受“有按钮、有文字”作为功能完成。

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

先看信号，再做补救

**识别信号：**页面出现需求卡外字段、发起网络请求、刷新后保留练习记录，或空标题也能入表，说明 v1.0 边界被突破。**补救动作：**回到字段卡，只保留五个字段、三个状态和内存态；依据输入卡重建工作副本并逐项复演新增、筛选、计数和拒绝。检查未通过前不要冻结基线。

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

9. 复选框验收

• 页面只显示五个约定字段。
• 有效记录可新增，空标题被拒绝。
• 不在三种允许值中的状态被明确拒绝。
• 三个状态均可筛选且计数正确。
• 刷新后恢复虚构样本并有内存态提示。
• npm run check:10 通过。
• 第 10 章检查通过后，冻结脚本从我自己的 workbench/tracker-app/ 建立了 v1.0 基线。

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

10. 停止、回退与交接

一旦需要联网、读取现实记录、增加需求卡外字段或引入安装依赖，就停止。回退为删除 workbench/tracker-app/ 的本章输出并从输入卡重建。第 10 章检查通过后，交给第 11 章的是 v1.0 文件、npm run check:10 结果和由冻结脚本生成的 workbench/chapter-11/v1.0-baseline/；公开练习包不预置这份完成态。

**停止条件：**页面尝试联网或持久化、字段超出需求卡、核心行为不一致，或尚未通过第 10 章检查就准备冻结基线。

**回退动作：**删除不合格的 workbench/tracker-app/，依据 inputs/chapter-10/ 重建；已有合格基线不得手工覆盖。

**交接文件：**工作副本、第 10 章通过结果，以及由冻结脚本从该成果生成的只读 v1.0 基线；第 11 章必须先让新需求在这份基线上失败。