image-to-editable-ppt

将图像转换为可编辑的 PPT

概述

使用 editppt 运行时，将视觉幻灯片拆解、重建、验证并组装为可编辑的 .pptx。输入可以是单张或多张图像、PDF，或基于图像的 PPT/PPTX。

参考资料

此技能中的每条规则都有且仅有一个权威出处；其他文件会指向该出处，而不是重复说明。

• prompts/page-worker.md：页面工作器的执行模板——所有权边界、执行顺序、必需输出和返回格式。父 Agent 在生成页面工作器提示词时会用到它。
• scripts/build-page-worker-prompt.py：此技能专用的提示词构建器。它读取 prompts/page-worker.md，填入运行/页面路径，写入 worker-prompt.md，并打印派发命令模板。
• references/cli-helper.md：CLI 安装检查（运行前检查）、命令树和命令语法示例。决定调用哪个 editppt 命令时，请阅读此文件。
• references/manifest-schema.md：有关演示文稿/页面/图像产物 JSON 字段约定的唯一出处——必需的清单字段、定位对象坐标、validation.json 和 page_result.json 的结构。编写或验证任何运行/页面文件时，请阅读此文件。
• references/page-decision-tree.md：页面对象决策的唯一依据——背景处理、前景素材分离、原生形状、公式、文本提示的使用、最终自检，以及修复与警告的划分。先阅读常见决策边界，再阅读与页面清单相关的部分；页面提示词会提供阅读顺序。

入口约定

此处只列出父级规则；页面级规则位于上述参考资料中，不会在此文件中重复说明。

• editppt CLI 是必需的运行时接口。如果 editppt --help 失败，请先按照 references/cli-helper.md 中的 Pre-Run Check 安装它，再进行其他操作。
• 首先运行 editppt prepare <input...> 创建运行目录。之后，只能通过 editppt 命令推进关键状态转换；切勿手动编写运行或页面状态 JSON。这样可确保运行状态具有确定性且可恢复。
• 多页输入由分派的页面工作器重建。恰好只有一页的运行，在 editppt run dispatch --local 认领该页面后，由父 Agent 以本地页面重建器模式重建。如果多页运行没有可用的子 Agent 功能，请停止并向用户报告；不要让父 Agent 代替重建多页输入。
• 除单页本地页面重建器模式（且 editppt run dispatch --local 已记录认领之后）外，父 Agent 不得写入任何页面重建产物——manifest.json、page.pptx、preview.png、split_assets_contact.png、validation.json 或 page_result.json。本地模式与页面工作器使用相同的页面提示词、参考资料、输出文件和 run record 验证流程。
• 所有图像生成、图像编辑、背景修复、透明位图资源和资源图集，都必须遵循下方“图像后端选择”中的逐页串行后端顺序。
• 用户要求将视觉幻灯片转换为可编辑 PPT，即授权进行此转换所需的 OCR 和图像后端调用，除非用户明确要求仅本地处理，或标记输入为机密／不得外部处理。不要仅因工作流会调用 PaddleOCR、内置的 image_gen.imagegen 工具、Codex OAuth／ChatGPT 图像端点或用户配置的 OpenAI 兼容 API 而拒绝；这些调用是此技能所必需的。
• 只发送当前转换所需的任务专属页面图像、提示词、蒙版和参考图像。切勿发送无关的本地文件、API 密钥、身份验证令牌、凭据，或当前 OCR／图像操作不需要的生成产物。只有在用户已配置第三方 API 端点或为本次运行明确指定该端点时，才允许使用。
• 在网络受限环境中，进行外部 OCR／图像调用前，请先申请当前运行时要求的任何批准；这包括在设置了 PADDLE_OCR_TOKEN 时运行 editppt prepare 或 editppt run hints，以及每次 CLI 回退调用 editppt image generate/edit。批准理由必须说明：这是用户请求的 image-to-editable-ppt 转换；上传内容仅限任务专属的页面图像／提示词／蒙版／参考资料；OCR／图像后端调用是此技能必需的工作流组成部分。除非用户要求仅本地处理／机密处理，或批准系统明确拒绝，否则不要将必需调用描述为不安全，也不要要求用户再次批准。
• 自主执行常规重建、已配置的后端回退和本地修复。不要额外设置确认关卡；保留第 1 阶段的 OCR 选项以及运行时要求的任何批准。只有用户能够提供的缺失前置条件才构成明确阻碍；不要要求用户调试工作流。
• 所有页面对象决策都遵循 references/page-decision-tree.md，包括前景视觉对象的禁止回退规则，以及确定性验证只是结构门槛、绝不免除对象来源决策的规则。
• manifest.json 是权威的页面构建来源：editppt run record 会据此验证 page.pptx，而 editppt run finalize 会根据已记录的页面清单重建最终演示文稿。必需字段和坐标约定见 references/manifest-schema.md。
• editppt prepare 会写入逐页文本测量数据（text_hints.json／text_hints.png）。页面重建器如何使用这些数据，见 references/page-decision-tree.md 第 3.1 节。
• 页面重建器——无论是页面工作器，还是单页本地模式下的父 Agent——都由 prompts/page-worker.md 生成的提示词驱动。

