/slides

name: slides
license: MIT
metadata:
  version: "1.5.16"
  homepage: https://github.com/cat-xierluo/legal-skills
  author: 杨卫薪律师（微信ywxlaw）
description: 幻灯片全流程创作工具。本技能应在需要从文稿或主题生成精美幻灯片、将 HTML 转换为可编辑 PPTX/PDF、从现有课件提取风格、或围绕主题做结构化研究时使用。不要用于纯文档排版（用 md2word）或图片处理（用 imagemagick）。

slides — 幻灯片全流程创作工具

从主题研究到最终交付的一体化幻灯片创作工具：主题研究 → 风格选择 → AI 生成 HTML → 转换可编辑 PPTX / PDF。支持从现有幻灯片中提取可复用的设计风格，构建个人风格库。

核心能力

• **主题研究**：输入主题和受众，自动产出结构化研究报告（`research.md`）和分页大纲（`slides_outline.json`）
• **可编辑 PPTX**：文字保留为可编辑文本框（非截图），位置、字号、颜色精确还原
• **混合式动态背景**：HTML 保留 WebGL / ASCII / canvas 动效；导出 PPTX 时只冻结背景层，前景文字、卡片、线条与图片继续逐项重建为原生对象
• **高保真 PDF**：基于 Chromium 渲染，以浏览器渲染为基础，交付前逐页核对
• **风格提取**：从现有 HTML 幻灯片提取配色、字体、布局等风格参数，保存为可复用的 JSON 风格文件
• **风格库**：内置 38 个预设风格（法律黑金、极简编辑白、咨询蓝、深度报道、客观网格等），支持用户自行提取和扩展
• **设计系统**：内置 CSS 设计语言（排版刻度、间距系统、组件模式、视觉层级规则），12 个完整 HTML 模板文件可直接 clone 替换内容
• **预检验证**：转换前用 Playwright 检查 slide 容器、尺寸、溢出、渐变/inset 阴影、裸 `div` 文本、远程/base64 图片、文字背景/边框等风险
• **兼容任意 HTML**：自动处理视口相对单位（100vh、clamp()、vw）、flexbox、grid 布局
• **动画系统**：浏览器模式支持入场动画（fadeSlideUp/Left/Right/Scale）、延迟级联（d1-d6）、页面转场策略（cascade/hero/quote/directional），PPTX 导出时自动降级
• **多页检测**：自动识别 `.slide` / `section` 容器，单文件多页一键转换
• **通用可分发**：不内置任何个人信息；讲者身份、联系方式、头像与二维码来自本地配置，未配置时按匿名默认生成，开箱即用
• **本地转换**：转换引擎不需要云端 API；HTML 中的远程字体、图片或脚本仍可能联网，处理私有材料时应使用本地资源并核对输入来源。

输入/输出

输入

• **HTML 幻灯片文件**（必需）：包含 `.slide` 或 `section` 容器的 HTML 文件
• **输出格式**（可选）：`--format pptx|pdf|both`；显式参数优先，否则按输出文件的 `.pptx` / `.pdf` 后缀选择，没有可识别后缀时默认 PPTX。
• **布局比例**（可选）：`--layout 16:9|4:3`，默认 16:9
• **风格参数**（可选）：`--extract-style` 提取风格，`--save 名称` 保存到风格库

输出

• **PPTX 文件**：可编辑 PowerPoint（文字保留为文本框）
• **PDF 文件**：基于 Chromium 渲染的高保真 PDF
• **风格 JSON**：`--extract-style` 时输出结构化风格参数

技术架构

HTML 文件 → Playwright 渲染（固定视口）
    → 动态背景层单独冻结为静态 PNG
    → getBoundingClientRect() / getComputedStyle() 提取前景位置与样式
    → Codex Presentations Runtime：Artifact Tool 逐项重建 + finalizer
    → 本地 CLI 回退：PptxGenJS 逐项重建
    → PDF：Chromium 高保真渲染

风格提取 → 遍历 DOM 元素收集配色/字体/布局
    → 聚类去重 → 结构化 JSON → 风格库

本地配置（可选）

技能**不内置任何个人信息**。没有配置时按匿名默认生成——课件只有本次内容，没有讲者姓名、联系方式、头像、二维码或空白介绍页。

需要个性化时，用本地配置提供讲者身份、联系方式、品牌与展示开关：

# 引导模式：打印需要收集的字段清单（Agent 逐项询问后回填）
node scripts/init-profile.js

# 非交互写入（默认 ~/.config/slides/profile.local.json）
node scripts/init-profile.js --name "张三" --title 律师 --organization "某某律师事务所" \
  --wechat-qr ~/assets/wx.png --show-wechat-qr --style 商务权威

# 校验（只报字段是否已填与路径状态，不打印资料值）
node scripts/check-profile.js

配置在**技能目录之外**，技能升级/重装不覆盖。一次运行只加载一份配置，解析顺序：`--config` / `SLIDES_PROFILE` → 课件项目 `.slides/profile.json` → 技能目录 `config/profile.local.json` → `~/.config/slides/profile.local.json` → 匿名默认。相对路径相对于被选配置文件所在目录解析；显式路径错误或 JSON 损坏直接报错，不回退到他人资料。

公私区分的总约定：**Git 跟踪的 = 可发布通用内容；被 `.gitignore` 忽略的 = 使用者私有**（`config/profile.local.json`、`config/local/`、`assets/local/` 等）。本人旧资料原件放在 `config/local/`（恢复来源，运行时不读取）。

**生成 HTML 时**读取同一份配置：

