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

PPTX 可编辑管线技术规则

完整技术约束详见 pptx-pipeline.md。核心原则：

1. 背景仅承担装饰：用户可能调整的元素必须作为独立 PPTX shape/picture
2. data-pptx-role 驱动分层：content / content-icon / decoration / watermark 四角色
3. z-order：shapes → icons → text boxes
4. 原生控件优先：表格/图表优先用 python-pptx 原生 API，禁止手动 XML 注入

---

核心理念

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

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

---

环境感知

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

能力	降级策略
信息获取（搜索/URL/文档/知识库）	全部缺失 -> 依赖用户提供材料
图片生成（绝大多数环境都有）	缺失 -> 纯 CSS 装饰替代
文件输出	必须有
脚本执行（Python/Node.js）	缺失 -> 跳过自动打包和可编辑管线转换
Sub-agent / 并行代理（Agent tool / subagent）	可用 -> Step 4 策划和 Step 5c HTML 生成启用并行模式；缺失 -> 退回逐页串行

原则：检查实际可调用的工具列表，有什么用什么。检测 sub-agent 能力时，确认是否有 Agent 工具（或等价的 subagent 调用能力）。若有，在 progress.json 中标记 "has_subagent": true，后续 Step 4 和 Step 5c 自动启用并行模式。

---

路径约定

变量	含义	获取方式
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 页	5 题精简版（Q1+Q2+Q7+Q8+Q12）	3-5 个查询	整体生成（Step 3 可与 Step 4 合并）	逐页生成
标准	9-18 页	完整 12 题 + 动态追问	8-12 个查询	逐页生成	逐页生成
大型	> 18 页	完整 12 题 + 动态追问	10-15 个查询	逐页生成	逐页生成

复杂度判断时机：(1) 预判（Step 1 前）：据用户描述估算；明确页数或暗示简短则预判轻量并精简提问。(2) 确认（Step 1 后）：据 Q8 写入 progress.json 的 complexity_level（light / standard / large）。(3) 传递：后续步骤从 progress.json 读取并调整搜索数、策划深度等。

---

6 步 Pipeline

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

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

执行：references/prompts/prompt-1-research.md。有搜索则搜主题背景（3-5 条）并据此生成 Q2/Q5/动态追问选项；无搜索则用通用选项并跳过第五层动态追问。一次性发出 12 基础题 + 0-3 动态题，等待用户回复，再整理为需求 JSON。整理后须对照 quality-checks.md 中的消费审查矩阵自检；五层问题详表、Q7/轻量/动态追问全文亦在同文件。

问题层级（简表）：场景层 Q1-3 → 内容层 Q4-6 → 视觉层 Q7（须表格展示 8 种预置风格：蓝白商务/极简灰白/清新自然/暖色大地/朱红宫墙/暗黑科技/紫金奢华/活力彩虹，各附一句灵魂描述；用户选编号）→ 执行层 Q8-12 → 动态层 0-3 题（仅当搜索揭示主题关键分歧时追加，须标注消费节点）。

轻量模式（页数 <= 8 或暗示简短）：仅 Q1+Q2+Q7+Q8+Q12。动态追问：不凑数。

产物：需求 JSON（字段须完整）：

{
  "topic": "PPT 主题",
  "scene": "Q1 演示场景（现场演讲/自阅文档/培训教学/其他）",
  "audience": "Q2 核心受众画像",
  "purpose": "Q3 期望观众做什么",
  "narrative_structure": "Q4 叙事结构",
  "emphasis": ["Q5 内容侧重（可多选）"],
  "persuasion_style": ["Q6 说服力要素（可多选）"],
  "style_choice": "Q7 风格选择（A-J）",
  "style_detail": "Q7 附加信息（如选 J 时的自定义描述）",
  "page_count": "Q8 页数（数字或 null=AI 决定）",
  "info_density": "Q8 信息密度偏好（少而精/适中/信息量大）",
  "brand_info": {
    "presenter": "Q9 演讲人",
    "date": "Q9 日期",
    "company": "Q9 公司名",
    "brand_color": "Q9 品牌色（如有，覆盖 style_choice）",
    "logo_path": "Q9 Logo 路径"
  },
  "content_must_include": ["Q10 必须包含"],
  "content_must_avoid": ["Q10 必须回避"],
  "language": "Q11 语言偏好（中文/英文/中英混排/其他）",
  "image_preference": "Q12 配图偏好（A-D）",
  "dynamic_answers": {"问题文本": "用户回答"},
  "complexity_level": "light | standard | large（根据 page_count 判定）"
}

