一键课件
把教案或课程大纲变成双版本课件：可编辑的 PPTX 和可放映的 HTML。自动拆分页面结构、AI 生成风格统一的配图、搜索推荐教学视频链接。
何时使用
- 用户说"一键课件""把这份教案做成课件""生成课件""帮我做个 XX 课的课件"等
- 用户提供教案、教学设计或课程大纲，要求产出课件
- 输入形态：对话中的文字，或文件（txt / md / docx / pdf）
环境检查
每次执行前先运行只读检查，不修改任何配置：
python scripts/check_environment.py
ready：直接进入主流程partial：继续主流程，按输出中的降级说明处理。例如 Python 工具链缺失时，跳过 PPTX 只交付 HTML 版needs_setup或unavailable：按输出中的 setup 步骤引导用户配置；用户拒绝配置时执行对应降级，不阻塞 HTML 课件生成- 生图工具与联网搜索属于宿主能力，无需预先配置：调用失败时按"主流程"内对应步骤降级
- python-pptx 库的可用性不在此步探测：由第 7 步 build_pptx.py 自检并以退出码 3 报告缺失
主流程
1. 解析教案
- 读取用户提供的教案或大纲（文字或文件）
- 提取：课题、学科、学段、教学目标、知识点、例题、练习安排、教学环节
- 无法确定课题或提取不到任何知识点时停止，向用户索要更完整的材料；不编造教案里没有的教学内容
- 教学确需补充教案外的常识内容时可以补充，但必须在对应页 notes 中标注"教案外补充"
2. 设计课件结构
加载 @references/page-structure.md 并按其规则执行：
- 默认页面流：封面 → 导入 → 知识点（1—6 页）→ 例题 → 练习 → 视频 → 总结
- 用户要求"按我的教案结构走"时，按 page-structure.md 中的环节映射规则处理
- 按学科从风格表选定统一视觉风格，用户指定风格时以用户为准
- 每页文字要点不超过 6 条，每条不超过 20 字
3. 组装课件数据
- 按 assets/courseware-template.json 的格式生成完整 courseware.json，页面类型和字段与该文件一致
- 每个需要插图的页面填写 image.prompt：中文画面描述 + 学科风格后缀
- 每个适合放视频的页面填写 video.topic（选题关键词）
- courseware.json 保存到输出目录，作为 PPTX 与 HTML 双版本共用的数据源
4. 生成配图
- 对每个 image.prompt 调用宿主的图片生成工具，图片存入输出目录 images/ 子目录，文件名用"页码-用途"（如 p03-concept.png）
- 生成成功后把相对路径回填到 image.path
- 工具不可用、生成失败或连续两次结果明显不符时：image.path 留空，课件对应位置输出灰色插图占位框并标注提示词，方便用户事后自行配图
- 同一份课件的所有提示词共用同一风格后缀，保证配图风格统一
- 不使用网络搜索到的图片，配图一律 AI 生成
5. 搜集视频链接
- 按每页 video.topic 用联网搜索找 2—3 个适合课堂的教学视频链接
- 只收录公开可访问的链接，逐条记录标题、地址、来源平台和适用页码
- 结果写入输出目录的视频链接清单.md，并在课件对应页保留视频占位页
- 搜索不可用或无结果时：保留占位页和选题关键词，清单中如实标注"未搜到可用链接"
- 不下载、不嵌入任何视频文件
6. 生成 HTML 课件
- 复制 assets/courseware-template.html 到输出目录，命名为"课题.html"
- 按模板内的页面注释结构填充 courseware.json 的全部内容，把模板默认主题色替换为学科风格表中的主色
- 图片一律用相对路径 images/ 引用；image.path 为空的页面保留模板自带的占位样式
- 填充后自查：页数与 courseware.json 一致，无残留模板示例文字
7. 生成 PPTX 课件
python scripts/build_pptx.py <输出目录>/courseware.json -o <输出目录>/<课题>.pptx
- 退出码 0：生成成功
- 退出码 3：python-pptx 缺失，向用户展示 references/setup-guide.md 中的安装步骤，跳过 PPTX 继续交付
- 其他退出码：向用户展示脚本报错原文，PPTX 标注"未生成"，HTML 版照常交付
输出目录结构
<课题>-课件/
├── <课题>.pptx 可编辑课件（依赖可用时）
├── <课题>.html 可放映课件
├── courseware.json 课件数据源
├── images/ AI 配图
└── 视频链接清单.md 推荐视频链接
输出目录已存在同名文件时不覆盖：改为追加序号命名，或先征得用户同意再替换。
交付自查清单
交付前逐项确认，结果向用户如实说明：
- [ ] HTML 打开后页面完整，页数与 courseware.json 一致
- [ ] PPTX 已生成，或明确告知未生成及原因
- [ ] 每张插图要么真实存在，要么是标注了提示词的占位框
- [ ] 视频链接清单标注了来源平台；未搜到时如实说明
- [ ] 所有降级项在交付说明中逐一列明
- [ ] 教案外补充的内容已在 notes 中标注
停止条件
- 教案信息不足以确定课题和知识点：停止，向用户索要材料
- 教案内容违反法律法规或平台规范：停止并说明
- 无法保证 HTML 版核心输出时：停止并说明原因，不用编造内容顶替
边界
- 不下载、不嵌入视频文件，只提供链接和占位页
- 不使用网络图片，配图一律 AI 生成
- 不代替用户发布、上传课件到任何平台
- 不覆盖用户已有文件
