ppt-agent

name	ppt-agent
description	专业 PPT 演示文稿全流程 AI 生成助手。模拟顶级 PPT 设计公司的完整工作流（需求调研 -> 资料搜集 -> 大纲策划 -> 策划稿 -> 设计稿），输出高质量 HTML 格式演示文稿。当用户提到制作 PPT、做演示文稿、做 slides、做幻灯片、做汇报材料、做培训课件、做路演 deck、做产品介绍页面时触发此技能。即使用户只说"帮我做个关于 X 的介绍"或"我要给老板汇报 Y"，只要暗示需要结构化的多页演示内容，都应该触发。也适用于用户说"帮我把这篇文档做成 PPT"、"把这个主题做成演示"等需要将内容转化为演示格式的场景。

PPT Agent -- 专业演示文稿全流程生成

核心理念

模仿专业 PPT 设计公司（报价万元/页级别）的完整工作流，而非"给个大纲套模板"：

1. 先调研后生成 -- 用真实数据填充内容，不凭空杜撰
2. 策划与设计分离 -- 先验证信息结构，再做视觉包装
3. 内容驱动版式 -- Bento Grid 卡片式布局，每页由内容决定版式
4. 全局风格一致 -- 先定风格再逐页生成，保证跨页统一
5. 智能配图 -- 利用图片生成能力为每页配插图（绝大多数环境都有此能力）

---

环境感知

开始工作前自省 agent 拥有的工具能力：

能力	降级策略
信息获取（搜索/URL/文档/知识库）	全部缺失 -> 依赖用户提供材料
图片生成（绝大多数环境都有）	缺失 -> 纯 CSS 装饰替代
文件输出	必须有
脚本执行（Python/Node.js）	缺失 -> 跳过自动打包和 SVG 转换

原则：检查实际可调用的工具列表，有什么用什么。

---

路径约定

整个流程中反复用到以下路径，在 Step 1 完成后立即确定：

变量	含义	获取方式
SKILL_DIR	本 SKILL.md 所在目录的绝对路径	即触发 Skill 时读取 SKILL.md 的目录
OUTPUT_DIR	产物输出根目录	用户当前工作目录下的 ppt-output/（首次使用时 mkdir -p 创建）

后续所有路径均基于这两个变量，不再重复说明。

---

输入模式与复杂度判断

入口判断

入口	示例	从哪步开始
纯主题	"做一个 Dify 企业介绍 PPT"	Step 1 完整流程
主题 + 需求	"15 页 AI 安全 PPT，暗黑风"	Step 1（跳部分已知问题）
源材料	"把这篇报告做成 PPT"	Step 1（材料为主）
已有大纲	"我有大纲了，生成设计稿"	Step 4 或 5

跳步规则

跳过前置步骤时，必须补全对应依赖产物：

起始步骤	缺失依赖	补全方式
Step 4	每页内容文本	先用 Prompt #3 为每页生成内容分配
Step 5	策划稿 JSON	用户提供或先执行 Step 4

复杂度自适应

根据目标页数自动调整流程粒度：

规模	页数	调研	搜索	策划	生成
轻量	<= 8 页	3 题精简版（场景+受众+补充信息）	3-5 个查询	Step 3 可与 Step 4 合并一步完成	逐页生成
标准	9-18 页	完整 7 题	8-12 个查询	完整流程	按 Part 分批，每批 3-5 页
大型	> 18 页	完整 7 题	10-15 个查询	完整流程	按 Part 分批，每批 3-5 页，批间确认

---

6 步 Pipeline

Step 1: 需求调研 [STOP -- 必须等用户回复]

禁止跳过。 无论主题多简单，都必须提问并等用户回复后才能继续。不替用户做决定。

执行：使用 references/prompts.md Prompt #1

1. 搜索主题背景资料（3-5 条）
2. 根据复杂度选择完整 7 题或精简 3 题，一次性发给用户
3. 等待用户回复（阻断点）
4. 整理为需求 JSON

7 题三层递进结构（轻量模式只问第 1、2、7 题）：

