Image to Editable PPT

Overview

这个 skill 用于把视觉型幻灯片输入重建成对象级可编辑的 PowerPoint .pptx。

输入可以是一张图片、多张图片、PDF、图片版 PPT/PPTX。输出始终是 .pptx。目标不是把整页截图包进 PPT，而是尽量让可读文字成为原生 PowerPoint 文本框，让基础结构成为原生形状，让复杂视觉元素成为独立图片资产，并用 manifest、预览和验证报告保证结果可检查、可返工。

默认取舍：对象级可编辑率优先。宁可视觉略粗糙，也不要用整页 raster 冒充可编辑 PPT。

Hard Constraints

• 每一个来源页面都必须由 page subagent 重建，包括单张图片输入。
• 主 agent 不做页面重建，只做 orchestration。
• 不设计父 agent 单独执行、顺序降级执行或低保真降级模式。没有可用 page subagent 就停止，不进入页面重建。
• 所有生图、改图、背景修复、透明 bitmap 资产和 asset sheet 都必须使用 $imagegen skill。
• $imagegen 的默认路径是 built-in image_gen。不要在本 skill 里直接调用 Image API。
• 如果页面需要 $imagegen，但 $imagegen 或 built-in image_gen 不可用，停止该页并报告 blocker，不伪造资产。
• 原始整页 source.png 加可编辑文本覆盖是失败模式，不是 fallback。
• 只有基础 primitive 和简单结构对象可以用原生 PPT shape。非文字视觉对象不确定时，默认用 $imagegen 重绘成独立资产。
• page worker 必须先做文字字号、视觉对象、背景策略和形状角形的清单校准，再写 manifest；不能靠审美猜测默认字号或默认圆角。
• 关键状态只能由脚本推进。agent 不能手写 JSON 把 page、imagegen job 或 run 标成完成。

Visible Progress Plan

正常运行时，主 agent 必须保持一个用户可见 checklist，同一时间只有一个 active step：

1. 准备输入和任务目录。
2. 分派页面重建。
3. 重建页面对象。
4. 检查并修复页面。
5. 组装和验证 PPTX。

完成条件：

• 准备输入和任务目录：deck_manifest.json、page_jobs.json、pages/page_NNN/source.png、notes_manifest.json 已存在。
• 分派页面重建：主 agent 按 max_concurrent_pages 分批 spawn page subagent；每个已 spawn page 都由 record_page_dispatch.py 记录为 dispatched。如果不能继续 spawn subagent，停在这里并报告 blocker。
• 重建页面对象：每个 page 都由 page worker 产出 manifest.json、page.pptx、preview.png、split_assets_contact.png、validation.json、page_result.json。
• 检查并修复页面：所有 page 通过 record_page_result.py 记录，repair queue 清空；无法修复时报告 blocker。
• 组装和验证 PPTX：final/<origin>_edited.pptx 和 final/validation.json 已存在。

不要只因为聊天里说完成就标记步骤完成；必须有真实文件或脚本推进的状态。

Default Workflow

1. 运行 prepare_deck_run.py 创建 run 目录、归一化输入、生成 deck/page manifest 和 page request。
2. 运行 page_job_status.py 查看待分派页面、active dispatches 和可用 dispatch slot。
3. 主 agent 按 max_concurrent_pages 分批 spawn 普通 Codex worker subagent；不要一次性 spawn 超过运行时并发上限。
4. spawn 后立即运行 record_page_dispatch.py 记录 dispatch。
5. 每个 page worker 只在自己的 page 目录内工作，完成 page-level build、preview、contact sheet、validation。
6. page worker 返回后，主 agent 运行 record_page_result.py 检查文件、路径和 hash，并推进 page 状态。
7. 再次运行 page_job_status.py；如果还有 pending/repair_needed page，就继续下一批分派。
8. 如有页面问题，运行 queue_page_repairs.py 生成 repair item，再分批分派 repair worker。
9. 所有 page accepted 后，运行 finalize_deck_run.py 组装最终 PPTX、复制 notes、运行 deck validation 和 QA summary。

正常主入口是 prepare_deck_run.py。不再保留旧输入归一化脚本作为公开入口或兼容 wrapper。

Generation Delegation

使用 $imagegen 前必须读取并遵守：

