PPT Master 技能使用手册

版本:6.6.0 · 作者:Hugo He · 许可:MIT 官方仓库:https://github.com/hugohe3/ppt-master 本文档基于本机已安装的技能(~/.claude/skills/ppt-master/)与实际运行结果整理。

一、这是什么

PPT Master 是一个"演示文稿工作流"技能。你在对话里说一句"把这份 PDF 做成 PPT",它就驱动 AI 在你的机器上跑完一整套流程,最终导出一个**原生可编辑的 .pptx**。

关键特点:

它能做的不止"生成":还能从参考资料里提炼可复用的品牌/风格/版式/演示模板、在保留原设计的前提下把已有 PPTX 填上新内容、给成品 deck 加原生转场/动画/旁白。

它不适合:追求像素级 1:1 复刻复杂动效、需要服务端批量并发出图、或要求完全离线无模型调用的场景。

二、安装

2.1 环境要求

2.2 三种安装方式

方式 A:Claude Code 插件市场(推荐用于 Claude Code)

仓库自带 .claude-plugin/marketplace.json,可通过插件市场安装:

# 跨 agent 的 CLI(Claude Code、Cursor、Codex 等)
npx skills add hugohe3/ppt-master

# 或在 Claude Code 内执行
/plugin marketplace add hugohe3/ppt-master
/plugin install ppt-master@ppt-master

⚠️ 注意:插件方式只拉取技能文件,不含仓库里的示例 deck。

方式 B:Git clone(推荐用于长期使用)

git clone https://github.com/hugohe3/ppt-master.git
cd ppt-master

优点:可随时 git pull 拉取最新版。

方式 C:手动安装到个人技能目录(本机采用的方式)

如果 GitHub 直连受限(国内常见),可以用 jsDelivr CDN 逐文件拉取,放进 Claude Code 的个人技能目录:

# 目标目录(Claude Code 会自动识别为技能)
~/.claude/skills/ppt-master/          # Windows: C:\Users\<你>\.claude\skills\ppt-master\

技能目录的必需结构:

ppt-master/
├── SKILL.md            # 技能入口(必需,Claude Code 靠它识别技能)
├── LICENSE
├── requirements.txt    # Python 依赖清单
├── references/         # 知识与规则文档(约 165 个文件)
├── scripts/            # Python 工具脚本(约 485 个文件)
├── templates/          # 内置资源:图标/图表/品牌/版式等(约 12450 个文件)
└── workflows/          # 工作流定义(23 个文件)

💡 完整性的重要提醒:技能启动时会执行 scripts/attribution_guard.py 做完整性校验,任何文件缺失都会直接中止技能加载。所以必须下齐全部文件(约 13004 个、81 MB),不能只挑核心文件。其中 templates/icons/(12027 个图标)占比最大。

若 GitHub 直连慢,可参考本机做法——用 jsDelivr 并发拉取:

# 单文件示例(jsDelivr 不受 GitHub API 限流)
curl -o SKILL.md \
"https://cdn.jsdelivr.net/gh/hugohe3/ppt-master@main/skills/ppt-master/SKILL.md"

2.3 安装 Python 依赖

进入技能目录安装依赖(这一步必需,否则后处理脚本跑不起来):

pip install -r requirements.txt

依赖分两类:

核心必需(SVG→PPTX 导出、模板注册):

可选功能(按需,不装则对应功能不可用):

国内加速:如果 PyPI 慢,加清华镜像

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

若 requirements.txt 因含中文注释报 UnicodeDecodeError,可先生成一份纯 ASCII 的包名清单再安装。

2.4 验证安装

跑一次技能自带的完整性校验门(返回 0 即通过):

python scripts/attribution_guard.py
echo $?      # 期望输出 0

再验证核心脚本可运行:

python scripts/svg_to_pptx.py --help

如果能看到用法说明(含 -f {ppt169,ppt43,...} 等参数),说明依赖装好了。

2.5 Windows 常见坑

1. python3 命令不存在 → Windows 上改用 python。

2. sys.prefix 异常导致 pip 不可用 → 本机遇到过 sys.prefix 为 C:、site-packages 路径拼成 C:Lib\site-packages 的情况。解决:用 python -m ensurepip --upgrade 引导 pip,并用 PYTHONPATH 显式指向正确目录,安装时加 --target:

   python -m pip install --target="C:\Lib\site-packages" -r requirements.txt
   export PYTHONPATH="C:\Lib\site-packages"# 运行脚本前设置
   

3. 控制台中文乱码 → 运行 Python 脚本前设 export PYTHONUTF8=1。

4. PATH 未勾选 → 装 Python 时务必勾选 "Add Python to PATH"。

2.6 更新

Git clone 安装的:

python3 skills/ppt-master/scripts/update_repo.py

该脚本会拉取最新版,并在 requirements.txt 变化时同步依赖。

插件/ZIP 安装的:插件重装,或下载最新 ZIP 覆盖(把旧 .env 和 projects/ 拷进新目录)后重跑 pip install -r requirements.txt。

三、实现原理

3.1 核心思路:一切皆 SVG

技能不直接写 PPTX 的 XML,而是走一条 中间层 = SVG 的路径:

