PPTX工具包Skill 用法详解

PPTX工具包Skill：用程序化方式创建、编辑与分析 PowerPoint 演示文稿

一句话定位：PPTX工具包Skill（英文名 pptx，技能ID 13068）是一个面向 .pptx 文件的演示文稿工具包，让 AI 能够以程序化方式创建、编辑幻灯片、布局、内容、演讲者笔记与评论。
三条主线：读取与分析（文本提取、原始 XML 访问）、从零创建（html2pptx 工作流）、模板复用与编辑（缩略图网格 + 库存提取 + 批量替换）。
可视化闭环：内置缩略图网格与「幻灯片转图片」校验流程，生成后可以自己检查文本截断、重叠、对比度等版面问题并迭代修正。
增强能力：可联动 scientific-schematics 技能，用自然语言描述即可生成出版物质量的科学示意图，补足纯文字幻灯片的表达短板。
适合谁用：需要批量产出汇报材料、把模板标准化、或把演示文稿生产接入自动化流水线的开发者、数据分析师、咨询与运营团队。

1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？

基本信息

项目	内容
技能中文名	PPTX工具包Skill
技能英文名	pptx
技能ID	13068
授权方式	专有许可，LICENSE.txt 包含完整条款

它解决什么问题

.pptx 本质上是一个包含 XML 文件和各类资源的 ZIP 归档。直接用肉眼或普通文本工具去改，几乎不可能；而只靠「让模型生成一段描述」又落不了地。这个技能把三件事打通了：

能读懂：把演示文稿转成 Markdown 提取文本，或解包后读取原始 XML，拿到演讲者笔记、评论、布局、动画、主题配色与字体。
能造出来：通过 HTML 描述版面、再转换为 PowerPoint 的 html2pptx 工作流，从零生成结构准确的演示文稿。
能改得动：基于模板复制、重排幻灯片，再按「库存清单」批量替换文字，保留原有格式。

一键安装的思路与步骤

需要说明的是：技能的具体安装命令与入口取决于你所使用的 AI 客户端或技能市场（以官方说明为准），此处给出通用路径与详情中明确列出的依赖准备。

确认运行环境：需要一个支持 Skill 机制、可执行脚本的 AI 客户端或 Agent 运行环境；同时本机需具备 Python 与 Node.js 环境，因为技能内部大量调用 python 脚本与 npm 库。
安装技能本体：在技能市场/技能目录中搜索英文名 pptx 或技能ID 13068，点击安装并启用；若平台提供命令行安装方式，按平台文档执行（以官方说明为准）。

补齐依赖项（技能详情中明确列出的必需依赖，应已安装）：

pip install "markitdown[pptx]"          # 文本提取
npm install -g pptxgenjs                # 通过 html2pptx 创建演示文稿
npm install -g playwright               # HTML 渲染
npm install -g react-icons react react-dom  # 图标
npm install -g sharp                    # SVG 栅格化与图像处理
sudo apt-get install libreoffice        # PPTX 转 PDF
sudo apt-get install poppler-utils      # pdftoppm 转图片
pip install defusedxml                  # 安全 XML 解析

验证是否生效：任选一个已有的 .pptx 文件，让 AI 执行 python -m markitdown 文件路径.pptx，若能正常输出 Markdown 文本内容，说明技能与依赖均已就绪；也可以直接要求它「用 pptx 技能生成一份 3 页的产品介绍幻灯片」，观察是否产出可打开的文件。
注意许可条款：该技能为专有授权，商用或分发前请阅读 LICENSE.txt 中的完整条款。

2. 该技能的主要功能和特点

