演示文稿（profy-pptx）

演示文稿有两条互斥管线，选定之后不能中途换道，也不能互相转换。先看这张表决定你在哪条路上：

	HTML Deck	原生 PPTX
交付物	单文件 `.html`，浏览器打开	`.pptx`，PowerPoint / Keynote 打开
视觉能力	WebGL 背景、CSS 动效、横向翻页	矢量 DrawingML、可编辑文本与形状
PDF 导出	禁止（见下）	用户在 PowerPoint 里自行导出
适合	演讲分享、发布会、杂志风 / 瑞士风	工作汇报、培训课件、需要 .pptx 文件

选定路径后不要尝试跨路径转换。 不要把 HTML Deck 转成 PDF 或 PPTX，也不要把 PPTX 转成 HTML Deck。HTML Deck 依赖 Tailwind + WebGL，而 WeasyPrint / wkhtmltopdf 渲染不了这两样，转出来是严重退化的结果。需要 PDF 就从一开始走 builtin/kami。

激活方式

profy-pptx 是 user_selectable: false——自动可用，不需要勾选。

{ "id": "profy-pptx", "activation": { "user_selectable": false } }

contracts 只有 skills: ["skills/"]，没有 tools。插件带两个技能：builtin/pptx（原生管线枢纽）与 builtin/html-deck（网页 PPT）。

导出管线锁

绝不要自己写导出/转换脚本。 产出 PPTX 的唯一途径是执行技能自带的 svg_to_pptx.py。自写脚本（cairosvg、python-pptx、pptxgenjs 等）产出的是光栅化的纯图片幻灯片，且中文文本破损——这是已知的 P0 缺陷。这条规则无条件生效，包括在沙箱报错、重试或上下文压缩之后。如果沙箱恢复了，重新跑管线脚本，不要重写它。

这条约束值得理解其成因。SVG 转 PPTX 有两种做法：一是把 SVG 渲染成位图贴进幻灯片，二是把 SVG 图元翻译成 PowerPoint 原生的 DrawingML。前者简单，任何通用库都能做，代价是幻灯片彻底不可编辑、文字不再是文字。svg_to_pptx.py 做的是后者。之所以要写成”无条件”，是因为这类规则最常在故障恢复之后被破坏：报错重试几次以后，重写一个”简单版本”看起来是合理的自救，而它恰好绕过了唯一正确的实现。

意图路由

用户意图	路径	交付物
网页 PPT / 杂志风 / 瑞士风 / swipe deck	HTML Deck	`.html`
做 PPT / 做幻灯片（无已有文件）	Create	`.pptx`
上传 .pptx + 改这个	Edit	`.pptx`
上传 .pptx + 按这个风格做新的	Template Clone	`.pptx`
已生成 + 第 N 页改 XXX	Iterate	`.pptx`

原生 PPTX：七步管线

Step 1: 素材准备
Step 2: 项目初始化
Step 3: 模板选择（可选）
Step 4: 策划阶段（设计规格 + 八项确认）
Step 5: 配图生成（如需）
Step 6: 执行阶段（SVG 生成 + 演讲备注）
Step 7: 后处理与导出

Phase 拆分：1–5 为 Phase A（规划与素材），6–7 为 Phase B（执行与导出）。长 deck 的 Phase B 可以在新会话里跑 resume-execute 工作流，把上下文预算腾出来。

Step 1 素材转换

素材类型	转换脚本
PDF	`source_to_md/pdf_to_md.py`
Word	`source_to_md/doc_to_md.py`
Excel	`source_to_md/excel_to_md.py`
PowerPoint	`source_to_md/ppt_to_md.py`
网页 URL	`source_to_md/web_to_md.py`
纯文本 / 聊天内容	直接用
只有主题、没有文件	先跑 `topic-research` 工作流联网搜集素材

Step 2 画布格式

格式	viewBox	场景
`ppt169`	`0 0 1280 720`	商务演示（默认）
`ppt43`	`0 0 1024 768`	传统投影仪
`xhs`	`0 0 1242 1660`	小红书图文
`wechat`	`0 0 1080 1080`	朋友圈 / IG 方图
`story`	`0 0 1080 1920`	竖版故事 / 短视频

同一套管线能产出社交媒体图片，是因为底层是 SVG——换 viewBox 就换了画布，不需要另一条管线。

Step 3 模板（可选）

模板只在用户给出明确模板目录路径时才应用。光说”学术风格”这类风格词不会触发模板拷贝，它们进入 Step 4 的风格描述符。

家族	提供什么
Layout 模板	品牌标识 + SVG 页面清单（固定页面结构）
Brand 模板	只有品牌标识（配色、字体、logo、语气，无页面 SVG）

两者同时提供时融合为一份 design_spec.md，冲突时的优先级：配色 / 字体 / logo / 图标风格由 Brand 决定，页面结构 / SVG 清单由 Layout 决定。

编辑已有 PPTX

流程是 unpack → 直接改 XML → 自动清理 → pack。edit_pptx.py 提供五个子命令：

命令	用途
`read <file.pptx>`	读取内容
`unpack <file.pptx> <output_dir>`	拆包
`pack <dir> <output.pptx> --original <original.pptx>`	重新打包（需带原文件）
`add-slide <unpacked_dir> <source>`	加一页
`thumbnail <file.pptx>`	生成缩略图

