Ppt Agent

ppt-agent

把一个主题（或一份文档）变成可演讲的 PPT。底层是整页 SVG（viewBox 0 0 1280 720），同时产出：

1. deck.html — 浏览器里左右键翻页的预览
2. deck.pptx — 在 PowerPoint 2019+ / Office 365 / Keynote 里可编辑的矢量 PPT
3. deck.pdf（可选）

设计理念（先读完再开工）

这个 skill 模仿 sandun 的"最强 PPT Agent"方法论，关键差异点是在大纲和设计之间插入"策划稿"——每页放什么版式、什么槽位先定死，再去渲染。这是市面 AI PPT 工具普遍跳过的环节，也是质量分水岭。

四个核心反直觉：

1. 不要听到主题就直接出大纲。 先反问 3-5 个问题（受众/场景/时长/调性/页数），写到 brief.md。这是质量上限的瓶颈。
2. 大纲走金字塔原理（结论先行 + 以上统下 + 归类分组 + 逻辑递进）。详见 [reference/pyramid-outline-prompt.md](reference/pyramid-outline-prompt.md)。
3. 策划稿先于设计。每页是哪种 Bento 布局（6 选 1）、放哪些卡片（component），先固化到 layout.json，再渲染 SVG。详见 [reference/bento-layouts-guide.md](reference/bento-layouts-guide.md)。
4. 底层是 SVG 不是 HTML。理由：PowerPoint 2019+ 原生支持矢量 SVG，文字可编辑、无限放大。HTML 只用于浏览器预览。

7 阶段工作流

| # | 阶段 | 你做什么 | 脚本做什么 | 产物 | |---|---|---|---|---| | 1 | needs | 反问 3-5 个问题，把答案写进 brief.md | ppt new 起工作区 | brief.md | | 2 | research | 用 WebSearch 按主题分章节搜真实材料 | — | research/.md | | 3 | outline | 套金字塔原理 prompt 出大纲 | — | outline.json | | 4 | planning | 把大纲转成 layout.json（每页选布局 + 槽位 component + 内容草稿） | — | layout.json | | 4.5 | fetch（可选） | 给 card-image 填 src=URL 或 source 规格 | ppt fetch 调 provider 下载/生成到 /assets/ | assets/*.png | | 5 | design | 检查 layout.json 内容质量 | ppt scaffold 调 render 装配 SVG | slides/*.svg | | 6 | review | 看截图清单（溢出/对比度/中英排版/重复） | ppt shoot 截图 + 生成 deck.html | shots/*.png、deck.html | | 7 | export | 决定导出格式 | ppt export | deck.pptx / deck.pdf |

任何阶段失败都可以单独重跑，不需要从头来。fetch 阶段也永远不会因为下载失败阻塞主流程（详见 [reference/image-providers.md](reference/image-providers.md)）。

阶段 1：需求调研（关键）

启动后第一件事是反问。不要默认用户给的主题已经够清楚了。

ppt new ""
# 输出 ~/ppt-decks/-/

然后向用户问以下问题（一次问完，不要逐个），把答案写到 /brief.md：

1. 目标受众是谁？ （投资人 / 客户 / 内部团队 / 行业大会观众）
2. 场景和时长？ （15 分钟产品发布 / 5 分钟电梯演讲 / 30 分钟内训）
3. 核心目标？ （让对方掏钱 / 让对方点头 / 让对方转发 / 让对方学到东西）
4. 调性偏好？ （严肃专业 / 活泼有趣 / 极简克制 / 数据密集）
5. 页数预算？ （8 页内 / 15-20 页 / 30+ 页）
6. 必须出现的内容？ （某个产品截图 / 某个数据 / 团队照 / 客户 logo 墙）

如果用户已经给了文档，先 Read 一遍，然后只问没有覆盖的问题。

brief.md 模板由 ppt new 自动写入，照着填即可。

阶段 2：资料检索

按 brief.md 里的核心主题，用 WebSearch 工具分章节搜资料，结果落到 /research/.md。

禁止凭空捏造数据/事实——所有数字、产品特性、市场状况必须有出处。检索结果用来"喂"阶段 3 的大纲，不是直接抄。

阶段 3：大纲

读完 brief.md + research/，套用金字塔原理 prompt 生成大纲，输出到 /outline.json。

完整 prompt 见 [reference/pyramid-outline-prompt.md](reference/pyramid-outline-prompt.md)（直接复用 sandun 开源的"顶级 PPT 结构架构师"v2.0）。

outline.json schema（关键字段）：

{
  "ppt_outline": {
    "cover": { "title": "...", "sub_title": "...", "content": [] },
    "table_of_contents": { "title": "目录", "content": ["第一部分", "第二部分", ...] },
    "parts": [
      {
        "part_title": "第一部分：...",
        "pages": [
          { "title": "页面标题", "content": ["要点 1", "要点 2", ...] }
        ]
      }
    ],
    "end_page": { "title": "总结与展望", "content": [] }
  }
}

阶段 4：策划稿（最容易跳过的关键步骤）

把 outline.json 的每一页转化成具体的 layout 选型 + 槽位填充。输出到 /layout.json。

完整布局指南、选型规则、槽位 schema 见 [reference/bento-layouts-guide.md](reference/bento-layouts-guide.md)。

6 种 Bento 布局（速查）：

| layout | 适合 | viewBox 用法 | |---|---|---| | single-focus | 1 个核心数字 / 1 张大图 / 1 句金句 | 1 个大卡片占满 | | two-col-symmetric | 对比、并列两个概念 | 2 张等宽卡片 | | two-col-asymmetric | 主内容 + 数据/图片辅助 | 2/3 + 1/3 | | three-col | 三步流程、三个特性 | 3 张等宽卡片 | | major-minor | 1 个主信息 + 2-3 个支撑细节 | 中央大卡 + 侧边小卡 | | hero-top | 顶部一句话 + 下方多个要点 | 横幅 + 2-4 等宽卡片 | | mixed-grid | 内容多样、有数据有图 | 自由混合 |

