code-deep-dive git:20260809.a7569fcA

Immutable. This exact content is served forever at /api/v1/blob/a09fe8bbf8eb4088.

---
name: code-deep-dive
description: "为 vibe coding 项目编写中文深度 markdown 长文，帮助用户在碎片时间（通勤、午休、睡前，手机观看）补齐代码知识。每次由用户明确指定主题（如某个框架机制、某段核心逻辑、某个技术概念），输出一篇完全自包含（代码完整内嵌、无需电脑即可学习）、附带充分外部链接与资料、单篇学习时长约 1.5 小时的深度长文，保存到项目的 docs/learning/ 目录。用户可要求 format=html 生成带目录、交互测验、代码高亮的单文件网页版。当用户说'帮我写一篇学习 XX 的文章'、'把这个项目的 XX 讲透'、'我想深入理解 XX 原理'、'碎片时间想学一下 XX'、'写一篇 XX 的深度笔记'，或任何 vibe coding 后想系统补齐代码知识的请求时，务必使用本技能，即使没有明确提到'文章'或'笔记'字样。"
---

# Code Deep-Dive

为 vibe coding 项目编写**中文深度 markdown 长文**，让用户在碎片时间用手机补齐全栈代码知识。

## 核心场景

- **用户是谁**：vibe coder——用自然语言指挥 AI 写代码，但对自己项目的底层机制缺乏系统理解。
- **何时触发**：用户指定一个主题，想深入理解它，把"AI 替他写出来的代码"变成"他自己懂的知识"。
- **学习场景**：不在电脑前。通勤、午休、睡前，用手机阅读。
- **输出形态**：单篇 markdown 文件，中文，约 1.5 小时学习时长，完全自包含，配丰富外部链接。

## 不可妥协的五条原则

这五条是本文档的基础，写作时的所有细节规范都从它们推导。先理解"为什么"，再执行具体规则。

### 1. 自包含——学习时不在电脑前

用户学习时看不到代码，也搜不了资料。因此：

- 文章中**每个被讲解的代码片段都必须完整内嵌**，标注来源文件路径。禁止只写"见 `src/foo.py` 第 42 行"而不贴代码。
- 所有需要的前置概念都在文中解释，默认读者零基础。禁止"你应该知道 X"这种甩锅式写法。
- 文中引用的每个外部链接都要有**一句话说明**：讲了什么、适合什么阶段。用户在手机/平板上随时可以点开——说明文字帮他们判断"这个链接值不值得现在点开"。

### 2. 深度优先——把代码讲透

一篇文章的价值在于把主题**讲透**，而不是复述项目的现状。**代码是文章的主体**：项目代码是教学载体和入口，核心与周边的代码逻辑都要讲透——不追求逐行抠细节，但核心机制和它周边的配套机制（被调用的依赖、相邻模块、生态中的同类机制）必须讲到位。正文还要覆盖：

- 核心概念的全貌（不限于项目用到的部分）
- 底层原理：机制如何实现、为何这样设计、有什么权衡
- 历史脉络：为什么会出现、解决了什么问题、后来如何演化

项目里没体现但主题相关的部分，一样要讲。这才能支撑起 1.5 小时的学习时长。

### 3. 代码讲解——讲清"它实际是什么"，而不是"它应该是什么"

本文的核心动作是**讲解代码**。姿态不带评价：

- **讲清实际行为**：这段代码做什么、怎么工作、数据怎么流、和谁交互。把代码的"实际样子"如实讲清楚——这正是读者拿去定位问题、规划重构的依据。
- **不做价值评判**：既不唱赞歌（"我们深思熟虑地选择了这个方案"），也不批判（"这段代码有缺陷，应该改"）。代码讲透了，哪里不对劲、哪里要动，读者自己看得出来——你的任务是让"看得出来"成为可能。
- **不虚构动机**：代码为什么长这样，只讲客观可考的因果（依赖关系、语言特性、历史沿革、遗留设计）。编造"当初为什么这么选"的叙事是不诚实的——大多数代码不是精心设计出来的。
- **不美化也不丑化**：代码行为诡异就如实描述"它的行为是……"，不加评论；代码写得规整也如实说，不吹捧。评判权在读者手里。

### 4. 手机友好——碎片时间可读，但不牺牲深度

手机友好指**排版和阅读节奏**，不是内容降级。深度和体量照旧，只为手机优化呈现方式：

- 段落短：每段不超过 4-5 行，长内容拆成多段，不用长段把深度堆成墙。
- 多用列表、表格、引用块、加粗——手机上一扫就能抓住重点。
- 标题层级清晰，用户随时中断、随时续读。
- 每个章节标注**预计阅读时长**（markdown 版写作时在章首写 `> 约 X 分钟`；HTML 版由转换脚本按字数/代码量**自动估算**，写作时不要手动写时长）。
- 代码块单行不宜过长；**每个代码块不超过 50 行**，更长的按逻辑拆段、段间插入解读，方便手机纵向阅读。

### 5. 面向 vibe coder 的讲解视角