node scripts/load-profile.js --json       # 完整配置（供生成流程消费）
node scripts/load-profile.js --footer     # 仅页脚文本
node scripts/load-profile.js --assets     # 已启用素材的解析路径

• 身份字段留空即省略该元素，不虚构。介绍页由 `presentation.intro_pages` 决定，收尾形态由 `presentation.closing_mode` 决定。
• `show_profile` / `show_footprints` / `show_wechat_qr` / `show_public_account_qr` 关闭时**不读取**对应图片与来源文件，页面上也不留占位框。
• 二维码是明确要求展示的承诺：启用而缺图片按校验错误处理，不得用旧码或假码顶替。
• 头像 / 二维码 / 字体等私有素材本地创作时直接引用配置路径；**发给他人的课件必须另做资源打包**（复制进课件资源目录、改相对引用并核移动后可打开）。
• 转换时导出元数据（PPTX 作者）与个人风格保存目录都读同一份配置；未配置身份时回退到工具名与个人风格目录。

字段定义与迁移说明见 [本地配置](references/configuration.md)；空白模板见 [config/profile.example.json](config/profile.example.json)。

完整创作工作流

① 需求澄清      ② 研究/大纲      ③ 风格+版式       ④ 生成 HTML       ⑤ 预检       ⑥ 转换+QA
受众/场景/格式 → research.md → 风格库/版式家族 → 本地 HTML 文件 → validate → PPTX/PDF
页数/证据密度     outline.json    templates/playbook    固定视口/语义标签   strict     打开复核

**标准流程**： 1. **需求澄清**：先读本地配置（`node scripts/load-profile.js`）确定讲者身份、页脚与展示开关；未配置即匿名生成，不补位任何个人信息。再确认受众、场景、页数、交付格式（PPTX/PDF/both）、是否需要后续编辑、证据密度和视觉语气；缺失信息标记为“待补充”。 2. **研究与大纲**：用户只有主题时，先产出 `research.md` + `slides_outline.json`（参考 `references/research/`）；用户已有文稿时，先拆成分页目标。 3. **风格与版式选择**：默认风格取配置的 `brand.style`（未配置则由场景决定）；从风格库选择预设或提取旧课件风格；再依据 `references/layout-theme-playbook.md` 选择版式家族，使用 `references/templates/` 下的完整 HTML 模板文件（12 个页面类型，共享 `_base.css` 设计系统）。 4. **生成 HTML**：clone `references/templates/` 中对应的模板文件，替换占位内容，切换 `:root` 主题变量。遵守 `_base.css` 的设计系统：语义标签、本地图片、固定视口。动态背景统一标记 `data-ppt-background`，讲者备注写在 slide 的 `data-note` 或 `[data-speaker-notes]` 中。 5. **预检验证**：执行 `cd scripts && npm run validate -- ../example.html --strict`；正式文件替换为目标 HTML 路径。先修复 errors，再处理 warnings。 6. **转换输出**：执行 `node convert.js 新内容.html -o 输出 --format both --background-mode auto`，或按需输出 PPTX/PDF。Codex 环境若提供 Presentations Runtime，优先按 `references/native-pptx-rebuild.md` 用 Artifact Tool 重建并通过 finalizer；本地 CLI 则用内置 PptxGenJS 转换器。 7. **最终 QA**：浏览器预览、PPTX 打开、PDF 打开三处复核：页面尺寸、文字裁切、图片缺失、PDF 文字是否可选、PPTX 前景是否可逐项编辑、动态背景是否已在 PPTX 中静态保留、讲者备注是否写入。

**常用参考**：

• 版式与主题：`references/layout-theme-playbook.md`
• 完整 HTML 模板：`references/templates/`（12 个页面类型 + `_base.css` 设计系统 + `README.md` 索引）
• PPTX/PDF 稳定性：`references/pptx-guide.md`
• 混合式原生重建：`references/native-pptx-rebuild.md`
• 风格参考：`references/style-reference.md`
• 本地配置（身份/素材/偏好/初始化/迁移）：`references/configuration.md`
• 中文课件排版与去冗余：`references/cn-deck-polish.md`（§1–23：不用斜体 / 页眉脚极简 / 封面分节去冗余 / 去出处标注 / 照片比例 / 内联色防隐形 / 计数同步 / 介绍页按配置拆页 / 收尾按配置定形态 / 招牌背景可见性 / 深浅搭配 / 翻页导航交互 / 素材按本地创作与对外交付两种策略 / §14 视口 overflow 三层陷阱 / §15–19 流程总览分步 / 并列卡密度 / Skill 命名精确 / 专有名词统一 / 跨页字号统一 / §20–22 组件复用先读 CSS / 720p 预算与 DOM 几何验证 / 页码全量重编（两处计数器按页分组同号）+ 排版基准附录 / §23 竖向引擎衬底与 slide 同族）——生成与审计中文 deck 前过一遍

主题研究模块

当用户只有主题想法，尚无可用讲稿和幻灯片大纲时，使用内置的研究框架：

**输入**：

• `topic`：研究主题
• `audience`：受众（律师团队/企业法务/公开分享等）
• `target_pages`：目标页数（建议 8-12）
• `tone`：表达风格（专业严谨/前瞻创新/培训导向等）

**输出**：

• `research.md`：结构化研究报告（含核心结论、证据、风险与边界）
• `slides_outline.json`：分页大纲（每页包含标题、摘要、布局类型、要点、演讲者备注）

**研究资源**：

• 研究框架：`references/research/research_framework.md`
• 报告模板：`references/research/research_report_template.md`
• 大纲 Schema：`references