源材料(PDF/DOCX/URL/图片/主题)
        ↓  转换
   Markdown / 结构化事实
        ↓  规划(设计规格)
   页面蓝图(每页内容+关系+节奏)
        ↓  逐页手写
   SVG 页面(svg_output/*.svg)   ← 唯一"可见设计"的权威来源
        ↓  导出编译
   PPTX(原生 DrawingML 对象)

为什么用 SVG 做中间层?

• SVG 是矢量、可读、可逐元素编辑的文本格式,AI 能精确控制每个形状/文字/坐标;
• 一份 SVG 同时承担三个角色:给人看的预览(浏览器直接打开)、给程序质检的对象(脚本能解析)、给导出器的输入(编译成 PPTX);
• 跨平台一致:不依赖任何 Office 组件就能生成预览。

硬规则:SVG 是页面设计的封闭边界。最终导出的幻灯片上每一个可见元素(文字、形状、图片、图表、背景)都必须存在于该页 SVG 里、或被它显式引用。模板、design_spec.md、spec_lock.md 都只是编写时的指导,绝不会在导出时"补"内容进去。

3.2 为什么产出的是"原生可编辑"PPTX

导出器(svg_to_pptx.py)会把 SVG 元素映射为 PowerPoint 的原生对象:

关键设计——元素分组:每个逻辑内容单元用带 data-pptx-bounds 的 <g id="..."> 包起来。这既让导出的对象归属清晰,也为后来的动画提供稳定的对象锚点。

flat 与 structured 两种打包模式:

• flat:所有对象都放在 Slide 本地,导出时只生成一个干净的 Master + Blank Layout。自由设计、仅品牌/风格模式走这条。
• structured:声明 Master / Layout / 占位符拓扑,把可复用的固定层提升到 Master/Layout。仅当用户传入已确认的 Layout/Deck 模板工作区,或 Quick 明确要写结构化契约时才用。

3.3 三级文件体系

技能用三层文件把"意图—锚点—实现"分离:

为什么要有"锁"这一层? 长 deck 生成时上下文会变长,容易漂移(比如第 12 页忘了主色是什么)。spec_lock.md 是一个精简的、可随时重读的锚点表——技能规定每完成 5 页就重读一次锁(P05/P10/P15…),纯粹重新锚定配色/字体/节奏,不做质检、不停顿。这让长文档也能保持视觉一致。

3.4 路由机制:三条顶级路线

技能的入口 (SKILL.md) 只做一件事:选路线。三条顶级路线,互斥:

选择逻辑是确定性的(workflows/routing.md):

"把这份 PDF/DOCX/网页 做成 PPT"        → Generate PPTX (Default)
"快速生成 / 跳过确认"                    → Generate PPTX (Quick)
"美化这个 PPTX,内容别动"                → Generate PPTX (Beautify)
"把这张图/这版设计稿还原成可编辑 PPT"     → Generate PPTX (Image to PPTX)
"用我这份 PPT 的模板填新内容,设计别动"    → Edit Native PPTX
"做一套可复用的品牌/版式模板"             → Create Template

硬规则:一旦选定路线,就只加载该路线的流程文档,不再加载其他路线的。支持文档(profiles/stages/governance)是细化当前路线用的,不是并列的第二路线。

3.5 角色分工与"技能即提示词工程"

技能内部定义了若干角色,每个角色对应一份参考文档,切换角色时技能会明确朗读:

## [Role Switch: <Role Name>]
📖 Reading role definition: references/<filename>.md
📋 Current task: <briefdescription>

这套设计的本质是:把"如何做好一份演示文稿"的专家经验,拆成结构化文档 + 强制流程,让 AI 每次都能按同一套高标准执行,而不是即兴发挥。

3.6 质量门与自校验

技能内建多个强制质检点(gates),错误会阻塞流程:

质检器检查什么?

• XML 合法性:禁止 HTML 命名实体(—)、禁止裸 &/</>;
• 结构性黑名单:<style>、class、外链 CSS、mask、<foreignObject>、textPath、@font-face、<animate*>、<script>、<iframe> 一律禁止;
• 文本溢出:每个 <g data-pptx-bounds> 里的文字超出边界 >5% 报错;
• 根组重叠:同级根组重叠超过 1px 报错;
• 重复段落:疑似被拆成多个 <text> 的段落会警告;
• 字号/颜色越界:超出 spec_lock 锚点合理范围时提示。

报告分级:blocking(阻塞)/ introduced(新增建议)/ inherited(继承自原型)/ source-import(源转换损失)。错误必须清零才能导出,警告可接受但要说明理由。

修复纪律:跑一次完整质检 → 一次读完所有问题 → 一次性合并修复 → 验证一次。绝不在单个修复之间反复质检。

四、功能总览

五、功能详解与用法

5.1 生成 PPTX(Default)

这是主流水线——你说"把这份材料做成 PPT",默认就走这里。

触发方式

请把 projects/q3-report/sources/report.pdf 做成 PPT

在对话里直接粘贴文字内容也可以。

完整流程(7 步)

源内容处理 → [事实研究] → 创建项目 → 模板候选准备
   → 阶段1确认(沟通契约+模板选择)→ [模板安装]
   → 阶段2方案 → [图片获取] → Executor 实时预览
   → 质量检查 → 后处理 → 导出

Step 1 源内容处理 — 转换各种格式:

充分性测试:只有当"不做外部研究就得编造/省略/留下无支撑的可核实主张"时,才去做研究。封闭语料(如一份完整的内部报告)不做外部检索。

Step 2 项目初始化:

python3 ${SKILL_DIR}/scripts/project_manager.py init <项目名>
python3 ${SKILL_DIR}/scripts/project_manager.py import-sources \
  <项目路径> <源文件或目录...>

项目目录形如 projects/<名称>_<YYYYMMDD>/。初始化的同时会创建 validation/workflow.log(冷审计日志——生成期间绝不读取)。

Step 3 模板候选准备 — 内部准备,不打扰你。

Step 4 策略师阶段(强制) — 这里有两个阻塞确认门:

⛔ 阻塞 — 两阶段确认

阶段 1:确认沟通契约 + 模板选择。沟通契约是六个字段:

同时确认:画布比例、自由设计 or 使用模板(模板模式可选内置库或你提供的精确路径)。

阶段 2:确认完整方案 —— 阅读模式、沟通模式(5 选 1)、视觉风格(19 选 1 + 自定义)、页数、配色、图标、字体、图片来源、生成方式等。

💡 实用提示:在这个确认环节,技能会给出推荐值。如果你只是想快速出稿,可以回答"都用推荐值"。

Step 5 图片获取(条件触发) — 当方案里有 ai / web / slice 图片需求时:

• ai:走 image_gen.py,支持 Gemini / OpenAI 兼容后端,或由宿主原生生成;
• web:走 image_search.py 检索,有视觉能力时会保存候选页供多模态审阅;
• slice:从 AI 生成的"元素图板"里切片。

Step 6 Executor 阶段 — 逐页手写 SVG。这一步会自动启动实时预览并报出 URL,你可以边生成边看。

Step 7 后处理与导出 — 严格串行三步:

# 7.1 拆分讲稿(仅当启用备注)
python3 ${SKILL_DIR}/scripts/total_md_split.py <项目路径>

# 7.2 生成自包含预览
python3 ${SKILL_DIR}/scripts/finalize_svg.py <项目路径>

# 7.3 导出原生 PPTX
python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <项目路径>
#     备注禁用时:python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <项目路径> --no-notes

产出:exports/<项目名>_<时间戳>.pptx + validation/<项目名>_<时间戳>.report.json

可选增强阶段(按需)

修订(已交付的项目)

deck 交付后要改:不重开规划,直接改对应的 SVG,然后同步改 §IX 蓝图、notes/total.md、以及所有重复该表述的页面(如目录页)。页数增删则先重排编号(文件名、页脚、目录页码、§IX、page_rhythm、animations.json 键、讲稿标题、同文档链接),再增删页。最后重跑最终质检 + 导出。

5.2 快速生成(Quick)

跳过策略师与确认,一次直出。

触发方式

快速生成一份 <主题> 的 PPT
跳过确认,直接做
直接给我 SVG 并导出

规则:页数本身从不触发或阻止 Quick。必须是"显式要快速/跳过策略/直接出"的意图。

与 Default 的差异

流程(4 步)

# §2 源与资源准备
python3 ${SKILL_DIR}/scripts/project_manager.py init <项目名> --quick-generate
python3 ${SKILL_DIR}/scripts/project_manager.py import-sources <项目路径> <源...>

§2 里也必须做的一步:排版校准(每个复用角色跑一次)

python3 ${SKILL_DIR}/scripts/text_measure.py calibrate <项目路径> --role <名称>:<字体>:<字号>

§3 直接手写 SVG — 页数 ≥7 时,P05 之后跑一次"早期门"(--stage early)。

§4 导出:

# 无锁最终质检(两个 flag 都必需)
python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <项目路径> \
  --quick-generate --canonical-authoring --stage final --json

# 导出
python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <项目路径> --quick-generate --with-notes  # 启用备注
python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <项目路径> --quick-generate --no-notes    # 禁用备注

⚠️ Quick 没有可恢复的设计记录:执行记忆只存在于当前上下文。上下文丢了就重开一次干净的 Quick,它不是 resume 协议。

5.3 美化重排(Beautify)

保留内容,1:1 重做版式。

触发方式

把这份 PPT 美化一下
重新排版这份 PPT,内容别动

必须是显式意图 + 提供了文件,技能绝不推断。

核心约束

内容冻结:每个源文字串逐字保留(不增/删/改/重排);自由度只在版式、层级、间距、节奏。

其他硬规则:

• run 级强调(源里加粗/着色的词)作为层级保留——同样的词仍然突出,只是用新配色重绘;
• 不加源里没有的页面装饰(页码、页脚、眉标);
• 不是补丁、不是填充:通过 SVG 管线重新生成一份原生 deck,绝不就地编辑源文件。它是 mirror 模板的逆操作(mirror 保版式改文字,Beautify 保文字改版式);
• 图表/表格/图片从数据重建,绝不逐字节搬运。

什么时候不该用

流程

# §3 创建项目(先读源画布比例)
python3 ${SKILL_DIR}/scripts/beautify_identity.py <源.pptx>          # 读 canvas.aspect
python3 ${SKILL_DIR}/scripts/project_manager.py init <项目名> [--format <格式>]
python3 ${SKILL_DIR}/scripts/project_manager.py import-sources <项目路径> <源.pptx>

# §4 装配清单(逐页冻结内容台账)
python3 ${SKILL_DIR}/scripts/beautify_inventory.py \
  <项目路径>/analysis/<stem>.slide_library.json \
  --images <项目路径>/images/image_manifest.json \
  -o <项目路径>/analysis/beautify_inventory.json

# §7 验证输出(逐页核对冻结字符串,缺失则退出码 1)
python3 ${SKILL_DIR}/scripts/beautify_inventory.py \
  <项目路径>/analysis/beautify_inventory.json --verify <项目路径>/exports/<输出.pptx>

有界读取(强制):装配好的完整清单是验证台账,不是写作提示。写作时只读 --summary,再按需 --page <N>,绝不批量读整个文件。

关键细节:body_size(正文字号)

这是承重项。方法:

1. 取源里最高频的 observed.sizes_pt;
2. × 4/3 换算成 px(20pt → 26.67;裸写 20 会缩小约 25%,这叫 pt-as-px 陷阱);
3. 若画布宽度与源码不同,再按比例缩放。

v1 边界(诚实说明)

支持:逐字重排、源配色/字体作为预选推荐、严格 1:1 页数、图表表格从抽取数据重生成、源图重排版。不支持:重分页、批量/多 deck 美化、逐字节搬运原图表/图片。

5.4 图片转 PPTX(Image to PPTX)

把栅格图(截图、设计稿、接触印相、扁平页面)还原为分层可编辑 PPTX。

触发方式

把这张幻灯片截图还原成可编辑的 PPT
按这张设计稿做一版 PPT

注意:作为素材的照片、插画、moodboard 不会激活此功能。仅在 Codex 上验证:它依赖 Codex 原生的参考图生成/编辑与逐层直接检查能力。

核心思路:不是"截图皮肤"

禁止 —— 截图皮肤:绝不把完整源页当作唯一的全幅图片、再在上面叠一层可编辑文字。源页是比较证据,不是隐藏底图。

正确做法是按内容族分类,重建最小可用层栈:

层栈自下而上:base(干净全画布背景)→ midground-* → subject-* → foreground-* → source-graphic-* → native-text-*。

注册组规则:同组每层都对齐同一规范页/场景 bbox;Codex 派生的成员必须从该规范源出发并保持画布、位置、缩放、姿态、光照、风格;绝不裁切注册的全画布层。

硬规则

• 仅 Quick:永远加载 quick-generate.md,即使你没说 "Quick";
• flat 输出:绝不从像素推断 Master/Layout/占位符;
• 绝不安装模板:会与规范页几何冲突;
• 与 Beautify 互斥,绝不组合。

流程关键点

# §2 归一化:规则接触印相按行优先切分
python3 ${SKILL_DIR}/scripts/slice_images.py <图板.png> --grid RxC --names ... --trim --alpha --bg <KEY_HEX> --strict-alpha

# §5 在决定层之前,先写可见事实台账
<项目路径>/analysis/reconstruction_inventory.json

硬门:有序的规范页图 roster 必须先存在;边界或顺序含糊 → 标记阻塞,绝不静默合并/丢弃/重排。一图一页——像素帧数决定 slide 数。

最终检查表(9 项证据)

页 roster、原生文字、源图形、数据图形、层注册、可见保真、诚实重建(AI 恢复的隐藏像素须标注为重建)、独立对象、参考排除(规范全页源图不得被打包进 slide media)、包质量。

5.5 编辑原生 PPTX(Edit Native PPTX)

保留现有 PPTX 的原生设计,只做填充/编辑/加旁白。

触发方式

核心机制:往返工作区

python3 skills/ppt-master/scripts/pptx_to_svg.py "<源.pptx>" \
  -o "projects/<slug>_<YYYYMMDD>" --inheritance-mode both --roundtrip

硬规则 —— 源代理是原子的:<image data-pptx-source-proxy="native-restore"> 代表不支持的原生对象(SmartArt、复杂效果、媒体帧)。留给它还原;编辑代理或其预览资产会导致导出失败。

导出证明:四个桶

python3 skills/ppt-master/scripts/svg_to_pptx.py "projects/<slug>_<YYYYMMDD>" --roundtrip

导出打印回执:

Round-trip export summary: output_pages=N passthrough=P cloned_passthrough=C patched=M rebuilt=R

纯交付任务必须 rebuilt=0 —— 纯加旁白/备注不该改动任何可见页。

增强模块

硬规则

• 绝不运行 Generate 管线:不跑 pptx_template_import.py、project_manager.py init、finalize_svg.py,绝不创建 svg_output/;
• 只编辑计划内的页:被引用的页绝不为写入而打开;
• 就地编辑、保留身份:改文字/涂色/位置,但保留你不打算改的对象上每个 data-pptx-* 属性;
• 从 Master/Layout 继承的对象不可编辑或删除。

边界

支持:引用未改动页(选择/重排/重复/省略)、编辑文字/涂色/图片/原生表格单元格/图表数据、撰写新元素、把 SmartArt/复杂效果/嵌入媒体保留为原子代理、加备注/旁白/转场/动画覆盖层。不支持:在复制页上删除继承的源备注、编辑源代理、更改 slide 尺寸、添加 Master/Layout 结构(改用 Create Template → Generate)。

5.6 创建可复用模板(Create Template)

从参考资料提炼可复用工作区。 固定入口名是 Create Template,它会派发到四个互斥子工作流之一:

分类硬规则:一份完整的 PPTX 不会自动判为 Deck。只分类"值得复用的稳定规则":只有身份稳定 → Brand;沟通方法要流转但不含身份 → Style;结构品牌中立 → Layout;结构携带身份或复用场景语义 → Deck。

触发方式

基于这份参考资料做一个可复用的品牌模板
把这套版式提炼成可复用模板

流程(8 步)

参考包摄入与分析 → 基于事实的简述提案 → 用户确认门(强制)
  → 预检 + 调用子工作流 → 校验模板资产
  → [原型评审轮:仅 Layout/Deck] → [评审 PPTX:多 Master 必需]
  → [库索引注册] → 输出

关键门:

⛔ [TEMPLATE_BRIEF_CONFIRMED] 门:在单独一行输出这个标记之前,不得写任何最终模板目录、模板 SVG 或 Design Spec。

三种内部创作策略(AI 自动推导,不问你):

关键命令:

# 导入参考 PPTX
python3 skills/ppt-master/scripts/pptx_template_import.py "<参考.pptx>" -o "<导入工作区>"

# 校验模板资产(硬门)
python3 skills/ppt-master/scripts/svg_quality_checker.py "<模板源>" \
  --template-mode --canonical-authoring --format <画布格式>

# 评审 PPTX(Layout/Deck;多 Master 必需)
python3 skills/ppt-master/scripts/template_preview_pptx.py "<创作工作区>"

# 注册到库索引(仅 library 范围)
python3 skills/ppt-master/scripts/register_template.py <template_id> --kind brand|style|deck|layout

工作区契约:

<模板工作区>/
├── templates/        # Design Spec(必需);Layout/Deck 另有 SVG 与 native_payloads.json.gz
├── images/           # 可选位图;SVG 用 href ../images/<name>
├── icons/imported/   # 可选导入矢量;data-icon="imported/<name>"
└── exports/          # 可选评审证据;绝不作为模板输入

多 Master 包边界(硬规则):多于一个 Master 仅在 mirror 保留源图,或创作模板有意定义不同的可复用设计家族时成立——绝不是一个 Layout 一个 Master。每个 Master 至少拥有一个 Layout,每个 Layout 至少被一个原型选用。

产出:

## Template Creation Complete

**Template Name**: <template_id> (<display_name>)
**Kind**: brand | style | layout | deck
**Workspace Path**: `<模板工作区>/`
**Design Spec**: `<design_spec_path>`
**Index Registration**: Done | Not registered (project workspace)

交接:工作区根路径就是交给 Generate Step 3 的候选。Stage 1 确认后,应用会解析其 spec、忽略 exports/、创作新的 svg_output/ 页——参考文件和原型都不会被就地升级。

5.7 旁白音频与视频

触发方式

给这份 PPT 加上语音旁白
生成讲解视频

或在生成时确认"启用旁白"。

硬依赖:讲稿

音频需要完整的逐页讲稿(notes/*.md)。讲稿缺失时:Generate 路线回 total_md_split.py;Edit Native 路线回其 §6 写 notes/<svg-stem>.md。绝不在往返工作区跑 Generate 的拆分器。

支持的后端

流程(5 步)

Step 1 判定语言 — zh-CN(默认)/ zh-TW / zh-HK / en / ja / ko…

Step 2 拉音色清单:

python3 skills/ppt-master/scripts/notes_to_audio.py --list-voices --locale <locale>
python3 skills/ppt-master/scripts/notes_to_audio.py --provider <elevenlabs|minimax|qwen|cosyvoice> --list-voices

技能会挑 3–6 个候选,每个用一行说明(性别 · 调性 · 适用场景),并给出要传给 --voice-id 的确切名称。

典型中文音色:

Step 3 解决生成设置 — Default/Edit Native 会一次性消息解决五项决策(生成模式、音色、语速、是否嵌入、是否出视频);Quick 不暂停,直接按推荐值执行。

Step 4 执行(不再交互,串行、不打包):

# 1. 生成音频(二选一形式)
python3 skills/ppt-master/scripts/notes_to_audio.py <项目路径> --voice <ShortName> --rate=<rate>
python3 skills/ppt-master/scripts/notes_to_audio.py <项目路径> --provider <provider> --voice-id <id>

# 2A. 仅当选择"旁白-cue 同步"且页 SRT + animations.json 存在
python3 skills/ppt-master/scripts/narration_sync.py animations <项目路径> \
  --narration-start-floor 0.8 --narration-padding 0.5 --force

# 2B. 重新导出并嵌入音频
python3 skills/ppt-master/scripts/svg_to_pptx.py <项目路径> --recorded-narration audio \
  --narration-start-floor 0.8 --narration-padding 0.5 \
  --inherit-motion-from "<基础 postflight 报告>"

# 2C. 仅当有页级 SRT
python3 skills/ppt-master/scripts/narration_sync.py subtitles <项目路径> \
  --pptx <最终带音频 PPTX> --force

# 2D. 可选:原生视频导出(需 Windows PowerPoint 2016+)
python3 skills/ppt-master/scripts/powerpoint_video.py <最终带音频 PPTX> -o <原始视频.mp4>

# 2E. 仅当最终动效含音效 cue 且选择直接 MP4 交付(需 ffmpeg + numpy)
python3 skills/ppt-master/scripts/video_sound_mix.py <项目路径> \
  --pptx <最终带音频 PPTX> --trace <最终 trace> --video <原始视频.mp4> \
  -o <最终混音视频.mp4> --stem-output <音效 stem.wav> \
  --report-output <混音报告.json> --force

# 2F. 仅当有页级 SRT:对齐到最终交付视频
python3 skills/ppt-master/scripts/video_subtitles.py <项目路径> \
  --video <最终交付视频.mp4> --language <语言> --force

Step 5 完成报告 — 汇总音频数量/位置、SRT、provider/model、视频状态。若跳过了嵌入,会给出提示命令。

重要细节

• 逐页音频:一页讲稿 → 一个音频文件。绝不用一条长音轨代替;
• 字幕永远是外挂 SRT,绝不硬烧;
• Qwen / CosyVoice audio-only:正常嵌入导出,但跳过 narration_timing.json、cue 同步、SRT 合并、最终视频字幕对齐;
• 实时放映录制是显式的手动 Windows 交接(桌面 PowerPoint 全屏播放并录屏),绝不是自动回退;
• 原生视频导出失败时,保留带音频 PPTX 作为成功的上游产物,单独报告视频失败。

5.8 动画与转场

触发方式

能力

• 48 种规范页面切换 — 查询:python3 skills/ppt-master/scripts/pptx_animations.py --list
• 203 种规范对象动画键 — 查询:python3 skills/ppt-master/scripts/pptx_animations.py --describe <effect>
• 逐页/逐对象的进入、强调、退出、路径、顺序、时序

流程

# §1 校验既有 sidecar
python3 ${SKILL_DIR}/scripts/animation_config.py validate <项目路径>

# §2 列出 ID(必要时先重建语义动效单元)
python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <项目路径> --canonical-authoring --stage final --json
python3 ${SKILL_DIR}/scripts/animation_config.py list-groups <项目路径>

# §5 再次校验,然后交回导出
python3 ${SKILL_DIR}/scripts/animation_config.py validate <项目路径>

关键约束

• 写字段前先查:pptx_animations.py --describe-transition <效果> / --describe <规范效果>;
• animations.json 是稀疏覆盖,只引用真实存在的目标;
• 同一 group 只能用「单个 legacy 效果字段」或effects[] 之一;
• 本阶段绝不自行 finalize/导出——交回所属路由;
• no-op 路径不创建任何文件、不改任何 SVG。

音效

音效不是 Strategist 资源——design_spec.md / spec_lock.md 里没有 id 或路径。cue 只在动效方案定稿后,按 animations.md §2.2 选择。

5.9 实时预览与批注

边生成边看,并在浏览器里批注修改。

两个步骤

Step 1 启动编辑器(生成期间无预览服务时):

python3 ${SKILL_DIR}/scripts/svg_editor/server.py <项目路径> --daemon

技能会告诉你编辑器 URL(默认从 6060 端口起找空闲端口)。远程主机加 --no-browser 并转发端口。

编辑器两种用法:

• Direct edit(直接编辑):选中元素 → 右栏控件 → Apply changes 才写入(Ctrl+Z 撤销暂存);
• Annotate(批注):选中元素 → 写指令 → Add annotation → Apply changes → 回对话说 应用注解 / apply my annotations。

也可以跳过编辑器,直接在对话里描述改动。

Step 2 应用批注(需要 <项目路径>/exports/ 至少有一个 *.pptx):

# 输出即待办清单(file → element_id → 批注文字)
python3 ${SKILL_DIR}/scripts/check_annotations.py <项目路径>

然后逐条改 svg_output/<文件> 里的目标元素,移除 data-edit-target / data-edit-annotation,并往 live_preview/annotations.jsonl 追加一条 annotation_applied,最后回到 Generate Step 7.2 重新导出。

边界

• 编辑期间不读取、不应用已提交的批注(那个窗口在 Step 7 之后才打开);
• 它是一个侧进程:绝不等待它,也绝不等待用户确认,一直跑到用户点 Exit preview 或在对话里要求关闭;
• 生产环境强制自启在 generate-pptx.md Step 6。

5.10 可选质量阶段

verify-charts 细节

触发条件:deck 至少有一个"源数值决定 SVG 几何或编码"的图表(柱长、点位置、弧角、多边形顶点、气泡中心/半径、流宽、单元格颜色、字号)。

python3 skills/ppt-master/scripts/svg_position_calculator.py calc bar \
  --data "L1:V1,L2:V2" --area "x_min,y_min,x_max,y_max" --bar-width 120 --value-range=0,axis_max

回执行数必须等于清单长度(这是"关门证据")。坐标确有差异时手工更新——不许正则或批量替换。

visual-review 细节

仅当用户明确要求(绝不因模型能力或 deck 大小自动触发)。Token 成本:20 页 deck 在 K=5 时约多 100–150K 输入 token。

pip install playwright && python3 -m playwright install chromium
python3 skills/ppt-master/scripts/visual_review.py <项目路径>

它派发 AI 子代理按固定评分表逐页目视自检,做原子化的位置/间距修复或标记 needs_human。原件备份在 <项目>/.review/backup/。

硬规则:不碰品牌决策与版式结构;改品牌色要人工做后重渲染重评审。

resume-execute 细节

长 deck 想分段做时适用。规划阶段完成后停手,新会话输入:

继续生成 projects/<项目名>

前置健全性检查:design_spec.md 与 spec_lock.md 必须都存在;若 spec_review/ 存在,先跑 check_spec_annotations.py。任一缺失就停住,经 failure-recovery.md §3 恢复——绝不进入 Step 6,绝不把孤儿锁当权威。

六、目录结构说明

ppt-master/
├── SKILL.md                  # 技能入口:强制加载顺序 + 路由表
├── LICENSE                   # MIT
├── requirements.txt          # Python 依赖
├── SPONSORS.md / _CN.md      # 赞助商(仅在用户明确询问时读)
│
├── workflows/                # 【流程定义】23 个文件
│   ├── routing.md            #   路由权威(选哪条路线)
│   ├── index.md              #   维护者用的流程注册表
│   ├── generate-pptx.md      #   主干:Default 生成(Step 1–7)
│   ├── create-template.md    #   创建模板入口
│   ├── edit-native-pptx.md   #   编辑原生 PPTX
│   ├── profiles/             #   4 个生成 profile
│   │   ├── quick-generate.md       # 快速直出
│   │   ├── beautify-pptx.md        # 美化重排
│   │   ├── image-to-pptx.md        # 图片转 PPTX
│   │   └── ... 
│   ├── create-template/      #   4 个子工作流
│   │   ├── create-brand.md / create-style.md
│   │   └── create-layout.md / create-deck.md
│   ├── stages/               #   11 个阶段
│   │   ├── topic-research.md / generate-audio.md
│   │   ├── customize-animations.md / verify-charts.md
│   │   ├── visual-review.md / live-preview.md / web-image-review.md
│   │   ├── refine-spec.md / apply-template-workspace.md
│   │   └── resume-execute.md
│   └── governance/
│       └── failure-recovery.md   # 失败恢复矩阵
│
├── references/               # 【知识与规则】约 165 个文件
│   ├── strategist.md         #   策略师角色
│   ├── executor-base.md      #   执行者核心
│   ├── plan-core.md          #   规划craft
│   ├── shared-standards-core.md  # SVG 技术边界
│   ├── semantic-svg.md       #   语义标记
│   ├── canvas-formats.md     #   画布格式表
│   ├── native-shape-authoring.md # 原生形状创作
│   ├── preset-shape-vocabulary.md # 187 种预设
│   ├── modes/                #   5 种沟通模式
│   ├── visual-styles/        #   19 种视觉风格
│   ├── image-renderings/     #   21 种图像渲染风格
│   ├── image-palettes/       #   15 种配色
│   └── ... (executor-*.md, native-*.md, svg-*.md 等)
│
├── scripts/                  # 【工具脚本】约 485 个文件
│   ├── attribution_guard.py  #   完整性校验门(启动时必跑)
│   ├── source_to_md.py       #   源格式转换入口(+ source_to_md/ 子模块)
│   ├── project_manager.py    #   项目初始化/导入/校验
│   ├── svg_quality_checker.py#   质量检查器
│   ├── svg_to_pptx.py        #   ★ 核心导出器
│   ├── finalize_svg.py       #   预览生成
│   ├── text_measure.py       #   排版校准
│   ├── icon_sync.py          #   图标同步
│   ├── preset_shape_svg.py   #   预设形状片段生成
│   ├── shape_boolean_svg.py  #   布尔运算形状
│   ├── notes_to_audio.py     #   旁白音频
│   ├── slice_images.py       #   图片切片
│   ├── image_gen.py / image_search.py
│   ├── pptx_to_svg.py        #   往返导入
│   ├── template_preview_pptx.py / register_template.py
│   ├── svg_editor/           #   实时预览 Web 服务
│   ├── confirm_ui/           #   确认界面
│   ├── spec_review/          #   spec 审阅服务
│   └── docs/                 #   工具行为文档
│
├── templates/                # 【内置资源】约 12450 个文件
│   ├── icons/                #   ★ 12027 个矢量图标(5 个库)
│   ├── charts/               #   33 种图表模板 + 词汇表
│   ├── tables/               #   6 种表格模板 + 词汇表
│   ├── brands/               #   21 个品牌模板
│   ├── styles/               #   14 个风格模板
│   ├── layouts/              #   7 个版式模板
│   ├── decks/                #   2 个演示体系模板
│   ├── sounds/               #   音效库
│   ├── design_spec_reference.md  # 设计规格写作模板
│   ├── spec_lock_reference.md    # 执行锁写作模板
│   └── schemas/              #   校验 schema

七、内置资源清单

图标库(12027 个)

沟通模式(5 种,选 1)

模式是论证方式;视觉风格是外观。两者独立:任何模式可搭配任何风格。

视觉风格(19 种,选 1)

企业/产品:swiss-minimal · soft-rounded · glassmorphism · dark-tech · blueprint编辑/出版:editorial · photo-editorial · data-journalism · brutalist表现/印刷:memphis · zine · vintage-poster · paper-cut手绘/笔触:sketch-notes · ink-notes · chalkboard · ink-wash特殊:pixel-art

图像渲染风格(21 种)

3d-isometric · blueprint · chalkboard · corporate-photo · digital-dashboard · editorial · fantasy-animation · flat · glassmorphism · ink-notes · minimalist-swiss · nature · paper-cut · pixel-art · screen-print · sketch-notes · vector-illustration · vintage-poster · warm-scene · watercolor

图表模板(33 种)

line_chart · column_chart · bar_chart · horizontal_bar_chart · stacked_bar_chart · grouped_bar_chart · area_chart · stacked_area_chart · pie_chart · donut_chart · pie_of_pie_chart · bar_of_pie_chart · scatter_chart · bubble_chart · radar_chart · heatmap_chart · treemap_chart · sunburst_chart · sankey_chart · waterfall_chart · funnel_chart · gantt_chart · bullet_chart · dumbbell_chart · butterfly_chart · pareto_chart · box_plot_chart · histogram_chart · stock_chart · gauge_chart · progress_bar_chart · word_cloud · matrix_2x2

表格模板(6 种)

comparison_matrix · feature_matrix · hierarchical_table · metric_table · rating_matrix · record_table

品牌模板(21 个)

accenture · alibaba · anthropic · aws · bain · bcg · deloitte · google · huawei · ibm · jpmorgan · mckinsey · microsoft · nvidia · pwc · tencent · xiaomi · zcare-rescue · 中国电信 · 中国电建 · 中汽研

风格模板(14 个)

academic-research · consulting-decision · creative-pitch · duty-manual · incident-postmortem · investor-pitch · mbb-consulting · narrative-keynote · operating-review · product-launch · science-explainer · solution-proposal · technical-deepdive · workshop-teaching

版式模板(7 个)

editorial_bleed · moments_square · presentation_core · presentation_core_43 · report_core · story_vertical · xiaohongshu_post

画布格式(8 种)

八、常用命令速查

说明:${SKILL_DIR} 指技能绝对路径(如 C:\Users\Administrator\.claude\skills\ppt-master)。Windows 上把 python3 换成 python。

九、常见问题

Q:必须联网吗?A:除 AI 模型通信外全本地运行。需要 AI 配图/网图检索时才会访问外部服务。

Q:产出真的可编辑吗?A:是。文字是可选中文本框、形状是原生 DrawingML、图表是原生图表对象。导出后会附带 [POSTFLIGHT] 回执确认质量门通过。

Q:为什么我的 deck 里数字对不齐?A:技能默认给数据用等宽字体(Consolas)。若你换了字体,可在 spec_lock.md 里改 data_family。

Q:生成中途断了怎么办?A:看你的路线:

• Default:若规划阶段已完成(design_spec.md + spec_lock.md 都在),新会话输入 继续生成 projects/<项目名> 可续跑;
• Quick:没有可恢复记录,重开一次干净的 Quick;
• 任何"失败的必需产物"都会阻塞下一道门,按 failure-recovery.md 的恢复矩阵处理。

Q:生成的文字溢出了 / 质检报错怎么办?A:质检器报的 error 必须清零。常见修复:

• 文字溢出根组边界 → 扩大该根的 data-pptx-bounds(先扩展有空间的区域,再重排或改文本质地);
• 根组重叠 → 调整边界;
• XML 合法性问题 → 用原始 Unicode 写排版符号(—©→),XML 保留字符用实体(&<>);
• 字号越界 → 声明的角色锚点 ±2px 内,或回规划阶段补声明的角色。

Q:能改已完成 deck 的某一页吗?A:能。Skill 支持 revision round:不重开规划,直接改对应 SVG,再同步改 §IX、讲稿和重复该表述的页,最后重跑最终质检 + 导出。旧导出会保留,新导出带自己的时间戳。

Q:怎么换配色?A:两种方式:

• 生成时在 Stage 2 确认环节选不同配色;
• 已生成的项目改 spec_lock.md 的 colors 段,然后用 update_spec.py 做 deck 级替换(注意:派生色调、围绕旧值设计的页面、以及生成了旧强调色的 AI 图不会自动跟随,需手工处理)。

Q:为什么 Quick 模式不能续跑?A:设计如此。Quick 的定位是"一次直出、不留可恢复的设计记录"——它删掉的是交互和可追溯性,不是能力。要可恢复请走 Default。

Q:输出文件在哪?A:<项目路径>/exports/<项目名>_<时间戳>.pptx。同时:

• validation/<项目名>_<时间戳>.report.json — 包审计报告
• backup/<时间戳>/svg_output/ — 冻结的作者源快照(可用 -o 显式指定路径来跳过备份)

Q:支持哪些源格式?A:PDF、DOCX/DOC、XLSX/XLSM、PPTX、EPUB、HTML/网页 URL、LaTeX、RST、Markdown、CSV/TSV、纯文本,以及图片(截图/设计稿)。冷门格式(.odt/.rtf/.org/.typ 等)需 Pandoc。