tutorial-writing-skill

Imported from AcSg999/tutorial-writing-skill (SKILL.md). Install upstream with npx skills add AcSg999/tutorial-writing-skill. Copyright stays with the author (MIT).

数学／技术推导讲义写作

规定如何写"从零到完整推导"的长文档：结构、公式排版、表达方式、迭代与交付方式。

目标读者是有基础但没学过本主题的人（例如刚进课题组的研究生）。写作标准是：读者只靠这篇文档，就能独立复现每一步推导与实现。

一、适用与不适用

适用

• "写一篇关于 X 的详细推导／讲义／教程／学习笔记"
• "把这个主题从数学原理一路讲到实现和应用"
• 已有草稿，要求按这种风格扩写、补全、重排结构

不适用

• 一段式的概念解释、API 用法说明 → 直接回答即可
• 纯科普／博客（无推导）→ 可借用结构与排版，跳过公式规范
• 论文正文／实验报告 → 结构、语气、引用规范都不同

二、交付格式：Markdown 是唯一源文件

这是本技能最重要的工程约定。

1. 唯一真源是 .md。 所有内容只在 Markdown 中编写、修改、评审。PDF／HTML／DOCX 一律是从 .md 生成的派生物。
2. 调试在 Markdown 里完成。 公式是否渲染正确、表格是否过宽、推导是否连贯，都在预览中当场解决：
   • 写作与迭代：VS Code 内置 Markdown 预览（Ctrl+Shift+V，KaTeX 渲染）——逐段调试公式与结构；
   • 发布前终检：推送到 GitHub 看线上渲染（MathJax）——确认平台间无差异。
3. git diff 必须可读。 每个语义单元独占一行，公式独立成块（见第七、八节）。不要用行内 HTML 或表格拼版式来"美化"版面，否则 diff 会失去可评审性。
4. 导出是可选的最后一步，永不反向。 需要 PDF 时再从 .md 生成，并把导出物当构建产物处理（如 build/，默认不进版本控制或明确标记为生成物）。绝不在 PDF 上改内容——那会立刻让 Markdown 失去唯一真源地位。
5. 一个源文件，处处可渲染。 只用 KaTeX ∩ MathJax 的安全子集（第八节），使同一份 .md 在本地预览、GitHub、导出器三处表现一致。
6. 导出工具（可选，仅按需取用）：Pandoc、Quarto、md-to-pdf、VS Code 的 Markdown PDF 类扩展。工具选择不应反过来影响源文件写法：若某导出器不支持某种写法，先确认它是否属于安全子集，再判断是导出器的问题还是写法的问题——不要为了迁就导出器而破坏 Markdown 预览的正确性。
7. 单文件优先。 一篇文档一个 .md（几千行也照此办理），便于分享、复制、导出。确实需要拆分时，建立目录页并用相对链接互指，同时保证每篇仍可独立阅读。

三、三条优先级

写作时按这个顺序取舍。后面所有骨架与排版规范都只是实现手段；出现冲突时以这三条为准。

1. 公式必须写对。 符号先定义后使用、全程不换名；每一步只做一处变换，并写出依据（代入、交换次序、条件期望的性质……）；主动做量纲／边界／退化情形的检查（$t=0$ 与 $t=1$、$n=1$、方差为零……）；能用代码数值验证的结论就真的验证一次。宁可多写一行说明，也不要留下一个说不清来源的等号。

2. 推导必须简洁易懂。 一次只前进一步；先给直觉（图像、比喻、物理意义）再形式化；砍掉不服务于主线的分支；每个独立公式后紧跟一句人话。简洁不等于跳步——跳步会把读者丢掉。

3. 名词必须串联成一条线。 全文读下来应当是一条"问题 → 工具 → 结论 → 下一个问题"的链子（见下两节）。

其余都是手段。 骨架、疑问式标题、\boxed{}、公式编号、检查清单，都是为了让上面三条更容易做到。不要为了填满模板而写文档，也不要为了统一格式牺牲更清楚的表达：内容与模板冲突时，听内容。

四、每个结论都要回答"为了解决什么，得到了什么"

读者读完每一节，应该能立刻回答两件事：

• 动机：为什么需要这一节？上一节的结论在哪里不够用？
• 结论：这一节得到了什么？可以拿它做什么？

落到写法上：