---

Step 2: 资料搜集

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

2a. 查询规划 — 按复杂度表控制查询数；维度与 JSON 整理模板见 execution-rules.md（Step 2 两节）。

2b. 并行搜索 — 搜索引擎、URL、文档、知识库等凡可用尽用。

2c. 结果整理 — 每组输出结构化 JSON（query + findings[]：fact / data / source / reliability high|medium|low / relevance）。仅 high/medium 可进策划 data_highlights；low 仅作参考。

产物：搜索结果集合 JSON。

---

Step 3: 大纲策划

执行：references/prompts/prompt-2-outline.md。方法论与 5 步思考过程全文见 execution-rules.md「Step 3」；prompt 内亦内置自动执行。

自检：页数合规；每 Part >= 2 页；Part 间逻辑递进；要点有搜索支撑（缺则 found_in_search: false）；design_rationale 与 transition_from_previous 完整。

产物：[PPT_OUTLINE] JSON（含 design_rationale）。

---

Step 4: 内容分配 + 策划稿 [STOP -- 完成后必须等用户确认]

内容分配与策划稿合并为一步；策划稿须为 AI 逐页思考的创作产物。核心：一页一 planning{n}.json，对应一页 HTML。 ⛔ 未经用户确认，禁止跳进 Step 5。

4a. 资源菜单预读（首页策划前一次）

策划第一页前按序读取（每项以 README 或指定章节为主，勿通读全书）：

优先级	路径	用途
0	principles/design-principles-cheatsheet.md	JSON 字段操作 + 逐页 8 项体检（必读第一项）
1	layouts/README.md	layout_hint
1b	layout-patterns.md	12 种布局模式、4 层结构、通用组件
2	blocks/README.md	card_type
3	blocks/card-styles.md	card_style
4	charts/README.md	chart_type
5	principles/README.md	原则索引
6	styles/README.md 的装饰技法工具箱章节	decoration_hints
7	image-generation.md（Q12 ≠ A 时）	image.prompt / image.usage

预读后从工具箱选型，避免只会 text+data+list。第 7 项仅在需要配图时读。

4b. 逐页策划

执行：references/prompts/prompt-3-planning.md。

占位符：{{DESIGN_PRINCIPLES_CHEATSHEET}}、{{RESOURCE_MENU}} 分别注入 cheatsheet 与 resource-menu.md 全文；其余从需求 JSON 填入（{{SCENE}} 等）。

设计感约束（须遵守）：拒绝千篇一律网页风；页与页版式须有反差与非对称；director_command 须给出具体、可执行的视觉与排版指令。

要点：逐页按 cheatsheet 尾部 8 项体检；映射搜索素材；主内容 40-100 字 + 数据亮点 + 辅助要点；layout_hint / card_type / chart_type 来自预读菜单；叙事节奏见 references/narrative-rhythm.md；每页 visual_weight、required_resources、image（总页数 >= 8 时全稿至少各用 1 次 split-content 与 card-inset）。

串并行、验证与操作边界

据 has_subagent 与复杂度选择串行或按 Part 并行；验证是写入流程的一部分（每页 planning_validator.py 单页验证，ERROR 必改）。4a 补充说明、4b 持久上下文与设计感约束、全量验证、Sub-agent 模板、操作边界 6 条、上下文传递 — 详见 execution-rules.md。

