pptx-from-layouts

基于布局的 PPTX — 步骤 3：渲染

通过填充模板的实际幻灯片母版布局，将 Markdown 大纲转换为适合顾问使用的 PowerPoint 演示文稿。核心原则：使用模板布局和占位符，绝不要在幻灯片上叠加文本框。

三步工作流

此技能是由三个技能组成的工作流中的步骤 3。每个步骤都是一个独立技能：

  STEP 1 — PROFILE          STEP 2 — AUTHOR           STEP 3 — RENDER  ◀ you are here
  pptx-profile              pptx-author               pptx-from-layouts
  ───────────────           ───────────────           ─────────────────
  your-template.pptx        slides.md (+ [HINT:])     slides.md + config
        │                         │                         │
        ▼                         ▼                         ▼
   catalog.py  ──catalog.md──▶  write & lint  ──slides──▶  generate.py ─▶ deck.pptx
        └────────────────── config.json ───────────────────▲   (validated)
  "what layouts do I        "write slides that        "fill the template's
   have?"                    name real layouts"        actual placeholders"

• 步骤 1 — pptx-profile： catalog.py 将 .pptx 转换为布局目录（[HINT:] 名称列表）和渲染用的 config.json。每个模板只需执行一次。
• 步骤 2 — pptx-author： 为每张幻灯片编写带有 [HINT: layout_name] 的 slides.md，然后由 lint_hints.py 根据目录验证这些提示。
• 步骤 3 — 此技能： generate.py 填充指定布局并进行验证。

你也可以直接从这里开始，使用随附的 Inner Chapter 模板（无需步骤 1）；它是默认模板，也是本文档中贯穿始终的示例。

[HINT:] — 根据实际布局编写内容

幻灯片可以指定其应使用的确切模板布局：

# Slide 2: Three outcomes the research must achieve

[HINT: column-3-centered-a]

[Column 1: Level-set] …

[HINT:] 会根据当前模板配置（来自步骤 1）解析，因此适用于任何已配置的模板，而不仅限于 Inner Chapter。它等同于 **Layout:** 标记，且优先级高于 **Visual:**。已知布局时使用 [HINT:]（精确指定）；希望引擎根据语义意图自动选择布局时（例如 process-4-phase），使用 **Visual:**。提示不匹配时会发出警告并回退到自动检测，因此请先在步骤 2 中运行 lint。

依赖项（请先检查）

需要 Python 3.10+、python-pptx 和 pydantic：

pip install python-pptx pydantic     # or: pip install -r requirements.txt

如果遇到 ModuleNotFoundError: No module named 'pptx' 或 'pydantic'，原因就在这里。入口脚本会自行设置 PYTHONPATH；请直接使用 python 运行。

决策：我该选择哪条路径？

用户需求…	操作
根据简报／笔记／源文档生成演示文稿（尚无大纲）	委托 pptx-outline-architect，然后生成
生成演示文稿，且已经编写好大纲	运行 generate.py → 验证
使用自己的 PowerPoint 作为模板	委托 pptx-template-onboarder（只需设置一次）
对现有演示文稿进行小范围文本修正／重排（少于 30% 的幻灯片）	使用 edit.py（清点 → 替换／重排）
更改布局、新增／删除幻灯片，或变动超过 30%	使用 generate.py 重新生成，绝不要编辑
判断演示文稿是否合格	委托 pptx-deck-qa 或运行 validate.py

必须遵循的生成工作流（请勿跳过步骤）

1. 选择或确认模板。 首次使用自定义模板？请先进行一次接入（参见下文的自带模板）。否则，默认使用随附的 Inner Chapter 模板。
2. 编写大纲，并确保每张内容幻灯片都声明 **Visual: <type>**。根据下文的决策顺序选择视觉类型，不要默认全部使用项目符号。
3. 生成：

   python scripts/generate.py outline.md -o deck.pptx --validate
   

   （使用自定义模板时，添加 --template <t.pptx> --config <c.json>。）
4. 验证并查看报告。 只有在验证无错误且无文本溢出后，演示文稿才算完成。否则，请修正后重新运行。
5. 向用户报告评分和输出路径。

完成标准（声明成功前请自检）

• 每张内容幻灯片都明确声明了 **Visual:**。
• generate.py 成功退出，且 .pptx 文件存在。
• validate.py 报告零错误且无文本溢出。
• 未使用以下反模式（列表使用 hero-statement、流程使用表格、比较使用项目符号，……）。
• 已报告验证评分和文件路径，而不只是说“完成”。

如果有任何一项未勾选，任务就尚未完成；请修正问题，或明确说明受阻原因。

子 Agent

规范定义位于 agents/；安装到 ~/.claude/agents/ 即可使用。

子 Agent	用途
pptx-outline-architect	将原始材料整理为可直接用于生成的 outline.md，并选择正确的视觉类型
pptx-template-onboarder	将用户的 .pptx 配置为可重复使用且符合品牌风格的模板（仅需一次）
pptx-deck-qa	验证演示文稿，并进行精准修复或建议重新生成

