Gpt Image2 Ppt

外部真实图片贴入（推荐精确流程）

默认规则：用户提供真实图时，优先按原图保真后贴，不要让 gpt-image-2 重画这张图。使用 slide_spec 声明外部图片槽位：

这套流程只在元素声明了 type: "external_image" / image_overlay / external_image_placeholder 且 source 能解析到真实本地图片文件时启用。没有真实图片 source 的普通生成、模板克隆、纯占位布局和老的自由风格生成不受影响。

如果用户明确说“更重视画面融合效果，不需要一定贴原图 / 可以重绘 / 可以图生图”，可以走参考图模式：把图片作为 generation reference 输入给模型，而不是最终独立后贴。此时版面通常更融合，但不保证像素级保真，PPT 里也不会有可单独选中的原图对象。

参考图模式可用 type: "image_reference"，或在 external_image 上显式写 render_mode: "reference" / preserve_original: false：

{
  "elements": {
    "mood_reference": {
      "type": "image_reference",
      "source": "/absolute/path/to/photo.png",
      "purpose": "只作为视觉参考，允许模型融合重绘，不作为独立 PPT 图片对象后贴"
    }
  }
}

不要对高精度素材使用参考图重绘：医疗影像、病理图、诊断依据、实验/工程读数、财务表格、论文图表、法律证据截图、产品 UI 精确截图等都应默认走 external_image 保真后贴，并在交付前提示用户核对。

{
  "elements": {
    "hero_photo": {
      "type": "external_image",
      "source": "/absolute/path/to/photo.png",
      "layout_intent": "auto",
      "tailor_to_asset": true,
      "slot_strategy": "fit-within",
      "fit": "contain",
      "slot": {
        "padding": 0.012,
        "bleed": 0,
        "fill": "#F7F7F5",
        "mask_placeholder": false,
        "sanitize_background": false,
        "draw_frame": false,
        "outline_width": 0,
        "skeleton_canvas_fill": "transparent",
        "skeleton_fill": "transparent",
        "skeleton_shape": "corners",
        "skeleton_outline": "#000000",
        "skeleton_outline_width": 2,
        "skeleton_ticks": false
      }
    }
  }
}

生成时脚本会自动做四件事：

1. 先规划槽位，再生成 skeleton。脚本会优先读取模板 profile 里的 external_image_slots，或根据模板摘要推断“左图右文 / 右图左文 / 底部图表 / 中央主视觉”等候选区域；然后结合本页文字量、标题长度、真实图片数量、真实图片宽高比和素材分类（照片 / 图表 / 文档 / 架构图等）打分选位，先产出 position / computed_bbox / auto_layout_reason / layout_planning_profile。skeleton 只是把这个规划结果画给模型看，不负责临时想位置。
2. 读取 source 真实图片尺寸。如果声明了 tailor_to_asset: true 或 slot_strategy: "fit-within"，脚本会把 position 当作“可用区域”，按真实图片宽高比在其中计算 computed_bbox；这个 bbox 会同时用于 prompt、骨架参考图和最终 PPTX 贴图。这样不是生成后再临时缩放，而是在 gpt-image-2 出图前就量体裁衣。
3. 在 outputs/<timestamp>/references/slide-XX-asset-skeleton.png 生成一张透明画布的角标骨架参考图，把最终真实图会覆盖的 final_image_rect_px 标出来，并作为 reference image 传给 gpt-image-2。这只用于引导模型不要把关键信息放进该区域；每页只调用一次 gpt-image-2，不是先生成一张再用骨架二次重生。
4. 打包 PPTX 时，按同一个 bbox 用 python-pptx 把 source 指向的真实图片作为独立图片对象贴入。默认不画额外框，也不铺遮罩；也不会默认清理 gpt-image-2 生成图。真实图片不应被合成进 images/slide-XX.png，否则用户无法在 PPT 里单独拖动。

如果生成后发现真实图片槽位压到大面积文字或图形，优先按下面两种方式处理：

1. 预生成前微调槽位：改 slide_spec.elements.<id>.position（或 anchor / padding），让真实素材移动到更干净的区域，再重新生成该页。只要槽位位置变了，就必须重新生成背景；不要只在 PPTX 里移动最终图片，否则背景内容仍可能压住新位置。
2. 二次版式修复：当第一页整体风格已经满意，只是局部内容压入槽位时，用 --edit SLIDE --external-slot-repair。该模式会同时把当前页和新的 asset-skeleton 作为 reference image 传入，要求模型保持原风格但重排文字/图形，让槽位空出来。

