教学课件 PPTX 生成器

把一份 Markdown 教案，变成一份面向学生、外观与结构高度统一、可逐页校验、关键决策经用户确认的教学 PPTX。

核心思路：统一设计系统 + 方案先行一次评审 + 一页一文件 + 批量并行生成 + 逐页渲染质检 + 正式输出前用户逐页评审。工具链为纯 Python（python-pptx），跨平台（Windows / macOS / Linux），无 Node 依赖。

通用性总则：脚本本体全部跨平台；真正平台相关的只有三件事——shell 命令写法、预览渲染器、可选能力（图标 MCP / 文生图 / 并行子代理）。这三件事一律按第 0 步探测结果自适应降级（见「能力分层与降级」表），任何一项缺失都不阻塞主流程、不降低交付质量要求。

配图（可选、默认不做）：当某页的核心概念确实需要一个"看得见"的图（实物 / 场景 / 界面 / 类比物）时，先把 D.figure() 写进 slide，写完页再用 assets/gen_image.py 一张一张调文生图模型生成（不做批量），最后经 D.figure() 排进预留框。一页最多一张。判不判配图看 references/outline-standard.md 第九节（三问），排版看 references/design-tokens.md 第八节。三条底线：信息匹配（图讲的就是本页那个概念）、排版合规（进框、不重叠、不越安全边、有图注）、表达准确（形态 / 比例 / 关系不能有错）。配图提示词一律按 主体 + 场景 + 风格 + 光照 + 构图 + 质量要求 六要素写；风格在"写实 / 教学插图风"里按内容二选一，不要求各张图风格统一；画面不出现任何文字，一切以"准确表达本页那个概念"为准。无文生图凭证时，可由用户自供图片放进 imgs/figs/，同样走 D.figure() 排版与校验。数据外发提示：gen_image.py 会把提示词 POST 到第三方文生图服务（api.agnes-ai.cn / api.agnes-ai.com），涉密、未公开的校本材料或学生个人信息不要写进提示词；不需要配图时不要设置 AGNES_API_KEY。

数学图件（数学 / 物理 / 计算机结构类课件的确定性图件；其他学科有公式 / 函数图像 / 流程结构需要时同理适用，与该不该配文生图无关）：公式（LaTeX → matplotlib mathtext 本地渲染，D.formula() 自动渲染 + 缓存，也可 assets/gen_formula.py 批量预生成）、函数 / 数据图像（assets/gen_plot.py，matplotlib）、流程图 / 架构图 / 状态机 / 树 / 网络拓扑 / ER 图（assets/gen_diagram.py，Python + Graphviz）。三类都走 D.formula() / D.figure() 预留框排版（禁止 add_picture 手放），不占"一页一图"名额、不计入 ≤3 张配图限制，规范见 references/design-tokens.md 第九节与 references/outline-standard.md 第十节。

教师演讲备注（speaker notes，每页必写）：每页在 slide_config["notes"] 里写一段五段式讲稿（本页目标 / 讲解脚本 / 课堂互动 / 时间建议 / 易错点），合成时由 compile.py 自动写进 PPTX 备注页（slide.notes_slide）——不进画面、不影响版式与体积，是教师站在讲台上看的"怎么讲、问什么、注意什么"，不是把正文抄一遍。合成期有覆盖率闸门（CONFIG["require_notes"]=True 时缺备注直接合成失败），并自动导出 output/备注稿-<out_name>.txt 供教师通读。内容规范见 references/outline-standard.md 第十一节，排版与 API 见 references/design-tokens.md 第十节。

能力分层与降级

> 降级必须显式告知：第 0 步探测出任何降级项，都要在第 1 步的方案评审里向用户说明（尤其"预览图改为文字稿评审"），不要等到渲染阶段才暴露。

适用场景

应该使用：

• 用户给出教案（.md 或结构等同的 Markdown 文本），要求生成教学 PPT / 课件 / pptx / 幻灯片。
• 用户说"继续按以上教案生成第 N 次课""按同一标准生成"——沿用上一课次的目录与设计系统。
• 用户要求批量把多份教案做成统一风格的教学课件。
• 学科不限：数学 / 物理 / 计算机结构类走数学图件三件套，其他学科用版式与图形表达；主题预设按学科推荐（示例命令偏工科，仅示范写法）。

不应该使用：

• 只需要 HTML 幻灯片 / reveal.js 课件（宿主有对应 HTML 课件技能就改用之；没有则与用户确认要 PPTX 还是 HTML）。
• 只要求编辑已有 PPTX 的局部内容（直接用 PPTX 编辑流程更快）。
• 只有大纲、还没有教案（宿主有教案生成技能就先用它产出教案；没有则请用户补齐教案后再来）。

前置条件

> 数学图件三件套（公式 / 图像 / 结构图）都是本地离线渲染、确定性输出，不依赖任何 API Key；用不到数学图件的课次无需安装 matplotlib / graphviz。所有 pip 依赖跨平台安装方式一致，无路径配置问题。

工作流

第 0 步 · 环境探测（开工 30 秒，决定降级方案）

python -c "import pptx"                  # 必需：缺则 pip install python-pptx
python -c "import PIL"                   # 必需：缺则 pip install pillow
python -c "import matplotlib"            # 数学图件（公式 / 函数图像）时
python -c "import graphviz" && dot -V    # 结构图时
python -c "import requests"              # 文生图配图时
soffice --version                        # 无 PowerPoint 时的渲染兜底（可选）

