JunfengRan/PPTWork / ppt-html-authoring
ppt-html-authoring
VerifiedAuthor a single PPT slide as a self-contained slide.html + design.md, given one outline entry. Use when the user asks to design, draft, or rewrite an individual slide page (KPI page, agenda, cover, two-column comparison, chart slide, etc.). Single-page only; does not plan across pages, does not screenshot, does not export. Works alongside the `ppt` skill or standalone.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.6 KB |
| references/design-md-spec.md | markdown | 7.7 KB |
| references/diagram-and-chart.md | markdown | 8.2 KB |
| references/editable-html-rules.md | markdown | 2.0 KB |
| references/ppt-best-practices.md | markdown | 6.6 KB |
| references/slide-html-rules.md | markdown | 10.2 KB |
references/design-md-spec.md
View on GitHub# design.md 写法
每个 slide 目录下的 `design.md` 是**前端要展示**的设计稿,不是注释,更不是临时草稿。空 design.md 会让前端看到空状态。
`initialize_slide` 创建 slide 时会写入空骨架(`Content` / `Note` / `Design` 三段),三段都要填。
## 三段语义(重要,别混)
| 段 | 给谁看 | 内容 | 是否进 PPTX |
|----|--------|------|-------------|
| `## Content` | 前端 design.md 预览 + 你写 slide.html 时的依据 | 这一页**真正讲什么**的人话版本 | 否(slide.html 才是真正进 PPTX 的) |
| `## Note` | **演讲者**(PPTX 备注栏) | 演讲者讲稿,自然语言 | **是**(需要由 agent 同步进 slide.html,见下) |
| `## Design` | agent 自己 + 后续改稿者 | 视觉决策 + 工程笔记(承接 / 数据来源 / 选型理由 / TBD) | 否 |
## frontmatter
```yaml
---
title: "页面标题" # 必填,前端缩略图列表会用
layout: "two-column" # 必填,简短英文标识,对应你在 slide.html 里实际用的版式
---
```
`layout` 例:`cover` / `agenda` / `two-column` / `image-text-split` / `micro-grid` / `flow-timeline` / `architecture-layers`。
## ## Content:页面正文
写"这页**真正讲什么**"的人话版本。可以比 slide.html 里的最终标题/正文更口语化、更完整 —— 前端会原样展示给用户看。
不要写「这是一个介绍页」「正文内容」这种废话占位。
### 两条强制写法(防"水页"的最大杠杆)
**1. 标题必须是结论性完整句(Action + Result),不是名词词组**
| ❌ 名词式 | ✅ 结论式 |
|----------|-----------|
| "AI Agent 市场" | "AI Agent 市场规模 3 年突破千亿美元" |
| "数字化转型" | "数字化转型让运营效率提升 40%" |
| "边缘计算" | "把推理下沉到边缘,端到端延迟压到 15ms" |
读者扫一眼标题就能拿到结论;正文只是支撑它。frontmatter 的 `title` 和 Content 段第一条 `###` 都按这个法则写。
**2. Content 段第一行用 `>` 引用块声明本页逻辑骨架**
强迫自己想清"为什么这一页这么排",也方便后续改稿者一眼看懂。常见骨架:
| 骨架 | 何时用 |
|------|--------|
| **总分** | 一句结论 + 几条支撑 |
| **并列递进** | 几个看似平行的点,实则有时间/优先级递进 |
| **对比** | A vs B、旧 vs 新、痛点 vs 方案 |
| **论据支撑** | 一个核心论点 + 数据/案例支撑 |
| **流程/时间线** | 阶段 1→2→3,强调顺序 |
| **总分总** | 起结论 → 展开论据 → 收束行动 |
例:
```markdown
## Content
> 本页采用**对比**结构:左栏列旧架构三个痛点,右栏给新架构两个核心数字,
> 让"必须改"这件事自己说话。
### 旧架构跑不动了
- ...
```
## ## Note:演讲者讲稿(重要)
`Note` 段是**演讲者讲稿**,最终会出现在 PPTX 的"备注"栏。
### 怎么落地到 PPTX
design.md 本身**不会**直接进 PPTX。`export.mjs`(editable 模式下的 `html2pptx-pro`)只读 `slide.html` 里的特定节点:
- 优先:`<script type="application/json" id="ppt-speaker-notes-json">{ "text": "..." }</script>`
- 兜底:`<div id="ppt-speaker-notes" hidden>...</div>` 或 `[data-ppt-speaker-notes]`
所以你写完 design.md 的 `Note` 段后,**还要把同样内容写进 slide.html 的 speaker notes 节点**,导出才能进备注栏。推荐用 JSON 形式(保留段落与符号最稳):
```html
<script type="application/json" id="ppt-speaker-notes-json">
{ "text": "开场先点题:3 年设备数涨 8 倍,老架构已经踩红线。\n承接到下一页的'三层新架构'..." }
</script>
```
或文本形式(更易手写):
```html
<div id="ppt-speaker-notes" hidden>
开场先点题:3 年设备数涨 8 倍,老架构已经踩红线。
承接到下一页的"三层新架构"...
</div>
```
### 写讲稿的几条经验
- 用自然口语,**不要**写成 bullet list 或文档语气
- 包含**承接句**(怎么从上一页过渡过来、引出下一页)和**口播节奏提示**("这里停一下让数据说话")
- 长度跟讲解时长匹配:每页 30~60 秒讲稿大约 100~250 字
- 数字关键点该重复就重复(slide 上写"15ms",讲稿里也要明说"端到端十五毫秒")
## ## Design:视觉决策 + 工程笔记
这段是**给你(agent)和后续改稿者看**的工程笔记位,**不会**进 PPTX。
因为没有 deck-outline.md 这种中间文件,所有跨页 / 跨阶段的"项目级信息"都靠这一段承载。建议至少含:
```markdown
## Design
### 视觉决策
- layout: 选用的布局(two-column-insight / image-text-split / micro-grid 等)
- emphasis: 视觉重心放哪个元素
- color: 强调色 #C7000B,底色 #FFFFFF
- font: inherit 或具体偏好
- 图表/示意图槽位的具体说明
### 故事承接
上一页讲完"业务现状",本页落到"为什么必须改架构",下一页给"三层新架构"。
### 数据来源
- 8 倍设备数:用户材料《2024 物联中台述职.pptx》第 12 页,2024-09 采集
- 40% 带宽下降:IDC, "Edge Computing TAM 2024 Q2", 2024-10-18 检索
https://example.com/idc-edge-2024-q2
### 可视化选型理由
双栏对比版式,左栏列旧架构痛点(文字),右栏给"延迟+成本"两个核心数字大字突出,
不上柱图(数字太少,柱图反而弱)。
### TBD
- 等用户确认 40% 这个数字是否可以引用 IDC 公开数据
```
涉及时效性数据的页,**数据来源 + 采集日期必须有**,不然下一轮改稿没人记得这个数字哪儿来的。
## 完整示例
```markdown
---
title: "为什么 2024 年要重做边缘计算"
layout: "two-column-insight"
---
## Content
### 旧架构跑不动了
- 端侧设备数 3 年涨 8 倍,回传带宽成本翻倍
- 中心云延迟稳定在 80~120ms,工业控制场景已经踩红线
- 核心业务单点故障半径 = 整个区域
### 边缘是必选项
把 30% 推理与状态下沉到边缘,端到端延迟可压到 15ms 以内,
带宽成本下降 ~40%(IDC 2024 Q2 调研)。
## Note
各位,刚才那张图我们看到了端侧设备数 3 年涨了 8 倍 —— 这个量级直接把回传成本拉到了不可接受的水平。
更要命的是延迟,中心云稳定在 80~120 毫秒,听起来还行,但工业控制场景下这就已经是红线。
所以下一步动作非常明确:把 30% 的推理和状态管理下沉到边缘节点。
请大家看右侧两个数字:端到端 15 毫秒,带宽成本下降 40%。15 毫秒意味着我们能进入实时控制场景,
40% 不是省钱,是把今年规划里"没钱做"的那部分变成"可以做"。
下一页我会给出我们打算怎么做这件事 —— 三层新架构。
## Design
### 视觉决策
- layout: two-column-insight
- emphasis: 右栏的 15ms / -40% 两个数字(96pt 强调字号)
- color: 强调色 #C7000B,背景 #FFFFFF,分隔线 #E5E7EB
- font: inherit
### 故事承接
上一页给了"业务现状(设备爆发 + 成本上涨)",本页落到"为什么必须改架构",
下一页讲"三层新架构怎么做"。
### 数据来源
- 8 倍设备数:用户材料《2024 物联中台述职.pptx》第 12 页,2024-09 采集
- 80~120ms:用户材料 / 内部 SLO 看板
- 40% 带宽下降:IDC, "Edge Computing TAM 2024 Q2", 2024-10-18 检索
https://example.com/idc-edge-2024-q2
### 可视化选型理由
双栏对比版式,左栏列旧架构痛点(文字),右栏给两个核心数字大字突出。
不上柱图:数字只有两个,柱图反而弱。
### TBD
等用户确认 40% 这个数字是否可以引用 IDC 公开数据。
```
slide.html 的 `#ppt-speaker-notes-json` 里再放同样的 Note 内容,导出后会自动进 PPTX 演讲者备注栏。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |