---
name: ppt-visual-to-editable
description: 将已确认的整页视觉稿或截图还原为高保真、分层、可编辑的 PowerPoint，并保留现有内容、人工调整、主题、几何关系和唯一主 PPTX。适用于 PPT/PPTX 改版、逐页视觉重建、AI 生成视觉稿、透明 PNG 素材提取、图片替换、可编辑文字/形状重建、WPS/PowerPoint 迭代评审，或用户要求“先生成整页设计再拼装进 PPT”的场景。
---

# PPT 可编辑还原

把已确认的位图视觉稿变成可维护的 PPT，而不是把最终稿退化成整页截图。按页推进，保留用户最新保存的主稿，把视觉稿当作重建合同，而不是最终页面。

## 必要配套技能

- 用 `pptx` 处理所有 PPTX 的读取、编辑、渲染、备注和 QA。
- 用 `imagegen` 生成或编辑整页视觉稿、复杂插画、纹理和图片素材。
- 内置生图后立即用 `persist-builtin-imagegen` 落盘并校验。
- 生图失败时不要本地替代，直接停止并报告失败原因。

## 事实源顺序

严格按以下顺序判断：

1. 用户最新保存的主 PPTX。
2. 用户最新的手工改动或截图。
3. 用户已确认的整页视觉稿。
4. 原始 PPTX 和源文档。
5. 更早生成的素材、提示词或脚本。

不要因为旧稿更“顺手”，就把新手工调整的坐标、字号、尺寸或图层改回去。  
如果用户另存为或重命名导致原文件路径失效，不要从备份里复刻旧文件名继续做，先找到用户最新保存的 PPTX 再继续。

## 硬规则

- 只维护一个权威 PPTX，不要一页一个 PPTX。
- 用户要求保留的业务文字和数据必须原样保留。
- 真实公司照片、logo、股东图片和官方标识必须保留，不要用 AI 重画。
- 标题、正文、标签、页码、logo、卡片、线条、箭头和简单图示，能编辑就尽量保持可编辑。
- 只有复杂视觉、纹理、玻璃效果、真实场景或插画才使用独立 PNG。
- 不要把整页截图当成最终可编辑页。
- 可复用的图标或视觉元素要保持独立，不要合并成一个 PNG。
- 复用已确认的页头、背景、字体和风格 token，不要每页都重新生成。
- imagegen 里的中文只当布局参考，最终文字仍要用 PPT 文本层重建。
- 处理透明 PNG 时要分别看 RGB 和 alpha；删除文字后，alpha 里残留的信息也要检查。
- 不要在 WPS/PowerPoint 锁文件存在时覆盖主稿，也不要在用户最新编辑可能尚未保存时覆盖。
- 修改要尽量局部增量，不要在用户已经手工修过的页面上整页重建，除非用户明确要求。
- 只改位图时，优先替换图片关系和媒体文件，保留图片框几何位置；如果层级没变，尽量让 slide XML 保持不变。
- 重复出现问题的图标族，先整组检查和统一，不要等每个图标轮流坏一遍。

## 快速开始

1. 先加载工作区依赖，后续用返回的 Python 跑需要 Pillow 的脚本。
2. 运行只读状态检查器：

```bash
python ~/.codex/skills/ppt-visual-to-editable/scripts/inspect_pptx_state.py /absolute/path/deck.pptx --slide 5
```

3. 确认权威主稿、锁状态、修改时间和目标页。
4. 编辑前先渲染当前目标页。
5. 先读 [page-design-standards.md](references/page-design-standards.md)，再读 [workflow.md](references/workflow.md)，然后建立重建合同。
6. 只改用户要求的页面或对象。
7. 改完渲染目标页，并按 [qa-checklist.md](references/qa-checklist.md) 做快速 QA。

## 素材决策规则

先给每个可见元素分类：

| 元素 | 首选实现 |
| --- | --- |
| 标题、正文、标签、数字 | 可编辑 PPT 文本 |
| 卡片、标签页、分割线、线条、箭头 | PPT 原生形状 |
| 简单图表或流程 | PPT 原生图表/形状 |
| 简单图标 | 能匹配就用原生矢量/形状，否则用独立确认过的 PNG |
| 复杂插画或设备 | 独立透明 PNG |
| 玻璃、光晕、纹理、氛围细节 | 本地 PNG 层 |
| 整页位图草稿 | 只作参考，不能作为最终可见层 |

如果要严格还原复杂素材，优先级如下：

