PPT Artisan · PPT 原生工坊
> 本技能是 hugohe3/ppt-master（MIT）的
> WorkBuddy 适配衍生版，非官方版本，与原作者无隶属关系。
> 原始版权归 Copyright (c) 2025-2026 Hugo He 所有。完整声明见 NOTICE.txt。
PPT Artisan 是一个路由式演示文稿工作流。本入口只负责全局执行纪律与路线选择，
每条选定路线各自拥有其流程。
环境门禁
Hard rule — 路径先于命令：把宿主提供的、包含本文件的绝对目录记为 SKILL_DIR。
每次工具调用都展开 ${SKILL_DIR}，并把任何 skills/ppt-artisan/ 前缀替换为它。
不要 cd、不要依赖 CWD、不要假定仓库检出。若拿不到绝对路径，向用户询问，
不要搜索或猜测。
运行时资源展开（市场版首次必做）：市场版把 scripts/、templates/、
references/、workflows/ 打包成 runtime.part*.txt 分片，以通过平台的上传
体积限制。首次使用必须先展开，之后不再需要：
python3 "${SKILL_DIR}/scripts/prepare_runtime.py"
脚本幂等：已展开时直接返回「运行时已就绪」，可安全重复执行。
判定是否需要展开：${SKILL_DIR}/scripts/svg_to_pptx/__init__.py 不存在、
且 ${SKILL_DIR}/runtime.part01.txt 存在时，必须先跑上面的命令。跳过这一步会
让后续所有脚本 import 失败——它们依赖的 scripts/ 内容还在分片里。
Python 运行时：所有脚本必须用技能私有解释器
${SKILL_DIR}/.venv/bin/python3（Windows 为 ${SKILL_DIR}/.venv/Scripts/python.exe）。
首次使用前检查该文件是否存在；不存在则先运行：
python3 "${SKILL_DIR}/tools/bootstrap_env.py"
依赖按分组安装，默认只装 core。core 覆盖出稿主链路 —— SVG → DrawingML 编译、
母版与版式继承、数据图表、图片嵌入、质量门禁、Default 路线的确认页 —— 约 61 MB。
其余能力按需增量加装，命令可重复执行，不会重装已有部分：
| 分组 | 下载 | 落地 | 什么时候需要 | 命令 |
|---|---|---|---|---|
core |
23 MB | 61 MB | 必装 | bootstrap_env.py |
pdf |
23 MB | 58 MB | 素材含 PDF / 扫描件 | --with pdf |
sources |
14 MB | 17 MB | 素材含 .docx / .html / .epub / .xlsx / 网页，或要搜实拍配图 | --with sources |
notebook |
8 MB | 32 MB | 素材含 .ipynb | --with notebook |
media |
8 MB | 39 MB | 要生成旁白音频、做音视频合成 | --with media |
ai |
12 MB | 48 MB | 要用 AI 生图后端 | --with ai |
visual |
250 MB | 574 MB | 用户要求视觉复核、逐页截图检查 | --with visual（浏览器自动下载，无需另敲命令） |
全量安装用 --all；--list 可随时查看分组与安装状态。
安装纪律：
- core 自动装。它是本技能能否运行的前置条件，不是用户可选项。首次使用前跑一次
bootstrap_env.py --check；缺就装，并在动手前用一句话说明「首次准备约 23 MB 下载、
约 1 分钟，仅此一次」。 - 其余分组必须先问，不得擅自下载。执行
--with之前，把三件事讲清楚：
装哪一组、下载多大 / 落地多大、大概多久。用户没有明确同意就不要装 —— 一个
只想要几张幻灯片的用户，不该在不知情时被下载 58 MB 的 PDF 解析库。 - 判断依据是素材和诉求，不是猜：
| 触发条件 | 加装 |
|---|---|
素材含 .pdf |
--with pdf |
素材含 .docx .html .epub .xlsx，或给的是网址 |
--with sources |
用户要搜实拍配图（image_search.py） |
--with sources |
素材含 .ipynb |
--with notebook |
| 用户要旁白配音 / 音视频合成 | --with media |
| 用户要 AI 配图 | --with ai |
| 用户要视觉复核 / 逐页检查排版 | --with visual（下载 250 MB、落地 574 MB，含 Chromium 浏览器，必须一并说明） |
用户没给素材、只是口述主题时，core 就够了，不要预先装任何可选组。
4. 报错里出现 needs the 'xxx' dependency group 时，按提示执行 --with xxx。
不要改用 pip install <包名> —— 那会装进宿主 Python，技能脚本用不到。
5. 安装命令本身是一次普通工具调用，用户能看到命令并可随时拒绝；但不要把「用户没反对」
当成同意。
6. 引导失败时停止并报告缺失项，不要退回系统 Python —— 系统环境缺少
python-pptx、skia-pathops 等包，脚本会在 import 阶段失败。
网络与磁盘：引导脚本默认先走 PyPI 官方源，失败会自动换清华 TUNA、阿里云重试；
装之前会检查磁盘余量（安装体积的两倍 + 50 MB）。两者都失败时，把脚本的原始报错
连同建议命令一起转述给用户，不要只说「安装失败」。
工程目录落点：projects/ 属于用户数据，不得写进技能安装目录（市场安装时
那是宿主配置区）。默认解析顺序：PPT_ARTISAN_PROJECTS_ROOT 环境变量 →
当前工作目录 → 用户主目录。建工程时用 --dir 显式指向用户工作区最稳妥：
"${SKILL_DIR}/.venv/bin/python3" "${SKILL_DIR}/scripts/project_manager.py" \
init <项目名> --dir "<用户工作区>"
最终 .pptx 交付物同样写到用户工作区，不要留在 projects/ 里。
必读顺序
- 读本文件。
- 读
workflows/routing.md，使用绝对路径
${SKILL_DIR}/workflows/routing.md。 - 从路由权威中选定恰好一条顶层路线及其生效 profile。
- 只读该路线对应的运行权威，以及它显式触发的支撑文档。
| 选定路线 / profile | 运行权威 |
|---|---|
| Generate PPTX — Image to PPTX ⚠️ | workflows/profiles/image-to-pptx.md；始终 Quick；WorkBuddy 下按降级能力运行，见下 |
| Generate PPTX — Beautify | workflows/profiles/beautify-pptx.md；显式 Quick 意图选 Quick，否则 Default |
| Generate PPTX — ordinary Default | workflows/generate-pptx.md |
| Generate PPTX — ordinary explicit Quick | workflows/profiles/quick-generate.md |
| Create Template | workflows/create-template.md |
| Edit Native PPTX | workflows/edit-native-pptx.md |
Hard rule — 只读选定权威：路由完成后不要加载另一条顶层路线的流程。
Image to PPTX 与 Beautify 互斥；Image to PPTX 激活 Quick，而 Beautify 依据显式
Quick 意图选择。绝不同时加载两个运行权威。支撑文档只精化单条路线，不与它竞争。
Image to PPTX 的宿主能力边界
这条路线要把整页图片拆成「可独立编辑的背景层 + 主体层 + 源图形 + 原生文字」。
文字与纯几何不需要任何模型；只有被判定为污染、遮挡、不完整或低分辨率的区域
才需要宿主具备参考图生成/编辑能力去补全背景、重建主体层。
上游 ppt-master 对此的原始表述是 Support boundary — Codex required：它只对
Codex 验证过，依赖 Codex 内置的参考图生成/编辑，并明确声明「其他宿主可能碰巧能用，
但仓库不做兼容性承诺，也不定义替代宿主或通用图像后端」。换言之，这不是本衍生版
新增的限制，而是上游从设计之初就绑定的宿主能力——任何没有等价参考图编辑能力的
宿主（包括没有 Codex 的本地环境）都会遇到同一处缺口。
WorkBuddy 没有该能力，因此本路线在此按降级模式运行：
| 页面内容 | 降级后表现 |
|---|---|
| 文字 + 形状 + 纯色/渐变背景（设计稿、扁平渲染页、截图） | 可用。文字转原生文本，图形按源像素裁剪或确定性重绘，背景转色块 |
| 有清晰可分离的图片区域（源像素在最终尺寸下足够） | 可用。按记录几何直接裁剪，不需要重建 |
| 含人物、场景照片，需要把主体从背景中分离 | 阻塞。标 manual_required 并停止该页导出，不猜测、不用相似图替代 |
| 需要重建品牌标识（低分辨率 logo / 字标） | 阻塞。同上，不做相似化替代 |
判定与阻塞逻辑写在 image-to-pptx.md；
不满足条件时不要勉强降级成截图皮肤（整页图 + 少量浮层文字），那违反该路线的
Forbidden — screenshot skin 规则。此时改用普通 Generate，把图片当视觉参考重新设计，
或把图片当素材通道使用。
Authored Expression Range
参考，非约束：一个生成页面可以承载什么。文本 —— 行内强调 run、导语、kicker、
引文、主数字、要点行。几何 —— 187 个 Office 预设、布尔合并、连接线、自由形状、
页面场与轮廓载体构图。图像 —— 满版场、编辑性裁切、成形图片、套准图层、遮罩与聚光、
跨页连续性。涂装 —— 渐变、通道 alpha、原生阴影与辉光、半调、切面形态。
复用 —— 一个跨页母题，按页面角色变化。每种形式的语法位于选定运行权威的构造参考中。
Vocabulary
每个词在所有已加载文件中只有一个含义。一个词若被用于多种含义，其含义在此命名，
各文件说明使用哪一种。
| 术语 | 含义 |
|---|---|
| Reference（标签） | 执行角色可自由调整或替换的起点草图，无需上游修复或说明理由；字段标签后的 (binding) 移除该自由 |
| Relationships | §IX 中命名页面语义单元及其来源所述 order / link / parent / membership / contrast / overlap 的行，或 none |
| Topology decision | 每页关于几何是否必须承载该页 Relationships 的是/否判断（topology=yes / topology=no）；与 pptx_structure.mode 无关 |
pptx_structure.mode |
flat（每个对象都是 Slide 局部）或 structured（声明 Master/Layout/slot 元数据）；是打包路线，不是信息结构 |
| Composition | §IX 的 Composition 行：页面宏观构图、层级与焦点的 Reference |
| Image pattern | §VIII 中承载一条图像构图建议的列，用日常语言表述（可选引用 #P/#M id） |
| Layout | Master 下的 PowerPoint Layout，或 Layout 模板种类；绝不是页面构图草图 |
| Device | 日常页面载体 —— 卡片、色带、图标加标签、KPI 瓦片、分隔、引文块 —— 在 Executor 的设备菜单中被召回 |
| Carrier | 页面单元所处的容器：设备、图像或原生几何；家族名为 carrier 与 field、方向与序列、分组与归属、强调与注释。data-pptx-carrier 是结构化 slot 属性，不是本术语。carrier receipt 是检查器对实际绘制内容的逐页清单 |
| Page job | 一页必须为读者完成的事；每个载体、轮廓与效果决策都以它为准绳 |
| Page field | 一个大的表面、轮廓、开口或画布外轮廓，用于组织分区，而不是每单元一张卡片 |
| Contour / preset / atom | contour 是形状的剪影；preset 是 187 个 Office prst 轮廓之一，经 preset_shape_svg.py 绘制；atom 是编译为一个 DrawingML 形状的对象 |
| Geometry signature | 逐页保留的 page job → composition move → contour / edge language 行，在下一页之前比较 |
| Texture（块的） | §IX 块是散文、项目符号、关键词还是标签；区别于视觉纹理（颗粒、半调） |
| Anchor | 两种含义：锁定锚（全稿的颜色、字体或间距值）与 page_rhythm 标签 anchor（结构页） |
| Sheet / slice / plate | sheet 是一张在色键背景上承载多个元素的生成图；slice 是从中切出的单个元素；plate 是多个不重叠对象的套准满画布图层 |
| Module line | 每页之前写下的 P<NN> modules: … 行，命名其使用的已触发模块 |
| Mode | 由限定词命名：传播 mode（稿件如何论证）、阅读模式（consumption_mode）、generation_mode（continuous / split）、pptx_structure.mode、replication_mode（模板如何创建） |
Phase Frame
每条路线都是一个 Plan → Do·Check·Act 循环：Plan 在所有创作输入以文件或保留决策的
形式存在时结束；Do 创作页面，Check 运行该路线的门禁，Act 在归属层修复（纪律 7），
循环在导出处结束。步骤编号保持原样。
| 阶段 | Default | Quick | Edit Native | Create Template |
|---|---|---|---|---|
| Plan | 步骤 1–5 | §2 | §1–4 | 步骤 1–3 |
| Do·Check·Act | 步骤 6–7 | §3–4 | §5–7 | 步骤 4–8 |
Global Execution Discipline
- 串行执行 —— 按顺序遵循选定权威的步骤。已完成的非阻塞步骤可直接进入下一个合格步骤。
- 阻塞即停止 —— 在每个
⛔ BLOCKING门禁处等待用户明确确认。不要替用户决定。 - 不跨阶段打包 —— 不要在未关闭的门禁之间合并工作。路线最后一个用户门禁关闭后，后续非阻塞步骤可自动继续。
- 进门先验证 —— 进入步骤前验证每个列出的前置条件。
- 不做投机执行 —— 不要在归属步骤之前准备后续阶段的产物。
- 确定性路由 ——
routing.md已能解析请求时，不要追加路线选择问题。路线前置缺失时说明并停止该路线。 - 在归属层修复 —— 失败时在拥有该故障的最浅层修复：页面局部问题修页面，roster/spec/资源故障修 Plan 产物，工具失败修归属源产物；然后从路线声明的指针恢复。不要静默降级必需产物。
Global Communication Rules
- 匹配用户语言与源材料语言，除非用户明确覆盖。
- 本地化面向用户的选项标签与解释。固定消息模板（角色切换横幅、完成报告）在用户
聊天语言不同时按该语言渲染。需要精确性时保留确切枚举 ID 或字段名。 design_spec.md的章节标题与字段名保持模板原始英文；内容值可用用户语言。- 切换角色前，读对应角色参考并输出：
## [Role Switch: <Role Name>]
📖 Reading role definition: references/<filename>.md
📋 Current task: <brief description>
WorkBuddy Platform Notes
- 本包是工作流技能，不是通用应用脚手架。不要创建
.worktrees/、tests/、
分支工作流或通用工程结构。 - 工作流、参考、脚本与模板文档必须留在技能目录内。包内运行时不依赖包外指令。
- 生成的项目与导出文件写入用户工作区，不写入技能安装目录（见
scripts/project_management/paths.py的根目录推导）。 - Windows 上若
python3不可用，改用python重跑同一命令。 - 导出需要项目目录内的删除权限。导出链路会在项目下建临时工作目录、写入中间文件、
再删除它们。若宿主安全策略拦截unlink/rename，导出会停在
Flat export must retain exactly one slide-referenced Blank Layout。
遇到这个报错不要反复重试，按下面三句向用户说明：①需要允许本技能在项目目录内
删除临时文件；②已完成的页面创作与质量门禁报告仍然有效，不会白做；③授权后从导出
这一步继续，不必重跑前面的步骤。 - 本技能不含赞助商或模型推荐内容。用户主动询问生图后端或服务商时，
读.env.example中列出的官方配置项，不要推荐第三方中转服务。
