Agent Skill

html-ppt-skill

制作以 HTML 为载体的幻灯片演示文稿(代替传统 PPT/PPTX)。每张幻灯片严格遵循 16:9 比例,使用 CSS scroll-snap 实现翻页,支持键盘/滚轮操作,并可通过浏览器打印导出 PDF。 每当用户提到"做 PPT"、"做幻灯片"、"做演示文稿"、"写 PPT"、"制作 slides"、"deck" 等关键词时,必须触发本 skill,优先以 HTML 形式交付,而非生成 .pptx 文件。 即使用户只说"帮我做个介绍某主题的 PPT"而未指明格式,也应主动采用本 skill 的方案。

办公效率·BOBOY·来自 skill_hub·skillhub.cn ↗
skillhub install @user_e9af5021/html-ppt-skill
27 Stars·10.1万 综合热度·9,723 字文档·源站更新 2026-11-22

README 文档

9,723 字

HTML PPT Skill v2.3

用 HTML + CSS 制作媲美专业设计软件的幻灯片。 HTML 是主交付物;只有用户明确要可编辑的源文件时,才启动 PPTX 转换分支。


第〇步:需求分流(每次必须先做)

收到演示文稿需求时,先判断交付形态:

| 用户想要 | 触发说法举例 | 走哪个模块 | 交付物 | |:--|:--|:--|:--| | 演示 / 汇报(默认) | "做份 PPT"、"做个演示"、"把这个文档转成 PPT" | 只走 A | .html | | 明确要可编辑文件 | "转成可编辑的"、"要 pptx"、"发给客户改" | A 定稿 → 转 B | .html + .pptx | | 要设计稿 / 画布 | "出视觉稿"、"设计稿"、"mockup" | C 转交 | Ardot .ardot 画布 |

判据口诀:默认只给 HTML;要可编辑的源文件才转 B;要设计稿走 C。

详细判据与环境检测见 references/scenario-routing.md。

HTML 优先原则(v2.3 核心变化)

  • 主交付物永远是 HTML。浏览器打开即演示、滚轮/键盘翻页、Ctrl+P 导 PDF、发链接即开——绝大多数场景够用。
  • PPTX 是"按需转换"而非"默认附送"。未经用户要求就产出 pptx,等于多一份需要维护一致性的副产物;

v2.3 起只在用户明确表达"要可编辑 / 要 pptx / 要在 Office 里改"时才启动。

  • HTML 定稿后再转 B:PPTX 分支复用 HTML 已确定的内容大纲与视觉主题,不重新规划内容。
  • 用户明确说"只要 pptx"时,仍先产出 HTML 作视觉基准,再转换(HTML 是两份文件的唯一真源)。

模块 A:HTML 演示(核心规范)

1. 比例与分页(视口安全版,v2 修复)

/* 每张幻灯片严格 16:9,且永不超出浏览器可视区 */
.slide {
  width:  min(100vw, 177.78vh);   /* 177.78vh = 100vh × 16/9 */
  height: min(56.25vw, 100vh);
  margin: 0 auto;                 /* 矮视口时水平居中 */
  overflow: hidden;
  scroll-snap-align: start;
  scroll-snap-stop: always;
}

/* body 开启强制对齐 */
body {
  scroll-snap-type: y mandatory;
  overflow-y: scroll;
  height: 100%;
}
html { height: 100%; }

原理:56.25vw = 9/16 × 100vw 保证比例;min(…, 100vh) 保证高度不超过可视区。 旧写法 height: 56.25vw 在 1080p 屏上会被浏览器标签栏/地址栏吃掉底部约 120px, 且 scroll-snap mandatory 会让被截部分难以回看——禁止回退到旧写法。

2. 打印 / 导出 PDF

@media print {
  html, body { height: auto; overflow: visible; scroll-snap-type: none; }
  #nav-dots, #nav-arrows { display: none !important; }
  .slide {
    width: 297mm;
    height: 167.0625mm;   /* 297 × 9/16 = 167.0625 */
    page-break-after: always;
    break-after: page;
    scroll-snap-align: none;
  }
}

用户按 Ctrl+P → 另存为 PDF 即可导出,每页精确对应一张幻灯片。 提醒用户取消勾选「页眉和页脚」。

3. 导航 JS(标准实现,每次必须包含,v2 修复版)

const slides = Array.from(document.querySelectorAll('.slide'));
const dotsEl = document.getElementById('nav-dots');
let current = 0;

