交付与维护

学习目标

读完本课你能：写出「可信」的 README、架构说明与验收报告——标准是不夸大、可复核；建立内容更新与回归检查两个维护流程；用一套交付清单给毕业作品收尾。

问题场景

半年没动项目，今天要给朋友演示。README 写着「开箱即用」——朋友 clone 下来第一步就卡住：没写需要配 .env.local。你翻出半年前的验收记录，只有一句「测试都过了」。交付物的可信度不在写了多少，在于每个陈述都能被复核：说能跑，就得有跑通的步骤；说测过，就得有当时的数字。

核心解释

交付三件套，每件的可信标准不同。

1. README——能让新环境跑起来。 必备四段：能做什么 / 不能做什么（已知限制）、前置条件（Node 版本、可选工具链）、启动步骤（E07 的五步，可直接复制）、数据与配置说明（data/ 是什么、AI 三变量去哪配）。反例是只写 happy path 的 README——「开箱即用」是个可验证的承诺，写之前先在干净环境走一遍（E07 正好练过）。

2. 架构说明——一页讲清数据流。 本站一页能画完：

content/（课程·题目·练习·项目 json/mdx）
  → lib/content/loader → scripts/seed.ts（upsert）→ SQLite（data/database）
  → 页面读取渲染（react-markdown，只渲染不执行）
AI 链路：/api/ai/chat → lib/ai/adapter（唯一出站点）→ 上游模型
  → 工具循环（search_courses 等）→ ai_message / ai_call 落库 → 存为笔记
实验执行：lib/runner/local.ts → data/runs（一次性目录 + 超时 + 输出上限）

3. 验收报告——当时的数字，不是形容词。 直接引用已有检查的结果：npm run typecheck / lint / test 输出、e2e 19 项通过数、已知限制（图像输入未启用、沙箱非容器隔离、quota 类别未实测）。报告带日期——半年前的数字不代表今天。

两个维护流程（写成制度，不靠记忆）：

• 内容更新：改 content/ → npm run content:check → npm run db:seed → 刷新验证。课程内容版本用 SemVer（语义化版本）：内容修正升 patch（1.0.1），新增课程升 minor（1.1.0），结构破坏性调整升 major（2.0.0）——本站每门课的 version 字段就是这么管理的。
• 代码回归：改动后按序跑 typecheck → lint → test → build → e2e，结果记入变更记录。改什么记什么，分类用 Keep a Changelog 的约定（Added / Changed / Fixed）。

示例拆解

一份合格的验收报告骨架（每条都可复核）：

## 验收报告 2026-10-26 · ReactLab 毕业交付

### 检查链
- typecheck / lint / test：全部通过（命令与输出已留档）

### 核心路径
- node scripts/e2e-core.mjs → 19/19 通过（耗时 xx 秒）

### 已知限制（诚实清单）
- 图像输入未默认启用（A37 口径：以提供方文档为准）
- 实验执行为目录隔离 + 资源限制，非容器级隔离（单人自用取舍）
- quota 错误类别未实测（本机无法触发账户欠费）

### 变更记录
- Changed: e2e 新增「搜索空态」检查（第 20 项）

关键点：「已知限制」是可信度的来源——全绿无限制的报告反而可疑，限制写清楚了，读者才知道边界在哪、哪些检查可信；每条结论都挂着一个可复现的命令或数字，复核成本一分钟。

毕业验收 = 两张清单叠加：A36 的上线检查（秘密/配置/权限/失败/日志/评估）+ 本课的交付清单（README/架构/验收报告/变更记录）。两张全打勾，项目才算交付完成——之后它进入维护态，靠本课的两个流程活着。

动手任务

1. 按四段结构重写（或校对）项目 README，特别补上「已知限制」——把 A37、E05 的诚实口径落进去。
2. 给最近一次真实改动补一条变更记录（分类 + 一句话 + 影响范围），跑一遍回归五连并记录结果。
3. 把验收报告骨架填成你的真实数字，存进 docs/，日期写今天。

常见错误

• README 只写理想路径：没写前置、没写限制，「开箱即用」在别人的机器上第一分钟就破产。
• 验收报告复制旧结果：数字是半年前的，代码是今天的——报告必须带当日日期与当日命令输出。
• 改动不记变更记录：两周后「这行为什么这么写」没人答得上来；变更记录是留给未来自己的排错线索。
• 版本号乱升：内容小修升 major，回滚就没了参照——SemVer 的意义就是让「升」有共同语言。

检查与复盘

• README 在干净环境按步骤能真跑通，「已知限制」至少三条
• 验收报告里的每个数字都对应一条可复现的命令
• 内容更新与回归两个流程已执行过至少一次，留有记录

参考资料

• GitHub 官方：About READMEs —— README 的定位与惯例
• Keep a Changelog —— 变更记录的分类与写法标准
• Semantic Versioning —— 版本号语义的规范原文