frontend-slides-editable

Frontend Slides（可编辑）

创建零依赖、动画丰富的 HTML 演示文稿，完全在浏览器中运行，并内置编辑器：移动对象、使用 Ctrl+click 多选、对齐吸附、通过字体族 + 字号控件进行简单文本格式化、撤销/重做、Pages 侧边栏（幻灯片缩略图，可拖动重新排序、删除）、演示工具（Laser 指针和全屏）、Ctrl+S 持久化以及导出 HTML。

本 skill 是 frontend-slides skill 的副本，并扩展了可编辑幻灯片运行时。对于不需要编辑器负担的只读幻灯片，请改用原始的 frontend-slides skill（skills 目录结构相同）。

<preset_fidelity> 与父级 frontend-slides 保持一致（样式灵活性）

添加编辑模式不得取代预设创作。 父级 skill 将 STYLE_PRESETS.md 中的每个选择视为一份规范：对于每个预设，你都要实现其 Layout 说明、Signature Elements、排版和颜色 —— 标题幻灯片和内容幻灯片在不同预设之间有所不同（例如 Bold Signal 的卡片 + 大号数字 vs. Notebook Tabs 的纸张 + 边缘标签 vs. Swiss Modern 的网格 + 红色条）。

Phase 3 中的规范性行为：

