学科复习讲义生成器

把一门学科的高考内容，做成一系列结构固定、风格统一的单文件 HTML 讲义（五色提示框 + 可折叠练习 + 可打印）。

核心教学立场：讲清"为什么"而不是罗列结论——每个结论都要能从材料/原理推出来，每个易错点都要说清错在哪、为什么错。

已交付的十四个学科系列（可作新学科模板）

★ 初中社会册的独有经验：① 三科合卷（地理+历史+道法），分册按"学科 × 时期"切；
② 必须按新教材核对（2024 秋起起始年级先行替换，2027 中考是新教材首届）；
③ 一律不配图——真题图拿不到且区域图涉国界合规，统一走「诚实图注」路线；
④ 每册固定 10 章（比 9 章多一个"易错点清单"独立章），10 册之间可逐章对照。见「初中社会系列」一节。

★ 科学册的独有经验（对其他"无题库"学科通用）：
① {{SVG:key|图注}} 自绘配图机制（与 {{FIG:}} 位图并存）；
② SVG 里 marker 的 id 必须逐图唯一（8 张图共用 id="ar" → 体检报 id 重复）；
③ 官方评析里的"分类式表述"直接当骨架（2025 浙江科学把实验探究题分成六种能力）。
见「科学系列」一节。

★ 政治册是本技能最完整的一套（8 册全完成，含 1 本“方法论册”）：见「政治系列」一节。★ 地理册的两个独有经验：① 不需要 MathJax（公式用纯文本即可）；② 真题几乎全带图，
引用时必须改成 【原题配有××图】，否则 validate_html.py 会报配图 FAIL。见「地理系列」一节。
它的两条独特经验对所有文科册通用：① 把官方答案拆成可复用的“答题骨架”；② 写教材定位前必须核对现行目录。

★★★ 2026-09-23 的四条「铁律」（见「关键约定」一节的详细版；做任何册次前先确认已生效）：

另有两处校验器误报已修（同类病：按字面匹配、没看语义上下文）：
- check_all.py 第 ② 项 → 改为看 <details> 的内容（含 .q / .stem 才算缺陷）；
第 ⑩ 项 → 正确答案是 收紧为"后面跟问号"；第 ⑫ 项 → 放过"前X册…后Y册"的整册划分句。
- 通用教训：只打印、不判定，等于没查；校验规则跨"文档类型"复用前，先跑一遍看有没有误报；
修"漏了几个词"要顺势改成"不再依赖手写"，否则只是把下次踩坑推迟。

★ 修完的成效：地理 9 册 + 全目录 58 册，check_all.py 15 项全部通过（修复前 46/58）。

★ 两套"深度风格"，按学生水平选：

• 减繁版（学生基础薄弱）：每章 = 1 个核心方法 + 1 个例析 + 1 个"练一练"（答案折叠）；自测固定 12 项。
• 提高版（学生基础较好）：每章 = 核心考点表 + 方法(为什么) + 真题例析(逐项分析 + 一句话判据) + 练一练 + ★提高板块（史料实证 / 历史解释 / 学科高阶能力）。

何时使用

• 用户要求整理某学科、某章节的知识点
• 用户要求延续已有系列制作新一册（如"请继续第七册"）
• 用户要求为薄弱学生制作复习材料、讲义、知识点梳理
• 用户抱怨已有材料"公式太多背不下来""看不懂推导过程"
• 用户指定了某个省份的考生（必须先判断该科是否自主命题，见「第 0.5 步」）

工作流程

第 0 步：确认范围（仅首次或信息不足时）

用 AskUserQuestion 确认两件事，一次问完：

1. 交付格式 —— HTML 网页版（推荐，公式渲染好、可打印）/ Word / Markdown
2. 内容深度 —— 知识梳理 + 推导 + 典型例题（推荐）/ 只做知识梳理 + 推导 / 再加真题演练

如果用户已经在延续某个系列，跳过此步，直接沿用该系列已确定的格式与深度。

第 0.5 步：确定分册方案（新学科必做）

先问清两件事（用 AskUserQuestion，一次问完）：

1. 考生是哪个省的？该科是否自主命题？（决定素材来源，见第 0.6 步）
2. 学生基础如何？（决定用"减繁版"还是"提高版"）

再确定"按什么分册"。分册依据有四种，按学科特点选：

★ 判断方法：先 ls 一遍素材目录。
如果素材按"模块"分了文件（如语文的 文言文阅读.jsonl），就按模块分册；
如果素材只有 选择题.jsonl + 解答题.jsonl（如历史），就必须按内容（时期/专题）分册。

分册数参考：7 ~ 9 册。太少则单册过厚，太多则素材不足。
建议最后 1 ~ 2 册留给"解题方法"（如历史的选择题方法、综合题与小论文），
把前几册的史实/知识转化为"得分能力"——这是学生最需要的，也最容易做得出彩。

第 0.6 步：获取素材（最容易踩坑的一步）

★★ 最重要的原则：本地题库不一定有你要的卷子。先确认，再动手。

① 先看本地题库有什么：
   ls _refs/gaokao/dataset/<学科>/          # 看有哪些年份、哪些卷别
   find _refs/gaokao/dataset/<学科> -path "*<省份>*"   # 找该省卷

② 如果本地没有该省卷 → 必须联网找：
   WebSearch  "<省> <年份> <科目> 真题 试题 答案"
   WebFetch   抓 21cnjy（zy.21cnjy.com）—— 可直接拿到完整真题 + 评分细则

实测的站点可用性（2026-09 验证）：

★★ 2026-09-22 实测的重要结论：真题源正在快速收窄。
做新学科/新省份时，不要假设"上次能抓的站点这次还能抓"——
先花 2 分钟逐站验证一遍（打开一个具体文档页，看能否看到题干），再决定素材策略。
实测结果：7 个商业站点全部拦截，只剩省考试院官网可用。
→ 因此"自拟题 + 标注示例，非真题"正在从"退路"变成"主路"，要提前接受这个前提。

★ 官方"命题评析"是最有价值的免费资源——省考试院每年发布，写明"命题特点、素养目标、第 N 题考查什么"。
它是"针对该省优化"的最佳依据，比真题本身还重要。

★ 命题评析里往往直接给出可复用的骨架。实测（浙江中考科学 2025）：
评析把"实验探究题"明确分成六种能力——① 基本实验技能 ② 变量控制 ③ 方案设计
④ 数据分析 ⑤ 预测现象（画图）⑥ 解释现象，并逐条点名对应题号。
这种"官方自己给出的分类"直接拿来当讲义骨架，比自拟的分类权威得多。
读评析时要专门找这类"分类式表述"。

★ 保存为素材文件：_refs/eng_mat/<学科>_<省>卷_<年>-<月>.txt，供后续各册共用。

没有真题的板块怎么办？ 两条路（历史写作册的教训）：
1. 做 "方法-only"（如语文写作册——全库无作文素材，就只讲方法 + 自撰示范范文）；
2. 从原始文本目录里挖（如英语听力——结构化库里没有，但 raw-papers/**/*.txt 里有听力原文）。

★ 无论哪条路，自撰的示范材料必须标注"（示范，非真题）"——这是诚实性要求，不是可选项。

★ 真题确实拿不到时，还有一条"讲考情不引题干"的路：
用官方评析里点名的题号 + 情境 + 考查点做 ch0 考情分析与 ch8 真题精讲
（讲"考什么""怎么考"，不逐字引题干）。这样既真实、又不违反诚实性。

第 1 步：搭建文件骨架

复制本技能的骨架资产，拼成一个完整的 HTML 文件：

assets/skeleton-head.html   # 从 <!DOCTYPE html> 到 <main class="body">
assets/skeleton-tail.html   # 从 </main> 到文件结尾

将两段拼接，中间填入正文。然后替换骨架里的占位内容：

• <title> 中的「第N册 章节名」
• 封面 .cover h1 里的册次与章节名
• 封面 .cover .sub 的一句定位描述
• 封面 .cover .meta 里的「核心主线」与「建议课时」
• 目录 <nav class="toc"> 中的 8 个条目（锚点 #ch0 ~ #ch7）

骨架里已包含完整的 CSS（含 @media print）和 MathJax 配置，不要修改。

第 2 步：撰写正文

先读 references/writing-principles.md，它规定了：

• 8 章的固定结构与每章职责
• 五色提示框的用途与写作要求
• 六条硬性写作原则（公式必推、推导链、跨册呼应、一句话判据、例题带验算、反例要具体）
• 技术约定（MathJax 定界符、禁用 \hline 等）

写作时严格按该文件的规范执行。

可用组件（class 名固定）：

第 3 步：校验结构与内容（不可跳过）

python scripts/validate_html.py <生成的文件.html>     # 结构层 + 内容层
python scripts/check_macros.py <生成的文件.html>      # 公式宏是否都被 MathJax 支持
python scripts/verify_render.py <生成的文件.html>     # 渲染层（用无头浏览器 dump DOM）
python scripts/check_html_static.py <生成的文件.html> # 渲染层备用方案（浏览器不可用时）

结构校验（必须全部通过，输出 OK）：

• <div> 嵌套深度末尾归零、无负深度、各 <h2> 处深度恒为 1
• table / ol / ul / nav 标签配对
• 是否残留 \hline、是否误用 $ 作公式定界符
• 公式里有没有没转义的 < —— 这是最隐蔽的一类事故（详见下）

为什么必须用脚本而不是数标签个数：漏写一个 </div> 时，<div> 和 </div> 的总数仍然可能相等，但嵌套会整体错位，导致后面所有章节的布局错乱。只有逐行追踪深度才能发现。

渲染层校验（不可跳过）：

结构校验查不出"文本被浏览器吃掉"的问题。公式里若出现没转义的 <，例如
\(x_1-t<x_1<x_1+t\)，浏览器会把它当成标签起始、一路吞到 > 为止——
公式不渲染、句子残缺，但 <div> 总数依然平衡。

python scripts/verify_render.py            # 扫描当前目录所有 *.html

它用 Chrome/Edge 无头模式 dump 出真实 DOM，做两件事：

1. 文本完整性比对：把源文件与 DOM 的"可见文本"按中文句末标点逐段比对。
   任何被吞的句子都会以"缺失片段"的形式暴露出来——这是最直接的判定依据。
   同时比对五色提示框数量与数学定界符配对情况。
2. 畸形标签扫描：DOM 里出现白名单外、且不以 mjx- 开头的标签名，
   说明有裸 < 被浏览器解析成了标签。

必须全部 OK。

> ★ 无头模式挂起的两个原因与解法（已内置到脚本里）：
>
> - --headless=new 在部分 Windows 机器上会挂起（Abnormal renderer termination，
> 或超时无任何输出）。脚本默认用旧模式 --headless，失败才回退新模式。
> - 讲义引了 MathJax CDN。网络不通时 Chrome 会一直等，表现为"无头模式挂起"。
> 脚本默认加 --host-resolver-rules=MAP * 0.0.0.0，把域名解析指向黑洞，
> 让 CDN 请求"快速失败"，dump 就能秒回（实测 57 秒完成，原先无限挂起）。
> 副作用是 MathJax 不渲染，所以此时不能用 mjx-container 判断渲染是否成功——
> 只判断"文本没被吞"。需要确认真的渲染了，加 --online 跑一次。
> - 每次换一个临时 --user-data-dir，避免上次残留 profile 锁导致启动失败。

