minimal-agent 0.8.2 → 0.10.0

package/skills/ui-design/references/export-pptx.md

@@ -0,0 +1,124 @@
+# PPTX 导出协议（三层：背景 / 前景 / 文本）
+
+本协议用于把 `ui-design` 生成的 HTML 页面或 HTML deck 导出为 `.pptx`。目标是保留 HTML/VI 模板的视觉质量，同时让**文本**与**前景元素**都可编辑。
+
+## 三层模型（核心）
+
+导出把页面拆成**三层**，各层处理方式不同：
+
+1. **背景**＝**纯背景**：页面/section 的底色、渐变、玻璃光效、装饰底纹，以及全幅**氛围背景图**（B 路线 `background-image` + scrim）。**整页截图**铺满幻灯片最底层，对应 PPT 的背景/母版。**不可编辑**（它就是底图）。
+2. **前景**＝除背景与文本外的**所有离散视觉块**：插图 `<img>`、媒体、图标、SVG、图表 `<canvas>`、卡片、色块、按钮底。每个**最外层**前景元素被**逐个截图**成独立 PNG，在 PPT 里是**独立可编辑图片对象**（可移动 / 缩放 / 替换；像素为光栅）。
+3. **文本**＝文字本身。抽取文字 + 字体 / 字号 / 颜色 / 粗细 / 对齐 + 位置，在 PPT **顶层**还原为**原生可编辑文本框**（真正可改字）。
+
+> 一句话：**背景当底图、前景每块各成一张可换的图、文字是真文本框。** 三层叠放：背景 < 前景切图 < 文本。
+
+> **分层是自动的（导出脚本 `tagLayers` 在截图前按结构判定，无需逐个标注）：**
+> - **背景**只剩：AI 氛围底图 + CSS 纯色/透明/渐变的**页/section 级基底** + scrim。
+> - **其余一切非文本**（实色/位图底的块、边框块、阴影块、圆角实色块、img/svg/canvas）只要**非全幅且够大**，都自动归**中层**、按 HTML 元素逐个切图、可在 PPT 单独拖拽/复制/删除。
+> - **一切文字**（含卡内、SVG `<text>`、未包块的散字）自动提到**顶层**可编辑框，永不烧进图。
+> 标注因此**可选**（见下）——它现在只是 override，不再是分层的前提。
+
+## 导出模式
+
+- `flat`：每页 HTML 完整截图铺满幻灯片。视觉最稳，适合正式演示和客户交付；**整页不可编辑**。
+- `hybrid`：走上面的三层模型。背景截图（不可编辑）+ 前景逐元素切图（独立可编辑图片）+ 文本原生框（可编辑）。
+- `native`：实验方向，首版禁用（脚本会报错）。
+
+默认推荐 `flat`。用户要“文字可编辑”“方便改文案/换图”时用 `hybrid`。不要承诺复杂 HTML 能 100% 转成矢量可编辑 PPT——前景是光栅切图，不是逐点矢量。
+
+## HTML 分层标注（现在**可选**——分层已自动）
+
+导出脚本 `tagLayers` 会在截图前**按结构自动分层**，所以**正常情况下什么都不用标**：正常写语义化 HTML（卡片用带底色/边框的 `div`、文字用 `h*`/`p`/`span`、图用 `img`/`svg`），自动得到「底图垫底 + 离散块逐个切中层 + 文字顶层可编辑」。
+
+标注只在你要 **override 自动判定** 时用：
+
+```html
+<section data-screen-label="01 首页">
+  <!-- 背景：页/section 级底色、渐变、scrim、AI 氛围底图——正常写即可，自动留底 -->
+  <div class="bg-aurora"></div>
+
+  <!-- 文字：正常写，自动提为顶层可编辑文本框（标 data-pptx-kind="text" 也行，等价） -->
+  <h1>中文标题</h1>
+  <p>中文说明文字</p>
+
+  <!-- 离散块：带底色/边框/阴影的块自动成中层切图；卡内文字自动提顶层、底色留在切图里 -->
+  <div class="stat-card">
+    <span class="chip">标签</span>   <!-- 药丸：底色留切图、文字自动提顶层 -->
+    <span>98%</span>
+  </div>
+  <img src="assets/photo.png" alt="产品照片" />
+</section>
+```
+
+override 字段（仅在自动判定不符预期时用）：
+
+- `data-pptx-layer="foreground"`：**强制**把某块当中层切图（自动判定漏判时兜底；显式标了一律生效）。
+- `data-pptx-export="ignore"`：让某元素**保留烧进底图、不被提取**（如嵌进图形里的艺术字、不想单独编辑的装饰）。
+- `data-pptx-kind="text"` / `data-pptx-layer="text"`：显式标文本（等价于自动，留作兼容）。
+
+**两条铁律（自动逻辑已内建，override 时仍需懂）：**
+
+1. **前景去嵌套**：只截**最外层**块——卡片成块后，卡里的图标/药丸**烘进卡片这一张切图**（不单独切，避免重影）。要图标单独成块，把它移出卡片或单独 `data-pptx-layer="foreground"` 且卡片不成块。
+2. **文字永远顶层可编辑、永不烧进图**：自动提取无需标注；带底色的 chip（药丸/标签）其**底色留在切图、文字提到顶层**（不再像过去整块当文本隐藏而丢底色）。只有 `data-pptx-export="ignore"` 的文字才保留烧进图。
+
+**两处已知边界（刻意不改，写 HTML 时绕开即可）：**
+
+- **切图按 border-box，超出的 `box-shadow` / 溢出子内容会被裁掉。** 切图取元素自身的 border-box（与记录的几何同源），
+  保证「切图尺寸 == 摆放尺寸」、绝不错位糊边；代价是落在 border-box **外**的投影/溢出物切不进来。
+  要保住投影感就把阴影做进框内（`inset` 阴影，或给容器留 padding 让阴影落在 border-box 内）。
+- **背景层只留全幅基底。** 背景 = 隐掉所有前景块 + 文本后剩下的：AI 底图 / 纯色 / 渐变 / scrim / 透明。
+  **半幅渐变带**（非全幅、带盒样式）会被当离散块切入**中层**；**极小装饰**（最小边 <24px 或面积 <2500px²）
+  留背景层烧进底图（不单独切，可接受）。要让一条渐变带留背景就把它做成**全幅**基底。
+
+## 导出 CSS
+
+`hybrid` 三层隔离靠导出脚本注入的 CSS（`data-export-mode` = background / foreground / text）。artifact 端只需保证多页 deck 的 `[hidden]` 生效：
+
+```css
+[hidden] {
+  display: none !important;
+}
+```
+
+如果 slide 自身使用 `display: grid`、`display: flex` 或 `display: block`，必须显式加入 `[hidden] { display: none !important; }`。否则会覆盖浏览器默认的 hidden 隐藏效果，导致多页 slide 同时叠在一张截图里。
+
+> 背景/前景/文本三层的可见性切换、前景逐元素 solo 隔离切图、文本隐藏，**全部由导出脚本注入的 CSS 自动完成**，artifact 作者无需再手写 `html[data-export-mode=...]` 规则（脚本会覆盖）。只要按上面标对 `foreground` / `kind="text"` 即可。
+
+## 中间产物
+
+`hybrid` 导出会在 workdir 落 3 个 HTML 中间产物供检视：`pure-background.html`（纯背景）、`pure-foreground.html`（纯前景块）、`pure-text.html`（纯文本）。它们是在**自动分层完成后**基于首个导出页生成的调试快照，均注入 `<base>` 指回原 HTML 目录、可单独打开。每页真实截图以 `slide-XX-full.png`、`slide-XX-background.png` 和 `slide-XX-fg-YY-*.png` 为准。另有 `export-manifest.json`（记缩放比例 `scale`、每块切图的 px/英寸几何、每段文本样式）与 `export-report.md`。前景切图文件名编码几何：`slide-NN-fg-KK-x{X}-y{Y}-w{W}-h{H}.png`。
+
+如果导出报告出现 `bakedText` / “截图夹带 HTML/SVG/伪元素文字”，这是阻断错误：说明某些 DOM 文本会被烧进背景或中层切图，后续又会在 PPT 顶层还原一遍，必然造成不可编辑文字和重影。必须先修 HTML 分层，或用 `data-pptx-export="ignore"` 明确表示这段文字就是插图内容、允许烧进图。
+
+## Deck 规则
+
+- 每页 slide 必须有 `data-screen-label`，编号从 `01` 开始，并包含中文标题。
+- 固定尺寸 deck 推荐按 `1920x1080` 设计，对应 PPT `10 x 5.625 inch`。
+- 导出脚本会按 `[data-screen-label]` 遍历页面；如果没有找到 slide，则把当前视口当作单页。
+- 导出时必须使用真实 `1920x1080` 画布截图，不要把浏览器预览缩放后的舞台截图进 PPT。导出脚本会强制取消 `.scaled-stage` 的 `transform: scale()`，并检查每页截图尺寸与 hash。
+- 导航控件、调试条和 Tweaks 面板应标注 `data-pptx-export="ignore"`。
+
+## 可编辑边界
+
+- **文本**（`kind="text"`）：顶层 PPT 原生文本框，**真正可改字**，还原字体 / 字号 / 颜色 / 粗细 / 对齐。
+  中文字号按 PPT 坐标体系换算：`font_pt = css_px / 1080 * 5.625 * 72`，在 `1920x1080` 到 `10 x 5.625 inch` 下约等于 `css_px * 0.375`。不要使用浏览器 96dpi 的 `css_px * 0.75`，否则导出文字会偏大、挤压（脚本已按此换算）。
+- **前景**（`layer="foreground"`，含卡片 / 色块 / 图标 / 插图 / SVG / 图表）：逐元素切图成**独立可编辑图片对象**（可移动 / 缩放 / 替换）。圆角、透明、object-fit 裁切、**border-box 内**的阴影都按网页渲染烘进 PNG（**超出 border-box 的外投影/溢出物会被裁掉**，见上「已知边界」）。注意它是**光栅图**，不是矢量逐点可编辑——任何 HTML→PPT 都做不到后者；要改内容就换这张图。
+- **背景**（不标）：玻璃、阴影、模糊、渐变光效、装饰底纹、全幅氛围背景图（B 路线）→ 整页截图垫底，不可编辑。
+- 中文字体：脚本按导出机器平台选真实存在的中文字体（win=微软雅黑 / mac=Hiragino / linux=Noto），避免缺字替换；导出后不同电脑仍可能替代字体，需在交付说明中提示。
+
+## 推荐流程
+
+1. 生成 HTML/deck 时正常写语义化结构即可——分层自动（无需逐个标注）。
+2. 仅在自动判定不符预期时用 override：`data-pptx-layer="foreground"` 强制某块为中层切图；`data-pptx-export="ignore"` 让某元素保留烧进底图。
+3. 运行 `scripts/check_ui_artifact.py --for-pptx-export <html>`，有 `ERROR` 必须先修 HTML，不得继续导出。它会拦截重复 `<head>/<body>`、裸露 CSS、坏结构和常见导出风险。
+4. 运行 `scripts/export_pptx_from_html.mjs <html> --out <output.pptx> --mode flat` 生成高保真版。导出脚本自身也会做一次静态预检；如果发现裸 CSS 或重复 body，会在启动浏览器前停止。
+5. 如需可编辑（文字 + 前景块），再运行 `--mode hybrid`，并抽查 workdir 里的 `pure-*.html` 三层中间产物。
+6. 生成后必须通过 `minimal-agent/skills/pptx/scripts/opc_check.py` 校验，避免 PowerPoint 打开提示修复。
+7. 交付时明确说明：当前 PPT 是全图不可编辑（flat），还是三层（背景底图不可编辑、前景每块为独立可编辑图片、文本为原生可编辑文本框）。
+
+## 注意事项
+
+- Playwright 负责浏览器截图；在本地 macOS 沙盒中可能需要额外权限。失败时不要悄悄降级，应提示用户安装或授权浏览器依赖。
+- `PptxGenJS` 必须用 Node 运行，不要用 Bun 生成 PPTX。
+- `python-pptx` 不作为主生成器；它可用于基础包检查或后处理，但不适合承载复杂 HTML 视觉。
+- 脚本通过不等于视觉通过。导出后仍要抽查截图、中文断行、文字重影、背景裁切和可编辑文本层。