⛔ [GATE] 所有页完成后，必须执行且必须 PASS 才能继续：

# Step 1: 运行门禁脚本（内部调用 planning_validator.py）
bash SKILL_DIR/scripts/pipeline_gate.sh check-planning OUTPUT_DIR SKILL_DIR

# Step 2: 若有 ERROR，修正 planning JSON 后重跑，直到 PASS
# Step 3: PASS 后向用户展示策划概览，等待确认

planning_validator.py 返回 exit 1（FAILED）时 → 禁止继续，必须修正全部 ERROR。ERROR 修复参考各条错误提示中的「期望格式」说明。

修正跨页问题 → 向用户展示概览 → [STOP -- 等待用户确认]（可编辑 planning/planning{n}.json 后回复再继续）。

产物：OUTPUT_DIR/planning/planning{n}.json。

---

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

顺序：5a → 5b（可选）→ 5c。

5a. 风格决策

执行：references/styles/README.md 的灵动创作方法论（四步法）：情绪关键词 → 从情绪推导色彩 → 灵魂宣言 → 变奏策略；并读对应 styles/{id}.md。style.json 须含灵魂层、装饰基因、css_variables（12 项）、font_family — 校验清单见 quality-checks.md。调色板路径见 resource-registry.md 第 1 节。

产物：OUTPUT_DIR/style.json。

5b. 配图生成（可选）

读取每页 planning{n}.json 的 image；usage = none 则跳过；否则 generate_image 用 image.prompt，保存 OUTPUT_DIR/images/。须在生成该页 HTML 之前完成该页配图。

5c. 逐页 HTML

一对一：planning{n}.json → slides/slide-{NN}.html。

⛔ GATE CHECK（任何一步 BLOCKED 则禁止写 HTML）：

# [1] 确认 planning 通过门禁
bash SKILL_DIR/scripts/pipeline_gate.sh check-planning OUTPUT_DIR SKILL_DIR

# [2] 组装 prompt-ready 文件（全量批次）
python3 SKILL_DIR/scripts/prompt_assembler.py \
  OUTPUT_DIR/planning/ --refs SKILL_DIR/references \
  --style OUTPUT_DIR/style.json -o OUTPUT_DIR/prompts-ready/

# [3] 确认 prompts-ready 与 planning 数量一致
bash SKILL_DIR/scripts/pipeline_gate.sh check-prompts OUTPUT_DIR

# [4] 读全局资源（仅一次）
# view_file SKILL_DIR/references/styles/README.md
# view_file SKILL_DIR/references/principles/README.md
# view_file SKILL_DIR/references/blocks/README.md
# view_file SKILL_DIR/references/layout-patterns.md

每页：先 view_file OUTPUT_DIR/prompts-ready/prompt-ready-{n}.txt，再据完整 prompt 生成 HTML；禁止跳过 prompt-ready。三层资源决策、prompt_assembler 占位符说明、批量/单页命令、并行 HTML Sub-agent、核心设计约束与逐页 ASSERT 流程 — 详见 execution-rules.md。

逐页自检：写入前执行 quality-checks.md 中的 5 项自检。

跨页叙事：遵循 references/narrative-rhythm.md。

HTML 完成后：html_packager.py 生成 preview.html → 请用户审阅 → [STOP]（确认或改稿后再 Step 6）。

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

