---
name: image-to-ppt
description: 将图片、PDF、图片版 PPTX 或含原生对象的混合 PPTX 转换为严格质量校验、分层可编辑的 PowerPoint；保留既有原生文字、形状、表格和图表，并使用宿主视觉 Agent 完成组件决策。用于截图、设计稿、科研图和幻灯片页面的组件重建、残影检查与可编辑输出。
---

# Image to PPT

把输入图片重建为分层可编辑 PPTX。质量未达标时，根据具体缺陷继续修复并重新验证；不得将整页 flatten 为单张图片，也不得将仅能打开的文件当作合格成品。

全部文字（包括艺术字）必须为可编辑文字，保留原有曲线、描边和多色。文字截图、转曲轮廓、透明文字叠在原字图上均不满足该要求。复用已验证的 OCR 和组件资产，只对存在缺陷的区域继续处理；渲染与编辑验收未通过时，不宣称转换完成。

清理描边文字时同时检查内部浅色填充及外侧阴影；只清除轮廓不代表文字已移除。修复背景中的条纹、残色和字影仍属于未通过状态。

## 环境

- 本 Skill 在转换前自动完成必要环境准备。依赖或 OCR 缺少时直接安装固定版本；产品 Runtime 模型缺少时直接安装并校验。不得为依赖或模型安装向用户询问确认，已满足的项目直接跳过。
- 使用 Python 3.10–3.12；该范围与当前项目测试和分发契约一致。
- 先解析当前 `SKILL.md` 所在目录为绝对路径 `<skill-root>`。缺少转换依赖时，运行 `python -m pip install -r "<skill-root>/references/requirements.txt"`，安装 `torch>=2.5.1`、`torchvision>=0.20.1`、Transformers 和 SAM 2.1；不得依赖调用者的当前工作目录。
- LaMa 由内置的本地 TorchScript adapter 调用，依赖随 `references/requirements.txt` 中的 `torch>=2.5.1,<3` 安装。产品安装默认从已验证的 runtime receipt 解析模型；独立 skill 必须通过绝对路径设置 `LAMA_MODEL`，且文件须匹配固定 Big-LaMa 身份。
- OCR 不可用时，默认运行 `python -m pip install "paddleocr==3.7.0" "paddlepaddle==3.3.1" "PaddleX==3.7.2" "PyYAML==6.0.2"`。PaddleOCR 是本 Skill 的固定默认 OCR，覆盖中文、英文和复杂版面，不再停下来要求用户选择 OCR 实现。
- 完整仓库或已安装 `image2editable` 产品包时，依次运行 `image2editable models install runtime --yes` 和 `image2editable doctor`。前者以非交互方式下载并校验固定的 SAM、LaMa、DINO runtime receipt。
- 纯 standalone 环境中，独立 skill 不假设该包存在，也不运行 `image2editable doctor`。开始转换前，必须把 `SAM2_MODEL`、`LAMA_MODEL` 和 `GROUNDING_DINO_MODEL` 设置为绝对本地路径；`SAM2_MODEL`、`LAMA_MODEL` 必须指向文件，`GROUNDING_DINO_MODEL` 必须指向目录，并运行最小只读预检：

  ```bash
  python -c "import os; from pathlib import Path; names=('SAM2_MODEL','LAMA_MODEL','GROUNDING_DINO_MODEL'); raw={name: os.environ.get(name, '') for name in names}; paths={name: Path(value) for name, value in raw.items()}; assert all(raw.values()) and all(path.is_absolute() for path in paths.values()) and paths['SAM2_MODEL'].is_file() and paths['LAMA_MODEL'].is_file() and paths['GROUNDING_DINO_MODEL'].is_dir(); print('runtime model paths: ok')"
  ```
- 纯 standalone 不包含模型下载器。任一模型路径缺失时，列出缺少的环境变量并停止；standalone 不得安装或切换到产品 Runtime。系统权限、网络策略或下载校验失败时，报告原始阻塞，不反复询问安装许可，也不伪装为安装成功。
- 优先使用当前平台已正确安装的硬件加速环境；产品环境须通过 `doctor`，所有环境须通过下列设备预检。不要仅为 WSL 建议离开已经可用的环境：

  ```bash
  python -c "import sys, torch; print({'platform': sys.platform, 'cuda': torch.cuda.is_available(), 'rocm': torch.version.hip})"
  ```

- Windows/Linux 沿用 PyTorch 的设备接口：PyTorch 报告 CUDA 可用时使用 CUDA，ROCm 环境使用 PyTorch 提供的兼容设备接口。
- macOS 保持当前受支持的设备选择；在完成真实 Apple Silicon 回归前，不把 MPS 自动设为新默认。
- CPU 仍运行完整模型和相同质量门禁，包括 SAM 2.1 large，不替换为轻量分割模型，但推理会显著较慢。

