yqw-666/ppt-skills 使用教程：新模板解析和 PPT 脚本修复怎么分工

yqw-666/ppt-skills 是一组面向 PPT 课件生成的 Claude Code Skills，适合在“新模板来了”和“生成脚本有问题”这两个场景使用。它的输出不是直接给一份通用 PPT，而是帮助解析模板、建立讲义章节映射、生成新的 Python 生成脚本，再用结构检查、生成测试、截图和视觉诊断把脚本修到可交付状态。

一分钟看效果，可以先安装技能包，再用触发语选择对应流程：

npx skills add yqw-666/ppt-skills

README 里给出的触发方式很清楚：说“新模板来了”“换模板了”“生成新脚本”，进入 ppt-new-template；说“PPT有问题”“修改脚本”“跑测试”“验证效果”，进入 ppt-script-fix。先分清入口，后面才不会把模板解析和脚本修复混在一次对话里。

为什么需要它

课件 PPT 生成的问题通常不是“有没有脚本”，而是模板、讲义、版式、公式、图片、页序一起变化。旧脚本直接改，容易把一个版式修好，又把另一个版式改坏。这个仓库把工作拆成两段：新模板阶段先建立可靠映射，修复阶段再用可重复测试减少回归。

ppt-new-template 要求准备正课模板、小班课模板、代表性讲义和需求文档。它先解析 PPT 模板版式结构和 Word 讲义章节，再生成“Word 章节 → 版式名 → 占位符用途”的映射表，等确认后才生成新的 generate_ppt_v{版本}.py。

核心功能

ppt-new-template 的核心是模板解析与脚本生成。它通过 parse_template.py 输出版式名称、占位符索引、占位符类型、位置百分比、讲义章节关键词和候选映射。生成脚本时要求遵循 references/script_architecture.md 的类结构，分正课和小班课生成器，并显式处理中文字体、OMML 公式、图片和溢出缩小。

python3 {SKILL_DIR}/scripts/parse_template.py 正课ppt模板.pptx 讲义.docx
python3 {SKILL_DIR}/scripts/parse_template.py 小班课ppt模板.pptx 讲义.docx

排版质量不能只看截图。ppt-new-template 还要求运行程序化字体检查，验证单字母变量、正体词、OMML 里的数学样式，以及中文字体的 ea typeface="微软雅黑" 是否真正写进文件。

python3 {SKILL_DIR}/scripts/check_typography.py 输出.pptx

和普通 PPT 生成器的区别

普通 PPT 生成器更像“给主题，出页面”；yqw-666/ppt-skills 更像“把课件生成脚本工程化”。它关心的是模板版式、Word 章节、占位符映射、正课和小班课两个输出、WPS 兼容性、字体 XML、代表页截图和测试用例。适合长期维护一套课件流水线，不适合只想临时生成一份展示型幻灯片的人。

ppt-script-fix 则负责脚本修改后的验证闭环。首次使用时先建立 ppt_cases.json，之后通过测试驱动器生成 PPT、跑结构检查、截代表页，再把视觉问题定位回脚本。

工作流

新模板流程先跑解析，再确认映射，之后生成新脚本。修复流程先判断问题类型：版式名、页面顺序、字体名、页数属于结构性问题；图片位置、内容溢出、选项排列更偏视觉问题。结构问题先更新用例或检查规则，视觉问题再改生成脚本。

完整测试由 test_driver.py 统一驱动。它读取当前目录的 ppt_cases.json，调用生成脚本输出正课和小班课 PPT，再执行结构检查和截图。需要快速检查时用 --struct-only；只看某一讲时用 --case。

python3 {SKILL_DIR}/scripts/setup_cases.py
python3 {SKILL_DIR}/scripts/test_driver.py
python3 {SKILL_DIR}/scripts/test_driver.py --case 第15讲
python3 {SKILL_DIR}/scripts/test_driver.py --struct-only

仓库结构

仓库根目录包含 README.md、ppt-new-template/ 和 ppt-script-fix/。ppt-new-template/ 下有 SKILL.md、scripts/parse_template.py、scripts/check_typography.py，以及 references/script_architecture.md、references/math_italic_rules.md、模板分析资料。ppt-script-fix/ 下有 scripts/setup_cases.py、scripts/test_driver.py、scripts/structural_checks.py、scripts/take_screenshots.py 和 references/check_rules.md。

仓库没有单独的 requirements.txt。从脚本导入看，本地执行解析和测试时至少要有 Python 环境，并准备 python-pptx、python-docx 这类 PPT 与 Word 处理库；截图相关能力还要看本机 Office、WPS 或转换工具是否可用。安装 skill 后先在一个样例目录跑 setup_cases.py，比直接改生产脚本更稳。

yqw-666/ppt-skills 的重点是让课件 PPT 脚本有一套可复用的模板解析和验证方法。先用 ppt-new-template 建立新模板脚本，再用 ppt-script-fix 跑结构和截图闭环，适合把一次性生成改成长期维护的课件生产流程。