（PowerShell 下逐条照跑即可；python -c 与 dot -V 跨平台通用。）

探测并记录，作为后续所有步骤的降级依据：

• OS 与 shell：决定第 2 步用 bash 还是 PowerShell 写法（python 调用与 cd、/ 路径两平台通用）。
• 渲染器：Windows 有 PowerPoint → render-png.py；否则查 soffice；再否则文字稿评审（第 8 步）。
• 图标来源：宿主是否有图标 MCP；旧课次目录是否已有栅格化图标可复用。
• 文生图凭证：AGNES_API_KEY 是否存在（无则默认不配图，或问用户是否自供图）。
• 数学图件依赖：本课次是否需要 matplotlib / graphviz。

> 探测出的每一项降级都要在第 1 步方案评审里显式告知用户（尤其"本环境渲染不了预览图，将改用文字稿逐页评审"），不要拖到第 8 步才暴露。

第 1 步 · 读教案，产出方案，一次交用户确认（不可跳过）

1. 完整读一遍教案 .md。确认并列出来：课型（理论 / 实验）、各教学环节与分钟数、分层任务、测试题、作业。
2. 产出方案，合并成一次评审发给用户（宿主支持结构化提问工具（如 AskUserQuestion）就用它，把问题一次问完）：
   - 环境与降级说明：一句话报告第 0 步探测结果——渲染方式（PowerPoint / LibreOffice / 文字稿）、图标来源、文生图是否可用。
   - 页序清单：按 references/outline-standard.md 划分 5~6 个部分，画出页序清单（默认 28~33 页；教案体量明显偏小 / 偏大时，在此一并提出调整区间与理由，经用户确认后执行），逐页写明页型 + 标题 + 拟用版式（版式库 14 种见该文第五节，数学 / 物理课次含公式 / 函数图像 / 结构图页）。明确排除教学反思与板书设计（板书里的知识内核要并入正文页）。用户可在此调整任何一页的版式与取舍。
   - 署名与页脚信息：确认 compile.py 的 CONFIG["author"] / CONFIG["company"]（授课教师姓名、院系名称）与 CONFIG["footer"] / CONFIG["title"]（课程名 + 模块主题）。技能自带的是 <授课教师> / <院系名称> 占位符，不确认就会原样写进 PPTX 文档属性与封面页；不得凭空填写他人姓名或单位，用户不提供时保持占位并在交付说明中列出。
   - 主题与布局建议：从 references/design-tokens.md 第一节的 6 套预设里按课程学科推荐 1 套 + 给 1~2 套备选（说明理由），用户也可给自定义品牌色（5 个基准色即可，衍生色自动派生）。布局问一句 classic / compact（compact 标题带更薄、正文区更高）。沿用上一课次时默认沿用既有主题，但仍要给用户改的机会。
   - 作业方案建议：从教案"课后作业"整理出三要素给用户确认——① 作业内容（题目 / 任务 2~3 项，可分层，学生视角改写）② 提交方式（平台：学习通 / 雨课堂 / 邮箱 / 教师机 / 用户课程实际所用平台… + 命名规范）③ 时间节点（截止日期，能到时分更好 + 迟交政策如有）。教案缺哪项就给默认建议并显式确认，不得臆造截止时间与提交方式。
   - 配图方案（默认不配图）：按 references/outline-standard.md 第九节的三问，逐条列出"建议配图的页 + 拟画内容 + 宽高比"（一般 0~3 张）。大多数课次一张都不需要——把"本课不需要配图"也作为默认结论说出来，让用户决定是否加。需要配图时逐张写明：主体 + 场景 + 风格（写实 / 教学插图风，按内容二选一）+ 光照 + 构图 + 质量要求；并声明图只做"帮看懂"，正文要点照常写；一页最多一张；画面不含任何文字；风格不要求统一、准确表达优先；一份课件 ≤ 3 张。配图在写完 slide 之后再逐张生成（第 6 步）；无文生图凭证时可改为用户自供图。
   - 数学图件方案（数学 / 物理 / 计算机结构类课次默认要有；其他学科有公式 / 函数图像 / 流程结构需要时同理）：扫一遍教案，列出公式页（哪些定义 / 定理 / 推导要上图）、函数图像页（哪些函数 / 物理图像 / 数据图像）、结构图页（哪些流程 / 架构 / 状态机 / 树 / ER 图）。这些是确定性图件，不适用第九节三问、不占 ≤3 张名额，按需列出即可；一般随页序清单一并给出（页型 12~14，见 outline-standard.md 第五节与第十节）。生成在第 5 步，一条命令一批。
   - 教师演讲备注说明（每页必写，先说清再动工）：声明每页都会带一段五段式讲稿写进 PPTX 备注页（本页目标 / 讲解脚本 / 课堂互动 / 时间建议 / 易错点），合成后另外导出 output/备注稿-<out_name>.txt 供教师通读或打印；备注不进画面、不影响版式。请用户在此一并确认讲稿偏好：互动风格（多提问点名 / 以讲授为主）、点名方式、每页时间粒度（按教案教学过程的分钟数）、是否需要写课堂管理提示（纪律 / 机房操作规范）。教师也可直接提供讲稿要点，按提供的写。
3. 按用户意见修订方案后再动工。方案一次问完，不要挤牙膏式追问——这是第一道提速关。