• 一级标题用疑问句，问题本身就是动机：「为什么还需要连续性方程？」「为什么 MSE 能学到条件期望？」
• 每节收尾给出能塞进这个句式的结论：「为了解决〈上一节的不足〉，我们得到〈本节的结论〉。」
• 关键结论用 \boxed{} 框出来；理想情况下，读者只看被框住的部分就能复述全文逻辑链。
• **动机：** 段落就是"为了解决什么"的显式化。不要用"值得注意的是……"这类不承载信息的句子占位。
• 总结章节不是复述目录，而是把若干条"为了…得到…"串成一条链，并说明它不回答的问题。

反例：一上来给最终损失函数；写"下面我们引入 X"却不解释 X 解决了什么。

五、名词串联

• 新名词第一次出现时，同时交代三件事：它解决上一节的什么问题、它是什么（一句话定义）、它与已有名词的关系（特例／一般化／等价形式／工具）。
• 一次只引入一个新名词；没被用到的名词不要提前定义。
• 术语首次出现写"中文（English，缩写）"，之后统一：Pushforward（推前分布）、Continuous Normalizing Flow（CNF，连续归一化流）。
• 让名词之间的关系显式化，例如在阅读路线或总结里画出链条：概率分布 → ODE → 连续性方程 → Flow Matching → Conditional Flow Matching → 应用；必要时用一句话说明相邻两个名词的从属关系。
• 自检方法：把本节的名词与上一节的名词连起来读一句话。读不通，说明串联断了。

六、默认骨架（可裁剪）

下面是最常见的信息顺序。它是默认起点，不是硬性模板：内容需要时可以调换、合并或省略，短文档不必具备全部元素。可直接复制的骨架见 examples/skeleton-template.md。

标题写法

• 一级标题：中文序号 + "第 N 步" + 疑问式主题，例如 # 三、第三步：为什么需要连续性方程？
  • 纯介绍或应用章节可以是陈述式，但仍用问句更佳：# 十一、第十一步：π0.5 如何使用 Flow Matching？
• 二级标题：## 3.2 连续性方程的推导（编号 + 动宾短语或问句）
• 三级标题：用于澄清易混点，例如 ### Flow Matching Velocity 不等于机器人关节速度

每个小节内部的固定节奏

1. 一句场景或问题铺垫；
2. 直觉版解释；
3. 形式化：定义符号 → 说明假设 → 推导 → 结论；
4. **动机：** / **关键：** 黑体段落，说明这一步换来了什么；
5. 需要时补最小可运行代码或数值例子。

总结章节的写法

用"1. 确定生成目标。 正文…"这种"黑体要点 + 独立公式"的有序列表，每条 1–3 行，公式用 $$ 单独成块。最后接"最重要的理解"（2–3 条），每条包含一个被框选的核心恒等式。

七、语言与表达（默认风格）

• 人称用"我们"（推导）和"读者"（提示），不用"你"。
• 引导句以冒号结尾，紧接公式：可以写出如下形式化定义： + $$ … $$。
• 递进连接词：因此、于是、注意到、这解释了、关键在于。
• 不用"显然"、"易得"，除非确实一行可得。
• 一句话只讲一件事；一个公式只推一步。
• 结论必须与公式一致；容易混淆的地方单开小节澄清（"训练时的插值直线 ≠ 推理时的轨迹"这类）。
• 推导步骤用有序列表（1. 2. 3.），性质罗列用无序列表，两者不要混用。
• 被引用的公式按编号回指：由式 (1)、类似式 (21)。

八、公式与排版规范（硬约束）

详细细则、符号速查与兼容性对照见 reference/math-and-markdown.md。核心约束：

