Image to PPT

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

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

清理描边文字时同时检查内部浅色填充及外侧阴影；只清除轮廓不代表文字已移除。重建范围须覆盖实际文字清理边缘，不能仅依据原 OCR 框。修复背景中的条纹、残色和字影仍属于未通过状态。

环境

• 转换前必须阅读并执行 自动环境准备，完整仓库和仅安装 Skill 在 Windows、macOS、Linux 都自动准备缺失的 Python、Git、项目 Runtime、依赖、OCR、模型和所需渲染器。不得为依赖或模型安装向用户询问确认；遵循宿主实际审批与权限限制。

• Windows 新安装优先 D 盘，再选其他非 C 本地磁盘，仅在不存在其他本地磁盘时使用 C 盘；macOS/Linux 优先其他已挂载的本地磁盘，否则使用用户目录。使用 scripts/skill_environment.py 统一环境、模型、OCR、下载缓存与临时目录；复用已有可用环境和已验证模型。

• 使用 Python 3.10–3.12。仅有 Skill 时自动安装项目 Runtime，默认使用下文 Runtime Host Agent 流程处理图片、PDF 和 PPTX；不再要求使用者预先配置模型路径。

• 模型准备使用 image2editable models install runtime --yes，随后执行 image2editable doctor。LaMa 由本地 TorchScript adapter 调用，依赖 torch>=2.5.1,<3；SAM/LaMa/DINO 从已校验的 runtime receipt 解析。

• 原生 PDF 先复用 PowerPoint 或 LibreOffice，缺少时按自动准备流程安装；Windows PowerPoint 需要 image2editable[render-qa]。实际渲染校验通过后才能交付。

• 优先使用当前平台已正确安装的硬件加速环境；产品环境须通过 doctor，所有环境须通过下列设备预检。不要仅为 WSL 建议离开已经可用的环境：

  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 模型。已有 SAM2_MODEL、LAMA_MODEL 和 GROUNDING_DINO_MODEL 绝对路径可复用：前两者校验固定文件身份，DINO 目录视为操作者显式信任的 override。源码和权重不存放在此 skill 中。大/深遮罩需要 LaMa；依赖缺失或初始化失败时明确失败，不降级到容易产生条带拖影的 OpenCV 修复。

图片兼容命令行

以下接口仅处理图片；自动准备环境后默认使用下文 Runtime 流程，PDF/PPTX 必须使用 Runtime。

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

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 根目录导入：

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 模式

自动准备后的 Runtime 只支持 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。

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、manifest、资产哈希及文字增量依赖；可证明安全时，只清除新增文字覆盖的组件像素并更新背景，复用其余有效资产。并行准备同样必须使用新增文字清理后的图像；验证不足时才重新准备受影响的视觉结果。高置信冲突按确定顺序最多写入 96 条绑定 source SHA-256、稳定 candidate_id 和文字 bbox 的 unowned_raster_text；超出部分截断但页面仍硬失败。后续 native-check 必须与初始哈希证据中的 diagnostics 结构和内容完全一致。页级硬失败不解冻已通过叶组件；没有真实失败组件时产生的 preserved_with_warning 仍是内部未完成状态，应根据页级文字或背景缺陷继续恢复；不得把它作为交付终点。不要根据文件名、语言或具体标签添加特例。

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

{
  "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 保留了该结构的来源证据，也可使用 absorb_residual，仅恢复绑定残差，不恢复整个已停用复合对象，不调用 SAM；随后按需 rebuild_background。只有残差证据不足以确定结构时才使用 retry_with_box / retry_with_points。不得用 accept、discard 或将其归为背景来消除违规。当 background_text_residual 是唯一阻断项时，对诊断命中的冻结文字或视觉 ID 执行 rebuild_background。

split 先使用已有连通区域；当卡片底色连接了多个独立纯色图形时，可根据原图色块边界拆分，保留全部像素，不调用 SAM。parts 应对应实际完整单元，包含底色部分；不得按期望数量任意切块。文字框外的标点仍属于文字，先检查 OCR 内容与实际字形范围，不得用 absorb_residual 将其包装成图形。

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

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，也不能要求使用者修代码或重传文件。修复后重新验证内容完整性、图层可编辑性和实际渲染效果。

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