每页 component 选自（在卡片内填充）：card-hero / card-stat / card-stack / card-list / card-quote / card-text / card-image / card-compare / chart-bar。详见 reference 文档。

页面还支持可选的 ghost_text 字段（3-10 个英文/数字字符），在背景渲染巨型半透明装饰文字（opacity 0.04），适合章节首页和核心数据页：

{ "page": 3, "ghost_text": "VISION", "layout": "single-focus", "cards": [...] }

阶段 5：设计渲染

确认 layout.json 内容质量后（中文标点、字数控制、必须信息齐全），运行：

ppt scaffold                         # 渲染所有页（默认主题 bento-tech）
ppt render  --page 3                 # 重渲第 3 页
ppt render  --theme bento-light      # 切换为浅色主题重渲

可用主题：bento-tech（深色科技风，默认）/ bento-light（浅色商务风）。也可在 layout.json 顶层设 "theme": "bento-light" 固定主题。

渲染前会自动跑 lint_cn.py 检查中文版式。命中阻断会要求重写——这不是警告，是错误。

阶段 6：截图自校

ppt shoot 

会用 playwright headless chromium 把每页 SVG 渲染成 PNG（放到 /shots/），并生成 /deck.html 多页翻页预览（左右键翻页 + 缩略图栏）。

然后 Read 截图，按下面清单逐页检查：

• [ ] 文字溢出卡片边界
• [ ] 中英文之间多余空格、英文标点（应是中标点）
• [ ] 主标题被装饰元素遮挡
• [ ] 配色对比度过低（白底白字、深底深字）
• [ ] 重复元素（同一图标/装饰被复制粘贴的痕迹）
• [ ] viewBox 越界（内容跑到 1280×720 外）

发现问题：改 layout.json → ppt render --page N 单页重渲。

阶段 7：导出

ppt export  --format pptx       # 默认：Native renderer（python-pptx 原生 shape，100% 可编辑）
ppt export  --format pptx-svg   # 备选：svgBlip 注入（SVG 矢量，好看但 PowerPoint 把整页当图片对象，需手动"转换为形状"）
ppt export  --format pdf        # chrome --print-to-pdf 转 deck.html
ppt export  --format html       # 单文件版 deck-standalone.html

pptx（默认 / 推荐）：

• 用 scripts/native_render.py 直接渲染 PowerPoint 原生 shape
• 单击文字 → 直接进入编辑模式
• 单击卡片背景 → 拖动 / 调色 / 加边框
• 视觉妥协：无渐变 / 无装饰光斑 / 无网格纹理（"商务平面"风格），但布局结构与 SVG 版完全一致

pptx-svg（备选）：

• 现行 svgBlip OOXML 注入方案
• PowerPoint 2019+/365 显示完美矢量（保留所有渐变 / 光斑 / 网格）
• 但每页是一个 picture 对象，要右键"转换为形状"才能编辑文字（且转换会丢渐变）
• 适合"出片好看、不需要二次编辑"的场景

详见 [reference/pptx-rendering.md](reference/pptx-rendering.md)。

CLI Reference

所有命令位于 ${CLAUDE_SKILL_DIR}/scripts/ppt.py（如未定义，回退到 ~/.claude/skills/ppt-agent/scripts/ppt.py）。

SKILL=${CLAUDE_SKILL_DIR:-$HOME/.claude/skills/ppt-agent}

python3 $SKILL/scripts/ppt.py new ""
python3 $SKILL/scripts/ppt.py fetch 
python3 $SKILL/scripts/ppt.py scaffold 
python3 $SKILL/scripts/ppt.py render  [--page N] [--theme ]
python3 $SKILL/scripts/ppt.py shoot 
python3 $SKILL/scripts/ppt.py export  --format pptx|pdf|html

工作区根目录默认 ~/ppt-decks/，可通过 env PPT_DECKS_DIR 覆盖。

每个工作区根有 .layout 标识文件，所有命令都会校验合法性以防误操作。

Prerequisites

首次使用前需要 Python 依赖：

pip3 install jinja2 python-pptx lxml

截图（ppt shoot）自动探测系统已安装的 Chrome / Chromium / Edge / Brave，无需额外配置。找不到浏览器时请安装 Chrome 后重试。

添加新主题

只需创建 themes//manifest.json，模板文件自动从 bento-tech 继承：

mkdir themes/
# 复制 bento-light/manifest.json 作为浅色底板，或 bento-tech/manifest.json 作为深色底板
# 修改 colors / effects / type_scale

完整字段说明和颜色设计要点见 [reference/extension-guide.md](reference/extension-guide.md)。

中文版式硬约束

• 中文与英文/数字之间不加空格（写 1米93 不是 1 米 93）
• 用中文标点（，。""：！？），不用英文标点
• 这两条是 AI 生成的常见痕迹，会被一眼识破，所以 lint 阻断而不是警告

已知限制

• 演讲者备注、动画 / 过渡：未实现
• 数据图表（chart-bar）只是占位，复杂图表请在 layout.json 里描述清楚后人工补
• Linux 端 PowerPoint 打开 SVG 中文字体可能 fallback 到方块字，建议在 macOS/Windows 端打开
• 一次性页数建议 ≤ 30 页（playwright 截图慢）

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: YingYveltal
• Source: YingYveltal/bento-ppt-skill
• License: MIT

Install and usage instructions live in the source repository linked above.