📊 概念入门文档站 — 完成度报告#
本报告记录「面向小白文档站」这一轮增强的落地情况：新增了什么、当前覆盖到什么程度、还剩什么没做。
生成方式：全部数字来自npm run docs:build/docs:lint/docs:verify的真实输出，非估算。
想直接开始学？回 概念入门总览。
一、这一轮做了什么（本批新增）#
这一轮是「继续优化」——在已达教科书级的概念站上做纯追加，不重写任何既有文档。共四件事：
- 新增互动件类型：时间轴（timeline）
作者只需写一个 `timeline 围栏，每行 标签 | 描述，即可渲染成一条竖向、逐条滚动进入的时间线。纯 CSS 实现、复用既有的滚动进入动画（initReveal），零新增 JS。已配套写进 linter（防呆校验）与单元测试。
- 补齐 flip 翻卡平权：5 篇 CONCEPT 各 +1
CONCEPT-21/23/24/26/28 原本没有 flip 翻卡，这一轮各补一张，放在每篇「X vs Y 对比」那一节，让"先猜后翻"的互动在进阶篇里也齐整。（00_INDEX 是纯导航页，合理保持无 flip。）
- 新增 3 篇概念文档（㉙㉚㉛）——"动手接入 + 避坑"实战篇
| 编号 | 文档 | 讲什么 |
|---|---|---|
| ㉙ | 什么是 API 与 SDK | 一动手就绕不开的两个词，附「首用 timeline」演示接入方式的演进 |
| ㉚ | 函数调用与 MCP 辨析 | 掰清"函数调用/工具调用/MCP"这组最容易混的词 |
| ㉛ | 什么是幻觉（Hallucination） | AI 为什么"一本正经胡说"、又该怎么防 |
三篇均沿用九节骨架，并已在 00_INDEX 表格与结语注册、彼此交叉链接。
二、互动件覆盖统计（当前全景）#
概念站现有 31 篇 CONCEPT + 1 篇 INDEX = 32 篇（本报告不计入教学篇计数）。核心互动件覆盖如下：
| 互动件 | 作用 | 覆盖情况 |
|---|---|---|
| callout（吉祥物插话） | tip/note/warn/star/ask 五种语气的旁白 | 31 篇 CONCEPT 全覆盖（每篇 ≥1） |
| quiz（练习互动窗） | 选择题 + 逐项解释，做错也长知识 | 31 篇 CONCEPT 全覆盖（每篇 =1） |
| flip（翻卡） | 先猜后翻的 3D 卡片 | 31 篇 CONCEPT 全覆盖（本轮补齐 5 篇后无缺口） |
| mermaid（图表） | 流程图/关系图，把抽象讲成画面 | 31 篇 CONCEPT 全覆盖（每篇多张） |
| popover（行内弹窗） | 行内 +[文字](提示) 悬浮补充 | 31 篇 CONCEPT 全覆盖 |
| timeline（时间轴） | 演进/阶段流程的竖向时间线 | 本轮新增件，首个消费者 CONCEPT-29；按需铺开 |
新增 3 篇的实测件数（
grep核对）：
- CONCEPT-29：callout×5 · quiz×1 · flip×2 · timeline×1 · mermaid×1 · popover×2
- CONCEPT-30：callout×5 · quiz×1 · flip×1 · mermaid×2 · popover×3
- CONCEPT-31：callout×4 · quiz×1 · flip×1 · mermaid×3 · popover×1
三篇均满足硬性门槛
flip≥1 · quiz=1 · callout≥1 · mermaid≥1 · popover≥1。
三、全站健康度（验证门实测输出）#
| 验证门 | 命令 | 结果 |
|---|---|---|
| 互动件防呆 | npm run docs:lint | ✅ 扫描 427 md · error 0 · warning 0 |
| md↔html 配对 + 链接可达 | docs:verify（verify_docs_site） | ✅ 658 md → 659 html · 8331 链接全部可达 |
| 面向小白体检 | docs:verify（check_beginner_docs） | ✅ 无孤儿页 · 编号连续 · 故事均有凡人笔记 · 正文均有底部导航 |
| widget 单元测试 | node --test build_docs_site.test.js | ✅ 13/13 pass |
对比上一轮基线（655 md / 656 html / 8273 链接）：本轮 md 计数上抬至 658（+3 新概念篇），链接总数增至 8331，零死链、零孤儿页——是健康增长，不是回归。
四、还剩什么没做（诚实的待办清单）#
按「不做静默截断」的原则，明确列出本轮刻意留到下一批的部分：
- 概念篇待补（下一批）
- Token 计费与成本：把"一次调用要花多少钱、怎么估算、怎么省"讲透（现散见于 CONCEPT-08）。
- Eval / 评测：怎么衡量一个 AI 应用"到底好不好、有没有变差"。
- 修仙故事番外（㉙㉚㉛ 的孪生）——刻意不加，理由如下
09_STORY_修仙学AI/ 是一部已完结、结构自洽的修仙长篇（孔浩原从药童到渡劫飞升，境界阶梯层层对应概念）。为 ㉙㉚㉛ 硬插三章中段番外，会打断这条已封笔的修炼主线（B3 外科原则：不顺手改动不该动的完整作品）。
值得一提的是：幻觉（㉛）这个概念，在故事里其实已由"幻魔道"反派线承载（"求真 vs 造假"的对抗）——再单开一章反而重复。
因此这三篇的故事化，作为独立议题留待后续：要么等故事作者决定如何在不破坏主线的前提下扩写，要么以别的轻量形式（如概念篇内的小故事段）承载。
- timeline 的更多消费点
本轮 timeline 仅在 CONCEPT-29 首用（形成闭环验证）。其它适合"演进/阶段"叙事的篇目（如 RLHF 的训练三步、Transformer 的发展史）可在后续按需补挂——非必需，属锦上添花。
五、一句话总结#
这一轮把「面向小白文档站」又往前推了一步：多了一种时间轴互动件、补齐了 5 篇翻卡、新增 3 篇"动手接入+避坑"实战概念篇，全站 32 篇概念文档的五类核心互动件已全覆盖，验证门全绿、零死链、零孤儿页。剩余的 Token 计费篇、Eval 篇与故事番外，已如实列入下一批，未做任何静默截断。
👉 回 概念入门总览 · 或直接读 ㉙ 什么是 API 与 SDK 开始新一批内容。