示例：把真实图区域右移并重排当前页：

python3 scripts/generate_ppt.py \
  --session outputs/20260529_120000 \
  --edit 3 \
  --external-slot-repair \
  --element-updates '{"hero_photo":{"position":[0.60,0.16,0.32,0.60],"anchor":"center"}}'

同时，每个包含外部真实图片的页面都会在 outputs/<timestamp>/external_image_trace/slide-XX/ 记录完整中间链路：

• step1-real-on-blank.png：把真实图片按最终坐标和大小先贴到空白页上，用来确认“真实图最终应该出现在这里”。
• step2-reference-outline-blank.png：去掉真实图片，只保留给 gpt-image-2 的角标定位参考图；默认透明画布，不铺白底。定位区域使用 final_image_rect_px，也就是最终真实图实际会覆盖的像素矩形，而不是外层 slot。这张图同时会复制到 references/slide-XX-asset-skeleton.png 并作为 image reference 输入。
• step3-generated-background.png：gpt-image-2 根据 step2 reference 生成的背景图，尚未贴入真实图片。
• step3-image2-raw.png / step3-sanitized-background.png：只有显式设置 sanitize_background: true 时才会出现，用于兜底清理模型已经画出的占位块；默认不启用。
• step4-final-overlay-preview.png：在 step3 上按 step1 同一坐标贴回真实图片的预览图，用来和 PPTX 最终效果对照。
• manifest.json：记录每个外部图片的 source、slot_bbox_norm、inner_rect_norm、reference_rect_px、final_image_rect_px、padding、bleed、素材尺寸和比例。

关键原则：

• reference skeleton 负责“告诉模型哪里不要放关键信息”，不是要求模型画白色空框。
• 模板克隆 / --template-strict 与外部真实图片槽位同时存在时，生成阶段会同时传入两张 reference：模板页用于学习风格，asset-skeleton 用于标记后贴图片覆盖区；不要二选一，否则模型只看模板页时不会知道最终图片位置。
• 外部真实图片页不能简单堆叠“模板照片/图片区 prompt”和“留空 prompt”。构造 prompt 前必须先消解冲突：模板只提供配色、字体、网格、节奏和装饰语言；模板里的照片区、图片框、全幅图、裁切图等都视为已被真实图片槽位替代。
• 构造 slide_spec 时，position 不能随便选，也不要默认固定右侧。模板克隆模式下，优先让模板 profile 提供 external_image_slots，或从模板布局摘要推断候选图片区，再根据本页文字量、真实图片数量、真实图片比例和页面类型打分：文字多时优先保证标题/正文阅读区；图片多或比例极端时优先用模板原有分栏/上下布局；无法共存时减少装饰和假视觉主体，而不是让真实图压内容。
• 推荐先写 layout_intent: "auto"，不手写 position。脚本会读取模板候选槽位、真实图尺寸、文字量、图片数量和比例来选择位置，写入 position / computed_bbox / auto_layout_reason；只有自动规划不理想时才用人工 position 覆盖。
• 使用 layout_intent: "auto" 时，slide_spec.layout 尽量写清图片区方向和结构，例如"左文右图 / right image / right landscape photo / 底部图片 / portrait rail"。自动规划会优先从这些方向性描述和模板候选槽位推断真实图区域；描述过泛时，重文本页可能退化到保守的小图槽位。
• position 默认可作为“允许使用的区域”；computed_bbox 才是脚本算出的最终真实图片槽位。
• 如果你想完全固定坐标，不要量体裁衣，直接写 bbox，或设置 slot_strategy: "exact" / tailor_to_asset: false。
• 最终精度由 python-pptx 坐标保证，不由模型画框保证。
• skeleton_outline_width 只控制给模型看的骨架参考图；outline_width / draw_frame 才控制最终 PPT 里是否出现可见框。
• prompt 中不写归一化坐标；位置通过透明角标 reference 图控制，避免模型错误解释数值坐标，也避免闭合框被理解成真实图片框。
• skeleton_canvas_fill / skeleton_fill / skeleton_outline / skeleton_outline_width / skeleton_shape 只影响参考骨架图。默认 skeleton_canvas_fill: "transparent" 且 skeleton_shape: "corners"，只在 final_image_rect_px 四角画短角标，不画闭合矩形、不铺白底，避免模型把 reference 理解成真实图片框或白色占位块。需要旧行为时显式设 skeleton_shape: "outline"。
• sanitize_background / mask_placeholder 不是推荐路径；它们只适合清掉极轻微的占位痕迹，不适合解决文字或图形大面积压住槽位的问题。遇到压内容，按“微调槽位并重生”或“二次版式修复”处理。
• 默认最终不画外框、不插入任何底色矩形，只贴真实图片；mask_placeholder 会被忽略，避免在真实图下方产生可拖动白底。只有显式设置 draw_frame: true 且 outline_width > 0 时，才会额外画无填充边框。
• 推荐默认：tailor_to_asset: true + slot_strategy: "fit-within" + fit: "contain" + 少量 padding。这会完整保留原图，并让骨架图从一开始就是按素材比例预留的。
• fit: "contain" 保留完整图片；fit: "cover" 会居中裁剪图片来铺满槽位。
• 如果要“严丝合缝”无白边，使用 fit: "cover"、padding: 0、outline_width: 0，并设置很小的 bleed（例如 0.0015-0.003）让图片比槽位多铺出约 1-3px，抵消 PowerPoint / Quick Look 渲染取整和抗锯齿缝隙。
• 如果想“预留一点但不要莫名空隙”，不要靠后期 contain 硬塞进一个比例不匹配的大框；应使用 fit-within 先算好比例匹配的槽位，再用很小的 padding 做设计留白。
• 交付前必须抽查 external_image_trace/slide-XX/manifest.json：重点看 final_image_rect_px 是否符合视觉预期，auto_layout_reason 是否选中了正确的左右/上下区域。若横图被算成小缩略图、竖图过窄或位置压内容，先补清楚 slide_spec.layout 的方向意图，或显式设置 position，再重新生成该页背景并重新打包 PPTX。