1. 能直接裁出完整干净区域时，先从已确认草稿中提取。
2. 边界清楚但缺透明时，按已确认裁切图做 image edit。
3. 还不够时，再用详细提示词加参考图重生。
4. 纯文字重生只作为最后手段，因为风格漂移最大。

### 图标实现门禁

在提取前先判断图标类型，不要默认把整页上所有图标都切下来。

- **直接画/用矢量**：通用业务图标、小尺寸重复图标、线性/实心符号、需要改色的图标，或者必须在 `0.75 in` 以下仍然清晰的图标。统一一个库/一个家族，保留 SVG 源文件。已有 PNG 关系时，可以先把 SVG 渲成高分辨率透明 PNG，但 SVG 仍是可编辑源。
- **从已确认草稿中裁切**：独特的 3D、玻璃、插画或材质丰富图标，而且其精确外观就是设计的一部分，同时还要满足边界完整、阴影局部完整、源图分辨率足够。
- **整体保留成一个视觉块**：多个元素共享光影、透视或空间关系，拆开后编辑价值不高。
- **重新生成专用素材组**：需要单独移动，但裁切被截断、分辨率低、碰到邻近元素、混入文字/背景，或和同组风格不一致。

通用业务概念不能因为都属于“机构”就共用同一个图标。组装前先确认语义唯一，再在图标板上检查网格、线宽、颜色、光学尺寸和 alpha 边缘。

如果一个页面图标超过三个，先读 [icon-extraction-vs-vector.md](references/icon-extraction-vs-vector.md)。

### SVG 图标交付门禁

通用或重复使用的矢量图标，必须以 SVG + 高分辨率 PNG 兜底的双格式写入 PPTX。  
只放 SVG 在 WPS、旧版 PowerPoint、LibreOffice 或分享后导出的文档里可能会丢；只放 PNG 又会损失矢量清晰度和改色能力。

- PNG 兜底保留在普通 `<a:blip r:embed="...">` 关系里，SVG 通过 `asvg:svgBlip` 挂到 `<a:extLst>`。
- 在 `[Content_Types].xml` 里声明 `image/svg+xml`，PNG 和 SVG 要用独立关系。
- 每个独立图标都要有稳定的语义对象名；凡是视觉上承诺了图标的文字标签，都要检查是否真的有对应图片对象。
- 在导出或拆分分享版后，要重新统计页数、SVG 媒体、`svgBlip` 引用、PNG 兜底和命名图标对象，再渲染对应页面，不能假定打包复制一定保留了向量关系。
- 对于约 `0.34 in` 高的页脚条，图标起始尺寸可先用 `0.18-0.20 in`，线宽略重，视觉中心与文字中心对齐。

### 图标切图失败后的恢复

如果图标裁切脏、被截断、风格不一致或很难分离，不要靠反复补 mask 去修同一个坏图。

1. 单独生成一张只包含所需图标的素材板，统一线宽、配色、视觉重量，并留足间距。
2. 内置 `imagegen` 使用纯平 chroma-key 背景，生成后立刻落盘，再用 `remove_chroma_key.py` 去底色。
3. 把透明素材板按固定单元格拆成独立 PNG，再按 alpha 边界裁紧并加 padding。
4. 检查每个结果的 alpha 四角、完整轮廓、边缘毛边、尺寸一致性，以及是否有残留邻接像素。
5. 需要浅色/深色卡片时，只在本地重着色透明图标，不要为了换蓝白再重画同样几何。
6. 只替换失败的图标对象，回到权威 PPTX 重新渲染目标页。

给模型的提示词是“切图素材板”，不是“最终展示图”：必须是准确数量的图标、单行或网格、等视觉大小、单独单元、无文字、无卡片、无边框、无箭头、无阴影、无背景细节。  
如果内置生成或去底失败，直接停并报告，不要悄悄换成本地替代或别的 API。

### Chroma 素材色彩完整性

不能把“删掉背景色”当成万能方案。绿色幕布可能已经混进抗锯齿、阴影、高光和半透明玻璃像素里了。

1. 蓝白不透明图标的新素材，优先用平铺洋红幕布，不要用绿色；同时禁止阴影、反射、玻璃和纹理背景。
2. 玻璃框和光晕组件不要走普通绿幕去底；优先原生透明生成、PPT 原生形状，或做真正的前景/幕布反混合。
3. 去底后把 alpha 为 0 的像素 RGB 也清成 `(0,0,0)`，否则 PowerPoint 缩放时会露出隐藏色边。
4. 固定蓝色体系下，残留的高饱和绿/青应尽量归回已确认蓝色，同时保留中性高光和深蓝。
5. 可见像素里残留绿色超过 0.5% 就视为失败，不能进入 PPT 拼装。
6. 在算裁切边界前，先清掉很小的孤立 alpha 组件，避免噪点撑大裁切框。