推理不会下载模型或回退 Hugging Face cache。产品环境先安装并验证 runtime 模型；独立 skill 必须把 `SAM2_MODEL`、`LAMA_MODEL` 和 `GROUNDING_DINO_MODEL` 设置为绝对本地路径，其中前两者校验固定文件身份，DINO 目录视为操作者显式信任的 override。源码和权重不存放在此 skill 中。大/深遮罩需要 LaMa；依赖缺失或初始化失败时明确失败，不降级到容易产生条带拖影的 OpenCV 修复。

## 命令行

从 skill 根目录执行 module，不要直接运行 `scripts/image_to_ppt.py`：

```bash
cd skills/image-to-ppt
python -m scripts.image_to_ppt input.png
python -m scripts.image_to_ppt input.png --slide-size original
python -m scripts.image_to_ppt input.png --slide-size 16:9
python -m scripts.image_to_ppt input.png --slide-size both
python -m scripts.image_to_ppt img1.png img2.png -o slides.pptx --slide-size both
python -m scripts.image_to_ppt input.png --lang en --reference
```

CLI 默认 `--slide-size both`。单图输出 `<stem>_original.pptx` 和 `<stem>_16x9.pptx`；批量输出 `<base>_16x9.pptx`，并在 `<base>_original/` 中为每张输入生成原比例单页 PPTX。`--period`、`--diff-threshold` 和 `--min-area` 仅为兼容保留，strict SAM 管线会忽略它们。

## Python API

从 skill 根目录导入：

```python
from scripts.image_to_ppt import (
    convert,
    convert_batch,
    convert_batch_variants,
    convert_variants,
)

convert("input.png", output_path="output.pptx")
convert_variants("input.png")
convert_batch(["img1.png", "img2.png"], output_path="slides.pptx")
convert_batch_variants(["img1.png", "img2.png"], output_path="slides.pptx")
```

旧 `convert()` 保持兼容：默认返回单个 16:9 PPTX 路径字符串；CLI 默认输出两种尺寸。

## Runtime Host Agent 模式

完整仓库环境只支持 `host` Provider。Provider 写入 Run 后不可切换；单个组件修复周期最多五轮，使用同一套严格组件动作和质量门禁。检测到无进展或重复产物时停止该无效策略，复用有效资产并切换针对性修复，不重复耗尽轮数。

当前 Codex、Claude Code 等宿主必须支持视觉识别、本地文件读取、工具调用和结构化 JSON。Runtime 直接使用当前 AI，不探测、加载、下载或要求配置其他组件决策模型。

Host 可能把诊断图交给宿主服务处理；处理敏感内容前，确认宿主服务的数据策略符合要求。该 Provider 当前保持 `experimental`，直到使用相同真实文件完成视觉、结构和资源验收。

每张图片、每一页都必须重新查看证据并独立决策，不能跨图片套用拆分决策。

Host 运行先准备并推进到 `awaiting_agent`：

对 PPTX，`prepare` 后循环调用 `run next`。每个非 `null` 的 `candidate` 都必须查看 `image_path`，按 `--page candidate.page_id --object candidate.source_shape_id` 执行 `decision record`，然后继续 `run next`。仅当返回对象的 `candidate` 字段为 `null` 时才退出路由循环，随后首次执行 `run execute`。进入 `awaiting_agent` 后，再循环执行 `agent next`、`agent record` 和 `run execute`。

```bash
image2editable prepare input.pptx --run-dir runs/pptx-job --agent-provider host
image2editable run next runs/pptx-job
# candidate 非 null：查看 image_path；--page candidate.page_id --object candidate.source_shape_id
image2editable decision record runs/pptx-job \
  --page candidate.page_id --object candidate.source_shape_id \
  --decision replace --confidence 0.96 \
  --category full_slide_screenshot \
  --evidence "complete slide layout"
# 对每个后续非 null candidate，重复 decision record，然后继续 run next
image2editable run next runs/pptx-job  # 响应对象的 candidate 字段为 null，退出路由循环
image2editable run execute runs/pptx-job
image2editable agent next runs/pptx-job
image2editable agent record runs/pptx-job --plan response.json
image2editable run execute runs/pptx-job
```