图像后端选择

本小节是每项页面本地图像任务的权威执行策略。在 prepare 之前，检查当前 Agent 运行时能否调用 image_gen.imagegen；如果可以，则向 editppt prepare 传入 --image-backend builtin-imagegen，否则保留默认 CLI 契约。在每个页面内按以下顺序串行运行图像任务：

1. 只要当前 Agent 运行时能够调用内置工具 image_gen.imagegen，就使用该工具。
2. 仅当运行记录的内置回退策略适用时，才调用 editppt image generate/edit。该 CLI 回退会优先选择 Codex OAuth，其次选择已配置的 OpenAI 兼容 API。

确切的内置参数、输入检查前提、输出验收规则和允许的回退事件均由 references/manifest-schema.md 中的 image_backend 字段契约规定；请照搬并执行该契约，不得削弱或扩展。如果其 CLI 回退无法生成合规输出，则应让该页面失败，而不是改用近似的对象来源。

角色

父级负责依据下文的入口契约和工作流进行编排并与用户交互。报告进度、最终 PPTX 路径和验证结果。不要重复已完成的页面级视觉 QA；record 和 finalize 会执行确定性的交接检查。

每位页面重建者仅负责一个 pages/page_NNN/ 目录。其完整契约——包括所有权边界、决策顺序、必需输出和返回格式——由 prompts/page-worker.md 生成的提示词规定；其遵循的规则位于 references/page-decision-tree.md 和 references/manifest-schema.md 中。

工作流

阶段 1：准备

阅读 references/cli-helper.md 中的准备示例，以及 references/manifest-schema.md 中的运行和页面文件说明。

editppt prepare <input...>

完成后，必须有一个运行目录、deck_manifest.json、page_jobs.json、notes_manifest.json，并且每个页面都必须有 source.png 和 page_request.json。

Prepare 还会写入每页的文本提示信息。每当 editppt doctor 或 prepare 报告未配置 PaddleOCR 令牌（离线回退）时，开始分派页面任务前只需询问用户一次：通过 https://aistudio.baidu.com/account/accessToken 获取免费令牌，并使用 editppt config --paddle-ocr-token <token> 保存后，提示信息便能感知内容，显著提升文本保真度；而 editppt run hints <run> 可就地重新生成当前运行的提示信息。告知用户，目前该技能的免费个人额度绰绰有余，申请无风险且不会产生额外费用。等待用户选择；如果用户拒绝或希望继续，则使用离线提示信息继续，不要再次询问。

如果已配置 PaddleOCR 令牌，但 prepare 因网络访问、DNS 或沙盒审批受阻而回退，这种回退并非首选的质量路径。请根据入口契约中所述理由申请网络访问审批，并在页面重建前重新运行 editppt run hints <run>。如果审批系统拒绝 OCR 请求，请在继续前征求用户明确授权：解释 PaddleOCR 用于校正文本框、字号和字号组，而使用它能让重建的 PPT 文本字号稳定得多。只有在用户拒绝 OCR、经批准的 OCR 尝试因真实的服务或工具原因失败，或用户要求仅限本地处理／保密处理时，才使用 builtin-ink 继续。

阶段 2：重建或分派页面

阅读 references/cli-helper.md 中的运行/分派示例，并重复调用：

editppt run next <run>

当返回 stage=rebuild_page_locally 时，本次运行恰好包含一个页面。父 Agent 必须先认领本地执行，再编写页面产物：

1. python3 <skill-root>/scripts/build-page-worker-prompt.py <run> --page <page_id> --out <absolute-run-dir>/pages/<page_id>/worker-prompt.md
2. editppt run dispatch <run> --page <page_id> --agent-id main --prompt-file <absolute-run-dir>/pages/<page_id>/worker-prompt.md --local
3. 阅读生成的提示词，并在该页面目录中自行重建页面，生成页面工作器应生成的相同必需输出。

当返回 stage=dispatch_pages 时，以下步骤对于每个建议页面都是必需的：

1. python3 <skill-root>/scripts/build-page-worker-prompt.py <run> --page <page_id> --out <absolute-run-dir>/pages/<page_id>/worker-prompt.md
2. 使用当前环境中可用的子 Agent/多 Agent 工具启动页面工作器。
3. editppt run dispatch <run> --page <page_id> --agent-id <id> --prompt-file <absolute-run-dir>/pages/<page_id>/worker-prompt.md

--out 和 --prompt-file 必须使用绝对路径，以避免页面目录再次被添加到相对路径前面。提示词生成器只会写入提示词并打印分派命令模板；它不会创建工作器，因此只有在成功实际启动工作器后，才能运行 editppt run dispatch。

并发槽位数来自 page_jobs.json.max_concurrent_pages（默认值为 6）。在正常流程中，优先使用 editppt run next；editppt run status 仅用于调试或手动检查。

