图像转可编辑PPT (Claude Code 移植版)
使用捆绑的 editppt 运行时来分解、重建、验证和组装视觉幻灯片为可编辑的 .pptx 文件。输入可以是一张或多张图片、一个PDF文件或一个基于图像的PPT/PPTX文件。输出始终是一个 .pptx 文件，每个输入页面对应一张幻灯片，并按输入顺序排列。
以下 <skill-root> 指代包含此 SKILL.md 文件的目录。
本技能的组成
本文件由作为编排器的你阅读。页面级别的工作由页面重建器（后台子代理，或单页模式下由你本人）根据生成的提示完成。每条规则只有一个权威所在——请按照指针指引，而不是自行猜测：
prompts/page-worker.md—— 页面重建器模板：所有权边界、读取路径、执行顺序、必需输出、返回格式。由scripts/build-page-worker-prompt.py填充。references/cli-helper.md——editppt安装检查、命令树、语法。在选择命令时阅读。references/manifest-schema.md—— 每次运行/页面工件的JSON契约。在编写或验证运行/页面文件时阅读。references/page-decision-tree.md—— 什么成为背景 vs. 图像资源 vs. 原生文本/形状/表格、文本提示的使用、最终自我检查、修复与警告。页面重建器阅读此文件；你很少需要阅读。
Claude Code 运行时映射
上游技能面向Codex。以下是使其能在Claude Code中运行的替代方案；它们在引用中提到的任何Codex等价物处均适用。
| 上游 (Codex) 概念 | 在Claude Code中 |
|---|---|
内置的 image_gen.imagegen + 图像模型资源表 | 被 claude-native 后端取代。 Claude 能看到但不能生成位图，因此它将图标/插图追踪为SVG，将照片保留为矩形源区域，并在本地修复干净的基底（references/page-decision-tree.md 第2.4节）。始终使用 --image-backend claude-native 进行 prepare；永远不要使用 builtin-imagegen。 |
CLI 图像 API (editppt image generate/edit) | 可选升级，仅在 editppt doctor --check-api 报告后端就绪且对象不适用任何原生源时使用。非必需。 |
view_image | Read 图像文件路径 (source.png, text_hints.png, 缩放和 .compare.png 图像, preview.png, split_assets_contact.png)。 |
| 生成页面工作器 / 子代理 | Agent 工具，subagent_type: "general-purpose"，run_in_background: true，name: "ppt-<page_id>"（例如 ppt-page_003）。 |
用于 --agent-id 的工作器 id | 你赋予代理的相同名称（ppt-page_003）；单页本地模式下为 main。 |
| 等待工作器 | 后台代理完成时通知你。不要循环轮询。 |
| 向工作器发送修复指令 | 使用 SendMessage 发送到工作器的名称，以便其保留上下文。 |
| 沙箱 / 网络审批 | Claude Code 权限提示。使用本地 RapidOCR 提示的 claude-native 运行完全不进行外部调用。只有当配置了令牌时才会调用 PaddleOCR（editppt prepare / editppt run hints）；如果使用可选升级，editppt image generate/edit 也会进行外部调用。 |
入口合约
以下是仅在此处声明的编排器级别规则。
- CLI 优先。
editppt是必需的运行时。如果editppt --help失败，请从<skill-root>/cli安装它（使用references/cli-helper.md中的预运行检查，当uv存在时优先使用uv tool install --force --editable <skill-root>/cli，然后使用pipx，最后使用pip --user），然后运行editppt doctor。 - 仅通过 CLI 进行状态管理。 从
editppt prepare <input...>开始。之后，仅通过editppt命令推进每个状态转换；切勿手动编写运行/页面状态 JSON。这确保了运行具有确定性和可恢复性。 - 谁重建页面。 正好包含一页的运行，在
editppt run dispatch --local声明后由你在本地模式下重建。多页运行由后台页面工作器重建——每页一个。不要自行重建多页工件：每个页面会消耗大量上下文（图像、清单、修复循环），将其保留在单独的工作器中可以保持你的编排上下文可用，并允许页面并行运行。 - 工件所有权。 除了在
--local声明后的单页本地模式外，你不编写manifest.json、page.pptx、preview.png、split_assets_contact.png、validation.json或page_result.json。本地模式遵循与工作器相同的页面提示、引用、输出和run record验证。 - 图像后端。 参见下面的“Claude Code 中的图像后端”。如果没有任何允许的源可以重现某个对象，则该页面验证失败，而不是使用近似形状或图标裁剪来替代（
references/page-decision-tree.md第2节）。 - 授权的外部调用。 将幻灯片转换为可编辑 PPT 的请求授权了该转换所需的 OCR 调用（以及如果配置的图像API调用），除非用户要求仅本地处理或将输入标记为机密。仅发送任务本地的页面图像、提示、蒙版和参考图像——绝不发送不相关的文件或凭据。仅当用户配置或指定了第三方端点时才允许使用它们。
- 自主性。 执行常规重建、已配置的回退和页面本地修复，无需确认门禁。仅当遇到只有用户才能提供的内容（例如OCR令牌决策、缺失的输入）时才停止并询问用户。报告具体的阻塞项，而不是要求用户进行调试。
- 对象决策 遵循
references/page-decision-tree.md；确定性验证是一个结构门禁，绝不放弃对象源决策。 manifest.json是权威的页面构建源；run record根据它验证page.pptx，并且run finalize根据记录的清单重建整个演示文稿。
凭据卫生
秘密信息（PaddleOCR 令牌、可选的图像API密钥）如果用户粘贴到聊天中，最终会出现在对话记录中。建议用户自己使用 ! 前缀运行配置命令，以便值直接进入 CLI，例如：
! editppt config --paddle-ocr-token <token>
! editppt config --api-key sk-... --base-url https://api.openai.com/v1 # 可选的图像API升级
如果他们仍然将密钥粘贴到聊天中，使用 editppt config 存储它，并且永远不要将其回显出来；CLI 会在输出中将其屏蔽。切勿将密钥写入项目、运行目录或技能目录。
Claude Code 中的图像后端
Claude 具有视觉能力但没有图像生成能力，因此每次运行都使用 claude-native 后端：editppt prepare <input...> --image-backend claude-native。然后页面重建器根据 references/page-decision-tree.md 第2.4节为每个对象选择源：
- 图标、徽标、徽章、手绘标记、扁平插画 —— Claude 将其追踪为 SVG（
editppt image zoom，然后editppt image svg）。PPTX 嵌入真实的 SVG，因此在 PowerPoint 中用户可以为其重新着色或使用 转换为形状 来编辑其单个路径。这使得这些对象比上游技能的位图资源更可编辑。 - 照片、截图、纹理块 —— 保留为矩形源区域（
editppt image photo-region）。矢量追踪会将它们变成卡通画。 - 重建文本后面的复杂背景 —— 通过本地图像修复进行清理（
editppt image inpaint）。
不要向用户询问图像API。如果 editppt doctor --check-api 恰好显示一个就绪的后端（Codex 登录或已配置的密钥），工作器可以使用 editppt image generate/edit 作为可选升级，用于那些没有很好地适配任何原生源的对象，例如复杂背景上的照片裁剪。页面内的资源命令串行运行。
工作流程
阶段 1：准备
阅读 references/cli-helper.md 中的准备示例和 references/manifest-schema.md 中的运行/页面文件描述。
editppt prepare <input...> --image-backend claude-native
保留默认的 --out-root：它在当前目录下创建工作运行目录 output/image-to-editable-ppt/<job-id>/。不要将其指向用户希望结果所在的文件夹；该文件夹应仅接收最终演示文稿（阶段4）。之后必须存在 deck_manifest.json、page_jobs.json、notes_manifest.json，并且每个页面必须拥有 source.png 和 page_request.json。
Prepare 还会写入每个页面的文本提示（text_hints.json/text_hints.png）。没有令牌时，它们来自本地 RapidOCR，它在设备上读取文本而不上传，因此不要向用户询问任何内容。只有当 prepare 报告仅几何信息的 builtin-ink 后端（RapidOCR 不可用）时，你才应在分派任何页面之前询问用户一次：来自 https://aistudio.baidu.com/account/accessToken 的免费令牌，使用 editppt config --paddle-ocr-token <token> 存储，可以使提示内容感知（它不仅测量文本位置，还读取文本内容），并显著提高文本保真度；然后 editppt run hints <run> 会在原地重新生成当前运行的提示。免费的个人配额对于此技能来说绰绰有余。等待他们的选择；如果他们拒绝，则继续使用离线提示，并且不再询问。
如果用户要求使用 Indra OCR（或更快/替代的本地OCR），运行 editppt config --text-hints-backend indra 并使用 [indra] 额外选项重新安装 CLI（references/cli-helper.md）。提一次 Indra 的模型权重带有修改后的 OpenRAIL-M 许可证，限制了某些商业用途。不要自行切换到它：在测试中，RapidOCR 读取幻灯片文本更完整。
如果已配置令牌但由于权限提示或网络故障导致 OCR 回退，那不是首选的质量路径：让调用通过并重新运行 editppt run hints <run>，然后再进行页面重建。仅在用户拒绝 OCR、允许的 OCR 尝试因真正的服务原因失败后，或者用户要求仅本地处理时，才继续使用离线模式。
阶段 2：重建或分派页面
重复调用并根据返回的 stage 进行操作：
editppt run next <run> --json
stage=rebuild_page_locally（正好一个页面）。声明它，然后自行重建：
python3 <skill-root>/scripts/build-page-worker-prompt.py <run> --page <page_id> --out <abs-run-dir>/pages/<page_id>/worker-prompt.mdeditppt run dispatch <run> --page <page_id> --agent-id main --prompt-file <abs-run-dir>/pages/<page_id>/worker-prompt.md --localRead生成的提示并遵循它，在该页面目录内进行操作，生成工作器会产生的相同输出。
stage=dispatch_pages。对于每个建议的页面，按此顺序：
- 使用上述脚本构建提示。
- 使用
Agent工具创建工作器——subagent_type: "general-purpose"，run_in_background: true，name: "ppt-<page_id>"，description: "Rebuild <page_id> as editable PPT"，并将prompt设置为：You are a page reconstructor for the image-to-editable-ppt skill (Claude Code port). Read <abs-run-dir>/pages/<page_id>/worker-prompt.md and follow it exactly. Claude Code notes: view images with the Read tool; you cannot generate bitmaps, so non-text visuals come from page-decision-tree.md section 2.4 (SVG traces, photo regions, local inpaint); run shell commands with Bash. Do not touch files outside your page directory. - 仅在派生成功后：
editppt run dispatch <run> --page <page_id> --agent-id ppt-<page_id> --prompt-file <abs-run-dir>/pages/<page_id>/worker-prompt.md
在一条消息中派生一批中的所有建议页面，以便它们并发运行。--out 和 --prompt-file 必须是绝对路径，以免页面目录被重复添加。并发槽位来自 page_jobs.json.max_concurrent_pages（默认为6）。
stage=wait。已分派的页面是活动租约，而不是空闲槽位。等待完成通知。不要因为工作器速度慢或安静而停止、重置或替换它——复杂页面可能需要10分钟以上的时间。
stage=configure_backend。运行 editppt run backend <run> --mode claude-native，而不是建议的 builtin-imagegen/CLI 合约。
阶段 3：记录
当工作器的完成通知到达时（或你完成本地页面后）：
editppt run record <run> --page <page_id> --agent-id <id>
这会根据 manifest.json 验证 page.pptx，如果定位的对象缺少源像素坐标、清单无法独立重建页面或 validation.json 缺少顶级的 passed: true，则拒绝该页面。然后返回 editppt run next。
修复。 如果记录失败，阅读失败证据，并让页面的所有者仅修复受影响的工件，重新验证（editppt page validate，参见 references/cli-helper.md），然后再次记录。在多页面模式下，将证据 SendMessage 发送给现有工作器（ppt-<page_id>），而不是派生一个新的工作器——它已经持有页面上下文及其已验证的资源。不要为了修复不相关的清单或表格错误而重新生成合规的资源。
重置 仅在页面需要重新执行时进行：工作器以最终失败状态结束、用户取消、或者重复的可达性尝试显示没有页面本地进展。慢不等于丢失。在修复了阻塞它的内容后：
editppt run reset <run> --page <page_id> --agent-id <id> --confirm-lost
重置将页面状态恢复为 pending；从阶段2开始使用新的提示和工作器继续。现有工件保留用作溯源和选择性重用。
仅在更改了输入或条件后重试——切勿重复相同的失败调用。如果真正的先决条件缺失，保留进度并向用户报告具体的阻塞项。一旦输出通过检查，就继续前进；不要重复不变的视觉质量检查。
阶段 4：最终确定
当 run next 返回 finalize 阶段时：
editppt run finalize <run>
Finalize 根据每个记录的 pages/page_NNN/manifest.json 按页面顺序重建演示文稿，原样复制 .pptx 的演讲者备注，并验证结果：有效的包、幻灯片数量等于输入页面数量、正确的PDF/PPTX分页（包括末尾的空白页）以及演讲者备注与备注清单匹配。它还会联系你删除运行目录（你可以删除或保留它），并告诉用户最终文件位于 output/image-to-editable-ppt/<job-id>/deck.pptx（除非他们指定了不同的输出路径）。
输出位置。 如果他们要求特定的文件名或文件夹，请在阶段1中传递 --out 以进行 prepare，或者让他们稍后移动文件。不得将输出重定向到不同于 --out-root 指定的路径。
阶段 2 详细信息和单页模式
（此处省略，因为完整文件已被截断，但已包含所有关键信息）