第一次 `agent next` 返回视觉 challenge。必须实际查看 `image_path`，把观察到的 `shape/color/count` 写入 `host_capability_response` 后记录；不能从 metadata 或文件名猜答案。后续 `agent next` 返回当前组件请求及绝对证据路径。必须先验证并遵循完整 request、组件图、evidence map、全部 hash、候选和冻结状态，只查看并逐项核验 request 的有序 `review_evidence`，不得再按固定文件清单重复打开未列入本轮审查的图片。首轮 `review_evidence` 仍包含全部视觉证据；后续轮的 `round-review.png` 以相同坐标提供本轮失败或重开节点及依赖邻居的 source、isolation、ownership、reconstructed、difference 和 residual 无损视图。若 request 回退为完整 `review_evidence`，必须逐项查看；`quality-report.json` 仍作为完整质量证据读取，不能当图片发送，也不得跳过任何质量门禁。再生成绑定当前 `request_sha256` 的严格 `component_plan`。Agent confidence 不能放宽硬失败。

当前单个组件修复周期最多 5 个批次。已通过组件冻结；失败子组件可折叠为完整父组件。`preserved_with_warning` 是内部未完成状态，不是交付结果，不能以此结束转换。继续定位缺陷、复用有效资产并采用不同修复策略；不得重置历史后重复无效动作，也不得用清空组件或栅格文字换取成功。文字必须全部由原生可编辑文本框贡献且仅出现一次；视觉组件和背景不得残留文字像素。重建组件通常是透明图片对象，不承诺把任意图形转换为原生矢量或 SmartArt。

prepare 会在全页 OCR 和首轮视觉候选完成后，对小型候选做两个最长边分别不超过 512 与 448 像素的确定性视图串行 OCR。比较文本只做 NFKC、casefold 和去空白，不删除语义标点；同候选多项文字按页坐标一一匹配，已知文字逐项去重，一致项逐条回灌并从 source 重建全部资产。高置信冲突按确定顺序最多写入 96 条绑定 source SHA-256、稳定 `candidate_id` 和文字 bbox 的 `unowned_raster_text`；超出部分截断但页面仍硬失败。后续 native-check 必须与初始哈希证据中的 diagnostics 结构和内容完全一致。页级硬失败不解冻已通过叶组件；没有真实失败组件时产生的 `preserved_with_warning` 仍是内部未完成状态，应根据页级文字或背景缺陷继续恢复；不得把它作为交付终点。不要根据文件名、语言或具体标签添加特例。

重叠文字冲突先复用整行识别上下文。isolated targeted OCR 仅对冲突区域做两尺度识别，复用 text-context-cache 中与像素、语言和 OCR 实现匹配的结果；读法分歧也不重复推理。跨栏的完整检测不能覆盖已有独立栏位、字号和颜色。原生 runs 支持字符位置、填充及描边，但自动样式估计不能代替实际渲染与编辑验收；未覆盖的字体、曲线及栅格残字问题仍须处理。

```json
{
  "schema_version": 1,
  "kind": "host_capability_response",
  "challenge_id": "agent next 返回的值",
  "observed": {"shape": "circle", "color": "#2b8a3e", "count": 3}
}
```

组件计划固定包含 `schema_version/kind/page_id/provider/repair_round/request_sha256/actions`；每个 action 固定包含 `action/object_ids/parameters/confidence/evidence`。只使用请求组件图中的候选 ID；`collapse_to_parent` 和 `absorb_into_parent` 可使用候选子组件关联的父 ID。既定十四类动作包括 `accept/discard/merge/split/expand/shrink/retry_with_box/retry_with_points/attach_text/suppress_text/collapse_to_parent/rebuild_background/absorb_residual/absorb_into_parent`，不添加未知字段。`accept`、`retry_with_box` 和 `retry_with_points` 仅在视觉证据确认对象是可单独移动的视觉元素、而非当前语义父级的子组件时，才可在既有参数中额外写入 `"independent": true`；不得按固定面积自动解除父关系。`rebuild_background` 可把已冻结视觉组件列为仅清理背景重复像素的对象，不得改变其冻结资产。

当 `quality-report.json` 包含 `unexplained_visual_residual` 时，必须查看 `unexplained-mask.png`。每个显著区域都必须由 active visual owner 覆盖；若区域是候选边界框内经验证的结构碎片，使用 `absorb_residual` 将绑定残差精确并入最小包含候选；否则对最接近的 inactive visual candidate 执行 `retry_with_box` / `retry_with_points`。不得用 accept、discard 或将其归为背景来消除违规。当 `background_text_residual` 是唯一阻断项时，对诊断命中的冻结文字或视觉 ID 执行 `rebuild_background`。

PPTX 的整页截图候选先使用决策路由：

```bash
image2editable run next runs/pptx-job
image2editable decision record runs/pptx-job \
  --page page_001 --object 7 \
  --decision replace --confidence 0.96 \
  --category full_slide_screenshot \
  --evidence "complete slide layout"
```

每次先查看 `run next` 返回的绝对 `image_path`。只有图片覆盖大部分页面、包含标题/多个文字区/图表或卡片等完整页面结构，且明显不是照片、Logo、头像或装饰素材时，才记录 `replace + full_slide_screenshot`。证据冲突或不确定时记录 `preserve` 或 `ambiguous`；不要为了提高拆分数量抬高置信度。