function updateDots(i) {
  dotsEl.querySelectorAll('.dot').forEach((d, idx) => d.classList.toggle('active', idx === i));
}

function goTo(i) {
  i = Math.max(0, Math.min(slides.length - 1, i));
  slides[i].scrollIntoView({ behavior: 'smooth' });
  current = i;
  updateDots(i);
}

// 圆点导航(自动生成)
slides.forEach((_, i) => {
  const b = document.createElement('button');
  b.className = 'dot' + (i === 0 ? ' active' : '');
  b.title = `第 ${i + 1} 页`;
  b.addEventListener('click', () => goTo(i));
  dotsEl.appendChild(b);
});

// 键盘:方向键 / PgUp·PgDn / 空格 / Home·End
document.addEventListener('keydown', e => {
  if (['ArrowDown','ArrowRight','PageDown',' '].includes(e.key)) { e.preventDefault(); goTo(current + 1); }
  if (['ArrowUp','ArrowLeft','PageUp'].includes(e.key))          { e.preventDefault(); goTo(current - 1); }
  if (e.key === 'Home') { e.preventDefault(); goTo(0); }
  if (e.key === 'End')  { e.preventDefault(); goTo(slides.length - 1); }
});

// 按钮翻页
document.getElementById('btn-up').addEventListener('click', () => goTo(current - 1));
document.getElementById('btn-dn').addEventListener('click', () => goTo(current + 1));

// 滚动时同步高亮当前页(单一 observer,勿写多个)
const io = new IntersectionObserver(entries => {
  entries.forEach(en => {
    if (en.isIntersecting) {
      current = slides.indexOf(en.target);
      updateDots(current);
    }
  });
}, { threshold: 0.6 });
slides.forEach(s => io.observe(s));

v2 修复说明:旧版曾出现两个 IntersectionObserver(一个废对象 + 一个 IIFE 兜底)、 updateDots() 被调用却未定义、缺少空格与 Home/End 键位。以上为修复后的完整实现, 不要省略任何键位绑定。

4. 标准文件结构

<head>
  Google Fonts 引入(按所选主题的字体搭配加载)
  <style>
    1. CSS 变量(从 style-library.md 选定主题后整套替换)
    2. 核心框架(slide 比例、scroll-snap、body)
    3. 导航组件样式(dots、arrows)
    4. 通用设计组件(见 design-system.md)
    5. @media print
  </style>
</head>
<body>
  <nav id="nav-dots"></nav>
  <div id="nav-arrows"><button id="btn-up">↑</button><button id="btn-dn">↓</button></div>

  <section class="slide" id="slide-1"> … </section>
  <section class="slide" id="slide-2"> … </section>

  <script> 导航逻辑 </script>
</body>

模块 B 触发流程:可编辑 PPTX(按需 · 委派 tencent-pptx)

v2.3 定位变化:本技能不自己实现 PPTX 生成。PPTX 分支的唯一正确做法,是委派产品内置的 tencent-pptx 技能(slidep DSL 管线,支持圆角/阴影/渐变/富文本/绝对定位,视觉保真度远高于 手写 python-pptx 脚本)。本技能只负责"要不要转、能不能转、转之前先装好"。

B-0 触发条件(缺一不启动)

用户原话含以下任一信号,才进入 PPTX 分支: 可编辑 / 编辑的 / pptx / PowerPoint 文件 / WPS 里改 / 发给客户(领导)改 / 走公司模板。

只说"做份 PPT"不算——那是演示需求,走 A。

B-1 环境检测(进入分支后第一步,自动执行)

# ① 是否处于 WorkBuddy 环境
ls -d ~/.workbuddy 2>/dev/null && echo "WORKBUDDY_ENV=YES"

