从零跑通 PPTCraftSkill:用 HTML 写页面,Agent 一键转成可编辑 PPT
从零跑通 PPTCraftSkill:用 HTML 写页面,Agent 一键转成可编辑 PPT
项目地址:https://gitcode.com/agent-best-practices/PPTCraftSkill 本文是一篇上手教程:从装转换引擎、写第一个页面,到生成一份版式丰富的 .pptx,并把整套能力装进 Agent。 核心思路一句话:用 HTML/CSS 描述幻灯片,转换器把它渲染成"原始形状 + 文本"的可编辑 PPTX,而不是截图。
读完这篇你能做到什么
按本文走一遍,你会完成:
装转换引擎 → 写一页 1280×720 的 HTML → 转成可编辑 .pptx → 验收
→ 把技能装进 Agent → 按设计规范批量出页 → 避开 5 个实测坑
和多数"PPT 生成"方案最大的区别是:产出的是真·可编辑的 PPT(每个文本框、形状、图表都能在 PowerPoint 里改),不是把网页截成图片塞进去。
前置条件清单
| 项 | 要求 | 说明 |
|---|---|---|
| Node.js | 能跑 npm install |
转换器是 Node 项目 |
| Chromium | 无头浏览器 | 转换器靠 Playwright 渲染 HTML |
| Agent(可选) | 支持 skill 目录 | 用来做"研究→大纲→逐页写 HTML" |
只想拿设计规范和素材、不做转换也可以——仓库里的
converter/designer/与materials/本身就很有价值。
第 1 步:认识仓库结构
PPTCraftSkill/
├── skill/ DSH/Agent skill 定义(pptx-craft SKILL.md)
├── converter/ HTML→PPTX 转换引擎(核心)
│ ├── scripts/ 转换器 CLI + bundle
│ ├── designer/ 全局设计规范(SKILL.md 97KB + charts.md)
│ ├── styles/ 4 套内置风格模板
│ ├── html-to-pptx/ 可读转换源码 + CSS 白名单
│ ├── assets/ 字体 / 图标 / ECharts / Tailwind / fonteditor
│ └── image-insert | outline-planner | research-writer 子技能
├── materials/ 从外部模板提取的可复用素材(238 张图片 + 色板/字体/版式清单)
├── photos/ 实景图示例素材
├── samples/ 生成出的成品示例
├── web-search/ AgentWebSearch(联网搜索 skill,Python 标准库)
└── knowledge/ 设计经验、配色、字体、版式心得
三个入口各管一件事:converter 干活(转 PPTX)、skill 指挥 Agent(怎么生成)、knowledge + designer 定标准(什么才算好看)。
第 2 步:装转换引擎
cd converter
npm install
依赖清单(来自 converter/package.json,可以直接核对):
| 包 | 版本 | 作用 |
|---|---|---|
playwright |
1.57.0 | 无头 Chromium 渲染 HTML |
jszip |
^3.10.1 | 打包成 .pptx(本质是 zip) |
commander |
^13.0.0 | CLI 参数解析 |
express + get-port |
本地服务/端口探测 |
装完记得确认浏览器本体在位:
npx playwright install chromium
.pptx本质是一个 zip 包(所以用 jszip 组装)。理解这点你就明白为什么"转换"能做到可编辑——它是在把 HTML 的 DOM 结构翻译成 OOXML 里的形状和文本框。
第 3 步:写第一个页面
转换器接受一个目录,里面放 page-1.pptx.html … page-N.pptx.html,每个文件是一页完整的 HTML。
最小可用骨架:
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<!-- 必须包含 designer/SKILL.md 里「防溢出硬性约束 → 全局 CSS 约束」整段 -->
<style>
.ppt-slide { width:1280px; height:720px; }
.content-safe { width:1220px; height:660px; margin:30px auto; }
</style>
</head>
<body>
<div class="ppt-slide flex flex-col" type="title">
<div class="content-safe">
<h1>在这里写页面主标题</h1>
<p>正文示例:一行 40 字以内,每卡不超过 2 行。</p>
</div>
</div>
</body>
</html>
尺寸约定是硬性的,别改:
- 根容器
<div class="ppt-slide flex flex-col" type="...">,固定 1280×720 - 核心内容放
.content-safe(1220×660,相当于四周 30px 安全边距) - 页面类型用
type="..."标注(封面/目录/内容等),转换器会据此决定处理方式
为什么要安全边距?因为投影/裁切会吃掉边缘。把内容写进 1220×660 里,投到任何屏幕都不会被切。
第 4 步:转换
node scripts/cli.js convert <pages目录> <输出.pptx>
例如:
node scripts/cli.js convert ./my-deck ./输出.pptx
转换器会顺手做一件很关键的事:把 HTML 里引用的 CDN 资源(Tailwind / ECharts / 字体 / 图标)自动映射到本地 assets/,所以转出来的结果是离线可用的。反过来说——不要手动把它们改成本地路径,让转换器自己映射就行。
第 5 步:验收(三件事必查)
- 可编辑性:用 PowerPoint/WPS 打开,点一下文本、点一下形状——应该能选中并编辑。如果全是"一整张图",说明渲染路径不对。
- 中文字体是否生效:字体丰富是有代价的——中文字体嵌入会让 PPTX 从几 MB 涨到几十 MB。如果体积不可接受:
node scripts/cli.js convert ./my-deck ./out.pptx --no-auto-embed-fonts
代价是换机器打开可能字体回退。
- 字号没被缩:把
px × 0.75换算成 pt 对一遍下方附录 A 的表。宁可拆页,也不许缩小字号硬塞——这是这个项目的第一原则。
第 6 步:把技能装进 Agent
skill/ 下的 SKILL.md 是给 Agent 的指令,核心流程是:
研究(research-writer)→ 大纲(outline-planner)→ 逐页写 HTML
→ 调转换器 → 配图(image-insert)→ 交付
把它复制到 Agent 的 skills 目录即被发现:
# 用户级(所有项目可用)
cp -r skill/* .dsh/skills/
# 或项目级
cp -r skill/* <dshHome>/skills/
装好后,你只要说清主题 + 页数 + 风格,Agent 就能跑完整条链路。
第 7 步:设计系统速查(这就是"好看"的来源)
每页 HTML 必须遵循这套规则,它们写在 converter/designer/SKILL.md(97KB)里。
字号(px → pt 的换算:pt = px × 0.75)
| 元素 | HTML | PPT(pt) |
|---|---|---|
| 页面主标题 | 37px | 28 |
| 分项标题 | 21–23px | 16–17 |
| 正文 | 19px | 14 |
| 标签 | 16px | 12 |
| 注释/来源 | 12px | 9 |
硬下限:正文与标签 ≥16px,注释 ≥11px;相邻层级字号比 ≥1.2(层级要拉得开才看得出主次)。
文字对比度(WCAG AA:正文 ≥4.5:1)
- 正文用
#000000或深灰#555757 - 禁止
#B5B5B5及更淡的浅灰做正文/注释(投影仪上一片糊) - 灰色只能用
#898989(中灰),且仅限英文副标题这类辅助信息
行距与密度
- 正文行距 1.5;元素间距 ≥16px
- 每页核心观点 3–6 个;每卡正文 ≤2 行(≤40 字);单页正文 ≤14 行
- 禁止
overflow-hidden裁剪正文、text-overflow:ellipsis、line-clamp、缩小字号硬塞——超预算就拆页
这三条(字号/对比度/密度)是"能看"和"难看的挤"之间的分界线,建议生成后逐条自查。
图表(ECharts)规则
echarts.init(el, null, { renderer: "svg" }) // 必须单行写,且 animation: false
- 用 SVG 渲染器(PPT 里矢量清晰),关掉动画(动画会干扰转换)
- 禁止渐变:
areaStyle/itemStyle/lineStyle用半透明纯色,如rgba(74,108,140,0.18) - 坐标轴标签、图例、数据标签只用
#000000/#555757/ 强调色,禁止浅灰
第 8 步:4 套内置风格 + 推荐配色
| 风格 | 特征 | 适合 |
|---|---|---|
business-classic |
白底 + 品牌红 #D33941,横向直角卡片 |
最通用 |
elegant-narrative |
米色羊皮纸 #f5f4ed + 陶土橙 #c96442 + 宋体标题 + 深炭卡明暗交替 |
最有质感 |
industrial-tech |
纯黑底 + 荧光绿 #76b900,硬朗字体 |
深色硬核 |
tech-minimal |
白/浅灰 + 科技蓝 #0071e3,极简大留白 |
科技产品 |
也可以直接从 materials/ 里抄现成色板:
- 黑金(正式汇报):底
#0F1423,玫红#EC5F74,金#FFBA55,蓝#6096E6,绿#56CA95,青#58B6E5,珊瑚#F18870 - 深蓝重用体(商务励志):主色
#256090+ 阿里巴巴普惠体 - Office 六色(通用安全):深蓝
#1F497D/ 蓝#4F81BD/ 红#C0504D/ 绿#9BBB59/ 紫#8064A2/ 青#4BACC6/ 橙#F79646 - 旅游活力:蓝
#4472C4/ 橙#ED7D31/ 金#FFC000/ 绿#70AD47 - 古典金陵(文化主题):朱砂红
#B03A2E+ 墨绿#2E5C4A+ 金#C9A06B,底为米白#F7F3EA
字体偏好:
- 标题衬线:文津宋体
WenJin Mincho Plane 0(书卷气,古典/文化/高端) - 正文:文源黑体
WenYuan Sans SC/ Noto Sans SC(可读性好) - 力量感:阿里巴巴普惠体 Heavy / 思源宋体 / 微软雅黑 / 等线
第 9 步:版式弹药库——别让每页长得一样
这是整个项目里最"值钱"的一条经验:只在同一种卡片版式上换颜色,用户几乎看不出变化。 真正要动的是版式本身。
| 版式 | 适用 | 手法 |
|---|---|---|
| 封面 hero | 首页 | 大图/大标题 + 副题 + 金句 + 装饰 |
| 目录导航 | 第 2 页 | 编号 01-06 + 英文副标 + 分隔线 |
| KPI 仪表盘 | 数据概览 | 2-3 个大数字 + 定位句 + 要点 |
| 横向时间轴 | 历史/发展 | 中心线 + 圆点 + 年份/事件 |
| 图文不对称 | 详情页 | 一张大图(object-fit:cover)+ 右侧文字要点 |
| 标签云 | 关键词页 | 彩色 Tag 一排 |
| 图标网格 | 清单/分类 | 图标 + 名称 + 一句话,三色顶条 |
| 排名卡 | 榜单 | ①-⑥ 编号 + 名称 + 描述 |
| 流程图 | 路线/步骤 | 节点 + 箭头连接(DAY1/DAY2) |
| 金句结尾 | 收尾 | 大字引言 + 副标 + 装饰 |
改造优先级的正确顺序(来自作者的实测对照):
版式(每页不同)> 字体(衬线/字重)> 图表(时间轴/流程/仪表盘)
> 排列(不对称/装饰/层级)> 配色(最后才碰)
配色排在最后——这条反直觉,但确实如此。
第 10 步:五个实测坑
- "只换颜色 ≠ 设计提升":只改配色,观感提升近乎为零。必须同时改版式、字体、图表、排列。
- Bing 图片搜索不可靠:主题经常对不上(搜「玄武湖」返回的是寺墙 + 樱花),且多带图源水印。正式商用请换无版权图源(Wikimedia Commons 等)或让用户提供。
- 中文字体嵌入让 PPTX 变大:几 MB → 几十 MB 是正常代价,用
--no-auto-embed-fonts可关。 - 转换器需要本机无头 Chromium:在受限沙箱里,Chromium 启动可能被"命名管道"限制拦截(
spawn EPERM),需要完整权限。 - 不要改 HTML 里的 CDN 路径:转换器会自动映射到本地
assets/,手动改成本地反而会破坏映射。
附录 A:可读性铁律自查清单
生成后逐条核对,全部通过才算合格:
- [ ] 正文字号 ≥16px(→12pt),没有为了塞内容缩小字号
- [ ] 文字对比度 ≥4.5:1,没有
#B5B5B5及更淡的浅灰 - [ ] 行距 1.5;每卡正文 ≤2 行;单页正文 ≤14 行
- [ ] 没有用
overflow-hidden/ellipsis/line-clamp截断关键信息 - [ ] 相邻层级字号比 ≥1.2
- [ ] 内容都在
.content-safe(1220×660)内 - [ ] ECharts 用 SVG 渲染器、
animation:false、无渐变 - [ ] 每页版式与其它页不同
附录 B:联网搜索子技能
当 web_search 工具额度不足、或需要直连时,用仓库自带的纯 Python 搜索(标准库实现,无需依赖):
python web_search.py search "关键词" --limit 5
python web_search.py fetch "https://..."
python web_search.py images "关键词" --limit 3 --output ./imgs
第二、三条正是"配图"环节要用的:先搜图,再交给 image-insert 子技能放进页面。
常见问题(FAQ)
Q:生成的是图片还是真 PPT? 真 PPT。转换产出的是原始形状与文本框(可选中、可编辑),不是截图——这也是它需要 Chromium 渲染 DOM 再翻译成 OOXML 的原因。
Q:我能不用 Node.js 吗? 转换这一步不行(依赖 Playwright)。但如果只想要设计规范和素材,designer/、styles/、materials/ 里的内容可以纯手工使用。
Q:能不能批量生成整个 deck? 可以——把 N 页 HTML 放进同一目录,一次 convert 全部转换。建议先在 samples/ 里看成品找手感。
Q:为什么我的图表在 PPT 里没动画了? 这是有意为之:规则要求 animation: false。PPT 里的图表是静态形状,动画会干扰转换结果。
Q:体积太大怎么办? 用 --no-auto-embed-fonts 关闭字体嵌入;或者精简用到的字重数量。
结语
PPTCraftSkill 的思路和"AI 直接生成 PPT 二进制"完全不同:它让 AI 用最擅长的方式(写 HTML/CSS)描述页面,再用一个转换器把 DOM 翻译成可编辑的 OOXML 形状。
真正让它从"能生成"走到"好看"的,是仓库里那一整套被写死的设计约束——字号换算表、对比度下限、密度上限、ECharts 渲染规则、版式弹药库。这些不是审美玄学,而是可以逐条自查、可以交给 Agent 执行的硬指标。
如果你也在做演示文稿自动化,建议先把 converter/designer/SKILL.md 和 knowledge/设计经验.md 读一遍——那两份文档比代码更值钱。
参考资料:项目 README.md、converter/package.json、knowledge/设计经验.md、materials/素材库清单.md;文中字号/对比度/密度等规则均为项目内写明的硬性约束。
- 点赞
- 收藏
- 关注作者
评论(0)