层级	问题	决定什么
场景层	1. 演示场景（现场/自阅/培训）	信息密度和视觉风格
场景层	2. 核心受众（动态生成画像）	专业深度和说服策略
场景层	3. 期望行动（决策/理解/执行/改变认知）	内容编排的最终导向
内容层	4. 叙事结构（问题->方案/科普/对比/时间线）	大纲骨架逻辑
内容层	5. 内容侧重（搜索结果动态生成，可多选）	各 Part 主题权重
内容层	6. 说服力要素（数据/案例/权威/方法，可多选）	卡片内容类型偏好
执行层	7. 补充信息（演讲人/品牌色/必含/必避/页数/配图偏好）	具体执行细节

产物：需求 JSON（topic + requirements）

---

Step 2: 资料搜集

盘点所有信息获取能力，全部用上。

执行：

1. 根据主题规划查询（数量参考复杂度表）
2. 用所有可用的信息获取工具并行搜索
3. 每组结果摘要总结

产物：搜索结果集合 JSON

---

Step 3: 大纲策划

执行：使用 references/prompts.md Prompt #2（大纲架构师 v2.0）

方法论：金字塔原理 -- 结论先行、以上统下、归类分组、逻辑递进

自检：页数符合要求 / 每 part >= 2 页 / 要点有数据支撑

产物：[PPT_OUTLINE] JSON

---

Step 4: 内容分配 + 策划稿 [建议等用户确认]

将内容分配和策划稿生成合为一步。在思考每页应该放什么内容的同时，决定布局和卡片类型，更自然高效。

执行：使用 references/prompts.md Prompt #3（内容分配与策划稿）

要点：

• 将搜索素材精准映射到每页
• 为每页设计多层次内容结构（主卡片 40-100 字 + 数据亮点 + 辅助要点）
• 同时确定 page_type / layout_hint / cards[] 结构
• 每个内容页至少 3 张卡片 + 2 种 card_type + 1 张 data 卡片
• 布局选择参考 references/bento-grid.md 的决策矩阵

向用户展示策划稿概览，建议等用户确认后再进入 Step 5。

产物：每页策划卡 JSON 数组 -> 保存为 OUTPUT_DIR/planning.json

---

Step 5: 风格决策 + 设计稿生成

分三个子步骤，顺序不可颠倒：

5a. 风格决策

执行：阅读 references/styles/index.md 主索引（含决策矩阵），按主题关键词匹配 26 种预置风格之一

26 风格按 5 板块分组（详细 JSON 定义在板块文件中）：

板块	数量	风格 ID	板块文件
暗色专业	7	dark_tech / xiaomi_orange / luxury_purple / nocturne_violet / cyberpunk_neon / chrome_y2k / noir_film	references/styles/dark.md
浅色高级	8	blue_white / fresh_green / minimal_gray / mocha_editorial / medical_pulse / earth_concrete / champagne_gold / liquid_glass	references/styles/light.md
活力鲜明	4	vibrant_rainbow / kindergarten_pop / bauhaus_block / candy_pastel	references/styles/vibrant.md
东方文化	3	royal_red / sakura_wabi / ink_jade	references/styles/cultural.md
自然/复古	4	botanic_forest / safari_savanna / retro_70s / gov_authority	references/styles/natural.md

风格预览：执行 python3 SKILL_DIR/scripts/gallery.py 生成 ppt-output/style-gallery/index.html，浏览器打开可视化对比 26 风格。

也必读：references/typography.md（排版铁律：字距 / tabular-nums / OpenType / serif italic 混排 / 首字下沉 / 不对称网格 / 字体栈三层降级 / 微妙纹理）

产物：风格定义 JSON -> 保存为 OUTPUT_DIR/style.json

5b. 智能配图（根据用户偏好）

在需求调研（Step 1 第 7 题）中确认用户的配图偏好后执行。如果用户选择"不需要配图"则跳过。

配图时机

在生成每页 HTML 之前，先为该页生成配图。每页至少 1 张（封面页、章节封面必须有），生成后保存到 OUTPUT_DIR/images/。

generate_image 提示词构造公式

提示词必须同时满足 4 个维度，按以下公式组装：

[内容主题] + [视觉风格] + [画面构图] + [技术约束]

