ppt-html-preview · 单页PPT HTML预览系统

<span style="display:inline-block;background:linear-gradient(135deg,#C41E3A,#8B0A1A);color:white;padding:6px 16px;border-radius:20px;font-size:13px;font-weight:600;">秋叶PPT出品</span>

用途

将一段文案自动转化为：
- 1280×720 HTML 预览页（16:9，浏览器打开直接看清整页，无需缩放）
- 左右切页预览（深色背景，页面居中，四周留空。导航点+鼠标/滚轮/键盘翻页，一页一页切换，不出现两页同时显示，无滚动条）
- 全屏播放（浏览器原生fullscreen API，16:9等比居中放大，与F11效果一致）
- 文案控容至 500字/页±50 + 视觉填充 ≥ 80%

⚠️ 强制前置规则（用户反复强调，违反会被批评）

规则A：每次生成新PPT必须先加载本skill

不允许凭记忆或经验直接写HTML。必须执行 skill_view(name='ppt-html-preview') 加载完整规范后再开始。本skill是全套规范的唯一权威来源。用户说："我后面说调用skills的那肯定是每次都按照skills的规范。"

规则A0：默认使用兽兽设计系统（2026.5.16锁定）

除非用户明确说"换个风格"，否则所有PPT必须使用兽兽设计系统，从 templates/兽兽默认骨架.html 复制完整代码再改内容。这套系统包含：

• 封面：红色渐变背景 + 四角装饰线 + 横线星星 + 白色边框标题 + 底部标签方块
• 内容页：米白纹理背景 + slide-header（红色竖线+标题+分割线）+ safe-area（intro-card + content-card + summary-bar）
• 字体：Noto Serif SC（标题/红色）+ Noto Sans SC（正文）
• 配色：秋叶红 #C41E3A + 黑白灰
• 全屏：CSS伪类 #viewer:fullscreen + JS fullscreenchange 监听

使用步骤：
1. skill_view(name='ppt-html-preview', file_path='templates/兽兽默认骨架.html') 加载模板
2. 复制全部内容做为基础HTML
3. 替换占位符 {{xxx}} 为实际文案
4. 按页数复制/删除slide结构
5. 调整内容、字号、布局，但不动CSS类名和骨架结构

📎 标准设计系统锚定：references/兽兽设计系统骨架.md

规则A1：用户提供参考设计文件时，必须完整复刻其设计系统（2026.5.16新增）

当用户发送一个HTML文件作为"参考效果"时：

1. 第一步：用 read_file 或 execute_code 读取该文件的完整源码
2. 第二步：逐行理解其设计系统——CSS类名体系、背景纹理、装饰元素、字号体系、配色、HTML骨架结构、JS实现方式、导航控件位置
3. 第三步：直接复制参考文件的 <style> 块、HTML骨架（<div id="viewer"> → <div id="stage"> → slide结构的层级关系）、JS脚本。不要自己重新写一套类似的
4. 第四步：只替换内容文案和页面标题，不动骨架
5. 第五步：如果文件中没有封面，按 references/兽兽设计系统骨架.md 中的标准封面样式（红色渐变+四角装饰线+横线星星+白色边框标题+底部标签）做封面

核心原则：用户给参考文件是让我"照抄"设计，不是让我"参照风格重新设计"。先打开看、再复制、再改内容。交付前对比参考文件的HTML骨架结构确保一致。

📎 标准设计系统锚定文件：skill_view(name='ppt-html-preview', file_path='references/兽兽设计系统骨架.md')

规则A2：先出文案，后做设计（2026.5.18新增，不可跳过）

每次生成PPT，第一步必须是输出纯文案让用户确认，确认通过后才能生成HTML。 禁止跳过文案确认直接出代码。

文案输出格式：

P[N]、[页面标题]

[引言段落——一段完整的论点，不是短语]

1. [板块名]——[一句话说明这个板块解决什么问题]
- [要点关键词]：[完整说明，包含具体场景或数据]
- [要点关键词]：[完整说明，包含具体场景或数据]
- [要点关键词]：[完整说明，包含具体场景或数据]

2. [板块名]——[一句话说明]
- ...

总结：[完整论断，不是口号]

硬性约束：
- 字数：500字±50，用 re.findall(r'[\u4e00-\u9fff]', text) 统计纯汉字
- 每个要点必须是一句完整的、有信息量的陈述（25-35字），不写关键词+短语
- 引言必须是完整段落（40-60字），不是一句话
- 总结必须是完整论断（20-30字），不写半句话

流程：
1. 输出文案 → 附汉字数统计
2. 等用户确认（"文案OK"或修改意见）
3. 用户确认后，再按规则B生成HTML