• 行内公式 $…$；独立公式 $$ … $$ 且前后各留一个空行，避免被并入段落。
• 独立公式默认不编号；被正文引用时加 \tag{n}。与原文风格一致：独立公式末尾的句点写在公式内部（$$ x \sim \mathcal N(0,I). $$）。
• 关键结论用 \boxed{}，允许与 \begin{cases}、\begin{aligned} 嵌套。
• 多行推导只用 \begin{aligned} … \end{aligned}，对齐符 & 放在等号前；分段定义用 \begin{cases}。
• 不要用裸 \\ 换行：KaTeX（VS Code 预览）下 $$ 内的 \\ 不换行并告警，MathJax（GitHub）下却会换行——同一份源文件两处不一致。多行一律交给 aligned／cases 环境。
• 不用 align／equation／gather 环境：它们在 KaTeX 下只能用于 display 模式，且编号与间距行为与 MathJax 不一致。
• 算符与集合用正体／黑板体：p_{\mathrm{data}}、\mathcal L_{\mathrm{FM}}、\mathbb E、\mathcal N(0,I)、\mathbb R^d。
• 结构强调用 \underbrace{…}_{\text{说明}}、\xrightarrow{F_\theta}、\qquad。
• 公式内的中文只能写在 \text{} 里，并且只放很短的说明；裸中文或 \mathrm{中文} 会触发 KaTeX 严格模式告警（"Unicode text character used in math mode"）。
• 条件概率用 \mid，不用 |。
• 中文标点用全角；正文中公式与中文之间保留一个空格：采样高斯噪声：$x_0\sim\mathcal N(0,I)$。
• 表格用于对比、映射、清单（求解器对比、概念对照、符号表），不用表格承载长段解释。
• 代码块与公式一一对应：给最小可运行实现，步骤编号与正文对应（# 1. Gaussian noise），变量名与符号名对应（x0、x1、t、target_v）。
• 禁止行内 HTML 与自定义宏（\newcommand）：会破坏可移植性与可移植渲染。

九、写作流程

1. 定核心问题。 写出一句话疑问；写不出说明主题还没收敛，先回去讨论而不是动笔。
2. 固定符号表。 一次确定全部符号（如 $x_0,x_1,t,v_\theta,p_t$），中途不换名；符号表可作为第一节末尾的表格。
3. 排章节标题。 按"为什么 A → 为什么 B → …"排成递进标题，确保每步只引入一个新工具；顺手为每节写出「为了解决…，得到…」一句话，写不出的节说明还没想清楚。
4. 逐节填肉。 每节写完立刻自检：结论是否被推导出来？是否给出动机？公式后是否有解释？
5. 补实现与澄清。 加最小代码、常见误解小节、边界情况（数值稳定性、时间方向约定等）。
6. 写总结。 压缩成 N 个关键环节（每个一个 \boxed 公式）+ 2–3 条最重要的理解。
7. 渲染校验。 在 VS Code 预览中逐段检查公式、表格、代码块；推送后在 GitHub 上再确认一次。渲染报错必须当场修掉，不能留给读者。

十、交付前自查（提示，不是门禁）

先按优先级顺序问三个问题，最后再看格式。

公式对不对

• 每个符号都有定义且全程未换名；没有"凭空出现"的等号
• 每一步只做一处变换，依据能一句话说出来
• 边界／退化情形检查过（如 $t=0,1$、$n=1$、方差为零）
• 结论的适用范围写清楚了（恒等式、近似，还是在某假设下成立）

推导是否简洁易懂

• 每节只引入一个新工具，且它服务于主线的下一步
• 每个独立公式后都有一句人话
• 不服务于主线的分支已删掉或移出正文
• 有最小可运行代码，变量名与公式符号一一对应

名词与结论是否串成链

• 新名词都交代了"解决上一节什么问题 + 它是什么 + 与已有名词的关系"
• 每个一级标题都能回答"为什么需要这一步"
• 每节结论能塞进「为了解决…，得到…」这个句式
• 只看被 \boxed{} 框住的部分，能复述全文逻辑
• 总结不是目录复述，并指出了它不回答的问题

格式（达成前三条的手段）

• frontmatter 完整且含 lang: zh-CN，且位于文件第一行
• 有阅读路线与参考链接
• 被引用的公式都有 \tag{n}，正文按编号回指
• 多行推导由 aligned／cases 承载，没有裸 \\ 换行
• 公式内的中文只在 \text{} 中；无 \ce{}／\SI{}／\href{}／\newcommand
• npm run verify 通过（或 node scripts/verify-math.mjs .）
• 在 VS Code 与 GitHub 预览中都无渲染错误；源文件只有 .md（导出物在 build/，git diff 逐行可读）

十一、反模式

十二、仓库内参考文件

• examples/skeleton-template.md — 可直接复制的空骨架（含最小排版示例）
• examples/screenshots/ — 该骨架的渲染效果截图（结构部分与公式部分）
• reference/math-and-markdown.md — 公式与排版细则、KaTeX／MathJax 兼容性速查、渲染自检方法
• scripts/verify-math.mjs — 公式渲染校验器（npm install && npm run verify）