PPT Agent -- 专业演示文稿全流程生成
核心理念
模仿专业 PPT 设计公司（报价万元/页级别）的完整工作流，而非"给个大纲套模板"：
- 先调研后生成 -- 用真实数据填充内容，不凭空杜撰
- 策划与设计分离 -- 先验证信息结构，再做视觉包装
- 内容驱动版式 -- Bento Grid 卡片式布局，每页由内容决定版式
- 全局风格一致 -- 先定风格再逐页生成，保证跨页统一
- 智能配图 -- 利用图片生成能力为每页配插图（绝大多数环境都有此能力）
环境感知
开始工作前自省 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
- 搜索主题背景资料（3-5 条）
- 根据复杂度选择完整 7 题或精简 3 题，一次性发给用户
- 等待用户回复（阻断点）
- 整理为需求 JSON
7 题三层递进结构（轻量模式只问第 1、2、7 题）：
| 层级 | 问题 | 决定什么 |
|---|
| 场景层 | 1. 演示场景（现场/自阅/培训） | 信息密度和视觉风格 |
| 场景层 | 2. 核心受众（动态生成画像） | 专业深度和说服策略 |
| 场景层 | 3. 期望行动（决策/理解/执行/改变认知） | 内容编排的最终导向 |
| 内容层 | 4. 叙事结构（问题->方案/科普/对比/时间线） | 大纲骨架逻辑 |
| 内容层 | 5. 内容侧重（搜索结果动态生成，可多选） | 各 Part 主题权重 |
| 内容层 | 6. 说服力要素（数据/案例/权威/方法，可多选） | 卡片内容类型偏好 |
| 执行层 | 7. 补充信息（演讲人/品牌色/必含/必避/页数/配图偏好） | 具体执行细节 |
产物：需求 JSON（topic + requirements）
Step 2: 资料搜集
盘点所有信息获取能力，全部用上。
执行：
- 根据主题规划查询（数量参考复杂度表）
- 用所有可用的信息获取工具并行搜索
- 每组结果摘要总结
产物：搜索结果集合 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
依次执行：
-
合并预览 -- 运行 html_packager.py
python3 SKILL_DIR/scripts/html_packager.py OUTPUT_DIR/slides/ -o OUTPUT_DIR/preview.html
-
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。
-
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 中右键图片 -> "转换为形状" 即可编辑文字和形状。
-
通知用户 -- 告知产物位置和使用方式：
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 完整版冒烟测试