1. 阅读所选预设的 STYLE_PRESETS，并在 HTML/CSS 中体现布局 + 标志性元素，而不仅仅是 :root 颜色和字体。
2. 可编辑参考（examples/editable-deck-reference.html）提供 JS/CSS 模式（chrome、侧边栏、对象、历史记录）—— 而不是可粘贴到每份幻灯片上的冻结幻灯片布局。不要为每种样式复用同一种通用的“标题 + 副标题 + 圆角矩形角标”几何结构。
3. examples/generated/presets/*.html 是示例幻灯片，不是布局捷径。这 12 个旧版示例用于运行时冒烟测试 + 视觉预览；这 34 个移植示例是来自 beautiful-html-templates 的真实模板移植，使用共享的 Swiss/reference 运行时以及锁定的 slot 编辑。对于真实交付，请匹配所选预设/模板语法，而不是复用通用的 README 幻灯片。
4. 静态 chrome（不应可拖动的装饰）可以按预设放在 .slide-edit-layer 之外（例如背景伪元素、固定导航 chrome）；可移动的文案和块保留在层内作为 [data-slide-object]。

如果运行时约束与某个标志性元素发生冲突，请调整该元素（例如用 CSS 实现相同的视觉效果，或拆分为多个对象）—— 不要为了单一模板而放弃预设身份。 </preset_fidelity>

<template_ports> 真实模板移植（slot 可编辑）

对于来自 beautiful-html-templates 的 34 个移植预设，优先考虑上游模板的氛围 / 基调 / 密度和视觉语法，而不仅仅是颜色 token 匹配。

交互基线：移植幻灯片必须使用与 examples/editable-deck-reference.html / swiss-modern.html 相同的 Swiss/reference 编辑器 chrome 和对象编辑器。原生模板 slot 是锁定布局的内容 slot；用户添加的对象是普通的 [data-slide-object][data-oid] 对象。

重要交互契约： data-edit-slot 是可编辑内容，不是可拖动组件。在编辑模式下，用户可以点击 slot 文本/图片，通过 RTE/撤销/重做/保存/导出更改其内容，但上游模板的布局网格、卡片几何结构、装饰层和间距保持锁定。只有 .slide-edit-layer 中用户添加的对象才会成为可选择、可拖动、可调整大小的组件。除非明确请求并实现单独的分组化模式，否则不要承诺每个原生模板子元素都会获得对象控制柄。

模板编辑模式：

• data-template-edit-mode="slots" 是默认模式，支持模板安全编辑：可通过插槽编辑创作内容，而布局和装饰保持锁定。
• data-template-edit-mode="components" 是可选的生成模式，适用于可表示为 [data-slide-object] 的语义块。
• 在交付的移植版演示文稿中，解锁布局会按需将当前幻灯片组件化：把原始可编辑插槽节点移动或包装到 .slide-edit-layer 中。必须保留原始元素标签、类和计算后的排版样式，不得创建重复的内容副本，并且必须支持撤销，以恢复到原始布局位置。
• 切勿将每个 DOM 节点都组件化。排除背景、网格、坐标轴、刻度、装饰标记、纹理／故障效果图层、SVG 路径、动画包装器和纯布局容器。

使用或扩展移植版预设时：

1. 将匹配的 beautiful-html-templates/templates/{source_slug}/template.html 视为视觉系统：保留字体、CSS 变量、幻灯片级类、布局网格、装饰性 DOM 和组件语法。
2. 通过插槽编辑创作内容，不要将模板拆解成可拖动方框。使用：
   • data-edit-slot
   • data-slot-type="text|image|metric|table-cell"
   • data-slot-label
   • data-slot-locked-layout="true"
3. 除非用户理应自然地修改某个具体元素，否则请保持装饰元素锁定。网格、纸张纹理、细线、扫描线、像素／故障效果图层、装饰标记和布局容器都不应变成可拖动对象。
4. 为用户添加的自由形式对象保留 .slide-edit-layer。新增对象可使用 [data-slide-object][data-oid] 和标准的 Swiss 拖动／调整大小／多选运行时；原生模板插槽使用 Swiss RTE／撤销／重做／保存／导出路径，但不会获得移动／调整大小控点。
5. 如果缺少所需的幻灯片类型，请在同一模板系统中设计新的幻灯片：使用相同的字体、配色、间距节奏、界面元素和组件语法。不要混入其他模板的视觉语言。 </template_ports>

<discovery_gate> Discovery gate（不可跳过）

模型经常会直接开始生成 HTML。对于模式 A（新建演示文稿）和模式 B（PPT 或 PDF）在提取后，必须先完成阶段 1，再进入阶段 2；再完成阶段 2，才能进入阶段 3——除非适用下方所述的特例。

硬性规则： 除非用户在一轮对话（或一个范围明确的批次）中提供了阶段 1 检查清单中的全部内容，否则必须先通过一条合并消息（或结构化提问界面）执行阶段 1。如果批次内容不完整，下一条消息中只发送缺失的检查清单项目——不要猜测幻灯片数量、大纲深度、预设或语言。**调用 /frontend-slides-editable 或附加此技能并不能免除发现流程。**一句话请求（例如“用 skill 介绍它自己”“做一份某某主题的演示”）只提供了主题／意图，不构成需求简报。

阶段 1 检查清单（完整需求简报——所有项目均为必需，不得由模型推断）：

| # | 维度 | “完成”的含义 | |---|-------------|-------------------| | 1 | **目的** | 推介／教学／会议／内部／元角色（例如技能入门）等 | | 2 | **长度** | **幻灯片数量范围**（例如短篇 5–10 页／中篇 10–20 页／长篇 20 页以上）**或**确切页数——绝不能仅根据主题推断 | | 3 | **内容** | 粘贴的大纲、要点、草稿文案，**或**指定来源及提取范围（例如“仅 README §X–Y”）；不能只有“一个主题” | | 4 | **风格方向** | Phase 1 风格偏好类别，**或**来自 [STYLE_PRESETS.md](STYLE_PRESETS.md) 的**具名**预设，**或**明确授权代为选择（“由你决定”）——如果用户只说“由你决定”，除非用户也明确跳过预览，**Phase 2** 仍需通过推荐／预览来缩小选择范围 | | 5 | **编辑** | 确认使用**完整可编辑运行时**（本技能的默认选项），**或**明确切换到父级**只读** `frontend-slides` | | 6 | **图片** | 不需要／需要／不确定；如果**需要**，文件可以稍后提供，但意向必须明确 | | 7 | **移动端** | 必须回答：**仅优先适配桌面端**（默认选项）或**适配手机竖屏和横屏**；不得默默推断 | | — | **语言／地区设置** | 当面向受众的文案尚未指定语言时：单语／双语／按地区设置分别提供文件——在 Phase 1 中询问 |

图片与大纲：仅当用户已有可供评估的素材或链接后，才共同设计大纲 ↔ 图片（Step 1.2）。不要仅因为图片尚未提供就跳过 Phase 1 的维度；在 Phase 1 中记录“需要，稍后提供”，然后等文件就绪后再评估图片。

模式 B（PPT／PDF）：运行 extract-pptx.py（.pptx）或 extract-pdf.py（.pdf）后，展示标题／摘要／素材数量，并且仍要针对提取结果无法确定的事项执行 Phase 1：需要重组时的长度目标、风格方向、编辑范围、地区设置，以及对提取素材的图片处理说明。不要从“这是提取结果”直接跳到只选择风格——先补齐 Phase 1 的缺项，再进行 Phase 2，最后生成代码。

可缩短 Phase 1 和／或 Phase 2 的情况（仅限少数例外）：

1. 明确选择跳过——用户明确跳过需求确认和／或预览（例如“跳过需求确认，你全部决定”、“不做需求确认——直接生成”）。
2. 完整的书面需求说明——同一批信息已满足 Phase 1 清单中的每一项，无需你猜测，并且满足以下任一条件：(a) 已选择具名预设，因此 Phase 2 可直接交接到 Phase 3；或 (b) 用户明确允许不提供预览，并接受你推荐的单个预设。

默认顺序： **Phase 1（分组进行）→ Phase 2（展示，而非空谈）→ Phase 3。**绝不要为了“减少轮次”而启动 Phase 3。

**部分回答：**下一条消息 = 仅询问 Phase 1 中缺少的项目，然后继续 Phase 2。

绝不要把沉默视为同意。 模式 C（增强现有 HTML）：变更清单明确时，可以跳过完整的 Phase 1–2；如果需求含糊，例如“做得更好”，则先提出 1–2 个澄清问题。

**反面模式：**仅仅因为附加了此技能，或因为你“已经知道”合适的长度或预设，就直接生成 HTML——这是失败模式。

为了“减少轮次”而跳过需求确认，是此技能的失败模式。 </discovery_gate>

<core_principles> 核心原则

1. 零依赖 — 使用内联 CSS／JS 的单个 HTML 文件。不需要 npm 或构建工具。
2. 展示，而非空谈 — 生成可视化预览，而不是抽象选项。人们通过亲眼看到来发现自己的需求。
3. 设计独特 — 不要千篇一律地生成“AI 垃圾”。每个演示文稿都必须有量身打造的感觉。
4. 视口适配（不可妥协） — 每张幻灯片都必须恰好适配 100vh。幻灯片内绝不能滚动。内容溢出？拆分成多张幻灯片。 </core_principles>

<design_aesthetics> 设计美学

你往往会趋向生成千篇一律、“符合分布”的内容。在前端设计中，这会造成用户所说的“AI 垃圾”风格。请避免这种情况：打造富有创意、风格鲜明、令人惊喜愉悦的前端设计。

</design_aesthetics> 关注以下方面：

• 字体排版：选择美观、独特且有趣的字体。避免使用 Arial 和 Inter 等通用字体；优先选择能提升前端美感的特色字体。
• 色彩与主题：坚持统一的美学风格。使用 CSS 变量保持一致性。主色鲜明、点缀色锐利的配色，胜过犹豫不决、分布均匀的调色板。可从 IDE 主题和文化美学中汲取灵感。
• 动效：生成的演示文稿中仅使用 CSS 动画和过渡效果（此技能输出单文件 HTML，不使用 React 或 Motion 库）。专注于影响力强的时刻：精心编排一次加载动画并使用错落的显示效果（animation-delay），胜过零散的微交互。
• 背景：营造氛围与层次感，而不是默认使用纯色。叠加 CSS 渐变、使用几何图案，或添加契合整体美学的情境效果。

避免千篇一律的 AI 生成风格：

• 过度使用的拉丁字体系列（Inter、Roboto、Arial、纯系统默认字体）——请注意，经过精心挑选的 CJK 系统字体栈才是正确的可移植选择，并不属于这里所说的“通用风格”（参见 Phase 3 §字体与可移植性）
• 陈词滥调的配色方案（尤其是白底紫色渐变）
• 可预测的布局与组件模式
• 缺乏情境特色的模板化设计

请发挥创意，做出出人意料、真正贴合情境的设计。尝试不同的明暗主题、字体和美学风格。你仍然容易在不同生成结果中趋向常见选择（例如 Space Grotesk）。务必避免这一点：跳出思维定式至关重要！ </design_aesthetics>

<viewport_fitting_rules> 视口适配规则

以下不变量适用于每个演示文稿中的每张幻灯片：

• 每个 .slide 都必须设置 height: 100vh; height: 100dvh; overflow: hidden;
• 所有字体大小和间距都必须使用 clamp(min, preferred, max)，绝不能使用固定的 px/rem
• 内容容器需要设置 max-height 限制
• 图片：max-height: min(50vh, 400px)
• 必须为 700px、600px、500px 高度设置断点
• 支持 prefers-reduced-motion
• 绝不能直接对 CSS 函数取反（-clamp()、-min()、-max() 会被静默忽略）——请改用 calc(-1 * clamp(...))

生成时，请读取 viewport-base.css，并在每个演示文稿中完整包含其全部内容。

每张幻灯片的内容密度限制

幻灯片类型	内容上限
标题页	1 个标题 + 1 个副标题 + 可选标语
内容页	1 个标题 + 4-6 个要点，或 1 个标题 + 2 段文字
功能网格	1 个标题 + 最多 6 张卡片（2x3 或 3x2）
代码页	1 个标题 + 8-10 行代码
引用页	1 条引用（最多 3 行）+ 署名
图片页	1 个标题 + 1 张图片（高度最多 60vh）

内容超出限制？请拆分成多张幻灯片。切勿塞得过满，也不要滚动。 </viewport_fitting_rules>

<quick_start> <mode_detection> 阶段 0：识别模式

确定用户的需求：

• 模式 A：新建演示文稿——从头创建。转到阶段 1。
• 模式 B：PPT / PDF 转换——转换 .pptx 或 .pdf 文件。转到阶段 4。
• 模式 C：优化——改进现有 HTML 演示文稿。读取并理解内容后进行优化。遵循下方的模式 C 修改规则。 </mode_detection>

<mode_c_modification_rules> 模式 C：修改规则

优化现有演示文稿时，视口适配是最大的风险： </mode_c_modification_rules> </quick_start>

1. 添加内容之前： 统计现有元素数量，并检查是否符合密度限制
2. 添加图片： 必须设置 max-height: min(50vh, 400px)。如果幻灯片内容已达上限，请拆分为两张幻灯片
3. 添加文本： 每张幻灯片最多 4-6 个项目符号。超出限制？请拆分为连续的多张幻灯片
4. 进行任何修改后，验证： .slide 已设置 overflow: hidden，新元素使用 clamp()，图片设置了相对于视口的最大高度，且内容在 1280x720 下能够完整显示
5. 主动重新组织： 如果修改会导致内容溢出，请自动拆分内容并告知用户。不要等用户提出要求

向现有幻灯片添加图片时： 先将图片移到新幻灯片，或减少其他内容。添加图片前，务必检查现有内容是否已占满视口。 </mode_c_modification_rules>

<phase_1_content_discovery> Phase 1：内容发现（新建演示文稿及 PPT/PDF 路径）

集中完成 Phase 1： 对于模式 A，以及模式 B 完成提取后，在一次集中的交互中提供清单（见上文的发现阶段门槛），不要分散到多轮对话中。如果用户的首条消息不完整，接下来只询问缺失的信息。

在 Phase 1 完成之前，不要跳到风格预览或 HTML（发现阶段门槛的例外情况除外）。

从头开始时，在这次集中的交互中询问以下所有发现问题（1–6）。如果有结构化问题工具，请使用；否则发送一条简洁的消息：

问题 1 — 用途（标题：「用途」）： 这份演示文稿的用途是什么？选项：路演演示 / 教学教程 / 会议演讲 / 内部演示

问题 2 — 长度（标题：「长度」）： 大约需要多少张幻灯片？选项：短篇 5-10 张 / 中篇 10-20 张 / 长篇 20 张以上

问题 3 — 内容（标题：「内容」）： 内容准备好了吗？选项：内容已全部准备好 / 只有粗略笔记 / 只有主题

问题 4 — 风格偏好（标题：「风格偏好」）： 您希望采用哪种视觉风格作为起点？选项：

• 「为我推荐」——根据受众、主题和内容推断
• 「简洁 / 专业」——克制、精致、可靠
• 「大胆 / 实验性」——高对比度、充满活力、令人惊喜
• 「编辑风 / 温暖」——有人情味、精心打造、以故事为主线
• 「技术风 / 极简」——精准、有条理、产品化
• 「我已经知道预设」——跳过此项，直接选择预设

问题 5 — 编辑范围（标题：「编辑」）： 确认用户需要完整的可编辑运行环境（此技能的默认选项）：对象布局、Pages 侧边栏、撤销/重做。如果用户明确表示只需要精简的只读文件，请改用上级 frontend-slides 技能，而不是随意从此技能中移除运行环境。

问题 6 — 素材 / 图片（标题：「图片」）： 这份演示文稿会使用您提供的图片文件（文件夹、上传文件或链接）吗？选项：不使用图片（仅使用 CSS/图形） / 使用，我会提供图片 / 不确定，请推荐

问题 7 — 移动端适配（标题：「移动端」）： 这份可编辑的演示文稿是否需要适配手机竖屏和横屏？选项：仅适配桌面端（推荐；让演示文稿针对桌面端演示和编辑进行优化） / 适配手机竖屏和横屏（添加移动端专用 CSS 钩子、侧边栏行为，以及额外的视口验证）。这是新建演示文稿以及 PPT/PDF 转换在提取内容后必须回答的 Phase 1 问题。

语言 / 地区设置（适用时在同一条集中消息中询问）： 如果交付内容必须为单语、双语或本地化版本（例如同一张幻灯片中包含中英双语，或分别生成两个文件），且用户尚未说明，请在此处一次性询问。

如果用户已有草稿内容（项目符号、文档、大纲），请让他们在同一轮或紧接着 Phase 1 粘贴或附上。

<image_evaluation> 步骤 1.2：图片评估（如果提供了图片） 如果 Question 6 的答案是 No images，或用户尚未提供任何图像文件 → Phase 1 的其他部分完成后，进入 Phase 2（如果用户改变主意，仍可在 Phase 3 前请他们添加图像）。

如果用户在 Phase 1 将图像标记为有之后，再提供图像文件夹（或链接）：

1. 扫描 — 列出所有图像文件（.png、.jpg、.svg、.webp 等）
2. 检查每张图像 — 使用主机提供的图像/文件查看功能
3. 评估 — 对每张图像说明其内容、是否可用（USABLE 或 NOT USABLE，并说明原因）、代表的概念以及主导颜色
4. 共同设计大纲 — 精选图像与文本共同决定幻灯片结构。这不是“先规划幻灯片再添加图像”——而是从一开始就围绕两者进行设计（例如，3 张截图 → 3 张功能介绍幻灯片，1 个徽标 → 标题/结束幻灯片）
5. 通过一次归组的后续提问确认大纲（如有结构化问题 UI，则使用该 UI）：“这个幻灯片大纲和图像选择看起来合适吗？”选项：看起来不错 / 调整图像 / 调整大纲

预览中的徽标： 如果识别出可用的徽标，请将其（base64）嵌入 Phase 2 的每个风格预览中 — 让用户看到自己的品牌以三种不同方式呈现。 </image_evaluation> </phase_1_content_discovery>

<phase_2_style_discovery> Phase 2：风格探索（展示，而非描述）

仅在 Phase 1 完成后开始（参见 探索门槛）。

目的： 通过视觉方式缩小美学风格范围 — 大多数人无法准确说出自己想要什么。使用 HTML 预览（以及 STYLE_PRESETS.md 中的具体参考和仓库示例：examples/generated/presets/ 烟雾测试演示文稿、用于运行时界面的 examples/editable-deck-reference.html），让用户先选择方向，再选择预设或混合风格。

这是“展示，而非描述”的阶段。

<style_preference_first> 步骤 2.0：先了解风格偏好

从 Phase 1 中记录的风格偏好开始。在询问用户想如何选择之前，先简短推荐 2-4 个最符合其偏好、受众和内容的预设。将名称与 STYLE_PRESETS 中的条目对应起来（适当时可补充“参见 slug X 的生成样例 *.html”），让选择有据可依，而非停留在抽象层面。

以此映射为起点：

风格偏好	推荐预设
为我推荐	根据用途 + 受众 + 内容进行推断，然后推荐 2-4 个最合适的选择
简洁 / 专业	Bold Signal、Electric Studio、Swiss Modern
大胆 / 实验性	Creative Voltage、Neon Cyber、Split Pastel
编辑感 / 温暖	Dark Botanical、Vintage Editorial、Paper & Ink
技术感 / 极简	Swiss Modern、Terminal Green、Notebook Tabs
我已经知道预设	跳过推荐说明，直接进入预设选择

简要说明推荐理由，例如受众契合度、活力水平、品牌调性或内容密度。

如果用户在 Phase 1 已选择 “我已经知道预设”，则跳过步骤 2.1，直接进入预设选择器。 </style_preference_first>

<style_path> 步骤 2.1：选择风格路径

询问用户想如何选择（标题：“风格”）：

• “从推荐中选择”（推荐）— 直接从建议的预设中选择（仍应尽可能展示预设缩略图或简短的视觉提示）
• “给我看看选项” — 生成 3 个单页 HTML 预览（步骤 2.3），在确定预设前缩小选择范围
• “我知道自己想要什么” — 从 STYLE_PRESETS.md 的完整预设列表中选择

如果用户直接给出预设名称： 与 STYLE_PRESETS 核对后，进入 Phase 3。如果用户在 Phase 1 选择“由你决定”： 默认路径 = 推荐，并在生成前提供预览。 </style_path>

<mood_selection> 步骤 2.2：情绪选择（引导式探索） 询问（标题：“氛围”，可多选，最多选 2 项）： 你希望观众感受到什么？选项：

• 印象深刻／充满信心 — 专业、值得信赖
• 兴奋／精力充沛 — 创新、大胆
• 平静／专注 — 清晰、深思熟虑
• 深受启发／感动 — 情感充沛、令人难忘

根据用户的风格偏好和推荐的预设系列来引导此问题。如果偏好已经明确决定了方向，请让预览保持在相近的风格范围内，而不是分散到毫不相关的美学风格。 </mood_selection>

<style_previews> 步骤 2.3：生成 3 个风格预览

根据氛围和之前的风格偏好，生成 3 个风格各异的单页 HTML 预览，展示字体、颜色、动画和整体美学风格。阅读 STYLE_PRESETS.md，了解可用预设及其规格。

氛围	建议预设
印象深刻／充满信心	Bold Signal、Electric Studio、Dark Botanical
兴奋／精力充沛	Creative Voltage、Neon Cyber、Split Pastel
平静／专注	Notebook Tabs、Paper & Ink、Swiss Modern
深受启发／感动	Dark Botanical、Vintage Editorial、Pastel Geometry

将预览保存到项目本地的临时文件夹中（例如 .claude-design-slide-previews/ 或 .design/slide-previews/），文件名为 style-a.html、style-b.html、style-c.html。每个预览都应是自包含的，约 50–100 行，并展示一张带动画的标题幻灯片。

如果可行，请在默认浏览器中打开每个预览：macOS open path/to/file.html；Linux xdg-open path/to/file.html；Windows start path\to\file.html。

如果可行，至少让 3 个预览中的 2 个属于推荐的预设系列，以便用户先看到相关的变化，再看到风格迥异的选项。 </style_previews>

<user_picks> 步骤 2.4：用户选择

询问（标题：“风格”）： 你更喜欢哪个风格预览？选项：风格 A：[名称]／风格 B：[名称]／风格 C：[名称]／混合元素

如果选择“混合元素”，请询问具体想混合哪些元素。 </user_picks> </phase_2_style_discovery>

<phase_3_generate_presentation> 阶段 3：生成演示文稿

使用阶段 1 的内容（文本，或文本 + 精选图片）以及阶段 2 的风格，生成完整演示文稿。

如果用户提供了图片，幻灯片大纲已在步骤 1.2 中纳入这些图片。如果没有图片，CSS 生成的视觉效果（渐变、形状、图案）也能增添视觉趣味——这是一条完全受支持的一等路径。

生成前，请阅读以下支持文件：

• STYLE_PRESETS.md — 所选预设的权威视觉规范（布局、标志性元素、字体、颜色）——与父级 frontend-slides 中的作用相同
• editor-runtime.md — DOM 契约（data-slide-object、data-oid、编辑层）、历史类型、吸附规则、生成器检查清单
• examples/editable-deck-reference.html — 复制演示文稿运行时（编辑器 + 侧边栏 + 历史记录 + 持久化模式）；不要将其中的幻灯片标记视为唯一允许的布局
• html-template.md — HTML 架构和集成说明
• viewport-base.css — 必需的 CSS（完整包含）
• animation-patterns.md — 所选氛围的动画参考
• 对于移植的预设，如果本地存在 beautiful-html-templates/templates/{source_slug}/template.html 和 template.json，也请阅读；将 STYLE_PRESETS.md 用作索引，但以上游模板作为详细的设计规范。 </phase_3_generate_presentation> 关键要求：
• 生成单个独立的 HTML 文件，所有 CSS/JS 均内联
• 所有创作的图像和视频默认都必须以 data: URL 嵌入 HTML；assets/ 路径仅可用作生成前的临时提取输入，绝不能用作交付媒体的 src 值。
• 在 <style> 块中包含 viewport-base.css 的完整内容
• 预设保真度： 对所选样式，按照 STYLE_PRESETS.md 实现 布局 和 标志性元素。不同幻灯片和不同预设之间应采用不同的结构；避免所有美学风格都使用单一重复的标题幻灯片原型（父级技能并非如此）。
• 移植预设保真度： 对于 34 个移植的预设，保留上游模板 DOM/CSS/类名，并使创作内容可通过插槽编辑。优先采用锁定的原生布局 + 可编辑的 data-edit-slot 内容，而不是让每个原生元素都可拖动。
• 每张幻灯片 section.slide 都必须有稳定的 id；可移动内容应放在 .slide-edit-layer 中，并使用 [data-slide-object][data-oid]，详见 editor-runtime.md
• 幻灯片列表： 胶片条克隆幻灯片时，绝不能使用全局 querySelectorAll('section.slide')；只能使用套件包装器下的幻灯片（例如 .slides-offset + :scope > section.slide）。参见 html-template.md §回归防护。
• 移动设备适配： 如果第 1 阶段选择了手机支持，则在 <html> 上设置 data-mobile-adaptation="enabled"，并为套件界面、侧边栏和幻灯片对象添加纵向 + 横向媒体规则。如果未选择，则设置 data-mobile-adaptation="desktop-default"，以便验证时区分明确选择了桌面优先与遗漏决策。
• 嵌入可编辑的套件运行时（来自参考示例）：SlideDeck、对象编辑器（选择 / 拖动 / 吸附 / RTE 工具栏）、SlideSidebar、HistoryStack、保存/导出
• 字体（见下方 §字体与可移植性）： 对于拉丁文字的展示文本/正文，优先选择有特色的 Fontshare 或 Google Fonts，而非通用系统字体。对于 CJK（中文/日文/韩文）文本，使用经过筛选的系统 CJK 字体栈——完整的 CJK 网页字体体积可达数 MB，会破坏单文件/自包含的承诺，因此这里选择合适的原生字体栈才是正确做法，而不是“AI 垃圾”。绝不要仅仅为了避免链接，而让拉丁文字正文使用裸的 Arial/Inter/系统默认字体。
• 添加详细注释，解释每个部分
• 每个部分都需要清晰的 /* === SECTION NAME === */ 注释块