文本提取与快速阅读：通过 markitdown 把演示文稿一键转为 Markdown，适合快速掌握内容大纲、做内容审计或喂给模型做二次加工。
原始 XML 深度访问：解包后可直接读取 ppt/presentation.xml、ppt/slides/slide{N}.xml、ppt/notesSlides/notesSlide{N}.xml、ppt/comments/modernComment_*.xml、ppt/slideLayouts/、ppt/slideMasters/、ppt/theme/、ppt/media/，覆盖评论、演讲者笔记、动画、设计元素等「普通工具改不动」的部分。
版式与配色逆向分析：当需要「照着某个示例设计做」时，可先读 ppt/theme/theme1.xml 中的颜色方案与字体方案，再采样 slide1.xml 中的实际字体与颜色，最后用 grep 在全量 XML 中检索颜色与字体引用——这是把「感觉像」变成「参数化复刻」的关键。
html2pptx 从零创建：用 HTML 描述每页版面（如 16:9 为 720pt × 405pt），再用 scripts/html2pptx.js 转换为 PowerPoint，图表与表格通过 PptxGenJS API 填入占位区域。
设计方法论内建：技能内含一整套设计原则——只用网络安全字体（Arial、Helvetica、Georgia、Courier New 等）、通过字号/字重/颜色建立层级、强调强对比与一致性；还提供 18 组可直接参考的调色板，以及几何图案、边框处理、排版处理、图表样式、布局创新、背景处理等视觉细节选项。
模板复用流水线：thumbnail.py 生成缩略图网格 → 人工/模型视觉分析生成模板库存 → rearrange.py 复制与重排幻灯片 → inventory.py 导出形状与段落属性 → replace.py 批量替换文本并保留格式。
视觉自检机制：thumbnail.py 出缩略图网格，或先 soffice --headless --convert-to pdf 再 pdftoppm -jpeg -r 150 转成逐页图片，用来排查文本截断、文本重叠、定位越界、对比度不足。
安全阀设计：validate.py 在每次 XML 编辑后校验结构，replace.py 会拦截「引用了不存在的形状/幻灯片」以及「替换后文本溢出更严重」两类高风险操作。
科学示意图增强：可调用 scientific-schematics 技能，用自然语言描述即可生成图文示意：
```
python scripts/generate_schematic.py "你的图表描述" -o figures/output.png
```
生成结果会自动迭代评审，并考虑可访问性（色盲友好、高对比度）。

和普通工具比强在哪：普通做法要么纯手工点鼠标（无法批量、无法版本化），要么只用某个代码库硬拼坐标（缺乏设计约束与视觉校验）。这个技能的价值在于把「内容理解—设计决策—代码生成—视觉验证—格式保留」串成了闭环。

3. 如何使用该技能？

技能提供四条典型路线，可单独使用也可组合。

路线 A：读取与分析现有演示文稿

提取文本：
```
python -m markitdown 文件路径.pptx
```
输出为该演示文稿的 Markdown 文本，可直接用于摘要、翻译或大纲复用。
需要更细粒度信息时解包：
```
python ooxml/scripts/unpack.py <office_file> <output_dir>
```
注：unpack.py 位于 skills/pptx/ooxml/scripts/unpack.py；若路径不存在，用 find . -name "unpack.py" 定位。
在输出目录中检索目标内容，例如查看某页的演讲者笔记或评论 XML。

路线 B：从零创建新演示文稿（无模板）

先陈述设计思路：技能要求「在编写代码前，说明基于内容的设计方法」——主题是什么、面向什么行业与受众、选哪套 3-5 色的协调配色。
为每页写 HTML：尺寸按 16:9 设为 720pt × 405pt；所有文字必须放在 <p>、<h1>-<h6>、<ul>、<ol> 中；需要放图表/表格的区域加 class="placeholder"（渲染为灰色背景）。渐变与图标先用 Sharp 栅格化为 PNG 再引用。
注意布局禁忌：含图表或表格的页面优先用「全宽标题 + 双列（如 40%/60%）」或「整页放图表」，切勿在单列中把图表堆在文字下方。
执行转换脚本：编写 JS 文件，调用 html2pptx() 处理每个 HTML，用 PptxGenJS API 往占位区加图表与表格，最后 pptx.writeFile() 保存。
视觉验证并迭代：
```
python scripts/thumbnail.py output.pptx workspace/thumbnails --cols 4
```
逐张检查是否截断、重叠、越界、对比度不足；有问题就改 HTML 的边距/间距/颜色后重新生成。
按需补充示意图：对工作流程图、架构图、内容组织图等，用 generate_schematic.py 生成并放入 figures/。

路线 C：基于模板创建（推荐用于企业汇报）

提取模板文本与缩略图：

python -m markitdown template.pptx > template-content.md
python scripts/thumbnail.py template.pptx

生成 template-inventory.md，逐张列出幻灯片索引（0 索引）与用途。
写 outline.md，并给出 template_mapping，例如：
```
template_mapping = [0, 34, 34, 50, 54]
```
同一索引可出现多次以复制该版式；切忌「2 个内容点硬塞进 3 列版式」。