第 2 步 · 建目录、搬资产

每个课次一个独立目录，结构见 references/design-tokens.md 第六节。目录位置与命名：<课件根目录> 由用户指定或沿用既有课程所在目录（首次使用时在方案评审里确认）；课次目录命名沿用用户课程的既有习惯（如 第XX次课-模块N-主题、Lecture-XX-主题），无既有习惯时用默认式 第XX次课-模块N-主题。

bash（Linux / macOS / Git Bash）：

K="<技能目录>/assets"                # 本技能安装位置下的 assets（从本 skill 文件所在目录定位）
D="<课件根目录>/第XX次课-模块N-主题"
mkdir -p "$D/py" "$D/imgs/figs" "$D/imgs/math" "$D/output"
cp "$K"/branding/* "$D/imgs/"
cp "$K"/design.py "$K"/compile.py "$K"/check_slides.py "$K"/rasterize_icons.py \
   "$K"/gen_image.py "$K"/figmath.py "$K"/gen_formula.py "$K"/gen_plot.py "$K"/gen_diagram.py "$D/py/"
cp "$K"/render-png.py "$D/output/"
# 已有上一课次时，最快是整目录复制后再删产物（见下）

PowerShell（Windows）：

$K = "<技能目录>\assets"
$D = "<课件根目录>\第XX次课-模块N-主题"
New-Item -ItemType Directory -Force -Path "$D\py","$D\imgs","$D\imgs\figs","$D\imgs\math","$D\output" | Out-Null
Copy-Item "$K\branding\*" "$D\imgs" -Force
Copy-Item "$K\design.py","$K\compile.py","$K\check_slides.py","$K\rasterize_icons.py","$K\gen_image.py","$K\figmath.py","$K\gen_formula.py","$K\gen_plot.py","$K\gen_diagram.py" "$D\py" -Force
Copy-Item "$K\render-png.py" "$D\output" -Force

> 后文所有 cd 与 python xxx.py 调用两平台通用，路径一律写 /（Windows 的 Python / PowerShell 都认正斜杠）。

compile.py 顶部 CONFIG 改七项：out_name / footer / title + author / company（填第 1 步确认的授课教师与院系；技能自带 <授课教师> / <院系名称> 占位符，交付前必须替换） + theme / layout（填第 1 步确认结果） + require_notes / notes_report（保持默认 True：备注缺失即合成失败、自动导出备注稿）。
imgs/figs 与 gen_image.py 只在第 1 步确认要配图时才需要（不配图也留着无妨，别误用即可）；
数学图件脚本（figmath.py / gen_formula.py / gen_plot.py / gen_diagram.py）与 imgs/math 在数学 / 物理 / 计算机结构类课次默认带上（不用也不占体积；跨课次沿用目录时它们已在 py/ 里，无需再搬）。

沿用上一课次（推荐，速度最快）

bash：

P="<课件根目录>/第0N-1次课-…"; C="第0N次课-…"
mkdir -p "<课件根目录>/$C/py" "<课件根目录>/$C/output" "<课件根目录>/$C/imgs"
cp -r "$P/imgs/." "<课件根目录>/$C/imgs/"
cp "$P"/py/{design.py,check_slides.py,rasterize_icons.py,gen_image.py,figmath.py,gen_formula.py,gen_plot.py,gen_diagram.py} "<课件根目录>/$C/py/"
cp "$P/output/render-png.py" "<课件根目录>/$C/output/"
# 再单独写 compile.py（改 CONFIG 七项）与 slide-XX.py
# ⚠ 沿用来的 imgs/figs/ 里是上一课次的图：不用的删掉，别让 slide 误引上一课次的配图
# ⚠ 沿用来的 imgs/math/ 里是上一课次的公式图缓存：内容哈希命名不会误用，懒得清也行

PowerShell（Windows）：

$P = "第0N-1次课-..."; $C = "第0N次课-..."
New-Item -ItemType Directory -Force -Path "<课件根目录>\$C" | Out-Null
Copy-Item "<课件根目录>\$P\imgs" "<课件根目录>\$C\imgs" -Recurse -Force
Copy-Item "<课件根目录>\$P\py\design.py","<课件根目录>\$P\py\check_slides.py","<课件根目录>\$P\py\rasterize_icons.py","<课件根目录>\$P\py\gen_image.py","<课件根目录>\$P\py\figmath.py","<课件根目录>\$P\py\gen_formula.py","<课件根目录>\$P\py\gen_plot.py","<课件根目录>\$P\py\gen_diagram.py" "<课件根目录>\$C\py" -Force
Copy-Item "<课件根目录>\$P\output\render-png.py" "<课件根目录>\$C\output" -Force
# 再单独写 compile.py（改 CONFIG 七项）与 slide-XX.py
# ⚠ 沿用来的 imgs\figs\ 里是上一课次的图：不用的删掉，别让 slide 误引上一课次的配图
# ⚠ 沿用来的 imgs\math\ 里是上一课次的公式图缓存：内容哈希命名不会误用，懒得清也行

第 3 步 · 取图标（只在需要新图标时）

图标获取优先级：① 沿用旧课次已栅格化图标（零成本）→ ② 宿主图标 MCP 取 SVG → ③ 都没有则该页改用无图标版式（编号圆点 / 形状 / 纯文字）。任何一步取不到都不阻塞流程，课件可用性不受影响。

宿主提供 universal-icons MCP 时（agent 侧操作，不联网下载、不碰 SSL / URL 编码坑）：

1. 逐个取 SVG：对 assets/icon-list.txt 里每一行 lucide:<name>，调 MCP get_icon：
   - collection = "lucide"，icon_name = <name>（冒号后的名字）
   - color = "<主色6位hex>"（主色集）或 #FFFFFF（白色集）——颜色直接烧进 SVG
   - 用写文件工具把返回的 SVG 存成 imgs/icons/lucide-<name>.svg 与 imgs/icons_white/lucide-<name>.svg
2. 栅格化成 PNG（python-pptx 不认 SVG；命令两平台通用）：

cd <课件目录>/py
python rasterize_icons.py ../imgs/icons          # 修复 MCP 缺陷 + 栅格化 + 颜色自检
python rasterize_icons.py ../imgs/icons_white

• 自动跳过已存在且颜色正确的图标：沿用上一课次通常零处理；换主题后主色变了，旧色图标过不了像素自检会自动重栅格化，也可用 python rasterize_icons.py ../imgs/icons <新主色> 离线换色（icons_white 不变）。--force 强制全量重栅格化。
• 需要清单外的图标时，先调 MCP search_icons（collection="lucide"）确认准确名字。
• rasterize_icons.py 会自动修复 MCP 输出的 stroke-（缺 stroke-width="2"）缺陷，不用手动处理。
• 图标用 D.icon_circle() 画圆底，不要裸放。
• 变体必须对照底色：深色底（T.navy 系、T.blue）用 white 变体；强调色（T.gold）底用主色变体；浅色底用主色变体。若所选主题的强调色本身很深（如 graphite-amber），强调色底改用 white 变体。
  选错的后果是图标隐形（详见 references/qa-and-pitfalls.md 第 0 条）。

第 4 步 · 写 slide-XX.py（一页一文件，批量产出）

以 assets/slide_template.py 为抄写源。每个文件固定长这样（notes 必写，见下方"教师演讲备注"）：

import design as D

T, L = D.T, D.L
slide_config = {
    "type": "content", "index": 5, "title": "页面标题",
    "notes": {
        "本页目标": "一句话：讲完后学生能说出 / 做出什么",
        "讲解脚本": ["先……（教师口语化串讲，可直接念）", "再……"],
        "课堂互动": "提问：…… ｜ 预期回答：……（没有就写「无」）",
        "时间建议": "3 分钟",
        "易错点": "学生常把 X 当成 Y，提醒……（没有就写「无」）",
    },
}

def create_slide(pres, theme):
    slide = D.content_slide(pres, "页面标题", 5)   # 浅色页；深色页用 D.dark_slide
    # …在此绘制内容…
    return slide

if __name__ == "__main__":
    D.preview(create_slide, "slide-05-preview.pptx", source=slide_config)   # 预览也带上备注

教师演讲备注（每页必写，讲稿不是正文复述）：

• 写在 slide_config["notes"] 里（推荐）或页内 D.notes(slide, {...})；compile.py 合成时自动写进备注页并统计覆盖率，缺备注直接合成失败。
• 五段固定：本页目标（一句话，学生能说出 / 做出什么）、讲解脚本（教师口播稿，2~4 条可念的话）、课堂互动（提问 + 预期回答 + 点名方式）、时间建议（分钟数，与"今天的课堂安排"加总一致）、易错点（学生最容易踩的坑 + 一句提醒）。没有内容就写"无"，不要省略段落。
• 别把页面正文抄进备注——正文给学生看，备注写怎么讲、问什么、注意什么；分页型重点（封面开场语、分隔页过渡语、提问页点名策略、作业页三要素复述）见 references/outline-standard.md 第十一节。
• 备注不进画面：不占坐标、不影响版式，也不参与渲染评审；教师看稿走 output/备注稿-*.txt，不靠预览图。

写每一页时必须现场算高度（这是最高频的翻车点）：

• code_box 文本可用高度 = h - (有标题 ? 0.62 : 0.34)，每行按 0.25" 估。
• 项目符号最后一行 = y + 条数 × row_h，必须小于下方元素的 y。
• 文案宽度 ≈ 汉字数 × 0.146"（10.5 pt）/ 0.163"（11.5 pt）；别让标点落到行首。
• 用了 compact 版式时，正文元素 y 一律从 D.L.contentY（1.16）起现场算，不照抄旧课次的 1.3。

批量产出规范（第二道提速关）：

• 不要边写边预览。全部页写完 → 一次 compile.py → 一次渲染 → 集中看图修。python slide-XX.py 单页预览只用于排查报错页。
• 批量写文件：一次回复里连续写多个 slide 文件，减少来回。
• 并行子代理（宿主支持并行任务派发工具时用，如 Agent / subagent 类工具）：按"部分"把页序清单切成 3~5 组并行派发。每个子代理的任务书必须自带（子代理看不到主对话）：① 第 4 步的全部规则 + slide_template.py、design-tokens.md 的完整路径（让它自己读）② 分到的页序切片（页型 + 标题 + 内容要点）③ 已确认的主题（CONFIG.theme / layout）与作业方案 ④ 本组要配图的页 + 图名（imgs/figs/<文件名>）与预留框坐标，铁律：一页最多一张配图、只能走 D.figure()、不许 add_picture 手放、不许压住文字越出安全边 ⑤ 本组要上数学图件的页 + 公式（LaTeX）/ 图像名 / 结构图名，铁律：公式走 D.formula()（一页 ≤ 4 条、中文不进公式）、图像 / 结构图走 D.figure()、比例对齐预留框（细则让它读 design-tokens.md 第九节）⑥ 每页必写教师演讲备注：slide_config["notes"] 五段齐全（本页目标 / 讲解脚本 / 课堂互动 / 时间建议 / 易错点），写"怎么讲、问什么、注意什么"而不是复述正文；本组的时间建议之和要与主对话给的本组分段分钟数对得上 ⑦ 铁律：只写自己分到的 slide-XX.py，禁止改 design.py / assets / 别组的文件；高度必须现场算；图标变体对照底色。主流程统一 compile + render + QA。
• 配图页照写不误：D.figure(...) 先写进 slide（此时图还没生成，不要单独跑 python slide-XX.py 预览它，会因缺图报错）；图在第 6 步补上，第 7 步 compile 时一并校验。
• 数学图件页照写不误：D.formula(...) 可以先不预生成公式图（compile 时自动渲染缓存）；gen_plot.py / gen_diagram.py 的图则先写 D.figure(...) 占位，图在第 5 步补齐后由第 7 步 compile 一并校验。

第 5 步 · 生成数学图件（公式 / 函数图像 / 结构图；仅在课次含数学图件时）

公式、函数图像、结构图是确定性图件：写完 slide 后一把生成，不需要一张张过人工评审（文生图才要）。
在 <课件目录>/py 下运行（命令两平台通用，LaTeX 里的反斜杠在 bash / PowerShell 双引号中均保持字面）：

cd <课件目录>/py

# ① 公式：D.formula 其实会自动渲染，预生成只为了"先审一遍公式图"
python gen_formula.py -o quadratic "x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}"
python gen_formula.py --from-file <技能目录>/assets/examples/formulas.txt     # 批量（名称<TAB>公式）

# ② 函数 / 数据图像：快速模式一条命令一条曲线；多曲线/参数方程/填充/矢量用 JSON 清单
python gen_plot.py -o sine --expr "sin(x)" --xrange -6.28:6.28 --pi-ticks --title "y = sin x" --legend
python gen_plot.py --from-file plots.json        # 样例：<技能目录>/assets/examples/plots.json

# ③ 结构图：JSON spec（功能全，支持 clusters 分组）或快速模式
python gen_diagram.py --from-file <技能目录>/assets/examples/diagrams.json    # 六种 kind 各一张
python gen_diagram.py --kind flowchart --nodes "开始:开始:start;输入:输入 a, b;判断:a > b ?:decision;输出:输出较大值;结束:end" --edges "开始->输入;输入->判断;判断->输出:是;判断->输入:否" -o max-flow

铁律（与文生图配图共用，细则见 references/design-tokens.md 第九节）：

• 公式走 D.formula()（contain 缩放、绝不裁切、一页可多条 ≤ 4）；图像 / 结构图走 D.figure()（一页一张、有图注）；都不许 add_picture 手放。
• mathtext 子集：不支持 \begin{aligned} 等环境与 \text{中文}；多行公式拆多条堆叠，中文说明用 D.text。
• 比例对齐：gen_plot.py 的 --figsize 默认 4.3,3.1（对齐图文混排框）；结构图天然偏高，cover=True 会切节点——用 cover=False 或 --rankdir LR 改横，或按图的实际比例给预留框。
• 配色：gen_plot.py / gen_diagram.py 默认自动读 compile.py 的 CONFIG.theme 与课件同色系；D.formula 直接用当前主题 T.ink（深色页传浅色）。
• 深色页公式：D.formula(..., color="E8F1FA")。
• 输出目录：公式图 imgs/math/，图像 / 结构图 imgs/figs/（结构图另存同名 .dot 便于微调重渲）。
• 生成后渲染成 PNG 时一并核对（公式完整性、坐标轴与节点未被切、中文无豆腐块），不用逐张人工审。

Graphviz 安装（跨平台）：本体——Windows winget install Graphviz.Graphviz（或便携版解压加 PATH）、macOS brew install graphviz、Debian 系 sudo apt-get install graphviz；Python 绑定 pip install graphviz（gen_diagram.py 报错提示同理）。

第 6 步 · 生成配图（仅在必要时；一页一张；一次一张）

只在第 4 步的 slide 里确实调了 D.figure() 的页才需要这一步；没有配图就整步跳过（默认就是没有）。
（数学图件在第 5 步，不在这里。）

先按 references/outline-standard.md 第九节的三问再确认一遍：三问有任何一问不过，就把那张 D.figure() 删掉改用图形/图标版式——默认不配图，不配图完全正常。

逐张生成，一条命令一张图（本脚本刻意不做批量；命令两平台通用；示例偏工科，仅示范六要素写法，任何学科同理）：

提示词固定六要素：主体 + 场景 + 风格 + 光照 + 构图 + 质量要求（少一项就不许生成）。

cd <课件目录>/py

# 一张一条命令；-o 就是 slide 里 D.figure(..., "名字") 用的名字；-r 对齐预留框比例
# 位置参数 = 主体 + 场景；--style 二选一：**realistic 写实 / teaching 教学插图风**
python gen_image.py -o editor-ui -r 16:9 --max-px 1400 --style teaching "一台打开代码编辑器的笔记本电脑，屏幕上排列着彩色的代码行；大学机房的课桌上，旁边有键盘与鼠标"

python gen_image.py -o oscilloscope -r 4:3 --max-px 1400 --style realistic "数字示波器，屏幕上显示稳定的正弦波形；电子实验室工作台上，旁边放着探头与面包板"

# 光照 / 构图 / 质量要求不写就用脚本兜底句；要更准就地填
python gen_image.py -o drone -r 16:9 --style realistic --lighting "黄昏侧逆光，机身轮廓清晰，天空有层次" --composition "低空悬停于画面三分线，远景带校园天际线" --quality "机身比例与桨叶数量准确，无变形无多余肢体" "四旋翼测绘无人机；校园操场上空"

# 可选：--palette "1F4E79,C9A227" 只作配色参考，**不强制整套课件统一**

• 输出到 imgs/figs/<文件名>.png（= D.FIGS_DIR）；已存在则跳过（--force 覆盖重生成）。
• 不要求风格统一：各图按篇幅需要选写实或插图即可，统一感由 D.figure() 的圆角 / 描边 / 图注来给；--palette 只是可选配色参考。
• 脚本强制附加"画面不出现任何文字 / 字母 / 数字 / 符号 / 水印"；不要在提示词里要求图上写字（模型画中文必失真），文字一律由 PPT 排版。
• 未给 --style 且提示词里也没写风格时，脚本会提醒并不会替你兜底——风格必须由生成者按内容判定。
• 需要图像服务凭证（AGNES_API_KEY；申请 https://platform.agnes-ai.com ，或临时 --api-key）；当前服务有限流（脚本内建重试）。
• 每生成一张就看一眼：主体有没有被裁、表达准不准确（数量 / 比例 / 结构有没有画错）、画面有没有乱码文字、与本页概念是否真的对得上。不合格就改提示词 --force 重生成，或干脆删掉这张图与对应的 D.figure() 调用。
• 约束：一页最多一张（同页第二次 D.figure() 会直接报错）；一份课件 ≤ 3 张；单次课课件体积目标 ≤ 2.5 MB。
• 无凭证时的等价路径：请用户自供图片（或用宿主可用的图像能力生成后）放进 imgs/figs/，文件名对齐 slide 里的 D.figure(..., "名字")，同样走 D.figure() 排版与后续校验。

配图只能在 D.figure() 里排版（cover 裁切 + 圆角 + 图注），坐标照 references/design-tokens.md 第八节 8.2 的预留框表取，不许 add_picture 手放。

第 7 步 · 合成 + 自检（一步到位）

cd <课件目录>/py
python compile.py          # 期望：已合成 N 页 -> output/....pptx
                           #      + 教师演讲备注：N/N 页已写入
                           #      + 备注稿已导出 -> output/备注稿-....txt

• compile.py 逐页 try/catch：python-pptx 的参数错误（颜色 / 坐标 / 图片缺失）在执行时即时抛出，出错直接列出 slide-XX.py: 原因。python compile.py --stack 看完整 traceback；疑难时才用 check_slides.py 逐页隔离。
• 备注闸门：CONFIG["require_notes"]=True（默认）时，有页缺教师演讲备注会直接合成失败并列出文件名——这是有意的交付门禁，不要去关它；改造旧课次确实要分批补时，才临时改 False，并在补齐后改回。
• CONFIG["notes_report"]=True（默认）时同时导出 output/备注稿-<out_name>.txt（逐页标题 + 备注全文），供教师通读 / 打印；如果报错提示缺备注，照着文件名回补五段即可。
• 修改个别页后用 python compile.py --only 5,12-13 只合成改动页快速复验（输出 *-review.pptx，不覆盖正式文件）。

第 8 步 · 渲染成图 + 两轮评审（不可省）

A. Windows + PowerPoint：

cd <课件目录>/output
python render-png.py "第XX次课-....pptx" "预览图"

B. macOS / Linux / 未装 Office（LibreOffice + poppler 兜底）：

cd <课件目录>/output
soffice --headless --convert-to pdf "第XX次课-....pptx"
pdftoppm -png -r 110 "第XX次课-....pdf" "预览图/幻灯片"    # 生成 预览图/幻灯片-1.png、-2.png …，页序与 render-png 一致

• LibreOffice 的字体度量与 PowerPoint 略有差异：重叠 / 溢出的判定保守处理（临界处多留余量）；若最终放映环境是 PowerPoint，临界问题以 PowerPoint 版为准。
• poppler 缺失时：macOS brew install poppler；Debian 系 sudo apt-get install poppler-utils；或改用任意"PDF → 逐页 PNG"工具（pdftocairo / ImageMagick 等），保持页序与文件名可对应即可。
• 第一轮 · 自查：逐张读图，重点看：重叠、裁切、孤字、溢出、图标"豆腐块"、柱子/底纹异常；有配图的页额外看：主体有没有被 cover 切掉、画面有没有乱码文字、图与旁侧文字有没有挤在一起或重叠、图注是否完整。有数学图件的页额外看：公式是否完整显示（有没有被压 / 变豆腐块）、函数图像的坐标轴与图例是否被 cover 切掉、结构图节点是否完整、深色页公式颜色是否够亮。首次生成一般有 4~7 处问题——找不到问题说明没认真看。修完重渲。
  备注不进画面，看图查不出：核对合成日志的 教师演讲备注：N/N 页已写入（必须 N/N），并通读 output/备注稿-*.txt——检查五段是否齐、有没有该写"无"却留空或该写内容却写"无"、是否成了正文复述、时间建议加总是否与"今天的课堂安排"一致。
• 第二轮 · 用户逐页评审（正式输出前的必经关卡）：把 预览图/ 的全部页面图连同页码清单交给用户，明确请用户逐页提修改意见（内容、版式、配色、文案语气、配图取舍均可改），并附上你自查已修问题的清单。同时把 output/备注稿-<out_name>.txt 一并交给用户——备注不进画面，只有靠这份讲稿才能审（讲解口径、互动问法、时间安排、易错点提醒）。用户提了意见就：改对应 slide-XX.py（含其 notes）→ compile.py --only <改动页> 复验 → 重渲后把改动页的新图与新讲稿再给用户确认。循环直到用户明确认可，才能进入第 9 步。
• 没有任何渲染器时：用 python-pptx 逐页 dump 文字与坐标自查，把逐页文字稿交给用户评审，并说明未做视觉校验。

第 9 步 · 内容校验 + 正式输出

用户认可预览后：

1. 若评审期间动过页面，跑一次完整 python compile.py（不带 --only）覆盖正式 PPTX。
2. 按 references/qa-and-pitfalls.md 第一节第 3 步的脚本核对：页数、占位符、是否误含"板书设计 / 教学反思"、页脚文字出现次数（封面除外应为 N−1）、作业页与结束页的提交方式和截止时间是否与用户确认的作业方案一致。
3. 配图核对（若有配图）：按 references/qa-and-pitfalls.md 第四节自查清单逐项过——每页至多一张、每张都过"信息匹配"三问、有图注、不压文字、不越安全边、图文对得上、画面无乱码文字、表达准确（形态 / 比例 / 数量 / 结构关系无错）；一份课件 ≤ 3 张；体积 ≤ 2.5 MB（默认目标）。（风格不必统一，不作为退图理由。）
4. 数学图件核对（若有）：按 references/qa-and-pitfalls.md 第四节清单逐项过——公式走 D.formula()（一页 ≤ 4 条、无中文进公式、深色页浅色）、图像 / 结构图走 D.figure() 且有图注、无 cover 裁切导致的坐标轴 / 节点缺失、中文无豆腐块；图件总量与体积仍在默认目标内。
5. 教师演讲备注核对：按 references/qa-and-pitfalls.md 第一节第 3 步的脚本核 备注覆盖率 = N/N 且每页五段齐全；output/备注稿-*.txt 已通读（无该写"无"却空缺、无正文复述、时间建议加总与"今天的课堂安排"一致）；确认备注没有挤占画面（备注页文本不参与排版，若发现页面上出现讲稿内容说明写错了位置）。

第 10 步 · 交付

向用户说明：

1. 输出路径（PPTX + 预览图/ + output/备注稿-<out_name>.txt）；
2. 页数与章节结构对照表；
3. 最终确认的作业三要素（内容 / 提交方式 / 时间节点），方便教师核对；
4. 教师演讲备注说明：每页都写了五段式讲稿（本页目标 / 讲解脚本 / 课堂互动 / 时间建议 / 易错点），已写进 PPT 备注页（视图 → 备注页，放映时用演讲者视图），覆盖率 N/N；另导出 备注稿-*.txt 可直接打印或发手机；讲稿口径与第 1 步确认的互动风格一致；
5. 本课次用了哪套主题预设、复用了哪些既有资产、新增了什么；
6. 配图说明（若有）：哪几页配了图、每张图讲什么、是文生图生成的（便于教师知情与后续替换）；
7. 数学图件说明（若有）：哪几页有公式 / 函数图像 / 结构图、分别讲什么（均为本地脚本生成，.dot / 公式缓存可复改）；
8. 用户评审意见的落实情况（改了哪些页，含备注的修改）；
9. 本环境用到的降级项（渲染方式、图标来源、配图来源），便于用户知情。

并提醒：下一课次只需复制目录 → 改 compile.py CONFIG 七项 → 重写 slide-XX.py（每页记得写 notes）。

生成提速清单

1. 方案一次评审：环境降级说明 + 页序 + 主题布局 + 作业三要素 + 教师演讲备注偏好（互动风格 / 点名方式 / 时间粒度）+（必要时）配图方案 +（数学 / 物理课次）数学图件方案合并成一次问答，不来回追问。
2. 批量写页文件（或宿主并行子代理 fan-out），写完统一 compile + render，不边写边预览。
3. 自检合成合一：compile.py 逐页报错定位，正常流程不跑 check_slides.py。
4. 增量复验：改动页用 compile.py --only 只重合成，不整份重来。
5. 图标零重复取图：沿用上一课次直接复用 imgs/；rasterize_icons.py 自动跳过已存在且颜色正确的 PNG，只对缺失 / 变色的栅格化。
6. 配图按需单张生成：写完 slide 后只给真调了 D.figure() 的页补图，一张一条命令；已存在的自动跳过；默认不配图，别为凑数生成；无凭证时走用户自供图路径。
7. 数学图件整批生成：公式（D.formula 自动渲染或 gen_formula.py --from-file 批量）、图像与结构图（gen_plot.py / gen_diagram.py --from-file 清单）都是确定性输出，写完 slide 一把跑完，不用一张张人工审；样例清单在 assets/examples/。
8. 备注随页一次写全：写 slide 时顺手在 slide_config["notes"] 补五段（本页目标 / 讲解脚本 / 课堂互动 / 时间建议 / 易错点），不留到后期补——compile.py 的闸门会让漏写当场暴露，补写反而更慢。
9. 跨课次整目录复制：保留 design.py 与 imgs，只写新的 slide-XX.py（注意清掉用不上的旧配图，并按新教案重写每页 notes）。

输入 / 输出

输入：一份教案 Markdown，含"基本信息 / 教学目标 / 重点难点 / 教学方法与手段 / 教学过程设计 / 实验安排 / 课后作业（+ 板书设计、教学反思）"；以及用户在第 1 步确认的主题 / 布局 / 作业方案 / 教师演讲备注偏好（互动风格、点名方式、时间粒度）/（必要时）配图方案 / 数学图件方案，与第 0 步探测确认的环境降级方案。

输出

<课件根目录>/第XX次课-模块N-主题/
├── py/      design.py · compile.py · check_slides.py · rasterize_icons.py · gen_image.py ·
│            figmath.py · gen_formula.py · gen_plot.py · gen_diagram.py · slide-01…NN.py
│            （每页 slide-XX.py 的 slide_config 里带 notes 五段教师演讲备注）
├── imgs/    校徽 + 装饰 + icons(主色) + icons_white + figs/(配图与数学图像/结构图，可无) +
│            math/(公式图缓存，可无)
└── output/  第XX次课-....pptx  ·  备注稿-第XX次课-....txt(教师讲稿，逐页)  ·
             render-png.py(仅 Windows 用；其他平台渲染走第 8 步 B)  ·
             预览图/…(render-png 或 LibreOffice 导出)

质量指标：页数 28~33（默认区间，经第 1 步评审可调）；compile.py 一次通过；无占位符；封面无页脚、其余页有页码；教师演讲备注覆盖率 N/N 且每页五段齐全（本页目标 / 讲解脚本 / 课堂互动 / 时间建议 / 易错点），时间建议加总与"今天的课堂安排"一致；作业三要素与用户确认一致；配图（若有）信息匹配且排版合规、每张都有图注、一份课件 ≤ 3 张；数学图件（若有）公式 ≤ 4 条/页、无中文进公式、无 cover 裁切导致的坐标轴 / 节点缺失；用户已逐页评审认可（含备注稿）；文件体积 ≤ 2.5 MB（默认目标，交付渠道另有要求时以渠道为准；python-pptx 自动去重图片，配图多时要留意；备注为纯文本，不计入体积）。

边界与错误处理

设计系统的六条铁律

1. 外观只从 design.py 取。配色与密度走 CONFIG["theme"] / CONFIG["layout"]（或 set_theme / set_layout），所有颜色、字号、间距从 D.T / D.L / D.* 组件取，禁止在 slide 里硬编码色值（唯一例外：深色页上的浅色文字如 E8F1FA）。文本一律走 D.text / D.text_lines（内含中文字体 ea typeface 修正），不要直接 add_textbox 手写字体。
2. 相邻两页不用同一种版式（见 references/outline-standard.md 第五节版式库）。
3. 改 design.py 本体（新增预设 / 组件 / 参数）必须同步回技能的 assets 源目录（assets/design.py），否则下一课次就分叉了；若本技能在工作区存在多份副本（不同 agent 各自安装了一份 skills 目录），改完任一份都要同步其余副本，以实际加载生效的目录为准。
4. 配图只在"信息匹配"时用，且一律走 D.figure()。默认不配图；一页最多一张（同页第二次调用 D.figure 会直接报错）；配图必须解释本页唯一核心概念（outline-standard.md 第九节三问）；排版进预留框、不压文字、不越 0.6" 安全边、必须给图注（design-tokens.md 第八节）；禁止 add_picture 手放配图。提示词按 主体 + 场景 + 风格 + 光照 + 构图 + 质量要求 六要素写，风格在写实 / 教学插图风里按内容选，不强求各图统一，画面不许出现任何文字，判断图好坏只看"是否准确表达了本页概念"。来源不限：文生图或用户自供图，排版规则一致。
5. 数学图件同样只走 D.formula() / D.figure()。公式（LaTeX → matplotlib mathtext）走 D.formula()：contain 缩放绝不裁切、一页可多条（≤ 4）、深色页传浅色、中文不进公式；函数图像与结构图走 D.figure()：一页一张、有图注、比例对齐预留框（保坐标轴 / 节点完整时用 cover=False）。数学图件是确定性内容，不受"默认不配图 / 一份课件 ≤ 3 张"限制，但排版合规（预留框、安全边、图注）与配图完全一致。
6. 每页必写教师演讲备注（slide_config["notes"] 或页内 D.notes(slide, {...})），五段固定：本页目标 / 讲解脚本 / 课堂互动 / 时间建议 / 易错点，没有内容写"无"但不省段。备注是教师讲稿——写怎么讲、问什么、注意什么，不是把正文抄一遍；它写进 PPTX 备注页，不进画面、不影响版式与体积。CONFIG["require_notes"]=True（默认）时缺备注直接合成失败，别为出稿关掉闸门；教师审阅走导出的 output/备注稿-*.txt。规范见 references/outline-standard.md 第十一节。