此规则优先于规则B——即使使用默认模板跳过设计师方案，也必须先过文案确认这一关。

规则B：设计师方案提交流程（2026.5.16更新 — 默认模板时跳过）

默认场景（使用兽兽设计系统模板）： 当使用 templates/兽兽默认骨架.html 做PPT时，跳过设计师方案环节，直接出内容+代码一步到位。模板的封面结构、slide-header体系、卡片样式都已锁定，唯一变化的是文案布局（几栏、几个要点、有无图表等）。用户已确认这套设计，不需要每次都看图再确认。

例外场景（新风格/非常规布局）： 仅在以下情况下输出设计师方案并等用户确认：
- 用户明确说"换个风格"或要求自定义设计
- 单页需要3+种不同卡片类型混合（如表格+图表+三栏卡片同页）
- 需要集成ECharts/图表/复杂grid布局
- 有外部参考文件需要复刻（此时按规则A1执行）

默认流程（标准模式）（仅限非默认场景）：先输出设计师方案再动手。
1. 分析文案的内容逻辑结构
2. 输出设计师方案
3. 等用户确认方案后再生成HTML
4. 如果用户不认可方案，重新出方案再等确认

用户原话（标准模式依据）：
- "每做一页之前都要有一个设计方案来确认，这个是务必每次都要做的。"
- "你给我看一下设计方案，我看到了设计方案再去做设计。"
- 选择题选项必须竖排编号1234，清楚可读，不要横排或乱排。

规则C：每次修改HTML前先备份

shutil.copy2(OUT, OUT.replace('.html', f'_备份_{ts}.html')) 带时间戳。
用户确认OK后用 xxx_版本_YYYYMMDD_HHMMSS.html 命名版本锚点。

规则D：每个新生成的PPT默认必须包含完整播放控件（用户反复确认，是常量要求，不是可选功能）

播放控件不是可选功能，不允许在生成时跳过或询问用户是否需要。必须在生成骨架时一并写入，不要等用户追问才加。
- 左侧导航圆点：竖排，当前页红色#C41E3A，其他半透明白rgba(255,255,255,0.25)
- 右下角页码：格式 1 / N，半透明白色
- 右下角竖排两个图标按钮（hover显示文字说明）：
- 上：⏮ 跳到首页+全屏，hover显示"从头播放"
- 下：▶ 当前页全屏播放，hover显示"当前页播放"
- 全屏播放规范：
- viewer: position:fixed;top:0;left:0;width:100vw;height:100vh;display:flex;align-items:center;justify-content:center;background:#000;overflow:hidden
- stage: 1280x720, transform:scale(window.innerWidth/1280) -> 宽度拉满，高度按16:9等比缩放，上下超出部分黑色背景露出=上下黑边
- 全屏时隐藏导航点、页码、播放按钮
- ESC退出或监听fullscreenchange事件恢复预览状态（恢复导航、页码、播放按钮，执行center()）
- 全屏下翻页：点击stage任意位置->下一页，滚轮上下翻页，键盘左右箭头翻页

规则E：所有内容必须在16：9画布内，不能超出（overflow红线）

safe-area可用高度 = 720 - 80(标题) - 24(底) - 36(顶) = 580px
这是铁律——底部summary-bar/任何元素都不能超出这个范围。
如果设计好内容后发现超出580px，按以下优先级处理：
1. 删减内容：去掉非核心要点，每层要点从4-5条压到2-3条
2. 提炼文案：缩短每句话，去掉修饰语
3. 缩小字号：正文20px→18px、注释18px→16px
4. 缩小间距：gap从14px→10px、padding从18px→14px、margin-bottom从8px→5px
5. 改布局：三栏改双栏、双栏改纵向阶梯

禁止：跳过溢出检查直接生成，等用户发现后再补救。必须在交付前自己确认。
改之前列清单：这个改动会影响哪些部分？退出逻辑、翻页兼容、导航隐藏、缩放恢复、ESC监听等关联功能是否都考虑到了？一次性告诉AI一起改，不要分多次改。
改完后验证：'nav-dots' in content、'</script>' in content、JS大括号匹配、slide数量正确、文件大小无明显缩小。
不要用：全局re.sub、content.split().join()、find().replace()匹配JS字符串——这些方法历史记录中反复导致文件被破坏。

⚠️ 用户画像（关键约束，指导所有交互）

用户不懂代码，也不应该需要懂。 用户描述的是使用体验问题（"全屏按不了"、"页面间距叠在一起"、"导出灰蒙蒙"），不是代码问题。不要问用户"具体是哪个函数报错？"、"控制台有什么输出？"——用户不知道也不需要知道。

