ZFY Math Courseware Final 数学课件制作技能（最终版）
安装后首次准备（SkillHub 发布版必读）
本包按 SkillHub 后缀白名单制作，不含二进制文件，也不含 .tex 文件
（PPTX 模板、KaTeX woff2 字体、Beamer 模板源码均未随原格式发布）。
首次安装后，在技能根目录运行一次：
python scripts/setup_assets.py --author "你的姓名" --institute "你的单位"
它会完成四件事：
- 下载 KaTeX 0.16.9 的 20 个 woff2 字体到
assets/vendor/katex/fonts/（联网一次即可）； - 调用
scripts/ppt_template.py生成assets/ppt_template.pptx（真母版 + 11 个版式）； - 从
assets/beamer_courseware_template.md还原出assets/beamer_courseware_template.tex； - 把包内
{{AUTHOR}}/{{INSTITUTE}}占位符替换为你自己的署名。
Beamer 模板为什么是 .md：SkillHub 的白名单不含 .tex，因此把完整 LaTeX 源码
装进 Markdown 的代码块里发布，安装脚本原样提取还原，内容一个字节不差。
随后在 scripts/ 下执行 npm i 安装 puppeteer-core（仅 HTML 验证脚本需要）。
若当前完全无外网，HTML 联网版仍可经 CDN 使用；离线版待联网后补字体即可。
斜杠命令：把 commands/math-courseware.md 复制到 ~/.codebuddy/commands/
（或 ~/.workbuddy/commands/），即可用 /math-courseware 矩阵的秩 直接调用本技能。
> 本技能为数学课件制作的最终版与首选技能。凡涉及数学课件（HTML/PPTX/PDF/Beamer）、
> 公式渲染、交互动画、翻页笔、课堂测试、教室字号适配等需求，优先命中本技能。
零、加载即弹窗（最高优先级，必须执行）
本技能被触发后、开始制作任何课件前，若用户未一次性给齐选项，必须用 AskUserQuestion
一次性问完下列 9 问，不得只在正文里问，也不得跳过任何一项直接默认堆满动画。用户已明确
给出的选择不重复问；用户说"你决定"时按第一节末尾的默认值执行。弹窗未完成前不得动笔写课件。
弹窗 9 问（多选项用 multiSelect）：
1. 课件用途：授课 / 报告 / 汇报 / 展示 / 背景
2. 教室类型 × 听众数量：小型教室 / 中型教室 / 大型教室；听众 30 以内 / 31–60 / 61–120 / 120+（据此由 layout_settings.room_scale 得字号缩放系数）
3. 产物类型（多选）：PPTX / HTML / Beamer(PDF) / Markdown 教案 / 全部都要
4. 配色方案（多选）：商务蓝 / 黑白灰 / 青紫蓝 / 学术深蓝 / 松烟青绿 / 全部
5. 导航条 + 教鞭 + 动画频次 + 正文字体：导航位置（顶/底/左/右/无）；是否用电子教鞭；页内动画（丰富逐行/适中按逻辑/精简按页）；HTML 正文字体（衬线学术/无衬线投影更清晰）
6. 可见要素（多选）：封面 / 目录 / 转场过渡 / 总结致谢 / 作业页
7. 测试与作业（多选）：课前测试 / 课中测试 / 课后测试 / 课后作业 / 全部都要 / 不添加
8. 是否联网：有网（仅联网 CDN）/ 无网（联网+离线双版，离线版内嵌 KaTeX+three.js，断网可用）
9. 课程思政 + OBE 理念：思政+OBE（推荐）/ 仅思政 / 仅 OBE / 都不插入（见 references/ideology-obe.md）
制作三类可靠产物，按用户选择执行，不擅自默认堆满动画：
- HTML 交互课件：KaTeX 公式完整渲染、three.js 动画可操作、逐步推导与翻页笔可用。
- PPTX 课件：公式是 PowerPoint 原生 OMML 对象，不用公式图片；按选择加入原生动画、切换与交互媒体。
- PDF 课件：XeLaTeX + Beamer 生成，16:9，内置覆盖动画、TikZ 分步、按钮、OCG 图层，可选 animate 逐帧与视频。
三类产物均支持课前/课中/课后测试与课后作业，坚持"先题后答"。默认署名为占位符 {{AUTHOR}} / {{INSTITUTE}}：首次安装时用 setup_assets.py --author/--institute 指定，或在 9 问弹窗中由使用者提供。
一、开始前必须确认选项
先判断用户要哪些产物、是新建还是修复。新建前必须用弹窗（AskUserQuestion）确认，不得只在正文里问，也不得未经询问默认堆满动画。一次问清，用户已给出的选择不重复问：
- 课件用途：授课 / 报告 / 汇报 / 展示 / 背景。决定内容密度与动画风格（授课重推导分步、报告重结论数据、展示重视觉、背景重概览）。
- 教室类型 × 听众数量：小型教室 / 中型教室 / 大型教室；听众 30 以内 / 31–60 / 61–120 / 120 以上。据此由
layout_settings.room_scale得出字号缩放系数，适配投影可视距离：HTML 调--font-scale、Beamer 映射字号档位、PPTX 全局缩放set_font。 - 产物类型（多选）：PPTX / HTML / Beamer(PDF) / Markdown 教案，另给「全部都要」——多选时分别生成对应产物，输出到同一目录。Markdown 教案基于
assets/lecture_template.md生成，公式复用$...$约定。 - 配色方案（多选，各产物通用，必问）：五套见
references/color-schemes.md——高端大气商务蓝（默认）、简洁优雅黑白灰、轻奢淡雅青紫蓝、学术深蓝、松烟青绿。多选时逐套生成，文件名追加方案短名，所选各产物都要生成对应配色版本，输出到同一目录。三产物配色由单一数据源scripts/color_schemes.py统一驱动。 - 导航条 + 教鞭 + 动画频次 + 正文字体：导航位置（顶部/底部/左侧/右侧/不显示，HTML 用
--nav）；是否用电子教鞭（HTML 用--pointer on，鼠标/触控笔跟随高亮）；页内动画三档（丰富=逐行/适中=按逻辑/精简=按页，HTML--anim、PPT--anim、PDF 覆盖动画密度对应）；HTML 正文字体（衬线=学术风格，默认；无衬线=投影远距离更清晰，HTML 用--font sans）。字体只影响 HTML 正文与标题，KaTeX 公式字体不变。 - 构成要素（多选）：封面页 / 目录页 / 转场过渡页 / 总结致谢页 / 作业页。缺省仍给封面+目录+总结致谢。
- 测试与作业（多选）：课前测试（上节/前置知识，置于正课前）、课中测试（一个完整单元后强化，紧跟知识点之后）、课后测试（课程结束巩固，置于最后）、课后作业（本节知识点习题），另给「全部都要」与「不添加」。
- 是否联网：有网（只用联网版 CDN）；无网（同时产出「联网版」与「离线版」两版——离线版把技能内置
assets/vendor/的 KaTeX + three.js 随课件复制，断网可用）。离线版优先。 - 课程思政 + OBE 理念（必问）：课程思政 + OBE（推荐）/ 仅课程思政 / 仅 OBE 成果导向 / 都不插入。格式见
references/ideology-obe.md——每单元末一页「课程思政与 OBE 理念」：思政主题 + 4 条要点；OBE 本讲目标 + 知识/能力/素养三层 + 以终为始可量化成果；收尾箴言「格物致知 → 以终为始·成果导向·持续进步 → 止于至善」。PPTX 用build_ppt.py --ideology both，HTML 用模板.ideo-card屏，Beamer 用block/exampleblock帧，Markdown 用对应小节。
用户明确一次性给齐选项时不重复问；用户说"你决定"时，采用少量分步动画（适中档），媒体选 HTML 交互入口，配色高端大气商务蓝，测试不擅自添加，默认离线+联网双版、不用教鞭、中型教室×31–60 人（字号 ×1.00）、顶部导航、授课用途、封面+目录+总结致谢、课程思政+OBE（推荐）。无网络时 HTML 用 --network both 同时出两版并复制 vendor/；PDF/PPTX 本不依赖外网。媒体缺依赖时说明并让用户改选，不得静默换成另一种方案。
Morph 只用于相邻页有共同对象、连续形态变化的内容；普通章节换页用 Fade 更稳妥。PPT 页内动画优先进入特效（Appear），页间配合 Morph 平滑强化观点。PDF 交互动画优先用全阅读器通用的覆盖动画与按钮，animate/视频交付时注明阅读器要求。
二、硬性质量要求
- HTML 公式用 KaTeX；独立公式写
$$...$$，行内写$...$。分式用\frac{分子}{分母}，不要用/冒充上下分式。行内分式用\frac，只有独占一行的主公式才用\dfrac——行内硬上\dfrac会把行距撑高、看着比正文大一圈。 - 公式字号与正文「视觉等高」：KaTeX_Main 的字形比中文正文字体高约 6%，所以
.katex{font-size:.94em}、块级.formula .katex{font-size:.96em}（实测行内 0.94×、块级 1.20× 正文）。不要改回1em，那就是用户说的「符号比同行文字大」。 - 希腊字母 ε 一律写
\varepsilon，不写\epsilon（后者是月牙形变体，字形偏小、与教材排版不符）。 - 数学符号必须进公式：
$n\to\infty$、$x\in[0,1]$、$s\approx1.479$、$L_n$。不要用普通文本的→、∞、∈、≈、x²、Lₙ充数（那是文字符号，不是公式）——这是「部分数学符号没渲染成公式」的典型来源。 - 与中文混排的数学变量必须包进数学模式才斜体：向量
$a$、点$n$、分量$(a_1,a_2,\dots,a_n)$、区间$[a,b]$，一律不要写成正体汉字旁的裸字母。HTML 与 PPTX 同样遵守；写完跑scripts/audit_latex_delimiters.py查缺$，再跑scripts/audit_math_symbols.py复查裸变量（如a_1不在数学模式）、中文省略号……当数学省略号、向量/矩阵后跟的字母（如「向量 n」的 n）未斜体。audit_math_symbols.py通吃 HTML/PPTX/TeX，只报告不改。 - canvas/three.js 动画上的数学标签（如 $f(x)=x^2$、$x_0=1$）必须用 HTML 绝对定位叠加层（
.viz-label）让 KaTeX 渲染，不得用ctx.fillText画正体字符串；动画中不等式符号在 HTML 源码里写<>，否则定界符审查误报。 - HTML 写完必须先跑
scripts/audit_latex_delimiters.py，处理缺前/缺后$、未闭合、裸变量未斜体，再跑浏览器实测。 - PPT 公式只走 LaTeX → MathML → OMML，嵌入
<a14:m>，不得用 PNG/SVG 公式代替。 - PPTX 必须是真母版 + 真版式驱动：
assets/ppt_template.pptx里有 1 个母版和 11 个版式（封面/要点/过渡/思政两栏/定义/定理/例题/习题/展示/归纳/测试），页面只往占位符里填内容，不允许再add_slide(slide_layouts[6])后逐个add_textbox手画骨架。母版版式里的装饰一律用a:schemeClr着色，换配色只改主题。 - PDF 用 XeLaTeX 编译、
aspectratio=169、ctex 中文；主题后必须\usefonttheme{professionalfonts}让数学公式标准；含代码/视频的帧必须加fragile。 - PDF 模板已全局重定义
\lim/\sum/\prod/\max/\min，行内巨算子下标自动显示在正下方，无需手加\limits（手加为无害冗余）；个别行内公式因此过高时改用行间公式\[...\]。 - PPT 巨算子 lim/sum/prod 下标版式用
--limit-placement below/right切换（below=正下方，right=右下角），默认 below。 - 代码高亮用 minted：minted v3 后端是
latexminted，旧版是pygmentize；构建脚本自动配 PATH 并开-shell-escape。 - 测试必须“题目初始可见，单击后答案出现”，绝不能把题目也隐藏。
- 测试题型要多样（判断/单选/多选/填空/排序五类），题量建议 课前 2–3 + 课中 3–5 + 课后 3–5（全课 ≥10 题）；同一测验内正确答案位置要打散，不得全 A；连线/分类仅作讲授页巩固，不进正式测验（见
references/assessment-types.md）。 - 课程思政 + OBE 理念按弹窗第 9 问插入：每单元末一页，思政要点须与本讲知识点真关联、OBE 写「知识/能力/素养 + 可量化成果」（见
references/ideology-obe.md）。 - PPTX 每页必须写备注栏讲稿/扩展提示（
build_ppt.py默认写DEFAULT_NOTES，--no-notes可关）；放映时演讲者视图可见。 - 所有产物必须实跑或读回验证。缺少渲染环境时，只能声称结构校验通过，并提醒用户在授课软件中放映核对。
三、PDF（Beamer）主流程
工作流与动画目录见 references/pdf-beamer.md，个人排版约定见 references/latex-style-guide.md。
- 生成脚手架：
bash python scripts/new_beamer_project.py --title 定积分的概念 --outdir lecture06 # 多文件工程加 --project python scripts/new_beamer_project.py --title 泰勒公式 --project # 按弹窗选择的配色生成（多选逐套输出，文件名追加中文短名） python scripts/new_beamer_project.py --title 定积分 --color-scheme pine-teal crimson python scripts/new_beamer_project.py --title 定积分 --all-schemes # 字号缩放（教室×人数，映射到 Beamer 字号档位 10/11/12/14/17pt） python scripts/new_beamer_project.py --title 定积分 --font-scale 1.24 - 在模板标记处填写内容，遵守
references/latex-style-guide.md的色板、命令与排错约定；按弹窗选择的配色，用references/color-schemes.md中对应方案整段替换模板的\definecolor块；多选时逐套生成 PDF。思政/OBE 按第 9 问保留或删除模板末尾「课程思政与 OBE 理念」帧（格式见references/ideology-obe.md）；多题型练习帧可按需保留。模板底部自带两级进度条（一级=节进度、二级=帧进度，节数由 totcount 自动统计），编译两遍后准确，不要删除 footline 定义。 - 构建（自动发现 TeX Live、修复系统 PATH、配置高亮后端）：
bash python scripts/build_pdf.py 课件.tex - 验证：
bash python scripts/verify_pdf.py 课件.pdf --tex 课件.tex - 放映模式实点，再交付 PDF；含外部媒体时连同媒体文件夹一起打包。
交互动画按兼容性选择：覆盖动画（pause/only/uncover）与按钮全阅读器通用；TikZ 路径覆盖用于分步图形；ocgx2 图层用于点击显隐；animate 逐帧与视频需 Adobe Reader，交付注明。
四、HTML 主流程
骨架为 assets/courseware_template.html，细节见 references/html-courseware.md。模板默认本地 vendor/ 引用（离线可用），仿 PPT 全屏分页：每屏一屏展示、屏间 fade+位移切换、屏内逐条播放；不显示翻页笔/拖动/滚轮等固定操作提示，鼠标悬浮动画区才浮动显示操作提示；公式尺寸已约束（行内公式与正文同字号、块级公式仅略大，绝不超出正文）；多配色/多联网方式/教鞭/导航/字号/正文字体/动画频次统一由 scripts/build_html_schemes.py 产出。模板默认 --font-scale:1.1（比旧版整体放大 10%），正文默认衬线，--font sans 切无衬线（投影更清晰）。
# 按弹窗选择的配色 + 网络条件 + 教鞭 + 导航 + 字号 + 动画频次生成
python scripts/build_html_schemes.py 课件.html --color-scheme business-blue --network both --pointer on
# 无网络：同时出联网版(CDN)与离线版(本地 vendor，自动复制 vendor/ 到输出目录)
python scripts/build_html_schemes.py 课件.html --all-schemes --network both
# 仅联网版 / 仅离线版
python scripts/build_html_schemes.py 课件.html --all-schemes --network online
python scripts/build_html_schemes.py 课件.html --all-schemes --network offline
# 启用电子教鞭（鼠标/触控笔跟随高亮）
python scripts/build_html_schemes.py 课件.html --color-scheme business-blue --pointer on
# 导航条位置（顶/底/左/右/无）+ 字号缩放（教室×人数）+ 动画频次（逐行/逻辑/按页）
python scripts/build_html_schemes.py 课件.html --nav bottom --font-scale 1.24 --anim rich
python scripts/build_html_schemes.py 课件.html --nav left --font-scale 1.10 --anim moderate
# 正文字体：serif 衬线（默认）/ sans 无衬线（投影远距离更清晰）
python scripts/build_html_schemes.py 课件.html --font sans --network both
- 公式：KaTeX 就绪后在
window load时对document.body整篇调用renderMathInElement，不要只处理[data-math]。
动态写入的公式必须补渲染：脚本里innerHTML含$...$的，写完立刻window.__tex(容器)；textContent带公式的改innerHTML再__tex。load时那一遍扫不到之后才塞进 DOM 的文本，否则交互区会留着裸露的$k=2$、$r_2\leftarrow r_2-2r_1$。canvas 的fillText画不出公式，公式只能放叠在画布上的 DOM 层（.sim-formula）。 - 定界符审查：
bash python scripts/audit_latex_delimiters.py 课件.html
错误逐项修正；slash-fraction是提醒，确认需要上下分式时改\frac。脚本只报告不改原文。
再跑python scripts/audit_math_symbols.py 课件.html复查裸变量/中文省略号/向量字母未斜体。 - 3D：
THREE.ParametricGeometry回调用target.set(x,y,z)，不是target.push(...)；创建后geo.computeVertexNormals()；makeViz返回组用v.group。 - 仿 PPT 翻屏与页内动画：每
<section class="section">是一“屏”，全屏展示。屏内.steps .step为推导步骤、.reveal为逐行要点（列表项/公式行/要点，加.on高亮），按屏内顺序逐条点亮；全部点亮后切到下一屏；后退反之。空格、方向键、鼠标点击空白、翻页笔、触屏均可前后翻屏。动画频次由data-anim控制：rich逐条、moderate按逻辑、minimal整页（CSS 已全亮）。屏间用.active/.leaving切换（fade + 位移）。
翻页节奏必须在屏上标注data-flow：page= 整页翻（封面、目录、转场页、纯展示页），line= 屏内逐条（有.step/.reveal的正文页）。不标时自动判定（有动画元素即line）；封面/目录一律显式写page，否则目录卡片会被当成逐条点亮。
单屏适配：.section用justify-content:safe center，内容超高时顶部不被挤出可达区；成品在 1920×1080 下应逐屏无滚动（可用无头 Chrome 量scrollHeight校验）。 - 测试：复制骨架中的
.quiz、.quiz-answer和显答脚本，点击先显示解析再继续翻页。 - 多题型：
.quiz-multi（多选勾选 → 提交判定）、.quiz-fill（填空输入 → 检查）、.quiz-sort（点击两项交换 → 检查排序），均即时判定并展开解析；题型/数量与出题规范见references/assessment-types.md。 - 仿真实验：
#sim屏用 2D canvas +<input type=range>做参数滑块（如折线逼近、黎曼和、割线趋近切线），拖滑块实时重绘并显示数值收敛，不依赖 three.js。 - 思政/OBE：
.ideo-card屏（思政要点 + OBE 知识/能力/素养三层 + 箴言），按弹窗第 9 问决定保留哪些块。
五、PPT 主流程
公式与版式见 references/ppt-omml.md，动画与媒体见 references/ppt-animation-media.md。
结构：母版 + 版式，不是手画页面。 scripts/ppt_template.py 一次性生成 assets/ppt_template.pptx（1 个母版 + 11 个版式），scripts/build_ppt.py 打开这个模板，每页 = 「选版式 + 填占位符」：
| 版式 | 用途 | 占位符 idx |
|---|---|---|
| 01 封面 | 封面、致谢（深色满屏） | 0 主标题 / 1 副标题 / 2 主旨句 |
| 02 要点讲解 | 通用内容页 | 0 标题 / 1 正文 |
| 03 章节过渡 | 章节页（深色满屏） | 0 章标题 / 1 章说明 |
| 04 思政两栏 | 思政 + OBE 并排卡片 | 0 标题 / 1 左栏 / 2 右栏 |
| 05 定义 | 蓝条放术语 + 定义正文 | 0 标题 / 1 术语 / 2 正文 |
| 06 定理 | 绿条放定理陈述 + 证明 | 0 标题 / 1 陈述 / 2 证明 |
| 07 例题 | 红条放题干 + 解答 | 0 标题 / 1 题目 / 2 解答 |
| 08 习题 / 09 展示 / 10 归纳 | 清单、多块要点、表格页 | 0 标题 / 1 内容 |
| 11 测试题 | 题注/题干/选项/答案解析 | 0 标题 / 1 题注 / 2 题干 / 3 选项 / 4 答案解析 |
标题占位符里第二段自动放小字标签（fill_title(title, tag)）；标题位置、顶部金线、色条、卡片底、页脚署名、页码都在母版/版式里，改样式只改 ppt_template.py 的 LAYOUTS 一处，重跑模板即可全局生效。另有 ideology_slide（思政+OBE）、assessment_slide（多题型：判断/单选/多选/填空/排序，ASSESS_BANK 题库）、set_notes/DEFAULT_NOTES 写每页备注讲稿。
改了版式后必须重跑模板，否则 build_ppt.py 会因为版式顺序/名字对不上直接报错（这是故意设的护栏）：
python scripts/ppt_template.py assets/ppt_template.pptx
依赖：
pip install -i https://pypi.org/simple latex2mathml mathml2omml python-pptx lxml
所有含反斜杠的 LaTeX Python 字符串必须写 r"..."，避免 \f/\t/\n 被转义。
- 构建：
scripts/omml.py与scripts/build_ppt.py，按第一节弹窗结果传参，不默认all：
bash python scripts/build_ppt.py -o 课件.pptx --anim rich --transition fade --assessments none # 动画频次三档：rich 逐对象 / moderate 按逻辑组 / minimal 按页（--animate 等价 rich，旧兼容） python scripts/build_ppt.py -o 课件.pptx --anim moderate --transition morph # 巨算子下标版式：below=正下方（默认）/ right=右下角 python scripts/build_ppt.py -o 课件.pptx --limit-placement right # 字号缩放（教室×人数） python scripts/build_ppt.py -o 课件.pptx --font-scale 1.24 # 按弹窗选择的配色生成（多选逐套输出，文件名追加中文短名） python scripts/build_ppt.py -o 课件.pptx --color-scheme pine-teal crimson python scripts/build_ppt.py -o 课件.pptx --all-schemes # 课程思政 + OBE 页（both/ideology/obe/none）+ 每页备注讲稿（默认写，--no-notes 关闭） python scripts/build_ppt.py -o 课件.pptx --ideology both python scripts/build_ppt.py -o 课件.pptx --assessments all --ideology both python scripts/build_ppt.py -o 课件.pptx --ideology none --no-notes - 动画与切换：
scripts/ppt_effects.py。页内默认 presetID=1"出现"进入特效；--anim-freq三档（rich 逐对象、moderate 按group_shape_ids按行聚组、minimal 按页）。Morph 写p159:morph option=byObject并带 Fade 回退，用于相邻页共同对象的连续形态变化，强化观点。
bash python scripts/ppt_effects.py 原稿.pptx 输出.pptx --animate --anim-freq moderate --transition morph - 交互媒体：
scripts/media_tools.py每次处理一种（HTML 入口、MP4、GIF、Manim）。交付时保留 PPTX 与同名_assets文件夹，链接用相对路径。
bash python scripts/media_tools.py 原稿.pptx 输出.pptx --slide 4 --html 交互页.html
六、验证与交付
# PDF
python scripts/verify_pdf.py 课件.pdf --tex 课件.tex
# HTML
python scripts/audit_latex_delimiters.py 课件.html
python scripts/audit_math_symbols.py 课件.html
node scripts/verify_courseware.js 课件.html # A公式 B动画 C报错 D翻页节奏 E先题后答 F动态公式 G全程走查
# PPT
python scripts/check_pptx.py 课件.pptx # 包级合规自检（结构/动画/备注），退出码 1 = 有问题
python scripts/verify_ppt.py 课件.pptx
python scripts/verify_ppt_effects.py 课件.pptx --require-appear --require-transition fade
python scripts/audit_math_symbols.py 课件.pptx
# TeX 源
python scripts/audit_math_symbols.py 源.tex
最终在对应软件放映核对：PDF 覆盖顺序与按钮、OCG/animate 显隐；HTML 公式、canvas、翻页、先题后答；PPT 公式可编辑、出现顺序、Morph、媒体播放。HTML 媒体与外部视频方案分享时打包整个交付目录，不能只发单个文件。
verify_courseware.js 的 F 段会自动点一遍所有交互控件（子式挑选器、分步演示、滑块），再全文扫描有无裸露的 $ ——这是「交互区公式不渲染」的回归测试；D 段核对 data-flow="page" 屏整页翻、line 屏逐条亮；G 段从首屏连按空格走到末屏，确认全程无报错、不卡死。
七、常见修复
| 现象 | 根因与处理 |
|---|---|
| PDF 代码帧编译异常 | 帧加 fragile；代码块不包 overlay 命令；minted 后端装 latexminted |
| PDF 页面跳动 | \only 换成 \uncover，预留占位 |
| Missing $ inserted | TikZ 节点下划线转义 \_，或中文符号误入数学模式 |
| animate/视频不播放 | 换 Adobe Reader，媒体随 PDF 一起交付，用相对路径 |
| 公式仍是 LaTeX 源码 | 先跑定界符审查；确认 load 后整篇 KaTeX 渲染 |
| 交互区里的公式不渲染（矩阵报表、步骤操作名、滑块维数等） | 这些内容是脚本 innerHTML 在 load 之后写入的，首轮 renderAllMath 扫不到。写完立刻 window.__tex(容器)；textContent 带公式的改 innerHTML 再 __tex。canvas 用 fillText 画的公式换成叠加 DOM 层（.sim-formula + __tex）。改完用 verify_courseware.js 的 F 段回归 |
| 封面/目录页按一下只亮一条，翻不过去 | 该屏被判定成 line；显式写 data-flow="page" |
| 正文页要按好几下才出现内容 | 该屏标了 data-flow="page"，或 .step/.reveal 缺失；改回 line 并给要点加 .reveal |
| 某一屏在投影上顶部被切掉/看不见标题 | .section 用了 justify-content:center 导致超高内容上溢；改 safe center，并压缩该屏内容直到 1920×1080 无滚动 |
| 分式只有斜线 | / 改为 \frac |
| 3D 空白 | 查 target.push、group 裸用；改 target.set、v.group |
| PPT 公式不可编辑/乱码 | 删公式图片改 OMML；LaTeX 字符串加 r 前缀 |
| 数学符号不斜体 | 中文混排的变量/分量/向量字母没包进 $...$；跑 audit_math_symbols.py 逐条修正（裸 a_1、中文省略号 ……、向量 n 的 n 等） |
| PPT 巨算子下标位置不对 | build_ppt.py --limit-placement below（正下方，默认）或 right（右下角） |
| 测试答案一开始就在 | HTML 给答案 hidden；PPT 只对答案加动画；PDF 答案放 \pause 后 |
| PPTX 每页没有讲稿备注 | build_ppt.py 默认写 DEFAULT_NOTES 到备注栏；若加了 --no-notes 则关闭，检查 notes key 是否命中 |
| 思政/OBE 页没出现 | --ideology 默认 none；要插入用 --ideology both（或 ideology/obe），HTML 保留 #ideo 屏，Beamer 保留对应帧 |
| PPTX 一打开就弹「无法打开部分内容，已删除相应内容」 | 跑 check_pptx.py 定位。四个已知根因：① Appear 里混了 p:animEffect（出现只有 p:set，animEffect 是淡入类才用）；② 空 <p:bldLst/> 或 grpId 找不到对应 p:bldP；③ p:sldSz type="screen4x3" 与 16:9 尺寸矛盾；④ 有 notesMaster 部件但 presentation.xml 缺 p:notesMasterIdLst。前三处已在 ppt_effects.py/build_ppt.py 修好，④ 由 ensure_notes_master_id() 补 |
| PPTX 没用到母版版式（页面是手画的） | 用 assets/ppt_template.pptx 作起点：new_prs() 返回 Layouts，各页函数只 add_slide(LO.xxx) + 填 idx 占位符；缺模板先跑 ppt_template.py |
| 行内公式比正文大 / 分式撑破行距 | .katex{font-size:.94em} 别改回 1em；行内 \frac、块级才 \dfrac |
更多见 references/troubleshooting.md。
八、资源清单
assets/beamer_courseware_template.tex（SkillHub 白名单不含.tex，发布包改以assets/beamer_courseware_template.md代码块封装，安装时由scripts/setup_assets.py原样还原）：PDF 封面、目录、覆盖动画、TikZ、按钮、OCG、测试、代码、富媒体骨架（含 professionalfonts、行内巨算子全局重定义、配色标记、多列间距安全约束\zyfcolsep与[onlytextwidth]、多题型练习帧、思政+OBE 帧）。assets/courseware_template.html：HTML 仿 PPT 全屏分页骨架（KaTeX 公式、three.js 3D、推导、翻屏、测试；不显示固定操作提示、悬浮才显示；公式尺寸约束；新增多题型测验.quiz-multi/.quiz-fill/.quiz-sort、2D 参数滑块仿真屏#sim、思政/OBE 屏#ideo）；:root 默认学术深蓝。assets/lecture_template.md：Markdown 教案骨架（与三产物共用$...$公式约定，含目标/内容分步/多题型测试/思政OBE/作业结构）。assets/ppt_template.pptx：真母版 + 11 个真版式的 PPTX 模板（16:9，母版带页脚署名与页码，各版式带金线/色条/卡片底，装饰全用a:schemeClr）。属于二进制文件，按 SkillHub 规则未随包发布；首次安装时由scripts/setup_assets.py调用scripts/ppt_template.py生成，改版式后重跑即可。scripts/ppt_template.py：模板生成器。build_template()重写母版与 11 个版式的 spTree，apply_theme(prs, sid)按配色方案重写theme1.xml的clrScheme（换配色 = 换主题，全跟随）。scripts/check_pptx.py：PPTX 包级合规自检（内容类型/关系可达性、根子元素顺序、sldSz矛盾、形状 ID 重复、空bldLst、grpId↔bldP一致性、Appear 混animEffect、OMML 命名空间、备注母版登记），退出码 1 表示有问题。assets/manim_demo.py：Manim 椭球演示场景。assets/vendor/katex/、assets/vendor/three/：离线模式用的 KaTeX 0.16.9（css/js/auto-render）与 three.js r128；js/css 已随包内置，20 个 woff2 字体属二进制文件，按 SkillHub 规则未随包发布，由scripts/setup_assets.py首次安装时下载补齐。离线课件随输出目录一起打包。scripts/color_schemes.py：五套配色单一数据源（Beamer/HTML/PPTX 共用），提供注入/替换接口。scripts/layout_settings.py：版式/字号/导航/动画/用途/产物/思政OBE单一数据源（Beamer/HTML/PPTX/Markdown 共用）——教室（大/中/小）×人数字号缩放、课件用途、产物类型（含 Markdown 教案）、课程思政+OBE 理念（IDEOLOGY_OPTIONS/OBE_LEVELS/IDEOLOGY_MOTTO/ideology_page）、导航条位置、动画频次三档、构成要素。scripts/new_beamer_project.py：Beamer 单文件/多文件脚手架，支持--color-scheme/--all-schemes/--font-scale。scripts/build_pdf.py、verify_pdf.py：PDF 构建与验证。scripts/build_html_schemes.py：把 HTML 按配色/联网方式/教鞭/导航/字号/动画频次各生成一版（--color-scheme/--all-schemes+--network online|offline|both+--pointer on|off+--nav+--font-scale+--anim）。scripts/audit_latex_delimiters.py：定界符审查（缺$、未闭合、裸变量）。scripts/audit_math_symbols.py：数学符号斜体/裸变量检查（HTML/PPTX/TeX 通吃，只报告）。scripts/omml.py、build_ppt.py、ppt_effects.py、media_tools.py：PPT 构建、巨算子版式、动画与媒体；build_ppt.py版式驱动（封面/定义/定理/例题/习题/展示页等版式函数）+ 思政页ideology_slide+ 多题型assessment_slide/ASSESS_BANK+ 每页备注set_notes/DEFAULT_NOTES；支持--color-scheme/--all-schemes、--limit-placement、--anim三档、--font-scale、--ideology、--no-notes；ppt_effects.py支持--anim-freq三档与group_shape_ids按行聚组。scripts/verify_courseware.js、verify_ppt.py、verify_ppt_effects.py：验证链。references/pdf-beamer.md、latex-style-guide.md：Beamer 工作流与个人 LaTeX 风格。references/color-schemes.md：五套配色方案（含简介与 definecolor 块、弹窗文案）。references/ideology-obe.md：课程思政与 OBE 理念页格式（思政主题+4 要点 / OBE 知识·能力·素养+以终为始 / 三句箴言 / 数学课主题对照 / 四产物落地）。references/assessment-types.md：题型与交互·仿真目录（单选/多选/填空/判断/排序/连线/分类/热区，8 类交互，5 种仿真，含数学课出题示例与各产物实现要点）。references/html-courseware.md、ppt-omml.md、ppt-animation-media.md、troubleshooting.md：详细参考。
