笔记怎么写：讲清楚，也方便回头复习

核心原则

先告诉读者这篇要解决什么疑问，再引入需要的概念。可以从下面的链条里选一个具体环节：

用户目标
→ 数据、memory、search 与 tools
→ LLM / multimodal policy
→ training、serving 与 runtime
→ evaluation、feedback 与持续改进

旧方法也值得讲，只要能帮助理解后来的设计。不必按论文年份排队，也不用为了显得新把基础一笔带过。

主路线包含什么

• 当前 LLM 和 multimodal model 的行为与系统机制；
• Agent memory、search、retrieval、tools 和 state；
• SFT、preference learning、RL、distillation 和 model updating；
• evaluation、LLM judge、human feedback 和 online outcomes；
• training infra、inference、GPU、data 和 observability；
• personal AI、长期交互、control、privacy 和 model experience；
• 能够验证上述概念的现代实战项目。

什么不单独展开

• 传统 classifier、CNN、RNN、SVM 等模型的目录式介绍；
• 只按年代排列、不能解释当前决策的论文史；
• 已经过时的 framework API 教程；
• 没有版本、硬件和 workload 的性能数字；
• 只有术语列表、没有系统关系和验证方法的内容；
• 为了“完整”而加入、却不会改变理解或实践的背景知识。

例外：如果历史机制仍然活跃，就应该解释。例如 stable softmax、embedding retrieval、SIMD/SIMT、attention 的二次方中间状态和 exposure bias 都直接影响现代系统。

一篇先讲清一个问题

导读可以短，正文不能只剩提纲。不要为了凑“五分钟读完”，把推理过程和适用条件删掉；也不要靠重复定义把文章拉长。

一篇正文围绕一个问题，把它讲到读者能自己用起来：

• 用具体情境说明为什么会遇到这个问题，交代需要的前置知识。
• 用同一个小例子走完机制；涉及公式，要解释符号、算一次，再换个条件。
• 给出可以核对的结果：手算、可运行代码或交互实验，不拿概念图代替解释。
• 比较至少一个合理替代方案，说明各自省了什么、牺牲什么，以及在哪里会失败。
• 标清哪些是已知结论、教学假设和待验证的设计，再指向相应的原始资料。

正文按理解顺序展开，不按“新手／高手”给人分组。读者只想了解直觉时，可以先看例子和图；想弄懂原理时，可以继续推导；要实现时，能找到代码和实验条件。用少量页内链接告诉读者这些内容在哪儿，不新增一排等级标签，也不把关键解释全藏进折叠框。

例子要放在读者最容易卡住的地方，不必给每段硬编故事。比如讲候选（candidate） softmax，先问“3 个同分候选，再加 1 个，原来的概率会变吗？”；读者看到 $1/3$ 变成 $1/4$，就能理解它依赖比较集合，再接公式会轻松很多。例子只改变一个关键条件，数字能复算；手造例子说明机制，不拿来证明模型性能。

审稿时多问 3 句：不看推导，能说出它解决什么问题吗？想继续读，能看见为什么成立、什么时候不成立吗？想动手，能找到实现与检查方法吗？一个人可以只读前一部分，也可以按需往下走；浅读有收获，不等于把正文写浅。

长主题按问题拆篇，而不是按字数拆篇。导读负责指出阅读顺序，章节负责讲透；相邻文章沿用例子和术语，避免每篇重新介绍整套系统。求职随笔和板块首页不必套用技术文章的结构。

板块首页先讲这里有什么、从哪里开始。功能标题直接写用途，例如「我的阅读」「备份」，不要写成口号。使用方法、贡献流程和版本计划分别放好，不在每个入口重复提醒「不用学完」「按自己的节奏」。删重复说明，不删技术前提和推导；中文的断句与标题长度也不必照搬英文。

练习跟着内容走

需要练习时，就放在相关讲解旁边：算一个小例子、改一处代码，或者换个条件看看结论是否还成立。不必每篇都配题，也不在页尾统一追加卡片、掌握度和打卡控件。

短时学习路线按有效学习小时估计范围，不按自然日倒计时。2／6／12 小时是选材参考，可以拆成多次，也可以只选其中一项；不承诺学完就能通过面试。起步路线多补前置解释，复习路线允许跳过熟悉内容，选择依据是当前知识，不是工作年限或能力排名。每次给一个具体练习和能接着学的位置，不设连续打卡、补课欠账或落后提醒。

参考思路要讲清前提和推理；开放问题说明判断依据，不装成只有一个答案。提醒误区时指出具体哪里容易出错，别只说“注意细节”。

例子优先用虚构的小数据；真实测量要有公开出处和实验条件。审核时同时看推理是否成立、中英含义是否一致、相关链接能否帮助理解。

中文尽量写成你当面解释时会说的话。比如“先固定候选池再比较”，比“构建多维度对齐的评估闭环”更具体。专业词可以保留英文，但不要整句逐词翻译。

先把中文句子写顺，再考虑术语：常用名称如 Transformer、SFT、LLM 可以直接保留；需要对照原文的中文术语，交给术语表在首次出现时加英文。每段最多自动标注两处，已有括注不重复添加，标题、按钮和图解保持简洁。不要把普通动词换成英文，也不要为了显得专业，把“拿到什么、交出什么”写成一串抽象名词。

双语阅读原则