正确的协作模式：
- 用户只负责：描述问题现象、确认最终效果
- 我负责：定位代码问题、修改、自动验证修改后的完整页面
- 用户不需要看任何代码。所有结论用中文描述。

自检原则：修改代码后必须由我自己验证，不能让用户"试一下看坏了没有"。

工作流程（3D决策：定义-设计-交付）

第一阶段：定义（用户确认前）

步骤1：确认用户需求
- 主题、页数、受众
- 通过3-5个选择性问题确认设计方向

步骤2：设计师角色评估（必须调用）
每页生成前先分析内容的逻辑结构，不套模板。输出格式：

=== 设计师方案：P[N] ===

【内容逻辑分析】因果/对比/步骤/问答/数据/总结 → 决定布局

【布局结构】上中下/左中右/三栏/双栏/纵向阶梯

【视觉细节】
- 用什么元素：intro-card / content-card / summary-bar / footer-note / mini-card
- 是否需要底部红色横幅（summary-bar）：如果不加视觉密度仍≥80%，就不加
- 段落是否要分段+序号标记：如果一篇有3-5个并列点，用 ①~④ 标记拆分
- 字号基准：正文约定后用下表
- 红白灰分布、尺寸比例、编号/图标/分隔线

设计师角色的核心职责不止是选布局，更是决定什么东西该有、什么东西不该有：
- 不是每页都需要红色总结横幅（summary-bar）。双栏对比页本身内容饱满时去掉横幅。
- 不是每页都需要底部脚注（footer-note）。只有引用外部数据或标注来源时才加。
- 不是每页都需要动画装饰。内容本身提供了视觉密度就足够。
- 判断标准：去掉这个元素后页面视觉密度是否仍≥80%？是就不加。
- 红色横幅只在以下场景使用：总结收尾页、关键结论强调页、封面之后的开场引言。

第二阶段：设计（定稿后执行）

步骤3：配置规格

⚠️ 字号规格（确认后固定，不动）：
- 正文段落：18px（用户要求+2时 → 20px）。正文不得使用15px及更小字号。
- 卡片说明/注释：17px（介于正文和脚注之间，不用15px）。用户反复强调：不存在15号字。
- 卡片标题：24px（+2→26px）
- 页面标题：40px（+2→42px）
- 极细标注/脚注：14px（+2→16px）
- 序号徽章：10-14px（卡片内小徽章）
- 封面：112/52/24px

⚠️ 字号变动的安全操作：用户要求全局+2时，不要用 re.sub(r'font-size:(\d+)px', ...) 做全局正则替换——会破坏JS和文件结构。正确做法：只改 <style> 块内的CSS class字号常量，然后逐页改inline style。

配色：秋叶红 #C41E3A + 黑白灰
- 正文文字必须用黑色：color:rgba(26,26,26,0.85) 或 color:#333 或 color:rgba(26,26,26,0.78)（正文标准色）
- 副文/注释用灰色：color:rgba(26,26,26,0.65)（比之前0.55更深，用户确认0.65正好）
- 禁止正文用浅灰或浅色：正文段落不得使用 rgba(26,26,26,0.55) 及更浅的灰色，否则在1280画布上不醒目。灰色只用于箭头要点后面的说明文字或脚注。

画布：1280×720，safe-area padding: 36px 48px 24px 48px
可用高度 = 720 - 80(标题) - 24(底) - 36(顶) = 580px

溢出检查：确保内容不超过580px高度。20px正文 + 4条li ≈ 140px，8条li ≈ 260px，加上intro-card(~60px) + footer-note(~30px) + padding和gap(~60px)，总高度估算：
- 双栏4条li：~140 + 80 + 60 + 60 = ~340px ✅
- 双栏6条li + summary-bar：~260 + 80 + 60 + 56 = ~456px ✅（刚好）
- 双栏8条li + summary-bar：~340 + 80 + 60 + 56 = ~536px ❌ 接近溢出
- 三栏每栏4条li + summary-bar：超出 ❌

步骤4：多要点内容的排版手法
当卡片内有多个并列要点时，用 分段+序号标记 + 图标：

<div style="display:flex;flex-direction:column;gap:10px">
  <div style="display:flex;gap:10px;align-items:flex-start">
    <span style="font-size:22px;color:#C41E3A;font-weight:700;flex-shrink:0;width:22px;text-align:center">①</span>
    <p style="font-size:20px;line-height:1.7;margin:0">每个要点独立成行</p>
  </div>
</div>

• 左侧序号红色醒目，右侧文字正常
• 卡片padding增加到20px
• 必要时卡片标题旁加SVG图标（叉号/勾号）
• 不要堆积段落：超过3行的段落必须拆分为要点列表