${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/SKILL.md

本 skill 只组合 $imagegen，不重新定义图片生成 API 规则。

页面内需要 $imagegen 的常见场景：

• complex background 上有文字、图标或前景对象，需要 source-preserving foreground removal + localized background restoration。
• 图标、pictogram、徽章、贴纸、手绘标记、风格化箭头、装饰符号等需要作为独立资产。
• 需要生成 chroma-key asset sheet，再本地去底、切分、透明化。
• 需要 targeted repair 某个 clean base 或某个前景资产。

项目实际使用的生成图片必须复制到 page 目录，并通过 page-local imagegen-jobs.json 记录。不要让 manifest 引用只存在于 $CODEX_HOME/generated_images/... 的图片。

复杂背景默认保留 source identity。可以用 $imagegen 生成 clean background，但必须把 source 当作 edit target 和强约束参考来修复/重建，不能生成一个“同类但不同”的新背景。遮挡少时优先局部修复；遮挡多或需要整张 clean base 时，也必须保留原始构图、透视、主要物体位置、色彩、光照和背景细节，并在 manifest 的 background_strategy 里记录保真策略。

Subagent Dispatch

page subagent 是唯一的页面重建执行者。主 agent 不重建页面。

每个 page worker 必须收到自包含 prompt，至少包含：

• run dir、page id、page dir、source image 绝对路径。
• 允许写入范围：只能写当前 page dir。
• 禁止写入范围：deck manifest、notes manifest、final deck、其他 page。
• 必读 reference：page-decision-tree.md、imagegen-integration.md、manifest-schema.md、qa-rubric.md。
• 必读 $imagegen/SKILL.md。
• required outputs 和返回格式。

page worker prompt 模板在 prompts/page-worker.md。

如果无法 spawn page subagent，停止并报告 blocker。不要顺序执行页面重建。

Rules

• 文字：所有可读文字都应成为可见原生 PPT text box。隐藏、透明、1 pt、off-canvas 或 metadata-only 文本不算可编辑文字。
• 字号：先根据 source 字形高度、容器高度和同行密度估算，再用 preview 对照缩放；不确定时偏小而不是偏大。manifest 必须记录 quality_checks.font_size_calibrated=true。
• 结构：只有基础 primitive 可以用原生 PPT shape，例如直线、矩形、圆形、表格线、坐标轴、简单柱状块、基础容器。矩形容器默认用 rect；只有 source 明确是圆角时才用 roundRect，并记录 source_corner_radius_px 或 corner_reason。
• 前景：图标、pictogram、logo-like mark、手绘标记、贴纸、徽章、复杂箭头、装饰元素默认用 $imagegen 重绘成独立资产。若源图里的小型视觉对象需要高度一致、无可读文字、且重绘会改变身份，可作为独立 source-derived raster asset 裁出并记录来源区域；这不是整页截图 fallback。
• 背景：纯色、简单渐变、规则网格、普通卡片可用原生或脚本重建；复杂照片、纹理、插画被前景遮挡时，用 $imagegen 做 inpainting/restoration。
• asset sheet：默认用稀疏 chroma-key asset sheet 减少生图次数。元素间距优先，不能拥挤、粘连、互相投影。
• provenance：每个最终 raster asset 都必须有来源记录。不能把原始 source crop 当成默认视觉资产。
• QA：确定性 validation 必要但不充分。必须检查 preview.png 和 split_assets_contact.png。
• repair：修最小失败范围。不要为了一个文本框或一个图标重建整页。
• 状态：page_jobs.json、imagegen-jobs.json 的关键状态必须由脚本推进。

Acceptance Criteria

• 输出是有效 .pptx。
• 单图输出 1 页；多图每图 1 页；PDF 第 N 页对应输出第 N 页；PPT/PPTX 第 N 页对应输出第 N 页。
• PPT/PPTX speaker notes 按页原样复制，不翻译、不摘要、不交给 page worker 改写。
• 每页有 manifest.json、page.pptx、preview.png、split_assets_contact.png、validation.json、page_result.json。
• 每页 source image size、text inventory、object decisions、asset provenance、known limits 都有记录。
• 每个 page 都由 record_page_dispatch.py 记录 dispatch，并由 record_page_result.py 记录结果。
• 最终 deck 有 final/<origin>_edited.pptx 和 final/validation.json。
• 若出现 blocker，最终回复必须说明 blocker 阶段、证据路径和未完成原因；不能称为正常完成。

Reference Map

• references/architecture.md：职责边界、run/page 目录结构、owner 原则。
• references/state-machine.md：run/page/imagegen 状态机和脚本推进规则。
• references/subagent-contract.md：page worker、repair worker 的提示词契约和返回格式。
• references/imagegen-integration.md：如何组合 $imagegen，包括 clean base、asset sheet、透明化和记录。
• references/page-decision-tree.md：页面分析、背景策略、前景/结构对象边界。
• references/manifest-schema.md：deck/page/imagegen JSON schema 第一版。
• references/qa-rubric.md：结构、文字、资产、背景、视觉 QA 标准。
• references/repair-policy.md：repair queue、最小返工范围和 blocker 判定。
• references/script-contracts.md：脚本职责、输入输出和允许调用者。
• prompts/page-worker.md：普通页面重建 worker prompt。
• prompts/page-repair-worker.md：页面修复 worker prompt。
• prompts/imagegen-clean-base.md：clean base 生成/编辑 prompt。
• prompts/imagegen-asset-sheet.md：稀疏 asset sheet prompt。
• prompts/imagegen-repair.md：targeted imagegen repair prompt。