转换卡住、校验失败、元素错位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}/进度全部落在文件里可随时检查文件作用page_jobs.json每页的分派与完成状态run_state.json整个任务的运行状态pages/page_NNN/validation.json每页校验结果页面状态机只有 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。「必须修」还是「可警告」一张判断表情况处理线条/曲线对象粒度错误、PPTX 打不开、文字明显拥挤溢出必须当前页修复硬失败素材轻微毛边、非关键装饰小偏差、低风险字体差异记录为 warning 即可交付公式渲染缺 TeX 环境保留可打开的 PPTwarning 记录 LaTeX 源码与错误完整规则见 skills/image-to-editable-ppt/references/page-decision-tree.md 的「Fix versus Warning」一节。四、元素错位、字号不对用测量值而不是目测文字错位、字号偏小是新手反馈最多的问题。skill 的设计是测量驱动prepare阶段为每页生成text_hints.json每行文字框的box_px坐标、实测字号、字号分组和带标注框的text_hints.png。修复错位的 3 个关键点用实测字号把text_hints.json里的box_px和对应字号列中文取font_pt_if_cjk、西文取font_pt_if_latin抄进 manifest 的text_boxes并加上font_size_source: measured——否则构建器会保守缩小字号文字整体比源图小。同级文字统一字号同一size_group的行必须用同一个字号避免同层级大小不一。配置 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对比每页源图和转换后的页面检查有没有缺字、错位或资产缺失并汇总校验结果。六、排查速查表症状第一步关键文件/命令转换卡住不动检查是否在等审批完全访问权限 run_state.json某页一直 dispatched确认只是慢别 reseteditppt run statusrecord 被拒看 validation 证据局部修复validation.json、editppt page validate文字偏小/错位使用实测字号 measured 标记text_hints.json最终 PPT 打不开页面 manifest 契约失败editppt run finalize报告更多背景资料可参考 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考