组件计划必须以可独立移动的最小完整视觉单元为单位。使用反事实标准：单独移动一个单元后，该单元及其余视觉单元是否仍各自完整；语义相关不构成合并理由。`component-isolation.png` 中沿 OCR 字形出现的透明孔洞，或本应连续的底色、填充、线条缺失，都属于残缺分割而不是成功去字；若失活父组件能恢复同一完整视觉单元，应使用 `collapse_to_parent`，同时保留可独立移动的高层组件且不得恢复源字形。质量报告出现 `contained_parent_review` 时，必须使用质量证据中的精确 `contained_parent_pairs` 对照两个隔离单元：若一个只是重复子集，选择唯一像素所有者并丢弃重复层；若两者确实都是可独立移动的视觉单元，双方必须分别使用 `accept`、置信度不低于 `0.92`，且每条 evidence 都把该 pair 的两个精确 ID 作为两个独立字符串列出，才允许共同保留，否则门禁继续硬失败。对被更完整组件覆盖、没有独立编辑价值的重复候选使用 `discard`。`absorb_into_parent` 只允许合并同一物理实体的重复掩码、碎边、阴影或分割缺口证据，禁止把多个可独立移动对象烘焙为一张父图；语义父级只用于分组，不参与最终像素渲染。仅当外缘画布颜色一致且证据显示背景残影时使用 `rebuild_background`，`margin_ratio` 必须在 `(0, 0.1]`。OCR 文字以冻结的 `text_XXXX` 节点出现，可作为 `attach_text` 的第二对象；只有视觉证据足以明确证明 OCR 候选实际为非文字时，才可对该文字节点使用 `suppress_text`，不确定或真实文字不得抑制。被抑制文字会从后续可编辑文字、文字蒙版、质量检查和 PPTX 中移除，并以该 OCR 边界框执行同质量 SAM，生成必须继续通过质量门禁的独立视觉候选；文字区域不能挖透明文字框，也不能只留在背景。任何动作仍需通过确定性重建、独占像素、残影/重影/缺损和 PPTX reopen 门禁；Agent 置信度不能放宽硬失败。

Runtime 只有在 `confidence >= 0.92` 时才重建完整截图。通过门禁后只原位替换命中的截图对象；既有原生文字、形状、表格、图表、备注、z-order、其他页面和未命中图片保持原生。未通过页面的 warning 是内部未完成状态；继续处理缺陷，不把保留原截图的页面作为已完成的可编辑交付。

`rebuild_background.margin_ratio` 必须由 Agent 根据当前残影和抗锯齿范围自适应选择：使用能完整覆盖残影、又不触及相邻结构线的最小值，禁止固定使用同一数值。

## 严格管线

1. 使用现有 OCR 逻辑检测文字并生成文字遮罩。
2. 使用 Grounding DINO 与 SAM 生成首轮视觉候选；对未被文字遮罩覆盖的小候选做资源有界的双视图 OCR，安全恢复后从源图重跑完整视觉准备。
3. 使用 Grounding DINO 生成整图与重叠分块语义候选，再用 SAM 2.1 生成对象掩膜，并以无提示 SAM 候选覆盖词表外对象。
4. 对候选去重，解析父子关系，为每个像素建立唯一 ownership；结合语义支撑和定向 SAM 复查修补组件内部破洞。
5. 导出不含文字的独立透明组件；小/窄遮罩用 OpenCV 修复背景，大/深遮罩用 LaMa。
6. 按实际导出的 RGBA 图层重建页面，执行严格视觉质量 QA。
7. 组装原比例或 16:9 画布；16:9 使用 contain 居中和四角/边缘颜色渐变，不使用模糊放大的原图副本。

## 输出与自动修复

每页从底到顶包含 clean background、可独立移动的透明组件和可编辑文本框。

命令会在处理每张图片前打印绝对 work directory。质量异常包含 `mae`、`p95` 和 diagnostics 绝对路径，供宿主检查 `source.png`、`ownership.png`、`reconstructed.png` 和 `report.json` 并执行修复；诊断不能代替最终 PPTX，也不能要求使用者修代码或重传文件。修复后重新验证内容完整性、图层可编辑性和实际渲染效果。

已有有效资产和已通过组件必须复用。比较输入及输出内容，识别重复状态和循环；有实际进展的任务不因总耗时较长而放弃。不得放宽门禁、删内容、伪造通过记录或用整页图片换取成功。当前运行时仍存在修复轮次耗尽后无法继续的路径；遇到该情况属于尚未完成的交付能力，须修复转换器并补通用回归，不能声称已完成转换或具备发布条件。用户主动取消时停止处理并保留恢复依据。