产物：OUTPUT_DIR/slides/*.html、preview.html。

---

Step 6: 管线选择 + 后处理 [必做]

用户确认 HTML 后必须跑转换管线，勿停在 preview。

6a. 管线选择 [STOP]

管线	路径	优势	劣势
A) PNG	HTML → PNG → PPTX	兼容极好；CSS 全保留	字不可编辑
B) 可编辑	HTML → Puppeteer + python-pptx	字可编辑；CSS 高级效果映射 OOXML	需 Node 18+ 与 python-pptx

等用户选 A 或 B。

6b. 执行转换

bash SKILL_DIR/scripts/setup.sh
pip install python-pptx lxml Pillow 2>/dev/null

管线 A：html2png.py → png2pptx.py（脚本自动选 Playwright / Puppeteer）。

python3 SKILL_DIR/scripts/html2png.py OUTPUT_DIR/slides/ -o OUTPUT_DIR/png/ --scale 2
python3 SKILL_DIR/scripts/png2pptx.py OUTPUT_DIR/png/ -o OUTPUT_DIR/presentation.pptx

管线 B：cd SKILL_DIR/scripts && npm install（首次）；node html2pptx.js ...

cd SKILL_DIR/scripts && npm install
pip install python-pptx lxml
node SKILL_DIR/scripts/html2pptx.js OUTPUT_DIR/slides/ -o OUTPUT_DIR/presentation.pptx

6c. 通知用户

说明 preview.html、presentation.pptx、png/（若用 A）及可编辑管线编辑能力；降级时说明原因与补装依赖。

---

执行规则（扩展）

策划与 HTML 阶段的串并行流程、Sub-agent 提示词模板、操作边界、Step 5c 资源决策树、prompt_assembler 与禁止行为等 — 详见 execution-rules.md。

---

质量检查、恢复与产物目录

需求消费审查矩阵、style.json 校验、HTML 5 项自检、全局质量表、progress.json 恢复流程、ppt-output/ 目录树、可移植性与首次使用 — 详见 quality-checks.md。

---

Reference 文件索引

完整映射见 resource-registry.md。

文件	何时读	内容
execution-rules.md	Step 4-5c 按需	串并行、Sub-agent 模板、资源决策树、prompt 组装、HTML 并行与约束
quality-checks.md	Step 1/5a/5c/恢复/部署	消费审查、style 校验、自检表、progress.json、目录结构、可移植性
prompts/prompt-1-research.md	Step 1	需求调研
prompts/prompt-2-outline.md	Step 3	大纲架构 v3.0
prompts/prompt-3-planning.md	Step 4	策划稿
prompts/prompt-4-design.md	prompt_assembler 内部	设计模板（勿手动读）
blocks/README.md	Step 4 首页前	复合组件
blocks/{type}.md	Step 4 + 5c 按需	8 种复合组件
principles/README.md	Step 4 首页前	6 大原则索引
principles/{name}.md	按需	各原则正文
principles/design-principles-cheatsheet.md	Step 4 首页前（第 0 项）	JSON 字段手册 + 体检单
resource-menu.md	经 {{RESOURCE_MENU}} 注入 prompt-3	资源速查
styles/README.md	Step 5a + 5c 首页前	色彩 + 装饰工具箱
styles/{id}.md	Step 5a	8 套调色板
layouts/README.md	策划 / 5c	布局总则
layout-patterns.md	5c GATE #2	布局模式 + 4 层结构 + 组件
layouts/{layout}.md	resource 组装	骨架
charts/{type}.md	resource 组装	图表模板
page-templates/{type}.md	resource 组装	页面结构建议
narrative-rhythm.md	Step 3 后	节奏与色彩递进
technique-cards.md	prompt_assembler	T1-T10 技法牌
resource-registry.md	维护	全局映射
pptx-pipeline.md	可编辑管线	PPTX 技术规则
scripts/prompt_assembler.py	Step 5c GATE	组装 prompt-ready
scripts/resource_assembler.py	内部	[RESOURCES] 块
scripts/planning_validator.py	Step 4	策划校验
scripts/setup.sh	首次 / 自检	环境
scripts/html2png.py	Step 6 A	截图
scripts/png2pptx.py	Step 6 A	PNG → PPTX
scripts/html2pptx.js	Step 6 B	可编辑管线入口
scripts/extract_slides.js	Step 6 B	Phase 1
scripts/assemble_pptx.py	Step 6 B	Phase 2
scripts/package.json	Step 6 B	Node 依赖
scripts/html_packager.py	Step 5c	preview.html