整体原理图保存于 docs/external_image_overlay_logic.txt；修改外部真实图片链路时，先对照这张图确认顺序仍是“模板/页面/素材画像 -> 候选槽位打分 -> 透明 skeleton -> 背景生成 -> 后贴真实图 -> 质检/有限修复”。

生成流程（模板克隆）

1. 拿到模板 .pptx（用户提供 / 内部模板库 / 网络下载）

2. （可选）先单独渲染并人工挑选----大模板（>15 页）建议先 python3 scripts/render_template.py xxx.pptx，再从 template_renders/<stem>/ 里挑 8-12 张代表页复制到 template_renders/<stem>_curated/，供 vision 分析。页数越精，layout 命中越准

3. 生成 slides_plan.md → 转 slides_plan.json（见指定风格流程第 2-3 步）。每页 slide_number / page_type (cover / content / data / 等) / content；想精准对位时在 h2 里加 layout=layout-NN（NN = 模板第 N 页 / 你期望对应的模板页编号）

4. 出图冒烟。API 直连 / 非 Codex 原生路径跑 generate_ppt.py：

   python3 scripts/generate_ppt.py \
     --plan slides_plan.json \
     --template-pptx xxx.pptx \
     --template-images template_renders/xxx_curated \
     --template-strict --slides 1

   如果当前 agent 自己是多模态模型，也可以先看模板 PNG 写出 template_profile.json，再这样跑，完全不需要 VISION_*：

   python3 scripts/generate_ppt.py \
     --plan slides_plan.json \
     --template-profile template_profile.json \
     --template-strict --slides 1

   先 --slides 1 出封面冒烟，效果 OK 再跑全量。

   如果当前 agent 就是带原生出图能力的 Codex，不要用上面的 generate_ppt.py 命令负责出图；先生成 / 读取 template_profile.json，再按“Codex 原生路径”直接调当前会话的图片生成 tool 输出第 1 页 PNG，用户确认后再生成全量页面并打包。

5. 告知用户产物路径

模板页面挑选 / 复用原则

核心原则：尽量做到 1 page : 1 layout----同一份 deck 里每个 slide 用不同的模板页作 reference，观众会觉得每页都是新内容；如果同一个独特 layout 出现 2-3 次，观众下意识会想"为什么又是这页"。

