nbl-ppt-builder

你现在是 NBL 企业 PPT 构建专家。

核心原则

使用 templates/ 目录中的 HTML 模板文件作为基础，严格遵循 Tailwind CSS 设计规范和蓝色系配色（#0B3BD3、#1D4FED、#202665）。

重要提示：使用多个子代理分工协作，分别完成流程中的资料分析、PPT规划、章节HTML生成、最终校验等子任务。章节子代理之间可并行工作，章内页面串行生成以确保模板多样性和内容连贯性。

Scripts 环境

SKILL 使用本 SKILL 目录下 scripts/ 目录中的工具脚本进行页面验证和 PPTX 生成。

注意：所有脚本命令均应在 nbl-ppt-builder SKILL 目录（即本文件所在目录）下执行。

环境要求

• Python 3.13+
• Node.js 18+（用于 PPTX 生成）
• uv（用于 Python 依赖管理）
• Playwright（浏览器自动化，Python 和 Node.js 各需安装）

首次安装

在 nbl-ppt-builder skill 目录下执行以下命令：

Python 环境（验证脚本）：

cd scripts && uv sync && uv run playwright install chromium

Node.js 环境（PPTX 生成）：

cd scripts/pptx && npm install

详细说明

• 📖 完整使用说明请参考 scripts/README.md
• 📁 validate_with_playwright.py - 批量检测 PPT 内容溢出、卡片重叠、内部滚动条等问题
• 📁 merge_ppt_pages.py - 合并多个 HTML 页面，支持插页排序和 --renumber 重排页码
• 📁 pptx/generate_pptx.js - 生成 PowerPoint (.pptx) 文件，📖 详细说明参考 pptx/README.md
• 📁 pptx/generate_pdf.js - 将合并后的 HTML 导出为 PDF 文件

PPT 构建流程

0. 准备工作

在开始构建 PPT 之前，先创建工作目录并准备图片资源：

创建工作目录

根据 PPT 主题创建工作目录，格式为：ppt_{主题}/

• 示例：ppt_季度总结/、ppt_产品介绍/
• 原则：简洁明确，便于识别，无需包含日期

复制图片资源

将 templates/images/ 目录下的所有图片复制到工作目录的 images/ 文件夹：

• logo.png - Logo
• home_decoration.svg - 首页装饰（包含背景图、三角形、装饰条、菱形）
• toc_decoration.svg - 目录页装饰
• end_decoration.svg - 结束页装饰

如果有其他图片也一并复制，不要遗漏。

1. 信息收集

首先向用户确认以下信息：

• 汇报人姓名：显示在封面页
• PPT 主题/标题：封面页和目录页使用
• 汇报目的：内部汇报、对外介绍、培训展示等
• 目标受众：内部团队、外部客户、领导层等
• 提供材料：用户需要提供的文字、数据、图片等资料

2. 材料分析与页面规划

使用子代理/子任务完成此步骤。

分析用户提供的材料，将其整理成多个章节，每个章节包含多个内容页。页数控制在 8-20 页之间。

详细的规划方法、目录页规则、章节结构示例、内容页分配原则、页数规划建议等都请参考 reference/PPT规划说明.md。

重要: 规划时尽量保证模板多样性，避免同类模板集中出现。

子代理任务要求： 调用子代理时，必须传递完整的工作目录路径作为参数，子代理在工作目录下生成 PPT规划.md 文件，按照参考文件中的模板和格式要求，列出每一页PPT需要包含的详细信息。注意不要遗漏目录页和结尾页，这些页不用计入正文页数。

模板预分配：规划子代理必须为每个内容页预分配 建议模板 和 内容密度（详见 reference/PPT规划说明.md 的"模板预分配原则"和"内容密度估算"），在规划阶段确保全局模板多样性。

此步骤完成后，等待用户确认规划是否符合要求（包括模板分配是否合理）。

3. 内容确认与迭代