重排幻灯片：

python scripts/rearrange.py template.pptx working.pptx 0,34,34,50,52

导出文本库存：
```
python scripts/inventory.py working.pptx text-inventory.json
```
库存会标注每个形状的占位符类型、位置尺寸、段落文本、项目符号、字号、颜色等（默认值不输出）。

编写 replacement-text.json，只引用库存中真实存在的形状，并保留原段落属性。示例：

{
  "slide-0": {
    "shape-0": {
      "paragraphs": [
        { "text": "2025 年度业务回顾", "alignment": "CENTER", "bold": true },
        { "text": "核心结论", "bold": true },
        { "text": "营收同比增长 32%（不含项目符号）", "bullet": true, "level": 0 }
      ]
    }
  }
}

注意：未在 JSON 中列出 paragraphs 的形状会被自动清空文本；bullet: true 时不要自己写「•、-、*」。

应用替换：
```
python scripts/replace.py working.pptx replacement-text.json output.pptx
```
若报错，会一次性列出所有无效形状或溢出恶化情况，按提示修正即可。

路线 D：编辑现有演示文稿（原始 XML）

先完整阅读 ooxml.md（约 500 行），不要设置行数范围限制。
解包：python ooxml/scripts/unpack.py <office_file> <output_dir>
编辑 ppt/slides/slide{N}.xml 等目标文件。
每次编辑后立即校验：python ooxml/scripts/validate.py <dir> --original <file>
打包：python ooxml/scripts/pack.py <input_directory> <office_file>

4. 同类型竞品对比分析

方案名称	定位	核心功能	安装/使用门槛	适用场景	优势与不足
PPTX工具包Skill（pptx）	面向 AI 的演示文稿全流程技能包	文本提取、原始 XML 读写、html2pptx 从零创建、模板库存与批量替换、缩略图视觉校验、科学示意图联动	需支持 Skill 的 AI 环境 + Python/Node 依赖（markitdown、pptxgenjs、playwright、sharp、LibreOffice、Poppler 等）	批量汇报材料、模板标准化、演示文稿自动化流水线	优势：打通「理解—设计—生成—校验—保格式」闭环，设计与校验规则内建；不足：依赖较多，首次环境配置成本高于单一代码库
python-pptx	Python 编程库	创建/修改幻灯片、形状、文本、图片、表格	`pip` 安装即可，需自行编写脚本	后端脚本化生成、数据驱动报表	优势：纯 Python、生态成熟、可控性强；不足：不提供设计规范与视觉校验，版式精度需手工调坐标，改模板格式易失真
PptxGenJS	JavaScript 编程库	在 Node/浏览器中生成幻灯片、图表、表格	`npm` 安装，需写 JS	Web 端导出、前端集成生成	优势：本技能 html2pptx 的底层依赖之一，图表能力顺手；不足：同样缺设计约束与版面自检，复杂排版需大量试验
AI 演示生成类在线工具（如对话式生成 PPT 的服务）	SaaS 产品	输入主题自动产出整套幻灯片	注册即用，零代码	快速出草稿、临时分享	优势：上手最快、门槛最低；不足：模板与格式可控性弱，难以嵌入企业既有模板与自动化流水线，细节调整受限

选型建议：只做一次性草稿，用在线生成类工具最快；需要嵌入系统批量产出，用代码库更轻；既要批量、又要贴合企业模板、还要能自检版面质量，PPTX工具包Skill 更合适。

5. 该技能的典型应用场景与实际体验情况

场景一：咨询/战略岗的月度汇报流水线 痛点：每季度几十份汇报，模板固定但内容要重填，手工复制粘贴极易错位。用法：走路线 C——缩略图网格读懂模板 → inventory.py 拿到形状清单 → 只写 replacement-text.json → replace.py 一次性出稿。体验：上手难度中等（需理解 0 索引与形状命名），但一旦跑通，单份材料从「半小时排版」压缩到「分钟级生成 + 几分钟复核」。注意事项：库存没列出的形状会被自动清空，第一次务必在副本上试跑。

