ppt-agent

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 種類のプリセットスタイルから 1 つを選びます。

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

ページタイプに応じた調整

ページタイプ	画像の特徴	プロンプトに追加するキーワード
表紙ページ	テーマの概要、強い視覚的インパクト	"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 #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 ごとに、1 回あたり 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 ページ目は完全なグラフ）	観客の理解を段階的に深められます

成果物：各ページ 1 つの 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 完整版冒烟测试