### WPS alpha 边缘完整性

WPS 有时会把普通图片查看器里看不出来的边缘像素渲染成浅色方块或竖条，圆形光晕图标尤其常见。

1. 不只看透明角，还要检查四条外边像素行/列。
2. 独立圆形 PNG 要求四边 `edge_alpha_max == 0`，除非图形本来就要碰到画布边缘。
3. 需要的话用径向或形状感知的 alpha 渐隐，但保留图标和内圈光晕；alpha 归零处 RGB 也要清成 `(0,0,0)`。
4. 同一组重复图标要用同一遮罩和同一尺寸，保证视觉重量一致。
5. 资产重新插回去后，要在 WPS/PowerPoint 里实机检查；无头渲染干净不代表 WPS 也没问题。

圆形图标资产可用 `scripts/clean_circular_icon_asset.py` 处理，PPT 组装前先数值验证边界 alpha。

### RGBA 资产里的嵌字处理

去除透明 PNG 里的文字时，不要只看普通预览。字形可能藏在 RGB、alpha 或两者里。

1. 在深色、浅色和棋盘背景上，以 400% 检查目标区域。
2. 从周围干净材质里重建 RGB；如果字形修补总是留下光晕，就整体换掉这个材质面，不要不停扩 mask。
3. 单独检查 alpha。对不透明表面，文字区域要归一成 alpha 255；对玻璃、光晕或其他半透明材质，则要从干净边界重建平滑 alpha。
4. 外轮廓、倒角、阴影、半透明边缘附近不要强行设成 alpha 255。
5. 不要拿一个已经污染的中间结果继续硬修，除非污染通道已经被明确替换。
6. 复查时用新文件名导出，避免 Preview、WPS、PowerPoint 或聊天图片缓存造成混淆。
7. 插入 PPT 前先跑 `scripts/verify_rgba_asset.py`，并保留证明图直到批准。

完整修复与验收流程见 [transparent-png-text-removal.md](references/transparent-png-text-removal.md)。

## 单页事务

每次改一页都按事务处理：

1. 检查锁、mtime、hash、页数和对象清单。
2. 渲染当前页。
3. 只有开始实质性修改时才创建一个带时间戳的备份。
4. 修改命名对象或替换图片关系，同时保留几何和层级。
5. 保存回同一个权威主稿。
6. 对比打包条目 hash。只改位图时，只允许声明的媒体部分变化；如果改了层级，还可能影响目标页 XML。
7. 只重新渲染受影响的页面。
8. 和用户最新截图及已确认草稿对照。
9. 除非用户要求继续，否则到此为止。

相关图标族尽量合并成一次事务。备份名要有足够精度或唯一后缀，避免同秒重复编辑互相覆盖。

如果当前图片框几何正确，只需要换媒体或前置层级，用 `scripts/replace_slide_image_incrementally.py`。

## 速度模式

按阶段使用最轻的模式：

- `Draft`：生成或修改整页视觉稿，不做 PPTX 组装。
- `Build`：重建单页，只渲染这一页。
- `Milestone`：用 contact sheet 和可编辑性检查来复核一个完成段落。
- `Final`：跑整稿文字、溢出、视觉、备注、对象和文件完整性 QA。

不要每改一点就跑全稿 QA；但每次 PPTX 修改后，都要重新渲染目标页。

## 参考文件

- [workflow.md](references/workflow.md)：端到端门禁流程和重建合同。
- [page-design-standards.md](references/page-design-standards.md)：页面网格、字体、间距、密度、图片和重复组件规则。
- [qa-checklist.md](references/qa-checklist.md)：快速、阶段和最终 QA。
- [public-data-ppt-lessons.md](references/public-data-ppt-lessons.md)：公共数据金融惠企项目沉淀的可复用经验和风格画像。
- [transparent-png-text-removal.md](references/transparent-png-text-removal.md)：面向 RGB/alpha 的文字清理、不透明/半透明判断、缓存控制和 400% 证明 QA。
- [icon-extraction-vs-vector.md](references/icon-extraction-vs-vector.md)：矢量绘制、草稿裁切、整体保留和素材重生的决策门禁。

编辑当前公共数据金融惠企相关页面前，先读 `public-data-ppt-lessons.md`。