PPT模板拆解（ppt-brand-kit）
从 PPTX 提取可追溯的设计数据，生成 brand-spec.md 和 ppt-templates.html。默认先解析，再按需生成原 PPT 基准图；以摘要和代码骨架减少 AI 全量读取与重写。
输入、输出与边界
- 必填：一个可读取、未加密的
.pptx文件路径。支持中文和空格路径，调用时加引号。 - 可选：输出目录；默认是输入文件同级的
ppt-brand-kit-out/。一个输出目录只对应一份源文件：同一文件夹有多份 PPTX 时，每份用--out指定独立目录。 - 依赖：Python 3.8+，生产解析与 lint 使用标准库。原 PPT 基准图额外需要 LibreOffice 和
pdftoppm；先检查已有工具，安装不是默认步骤。 - 交付物：
brand-spec.md和ppt-templates.html，保留用户已有文件；需要更新已有交付物时沿用用户的授权范围。
适用成品页面与设计主要位于版式层的空壳模板。不接受损坏或加密文件；不直接生成可编辑 PPTX。复杂 OOXML 对象和视觉效果有还原边界，不能承诺任意 PPT 的像素一致。
| 中间产物 | 用途 |
|---|---|
design-summary.json |
优先读取的尺寸、令牌与版式目录（含每个版式的 digest 摘要）；统计包含页面与未使用布局，作为来源校验输入 |
template-scaffold.html |
代码生成的版式骨架，文字与图片默认占位；供浏览器预览，AI 无需读取 |
layout-notes.json |
build_templates.py --init 生成的版式说明，AI 只编辑此文件 |
tokens.css |
源设计值映射到 HTML 的 CSS 变量 |
design-report.md / shapes.json |
按需读取的报告与形状细节 |
deck.html / assets/ |
结构底稿和提取素材；不作为独立的源一致性证据 |
run-status.json |
阶段耗时、缓存与渲染结果；不包含模型生成耗时 |
reference-png/ |
可选的原 PPT 独立渲染基准图；本次有效文件列表以 run-status.json 为准 |
S1 解析：先取得可靠数据
使用自带脚本： 拆解时先定位本 Skill 的 scripts/pptx_design_kit.py，不另写同功能脚本。依次查 WorkBuddy 注入的 Skill 目录、~/.workbuddy/skills/ppt-brand-kit/、Windows 用户目录的 .workbuddy\skills\ppt-brand-kit\。确实缺失时报告安装不完整。
环境或路径不明确时先读 env-notes.md。检查 Python 版本后，默认运行不带基准图的解析：
python3 "<skill目录>/scripts/pptx_design_kit.py" "<输入.pptx>" --out "<输出目录>"
解析产物就绪即可进入 S2，不等待外部转换。调用失败先读报错、修正路径或参数，再重试一次；仍失败报告具体阶段，不能把输入或解析失败称为成功降级。
需要视觉校准时独立运行：
python3 "<skill目录>/scripts/pptx_design_kit.py" "<输入.pptx>" --out "<输出目录>" --render-only --shots sample
| 参数 | 行为 |
|---|---|
--out <目录> |
解析与渲染共用的输出目录；默认输入同级 ppt-brand-kit-out/ |
--shots [sample\|all] |
代表页或全页基准图；裸 --shots 等同 sample |
--pages 1,3-5 |
指定 1 起始源页面页码；须搭配 --shots 或 --render-only，优先于模式的页面选择 |
--render-only |
复用当前输入的有效解析产物，只执行渲染；缺失或失效时报错，先另行运行正常解析；不带 --shots 时用 sample |
--render-timeout 120 |
PDF 与 PNG 转换共用的总秒数预算，默认 120；超时后另有有界进程清理耗时，大型文件按实际需要调整 |
--width 1280 |
解析画布与截图宽度，至少 100px；高与字号等比缩放；--render-only 必须沿用已有解析的宽度 |
--force |
输出目录已有另一份源文件的解析产物时仍覆盖；默认拒绝并提示改用 --out。同一路径的源文件修改后重跑、或整体搬移后内容未变，不需要此参数 |
--no-cache |
正常调用强制重解析和重渲染；与 --render-only 合用时仍复用有效解析，只强制重渲染 |
--help |
查询本机脚本的实际参数 |
缓存按输入、脚本与相关参数验证，渲染还考虑工具和字体环境。缓存命中改善重复运行，不能当作首次运行性能；旧文件存在也不等于有效缓存。素材按内容指纹命名，同名图片不会串用。layout-notes.json 与 brand-spec.md 记录生成时的源文件；输出目录换成另一份源文件的解析产物后，build_templates.py 与 draft_brand_spec.py --check 会拒绝继续使用旧交付物（返回 2），同一路径的源文件修改后只给出提醒。v1.3.0 生成的旧说明文件没有来源记录，build_templates.py 会拒绝使用，确认其属于当前源文件后加 --adopt 登记；旧版 brand-spec.md 按来源表中的哈希前缀核对，一致才放行；不一致（包括同一文件修改后）需 draft_brand_spec.py <输出目录> --check --adopt 确认登记，或用 --force 重新生成。来源记录格式无效时同样需要 --adopt。
S2 品牌提炼：生成 brand-spec.md
先读 brand-spec-guide.md，再读 design-summary.json。数值表不手写，先由脚本预填：
python3 "<skill目录>/scripts/draft_brand_spec.py" "<输出目录>" # 生成 brand-spec.md 草稿
python3 "<skill目录>/scripts/draft_brand_spec.py" "<输出目录>" --check # 交付前确认无剩余待补
草稿已按固定章节写好来源、色板、渐变、字体、字号（源 pt 与输出 pt）、版式目录与资产，连同 CSS 变量、频次与出现位置。AI 只用局部编辑替换每章一处的 <!-- 待补：… -->（有图片资产时 7 处，无图片时 6 处），不改动或重写数值表。语义命名、频次筛选和使用限制属于 AI 归纳，应标明“观察”“推测”或“建议”，不能冒充原品牌制度。已有 brand-spec.md 时需用户授权后加 --force。只在摘要不能解释具体问题时查报告、形状或基准图。
摘要的 layout_count 是布局文件数，layout_catalog 条目数是页面版式加未使用布局并合并结构相同者后的结果，两者不必相等。摘要令牌的 count 是页面与版式的解析出现次数，包含未使用布局及继承元素重复出现，不是实际页面使用频率、屏幕面积或品牌重要性。版式目录先列源页面归并出的版式（kind: slide，source_pages 为页码），再列源页面未使用的布局（kind: layout，source_pages 为 L 标识，按布局文件编号排序）；每个版式另有 digest：前几段源文字、文字/图片/其他形状数、图片面积占比、主要纯色填充与背景，命名和描述版式优先用它；仍需定位具体形状时才查 shapes.json（体积可达数 MB，只读需要的页面），页面的 layout_part 指向其所用布局。未使用布局中的设计值不能直接认定当前成品在使用。
字号明确区分源 PPT pt 与 HTML 输出 pt：shapes.json 的 sz 是源字号、render_sz 是输出字号；摘要字号令牌的 value 对应输出 pt，source_value 保留源 pt。默认画布宽 1280px、高按源比例计算，坐标与字号等比缩放。默认宽度下源 16:9 输出 1280×720；源 4:3 输出 1280×960。指定 --width 后以摘要的实际尺寸和比例为准。
S3 模板库：用版式说明合成 ppt-templates.html
先读 templates-guide.md。不读、不手写整份 HTML：骨架可达数百 KB，逐段读写是拆解最慢的环节。按以下三步执行：
python3 "<skill目录>/scripts/build_templates.py" "<输出目录>" --init # 生成 layout-notes.json 骨架
# 只编辑 layout-notes.json：各版式 name / use / limits，可选 texts、images、skip
python3 "<skill目录>/scripts/build_templates.py" "<输出目录>" # 合成 ppt-templates.html 并自动来源 lint
layout-notes.json 以版式 ID 为键，_source 与 _text_shapes（形状 key 与源文字样例）只供参考。texts 以形状 key 为键替换占位文案，沿用该形状首个文字的源样式，换行即分段；images 值为 keep 时恢复 assets/ 源素材，默认 placeholder。不会自动识别 LOGO，标 keep 前须核实并对照原图。校验失败返回 2 并列出可用的版式与形状 key；已有 ppt-templates.html 时需用户授权后加 --force。合成器只使用源令牌，不提供写入源外颜色、字号或新形状的入口。
一个模块对应一种有源证据的版式。L1–L17 仅供结构识别，不要求凑齐 17 种；颜色、字号、区块比例和具体禁忌由输入决定。图表、SmartArt 等未还原对象在该版式的 limits 中写明替代范围；LOGO 未可靠提取时保留原素材，不自动矢量重绘后声称源资产。
合成结果的颜色、字号、字体、渐变均在 :root 定义并以 var() 引用。确需在合成后手工微调时只做局部编辑，并重新运行来源 lint。出现源外设计需求时先指出差异，按用户已有授权处理；没有授权时将方案标为建议，不偷偷加进源规范。
S4 验收：明确交付状态
正式来源检查：
python3 "<skill目录>/scripts/lint_deck.py" "<输出目录>/ppt-templates.html" --source "<输出目录>/design-summary.json"
仅传 HTML 只能检查变量纪律，不能宣布来源一致。lint 覆盖 CSS/SVG 中的常见颜色、字号、字体与渐变写法及变量来源；来源校验确认值属于源令牌集合，不保证逐页逐形状使用与源相同。通过不等于坐标、文本、图片和所有浏览器行为已正确。
--source 也兼容 tokens.css，正式流程优先摘要。lint 退出码 0 为通过、1 为检查发现问题、2 为输入不可读或无效；不能把返回 2 当作“没有问题”。
| 状态 | 完成条件 | 可使用的结论 |
|---|---|---|
| 快速预览 | 解析成功、交付物可打开、记录 lint 结果；视觉检查可未执行 | “预览已生成，视觉与源对照未完成” |
| 结构自查 | 来源 lint 通过；生成 HTML 全页检查文字、图片加载、溢出与版式结构；无足够独立基准图 | “结构自查通过，原 PPT 视觉一致性未验证” |
| 完整源对照 | 来源 lint 通过；全页原 PPT 基准图与生成 HTML 对照粗筛；疑似页全部精查并抽查其余页至少 20%，记录来源页映射与替代对象 | “在记录范围内完成源对照”，列出剩余差异与还原边界 |
执行者无法查看图片时，基准图无法用于对照，验收状态最高为“结构自查”；不能用颜色直方图、像素相似度等自动指标替代人工或视觉模型的逐页对照，并宣称完整源对照。
完整源对照使用 --render-only --shots all。代表页只支持提炼与抽样校准，不能充当全页验收。视觉粗筛只产出疑似页与问题类型；不能以“未发现疑似”代替精查。精确设计值以 XML 与来源 lint 为依据，不让视觉模型报数值。
空壳模板中未被源页面使用的版式可能没有对应原图；这些模块单独标“结构自查”。全页原图不自动覆盖未使用版式，完整源对照结论必须限定到有参考图的模块。
缺少基准图时可以交付明确标为“结构自查版”的结果；若用户要求完整源一致，则保留产物并报告未完成条件。底稿与最终 HTML 都来自同一解析链，其相互对照不能证明原版一致。--fast 不是脚本参数；“快速”指上表的验收状态。
效率与交付记录
端到端耗时主要在 AI 读写，而非脚本解析。默认路线：AI 只读 design-summary.json（含版式 digest）与 layout-notes.json，只编辑说明文件和 brand-spec.md 的待补标记；不整份读取 shapes.json、deck.html 或 template-scaffold.html（重型文件可达数 MB），不手写模板 HTML 或数值表；基准图只在需要视觉核对时按 --pages 渲染。
先看 run-status.json 区分 XML、素材、产物写出、PDF、PNG、缓存与总墙钟时间。AI 提炼、HTML 编辑和验收分别由执行者记录；不将解析完成时间冒充端到端耗时。
交付时报告两件文件路径、验收状态、关键差异、解析/渲染耗时与缓存是否命中。完整统计、新产物与校验会增加首次运行工作量，首次解析不保证更快；缓存、按需渲染和减少 AI 重写的收益分别衡量。不将合成素材、无渲染 CLI 或缓存计时推广为真实 PPT 的端到端提速保证。
已知限制
- 结构底稿用于提炼；SmartArt、艺术字、复杂图表、阴影、特殊文字效果等不保证精细还原。
- 主题、占位符和默认文本样式按页面、版式、母版解析，复杂继承与扩展属性仍须在具体源文件上核查。
- 参考图受 LibreOffice、字体与系统环境影响，不能等同 PowerPoint 在所有机器上的渲染。
- Windows 和 WorkBuddy 的真实运行须单独验证；Mac 本地回归或截图检查不证明它们通过。
- 加密、损坏或不支持的对象应明确报告，不能将缺失文本或素材当成空模板。
禁止事项
- 跳过脚本后凭感觉写品牌规范，或脚本缺失时现场另造解析器。
- 将推测的品牌规则、源外颜色/字体/字号或通用原型写成源事实。
- 将缓存、局部测试、结构自查或代表页抽查称为完整源一致性验收。
- 未经已有授权删除或覆盖用户交付物；在 Skill 文件与输出中使用 emoji。
版本历史
| 版本 | 日期 | 变更 |
|---|---|---|
| 1.3.1 | 2026-10-05 | 一个输出目录只对应一份源文件：解析默认拒绝覆盖另一份源文件的产物（--force 放行）；layout-notes.json 与 brand-spec.md 记录来源，与当前解析不符时拒绝使用，旧版无来源记录的说明需 --adopt 确认；内容相同但路径不同的文件不再复用缓存中的旧来源；--check 输出前缀改为“[检查]”；补充无视觉能力时的验收上限与 layout_count 说明 |
| 1.3.0 | 2026-10-05 | 提速：S3 改为 layout-notes.json + build_templates.py 合成并自动来源 lint，AI 不再读写整份骨架 HTML；版式目录增加 digest 摘要；draft_brand_spec.py 预填品牌规范数值表，AI 只填每章一处的待补（有资产 7 处、无资产 6 处）；shapes.json 紧凑输出、缓存清单复用已知哈希并按大小与修改时间跳过重算（80 页重型样本首次解析 4.5s→2.9s，缓存命中 0.9s→0.5s） |
| 1.2.0 | 2026-10-05 | 版式目录在页面版式之后保留未使用布局（空壳模板带示例页时不再丢失全部布局）；修复 1.1.1 渐变描边实际被丢弃（色标字段名错误），改为首色标近似并给出复核警告；非 UTF-8 locale 下中文路径写入状态文件崩溃；布局按数字顺序编号；空几何调整公式不再崩溃；脚本版本号与 Skill 同步；路径仅在含代理字符时还原字节，GBK 等 locale 下正常路径原样保留；新增 5 项回归测试，114 单测通过（含 Linux C locale）；修复 Windows 下 lint 子进程输出解码与 POSIX 进程清理模拟测试的兼容性 |
| 1.1.1 | 2026-10-01 | 修复成品 PPT 渐变描边崩溃: 渐变边框取首色标登记为令牌(商务汇报.pptx 回归抓出), 双路径回归+109 单测通过 |
| 1.1.0 | 2026-10-01 | 修复设计值/继承/图片/渐变/尺寸与 UTF-8；增加来源 lint、摘要、骨架、缓存、分段计时与按需渲染；统一验收状态 |
| 1.0.3 | 2026-10-01 | 禁止现场重写脚本，补脚本定位与重试序列 |
| 1.0.2 | 2026-09-30 | name 同步中文名 |
| 1.0.1 | 2026-09-30 | displayName 改为 PPT模板拆解 |
| 1.0.0 | 2026-09-30 | 首次发布 |
