slide-creator

幻灯片创建器 — HTML → PDF 演示文稿

将幻灯片制作成 HTML，并通过无头 Chromium 导出为像素级精准的 16:9 PDF。

输出格式：PDF — 不是 Microsoft PowerPoint（.pptx）。PDF 可在所有设备上精确保留布局、字体和颜色。

为什么选择 HTML → PDF

• CSS 布局（Grid/Flexbox）比任何 PPT 编辑器都灵活得多
• 完整支持 Web 排版、渐变、SVG、动画（打印时也能优雅降级）
• 适合 Git 管理、可复现、可脚本化
• 一条命令 → 生成页面尺寸精确为 16:9 的 PDF

工作流

0. 识别场景（新）

开始其他步骤前，先识别演示文稿的场景。阅读 references/content-scaffolding.md 获取完整模板。

场景关键词	使用的模板
路演 / 投资者 / 融资	pitch-deck
会议 / 主题演讲 / 峰会 / 演讲	conference-keynote
产品发布 / 发布活动	product-launch
报告 / 研究 / 分析	research-report
（以上都不适用）	询问用户最符合哪种场景

每个模板都定义了：幻灯片数量、页面标题、每页必需的内容。

0.5 双语布局（如有需要）

如果受众为双语群体（例如香港、新加坡、全球华人会议），或用户提到中文 + 英文：

• 使用 references/content-scaffolding.md 中的 bilingual 布局模式
• 标题：英文（大号）+ 中文副标题（较小，--text-muted）
• 正文要点：先中文，英文可放在括号内
• 面向香港／台湾／新加坡受众时，避免纯英文幻灯片

1. 规划演示文稿

根据场景模板确定幻灯片数量和每页内容。每张幻灯片对应一个 <section class="slide">。

1.5 艺术指导（构建前运行）

每当用户未指定具体视觉风格时，都运行此步骤。 阅读 skills/slide-creator/references/art-direction.md，了解完整的风格分类、 CSS 令牌模板和风格简报输出格式。

步骤 A — 提出 4 个问题：

1. 受众与场景：这是为谁准备的？用于什么场合（投资者／内部团队／公开主题演讲）？
2. 情绪关键词：希望受众产生什么感受（权威／活力／友好／极客现代）？
3. 品牌限制：是否有指定的品牌颜色、标志或字体？
4. 参考资料：是否有需要参考的模板（图片、网页链接、现有幻灯片截图）？

步骤 B — 生成视觉风格选择页： 不要用文字描述来展示风格选项——用户无法仅凭文字评估风格。

参考资料处理规则：

• 如果用户提供了图片文件／截图：从视觉内容中提取配色（主色／表面色／强调色），检查布局密度、圆角半径和字体风格。
• 如果用户提供了网页 URL：使用 web_fetch 提取设计线索。重要——遵循此提取流程，避免误判风格：
  1. 忽略品牌名／域名——绝不要根据产品所属行业或名称推断视觉风格（例如，“Neo”不代表霓虹风，“Opera”不代表欧洲奢华风）。
  2. 阅读文案的语气和词汇——页面用词能揭示情绪（例如，“精准如手术刀”“沉静自信”→克制；“释放”“彻底革新”→大胆／激进）。
  3. 提取明确的颜色词汇——查找抓取文本中的 CSS 关键词，或正文／alt 标签中提到的颜色名称。判断色调是暖还是冷、浅还是深、柔和还是鲜艳。
  4. 推断布局密度——统计每个版块的字数；稀疏＝编辑风／奢华风，密集＝技术风／功能风。
  5. 识别装饰元素——查找明确提及或暗示的元素（例如几何图形、渐变、摄影、插画、线稿、粗野主义）。
  6. 对照 art-direction.md——找出最接近的模板，然后描述差异（例如，“采用风格 G，但更温暖，将蓝色换成焦橙色，并添加细微网格线”）。
  7. 无法确定时：谨慎处理——不要过度承诺风格匹配，并提供 3 个选项，其中选项 A 是你认为最符合的解读，B 更稳妥／简洁，C 更具实验性。绝不要自信地断言与实际视觉证据相矛盾的风格。
• 如果用户同时提供了图片和网页参考：优先依据图片线索，其次参考网页线索。
• 如果没有提供参考资料：使用内置风格分类的默认设置。

然后：

1. 创建 output/style-picker/index.html——单页包含 3 个并排的迷你幻灯片预览（16:9 宽高比），每个预览都使用真实 CSS 完整渲染（颜色、字体、布局和装饰元素）。每个预览都必须看起来像一张实际幻灯片，而不是色卡。
2. 将这 3 个选项设计为：(A) 忠实还原参考风格、(B) 更稳妥的企业风格变体、(C) 更大胆的创意变体。
3. 对该目录运行 preview(action='serve')，并显示预览 URL。
4. 每张卡片下方都要有标签：风格名称＋一句话描述。
5. 添加 onclick 高亮效果，让用户可以点击选择。

