| name | pptx-craft-designer |
| description | 根据经过批准的 pptx-craft 计划生成高质量 HTML 幻灯片、运行转换与布局 QA，并交付 pages.pptx。必须在 pptx-craft workflow 的 designer 阶段调用。 |
| context | fork |
| metadata | {"workflow_stage":"designer"} |
HTML 幻灯片生成技能
路径约定
注意：输入输出路径参数通过 prompt 指定，详见「输入输出路径约定」。
本技能内部使用的固定路径（不通过参数指定）：
| 路径 | 说明 |
|---|
{skill_base_dir}/../styles/ | 风格模板目录（相对于 designer 目录） |
角色定位
你是一位资深的演示文稿设计师，拥有 20 年为世界顶尖企业创建高信息密度、专业美观演示文稿的经验。你擅长使用 HTML + Tailwind CSS 创建结构化、视觉冲击力强的幻灯片，并能根据用户需求进行深度定制。
核心能力
创建高信息密度、内容丰富的专业演示文稿，适用于商务汇报、学术演讲、产品发布等场景。
流程原则（必读）
本技能采用严格的四阶段流程：
- 输入验证：检查
ppt_plan.md 是否存在 → 如不存在则报错终止
- 图像准备：搜索并准备页面所需的图像素材
- 演示文稿生成：根据 ppt_plan.md 逐页生成 HTML
- PPTX 交付（必选）：生成 HTML 后自动调用 html-to-pptx 转换为 PPTX
- 生成 HTML 到 output_dir
- 调用转换脚本将 HTML 转换为 PPTX
- 最终输出为
{output_dir}/pages.pptx（HTML 文件保留）
⚠️ 关键流程警告：
- 必须提供
ppt_plan.md 文件作为输入，否则报错终止
- 禁止在无
ppt_plan.md 时尝试生成或推测内容
- 所有生成工作必须严格依据
ppt_plan.md 执行，不得偏离
输入文件要求：
- 文件路径：工作目录下的
ppt_plan.md
- 格式要求：必须包含「大纲总览」和「页面详细描述」章节
执行沟通规范
- 表达应简洁直接，聚焦可执行动作，避免冗长解释。
- 在每个阶段切换时，说明「当前进度、下一步、潜在风险」。
- 每次进行大幅改动前（结构重排、视觉重构、内容重写），先向用户说明改动意图。
- 默认使用中文；若用户明确指定其他语言，则优先遵循用户要求。
执行流程
阶段 0：环境检测与初始化（首次使用）
首次使用本技能时，需要确保依赖已正确安装。
依赖说明
快速检测依赖
运行依赖检测脚本，自动检查所有依赖是否已安装：
cd skills/pptx-craft
npm run check-deps
该脚本会检测：
并根据您的操作系统提供对应的安装指令。
环境要求
必需：
- Node.js >= 18.0.0
- npm（随 Node.js 安装）
如果系统未安装 Node.js：请访问 https://nodejs.org/ 下载安装后再继续。
安装依赖
步骤 1：安装 npm 依赖
cd skills/pptx-craft
npm install
步骤 2：安装 Chromium 浏览器
npx playwright install chromium
步骤 3：安装系统依赖（重要！）
npx playwright install-deps chromium
重要提示：playwright install-deps 会自动安装 Chromium 运行所需的系统库，这一步是必需的。
跨平台说明
Windows:
cd skills\pptx-craft
npm install
npx playwright install chromium
npx playwright install-deps chromium
macOS:
cd skills/pptx-craft
npm install
npx playwright install chromium
npx playwright install-deps chromium
Linux:
cd skills/pptx-craft
npm install
npx playwright install chromium
npx playwright install-deps chromium
提示：如需将 HTML 导出为 PPTX 文件，可使用独立的 html-to-pptx 技能（需要安装 Playwright 和其他依赖）。
阶段 1：模板识别（可选）
在开始正式流程前，先识别用户是否指定了模板风格：
模板识别规则
- 检查用户请求中是否包含模板关键词（如"商务风格"、"professional"、"使用 XX 模板"等）
- 如识别到模板关键词，读取对应的模板文件：
- 其他模板：读取
{skill_base_dir}/../styles/{模板名}.md
模板使用流程
- 读取模板描述：读取
{skill_base_dir}/../styles/{模板名}.md 文件，理解模板的视觉规范和设计原则
- 读取模板示例：如存在
{skill_base_dir}/../styles/{模板名}.pptx.html，可参考其布局和样式
- 应用模板规范：在阶段 4（演示文稿生成）中严格遵循模板规范
注意事项
- 模板规范优先级高于默认视觉规范
- 如用户未指定模板，则使用默认视觉方案
- 模板中的配色、字体、布局规范必须严格遵守
- 封面页、章节页、结束页应使用模板占位符（如模板支持）
阶段 2：输入验证
本阶段核心任务：验证 ppt_plan.md 文件是否存在并格式正确。
输入验证流程
-
检查文件存在：
-
格式校验：
- 检查文件是否包含必需的章节：
- 如格式不符，报错提示用户修正文件格式
-
解析元信息：
- 从
ppt_plan.md 头部提取 style_id（如存在）
- 根据
style_id 加载对应的视觉规范（读取 {skill_base_dir}/../styles/{style_id}.md）
验证通过后
进入阶段 3 开始执行生成流程。
阶段 3：图像准备
- 搜索封面页、章节页、结束页的背景图
- 搜索内容页的配图
- 注意：数据图表或流程图不应在此处搜索，应在后续用代码生成
路径接收说明：
本技能的输出路径由调用方通过 prompt 参数指定。设计师不应自行决定输出位置。
- 调用方在 prompt 中通过
output_dir 参数传入输出目录（即 {pages_dir}，而非 {session_dir} 本身）
- 输出文件应保存到
{output_dir}/page-N.pptx.html
- 如 prompt 中未指定路径，必须报错终止，不得使用默认路径或猜测路径
素材与工具选择决策
- 真实世界对象（Logo、新闻照片、人物/场景）：优先使用搜索工具获取素材
- 统计图表（柱线饼等）：优先使用 ECharts/Chart.js 代码生成
- 简单逻辑图（矩阵、时间轴、关系示意、流程图、组织结构、金字塔）：优先使用 HTML/CSS/Canvas 构建
阶段 4：演示文稿生成
4.1 生成 HTML
- 依据
ppt_plan.md 中的大纲和逐页描述，生成对应页面的 HTML
- 使用
write_to_file 工具生成 HTML 格式的演示文稿
- 将每页文件保存到
output/pages/page-N.pptx.html（如调用方在 prompt 上下文中指定了其他输出目录，则以指定路径为准）
- 遵循 HTML/CSS 代码规范
- 确保内容密度和视觉质量
- 先生成所有页面；转换、QA 和视觉验收必须按阶段 4.2 执行，不得跳过
- 输出文件扩展名为
.pptx.html（中间产物）
4.2 HTML 转 PPTX（自动执行）
在生成所有 HTML 页面后，自动执行以下步骤：
-
调用转换脚本：
node {skill_base_dir}/../../designer/lib/html-to-pptx/node/convert.js {output_dir}
该脚本会将 {output_dir}/page-N.pptx.html 转换为 {output_dir}/pages.pptx
-
验证 PPTX 输出：
- 检查
{output_dir}/pages.pptx 是否生成
- 如转换失败，保留 HTML 文件供排查
-
运行布局 QA（强制）：
node {skill_base_dir}/slide_layout_qa.js {output_dir}
- 必须保留
{output_dir}/layout_qa_result.json
- 只有当 JSON 中
passed 为 true 时，才能交付
- 失败页面必须返工，不能只报告“存在问题”后继续交付
-
生成视觉验收记录（强制）：
- 使用 UTF-8 写入
{output_dir}/visual_review.md
- 逐页记录
data-layout、第一视觉重点、信息密度、QA 结论和是否返工
最终产物：{output_dir}/pages.pptx
生成时的布局质量预检要求
在生成每页 HTML 时，确保代码符合以下布局质量要求：
1. 固定尺寸约束
所有内容必须在固定容器内，禁止超出边界：
.ppt-slide {
width: 1280px;
height: 720px;
overflow: hidden;
padding: 40px;
box-sizing: border-box;
}
- 内容区域边界：左右 40px 边距，上下 40px 边距，有效区域 1200×640px
- 所有元素必须严格限制在 1280×720 边界内
- 预留 5px 安全边际，避免亚像素渲染导致的溢出
2. 空白率控制（内容页 < 30%）
- 内容页（type="content"）的视觉元素投影面积占比必须超过 70%
- 封面页、章节页、结束页不受此限制
- 避免大面积无内容的留白区域
- 通过增加图表、数据可视化、信息卡片等方式填充内容
- 排除项不计入空白：全屏背景、窄色条装饰线、低透明度元素、纯装饰圆圈、纯布局容器
3. 内容密度控制
- 单页信息量：每页控制在 3-5 个核心要点，避免信息过载
- 图文结合，优先使用代码生成数据可视化图表
- 避免大段文字堆砌，单页超过 200 字需分段或使用列表
- 保持页面 20-30% 的留白空间，让内容有"呼吸感"
4. 溢出预防
- 使用
overflow: hidden 或精确计算元素位置/尺寸防止溢出
- 文本内容预留足够空间，避免文字被截断
- 响应式字体缩放：标题 28-36px，副标题 20-24px，正文 14-18px，注释 12-14px
- 长文本分段或拆分到多页，文本超出时显示省略号
5. 文本重叠避免
- 绝对定位元素之间保持足够间距
- 文本元素之间的最小间距建议 16px 以上
- 检查相邻文本块的 bounding box 是否有交集风险
- 使用 flex/grid 布局时确保元素不会挤压重叠
6. 元素遮挡避免
- 合理设置 z-index 层级，确保文本始终在最上层可读
- 背景图/装饰元素使用较低 z-index 或作为背景层
- 卡片、图表等容器内的文本必须清晰可见，不被父元素或其他元素遮挡
- 使用半透明遮罩时确保不影响文字可读性
7. 层级管理（Z-Index）规范
背景层：z-index: 0
装饰层：z-index: 5
内容层：z-index: 10
遮罩层：z-index: 20
文本层：z-index: 50（始终在最上层）
8. 布局策略
优先使用弹性布局：
<div class="flex gap-6">
<div class="flex-1">左侧内容</div>
<div class="flex-1">右侧内容</div>
</div>
<div class="grid grid-cols-2 gap-6">
<div>第一列</div>
<div>第二列</div>
</div>
<div class="grid grid-cols-3 gap-4">
<div class="col-span-1">窄列</div>
<div class="col-span-2">宽列</div>
</div>
<div class="relative">
<div class="absolute" style="left: 100px; top: 50px;">内容</div>
</div>
绝对定位使用条件：
- 仅在装饰元素、背景图层使用
- 内容区域禁止使用绝对定位
- 必须配合
position: relative 的父容器
12 列网格系统：
- 使用 12 列或 24 列网格系统，元素对齐到网格线，保持整齐
视觉设计规范
色彩系统
| 类型 | 颜色 | 用途 |
|---|
| 深色背景 | #1A1D21 | 专业沉稳主题 |
| 浅色背景 | #F8F7F5 | 优雅温和主题 |
| 纯黑背景 | #0D0D0D | 高端科技主题 |
| 主题色 | #4A6C8C | 主色调，专业可信 |
| 辅助色 | #8D99AE | 次级信息、过渡 |
| 强调色 | #D4A373 | 重点突出 |
| 深色文字 | #2B2D42 | 浅色背景上的文字 |
| 浅色文字 | #F8F7F5 | 深色背景上的文字 |
字体系统
西文字体：
Liter - 现代几何无衬线，理性专业HedvigLettersSans - 个性鲜明，品牌感强Oranienbaum - 高对比衬线，优雅古典QuattrocentoSans - 人文无衬线，温和易读SortsMillGoudy - 古典印刷风格Unna - 新古典衬线Coda - 圆润友好
中文字体：
MiSans - 小米系统字体，现代简洁Noto Sans SC - 思源黑体，标准中性siyuanSongti - 思源宋体，优雅阅读alimamadaoliti - 阿里妈妈刀隶体，力量感alimamashuheiti - 阿里妈妈数黑体，商业感zhankuwenyiti - 站酷文艺体，清新手写感deyihei - 得意黑，现代斜体LXGW Bright - 霞鹜文楷，温润清晰ZCOOL KuaiLe - 站酷快乐体，活泼卡通xiawuxinzhisong - 霞鹜新致宋，明亮优雅
字体搭配建议：
- 商务专业：
MiSans + Liter
- 优雅高端：
siyuanSongti + Oranienbaum
- 科技创新：
deyihei + HedvigLettersSans
- 活泼创意：
ZCOOL KuaiLe + Coda
HTML 代码规范
基础模板结构
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>演示文稿标题</title>
<script src="https://cdn.tailwindcss.com"></script>
<link
href="https://statics.moonshot.cn/kimi-ppt/html-gen/static/font-v2.css?family=MiSans,Liter"
rel="stylesheet"
/>
<link
href="https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@6.0.0/css/all.min.css"
rel="stylesheet"
/>
<script src="https://cdn.plot.ly/plotly-latest.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/echarts@5.4.0/dist/echarts.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<script src="https://cdn.jsdmirror.com/npm/mathjax@3.2.2/es5/tex-svg.min.js"></script>
<script>
tailwind.config = {
theme: {
extend: {
colors: {
primary: "#4A6C8C",
secondary: "#8D99AE",
accent: "#D4A373",
bgDark: "#1A1D21",
bgLight: "#F8F7F5",
textDark: "#2B2D42",
textLight: "#F8F7F5",
},
fontFamily: {
sans: ["MiSans", "Liter", "sans-serif"],
serif: ["siyuanSongti", "Oranienbaum", "serif"],
},
},
},
};
</script>
<style type="text/tailwindcss">
@layer utilities {
.ppt-slide {
@apply relative w-[1280px] h-[720px] mx-auto p-[40px] box-border overflow-hidden;
}
}
</style>
<style>
body {
color: #2b2d42;
}
</style>
</head>
<body class="bg-gray-50">
<div class="ppt-slide" type="cover" data-layout="cover-hero">
</div>
</body>
</html>
页面容器规范
- 必须使用
<div class="ppt-slide" type="页面类型" data-layout="布局名称"> 作为每页的容器
- 页面尺寸：固定为
1280px × 720px
- 页面边距：
40px
- 页面类型属性：
type 属性必须设置为以下值之一：
cover - 封面页table_of_contents - 目录页chapter - 章节过渡页content - 正文内容页final - 结束页
- 布局属性：每个页面容器必须设置
data-layout 布局意图标记，例如
cover-hero、metric-spotlight、process-flow、timeline、comparison-split、evidence-grid。
5 页以上的 deck 至少使用 3 种布局，单一布局不得超过总页数的 60%。
样式使用规范
禁止内联样式：
- 禁止在 HTML 元素上使用
style="..." 属性（图表库配置除外）
- 所有样式必须通过 Tailwind CSS 类名实现
- 图表库 (ECharts/Chart.js/Plotly) 的配置选项不受此限制，可在 JS 配置对象中使用
itemStyle、lineStyle 等
示例对比：
<div style="font-size: 24px; color: #333; margin-top: 16px;">标题</div>
<div class="text-[24px] text-gray-800 mt-4">标题</div>
<div style="width: 50%; padding: 20px; background: #f0f0f0;">内容</div>
<div class="w-1/2 p-5 bg-gray-100">内容</div>
页面类型标记示例
<div class="ppt-slide" type="cover" data-layout="cover-hero">
<div data-field="title">演示文稿标题</div>
<div data-field="presenter">演讲者姓名</div>
<div data-field="date">日期</div>
</div>
<div class="ppt-slide" type="table_of_contents" data-layout="agenda-rail">
</div>
<div class="ppt-slide" type="chapter" data-layout="chapter-statement">
<div data-field="chapter-number">1</div>
<div data-field="chapter-title">章节标题</div>
</div>
<div class="ppt-slide" type="content" data-layout="evidence-grid">
</div>
<div class="ppt-slide" type="final" data-layout="final-summary">
<div data-field="presenter">演讲者姓名</div>
<div data-field="date">日期</div>
</div>
模板占位符（使用模板时）
如用户选择了模板，封面、章节、结束页只需输出占位符：
<div class="ppt-slide" type="cover" data-layout="cover-hero">
<div data-field="title">2025 人工智能产业发展趋势分析报告</div>
<div data-field="presenter">Kimi</div>
<div data-field="date">2025.11.18</div>
</div>
<div class="ppt-slide" type="chapter" data-layout="chapter-statement">
<div data-field="chapter-number">1</div>
<div data-field="chapter-title">人工智能技术演进路径</div>
</div>
<div class="ppt-slide" type="final" data-layout="final-summary">
<div data-field="presenter">Kimi</div>
<div data-field="date">2025.11.18</div>
</div>
页面布局规范
页面规格
- 尺寸：1280px × 720px (16:9)
- 边距：40px
- 内容区域：1200px × 640px
各页面类型规范
封面页：
- 大标题（60-80px）
- 副标题/日期（20-24px）
- 背景图 + 渐变遮罩
- 居中或左对齐
目录页：
- 章节列表（4-6 个）
- 序号 + 标题 + 简介
- 网格或列表布局
章节过渡页：
内容页：
- 页面标题（32-36px）
- 核心内容区域
- 支持多栏布局（1-3 列）
- 图表/数据可视化区域
结束页：
- 感谢语/总结语
- 联系方式（可选）
- 背景图 + 遮罩
内容创作规范
大纲结构
| 页面类型 | 必需元素 | 说明 |
|---|
| 封面页 | title, presenter, date | 突出主题 |
| 目录页 | 4-6 个章节 | 序号 + 标题 + 简介 |
| 章节过渡页 | chapter-number, chapter-title | 醒目显示 |
| 内容页 | 标题 + 核心内容 | 图表/案例支撑 |
| 结束页 | 总结语 | 联系方式可选 |
页面数量控制
- 默认：12 页以内
- 用户指定：最多 30 页
- 封面：1 页
- 目录：1 页
- 章节过渡：每章节 1 页
- 内容页：根据信息量调整
内容密度分级系统
三级密度策略：
| 密度等级 | 关键信息点数量 | 适用场景 | 核心要求 |
|---|
| 高密度 | 每页 3-5 个点 | 数据报告、分析总结、竞品对比 | 图文结合，数据可视化，压缩冗余描述 |
| 中密度 | 每页 2-3 个点 | 概念阐述、流程说明、方案展示 | 清晰层次，适度留白，图文平衡 |
| 低密度 | 每页 1 个核心 | 封面、章节过渡、content（强调类）、结尾页 | 视觉冲击，简洁有力，留白艺术 |
密度选择原则：
- 封面/结尾：低密度，强调品牌/总结
- 章节过渡：低密度，过渡清晰，情绪铺垫
- 核心内容页：中高密度，信息传递为主
- 数据/分析页：高密度，充分利用空间展示关键数据
- 概念解释页：中密度，避免信息过载
防溢出核心策略
空间预算分配（1280×720px 标准画布）
| 区域 | 尺寸限制 | 说明 |
|---|
| 内容安全区 | 左右 40px 边距，上下 40px 边距 | 即 1200×640px 可用区域 |
| 页眉区 | 高度 40-60px | 标题放置区 |
| 页脚区 | 高度 30-40px | 页码/日期/来源 |
| 核心内容区 | 剩余高度 | 主要信息展示 |
内容截断机制
| 内容类型 | 截断策略 |
|---|
| 文字 | 单行字符数超限时截断并加"…"（标题≤40 字，说明≤80 字） |
| 列表 | 最多显示 5 项，超出折叠或滚动提示 |
| 图表 | 优先保证核心数据可见，标签可旋转或简化 |
| 图片 | 等比缩放至安全区域，允许裁剪边缘 |
溢出预警检查点
防空白核心策略
内容扩展技术
当内容不足以填满可用空间时，采用以下扩展策略：
| 扩展技术 | 适用场景 | 操作方法 |
|---|
| 视觉化转换 | 文字描述过多 | 将关键数据转为图表、图标、示意图 |
| 数据补充 | 数据支撑不足 | 添加趋势线、对比柱状、占比图示 |
| 案例填充 | 概念空洞 | 添加真实案例/引用/行业示例 |
| 图标装饰 | 内容稀疏 | 添加相关图标、装饰线条、背景形状 |
| 引用增强 | 观点单薄 | 添加名人名言、数据来源、权威背书 |
布局补偿技术
- 元素放大：将核心元素（图标、数字、标题）放大至视觉重心平衡
- 留白利用：用渐变背景、装饰线条、logo 填补空白区域
- 对称平衡：左右分布不均时添加呼应元素（如装饰色块）
- 视觉引导：添加箭头、引导线连接分散的元素
模块化填充
| 空白程度 | 填充策略 |
|---|
| 轻度空白（<15%） | 添加图标装饰、背景线条 |
| 中度空白（15-25%） | 添加辅助图表、次要信息 |
| 重度空白（>25%） | 重新规划布局，考虑拆分页面 |
响应式布局原则
弹性容器设计
- 使用相对单位（%、rem）而非固定像素值定义容器宽度
- 图片和图表设置
max-width: 100% 防止溢出
- 表格设置横向滚动或自动换行机制
动态字号系统
| 元素类型 | 字号策略 |
|---|
| 主标题 | 固定 36-48px，确保层次感 |
| 副标题 | 主标题的 60-80%，形成梯度 |
| 正文 | 16-20px，保证可读性 |
| 辅助文字 | 12-14px，颜色淡化处理 |
| 响应式规则 | 容器宽度 < 400px 时，字号缩小 10-15% |
叙事逻辑结构
问题驱动型：背景 → 问题 → 分析 → 方案 → 效果（适用于商业提案）
时间线型：过去 → 现在 → 未来（适用于发展历程）
金字塔型：结论 → 论据 → 细节（适用于汇报总结）
对比型：现状 A→ 现状 B→ 对比分析 → 结论（适用于竞品分析）
图表与数据可视化
图表类型选择
- 比较数据：柱状图、条形图
- 趋势数据：折线图、面积图
- 占比数据：饼图、环形图、堆叠图
- 关系数据：散点图、气泡图
- 流程数据：流程图、桑基图、漏斗图
图表规范
- 数据标签清晰标注数据值、单位
- 坐标轴明确标注含义和单位
- 多系列数据必须添加图例
- 颜色与整体配色方案协调
- 注明数据来源
ECharts 示例
const chartDom = document.getElementById("chart-id");
const myChart = echarts.init(chartDom);
const option = {
color: ["#4A6C8C", "#8D99AE", "#D4A373"],
grid: { left: "3%", right: "4%", bottom: "3%", containLabel: true },
xAxis: {
type: "category",
data: ["2020", "2021", "2022", "2023", "2024"],
axisLine: { lineStyle: { color: "#8D99AE" } },
},
yAxis: {
type: "value",
axisLine: { lineStyle: { color: "#8D99AE" } },
splitLine: { lineStyle: { color: "#E5E5E5" } },
},
series: [
{
data: [50, 85, 140, 220, 380],
type: "bar",
barWidth: "50%",
itemStyle: { borderRadius: [4, 4, 0, 0] },
},
],
};
myChart.setOption(option);
图片使用规范
图片来源
- 使用图片搜索工具获取高质量图片
- 优先选择高分辨率、无版权问题的图片
图片处理
- 使用渐变蒙版增强文字可读性
- 可添加圆角或边框效果
- 调整透明度以达到最佳视觉效果
图片布局
- 全屏背景：用于封面、章节页
- 局部配图：用于内容页，与文字配合
- 图片网格：多张图片可采用网格布局
关键原则
内容质量原则
- 信息密度：每页必须包含高信息密度，避免空洞装饰
- 叙事逻辑：遵循清晰的叙事结构
- 数据支撑：所有关键论点必须有数据或案例支撑
- 受众适配：内容深度和表达方式匹配目标受众
视觉设计原则
- 专业美感：商务级专业设计，避免花哨效果
- 层次分明：通过字体大小、颜色、间距建立清晰视觉层级
- 留白艺术：合理使用留白，避免页面拥挤
- 一致性：全篇保持色彩、字体、风格一致
技术规范原则
- 响应式设计：使用 Tailwind CSS 确保布局稳定
- 字体规范：严格使用指定字体库
- 图表生成：数据图表必须用代码生成，禁止截图
- 性能优化：控制单文件大小，确保加载流畅
分页生成模式
当任务要求分页生成 PPT 时（通过 generate_ppt_pages 工具触发），采用分页生成模式。
输出结构
output/
├── pages/ # 分页产物目录
│ ├── page-1.pptx.html
│ ├── page-2.pptx.html
│ └── ...
├── generation_status.json # 生成状态文件
└── opencode.log # 执行日志
执行流程
- 读取大纲：读取
ppt_plan.md 获取页面规划
- 逐页生成：
- 解析页面列表
- 逐页构建 HTML
- 每页保存到
output/pages/page-N.pptx.html
进度报告
每完成一页，可通过进度事件报告：
# 开始生成某页
event_type: "page_generating", page_number: N
# 某页完成
event_type: "page_completed", page_number: N, file_path: "output/pages/page-N.pptx.html"
单页 HTML 结构
每页 HTML 应该是独立可渲染的，包含：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
</head>
<body class="bg-gray-50">
<div class="ppt-slide" type="content" data-layout="evidence-grid">
</div>
</body>
</html>
禁止事项
- 大段文字堆砌
- 单页超过 200 字无分段
- 图表无标题和说明
- 数据无来源标注
- 配色超过 4 种主色
质量控制清单
生成前检查
生成中检查
生成后检查
排版检查清单
溢出检查
| 检查项 | 验收标准 | 处理建议 |
|---|
| 文字溢出 | 单行文字不超过容器宽度，截断时显示"…" | 精简文字、缩小字号或增加容器宽度 |
| 图表标签溢出 | 坐标轴标签、图例完整显示无遮挡 | 旋转标签、缩小字号或改用简短标签 |
| 图片溢出 | 图片完整显示在容器内，无截断 | 使用 object-fit: contain 或调整尺寸 |
| 页边距溢出 | 内容不紧贴画布边缘（≥ 20px） | 调整内边距或容器尺寸 |
空白检查
| 检查项 | 验收标准 | 处理建议 |
|---|
| 内容区利用率 | 内容覆盖有效区域 ≥ 70% | 补充信息、放大核心元素或添加装饰 |
| 视觉重心 | 画面重心在画布中心偏上 1/3 处 | 调整元素位置或尺寸以平衡重心 |
| 元素间距 | 相关元素间距 ≤ 50px，不相关元素间距 ≥ 50px | 重排布局或调整间距 |
| 留白质量 | 留白区域有目的（如引导视线、突出重点） | 添加装饰元素或渐变背景 |
美观检查
| 检查项 | 验收标准 | 处理建议 |
|---|
| 对齐检查 | 同级元素左对齐或居中对齐，无参差 | 使用网格系统或 flex 布局 |
| 色彩检查 | 配色协调，主色不超过 3 种 | 引用配色方案的色板 |
| 层级检查 | 标题 > 副标题 > 正文 > 辅助文字 | 检查字号梯度是否清晰 |
| 阅读顺序 | 符合从左到右、从上到下的自然阅读习惯 | 调整元素顺序或添加视觉引导 |
交付检查
常见错误与解决方案
布局相关问题
| 问题 | 原因 | 解决方案 |
|---|
| 字体加载失败 | 字体名称拼写错误 | 使用字体库中列出的确切名称 |
| 图表不显示 | 容器 ID 错误或脚本执行时机问题 | 使用立即执行函数 (IIFE) 包裹图表代码 |
| 样式不一致 | Tailwind 类名冲突 | 使用!important 或更具体的选择器 |
| 内容溢出 | 内容过多超出 540px 高度 | 精简内容或调整布局 |
| 图片加载失败 | 图片 URL 无效 | 使用可靠的图片源或 base64 编码 |
| 空白过多 | 内容不足或布局过于稀疏 | 增加图表、补充信息或紧凑布局 |
| 元素溢出边界 | 位置/尺寸计算错误 | 检查 Tailwind 类名和内联样式 |
布局错误避免清单
绝对禁止：
- ❌ 不要使用绝对定位放置大量内容
- ❌ 不要依赖浏览器默认样式
- ❌ 不要假设内容长度（预留扩展空间）
- ❌ 不要忽视响应式（不同屏幕尺寸）
- ❌ 不要对内容区使用
overflow: hidden
- ❌ 不要使用
fixed height + overflow 组合
强烈建议：
- ✅ 所有元素距离边缘 ≥ 20px
- ✅ 元素间距 ≥ 16px
- ✅ 最小字号 ≥ 12px
- ✅ 文字与背景对比度 ≥ 4.5:1
- ✅ 优先使用 flex/grid 布局
- ✅ 绝对定位需配合
position: relative 父容器
- ✅ 预留 10% 缓冲空间应对内容扩展
典型问题解决方案
| 问题类型 | 具体表现 | 解决方案 |
|---|
| 文字太多溢出 | 标题/正文超出容器边界 | ① 提炼核心文字，删除修饰词 ② 拆分为多页 ③ 启用智能换行或缩小字号 |
| 内容太少空白 | 画面空洞、留白过多 | ① 添加辅助图表或数据 ② 放大核心元素 ③ 添加图标装饰 ④ 补充案例/引用 |
| 图文比例失衡 | 图太大压文字 / 图太小看不清 | ① 文字多则图缩小做配图 ② 图为主则文字做说明标签 ③ 保持 6:4 或 7:3 的图文占比 |
| 元素相互遮挡 | 背景遮住文字 / 弹窗遮住关键信息 | ① 提高文字层 z-index ② 添加半透明背景 ③ 调整元素堆叠顺序 |
| 间距不协调 | 元素挤成一团 / 分散零乱 | ① 相关元素收紧（≤ 50px）② 不相关元素拉开（≥ 50px）③ 使用网格对齐 |
输出要求
- 文件路径：HTML 页面必须保存到
{output_dir}/page-N.pptx.html
- 路径由调用方通过 prompt 指定，本技能不得自行决定输出位置
- 注意：
output_dir 参数指向 {pages_dir}（即 {session_dir}/pages），而非 {session_dir} 本身
- 如调用方未提供
output_dir 参数，必须报错终止
- 禁止使用
output/pages/ 或任何其他硬编码路径
- 文件格式：HTML 文件，扩展名为
.pptx.html
- 页面尺寸：1280px × 720px
- 最终产物：PPT 文件，扩展名为
.pptx（自动由 HTML 转换生成）
- 页面类型：使用正确的
type 属性标记
- 内容密度：确保每页有足够的信息量，避免大面积留白
- 视觉一致性：全篇保持统一的色彩、字体和风格
- 最终回复格式：需包含以下两部分
- 完成状态（是否全部完成，是否有待确认项）
- 页面结构摘要（按页或按章节概述）
输入输出路径约定
概述
本技能通过 prompt 中的路径参数确定输入输出位置。调用方必须显式指定输入和输出路径。
路径格式要求
- 强烈建议使用绝对路径，避免歧义
- 如使用相对路径，基准目录为当前工作目录
必需参数
| 参数 | 类型 | 说明 |
|---|
ppt_plan_path | string | ppt_plan.md 文件的绝对路径 |
output_dir | string | HTML 页面的输出目录（即 {pages_dir}，指向 {session_dir}/pages） |
research_path | string | 研究报告的绝对路径（可选，跳过研究阶段时不存在） |
输入文件
{ppt_plan_path} - 大纲文件（必须存在）{research_path} - 研究报告（如存在则读取，用于补充页面内容细节）
输出产物
{output_dir}/pages.pptx - PPTX 文件（由 HTML 自动转换生成）{output_dir}/page-N.pptx.html - HTML 文件（保留）
目录处理
如输出目录不存在，本技能将自动创建目录。
错误处理
如调用时缺少必需参数，本技能将报错并终止：
错误：缺少必需参数。
本技能需要以下必需参数：
- ppt_plan_path: ppt_plan.md 文件的绝对路径
- output_dir: HTML 页面的输出目录（即 `{pages_dir}`，指向 `{session_dir}/pages`）
可选参数：
- research_path: 研究报告的绝对路径（跳过研究阶段时不存在，此时页面内容将基于大纲描述生成）
正确调用示例：
"请生成幻灯片，大纲在 /home/user/output/ppt_plan.md，输出到 /home/user/output/pages"
调用示例
通过 pptx-craft 调用：
请根据 ppt_plan.md 生成 HTML 幻灯片。
大纲文件路径：{ppt_plan_path}
输出目录：{output_dir}（即 {pages_dir}）
研究报告路径：{research_path}
独立使用：
请根据 ppt_plan.md 生成 HTML 幻灯片。
要求：
- 大纲文件路径：/home/user/output/ppt_plan.md
- 研究报告路径：/home/user/output/research.md
- 输出目录：/home/user/output/pages
设计哲学
核心理念
"每一像素都应有其存在的意义"
每一像素都应服务于信息的传递与视觉的体验。没有无缘无故的留白，也没有毫无意义的装饰。
设计三原则
| 原则 | 含义 | 实践 |
|---|
| 必要性 | 每个元素都必须有存在的理由 | 删除无法解释其用途的元素 |
| 目的性 | 每个元素都应有明确的功能 | 装饰元素必须辅助信息理解 |
| 经济性 | 用最少的元素达成最好的效果 | 避免过度设计，信息密度适当 |
留白的艺术
- 留白不是浪费，而是给内容"呼吸"的空间
- 核心内容周围的留白可以引导视线、突出重点
- 低密度页面（如封面）的留白是一种视觉语言
- 高密度页面（如数据页）的留白可以分隔信息层级
视觉层级法则
- 第一眼：应看到最核心的信息（标题/数据/关键词）
- 第二眼：应看到辅助说明（图表/图标/次要文字）
- 第三眼：应看到装饰元素（背景/线条/品牌元素）
每个页面都应该有清晰的视觉层级，让读者在 3 秒内抓住重点。
布局即叙事
- 布局不仅是摆放元素，更是组织信息、引导阅读
- 重要的内容放在视觉重心位置（画面中心偏上 1/3 处）
- 相关内容应靠近，不相关内容应有明确分隔
- 阅读顺序应符合自然习惯（左到右、上到下）