场景二：数据分析师把分析结果变成可讲的幻灯片 痛点：图表在 Notion/HTML 里好看，搬进 PPT 就变形。用法：走路线 B——用 HTML 描述版面、占位区留给图表，双列布局让「文字 + 图表」各占其位，再用 PptxGenJS 填图。体验：效果明显好于手工拼贴，尤其是双列布局对图表可读性的提升。注意事项：一定不要垂直堆叠图表在文字下方，也不要自造字体，只用网络安全字体列表中的字体。

场景三：内容团队照着品牌示例复刻视觉风格 痛点：「按这个设计做」通常意味着反复调色号、试字体。用法：先读 theme1.xml 的颜色方案与字体方案，采样 slide1.xml 的实际字体与颜色，再用 grep 全量核对。体验：配色与字体的还原度显著提高，且结论是可复用的参数而非感觉。注意事项：示例若使用非网络安全字体，需提前替换为等价的可用字体。

场景四：需要精确改动某一页的演讲者笔记与评论 痛点：常规工具无法批量写入备注或读取历史评论。用法：走路线 D，解包后直接编辑 notesSlide{N}.xml 与 modernComment_*.xml，每次修改后 validate.py 校验，最后 pack.py 打包。体验：能力强但门槛最高，属于「有明确结构诉求时才动」的手段。注意事项：务必遵守「编辑一次、校验一次」的节奏，否则错误会累积到打包阶段才暴露。

6. 该技能能为用户带来的价值

效率提升的方向明确：把「读内容—定设计—出稿—查版面」这条链路自动化，重复性的排版劳动被脚本替代，人力集中在内容判断上。模板替换路线里，替换脚本还内置溢出与形状校验，减少了来回返工。
门槛降低：不会画版式也能做出规范幻灯片——技能直接给出了字体白名单、18 组配色、布局禁忌（如「切勿垂直堆叠图表」）与版面自检方法，相当于把设计规范前置到生成环节。
质量可控、可复用：缩略图网格 + 转图片校验让「好看」变成可检查项（截断、重叠、越界、对比度），模板库存与替换 JSON 本身也是可版本化管理的资产。
格式保真：基于模板替换而非重新排版，最大限度保留企业既有母版、主题与样式，避免「生成一次、样式全毁」。
长期价值：演示文稿生产变成可编程、可审计、可批量复现的流水线，可与数据源、报表系统、CI 流程对接，形成稳定的内容交付能力。

7. 常见问题 FAQ

Q1：怎么安装这个技能？需要准备什么？ 在支持 Skill 的 AI 客户端或技能市场中搜索英文名 pptx 或技能ID 13068 启用，具体安装命令与入口以官方说明为准。安装后必须补齐依赖（markitdown、pptxgenjs、playwright、react-icons、sharp、LibreOffice、Poppler、defusedxml），否则涉及提取文本、生成幻灯片、转图片的步骤会失败。验证方式：对一个已有 .pptx 执行 python -m markitdown 文件路径.pptx，能输出 Markdown 即生效。

Q2：这个技能收费吗？可以商用吗？ 技能详情标注为「专有」授权，完整条款见 LICENSE.txt。是否收费、可否商用、可否二次分发，都需以该许可文件与官方说明为准，建议在正式投入使用前先阅读。

Q3：它和 python-pptx、PptxGenJS 这类库有什么本质区别？ 库只提供「操作文件的 API」，怎么排版、配色怎么选、生成后怎么检查全靠你自己。这个技能在库之上补了三层：设计规范（字体白名单、配色方案、布局禁忌）、工作流（从零创建 / 模板复用 / XML 编辑三条路径），以及视觉自检（缩略图网格、转图片排查）。它更像是「方法论 + 脚本 + 校验」的组合。

Q4：我没有编程基础，能直接用吗？ 能，但建议从模板复用路线开始：你只需要说清楚想用哪份模板、每页要写什么内容，剩下的缩略图分析、库存提取、替换执行由 AI 驱动脚本完成。真正需要你参与的是内容判断与最后的视觉复核。

Q5：生成后版面错乱怎么办？ 按技能内置的排查流程走：先 python scripts/thumbnail.py output.pptx ... --cols 4 生成缩略图网格，重点看四类问题——文本截断、文本重叠、内容太靠边界、对比度不足；定位到具体幻灯片后，回到 HTML 调整边距/间距/颜色再重新生成。若是模板替换路线，留意 replace.py 报出的「溢出恶化」提示，缩短对应形状的文案即可。