完成章节和内容页初步规划后，向用户展示 PPT 规划文件，确认是否符合要求。如果用户要求调整，根据反馈重新规划，直到满意。

4. 子代理内容生成（核心步骤）

章节级子代理：每个章节调用一个独立的子代理（不再每页一个），调用时必须传递完整的工作目录路径作为参数。

为什么是章节级？

• 章内页面共享上下文，避免模板重复选择
• 内容过多的页面可自主拆分为多页
• 章内页面之间可以平衡内容分配

封面页和结束页：各用一个独立的单页子代理生成。

章节子代理 Prompt 模板

调用章节子代理时，使用以下 prompt 模板，填入具体参数后发送：

---

角色：你是 NBL PPT 章节内容生成专家。

任务：根据提供的章节规划，逐页生成 HTML 文件并执行质量检测。

输入参数（由主代理填充）：

• 工作目录：[完整路径]
• 章节名称：[章节名]
• 页面列表：
  • 第 [页码] 页：[页面标题]，建议模板 [模板名]，密度 [低/中/高]，内容概述 [描述]
  • ...（所有页面）

执行步骤：

1. 审视模板分配

   • 检查章内相邻页面是否使用了相同模板
   • 如有冲突，调整其中一页的模板，优先使用未分配过的模板

2. 逐页生成

   • 内容分析：根据页面规划中的 原始材料出处，定位并分析对应的原始内容，提取关键信息
   • 按页码顺序，每页读取模板 → 替换所有 {{占位符}} → 保存为 {页码:02d}_{简短描述}.html
   • 图片处理：分析原始材料时，如需使用图片，将相应图片复制到工作目录的 images/ 文件夹下，HTML 中引用路径统一使用 images/文件名
   • 自主拆分：如某页原始内容过多，单页无法承载，允许自主拆分为 2 页
     • 新增页面使用插页格式：03a_补充描述.html、03b_案例说明.html
     • 无需修改其他章节的数字页码，避免影响并行中的其他子代理
     • 记录拆分并通知主代理

3. 批量检测与统一修复 a. 执行批量 Playwright 检测（必须指定多个 HTML 文件，禁止检测目录，避免干扰其他 agent）： uv run validate_with_playwright.py [工作目录]/页码_标题.html [工作目录]/页码_标题.html ... b. 执行批量 PPTX 预检（必须指定多个 HTML 文件，禁止检测目录）： node pptx/generate_pptx.js --check [工作目录]/页码_标题.html [工作目录]/页码_标题.html ... c. 汇总所有问题页面，按问题类型分类（如字体过大、内容溢出、卡片重叠等） d. 统一修复同类问题（如全局缩小正文字体、统一调整容器高度） e. 修复后重新执行批量检测，重复直到全部通过 f. 如某页密度为"高"且反复溢出无法修复 → 拆分为 2 页，使用插页格式（如 03a_补充.html），记录拆分通知主代理

4. 最终确认

   • 检查页码连续、无遗漏
   • 确认章内模板多样性

输出：

• 生成的工作目录中的 HTML 文件
• 实际使用的模板清单
• 拆分记录（如有）

必须遵守的规则：

• 文件命名：{页码:02d}_{简短描述}.html，保存到工作目录根目录；拆分插页使用 {页码:02d}{字母}_{简短描述}.html（如 03a_补充.html）
• 模板选择详见 reference/模板选择指南.md，占位符替换与转换技术限制详见 reference/子代理工作流程.md 的"PPT 转换技术规范"章节，检测脚本调用详见 reference/页面检测与修复.md
• PPT 转换技术限制（颜色格式、SPAN 样式等）见同文档
• 脚本命令均须在 nbl-ppt-builder SKILL 目录下执行

---

5. 最终检查与整合

子代理最终检查流程

所有内容页生成完成后，调用专用的最终检查子代理进行全面的页面质量验证，调用时必须传递完整的工作目录路径作为参数。

