从零跑通 PPTCraftSkill:用 HTML 写页面,Agent 一键转成可编辑 PPT

举报
yd_274732647 发表于 2026/10/29 09:33:41 2026/10/29
【摘要】 PPTCraftSkill 是一套可复用的 PPT 生成能力包:用 HTML/CSS 描述幻灯片,再由转换器渲染成可编辑的 .pptx(原始形状而非截图),支持 ECharts 图表、FontAwesome 图标与中文字体嵌入。本文是从零上手教程:装转换引擎、写第一页 HTML、转换与验收、把技能装进 Agent,并附设计规范、4 套内置风格、10 种版式与 5 个实测坑。

从零跑通 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 步:验收(三件事必查)

  1. 可编辑性:用 PowerPoint/WPS 打开,点一下文本、点一下形状——应该能选中并编辑。如果全是"一整张图",说明渲染路径不对。
  2. 中文字体是否生效:字体丰富是有代价的——中文字体嵌入会让 PPTX 从几 MB 涨到几十 MB。如果体积不可接受:
   node scripts/cli.js convert ./my-deck ./out.pptx --no-auto-embed-fonts

代价是换机器打开可能字体回退。

  1. 字号没被缩:把 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 步:五个实测坑

  1. "只换颜色 ≠ 设计提升":只改配色,观感提升近乎为零。必须同时改版式、字体、图表、排列。
  2. Bing 图片搜索不可靠:主题经常对不上(搜「玄武湖」返回的是寺墙 + 樱花),且多带图源水印。正式商用请换无版权图源(Wikimedia Commons 等)或让用户提供。
  3. 中文字体嵌入让 PPTX 变大:几 MB → 几十 MB 是正常代价,用 --no-auto-embed-fonts 可关。
  4. 转换器需要本机无头 Chromium:在受限沙箱里,Chromium 启动可能被"命名管道"限制拦截(spawn EPERM),需要完整权限。
  5. 不要改 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;文中字号/对比度/密度等规则均为项目内写明的硬性约束。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。