knowledge-point-slides
/knowledge-point-slides
Opracowuje jednoplikowe slajdy HTML tłumaczące pojęcie lub wzór krok po kroku, z wyprowadzeniem od aksjomatów, i sprawdza je zanim trafią do odbiorcy.
- Autor
- yue-a11y ↗
- Repozytorium
- knowledge-point-slides ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 10.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 19
- Skrypty
- 8
- Komentarze HTML
- 2
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 10.11.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
- 8 skryptów w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
- SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.
Skrypty: scripts/check_deck.py, scripts/get_pandoc.sh, scripts/make_mathfont.py, scripts/mathrender.py, scripts/md2docx.py, scripts/scaffold.py, tests/fixtures/rebuild.py, tests/smoke.sh
Co robi i kiedy
Opracowuje jednoplikowe slajdy HTML tłumaczące pojęcie lub wzór krok po kroku, z wyprowadzeniem od aksjomatów, i sprawdza je zanim trafią do odbiorcy.
Oryginalny opis (EN)
把一个知识点讲成单文件 HTML 幻灯片(开讲前先把要用的公式从公理一步一次变换推一遍,推导折叠在公式旁边、一页写不下可续页,无 docx、无例题页、无结论页):当用户要求讲清某个概念、公式或原理,要做讲解 PPT、备课或组会讲一个知识点,并给出起点材料与终点能力时使用。三道闸门(5 行确认 → outline+坐标+公理+公式预备+正文公式五张表 → 交付)逐页验收;公理清单、预备段符号闭包、坐标系、页码可见、推导块全部机器校验;推导里不许解释符号、不许用「由式 (N)」代替推理。
Jak działa
- 何时使用
- 输入槽位
- 输出位置
- 三道闸门(强制,不许跳阶段,不许一次回多个阶段)
- 讲法顺序(先公理,后理论,再算例)
- 公式预备段(全篇最前面,第 1 页就是它)
- 页面规范
- 公式怎么排(Presentation MathML + 文字手写 + 展开态)
- 坐标系契约(换坐标 = 换一整套)
- 动画白名单(只做这四类)
Podgląd SKILL.md
---
name: knowledge-point-slides
description: 把一个知识点讲成单文件 HTML 幻灯片(开讲前先把要用的公式从公理一步一次变换推一遍,推导折叠在公式旁边、一页写不下可续页,无 docx、无例题页、无结论页):当用户要求讲清某个概念、公式或原理,要做讲解 PPT、备课或组会讲一个知识点,并给出起点材料与终点能力时使用。三道闸门(5 行确认 → outline+坐标+公理+公式预备+正文公式五张表 → 交付)逐页验收;公理清单、预备段符号闭包、坐标系、页码可见、推导块全部机器校验;推导里不许解释符号、不许用「由式 (N)」代替推理。
license: MIT
---
# 知识点讲解(HTML 版 PPT)
讲清**一个**知识点:听众听完能动手算、能判断、能反推。
这是讲解,不是名词解释、不是综述、不是文献汇报。
## 何时使用
- 用户说「讲清 XX」「XX 是怎么来的」「做个讲解 PPT」「备课讲一个知识点」「组会讲一下 Tafel 斜率怎么算」
- 用户说「先把要用的公式从最基本的公理推一遍」「别直接甩结论」
- 需要「听完能做到某件事」,而不是「知道这个词是什么意思」
不适用:
- 名词解释、文献综述、论文汇报 → 用 `paper-to-cn-slides`
- 要 Word/PDF 推导文档 → 本技能把推导折叠进 HTML;确实要 docx 才另外用 `scripts/md2docx.py`
- 要 `.pptx` 文件 → 本技能只产单文件 HTML(Ctrl+P 导 PDF)
## 输入槽位
缺任何一项**先问,不要开写**:
| 槽位 | 要求 | 缺失时 |
|---|---|---|
| 知识点 | 一句话,具体到可判定(「LSV → Tafel 斜率怎么取」而非「电化学」) | 必须问 |
| 终点能力 | 动词句:能取 / 能算 / 能判 / 能反推 | 必须问,不要替用户定 |
| 听众 | 谁 + 已知 A、B + 不知道 C、D | 默认「同领域研究生,懂概念不会算」并明示 |
| 起点材料 | 形态 + 量纲 + 范围;预备段之后的第一页必须从它开始 | 必须问 |
| 终点量 | 结论 + 单位 | 必须问 |
| 贯穿算例 | 全篇唯一一组数 | 自造一组,页面上标注「示例数据」 |
| **预备段要几条 P** | **= 从终点量到停点的链长**(沿计算链往下走,走到正文最后一次代入这一式的那一步就停);闸门 1 的「起点」那一行里报个数 | 自己数,别问;数不出来说明终点量还没定 |
硬规则:
- 全篇只用这一组数。任何一页出现这些数,必须完全一致、带单位。
- 没有实测依据的数字写 `[待补:来源]`,**不许补一个看起来合理的值**。
- 全程中文;术语首次出现给英文原词;同一概念全篇一个叫法,中途不换。
- 每页必须有**屏幕上看得见的页码** `N / M`,并且画布要缩放到视口。
- 每张图必须**声明坐标**(`data-x` / `data-y` / `data-xscale` / `data-yscale`),轴标签写「量 + 单位」。
- 公式里**每个符号**都要 `<var data-sym="…">`;正文页要求本页图上能指到同名符号,预备段页不要求(见「公式预备段」)。
- 每条公式**同页**必须有 `<details class="deriv">` 推导块;全篇有一张 `<details class="recalc">` 数值复算表。
- 每页必须声明**页角色** `data-kind`(**axioms** / formula / origin / theory / calc / pitfall)——**没有结论页**。
- 第 1 页是**公理清单页**(`data-kind="axioms"`,不挂 `data-eq`、不挂推导),随后每条 P 一页(`data-kind="formula"`),起点原图页顺延。
## 输出位置
```text
work/<slug>/ # slug = 英文小写连字符
├── <slug>.html # 单文件幻灯片(唯一产物,推导在页面里折叠)
├── shots/deck-print.pdf # 整份打印件
├── shots/p-0N.png # 抽查 ≥3 页截图
└── <slug>-交付说明.md # 勾选结果 + 没做到的事
```
**不产 docx。** 推导与数值复算都以 `<details>` 折叠块住在 HTML 里。
## 三道闸门(强制,不许跳阶段,不许一次回多个阶段)
### 闸门 1:只回 5 行,等确认
```text
起点:(从哪条公理起;预备段要几条 P)
终点:
听众缺:
贯穿算例:
最容易错的一步:
```
不写正文、不写大纲、不解释为什么这么设计。
「起点」那一行必须报出**预备段要几条 P**:从终点量沿计算链往下走,走到「正文最后一次代入这一式」就停,链长就是 P 条数。报不出 → 终点量还没定,回去问。
### 闸门 2:outline + 坐标表 + 公理表 + 公式预备表 + 正文公式表,一次给全,等确认
五张表的**合并**就是为了少一轮等待,别拆开问。
```text
页码 | 页角色 | 这页让听众做什么判断 | 比上一页多/变了哪个视觉元素 | 一句话结论
```
页角色只能填 `axioms` / `formula` / `origin` / `theory` / `calc` / `pitfall`,与 HTML 的 `data-kind` 一一对应。
- 第 1 页 `axioms` 是公理清单;紧接着每条 P 一页(`formula`);再往后 `origin` 是起点那张图。
- **最后一页停在最后一个算例(`calc`)或错例(`pitfall`)上**,不再另起一页总结。
- `theory`(成立条件 / 失效后果 / 判据)必须排在任何 `calc` 之前;`pitfall` 至多 1 页。
- 页数**不设上下限**:预备段长度 = 链长,正文长度 = 算例走完所需页数。硬约束只有三条(脚本会判):
- **S1**:预备段页数 = 1(`axioms`)+ P 条数(+ 各自的续页);一页一条 P(续页同 `data-eq` + `data-part`),两条 P 不许挤一页。
- **S2**:正文顺序不变:`origin` → `theory…` → `calc…` → 至多 1 页 `pitfall`;末页是 `calc` 或 `pitfall`,没有结论页。
- **S3**:`calc` 占**正文页**(不含预备段)至少一半;`check_deck.py` 会打印「公理 X 条 / 预备段 Y 页 / 正文 Z 页 / calc 占比 W%」,低于 50% 直接 error。
- 最后一页之前,每页都是对**同一张图的递进变形**,不是换一张新图。
```text
坐标表:页 | x 量 | x 刻度 | y 量 | y 刻度 | 与上一页相比变了什么(换了就必须写 recast 那句话)
公理表:A 号 | 标签(定义/定律/经验事实) | 式子 | 为什么它是公理而不是推论 | 被哪几条 P 引用
公式预备表:P 号 | 式子 | 输入量(第几页哪个读数) | 输出量 + 单位 | 起点 A 号 | 步数 | 用于第 N 页 | 停点理由(为什么不再往下推) | 失效条件(带数值)
公式表:页 | 式号 | 式子 | LHS | 推导起点(定义 / 物理前提 / 实验事实 / 哪条 P) | RHS 里每个量在本页图的哪里 | 代入哪几个数 | 误差/失效边界 | 分几页
```
- 「停点理由」或「起点 A 号」为空的行视为**没写**,打回。
- 公理表与公式预备表管 `P1…Pn`;公式表管正文式 `1…n`。**两张表不许混号**:正文引用预备式只写「P2」,不写「式 (P2)」。
- 公理表里出现「Tafel 方程」「Nernst 极限电流」这类**有推导来源**的式子 → 它不是公理,必须给推导。
真实图拿不到时写「拿不到」,**不许用近似图顶替,不许 AI 生图当数据曲线**。
### 闸门 3:产出文件 + 自检全绿
先跑脚手架,再填内容:
```bash
python3 scripts/scaffold.py work/<slug>/outline.json work/<slug>/<slug>.html
```
`outline.json` 格式见 `scripts/scaffold.py` 文件头。它会一次性把页码、视口缩放、坐标声明、轴标签、
刻度占位、公理清单页、P 式页、推导块、复算表、翻页脚本全部生成好——这些靠手写必然漏,漏了就要反复返工。
填完后:
```bash
python3 scripts/check_deck.py work/<slug>/<slug>.html
```
**退出码 0 才算交付**。有 error 就改,不要解释为「模型限制」。脚本会额外打印一行结构摘要:
`公理 5 条 / 预备段 4 页 / 正文 9 页 / calc 占比 67%`。
## 讲法顺序(先公理,后理论,再算例)
顺序错了,后面每一页都在打补丁:
1. **公理清单页**(`data-kind="axioms"`):文首单列一节 `A1…An`,每条带 [定义] / [约定] / [定律] / [经验事实] 之一,并写 `data-used-in="5,7"`。全文只引编号。
2. **公式预备段**:一条链一页(`P1…Pn`),从 A 编号出发、一步一次变换,推到「正文最后一次代入」就停。
3. **起点页**:只放用户给的那张原图,不叠任何后文标记。标题只能是原图上肉眼可见的事实。
4. **条件页**:在第一次取数之前,把「成立条件 / 违反后图会长什么样 / 判据」一次性讲完。
5. **算例页**:从条件页的判据出发,一页一个动作,正例推导到底。
6. **错例页(至多 1 页)**:三段式易错点集中列,不占多页、不带动画。**错误不靠举例说明,靠条件页的理论提前拦掉。**
收尾停在最后一个算例上:`calc` 页的标题已经写着这一步算出的数与它的意义,**不要另起一页做总结/结论**。
**不出结论页、不出例题页、不出自测题、不出「你学到了什么」。**
## 公式预备段(全篇最前面,第 1 页就是它)
一句话目标:**开讲之前,把讲这个知识点要用到的每一条数学公式,从最基本的公理 / 定义出发、
一步一次变换地推导出来——但只推到本文档真正用到的那一式为止。**
起点永远是公理,终点才是「用到的那一步」。
- **位置**:预备段在全篇最前面:第 1 页是公理清单页(`data-kind="axioms"`),第 2 页起是 P 页(`data-kind="formula"`)。起点原图页顺延到第 N+1 页,仍遵守「不许叠任何后文标记、标题只能是图上肉眼可见的事实」。
- **不是目录**:不许把预备段写成目录页 / 导览页 /「本章公式一览」。
- **页角色**:允许集 `axioms` / `formula` / `origin` / `theory` / `calc` / `pitfall`;`axioms` 只有第 1 页且不挂 `data-eq`。
- **两套号永不复用**:预备段 `P1、P2…`(`data-eq="P1"`),正文核心式仍是 `式 1、式 2…`(`data-eq="1"`)。正文引用预备式只准写「P2」,**不许写「式 (P2)」**。
- **一页一条式**(≤1 条公式);编号从 P1 连号;一页写不下就续页(同 `data-eq`,`data-part="2"`)。
- **每页必须有 `.io` 行**:`<p class="io">吃进:E [mV](第 4 页读得到)→ 吐出:η [mV]</p>`。式子的 LHS/RHS 全用 `<var data-sym="…">`,带单位行。
- **可以不带图**;带图就守既有坐标系契约。**「式里的量必须在图上指得到」只管正文页,不管预备段页**。
- **禁止动画、禁止高亮带、禁止滑块**;第 1 页连强调色块都不加。
### 深度:终点闭包 + 起点公理
- **终点(停点)**:从本文档的终点量出发沿计算链往下走,走到「正文最后一次代入这一式的那一步」就停。
停点之后的内容(机理来源、常数取值、更高阶修正)一律不写。
原「反向闭包」不许再用来删前置式——它只决定最后一条 P 是哪条。
- **起点**:链条第一步必须是公理清单里的 A 编号,或一条被明确标注的定义。
**不许从「图上读得到的量」或「教科书结论」起步。**
- **核心步骤不要跳过,换算步可以省略**:产生本知识点判据 / 结论的那几步一条都不许跳;
纯换算步(换底、换单位、移项、一次等价变形)可以压成相邻式子「依据」里的一行,不单独成页、不占 P 号。
注意:**换算步可省 ≠ 公理可省**,从公理到该式的路径不许断。
### 定义不推导(P 段准入四条)
**定义式、约定式、纯换算式(取对数、换单位、移项)一律不占 P 号**,写进文首 A 节。
A 条目用 `data-used-in="5,7"` 交代它被哪些页用到;未被任何页用到的 A 是冗余 → error。
P 段准入四条,全满足才许立 P 页:
1. 式子归一化(去空格、去单位、≡ 当 =)后**不等于任何一条 A 的式子**;
2. `deriv` 表 **≥3 步**;
3. 至少 **2 步是真实变换**(取对数 / 引入近似 / 相减 / 与 A 对照定系数)——不许出现
「照抄 A × → 代常数 → 换个单位」这种三步空转;
4. `data-axiom` 指向的 A 存在,且不是这条 P 自己。
预备段**允许只有 1 条 P**。不许为了「看起来完整」把定义包成 P。
判据:删掉这条 P,听众还能读吗?能 → 它不是预备式,降为 A 条目或正文一行。
本仓库的对照样本(`work/lsv-to-tafel-prep`):A1 = η 定义、A2 = j = I/A(附 log 注记)、
A4 = E_eq 约定、A5 = 直线斜率 k = Δy/Δx;P 只剩一条 `b = Δη/Δlog₁₀ j`。
脚本判据(C7,全 error):P 的式子归一化后等于某条 A → `P1 是 A1 的重述,定义不推导`;
推导里「依据 A×」且该行与该 A 一字不差 ≥2 行 → 照抄公理;步数 <3 或真实变换 <2 → 空转。
### 公理清单(文首单列一节,编号 A1…An)
```html
<section class="slide" data-page="1" data-kind="axioms" data-goal="b">
<h1>三条定义、一条约定、一条定律</h1>
<ol class="axioms">
<li data-axiom="A1" data-used-in="5,7"><b>[定义]</b> <span class="eq">η ≡ E − E_eq</span><span class="note">过电位</span></li>
<li data-axiom="A2" data-used-in="6"><b>[定义]</b> <span class="eq">j = I / A</span><span class="note">纵轴取 log₁₀(j/j_ref),j_ref = 1 mA/cm²;log 的自变量必须无量纲</span></li>
<li data-axiom="A3" data-used-in="2"><b>[定律]</b> <span class="eq">j = j₀[exp(α_aFη/RT) − exp(−α_cFη/RT)]</span><span class="note">Butler–Volmer</span></li>
<li data-axiom="A4" data-used-in="5"><b>[约定]</b> <span class="eq">E_eq = 0.00 V</span><span class="note">RHE 刻度、pH 0 基准下的 HER</span></li>
<li data-axiom="A5" data-used-in="2,7"><b>[定义]</b> <span class="eq">k = Δy / Δx</span><span class="note">直线 y = kx + c 的斜率</span></li>
</ol>
</section>
```
上面 `.eq` 里的式子写的是 **DSL**(给人看的),产出 HTML 里是 `<span class="eq"><math>…</math></span>`
(由 `scaffold.py` 从 outline 的 `eq` 字段生成)。分式按 C12 自动二维(`j = I/A`、`k = Δy/Δx`
都是 `<mfrac>`),量纲写法(`mA/cm²`、`mV/dec`)保留斜杠。
- 每条必须带标签,只许四种:`[定义]` / `[约定]` / `[定律]` / `[经验事实]`。判据:
- **约定** = 刻度 / 参考点的选择(例:RHE 刻度下 HER 的 E_eq = 0.00 V)→ 标 `[约定]`,不标 `[经验事实]`
- **定律** = 有独立实验支撑的唯象关系(例:BV 方程)
- **定义** = 纯定义或纯数学(例:η ≡ E − E_eq;直线斜率 k = Δy/Δx)
- **经验事实** = 具体体系的具体测量值(必须带条件:介质、温度、pH)
- 每条 A 必须带 `data-used-in="5,7"`(它被哪些页用到),且那些页真的引用它;未被任何页用到的 A 是冗余 → error。
- **禁止标签**:`[教科书结论]`、`[已知结论]`、`[显然]`、`[由…可知]`。出现即 error。
- **推论不许升格为公理**。判据:这条式子在本文档之外的文献里是否还有推导来源?
有 → 它不是公理,必须给推导。(例:Tafel 方程有 → 不能进 A 节;BV 是唯象公理 → 可以)
- **目标量不许进公理清单**。A 节只收三类东西:基本量的定义、守恒律 / 唯象定律、明确的实验事实或测量约定。
「某个要通过本文档求出的量 = 某条直线的斜率 / = 某个待求关系的系数」是判断结果,不许写成 A 条目。
文首用 `data-goal="b"` 声明终点量;A 节任一 LHS 出现终点量 → error。
- 斜率要写成**纯数学**(不含任何待求量):`A5 [定义] 直线 y = kx + c 的斜率 k = Δy/Δx`。
`b` 的首次出现放在推导里,不许在 A 节:
```text
(3.5) η = (2.303RT/α_aF)·log₁₀(j/j₀) 与 A5 的 y = kx + c 对照(y = η, x = log₁₀j, c = 0)
→ k = 2.303RT/(α_aF),记 b ≡ k 依据 A5 + 代数
(3.6) k = (η₂−η₁)/(log₁₀j₂ − log₁₀j₁) 依据 A5(直线斜率定义)
(3.7) b = Δη/Δlog₁₀ j 代数
```
- A 条目的 RHS 以另一条 A 的 LHS 开头 → error(公理之间不许互推)。
- **`[近似]` 类不许出现在 A 节**——近似写在引用它的那一步的「依据」列,并当场给数值
(「η = 150 mV 时还原项占 2.9×10⁻³」),不许写「η 较大时」。
### 口径示例(LSV → Tafel 斜率)
```text
公理清单(文首单列一节,全文只引编号)
A1 [定义] η ≡ E − E_eq
A2 [定义] j = I / A
A3 [定律] j = j₀[exp(α_aFη/RT) − exp(−α_cFη/RT)] Butler–Volmer
A4 [近似] η ≫ RT/F 时还原项/氧化项 < 1%,可略(当场给数值)
A5 [定义] b ≡ 直线 η–log₁₀j 的斜率
—— Tafel 方程不是公理,是 A3+A4 的推论;把它写进 A 节即 error。
P1 η = E − E_eq
(1.1) η ≡ E − E_eq 依据 A1
(1.2) E 取 vs RHE、HER 的 E_eq = 0.00 V 依据 A1 + 实验条件
(1.3) η [mV] = E [mV] 代数
P2 log₁₀(j / j_ref),j_ref = 1 mA/cm²
(2.1) j = I/A 依据 A2
(2.2) 取对数必须无量纲,故写 log₁₀(j/j_ref) 依据 量纲
(2.3) 100→2、10→1、1→0 代数
P3 b = Δη/Δlog₁₀j = (η₂−η₁)/(log₁₀j₂−log₁₀j₁)
(3.1) j = j₀[exp(α_aFη/RT) − exp(−α_cFη/RT)] 依据 A3(起点)
(3.2) j ≈ j₀exp(α_aFη/RT) 依据 A4;η=150 mV 时还原项占 2.9×10⁻³
(3.3) η = (RT/α_aF)ln(j/j₀) 代数:两边取自然对数
(3.4) η = (2.303RT/α_aF)log₁₀(j/j₀) 代数:ln x = 2.303 log₁₀x
(3.5) b = 2.303RT/(α_aF) 依据 A5 + 系数对比
(3.6) η₂−η₁ = b(log₁₀j₂−log₁₀j₁) 代数:在 (3.4) 上取两点差
(3.7) b = Δη/Δlog₁₀j 代数:除以 Δlog
(3.8) (250−150) mV ÷ 1.667 dec = 60.0 mV/dec 数值:代本 deck 的数
(3.9) 窗口内不线性时得弦斜率 b_app,偏离真 b 误差与失效边界
到此为止:不推 α 的物理来源,不推 j₀。
```
示例按原文照录,落成 deck 时有两处必须改:
1. **A4 是 `[近似]`**——按上面「`[近似]` 不许进 A 节」的规则,它要挪到 (3.2) 的「依据」列并当场给数值;
A 节里换成这个算例真正需要的 `[经验事实]`(例:`A4 [经验事实] 0.1 M KOH、pH 0 基准下 HER 的 E_eq = 0.00 V vs RHE`)。
2. **(3.8) 的 250/150/1.667/60.0 是另一组数**——换成你自己那组贯穿算例
(`work/lsv-to-tafel-prep` 用 `120 mV ÷ 0.905 dec = 132.6 mV/dec`)。
另外每条 P 还要补两行才能过闸门:用贯穿算例代入的那一行、带数值阈值的失效行(见下面五问第 3、4 问)。
示例里 P1(η 定义)、P2(log₁₀(j/j_ref))按「定义不推导」应降为 A 条目——它们不产生任何可算的中间量,
删掉后听众照样能读(对照样本 `work/lsv-to-tafel-prep` 就是这么做的)。
### 「讲清楚」的五问——每条 P 式必须五问全答,缺一条算没讲清
1. 这一式把哪个量换成哪个量?(输入量 + 从哪读;输出量 + 单位)→ `.io` 行
2. 它在本文档第几页被用?(`data-used-in="N"`,N 必须是存在的 `calc` 页,且该页真的引用它)
3. 一个数代进去能算出结果吗?(用贯穿算例的数代入,落在该式推导块里)
4. 什么时候不能用?(失效 / 近似条件,一句话,带数值阈值)
5. 这条链的起点是哪条 A 编号?(`data-axiom="A3"`;答不出不许进预备段)
额外:这条链上每一步都不许跳。判定:读者只看 A 节 + 这条链,能否独立复现整条式子?
不能复现 → 中间少了步,补。
### 推导块格式(沿用 `details.deriv`,新增两条列要求)
```html
<details class="deriv" data-eq="P3">
<summary>推导:BV → b = Δη/Δlog₁₀j(P3)</summary>
<table><tr><th>步骤</th><th>式子</th><th>依据</th></tr>
<tr><td>(3.1)</td><td>j = j₀[exp(α_aFη/RT) − exp(−α_cFη/RT)]</td><td>A3</td></tr>
…
</table>
</details>
```
- 第一步的「依据」单元格**只能是「A编号」或「定义」**,不许写「已知」「题设」。
- 之后每步的依据只能取:`A编号` / `代数` / `量纲` / `近似及条件`。
- 每步只做一次变换;一页写不下就续页(同 `data-eq`,`data-part="2"`),不许把两步并一行。
- 末尾必须有:**数值代入一行(带单位) + 误差/失效边界一行**。
### 三条既有禁令在预备段怎么用
- **不许解释符号含义**照旧生效:不许「其中 j 为电流密度」「分别表示」。含义靠 `<var data-sym>` + 单位行 + `.io` 行的「进/出」表达。
- **不许用「由式 (N) 得」代替推理**:预备段内部完全生效(P 之间不许互相当代替推导)。
**正文算例段允许写「依据:P3(已在预备段完整推导)」**——理由:预备段存在的目的就是让后面能引用,而不是重推。
- **每页 ≤1 条公式**不变。
### 脚本硬校验(C1–C12,全是 error,不是 warn)
| 编号 | 查什么 | 报错示例 |
|---|---|---|
| C1 | 孤儿符号闭包:`calc` 页的 `<var data-sym="X">` 必须属于某条 P 的 LHS/RHS,或 `origin_reads` | `孤儿符号 X 首次出现于第 N 页,预备段无定义式` |
| C2 | 每条 P 的 `data-used-in="N"` 必须指向存在的 `calc` 页,且该页真的引用它 | `P3 声明用于第 7 页,但第 7 页未引用它(预备段冗余)` |
| C3 | 第 1 页 `data-kind="formula"`;预备段每页 ≤1 式;P 号连号;无动画/高亮带/滑块;每条 P 有非空 `data-stop` 与 `.io` | `P1 缺 data-stop(停点理由)…` |
| C4 | 每条 P 的推导首步依据命中 A 编号或「定义」;全文无「由式/由上可知/显然/易得/已知结论」;推导里至少一次 A 编号 | `P3 推导首步依据为「Tafel 方程」,未命中公理清单(推论当公理)` |
| C5 | 每条 A 带四标签之一;无禁用标签;A 节内无近似;`data-used-in` 指向的页真的引用它 | `A4 里写了近似「较大时」…不许进公理清单` |
| C6 | 标题 / lead / 正文 / 列表里出现元话语黑名单词 | `第 3 页标题出现元话语「开讲前」:「开讲前先钉死五条…」` |
| C7 | P 段准入:式子归一化后等于某条 A(定义不推导)、照抄公理 ≥2 行、步数 <3 或真实变换 <2 | `P1 是 A1 的重述,定义不推导` |
| C8 | A 节收进终点量、A 之间互推、`[约定]` 里写「实测」 | `A5 的 LHS 是终点量 b,目标量不许进公理清单` |
| C9 | MathML 结构:每个公式实例恰好一个 `<math>`;`<math>` 外无公式内容;叶子只用 mi/mn/mo/mtext/mrow/msub/msup/msubsup/mfrac/msqrt;整条式子不许只在一个 `<mtext>` 里;`<math>` 文本里不许 `_` / `^` | `第 5 页 推导表式子列 里有 0 个 <math>…` |
| C10 | 无外部数学排版库(MathJax/KaTeX/polyfill/CDN)、无图片顶替公式、无 `.mth`/`.scr` 定位 span | `引了外部数学排版库「mathjax」…` |
| C11 | 公式外(HTML 文本,跳过 `<svg>`)不许残留 Unicode 上下标;单位里的 ²/³(mA/cm²)例外 | `第 10 页公式外残留 Unicode 上下标「₁」…` |
| C12 | 分式一律二维:`<mo>/</mo>` 只许夹在两侧都是量纲文本的位置(`<mtext>mA</mtext>`、`<msup><mtext>cm</mtext><mn>2</mn></msup>`);`<mfrac>` 的分子分母不许都是量纲词;`<mfrac>` 后面不许紧跟操作数(分母只框一个 token) | `第 3 页 推导表式子列 的 <mo>/</mo> 两侧不是量纲词(左=<mi>j</mi>,右=<msub><mi>j</mi><mn>0</mn></msub>)…` |
实现位置:`check_deck.py` 的 `check_formula_section()`(C1–C5)、`check_meta_discourse()`(C6)、`check_prep_admission()`(C7)、`check_axiom_scope()`(C8)、`check_mathml()`(C9–C11)、`check_fraction_shape()`(C12),与坐标系 / 推导检查分开。报错文案带页号 + `data-eq` + `data-sym`,便于回修。
## 页面规范
### 页面不许有元话语(C6,脚本 error)
**元话语 = 关于「本文档怎么组织 / 为什么不那样做 / 后面会讲什么 / 讲解者做了什么」的句子。**
它不是知识点,不许出现在任何幻灯片页面上(标题、lead、正文、图注、列表都不许)。
典型形态:
- 「开讲前先钉死五条」「A1–A5 之外不再假设任何东西」
- 「Tafel 方程不在这五条里:它是 A3 加近似推出来的」
- 「为了讲清楚,我们先…」「本节只讲…」「注意:后面会用到」
- 「这几条是全部前提」「本文档不引入其他假设」
判据一句话:把这句话念给听众,他获得的是「知识」还是「讲解者的说明」?后者删。
去处:只能进 `<slug>-交付说明.md`,或页面里**默认折叠**的 `<div class="notes">`(仅供讲者,
Ctrl+P 打印时必须不展开)。不许留在标题或 lead。
首页(公理清单页)的正确写法:标题只陈述这页有什么(例:「三条定义、一条约定、一条定律」),
下面直接是 `<ol class="axioms">`,不写任何 lead 段落,不解释为什么只列这些。
脚本黑名单:`开讲前 / 本文档 / 不再假设 / 为了讲清楚 / 本节只 / 后面会 / 接下来我们 /
不在这几条里 / 先钉死 / 请记住 / 需要说明的是`——命中即 error,报错带页号与原句。
- 一页一个动作。标题就是这页的结论,不是话题名(写「η 增大时斜率由 60 降到 40 mV/dec」而不是「Tafel 斜率讨论」)。
- **标题与图必须同页同源**:跨坐标系的结论(「变平」「偏离直线」「线性区」)只能出现在纵轴取对数的那一页;线性原图页只说「j 增长变慢」。
- 正文 ≤60 字/页,图为主;只出现当前这一步需要的公式。
- 每页右下角显示 `N / M` 页码,且**画布缩放到视口**(1600×900 固定版式 + `transform: scale` + resize 监听),保证任何窗口下页码都在屏幕内。
- 阶梯必须完整:每步写清「输入 → 操作 → 输出 → 判据」,不跳中间步骤。
- ≥3 条具名易错点,每条三段式:**错误做法 / 现象 / 正确做法**。写成「注意 XX」的视为没写;全部集中在 1 页(`data-kind="pitfall"`)。
## 公式怎么排(Presentation MathML + 文字手写 + 展开态)
公式不是正文的一部分:**公式排成结构化的 Presentation MathML(Chromium 原生排版,
变量斜体走 Latin Modern Math 的 MATH 表),正文文字用手写体**。两条线各用一套内嵌字体,互不继承。
### 公式必须是 MathML(C9–C11,全部 error)
产出的 HTML 里**每个公式实例都是一个 `<math>` 元素**:屏幕上量
`document.querySelectorAll('math').length` 与该页公式清单逐条对得上;
`<math>` 之外不许残留公式内容文本(式号、单位行除外)。
- 结构成层:变量 `<mi>`、数字 `<mn>`、运算符/关系符 `<mo>`、上下标 `<msub>`/`<msup>`/`<msubsup>`、
分式 `<mfrac>`、根式 `<msqrt>`、中文注释与单位词 `<mtext>`。整条式子塞进一个 `<mtext>`、
或只有 `<semantics>`/`<annotation>` 带公式,都算没做。
- 式子写成一行 **DSL**(`j = j_0 e^{η/b_a}`),由 `scripts/mathrender.py` 排成 `<math>`:
`_` / `^` 接单字符或 `{…}` 组(下标可连写 `E_eq` / `b_app`,多字母按正体标签排),
可嵌套(`b_a` 在指数里也能再带下标);**真分式写 `a/b` 就自动排成 `<mfrac>`**
(`\frac{分子}{分母}` 也认,显式写法用于分子/分母里有加减的情形),
`\sqrt{…}` → `<msqrt>`,`\text{…}` → `<mtext>`(走正文手写体)。
- **分式一律二维,量纲保留斜杠**(C12):`/` 两侧都是单位词(`mA/cm²`、`mV/dec`、`mol/L`)时
才留斜杠;分子、分母各是一个完整式子时必须是 `<mfrac>`。细则见下节「分式与量纲斜杠」。
- **变量斜体、数字/运算符/函数名正体**:单字母变量进 `<mi>`(浏览器按 MATH 表挑数学斜体字形),
`e`、`i`、`d` 与希腊大写写 `mathvariant="normal"`,函数名与多字母标签是正体 `<mi>`;
单位词(mV、dec、cm、mol…)落进 `<mtext>`。
- **公式里的上下标只有一种写法**:`<msub>`/`<msup>`/`<msubsup>`。
`<sub>`/`<sup>`、`T_0` 这种下划线拼接、Unicode 上下标(`x²`、`η⁻¹`、`log₁₀`)在公式区域一律 error。
(旧版验收表里「下标写成 `<sub>` 不是 `_`」与「公式里不许出现 `<sub>`」互相打架,
2026-11 起统一成 MathML:`<sub>` 与 `_` 都不许,只用 `<msub>`。)
- **散文里的公式词自动变行内 `<math>`**:`scaffold.subs()` 把标题/正文/图注/单位行/推导表里含
Unicode 上下标或 `_`/`^` 的词(`log₁₀`、`j₀`、`10⁻³`、`E_eq`)自动排成行内 `<math>`;
复杂式子用 `$…$` 显式包起来。**产出的 HTML 里不会有可见的纯文本公式**(C11 就在查这个)。
- **推导表「式子」列整格是一个 `<math>`**:中文注释进 `<mtext>`,不要手写 `$…$`;
「依据」列是散文,只认 `$…$`。
- **白底、1px 深色方框**(`#0f1115`,内边距 9–10px),无旋转、无下划线、无底色——参考图口径。
方框只框式子本身(`.expr`),单位行与推导表留在框外。
- **不引 MathJax / KaTeX / MathML polyfill / CDN,不用图片或 SVG 充当公式**(C10):
Chromium 109+ 原生支持 MathML Core,单文件离线、断网打开仍成立。
- 字体:`scripts/make_mathfont.py` 生成 `scripts/assets/mathfont.css`(Latin Modern Math 子集,
woff2 约 75KB),子集内部 name 改成 `DeckMath`。换机器、断网都不掉档。
- 字形覆盖:`<math>` 里除 `<mtext>` 外的每个字符都必须在 DeckMath 的 cmap 里,
`<mtext>` 的内容必须在 DeckText 的 cmap 里(`check_deck.py` 解 base64 逐字核对)。
### 分式与量纲斜杠(C12,脚本 error)
**分式一律二维,量纲保留斜杠。** 两类写法靠「斜杠两侧是什么」判定,不靠人眼:
| 类别 | 判据(可机器判定) | 写法 | 例子 |
|---|---|---|---|
| **真分式** | 分子、分母**各是一个完整式子**(变量 / 数字 / 乘积链 / 带括号的整组 / 函数作用 / 幂或根式) | `<mfrac>` | `j/j₀`、`I/A`、`η/b_a`、`Δy/Δx`、`(η₂−η₁)/(log₁₀j₂−log₁₀j₁)` |
| **量纲斜杠** | 斜杠两侧都是**单位词**(`<mtext>`),可带数字前缀与指数(`<msup><mtext>cm</mtext><mn>2</mn></msup>`) | `<mo>/</mo>` | `mA/cm²`、`mV/dec`、`mol/L`、`59.2 mV/dec` |
判据一句话:**把斜杠两侧念出来,是两个物理量就是分式(二维),是两个单位就是一个单位写法(斜杠)。**
`0.1 M KOH` 这类浓度写法里 `M` 是单位词(mol/L),根本不涉及斜杠。
**「分母整组」是什么意思**(最常见的错处:分母只框了第一个 token):
- `Δη/Δlog₁₀ j` 的分母是**整个 `Δlog₁₀ j`**,不是 `Δ`,也不是 `Δlog₁₀`——`j` 必须在分母里。
- `RT/α_aF` 的分母是 **`α_aF` 整体**(带上标),不是 `α` 或 `α_a`。
- `2.303RT/α_aF` 的分子是 **`2.303RT` 整条乘积链**,不是只有 `T`。
`mathrender.py` 的解析器直接按这个口径切项:分子取「斜杠前的那一项」(含 `·`/`×` 乘法链),
分母取「斜杠后到加减/关系符/括号/中文注释为止的整项」,所以 DSL 里写 `Δη/Δlog_{10} j`、
`RT/α_aF` 得到的就是整组分母,**不需要额外加 `{}`**。反过来,`\frac{RT}{α}_aF` 这种
「分母只框一个 token、后面的操作数掉在分式外」的写法会被 C12 直接报错。
脚本查三条(全部 error,报错带页号 + 位置 + 左右节点):
1. `<mo>/</mo>` 左右不是量纲文本 → `真分式(分子、分母各是一个完整式子)必须排成 <mfrac>`;
2. `<mfrac>` 的分子分母都是量纲词 → `量纲写法保留斜杠,不要排成二维分式`(`mA/cm²` 不许二维);
3. `<mfrac>` 后面紧跟操作数(`mi/mn/msub/msup/mrow/mfrac/msqrt`)→ `分母只框住了一个 token`。
量纲词表只有一份:`mathrender.UNITS` / `mathrender.SINGLE_UNITS`,`check_deck.py` 直接引用,
渲染与校验不会各说一套。
### 为什么不用自带定位 span(旧方案)与 weasyprint
- **旧方案**(`.mth` / `.scr` 定位 span 手写上下标)已删:产出的公式不是结构化数学,
无法逐层校验。`check_deck.py` 发现 `.mth` / `.scr` 直接 error(C10)。
- **weasyprint 不支持 MathML**(实测 70.0:`<math>` 当未知行内元素,上下标拍平、分式塌成一行、
变量斜体丢失)。所以 weasyprint **不再是打印源**,也不能拿它的输出做观感对照;
打印走 `tools/shoot_deck.py` 的 Chromium `page.pdf()`,屏幕态与 `deck-print.pdf` 同引擎同观感。
weasyprint 只剩「页数交叉验证」一个用途(页数由 `@page` + 每页一屏决定,与公式排版无关)。
- **SVG 图内文字是图形标注,不是公式实例**:轴标签/刻度里的 `10⁻²`、`log₁₀ j [mA/cm²]`
保持 SVG 文本(MathML 不能进 `<text>`),C11 扫描时会跳过 `<svg>`。
### 文字:LXGW WenKai 子集(按 deck 现场生成)
- 正文、标题、图注、表格文字统一 `var(--text)` = `DeckText`(LXGW WenKai 子集,手写体)。
**不许退回无衬线**:`check_deck.py` 要求 `body { font-family: var(--text) }` 且 DeckText 内嵌。
- 文本字体按 **deck 的字符集**现场子集化(`scaffold.embed_text_font`):300 个汉字约 86KB woff2,
全量 CJK 会撑爆 320KB。字符集要含 **空格 U+0020**(缺了空格会回退系统字体,Chrome PDF 实测)
与 CSS 伪元素的 `content` 字符串(`•`、`——`)。
- 字形覆盖:每一页的可见文字都必须落在 DeckText 的 cmap 里,否则 error。
### 字形来源怎么量
`python3 tools/measure_deck.py <html> --fonts`(CDP `CSS.getPlatformFontsForNode`):
公式元素只许 `DeckMath`,正文只许 `DeckText`;`--tilt` 量表格与公式的水平度(|Δy| ≤ 1px)。
### 打印
`tools/shoot_deck.py` 用浏览器打印生成 `deck-print.pdf`(= Ctrl+P 同一条路径),PDF 里只有
DeckText / DeckMath。**不要用 weasyprint 当打印源**:它的 SVG `<text>` 不走 `@font-face`,
会把系统字体(DejaVu / WenQuanYi)带进 PDF(实测)。weasyprint 只用于页数交叉验证。
**折叠块必须「展开后仍在一页内」。** 屏幕态是折叠的,一展开就顶出 900px,
`overflow: hidden` 会把下半截直接裁掉——观众看到的是半张表。规则:
- 一条 `details` 展开后,页面 `scrollHeight` 不得大于 900px;
- 复算表**单独成页**(同页有图且行数 > 8 = 必然溢出,脚本直接 error);
写不下就拆 `data-part="1"` / `"2"`;单独成页时必须 `<details class="recalc" open>`——
默认折叠的末页等于一张空白页,讲的时候还得先点一下;
- 判定靠真浏览器:`python3 tools/shoot_deck.py <html>` 会把本页所有 `details` 打开再量一次
`scrollHeight - clientHeight`,> 1px 就报 `✗ … 展开 N 个折叠块后溢出 Xpx`。
它同时核对打印页数 == 幻灯片页数(多一页就是内容溢到下一页)。
## 坐标系契约(换坐标 = 换一整套)
只要坐标变了(E → η、j → log j、刻度重排),下面五样必须**同时**改,缺一样就算错页:
1. 轴标签(`<text class="ax" data-axis="x|y">量 [单位]</text>`)
2. 刻度值与刻度形态(`data-axis` 标在每个刻度上;对数轴写 `10⁻²`,不许出现 0)
3. 图注里的量名
4. 正文里提到该量时的名字
5. 一行 `<p class="recast">旧量 → 新量 = 换算关系(刻度是否变)</p>`
额外规则:
- 纵轴取对数就直接写 `log₁₀ j [mA/cm²]`;**禁止**「j [mA/cm²](对数)」这种把刻度塞进单位括号的写法。
- 几何标注必须带方向:`data-span="x"` 的边只能量横轴的量,`data-span="y"` 只能量纵轴的量。Δ 量画错方向是最常见的翻车点。
- 一张图只声明一组坐标;换图不要偷偷改声明。
## 动画白名单(只做这四类)
1. 坐标轴变换(线性 ↔ 对数、刻度重排)
2. 数据点沿曲线移动,标出当前取的区间
3. 拟合线扫过区间、几何量的边长标注出现
4. 参数滑块驱动图形与公式数值同步
配额与判据:
- 全篇动画页 **≤3**,同一种动画**只用一次**。
- 每个动画必须绑住公式里的一个量:删掉后听众会失去哪个数?说不出来就删。
- **错例页禁止动画**:错误用静态对比 + 三段式文字。
- 第 1 页禁止任何叠加标记(高亮带、拟合线、标注、动画)。
判据:**删掉这个动画观众仍能理解 → 不做。**
禁止:入场动画、呼吸浮动、粒子背景、打字机、转场特效、无关 hover、emoji 当图标。
## 公式、推导与数值复算(全部住进 HTML)
幻灯片页面上只留**正文核心式**:
- **不再设「全篇核心式 ≤3 条」**:核心步骤(产生本知识点判据 / 结论的那几步)一条都不许跳过;
纯换算步(换底、换单位、移项、一次等价变形)可以压成相邻式子「依据」里的一行,不单独成页。
需要卡上限时手动给 `--max-eq N`,默认不卡。
- 一个关系全篇只出现一次;**不许移项/代入后另编一个式号**。正文可以写「同式 (2)」指代,但推导里不许拿「由式 (2) 得」当依据(见下节)。
- 同一个量的左边(LHS)不许在两条式子里各当一次主角。
- 每页最多 1 条公式,带编号(式 1、式 2…,全篇连续);预备段用另一套号 `P1、P2…`,两套永不复用。
- 每个符号写成 `<var data-sym="j">j</var>`,且正文页**至少一个符号必须在本页图上找得到**(预备段页不要求)。
- 页面上出现「补偿 / 外推 / 换算 / 折算 / 归一化 / 校正」这类操作词时,该页**必须给出该操作的定义式**(例如 `E_meas = η_kin + R_u·j`)。
- 页面正文里**不铺推导**,也不许出现「两边取对数」「代入整理得」「移项得」这类推导链。
推导写在公式旁边的折叠块里(原 docx 的内容搬到这里):
```html
<details class="deriv" data-eq="1">
<summary>推导:Butler–Volmer → Tafel(式 1)</summary>
<table>
<tr><th>步骤</th><th>式子</th><th>依据</th></tr>
<tr><td>(1.1)</td><td>j = j₀[exp(α_aFη/RT) − exp(−(1−α_a)Fη/RT)]</td><td>定义:BV 方程(起点,不引用别式编号)</td></tr>
<tr><td>(1.2)</td><td>j ≈ j₀ exp(α_aFη/RT)</td><td>近似 A1:η = 150 mV 时还原项/氧化项 = 2.9×10⁻³,故可舍</td></tr>
<tr><td>(1.3)</td><td>η = (RT/α_aF)·ln(j/j₀) = b·log₁₀(j/j₀),b = 2.303RT/(α_aF)</td><td>代数:取自然对数再换底;量纲:mV / dec</td></tr>
<tr><td>(1.4)</td><td>log₁₀(j/j₀) = 150 mV ÷ 60 mV/dec = 2.5 dec</td><td>代数:代入本页的数(η = 150 mV、b = 60 mV/dec)</td></tr>
<tr><td>(1.5)</td><td>η < 60 mV 时还原项不可忽略,误差可达 10%</td><td>误差与边界:低过电位段不能用式 (1),假设 A1 失效</td></tr>
</table>
</details>
```
**推导只讲一件事:这个式子是怎么被推出来的。** 具体是四条:
1. **从起点写起**:第一步必须是定义、物理前提或实验事实(BV 方程、Tafel 形式、欧姆降的定义、测量得到的两个读数…),不许从另一条式子的编号起步。
2. **一次一步,代数链条不断**:每行只做一次变换(取对数 / 相减 / 取极限 / 代入常数),并在「依据」列写清为什么这一步合法(定义 / 物理前提 / 假设 A1 / 代数 / 量纲)。
3. **落到本页的数**:必须有一行把这一页的数字代进去,算出这一页的结论(`(250−150) mV ÷ 1.667 dec = 60.0 mV/dec`),数字与 `recalc` 表一致。
4. **误差与失效边界**:这个式子什么条件下不成立、偏差多大(`端点读数 ±2 mV → b 偏差 ±1.2 mV/dec;窗口弯曲时得到的是弦斜率`)。
**两条硬禁令**:
- **不许解释符号含义**。「其中 j 为电流密度」「η 表示过电位」「j₀、b 分别是…」一律不要——符号与单位写在公式的 `<var data-sym>` 与单位行里,推导只写怎么算。
- **不许用「由式 (N) 得」代替推理**。前一条式子只是结论;读者要的是这一步的前因后果。数学上必须能独立走通:把第 N 式的内容直接写出来,再往下推。
**唯一例外(预备段的用处)**:正文算例段允许写「依据:P3(已在预备段完整推导)」。理由:预备段存在的目的就是让后面能引用,而不是重推。但预备段**内部**不许 P 之间互相引用。
**一页写不下就多写几页**。推导默认住在公式旁边的折叠块里;装不下时拆片:
```html
<!-- 第 5 页:公式与第 1 片 -->
<details class="deriv" data-eq="2">…</details>
<!-- 第 6 页:同一条式子的第 2 片(页面 data-kind="calc") -->
<details class="deriv" data-eq="2" data-part="2">
<summary>推导(第 2 段):式 (2)</summary>
<table><tr><th>步骤</th><th>式子</th><th>依据</th></tr>…</table>
</details>
```
分片规则:第 1 片必须与公式同页;续片落在**后面的 `calc` 页**;分片号从 1 连续;总步数按所有分片合计,≥3 步;误差/失效边界可以放在最后一片。
硬要求(脚本校验):
- 每条公式至少要有一个 `data-eq` 与之相同的推导块第 1 片,且与公式同页。
- 合计 ≥3 步;必须有「依据」列,且每行落到 定义 / 物理前提 / 实验事实 / 哪条 P / 代数 / 量纲 / 误差,不能是空泛的「整理得」。
- 必须有一行数值代入(带单位的结果);必须有一行写误差、偏差、适用范围或失效条件;必须引用公理编号 A1、A2…。
- 全篇禁止出现「由式」「由上可知」「显然」「易得」「已知结论」「其中」「分别表示」「符号说明」这类字样(脚本 error)。
- 首末两条式子的推导里各查一次量纲;同一个参数全篇只取一个值。
数值复算表(原 docx 的另一半内容,放在任一 `calc` 页):
```html
<details class="recalc">
<summary>数值复算</summary>
<table>
<tr><th>输入</th><th>计算</th><th>结果</th><th>对应</th></tr>
<tr><td>j 0.50 → 23.2 mA/cm²</td><td>log₁₀(23.2/0.50)</td><td>1.667 dec</td><td>第 5 页 Δlog j</td></tr>
<tr><td>100 ÷ 1.667</td><td>除法</td><td>60.0 mV/dec</td><td>式 (2)</td></tr>
</table>
</details>
```
要求:≥3 行;幻灯片上每个带单位的数字都要能在这里找到出处。
## 图与数据(数据驱动,不要逐点内联)
- 示意图手写内联 SVG,但**曲线必须「数据数组 + 一个渲染函数」**:点存成
`<script type="application/json" class="deck-data">` 或一个 `const D=[[x,y],…]`,由 JS 生成 `points`。
单条 `points` 串 >2400 字符或整份 HTML >320KB 会被提示改写。
- 每张图声明 `data-x` / `data-y` / `data-xscale` / `data-yscale`;轴标签用 `<text class="ax">`,刻度用 `data-axis` 标归属。
- 引用真实文献图必须标注出处(作者/期刊 + 图号)。
- AI 生成图不得充当数据曲线。
- 拿不到的材料就写「拿不到」。
## 交付形态
- **单文件 HTML,无外网依赖**:字体、脚本、公式全部内联;不用 CDN 的 MathJax / Chart.js。
- 1600×900 固定版式 + `transform: scale(var(--k))` + `resize` 监听 → 任何窗口都完整可见,页码不跑出屏幕。
- 键盘 ←/→ 与滚轮翻页;1 页 1 屏,任何页面不出现滚动条。
- 正文 ≥20px(1600×900 下);页码 ≥18px;层级 ≤3 级。
- Ctrl+P 导出 PDF 时每页一张、每页一张页面正好一屏;`details` 在打印时自动展开,
**展开后仍不得超过一屏**(导出前用 `tools/shoot_deck.py` 验一遍;chromium 版 `deck-browser.pdf`
用 `pdfinfo` 核页数,weasyprint 版用 `pdftotext -f N -l N` 核最后一页内容没被裁)。
- 截图只交「整份 PDF + ≥3 张抽查」,不再逐页 PNG。
完整契约见 `references/deck-contract.md`,常见翻车点见 `references/anti-patterns.md`。
## 验收(交付前逐条打勾,写进 `<slug>-交付说明.md`)
| 项 | 判据 | 谁来查 |
|---|---|---|
| A | 抽任意一页能说出它比上一页多了哪个视觉元素 | 人 |
| B | 用贯穿算例从起点原图页复算到末页,数值一致 | 人 |
| C | ≥3 条易错点,均为三段式,集中在 1 页 | 脚本 + 人 |
| D | 每条公式有推导块(第 1 片与公式同页,可续页):≥3 步、从起点写起、不解释符号、不用「由式 (N)」、依据落到定义/前提/假设、代入本页的数、给误差/失效边界、首末查量纲 | 脚本 + 人 |
| E | 断网打开,公式/图/动画正常 | 脚本 + 人 |
| F | 每页无溢出、无滚动条、字号达标;**页码在屏幕内可见**(缩放后逐页看) | 人 |
| G | 附 `shots/deck-print.pdf` + ≥3 张抽查截图 + 勾选结果 + 「没做到的事」清单 | 人 |
| H | 每页公式 ≤1 条且带编号,无推导链,符号有含义与单位 | 脚本 + 人 |
| I | 数值复算表齐全:幻灯片上每个带单位的数都能找到出处,单参数贯穿 | 脚本 + 人 |
| J | 坐标系一致:轴标签/刻度/图注/正文量名同一套,recast 说明了每一跳 | 脚本 + 人 |
| K | 公式最小集:LHS 不重复、式里的量在图上指得到(正文页)、操作词有定义式(上限默认不设,核心步骤一条不许跳) | 脚本 + 人 |
| L | 页码齐、结构合规(S1 一页一条 P、S2 正文顺序、S3 calc 占比 ≥ 50%、条件页在前、错例 ≤1 页、动画 ≤3 且不重复、末页是 calc/pitfall,没有结论页) | 脚本 + 人 |
| M | 无例题/自测页;体积与图是数据驱动生成 | 脚本 + 人 |
| N | 公式是 `<math>` 里的 Presentation MathML、结构成层(mi/mn/mo/msub/msup/mfrac/msqrt);字形内嵌(`@font-face` + `url(data:font/woff2)`)、数学字体只挂 `math` / `.formula .expr` / `ol.axioms .eq`;`<math>` 字符全在 DeckMath、`<mtext>` 全在 DeckText;**下标只用 `<msub>`(`<sub>` 与 `_` 都不许)**;**真分式是 `<mfrac>`、量纲斜杠(mA/cm²、mV/dec)保留 `/`(C12)**;**块级元素不倾斜**(表格横线两端 |Δy| ≤ 1px) | 脚本 + 人 |
| O | 折叠块展开后仍在一页内:`shoot_deck.py` 无「展开后溢出」;复算表单独成页;打印页数 == 幻灯片页数 | 脚本 + 人 |
| **M2** | **公理清单:每条带 [定义]/[定律]/[经验事实] 之一、无禁用标签、A 节内无近似、无未被任何 P 引用的冗余公理** | 脚本 + 人 |
| **N** | **每条 P 的推导首步依据命中 A 编号 / 定义;全文无「由式/由上可知/显然/易得/已知结论」;推导里至少一次 A 编号;P 号连号** | 脚本 + 人 |
| **O** | **孤儿符号为 0:calc 页每个 `<var data-sym>` 都能追到某条 P / A 的式子或起点读数;每条 P 的 `data-used-in` 指向的 calc 页真的引用了它** | 脚本 + 人 |
| **P** | **页面无元话语:标题 / lead / 正文里没有「开讲前 / 本文档 / 为了讲清楚 / 后面会 / 本节只」** | 脚本 + 人 |
| **Q** | **P 段无定义重述:每条 P 删掉后听众会失去一个可算的中间量;不是 A 的复述、不是三步空转** | 脚本 + 人 |
| **R** | **A 节无目标量、无互推、标签正确(约定 vs 经验事实);每条 A 的 `data-used-in` 页真的引用它** | 脚本 + 人 |
| **S** | **删页后页码与 `data-used-in` / `data-uses` 全部重排,没有指向已删页的编号** | 脚本 + 人 |
逐条细则见 `references/checklist.md`。「文件写完」不算交付。
## 为什么上次跑很久(以及怎么不重演)
慢的不是知识点本身,而是**契约返工**与**大文件反复重写**:
| 慢在哪 | 怎么省 |
|---|---|
| 手写契约属性,漏一个就报错,报错就整页重写 | 先跑 `scripts/scaffold.py`,契约一次生成 |
| 每页几百个坐标点写进 SVG,单文件 150KB+,改一次重写一次 | 曲线存数据数组,用渲染函数生成;改数只改数组 |
| 闸门 2、3 各等一轮 | 合并:outline + 坐标表 + 公理表 + 公式预备表 + 正文公式表一次给全 |
| 逐页截图(10 页渲染两遍) | 只出整份 PDF + 3 张抽查 |
| 每改一页就跑一次校验 | 只在「一页画完」和「交付前」各跑一次 |
| docx 转换 + 来回校对 | 已取消:推导折叠进 HTML |
## 禁止
- 定义 → 公式 → 意义 → 应用 → 小结 四段式
- 每页「标题 + 3 个 bullet」
- 「谢谢观看」「欢迎提问」页
- 例题页、自测题、「你学到了什么」
- 单独产 docx(推导已折叠进 HTML)
- 装饰性大图与渐变 hero
- 跳步直接给公式;页面正文里铺推导
- 编造数值
- 只给源码不给截图
- 换坐标只改曲线不改标签(或只改标签不改刻度、图注、正文)
- 把移项后的同一关系再编一个式号
- 一页一个错例(错例只占 1 页)
- 线性图上说「变平 / 偏离直线」
- 起点页就下结论(那是后面几页才证出来的事)
- 页码只写进 HTML 而没做视口缩放(小窗口下直接出屏)
- 推导只写「定义 / 代数」两行就收尾(这是最常见的「公式没讲清」)
- 推导里解释符号(「其中 j 为电流密度」)
- 用「由式 (N) 得」代替推理
- 另起一页写结论 / 小结 / 总结
- 公式排在系统字体里(没有 `var(--math)`),或用 `E_eq` 这种编程写法当页面对下标
- 公式退回 `.mth` / `.scr` 定位 span、`<sub>`/`<sup>` 平铺、或整条塞进一个 `<mtext>`(不是 MathML 就没有结构)
- 引 MathJax / KaTeX / MathML polyfill / CDN,或用图片、SVG 充当公式
- 公式外的正文里留 Unicode 上下标(`x²`、`η⁻¹`、`log₁₀`):写 `$…$` 或让 `subs()` 自动转
- 复算表/长推导与图挤在同一页,展开后被 `overflow:hidden` 裁掉下半截
- 把上千个坐标点逐点写进 `points`
- 把推论写进公理清单(Tafel 方程、Nernst 极限电流这类有推导来源的式子必须先证明)
- 从「图上读得到的量」或「教科书结论」起步推导
- 用「由式」「由上可知」「显然」「易得」跳步
- 把近似写进公理清单(「η 较大时可略还原项」);公理未被任何 P 引用
- 把预备段写成目录页 /「本章公式一览」
- 预备段里解释符号;预备段放动画、高亮带、滑块
- 为凑页数给换算步立页(换算步可以压进「依据」列)
- 用「式 (P2)」混写两套号(正文引用预备式只写「P2」)
- 为让新 deck 过而删掉既有 error 规则、或把新校验降级成 warn
- 幻灯片页面上写元话语(「开讲前先钉死五条」「本文档不引入其他假设」「为了讲清楚…」)
- 把定义 / 约定 / 纯换算式包成 P 页(定义不推导;删掉它听众照样能读)
- 把终点量写进公理清单(`b ≡ 直线斜率` 是判断结果,不是公理)
- A 条目之间互推(A 的 RHS 以另一条 A 的 LHS 开头)
- 删页后不重排 `data-used-in` / `data-uses` / 页码 `N / M`
Pliki w paczce (19)
- LICENSE 1 KB
- README.md 7 KB
- SKILL.md 52 KB
- references/anti-patterns.md 28 KB
- references/checklist.md 15 KB
- references/deck-contract.md 29 KB
- scripts/check_deck.py 121 KB
- scripts/get_pandoc.sh 2 KB
- scripts/make_mathfont.py 4 KB
- scripts/mathrender.py 25 KB
- scripts/md2docx.py 4 KB
- scripts/scaffold.py 30 KB
- scripts/assets/mathfont.b64 99 KB
- scripts/assets/mathfont.css 100 KB
- scripts/assets/mathfont.woff2 75 KB
- tests/smoke.sh 43 KB
- tests/fixtures/rebuild.py 7 KB
- tests/fixtures/tafel-deck-公式推导.md 1 KB
- tests/fixtures/tafel-deck.html 244 KB
Wersje
W bazie nie ma innych skilli o nazwie knowledge-point-slides.
Migawka bazy z 13.11.2026 · wersja paczki d5d37bc3653b (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.