vision 分析时会给每个 layout 标 reuse_friendly：

Agent 在搭 plan 时的执行策略：

1. 优先把模板里 N 个不同 layout 分配给 N 页 slide（N 不够就在 SKILL 里看 reuse_friendly=true 的部分挑能复用的）
2. 如果 plan 里某页内容结构非常相似（比如多个"5 步骤流程"），先尝试改写内容用不同 layout 表达（4 步骤 + 5 步骤分别用不同流程页），而不是同一个 zigzag 用两次
3. 冒烟跑完后，看 Layout 复用检测 那段输出：(!) 必须改，(i) 看情况改；改 plan 里相应 slide 的 layout_id 即可
4. 看完 profile JSON 选 layout：cat <cwd>/template_cache/<sha256>.json | jq '.layouts[] | {id, page_type, reuse_friendly, summary}'；如果是多模态 agent 自己生成的 template_profile.json，就读取那个文件。

generate_ppt.py 在派发任务前会自动跑一次复用检测，把警告打到终端，不阻塞执行。

Skill 调用规范

当用户说"做一份 PPT" / "生成幻灯片"时：

1. 先问三件事（不要直接动手）：
   • 内容 / 页数 / 观众是谁？
   • 风格偏好？按 styles/ 和 docs/distilled-styles.md 的场景类目映射推荐 1-2 个；或者用户上传自己的 .pptx 模板（走 --template-pptx，自动渲染）
   • 是否需要单页测试一张图先看效果（API 直连用 --slides 1；Codex 原生路径直接生成第 1 页 PNG）
2. 先写 slides_plan.md 给用户确认文案（md 是 source of truth，人审阅友好）
3. 转 slides_plan.json：python3 scripts/md_to_plan.py slides_plan.md -o slides_plan.json（json 标为 generated，不手改；要改文案回到 md 改再转）
4. 构造 slide_spec（Agent 步骤）：读 styles/<id>.md 了解视觉规范，然后为 slides_plan.json 每页构造 slide_spec，写入每页的 slide_spec 字段（格式见"指哪改哪"章节）。这一步让后续修改能精确到每个元素
5. 出图冒烟：
   • API 直连 / 非 Codex 原生路径：跑 generate_ppt.py --slides 1 出封面冒烟，效果 OK 再跑全量
   • 当前 agent 就是带原生出图能力的 Codex：按上方“Codex 原生路径”直接调当前会话的 image_generation tool 生成 outputs/<timestamp>/images/slide-01.png；不要用 generate_ppt.py --backend codex
6. 告知用户产物路径，产物在 outputs/<timestamp>/，<title>.pptx 可直接打开

面向用户的表达规范

对普通用户汇报时，默认不要解释 slide_spec、metadata.json、element-updates、JSON Schema、pytest 命令等内部实现，除非用户明确问技术细节。

用户最关心的是：

1. 做出来的 PPT 是否好看、能不能直接用。
2. 哪些场景稳定，哪些场景需要人工验收。
3. 是否只改了指定页 / 指定内容。
4. 最终输出目录和 PPTX 文件在哪里。
5. 当前不足是什么，例如背景/文字仍是整页图片、数字小字需复核；真实 logo/产品图需提供素材，才能作为独立图片对象放入。

如果需要介绍修改能力，优先引用 docs/edit_guide.md 的场景分级、before / after 案例和当前不足，不要把实现链路放在用户前面。

当用户说"改第 X 页的 XX"时：

1. 找到 session：先用 --list-sessions 列出现有 session，确定要编辑的是哪个
2. 读 metadata.json：查看对应 slide 的 slide_spec，找到目标元素
3. 确认修改内容：告知用户当前内容，询问新内容
4. 构造编辑指令：用 --element-updates 指定要改的元素和新内容
5. 执行 --edit：python3 scripts/generate_ppt.py --edit X --session <ts> --element-updates '{"elem_id": {"content": "new"}}'
6. 告知结果：新版本已生成，PPTX 已更新

仅生成部分页

python3 scripts/generate_ppt.py --plan my_plan.json --style styles/dark-aurora.md --slides 1,3,5

跑过的页有同名 PNG 时会自动跳过，方便逐页迭代。

"指哪改哪" PPT 编辑工作流