pack 要求传 --original，因为 pptx 包里有大量未被编辑的关系文件与资源，需要从原包继承。

HTML Deck：网页 PPT

单文件 HTML 的横向翻页演示，两种视觉基调：

风格 A · 电子杂志 × 电子墨水（默认）

WebGL 流体 / 等高线 / 色散背景（hero 页可见）
衬线标题（Noto Serif SC + Playfair Display）+ 非衬线正文 + 等宽元数据
适合人文分享、行业观察、商业发布
美学锚点：像 Monocle 杂志贴上了代码

风格 B · 瑞士国际主义

WebGL 极细网格 + 点阵背景
全程无衬线（Inter + Helvetica + Noto Sans SC），极致字号对比
高反差功能色四选一：克莱因蓝 IKB / 柠檬黄 / 柠檬绿 / 安全橙
适合科技产品、数据汇报、年度总结
美学锚点：Massimo Vignelli + Helvetica Forever

两种风格共享：横向翻页（键盘 ← →、滚轮、触屏、ESC 索引）、Lucide 图标、Motion One 入场动效（本地 + CDN 双保险）。

什么时候不要用 HTML Deck

情况	改用
需要 `.pptx` 文件	`builtin/pptx` 原生管线
需要 `.pdf` 文件	`builtin/kami`
大段表格数据、图表叠加	常规 PPT
培训课件	常规 PPT（HTML Deck 信息密度不够）
需要多人协作编辑	常规 PPT（HTML Deck 是静态文件）

环境约束

沙箱镜像已预装全部 Python 依赖，不要跑 pip install / uv pip install 或任何包管理命令。 如果 import 失败，那是沙箱镜像的问题，不是应该在运行时修的东西。

脚本通过 skill(action="execute") 在沙箱内运行，依赖首次使用时自动部署，同一会话内后续调用跳过部署。沙箱目录结构：

/home/user/workspace/pptx/
├── scripts/      # Python 脚本，首次 execute 时自动部署
├── templates/    # 图标与图表模板
└── projects/     # 生成内容的工作目录

边界与失败态

两条管线互斥，不能互转（见页头警告）。
自写导出脚本会产出破损的中文，且看起来”生成成功了”——这是最需要警惕的一类失败：它不报错。
模板需要显式路径，风格词不触发。
长 deck 的 Phase B 建议换会话，否则上下文会被 SVG 源码占满。
HTML Deck 是静态文件，没有协作编辑能力。

排错

症状	原因	处理
PPTX 打开后文字选不中、是图片	用了自写的转换脚本	重跑 `svg_to_pptx.py`
中文变成方块或乱码	同上，光栅化管线的典型症状	同上
import 报错	沙箱镜像缺依赖	报告问题，不要在运行时装包
说了”学术风格”但模板没生效	风格词不触发模板	给出明确的模板目录路径
HTML Deck 导出 PDF 后面目全非	Tailwind + WebGL 无法被 PDF 渲染器处理	需要 PDF 就改走 `builtin/kami`
长 deck 跑到一半上下文耗尽	没有做 Phase 拆分	用 `resume-execute` 工作流在新会话继续

验证你的产出

打开 PPTX 后点一下正文文字——能选中、能编辑才说明走的是 DrawingML 管线。选不中就是被光栅化了。
中文页面确认没有方块字。
HTML Deck 用键盘 ← → 翻一遍，确认动效与索引（ESC）正常。

办公文档总览

四类文档能力的定位与选型

PDF 文档

需要 PDF 交付物时走 kami 排版引擎

核对日期 2026-08-11。来源：services/agent-runtime/src/plugins/builtin/pptx/plugin.json、skills/pptx/SKILL.md、skills/html-deck/SKILL.md、skills/pptx/scripts/。html-deck 来源为 guizang-ppt-skill（作者歸藏）。

开始使用

核心概念

使用指南

平台与账户

深入了解

演示文稿

演示文稿（profy-pptx）

激活方式

导出管线锁

意图路由

原生 PPTX：七步管线

Step 1 素材转换

Step 2 画布格式

Step 3 模板（可选）

编辑已有 PPTX

HTML Deck：网页 PPT

风格 A · 电子杂志 × 电子墨水（默认）

风格 B · 瑞士国际主义

什么时候不要用 HTML Deck

环境约束

边界与失败态

排错

验证你的产出

相关页面

办公文档总览

PDF 文档

​演示文稿（profy-pptx）

​激活方式

​导出管线锁

​意图路由

​原生 PPTX：七步管线

​Step 1 素材转换

​Step 2 画布格式

​Step 3 模板（可选）

​编辑已有 PPTX

​HTML Deck：网页 PPT

​风格 A · 电子杂志 × 电子墨水（默认）

​风格 B · 瑞士国际主义

​什么时候不要用 HTML Deck

​环境约束

​边界与失败态

​排错

​验证你的产出

​相关页面

办公文档总览

PDF 文档

演示文稿（profy-pptx）

激活方式

导出管线锁

意图路由

原生 PPTX：七步管线

Step 1 素材转换

Step 2 画布格式

Step 3 模板（可选）

编辑已有 PPTX

HTML Deck：网页 PPT

风格 A · 电子杂志 × 电子墨水（默认）

风格 B · 瑞士国际主义

什么时候不要用 HTML Deck

环境约束

边界与失败态

排错

验证你的产出

相关页面