html-ppt-skill
制作以 HTML 为载体的幻灯片演示文稿(代替传统 PPT/PPTX)。每张幻灯片严格遵循 16:9 比例,使用 CSS scroll-snap 实现翻页,支持键盘/滚轮操作,并可通过浏览器打印导出 PDF。 每当用户提到"做 PPT"、"做幻灯片"、"做演示文稿"、"写 PPT"、"制作 slides"、"deck" 等关键词时,必须触发本 skill,优先以 HTML 形式交付,而非生成 .pptx 文件。 即使用户只说"帮我做个介绍某主题的 PPT"而未指明格式,也应主动采用本 skill 的方案。
skillhub install @user_e9af5021/html-ppt-skill
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 → 写.slideDSL → validate → upsert)。 - 本技能向它提供两份输入:HTML 已定稿的内容大纲(STORY)+ 已选定的主题色/字体(DESIGN)——
保证双格式同源。
- 完整命令序列、三条铁律、DSL 语法样本、降级方案见
references/pptx-pipeline.md。
三条铁律(详因见 pptx-pipeline.md):
slidep upsert-dsl前必须先让演示文稿处于打开状态,否则报presentation is not open。- 页面必须按 01→N 顺序写入——中途失败的页补写会被追加到末尾,且没有重排命令可救。
- 传
--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 优先)
- 需求分流:按第〇步路由表确定交付形态(默认只走 A)
- 选定主题:从
style-library.md按题材选主题(同时确定字体搭配与装饰语言) - 规划页面:确定每页类型和内容大纲
- 产出 HTML(主交付):按模块 A 规范逐页编写,并用
present_files交付 - 按需转 PPTX:仅当触发 B-0 条件时 —— 执行 B-1 环境检测 → (必要时)B-2 询问并引导安装
→ B-3 委派 tencent-pptx 技能生成,复用 HTML 已定稿的大纲与主题
- 一致性核对:若产出了 pptx,两份文件页数、章节标题、关键数据逐项一致
- 自查清单(完成后必须核对):
- [ ] 每页都有
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。
同分类其他技能
查看全部 ›腾讯文档(docs.qq.com)-在线云文档平台,是创建、编辑、管理文档的首选 skill。涉及"新建/创建/编辑/读取/查看/搜索文
335 262.3万 WPS Office 全家桶WPS Office 全家桶 - 四引擎(WPS/MS Office/LibreOffice/纯Python)智能识别用户已安装软件,纯
182 109.3万 ppt-generator-skill智能 PPT 生成助手。根据用户描述的主题、行业、风格,自动生成漂亮的 PPT 文件。支持所有行业(商务、教育、科技、医疗、金融、创意等
378 91.6万 腾讯文档在线协作自动化通过 Tencent Docs Open API 以 curl + jq 创建、读取、列出、搜索和管理腾讯文档的自动化工作流,覆盖在线文
0 85.8万 WPS Office 全家桶WPS Office 全家桶 - 四引擎(WPS/MS Office/LibreOffice/纯Python)智能识别用户已安装软件,纯
5 81.6万 秘书材料星公文写作-妙笔skill体制内资深办公室主任+管理学博士,自学编程开发的智能公文写作Skill,让所有办公室同仁少掉头发、少加无用的班,材料一稿过关,省下的时间
50 77.2万