- **具体，不抽象**：讲具体代码、具体例子、具体场景，不堆概念和抽象描述。能用一段代码说明的，不用三句抽象话。全文的默认语言是"实在"。
- **先讲"为什么在意"**：这个知识对用户有什么用——更好指挥 AI、能审查 AI 的产出、能排查问题、能重构旧代码。这是动机，也是留存。
- **从现象到原理**：先用用户熟悉的产品行为做钩子（"你点那个按钮时……"），再往下拆。
- **类比要准**：类比是为了建立直觉，但必须准确，讲完类比要回到精确的定义。
- **术语给中文**：首次出现的英文术语给中文译名 + 简短解释，括号保留英文原名（如"中间件（middleware）"），因为用户和 AI 沟通时要用到英文术语。

## 工作流程

### Phase 1：确认主题与学习目标

用户指定主题后，先用一两句话向用户确认（或自行明确）**本篇的定位**：

- 主题是什么、为什么选它（它在你项目里承担什么角色）
- 学习目标：学完能做什么（3-5 条具体能力）
- 前置知识假设：读者已经知道什么、从哪开始补

确认后输出一份**本篇规划**给用户：主题、学习目标、章节大纲（每章一句话 + 预计时长）。**得到用户确认后再开写**。一篇 1.5 小时的长文方向错了代价很高，值得花 30 秒确认。

> 注意：规划要简短（几行即可），不要写成文档。用户确认只是防止方向跑偏。

### Phase 2：项目调研

- 先读项目根目录的 `AGENTS.md`（如有）和 README，了解项目定位。
- 找出与主题相关的代码文件，完整阅读。
- 提取将要在文章中讲解的代码片段，记录文件路径与行号。
- 理解真实代码的调用链：这段代码被谁调用、它调用谁、数据怎么流。
- 带着**理解**的眼光读代码：不仅要懂"它在干什么"，也要看懂它的异常之处和不寻常之处——这些在讲解时要如实讲清（讲行为，不评价）。

> 只有先真正读懂代码，才能写出有深度的解读。这一阶段不做透，文章必然浮于表面。

### Phase 3：网络调研与资料收集

写作前必须做一轮 Web 搜索，收集主题相关的权威资料：

- **官方文档**优先（框架/语言的官方 docs、API 参考）
- 经典教程、权威博客、高质量视频、社区讨论（Stack Overflow、Hacker News 等）
- 尽量核实链接真实有效，禁止编造 URL。

收集到的链接按主题组织，稍后写入文章末尾的"学习资料库"，并给每个链接配一句话说明。

### Phase 4：撰写

按 `references/article-template.md` 的结构撰写全文。写作规范见 `references/writing-guidelines.md`。

撰写时用项目真实代码作为讲解对象（见 `references/writing-guidelines.md` 的"代码解读规范"）。

### Phase 5：自检

对照下面的质量标准逐条自查，不达标就修改。写完自查很重要——长文容易在细节上偷工减料。

#### 质量标准（每篇必须满足）

| 项 | 标准 |
|---|---|
| 学习时长 | 约 85-95 分钟（正文 10000-15000 中文字符，不含代码） |
| 章节数 | 5-15 个章节 |
| 代码自包含 | 每个被讲解的片段完整内嵌，标注来源文件路径 |
| 代码量 | 全文代码片段合计 600-1000 行，覆盖项目真实代码；**每个代码块不超过 50 行** |
| 外部链接 | ≥ 12 个，至少覆盖官方文档 / 教程 / 博客 / 视频四类中的三类 |
| 手机可读 | 段落短、列表多、章节标注预计时长、长代码按逻辑拆分并在段间解读 |
| 深度 | 至少 1 个章节讲"超越项目本身"的底层原理或历史脉络 |
| 讲解姿态 | 如实讲解代码实际行为；不唱赞歌、不做价值评判、不虚构设计动机 |
| 读者视角 | 每篇至少 2 处把知识映射回"指挥 AI / 审查代码 / 排查问题 / 重构演进"的实际用途 |

### Phase 6：输出

- 保存到项目 `docs/learning/` 目录，文件名 `yymmdd-{主题slug}.md`（如 `260807-react-hooks-原理.md`）。目录不存在则创建。
- 文章开头用几行"元信息"：主题、来源项目、学习时长、前置知识、写作日期。
- **可选：`format=html`**——若用户要求 HTML 版，则在撰写 markdown 时按 `references/html-format.md` 的约定加入测验（`:::quiz`，支持选择题与问答、含解说）、折叠块（`:::details`）、图表（`:::mermaid`）、图标（`{{icon:name}}`）等互动元素，然后用 `scripts/md2html.py` 转换为单文件 HTML，md 与 html 并存。预计时长由脚本自动计算，**不要**手动标注。
- 交付后向用户简述：文章位置、篇章结构、学习建议（每章适合什么碎片场景）。

## Reference Files

- `references/article-template.md` — 文章结构模板：每个章节写什么、量化指标。写文章前必读。
- `references/writing-guidelines.md` — 写作规范：深度讲解方法、代码解读规范、外部链接规范、手机排版细节。写文章前必读。
- `references/html-format.md` — HTML 版约定格式与转换脚本用法（仅 `format=html` 时阅读）。
- `scripts/md2html.py` — markdown → 单文件 HTML 转换脚本（仅 `format=html` 时使用）。