维度	说明	示例
内容主题	从该页策划稿 JSON 的核心概念提炼，具体到场景/对象	"DMSO molecular purification process, crystallization flask with clear liquid"
视觉风格	与 style.json 的配色方案和情感基调对齐	暗黑科技 -> "deep blue dark tech background, subtle cyan glow, futuristic"
画面构图	根据图片在页面中的放置方式决定	右侧半透明 -> "clean composition, main subject on left, fade to transparent on right"
技术约束	固定后缀，确保输出质量	"no text, no watermark, high quality, professional illustration"

风格与配图关键词对应

PPT 风格	配图风格关键词
暗黑科技	dark tech background, neon glow, futuristic, digital, cyber
小米橙	minimal dark background, warm orange accent, clean product shot, modern
蓝白商务	clean professional, light blue, corporate, minimal, bright
朱红宫墙	traditional Chinese, elegant red gold, ink painting, cultural
清新自然	fresh green, organic, nature, soft light, watercolor
紫金奢华	luxury, purple gold, premium, elegant, metallic
极简灰白	minimal, grayscale, clean, geometric, academic
活力彩虹	colorful, vibrant, energetic, playful, gradient, pop art

按页面类型调整

页面类型	图片特征	Prompt 额外关键词
封面页	主题概览，视觉冲击	"hero image, wide composition, dramatic lighting"
章节封面	该章主题的象征性视觉	"symbolic, conceptual, centered composition"
内容页	辅助说明，不喧宾夺主	"supporting illustration, subtle, background-suitable"
数据页	抽象数据可视化氛围	"abstract data visualization, flowing lines, tech"

禁止事项

• 禁止图片中出现文字（AI 生成的文字质量差）
• 禁止与页面配色冲突的颜色（暗色主题配暗色图，亮色主题配亮色图）
• 禁止与内容无关的装饰图（每张图必须与该页内容有语义关联）
• 禁止重复使用相同 prompt（每页图片必须独特）

产物：OUTPUT_DIR/images/ 下的配图文件

5c. 逐页 HTML 设计稿生成

执行：使用 references/prompts.md Prompt #4 + references/bento-grid.md

禁止跳过策划稿直接生成。 每页必须先有 Step 4 的结构 JSON。

每页 Prompt 组装公式：

Prompt #4 模板
+ 风格定义 JSON（5a 产物）[必须]
+ 该页策划稿 JSON（Step 4 产物，含 cards[]/card_type/position/layout_hint）[必须]
+ 该页内容文本（Step 4 产物）[必须]
+ 配图路径（5b 产物）[可选 -- 无配图时省略 IMAGE_INFO 块]

核心设计约束（完整清单见 Prompt #4 内部）：

• 画布 1280x720px，overflow:hidden
• 所有颜色通过 CSS 变量引用，禁止硬编码
• 凡视觉可见元素必须是真实 DOM 节点，图形优先用内联 SVG
• 禁止 ::before/::after 伪元素用于视觉装饰、禁止 conic-gradient、禁止 CSS border 三角形
• 配图融入设计：渐隐融合/色调蒙版/氛围底图/裁切视窗/圆形裁切（技法详见 Prompt #4）

分批策略：按 Part 为单位分批生成，每批 3-5 页。每批完成后将 HTML 写入 OUTPUT_DIR/slides/ 目录，再开始下一批。避免上下文爆炸的同时保证同一 Part 内的风格一致性。

跨页视觉叙事（让 PPT 有节奏感，不只是独立页面的堆砌）：

策略	规则	原因
密度交替	高密度页（混合网格/英雄式）后面跟低密度页（章节封面/单一焦点），形成张弛有度的节奏	连续 3+ 页高密度内容会导致观众视觉疲劳
章节色彩递进	Part 1 卡片主用 accent-1，Part 2 用 accent-2，Part 3 用 accent-3 ... 每章换一种 accent 主色	通过颜色让受众无意识感知章节切换
封面-结尾呼应	结束页的视觉元素与封面页形成呼应（相同装饰图案、对称布局），给出完整闭环感	首尾呼应是最基本的叙事美学
渐进揭示	同一概念跨多页展开时，视觉复杂度应递增（第1页简单色块 -> 第2页加数据 -> 第3页完整图表）	引导观众逐步深入理解