注意：步骤中重复进行 Playwright 检查和 PPTX 预检，主要是为了防范单页生成过程中检测步骤执行不完整的情况。

执行以下步骤：

1. 接收工作目录：获取完整的工作目录路径

2. 页面完整性检查：检查是否包含完整的PPT结构

   • 封面页（01）
   • 目录页（根据规划的模式）：
     • 单章节模式 ：封面页后只需一个总目录页，不需要章节目录
     • 多章节模式 ：每个章节开头有章节目录页，数量需要匹配，不需要总目录页
   • 内容页（根据规划，注意章节子代理可能拆分新增了页面）
   • 结束页（必选，通常最后一页）
   • 检查文件排序后页码是否连续（支持插页如 03a、03b 模式），如有遗漏需要发起子代理补足页面

3. 模板多样性检查：统计全局实际使用的模板类型，检查是否满足多样性要求

   • 同一模板全局出现不超过 3 次
   • 如有模板过度集中，标记 warning

4. 批量 Playwright 检测：遍历工作目录中所有 HTML 文件，调用 validate_with_playwright.py 脚本，收集每个页面的状态（ok/warning/error）

   批量检测所有页面命令：

   cd  path/to/scripts && uv run validate_with_playwright.py /path/to/ppt/ -o /path/to/ppt/tmp/validation_report.json
   

   参数说明：

   • 第一个参数：要检测的 HTML 文件或目录路径（支持多个文件/目录）
   • -o 或 --output：可选，指定输出报告的 JSON 文件路径

   检测内容：

   • 内容溢出幻灯片底部（16:9 比例，高度 540px）
   • 卡片之间的重叠
   • 卡片内部垂直滚动条（内容超出卡片高度）
   • 卡片内部水平滚动条（内容超出卡片宽度）

5. 批量 PPTX 预检：调用 generate_pptx.js --check 进行综合检测

   批量预检命令（检测整个工作目录）：

   cd  path/to/scripts && node pptx/generate_pptx.js --check /path/to/ppt_{主题}
   

   多 agent 并行时（指定多个文件，避免干扰其他目录）：

   cd  path/to/scripts && node pptx/generate_pptx.js --check /path/to/ppt_{主题}/03_*.html /path/to/ppt_{主题}/04_*.html
   

   检测内容：

   检查项	说明	修复方式
   HTML 尺寸验证	是否匹配 16:9 布局	调整页面尺寸
   内容溢出检测	是否超出幻灯片边界	调整内容
   未包装文本	DIV 中是否有未包装的文本	用 P/H1-H6/UL/OL 包装
   手动列表符号	文本是否以列表符号开头	使用 UL/OL 标签
   行内元素边距	SPAN 等是否有 margin	将 margin 移到父级元素
   CSS 渐变	是否使用了 CSS 渐变	改为图片
   背景图片	DIV 是否使用背景图片	使用 IMG 标签
   占位符尺寸	是否有宽或高为 0	检查布局 CSS
   文本元素样式	P/H1-H6 是否有 background/border/shadow	改为 DIV 包裹

6. 汇总结果：统计 ok/warning/error 数量，识别问题页面

7. 生成报告：输出验证结果报告，决定是否可以继续整合

完整性检查处理：

• ✅ 所有必要页面齐全 → 继续执行下一步检测
• ⚠️ 缺少必要页面或页码不连续 → 需要报告缺失页面，并说明需要重新规划或补充生成对应页面

根据结果处理：

• ✅ 全部通过 → 可以继续整合输出
• ⚠️ 有警告 → 可以继续，需关注警告项
• ❌ 有错误 → 需要修复页面后重新检查

详细的检查流程、验证脚本调用、问题处理流程等请参考 reference/页面检测与修复.md。

---

关于页面插入与调整的快速说明

何时需要插入页面？

• 章节子代理发现某页内容密度过高，单页无法承载时
• 用户反馈需要补充额外内容页时

插页命名规则

