> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.
# 演示文稿
> profy-pptx — 两条互斥管线：原生 .pptx（SVG → DrawingML）与 HTML Deck（单文件网页 PPT）
# 演示文稿（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`——**自动可用，不需要勾选**。
```json theme={null}
{ "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 ` | 读取内容 |
| `unpack ` | 拆包 |
| `pack --original ` | 重新打包（需带原文件） |
| `add-slide ` | 加一页 |
| `thumbnail ` | 生成缩略图 |
`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` 工作流在新会话继续 |
## 验证你的产出
1. **打开 PPTX 后点一下正文文字**——能选中、能编辑才说明走的是 DrawingML 管线。选不中就是被光栅化了。
2. 中文页面确认没有方块字。
3. HTML Deck 用键盘 ← → 翻一遍，确认动效与索引（ESC）正常。
## 相关页面
四类文档能力的定位与选型
需要 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（作者 歸藏）。