产物：每页一个 HTML 文件 -> OUTPUT_DIR/slides/

---

Step 6: 后处理 [必做 -- HTML 生成完后立即执行]

禁止跳过。 HTML 生成完后必须自动执行以下四步，不要停在 preview.html 就结束。

slides/*.html --> preview.html --> svg/*.svg --> presentation.pptx

依赖检查（首次运行自动执行）：

pip install python-pptx lxml Pillow 2>/dev/null

依次执行：

1. 合并预览 -- 运行 html_packager.py

   python3 SKILL_DIR/scripts/html_packager.py OUTPUT_DIR/slides/ -o OUTPUT_DIR/preview.html
   

2. SVG 转换 -- 运行 html2svg.py（DOM 直接转 SVG，保留 <text> 可编辑）

   重要：HTML 设计稿必须遵守 references/pipeline-compat.md 中的管线兼容性规则，否则转换后会出现元素丢失、位置错位等问题。

   python3 SKILL_DIR/scripts/html2svg.py OUTPUT_DIR/slides/ -o OUTPUT_DIR/svg/
   

   底层用 dom-to-svg（自动安装），首次运行会 esbuild 打包。 降级：如果 Node.js 不可用或 dom-to-svg 安装失败，跳过此步和步骤 3，只输出 preview.html。

3. PPTX 生成 -- 运行 svg2pptx.py（OOXML 原生 SVG 嵌入，PPT 365 可编辑）

   python3 SKILL_DIR/scripts/svg2pptx.py OUTPUT_DIR/svg/ -o OUTPUT_DIR/presentation.pptx --html-dir OUTPUT_DIR/slides/
   

   PPT 365 中右键图片 -> "转换为形状" 即可编辑文字和形状。

4. 通知用户 -- 告知产物位置和使用方式：

   • preview.html -- 浏览器打开即可翻页预览
   • presentation.pptx -- PPTX（右键 -> "转换为形状" 可编辑）
   • svg/ -- 每个 SVG 也可单独拖入 PPT
   • 如果步骤 2-3 被降级跳过，说明原因并告知用户手动安装 Node.js 后可重新运行

产物：preview.html + svg/*.svg + presentation.pptx

---

输出目录结构

ppt-output/
  slides/              # 每页 HTML
  svg/                 # 矢量 SVG（可导入 PPT 编辑）
  images/              # AI 配图
  preview.html         # 可翻页预览
  presentation.pptx    # 可编辑 PPTX（右键"转换为形状"）
  outline.json         # 大纲
  planning.json        # 策划稿
  style.json           # 风格定义

---

质量自检

维度	检查项
内容	每页 >= 2 信息卡片 / >= 60% 内容页含数据 / 章节有递进
视觉	全局风格一致 / 配图风格统一 / 卡片不重叠 / 文字不溢出
技术	CSS 变量统一 / SVG 友好约束遵守 / HTML 可被 Puppeteer 渲染 / pipeline-compat.md 禁止清单检查

---

资源路由表（字段 → 文件夹）

策划稿 JSON 中各字段决定从哪个目录抽取相应资源：

• 字段路由：layout_hint→layouts/、page_type→page-templates/、card_type→blocks/、chart_type→charts/

字段	取值	路由到	例
layout_hint	asymmetric / hero-top / l-shape / mixed-grid / primary-secondary / single-focus / symmetric / t-shape / three-column / waterfall	references/layouts/<name>.md	主次结合 → references/layouts/primary-secondary.md
page_type	cover / toc / section / end	references/page-templates/<name>.md	封面 → references/page-templates/cover.md
card_type	text / data / list / quote / timeline / comparison / diagram / image-hero / matrix-chart / people	references/blocks/<name>.md	数据卡 → references/blocks/card-styles.md
chart_type	progress-bar / ring / sparkline / radar / funnel / kpi / metric-row / waffle / rating / timeline / treemap / comparison-bar / stacked-bar	references/charts/<name>.md	雷达 → references/charts/radar.md

Step 0/1 采访模板规则

Step 0 默认强制模板化：主 agent 必须先生成 OUTPUT_DIR/runtime/prompt-interview.md，再依据渲染结果向用户发问；采访运行时模板必须按能力在 tpl-interview-structured-ui.md 与 tpl-interview-text-fallback.md 之间二选一。

Step 0 优先结构化采访 UI：只要当前 CLI 提供任何等价于 AskUserQuestion / request_user_input 的原生提问能力，主 agent 就必须优先使用结构化采访 UI；不支持时回退到 tpl-interview-text-fallback.md。

Step 0 唯一例外：仅当 prompt 生成在 Step 0 发生真实脚本接口故障，并已判定 BLOCKED_SCRIPT_INTERFACE 时，才允许主 agent 直接发问；但覆盖维度不得低于 prompt-interview.md 的最终要求。

详细模板：references/prompts/tpl-interview.md · references/prompts/tpl-interview-structured-ui.md · references/prompts/tpl-interview-text-fallback.md

Reference 文件索引

文件	何时阅读	关键内容
references/prompts.md	每步生成前（合并版）	5 套 Prompt 模板（调研/大纲/策划/设计/备注）
references/prompts/*.md	模块化版本（23 文件）	按 step + module + tpl 拆分的 Prompt 模板
references/playbooks/*.md	每步执行手册（11 文件）	outline / research / source / style / step4 各 phase 的执行 playbook
references/styles/index.md	Step 5a	26 种预置风格索引 + 决策矩阵 + JSON Schema
references/styles/{dark,light,vibrant,cultural,natural}.md	Step 5a 选定风格后	该板块所有风格的完整 JSON + CSS 变量 + Mock 链接
references/typography.md	Step 5c	排版铁律 14 条（字距/tabular-nums/OpenType/serif italic 混排/字体栈降级）
references/charts/index.md	Step 5c 涉及数据可视化时	18 种图表索引 + 决策矩阵
references/charts/{basic,advanced,complex}.md	选定图表后	完整 HTML 模板（基础 8 种 / 进阶 6 种 / ECharts 级 4 种）
references/charts/<chart_type>.md	单一图表精细规格	sunbigfly 风格的单文件图表（13 个）
references/layouts/*.md	Step 5c layout_hint 路由	10 个 layout 各成文件（asymmetric / hero-top / l-shape 等）
references/blocks/*.md	Step 5c card_type 路由	9 个可复用卡片原型（card-styles / comparison / diagram / quote 等）
references/page-templates/*.md	Step 5c page_type 路由	4 个页面模板（cover / end / section / toc）
references/principles/*.md	Step 4-5 自检与原则	8 设计原则 + failure-modes（cognitive-load / color-psychology / composition / data-visualization / narrative-arc / runtime-failure-modes / visual-hierarchy）
references/design-runtime/*.md	Step 5c 设计运行时	css-weapons / data-type-decoration-mapping / data-type-visual-mapping / design-specs / director-command-rules-examples
references/bento-grid.md	Step 5c	7 种布局精确坐标 + 5 种卡片类型 + 决策矩阵
references/method.md	初次了解	核心理念与方法论
references/pipeline-compat.md	Step 5c 设计稿生成时	CSS 禁止清单 + 图片路径 + 字号混排 + SVG text + 环形图 + svg2pptx 注意事项
references/cli-cheatsheet.md	脚本调用查阅	所有 scripts 的完整调用命令速查
references/style-system.md	（兼容引导文件）	已升级为引导文件，redirect 到 styles/index.md

维护与校验

真源文件：

资源	真源位置	用途
Step 4 schema	scripts/planning_validator.py	P4 planning Gate
Workflow 版本	scripts/workflow_versions.py	跨脚本版本号
Skill 一致性	scripts/check_skill.py	文档/代码合同漂移检查

自动检查入口：修改 prompt / playbook / cheatsheet / Step 4 schema 示例后，运行：

python3 scripts/check_skill.py            # 文档与代码合同漂移检查
python3 scripts/planning_validator.py     # 策划稿 schema 校验
python3 scripts/contract_validator.py     # 各 phase 间 JSON 合同校验
python3 scripts/visual_qa.py              # 视觉 QA 双层断言（planning + html）
python3 scripts/smoke_test.py             # 我们简化版端到端冒烟测试
python3 scripts/smoke_skill.py            # sunbigfly 完整版冒烟测试