# 📊 概念入门文档站 — 完成度报告

> 本报告记录「面向小白文档站」这一轮增强的落地情况：新增了什么、当前覆盖到什么程度、还剩什么没做。
> 生成方式：全部数字来自 `npm run docs:build` / `docs:lint` / `docs:verify` 的真实输出，非估算。
> 想直接开始学？回 [概念入门总览](./00_INDEX_概念入门-总览.md)。

---

## 一、这一轮做了什么（本批新增）

这一轮是「继续优化」——在已达教科书级的概念站上做**纯追加**，不重写任何既有文档。共四件事：

1. **新增互动件类型：时间轴（timeline）**
   作者只需写一个 ` ```timeline ` 围栏，每行 `标签 | 描述`，即可渲染成一条竖向、逐条滚动进入的时间线。纯 CSS 实现、复用既有的滚动进入动画（`initReveal`），零新增 JS。已配套写进 linter（防呆校验）与单元测试。

2. **补齐 flip 翻卡平权：5 篇 CONCEPT 各 +1**
   CONCEPT-21/23/24/26/28 原本没有 flip 翻卡，这一轮各补一张，放在每篇「X vs Y 对比」那一节，让"先猜后翻"的互动在进阶篇里也齐整。（00_INDEX 是纯导航页，合理保持无 flip。）

3. **新增 3 篇概念文档（㉙㉚㉛）——"动手接入 + 避坑"实战篇**
   | 编号 | 文档 | 讲什么 |
   |------|------|--------|
   | ㉙ | [什么是 API 与 SDK](./[CONCEPT-29]%20什么是API与SDK.md) | 一动手就绕不开的两个词，附「首用 timeline」演示接入方式的演进 |
   | ㉚ | [函数调用与 MCP 辨析](./[CONCEPT-30]%20函数调用与MCP辨析.md) | 掰清"函数调用/工具调用/MCP"这组最容易混的词 |
   | ㉛ | [什么是幻觉（Hallucination）](./[CONCEPT-31]%20什么是幻觉-Hallucination.md) | 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，**零死链、零孤儿页**——是健康增长，不是回归。

---

## 四、还剩什么没做（诚实的待办清单）

按「不做静默截断」的原则，明确列出本轮**刻意留到下一批**的部分：

1. **概念篇待补（下一批）**
   - **Token 计费与成本**：把"一次调用要花多少钱、怎么估算、怎么省"讲透（现散见于 CONCEPT-08）。
   - **Eval / 评测**：怎么衡量一个 AI 应用"到底好不好、有没有变差"。

2. **修仙故事番外（㉙㉚㉛ 的孪生）——刻意不加，理由如下**
   `09_STORY_修仙学AI/` 是一部**已完结、结构自洽**的修仙长篇（孔浩原从药童到渡劫飞升，境界阶梯层层对应概念）。为 ㉙㉚㉛ 硬插三章中段番外，会**打断这条已封笔的修炼主线**（B3 外科原则：不顺手改动不该动的完整作品）。
   值得一提的是：幻觉（㉛）这个概念，在故事里**其实已由"幻魔道"反派线承载**（"求真 vs 造假"的对抗）——再单开一章反而重复。
   因此这三篇的故事化，作为**独立议题留待后续**：要么等故事作者决定如何在不破坏主线的前提下扩写，要么以别的轻量形式（如概念篇内的小故事段）承载。

3. **timeline 的更多消费点**
   本轮 timeline 仅在 CONCEPT-29 首用（形成闭环验证）。其它适合"演进/阶段"叙事的篇目（如 RLHF 的训练三步、Transformer 的发展史）可在后续按需补挂——非必需，属锦上添花。

---

## 五、一句话总结

这一轮把「面向小白文档站」又往前推了一步：**多了一种时间轴互动件、补齐了 5 篇翻卡、新增 3 篇"动手接入+避坑"实战概念篇**，全站 32 篇概念文档的五类核心互动件已**全覆盖**，验证门全绿、零死链、零孤儿页。剩余的 Token 计费篇、Eval 篇与故事番外，已如实列入下一批，未做任何静默截断。

👉 回 [概念入门总览](./00_INDEX_概念入门-总览.md) · 或直接读 [㉙ 什么是 API 与 SDK](./[CONCEPT-29]%20什么是API与SDK.md) 开始新一批内容。