它们的工作流程为 architect → generate.py → QA；如果使用自己的模板， 则先由 onboarder 执行一次。（完整说明：仓库中的 docs/workflows.md。）

快速开始

# Generate from outline (bundled Inner Chapter template, with validation)
python scripts/generate.py outline.md -o deck.pptx --validate

# Use your own template
python scripts/generate.py outline.md -o deck.pptx \
    --template your-template.pptx --config your-template-config.json --validate

# Edit existing deck (dump inventory, edit its JSON, apply as a file)
python scripts/edit.py deck.pptx --inventory -o inv.json
#   edit inv.json: change the text on the paragraph(s) you care about
python scripts/edit.py deck.pptx --replace inv.json -o edited.pptx

# Validate quality
python scripts/validate.py deck.pptx

# Profile a custom template (one-time onboarding)
python scripts/profile.py template.pptx --name my-template --generate-config

使用自己的模板（配置一次，之后永久自动化）

内置模板仅供演示。若要制作符合品牌风格的演示文稿，只需将自己的 .pptx 配置一次 — 分析模板、生成布局映射配置、进行冒烟测试， 之后即可在未来的每份演示文稿中重复使用。

python scripts/profile.py /path/to/your-template.pptx \
    --name your-template --generate-config --output-dir templates/

这会生成 your-template-config.json。之后，每份演示文稿只需调用一次 generate.py，并使用 --template/--config。完整指南： rules/bring-your-own-template.md。如需自动完成整个流程，可委托给 pptx-template-onboarder。

视觉类型

在大纲中使用 **Visual: type-name** 声明。

类型	适用场景
process-N-phase	顺序步骤（N=2-5）
comparison-N	并排展示的选项（N=2-5）
cards-N	非顺序的并列项目（N=2-5）
data-contrast	两项对比指标
quote-hero	有感染力的引言
hero-statement	仅适用于单句、有力的陈述
timeline-horizontal	基于日期的序列
table	真正的表格数据
bullets	默认类型（3 项以上）— 最后选择

**决策顺序：**顺序 → 对比 → 并列项目 → 数据对比 → 引言 → 表格 → 主视觉 → 项目符号。完整参考及各类型的长度限制： rules/visual-types.md。

排版标记

行内	效果		段落	效果
{blue}text{/blue}	IC 品牌蓝		{bullet:-}	短横线项目符号（–）
{bold}text{/bold}	粗体		{bullet:1}	编号
{italic}text{/italic}	斜体		{level:N}	缩进级别
{question}text?{/question}	蓝色斜体
{signpost}LABEL{/signpost}	章节标签

大纲示例

# Project Overview
**Visual: hero-statement**
Transforming operations through digital innovation

# Our Approach
**Visual: process-4-phase**

[Column 1: Discover]
- Stakeholder interviews
- Competitive audit
[Image: research process]

[Column 2: Define]
- Workshop facilitation
- Strategic framework

[Column 3: Design]
- Solution architecture
- Prototype development

[Column 4: Deliver]
- Implementation
- Training & handover

编辑工作流

# 1. Dump the inventory — this is the schema replace.py consumes
python scripts/edit.py project.pptx --inventory -o inv.json
# 2. Open inv.json, find the target paragraph, change only its "text" field.
#    e.g. inv.json["slide-2"]["shape-3"]["paragraphs"][0]["text"] = "Q2 2026"
# 3. Apply, then validate
python scripts/edit.py project.pptx --replace inv.json -o updated.pptx
python scripts/validate.py updated.pptx

模式选择

更改类型	操作
新建演示文稿	generate.py
拼写错误/数值（少于 30% 的幻灯片）	edit.py
重新排列幻灯片	edit.py --reorder
布局更改	重新生成
添加/删除幻灯片	重新生成
更改超过 30% 的幻灯片	重新生成

反模式（禁止）

• 不要跳过 **Visual:** 声明 — 解析器的默认类型可能不匹配。
• 当更丰富的视觉类型适用时，不要默认使用项目符号 — 项目符号是 最后的选择，而不是条件反射。
• 不要将 hero-statement 用于 3 项以上内容或多句内容。
• 不要用表格展示方法论/流程（请使用 process-N-phase）。
• 不要用项目符号列表展示并排对比（请使用 comparison-N）。
• 不要在布局更改或添加/删除幻灯片时使用编辑模式 — 请重新生成。
• 不要编辑超过 30% 的幻灯片 — 请改为重新生成。
• 未通过完整验证前，不要宣称成功。

另请参阅

面向作者的规则位于 rules/： outline-format.md、visual-types.md、typography.md、columns.md、 tables.md、editing.md、bring-your-own-template.md、decisions.md。

参考资料：references/layouts.md（内页章节布局索引）。 子 Agent：agents/（此技能）。工作流说明：docs/workflows.md（仓库）。