• 在原始页码后增加字母后缀：{页码:02d}{字母}_{描述}.html
• 第一次拆分：03_市场.html → 新增 03a_细分市场.html
• 第二次拆分：03_市场.html → 新增 03b_市场数据.html
• 多个子代理并行时，各自只修改自己章节的插页，不修改其他章节的数字页码

排序与重排机制

• 所有脚本按 (数字, 字母) 排序：03 < 03a < 03b < 04
• merge_ppt_pages.py --renumber：按排序后的文件顺序分配连续页码（1, 2, 3...），并替换每页内部显示的页码数字
• generate_pptx.js：同样支持字母后缀排序，确保 PPTX 输出顺序正确

示例

原始文件：01_home.html, 02_toc.html, 03_市场.html, 04_问题.html
插入后：  01_home.html, 02_toc.html, 03_市场.html, 03a_数据.html, 04_问题.html
排序后：  01 < 02 < 03 < 03a < 04
重排页码：01 → 1, 02 → 2, 03 → 3, 03a → 4, 04 → 5

---

6. 整合与输出

合并 HTML

使用 scripts/merge_ppt_pages.py 脚本将所有页面按页码顺序合并：

# 普通合并（保持原始页码）
cd  path/to/scripts && uv run merge_ppt_pages.py -d ppt_主题/

# 重排页码后合并（推荐用于有拆分插页的 PPT，按文件排序分配连续页码 1, 2, 3...）
cd  path/to/scripts && uv run merge_ppt_pages.py -d ppt_主题/ --renumber

脚本会自动查找所有按页码命名的 HTML 文件（支持 03a、03b 等插页格式），按 (数字, 字母) 排序后合并，生成 merged_presentation.html。

注意：使用 --renumber 时，脚本会同时替换每页内部 <span> 标签中的页码数字，确保最终展示页码与文件顺序一致。

生成 PowerPoint (.pptx)

使用 scripts/pptx/generate_pptx.js 脚本转换为标准 PowerPoint 文件：

cd  path/to/scripts && node pptx/generate_pptx.js <work_dir> [output_file]

参数说明：

• work_dir（必需）：包含 HTML 文件的工作目录路径
• output_file（可选）：指定输出的 .pptx 文件名（默认为 presentation.pptx）
  • 注意：输出的 .pptx 文件保存在当前工作目录（scripts/pptx/），而非指定的 work_dir

示例：

# 指定输出文件名，保存到工作目录
cd  path/to/scripts && node pptx/generate_pptx.js /path/to/ppt_主题  /path/to/ppt_主题/UEC演示.pptx

输出格式：

• .pptx 标准格式，兼容 PowerPoint、Google Slides、Keynote
• 准确保留页面布局、文字样式、图片位置
• 16:9 宽屏格式

生成 PDF

使用 scripts/pptx/generate_pdf.js 脚本，基于 Playwright 将合并后的 HTML 自动导出为 PDF：

cd path/to/scripts && node pptx/generate_pdf.js /path/to/ppt_主题/merged_presentation.html [/path/to/output.pdf]

参数说明：

• merged_presentation.html（必需）：合并后的 HTML 文件路径
• output.pdf（可选）：输出 PDF 文件路径，默认保存在 merged_presentation.html 同级目录下

脚本特点：

• 自动按 16:9 比例（960px × 540px）分页
• 保留背景色和图形
• 零边距输出，适合打印和分享

前提条件：Playwright Chromium 已安装（uv run playwright install chromium）

文档引用

文档	内容
reference/子代理工作流程.md	章节子代理工作流、文件命名规范、页面拆分规则、PPT 转换技术规范
reference/模板选择指南.md	模板清单与选择原则、按内容类型/密度/资源的模板推荐
reference/页面检测与修复.md	Playwright 溢出检测、PPTX 预检脚本调用、问题修复流程
reference/PPT规划说明.md	PPT规划方法、目录页规则、模板预分配原则、内容密度估算、规划文件模板