正文语言和熟悉哪套术语，是两回事。有人只读中文，有人用英语学过这些知识但喜欢看中文解释，也有人只读英文。不要按国籍、学校或浏览器语言替读者做决定。

• 中文能独立读懂。 先用中文解释概念在做什么，再给英文名称。保留 Transformer、SFT 等常用名字，但首次出现的必要缩写要解释，不能让读者靠查英文才能接着读。
• 双语读者自由切换。 中文和英文一键切换到同一篇文章。中文页默认显示首次出现的英文术语对照，每段最多两处，不把整段写成中英夹杂的术语清单。
• 英文不是附录。 英文页保留同样的推导、例子、代码、图解、交互说明、复习题和限制条件。导航、按钮与无障碍标签也要用英文；不能让英文读者跳回中文补关键内容。
• 概念卡就地对照。 每张双语卡的两面都要完整，公式、张量形状、例子和前提等价；初始语言跟随当前页面，切换时不打断阅读位置。
• 不擅自跳转。 读者打开哪种语言的链接，就显示哪一版，不根据读者身份或浏览器语言自动改变正文语言。

审核时分别试读：不看英文也能理解这段吗？熟悉英文术语的人能认出对应概念吗？只打开英文页能完成例子和练习吗？site/paritycheck.py 可检查两版结构，但不能代替这样的逐段核对。

新增或改写概念时，中英文两面必须在同一次更新中完成。无法准确翻译时，宁可先不发布这张卡，也不要留下长期漂移的两套解释。

图表规范

图里的标题、图例、说明和无障碍文本跟随页面语言；中文图不能只换一条中文图注。公式、代码与常用模型名可以共用，完整句子要分别写顺。文字较多的比较图优先使用能换行的 HTML，不把桌面图片缩成手机上的小字。中文不套英文的全大写、字母间距或斜体，英文也不照搬中文的断句。生成脚本必须同时维护两种语言，重跑后不能把中文图覆盖成英文。

图要让读者看清一件具体的事：一个向量怎样变化，一条请求经过哪里，或两种设置的结果差在哪儿。优先沿用正文的小例子，箭头写清传递的内容，不要把抽象名词装进几个方框就算讲过了。节点形状和颜色只用于区分有意义的角色；需要约定时加简短图例，不给所有主题硬套同一张流程图。

默认画面就应当有信息，不操作也能读懂；交互用来比较和探索，不用来解锁正文。示意数值要标明，实测结果要给来源。发布前检查窄屏、英文版以及每个 Mermaid block 的实际渲染。图注说清这幅图展示了什么和没展示什么，少写口号式总结。

时效性

快速变化的页面应包含 Last reviewed: YYYY-MM。无法确认的当前事实不应以永久结论写入。

更新时写清具体版本与核对日期，不把旧报告改个年份就叫“最新”。新版本改变了结构、接口或评估方法，才在正文解释变化；只有产品公告时，只介绍公告确认的内容。架构和训练细节未公开，就直接说明，不根据家族名猜内部配置。

参考笔记只用于查漏。每个主题还要独立核对一手来源、算例和适用条件；读完参考、写好草稿、接入页面、运行测试与允许发布分别记录。全站改版按 CONTENT_RELEASE_CHECKLIST.md 验收。经明确同意，可以先开阶段性 PR 供审阅，但不能把它写成全站完成；开 PR、审核通过和合并上线是三件事。

参考资料怎么用

先弄清参考文章在回答什么、用了哪些前提，再判断本站该补什么。它偏重某种方法，不代表别的方法不值得讲；提到一个概念，也不代表已经讲透。目录用来查漏，不是我们必须照着排的课表。

拿不准的结论回到原论文、文档或实现核对。分清作者实际验证了什么、哪些是推测，以及换个数据集、预算或版本后还成不成立。有冲突就把条件说清楚，不因为写得顺、发布时间近就直接采用。一手资料也可能有笔误，算例仍要自己复算。旧方法先放回当时的问题里理解，再解释今天有哪些变化。

写本站的版本时，重新组织讲述和例子，不做逐段换词。先让读者看懂一个具体问题，再按需要展开原理、替代方案和实现。参考里缺少的前置知识、反例和局限也要补，但不为追求篇幅堆内容。来源留在相关解释旁；外部图、代码或原话需要引用时，检查许可并注明出处。

来源顺序

1. 官方文档和规范；
2. 原始论文；
3. 可复现代码、实验和 benchmark；
4. 高质量二手解释。

事实、实测结果和推断要明确区分。Benchmark 必须包含模型、数据、硬件、版本、配置和 workload。

涉及具体方法，先读原论文的相关正文、实验设置和局限，不能只读摘要或参考笔记。需要背景时，简短交代当时常用什么、遇到了什么瓶颈、作者实际比较了哪些方案；论文里的对照组不等于整个业界，今天的结果也不能倒过来当作当年的依据。

论文链接放在它支持的解释旁边，尽量注明年份、版本和相关章节；有官方实现，再附代码或模型卡。只有确实读过的部分才记为已核对。公开细节不够就直说，不补猜测，也不用为了放链接新增“论文”大板块。

Modern 不等于追新

Modern-first 不是追逐每个新名词。真正的判断标准是：

• 是否已经改变主流系统设计；
• 是否有可靠证据；
• 是否解决真实瓶颈；
• 是否能与现有模块建立清楚关系；
• 六个月后是否仍可能帮助做决策。

如果答案只是“最近很热”，它应该先进入实验记录，而不是主学习路线。