<fonts_portability> 字体与可移植性（有意识地兑现自包含承诺）

导出的文件必须保持为单文件、自包含——不包含外部字体链接（见第 5 阶段）。这会限制字体选择；请勿忽视：

• 拉丁文展示/正文： 鼓励使用一款有特色的 Fontshare/Google 字体来体现个性。但单纯的 <link rel="stylesheet" href="https://fonts..."> 会让导出依赖网络——离线打开时字体会静默回退。二选一：
  1. 内联自托管——将拉丁文 Web 字体以 base64 @font-face src: url(data:font/woff2;base64,...) 的形式嵌入，使其随文件一起分发（保真度最佳，文件更大），或
  2. 分层回退——为实时/编辑体验链接 Web 字体，但搭配一套同类别、强健的系统字体栈，使离线导出能够优雅降级，而不是退回到裸 Arial。 导出清理器会剥离遗留的外部字体 <link>，因此未内联的 Web 字体必定会在交付文件中回退——当保真度重要时请选择 (1)。
• CJK（中文 / 日本語 / 한국어）： 不要追求 CJK Web 字体——完整覆盖需要数兆字节，无法内联进单文件幻灯片。请使用精选的原生 CJK 字体栈，例如 "PingFang SC","Hiragino Sans GB","Microsoft YaHei","Source Han Sans SC","Noto Sans CJK SC",sans-serif。 对 CJK 而言这是正确且可移植的选择——并非质量上的妥协。CJK 幻灯片中的拉丁字形仍可通过字体栈中更靠前的字体族使用 Web 字体。
• 中英混排幻灯片： 将拉丁文展示字体放在最前，然后是 CJK 字体栈，这样标题能体现个性，而 CJK 正文以干净的原生字体渲染："Clash Display","PingFang SC",...。 </fonts_portability> </phase_3_generate_presentation>