用户可以说“Choose A”“I want B”“Blend A+C”等来选择。

步骤 C — 生成 style-brief.md： 用户选定风格后，在项目目录中编写 style-brief.md（模板见 art-direction.md）。 后续所有 HTML/CSS 工作都必须遵循此简报。

步骤 D — 询问品牌素材（标志／颜色）： 用户选定风格后，询问：

“您是否有要加入的标志或品牌颜色？可以上传图片文件，我会将标志嵌入所有幻灯片。”

如果用户上传了标志：将其以 base64 格式嵌入 HTML（在 bash 中使用 base64.b64encode），放在左上角或右上角，高度不超过 60px。 如果用户提供了品牌颜色：在 CSS 令牌区块中用用户指定的颜色覆盖 --accent。

2. 选择主题

如果已完成 Art Direction，style-brief.md 就是主题规范——跳过此表格。 否则，可将其用作快速备用方案：

风格	背景	强调色	字体	氛围
深色科技	#000 / #0a0a0a	亮橙色／蓝色／绿色	Inter、Space Grotesk	大胆、现代
明亮简洁	#fff / #f8f8f8	藏青色、青绿色、珊瑚色	Inter、DM Sans	专业、简约
渐变	深色渐变	鲜艳的强调色	任意无衬线字体	富有创意、充满活力
企业风	#1a1a2e / 白色	品牌色	系统字体	可靠、正式
活泼	柔和的粉彩色	温暖亮眼的颜色	Nunito、Poppins	友好、随性

3. 构建 HTML + CSS

创建包含 index.html 和 styles.css 的项目目录。

从 assets/base.css 开始——它包含结构框架（幻灯片尺寸、打印规则、布局辅助类），不含颜色和字体。在此基础上叠加主题样式：