# ② tencent-pptx 内置技能是否可用
ls -d ~/.workbuddy/plugins/cache/workbuddy-builtin/tencent-pptx/*/ 2>/dev/null

# ③ slidep 工具链是否就绪(tencent-pptx 的底层 CLI)
slidep --version 2>&1 | head -3

| 检测结果 | 动作 | |:--|:--| | ①② 均在 + ③ 可用 | 自动调用 tencent-pptx 技能,直接进入 B-3 | | ① 在、②或③ 缺失 | 视为 WorkBuddy 内置能力未就绪 → 走 B-2 安装引导 | | ① 不在(非 WorkBuddy) | 必须征询用户,走 B-2 安装引导 |

B-2 安装引导(未就绪 / 非 WorkBuddy 时,先问再装)

不要默默降级,也不要默默跳过——先向用户说明并征询,话术:

生成可编辑 PPT 需要 tencent-pptx 技能(WorkBuddy 内置的 PPT 编写能力,走 slidep DSL 管线, 圆角/渐变/阴影能真正还原 HTML 效果)。当前环境未检测到它。 ① 若你已在 WorkBuddy 中:我将重新检测/等待其就绪后继续; ② 若不在 WorkBuddy:tencent-pptx 随 WorkBuddy 内置分发,也可尝试从 SkillHub 安装同名技能。 是否现在安装并继续生成可编辑 PPT?(也可选:仅交付 HTML / 用基础版 python-pptx 兜底)

用户同意后按顺序执行,每一步都要验证再进下一步:

# 方式 A · SkillHub 安装(推荐,需本机已配置 skillhub CLI)
python ~/.skillhub/skills_store_cli.py search tencent-pptx
python ~/.skillhub/skills_store_cli.py install tencent-pptx

# 方式 B · WorkBuddy 内置插件(客户端内启用后自动落盘到 plugins/cache/workbuddy-builtin/)

# 安装后必做:重新验证,通过才继续
slidep --version
  • 验证通过 → 回到 B-3 继续生成。
  • 验证仍失败 → 如实告知,提供两个选项:仅交付 HTML(Ctrl+P 导 PDF),或用 python-pptx 生成基础版

(无渐变/阴影等高级效果,视觉以 HTML 为准)。由用户选,不替他选。

B-3 委派 tencent-pptx 执行

  • 加载 tencent-pptx 技能,按其自身工作流执行(create → 写 .slide DSL → validate → upsert)。
  • 本技能向它提供两份输入:HTML 已定稿的内容大纲(STORY)+ 已选定的主题色/字体(DESIGN)——

保证双格式同源。

  • 完整命令序列、三条铁律、DSL 语法样本、降级方案见 references/pptx-pipeline.md。

三条铁律(详因见 pptx-pipeline.md):

  1. slidep upsert-dsl 前必须先让演示文稿处于打开状态,否则报 presentation is not open。
  2. 页面必须按 01→N 顺序写入——中途失败的页补写会被追加到末尾,且没有重排命令可救。
  3. 传 --project 参数时用 C:/… 形式的 Windows 路径,不要用 $(pwd) 的 /c/… 形式。

模块 C:Ardot 设计稿(转交场景)

用户要的是设计稿(在画布上逐图层编辑的视觉稿)而非演示文件时,转交 Ardot 画布流程:

  • 环境中若可用 Ardot 画布工具(createdesign / batchedit 等 MCP 工具),加载 ardot-slides 技能执行。
  • 工具不可用时,如实告知,并用本技能模块 A 产出高保真 HTML 作为替代(说明其可改代码但非画布图层)。
  • 判据与话术见 references/scenario-routing.md。

设计规范

字体与字号硬约束(v2.1 新增 · 按行业)

PPT 不是艺术品,是信息载体。字体选错、字号太小,行业内一眼就能识破——这比"风格不高级"更致命。

场景 × 字体规则(PPT 与 HTML 路径分离)

| 场景 | PPTX font.name(PowerPoint/WPS 落地) | HTML font-family(浏览器渲染) | 最小字号 | |:--|:--|:--|:--| | 商业 / 咨询 / 互联网 / 科技 | Microsoft YaHei(标题加 SimHei 黑体强调) | 'Noto Sans SC', 'Microsoft YaHei', sans-serif | 12pt / 0.85vw | | 政府 / 事业单位 / 公文 | SimSun(标题加 SimHei 黑体强调) | 'Noto Serif SC', 'SimSun', 'Microsoft YaHei', serif | 12pt / 0.85vw | | 学术 / 教育 / 研究 | SimSun(正文)+ Microsoft YaHei(标题) | 'Noto Serif SC', 'SimSun', 'Microsoft YaHei', serif | 12pt / 0.85vw | | 品牌 / 文化 / 高端提案 | Microsoft YaHei(标题)+ SimSun(正文) | 'Noto Serif SC', 'Noto Sans SC', serif | 12pt / 0.85vw |

实现要点:HTML 字体链要写"在线优先 + 系统兜底"——这样 PowerPoint 中能用微软雅黑、浏览器中能用 Noto Sans SC,两端都不掉链子。

字号层级规范(统一比例,禁止混乱)

| 层级 | PPTX (pt) | HTML (vw) | 用途 | |:--|:--|:--|:--| | H0 封面大标题 | 44 ~+ | 4 ~+ | 封面主标题 | | H1 页面主标题 | 24 ~28 | 2 ~2.5 | 页面顶部大标题 | | H2 卡片 / 区块标题 | 16 ~18 | 1.4 ~1.5 | 卡片标题、模块名 | | H3 小标题 / KPI 数字 | 14 ~16 | 1.1 ~1.4 | 段落小标题、大数字 | | 正文 | 12 ~14 | 0.85 ~1 | 描述、列表、说明 | | 标签 / 辅助文字 | 9 ~11 | 0.7 ~0.85 | page-tag、KPI 标签 |

⚠️ 正文不得低于 12pt / 0.85vw——会议室投影仪分辨率低,字太小后排看不见。 ⚠️ 同一份 PPT 内,H1/H2/H3 字号必须统一——不同页的"页面主标题"都用 28pt,不能一会儿 28、一会儿 24。

行业 × 方案类型 → 字体 + 主题速查表(直接照搬)

| 行业 / 场景 | 方案类型 | 字体规则 | 推荐主题 | |:--|:--|:--|:--| | 政企 / 政府 / 事业单位 | 工作汇报、政策研究、规划方案 | 宋体 + 黑体 | 冰蓝商务、纯白简约、瑞士网格 | | 商业咨询 / 管理咨询 | 咨询报告、提案、调研汇报 | 微软雅黑 + 黑体 | 冰蓝商务、瑞士网格 | | 互联网 / 科技 / AI | 产品发布、白皮书、融资材料 | 微软雅黑 | 深空暗黑、渐变流体 | | 金融 / 投资 / 保险 | 路演、招股书、年报、尽调 | 微软雅黑 + 黑体 | 冰蓝商务、勃艮第酒红 | | 学术 / 教育 / 科研 | 论文答辩、教材、学术汇报 | 宋体(正文)+ 微软雅黑(标题) | 极简黑白、纯白简约、暖米纸感 | | 医疗 / 大健康 / 生命科学 | 产品介绍、学术汇报 | 宋体 + 微软雅黑 | 薄荷清新、森林墨绿 | | 能源 / 制造 / 工业 | 规划方案、技术报告 | 微软雅黑 + 黑体 | 午夜靛蓝、深空暗黑 | | 文化 / 品牌 / 高端 | 年报、品牌手册、提案 | 微软雅黑(标题)+ 宋体(正文) | 中文风骨、复古印刷、极简黑白 | | 消费零售 / 餐饮 | 产品发布、营销方案 | 微软雅黑 | 樱花粉彩、暖米纸感、落日橙紫 |

字体选择原则

  • 中文展示字体:ZCOOL XiaoWei(庄重)、Ma Shan Zheng(书法)、Long Cang(手写)
  • 中文正文字体:Noto Serif SC(衬线)、Noto Sans SC(无衬线)
  • 英文展示字体:Playfair Display、Cormorant Garamond、Space Mono
  • 禁止使用:Arial、Inter、Roboto、system-ui(太通用,无设计感)

主题选择(v2 扩充为 18 套)

从 references/style-library.md 选择。不要默认用深色科技风——先看主题速查表:

| 主题调性 | 适用题材 | |:--|:--| | 暗色系(深空/赛博/靛蓝/鎏金/墨绿/勃艮第) | 科技、游戏、发布会、夜间投屏 | | 亮色系(纯白/冰蓝/暖米/樱粉/薄荷/落日) | 学术、政务、咨询、消费品牌、医疗 | | 编辑系(瑞士网格/中文风骨/复古印刷/极简黑白/玻璃/渐变流体) | 品牌手册、年报、文化内容、高端提案 |

选定后整页配色、字体、装饰语言、排版密度一起换(风格 DNA),不是只换颜色。

每张幻灯片的尺寸感知

  • 字体大小使用 vw 单位(如 3.5vw),随屏幕等比缩放
  • 间距使用 % 或 vw 单位,避免固定 px
  • 内容区 padding 建议:4% 6%
  • 单页信息过载时优先拆页,其次缩字号(正文最小 1vw)

页面类型(v2 扩充为 12 种)

页面类型适用场景布局要点
封面页第一页大标题居中或左对齐,背景有视觉冲击力
目录页第二页2×2 或 1×N 卡片网格列举章节
双栏内容页文字+图/列表grid-template-columns: 1fr 1fr
全图页视觉冲击图片铺满,文字叠加半透明遮罩
数据页展示指标大数字 + 进度条 + 说明文字
时间线页历史/流程/路线横向或纵向时间轴
引用页金句/观点超大引号装饰,居中排版
大数字锚点页单一震撼数据一个巨型数字占满版面 60%,v2 新增
对比页方案 A vs B / 前后对照左右镜像两栏,中线分隔,v2 新增
看板网格页(Bento)多模块信息聚合不等宽 grid 网格卡片,v2 新增
层级架构页组织/技术/系统架构纵向分层横条 + 连接线,v2 新增
结尾页致谢/Q&A/CTA简洁有力,附联系方式或行动引导

工作流程(v2.3 · HTML 优先)

  1. 需求分流:按第〇步路由表确定交付形态(默认只走 A)
  2. 选定主题:从 style-library.md 按题材选主题(同时确定字体搭配与装饰语言)
  3. 规划页面:确定每页类型和内容大纲
  4. 产出 HTML(主交付):按模块 A 规范逐页编写,并用 present_files 交付
  5. 按需转 PPTX:仅当触发 B-0 条件时 —— 执行 B-1 环境检测 → (必要时)B-2 询问并引导安装

→ B-3 委派 tencent-pptx 技能生成,复用 HTML 已定稿的大纲与主题

  1. 一致性核对:若产出了 pptx,两份文件页数、章节标题、关键数据逐项一致
  2. 自查清单(完成后必须核对):
  • [ ] 每页都有 class="slide" 和 id="slide-N"
  • [ ] 每页底部有页码 <span class="slide-num">N / Total</span>
  • [ ] .slide 使用 min(100vw, 177.78vh) / min(56.25vw, 100vh)(视口安全)
  • [ ] body 有 scroll-snap-type: y mandatory
  • [ ] 导航 JS 完整(方向键 / PgUp·PgDn / 空格 / Home·End / 圆点 / 箭头)
  • [ ] IntersectionObserver 只有一个
  • [ ] 所有字体大小用 vw 单位(非 px)
  • [ ] 包含 @media print 样式
  • [ ] 主题不是无脑深色——题材匹配亮色/编辑系时已换用对应家族
  • [ ] 未收到"可编辑/pptx"请求时,不产出 pptx(HTML 优先,v2.3)
  • [ ] 若产出了 pptx:.pptx 与 .html 页数一致、章节一致、关键数据一致
  • [ ] 若产出了 pptx:走的是 tencent-pptx 委派路径(B-1 检测/B-2 征询已执行),而非自行手写 python-pptx 脚本—— v2.3
  • [ ] 文件输出到当前项目工作区,并调用 present_files 交付(不要输出到 /mnt/user-data/outputs/ 等沙箱路径)
  • [ ] 正文 ≥ 12pt / 0.85vw(投影后排可读底线)—— v2.1
  • [ ] 字体匹配行业:商业/科技用 Microsoft YaHei,政府/公文用 SimSun + SimHei(按场景表)—— v2.1
  • [ ] 主题匹配场景:参考「行业 × 方案类型 → 字体 + 主题」速查表选定主题—— v2.1
  • [ ] H1/H2/H3 层级统一:同一份 PPT 内页面主标题统一字号(如都是 28pt),不混用 24/26/28—— v2.1

快速参考:CSS 变量模板

:root {
  /* 从 references/style-library.md 选定主题后整套替换 */
  --c-bg:      #0D0F14;
  --c-surface: #151820;
  --c-border:  rgba(255,255,255,0.08);
  --c-accent:  #4F8EF7;
  --c-accent2: #A78BFA;
  --c-text:    #F0F2F8;
  --c-muted:   rgba(240,242,248,0.45);

  --f-display: 'ZCOOL XiaoWei', serif;
  --f-body:    'Noto Sans SC', sans-serif;

  /* 固定不变 */
  --slide-w: 100vw;
  --slide-h: 56.25vw;
}

组件库与布局模板见 references/design-system.md; 18 套主题与风格 DNA 见 references/style-library.md。

同分类其他技能

查看全部 ›