步骤4b：视觉突出手法
用户确认的视觉优先级（按这个顺序选择，不要拍脑袋）：
1. 红色关键词色块：引言或卡片中需要强调的短语 → <span style="background:rgba(196,30,58,0.09);color:#C41E3A;font-weight:700;padding:1px 6px;border-radius:3px">关键词</span>。比纯 color 更醒目。不要用 color 纯色，用背景色块。
2. 红色边框卡片：三栏中需要突出的一栏 → border:2px solid rgba(196,30,58,0.12)。但如果所有卡片同等重要，就都不加边框，不要无理由给某一栏加边框。
3. 每页底部结论必须用summary-bar（红色渐变横幅）：不要用 footer-note 放结论文字。footer-note 只用于引用外部数据来源或标注。结论性的话必须用 summary-bar（红底白字，宽度拉满对齐上方卡片，display:flex;justify-content:center;text-align:center）。
4. 卡片内要点箭头：并列要点用 → 箭头 + color:rgba(26,26,26,0.55) 灰色文字，不要堆积段落。超过2行的内容必须拆分为要点列表。
5. 白色底卡片为主：大部分卡片保持白色底。红色边框或色块只用在最需要突出的信息上。

步骤5：生成HTML（逐页，每次只做一页）

⚠️ 从1栏模板展开为N栏的规范写法（2026.5.16新增pitfall）
模板 兽兽默认骨架.html 的content区只包含1个卡片占位。当你需要3栏时，不要在替换占位符之后再拆分字符串——这会导致{{卡片标题}}、{{要点文字}}等占位符被替换一次后无法复用。

正确做法（在Python代码中）：

# 1. 先不替换卡片占位符，直接用字符串操作
with open(template_path) as f:
    base = f.read()
base = base.replace('{{主标题}}', 'xxx')  # 先做非卡片替换

# 2. 找到卡片区块的精确边界
card_start = base.find('<!-- 1-3栏 content-card')
# 计算卡片区块长度（从注释到闭合标签）
card_block = base[card_start:card_block_end]

# 3. 对每个卡片单独做替换，再拼接
card1_html = card_block.replace('{{卡片标题}}', '标题1').replace(...)
card2_html = card_block.replace('{{卡片标题}}', '标题2').replace(...)
card3_html = card_block.replace('{{卡片标题}}', '标题3').replace(...)

# 4. 用三张卡片替换模板中的单卡片区块
base = base.replace(card_block, card1_html + card2_html + card3_html)

禁止：body.split('{{卡片标题}}')、re.sub做卡片展开、替换完{{xxx}}后再找结构边界。

你的修改属于哪个场景？
├── 场景A：改某页内容 → 定位safe-area → content[:safe]+new+content[next_title:]
├── 场景B：改JS函数 → 花括号匹配定位 → 只替换函数体
├── 场景C：全局字号+2 → 只改CSS类 + 逐页inline
├── 场景D：追加/删除整页 → 在stage结束前/后插入/截取
└── **不要用**：全局re.sub、content.split().join()、find().replace()匹配JS字符串

步骤6：自检（每次写完必检查）
1. len(content) > 30000（没有被破坏缩小）
2. 'nav-dots' in content（导航存在）
3. '</script>' in content（脚本存在）
4. len(re.findall(r'<div class="slide[ >]', content)) >= 7（slide数量）
5. 所有标题不重复
6. JS大括号匹配
7. 内容无溢出：safe-area内所有内容（含底部summary-bar）必须在580px可用高度内。估算方法：intro-card(~60px) + 每层card高度 + gap + padding + summary-bar(~48px)。如果超过启动规则F的溢出处理流程。

步骤7：自动浏览器质检（新增——用户反复强调的关键环节）

用户不懂代码，修改HTML之后 必须自己打开浏览器验证，不要让用户说"你帮我看看好了没有"——用户应该只用说"可以了"或"这里还有问题"。

质检清单（打开本地HTML文件后逐项确认）：

[ ] 页面不白屏、控制台无报错
[ ] 向前/向后点击翻页正常
[ ] 滚轮翻页正常
[ ] 键盘左右箭头翻页正常
[ ] 全屏进入正常（双击或点击播放按钮）
[ ] 全屏后ESC退出正常，导航和按钮恢复
[ ] 导航圆点数量 = 幻灯片数量，当前页高亮正确
[ ] "从头播放"按钮正常
[ ] "当前页播放"按钮正常
[ ] 文字无截断/乱码/重叠

所有项目确认通过后，再告诉用户"改好了，你试一下"。