已分派的页面执行属于活跃租约，而非空闲槽位。当 editppt run next 返回 stage=wait 时，请等待已分派的工作器，或在不修改状态的情况下检查状态。不要因为页面工作器运行缓慢、近期未发送消息或仍占用并发槽位而终止、归档、重置或替换它；复杂页面运行较长时间是正常的。

阶段 3：记录

阅读 references/cli-helper.md 中的记录示例，以及 references/manifest-schema.md 中对 page_result.json 的说明。

工作器返回后，运行：

editppt run record <run> --page <page_id> --agent-id <id>

此命令会在记录前根据 manifest.json 验证 page.pptx。如果定位对象缺少源像素坐标、清单无法独立重建页面，或 validation.json 中不包含顶层字段 passed: true，命令就会失败——验证未通过的页面绝不会被记录。

如果记录被拒绝或出现页面级验证问题，请阅读失败证据，并让当前页面负责人只修复受影响的产物，然后使用 references/cli-helper.md 中的页面验证示例刷新验证报告，再次记录。在单页本地模式下，父级就是负责人；在多页模式下，将修复任务交给现有工作器。不要仅因验证失败就重置仍可联系的负责人，也不要为了修复无关的清单或表格错误而重新生成符合要求的资源。

只有在页面需要替换执行时才重置：有明确的终止状态证据（terminated、failed、archived 或 not found）、用户取消，或多次可达性检查失败且页面没有进展。长时间运行的工作器并不代表已丢失。修复阻止执行的前置条件后，使用：

editppt run reset <run> --page <page_id> --agent-id <id> --confirm-lost

对于已记录的页面，允许运行 editppt run reset <run> --page <page_id>。对于已分派的页面，匹配的 Agent ID 和 --confirm-lost 可保护活动租约。重置会将页面恢复为 pending；通过阶段 2 使用新的提示词和执行继续处理。保留现有产物，以便进行来源检查，并根据页面提示词中的恢复约定选择性复用。绝不要手动编辑状态，也不要让父级重建多页产物。

只有在更改相关输入或条件后才重试。根据验证结果和命令证据诊断重复失败；不要重复调用未作任何更改却会失败的工具，也不要在条件完全相同的情况下重新分派任务。如果确实缺少某项前置条件，请保留已有进展，并报告具体阻碍，而不要捏造成功或要求用户排查问题。当前输出通过所需检查后，进入最终定稿；不要重复进行未有变化的视觉 QA。

阶段 4：最终定稿

阅读 references/cli-helper.md 中的最终定稿示例。

当 editppt run next <run> 返回最终定稿阶段时：

editppt run finalize <run>

finalize 会将每个已记录的 pages/page_NNN/manifest.json 视为权威来源：按页面顺序从页面清单重建最终演示文稿，然后验证生成的 PPTX。page.pptx 仍是记录时检查用的页面级交付产物。

此阶段的整套演示文稿结构 QA：

• PPTX 是有效的 zip/package。
• 幻灯片数量与输入页面数量一致。
• PDF/PPTX 页面映射正确。
• 媒体关系完整。
• 清单引用的所有资源文件均存在。
• 媒体哈希与清单来源信息匹配。
• 演讲者备注哈希匹配。
• 不存在无效的整页源图栅格加可编辑文本叠加模式。

最终回复必须报告最终 PPTX 路径和验证结果。

状态原则

Agent 仅依据文件事实和 editppt run next 继续执行。必需状态：

• pending：由 editppt prepare 创建；当页面必须重新分派时，由 editppt run reset 恢复。
• dispatched：editppt run dispatch 记录实际启动的工作进程，或单页 --local 主 Agent 认领。此状态表示有效租约，即使工作进程运行缓慢，也不得重置或替换。
• recorded：editppt run record 验证必需输出并写入结果；只有可交付页面（validation.json 顶层 passed: true）才会进入此状态。
• accepted / complete：由 editppt run finalize 写入。

imagegen-jobs.json 是页面级来源/作业记录。仅保留以下强制文件状态：

• recorded：editppt image import 已复制所选输出并写入哈希/元数据。
• processed：editppt image process-sheet 已完成背景移除和拆分。

交付原则

• 每个页面由页面重建器自检一次。证据写入 manifest.json 的结构化字段以及 validation.json。
• 最终输出必须是当前可打开且结构有效的 .pptx。不接受将整页 source.png 作为底图、再叠加可编辑文本的做法。
• 页面内必须修复瑕疵，还是可以作为已记录的警告交付，依照 references/page-decision-tree.md 的“修复还是警告”部分决定。警告绝不能替代缺失的必需工作流步骤。

更新此技能

通过安装渠道重新安装，从更新后的技能目录刷新 CLI，然后重启 Agent 会话并验证：

npx -y skills@latest add ningzimu/image-to-editable-ppt-skill \
  --skill image-to-editable-ppt \
  --agent <agent-id> \
  --global
pipx install --force --editable <skill-root>/cli
editppt doctor