<phase_4_ppt_conversion> 阶段 4：PPT / PDF 转换

转换 PowerPoint（.pptx）或 PDF（.pdf）文件时：

1. 提取内容
   • PPTX： python3 scripts/extract-pptx.py <input.pptx> <output_dir>（如需要请安装 python-pptx：pip install python-pptx）
   • PDF： python3 scripts/extract-pdf.py <input.pdf> <output_dir>（如需要请安装 PyMuPDF：pip install pymupdf）。可选：--raster-if-empty 会在某页没有可提取文本且没有嵌入图片时将该页渲染为 PNG（例如类扫描页仍需单独 OCR；此标志仅捕获该页的位图）。
   • 两种写入器都会输出相同的中间产物：extracted-slides.json + assets/（每张幻灯片/每页一条记录；PDF 没有演讲者备注——使用 notes: ""）。
2. 与用户确认——展示提取出的幻灯片/页面标题、内容摘要和图片数量
3. 阶段 1（补齐缺口）——提取提供内容，但对于文件未确定的事项，你仍需明确答案：风格方向（或预设/委托），完全可编辑还是只读，语言环境，合并/拆分幻灯片时的长度意图，以及提取资源上的图片处理方式。仅针对缺失项做一次归组的追问。
4. 阶段 2——风格探索（预览 / 预设选择）；参见本技能文件中的 阶段 2：风格探索
5. 生成 HTML——转换为所选风格，保留所有文本、图片（来自 assets/）、幻灯片顺序；PPTX： 演讲者备注以 HTML 注释形式保留。PDF： 源文件中没有备注——仅在用户另行提供时才省略或留下注释占位符。

