先把一个容易误会的点说清楚：soulmujoco/EditableImage2PPTSkill 不是把截图塞进 PPT 当背景图的工具。它真正要解决的是另一件事，把幻灯片截图或导出的单页图片拆成可移动的 PNG 素材、可编辑文字框、原生形状和线条，最后重新打包成可以继续改的 PPTX。

这个 skill 适合手里只有页面图片、没有原始 .pptx 的情况。仓库里的 `SKILL.md` 写得很明确：如果原生 PPTX 文件还在，应该直接编辑原文件；只有截图、导出图、扫描式页面需要重建时，才值得走 EditableImage2PPTSkill 这条路。

先确认你要修的是图片页，不是原始 PPTX

开始安装前先看输入材料。它要吃的是 slide screenshot、导出的 slide image，或者一组页面图片；如果你已经拿到原始 .pptx，再用这个仓库重建一遍反而会增加误差。

仓库目录也说明了这条边界：`references/asset-manifest.md` 管裁剪素材，`references/layout-json.md` 管版面 JSON，`references/reconstruction-sop.md` 管重建检查。它不是一键美化工具，而是一个分步骤重建工作流。

把 skill 放到 Codex 能识别的位置

安装时不要只下载 zip 放在下载目录里。新手要做的是把仓库放进本机 Codex skills 目录，然后重启或刷新 Codex，让 `$ppt-image-to-editable-ppt` 能被识别。

1. Windows PowerShell 按 README 的写法执行：git clone https://github.com/soulmujoco/EditableImage2PPTSkill.git "$env:USERPROFILE.codexskillsEditableImage2PPTSkill"。
2. macOS 或 Linux 可以放到对应用户目录：git clone https://github.com/soulmujoco/EditableImage2PPTSkill.git ~/.codex/skills/EditableImage2PPTSkill。
3. 进入目录做一次文件检查：cd ~/.codex/skills/EditableImage2PPTSkill，确认能看到 `README.md`、`SKILL.md`、`agents/openai.yaml`、`scripts/` 和 `references/`。
4. 重启 Codex 后输入一个很短的任务，例如“用 ppt-image-to-editable-ppt 重建这张单页截图”，如果 Codex 能识别这个 skill，安装路径才算放对。

这里的成功标志很具体：不是终端没有报错就结束，而是 Codex 能读到 `SKILL.md`，并把任务路由到 PPT Image to Editable PPT 这套流程。识别不到时，先查目录层级，不要急着改脚本。

Python 依赖要先补齐，不然脚本会半路停

这个仓库真正落地靠几个 Python 脚本：`scripts/asset_cropper.py` 负责裁剪素材，`scripts/build_pptx_from_layout.py` 负责按 layout JSON 生成 PPTX，`scripts/combine_layouts.py` 负责合并多页，`scripts/inspect_pptx.py` 负责检查包体。

1. 先确认当前 Python 环境可用：python --version。
2. 安装 README 里列出的依赖：python -m pip install python-pptx pillow numpy。
3. 如果 `build_pptx_from_layout.py` 提示缺 `python-pptx`，说明依赖装到了另一个 Python 环境；切回正在运行脚本的环境再装一次。
4. 这个仓库的脚本本身没有单独的 API Key 参数；如果后续让模型帮助识别页面结构，密钥属于 Codex 或模型运行环境，不在 `scripts/` 里配置。

依赖检查通过后，再把页面图片拿进来。建议先建一个独立工作目录，里面放 `assets/page_001/`、`layouts/`、`output/`、`scratch/`，这样裁剪素材、版面 JSON、生成 PPTX 和检查报告不会混在仓库源码里。

第一次只拿一页截图做小测试

首次试跑不要直接扔一整套 40 页的材料。先选一张结构简单的 slide image，做一个 asset manifest，把 logo、图标、照片这类不能重建成文字和形状的部分列出来。

1. 先按 `references/asset-manifest.md` 写 `page_001.assets.json`，每个素材写清名称、裁剪坐标和源图片。
2. 运行素材裁剪：python scripts/asset_cropper.py --manifest page_001.assets.json --out-dir assets/page_001 --contact-sheet。
3. 打开 `assets/page_001/_contact_sheet.png`，确认图标、照片、装饰条没有漏裁，也没有把普通文字当成图片。
4. 再按 `references/layout-json.md` 写 `layouts/page_001.layout.json`，把普通文本写成 text box，把矩形、圆、分割线写成原生 shape 或 line。
5. 生成单页 PPTX：python scripts/build_pptx_from_layout.py --layout layouts/page_001.layout.json --assets-root . --out output/page_001_editable.pptx。

这一轮的小测试只看两件事：`output/page_001_editable.pptx` 是否生成，打开后文字是否能点选编辑。如果文字还是整张图片的一部分，就说明你没有按这个 skill 的标准重建，只是换了一个容器。

多页合并前先跑检查报告

单页能跑通后，再把每一页各自的 layout JSON 放进 `layouts/`。合并前用 python scripts/combine_layouts.py --layouts layouts --out layouts/combined.layout.json 得到总 layout，再用 build 脚本导出最终 deck。

最后一定要跑检查：python scripts/inspect_pptx.py --pptx output/deck_editable.pptx --report scratch/quality_report.json。成功标志是报告里有 slide 数、media 数、text run 数，并且没有空媒体、占位文字或无 slide 这类 failures。

失败时先看目录和报告，不要重做整套

如果裁剪脚本失败，先看 manifest 里的坐标是否越界、图片路径是否写错。`asset_cropper.py` 会按裁剪框导出 PNG，路径或 box 错了，后面的 build 阶段一定跟着错。

如果 PPTX 生成了但效果差，优先回到 `layout-json.md` 调整 text box、shape、line 和图片层级。EditableImage2PPTSkill 的价值不是一次生成完美稿，而是把不可编辑的图片页拆成可继续修改的 PPT 对象。

收尾时按三项检查：skill 是否被 Codex 识别，单页小测试是否生成 editable PPTX，`scratch/quality_report.json` 是否能定位问题。三项都过，再上多页材料；只要有一项不清楚，就停在单页工作目录里修，不要把错误扩散到整套 deck。