市面上大多数 AI 生成 PPT 的工具，往往是“每页生成一张全屏大图片”贴在幻灯片里——看起来好看，但文字无法双击修改、图形无法拖动调��，稍微放大还会模糊失真。

ppt-master 是一个为 AI Coding Agent（如 Claude Code / Qwen Code / Codex）设计的技能插件。它的核心价值在于：根据你的文档自动排版，并生成“每个文字都能双击修改、每个图表和形状都能自由拖动调色”的原生完全可编辑 PPTX 演示文稿。

一、怎么用？端到端用户体验

日常使用该技能制作 PPT 的协作流程非常自然：

  1. 技能触发（支持显式指定与自动识别）：

    • 显式主动调用：通过斜杠命令（如 /ppt-master <文档路径>）或变量符号（如 $ppt-master）显式指定加载该技能；
    • 隐式自动识别：直接输入日常自然语言（如：“帮我把这份技术文档做成 10 页精美 PPT”），AI 自动匹配并挂载 ppt-master。

  2. 自动提炼与排版：AI 自动解析源文档、设计大纲，并在本地生成每一页的矢量排版。

  3. 本地 Web 预览、批注提交与通知修图：

    • AI 在后台启动本地预览网页（http://127.0.0.1:5050），供用户在浏览器中查阅渲染效果；
    • 用户在网页中点击不满意元素输入修改意见，并点击 「提交批注」 将修改意见持久化写入磁盘；
    • 用户回到终端对 AI 说：“已提交批注，请按批注修改”，AI 调用 check_annotations.py 精准重绘被标记的局部元素。

  4. 导出与二次编辑：满意后，AI 在本地自动输出最终的 .pptx 文件。用 Office 或 WPS 打开即可自由二次编辑所有内容。

同类生态对比

Skill 标识生态与特点适用场景
anthropics/skills@pptx官方轻量版，纯脚本生成基础形状与文本适合快速产出简单结构 PPT
hugohe3/ppt-master社区全能版，支持网页可视化批注与原生 DrawingML 深度排版适合高质量、复杂图文排版的深度演示文稿
claude-office-skills/skills@ppt-visual社区视觉版，偏插图与海报风格适合偏艺术视觉的展示场景

二、深入底层机理：为什么它能做到“双击改字”？

架构中转设计（SVG 到 DrawingML）

PowerPoint 底层使用的是微软专有的 DrawingML 矢量图形标记语言。但 DrawingML 语法极其繁琐冗长，如果让大模型直接手写 XML，极易出现语法错乱导致文件损坏。

ppt-master 采用了一种聪明的两阶段中转架构：

源文档 → [AI负责排版创意] → SVG矢量代码 → [Python脚本精准翻译] → DrawingML (PPTX)
  • 阶段一（AI 发挥排版能力）：大模型天生擅长编写标准 SVG 矢量代码，负责各页面的视觉构图、色彩搭配和文字布局；
  • 阶段二（脚本保证格式确定性）：本地 Python 脚本（svg_to_pptx.py）将 SVG 中的 <text>、<rect>、<path> 等标签一对一精准翻译为 PowerPoint 底层的 DrawingML 形状与文本框节点。

三、安全审计与 API 依赖分析

1. 安全审计结论

  • 网络隔离：内置的预览 Web 服务仅监听本地回环地址 127.0.0.1:5050，无任何遥测、埋点或数据外发；
  • 执行安全：全库无任意 eval() / exec()，subprocess 仅调用内部固定工具链；
  • 文件与密钥：读写严格限制在项目目录；无硬编码 Key，按层级加载 .env。
  • 定性：安全，无后门。

2. 零外部 API 依赖与离线手动降级

核心生成流程完全不依赖任何外部商业 API：

环节是否依赖外部 API？实现机制
文档解析与格式转换❌ 不需要纯本地 Python 库（PyMuPDF、docx 等）
SVG 排版与 PPTX 导出❌ 不需要本地 AI 对话生成 SVG + 本地 python-pptx 转换
浏览器本地预览与批注❌ 不需要本地 Flask (127.0.0.1:5050) + check_annotations.py
AI 配图 / 图片搜索 / 语音⚠️ 可选依赖支持 14+ 图像后端，未配置时自动降级

离线手动降级机制（Offline Manual Mode）： 即使未配置任何图像 API Key，系统也不会报错卡死，而是自动将配图标记为 Needs-Manual 并在页面中生成带提示词的虚线占位框，PPTX 导出流程照常进行。

四、安装踩坑与依赖解耦实录

  1. 执行 npx skills add 安装超时导致脚本缺失：

    • 原因：该 Skill 仓库体积较大（包含约 99MB 的 SVG 图标与模板），安装超时��致只下载了外层文档，scripts/ 脚本目录为空；
    • 解决：从完整克隆仓库中通过 rsync 补齐 scripts/（105 个 .py 脚本）与 templates/。

  2. PEP 668 拦截全局 pip 安装（externally-managed-environment）：

    • 背景：现代 Linux 默认启用 PEP 668，禁止直接向系统 Python 写入第三方包以保护系统级工具栈；
    • 解决：避免使用危险的 --break-system-packages，改用 uv 创建专用的独立虚拟环境进行隔离：
      uv venv ~/.ppt-master/venv
uv pip install -r requirements.txt --python ~/.ppt-master/venv/bin/python

  3. pycairo / svglib 依赖剔除：

    • 分析：svglib（依赖系统级 libcairo2-dev）仅作为旧版 Office 兼容模式下的 SVG 转 PNG 备用后备，核心 DrawingML 转换完全不需要；
    • 解决：从依赖清单中剔除 svglib / reportlab / rlpycairo，其余 88 个核心依赖包全部安装成功。