/* Example theme layer — customize freely */
body {
  font-family: 'Inter', sans-serif;
  color: #fff;
  background: #000;
}
.slide { background: #0a0a0a; }
.slide-tag { background: rgba(0,120,255,0.15); color: #0078ff; }
.card { background: rgba(255,255,255,0.04); border: 1px solid rgba(255,255,255,0.08); }

强制结构规则（位于 base.css 中——不要删除）：

.slide { width: 1280px; height: 720px; page-break-after: always; overflow: hidden; }
@page { size: 1280px 720px; margin: 0; }

关键规则：

• 使用 px 单位——幻灯片尺寸不得使用 vh/vw/rem/%
• Google Fonts：在 <head> 中使用 <link>，导出脚本会等待网络空闲
• 视口 meta 标签：<meta name="viewport" content="width=1280">
• 内容必须控制在 720px 高度以内——溢出部分会被裁切

4. 预览（可选）

导出前，使用 preview(action='serve') 在浏览器中预览。

5. 导出为 PDF

python3 skills/slide-creator/scripts/export_pdf.py --dir <project-dir> --output output/<name>.pdf

选项：

• --dir — 包含 index.html 的目录（必填）
• --output / -o — 输出 PDF 路径（默认值：<dir>/deck.pdf）
• --width — 幻灯片宽度，单位为 px（默认值：1280）
• --height — 幻灯片高度，单位为 px（默认值：720）

6. 验证

脚本会输出幻灯片数量并确认输出路径。额外检查：

import fitz
doc = fitz.open("output/deck.pdf")
print(f"Pages: {doc.page_count}")
for p in doc:
    r = p.rect
    print(f"  {r.width*96/72:.0f}x{r.height*96/72:.0f}px")

风格指南

• 不设默认品牌风格——每个演示文稿都应采用契合其内容的主题
• 优先采用 Art Direction 优先的工作流（提问 → 参考 → 用户选择 → style-brief.md）
• 询问用户的偏好：深色／浅色、强调色、字体、氛围
• 每张幻灯片都应具有清晰的视觉层级：标签 → 标题 → 内容
• 保持文字简洁——幻灯片是视觉呈现，而不是文档
• 使用带有主题色径向渐变的 .bg-glow 来增强纵深感
• 默认不要使用 web_search 探索风格；优先采用用户提供的参考图片／链接以及 art-direction.md 中的模板。
• 用户提供参考链接时，使用 web_fetch 提取设计线索（色调／语气／布局），但最终 CSS 应使用本地模板和 token 变量实现。
• 用户请求“art-direction advice / style advice”时，始终生成一个包含 3 种方案的可视化风格选择预览页——不要只依赖文字描述。
• 严格按照选定的风格规范构建 HTML，然后导出 PDF（除非用户明确选择跳过，否则不要省略风格规范）
• 选定风格后，构建前始终询问是否有 Logo／品牌素材
• 面向 HK/TW/SG／双语受众时，默认采用双语布局，除非用户要求仅使用英语

风格微调（选定风格后）

如果用户说“将主色改为红色”／“更换字体”／“增大圆角半径”，不要重新开始 Art Direction。 直接修改 styles.css 中的 --accent / --font-head / --radius CSS 变量即可。 只有当用户想要完全不同的风格时，才重新开始 Art Direction

注意事项

• Chromium：容器启动时通过 workspace/setup.sh 预装（约 641 MB，缓存在 ~/.cache/ms-playwright/）。切勿在每次导出时运行 playwright install——它会重新下载同一个浏览器。只有当 export_pdf.py 因 Executable doesn't exist 而失败时才运行，并且还要将该命令追加到 workspace/setup.sh，以确保设置持久生效。

• 字体：Google Fonts 需要 HTTP——导出脚本会自动启动本地服务器

• Emoji 渲染：无头 Chromium 可能缺少 Emoji 字体——请改用 SVG 图标

• 大尺寸图片：以 base64 嵌入或使用相对路径（本地服务器会提供项目目录）

• 幻灯片溢出：超过 720px 高度的内容会被裁切——请将内容控制在边界内

• ⚠️ PDF 文本无法选中（已于 2026 年验证）：对任何包含文本的祖先元素应用 CSS filter / backdrop-filter，都会导致 Chromium 在导出 PDF 时将该图层栅格化为位图——所有子元素中的文本都会变成像素，无法选中。解决方法：绝不要对包含文本的容器应用 filter / backdrop-filter。仅对不含文本子元素的空装饰性 <div> 元素（例如 .blur-layer、.glow-overlay）应用这些属性。同样的规则也适用于文本父元素上的 mix-blend-mode。导出前检查清单：搜索 HTML，查找非装饰性元素上的 filter / backdrop-filter，并移除这些属性。

• ⚠️ 页脚 / 来源标注——使用标准组件 + 严格遵守底部安全区约定（已于 2026 年验证）：临时编写的页脚标记会导致各幻灯片上的位置不一致。所有来源引用、页码和免责声明都必须使用此 .slide-footer 模式。

  严格布局约定（不得省略）：

  • 除封面外，每张幻灯片都必须有专用的内容包装器（例如 .slide-body），并为页脚预留空间。
  • 硬性规则：.slide-body 必须通过底部安全区预留页脚空间，且数值 >= 96px（默认值为 96px）。示例：.slide-body { padding: 52px 72px 96px; }。
  • 页脚必须脱离常规文档流：设置 position: absolute; bottom: 24px，作为 .slide 下面与 .slide-body 同级的元素。
  • 来源 / 免责声明文本不得放在 .slide-body 中。
  • 仅当封面没有 .slide-footer 时，才可以例外处理。

  这样可以确保物理隔离：正文内容区域在预留的页脚区域上方结束，页脚则留在画布底部区域，因此无论内容密度如何，两者都不会重叠。

  <footer class="slide-footer">
    <span class="footer-source">Source: CoinGecko · Coinglass · DefiLlama</span>
    <span class="footer-page">03 / 12</span>
  </footer>
  

  .slide-footer {
    position: absolute;
    bottom: 24px; left: 48px; right: 48px;
    display: flex; justify-content: space-between; align-items: center;
    font-size: 11px; color: rgba(255,255,255,0.35);
    border-top: 1px solid rgba(255,255,255,0.08);
    padding-top: 8px;
    z-index: 2;
  }
  .slide > *:not(.bg-glow):not(.slide-footer) {
    position: relative;
    z-index: 1;
  }
  .slide-body { padding-bottom: 96px; }
  

  切勿使用流内页脚或 position: relative 页脚——它们会随幻灯片内容高度变化而移动。还要将 .slide-footer 排除在通用 .slide > * 层叠规则之外，否则 CSS 顺序可能会意外覆盖页脚的层级。 验证检查清单（导出前必须完成）：

  1. 除封面外，每张幻灯片的 .slide-body 和 .slide-footer 都是同级元素；
  2. .slide-body 的底部内边距为 >=96px；
  3. 来源 / 免责声明文本只出现在 .slide-footer 中，不得出现在正文容器中。

• ⚠️ z-index / 装饰性叠层错误（已于 2026 年验证）：.bg-glow 和其他装饰性伪图层必须设置 z-index: 0，并为所有实际幻灯片内容明确设置 z-index: 1。如果 .bg-glow 与 .slide > * 是同级元素（而不是 ::before / ::after 伪元素），请添加以下规则，确保内容不会被视觉上遮挡：

  .slide > *:not(.bg-glow) { position: relative; z-index: 1; }
  .bg-glow { position: absolute; z-index: 0; pointer-events: none; }
  

  故障表现：PDF 导出后内容被推到底部或不可见，但浏览器预览正常（与 Chromium 的打印流程相比，浏览器合成对 z 轴顺序的处理更宽松）。