转换卡住、校验失败、元素错位？image-to-editable-ppt-skill常见问题排查与修复清单

【免费下载链接】image-to-editable-ppt-skillCodex skill for converting slide images, PDFs, and image-based PPTX files into editable PowerPoint decks.项目地址: https://gitcode.com/gh_mirrors/im/image-to-editable-ppt-skill

使用image-to-editable-ppt-skill（把幻灯片图片、PDF、图片版 PPT 转成可编辑 PowerPoint 的 Codex skill）时，新手最常遇到三类问题：转换卡住、校验失败、元素错位。这篇文章按「症状 → 定位 → 修复」的顺序给出一份排查清单，帮你快速找回卡住的页面、读懂校验报告、修好错位和字号漂移，让转换稳定跑完。

一、转换卡住：先排除这 3 个最常见原因

多页转换是「主 agent 分派 + page worker 并行重建」的长流程，卡住通常不是程序崩溃，而是流程在等某个条件。

1. 权限模式在等你审批

「请求批准」和「替我审批」模式都会在 OCR、图片生成等阶段弹出审批；如果你不在电脑旁，转换就会停住。

✅ 修复方法：建议在 Codex 中使用「完全访问权限」执行本 skill，详见 docs/installation.md 的「运行权限建议」一节。

2. 环境不支持 page worker

多页输入必须能创建 page worker/subagent。如果当前 agent 环境不支持，skill 会停止并报告，不会退化成主 agent 单线程硬跑（避免状态混乱）。

✅ 修复方法：换到支持 page worker 分派的环境执行；单页/单图输入不受此限制，主 agent 会本地重建。

3. 已分派的页面只是「慢」，不是「死」

dispatched状态代表一个活跃租约（active lease）：复杂页面跑 10 分钟以上很正常。不要因为 worker 没发消息就杀掉或重置它——慢页面占着并发槽位是正常的。

官方提示：「转换到一半停住了怎么办」的完整问答见 docs/faq.md。

二、如何检查任务状态：看懂 3 个状态文件

每次转换都有独立任务目录（output/image-to-editable-ppt/{job-id}/），进度全部落在文件里，可随时检查：

页面状态机只有 4 个状态：pending → dispatched → recorded → accepted/complete，定义见 skills/image-to-editable-ppt/SKILL.md 的「State Principles」一节。

让 AI 帮你查状态并续跑

不用自己读 JSON。直接把这句话发给 agent（来自 docs/prompts.md）：

刚才的转换中断了。请检查 output/image-to-editable-ppt/ 下最近任务的运行状态，继续完成未处理的页面。

agent 会通过editppt run next / run status读取状态，从断点继续，而不是从头重跑。

页面真的丢了才用 reset

只有出现明确失败证据（worker terminated/failed/archived/not found）、用户取消、或反复探活无进展时，才用editppt run reset --confirm-lost把页面退回pending重新分派。命令语法见 skills/image-to-editable-ppt/references/cli-helper.md。

三、校验失败：局部修复，而不是整页重做

editppt run record会先校验page.pptx是否符合manifest.json契约，任一条件不满足就拒绝记录：

• 定位对象缺少源图像素坐标；
• manifest 无法独立重建页面；
• validation.json顶层没有passed: true。

修复原则：读取失败证据 → 只让当前页面负责人（page worker 或本地模式的主 agent）局部修复受影响产物→ 重新生成校验报告 → 再次 record。不要为了修一个 manifest 或表格小错就重新生成已经核验通过的素材，更不要手改状态 JSON（状态只能由editppt命令推进，见 docs/workflow.md）。

「必须修」还是「可警告」：一张判断表

完整规则见 skills/image-to-editable-ppt/references/page-decision-tree.md 的「Fix versus Warning」一节。

四、元素错位、字号不对：用测量值而不是目测

文字错位、字号偏小是新手反馈最多的问题。skill 的设计是测量驱动：prepare阶段为每页生成text_hints.json（每行文字框的box_px坐标、实测字号、字号分组）和带标注框的text_hints.png。

修复错位的 3 个关键点：

1. 用实测字号：把text_hints.json里的box_px和对应字号列（中文取font_pt_if_cjk、西文取font_pt_if_latin）抄进 manifest 的text_boxes，并加上"font_size_source": "measured"——否则构建器会保守缩小字号，文字整体比源图小。
2. 同级文字统一字号：同一size_group的行必须用同一个字号，避免同层级大小不一。
3. 配置 OCR Token：有百度 PaddleOCR-VL Token 时，hints 带识别内容和更干净的块边界，文字还原质量明显更好；没有 Token 时退化为离线几何检测（只知位置不知内容），质量打折。Token 免费申请，首次使用时直接把 Token 发给 AI 即可，配置保存在~/.editppt/config.yaml，见 docs/installation.md。

另外两类错位：

• 图标/文字被背景盖住→ 检查 z-index 分层（背景 0 → 结构形状 10-20 → 前景资产 30 → 文本 40+）；
• 卡片圆角过度→ 圆角半径要按源图实测（source_corner_radius_px），不确定的取更小值。

下面对比一下转换前后的同一页，转换后可编辑版会保留文字框、形状与素材的分层结构：

五、最终交付前：finalize 校验清单

所有页面 recorded 后，editppt run finalize会按页顺序读取manifest.json重建最终.pptx并运行 deck 级校验（zip 包有效性、页数匹配、媒体关系完整、资产哈希一致、备注哈希一致等，见 SKILL.md 的 Phase 4）。

交付前建议让 AI 跑一轮质量对比（来自 docs/prompts.md）：

对比每页源图和转换后的页面，检查有没有缺字、错位或资产缺失，并汇总校验结果。

六、排查速查表

更多背景资料可参考 README.md、docs/workflow.md 和 CHANGELOG.md，按这份清单排查，绝大多数「卡住 / 失败 / 错位」问题都能在任务目录内定位并修复。

【免费下载链接】image-to-editable-ppt-skillCodex skill for converting slide images, PDFs, and image-based PPTX files into editable PowerPoint decks.项目地址: https://gitcode.com/gh_mirrors/im/image-to-editable-ppt-skill