本节只保留 agent 执行所需信息；完整结构、版本链和数据安全细节见 docs/workflow.md。向普通用户解释能力时看 docs/edit_guide.md。

生成时的结构化要求

生成新 PPT 时，agent 应为每页写入简洁的 slide_spec，方便后续按标题、副标题、卡片、指标等元素精确修改。最低要求：

• layout: 一句话描述版式
• elements: 语义化元素字典
• 常用元素 ID：title、subtitle、card_1、card_2、metric_1、date_line、footer
• 元素字段优先写 type、content 或 heading/body、position、style、color

不要为了追求完整而写很长的 spec；能让后续定位和编辑即可。

修改已有幻灯片

1. 用 --list-sessions 找到目标 session。
2. 读目标 session 的 metadata.json，定位页号和元素 ID。
3. 如果用户没给新内容，先问一句“当前是 X，要改成什么？”
4. 用 --element-updates 描述修改；需要更强约束时加 --edit-instruction，明确“其他内容、布局、配色不要动”。
5. 执行 --edit 后检查目标页图片，重建后的 PPTX 会同步更新。

常用命令：

python3 scripts/generate_ppt.py \
  --edit 3 \
  --session 20240523_143052 \
  --element-updates '{"subtitle": {"content": "医疗数据碎片化"}}' \
  --edit-instruction "将副标题从'健康管理的两类割裂'改为'医疗数据碎片化'"

python3 scripts/generate_ppt.py \
  --edit 3 \
  --session 20240523_143052 \
  --edit-prompt "在参考图基础上，只修改标题下方副标题的文字，从'健康管理的两类割裂'改为'医疗数据碎片化'，保持位置、字体、颜色、大小完全不变。" \
  --element-updates '{"subtitle": {"content": "医疗数据碎片化"}}'

外部 PPTX 摄取后修改

外部 PPTX 可先摄取为图片 session，再由多模态 agent 看图补齐每页的 slide_spec。没有补 spec 前，不要承诺“精确改某个对象”。

python3 scripts/generate_ppt.py --ingest-pptx path/to/deck.pptx
python3 scripts/generate_ppt.py --ingest-pptx path/to/deck.pptx --session my_deck_2024

回滚和 session 列表

python3 scripts/generate_ppt.py \
  --rollback 3 \
  --to-version 1 \
  --session 20240523_143052

python3 scripts/generate_ppt.py --list-sessions

文件结构

gpt-image2-ppt-skills/
|---- SKILL.md                # 本文件（Claude Code skill 入口）
|---- AGENTS.md               # codex / aider / cursor 等 agent 的薄索引，指向本文件
|---- README.md               # 项目说明
|---- scripts/                # 所有 Python 脚本
|   |---- generate_ppt.py         # 主入口（CLI）
|   |---- md_to_plan.py           # slides_plan.md -> slides_plan.json 转换器（CLI）
|   |---- render_template.py      # PPTX -> 每页 PNG 的辅助脚本（CLI + library）
|   |---- image_generator.py      # gpt-image-2 wrapper（支持 reference image，openai backend）
|   |---- codex_backend.py        # 可选：走 codex CLI 出图（--backend codex）
|   \---- template_analyzer.py    # PPT 模板剖析器（vision + 缓存）
|---- styles/                 # 所有可用风格，每个 .md 对应一个 style id
|   |---- gradient-glass.md           dark-aurora.md
|   |---- clean-tech-blue.md          risograph.md
|   |---- vector-illustration.md      japanese-wabi.md
|   |---- editorial-mono.md           swiss-grid.md
|   |---- hand-sketch.md              y2k-chrome.md
|---- docs/README.en.md       # 英文 README
|---- install_as_skill.sh     # 一键安装到 agent skills 目录
|---- requirements.txt        # requests + python-dotenv + python-pptx + jsonschema + pymupdf
\---- .env.example

调用时产生的运行时目录都在 <cwd> 下：

<your-project>/
|---- template_renders/<stem>/page-NN.png   # PPTX 渲染（render_template.py）
|---- template_cache/<sha256>.json          # 外挂 vision 风格分析缓存（纯文本 agent 路径）
|---- template_profile.json                 # 多模态 agent 可手写/生成的模板 profile（可选）
\---- outputs/<timestamp>/                  # 每次生成产物

License

Apache License 2.0.