sunbigfly/ppt-agent-skills README：用状态机和 Gate 生成可预览、可导出的 PPTX

sunbigfly/ppt-agent-skills 是一个以 Agent Skill 形式运行的 PPT Agent 框架，目标是把一句演示需求拆成采访、资料、叙事大纲、全局风格、逐页生产、视觉检查和双格式 PPTX 导出。它面向需要生成路演 Deck、汇报材料、培训课件、产品介绍页或现有 PPT 美化的人，最终产物会落到 ppt-output/runs//，包括 preview.html、presentation-png.pptx、presentation-svg.pptx 和 delivery-manifest.json。

仓库 README 把它称为“基于软件工程理念的演示文稿全自动生成框架”。它的核心不是给出几套 PPT 模板，而是用状态机、Gate 校验、subagent 阶段隔离、Planning JSON、HTML 渲染和 Visual QA，把大模型做 PPT 时常见的幻觉、重叠、布局混乱和返工不可追踪问题拆开处理。

一分钟看效果

安装入口是 Skill 安装命令，不需要把它当成独立 Web 服务部署：

npx skills add sunbigfly/ppt-agent-skills

在支持 Skill 的代理环境中，直接输入演示需求即可触发完整流程，例如：

帮我生成一份关于 2026 年具身智能发展趋势的 15 页路演 Deck，暗色科技风格。

一次完整运行会创建带时间戳的 RUN_ID，并把采访记录、需求归一化结果、资料摘要、大纲、风格锁定、每页 planning、HTML、PNG、预览页和 PPTX 导出文件保存在同一条运行目录下。后续断点恢复不依赖单独进度状态文件，而是扫描磁盘上已经存在的产物来判断该从哪一步继续。

为什么需要状态机和 Gate

普通“直接生成 PPT”的方式容易把资料理解、页面叙事、视觉风格、版式实现和导出检查混在一次回答里。只要中间某一页出了问题，后面常常变成全局重做。ppt-agent-skills 的路线更接近软件工程流水线：每个阶段只处理自己的产物，产物落盘后经过 Gate 校验，通过后才进入下一步。

SKILL.md 对主 Agent 的边界写得很重：主 Agent 维护计划、调用 harness、管理 subagent 生命周期、校验 Gate，并和使用者交互；P2A/P2B/P3/P3.5/P4 的正式产物必须由对应 subagent 生成。这个设计把“谁负责资料整理、谁负责大纲、谁负责风格、谁负责单页规划和 HTML”分清，减少上下文互相污染。

核心功能

• Subagent 阶段隔离：Research、Source、Outline、Style、PageAgent 等阶段独立运行，完成即关闭，不复用上下文。
• 视觉 QA 闭环：每页 HTML 构建后生成截图，结合 planning 与 html 双层断言检查结构、装饰预算和溢出问题。
• 断点恢复：中断后通过 outline.txt、style.json、slide-N.png 等已落盘文件推断恢复点。
• 数据层与渲染层隔离：每页先生成 planningN.json，通过 planning_validator.py 后再驱动 HTML 渲染。
• 双引擎 PPTX 导出：PNG 光栅流强调跨平台视觉还原，SVG 矢量流保留更强的可编辑空间。
• v4.1 密度合同：README 最近更新里提到 Step 3 的 density_bias 和 Step 4 的 density_label / density_contract，页面密度预算开始进入可校验约束。

和普通 PPT 生成方式对比

工作流和产物链

README 给出的主链是固定的，从采访到交付分成 P0 到 P5：

P0 采访   →  P1 分支确认
P2A 联网检索 / P2B 本地资料压缩
P3 叙事大纲  →  P3.5 全局风格锁定
P4 逐页并行生产（Planning → HTML → Visual QA）
P5 Preview + 双 PPTX 导出

产物链也比较明确，适合运行后按文件检查：

interview-qa.txt → requirements-interview.txt
  → search.txt + search-brief.txt | source-brief.txt
  → outline.txt → style.json
  → planningN.json → slide-N.html → slide-N.png
  → preview.html → presentation-{png,svg}.pptx → delivery-manifest.json

这条链路的好处是每一步都有可复查文件。大纲不满意时看 outline.txt，风格跑偏时看 style.json，单页布局失败时看对应的 planningN.json、slide-N.html 和 slide-N.png，交付时再看预览页和两份 PPTX。

仓库结构

ppt-agent-skill/
├── SKILL.md          # 主控制台：状态机、Gate、恢复规则
├── scripts/          # 执行脚本（validator / harness / exporter）
├── references/       # 按需挂载的知识源
│   ├── playbooks/    # 各阶段子代理执行手册
│   ├── styles/       # 主题风格规范
│   ├── layouts/      # 版式资源
│   ├── charts/       # 图表模板
│   └── blocks/       # UI 组件
└── assets/

scripts/README.md 把脚本分成调度、校验、导出和辅助几类。调度侧有 prompt_harness.py、resource_loader.py、subagent_logger.py；校验侧有 contract_validator.py、planning_validator.py、milestone_check.py、visual_qa.py；导出侧有 html_packager.py、html2png.py、html2svg.py、png2pptx.py 和 svg2pptx.py。

环境和常用命令

普通使用者从安装命令开始即可：

npx skills add sunbigfly/ppt-agent-skills

维护或二次开发时，重点看 references/cli-cheatsheet.md，里面按步骤列出 SKILL_DIR、OUTPUT_DIR 等占位路径的替换方式。比如 Step 0 采访产物和需求归一化产物的 Gate 检查命令如下：

python3 SKILL_DIR/scripts/contract_validator.py interview OUTPUT_DIR/interview-qa.txt
python3 SKILL_DIR/scripts/contract_validator.py requirements-interview OUTPUT_DIR/requirements-interview.txt

如果改动模板、playbook、resource 或 validator，维护期可参考 scripts/README.md 里的 check_skill.py 和 smoke_skill.py。前者用于检查 markdown、prompt、validator 和资源之间的协议漂移；后者用于跑 Step 3/4 的最小端到端冒烟检查。

sunbigfly/ppt-agent-skills 更适合把 PPT 生产当作一条可复查的工程流水线来用：需求先落盘，资料先压缩，大纲和风格先锁定，每页再进入 planning、HTML、截图和视觉检查，交付时同时拿到网页预览与两种 PPTX。对经常做汇报、路演和培训材料的人来说，价值不只在“生成一份文件”，而在每次返工都能找到对应阶段和对应文件。