参考与规范：知识博客化写作框架

这份框架服务于全站正文页：每篇文章要能独立阅读，每个板块又要能拼成完整专题。它借鉴公众号和知识博客常用的“先带入问题，再拆机制和边界”的节奏，但不复制外部文章的原文、标题或配图。

单篇文章的主线

一篇正文最好只回答一个主问题。开头先告诉读者：这是什么，为什么值得读，它解决什么问题，读完能做出什么判断。随后用一个直觉例子把读者带进来，再拆核心机制、公式、论文图、工程边界和常见误解。

推荐结构如下：

模块	作用	写作检查
这篇回答的问题	让搜索进入的读者立刻定位	读者不用先看目录也知道本文目标
一句话结论	先给判断框架	不是口号，而是可被正文展开的结论
直觉例子	降低进入门槛	例子要和后文机制一一对应
核心机制	解释为什么成立	每个小节回答一个问题
论文图/博客图怎么读	把图纳入证据链	写清图源、原图表达、本站读法
常见误解	划清边界	说明哪些结论不能外推
相关阅读与下一步	接回知识网	至少包含站内下一篇和外部来源

板块和导航的职责

主导航不再放独立索引条目。index.md 可以作为站内索引页保留，方便搜索、站内链接和后续维护，但它不承担一级导航里的第一屏角色，也不应该写成厚重的二级首页。

如果一个一级导航下面有多个子领域，优先像“论文精读”那样在 mkdocs.yml 里使用二级标题分组。例如“训练与推理系统”可以分成“训练系统、推理系统、量化、算子与编译器”，“世界模型与具身智能”可以分成“世界模型、具身智能、VLA、VLM”。这种分组比在索引页堆长表更适合读者扫描，也不会把原本清爽的导航改成说明书。

索引页如果保留，可以回答这些问题，但不要求展开成完整覆盖表：

问题	说明
这个板块的直觉是什么	用一两段文字给读者建立方向感
第一篇适合读什么	给初学者一个低摩擦起点
阅读时该警惕什么	提醒常见误解、证据边界或工程陷阱
和其他板块怎么接	用少量链接指向相邻主题

板块完整性主要通过三层共同保证：导航负责分组，单篇文章负责独立讲清问题，正文结尾负责把读者送到下一篇。这样即使读者从搜索直接进入某篇文章，也能知道为什么读、读完判断什么、下一步去哪；同时从站点导航进入的读者，也能先按板块二级标题找到自己的路径。

来源与图的使用边界

外部博客和公众号适合补直觉、叙事和问题组织；论文、官方文档、代码仓库和技术报告负责定事实边界。新增图片优先来自论文、官方博客、项目页或许可证清晰的资料。许可证不清的博客图只链接，不本地化。

每张复杂图至少写清三件事：

项	要写什么
图源	原论文、官方博客、项目页或文档链接
原图表达	作者原本想证明或展示什么
本站读法	这张图在本文中支撑哪个解释，不能证明什么

改写时的优先级

改一篇旧文时，优先补读者最缺的判断框架，而不是先追求篇幅。好的补强通常是这四步：

1. 在开头补一句“这篇回答的问题”，让读者知道自己为什么要继续读。
2. 在第一个机制段落前放一个直觉例子，避免公式和名词直接压上来。
3. 对已有论文图补“图源、原图表达、本站读法”，把图变成证据而不是装饰。
4. 在结尾补外部来源和站内下一步，让文章能独立进出知识网。

如果文章已经有清晰主线，不要为了统一模板硬塞所有标题；可以把这些模块融进自然段。本站追求的是“读者能顺着一个问题走完”，不是所有页面长得一模一样。

新增外部材料时，博客、公众号和知识性长文主要用于补直觉和叙事框架；论文、官方文档、技术报告、代码仓库和项目页用于确认事实边界。遇到二者冲突时，正文以可核验来源为准，博客表达只作为解释方式参考。

审核清单

交付前快速问四个问题：

检查项	合格标准
为什么读	开头能说清本文解决的具体问题
读什么	正文至少有一个机制解释、一个例子或一张可读图
怎么验证	关键事实能回到论文、官方文档、项目页或明确的外部材料
下一步去哪	结尾能把读者接到站内相邻文章或外部精读材料

这份清单只约束正文质量，不强制索引页承担全站路线图。板块之间的区分优先放在导航分组里完成。

导航分组命名

二级分组名称要像书架标签，而不是文章标题。它应该帮助读者判断“我现在要进入哪一类问题”，例如“训练系统”“推理系统”“量化”“算子与编译器”，而不是再写一篇解释性的长标题。

好的分组通常满足三点：第一，和已有文章数量相匹配，至少能承载两三篇相关内容；第二，和读者任务一致，例如排障读者会找“推理系统”或“算子与编译器”，论文读者会找“扩散生成”或“世界模型”；第三，不和正文标题抢解释任务，具体机制仍由文章自己讲清楚。

索引页和导航的边界也要稳定：导航负责让人找到板块，索引页只在需要时提供一点方向感，正文负责完成知识解释。只要这三者不互相抢活，网站就会既清楚又不臃肿。

参考写法

• 阮一峰：技术写作的线索意识：参考“一条线索”的组织方式，避免概念散点化。
• 如何写好技术博文：参考开头定位、读者预期和结构化表达。
• 机器之心深度学习技术词条：参考“定义、来源、应用边界”的概念卡片写法。
• 量子位 CFM 访谈：参考“问题、回答、反例、边界”的问答推进节奏。