> 浏览器不可用时（无 Chrome/Edge）：改用 check_html_static.py。
> 它不启动浏览器，改为静态扫描，覆盖同样的失败模式：
> 定界符是否成对（注意排除 \\[6pt] 里的 \[）、裸 <、公式区域内的 <、
> 侧边栏与目录的锚点是否都能找到对应 id、提示框 class 是否合法。
> 局限：不能确认"MathJax 真的渲染了"——这一点要另外人工抽查或等浏览器可用时补跑。

公式宏校验（不可跳过）：

从 LaTeX 真题源码抄公式时，很容易把源码里的自定义宏一并抄进来
（如 \bs 表示向量、\i 表示虚数单位、\e 表示自然底数）。
MathJax 不认识它们，会原样渲染成红色源码——结构校验、DOM 扫描都发现不了。

python scripts/check_macros.py            # 扫描当前目录所有 *.html

它把公式区域内所有 \cmd 抽出来，与 mathjax_commands.txt（从 MathJax 包提取的1513 个命令名）比对。必须全部 OK。

修法二选一：换成标准写法（\bs a → \mathbf{a}、\i → \mathrm{i}），
或在 MathJax 配置里加 macros 段定义它们。详见写作规范第 13 条。

真题原文逐词比对（有真题的册次不可跳过）：

出处对、答案对，原文仍可能被悄悄改写——只比答案查不出来。

python scripts/check_exam_transcript.py --db <database.json> --html <讲义.html> --targets <targets.tsv>

它把讲义里的题干与数据库原句做同样的归一化（标点、撇号字形、空标记）后逐字比对，
不一致时定位第一个不同的字符。详见写作规范第 14、16 条。

内容校验（validate_html.py 同时输出两类提示）：

• [内容告警] —— 必须处理。覆盖四类真实出现过的缺陷：
• 使用超纲记号（叉积求法向量、\binom）
• 例题里残留试错过程（"不行，……调整：……"）
• 公式区域内未转义的 <
• [待确认] —— 需人工判断。主要是"第 N 章"交叉引用是否写清了册次，以及 MathJax CDN 是否加了加载失败兜底。

内容告警的处理方式见 references/writing-principles.md 第七节「常见缺陷检查清单」。

若校验失败，按脚本提示的行号定位并修复，然后重新运行直到没有 FAIL 和内容告警。

第 3.5 步：往已有讲义里注入公共资源时，脚本必须幂等

给多册统一加导航、加兜底脚本这类"批量注入"操作，注入脚本必须写成幂等的：
先删掉旧的同名块，再插入新的；且删除用的正则要能匹配已经注入过的形态。

否则脚本每跑一次就多堆一份，曾出现过每册末尾堆了 14 份相同的侧栏滚动脚本（14 个 scroll 监听器）的情况。

自查方法：注入脚本跑完后立刻再跑一遍，确认第二次运行时改动数为 0；
并统计关键块（侧栏脚本、@media print{.sidenav…}）的出现次数，应当恰好为 1。

第 4 步：交付

用 present_files 展示生成的文件。如果用户在做系列，把已有的其他册次一并展示，便于对照。

在回复里简要说明：本册的推导亮点、用到的教学手法、校验结果。

关键约定

★★★ 铁律一：每道题必须自带完整「材料 + 图注」，不能只留设问

这是用户实际报过的问题（2026-09-23，地理第 09 册）：
> "很多题目缺少了原题的主要题干，只有问题的那一小问。"

学生看到「从下垫面角度，解释甲地每年 11 月至次年 5 月多大风的原因」，
却不知道「甲地」在哪、是什么情境——题目等于作废。

硬性要求：

1. <div class="quote"> 里必须先写材料，再写设问。材料一 / 材料二 分条写全，
   不得压缩、不得只留与设问相关的一句。
2. 原题配了图的，必须在材料里写出图注，形如 【图 1 为××略图；图 2 为××统计图】。
   否则答案里出现「图 3 中①、②、③」「呈 ▲ 走向」时，读者无从对应。
3. 一题多问时，把其余小问也列出来（可标注「见第 N 章」），让学生看到完整的设问组合；
   只截取自己讲的那一小问，会让人以为原题就这么点内容。
4. 同一大题的多个小问被拆到不同章节讲时，每个小节都要重写完整材料——
   讲义是"可跳读"的参考书，读者可能直接翻到第 5 章，不能指望他记得第 2 章的材料。

交付前必做的一次扫描（30 行脚本，能一次抓出所有"只有设问没有材料"的块）：

import io, re
t = io.open(f, encoding='utf-8').read()
t = re.sub(r'<aside class="sidenav".*?</aside>', '', t, flags=re.S)
for m in re.finditer(r'<div class="quote">(.*?)</div>', t, re.S):
    txt = re.sub(r'<[^>]+>', '', m.group(1))
    if '材料' not in txt and '题目' not in txt:      # ← 缺材料
        print('缺材料：', re.sub(r'\s+', ' ', txt)[:80])

★ 为什么这类缺陷最容易漏：它不影响任何自动校验——结构层、静态层、渲染层全绿，
字数统计也正常（设问本身是完整的句子）。只有人（或上面这个扫描）能发现。

★★★ 铁律二：新增册次后，必须回扫全系列的「册数表述」

给一个系列补册（如地理从 8 册补到 9 册）时，前几册里"全系列共 N 册"的说法会集体过时，
而它们所在的册次你根本没碰过——这是最容易漏的一类错。

实测漏点（2026-09-23 加地理第 09 册后扫出来的）：

回扫命令（30 秒）：

# 在项目根跑，把"这/前/后N册""全系列N册""第N册"全部列出来人工过一遍
grep -oE '[这前后]?[一二三四五六七八九十]册[^<]{0,40}' 高考<学科>重点章节梳理-*.html

★ 更省事的做法：check_all.py 第 ⑬ 项（总册数自洽）已能自动报出
「全系列共 N 册，但文中出现「M 册」」——加册后先跑一次 check_all.py，按它的提示改。

★ 踩坑提醒：在非本册视角的句子里写"前 N 册"会被第 ⑫ 项（册序自洽）误报
（例：第 08 册里写"把前八册的要素组装成答案"，那是第 9 册的视角）。
规避办法：直接写明确册号——「第 1~8 册」而不是「前八册」。
★ 2026-09-23 实测：英语 4 册 + 历史 08 也踩了同一处，全都改成了明确册号
（"前六册语法在写作里的用法" → "第 1~6 册语法在写作里的用法"）。
写新册次时从一开始就用「第 N~M 册」，不要写「前N册」——省掉一轮返工。

★★★ 铁律三：每一个 build_*_common.py 都必须并进侧栏注入

事故（2026-09-23，真实发生）：给历史 02/07/08 补完材料后重建，三册的左侧导航整块消失——
因为 build_his_common.py 没有并进 add_sidenav（当时只有 build_wk_common.py 有）。
更隐蔽的是：build 的输出里连"侧栏 N 条"都不打印，跑完看起来一切正常。

本项目的四个组装器，必须全部改到位（缺一个就会在重建那一系列时静默丢导航）：

# 加在 `html = head + "\n" + body + "\n" + tail` 之后
if SKILL_SCRIPTS not in sys.path:
    sys.path.insert(0, SKILL_SCRIPTS)
import add_sidenav
html, n_nav = add_sidenav.build(html)
assert n_nav > 0, "侧栏条目为 0 —— add_sidenav 没生效，产物不完整"

# ★ 打印里带上侧栏条数——这样"跑完 build 一眼就能看出导航在不在"
print("已生成 %s（%d 行，%d 字节，侧栏 %d 条）" % (out_name, ..., n_nav))

★ 别忘了 import sys：build_common.py / build_zh_common.py / build_his_common.py
原本只 import 了 io / os / re，直接加 sys.path 会 NameError。

★ 重建任何册次后必做的一次核对（10 秒）：

grep -c 'aside class="sidenav"' 高考<学科>重点章节梳理-*.html   # 应全为 1

★★★ 铁律四：公式白名单必须以 MathJax 包提取表为准，不能手写

事故（2026-09-23）：数学 8 册全部报 公式命令不在白名单：\bigl、\bigr、\tag、\checkmark…。
查证后发现：check_math_syntax.py 用的是文件内手写的 KNOWN 集合，而旁边就有
mathjax_commands.txt（1512 条，从 MathJax 包本体提取）没被使用。
被误报的 \bigl \bigr \tag \checkmark \middle \not \lnot \complement \subsetneqq \nRightarrow
全是 MathJax 3 原生支持的命令。

正确做法（已落地）：

KNOWN = set(""" …手写常用集… """.split())
_MJ_TXT = os.path.join(os.path.dirname(os.path.abspath(__file__)), "mathjax_commands.txt")
if os.path.exists(_MJ_TXT):
    with io.open(_MJ_TXT, encoding="utf-8") as _f:
        KNOWN |= {ln.strip() for ln in _f if ln.strip()}      # 1512 条兜底

★ 这条技能里已经写过一次（"手写白名单一定会漏，第一版就漏了 \langle \rangle \lfloor"），
但当时只补了手写表、没有换成读文件 → 同一个坑又踩了一次。
教训：修"漏了几个词"要顺势改成"不再依赖手写"，否则只是把下一次踩坑推迟。

★★ 改题目材料时的幂等陷阱（2026-09-23 实测连插两次）

给已有题目补材料时，插入点是「设问那一行之前」。于是：

• 旧写法 if old not in t → 永远为真（设问那一行始终在）→ 每跑一次就多插一份。
• 正确写法：判据要看插入后的整体——if new in t: skip（new = 材料 + old）。

if new in t:                       # ✅ 幂等
    print("跳过（已补过）")
    continue
assert t.count(old) == 1           # 顺带保证唯一
t = t.replace(old, new, 1)

已经插重复了怎么救：M + M → M 循环替换（材料块是逐字节相同的），
再核对关键短语出现次数（如 论坛邀请函要点 应为 1）。

项目目录布局（脚本依赖此约定）

<项目根>/
├── 高考<学科>重点章节梳理-NN-<册名>.html      # 成品（输出在这里）
└── _refs/
    ├── gaokao/dataset/<学科>/**/*.jsonl        # 素材源（题库）
    ├── eng_mat/<学科>_<模块>.txt                # 提取出的素材
    ├── extract_<学科>.py                        # 素材提取器
    ├── build_<学科>_common.py                   # 通用组装器
    └── build_<学科>NN/                          # 每册一个目录
        ├── build.py                             # 该册的组装入口
        └── p1_ch0-1.html … p5_ch8.html          # 正文片段

build_*_common.py 会从"片段目录"上溯两级找输出位置——所以片段目录必须放在 <项目>/_refs/ 下。

文件名

沿用系列命名：高考<学科>重点章节梳理-NN-<册名>.html（NN 为两位册次号）。
新系列时按此规则类推，并在回复中告知用户命名规则。

系列连贯性

用户延续系列时，必须先读取已有册次，确认：

• 章节结构是否仍为 9 章（ch0 ~ ch8）
• 五色框用法是否一致
• 是否有可以建立"跨册呼应"的知识点

保持结构与风格完全一致，只替换内容。跨册呼应关系记录在 references/writing-principles.md 的「跨册呼应」一节，做新册次时优先在其中找可复用的对照点。

教学手法清单（做新册次时逐条过一遍）

理科通用：

1. 推导链 —— 全册公式串成一条链，在 ch7 用 steps 呈现
2. 一句话判据 —— 凡"该用 A 还是 B"的地方都给一句自问的话
3. 退化检验 —— 用特殊情况验记公式（如令参数取 0 或相等）
4. 具体反例 —— 讲"为什么必须满足条件 X"时给可想象的场景
5. 双路径验算 —— 例题用两种方法算同一个量互相对照

文科通用：

6. 从材料提答案 —— 每章至少练一道"从材料里读出来"的题（浙江卷官方明确的命题取向）
7. 逐项比对表 —— 选择题用"选项 / 判断 / 理由"三列表，逐项说清"错在哪"
8. 评分细则原版引用 —— 有官方评分细则的题，直接引用（"一点一分""抠词"最能说明问题）
9. 提高板块 —— 每章末设"★提高"板块，覆盖该科的高阶能力（史料实证 / 历史解释 / 唯物史观 / 时空观念）
10. 跨册呼应 —— 把结构相同的知识点放在一起讲（如"器物—制度—思想"三级台阶）

新学科上手清单（做一门全新学科时逐条过）

□ 1. 问清：哪个省的考生？该科是否自主命题？学生基础如何？
□ 2. ls 素材目录，判断"按什么分册"（模块 / 分期 / 板块 / 专题）
□ 3. 本地没有该省卷 → 联网找（21cnjy + 省考试院命题评析）
□ 4. 定分册方案（7~9 册，最后 1~2 册留给"解题方法"）
     ★ 文科系列（语文/历史/政治/地理）**方法册已是标配**——政治第 8 册、地理第 9 册都是
       「综合题解题方法」。**判据**：前几册讲的全是"考什么"，学生仍答不出题 → 缺"怎么答"。
       方法册**不需要新抓素材**：把已有册次的真题按"题型"重新切一遍即可。
□ 5. 选骨架：
     · 有公式 → skeleton-head.html（MathJax）
     · 语言类 → skeleton-head-en.html
     · 文科（无公式）→ skeleton-head-zh.html（可离线）
     · 与语文同类的文科 → 直接复用语文骨架，用 build_*_common.py 里 replace 学科名
     · 政治 / 地理等文科 → 复用语文骨架 + `build_wk_common.py`（传 `subject="政治"`）
□ 6. 写一个 extract_<学科>.py（读 jsonl → 输出素材 txt）
□ 7. 写一个 build_<学科>_common.py（读骨架 + 替换占位符 + 生成目录）
□ 8. 逐册写片段（p1~pN，**每片 ≤ 15KB**；一册内容厚时按“章”拆片），每写完一册立刻校验：
     build（**已自动含侧栏注入**）→ validate_html → check_html_static → verify_render
     （★ 2026-09-23 起 `add_sidenav` 已并进 `build_*_common.py`；旧的"build 后再跑 add_sidenav"写法已废弃）
□ 8.5 **扫一遍"只有设问、没有材料"的题块**（铁律一）——三层校验查不出这类缺陷：
     ```python
     for m in re.finditer(r'<div class="quote">(.*?)</div>', t, re.S):
         if '材料' not in re.sub(r'<[^>]+>','',m.group(1)): print('缺材料', m.start())
     ```
     凡缺材料/缺图注的，回素材原文补齐后再重建。
□ 9. 三层全绿 + 跑一次 `check_all.py`（15 项）+ **配图渲成 PNG 逐张目视核对**，才算完成
□ 10. **本系列若有既有册次**：加册后回扫全系列的"册数表述"（铁律二），
      按 `check_all.py` 第 ⑬ 项的提示改
□ 11. **重建任何册次后**核对侧栏没丢：`grep -c 'aside class="sidenav"' <file>` 应为 1（铁律三）
□ 12. **新建组装器时**：把 `add_sidenav` 并进 build（铁律三）、`import sys`；
      公式白名单从 `mathjax_commands.txt` 读，不要手写（铁律四）

★ 单次 Write 一个碎片文件，不要一次写多个——碎片超过约 15KB 且伴随长文字回复时，
响应会因输出长度上限被截断（本技能开发过程中连续踩过两次）。

★ 校验脚本的"误报"要处理，不要绕过：

英语系列（同一技能，不同骨架）

本技能已扩展支持英语系列（高考英语重点章节梳理-NN-*.html）。与数学版的差异：

英语册的推荐结构（9 章）：ch0 写在前面 → ch1~ch5/6 知识点 → ch6 易错点清单 → ch7 知识地图与自测 → ch8 真题精讲。

已完成的英语 8 册（可作后续册次的模板）

八册的跨册呼应闭环：

第一册 句子怎么拆
  ├→ 第二册 谓语怎么变（时态/语态/一致）
  ├→ 第三册 从句怎么认（三步判断法）
  ├→ 第四册 非谓语怎么用（数谓语→定成分→判主被动）
  ├→ 第五册 词怎么变（构词法/词性转换）
  ├→ 第六册 文章怎么读（定位/同义替换/语篇衔接）
  ├→ 第七册 语篇里怎么判断（完形五线索 + 语法填空判断树）
  └→ 第八册 文章怎么写（审题四问 + 双线构思 + 语言升级）

★ 写作时要在每一册的 ch0 和 ch7 里写明这条链的位置——让学生知道"这一册在整个体系里解决什么问题"。

★ 听力素材只存在于原始文本目录（重要）

结构化库里没有听力字段。 structured/database.json 里名为"2020 听力试题及答案"的
那一条，所有字段都是 null——是个空壳。

听力材料只存在于 raw-papers/**/*.txt（原始试卷文本） 里：

grep -l "听力原文" _refs/eng_db/raw-papers/*/*.txt    # 55 个文件
# 其中 47 套含完整听力原文（Text 1~10）+ 试题 + 答案

★ 通用教训：结构化库不等于"全部数据"。原始文本目录里往往藏着结构化时被丢弃的板块
（听力、语音、附录等）。做新册次前，先 ls 一遍原始目录、grep 几个关键词，
确认"结构化库缺了什么"。

没有音频怎么做听力册？ 本册的编排思路（可复用）：
语音规则（音标 + 例词）、听前预测（纯技巧）、场景词汇（按词频统计排）、
数字读法（规则）、真题听力稿（当阅读材料做"预测 → 定位 → 核对"）。
并在 ch0 用一张表说明"每一章为什么不需要音频"。

英语册素材提取的三个坑（都踩过）

1. 不能信 type 字段。它是自动标注的，大面积误标；而且 2010—2015 年的单选卷，
   整段的 type 被复用到每个小题上，会混进大量无关题目。
   → 改用答案形态筛选（如"从句题 = 答案是一个连接词"）。
2. 答案形如 A/B/C/D 的是混进来的听力或阅读选择题（它们没有 options 字段，
   躲过了第一层过滤）→ 加 re.fullmatch(r"[A-Da-d]", answer) 过滤。
3. 数据源里的引号和撇号极不规范（缺开引号、缺闭引号、直/弯撇号混用）
   → 逐词比对时必须先做"引号归一"和"撇号归一"。

★ 校验规则跨文档类型要检查误报

validate_html.py 的"思考痕迹"规则用 Hmm|Let me 做匹配——这是从数学讲义
里总结出来的。用到英语讲义上时大面积误报：

• W: Hmm. Could be interesting. —— 听力原文里的语气词
• Let me change that… —— 教学表格里的"改动信号词"

修法：要求这两个词紧跟中文字符才算痕迹
（Hmm\s*[，。！？、]\s*[\u4e00-\u9fa5]、Let me\s+[\u4e00-\u9fa5]）——
真实的思考痕迹长这样："Hmm，让我想想" / "Let me 重新算一遍"。

★ 通用原则：校验规则一旦跨"文档类型"复用，先跑一遍看有没有误报正当内容。

英语册的"推导链"体现在三处（对应数学的公式推导链）：
1. 构词链——一个词根/词缀长出几十个词
2. 句型生成链——五种基本句型长出所有句子
3. 从句降级——主句如何一步步变成从句（反过来就是"长难句拆解"）

例句块的写法：

<div class="eg-en">
  <div class="en">He <b>gave</b> <u>me</u> a book.</div>
  <div class="cn">他给了我一本书。</div>
  <span class="src">2020 新课标Ⅰ卷 · 语法填空</span>
</div>

句子成分标注的写法：

<div class="syn">
  <span class="s">The man</span> <span class="v">told</span> <span class="o">me</span>
  <span class="m">that he had been waiting</span>.
</div>
<div class="syn-legend">
  <span class="s">主语</span><span class="v">谓语</span><span class="o">宾语</span><span class="m">修饰/补充</span>
</div>

语文系列（同一技能，第三套骨架）

本技能已扩展支持语文系列（高考语文重点章节梳理-NN-*.html）。语文版不含 MathJax（无公式，可完全离线）。

语文版的"减繁"风格（教师反馈后的定型，必守）

初版语文册被老师评价"整理得挺好，就是有点繁杂，应加强练习"。定型后的风格：

• 每章 = 1 个核心方法 + 1 个例析 + 1 个"练一练"（不再堆知识点）
• "练一练"用可折叠块，题干可见、答案收起：
  html <details class="quiz"> <summary>查看答案</summary> <div class="ans"> <span class="rubric"><b>①</b> ……</span> </div> </details>
• 自测清单固定 12 项，分三组：会做 / 会判 / 会答（替代冗长的 24~34 项）
• ch7 = 知识地图 + 自测；ch8 = 真题精讲 + 刷题区（刷题答案同样用 details.quiz 折叠）

语文册的章节规划（7 册）

★ 语文素材源的三个坑（都踩过）

1. question 字段把"材料 + 题干 + 选项"混在一起，必须自己切分：
   切分点用 re.search(r"\n\s*(?=\d{1,2}\s*[.．]\s*\S)", q)。
2. question 里混有页码数字（如 …突破口。6B.不育系… 的 6），引用时必须删掉。
3. 全库没有作文素材（检索"自拟标题""不少于800字""写一篇"命中 0）。
   → 第 7 册《写作》只能做 "方法-only + 自撰示范范文"，材料与范文都要明确标注"示范（非真题）"，
   不能冒充真题。这是诚实性要求，不是可选项。

★ 通用教训：先确认"素材库里有没有这一类题"，再决定这一册的形态。
没有真题的板块，要么做"方法-only"，要么从原始文本目录里挖（见英语听力册的教训）。

★ 骨架文件的两个致命坑（语文册踩过，其他册同样适用）

1. 绝不用 cat >> 往骨架文件追加 CSS。
   骨架文件（skeleton-head-*.html）末尾已经是 <header class="cover">——
   位于 </style> 和 </head> 之后。用 cat >> 追加的 CSS 会落进 <body>，
   在页面上直接显示成一段乱码文字（用户会截图报"页面里面有错误的文字"）。
   → 正确做法：用脚本在 </style> 之前插入，或改 make_zh_skeleton.py 重新生成骨架。
2. build.py 的 meta 里，含中文引号的标题必须用单引号包裹 Python 字符串。
   例："写在前面：考的是"语言基本功"" 会因内层英文直引号提前结束字符串 → SyntaxError。
   → 写成 '写在前面：考的是"语言基本功"'。

语文册的构建与校验（一条命令）

python _refs/build_zhNN/build.py                     # 组装（读骨架 + 替换占位符 + 生成目录）
python add_sidenav.py "高考语文重点章节梳理-NN-*.html"   # 注入侧边导航（幂等）
python scripts/validate_html.py  <file>              # 结构层
python scripts/check_html_static.py <file>           # 静态层（语文无公式，不需要 check_macros）
python scripts/verify_render.py  <file>              # 渲染层

validate_html.py 会提示"第 N 章"交叉引用"待确认"——语文册正文大量引用本册其他章
（"见第 2 章"），这是正常的；本册内引用写"第 N 章"、跨册才写"第 X 册"。

新增资产（语文版专用）

• assets/skeleton-head-zh.html / assets/skeleton-tail-zh.html —— 语文版骨架（无 MathJax）
• _refs/make_zh_skeleton.py —— 从数学骨架生成语文骨架（剥离 MathJax、换文案、追加语文 CSS）
• _refs/build_zh_common.py —— 语文册通用组装器（build_volume(parts, here, meta, out_name)）
• _refs/extract_zh.py —— 语文素材提取器（python extract_zh.py <模块> → _refs/eng_mat/ZH_<模块>.txt）
• _refs/ZH_WRITING_SPEC.md —— 语文册撰写规范（9 条硬性规则）

历史系列（第四套变体：复用语文骨架）

历史与语文同属"无公式的文科"，因此直接复用语文版骨架，不新增骨架文件。

# _refs/build_his_common.py 的关键一行：
head = head.replace("语文", "历史")   # 先把骨架里的「语文」换成「历史」，再替换占位符

★ 分册依据：历史没有"模块"，要按"通史分期"分册

本地 dataset 的历史只有「选择题.jsonl」和「解答题.jsonl」两类，不像语文有"文言文/古诗/默写"等模块。
所以分册必须靠题目内容（时期），不能靠文件分类：

8 册方案（已确认）：① 中国古代史·政治制度 ② 中国古代史·经济文化 ③ 中国近代史
④ 中国现代史 ⑤ 世界古代与近代史 ⑥ 世界现代史 ⑦ 选择题解题方法 ⑧ 综合题与小论文

★★ 关键教训：地方卷必须联网找，本地 dataset 里没有

本地 dataset 只有全国卷（2010—2024），没有任何省份卷。当用户是某省考生时：

1. 先确认该省是否自主命题。如浙江：语数英用新课标Ⅰ卷，但选考科目（含历史）是浙江自主命题。
2. 联网找真题：21cnjy（zy.21cnjy.com）可以直接抓取完整真题（题干 + 选项 + 答案 + 评分细则）；
   doc88 / book118 / 百度文库需登录或付费，抓不到（实测）。
3. 抓官方命题评析：省教育考试院官网（如 zjzs.net）发布的"选考科目试题评析"是权威且免费的，
   含命题特点、素养目标、具体题号考查点——这是"针对该省优化"的最佳依据。
4. 保存为素材文件：_refs/eng_mat/HIS_<省>卷_<年>-<月>.txt，供后续各册共用。

★ 通用原则：做地方卷讲义前，先问"这是哪个省、该科是否自主命题"，再决定素材来源。
不要默认用本地 dataset（那可能根本不是该省的卷子）。

★ 历史册的"提高版"风格（用户要求：学生基础好，要进阶）

与语文册的"基础薄弱·减繁版"不同，历史册面向基础较好的学生，每章结构为：

核心考点表（史实结构化，简洁）
  + 方法(proof)：讲"为什么这样判断"
  + 真题例析(eg)：浙江真题 + 逐项分析 + 一句话判据
  + 练一练(details.quiz，答案折叠)
  + ★ 提高板块：史料实证 / 历史解释 / 答题模板

每册的"提高板块"要有意识地覆盖浙江卷的四种核心能力：
史料实证（辨析史料价值与局限）、历史解释（比较/评价/辩证）、唯物史观（用生产力等概念解释）、时空观念。

★ 历史册必须体现的四个浙江卷特点

1. 乡土考点几乎每年必考：良渚文化、浙江安吉白茶苗扶贫、"千万工程"、"浙里办"、浙东学派陈亮叶适。
2. 史学理论高频：史料实证、历史解释、唯物史观、时空观念（不是背史实，是考思维方法）。
3. 漫画/图表/表格题高频：几乎每套都有，考"读图提取信息"。
4. 小论文是固定压轴（12 分）：2026.1 的评分规则最细——结构分 6（主题 3 + 结构 3）+ 论证分 6（3 个史实论证），
   且主题有"分档表"（战争破坏文化 3 分 / 文化遗产保护 3 分 / 战争辩证影响 1 分 / 战争推动文化交流 0 分）。
   讲"小论文"时直接引用这套规则。

政治系列（第五套变体：复用语文骨架，按教材分册）

分册依据：按教材（必修 + 选择性必修，8 册）—— ✅ 已全部完成

① 中国特色社会主义（必修1）　② 经济与社会（必修2）　③ 政治与法治（必修3）　④ 哲学与文化（必修4）
⑤ 当代国际政治与经济（选必1）　⑥ 法律与生活（选必2）　⑦ 逻辑与思维（选必3）　⑧ 综合题解题方法

> ★ 上表是 2026-09-23 补齐 5 处教材缺口后的版本（补前 01/03/06 册分别少 1.8k/2.0k/1.2k 字）。
> 补缺口的方法与"教材覆盖度核对"流程见本节末尾。

政治册的章节映射（9 章 / ch0~ch8）

ch0 写在前面（教材单元表 + 命题规律表 + 学法建议）
ch1 ~ ch6 知识点（按教材单元合并，不必一课一章）
ch7 知识地图与自测（自测固定 12 项：会记 / 会辨 / 会答；补内容后计数要同步改）
ch8 真题精讲 + 刷题区（2~4 道浙江真题完整精讲 + 2 道自拟示范题 + 提分要点 + 时间分配）

★★ 第 8 册是“方法论册”——本系列首创，值得复用

前七册讲“考什么”，第八册讲“怎么答”。做法：

1. ch0 给试卷结构 + 五大题型一览表（题型 / 特征词 / 真题实例 / 对应章节）。
2. ch1 给“审题四步法：圈、定、标、配” + 答题四条规范（分点、原理在前材料在后、术语准确、该分段就分段）。
3. ch2~ch6 一章一种题型，每种给“特征词 → 答题骨架 → 真题例析 → 练一练”。
4. ch7 放两张独有表：① 五类题型骨架汇总表；② 跨册呼应总表（结构相同的知识出现在哪几册）。
5. ch8 用当年全套综合题做收官演练（逐题标出题型 + 模块 + 骨架）。

★ 这套结构的价值：把前七册散落的答题公式汇总成可查的表。做新学科时，
只要该学科册数 ≥5，都值得补一本“解题方法册”。

★★ 政治册最核心的教学手法：把官方答案拆成“答题骨架”

政治册的价值不在“罗列知识点”，而在把官方答案翻译成可复用的句子结构。
做法：从官方答案里抽出固定句式，做成 tmpl 模板框，再配一张“答案句 ↔ 原理”对照表。

已提炼的骨架（做新册次时继续积累）：

★ 政治册的“材料信号词表”（审题用，比背原理快）

每章末列一张“材料出现什么词 → 用哪条原理”的对照表，这是学生最买账的部分。例：

• “体制改革 / 经营权调整 / 承包权变动” → 生产关系要适应生产力状况
• “修改法律 / 机构调整 / 制度完善” → 上层建筑要适应经济基础状况
• “多件事里挑重点” → 主次矛盾；“一件事里看主流” → 矛盾主次方面
• “由坏变好 / 由劣势变优势” → 矛盾双方在一定条件下相互转化

★ 素材获取：浙江选考政治，本地 dataset 里没有

本地 dataset 只有全国卷；浙江政治选考必须联网抓（21cnjy ✅，省考试院 zjzs.net 的官方命题评析 ✅）。
已抓到的必修4 真题（存 POL_浙江卷_补充_必修4.txt）：

★★ 教材定位必须先查证再写。 例：“辩证否定观”在 2019 版必修4 的位置是
第三课第二框「世界是永恒发展的」（P34），不是旧版教材的“第十课 创新意识与社会进步”（该课已删）。
写“某知识点在第几课第几框”之前，一定先联网核对现行教材目录——写错会让整册的可信度崩塌。

已核对的现行教材目录（2026-09 实测，做后续册次可直接引用）：

★ 核对教材目录首选“电子课本网”类站点（haoduoyun.cc / kebenwang.cn）——它们的目录页是
纯文本、结构完整；dzkbw.com 的目录页实测会返回乱码或诗词导航，gaozhong360.com 的目录页已 404。

★ 易错点：选必1 是 7 课（不是 9 课）；“辩证否定”在必修4 第三课第二框（不是旧版第十课）。

★ 跨册引用的统一写法：第 X 册（教材名）第 N 章

政治是 8 册系列，跨册呼应很多。统一写成 第 X 册（教材名）第 N 章，例如
“第 4 册（必修4）第 3 章”。只写“必修4 第 3 章”会与系列其他册的“第 4 册第 3 章”写法冲突，
validate_html.py 的“待确认”告警也会提示。本册内引用仍写“第 N 章”。

★ 册数厚时按“章”拆片段文件

政治一册覆盖教材 2~3 个单元，比语文/历史单册厚。片段文件按章拆
（p1=ch0+ch1、p2=ch2、p3=ch3……），每片控制在 15KB 以内，避免单次 Write 被截断。
第 4 册《哲学与文化》用了 8 个片段（ch0~ch8），成品 2043 行 / 145 KB / 86 个提示框；
第 5~8 册各用 6 个片段。

政治册的构建与校验（一条命令）

python _refs/build_polNN/build.py                    # 组装（★ 已内联 add_sidenav，跑完即成品）
python "$S/validate_html.py"     <file>              # 结构层 + 内容层
python "$S/check_html_static.py" <file>              # 静态层（政治无公式，不需要 check_macros）
python "$S/verify_render.py"     <file>              # 渲染层
python "$S/check_all.py"                             # 整体体检（★ 会自动识别"文科档"）

> ★ 2026-09-23 起 add_sidenav 已并进 build_wk_common.py，不再需要单独跑一步。
> 见科学系列的教训：后置步骤漏跑会让侧栏整块消失，而校验器只把「导航=0」当信息打印、不报错。

★★★ 校验规则必须按「文档类型」分档——否则文科册会被大面积误报

check_all.py 最初是给初中数学写的，规则里写死了那套约定
（<div class="quiz"> 外框 + <div class="q"> 题干 + <span class="key">N. 答案</span>）。
用到政治等文科册上，8 册全部 FAIL，但其中没有一条是真问题：

✅ 修法（已合入 check_all.py）：开头做一次 profile 判定，之后按档走不同规则。

profile = "czmath" if '<div class="q">' in body else "wk"

• 文科档 ②：改为查「<details class="quiz"> 里除了 <summary> 和 .ans 还有没有别的内容」——
  这才真正等价于"题干是否被折叠"。
• 文科档 ③：改为查「每个答案块是否有非空内容」（有题无答才是真风险）。
• 文科档 ⑩：省略号降级为提示（note），不当 FAIL。

★★ 通用原则：任何校验脚本跨"文档类型"复用前，先跑一遍看有没有误报正当内容。
一个"每册都报错、但都不是真问题"的门禁，很快就会被人整体忽略——那等于没有门禁。

★★ 第 ⑫ 项「视角判定」要同时认阿拉伯数字与中文数字

政治册正文写「读第四册《哲学与文化》。前三册讲"制度"……」——这是站在第四册的视角说的，完全正确。
但旧的视角判定正则写的是 第 (\d+) 册（只认阿拉伯数字 + 空格），匹配不到「第四册」，
于是「前三册」被误判成"本册是第 03 册却写前三册"。

✅ 修法：两种写法都认。

mref  = re.findall(r"第\s*(\d+)\s*册", ctx)
mref += [CN[x] for x in re.findall(r"第\s*([一二三四五六七八九十])\s*册", ctx)]

★ 通用：中文语境里"册/章/课/条"的编号两种数字混用极常见，任何按编号做的判定都要两边都覆盖。

★★★ 幂等判据必须按「修改类型」分档（两种方向各踩一次）

批量改片段时，修改分两类，幂等判据恰好相反：

def needs_work(mode, t, old, new):
    if mode == "append": return new not in t
    if mode == "dedup":  return old in t

★ 通用原则：判据要问「这处修改是否还需要做」，而不是「某个串在不在」。
两条经验：① 每个 JOB 显式带 mode 字段；② 改完立刻再跑一遍，第二次必须输出"无变化"。

★★ 半角引号 / 全角引号在同一批内容里会混用

政治 03 册的自测清单写的是半角 "十六字"，而同册正文写的是全角 “…”。
按全角去匹配 → 两处静默漏插（脚本报 FAIL 才发现）。
★ 做法：先 probe 出原文的 repr，再写匹配串；不要凭"看着像全角"就下手。

★★ 从成品里抽小节做预览图：同名标题在侧栏和目录里也各出现一次

做「目视核对」时要抽取某个小节拼成预览页。用 t.find(title) 会先命中侧栏（侧栏在 <body> 之后、
<header> 之前），于是 t.rfind("<h3", 0, i) 返回 -1、切片得到空串——整页渲出来是空白。

✅ 正确做法：用「标签 + 标题」整体正则匹配。

m0 = re.search(r'<h3[^>]*>' + re.escape(title) + r'</h3>', t)

★ 通用：凡是"按标题文本定位"，都要意识到同一份文档里标题会出现 2~3 次
（侧栏 / 目录 / 正文），必须用标签把"正文那一处"框住。

★★★ 政治册的「教材覆盖度核对」——本系列必须逐课核对

按教材分册不代表覆盖完整。2026-09-23 用两层扫描（关键词表 → 同义表述复查）查出 5 处真缺口：

★ 第二层扫描（同义表述复查）不可省：第一层扫「抽象与具体」命中 0，但「思维抽象/思维具体/感性具体」
各有 14~17 次——是同一内容的另一种说法，属假阳性。反之「社会主义改造」命中 0 但「三大改造」有 7 次，
也是假阳性。真缺口要靠同义词表复查才能定。

★ 补缺口的做法（爆炸半径最小）：新内容一律作为 h3 插进既有章节，不新开 h2；
插在「★ 提高板块」之前，插入后把后续 h3 编号整体顺延；同时同步更新该册的
知识地图节点 / 自测清单（含"N 项"的计数）/ build.py 的 toc。补完必须重建，不要在成品 HTML 上直接改。

★ 政治册的密度基线（本次实测，供后续册次参考）：
必修1/2/3 三册合计 13~15k 字，选必册 18~19k 字，必修4（哲学与文化）27k 字。
单章 1,000~2,900 字属正常（"考点表 + 方法 + 例析 + 练一练 + 误区"就是一个完整教学单元）；
低于 900 字要重点核查（本次 03 册 ch6 只有 897 字，核查后发现正是缺了第九课）。

★★★ 真题必须带「原题材料」——只给设问是最常见的交付缺陷

用户反馈（2026-09-23）：「很多题目缺少了原题的主要题干，只有问题的那一小问」。
审计后确认，8 册里共有 15 处真题块只给了设问、没给材料。这是本技能最容易复发的一类缺陷，
因为写讲义时注意力都在"答题骨架"上，很容易把"材料"当成读者已经知道的东西跳过去。

最典型的失败形态（08 册《综合题解题方法》ch8「真题总演练」）：

> 演练一 · 第 1 题（1）概括归纳类（必修3，9 分）
> 设问： 结合材料一，运用《政治与法治》的相关知识，分析我国系统推进人工智能的发展与治理的实践智慧。
> 题型判断｜材料层次　材料明确给了三层：战略层面 / 价值观层面 / 规范层面
> 答题骨架｜一层对一点：战略层面 → 坚持党的领导……

表格里描述了材料（"材料明确给了三层"），却从没给出材料——读者根本不知道"战略层面"里写了什么。
这是最隐蔽的一种缺失：它看起来"信息很全"，但关键内容全靠读者自己猜。

判据（写每一道真题精讲时逐条过）：
1. 引用了一道真题 → 必须能见到 ① 材料原文，或 ② 完整题干（含 （　） 与四个选项）。
2. 设问里写了「结合材料」「运用材料一/材料二」→ 对应材料必须出现在同一块内，且在设问之前（阅读顺序：材料 → 设问）。
3. 材料照抄素材文件（_refs/eng_mat/POL_*.txt），不改写、不缩略、不臆造。
原本标「节选」的，补全后要把「节选」二字去掉。
4. 查不到完整题干的，就诚实标注，例如 08 册对 2025.1 第 28 题的处理：
"本题的完整题干与参考答案未在本次可获取的公开来源中查到，故只引用官方评析原文与题号信息，不臆造材料与答案。"
—— 不要为了"填满"而编材料。

可复用的审计脚本（两个都要跑）：
- audit_stem_final.py：凡引用「20XX 年 X 月浙江…第 N 题」的块，必须能见到 ① 材料 / ② 完整题干 / ③ ≥120 字叙述段。
这一条最能抓住"只有设问"。
- audit_stem_jh.py：凡出现「结合材料」的块，同块必须有材料（覆盖未标年份的自拟题）。

★★ 审计判据要锚在"引用了真题"上，不要锚在"出现了『设问』二字"上。
初版判据用后者，噪音极大——正文里"这类设问的答案骨架""设问写'中国如何…'，按四层答"等大量行文都会被误报，
一次跑出 40+ 条，真问题只有 15 条。判据越贴近"用户能看见的缺陷"，信噪比越高。

★ 补材料的幂等做法（patch_stems.py）：按行操作，before / replace / delete 三种动作；
幂等判据用「锚点行之前 8 行内是否已含本次载荷的特征串」。
replace 型会把锚点行本身吃掉（如去掉"节选"、把"……"补全），所以锚点找不到时还要回退查
「载荷特征串是否已在全文里」——否则重跑会误报 FAIL。

初中数学系列（第六套变体：复用数学骨架 + 注入折叠练习样式）

初中数学讲义 = 复用数学版骨架（MathJax），并在 </style> 之前注入 details.quiz 等
折叠练习样式——数学骨架本身没有这些组件（只有语文骨架有）。

★ 初中数学的六个额外要点

1. 必须注入折叠练习 CSS。 数学骨架里没有 details.quiz / .term / .wrong / .right，
   直接写 <details class="quiz"> 会渲染成浏览器默认样式、与整体风格不搭。
   → 把语文骨架（skeleton-head-zh.html 第 420~440 行附近）的 quiz CSS 复制到
   build_czmath_common.py 的 EXTRA_CSS 里，注入到 </style> 之前（幂等：先正则删旧块再加）。
2. add_sidenav.py 要求 h2 形如 <h2 id="chN"><span class="num">N</span>标题</h2>，
   且正则 <h2 id="ch(\d)"> 里 ch 编号只能是单个数字 —— 所以册内章数不要超过 10（ch0~ch9）。
3. 初中数学无本地题库。 例题以"自拟典型题"为主，必须在出处行标注"示例，非真题"；
   引用搜到的卷子时要写全出处（如"2025 浙江中考模拟卷（省统一命题卷）· 第 17 题"）。
   不要凭记忆写中考真题——无法核对，且容易出错（写作规范第 9 条）。
   实测：doc88 / 百度文库 / 道客巴巴 / 豆丁需登录或付费，抓不到；只能拿到搜索摘要里的题干片段。
4. ★ "练一练"的答案必须先把题独立算一遍再写。 初中数学册里 details.quiz 的答案是折叠的，
   校验脚本查不出答案错没错。本次开发中连续出现 3 处"边写边算"导致的答案错误 / 残留试错痕迹
   （如分式方程答案写错、rubric 里留下"重算：……"），都是在同一段落里边推演边写文件造成的。
   → 先算、再写；写完用 grep -n "重算\|注意代入\|正确答案" <html> 自查一遍。
5. ★ 公式语法必须单独查（check_math_syntax.py，已并入 check_all.py 第 ⑭ 项）。
   宏名打错时 MathJax 会把未定义命令渲染成红色源码，而：
   - 结构校验查不出（标签是平衡的）；
   - 宏校验也查不出（check_macros.py 查的是"宏有没有定义"，而这里是"宏名拼错了"）。
   → 属于静默故障，必须专门查：花括号配平 + \left/\right 配对 + 命令在白名单内。
   实测全 10 册共 50 种命令，逐一核对全部合法。
   写这个检查踩的两个坑：① \\left 的正则会匹配 \leftrightarrow 的前 4 个字母
   → 必须用负向先行断言 \\left(?![A-Za-z])；② 白名单要足够全——
   \iff \leftrightarrow \longrightarrow \Longrightarrow \xrightarrow
\underbrace \odot \bar \circ \pi 都是合法命令，漏一个就全量误报（第一版漏了 8 个，报了 130 处假问题）。
6. ★ 每条答案必须带题号，格式固定为 <span class="key">N. 答案</span>（N 与题干 <span class="stem">N.</span> 一致）。
   用户报过这个 bug：04~10 册的答案只写了答案值、没写题号，全部堆在一起，
   学生得数位置去对应第几题（而 01~03 册是写了的——所以是"写漏了"，不是"设计如此"）。
   - 答案块结构必须严格是 <p><span class="key">N. …</span></p> + <span class="rubric">…</span>，
   不要出现"<p> 里除 key 还有别的内容"或"key 不在 <p> 里"的变体，
   否则悬挂缩进（见下）会对不齐；
   - 配套 CSS 要加悬挂缩进（已写进 build_czmath_common.py 的 EXTRA_CSS）：
   padding-left:1.7em; text-indent:-1.7em 让题号挂在左侧、多行答案的续行与首行正文对齐。
   不加的话续行会顶到左边缘、看着像新条目——这正是用户说的"全部放在一起了"的观感来源；
   - 批量补号用 scripts/fix_answer_numbers.py（幂等，直接改 _refs/build_cz*/p*.html 片段，
   这样重建不会丢）。它按 quiz 块处理：数出该块题干序号 → 逐个重写 key 的题号。
   两个必须防的坑：① 答案本身以数字开头的不少（概率答案 0.2、2.6 小时），
   判据必须是「数字 + . + 至少一个空白」才算题号——0.2 的点后是数字，不算；
   ② CSS 注释里的 <div class="quiz"> 示例会被误当成练习块，
   只处理不含 <style> 的片段即可天然规避（若直接处理成品 HTML，必须先剥 <style>）；
   - 体检第 ⑮ 项会兜底查（题干/答案数量是否相等 + 每条答案的题号是否与题干一致）。
   做反向测试验证过：缺号、错号、数量不等三种故障都能准确报警。

★★ 内容补漏：逐章密度体检法（做完整套后必跑一遍）

一套讲义做完、校验全绿之后，内容仍然可能"厚薄不均"——校验只管结构和正确性，不管密度。
用户第二次要求"再检查一遍，看哪些章节还需要补充"时，用这两个扫描：

扫描 ① 知识点覆盖扫描：对全部册次做关键词全文检索，列出每个知识点的出现次数，
挑出"覆盖数 = 0"或"≤2"的。用教材目录当关键词表（浙教版 33 章逐个检索）。
实测扫出 10 处缺口：无理数估算、有效数字、精确度、命题/逆命题、真假命题、反证法、
换元法、数字问题、配套问题、直角梯形。

扫描 ② 逐章密度统计（最有效的一招）：按 <h2> 切块，统计每章的
h3 数 / 例题数 / 题量 / 五色框数 / 正文字数，横向对比同册各章。

t = re.sub(r'<aside class="sidenav".*?</aside>', '', t, flags=re.S)
t = re.sub(r'<style.*?</style>', '', t, flags=re.S)
t = re.sub(r'<script.*?</script>', '', t, flags=re.S)
parts = re.split(r'(<h2 id="ch\d+">.*?</h2>)', t)   # 奇数下标=标题，偶数下标=正文

一眼就能看出哪一章偏薄。实测 10 册 ch5 只有 2816 字，而同册其他核心章 5300~9500 ——
字数只有一半，例题数也少，是最该补的。补完后 5553 字，与其他章持平。
另外查出 10 册 ch4 的"核心方法表"里列了 6 类存在性问题，其中"相似三角形"没有任何例题——
这种"表格承诺了但正文没兑现"的缺口也要补。

判断标准（供参考）：同一册内，核心章的正文 4000~9500 字较合适；
低于 3000 字基本是内容不足；练习数 每章 3~5 题，为 0 就是明显缺口。
（纯清单/索引类章节，如"易错点清单""方法索引"，1000~2000 字属正常。）

★★ 往已有小节里插新内容：编号顺延必须同步做

补漏时往往要把新小节插在 ★ 提高板块 之前。如果新小节编号 1.5、原 ★ 块也是 1.5，就撞号了。

做法：补丁脚本里给每个 JOB 带一组 renames，插入完成后做整串替换：

JOBS.append((rel, anchor, block,
             [('<h3>1.5 ★ 提高板块：三边关系与化简</h3>',
               '<h3>1.6 ★ 提高板块：三边关系与化简</h3>')],
             "before"))

要点：
- 用完整 <h3>…</h3> 整串做 old/new，不要用 1.5 这种片段（会误伤）；
- 重命名放在插入之后执行，这样新块自己的小节号不会被动到；
- 脚本加 mode 参数：before / after / append（append 用于"练一练放章末"）；
- 改完必须打印每个文件的 h3 列表核对编号连续，不能只信脚本返回的 OK。

★ 体检第 ⑩ 项（省略号）的判定要放宽

原来"出现 …… 就报错"，但 因为（依据）……所以（结论）…… 这种格式模板里的省略号是合法的。
新判据：同一行 ≥2 个 …… = 格式描述（合法）；只有 1 个才报错（多半是推导没写完）。

> 不过教学文本里含糊的省略号本来就不该用——本轮虽然放宽了检查，
> 同时还是把那 3 处改成了明确表述（"先写因为（后面跟依据），再写所以（后面跟结论）"）。
> 放宽检查是为了不误报，不是为了纵容含糊。

已交付的初中数学系列（浙教版 · 中考专题分册，10 册）

① 数与式 ② 方程与不等式 ③ 一次函数与反比例函数 ④ 二次函数 ⑤ 三角形与全等三角形
⑥ 四边形与相似三角形 ⑦ 圆与解直角三角形 ⑧ 统计与概率
⑨ 图形认识、变换与尺规作图 ⑩ 中考压轴题解题方法

> ★ 为什么是 10 册而不是 9 册：按"专题"分册会天然漏掉"不属于任何专题、但教材单独成章"的内容。
> 实测漏掉了四块：几何入门（线·角·相交线·平行线）、图形的对称与变换、尺规作图、投影与三视图，
> 合计约 13~15 分。补救方式是新增一册专册（⑨），而不是硬塞进现有册次。
> ⑨ 是基础册、⑩ 是方法册，方法册必须排在最后 —— 若先排了方法册再补基础册，
> 一定要把两者对调，否则"基础排在第 10、方法排在第 9"。

★★★ 改册次编号时，必须扫三类表述（踩过，漏改了 7 处）

只改显式册号是不够的。三类表述都要处理：

实测漏改的后果：第 10 册 ch0 写「前面八册」（应为九册）、
第 09 册写「前九册」（应为八册）、第 08 册写「下一册是《压轴题》」（其实下一册是图形认识册）、
第 10 册末尾「九册到这里全部结束了」（应为十册，且清单缺了 09 册）……
前后两轮用户各发现一次，共修了 11 处。

做法：
1. 对调目录名（mv build_cz09 _tmp && mv build_cz10 build_cz09 && mv _tmp build_cz10）；
2. 改两个 build.py 的 vol / out_name；
3. 用 \x00VOL9\x00 这类占位符把两册里的「第 09 册」↔「第 10 册」整体对调（避免二次替换）；
4. 扫一遍全系列的 前(面)?[一二三四五六七八九十]册 与 下一册，逐个核对；
5. 跑 check_all.py 第 ⑫⑬ 项自动查（⑫ 查"前面 N 册"，⑬ 查"总册数/这 N 册"）。

⑫ 项的规则：本册是第 NN 册 ⇒ 文中「前(面)N册」应等于 NN−1。
⑬ 项的规则：全系列共 N 册（= 目录里的 HTML 数）⇒「N 册就全部结束」「这 N 册」里的 N 应等于 N。

写这两个检查一共踩了三个坑（都已修）：
- 编号要从文件名 -(\d{2})- 里取——文件名没有"第 08 册"字样，
第一版写成匹配「第 (\d+) 册」导致永远匹配不到，检查形同虚设；
- 要加"视角判定"：08 册里写「第 10 册……把前面九册的工具串起来」是对的
（站在第 10 册的视角），别误报。判据：该词前 40 字内若出现「第 M 册」且 M = N+1，跳过；
- 「这一册」不是数量：第一版把 这([一二三四五六七八九十]+)册 也纳入检查，
结果 10 册全部报错——"这一册"是"本册"的意思，要排除 word == "一"。

册内结构（9 章）：

ch0 写在前面（三级台阶 + 三条学法建议 + 先破除 2 个常见误解）
ch1~ch5 知识点（每章：核心考点表 → 方法"讲为什么" → 例题(分步 + 必带验算 + 一句话判据)
                  → 练一练(答案折叠) → ★ 提高板块）
ch6 易错点清单（表格，15 条左右，每条写"易错点 / 正确做法"）
ch7 知识地图与自测（地图卡片 + 全册公式推导链 + 自测清单分"会算 / 会判 / 会变"三组）
ch8 中考题型精讲与刷题区（题型分布表 + 2 道精讲 + 提分要点 + 刷题区）

风格 = "基础 + 提高"综合版：既保留"减繁版"干净的方法讲解（每章一个核心方法、不堆知识点），
又带"提高版"的 ★ 板块（方法进阶 + 拓展技巧）。这是用户明确要求"两种都要"时的定型结构。

地理系列（第七套变体：复用语文骨架，按知识板块分册，9 册）

分册依据：按知识板块（9 册，前 5 册自然地理 + 第 6~8 册人文与安全 + 第 9 册解题方法）

① 地球运动与地图判读　② 大气运动与天气气候　③ 水循环与洋流　④ 地貌与地质
⑤ 自然环境整体性与差异性　⑥ 人口城市与交通　⑦ 农业工业与区域发展　⑧ 资源环境与国家安全
⑨ 综合题解题方法（✅ 2026-09-23 完成）

★ 地理的教材是必修1/必修2 + 选必1/2/3，但分册不能按教材（教材章节零碎、跨度大），
要按知识板块分——这是与政治册（按教材分册）最大的差异。

★ 方法册必须排在最后（第 9 册），因为它是"把前八册的要素组装成答案"的收口册。
判断要不要做方法册的判据：前八册讲的全是"考什么"，如果学生仍答不出题，
说明缺的正是"怎么答"——政治、历史、地理三个文科系列都做了方法册，这已是系列标配。

★★ 地理第 9 册《综合题解题方法》——方法册的可复用模板

★ 地理方法册的题型分类（按浙江卷真实设问归纳，不要自拟）：

★ 用量数据（写方法册的 ch0 时直接引）：两套卷 6 道综合题共 20 个小问，成因类占 11 个
——所以成因分析是绝对主力，八条高频成因骨架必须背熟。

★ 方法册的核心教学手法（三条）：
1. 审题四步法"圈、定、拆、配"——圈角度定边界、定题型定套路、拆要素定完整、配骨架定规范。
四步各管一件事，缺一步就丢一类分。
2. "数设问给了几个面"——设问写"有利和不利"就答两面，只写"优势"就只答一面。
这是条件评价类最容易被忽视的判据。
3. 把评分细则的"抠词"单独做成一张表（见下），这是学生最买账、也最容易提分的部分。

★★ 地理"抠词清单"（真题评分细则实录，方法册必收）

★ 一句话判据："地理阅卷是按词给分，不是按意思给分"——
所以术语必须背教材上的写法，不能用自己顺口的说法。

★★ 地理册最大的坑：真题几乎全部带图

validate_html.py 有一条"配图完整性"检查。地理引用的真题绝大多数配区域略图、剖面图、统计图，
照抄原文的"下图为……"会直接报 FAIL。

正确做法（写地理册的默认动作）：

1. 引用带图真题时，把"下图为……"改写为 【原题配有××图】，例如
   【原题配有某年 10 月两日内气旋移动路径图】。
2. 在该题末尾补一句 "本题需读取原题××图，讲义为纯文本形式，此处保留题干、答案与判据"——
   这既通过校验，也守住诚实性（不假装图在讲义里）。
3. 若题目本身可脱离图作答（如纯文字材料题），则不必加图注。

★ 注意 【原题配有××图】 里的"××图"不含"下图"字样，不会触发正则 r"如图|如下图|下图|右图|上图"。

★★ 地理真题图找不到——必须自绘 SVG（2026-09 实测结论）

用户明确要求"不要不配图"后，系统检索了所有可能来源，结论是地理真题图库不存在：

★★ 那位浙江地理一本通作者自己也写："真题配图：已获取原卷原图的 3 处采用官方原图，其余为据题述重绘的示意图。"
→ "据题重绘"是本领域的通行做法，不是偷懒。 做地理册时默认就走自绘路线，不要在这上面反复找图。

★★ 自绘 SVG 的工程化做法（可直接复用）

两个脚本，放在 _refs/：

• geo_figs.py —— 配图库。FIGURES = {key: svg_string} + get(key)。
  每张图自包含（自带 <defs> 箭头 marker），可离线、可打印。
• geo_inject_figs.py —— 幂等注入器：
  1. 在 </style> 之前插入 .fig svg 样式（起止标记界定，先删旧块再插新的）；
  2. 把正文里的 {{FIG:key}} 占位符替换为 <div class="fig">…SVG…<span class="cap">…</span></div>；
  3. 用题注覆盖 SVG 里占位的 <title> / aria-label（保证无障碍可读）。
  幂等原理：占位符替换后即消失，所以重复运行无变化（实测第二次输出"无变化"）。

★ 重要：因为占位符会被消耗，要更新图必须先重建（重新生成占位符）再注入——
直接对已注入的 HTML 重跑注入器是无效的。

★ marker id 的命名空间问题（2026-09-23 已在注入器里根治）：

geo_figs.py 的 _defs() 让每张图共用 id="ar" / arw / arm / arc——
单张图看没问题，多张图内联到同一页就成了重复 id（无效 HTML，check_all.py 第 ⑥ 项报 FAIL）。

根治办法：在注入器里按图名加后缀（已写进 geo_inject_figs.py 的 _rep）：

suffix = "-" + re.sub(r"[^A-Za-z0-9]", "", key)      # 如 "-g3_cycle" → "-g3cycle"
for mid in ("ar", "arw", "arm", "arc"):
    svg = svg.replace('id="%s"' % mid, 'id="%s%s"' % (mid, suffix))
    svg = svg.replace("url(#%s)" % mid, "url(#%s%s)" % (mid, suffix))

• 在注入器里改，一次修好所有册次；在图库里改，则要为 39 张图各写一份 _defs()。
• 已生成的旧册次用 _refs/fix_fig_ids.py 就地修（按图在页内的出现序号加 -fN 后缀，
  只动配图块内部，不重建、不碰骨架，幂等）：
  bash python _refs/fix_fig_ids.py 高考地理重点章节梳理-*.html
• ★ 旧册次里重复 id 视觉上无害（各图 marker 定义逐字节相同，浏览器取第一个也得到同样的颜色），
  所以这是"HTML 不合法"而非"看得见的错"——但 check_all.py 会一直报 FAIL，噪音会淹没真问题。

★ 通用：任何"每张图自带 <defs>"的 SVG 库都要注意 id 命名空间——
不只是 marker，还有 clipPath / linearGradient / mask / pattern。

★ 写完必跑配图自查（10 秒，抓"HTML 标签混入 SVG"与"未知标签"）：

allow = set('svg path g line circle ellipse rect polygon polyline text tspan defs use marker '
            'symbol desc switch view lineargradient radialgradient stop clippath mask pattern '
            'filter foreignobject animate title'.split())
for k in geo_figs.all_keys():
    s = geo_figs.get(k)
    for t in ('<sub>','<sup>','<strong>','<b>','<em>','<i>','<br>','<span>','<div>'):
        assert t not in s, ('HTML 标签混入 SVG', k, t)
    extra = {x.lower() for x in re.findall(r'<([a-zA-Z][a-zA-Z0-9]*)', s)} - allow
    assert not extra, ('未知标签', k, extra)
    # 顺带查盒子有没有超出画布
    for m in re.finditer(r'<rect x="(\d+)" y="(\d+)" width="(\d+)" height="(\d+)"', s):
        y, h = int(m.group(2)), int(m.group(4))
        assert y + h <= int(re.search(r'viewBox="0 0 (\d+) (\d+)"', s).group(2)), ('盒子超画布', k)

★★★ 合规红线：配图不画国界与海岸线

已加载 geo-map-compliance-guard：其"输出前合规自查"要求国界、台湾、南海诸岛等领土要素必须符合国家标准，不得错绘错标。

→ 地理册配图一律限定为：剖面图 / 模式图 / 流程图 / 受力图 / 统计图。
- 洋流图只画纬度线 + 环流箭头，不画海岸线（因此不构成"地图"，也不存在画错区域的风险）。
- 区域类真题（世界某区域、福建省、长江口、洞庭湖等）不重绘，保留 【原题配有××图】 的诚实说明。
- 需要定位信息时，用经纬度示意框 + 文字标注代替海岸线。

★★★ 配图必须"渲成图逐张目视核对"（本节最重要的一条）

结构校验 / DOM 校验 / 文本完整性校验，全都查不出"图画反了"。
地理图的很多要素——等压面凸凹、环流方向、方位关系——画反了照样"渲染成功"。

实测：两批共 36 张图里查出 6 处实质错误：

★★ 教训：地理图"看着像对"不等于对。必须渲成 PNG 逐张看——
尤其是"方向类"要素（凸凹、顺逆、升降、东西），画反了完全不影响渲染。

标准做法（务必执行）：

# 1) 生成"全图总览"预览页（用 io 直接拼 FIGURES 里的 SVG）
# 2) Chrome 无头截图 —— 注意 --screenshot 必须用**绝对 Windows 路径**，否则报 "系统找不到指定的路径"
"C:/Program Files/Google/Chrome/Application/chrome.exe" --headless --disable-gpu --no-sandbox \
  --hide-scrollbars --virtual-time-budget=6000 --window-size=760,4400 \
  --screenshot="D:/…/_figpreview.png" "file:///D:/…/_figpreview.html"
# 3) 用 PIL 纵向切成 2~3 段，逐段 Read 目视检查

★ 顺带一个已验证的坑：直连下载要用 curl --noproxy '*'。
本机代理 HTTP_PROXY=http://192.168.3.19:8080/ 需要认证，不带 --noproxy 会报
CONNECT tunnel failed, response 407；加 --noproxy '*' 后 raw.githubusercontent.com 直连返回 200。

★★★ 校验脚本的标签白名单有四份副本——改一处必须同步改四处

validate_html.py / verify_render.py / check_html_static.py 各自维护一份
HTML/SVG 标签白名单（都写着 svg path g line circle rect polygon polyline text tspan defs use marker symbol），
外加 sci_figs.py 自己的自查——合计 4 份。

第一次踩坑：三份白名单都漏了 ellipse。用椭圆画等高线闭合圈 / 等压线时，
三个脚本会一起把 <ellipse 误判为"裸 < 后跟字母"（会吞文本）而报 FAIL。

第二次踩坑（更隐蔽，2026-09-23 科学 09 册）：画 pH 色阶用了 <linearGradient>，
四份白名单都缺这个标签，于是又被误判成"裸 <"。

★★ 而真正隐蔽的是这一点：比对代码写的是

if m.group(1).lower() in HTML_TAGS:   # ← 比对前先 lower() 了

但白名单里补的条目写成了驼峰 linearGradient radialGradient clipPath foreignObject——
lower() 之后永远匹配不上小写的 lineargradient，
等于白名单里根本没有这四个条目，补了跟没补一样。

✅ 修法：四份白名单统一全小写，并补齐：

ellipse desc switch view lineargradient radialgradient stop clippath mask pattern filter foreignobject animate title

★ 通用教训（比"改四处"更本质）：
白名单 / 枚举 / 映射表的 key，必须和"比对时实际使用的形式"一致。
只要比对前做了 lower() / strip() / 归一化，白名单就必须是归一化后的形式；
否则条目静默失效，而且看起来像是"已经补过了"——这是最难发现的一类 bug。

排查手法：遇到"明明加了白名单还报错"，先打印
repr(被比对的值) 和 repr(白名单里的条目) 各看一遍，比盯代码快得多。

★ 另一条：这类"多脚本共享同一份常量"的设计，改一处必须同步改全部。
本轮就是先修了 validate_html.py，跑完仍 FAIL，才发现另两个脚本也各有一份。
画新类型的 SVG 元素（ellipse / 渐变 / clipPath 等）前，先确认四份白名单都包含它，且大小写一致。

★★★ SVG 里绝不能出现 HTML 标签——四层校验全查不出

<svg> 内部只认 SVG 元素。写化学 / 物理类配图时，很容易顺手用 <sub>（下标）、<sup>（上标）、
<strong>（加粗）——浏览器会直接丢弃该 <text> 里的全部文字，而
validate_html.py / check_html_static.py / verify_render.py 全都查不出：
标签本身在白名单里（sub/sup 是合法 HTML 标签），文本完整性校验只比"源文本 vs DOM 文本"的字数——
而这段字在两边都不存在（源文件里它是标签、渲染后它被丢了），所以校验"相等"。

实测：化学第 3 册 che_figs.py 初版有 6 处 <sub>/<sup>；第 9 册初版有 7 处 <strong>。

✅ 做法：化学式一律用 Unicode 下标 / 上标（H₂O、SO₄²⁻、Vₘ、Nₐ、10⁻³⁰）；
加粗用 _t(..., bold=True)；换行用两个 <text>。
⚠️ 注意 Unicode 里没有上标 q——写 K = [C]ᶜ·[D]ᵈ ÷（[A]ᵃ·[B]ᵇ） 时要避开 q（ᵃᵇᶜᵈᵉᶠᵍʰⁱʲᵏˡᵐⁿᵒᵖʳˢᵗᵘᵛʷˣʸᶻ 里没有 q）。

✅ 写完必跑自查（10 秒）：

import re, che_figs          # 或 geo_figs
allow = set('svg path g line circle ellipse rect polygon polyline text tspan defs use marker '
            'symbol desc switch view linearGradient radialGradient stop clipPath mask pattern '
            'filter foreignObject animate title'.split())
for k in che_figs.all_keys():
    s = che_figs.get(k)
    for t in ('<sub>', '<sup>', '<strong>', '<b>', '<em>', '<i>', '<br>', '<span>', '<div>'):
        assert t not in s, ('HTML 标签混入 SVG', k, t)
    extra = {x.lower() for x in re.findall(r'<([a-zA-Z][a-zA-Z0-9]*)', s)} - allow
    assert not extra, ('未知标签', k, extra)
print('OK')

★★ 手绘"表格型" SVG：行数一变就要重算盒子高度

卡片 / 表格式 SVG（<rect> 做盒子 + 逐行 <text>）最常见的 bug 是
最后一行溢出盒子、压到下一个盒子上。本轮化学册出现 4 次
（gch6_hydro 第 4 行、gch6_ksp 第 3 行、gch8_naoh 第 5 行、gch6_cons 文字横压）。

根因：盒子 height 是按"初版行数"估的；后来加了行或行距变大，忘了同步改 height。
自查公式：盒子底边 = y + height；最后一行文字底 ≈ 首行 y + (行数−1) × 行距 + 字号；
必须满足 最后一行文字底 + 8px ≤ 盒子底边。

★ 经验值：10px 字号配 22~24px 行距较安全；
盒子高度 ≈ 标题区(24) + 行数 × 行距 + 上下留白(20)。

★ 同一行里"标签 + 说明"两段文字，说明文字的 x 必须 ≥ 标签文字右边界 + 8px——
本轮 gch6_cons 就因为把说明放在 x=190 而标签长到 254px 处而横压。中文字宽 ≈ 字号 × 1.0，据此估算。

★ 幂等注入器的计数器必须在两个闭包之前定义一次

che_inject_figs.py 同时处理 {{FIG:key}}（SVG）与 {{IMG:key}}（base64 位图），
用一个 n = [0, 0] 分别计数。实测踩坑：n = [0, 0] 被写了两次，
第二次在 SVG 替换之后，导致 SVG 计数归零（图其实注入成功，只是日志显示 0）。

→ 计数器只在两个替换闭包之前定义一次；每次改注入器后，核对日志里的张数与正文
<div class="fig"> 的实际计数是否一致（out.count('<div class="fig')）。

★★ 逐张目视核对是唯一能查出"压字 / 难看"的手段

同地理册的结论：三层校验只保证"结构合法、文本不丢"，不保证"排版不压字"。
本轮化学 9 册共 73 张配图，逐张渲成 PNG 目视后查出并修正 5 处
（1 处文字压圆 + 1 处标签压曲线 + 3 处表格行溢出）。

已验证的流程：che_figs.py → 用 io.open 直接拼 _cN.html（每张图一个 <div class="w">）
→ Chrome 无头截图（--screenshot 必须用绝对 Windows 路径）→ PIL 按 450px 切段 → 逐段 Read。
每张图约 10 秒，值得做。

★★ 地理册"缺图"有两种——都要主动审计

做新册次时，用脚本审计"提到图但没有图"的位置，同时还要检查"讲机理的小节有没有图"：

实测：地理前 4 册初版只有 12 张图（且全是真题相关），审计后发现11 个"讲机理但没图"的小节，
补齐后 4 册共 23 张；第 5~8 册各配 2~4 张，全系列共 36 张。

★ 地理综合题的三个鲜明特点（讲义要写进去）

1. 一境多问：一个区域情境串起自然 + 人文 + 区域 + 国家安全。如 2026.1 第 28 题用"河套灌区"
   连考下垫面与大风、农业光照、湖泊污染物、工业产业链四个方向。
2. 角度限定：设问常写"从下垫面角度""从产业链角度""从锋面形成角度"——
   限定角度答偏了不给分。这是地理综合题最容易丢分的地方，讲义里要反复强调"先圈角度再动笔"。
3. 评分细则"抠词"（2026.1 实录）："绿色能源"不给分（要写"清洁能源"）；
   "植树造林"不给分（要写"植树种草"或"建草场"）；"减弱太阳辐射"不给分（要写"削弱"）；
   错别字"峡、磨、幅"不给分。→ 讲义里要把"必用术语"单独列出。

地理册的“答题骨架”（做新册次时继续积累）

★ 做新册次时继续往这两张表里加——方法册的价值就在于把散落的骨架汇成"可查的表"。

★ 地理册的“一句话判据”（判断类知识点，考试直接问自己）

地理册的构建与校验（一条命令）

python _refs/build_geoNN/build.py                    # 组装（★ 已内含侧栏注入）
python _refs/geo_inject_figs.py  "高考地理重点章节梳理-NN-*.html"   # 注入 SVG 配图（幂等）
python "$S/validate_html.py"     <file>              # 结构层 + 内容层（含配图检查）
python "$S/check_html_static.py" <file>              # 静态层（地理无公式，不需要 check_macros）
python "$S/verify_render.py"     <file>              # 渲染层
python "$S/check_all.py"                             # 整体体检（15 项，全目录扫）

★★★ 两个必须做的"产物链"整改（2026-09-23，影响全部文科册）

① add_sidenav 必须并进 build_*_common.py，不能作为"第二步"。

import sys
sys.path.insert(0, r"C:\Users\g12363\.unvbuddy\skills\study-guide-html\scripts")
import add_sidenav
html, n_nav = add_sidenav.build(html)
assert n_nav > 0, "侧栏条目为 0 —— add_sidenav 没生效，产物不完整"

为什么：实测事故——重建 8 册时只跑了 build.py，8 册的左侧导航整块消失；
更糟的是校验器一路"全绿"（check_html_static.py 明明算出 导航=0，
却只当信息打印、不报错），直到用户打开文件才发现。
⇒ 只打印、不判定，等于没查。 凡是能算出来的关键指标（导航条目数、配图数、锚点数）
都要有下界断言，而不是只在行末显示。

② check_all.py 第 ② 项（旧结构残留）必须看 <details> 的内容，不能只看标签名。

# ❌ 旧版：只要出现 <details class="quiz"> 就报错
legacy = len(re.findall(r'<details class="quiz">', body))

# ✅ 新版：只有 details 里真的装着题干才是缺陷
for m in re.finditer(r'<details class="quiz">(.*?)</details>', body, re.S):
    inner = m.group(1)
    if '<div class="q">' in inner or re.search(r'class="stem"', inner):
        legacy += 1

为什么：文科册（语文 / 历史 / 政治 / 地理）的通用写法是
「题干放在 <div class="quote"> 里（details 之外），<details class="quiz"> 只包答案」——
此时题干常显、不构成缺陷。旧版只匹配标签名，导致 20+ 册大面积误报。
★ 修正后要跑反向测试：构造一个"真把题干包进 details"的文件，确认仍能抓到（实测通过）。

★ 通用教训：校验规则一旦跨"文档类型"复用，先跑一遍看有没有误报正当内容。
一个会误报的门禁很快就会被忽略——误报比漏报更致命。

③ 第 ⑩ 项（草稿痕迹）里的 正确答案是 太宽，已收紧。

# ❌ 旧版：只要出现「正确答案是」就报草稿痕迹
r"重算[：:，,、]|正确答案是|让我重新|我(?:重新|搞混)|调整：|换个思路[：:]"

# ✅ 新版：只保留"作者在自问自答"的形态
r"重算[：:，,、]|正确答案是[^，。；」""]{0,10}[？?]|让我重新|我(?:重新|搞混)"
r"|调整：|换个思路[：:]|[？?]\s*不行"

为什么：「第 11 题问……，正确答案是"区位条件优越，便于区域联系与协作"」——
这是"真题呼应"段落里的标准写法，地理册 06、07 各被误伤 1 处。
只有「正确答案是 X？」（后面跟问号）才是作者在自我怀疑。
同时补上原始真实案例里的 ？不行（"取 X 为两点分布且 E(X)=3？不行，……"）。

④ 第 ⑫ 项（册序自洽）会把"整册划分句"误判成本册视角。

# 追加在"视角判定"之后：同一行同时出现「前X册」与「后Y册」→ 判为整册划分句，跳过
line = body[body.rfind("\n", 0, m.start()) + 1: body.find("\n", m.end())]
if re.search(r"后\s*[一二三四五六七八九十]\s*册", line):
    continue

为什么：「前五册是"自然地理"，后三册是"人文地理 + 国家安全"」——
这是对整个系列的划分，出现在哪一册都成立，与"本册是第几册"无关（地理第 01 册被误伤）。

★ 这两处（连同上面 ② 的 details 检查）都是同一类病：
规则按"标签/字面"匹配，而没有看"语义上下文"。
写校验规则时先问一句：这个字面形态，有没有一种完全正当的用法？ 有，就必须加限定。

★★ 从 GitHub 取素材：git clone 能用，curl 不能用（重要）

需要真实题目时，直接 clone 仓库，不要走 HTTP：

curl https://api.github.com/...        →  curl: (7) CONNECT tunnel failed, response 407  ❌
git clone --depth 1 https://github.com/<owner>/<repo>.git  →  成功  ✅

Git Bash 里 clone 到 /tmp/xxx 后，必须用 cygpath -w /tmp/xxx 转成 Windows 路径再交给 Python
（Python 不认 /tmp/...，会静默抽出 0 条）。

实测可用的初中数学题库（2026-09 验证）：

抽取脚本（放项目 _refs/ 下跑）：
extract_sxs.py <repo_root> <out.txt>、extract_sh_tex.py <test.tex> <outdir>。

★ 几何册的配图策略（手绘 SVG 成本很高，分两档）

1. 能用文字完全确定的题 → 把条件写全，不要写"如图"。
   validate_html.py 的配图检查只匹配 如图|下图|右图|上图——不写这四个词就不会报错。
2. 必须配图的（手拉手模型、等腰证全等、折线图信息题）→ 内联 <svg> 包在 <div class="fig"> 里，
   坐标先用 Python 算好再画，并配 <span class="cap"> 说明。

★★★ 折叠练习块：题干必须放在 <details> 外面（踩过，全系列返工过）

<details> 里除了 <summary> 以外的所有内容都是折叠的——题干也不例外。

错误写法（用户会反馈"题目只有打开答案才能看到"）：

<details class="quiz">
  <summary>查看答案</summary>
  <div class="q">题干…</div>     <!-- ❌ 被折叠了 -->
  <div class="ans">答案…</div>
</details>

正确写法（题干常显、只有答案折叠）：

<div class="quiz">
  <div class="q">题干…</div>
  <details class="ans-fold">
    <summary>查看答案</summary>
    <div class="ans">答案…</div>
  </details>
</div>

CSS 相应改成：.quiz 是卡片外框，details.ans-fold 只负责折叠行为。
通用原则：<details> 只包"要折叠的那一部分"，写完后问一句"不点开的话，读者能看到什么"。

> 本技能早期版本（语文/历史/政治册）也用了 details.quiz 包题干，同样有这个缺陷。
> 项目里可放一个幂等修复脚本 fix_quiz_stems.py：正则匹配 <details class="quiz">…</details>，
> 把 <div class="q">…</div> 提到外层 <div class="quiz">，只把 .ans 留在 <details class="ans-fold"> 里。

★★ 交付前跑「整体体检」，不要只依赖三层校验

三层校验（validate / check_macros / verify_render）查不出：折叠结构错、答案算错、
省略号残留、章节编号跳号、锚点失效、id 重复。建议在项目 _refs/ 放一个 check_all.py，
一条命令查这 10 项：

写这个检查器时的两个坑（都会造成大面积误报）：
1. \\[4pt] 里的 \[ 会被当成行间公式起始 → 必须先用 re.sub(r"\\\\\[[^\]]*\]", "", body) 抠掉再数，
否则每用一次 \begin{cases} 的分行间距就多报一个"定界符不成对"。
2. 报行号要用【原文】的 text.split("\n")，不能用剥离 <style>/<script> 之后的 body，
否则行号会偏到无关行上（第一版就因此把 CSS 行报成了正文问题）。

★ 本批体检真实抓出的缺陷（说明"只靠三层校验不够"）

• 平移题方向算反（把"向左平移 1/3"写成"向右平移 1/3"）；
• 例题推导用"……"跳步，实际没推出结论；
• 4 处折叠答案数值算错（如 2√5 应为 4√2）；
• 若干"……"占位残留。

共同教训：details.quiz 的答案是折叠的，三层校验脚本一律查不出对错。
→ 对策：每写一道题的答案，先在 Python 里用数值 / 坐标算一遍，再落笔。

★★★ 交付前必做「教材覆盖度核对」——不要凭印象说"覆盖全了"

按"专题"分册最大的风险是：专题分类会天然漏掉某些内容。
实测：初中数学按"数与式 / 方程 / 函数 / 几何 / 统计"分册后，
"图形本身的认识与操作"整块被漏掉了（线段角平行、对称变换、尺规作图、投影三视图），
合计约 13~15 分，而且全是基础送分题。

做法（5 分钟，必做）：把教材每章的核心词列出来，逐个全文扫描：

for kw in 三视图 主视图 俯视图 尺规 圆规 轴对称图形 中心对称图形 同位角 同旁内角 黄金分割 位似; do
  printf "%-14s %3d\n" "$kw" "$(grep -o "$kw" *.html | wc -l)"
done

命中数为 0 的，就是完全没覆盖的——立刻补。

为什么"专题分册"容易漏：专题是按"能力模块"切的，而教材是按"知识顺序"编的。
凡是"不属于任何模块、但教材单独成章"的内容最容易两边都不沾。
核对时要以教材目录为准，不是以专题分类为准。

> 初中数学的教训清单（做其他学科时按这个思路自查）：
> ① 几何入门（线、角、相交线、平行线）；② 图形的对称与变换；
> ③ 尺规作图；④ 投影与三视图；⑤ 位似；⑥ 黄金分割。
> 修补方式：新增一册专册比硬塞进现有册次更好——不破坏已有册次的结构。

★ 正则替换的坑：替换串里的 group 编号要回读一遍

给自测清单重新编号时写了
re.sub(r'<td>(\d+)\.\s*(.*?)</td>', lambda m: '<td>%d. %s</td>' % (cnt, m.group(1)), seg)——
m.group(1) 是原来的编号，不是正文，结果 22 项正文全被覆盖成"1. 1""2. 2"。

救援办法：从已构建的 HTML 里恢复原文（产物文件里通常还留着上一版内容）。
注意定位要用 rindex（侧栏导航里也有同名字符串），否则会取到导航里的那一处。

通用教训：① 正则替换的 lambda 里，每个 group 编号都要核对；
② 改"片段源文件"之前，先确认能从已构建产物里恢复；③ 批量改写前先备份。

化学系列（第八套变体：复用语文骨架，按知识板块分册，9 册）

★ 化学卷的结构（与其他科差异很大，讲义要写进去）

★ 三个关键差异（决定了讲义怎么写）：
1. 单题分值最高——选择题每题 3 分，错一题丢 3 分，容错率极低；
2. 非选择题只有 4 道，但一道题内跨多个模块——2026.1 第 17 题（16 分）一题内考了
晶胞、电子式、杂化、价层电子对、晶格能与熔点、有机结构简式、水解方程式；
3. “基于教材又高于教材”（2025.6 官方评析原话）——考信息获取与加工，不是背诵。

分册依据：按知识板块（9 册）

① 化学计量与离子反应　② 元素化合物　③ 物质结构与元素周期律　④ 化学反应与能量
⑤ 速率与化学平衡　⑥ 水溶液中的离子平衡　⑦ 电化学基础　⑧ 有机化学基础　⑨ 化学实验与工艺流程

★ 化学教材只有 5 本（必修 2 + 选必 3），但内容量大，故按知识板块拆成 9 册
（与英语同为 9 册，有先例）。“化学实验”必须独立成册——浙江卷选择题第 7、10、16 题
考基本操作与方案设计，非选择题第 19 题（12 分）整道是工业流程题。

★★★ SVG 里绝对不能用 <sub> / <sup>（化学册专属大坑）

SVG 不支持 <sub> / <sup> 这两个元素——写在 SVG 的 <text> 里，浏览器会
丢弃或错位渲染，而四层校验全都查不出来（因为 sub/sup 是合法 HTML 标签，
白名单里有，不会报错）。

必须改用 Unicode 上下标：

★ 写化学/物理类 SVG 配图前，先自查："<sub>" in svg or "<sup>" in svg。
★ 正文 HTML 里用 <sub>/<sup> 是正确的——只有 SVG 内部不行。
★ 本轮实测：che_figs.py 初版有 6 处 <sub>，已用脚本全部替换为 Unicode。

★★★ 真题原图（位图）的嵌入：{{IMG:key}} 与 base64

当能拿到真题原图时，优先用真图而不是自绘——装置图、晶胞图、流程图这类重绘容易失真。
化学册为此建了一套位图体系（可推广到任何科目）：

★ 图片必须先压缩再 base64（否则单文件会爆炸）：

im = im.convert("L")                       # 线条图转灰度，观感无损
if im.size[0] > 900:                       # 宽度超 900 缩到 900
    im = im.resize((900, h*900//w), Image.LANCZOS)
im.save(out, "PNG", optimize=True)

实测：29 张从 1002 KB → 382 KB（37%），base64 后约 500 KB，分到 6 册每册仅 ~83 KB。

★★ 踩过的坑：inject() 里计数器 n = [0, 0] 被写了两次，第二次在 SVG 替换之后 →
SVG 计数被清零（注入其实成功，但计数显示 0）。
教训：计数器只能在所有 _rep 闭包之前定义一次。

★ 成品必须反解校验：从生成的 HTML 里正则抽出 <img src="data:image/png;base64,…">，
base64 解码后用 PIL 打开，确认尺寸与可读性——不能只信"注入了 N 张"的计数。

★★ 没有真图时的取舍

一个学科/一册未必每册都有对应的真题原图（化学第 1、4、6 册就没有）。
处理原则：
- 自绘 SVG 示意图照旧（讲机理的图本来就没有"真题原图"）
- 在正文里明确说明本册无对应真题原图，不假装有
- 不要把真图硬塞到不相关的册次——图与内容必须对应

化学册的构建与校验（一条命令）

python _refs/build_cheNN/build.py                    # 组装
python add_sidenav.py "高考化学重点章节梳理-NN-*.html"  # 注入侧边导航（幂等）
python _refs/che_inject_figs.py <file>               # 注入 SVG 配图（幂等）
python "$S/validate_html.py"     <file>              # 结构层 + 内容层（含配图检查）
python "$S/check_html_static.py" <file>              # 静态层（化学无 MathJax，不需要 check_macros）
python "$S/verify_render.py"     <file>              # 渲染层

★ 化学册的“一句话判据”（做新册次时继续积累）

★★★ 给讲义配「教材原题图」——单文件 HTML 里内嵌图片的完整做法

用户反馈"几何题手绘 SVG 不如用题目本身的图"。实测可行，做法如下（可复用）：

① 找图源：优先找带原题配图的题库/讲义仓库，而不是自己去截真题 PDF。
初中数学实测可用：Onion12138/math 的 picture/（216 张 LaTeX 矢量渲染的题图，
与 test.tex 里的 problem 环境一一对应）。抽取脚本：extract_tex_figs.py
（把 \begin{problem}…\end{problem} + 紧随的 \includegraphics{picture/X.png} 配成对）。

② 压缩是能不能内嵌的关键。这批图是黑白线条图，实测三种方案（10 张样本）：

→ 选 WebP。现代浏览器（Chrome 32+ / Edge / Firefox 65+ / Safari 14+）全支持，
打印成 PDF 也正常，体积只有 PNG 的 1/3。视觉上放大对比过，线条图看不出差别。

③ 预处理要点（prep_figs.py）：
- RGBA 透明底必须压成白底——否则在深色主题下透明区域会显黑；
- 裁掉四周白边（ImageChops.difference + getbbox）；
- 等比缩放到最长边 ≤ 820px（讲义正文列宽约 600~680px）。

④ 内嵌方式：占位符 + 构建时展开（保持单文件 HTML，不会"丢图"）。
片段里写 {{FIG:6104|图注}}，构建器用正则替换成
<div class="fig"><img src="data:image/webp;base64,…"><span class="cap">图注</span></div>。
好处：片段保持可读（不会塞满几万字符的 base64），且构建幂等。

⑤ 实测成本：每册放 2~3 张图只增加 20~38 KB（100 KB → 120~143 KB），完全可以接受。

⑥ 两个必踩的坑：
- 图注里的 LaTeX 必须用 \( … \) 包起来，否则 MathJax 不渲染、页面上直接显示 \dfrac 源码；
- 骨架自带的 .fig img{ max-width:300px } 对数学图形太小（标注挤在一起），
要在 EXTRA_CSS 里放宽到 460px（打印 340px）。

⑦ 新增的校验项：check_all.py 第 ⑪ 项——文本里裸写的 LaTeX 命令。
做法：先剥掉 <img> 标签与 alt/title 属性（图注的 LaTeX 在 alt 里是允许的），
再去掉所有 \(…\) / \[…\] 区段，剩下的若还匹配 \\[a-zA-Z]{2,}，就是会显示成源码的裸命令。

⑧ ★★ 验算时把"比例方向"读准（本批差点出错的地方）。

题目写"(DE=2CE)"时，是 (DE) 长、(CE) 短。我第一次写验算脚本时按 (CE) 长取值，
算出的答案（(3\sqrt{26}/13)）是错的；改成正确取值后答案是 (6\sqrt5/5)——两个数完全不同。

防范流程（设完坐标立刻做）：

E = (4, 6)                     # 由 DE=2CE、CD=6 ⇒ CE=2, DE=4 推出
print("核对题设：CE =", C[0]-E[0], " DE =", E[0]-D[0])   # 必须打印出来与题设对照

不要只在脑子里过一遍——把实测值打印出来和题设数字比对，一眼就能发现方向反了。

同理，凡是"(AE=2BE)""(BC=2AD)""(DE=EC)"这类比例条件，
都要先把各段的实际长度算出来核对一遍，再往下做。

⑨ 解析里只保留"最终那条干净路径"。
本批有 3 处留下了"多思路草稿"（用"……"连着写了好几种算法，或写"更准确地说""换个思路"）。
check_all.py 的第 ⑩ 项（省略号/草稿痕迹）能抓出来，但最好一开始就只写一条路径：
定好解法 → 算准 → 一次写完，不要边写边换思路。

★★★ 从 GitHub 找题库仓库：不要被仓库描述骗，要查具体目录

实测结论（2026-09，找化学素材时踩过）：

★ 正确做法：拿到候选仓库后，必须逐级查具体目录
（GET /repos/{owner}/{repo}/contents/{path}），而不是相信仓库描述或 README 里的统计数字。

★★★ docx 里的公式：分清 OMML 与 MathType OLE

★ MathType OLE 的识别信号：纯文本提取后出现大量 false
（来自 <o:LockedField>false</o:LockedField>），说明公式没被提取到。

★ 解法（实测可行）：

# 1) 导出 word/media/*.wmf
# 2) Windows 上 PIL 可以直接打开 WMF（关键！）
from PIL import Image
im = Image.open("media/image10.wmf"); im.load()      # 成功
im.convert("RGB").resize((w*3, h*3), Image.LANCZOS).save("out.png")
# 3) 放大 3 倍拼成对照表，目视读取（实测能读出 H₂S、KMnO₄、C₃H₆、HC≡CCH₃ 等）

★ 透明 PNG 的坑：im.convert("RGB") 会把透明背景渲染成全黑，看起来像“图片是空的”。
必须先合成白底：

bg = Image.new("RGBA", im.size, (255,255,255,255))
im = Image.alpha_composite(bg, im.convert("RGBA")).convert("RGB")

★★ 素材可用性实测：三类“看起来有、实际没有”

★ 教训：下载后先做一次“可用性探测”（抽 3 页文本 / 看字符数），
再决定要不要花时间处理——不要下了一堆才发现全是扫描件。

★ pip 装包需带代理凭据（本机环境）

export HTTPS_PROXY="http://<user>:<pwd>@192.168.3.19:8080"
export HTTP_PROXY="$HTTPS_PROXY"
uv pip install --python <venv>/Scripts/python.exe pypdf --index-url https://mirrors.tencent.com/pypi/simple/

不带凭据会报 tunnel error: proxy authorization required。
（GitHub 下载则相反：用 curl --noproxy '*' 直连。）

科学系列（第九套变体：复用数学骨架 + 自绘 SVG 配图，浙江合科）

> 浙江特有的"合科"：物理 + 化学 + 生物 + 地理天文合成一张卷，满分 160 分
> （浙江中考分值最高的科目，语数英各 120）。

★★ 科学的三条独有经验

① 真题源几乎全部失效，只剩省考试院官网（2026-09-22 实测）

→ 7 个商业站点全部拦截。 讲义走"自拟题 + 标注示例，非真题"。
→ 但有一条新路：用官方评析里点名的题号 + 情境 + 考查点做考情分析与真题精讲表
（讲"考什么""怎么考"，不逐字引题干）——既真实、又不违反诚实性。
★ 做新省份/新学科前，先花 2 分钟逐站验证，别假设"上次能抓的这次还能抓"。

② 官方评析里藏着现成的骨架——专门找"分类式表述"

2025 浙江科学评析把实验探究题分成六种能力并逐条点名题号：
① 基本实验技能　② 实验变量的控制　③ 实验方案的设计　④ 实验数据的分析
⑤ 预测实验现象（画图）　⑥ 解释现象。
这种"官方自己给出的分类"拿来当讲义骨架，比自拟的权威得多。

③ 科学的图必须自绘——新增 {{SVG:key|图注}} 机制

电路图、光路图、受力图、实验装置图、曲线图找不到公开图库，
所以构建器在原有 {{FIG:key|图注}}（base64 位图）之外，新增 {{SVG:key|图注}}：
从 _refs/sci_figs.py 取 SVG 字符串内联进 HTML。

# build_czsci_common.py
SVG_PLACEHOLDER = re.compile(r"\{\{SVG:([A-Za-z0-9_\-]+)\|(.*?)\}\}")
def rep_svg(m):
    key, cap = m.group(1), m.group(2)
    return '<div class="fig">%s<span class="cap">%s</span></div>' % (
        sci_figs.get(key, caption=_plain(cap)), cap)

_refs/sci_figs.py 的写法：一堆 _t() / _line() / _rect() / _path() helper
+ FIGURES = {key: 函数} + get(key, caption)；__main__ 里跑自查
（无 HTML 标签、无未知 SVG 元素）。配套 CSS 放宽 .fig svg 到 560px（打印 420px）。

★★★ 当"写进文档的规则"反复挡不住同一个错误时——把它变成机械门禁

真实案例（连续三轮踩同一个坑）：在 sci_figs.py 里给 SVG 写中文说明时，
误把英文双引号写进中文文案：

s.append(_t(60, 262, "★ 植物的层次<tspan>没有"系统"</tspan>这一级：", ...))
#                                        ↑↑ 这个引号提前闭合了外层 Python 字符串

后果：整个模块 SyntaxError，配图库加载不了，所有册次一起报错。
04 册、08 册、10 册各犯一次。 把"别这么写"写进模块 docstring 的第 3 条铁律，依然挡不住。

第一次尝试（失败）：写正则脚本找"中文里的英文引号"。
→ 假阳性爆炸：77 处命中里绝大多数是合法的字符串分隔符
（如 ("俯视", 130, -54, "读数偏大", RED)）。该方案已废弃删除。

第二次尝试（成功）：scripts/check_py_syntax.py —— 直接用 ast.parse 做语法检查。
- 零假阳性（只有真语法错误才报）
- 给出行号 + 出错行内容
- 当出错行同时含 " 和中文字符时，额外提示"疑似中文里混用英文引号，请改成「」"

python scripts/check_py_syntax.py _refs          # 递归扫目录

反向测试：人为造 s = "中文"引号"测试" → 准确报 行 2 invalid syntax + 提示 ✓

★★ 通用教训（比这个具体坑更重要）：

1. 同一类错误重复出现 2 次以上，说明"靠记性"这条路已经失败了——
   不要再写第三条规则进文档，直接做机械门禁。
2. 门禁必须选零假阳性的实现。 正则"猜"语义必然误报，
   而误报的门禁很快就会被忽略（第一次那版 77 处误报，等于没用）。
   优先用语言自带的解析器（ast.parse / compile / json.loads），
   而不是自己写正则去近似。
3. 门禁的输出要带行号和出错内容，并给出改法提示——
   这样它在出错的那一刻就能直接指导修复。

★★★ 新踩的坑：SVG 里 marker 的 id 必须逐图唯一

_defs() 里写 id="ar"，单张图看没问题；但 8 张图内联到同一页后就成了 8 个同名 id：
- 属无效 HTML（浏览器只认第一个）；
- 被 check_all.py 第 ⑥ 项「id 重复」抓到 → ✗ id 重复：['ar']。

✅ 修法：在 get(key) 里统一加图名后缀。
★ 第 06 册的升级：一张图里要用两种颜色的箭头时（_defs() + _marker("ar2", RED)），
只处理 id="ar" 就不够了。现在改成扫出所有 ar 开头的 id 逐个加后缀：

for mid in sorted(set(re.findall(r'id="(ar\w*)"', svg)), key=len, reverse=True):
    svg = svg.replace('id="%s"' % mid, 'id="%s-%s"' % (mid, key))
    svg = svg.replace("url(#%s)" % mid, "url(#%s-%s)" % (mid, key))

（按长度倒序替换，避免 ar 误伤 ar2。）新增 marker 时不必再改 get()。
★ 通用：任何"每张图自带 <defs>"的 SVG 库都要注意 id 命名空间——
不只是 marker，还有 clipPath / linearGradient / mask / pattern。

★★ 配图"逐张目视核对"在科学图上又抓到 3 处实质错误

三层校验完全查不出的（渲成 PNG 逐张看才发现）：

外加一处长文字冲出画布 → 改为左对齐另起行，别接在靠右的位置后面。

三条通用教训：
1. 图上的几何比例必须和文字里的数字对上——最隐蔽的一类错误（图看着没问题，但和文字矛盾）。
2. "方向类"要素（视线、力、光、电流、遗传分离）画成水平或对称就失去了表达力，
必须把"倾斜/差异"画出来。
3. 手绘表格型 SVG 要核算行高：最后一行文字底 + 8px ≤ 盒子底边（化学系列出现过 4 次溢出）。

★★ 磁学配图的四条方向铁律（第 06 册《电与磁》）

磁学的图几乎全是方向图，方向错一处整张图就废了。落笔前先把这四条钉死，
并且每条都要用"两条独立路径"互查——只凭一条极容易画反。

★★ 螺线管磁极的双路径互查（第 06 册最有价值的一条）：
配图里螺线管画成"正面斜线电流由左下 → 右上"（即正面电流向上），推得 N 极在左端。
两条独立路径都验过才敢画：
1. 右手握法：四指指正面电流方向（向上），大拇指指向左端；
2. 等效环电流法：把螺线管看成一叠同轴环电流 → 取任意一环，正面电流向上、背面向下 →
从右端朝左看，屏幕左＝正面 ⇒ 屏幕上"左↑右↓"＝顺时针 ⇒
右手四指顺时针时大拇指指向纸面内＝左端 ✓

★ 一个符号只能有一个含义：⊗ / ⊙ 是"垂直于纸面向内/向外"的通用符号，
第 06 册初版把它同时用在"磁场方向""受力方向""用电器"三处 → 读者无法分辨。
→ 同一册内每个符号只保留一个语义；表示"用电器"改用矩形 + 字母 M。

★ 平面图里画不出"三者两两垂直"时的解法：
"导体棒、磁场、运动方向"要两两垂直才有感应电动势，但纸面内只有两个独立方向，
所以必然有一个要素垂直于纸面。第 06 册的选择是让磁场垂直于纸面（用 ⊗ 表示），
导体棒水平、运动方向上下 —— 三者关系全部画得出来，且物理正确。
（"导体棒垂直纸面""运动方向垂直纸面"这两种选法都画不出来。）

★ 别在图里写"语义箭头"：初版在条形磁体内部标了 S → N 的文字。
但磁体左端是 N、右端是 S，文字箭头的方向（语义）与图上的空间方向正好相反，
写上去反而误导。→ 方向只用图形箭头表达，语义交给图注和正文。

★ 目视核对要看的四件事（顺序别反）：
1. 文字有没有被图形压住——第 06 册"切割磁感线"五个字被 ⊗ 压掉半个字，
而 check_all.py 的字宽估算查不出（它只算"是否出画布"，不算"是否被图形盖住"）；
2. 文字有没有冲出画布；
3. 方向类要素对不对（磁感线箭头、N/S 位置、受力 ⊗/⊙、电流箭头）；
4. 数量/比例与文字对不对（如"每周期方向改变 2 次"要能在波形图上看出两个过零点）。

科学的 12 册方案（按专题，与模块权重成正比）

考情速记：选择 15×3 = 45 分、填空 7 题 40 分、实验探究 + 综合 75 分；
物理占 40.6%（≈65 分）；九上 45 分、八上 42 分是重点。
教材版本：2026 秋起九年级也换新教材 → 2027 中考是新教材首届。
（新教材变化：酸碱盐从八下前移到九上第 1 章；微粒/化学式从八下提到七下；
新增"技术与工程"板块。★ 新教材各册目录公开渠道有冲突版本，动笔前必须逐册核对。）

★★★ 全套做完后的「五层完整性审计」（2026-09-23，科学 12 册实测）

做完一整套之后，"关键词覆盖度"这一层会给出虚假的安全感。
科学 12 册第一层审计（221 个关键词）未命中 0 个，看着很完美；
但第二层精扫查出 13 处"提及但未展开"的真缺口（光的色散、能源与核能、
乳化、气体除杂与干燥、化学肥料、导管筛管与蒸腾、血型与输血、动物行为、
生物分类、青春期、太阳活动、水循环、温室效应）。

→ 审计必须分层做，顺序不能省：

★★ 第 2 层的判据（关键）：不要问"这个词出现过吗"，要问
"这个考点在对应册次里该有多少篇幅"。科学 12 册的判据是：
一个必考考点至少要有考点表 + 讲清为什么 + 例题 + 练习四件套；
若全系列只有 0~6 次顺带提及，就是缺口。

★ 第 3 层是本次新增的能力。原来六层校验只能保证"公式能被渲染"，
保证不了"算得对"。check_numeric.py 把「A = B = C」等式链抽出来逐项核算。
它一上来就查出第 05 册一处真实瑕疵：
R = U/I = 220/0.18 ≈ 1210 Ω（220/0.18 实际是 1222.2，是"用取整值算、拿精确值对"）。

★★★ check_numeric.py 的六条设计要点（每条都是被假阳性逼出来的）

写这类验算器，假阳性比漏报更致命（一个吵的门禁很快会被忽略）。踩过的坑：

1. 单位换算是"合法的不等"。t = 2+3 = 5 min = 5×60 = 300 s 里 5 和 300 都对。
   ⇒ 只比相邻项，单位不同就跳过（不要"全链取首项当基准"）。
2. 单位常常写在 \text{} 里（5\ \text{min}、400\ \text{cm}^2）。
   ⇒ 必须把 \text{} 解包而不是删除，否则单位丢失，退化成 "5 vs 300"。
3. \% 不是单位，是「×100 后加 %」的记号。
   ⇒ 把数值 /100 归一到小数空间再比（否则报 11 处假阳性）。
4. \dfrac14 有简写形式（不带花括号）。
   ⇒ 必须用"读一个参数"的函数（{...} 配平 或 单字符），
   否则会把 \dfrac14 切成 "14"，把 100 × \dfrac14 算成 1400。
5. 容差取"半个末位"（按书写精度），而不是固定相对误差。
   36/136 ≈ 26.5% 差 0.0003 是正常四舍五入；220/0.18 ≈ 1210 差 12
   （末位是十位）就该报出来复核。
6. 单位也可能是 LaTeX 命令：\approx 1222\ \Omega 里的 \Omega 要先换成 Ω
   再匹配单位表，否则 _decimals 落到"非纯数字 ⇒ 6 位小数"的兜底分支，
   容差被压到 0.005，把 1222.22 vs 1222 判成错误（这是第 6 次假阳性）。

★★ 校验器本身也会出错——"全绿"可能是假象

科学 12 册审计时踩到两个校验器自身的缺陷：

1. check_all.py 第 ⑬ 项「总册数自洽」误报：它用
   len(目录里全部 .html) 当"全系列册数"。同一目录并存两个系列
   （初中数学 10 册 + 初中科学 12 册）后，22 就成了"总册数"，
   于是数学第 10 册的「这十册」被判成错误。
   ⇒ 已改为按系列前缀分别计数（把文件名末尾的 -NN-… 剥掉当系列键）。
2. check_numeric.py 的 6 次假阳性（见上，全是"单位/记号没归一化"）。

★★ 通用教训：每次校验器报错，先怀疑校验器。
确认是内容问题再改内容——否则会为了迁就一个有 bug 的校验器，
把本来正确的内容改错。

★ 能把"错误"转成"教学点"的修改优先

第 05 册那处取整偏差，修的时候顺手写成一条教学点：
「用"换一条路验算"时中间量尽量保留分数或多数位，过早取整会让两条路对不上，
白白怀疑自己」。
比单纯把 1210 改成 1222 有价值得多——讲义的价值在"教会"，不在"无误"。

★★ 往既有册次补内容时：h3 插入 > 新开 h2

补缺口时不要新开 h2 章节（那会牵动 id="chN"、目录锚点、后续全部重编号）。
科学 12 册的做法是：把新内容作为 h3 插进最相关的既有章节——
h3 不带 id，只有 h2 与目录关联，所以只需在本章内做局部编号顺延，
爆炸半径最小。

配套动作（漏一个就不一致）：

1. 本章内后续 h3 编号顺延；
2. 该册 0.1 考情表加一行（含约分值）；
3. 该册 0.2 本册地图对应行补关键词；
4. 该册 易错点清单加 2~3 条，并把"本册 N 条易错点"的计数同步改掉；
5. 补一个"例 N"（含验算段）+ 练一练补 2 题 + 答案区补对应题号；
6. 改完必须重建该册（build.py），不要在生成的 HTML 上直接改——
   否则下次重建会把修改覆盖掉（科学 05 册就踩过这个）。

★★★ 构建的「后置步骤」必须并进构建——否则漏跑一步就静默丢功能

真实事故（2026-09-23，用户反馈"怎么有些章节左边的导航没了"）：

科学系列的产物链原本是两步：

python _refs/build_czsci02/build.py        # ① 生成 HTML
python _refs/add_sidenav.py <file.html>    # ② 注入左侧固定导航 ← 单独一步

做完整性审计时我重建了 8 册，只跑了第 ① 步，于是这 8 册的左侧导航整块消失。
更糟的是：校验器一路"全绿"——check_html_static.py 明明算出了
h3=0 导航=0，却只把这两个数当信息打印、不报错。
直到用户打开文件才发现。两轮校验、几十项检查，全都没拦住。

两个根治动作（都不是"下次记得"）：

1. 把后置步骤并进构建。build_czsci_common.py / build_czmath_common.py
   现在在写文件前直接调用 add_sidenav.build(html)，并断言侧栏条目 > 0：

python import add_sidenav html, n_nav = add_sidenav.build(html) assert n_nav > 0, "侧栏条目为 0 —— add_sidenav 没生效，产物不完整"

保证「跑完 build.py 就是完整成品」，没有"第二步"可以漏。

2. 把算出来的信号变成判定。check_html_static.py 里新增：

python if not hrefs: probs.append("缺少左侧导航（侧栏 0 条）——多半是构建后漏跑了 " "add_sidenav.py；跑一次即可（幂等）")

★★ 通用教训：只打印、不判定，等于没查。
一个校验器如果"算出了异常值却当成正常输出的一部分"，它就是装饰。
凡是能算出来的关键指标（导航条目数、配图数、锚点数……），
都要有一条下界断言（> 0 / == 预期值），而不是只在行末显示。

3. 顺带修正了一个误导性计数：h3 的统计正则原为 <h3（带尾空格），
   而未注入 id 的 <h3> 没有空格，所以侧栏丢失时 h3 数会显示成 0——
   这个"0"本来是重要线索，却因为正则写法被当成"这册 h3 本来就少"。
   → 改为 <h3[\s>]，同时把 h2 也一并改掉。

★ 同时提醒：add_sidenav.py 不是一次性脚本，它是产物链的必需环节。
归档"死脚本"时务必先确认它不在构建流程里——
extract_*.py / patch_content*.py / insert_fig_content*.py / shot*.py
可以归档，add_sidenav.py 不行。

★★ 清理一次性脚本：移出 _refs/*.py 的 glob 范围

每个系列都会留下一批"跑完就废"的一次性脚本（内容补丁、素材提取、截图工具）。
它们会：① 污染语法门禁的输出；② 让"哪些脚本还活着"变得不清楚。

⇒ 做法：确认无人 import 后，统一移入 _refs/_legacy/。
科学 12 册整理后，门禁范围从 28 个收敛到 15 个活动脚本、零告警。

★ 顺带修 SyntaxWarning: invalid escape sequence 的正确姿势：
把三引号字符串改成 raw 字符串时，不要用正则做替换——
正确做法是「先用 ast 取字面量的真实值，再用这个值重建 r"""..."""」，
并断言改写前后所有字符串常量逐字相等。两个必须注意的点：

• col_offset 是 UTF-8 字节偏移，中文行必须换算成字符偏移，否则替换位置错位；
• 取源码片段要用 ast.get_source_segment(src, node)，
  不能用 src[node.lineno-1:node.end_lineno] 按行号切字符串（第一版就是这么错的）。

小学系列（第十套变体：四科 × 三学段 = 12 册）

> 浙江小学四科：语文（统编版）· 数学（人教版）· 英语（人教 PEP，三年级起点）· 科学（教科版）。
> 按「学科 × 学段」分册：每科 3 册（低年级 1-2 / 中年级 3-4 / 高年级 5-6），共 12 册。
> 文件名：小学<学科>知识体系梳理-NN-<学段>.html。

★ 教材版本与换版时间线（做浙江小学讲义前必查）

换版节奏（2024 秋起）：一年级起逐年级替换，2026 秋 1-6 年级上册全部新版；
但四/五/六年级下册新版 2027 春才启用——做这几册时要按旧版目录，并在 ch0 明确标注。

★ 三处"教材数字"必须核对，不能凭印象

1. 古诗文篇数：课标必背 75 首古诗（不含古文）+ 教材 14 篇文言文 = 129 篇。
   "128 篇"没有权威出处，是讹传，不要用。
2. 识字量：课标只给学段累计数（第一学段 1600 认 / 800 写；第二 2500 / 1600；第三 3000 / 2500）。
   网传的"逐册精确字数表"版本互不一致，不要写进讲义正文。
3. 小学数学知识点会跨册移动：换版期"表内除法上移""观察物体上移合并""认识时间并入综合实践"都发生过。
   → 讲义以"知识块"为骨架，册次只作备注，不要用"几年级上册第几单元"当唯一索引。

★★ 本变体踩过的坑（每一条都会复发，先按此处理）

本变体的工具链（放项目 _refs/ 下）

# 一册的完整流水线（推荐：一条命令跑完全部）
bash _refs/pipe.sh _refs/pri_yw01 "小学语文知识体系梳理-01-低年级（1-2年级）.html"
#   内部顺序：fix_md → build.py → add_sidenav → check_all → validate_html → check_html_static

# 定点修补
python _refs/autofix.py _refs/pri_sx02                    # 批量换掉"会被误判为草稿痕迹"的措辞
python _refs/fix_ellipsis.py <文件> '<正则>' '<替换>'      # 清单省略号（引号用 . 通配）
python _refs/fix_md.py <文件...>                           # 清 Markdown 加粗

build_pri_common.py 的骨架映射（这是本变体唯一需要改的地方）：

SUBJECTS = {
    "语文": ("skeleton-head-zh.html", "小学语文 · 知识体系梳理（统编版）"),
    "数学": ("skeleton-head.html",    "小学数学 · 知识体系梳理（人教版）"),
    "英语": ("skeleton-head-zh.html", "小学英语 · 知识体系梳理（人教 PEP）"),
    "科学": ("skeleton-head-zh.html", "小学科学 · 知识体系梳理（教科版）"),
}
EXTRA_CSS = {"语文": QUIZ_CSS, "英语": QUIZ_CSS + EN_CSS,
             "科学": QUIZ_CSS + SCI_CSS, "数学": QUIZ_CSS + MATH_CSS}

★★ 交付前必做「逐章密度统计」（本变体最有效的一招）

一套讲义做完、三层校验全绿之后，内容仍然可能"厚薄不均"。用 <h2> 切块统计每章正文字数 +
练习数，一眼就能看出哪一章偏薄。

实测：12 册里有 20 个知识章完全没有"练一练"（因为练习都写在了章末的下一个章节里）。
补齐后才符合"每章一个练一练"的系列约定。

parts = re.split(r'(<h2 id="ch\d+">.*?</h2>)', t)   # 奇数下标=标题，偶数下标=正文
# 对每个 body：数字数、数 <div class="quiz">、数五色框

判断标准（小学）：知识章正文 1500~4000 字较合适；低于 1000 字要看是不是真没内容
（如"图形与位置"对一二年级确实就那么多）。ch0（写在前面）/ch6（易错点清单）/ch7（知识地图）
1000 字左右属正常，不需要补。

★ 给讲义"补练习"的正确做法

补练习要插在"下一章的 <h2> 之前"（也就是本章末尾），而不是随便找地方插。
写补丁脚本时用 t.replace(anchor, block + "\n\n" + anchor, 1)，
其中 anchor 是下一章的 <h2 id="chN"> 开头串——这个锚点一定在同一片段文件里（每章的 h2 都紧跟在上一章末尾之后）。

已交付的小学系列（浙江，12 册）

各册的核心主线（做续册或改版时沿用）：

语文  01 会拼 → 会认 → 会读 → 会说 → 会写
      02 会默读 → 会概括 → 会复述 → 会成篇
      03 读得快 → 分文体 → 看写法 → 写具体
数学  01 数数 → 位值 → 加减 → 乘除 → 倍
      02 位值扩展 → 运算定律 → 小数分数 → 面积
      03 分数四则 → 方程 → 体积与圆 → 比与比例
英语  01 听 → 说 → 认字母 → 拼读
      02 词汇 → 句型 → be 动词 → 一般现在时 → 疑问句
      03 四个时态 → 动词变形 → 比较级 → 语篇输出
科学  01 观察 → 描述 → 公平比较 → 动手制作
      02 用工具测量 → 做对比实验 → 记录数据 → 解释现象
      03 放大它 → 看它的效果 → 让它显形 → 看它造成的影响

小学讲义的三条写作口径（与中学系列不同）

1. 不写"考点/得分"，写"能力/习惯"。 小学没有选拔性考试（浙江小升初免试就近入学），
   讲义的价值在"把地基讲清楚"，而不是"提分技巧"。
2. 每条结论都要有"为什么"。 例：不能只说"三角形面积要 ÷2"，要说清"它是拼出来的平行四边形的一半"。
3. 必须有一节"学段衔接"。 小学家长最关心"三年级现象""小升初落差"。
   用数据说话：阅读量 5 万 → 40 万 → 100 万字；识字 1600/800 → 2500/1600 → 3000/2500。
   这些数字本身就是最有说服力的论证。

初中社会系列（第十一套变体：复用语文骨架，三科合卷，10 册）

> 浙江特有的"社会·法治"合卷：地理 + 历史 + 道德与法治装在同一张卷子里，
> 满分 100 分、时长 100 分钟。2024 年起省级统一命题，2026 年起全省统一闭卷
> （2024/2025 为过渡期，原开卷地区可继续选开卷卷）。

★★ 考情（2026-09 联网核实，做任何一册前先确认）

分值配比：道德与法治 ≈40 + 历史 ≈40 + 地理 ≈20（4:4:2）。
教材构成（16 本）：地理 4 本（人教版，七上/七下/八上/八下）+ 历史 6 本（统编版）+ 道法 6 本（统编版）。
★ 注意：浙江从 2024 秋起地理由《人文地理》2 册改为《地理》4 册（原《历史与社会》= 统编历史 6 册 + 人文地理 2 册的旧口径已过时）。

★★★ 时间线：2027 中考是新教材首届

2024 秋起按"起始年级先行"逐年级替换 → 2024 级学生（2027 年中考）用的是全新教材。
做这个系列时必须按新教材核对，已核实的变化：

• 地理：从《人文地理》2 册变为人教版《地理》4 册；七上第一章「地球」（含"地球的宇宙环境"）、第二章「地图」，
  七下章号从第七章接续（我们生活的大洲——亚洲 / 我们邻近的地区和国家 / 东半球其他的地区和国家 / 西半球的国家 / 极地地区）。
• 道法七上（2024 版）：4 单元 13 课 —— 一 少年有梦（开启初中生活 / 正确认识自我 / 梦想始于当下）；
  二 成长的时空（幸福和睦的家庭 / 和谐的师生关系 / 友谊之树常青 / 在集体中成长）；
  三 珍爱我们的生命（生命可贵 / 守护生命安全 / 保持身心健康）；四 追求美好人生（确立人生目标 / 端正人生态度 / 实现人生价值）。
• 道法八上：原八下的「追求自由平等」「维护公平正义」前移到八上第三单元「勇担社会责任」。
• 道法九上（2026 秋）：第一单元改为「坚持党的全面领导」。
• 历史七上（2024 版）：4 单元 21 课（一 原始社会与中华文明的起源 / 二 奴隶制王朝的更替和向封建社会的过渡 /
  三 统一多民族封建国家的建立和巩固 / 四 政权分立与民族交融）+ 学史方法。
• 历史七下：第一单元「隋唐时期」由 5 课扩充为 7 课（新增"隋唐时期的民族交往与交融""隋唐时期的科技与文化"）。

★ 应对办法：讲义按「历史时期 / 主题」组织内容，不绑定具体单元序号。
并在每册 ch0 写明"新教材正在逐年级替换，本册按考点组织，复习范围不受影响"。
这样无论教材怎么微调，产物都不用返工。不要写"某知识点在第几单元第几课"——那是返工率最高的写法。

分册方案（10 册，已交付）

① 世界地理　② 中国地理　③ 中国古代史　④ 中国近代史　⑤ 中国现代史　⑥ 世界历史
⑦ 道法·成长与交往（七上七下）　⑧ 道法·法治与责任（八上八下）　⑨ 道法·国情与全球视野（九上九下）
⑩ 综合题解题方法

分册依据 = 学科 + 时期：地理按"世界 / 中国"，历史按"古代 / 近代 / 现代 / 世界"，道法按"成长 / 法治 / 国情"。
三科各占的卷面分不同（20 / 40 / 40），所以册数不必均分——地理 2 册、历史 4 册、道法 3 册、方法 1 册正对应分值。

★★★ 本系列定型的「10 章骨架」（比 9 章更适合多册系列）

ch0 写在前面（考情表 + 本册地图 + 学法建议 + 教材版本提示 + 图注说明）
ch1 ~ ch6 知识板块（每章固定五件套 ↓）
ch7 易错点清单（16~18 条表格：易错点 / 正确做法）
ch8 知识地图与自测（地图卡片 + 核心链 chain + 自测 12 项，分「会记 / 会判 / 会答」）
ch9 中考题型精讲与刷题区（题型分布表 + 3 道示例精讲 + 提分要点 + 刷题区 6~8 题）

每章的五件套（固定顺序）：

1. 核心考点表（tbl-wrap + table）
2. 方法 / 为什么（box proof）——讲清机制，不罗列结论
3. 例题精讲（box eg）——分步 + <span class="ask">一句话判据</span>
4. 练一练（div.quiz + details.ans-fold）
5. ★ 提高板块（bone 答题骨架）

★ 10 章而不是 9 章的理由：把"易错点清单"和"知识地图与自测"拆成两章后，
每册的固定章节数整齐（ch0~ch9），10 册之间可以逐章对照，读者跨册翻阅时不用重新适应结构。

★★ 新增两个 CSS 类（写进 build_soc_common.py 的 EXTRA_CSS）

/* 一句话判据（自问句）—— 例题里每个"判据"都用它，全系列统一 */
.ask{ display:inline-block; padding:1px 9px; margin:0 2px;
      border-radius:6px; background:#fff4e5; border:1px solid #f5dcae;
      color:#9a5c05; font-weight:700; font-size:.94em; }
/* 出处 / 说明行 */
.src{ display:block; margin-top:8px; font-size:12.5px; color:var(--muted); }
.muted{ color:var(--muted); font-size:13.5px; }

.ask 是本系列的"标志性组件"——每道例题末尾都有一句"考试时自问的一句话"。
muted 用于图注说明（如"本题需读取原题××图，讲义为纯文本形式……"）。

★★ 地理册不配图——统一走「诚实图注」路线

社会系列的真题（尤其是地理）几乎每题都配图，但：① 公开渠道拿不到原图；
② 区域图涉及国界与海岸线，受 geo-map-compliance-guard 约束不能重绘。

⇒ 本系列一律不配图（fig=0），凡引用带图真题处写：

<p class="muted">本题需读取原题等高线图，讲义为纯文本形式，此处保留题干、答案与判据。</p>

这样同时通过 validate_html.py 的配图校验（不出现"如图/下图"）与合规要求。
★ 在每册 ch0 用 box warn 明确告知读者这一点，并提醒"真题请配合原卷使用"。

★★ 客观题是"保分项"，主观题是"拉分项"——第 10 册的方法册定位

第 10 册《综合题解题方法》是本系列的收口册，结构与其他册不同：

★ 第 10 册的 ch9 是"全系列收官"的位置——这里要写"全系列十册回顾表"和收尾的话，
check_all.py 第 ⑬ 项会核对"十册"这个数字（见下方坑）。

★★★ 本系列踩过的四个坑（每个都会复发）

★ 第 3 条最值得记：check_all.py 的"文档类型分档"是按 '<div class="q">' in body 判定的。
只要用了 <div class="q">（题干常显的正确写法），就自动进入 czmath 档，单省略号从"提示"升级为"FAIL"。
这是"文科册用 czmath 结构"时的隐性代价，做新系列前先确认。

构建与校验（一条命令）

python _refs/socNN/build.py                        # 组装（★ 已内含侧栏注入）
python "$S/check_all.py" 初中社会中考复习-*.html     # 整体体检（★ 必须整目录跑，否则 ⑬ 项误报）
python "$S/validate_html.py" 初中社会中考复习-*.html
python "$S/check_html_static.py" 初中社会中考复习-*.html
python "$S/verify_render.py" 初中社会中考复习-*.html  # 10 册约需 9 分钟，建议后台跑

★★ check_all.py 第 ⑬ 项（总册数自洽）必须"整目录一次跑完"——
只传单个文件时它按 1 册计数，于是第 10 册的「这十册」「十册就全部结束」会被误报为错。
正确做法：python check_all.py 初中社会中考复习-*.html（一次传全部）。

已交付成果（10 册，2026-09-23）

合计 22.9 万字；每册 10 章、26 道折叠练习、54~70 个提示框；
check_all / validate_html / check_html_static 三项 10/10 全通过。

密度基线（供后续册次参考）：知识章 2100 ~ 4100 字（"考点表 + 方法 + 例析 + 练一练 + 提高"就是一个完整教学单元）；
"易错点清单" 800~1080 字、"知识地图与自测" 800~1130 字属正常（清单/索引类章节，不必补）。

★★★ 内容自检（十册做完后必跑，别只跑结构校验）

结构校验 ≠ 内容自检。 check_all / validate_html / check_html_static / verify_render
查的是"标签对不对、锚点通不通、字数掉不掉"，查不出"自测清单承诺的内容正文里没有""某个知识章忘了放考点表"
这类内容缺陷。社会系列交付前跑了 _refs/audit_soc_content.py，按 writing-principles.md 第七章逐条过，
当场查出 3 类真实缺陷。做新系列时把这个脚本复制过去改改关键词即可。

★★ ③ 的匹配器有个坑：自测项是"任务描述"（"说出经线与纬线在形状、长度、指示方向上的三点区别"），
正文是"知识陈述"（表格里写"形状 / 长度 / 指示方向"），措辞必然不同。
第一版要求整段短语逐字命中 → 报出 73 项假缺陷；改成"去掉动词虚词后取 2~6 字内容词、任一片段命中即算有出处"后，
真实缺口只剩 1 项。先怀疑匹配器，再怀疑内容。

★★ ⑦⑧ 的两个易误报：
- "相反表述同时存在"往往不是缺陷——黄河没有结冰期 只出现在错误选项里，南少北多 只出现在错误选项 + 易错点清单里。
查到这类要回到上下文确认，不要直接判错。
- 练习答案格式是 N. X（题号 + 点 + 空格 + 字母），不是 X.。正则写成 ^\s*([ABCD])\b 会全量误报。

★ ②⑥ 里两个必须"按设计豁免"的情况（否则每次跑都报错）：
- 方法册的 ch7 不是"易错点清单"，而是"答题骨架汇总表"（第 10 册就是这样），条数为 0 属正常；
- "教材版本说明"段是有意为之的 boilerplate，在 07/08/09 册 ch0 各出现一次是合理的（读者可能只读一册），
跨册重复检测要把它加进豁免名单。

交付前建议追加的抽查（人工，脚本替代不了）

1. 抽 3~5 道练习，把答案代回题干验算一遍——脚本只能查"答案字母在不在选项里"，查不出"答案本身选错了"。
2. 抽 1~2 个"一句话判据"，回正文确认它真的能判——判据若与正文规则不一致，学生会被带偏。
3. 抽查跨册引用的"语义"（不只是册号存在）——例如"第 01 册第 6 章的四口袋"要确认第 01 册第 6 章真有"四口袋"。

★★★ 第二轮深查（第一轮过完后，再查这四项）

第一轮查的是"有没有"，第二轮查"对不对、全不全"。社会系列第二轮又查出 2 类真实缺陷。

★★★ ④ 练习题重复（学生最容易感知、也最伤体验的缺陷）

社会系列第一版里，ch9 刷题区大量重复前面章节的练一练：第 09 册 6 道题全部重复，
第 07、08 册各 2 道，第 05、10 册各 1~3 处。根因是写 ch9 时偷懒，把对应章的练一练换个说法又写了一遍。

处理原则（重要）：
- 真正要修的：题干 + 选项都高度重合（同一考点、同一组选项）→ 换成同章尚未覆盖的另一个小节的角度。
- 必须保留的：刻意设计的易混对比题——如"第一个王朝（夏朝）vs 第一个统一多民族的封建国家（秦朝）"、
"最高国家权力机关 vs 最高国家行政机关"、"核心价值观国家层面 vs 社会层面"、
"限定'不利条件只写一面 vs 写'有利和不利'要写两面"。这些选项互为干扰项，是教学设计，不是冗余。
- 判据：看两题的选项是不是互为干扰项。是 → 保留；否 → 换掉。
- 换的时候先扫一遍该章所有小节，选一个没被考过的。我第一轮把"生命特点"重复题换成"火灾"，
结果撞上了 ch3 已有的火灾题，只好再换成"保持身心健康"——换题也要做一次重复检测。

★★★ ③ 题干丢失（脚本 bug 引发的批量损坏）

批量替换题目时我写了个辅助函数 q(stem, opts, ans, rubric)，第一个参数只传了题号（"6."），
题干文字没传进去 → 13 道题的题干变成只剩题号 + 选项。
更糟的是它通过了 check_all——因为 check_all 只校验"题干在 <details> 之前""答案有内容"，
不校验题干是否有文字。⇒ 新增硬检查：每个 <div class="q"> 的纯文本长度必须 ≥ 12 字。

★★ 批量改 HTML 的两个"丢包裹"陷阱（这次连续踩了两次）

用 t[:s] + newblock + t[e:] 做块替换时，s/e 的取法决定会不会丢标签：

# ❌ 陷阱一：s 取到 <div class="quiz">，但 newblock 里没带它 → 丢外层包裹
s = t.rfind('<div class="quiz">', 0, i); e = t.find('</details>', i) + len('</details>')

# ❌ 陷阱二：e 取到 </span>，中间那段 between（含 <div class="opts">）被丢弃 → 丢内层包裹
e = t.find('</span>', k) + len('</span>'); t = t[:e] + text + t[j:]

两次都表现为 validate_html.py 报"末尾深度为负"（-1 / -2 / -3 / -6），非常好定位。
✅ 替换后立刻跑一次 validate_html.py，深度必须为 0。
✅ 补救脚本要幂等：先判断"前面是不是已经有 <div class="quiz"> / <div class="opts">"，有就跳过
（见 _refs/fix_quiz_wrapper.py / fix_opts_wrapper.py）。

★★★ 第三方评审后的「实战化补强」（社会系列第三轮，2026-09-23）

评审人按"中考实战"标准逐册读完，提了 4 个问题 + 5 条建议。这一轮的改动对任何应试型系列都适用。

① 数据时效性 —— 所有具体数字都要"口径 + 来源 + 截止时间"三件套

★ 原则：教材口径与最新数据双写。 考试按教材口径答，但学生要知道现实在变——两个都写，比只写一个更负责。

② "凡是……就……"这类判据要留例外口

真实案例：本系列写过判据"句子里出现今天/明天说的是天气，出现全年/四季说的是气候"，
但"人间四月芳菲尽，山寺桃花始盛开"既不是天气也不是气候类型，而是地形对海拔气温的影响——
硬套判据就会判错。评审人直接点了出来。

改法（两步）：
1. 把那处判据改成"一般说的是……"，并补一段"但这个判据不是万能的"，给出上面那个反例；
2. 系统性加一条"判据使用说明"：在第 01 册 ch0（最早读的）和第 10 册的判据总表前各加一块 box warn，
写清"判据是快速定位的工具，不是万能公式；遇到不典型材料要回到原理推；判据与题干冲突时以题干为准"。

★ 扫法：grep -rn '凡是\|一定\|唯一\|必然' 后逐条分类——
"答题套路"类（如"答题时答案永远落在经济发展上"）可保留；"学科规律断言"类必须软化或补例外。

③ 方法册的"通用性"不能压过"学科特性"

评审人原话：三科答题逻辑差别很大——道法重"立场 + 原理 + 材料"，历史重"史实 + 史论 + 时序"，地理重"要素 + 逻辑 + 术语"；
一套"审题四步法"对道法够用，但历史"评价类"、地理"过程推断类"覆盖不足。

改法：每科各加一节「真题级示例（含评分细则）」，给出"材料 + 设问 + 评分细则 + 分层答案"四件套。
★ 评分细则才是这一节的核心价值——学生看答案只能模仿，看细则才知道"分从哪来"。
★ 细则要写清三种情况：答出什么得几分 / 什么写法不给分 / 只写某一种最多得几分。

④ ★★★ 真题正文拿不到时，用「官方试题评析」替代

社会系列的真题原文在 book118 / 人人文库 / 21cnjy / 学科网 全部需要付费或登录
（唯一"免费可见"的那份上传于 2026-04-17，早于 6 月考试 → 是模拟卷冒充真题，不能用）。

但省级教育考试院的《试题评析》是免费且权威的，信息量极大。本次从一份评析里拿到了：

• 题型结构的官方表述："通过降低判断题分值、提高综合题占比，缩减客观性试题比重" → 印证了判断题 6 分、综合题 54 分
• 各题的题号 + 材料主题 + 考查定位（如"第 27 题黄河三角洲种植业与 CCUS 示范工程""第 30 题林则徐 + 北斗团队"）
• 官方给的答题层次模型："事实辨识 → 因果分析 → 价值判断 → 行动建构" —— 可直接当骨架用
• 跨学科命题的官方确认："第 27 题（3）学生可以运用道德与法治、地理等学科知识……体现综合性"
• 命题人对考生的提示："整卷尽力搭设思维支架……题干中的提示语、材料中的注释、设问中的角度限定"

★ 这一条对所有"真题拿不到"的学科都通用：去找官方评析，不要去找真题。
搜法：<省> 中考 <科目> 试题评析 <年份>，站点试 zizzs.com / 省教育考试院官网 / 教研公众号。
★ 引用时写明出处（"据 XX 省教育考试院官方试题评析"），可溯源——可信度比自拟真题高一个量级。

⑤ 加「跨学科综合题」独立一章（方法册变 11 章）

真题已确认跨学科命题。新增一章讲：三种组合（地理+道法 / 历史+道法 / 地理+历史）、各科各答什么、
三条铁律（一问一科；分栏列要点；末问要"合"）、2 道含评分细则的示例。
★ 核心得分点是"两科各占一半，缺一科最多得一半分"——要写成细则里最醒目的一句。

⑥ 加「考场时间分配」与「错题归因表」

• 时间分配：按 100 分钟给出"判断题 5 + 选择题 25 + 综合题 55 + 检查 15"，点出三个时间坑
  （选择题恋战 / 综合题按顺序写 / 不检查），并提醒"时间不够时先保能拿的分"。
• 错题归因表：放在刷题区之后（做完题正好填）。表头 = 题号 / 考点 / 错因类型 / 正确思路 / 下次怎么避免；
  配"五类错因"（看错限定词 / 知识点记混 / 漏答要点 / 角度答偏 / 材料没用上）+ 2 行示例 + 5 行空行；
  再加一块"填满三次之后数哪类最多，回对应章节补"。★ 这张表把"预设的易错点"变成"你的易错点"。

⑦ 加自绘 SVG 示意图（只画非地图类）

评审人指出"没有图的地理复习材料，实用性会打折扣"。做法：

• 只画非地图类：等高线五种部位、气温曲线与降水柱状图、地球公转与二分二至、地势三级阶梯剖面。
• 涉及国界 / 海岸线的区域图一律不重绘（合规底线），改写成"请对照教材相应章节的图"。
• 实现：内联 <svg> 包在 <div class="fig"> 里 + <span class="cap"> 图注。
  ★ validate_html.py 的标签白名单已含 svg path g line circle ellipse rect polygon polyline text tspan defs marker，
  所以内联 SVG 不会被误报成"裸 <"——但必须全部小写。
  ★ .fig 的 CSS 只管 .fig img（位图），内联 SVG 要自己加 .fig svg{...}（写进 EXTRA_CSS）。
  ★ 图注里不要出现"如图/下图"（会触发 check_all ⑧ 的配图检查）——写"图 1""图 2"即可。
• 统一放 _refs/soc_figs.py，用 FIGS = {...} 字典按 key 取用。
• ★ 每张图配一句读图指令（"看图时只盯两件事……"），否则学生不知道看什么。

⑧ ★★ 章数超过 9 时要改脚本的单数字正则

方法册扩到 11 章（ch0~ch10）后，ch10 触发了两个脚本的单数字正则限制：
add_sidenav.py 的 <h2 id="ch(\d)"> 和 check_all.py 的 ch(\d) / href="#(ch\d)" ——
ch(\d) 会先匹配到 ch10 里的 ch1 然后失配，导致 ch10 不进侧栏、check_all 报"目录 11 条、h2 10 个"。

✅ 改法：全部改成 ch(\d+)（向后兼容，ch0~ch9 行为不变）。已改 add_sidenav.py 与 check_all.py。
★ 做超过 9 章的册子前，先确认这两处已是 \d+。

⑨ 审计脚本不要写死章节索引

方法册章数变了以后，audit_soc_content.py 里所有 secs[8] / secs[0:8] / struct[k][0][7] 这类
固定索引全部失效（把"易错点清单"读成了别的章）。改成 find_chap(secs, "关键词") 按标题找章。
★ 同时给"跨册重复段落检测"加boilerplate 豁免名单——错题归因表、真题示例说明、教材定位说明
这三类都是"每册都需自带一份"的，跨册重复属有意为之。

高中物理 / 高中生物系列（第十二、十三套变体：复用数学骨架 + 自绘 SVG 配图）

两套系列结构与流水线完全一致，只有学科内容、配图库与验算类型不同，
所以合在一节写。可直接当作「高中理科选考」的通用模板。

> 进度：高中物理 01~12 全部完成（2026-09-24 收官）；
> 高中生物 01~12 全部完成（2026-09-28 收官，37 918 行 / 135 图 / 2268 项验算）。
> ★ 批量生产多册时先读附录 A「一册一个 Agent 并行派发」；
> ★ 配图避坑看附录 C（比本节「五、配图铁律」更全，含 12 册实测汇总）。

一、共同点（与初中科学系列同源，但更严格）

二、9 段结构（toc 条目数 = h2 数 = 9）

★ 每个知识章固定五段：① 核心考点表 → ② 讲清为什么（box proof，用 ol.steps 分步推理）
→ ③ 典型例题（box eg，必须带「验算」环节，用两条独立路径互查）
→ ④ 练一练（div.quiz + details.ans-fold 折叠）→ ⑤ 本章判据小结（box tip）。

★ 提示框白名单（check_html_static.py 的 BOXES）：
def / proof / eg / warn / tip + exp / graph / fml / judge（物理、生物系列新增的四种）。
生物系列常用 box exp（检测实验）、box graph（读图卡）。

三、内容铁律（违反会被 audit_iron_rules.py 抓住）

1. 真题拿不到（实测各大题库站点全部拦截）→ 一律用「自拟典型题」，
   出处行标注「（示例，非真题）」。绝不凭记忆写真题。
2. 每册 ch8 放一张「当年官方评析点名的相关题型」表，
   只写「题号 + 情境概括 + 考查能力 + 对应本册章节」，不逐字引用题干。
   ★ 物理写「2025 年」、生物写「2026 年 1 月」（生物是 1 月首考）。
3. 避开会被体检误判为「试错痕迹」的词：重算、换个思路、调整：、
   正确答案是、让我重新、我搞混了。改用「另一种算法」「代入新数据」。
4. 单行不要只出现 1 个「……」（会被判为没写完）；一行两个以上或改成完整表述。
5. 正文禁用 <sub> / <sup> → 下标用 Unicode（CO₂、H₂O、v₀、x₁）或改写成文字。
6. 正文提「第 N 章」只指本册章号（0~8）；提教材章节写「必修1 第 3 章」
   （audit_chapter_refs.py 会自动排除紧邻 8 字符内有「必修/选必/选修」的章号）；
   提别的册写「第 03 册」。★ 引用本册章号时不要补零（「第 03 章」会被误判成册号）。
7. 术语必须与教材一致（生物卷的高频失分点）：「细胞呼吸」不写「呼吸作用」；
   「减数分裂 / 有丝分裂 / 同源染色体 / 姐妹染色单体」；
   「基因 / 等位基因 / 相对性状 / 表现型 / 基因型」；
   「内环境 / 稳态 / 神经冲动 / 突触 / 反射弧」；「种群 / 群落 / 生态系统 / 生物多样性」。

四、两套系列的验算类型（verify_*.py，每条都用两条独立路径互查）

• 高中物理：运动学（v=v₀+at、x=v₀t+½at²）、牛顿定律、圆周与万有引力、
  能量与动量、电场与电路、磁场与电磁感应、交变电流、光学（折射/全反射）、
  热学（气体定律、热力学第一定律）、近代物理（光电效应、能级、半衰期、质能方程）。
  ★ 正文声明了 π 取 3.14 时，验算脚本必须用同一个值（第 11 册实测踩过 4 项 FAIL）。
• 高中生物：① 肽键/脱水/相对分子质量（肽键数 = 脱水数 = 氨基酸数 − 肽链数，
  环状肽例外）；② 双链 DNA 碱基比例（A = T、G = C、A + G = T + C = 50%）；
  ③ 由元素质量分数反推分子质量（如血红蛋白含 4 个 Fe）；
  ④ 元素含量排序与分类计数（鲜重 O 最多、干重 C 最多）；
  ⑤ 膜层数换算（一层生物膜 = 2 层磷脂分子；单层膜细胞器 2 层、线粒体/叶绿体/核膜 4 层）。
  ★ 生物的 chk() 要支持字符串、布尔、集合、任意层嵌套的元组/列表
  （只支持一层数值会 TypeError）。
  ★ "相加"这一步也必须进验算脚本：生物 02 册实测把 4 + 1 + 2 写成 6（正确 7），
  连带磷脂分子写成 12（正确 14）—— 只验"乘以 2"那一步是查不出来的。
  写验算时要同时放「易错核对」（如"只算 1 个溶酶体会得 6"）作为反例锚点。

五、配图铁律（自绘 SVG，都是踩出来的）

> ★ 本节是最早的 16 条；12 册做完后又汇总了一份更全的清单（17 条，按自动检查查不出排序），
> 见 附录 C。两节一起看。

1. SVG 里绝不能出现 HTML 标签（浏览器会丢弃整个 <text> 的文字，
   而四层校验全查不出）。句内部分加粗只能用 <tspan font-weight='700'>。
2. 中文文案里禁用英文双引号 "（会破坏外层 Python 字符串）→ 一律用「」。
3. 长句必须拆行（x=56 起、12px 中文，一行最多约 41 字）。
4. path 里不要用 A（圆弧）命令 —— 自查第 ④ 项会把半径与标志位也当成坐标点
   而误报「图形越界」。圆弧一律改用两段三次贝塞尔（控制点偏移 = r × 0.5523）。
5. 正弦/曲线一律用折线逼近（每半周 12 段），不要用一段贝塞尔（会得到明显的「圆顶」）。
6. 符号阵列（⊙ / ⊗ / 电子）必须对准它标注的那个量的极值位置 —— 先把极值解出来再放符号。
7. 几何类图必须「先算后画」：折射光线要先算 atan2 夹角再定终点（第 12 册
   曾把折射角画得比入射角还大，是物理错误不是排版问题）。
8. 标签密集区用「锚点方向」错开：上下间隔 ≥ 20px、左右间隔 ≥ 12px；
   排不开就移到另一侧（anchor="end" / anchor="start"）。
9. 分组标签必须对准「组中心」：首柱 x + (柱数−1)×间距 ÷ 2 + 柱宽 ÷ 2，
   不要写成「组起点 + 常数」。
10. 结构式里的连线不要穿过文字：如氨基酸通式的四条键，要在离中心 14 px 处断开，
    否则竖线会从「C」字里穿过去。
11. 圆内文字必须真的比圆窄：落笔前先算 字数 × 字号 与 2r。
12. 注释句子要读一遍再交付：自查全过也挡不住「句子没写完」。
13. 彩色箭头必须配同色 marker。_line(..., color=ORANGE, marker="ar") 会让
    橙色的线配蓝色的箭头 —— 四项自查全查不出，渲染出来一眼就看出不搭。
    ⇒ 用 _arrow_defs(ORANGE, RED, …) 生成 ar2/ar3/ar4，再写 marker="ar2"。
14. 多面板图要逐个核对"图形是否越出自己那一格"。生物 02 册 f02_nucleus_exp
    的面板④把伞藻画成 y 100~280，而面板④只占 y 196~316 —— 整株穿到面板②里去了。
    越界检查只查画布、不查面板 ⇒ 多面板图必须逐格核对坐标范围。
15. "两段曲线接不上"要解方程，不要目测。膜线要与圆相切/相接时，
    解 x = cx ± √(r² − (cy − y线)²) 得端点（如 145±√(30²−10²) = 116.7/173.3）。
16. 交付前必查 <b> 与 </b> 数量是否相等。写正文时极易把加粗结束标签写成
    Markdown 的 **（生物 02 册 6 个片段各中招若干处，p7 里还因此留下了一段
    带禁词的"试错痕迹"）。
    bash for f in <片段>; do echo "$f $(grep -o '<b>' $f|wc -l) $(grep -o '</b>' $f|wc -l)"; done
    数量不等就逐行找；再 grep 六个禁词兜底。

六、配图自查与目视核对（两步都要做）

python _refs/phy_figs.py     # 或 bio_figs.py —— 4 项自查
# ① 无 HTML 标签  ② 无未知元素  ③ 无文字溢出  ④ 无图形越界
python _refs/shot_phypNN.py  # 或 shot_biogNN.py —— 渲染 PNG
# 然后用 Read 工具逐张人眼看

★ 「自查通过 ≠ 没问题」已被反复实证：
- 第 10 册 10 张图全部通过四项自查，人眼仍抓出 8 处缺陷；
- 第 12 册抓出 11 处（3 张图整张重画）；
- 生物第 01 册 11 张图全部通过自查，人眼抓出 3 处
（分组标签偏左、竖线穿过「C」字、圆内文字顶到描边 + 一句注释没写完）。

看图的正确姿势：整图看不出问题时，用 PIL 把可疑区域裁剪并放大 3~12 倍再看
（Image.crop + resize(LANCZOS)；SVG 坐标 → PNG 像素要先加页边距再乘截图缩放）。
可直接复用项目里的 _refs/_zoom01.py。

七、六层校验 + 6 个审计脚本

PY="C:/Users/g12363/.unvbuddy/binaries/python/versions/3.13.12/python.exe"
"$PY" _refs/build_phypNN/build.py                          # 构建
"$PY" _refs/check_all.py          "高中物理选考专题梳理-NN-*.html"   # L1 结构
"$PY" _refs/validate_html.py      "<文件>"                          # L2 结构
"$PY" _refs/check_macros.py       "<文件>"                          # L3 宏
"$PY" _refs/check_math_syntax.py  "<文件>"                          # L4 公式
"$PY" _refs/check_html_static.py  "<文件>"                          # L5 静态
"$PY" _refs/verify_render.py      "<文件>"                          # L6 渲染
"$PY" _refs/phy_figs.py                                             # 配图库自查

审计脚本全部支持传系列 glob，不传参数时保持初中科学的原行为：

★ audit_coverage.py 的两个关键设计（新建系列时必须照做）：
1. 每个系列必须有自己的关键词清单。若只有初中科学一套，
对高中系列会把初中模块全报成缺口（物理实测：139/221 缺失），等于审计完全失效。
2. 只检查「已经建册」的册次：从文件名抓 -NN-，mod[:2] not in vols
就跳过并打印「尚未建册，跳过」—— 免得建设期把「还没做的册」误报成「关键词缺口」。

八、validate_html.py 的 [待确认] 项不是噪音，必须逐条核对

已知良性假阳性两类：
- 「出现『第 N 章』交叉引用」→ 逐条看上下文：指本册章号（0~8）就对，指教材则须带「必修/选必」；
- 「使用了 MathJax CDN」→ 确认 skeleton-head.html 里有加载失败兜底提示即可
（成品里搜「公式未加载成功」应能命中）。

初中语文系列（第十四套变体：复用语文骨架，按能力专题分册，10 册）

> 浙江中考语文：满分 120 分（含卷面书写 3 分），120 分钟，19 道题，难度 7:2:1。
> 教材：统编版（部编版）初中语文 6 册；2024 秋起七年级先行换新教材 → 2027 中考是新教材首届。

★★ 与理科系列最大的差异：语文卷的真题拿得到

初中科学 / 高中物理 / 高中生物三个系列的实测结论是「7 个商业站点全拦截，只剩省考试院官网」。
语文卷不同：2026 年浙江中考语文卷的完整公开全文 + 参考答案可以从
微信公众号（如「方杰的语文世界」）、道客巴巴、人人文库、原创力文档、自主选拔在线（zizzs.com）
多处拿到，且多源一致、分值自洽（3+18+14+17+18+50 = 120）。

⇒ 因此初中语文系列的素材策略是三线并行（而不是理科的「只能自拟」）：
1. 官方评析定骨架 —— zjzs.net/art/2025/6/23/art_31_11386.html
（《浙江省 2025 年初中学业水平考试命题思路》语文部分，权威免费）；
2. 可溯源真题做精讲 —— 引用时写明「2026 年浙江省中考语文卷第 N 题」；
3. 自拟题打底 —— 标「（示例，非真题）」。

★ 做新学科前先花 2 分钟逐站验证：不要假设"上次拦截的这次还拦截"，
也不要假设"上次能抓的这次还能抓"。语文这次就是"以为拿不到、其实拿得到"的反例。

分册方案（10 册，按能力专题）

① 汉字积累与书写规范　② 词语、病句与标点　③ 古诗文名句默写与文学文化常识　④ 名著阅读
⑤ 文学类文本阅读（散文·小说）　⑥ 实用类与论述类文本阅读　⑦ 文言文阅读　⑧ 古诗词鉴赏
⑨ 写作　⑩ 中考题型精讲与综合运用（方法册）

★ 为什么不按板块名分册：2026 年五大板块按「语文实践活动」命名
（语言生活 / 文学编辑 / 好书推荐 / 说理艺术 / 表达交流），
2025 年按「主题」命名（山水家园 / 心灵家园 / 生态家园 / 文化家园 / 精神家园）——
板块名年年换，考的能力不变。所以按能力专题分册，教材和板块怎么调都不返工。

★★ 考情（2026 实卷核实）

★ 写作 50 分（41.7%）是单题最大项；现代文 31 分；古诗文 18 分；语言积累 18 分。

★★ 2025 官方评析里可直接复用的三条骨架

1. 三性定位：开放性（第 2、4、5、9、11、12、13 题）、综合性（第 2、5、9、11、12、13 题）、
   探究性（第 2、5、9、12、13、20 题）——每道例题都应标注它属于哪一性。
2. 「提供支架」被点名 4 次（第 1(2)(3)、4、6、14、15 题）。
   ★ 这条最重要：2026 卷把「知识卡片」直接印在卷面上
   （卡片 1 讲「陟」的字形与本义/引申义，卡片 2 讲「降贵纡尊」是敬辞），
   考的不是「背过没有」，而是「会不会用给出的线索推」。讲义必须照此训练。
3. 全卷「由易到难、层层递进」，前一板块为后一板块铺垫。

★★ 语文册的四个专属约定（做新册次时逐条过）

1. 骨架必须复制到项目 _refs/ 下。
   build_czyw_common.py 的 SKELETON_DIR 逻辑是「_refs/ 里没有就回退到技能 assets/」，
   而 _SKILL_DIR = dirname(HERE)（HERE 是 _refs/）算出来是项目根，
   于是回退路径成了 项目根/assets/ → FileNotFoundError。
   ⇒ cp 骨架到 _refs/ 即可（build_wk_common.py 也是这个约定）。
2. 单省略号是 FAIL，不是提示。本册用了 <div class="q">（题干常显的正确写法），
   check_all.py 的 profile 判定 '<div class="q">' in body → 进 czmath 档，
   第 ⑩ 项「一行仅 1 个 ……」从 note 升级为 FAIL。
   ⇒ 全册禁止「一行只有一个 ……」。这是文科册用 czmath 结构的隐性代价。
3. 册数与章号的写法：跨册写「第 03 册」，本册章号写「第 3 章」（不补零，
   补零会被 audit_chapter_refs 与 check_all 的册数正则误判）。
   check_all 第 ⑬ 项只认中文数字 ⇒ 写「全系列共 10 册」而不要写「这十册」
   （首册时 TOTAL_VOLS = 1，必然误报）。
4. 真题引用要标到「题号」：如「2026 年浙江省中考语文卷第 1 题（据公开流传版本整理）」；
   自拟题标「（示例，非真题）」。绝不凭记忆写中考真题。

语文册的章节骨架（9 章，ch0 ~ ch8）

ch0 写在前面（本册考什么占多少分 + 本册地图 + 全系列 10 册全景表 + 3 个常见误解 + 3 条学法建议）
ch1~ch4 知识章（每章五件套：核心考点表 → 讲清为什么(proof) → 典型例题(eg，**必带「验算」**)
                → 练一练(div.quiz + details.ans-fold) → ★ 提高板块）
ch5 ★ 提高板块（专章式：3 个专题，每专题 = 方法 + 例题）
ch6 易错点清单（15 条表格：易错点 / 正确做法）
ch7 知识地图与自测（.map 卡片 + .chain 核心链 + 自测 12 项，分「会认 / 会判 / 会答」三组）
ch8 中考题型精讲与刷题区（题型分布表 + **官方评析点名真题表** + 3 个题型精讲 + 提分要点 + 刷题区）

★ 语文的「验算」是什么：理科是两条独立路径算同一个量；
语文是两条独立路径证同一个结论——
例如字义推断题：「路径一 = 拆字形定本义再推引申义」「路径二 = 代入整句用搭配验证」；
错别字题：「路径一 = 追成语出处」「路径二 = 按字义配对看讲不讲得通」。

★ 新增的语文专用 CSS（在 build_czyw_common.py 的 EXTRA_CSS 里）

★ 骨架自带的 .quote（材料引用，含 .gloss / .src）正好用来放「知识卡片」——
浙江卷的支架型题目就是「卡片 + 设问」，用 .quote 装卡片最合适。

★ 已交付的第 01 册（可作模板）

初中语文中考专题梳理-01-汉字积累与书写规范.html —— 2235 行 / 151.3 KB / 6 张自绘 SVG / 侧栏 47 条。
六层 + 3 个审计全过（h2=9 h3=38 quiz=21 fig=6；源文本 25152 字 = DOM 25152 字，畸形标签 0）。

配图 6 张（chn_figs_01.py）：象形字古今对照 / 六书分类 / 形声字家族 / 笔顺七则 /
多音字三问法 / 「语言生活」18 分题型拆解。

★ 目视核对抓到 1 处真实缺陷（四项自查全查不出）：
f01_xingsheng 的「声旁：提示读音 qīng」居中放在 (310,146)，
正好落在五条汇聚箭头的扇面里被线条穿过 ⇒ 移到声旁圆的右侧（x=352, y=102）——
该高度箭头尚未起始（箭头从 y=120 才起），且已在圆右缘之外。
又一次印证「配图自查通过 ≠ 没问题，渲染成 PNG 逐张人眼看省不掉」。

附录 A　★ 多册批量生产：一册一个 Agent 并行派发

这是本技能最值钱的一节。 一个系列常有 10~12 册，逐册手写要几十小时；
用「一册一个 Agent」并行派发，实测 7 册在一轮内全部产出并验证通过
（高中生物 06~12 册就是这样做完的）。

9.1 派发前必须准备好四样东西（缺一样 agent 就会跑偏）

1. 分册方案文件（考情 + 册次映射 + 内容铁律 + 配图铁律）
2. 教材目录文件（让 agent 能逐节核对覆盖）
3. 上一册的完整实现 —— 这是最重要的模板。让 agent 照抄结构、只换内容。
4. 本技能中该学科对应的章节

9.2 brief 必须包含的六块（照抄下面的骨架，换学科即可）

① 任务：第 NN 册《册名》（教材来源），第 01~NN-1 册已完成，照它们的标准做，结构照抄、内容全新
② 必读清单（4 项，逐项注明"不要跳过"）：方案文件 / 教材目录 / 本技能相应章节 / 上一册的完整实现
③ 要产出的 5 组文件与命名规范：
   _refs/build_<前缀>NN/（build.py + p1_ch0 ~ p8_ch8）
   _refs/<学科>_figs_NN.py（图名一律 fNN_ 前缀，约 11 张）
   _refs/verify_<前缀>NN.py（每个数字两条独立路径互查）
   _refs/shot_<前缀>NN.py（由上一册改，换册号即可）
   成品 HTML（构建脚本自动输出到项目根目录）
④ 硬性要求：
   · 结构（toc=h2=9；每个知识章五段；提示框白名单；ch8 评析表不引题干）
   · 内容铁律（「（示例，非真题）」≥10 处；六个禁词；单行不许只有 1 个「……」；
     正文禁 <sub>/<sup>；「第 N 章」只指本册；术语用教材原词）
   · 配图铁律（见附录 C）
   · 交付前必须跑的校验命令（逐条列出）
   · 配图必须渲染 PNG 逐张人眼看
⑤ 回报格式：≤8 行 —— 进度一行 + 关键数字（行数/图数/验算项数）
   + **你人眼抓出并修掉的缺陷清单**（每条一句话）
⑥ ★ 边界：只写自己那一册的文件；**不要修改**共享的 <学科>_figs.py、
   audit_*.py、check_*.py、build_<前缀>_common.py，也不要碰其他册——有并行任务在跑

第 ⑥ 条（边界）必须写，否则并行 agent 会互相踩踏。

9.3 派发后必须做的三件事（一件都不能省）

1. 自己独立复跑一遍全部校验。 agent 的回报只是"它认为"，不是事实。
   实测两例：05 册被额度上限中断（缺 verify_biog05.py，我补写 103 项）；
   11 册的 agent 回报为空但实际已完成。
2. 逐张看配图（用附录 B 的去重绕过法）。agent 报的"人眼缺陷"数量可观且都是真的
   （各册 3~8 处），但它也可能漏看——尤其生物学/物理标注写错这类错误。
3. 全部册次建完后跑一次全系列终检：先重建全部册次（agent 可能只改了图源
   却没重新构建），再跑六层 + 全部审计 + 全部验算脚本 + 配图自查，最后出一份自检报告。

9.4 已知的派发风险

附录 B　配图复核：Read 工具的内容去重与绕过

Read 工具对 PNG 有内容去重：同一张图被读过一次后，再读（哪怕换了路径）
只会返回 Same image content as previously loaded，看不到图。
这在"agent 读过图、我要复核"时必然发生。

绕过方法：用不同的缩放倍数重新渲染 —— 像素内容变了就能正常显示。

PY="C:/Users/g12363/.unvbuddy/binaries/python/versions/3.13.12/python.exe"
"$PY" _refs/_reshot.py <册号>                       # 该册全部图，默认 3 倍
"$PY" _refs/_reshot.py 12 f12_gene_flow --scale 3    # 只渲染指定几张

_reshot.py 同时是放大复核的利器：3 倍下，细小的标注错位、引线贴边、
文字与线条间距不足，都能一眼看出来（这些正是自动检查查不出的）。

附录 C　自绘 SVG 避坑总清单（12 册实测汇总）

按「自动检查查不出」的程度排序 —— 前几条是最危险的。

★ 一句话总结：<学科>_figs.py 的四项自查（无 HTML 标签 / 无未知元素 /
无文字溢出 / 无图形越界）只能挡住一半。上面 1~12 条它全都查不出，
必须靠渲染 PNG + 逐张人眼。这一条在 12 册里被反复印证，每册都能抓出 3~8 处。

附录 D　验算脚本（verify_*.py）的通用要求

12.1 三条硬要求

1. 每个数字都要有两条独立路径，且两条路径要真的不同
   （如"先加后乘" vs "逐个换算再相加"、"棋盘法" vs "概率法"、"读表找极值" vs "看单调性"）。
2. "相加"这一步也必须进脚本。实测教训：某册把 4 + 1 + 2 写成 6（正确 7），
   连带下游数字全错 —— 只验"乘以 2"那一步是查不出来的。
3. 要放"易错核对"作为反例锚点（如"只算 1 个溶酶体会得 6"、
   "把 18 当总光合会漏掉 6"），把常见的错误算法也写进去，确认它不等于正确答案。

12.2 chk() 必须支持的比较类型

只支持一层数值的 chk() 会在遇到字典/嵌套结构时抛 TypeError。

12.3 学科专属的规范化（踩过坑才想得到）

• 遗传题必须规范化基因型：D + d 与 d + D 是同一个基因型，
  直接拼字符串会数出"16 格 16 种基因型"的假结果。
  ⇒ 写 geno1()（单基因座）与 geno2()（双基因座：显性在前、位点归并）。
  伴性遗传的 X^a X^A 也要规范成 X^A X^a。
• 生物表现型判定的下标：规范化后位点顺序会变，ph(g) 的索引要跟着改。
• 配图数值要与图源一致：最后一节「配图数值」必须和 <学科>_figs_NN.py
  的几何参数逐条对齐；改图后必须同步改这一节，否则等于没验算。

12.4 各学科的验算类型速查

附录 E　全系列终检清单（12 册收官时用的）

全部册次建完后，按顺序过一遍：

PY="C:/Users/g12363/.unvbuddy/binaries/python/versions/3.13.12/python.exe"

# 1) 先重建全部册次（agent 可能只改了图源没重建）
for n in 01 02 03 04 05 06 07 08 09 10 11 12; do
  "$PY" _refs/build_biog$n/build.py
done

# 2) 六层校验（★ glob 不要加引号，让 shell 展开；加了引号只会命中 1 个文件）
"$PY" _refs/check_all.py 高中生物选考专题梳理-*.html
for n in 01 02 03 04 05 06 07 08 09 10 11 12; do
  F=$(ls 高中生物选考专题梳理-$n-*.html)
  for s in validate_html check_macros check_math_syntax check_html_static verify_render; do
    "$PY" _refs/$s.py "$F"
  done
done

# 3) 6 个审计
G="高中生物选考专题梳理-*.html"
for s in audit_chapter_refs audit_chapter_titles audit_iron_rules \
         audit_structure_deep audit_coverage check_numeric; do
  "$PY" _refs/$s.py "$G"
done

# 4) 全部验算脚本 + 配图自查
for n in 01 02 03 04 05 06 07 08 09 10 11 12; do "$PY" _refs/verify_biog$n.py; done
"$PY" _refs/bio_figs.py

★ 收尾三件事：
1. 生成《全系列自检报告》（分册清单 + 校验结果表 + 主线），放项目根目录。
2. 抽查若干册的配图（用 _reshot.py --scale 3 绕过去重）。
3. 更新项目记忆（MEMORY.md 记全系列数字，当日日志记本轮做了什么）。

★ 高中生物系列收官数字（可作为其他系列的参照基线）：
12 册 / 37 918 行 / 135 张自绘 SVG / 2268 项数值验算 / 163 处「（示例，非真题）」；
六层校验 12/12、6 个审计全过、CHECK_BIO 222 词全命中。

13.1 高中生物 12 册的册次映射（可直接复用为模板）

分册的两条原则：
① 按「能力/知识模块」分册，不按教材章号机械切分 —— 教材 5 册 25 章拆成 12 册，
每册对应一个完整的知识板块；
② 内容多的章单独成册（如必修1 第 5 章「细胞的能量供应和利用」含酶/ATP/呼吸/光合
四大块，单独成第 03 册；必修1 第 3~4 章合并成第 02 册）。

13.2 合规红线（做涉及伦理/安全的内容时必须遵守）

第 12 册《生物技术与工程》含「生物技术的安全性与伦理问题」一章，落笔要点：
- 禁止生物武器：按我国立场写（《禁止生物武器公约》、我国一贯主张全面禁止和彻底销毁生物武器）；
- 生殖性克隆人：明确写我国不赞成、不允许、不支持、不接受任何生殖性克隆人的实验；
- 转基因安全性：写"应科学理性看待、依法管理、实行标识制度"；
- 绝不含任何可操作性强的危险操作细节。

同类内容（涉及国界的地图、涉及民族的表述、涉及政治敏感的内容）一律
按官方口径表述，宁可不写也不越界。

附录 F　★ 全系列「第二轮」自检：按教材目录逐节补缺（高中物理 12 册实战，2026-09-24）

> 第一轮全绿 ≠ 内容完整。 高中物理 12 册在「六层校验 + 6 个审计 + 2994 项验算 + 106 张配图自查」
> 全部通过之后，第二轮自检仍然抓出 12 处真实缺陷，其中 6 处是教材整节缺失——
> 六层校验、验算脚本、配图自查一条都查不出来。这一节就是第二轮的完整方法。

F.1 覆盖度审计的关键词清单必须「按系列切换」，否则审计会静默失效

• 现象：audit_coverage.py 虽然已支持传系列 glob，但关键词字典 CHECK 只有初中科学一套。
  传 "高中物理选考专题梳理-*.html" 时，221 个词里 139 个未命中，报出的全是
  「科学探究与测量」「光与声」「运动和力」这类初中模块 ⇒ 这个审计对本系列完全失效。
• 修法：新增 CHECK_PHY（按人教版 2019 六册目录逐节建），main() 改为
  按文件名自动切换清单（含「高中物理」→ CHECK_PHY，否则 CHECK）。
• 验证：高中物理 197 词全命中；初中科学回归仍 221 词全命中（无副作用）。
• ★ 通用教训：任何「按系列参数化」的审计脚本，都要检查它的判断依据是否也跟着切换了。
  只参数化「输入范围」、没参数化「判断标准」，比不参数化更危险——它会给你一个绿灯。

F.2 内容缺口只能靠「按教材目录逐节建关键词清单」发现

• 本轮 12 处缺陷里 6 处是整节缺失（都是人教版教材的正式内容）：

• 方法：把教材目录的节标题 + 核心概念逐条做成关键词清单，逐词在全系列全文里扫，
  命中数为 0 的即为完全没覆盖。清单必须逐节建，不能只建到「章」。
• ★ 再补一轮独立探测：_probe_kw.py / _probe_kw2.py 两轮共 256 个候选词
  （含 SVG 图内文字）交叉验证，确认没有别的整节缺失。
• ★ 关键词过细也会误报：第 04 册报「运动的分解」未命中，实际正文用的是教材原词
  「运动的合成与分解」——改关键词，不改内容。

F.3 新增内容的「量级」最容易被顺手写错 → 必须与验算脚本同步

• 现象：新增的德布罗意框里先写了「宏观 λ 比原子核尺度小 10¹⁶ 倍」
  与「两者相差 30 个数量级」。用 Python 复核：
  1 g 小球 λ = 6.63×10⁻³¹ m，电子 λ = 1.228×10⁻¹⁰ m ⇒ 比值 1.85×10²⁰ ⇒ 20 个数量级；
  核尺度 10⁻¹⁵ / 6.63×10⁻³¹ = 1.5×10¹⁵ ⇒ 约 10¹⁵ 倍。
• 修法：正文改成正确值，并把这两个数写进 verify_phyp12.py（round(log10(...)) 断言）。
• ★ 教训：新增内容的量级必须和验算脚本同步。否则下一轮验算「自己验自己」，
  永远发现不了——新增内容必须同时补验算项。

F.4 术语必须对齐教材原词

• 现象：第 11 册通篇写「初级线圈 / 次级线圈 / 初级电流」，
  人教版选必二 §3.3 用的是「原线圈 / 副线圈」。
• 修法：全文统一 17 处，并在「变压器的三条关系」表后加一条术语对齐说明
  （接电源一侧 = 原线圈（初级）、接负载一侧 = 副线圈（次级）；
  下标 1 一律指原线圈、下标 2 一律指副线圈）。
• ★ 讲义术语跟教材不一致，学生考试时「看着眼熟但不确定」，是隐性失分点。

F.5 人眼回溯：把「第 N 章」全部打出来逐条读

• audit_chapter_refs.py 只查越界，不查语义。第 09 册 ch2 例 1 写
  「本册第 1 章配图给出串并联结构」，但那张图实际在第 2 章——脚本报不出来。
• 方法：用 _scan_chapter_refs.py 把 12 册的 198 处「第 N 章」连上下文全部打印出来逐条读
  （其中教材章号 79 处、本册章号 119 处）：越界 0 条，但抓到 1 处语义错误。
• 配套：_scan_h2.py 提取每册 h2 章节目录，用于核对「引用的章号指向哪一章」。
• ★ 这是「脚本查边界、人眼查语义」的典型分工。

F.6 判据条数自检：正文说的 N 必须等于 <li> 数

• _check_judge_count.py 校验「这一章只需要记住 N 条判据」的 N
  与紧随其后的 <ol> 中 <li> 数是否一致。本轮抓出 3 处需要同步的改动
  （补内容后判据小结 5→6 条、6→8 条）。
• ★ 凡是「正文里出现了一个数、而它描述的是文档自身的结构」的地方，都值得写一个机械校验。

F.7 validate_html.py 的 [待确认] 良性只有两类（高中物理 24 条实测）

⇒ 所以 [待确认] 的条数应该稳定在「每册 2 条」。明显多于 2 条/册，就说明有新问题。

F.8 所有修改只落「源片段」，绝不直接改产物 HTML

• 改法固定三步：改 _refs/build_phypNN/pN_chN.html（源片段）或 verify_phypNN.py（源脚本）
  → 重建该册 → 重跑该册六层校验。
• ★ 直接改产物 HTML 会让「源片段 / 产物」永久不一致，下一轮重建就把修改冲掉。

F.9 并发安全：开工快照 + md5 前后比对 + 差异合并 + 收尾全量重跑

• 本轮自检期间同一个自动化任务有两个进程并发（两个 agent 同时在做同一步）。
• 处理：开工快照 → 收尾 md5 比对 → 差异合并 → 收尾全量重跑。
  比对结果：_refs/build_phypNN/ 下 108 个源文件只有 1 处差异，且是本进程自己的修改
  ⇒ 两个进程改的是不同册次，没有互相覆盖。
• ★ 开工前先检查是否已有同名进程在写同一批文件；确认方向一致就合并，
  最终态以最后一次全量重跑为准。

F.10 两轮改动后的重建规模（可作"补缺后应该变多少"的参照）

F.11 高中生物 12 册（2026-09-28 收官）的收尾数据 —— 可作"完工"的验收基线

• 验收口径：每册 h2=9 h3=33 quiz=6 题=30 答案=6；12 册六层全过；
  关键词 222 词全命中；内容铁律 12/12（示例标注 ≥10、评析表 1、禁词 0、单省略号行 0、SVG 内 HTML 0）。
• 主线一句话：细胞（01~04）→ 遗传（05~07）→ 稳态（08~09）→ 生态（10~11）→ 技术（12），
  全系列概括为「从『细胞由什么组成』到『人如何改造生物』」。
• ★ 全系列收尾时给一句「主线一句话」，读者一眼就知道这 12 册在讲什么——成本极低、收益很高。

参考文件

> ★ 使用方式：把需要的脚本 cp 到项目的 _refs/ 下再运行。
> extract_*.py 用 os.path.dirname(__file__) 定位素材目录（<项目>/_refs/gaokao/dataset/<学科>/），
> 放在技能目录里跑会因为找不到素材而报错；build_*_common.py 同理（它按「片段目录上溯两级」找输出位置）。
> 只有 validate_html.py / check_html_static.py / verify_render.py / add_sidenav.py /
> audit_*.py 可以直接在技能目录调用（它们接受文件路径或 glob 参数）。
> ★ Windows 下用引号包 glob 时 shell 不会展开，check_numeric.py 与 audit_coverage.py
> 已内置 glob.glob() 兜底，两种写法都能用。

一、写作规范与骨架资产

• references/writing-principles.md —— 完整的写作规范（8 章结构、五色框用法、六条硬性原则、技术约定、17 条常见缺陷清单）。

二、构建器（build_*_common.py，一册一个片段目录）

三、自绘 SVG 配图（框架 + 各册 *_figs_NN.py）

> 每个 *_figs.py 都自带四项自查（无 HTML 标签 / 无未知元素 / 无文字溢出 / 无图形越界），
> 但四项自查通过 ≠ 没问题——必须再渲染 PNG 逐张人眼核对（见附录 C、附录 E）。

四、六层校验（必须全绿）

辅助校验

• check_numeric.py —— 数值抽取核对（支持未展开的 glob）
• check_py_syntax.py —— 全部 .py 语法检查（高中物理实测 117 个文件）
• check_exam_transcript.py —— 真题原文逐词比对（抓「原文被改写」，只比答案查不出）
  bash python scripts/check_exam_transcript.py --db <database.json> --html <讲义.html> --targets <targets.tsv> # targets.tsv 每行：题号 <TAB> 年份 <TAB> 卷别关键词 <TAB> 空号

五、专项审计（audit_*.py）

六、人眼回溯与探测工具（_*.py，一次一用但很值钱）

七、素材提取与定点修补

• extract_zh.py —— 语文素材提取器（python extract_zh.py <模块>）
• extract_his.py —— 历史素材提取器（支持按时期筛选：python extract_his.py 解答题 古代中国）
• extract_sh_tex.py / extract_tex_figs.py / extract_sxs.py —— LaTeX / 试卷素材提取
• extract_mj_commands.py —— 生成 mathjax_commands.txt（MathJax 命令表）
• add_sidenav.py —— 侧边导航注入器（幂等，可重复运行）
• fix_answer_numbers.py / fix_quiz_stems.py / insert_fig_content*.py —— 定点修补（编号顺延、题干回位、插图）

八、配套脚本的"最小可用集"

做一门新学科，最少需要这几个（其余按需取）：

assets/   skeleton-head*.html + skeleton-tail*.html
scripts/  build_<系列>_common.py      ← 构建器（抄最接近的变体改）
          <系列>_figs.py              ← 配图框架（不配图就跳过）
          add_sidenav.py              ← 若构建器未内联注入
          check_all.py / validate_html.py / check_macros.py
          check_math_syntax.py / check_html_static.py / verify_render.py   ← 六层
          audit_coverage.py / audit_iron_rules.py / audit_chapter_refs.py  ← 审计
          verify_<系列>NN.py          ← 数值验算（自己写，见附录 D）

更新记录

v1.3.0 —— 2026-09-29（当天两轮）

第一轮

• 变体表补齐：高中生物一行从「01~02 已完成，建设中」→「01~12 全部完成」（六层 + 6 审计 + 2268 项验算 + 135 张配图全过）；
  初中语文一行从「01 已完成」→「01~10 全部完成」。
• 新增五个大章节（原顶层「九~十三」，本次改名为附录 A ~ E）：
  A 多册批量生产（一册一个 Agent 并行派发）、B 配图复核、C 自绘 SVG 避坑总清单（17 条）、
  D 验算脚本通用要求、E 全系列终检清单。

第二轮

• frontmatter 修正：description 的「含十三套变体」→「含十四套变体」，
  补上遗漏的初中语文（第十四套）及其触发词（description_zh / description_en 原本已含）。
• 结构重整：## 参考文件 从文中移到文末；原顶层「九、十、十一、十二、十三」改名
  附录 A ~ E，消除与「第九 ~ 十三套变体」的编号撞车；同步修正全部 § 交叉引用。
• 新增附录 F　全系列「第二轮」自检：按教材目录逐节补缺（高中物理 12 册实战，2026-09-24）——
  覆盖度清单必须按系列切换、整节缺失的发现方法、新增内容的量级必须与验算脚本同步、
  术语对齐教材、人眼回溯「第 N 章」、判据条数自检、[待确认] 的良性两类、
  只改源片段不直接改产物、并发安全，以及高中生物 12 册（2026-09-28）的收尾验收基线。
• 参考文件 章节重写：补全构建器 5 个、配图框架 4 个、专项审计 6 个、
  人眼回溯工具 6 个的清单与用法，并给出「做新学科的最小可用脚本集」。
• 并入后期新增的可复用脚本到 scripts/；
  audit_coverage.py（新增 CHECK_PHY）、check_html_static.py（BOXES 白名单加 exp/graph/fml/judge）、
  check_numeric.py（glob 兜底）同步到最新版。
• 版本号维持 1.3.0（语义上等同于需求里的「1.30」，不写成更低的号以免版本倒退）。

v1.0.0 ~ v1.2.0 —— 2026-09-20 ~ 09-23（回溯整理）