PDF 注意事项： 文本阅读顺序以及“标题还是正文”的判断是启发式的；布局不像 PPTX 那样是对象级的。纯图片 PDF 需要 --raster-if-empty 或外部 OCR 才能得到可用文本。 </phase_4_ppt_conversion> </quick_start>

<success_criteria> 阶段 5：交付

1. 清理 — 如果临时幻灯片预览文件夹存在，请将其删除（参见第 2 阶段）
2. 快速冒烟测试 — 交付前：打开文件一次；确认在约 1280×720 的视口下，幻灯片内无需滚动；如果选择支持移动设备，也要检查竖屏约 390×844 和横屏约 844×390 的显示效果；在编辑模式下，打开 Pages，重新排列一张幻灯片，Copy 一张幻灯片，添加 +New Page，然后刷新 — 不得出现重复的幻灯片或对象 ID（回归保护）；Export HTML 应能打开并独立运行
3. 打开 — 在默认浏览器中启动：macOS open [filename].html；Linux xdg-open [filename].html；Windows start [filename].html
4. 总结 — 告知用户：
   • 文件位置、样式名称、幻灯片数量
   • 导航：方向键、空格键、滚动/滚轮（编辑模式开启时禁用滚轮）、点击导航圆点
   • 演示工具：将鼠标悬停在左上角，即可显示 Laser 和 Fullscreen。Laser 会显示一个跟随指针的激光点（已按设计移除拖尾效果 — 不会创建拖尾节点）；按 Esc 可将其关闭，进入编辑模式时也会自动关闭。Fullscreen 使用浏览器全屏 API。
   • 编辑模式：按 E 进入编辑模式。将鼠标悬停在左上角，即可显示 Edit、Pages，以及（编辑期间显示的）Undo / Redo / Done；指针离开后，控件会在约 400 毫秒后隐藏。Done（同一组控件中）可退出编辑模式 — Edit 按钮的标签仍为 Edit。按 Esc 会先取消文本焦点，然后在未于文本框中输入时退出编辑模式
   • Pages 侧边栏可用于查看缩略图、重新排序（拖动行）、将鼠标悬停在缩略图上并点击 Copy 以复制该页面、删除幻灯片，以及使用 Export HTML 旁边的 +New Page，在当前幻灯片之后插入与样式匹配的空白页面
   • 对象：拖动 ⠿ 可移动对象；将鼠标悬停在对象上的 ×，或使用 Delete/Backspace 可将其删除（多选确认提示为英文）；拖动选中对象的角部调整大小控件可更改宽度/高度（文本会重新排版）；按住 Ctrl 并点击可多选（macOS：按 Control 键）
   • **添加元素：**Add element（编辑模式下位于左上角，与 Edit/Pages 同组）会打开菜单，包含 Text、Image（本地文件、粘贴或占位符）、Video（本地文件 + 控件）；添加的媒体会以内嵌数据 URL 的形式嵌入，因此导出的演示文稿可作为单个文件携带
   • 吸附：对齐到幻灯片中心和其他对象 — 不会吸附到幻灯片外边缘
   • **文本：**点击文本即可输入；浮动工具栏：B/I，以及 Font · Scale · Px 抽屉（点击可展开卡片，查看字体系列、缩放级别、像素预设 + 自定义选项）；按 Ctrl+Z / Ctrl+Y 或 Ctrl+Shift+Z；在 macOS 上未于 contenteditable 中输入时，按 Cmd+Z / Cmd+Y / Cmd+Shift+Z
   • 保存（编辑时位于左上角、Edit / Pages 旁边的 #btnSave — 同样通过悬停显示），或按 Ctrl+S / Cmd+S，会将浏览器草稿保存到 localStorage，并在浏览器支持 File System Access 时写入便携式 HTML 文件；否则会下载更新后的 HTML 备用文件。Export HTML 仍位于 Pages 侧边栏中，必须将当前演示文稿状态和媒体嵌入导出的文件，同时去除临时编辑状态。导出的文件便于移植、是单个独立文件（不含外部字体链接），且无拖尾效果 — 它包含最新编辑内容，并保留 Laser/Fullscreen 功能，但绝不会嵌入激活状态的 Laser。
   • 自定义方法：幻灯片主题 :root 变量、用于编辑界面的 --deck-chrome-*（参见 STYLE_PRESETS.md §Deck chrome tokens）、字体（将拉丁 Web 字体以内联 base64 @font-face 或分层系统字体栈的形式嵌入，并使用原生 CJK 字体栈 — 参见第 3 阶段 §Fonts & portability；导出文件保持自包含，不含外部字体链接）、.reveal 动画；添加对象时确保 data-oid 唯一 </success_criteria>

<supporting_files> 支持文件

文件	用途	阅读时机
editor-runtime.md	DOM 契约、撤销类型、吸附规则、生成器检查清单	第 3 阶段（代码生成前）
examples/editable-deck-reference.html	可运行的参考示例：完整运行时包含在一个文件中	第 3 阶段（复制/调整 JS/CSS）
STYLE_PRESETS.md	46 种精心挑选的视觉预设，包含颜色、字体和标志性元素	第 2 阶段（样式选择）
viewport-base.css	必需的响应式 CSS——复制到每份演示文稿中	第 3 阶段（生成）
html-template.md	HTML 结构、与可编辑运行时的集成	第 3 阶段（生成）
animation-patterns.md	CSS/JS 动画代码片段及效果与感受指南	第 3 阶段（生成）
scripts/extract-pptx.py	用于提取 PPT 内容的 Python 脚本	第 4 阶段（PPTX）
scripts/extract-pdf.py	用于提取 PDF 页面内容的 Python 脚本（与 PPTX 使用相同的 JSON 结构）	第 4 阶段（PDF）
README.md	双语扩展概览、对比表、故障排除	可选（用户/维护者）