技术知识库写作规范 (Writing Guide)

本规范适用于 content/tech/ 下所有双语主题文件(*.zh.md / *.en.md)。目标:面试导向 —— 每个知识点不仅要有公式,还要有”能直接说出口的面试回答”。

核心原则

1. 公式必须有直觉。任何公式出现前(或紧接其后),先用一句大白话讲清楚”这个公式在算什么、为什么长这样”。
2. 每个知识点 = 公式 + 直观理解 + 面试速答 + (可选)数字例子。
3. 面试回答要能直接背诵。30 秒口头表达:结论先行 → 一句话机制 → 一个具体例子。
4. 字数不设上限。需要多解释就多写;类比、生活化例子、手算示例都可以加。
5. 中英成对文件内容对应(不必逐字翻译,但知识点覆盖一致)。

知识点段落格式

在 ### x.y 小节(或考点、Section)末尾追加统一格式:

> 💡 **直观理解**: 用大白话 + 类比讲清本质。例如"GQA 就像全班共用 4 份笔记,
> 而 MHA 每人一份 —— 省了 KV 缓存但牺牲一点表达能力"。
>
> 🎤 **面试速答**: "结论:……。原理:……。举个例子:……。"(30 秒可背诵)

• 如果小节只有公式/代码/表格没有解释文字 → 必须在公式前补一段解释,再加上面的 blockquote。
• 如果小节已有解释但只有推导没有直觉 → 补”为什么是这样”的直觉段落。
• 面试 cheatsheet 类的”考点”已有标准回答的,检查是否可直接背诵;不够口语化/缺例子的要改写强化。
• 表格要加”怎么读这张表”的一句话引导(如”注意第三列:…,这是面试常考的对比点”)。

面试速答写作模板

结论: <一句话>
原理: <为什么, 2-3 句>
例子: <一个具体数字/场景, 如"8 层 LLaMA-7B, 4096 序列 → 33.5MB KV cache">

质量检查清单

• [ ] 每个 ### 小节都有 💡 直观理解(无遗漏)
• [ ] 每个面试速答 ≤ 5 句话、可直接口述
• [ ] 至少一半的知识点带具体数字/例子
• [ ] en 用英文写, zh 用中文写, 术语双语标注
• [ ] 不删减原有公式/表格/代码, 只增不删

维护流程

• 新增主题: 按统一模板(H1 + 核心摘要 + Mermaid + 考点速查 + 章节 + Numpy + 总结)创建 en/zh 成对文件,同时遵守本规范。
• 新增知识点: 在对应章节追加 ### 小节,按上述格式写。
• 批量质量检查: 运行 scripts/audit-gaps.mjs 看覆盖,scripts/normalize-frontmatter.mjs 看 frontmatter。