如果任何一项不通过，自己修复后再质检，不需要找用户确认中间状态。

• D:/hermes-agent/Hermes-product/
• 不用 write_file 工具（D盘兼容性问题），用 Python open()
• 每次修改前 shutil.copy2(OUT, OUT.replace('.html', f'_备份_{ts}.html'))
• 用户确认OK后用 xxx_版本_YYYYMMDD_HHMMSS.html 命名锚点

数据获取（重要！财务/业绩类PPT的前置步骤）

⚠️ 环境诊断：本环境的网络搜索和数据抓取能力全面受限，并非个别站点的问题。

历次尝试均失败且覆盖了所有路径：
- 搜索引擎类：DuckDuckGo Lite → 超时；Startpage → 超时；Yahoo → 超时
- 金融API类：Yahoo Finance API → 429 Too Many Requests（限流）；东方财富API → 报表配置不存在
- 浏览器类：Google → 连接超时；Bing国际版 → UTF-8解码错误；Bing国内版 → 只能中文搜索
- 英文综合类：Brave Search → 编码错误；DDG → 超时

根本原因：Git Bash环境的网络栈有兼容性问题，加上API反爬/限流/地区限制，使任何自动化数据抓取或网络搜索在当前terminal中都不可靠。

决策树（不要在每条路径上浪费超过30秒）：

用户需要外部实时数据？
├── 用户手里有数字？
│   ├── 是 → 直接问用户要数字，快速开始做PPT
│   └── 否 → 尝试一次browser_navigate（仅限Yahoo Finance首页/Bing中文）
│         ├── 成功 → 手动抓取关键数据
│         └── 失败 → 直接进入"无网络"模式
└── 进入"无网络"模式后：
    ├── 方案A（首选）：问用户：'你手上有数据吗？发给我我来做'
    ├── 方案B（次选）：用训练数据中的已知公开数字（如特斯拉2024Q1=38.7万辆），标注为"参考数据"
    └── 方案C（备选）：用示意数据 + 醒目标注"模拟数据/仅供参考"

正确的协作模式：
1. 先尝试一次browser_navigate快速探测——行就行不行就拉倒
2. 不行→直接问用户"你手上有数字吗？"，不要重试3次再问
3. 用户提供数字后，我做图表呈现和美化
4. 如果用户也没数字→用训练数据中的已知公开数字做示意（标注来源说明）
5. 总时间预算：数据获取阶段不超过1分钟。超过这个时间还没拿到数据，立刻转向询问用户

ECharts 集成规范

ECharts 5.x CDN: https://cdn.jsdelivr.net/npm/echarts@5.5.0/dist/echarts.min.js

在 <head> 中引入，在 <script> 中用 DOMContentLoaded 事件初始化。

重要： 图表必须放在 slide 的 safe-area 内，高度不超过 280px。超过 280px 的高度会挤压内容区，导致溢出。

可用图表类型（详见 references/ECharts图表类型参考.md）：
- 柱状图 + 折线图组合（趋势展示）
- 饼图（占比展示）
- 横向柱状图（对比展示）

引用文件

• references/HTML文件安全修改指南.md — 修改方案选择树 + 验证清单 + 回滚操作 + 本session事故记录
• references/全屏播放实现.md — 全屏方案规范 + 宽度拉满公式 + ESC退出恢复 + 历史踩坑记录
• references/设计师布局参考.md — 布局匹配规则 + 内容分析指引
• references/汉字字数统计方法.md — 纯汉字统计方法
• references/ECharts集成模板.md — ECharts配置（CDN、初始化、配色）
• references/ECharts图表类型参考.md — 3种完整图表示例（柱+线组合/饼图/横向柱状），可直接复制使用
• references/知识库回存工作流.md — 将PPT产出/方法论/洞察回存到「兽兽的知识库」的分类式保存工作流
• references/用户环境诊断与优化指南.md — Windows环境限制、terminal不可用时的根本原因（WSL自动触发）、rg的真实可用路径、文件路径约定。每次操作前先读此文件了解环境边界
• references/多页间距.md
• references/字号偏好.md
• references/左右切页实现.md
• references/排版密度参考.md
• references/兽兽设计系统骨架.md — 用户确认满意的完整设计系统（从 痛点就是价值的第一块基石_备份_temp8.html 提炼）。每次生成新PPT时，除非用户明确要求新风格，否则基于此骨架做所有页面。包括CSS类体系、HTML骨架结构、JS全屏/翻页范式。
• references/数据看板组合布局.md — 一页内组合柱线图+饼图+表格+总结的布局模式，含尺寸规格和CSS要点（2026.5.15新增）