Skip to content

JuneYaooo/gpt-image2-ppt-skills

gpt-image2-ppt

Verified

Generate visually striking PPT slides via OpenAI's gpt-image-2 -- use any style in styles/<collection>/STYLE_ID.md or mimic a user-supplied .pptx template; outputs high-res slide PNGs and a 16:9 .pptx. Use when the user asks to make a presentation, slides, deck, pitch deck, investor PPT, magazine-style PPT, or 做一份 PPT / 生成幻灯片 / 用 gpt-image 生成 PPT / 按这个模板生成 PPT.

FileKindSize
SKILL.mdskill md56.8 KB
agents/openclaw.yamlconfig1006 B
examples/README.mdmarkdown2.8 KB
examples/book-sharing/recipe.mdmarkdown787 B
examples/book-sharing/slides_plan.mdmarkdown1.8 KB
examples/courseware/recipe.mdmarkdown725 B
examples/courseware/slides_plan.mdmarkdown2.0 KB
examples/editable-pptx-poc/demo1-cover.scene.jsonconfig912 B
examples/editable-pptx/case05-summer-poster/README.mdmarkdown4.1 KB
examples/editable-pptx/case05-summer-poster/clean-plate.pngbinary2.5 MB
examples/editable-pptx/case05-summer-poster/edge-check-black.pngbinary697.7 KB
examples/editable-pptx/case05-summer-poster/edge-check-white.pngbinary695.4 KB
examples/editable-pptx/case05-summer-poster/editable.pptxbinary3.3 MB
examples/editable-pptx/case05-summer-poster/layers/mascot-icecream-group.pngbinary813.1 KB
examples/editable-pptx/case05-summer-poster/original.pngbinary2.4 MB
examples/editable-pptx/case05-summer-poster/quality-report.jsonconfig355 B
examples/editable-pptx/case05-summer-poster/rendered.pngbinary3.7 MB
examples/editable-pptx/case05-summer-poster/slide-01.scene.jsonconfig3.3 KB
examples/investor-pitch/recipe.mdmarkdown803 B
examples/investor-pitch/slides_plan.mdmarkdown2.5 KB
examples/product-launch/recipe.mdmarkdown841 B
examples/product-launch/slides_plan.mdmarkdown1.8 KB
examples/thesis-defense/recipe.mdmarkdown806 B
examples/thesis-defense/slides_plan.mdmarkdown2.4 KB
examples/weekly-report/recipe.mdmarkdown771 B
examples/weekly-report/slides_plan.mdmarkdown1.6 KB
scripts/codex_backend.pyscript9.1 KB
scripts/editable_pptx/__init__.pyscript398 B
scripts/editable_pptx/layers.pyscript2.0 KB
scripts/editable_pptx/masking.pyscript3.8 KB
scripts/editable_pptx/poc.pyscript5.7 KB
scripts/editable_pptx/provider.pyscript2.7 KB
scripts/editable_pptx/renderer.pyscript6.0 KB
scripts/editable_pptx/scene.pyscript4.8 KB
scripts/editable_pptx/workflow.pyscript6.0 KB
scripts/generate_ppt.pyscript162.9 KB
scripts/image_generator.pyscript26.0 KB
scripts/md_to_plan.pyscript5.9 KB
scripts/render_template.pyscript21.7 KB
scripts/runtime_profile.pyscript6.3 KB
scripts/template_analyzer.pyscript42.9 KB

scripts/generate_ppt.py

View on GitHub
#!/usr/bin/env python3
"""
PPT Generator - Generate PPT slide images using OpenAI gpt-image-2 (Images API).

Generates 16:9 slide images from a slide plan + style template, saves
structured slide_spec metadata for precise editing, and packages a .pptx.
"""

import argparse
import copy
import json
import os
import re
import sys
from datetime import datetime
from pathlib import Path
from typing import Any, Dict, List, Optional, Tuple, Union

try:
    from .runtime_profile import (
        normalize_runtime_profile,
        runtime_profile_summary,
    )
except ImportError:
    from runtime_profile import (
        normalize_runtime_profile,
        runtime_profile_summary,
    )

# =============================================================================
# Constants
# =============================================================================

OUTPUT_BASE_DIR = "outputs"
SLIDE_TRACE_WIDTH = 1536
SLIDE_TRACE_HEIGHT = 864
EXTERNAL_IMAGE_TYPES = {"external_image", "external_image_placeholder", "image_overlay"}
REFERENCE_ONLY_IMAGE_TYPES = {"image_reference", "visual_reference", "reference_image", "style_reference_image"}
REFERENCE_ONLY_MODES = {"reference", "image_reference", "image-to-image", "image_to_image", "redraw", "blend", "inspiration"}

SCRIPT_DIR = Path(__file__).parent
SKILL_ROOT = SCRIPT_DIR.parent
CWD = Path.cwd()


# =============================================================================
# Environment Configuration
# =============================================================================

SKILL_PREFIX = "gpt-image2-ppt"

SKILL_ENV_MAP = {
    "OPENAI_API_KEY":        "OPENAI_API_KEY",
    "OPENAI_BASE_URL":       "OPENAI_BASE_URL",
    "GPT_IMAGE_MODEL_NAME":  "GPT_IMAGE_MODEL_NAME",
    "GPT_IMAGE_QUALITY":     "GPT_IMAGE_QUALITY",
    "GPT_IMAGE_BACKEND":     "GPT_IMAGE_BACKEND",
    "GPT_IMAGE_CONCURRENCY": "GPT_IMAGE_CONCURRENCY",
    "VISION_BASE_URL":       "VISION_BASE_URL",
    "VISION_API_KEY":        "VISION_API_KEY",
    "VISION_MODEL_NAME":     "VISION_MODEL_NAME",
}


def _load_platform_env() -> bool:
    """Map platform-injected 'skill-prefix_VAR' env vars to unprefixed names.

    The platform (MedAgent / Codex / OpenClaw) sets env vars like
        gpt-image2-ppt_OPENAI_API_KEY=sk-...
    but the script expects plain OPENAI_API_KEY.  This function detects
    the prefixed form and maps them transparently into os.environ.
    Returns True if any prefixed var was found.
    """
    found = False
    for base_name in SKILL_ENV_MAP:
        prefixed = f"{SKILL_PREFIX}_{base_name}"
        value = os.environ.get(prefixed)
        if value and not os.environ.get(base_name):
            os.environ[base_name] = value
            found = True
    return found


def _load_scoped_env_files() -> List[str]:
    """Load env files from explicit or skill-owned locations only.

    This intentionally does not read CWD/.env or walk parent directories. Skill
    credentials should come from the agent framework / system environment first;
    .env is only a standalone CLI fallback.
    """
    candidates: List[Path] = []
    explicit = os.environ.get("GPT_IMAGE2_PPT_ENV")
    if explicit:
        candidates.append(Path(explicit).expanduser())
    candidates.extend([
        SKILL_ROOT / ".env",
        Path.home() / ".codex/skills/gpt-image2-ppt-skills/.env",
        Path.home() / ".claude/skills/gpt-image2-ppt-skills/.env",
        Path.home() / "skills/gpt-image2-ppt/.env",
        Path.home() / "skills/gpt-image2-ppt-skills/.env",
    ])

    try:
        from dotenv import load_dotenv
    except ImportError:
        return []

    loaded: List[str] = []
    seen = set()
    for path in candidates:
        resolved = str(path.resolve()) if path.exists() else str(path)
        if resolved in seen or not path.is_file():
            continue
        seen.add(resolved)
        if load_dotenv(path, override=False):
            loaded.append(resolved)
    return loaded


def load_skill_env() -> None:
    """Load environment with safe precedence.

    Existing process environment wins. Platform-prefixed variables are mapped
    next, then explicit / skill-owned .env files fill in missing values.
    """
    _load_platform_env()
    _load_scoped_env_files()
    # Provider-specific convenience aliases. They are only fallbacks: an
    # explicit OPENAI_* value from the current process or a scoped .env file
    # must never be replaced implicitly.
    juling_base = os.environ.get("JULING_GPT_IMAGE2_BASE_URL")
    juling_key = os.environ.get("JULING_GPT_IMAGE2_API_KEY")
    if juling_base and not os.environ.get("OPENAI_BASE_URL"):
        os.environ["OPENAI_BASE_URL"] = juling_base
    if juling_key and not os.environ.get("OPENAI_API_KEY"):
        os.environ["OPENAI_API_KEY"] = juling_key

# =============================================================================
# Session & Metadata Management
# =============================================================================

METADATA_FILENAME = "metadata.json"


def _find_sessions(base_dir: Optional[str] = None) -> List[Dict[str, Any]]:
    """Discover all generation sessions (directories containing metadata.json).

    Returns a list of dicts with 'timestamp', 'dir', 'title', 'slides'.
    """
    if base_dir is None:
        base_dir = str(CWD / OUTPUT_BASE_DIR)
    sessions: List[Dict[str, Any]] = []
    if not os.path.isdir(base_dir):
        return sessions
    for entry in sorted(os.listdir(base_dir), reverse=True):
        session_dir = os.path.join(base_dir, entry)
        meta_path = os.path.join(session_dir, METADATA_FILENAME)
        if os.path.isfile(meta_path):
            try:
                with open(meta_path, "r", encoding="utf-8") as f:
                    meta = json.load(f)
                sessions.append({
                    "timestamp": entry,
                    "dir": session_dir,
                    "title": meta.get("title", "Untitled"),
                    "slide_count": len(meta.get("slides", {})),
                })
            except Exception:
                sessions.append({
                    "timestamp": entry,
                    "dir": session_dir,
                    "title": "(corrupt metadata)",
                    "slide_count": 0,
                })
    return sessions


def _resolve_session(session_id: str) -> str:
    """Resolve a session timestamp or path to the session directory.

    Accepts: full path, relative path, or timestamp in OUTPUT_BASE_DIR.
    """
    # Absolute or relative path
    if os.path.isdir(session_id) and os.path.isfile(os.path.join(session_id, METADATA_FILENAME)):
        return os.path.abspath(session_id)
    # Try under OUTPUT_BASE_DIR
    candidate = str(CWD / OUTPUT_BASE_DIR / session_id)
    if os.path.isdir(candidate) and os.path.isfile(os.path.join(candidate, METADATA_FILENAME)):
        return candidate
    # Try with partial match (prefix)
    sessions = _find_sessions()
    for s in sessions:
        if s["timestamp"].startswith(session_id):
            return s["dir"]
    print(f"[X] Session not found: {session_id}")
    print(f"    Tried: {session_id}")
    if candidate != session_id:
        print(f"    Tried: {candidate}")
    sys.exit(1)


def _load_metadata(session_dir: str) -> Dict[str, Any]:
    """Load metadata.json from a session directory."""
    meta_path = os.path.join(session_dir, METADATA_FILENAME)
    if not os.path.isfile(meta_path):
        print(f"[X] No metadata.json found in {session_dir}")
        sys.exit(1)
    with open(meta_path, "r", encoding="utf-8") as f:
        return json.load(f)


def _save_metadata(metadata: Dict[str, Any], session_dir: str) -> None:
    """Atomically save metadata.json to a session directory.

    Writes to a temp file first, then renames to avoid corruption
    on crashes or disk-full conditions.
    """
    import tempfile as _tempfile
    meta_path = os.path.join(session_dir, METADATA_FILENAME)
    fd, tmp_path = _tempfile.mkstemp(
        suffix=".json", prefix=".metadata_", dir=session_dir
    )
    try:
        with os.fdopen(fd, "w", encoding="utf-8") as f:
            json.dump(metadata, f, ensure_ascii=False, indent=2)
        os.replace(tmp_path, meta_path)  # atomic on POSIX + modern Windows
    except Exception:
        try:
            os.unlink(tmp_path)
        except OSError:
            pass
        raise


def _collect_slide_numbers(metadata: Dict[str, Any]) -> List[int]:
    """Extract sorted slide numbers from metadata slides dict."""
    slides_dict = metadata.get("slides", {})
    ordered: List[int] = []
    seen = set()
    for raw in metadata.get("slide_order", []) or []:
        try:
            n = int(raw)
        except (TypeError, ValueError):
            continue
        if str(n) in slides_dict and n not in seen:
            ordered.append(n)
            seen.add(n)

    nums: List[int] = []
    for k in slides_dict.keys():
        try:
            n = int(k)
        except ValueError:
            continue
        if n not in seen:
            nums.append(n)
    nums.sort()
    return ordered + nums


def _get_latest_slide_spec(metadata: Dict[str, Any], slide_number: int) -> Dict[str, Any]:
    """Get the current slide_spec for a given slide number."""
    slide_key = str(slide_number)
    slide_data = metadata.get("slides", {}).get(slide_key)
    if not slide_data:
        return {}
    current_version = slide_data.get("current_version", 1)
    for v in slide_data.get("versions", []):
        if v.get("version") == current_version:
            return v.get("spec", {})
    return {}


def _get_version_info(metadata: Dict[str, Any], slide_number: int, version: int) -> Optional[Dict[str, Any]]:
    """Get a specific version entry for a slide."""
    slide_key = str(slide_number)
    slide_data = metadata.get("slides", {}).get(slide_key)
    if not slide_data:
        return None
    for v in slide_data.get("versions", []):
        if v.get("version") == version:
            return v
    return None


def _init_slide_metadata(
    slide_number: int,
    page_type: str,
    initial_spec: Dict[str, Any],
    prompt_file: str,
    image_path: str,
) -> Dict[str, Any]:
    """Create the initial metadata entry for a slide."""
    return {
        "slide_number": slide_number,
        "page_type": page_type,
        "current_version": 1,
        "image_snapshot": image_path,
        "versions": [
            {
                "version": 1,
                "action": "generate",
                "spec": initial_spec,
                "prompt_file": prompt_file,
                "image_snapshot": image_path,
            }
        ],
    }


def _add_slide_version(
    slide_data: Dict[str, Any],
    new_version: int,
    spec: Dict[str, Any],
    action: str,
    image_snapshot: str,
    prompt_file: str,
    edit_instruction: str = "",
    reference_version: Optional[int] = None,
) -> None:
    """Append a new version entry to slide metadata."""
    entry: Dict[str, Any] = {
        "version": new_version,
        "action": action,
        "spec": spec,
        "prompt_file": prompt_file,
        "image_snapshot": image_snapshot,
    }
    if edit_instruction:
        entry["edit_instruction"] = edit_instruction
    if reference_version is not None:
        entry["reference_version"] = reference_version
    slide_data.setdefault("versions", []).append(entry)
    slide_data["current_version"] = new_version
    slide_data["image_snapshot"] = image_snapshot


def _stabilize_version_snapshots(slide_data: Dict[str, Any], slide_number: int, images_dir: str) -> None:
    """Point version history entries at immutable versioned image files when present."""
    for version_entry in slide_data.get("versions", []):
        version = version_entry.get("version")
        if not isinstance(version, int):
            continue
        versioned_rel = f"images/slide-{slide_number:02d}_v{version:04d}.png"
        versioned_abs = os.path.join(images_dir, f"slide-{slide_number:02d}_v{version:04d}.png")
        if os.path.isfile(versioned_abs):
            version_entry["image_snapshot"] = versioned_rel


# =============================================================================
# Slide Spec Helpers
# =============================================================================

def apply_spec_updates(spec: Dict[str, Any], element_updates: Dict[str, Any]) -> Dict[str, Any]:
    """Apply element-level updates to a slide_spec, returning the updated spec.

    element_updates maps element_id to a dict of key-value changes.
    e.g. {"subtitle": {"content": "新内容"}, "title": {"color": "#ff0000"}}
    """
    import copy
    updated = copy.deepcopy(spec)
    elements = updated.setdefault("elements", {})
    derived_external_keys = {
        "computed_bbox",
        "placement_region",
        "asset_size",
        "asset_ratio",
        "tailored_to_asset",
        "auto_layout_reason",
    }
    geometry_keys = {
        "position",
        "bbox",
        "source",
        "path",
        "asset",
        "fit",
        "slot",
        "slot_strategy",
        "tailor_to_asset",
        "anchor",
        "padding",
        "bleed",
        "layout_intent",
        "auto_layout",
    }
    for elem_id, changes in element_updates.items():
        if elem_id in elements:
            elem = elements[elem_id]
            if (
                isinstance(elem, dict)
                and str(elem.get("type", "")).lower() in {"external_image", "external_image_placeholder", "image_overlay"}
                and any(k in changes for k in geometry_keys)
            ):
                for k in derived_external_keys:
                    elem.pop(k, None)
            elements[elem_id].update(changes)
        else:
            elements[elem_id] = changes
    return updated


def construct_edit_prompt(spec: Dict[str, Any], element_updates: Dict[str, Any]) -> str:
    """Construct a natural-language edit prompt from the old spec and element changes.

    The prompt instructs gpt-image-2 to change only specific elements
    while keeping everything else identical to the reference image.
    """
    parts = ["在参考图基础上,只修改以下内容,保持其他所有元素(背景、装饰、布局、字体、颜色、大小)完全不变:"]
    elements = spec.get("elements", {})

    for elem_id, changes in element_updates.items():
        old_elem = elements.get(elem_id, {})
        position = old_elem.get("position", "相应位置")
        etype = old_elem.get("type", "元素")
        old_content = old_elem.get("content", "")
        new_content = changes.get("content", old_content)

        if "content" in changes and old_content and new_content != old_content:
            parts.append(
                f"将{position}{etype}的文字从「{old_content}」改为「{new_content}」"
            )
        elif "color" in changes:
            old_color = old_elem.get("color", "")
            new_color = changes.get("color", "")
            parts.append(
                f"将{position}{etype}的颜色从{old_color}改为{new_color}"
            )
        elif "style" in changes:
            parts.append(
                f"将{position}{etype}的样式改为{changes['style']}"
            )
        else:
            for k, v in changes.items():
                parts.append(f"修改{position}{etype}的{k}为{v}")

    return "\n".join(parts)


def construct_external_slot_repair_prompt(spec: Dict[str, Any], element_updates: Optional[Dict[str, Any]] = None) -> str:
    """Prompt for repairing a slide whose content collides with external-image slots."""
    slot_ids = []
    for elem_id, elem in (spec.get("elements") or {}).items():
        if isinstance(elem, dict) and str(elem.get("type", "")).lower() in {
            "external_image",
            "external_image_placeholder",
            "image_overlay",
        }:
            slot_ids.append(str(elem_id))
    slot_text = "、".join(slot_ids) if slot_ids else "外部真实图片槽位"
    parts = [
        "请基于当前幻灯片图进行版式修复,保持整体风格、配色、字体气质、背景质感和主要视觉层级不变。",
        f"另一张参考图是空间定位图,细角标标出的区域是后续会贴入真实图片的覆盖区({slot_text}),不是页面设计元素。",
        "必须把所有标题、正文、数字、图标、线条、装饰图形、照片主体和重要视觉元素移出这些角标区域。",
        "允许为了避让槽位而小幅移动、缩短、换行、重排或重新对齐文字和图形;优先保持页面清爽和可读。",
        "修复后仍要保持模板原本的结构节奏:图文分栏、上下区块、主视觉方向和留白比例要自然,不能为了避让产生大片无意义空白、断裂分割线、挤在角落的文字或失衡构图。",
        "角标区域下方只生成自然连续的背景、轻微纹理或非常轻的抽象装饰。",
        "严禁在角标区域生成白色/浅色矩形、空卡片、图片占位框、边框、阴影、透明洞或任何可见预留块。",
        "不要复制、描摹、强化、美化或保留空间定位图里的角标;最终页面里应看不到任何占位痕迹。",
        "不要生成或仿造真实图片内容,真实图片会在 PPTX 打包阶段由代码按同一坐标贴入。",
    ]
    if element_updates:
        parts.append("同时应用以下 slide_spec 位置/内容更新,并以更新后的空间定位图为准:")
        parts.append(json.dumps(element_updates, ensure_ascii=False, indent=2))
    return "\n".join(parts)


def _format_external_slots_constraint(external_slots: List[Dict[str, Any]]) -> str:
    """Prompt block for pages where real external images are overlaid later."""
    if not external_slots:
        return ""
    slot_lines = []
    for slot in external_slots:
        tailored = "已按真实素材宽高比量体裁衣" if slot.get("tailored_to_asset") else "固定槽位"
        asset_info = ""
        if slot.get("asset_size") and slot.get("asset_ratio"):
            asset_info = f",素材尺寸={slot.get('asset_size')},素材比例={slot.get('asset_ratio')}"
        if slot.get("asset_class"):
            asset_info += f",素材类别={slot.get('asset_class')},细节级别={slot.get('detail_level')}"
        slot_lines.append(
            f"- {slot['id']}({tailored}{asset_info}):对应参考图中的一组细角标定位区。"
        )
        if slot.get("auto_layout_reason"):
            slot_lines.append(f"  版式规划: {slot.get('auto_layout_reason')}")
    return (
        "\n\n【外部真实图片槽位 - 强约束】\n"
        "在绘制页面前,先根据本页文字量、真实图片数量、真实图片比例和参考图角标位置做整体排版规划。"
        "不要照搬风格模板中原有的照片区、图片框或主体摄影构图;它们只提供风格气质,不提供本页最终图片内容。\n"
        "参考图中的细角标只标出后续会由代码贴入真实图片的覆盖区,"
        "它们不是页面设计元素,也不是图片框、卡片、遮罩或留白块。\n"
        + "\n".join(slot_lines)
        + "\n请只避让这些定位区里的关键信息:不要把标题、正文、数字、图标、人物或主体照片放进这些区域。"
        + "定位区底下的背景必须自然连续,可以有同页背景色、纸张纹理或轻微装饰延续过去。"
        + "严禁在定位区生成白色/浅色矩形、空卡片、图片占位框、边框、阴影、透明洞或任何可见预留块。"
        + "如果页面布局或风格模板提到主体照片、产品照、人物照、场景摄影、photo crop、image crop、图片区或照片区,"
        + "这些角色都将由代码后贴真实图片完成,模型绝对不要自行生成、仿造或重绘这些照片内容。"
        + "本页可以保留本风格的文字、细线、背景纹理、柔和光影和少量抽象装饰,但不要生成额外摄影主体。"
        + "如果风格模板的照片/图像构图与外部真实图片槽位冲突,以外部槽位、文字可读性和页面清爽为最高优先级。"
        + "不要复制、描摹、强化或美化参考图里的角标;最终页面里应看不到任何占位痕迹。"
    )


def _compact_text_for_asset_first_layout(content: Any, max_items: int = 3, max_chars_per_item: int = 24) -> str:
    text = str(content or "").strip()
    if not text:
        return ""
    parts = [
        p.strip()
        for p in re.split(r"[\n。;;.!!??]+", text)
        if p.strip()
    ]
    compact: List[str] = []
    for part in parts:
        part = re.sub(r"\s+", " ", part).strip()
        if len(part) > max_chars_per_item:
            part = part[: max_chars_per_item - 1].rstrip() + "…"
        compact.append(part)
        if len(compact) >= max_items:
            break
    return "\n".join(f"要点:{p}" for p in compact)


def _wrap_title_for_asset_first_layout(content: Any, max_chars_per_line: int = 12, max_lines: int = 3) -> str:
    text = re.sub(r"\s+", " ", str(content or "").strip())
    if not text:
        return ""
    lines: List[str] = []
    current = ""
    for ch in text:
        current += ch
        if len(current) >= max_chars_per_line or ch in "::,,、/":
            lines.append(current.strip())
            current = ""
            if len(lines) >= max_lines:
                break
    if current and len(lines) < max_lines:
        lines.append(current.strip())
    return "\n".join(line for line in lines if line)


def _format_asset_first_layout_constraint(high_detail_slots: List[Dict[str, Any]]) -> str:
    if not high_detail_slots:
        return ""
    slot_names = "、".join(str(slot.get("id", "真实图")) for slot in high_detail_slots)
    return (
        "\n\n【高细节真实图主视觉页 - 强约束】\n"
        f"本页包含需要阅读细节的真实素材({slot_names}),例如论文截图、表格、架构图、代码、公式或曲线图。"
        "这些真实图不是装饰缩略图,而是页面主视觉,必须预留大面积可读区域。\n"
        "版式策略:采用“左侧窄文字栏 + 右侧/下方大素材面板”结构;文字区必须明显避开角标素材区。"
        "当素材是标准比例或竖图时,标题和摘要都收进左侧窄栏,标题可以换行变短,但不要横跨到右侧素材面板。\n"
        "当素材是超宽图时,标题和摘要收进上方/左上文字区,不要下探到下方素材面板。\n"
        "文字策略:正文最多 2-3 条短要点,每条尽量不超过 18 个中文字符;不要把原文长段落完整铺进页面。"
        "如果文字和真实图可读性冲突,优先牺牲文字数量,保留大图可读性。\n"
        "视觉策略:素材区底下只生成连续背景,不生成白卡、图片框、假截图、假论文页或装饰块。"
    )


def _strip_generated_image_directives(text: str) -> str:
    """Remove photo/image-generation directives from a prompt for external-image pages."""
    photo_terms = (
        "image",
        "photo",
        "photograph",
        "photography",
        "crop",
        "full-bleed",
        "imagery",
        "照片",
        "摄影",
        "图片",
        "图像",
        "图片区",
        "图像区",
        "照片区",
    )
    keep_markers = (
        "外部真实图片",
        "真实图片会",
        "后续会由代码贴入",
        "reference skeleton",
        "asset-skeleton",
    )
    lines = []
    for line in text.splitlines():
        stripped = line.strip()
        lowered = stripped.lower()
        if any(marker in stripped for marker in keep_markers):
            lines.append(line)
            continue
        if any(term in lowered for term in photo_terms):
            continue
        lines.append(line)
    return "\n".join(lines).strip()


def adapt_template_prompt_for_external_slots(prompt: str, external_slots: List[Dict[str, Any]]) -> str:
    """Make a template-derived prompt safe for pages with real image overlays."""
    if not external_slots:
        return prompt
    prompt = _strip_generated_image_directives(prompt)
    return (
        prompt
        + "\n\n【模板冲突消解 - 最高优先级】\n"
        + "本页不是按模板照片区直接重画照片;模板只提供配色、字体、网格、节奏和装饰语言。"
        + "真实图片的位置、数量和比例由外部图片槽位与参考图角标决定。"
        + "请先根据本页文字量和真实图片槽位重新组织版式:文字必须绕开槽位,图形和装饰不得侵入槽位。"
        + "如果模板布局描述中仍隐含照片、图片区、全幅图、裁切图或视觉主体图,请把这些指令视为已被外部真实图片替代。"
        + "最终生成图中不要出现额外照片、假图、图片框、占位卡片或为了图片区而留下的白色/浅色底块。"
    )


def generate_prompt_from_spec(
    style_template: str,
    slide_spec: Dict[str, Any],
    page_type: str,
    slide_number: int,
    total_slides: int,
    output_dir: Optional[str] = None,
) -> str:
    """Generate a detailed prompt from a structured slide_spec.

    Uses element-level descriptions (type, content, position, style, color)
    to construct a precise prompt that gpt-image-2 can follow.
    """
    elements = slide_spec.get("elements", {})
    layout = slide_spec.get("layout", "")
    external_slots = _collect_external_image_slots(slide_spec)
    if output_dir:
        external_slots = _slots_with_real_sources(external_slots, output_dir)
    high_detail_slot_ids = {
        str(slot.get("id"))
        for slot in external_slots
        if _external_asset_detail_level(slide_spec, str(slot.get("id")), (elements.get(str(slot.get("id"))) or {})) in {"high", "critical"}
    }
    effective_style_template = (
        _adapt_style_template_for_external_slots(style_template)
        if external_slots
        else style_template
    )

    # Build element descriptions
    element_lines = []
    for elem_id, elem in elements.items():
        etype = elem.get("type", "unknown")
        if str(etype).lower() in EXTERNAL_IMAGE_TYPES or str(etype).lower() in REFERENCE_ONLY_IMAGE_TYPES:
            continue
        content = _element_text_content(elem)
        etype_lower = str(etype).lower()
        if high_detail_slot_ids and etype_lower in {"title", "headline", "heading"}:
            content = _wrap_title_for_asset_first_layout(content)
        elif high_detail_slot_ids and etype_lower in {"body", "paragraph", "text", "bullet", "bullets"}:
            content = _compact_text_for_asset_first_layout(content, max_items=2, max_chars_per_item=16)
        position = elem.get("position", "")
        if high_detail_slot_ids and not position:
            if etype_lower in {"title", "headline", "heading"}:
                position = "左侧窄文字栏上方,标题必须换成短行,不要横向延伸到右侧素材面板"
            elif etype_lower in {"body", "paragraph", "text", "bullet", "bullets"}:
                position = "左侧窄文字栏内、标题下方,只保留短要点,不要进入右侧素材面板"
        style_hint = elem.get("style", "")
        color = elem.get("color", "")
        description = elem.get("description", "")

        if description:
            element_lines.append(f"- {elem_id}({etype}): {description}")
            continue

        desc_parts = [f"- {etype}「{content}」"]
        if position:
            desc_parts.append(f"位置: {position}")
        if style_hint:
            desc_parts.append(f"样式: {style_hint}")
        if color:
            desc_parts.append(f"颜色: {color}")
        element_lines.append(",".join(desc_parts))

    elements_text = "\n".join(element_lines)
    if external_slots:
        elements_text += _format_external_slots_constraint(external_slots)
        high_detail_slots = [
            slot for slot in external_slots
            if str(slot.get("id")) in high_detail_slot_ids
        ]
        elements_text += _format_asset_first_layout_constraint(high_detail_slots)

    # Page type hint
    is_cover = page_type == "cover" or slide_number == 1
    is_data = page_type == "data" or slide_number == total_slides
    if is_cover:
        label = "封面页(cover)"
        hint = "标题/副标题处理为视觉焦点,按本风格的封面构图规范处理。"
    elif is_data:
        label = "数据页(data)"
        hint = "突出关键数字、对比或结论;按本风格的数据/总结构图规范处理。"
    else:
        label = "内容页(content)"
        hint = "把要点按本风格的内容构图规范结构化呈现,注意层级、对齐、留白。"

    if external_slots:
        if high_detail_slot_ids:
            layout_line = (
                "\n页面布局: 高细节真实图主视觉页。先围绕参考图角标区域建立大素材面板,"
                "再把标题和 2-3 条短摘要放入剩余窄文字栏;模型只生成背景、短文字、细线、编号和抽象装饰,"
                "不生成任何照片、截图或图片区。"
            )
        else:
            layout_line = (
                "\n页面布局: 按文字元素的位置组织版式;参考图角标区域只作为后续真实图片覆盖区,"
                "模型只生成背景、文字、细线、编号和抽象装饰,不生成任何照片或图片区。"
            )
    else:
        layout_line = f"\n页面布局: {layout}" if layout else ""

    return (
        effective_style_template
        + "\n\n---\n\n"
        + f"现在请生成本组中的【{label}】,{hint}{layout_line}"
        + "\n\n本页各元素的精确描述(请严格按以下布局、位置、样式生成):\n\n"
        + elements_text
        + LANGUAGE_FONT_RULE
    )


def _stringify_content_value(value: Any) -> str:
    if value is None:
        return ""
    if isinstance(value, (list, tuple)):
        return ";".join(str(x).strip() for x in value if str(x).strip())
    if isinstance(value, dict):
        return json.dumps(value, ensure_ascii=False)
    return str(value).strip()


def _element_text_content(elem: Dict[str, Any], *, include_description: bool = False) -> str:
    """Return human-facing text from a slide_spec element.

    SKILL.md documents both `content` and `heading`/`body` element shapes.
    Prompt generation and text-density heuristics must serialize either shape,
    otherwise card-like specs become empty text guides.
    """
    content = _stringify_content_value(elem.get("content"))
    if content:
        return content

    parts: List[str] = []
    for key in ("heading", "title", "label"):
        value = _stringify_content_value(elem.get(key))
        if value:
            parts.append(value)
            break
    for key in ("body", "text"):
        value = _stringify_content_value(elem.get(key))
        if value:
            parts.append(value)
            break

    items = elem.get("items")
    if items is None:
        items = elem.get("bullets")
    item_text = _stringify_content_value(items)
    if item_text:
        parts.append(item_text)

    if parts:
        return ":".join(parts[:2]) + (";" + ";".join(parts[2:]) if len(parts) > 2 else "")

    if include_description:
        return _stringify_content_value(elem.get("description"))
    return ""


def _adapt_style_template_for_external_slots(style_template: str) -> str:
    """Remove generated-photo directives when real images are overlaid later."""
    skipped_sections = {
        "封面页构图",
        "内容页构图",
        "布局系统",
        "图片处理",
        "章节页构图",
        "收尾页构图",
    }
    photo_terms = (
        "image",
        "photo",
        "photograph",
        "photography",
        "crop",
        "full-bleed",
        "imagery",
        "照片",
        "摄影",
        "图片",
        "图像",
    )
    lines = []
    skip = False
    for line in style_template.splitlines():
        stripped = line.strip()
        section_match = re.match(r"^【(.+?)】$", stripped)
        if section_match:
            skip = section_match.group(1) in skipped_sections
            if skip:
                continue
        if skip:
            continue
        if any(term in stripped.lower() for term in photo_terms):
            continue
        lines.append(line)

    override = """

【外部真实图片后贴页覆盖规则 - 最高优先级】
- 本页真实图片会在生成后由代码精确贴入;模型不要生成任何照片、图片裁切、产品照、人物照、场景摄影或类似主体。
- 保留所选风格本身的配色、字体气质、结构线、留白、背景质感和抽象装饰语言。
- 参考图角标区域下方只允许连续背景、轻微纹理或非常轻的抽象装饰;不要出现白色占位块、图片框、卡片、边框、阴影或透明洞。
- 如需要视觉重心,用字号、细线、编号、留白、色块或轻微纹理实现,不要用生成照片实现。
"""
    return "\n".join(lines).strip() + override


# =============================================================================
# Style Template
# =============================================================================

def load_style_template(style_path: str) -> str:
    """Extract the '## 基础提示词模板' section from a style markdown file."""
    with open(style_path, "r", encoding="utf-8") as f:
        content = f.read()

    base_prompt_marker = "## 基础提示词模板"
    start_idx = content.find(base_prompt_marker)

    if start_idx == -1:
        print("Warning: '## 基础提示词模板' section not found, using fallback extraction")
        start_idx = content.find("## ")
        end_idx = content.find("## ", start_idx + 3)
        if start_idx == -1 or end_idx == -1:
            return content
        return content[start_idx + 3:end_idx].strip()

    section_start = start_idx + len(base_prompt_marker)
    next_section_idx = content.find("\n## ", section_start)

    if next_section_idx == -1:
        extracted = content[section_start:]
    else:
        extracted = content[section_start:next_section_idx]

    return extracted.strip()


def _style_layout_sidecar_path(style_path: str) -> Path:
    path = Path(style_path)
    if path.suffix:
        return path.with_suffix(".layouts.json")
    return Path(f"{style_path}.layouts.json")


def load_style_layout_profile(
    style_path: str,
    style_template: str = "",
) -> Optional[Dict[str, Any]]:
    """Load a style's colocated .layouts.json as a RuntimeProfile-compatible dict."""
    sidecar = _style_layout_sidecar_path(style_path)
    if not sidecar.is_file():
        return None

    with open(sidecar, "r", encoding="utf-8") as f:
        profile = json.load(f)
    if not isinstance(profile, dict):
        raise ValueError(f"Style layout sidecar must be a JSON object: {sidecar}")
    layouts = profile.get("layouts")
    if not isinstance(layouts, list) or not layouts:
        raise ValueError(f"Style layout sidecar must contain non-empty layouts: {sidecar}")
    return normalize_runtime_profile(
        profile,
        source_kind="distilled-style",
        global_style=style_template,
        profile_path=str(sidecar),
        style_id=Path(style_path).stem,
    )


def load_style_runtime_profile(
    style_path: str,
    style_template: str = "",
) -> Dict[str, Any]:
    """Compile a sidecar-backed style or reject the obsolete Markdown-only form."""
    sidecar_profile = load_style_layout_profile(style_path, style_template)
    if sidecar_profile:
        return sidecar_profile
    sidecar = _style_layout_sidecar_path(style_path)
    raise ValueError(
        "Markdown-only styles are no longer executable. "
        f"Missing required layout profile: {sidecar}. "
        "Migrate the style to the paired <style>.md + <style>.layouts.json contract "
        "with non-empty layouts, routing, content_capacity, and json_schema fields."
    )


def select_runtime_profile(
    template_candidate: Optional[Dict[str, Any]],
    style_candidate: Optional[Dict[str, Any]],
) -> Optional[Dict[str, Any]]:
    """Apply the single documented precedence rule for runtime profiles."""
    if template_candidate and template_candidate.get("layouts"):
        return template_candidate
    if style_candidate and style_candidate.get("layouts"):
        return style_candidate
    return None


def _normalize_template_profile_references(profile: Dict[str, Any], profile_path: str) -> Dict[str, Any]:
    """Adapt a template-authored profile into the unified RuntimeProfile."""
    return normalize_runtime_profile(
        profile,
        source_kind="template-clone",
        profile_path=profile_path,
    )


def attach_template_layout_profile(
    slide_spec: Optional[Dict[str, Any]],
    matched_layout: Optional[Dict[str, Any]],
) -> Dict[str, Any]:
    """Attach compact template layout metadata to a slide_spec.

    The full TemplateProfile may include absolute reference image paths and
    schema details. Metadata only needs the layout identity and decision hints
    used for later slot planning, editing, and audit.
    """
    spec = copy.deepcopy(slide_spec) if isinstance(slide_spec, dict) else {}
    if not matched_layout:
        return spec

    profile_keys = [
        "id",
        "page_type",
        "summary",
        "visual_signature",
        "content_capacity",
        "best_for",
        "avoid_for",
        "variation_tags",
        "routing",
        "evidence_pages",
        "external_image_slots",
        "reuse_friendly",
        "reuse_reason",
    ]
    compact_profile = {
        key: copy.deepcopy(matched_layout.get(key))
        for key in profile_keys
        if matched_layout.get(key) not in (None, "", [], {})
    }
    spec["template_layout_profile"] = compact_profile

    if not spec.get("layout"):
        layout_id = matched_layout.get("id") or "unknown"
        summary = str(matched_layout.get("summary") or "").strip()
        spec["layout"] = f"模板 {layout_id}:{summary}" if summary else f"模板 {layout_id}"
    return spec


# =============================================================================
# Prompt Generation
# =============================================================================

LANGUAGE_FONT_RULE = """

【强制语言与字体要求】
1. 幻灯片上所有文字必须使用简体中文,严禁出现任何英文单词或句子(产品名称等专有名词可保留英文,其余一律用中文)。
2. 中文字体使用思源黑体(Source Han Sans)或苹方(PingFang SC),字形清晰、笔画规整,严禁使用草书、艺术字或变形字体。
3. 标题字体粗体,正文字体常规,字号对比清晰,确保在演示场景下可读性极高。
"""


def generate_prompt(
    style_template: str,
    page_type: str,
    content_text: str,
    slide_number: int,
    total_slides: int,
    slide_spec: Optional[Dict[str, Any]] = None,
    output_dir: Optional[str] = None,
) -> str:
    """Generate a complete prompt for a single slide.

    When slide_spec is provided (the Agent constructed it from plan + style),
    it produces a precise element-by-element prompt.  Otherwise falls back to
    the original freeform content-based prompt.

    Built-in style prompts provide coarse composition rules; template clone mode
    uses TemplateProfile page types and layout metadata before this fallback path.
    """
    if slide_spec and slide_spec.get("elements"):
        return generate_prompt_from_spec(
            style_template, slide_spec, page_type, slide_number, total_slides,
            output_dir=output_dir,
        )

    is_cover = page_type == "cover" or slide_number == 1
    is_data = page_type == "data" or slide_number == total_slides
    if is_cover:
        label = "封面页(cover)"
        hint = "标题/副标题处理为视觉焦点,按本风格的封面构图规范处理。"
    elif is_data:
        label = "数据页(data)"
        hint = "突出关键数字、对比或结论;按本风格的数据/总结构图规范处理。"
    else:
        label = "内容页(content)"
        hint = "把要点按本风格的内容构图规范结构化呈现,注意层级、对齐、留白。"

    return (
        style_template
        + "\n\n---\n\n"
        + f"现在请生成本组中的【{label}】,{hint}\n"
        + "本页要呈现的内容如下(请按本风格美学重新设计版式,不要原样照搬文本节奏):\n\n"
        + content_text
        + LANGUAGE_FONT_RULE
    )


def compile_runtime_slide_prompt(
    runtime_profile: Dict[str, Any],
    matched_layout: Optional[Dict[str, Any]],
    slide_info: Dict[str, Any],
    *,
    external_slots: Optional[List[Dict[str, Any]]] = None,
) -> str:
    """Compile one slide through the only supported layout-fields strategy."""
    if runtime_profile.get("prompt_strategy") != "layout-fields":
        raise ValueError(
            "Unsupported RuntimeProfile prompt strategy: "
            f"{runtime_profile.get('prompt_strategy')!r}"
        )
    if not matched_layout:
        raise ValueError("RuntimeProfile layout assignment returned no layout")

    try:
        from .template_analyzer import coerce_fields, render_prompt_from_template
    except ImportError:
        from template_analyzer import coerce_fields, render_prompt_from_template

    fields = coerce_fields(slide_info, matched_layout)
    prompt = render_prompt_from_template(
        profile=runtime_profile,
        layout=matched_layout,
        fields=fields,
        language_rule=LANGUAGE_FONT_RULE.strip(),
    )
    if external_slots:
        prompt = adapt_template_prompt_for_external_slots(prompt, external_slots)
        prompt += _format_external_slots_constraint(external_slots)
    return prompt


# =============================================================================
# External image slot support
# =============================================================================

def _parse_bbox(value: Any) -> Optional[List[float]]:
    """Parse a normalized [x, y, w, h] bbox from slide_spec data."""
    if isinstance(value, (list, tuple)) and len(value) == 4:
        try:
            nums = [float(v) for v in value]
        except (TypeError, ValueError):
            return None
        x, y, w, h = nums
        if w <= 0 or h <= 0:
            return None
        # Clamp to the slide bounds; bad input should degrade, not crash a deck.
        x = max(0.0, min(1.0, x))
        y = max(0.0, min(1.0, y))
        w = max(0.0, min(1.0 - x, w))
        h = max(0.0, min(1.0 - y, h))
        return [x, y, w, h] if w > 0 and h > 0 else None
    return None


def _is_reference_only_image_element(elem: Dict[str, Any]) -> bool:
    etype = str(elem.get("type", "")).lower()
    mode = str(elem.get("render_mode") or elem.get("mode") or "").lower()
    if etype in REFERENCE_ONLY_IMAGE_TYPES:
        return True
    if etype in EXTERNAL_IMAGE_TYPES and mode in REFERENCE_ONLY_MODES:
        return True
    preserve_original = _truthy(elem.get("preserve_original"))
    if etype in EXTERNAL_IMAGE_TYPES and preserve_original is False:
        return True
    return False


def _collect_generation_reference_images(slide_spec: Optional[Dict[str, Any]], output_dir: str) -> List[str]:
    """Return source images used as generation references, not PPT overlays."""
    if not slide_spec:
        return []
    refs: List[str] = []
    for elem in (slide_spec.get("elements") or {}).values():
        if not isinstance(elem, dict) or not _is_reference_only_image_element(elem):
            continue
        source = elem.get("source") or elem.get("path") or elem.get("asset")
        resolved = _resolve_asset_path(source, output_dir)
        if resolved and resolved not in refs:
            refs.append(resolved)
    return refs


def _merge_reference_images(
    existing: Optional[Union[str, List[str]]],
    additions: List[str],
) -> Optional[Union[str, List[str]]]:
    if not additions:
        return existing
    refs: List[str] = []
    if isinstance(existing, (list, tuple)):
        refs.extend(str(p) for p in existing if p)
    elif existing:
        refs.append(str(existing))
    refs.extend(str(p) for p in additions if p)
    deduped: List[str] = []
    for ref in refs:
        if ref not in deduped:
            deduped.append(ref)
    if not deduped:
        return None
    return deduped[0] if len(deduped) == 1 else deduped


def _format_generation_reference_constraint(reference_images: List[str]) -> str:
    if not reference_images:
        return ""
    return (
        "\n\n【真实图参考模式】\n"
        f"本页提供了 {len(reference_images)} 张真实图作为生成参考。用户已允许模型对其进行风格化、融合、重绘或版式再设计,"
        "因此这些图片不会在 PPTX 中作为独立对象原样后贴。"
        "请参考其主体、构图、材质、色彩或场景气质来设计页面,但不要承诺像素级保真。"
        "如果原图中包含文字、数字、表格、医学影像、证据截图、诊断图、工程图或任何需要精确读数/识别的内容,"
        "参考模式不适合保真呈现;这类素材应改用 external_image 独立后贴。"
    )


def _collect_external_image_slots(slide_spec: Optional[Dict[str, Any]]) -> List[Dict[str, Any]]:
    """Return normalized external image slot descriptors from a slide_spec.

    Supported element shape:
      {
        "type": "external_image",
        "source": "/path/to/photo.png",
        "position": [0.60, 0.10, 0.32, 0.76],
        "fit": "cover" | "contain",
        "slot": {"padding": 0.012, "fill": "#F7F7F5", "outline": "#1A1A1A"}
      }

    `external_image_placeholder` is also recognized for reference skeletons, but
    final PPTX overlay requires a `source`.
    """
    if not slide_spec:
        return []
    slots: List[Dict[str, Any]] = []
    for elem_id, elem in (slide_spec.get("elements") or {}).items():
        if not isinstance(elem, dict):
            continue
        etype = str(elem.get("type", "")).lower()
        if etype not in EXTERNAL_IMAGE_TYPES:
            continue
        if _is_reference_only_image_element(elem):
            continue
        bbox = _parse_bbox(elem.get("computed_bbox") or elem.get("bbox") or elem.get("position"))
        if not bbox:
            continue
        slot_style = elem.get("slot") if isinstance(elem.get("slot"), dict) else {}
        slots.append({
            "id": str(elem_id),
            "type": etype,
            "bbox": bbox,
            "placement_region": _parse_bbox(elem.get("placement_region") or elem.get("position")),
            "source": elem.get("source") or elem.get("path") or elem.get("asset"),
            "fit": str(elem.get("fit", "contain")).lower(),
            "slot_strategy": str(elem.get("slot_strategy", slot_style.get("strategy", ""))).lower(),
            "tailored_to_asset": bool(elem.get("tailored_to_asset", False)),
            "asset_ratio": elem.get("asset_ratio"),
            "asset_size": elem.get("asset_size"),
            "layout_intent": elem.get("layout_intent"),
            "auto_layout_reason": elem.get("auto_layout_reason"),
            "layout_planning_profile": elem.get("layout_planning_profile"),
            "asset_class": elem.get("asset_class"),
            "detail_level": elem.get("detail_level"),
            "asset_tags": elem.get("asset_tags"),
            "visual_metrics": elem.get("visual_metrics"),
            "trim_whitespace": elem.get("trim_whitespace", slot_style.get("trim_whitespace", "auto")),
            "padding": float(elem.get("padding", slot_style.get("padding", 0.0)) or 0.0),
            "bleed": float(elem.get("bleed", slot_style.get("bleed", 0.0)) or 0.0),
            "mask_bleed": float(elem.get("mask_bleed", slot_style.get("mask_bleed", 0.0)) or 0.0),
            "fill": elem.get("fill", slot_style.get("fill", "#F7F7F5")),
            "mask_fill": elem.get("mask_fill", slot_style.get("mask_fill", slot_style.get("fill", "#F7F7F5"))),
            "outline": elem.get("outline", slot_style.get("outline", "#1A1A1A")),
            "draw_frame": bool(_truthy(elem.get("draw_frame", slot_style.get("draw_frame"))) or False),
            "mask_placeholder": _truthy(elem.get("mask_placeholder", slot_style.get("mask_placeholder", False))) is True,
            "sanitize_background": _truthy(
                elem.get("sanitize_background", slot_style.get("sanitize_background", False))
            ) is True,
            "cleanup_rect": elem.get("cleanup_rect", slot_style.get("cleanup_rect")),
            "outline_width": int(elem.get("outline_width", slot_style.get("outline_width", 0)) or 0),
            "skeleton_canvas_fill": elem.get("skeleton_canvas_fill", slot_style.get("skeleton_canvas_fill", "transparent")),
            "skeleton_fill": elem.get("skeleton_fill", slot_style.get("skeleton_fill", "transparent")),
            "skeleton_outline": elem.get("skeleton_outline", slot_style.get("skeleton_outline", "#000000")),
            "skeleton_outline_width": int(
                elem.get(
                    "skeleton_outline_width",
                    slot_style.get("skeleton_outline_width", slot_style.get("reference_outline_width", 2)),
                ) or 0
            ),
            "skeleton_shape": str(
                elem.get("skeleton_shape", slot_style.get("skeleton_shape", "corners"))
            ).lower(),
            "skeleton_ticks": _truthy(elem.get("skeleton_ticks", slot_style.get("skeleton_ticks", False))) is True,
        })
    return slots


def _slots_with_real_sources(slots: List[Dict[str, Any]], output_dir: str) -> List[Dict[str, Any]]:
    """Keep only slots that point to a real local image asset."""
    return [
        slot for slot in slots
        if _resolve_asset_path(slot.get("source"), output_dir)
    ]


def _hex_to_rgb(value: Any, default: Tuple[int, int, int] = (247, 247, 245)) -> Tuple[int, int, int]:
    if not isinstance(value, str):
        return default
    text = value.strip()
    if text.lower() in {"none", "transparent"}:
        return default
    if text.startswith("#"):
        text = text[1:]
    if len(text) == 3:
        text = "".join(ch * 2 for ch in text)
    if len(text) != 6:
        return default
    try:
        return tuple(int(text[i:i + 2], 16) for i in (0, 2, 4))  # type: ignore[return-value]
    except ValueError:
        return default


def _is_transparent_color(value: Any) -> bool:
    return isinstance(value, str) and value.strip().lower() in {"none", "transparent", "no-fill", "nofill"}


def _resolve_asset_path(source: Any, output_dir: str) -> Optional[str]:
    if not source or not isinstance(source, str):
        return None
    p = Path(source).expanduser()
    if not p.is_absolute():
        p = Path(output_dir) / p
    return str(p.resolve()) if p.is_file() else None


def _norm_rect_to_pixels(rect: List[float], width: int = SLIDE_TRACE_WIDTH, height: int = SLIDE_TRACE_HEIGHT) -> List[int]:
    x, y, w, h = rect
    return [
        int(round(x * width)),
        int(round(y * height)),
        int(round(w * width)),
        int(round(h * height)),
    ]


def _slot_inner_rect(slot: Dict[str, Any]) -> List[float]:
    x, y, w, h = slot["bbox"]
    pad = max(0.0, float(slot.get("padding") or 0.0))
    bleed = max(0.0, float(slot.get("bleed") or 0.0))
    inner_x = max(0.0, x + pad - bleed)
    inner_y = max(0.0, y + pad - bleed)
    inner_w = max(0.001, min(1.0 - inner_x, w - 2 * pad + 2 * bleed))
    inner_h = max(0.001, min(1.0 - inner_y, h - 2 * pad + 2 * bleed))
    return [inner_x, inner_y, inner_w, inner_h]


def _compute_final_image_rect_px(slot: Dict[str, Any], asset_path: str, width: int, height: int) -> List[int]:
    """Return the actual picture rectangle used by contain/cover placement."""
    inner = _slot_inner_rect(slot)
    box_left, box_top, box_w, box_h = _norm_rect_to_pixels(inner, width, height)
    if slot.get("fit") == "cover":
        return [box_left, box_top, box_w, box_h]

    try:
        from PIL import Image
        with Image.open(asset_path) as im:
            ratio = im.width / im.height
    except Exception:
        ratio = box_w / box_h if box_h else 1.0

    box_ratio = box_w / box_h if box_h else ratio
    if ratio >= box_ratio:
        draw_w = box_w
        draw_h = int(draw_w / ratio)
        draw_left = box_left
        draw_top = box_top + int((box_h - draw_h) / 2)
    else:
        draw_h = box_h
        draw_w = int(draw_h * ratio)
        draw_left = box_left + int((box_w - draw_w) / 2)
        draw_top = box_top
    return [draw_left, draw_top, draw_w, draw_h]


def _paste_asset_into_rect(canvas: Any, asset_path: str, rect_px: List[int], fit: str = "contain") -> None:
    from PIL import Image

    left, top, draw_w, draw_h = rect_px
    if draw_w <= 0 or draw_h <= 0:
        return
    asset = Image.open(asset_path).convert("RGB")
    if fit == "cover":
        target_ratio = draw_w / draw_h
        ratio = asset.width / asset.height
        if ratio > target_ratio:
            new_w = int(asset.height * target_ratio)
            x0 = max(0, (asset.width - new_w) // 2)
            asset = asset.crop((x0, 0, x0 + new_w, asset.height))
        elif ratio < target_ratio:
            new_h = int(asset.width / target_ratio)
            y0 = max(0, (asset.height - new_h) // 2)
            asset = asset.crop((0, y0, asset.width, y0 + new_h))
    canvas.paste(asset.resize((draw_w, draw_h)), (left, top))


def _trace_dir(output_dir: str, slide_number: int) -> Path:
    return Path(output_dir) / "external_image_trace" / f"slide-{slide_number:02d}"


def _write_json(path: Path, data: Dict[str, Any]) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")


def _load_trace_manifest(path: Path) -> Dict[str, Any]:
    if path.is_file():
        try:
            return json.loads(path.read_text(encoding="utf-8"))
        except Exception:
            return {}
    return {}


def _truthy(value: Any) -> Optional[bool]:
    if isinstance(value, bool):
        return value
    if isinstance(value, (int, float)):
        return bool(value)
    if isinstance(value, str):
        text = value.strip().lower()
        if text in {"1", "true", "yes", "y", "on"}:
            return True
        if text in {"0", "false", "no", "n", "off"}:
            return False
    return None


def _asset_size_and_ratio(source: Any, output_dir: str) -> Optional[Tuple[int, int, float]]:
    path = _resolve_asset_path(source, output_dir)
    if not path:
        return None
    try:
        from PIL import Image
        with Image.open(path) as im:
            if im.width <= 0 or im.height <= 0:
                return None
            return im.width, im.height, im.width / im.height
    except Exception as e:
        print(f"(!)  无法读取外部图片尺寸,跳过量体裁衣: {path} ({e})")
        return None


def _fit_bbox_to_asset_ratio(
    region: List[float],
    asset_ratio: float,
    padding: float = 0.0,
    anchor: str = "center",
) -> List[float]:
    """Fit a slot inside a normalized slide region while preserving asset ratio.

    The existing overlay code treats `padding` as normalized x/y in slide
    coordinates, so the inner normalized ratio must be adjusted by the 16:9
    slide aspect to match the image's actual pixel ratio.
    """
    slide_aspect = 16.0 / 9.0
    x, y, w, h = region
    pad = max(0.0, min(float(padding or 0.0), min(w, h) / 2.0 - 0.0005))
    inner_max_w = max(0.001, w - 2 * pad)
    inner_max_h = max(0.001, h - 2 * pad)
    target_norm_ratio = max(0.001, asset_ratio / slide_aspect)

    if inner_max_w / inner_max_h >= target_norm_ratio:
        inner_h = inner_max_h
        inner_w = inner_h * target_norm_ratio
    else:
        inner_w = inner_max_w
        inner_h = inner_w / target_norm_ratio

    outer_w = min(w, inner_w + 2 * pad)
    outer_h = min(h, inner_h + 2 * pad)

    anchor_text = (anchor or "center").lower().replace("_", "-")
    if "left" in anchor_text:
        out_x = x
    elif "right" in anchor_text:
        out_x = x + w - outer_w
    else:
        out_x = x + (w - outer_w) / 2

    if "top" in anchor_text:
        out_y = y
    elif "bottom" in anchor_text:
        out_y = y + h - outer_h
    else:
        out_y = y + (h - outer_h) / 2

    return [
        max(0.0, min(1.0, out_x)),
        max(0.0, min(1.0, out_y)),
        max(0.001, min(1.0 - out_x, outer_w)),
        max(0.001, min(1.0 - out_y, outer_h)),
    ]


def _external_element_items(slide_spec: Dict[str, Any]) -> List[Tuple[str, Dict[str, Any]]]:
    items: List[Tuple[str, Dict[str, Any]]] = []
    for elem_id, elem in (slide_spec.get("elements") or {}).items():
        if not isinstance(elem, dict):
            continue
        etype = str(elem.get("type", "")).lower()
        if etype in EXTERNAL_IMAGE_TYPES and not _is_reference_only_image_element(elem):
            items.append((str(elem_id), elem))
    return items


def _slide_text_load(slide_spec: Dict[str, Any]) -> int:
    chars = 0
    for elem in (slide_spec.get("elements") or {}).values():
        if not isinstance(elem, dict):
            continue
        etype = str(elem.get("type", "")).lower()
        if etype in EXTERNAL_IMAGE_TYPES or etype in REFERENCE_ONLY_IMAGE_TYPES:
            continue
        chars += len(_element_text_content(elem, include_description=True))
    layout_text = str(slide_spec.get("layout") or "")
    return chars + min(len(layout_text), 80)


def _slide_text_profile(slide_spec: Dict[str, Any]) -> Dict[str, Any]:
    title_chars = 0
    body_chars = 0
    text_blocks = 0
    for elem in (slide_spec.get("elements") or {}).values():
        if not isinstance(elem, dict):
            continue
        etype = str(elem.get("type", "")).lower()
        if etype in EXTERNAL_IMAGE_TYPES or etype in REFERENCE_ONLY_IMAGE_TYPES:
            continue
        length = len(_element_text_content(elem, include_description=True))
        if not length:
            continue
        text_blocks += 1
        if etype in {"title", "headline", "heading", "subtitle"}:
            title_chars += length
        else:
            body_chars += length
    layout_chars = min(len(str(slide_spec.get("layout") or "")), 80)
    text_load = title_chars + body_chars + layout_chars
    if text_load >= 180:
        density = "heavy"
    elif text_load >= 90:
        density = "medium"
    else:
        density = "light"
    return {
        "title_chars": title_chars,
        "body_chars": body_chars,
        "layout_chars": layout_chars,
        "text_blocks": text_blocks,
        "text_load": text_load,
        "density": density,
    }


def _is_auto_external_layout(elem: Dict[str, Any]) -> bool:
    intent = str(elem.get("layout_intent", elem.get("auto_layout", ""))).strip().lower()
    position = elem.get("position")
    return (
        intent in {"auto", "auto-layout", "autolayout", "smart", "smart-layout"}
        or (isinstance(position, str) and position.strip().lower() in {"auto", "auto-layout", "smart"})
        or position is None
    )


def _analyze_external_asset_visual(source: Any, output_dir: str) -> Dict[str, Any]:
    """Heuristically classify a real image before layout planning.

    This is deliberately local and deterministic. Vision review remains the
    final guard, but these tags let the first generation start with a better
    slot size instead of learning only after a failed overlay review.
    """
    path = _resolve_asset_path(source, output_dir)
    if not path:
        return {}
    try:
        from PIL import Image, ImageStat

        with Image.open(path) as im:
            original_w, original_h = im.size
            rgb = im.convert("RGB")
            rgb.thumbnail((256, 256))
            stat = ImageStat.Stat(rgb)
            mean = stat.mean
            stddev = stat.stddev
            pixels = list(rgb.getdata())
            total = max(1, len(pixels))
            white_ratio = sum(1 for r, g, b in pixels if r > 238 and g > 238 and b > 238) / total
            dark_ratio = sum(1 for r, g, b in pixels if r < 80 and g < 80 and b < 80) / total
            color_std = sum(stddev) / 3.0

            gray = rgb.convert("L")
            w, h = gray.size
            edge_hits = 0
            edge_total = 0
            if w > 1 and h > 1:
                pix = gray.load()
                step = max(1, min(w, h) // 96)
                for y in range(0, h - step, step):
                    for x in range(0, w - step, step):
                        gx = abs(int(pix[x + step, y]) - int(pix[x, y]))
                        gy = abs(int(pix[x, y + step]) - int(pix[x, y]))
                        if gx + gy > 42:
                            edge_hits += 1
                        edge_total += 1
            edge_density = edge_hits / max(1, edge_total)
    except Exception:
        return {}

    ratio = original_w / original_h if original_h else 1.0
    tags: List[str] = []
    if ratio >= 2.0:
        tags.append("wide")
    elif ratio <= 0.8:
        tags.append("portrait")
    else:
        tags.append("standard-ratio")
    if white_ratio > 0.45:
        tags.append("white-background")
    if edge_density > 0.16:
        tags.append("dense-lines")
    elif edge_density > 0.09:
        tags.append("line-art")
    if dark_ratio > 0.08:
        tags.append("text-like")
    if color_std > 58 and white_ratio < 0.35:
        tags.append("photo-like")

    if "photo-like" in tags and edge_density < 0.12:
        asset_class = "photo"
        detail_level = "normal"
    elif ratio >= 2.0 and (white_ratio > 0.35 or dark_ratio > 0.06):
        asset_class = "wide-document"
        detail_level = "high"
    elif white_ratio > 0.65 and edge_density > 0.04 and color_std < 35:
        asset_class = "dense-diagram"
        detail_level = "critical"
    elif white_ratio > 0.45 and edge_density > 0.13:
        asset_class = "dense-diagram"
        detail_level = "critical"
    elif white_ratio > 0.35 and (edge_density > 0.08 or dark_ratio > 0.08):
        asset_class = "chart-or-document"
        detail_level = "high"
    else:
        asset_class = "general-image"
        detail_level = "normal"

    return {
        "asset_class": asset_class,
        "detail_level": detail_level,
        "asset_tags": tags,
        "visual_metrics": {
            "white_ratio": round(white_ratio, 4),
            "dark_ratio": round(dark_ratio, 4),
            "edge_density": round(edge_density, 4),
            "color_std": round(color_std, 2),
            "mean_rgb": [round(x, 2) for x in mean],
        },
    }


def _external_asset_detail_level(slide_spec: Dict[str, Any], elem_id: str, elem: Dict[str, Any]) -> str:
    """Classify whether a real asset needs enough size to be read, not just seen."""
    explicit = str(
        elem.get("detail_level")
        or elem.get("readability")
        or elem.get("readability_priority")
        or ""
    ).strip().lower()
    if explicit in {"low", "photo", "decorative", "ambient"}:
        return "low"

    asset_class = str(elem.get("asset_class") or "").lower()
    if explicit in {"critical", "very-high", "dense", "dense-diagram"}:
        return "critical"
    if asset_class in {"dense-diagram", "dense-chart", "architecture-diagram"}:
        return "critical"
    if explicit in {"high", "detail", "detailed", "readable", "legible", "text-heavy", "diagram"}:
        return "high"
    if asset_class in {"wide-document", "chart-or-document", "screenshot-document"}:
        return "high"

    context = " ".join(
        str(x)
        for x in [
            elem_id,
            elem.get("label", ""),
            elem.get("caption", ""),
            elem.get("description", ""),
            slide_spec.get("layout", ""),
        ]
    ).lower()
    high_terms = {
        "paper", "table", "proof", "architecture", "diagram", "chart", "curve",
        "graph", "screenshot", "code", "formula", "equation", "lean", "result",
        "论文", "表格", "证明", "架构", "流程", "图表", "曲线", "截图", "代码",
        "公式", "定理", "结果", "系统图",
    }
    if any(term in context for term in high_terms):
        return "high"
    return "normal"


def _region_area(region: List[float]) -> float:
    return max(0.0, float(region[2])) * max(0.0, float(region[3]))


def _region_fit_efficiency(region: List[float], ratio: float) -> float:
    """How much of a candidate slot a contain-fitted asset can actually use."""
    if ratio <= 0:
        return 0.0
    x, y, w, h = region
    px_w = w * SLIDE_TRACE_WIDTH
    px_h = h * SLIDE_TRACE_HEIGHT
    if px_w <= 1 or px_h <= 1:
        return 0.0
    slot_ratio = px_w / px_h
    if slot_ratio >= ratio:
        used_w = px_h * ratio
        used_h = px_h
    else:
        used_w = px_w
        used_h = px_w / ratio
    return max(0.0, min(1.0, (used_w * used_h) / (px_w * px_h)))


def _normalize_candidate_region(region: Any) -> Optional[List[float]]:
    parsed = _parse_bbox(region)
    if not parsed:
        return None
    x, y, w, h = parsed
    if w < 0.12 or h < 0.12:
        return None
    return [x, y, w, h]


def _template_slot_candidates(slide_spec: Dict[str, Any]) -> List[Tuple[List[float], str, float]]:
    """Return template/style-derived image zones before generic fallback rules.

    The template analyzer can provide explicit normalized media slots. Older
    profiles and built-in styles may only have a layout summary, so we also
    infer a few candidate zones from common composition language.
    """
    candidates: List[Tuple[List[float], str, float]] = []
    profile = slide_spec.get("template_layout_profile")
    summary = ""
    if isinstance(profile, dict):
        summary = " ".join(
            str(x)
            for x in [
                profile.get("id", ""),
                profile.get("page_type", ""),
                profile.get("summary", ""),
            ]
        )
        for idx, slot in enumerate(profile.get("external_image_slots") or []):
            if not isinstance(slot, dict):
                continue
            region = _normalize_candidate_region(slot.get("bbox"))
            if not region:
                continue
            try:
                priority = float(slot.get("priority", idx + 1) or (idx + 1))
            except (TypeError, ValueError):
                priority = idx + 1
            candidates.append((
                region,
                f"template explicit slot {slot.get('id') or idx + 1}: {slot.get('purpose', '')}".strip(),
                max(0.70, 1.25 - 0.12 * (priority - 1)),
            ))

    layout_text = " ".join(
        str(x)
        for x in [
            summary,
            slide_spec.get("layout", ""),
            slide_spec.get("page_type", ""),
        ]
    ).lower()

    def add(region: List[float], reason: str, weight: float) -> None:
        parsed = _normalize_candidate_region(region)
        if parsed:
            candidates.append((parsed, reason, weight))

    # Explicit directional patterns. Phrases like "左文右图" mean the image zone
    # is on the right; "右文左图" means the image zone is on the left.
    if any(t in layout_text for t in [
        "左文右图", "右侧为图", "右侧为图片", "右侧为照片", "图像在右", "图片在右",
        "left text right image", "text left image right", "right image", "image on the right",
        "photo on the right", "right photo", "photo right", "right photograph", "right visual",
        "right landscape photo", "right preserved landscape photo",
        "media on the right",
    ]):
        add([0.52, 0.10, 0.42, 0.78], "template inferred right image column", 1.10)
    if any(t in layout_text for t in [
        "右文左图", "左侧为图", "左侧为图片", "左侧为照片", "图像在左", "图片在左",
        "right text left image", "text right image left", "left image", "image on the left",
        "photo on the left", "left photo", "photo left", "left photograph", "left visual",
        "left landscape photo", "left preserved landscape photo",
        "media on the left",
    ]):
        add([0.06, 0.10, 0.42, 0.78], "template inferred left image column", 1.10)
    if any(t in layout_text for t in ["图片区在左", "左侧图片", "左侧照片", "左侧主视觉", "left visual", "left media"]):
        add([0.06, 0.10, 0.44, 0.78], "template inferred left visual region", 1.08)
    if any(t in layout_text for t in ["图片区在右", "右侧图片", "右侧照片", "右侧主视觉", "right visual", "right media"]):
        add([0.50, 0.10, 0.44, 0.78], "template inferred right visual region", 1.08)
    if any(t in layout_text for t in ["底部图片", "底部图表", "下方图片", "bottom image", "bottom chart", "lower image"]):
        add([0.08, 0.56, 0.84, 0.36], "template inferred bottom media band", 1.04)
    if any(t in layout_text for t in ["顶部图片", "顶部图表", "上方图片", "top image", "top chart", "upper image"]):
        add([0.08, 0.10, 0.84, 0.36], "template inferred top media band", 1.02)
    if any(t in layout_text for t in ["中央主视觉", "居中主视觉", "中心图片", "central visual", "center visual", "centered image"]):
        add([0.22, 0.14, 0.56, 0.68], "template inferred central visual region", 1.02)
    if any(t in layout_text for t in ["分屏", "split screen", "split-screen"]):
        add([0.52, 0.08, 0.42, 0.84], "template inferred split-screen right panel", 0.96)
        add([0.06, 0.08, 0.42, 0.84], "template inferred split-screen left panel", 0.94)

    # De-duplicate near-identical candidates while keeping the highest weight.
    deduped: List[Tuple[List[float], str, float]] = []
    for region, reason, weight in candidates:
        for idx, (existing, existing_reason, existing_weight) in enumerate(deduped):
            if _bbox_delta(existing, region) < 0.08:
                if weight > existing_weight:
                    deduped[idx] = (region, reason, weight)
                break
        else:
            deduped.append((region, reason, weight))
    return deduped


def _choose_template_aware_region(
    slide_spec: Dict[str, Any],
    elem_id: str,
    elem: Dict[str, Any],
    asset_ratio: Optional[float],
    text_profile: Dict[str, Any],
    total: int,
    index: int,
    detail_level: str,
    planning_bits: str,
) -> Optional[Tuple[List[float], str]]:
    candidates = _template_slot_candidates(slide_spec)
    if not candidates:
        return None
    ratio = asset_ratio or 1.6
    text_load = int(text_profile["text_load"])
    density = str(text_profile["density"])
    min_area = 0.18
    if detail_level == "high":
        min_area = 0.26
    elif detail_level == "critical":
        min_area = 0.36
    if total >= 2:
        min_area *= 0.62

    best: Optional[Tuple[float, List[float], str]] = None
    for region, reason, weight in candidates:
        x, y, w, h = region
        area = _region_area(region)
        fit = _region_fit_efficiency(region, ratio)
        if detail_level in {"high", "critical"} and fit < 0.52:
            # A template may expose a very wide media band, but a standard-ratio
            # chart/table would render as a small thumbnail inside it. In that
            # case preserving the template slot is worse than choosing a more
            # balanced readable region.
            continue
        score = weight + min(area / max(min_area, 0.01), 1.35) * 0.55 + fit * 0.35
        if detail_level in {"high", "critical"} and area < min_area:
            score -= (min_area - area) * 2.0
        if density == "heavy" and y < 0.18 and h > 0.65 and 0.18 < x < 0.45:
            score -= 0.18
        if total == 1 and detail_level in {"high", "critical"} and area >= min_area:
            score += 0.12
        if best is None or score > best[0]:
            best = (score, region, f"{reason}; score={score:.2f}; {planning_bits}")

    if not best:
        return None
    score, region, reason = best
    # Do not force a tiny template thumbnail slot for dense assets. In that
    # case, let the generic readability fallback choose a larger area.
    if detail_level in {"high", "critical"} and _region_area(region) < min_area * 0.82:
        return None
    return region, f"template-aware slot selected: {reason}"


def _auto_external_image_region(
    slide_spec: Dict[str, Any],
    elem_id: str,
    elem: Dict[str, Any],
    asset_ratio: Optional[float],
    index: int,
    total: int,
) -> Tuple[List[float], str]:
    """Choose an allowed region for a real image before generating the slide."""
    ratio = asset_ratio or 1.6
    text_profile = _slide_text_profile(slide_spec)
    text_load = int(text_profile["text_load"])
    title_chars = int(text_profile["title_chars"])
    density = str(text_profile["density"])
    page_type = str(slide_spec.get("page_type", "") or "").lower()
    detail_level = _external_asset_detail_level(slide_spec, elem_id, elem)
    planning_context = " ".join(
        str(x)
        for x in [
            elem_id,
            elem.get("label", ""),
            elem.get("caption", ""),
            elem.get("description", ""),
            slide_spec.get("layout", ""),
        ]
    ).lower()
    structural_terms = {
        "architecture", "diagram", "flow", "workflow", "system", "agent",
        "transformer", "pipeline", "loop", "架构", "流程", "系统", "闭环",
        "模块", "链路",
    }
    is_structural_diagram = any(term in planning_context for term in structural_terms)
    planning_bits = (
        f"text_density={density}; title_chars={title_chars}; "
        f"text_load={text_load}; image_count={total}; ratio={ratio:.2f}; detail={detail_level}"
    )

    template_region = _choose_template_aware_region(
        slide_spec, elem_id, elem, asset_ratio, text_profile, total, index, detail_level, planning_bits
    )
    if template_region:
        return template_region

    if total >= 3:
        col_w = 0.78 / min(total, 3)
        col = index % 3
        row = index // 3
        y = 0.62 if density in {"medium", "heavy"} and row == 0 else (0.58 if row == 0 else 0.34)
        return [0.11 + col * col_w, y, col_w - 0.025, 0.26], (
            f"auto multi-image grid after text-first planning; {planning_bits}"
        )

    if total == 2:
        if detail_level in {"high", "critical"}:
            if ratio < 0.8:
                return [0.48 + index * 0.24, 0.10, 0.22, 0.78], (
                    f"auto two readable portrait rails; {planning_bits}"
                )
            return [0.08 + index * 0.44, 0.54, 0.40, 0.36], (
                f"auto two readable bottom panels; {planning_bits}"
            )
        if ratio < 0.8:
            return [0.08 + index * 0.28, 0.18, 0.24, 0.64], (
                f"auto two portrait side-by-side; {planning_bits}"
            )
        if density == "light":
            return [0.10 + index * 0.42, 0.52, 0.38, 0.34], (
                f"auto two-image lower gallery with open title area; {planning_bits}"
            )
        return [0.56, 0.15 + index * 0.35, 0.36, 0.29], (
            f"auto two-image right column; {planning_bits}"
        )

    if detail_level == "critical":
        if ratio >= 2.0:
            return [0.06, 0.48, 0.88, 0.44], (
                f"auto near-full bottom panel for critical wide asset; {planning_bits}"
            )
        if ratio < 0.8:
            return [0.52, 0.08, 0.42, 0.84], (
                f"auto near-full right rail for critical portrait asset; {planning_bits}"
            )
        if not is_structural_diagram and text_load >= 80:
            return [0.34, 0.06, 0.62, 0.88], (
                f"auto enlarged right chart/document panel with compact protected text rail; {planning_bits}"
            )
        return [0.30, 0.08, 0.66, 0.84], (
            f"auto right panel with protected text rail for critical detailed asset; {planning_bits}"
        )

    if detail_level == "high":
        if ratio >= 2.0:
            return [0.08, 0.52, 0.84, 0.40], (
                f"auto large bottom band for detailed wide asset; {planning_bits}"
            )
        if ratio < 0.8:
            return [0.58, 0.10, 0.36, 0.78], (
                f"auto large right rail for detailed portrait asset; {planning_bits}"
            )
        return [0.46, 0.10, 0.48, 0.80], (
            f"auto large right panel for detailed asset; {planning_bits}"
        )

    if text_load >= 180:
        if ratio >= 1.25:
            return [0.56, 0.20, 0.36, 0.50], f"auto right landscape block for text-heavy slide; {planning_bits}"
        if ratio < 0.8:
            return [0.68, 0.17, 0.24, 0.64], f"auto narrow right rail for text-heavy portrait; {planning_bits}"
        return [0.64, 0.22, 0.28, 0.42], f"auto compact right slot for text-heavy slide; {planning_bits}"

    if text_load >= 90:
        if ratio < 0.8:
            return [0.66, 0.14, 0.26, 0.68], f"auto right portrait rail for medium text; {planning_bits}"
        return [0.56, 0.18, 0.36, 0.52], f"auto right image block for medium text; {planning_bits}"

    if page_type == "cover" and ratio >= 1.1:
        return [0.52, 0.18, 0.40, 0.56], f"auto cover hero slot; {planning_bits}"
    if ratio < 0.8:
        return [0.66, 0.14, 0.26, 0.70], f"auto right portrait feature rail; {planning_bits}"
    return [0.54, 0.18, 0.38, 0.54], f"auto standard right slot; {planning_bits}"


def prepare_external_image_slots(slide_spec: Optional[Dict[str, Any]], output_dir: str) -> Optional[Dict[str, Any]]:
    """Compute final external image bboxes before prompt/skeleton/PPTX.

    For `tailor_to_asset` / `slot_strategy: fit-within`, `position` is treated
    as the allowed region. The function writes a code-owned `computed_bbox`
    based on the real asset's aspect ratio, and later stages all consume that
    same bbox. This keeps the skeleton reference and PPTX overlay in sync.
    """
    if not slide_spec or not slide_spec.get("elements"):
        return slide_spec

    prepared = copy.deepcopy(slide_spec)
    external_items = _external_element_items(prepared)
    total_external = len(external_items)
    for idx, (_elem_id, elem) in enumerate(external_items):
        if not isinstance(elem, dict):
            continue
        etype = str(elem.get("type", "")).lower()
        if etype not in EXTERNAL_IMAGE_TYPES or _is_reference_only_image_element(elem):
            continue

        slot_style = elem.get("slot") if isinstance(elem.get("slot"), dict) else {}
        source = elem.get("source") or elem.get("path") or elem.get("asset")
        size_ratio = _asset_size_and_ratio(source, output_dir)
        if size_ratio:
            asset_w, asset_h, asset_ratio = size_ratio
            elem["asset_size"] = [asset_w, asset_h]
            elem["asset_ratio"] = round(asset_ratio, 6)
        else:
            asset_ratio = None
        visual_analysis = _analyze_external_asset_visual(source, output_dir)
        if visual_analysis:
            elem.setdefault("asset_class", visual_analysis.get("asset_class"))
            elem.setdefault("asset_tags", visual_analysis.get("asset_tags"))
            elem["visual_metrics"] = visual_analysis.get("visual_metrics")
            if not any(elem.get(k) for k in ("detail_level", "readability", "readability_priority")):
                elem["detail_level"] = visual_analysis.get("detail_level")

        if _is_auto_external_layout(elem):
            region, reason = _auto_external_image_region(prepared, _elem_id, elem, asset_ratio, idx, total_external)
            elem["position"] = region
            elem["auto_layout_reason"] = reason
            elem["layout_intent"] = "auto"
            elem["layout_planning_profile"] = {
                **_slide_text_profile(prepared),
                "image_count": total_external,
                "image_index": idx,
                "asset_ratio": round(asset_ratio, 6) if asset_ratio else None,
                "detail_level": _external_asset_detail_level(prepared, _elem_id, elem),
                "asset_class": elem.get("asset_class"),
            }
        else:
            region = _parse_bbox(elem.get("position") or elem.get("bbox"))
        if not region:
            continue

        strategy = str(elem.get("slot_strategy", slot_style.get("strategy", ""))).lower()
        tailor_flag = _truthy(elem.get("tailor_to_asset", slot_style.get("tailor_to_asset")))
        fit = str(elem.get("fit", "contain")).lower()

        # Back-compatible rule: explicit bbox remains exact by default. A
        # position-only contain image is usually an allowed region, so tailor it.
        should_tailor = (
            asset_ratio is not None
            and strategy not in {"exact", "fixed", "cover-region"}
            and (
                tailor_flag is True
                or strategy in {"fit-within", "contain-within", "tailored-contain", "asset-fit"}
                or (tailor_flag is None and "bbox" not in elem and fit == "contain")
            )
        )

        elem["placement_region"] = region
        if should_tailor:
            padding = float(elem.get("padding", slot_style.get("padding", 0.0)) or 0.0)
            anchor = str(elem.get("anchor", slot_style.get("anchor", "center")))
            elem["computed_bbox"] = _fit_bbox_to_asset_ratio(region, asset_ratio, padding, anchor)
            elem["tailored_to_asset"] = True
            elem["slot_strategy"] = strategy or "fit-within"
        else:
            elem["computed_bbox"] = _parse_bbox(elem.get("bbox") or elem.get("position"))
            elem["tailored_to_asset"] = False
            if strategy:
                elem["slot_strategy"] = strategy

    return prepared


def create_asset_reference_skeleton(
    output_dir: str,
    slide_number: int,
    slide_spec: Optional[Dict[str, Any]],
) -> Optional[str]:
    """Create a transparent skeleton reference image marking external image slots.

    This reference gives gpt-image-2 a concrete visual constraint for reserved
    space. The final geometry still comes from slide_spec bbox values.
    """
    slide_spec = prepare_external_image_slots(slide_spec, output_dir)
    slots = _slots_with_real_sources(_collect_external_image_slots(slide_spec), output_dir)
    if not slots:
        return None
    try:
        from PIL import Image, ImageDraw
    except ImportError:
        print("(!)  缺 Pillow,跳过外部图片槽位参考图生成(pip install pillow)")
        return None

    width, height = SLIDE_TRACE_WIDTH, SLIDE_TRACE_HEIGHT
    canvas_fill = slots[0].get("skeleton_canvas_fill", "transparent")
    if _is_transparent_color(canvas_fill):
        img = Image.new("RGBA", (width, height), (0, 0, 0, 0))
    else:
        img = Image.new("RGB", (width, height), _hex_to_rgb(canvas_fill, (247, 247, 245)))
    draw = ImageDraw.Draw(img)
    real_on_blank = Image.new("RGB", (width, height), (247, 247, 245))
    trace_slots: List[Dict[str, Any]] = []
    for slot in slots:
        asset_path = _resolve_asset_path(slot.get("source"), output_dir)
        display_asset_path = _display_asset_for_slot(slot, asset_path, output_dir, slide_number) if asset_path else None
        inner_rect = _slot_inner_rect(slot)
        final_rect_px = None
        if display_asset_path:
            final_rect_px = _compute_final_image_rect_px(slot, display_asset_path, width, height)
        else:
            final_rect_px = _norm_rect_to_pixels(inner_rect, width, height)
        rect = [
            final_rect_px[0],
            final_rect_px[1],
            final_rect_px[0] + final_rect_px[2],
            final_rect_px[1] + final_rect_px[3],
        ]
        fill = None if _is_transparent_color(slot.get("skeleton_fill")) else _hex_to_rgb(slot.get("skeleton_fill"), (244, 240, 235))
        outline_width = int(slot.get("skeleton_outline_width") or 0)
        outline = _hex_to_rgb(slot.get("skeleton_outline"), (216, 211, 200))
        skeleton_shape = str(slot.get("skeleton_shape") or "corners").lower()
        if skeleton_shape in {"outline", "rectangle", "rect"} and outline_width > 0:
            draw.rectangle(rect, fill=fill, outline=outline, width=outline_width)
        elif skeleton_shape in {"fill", "filled"}:
            if fill is not None:
                draw.rectangle(rect, fill=fill)
        elif skeleton_shape not in {"none", "off", "false"} and outline_width > 0:
            # Closed rectangles are often interpreted by image models as real
            # photo frames. Corner marks preserve the geometry while making the
            # guide less likely to become a visible placeholder in the output.
            x1, y1, x2, y2 = rect
            mark = max(14, min(x2 - x1, y2 - y1) // 10)
            corners = (
                ((x1, y1), (x1 + mark, y1), (x1, y1 + mark)),
                ((x2, y1), (x2 - mark, y1), (x2, y1 + mark)),
                ((x1, y2), (x1 + mark, y2), (x1, y2 - mark)),
                ((x2, y2), (x2 - mark, y2), (x2, y2 - mark)),
            )
            for corner, horizontal, vertical in corners:
                draw.line((corner, horizontal), fill=outline, width=outline_width)
                draw.line((corner, vertical), fill=outline, width=outline_width)
        if slot.get("skeleton_ticks"):
            # Optional corner ticks are useful for debugging, but should stay
            # off by default because image models may copy them into the slide.
            line_w = max(1, outline_width)
            tick = max(10, min(rect[2] - rect[0], rect[3] - rect[1]) // 20)
            for cx, cy in ((rect[0], rect[1]), (rect[2], rect[1]), (rect[0], rect[3]), (rect[2], rect[3])):
                draw.line((cx - tick, cy, cx + tick, cy), fill=outline, width=line_w)
                draw.line((cx, cy - tick, cx, cy + tick), fill=outline, width=line_w)

        if display_asset_path:
            _paste_asset_into_rect(real_on_blank, display_asset_path, final_rect_px, fit=slot.get("fit", "contain"))

        trace_slots.append({
            "id": slot.get("id"),
            "source": asset_path,
            "display_source": display_asset_path,
            "fit": slot.get("fit"),
            "slot_bbox_norm": slot.get("bbox"),
            "slot_bbox_px": _norm_rect_to_pixels(slot.get("bbox"), width, height),
            "inner_rect_norm": inner_rect,
            "inner_rect_px": _norm_rect_to_pixels(inner_rect, width, height),
            "reference_rect_px": final_rect_px,
            "final_image_rect_px": final_rect_px,
            "padding": slot.get("padding"),
            "bleed": slot.get("bleed"),
            "skeleton_canvas_fill": slot.get("skeleton_canvas_fill"),
            "skeleton_shape": skeleton_shape,
            "layout_intent": slot.get("layout_intent"),
            "auto_layout_reason": slot.get("auto_layout_reason"),
            "tailored_to_asset": slot.get("tailored_to_asset"),
            "asset_size": slot.get("asset_size"),
            "asset_ratio": slot.get("asset_ratio"),
        })

    ref_dir = Path(output_dir) / "references"
    ref_dir.mkdir(parents=True, exist_ok=True)
    ref_path = ref_dir / f"slide-{slide_number:02d}-asset-skeleton.png"
    img.save(ref_path)

    trace = _trace_dir(output_dir, slide_number)
    trace.mkdir(parents=True, exist_ok=True)
    step1 = trace / "step1-real-on-blank.png"
    step2 = trace / "step2-reference-outline-blank.png"
    real_on_blank.save(step1)
    img.save(step2)
    manifest_path = trace / "manifest.json"
    manifest = _load_trace_manifest(manifest_path)
    manifest.update({
        "slide_number": slide_number,
        "canvas_size": [width, height],
        "step1_real_on_blank": str(step1),
        "step2_reference_outline_blank": str(step2),
        "reference_image_used": str(ref_path),
        "slots": trace_slots,
    })
    _write_json(manifest_path, manifest)
    return str(ref_path)


def _crop_image_to_ratio(src: str, dst: str, target_ratio: float) -> str:
    from PIL import Image

    im = Image.open(src).convert("RGB")
    ratio = im.width / im.height
    if ratio > target_ratio:
        new_w = int(im.height * target_ratio)
        left = max(0, (im.width - new_w) // 2)
        im = im.crop((left, 0, left + new_w, im.height))
    elif ratio < target_ratio:
        new_h = int(im.width / target_ratio)
        top = max(0, (im.height - new_h) // 2)
        im = im.crop((0, top, im.width, top + new_h))
    Path(dst).parent.mkdir(parents=True, exist_ok=True)
    im.save(dst, quality=95)
    return dst


def _truthy_or_auto(value: Any) -> Optional[bool]:
    if value is None:
        return None
    text = str(value).strip().lower()
    if text in {"auto", "smart", "default"}:
        return None
    return _truthy(value)


def _trim_white_margins(src: str, dst: str, threshold: int = 248, padding: int = 10) -> str:
    from PIL import Image, ImageChops

    im = Image.open(src).convert("RGB")
    bg = Image.new("RGB", im.size, (255, 255, 255))
    diff = ImageChops.difference(im, bg).convert("L")
    # Treat near-white pixels as background so screenshot/document margins are
    # removed, while retaining axes, labels, arrows, colored boxes, and text.
    mask = diff.point(lambda p: 255 if p > (255 - threshold) else 0)
    bbox = mask.getbbox()
    if not bbox:
        return src
    left, top, right, bottom = bbox
    left = max(0, left - padding)
    top = max(0, top - padding)
    right = min(im.width, right + padding)
    bottom = min(im.height, bottom + padding)
    if (right - left) >= im.width * 0.96 and (bottom - top) >= im.height * 0.96:
        return src
    Path(dst).parent.mkdir(parents=True, exist_ok=True)
    im.crop((left, top, right, bottom)).save(dst, quality=95)
    return dst


def _display_asset_for_slot(slot: Dict[str, Any], asset_path: str, output_dir: str, slide_number: int) -> str:
    explicit = _truthy_or_auto(slot.get("trim_whitespace"))
    detail_level = str(slot.get("detail_level") or "").lower()
    tags = {str(x).lower() for x in (slot.get("asset_tags") or [])}
    should_trim = explicit
    if should_trim is None:
        should_trim = detail_level in {"high", "critical"} and "white-background" in tags
    if not should_trim:
        return asset_path
    dst = os.path.join(
        output_dir,
        "assets",
        "_trimmed",
        f"slide-{slide_number:02d}-{slot.get('id', 'asset')}.jpg",
    )
    try:
        return _trim_white_margins(asset_path, dst)
    except Exception as e:
        print(f"(!)  白边裁切失败,使用原图: {asset_path} ({e})")
        return asset_path


def _add_external_image_overlays(prs: Any, slide: Any, slide_number: int, slide_spec: Dict[str, Any], output_dir: str) -> int:
    """Draw exact slot panels and add real image overlays to a PPT slide."""
    try:
        from pptx.dml.color import RGBColor
        from pptx.enum.shapes import MSO_SHAPE
    except ImportError:
        return 0

    slide_spec = prepare_external_image_slots(slide_spec, output_dir) or slide_spec
    slots = _slots_with_real_sources(_collect_external_image_slots(slide_spec), output_dir)
    added = 0
    for idx, slot in enumerate(slots, start=1):
        asset_path = _resolve_asset_path(slot.get("source"), output_dir)
        if not asset_path:
            continue
        x, y, w, h = slot["bbox"]
        pad = max(0.0, float(slot.get("padding") or 0.0))
        left = int(x * prs.slide_width)
        top = int(y * prs.slide_height)
        box_w = int(w * prs.slide_width)
        box_h = int(h * prs.slide_height)

        if bool(slot.get("mask_placeholder")):
            print(
                f"(!)  slide {slide_number} / {slot.get('id')}: "
                "mask_placeholder 已忽略;不会在真实图片下方添加填充底图。"
            )

        # Optional final frame only. Never add a fill-only mask under the real
        # image: it becomes a selectable white rectangle in PowerPoint.
        if bool(slot.get("draw_frame")) and int(slot.get("outline_width") or 0) > 0:
            mask_bleed = max(0.0, float(slot.get("mask_bleed") or 0.0))
            mask_x = max(0.0, x - mask_bleed)
            mask_y = max(0.0, y - mask_bleed)
            mask_r = min(1.0, x + w + mask_bleed)
            mask_b = min(1.0, y + h + mask_bleed)
            frame = slide.shapes.add_shape(
                MSO_SHAPE.RECTANGLE,
                int(mask_x * prs.slide_width),
                int(mask_y * prs.slide_height),
                int((mask_r - mask_x) * prs.slide_width),
                int((mask_b - mask_y) * prs.slide_height),
            )
            outline_rgb = _hex_to_rgb(slot.get("outline"), (26, 26, 26))
            frame.fill.background()
            frame.line.color.rgb = RGBColor(*outline_rgb)
            frame.line.width = int(slot.get("outline_width") or 2) * 12700

        bleed = max(0.0, float(slot.get("bleed") or 0.0))
        inner_x = max(0.0, x + pad - bleed)
        inner_y = max(0.0, y + pad - bleed)
        inner_w = max(0.001, min(1.0 - inner_x, w - 2 * pad + 2 * bleed))
        inner_h = max(0.001, min(1.0 - inner_y, h - 2 * pad + 2 * bleed))
        pic_left = int(inner_x * prs.slide_width)
        pic_top = int(inner_y * prs.slide_height)
        pic_box_w = int(inner_w * prs.slide_width)
        pic_box_h = int(inner_h * prs.slide_height)
        box_ratio = pic_box_w / pic_box_h

        pic_path = _display_asset_for_slot(slot, asset_path, output_dir, slide_number)
        if slot.get("fit") == "cover":
            pic_path = os.path.join(
                output_dir,
                "assets",
                "_cropped",
                f"slide-{slide_number:02d}-{slot['id']}-{idx}.jpg",
            )
            try:
                pic_path = _crop_image_to_ratio(asset_path, pic_path, box_ratio)
            except Exception as e:
                print(f"(!)  cover 裁剪失败,回退 contain: {asset_path} ({e})")
                pic_path = asset_path

        try:
            from PIL import Image
            with Image.open(pic_path) as im:
                ratio = im.width / im.height
        except Exception:
            ratio = box_ratio

        if ratio >= box_ratio:
            draw_w = pic_box_w
            draw_h = int(pic_box_w / ratio)
            draw_left = pic_left
            draw_top = pic_top + int((pic_box_h - draw_h) / 2)
        else:
            draw_h = pic_box_h
            draw_w = int(pic_box_h * ratio)
            draw_left = pic_left + int((pic_box_w - draw_w) / 2)
            draw_top = pic_top
        slide.shapes.add_picture(pic_path, draw_left, draw_top, width=draw_w, height=draw_h)
        added += 1
    return added


def create_final_overlay_trace(
    output_dir: str,
    slide_number: int,
    slide_spec: Optional[Dict[str, Any]],
) -> Optional[str]:
    """Create step4 preview: generated background plus real images at exact slots."""
    slide_spec = prepare_external_image_slots(slide_spec, output_dir)
    slots = _slots_with_real_sources(_collect_external_image_slots(slide_spec), output_dir)
    if not slots:
        return None
    try:
        from PIL import Image
    except ImportError:
        return None

    bg_path = Path(output_dir) / "images" / f"slide-{slide_number:02d}.png"
    if not bg_path.is_file():
        return None

    width, height = SLIDE_TRACE_WIDTH, SLIDE_TRACE_HEIGHT
    canvas = Image.open(bg_path).convert("RGB").resize((width, height))
    trace_slots = []
    for slot in slots:
        asset_path = _resolve_asset_path(slot.get("source"), output_dir)
        if not asset_path:
            continue
        display_asset_path = _display_asset_for_slot(slot, asset_path, output_dir, slide_number)
        final_rect_px = _compute_final_image_rect_px(slot, display_asset_path, width, height)
        _paste_asset_into_rect(canvas, display_asset_path, final_rect_px, fit=slot.get("fit", "contain"))
        trace_slots.append({
            "id": slot.get("id"),
            "source": asset_path,
            "display_source": display_asset_path,
            "final_image_rect_px": final_rect_px,
            "slot_bbox_norm": slot.get("bbox"),
            "inner_rect_norm": _slot_inner_rect(slot),
            "layout_intent": slot.get("layout_intent"),
            "auto_layout_reason": slot.get("auto_layout_reason"),
        })

    trace = _trace_dir(output_dir, slide_number)
    trace.mkdir(parents=True, exist_ok=True)
    step3 = trace / "step3-generated-background.png"
    step4 = trace / "step4-final-overlay-preview.png"
    try:
        Image.open(bg_path).convert("RGB").resize((width, height)).save(step3)
    except Exception:
        pass
    canvas.save(step4)

    manifest_path = trace / "manifest.json"
    manifest = _load_trace_manifest(manifest_path)
    manifest.update({
        "slide_number": slide_number,
        "step3_generated_background": str(step3),
        "step4_final_overlay_preview": str(step4),
        "final_overlay_slots": trace_slots,
    })
    _write_json(manifest_path, manifest)
    return str(step4)


def _coerce_suggested_position(value: Any) -> Optional[List[float]]:
    if not isinstance(value, (list, tuple)) or len(value) != 4:
        return None
    try:
        nums = [float(v) for v in value]
    except (TypeError, ValueError):
        return None
    # Some vision models return pixel-ish coordinates. Normalize against the
    # trace canvas when values are clearly not 0..1.
    if any(abs(v) > 1.5 for v in nums):
        x1, y1, x2, y2 = nums
        if x2 > x1 and y2 > y1:
            nums = [x1 / SLIDE_TRACE_WIDTH, y1 / SLIDE_TRACE_HEIGHT, (x2 - x1) / SLIDE_TRACE_WIDTH, (y2 - y1) / SLIDE_TRACE_HEIGHT]
        else:
            nums = [nums[0] / SLIDE_TRACE_WIDTH, nums[1] / SLIDE_TRACE_HEIGHT, nums[2] / SLIDE_TRACE_WIDTH, nums[3] / SLIDE_TRACE_HEIGHT]
    return _parse_bbox(nums)


def _expand_position_for_readability(spec: Dict[str, Any], slot_id: str, position: List[float]) -> List[float]:
    elem = ((spec.get("elements") or {}).get(slot_id) or {})
    detail_level = _external_asset_detail_level(spec, slot_id, elem)
    if detail_level not in {"high", "critical"}:
        return position
    ratio = None
    try:
        ratio = float(elem.get("asset_ratio"))
    except (TypeError, ValueError):
        pass

    x, y, w, h = position
    min_w, min_h = (0.50, 0.68) if detail_level == "critical" else (0.46, 0.68)
    if ratio and ratio >= 2.0:
        min_w, min_h = (0.78, 0.38) if detail_level == "critical" else (0.70, 0.30)
    elif ratio and ratio < 0.85:
        min_w, min_h = (0.38, 0.78) if detail_level == "critical" else (0.30, 0.70)

    new_w = max(w, min_w)
    new_h = max(h, min_h)
    cx = x + w / 2
    cy = y + h / 2
    new_x = max(0.06, min(0.94 - new_w, cx - new_w / 2))
    new_y = max(0.08, min(0.90 - new_h, cy - new_h / 2))
    return _parse_bbox([new_x, new_y, new_w, new_h]) or position


def _overlay_review_passed(review: Optional[Dict[str, Any]]) -> bool:
    if not review:
        return False
    return review.get("ok") is True and review.get("white_placeholder_issue") is not True


def _bbox_delta(a: Optional[List[float]], b: Optional[List[float]]) -> float:
    if not a or not b:
        return 1.0
    return sum(abs(float(x) - float(y)) for x, y in zip(a, b))


def _fallback_repair_position(spec: Dict[str, Any], slot_id: str) -> Optional[List[float]]:
    """Pick a conservative slot if vision reports a problem but gives no bbox.

    Prefer right-side regions because generated text usually flows from the
    left/top in the built-in styles. Skip candidates that are effectively the
    current position so repeated repair rounds can still make progress.
    """
    elem = ((spec.get("elements") or {}).get(slot_id) or {})
    current = _parse_bbox(elem.get("position") or elem.get("computed_bbox") or elem.get("bbox"))
    asset_ratio = None
    try:
        asset_ratio = float(elem.get("asset_ratio"))
    except (TypeError, ValueError):
        pass
    detail_level = _external_asset_detail_level(spec, slot_id, elem)

    if detail_level in {"high", "critical"}:
        if detail_level == "critical" and asset_ratio and asset_ratio >= 2.0:
            candidates = [
                [0.06, 0.48, 0.88, 0.44],
                [0.08, 0.44, 0.84, 0.48],
                [0.30, 0.08, 0.64, 0.84],
            ]
        elif detail_level == "critical" and asset_ratio and asset_ratio < 0.85:
            candidates = [
                [0.52, 0.08, 0.42, 0.84],
                [0.46, 0.08, 0.48, 0.84],
                [0.10, 0.08, 0.42, 0.84],
            ]
        elif detail_level == "critical":
            candidates = [
                [0.34, 0.06, 0.62, 0.88],
                [0.30, 0.08, 0.66, 0.84],
                [0.32, 0.12, 0.63, 0.78],
                [0.35, 0.15, 0.60, 0.70],
            ]
        elif asset_ratio and asset_ratio >= 2.0:
            candidates = [
                [0.12, 0.58, 0.78, 0.32],
                [0.10, 0.54, 0.82, 0.36],
                [0.50, 0.16, 0.42, 0.56],
            ]
        elif asset_ratio and asset_ratio < 0.85:
            candidates = [
                [0.62, 0.12, 0.30, 0.72],
                [0.58, 0.14, 0.34, 0.68],
                [0.10, 0.18, 0.30, 0.68],
            ]
        else:
            candidates = [
                [0.50, 0.18, 0.42, 0.62],
                [0.48, 0.16, 0.44, 0.66],
                [0.12, 0.58, 0.78, 0.32],
            ]
    elif asset_ratio and asset_ratio < 0.85:
        candidates = [
            [0.66, 0.14, 0.26, 0.68],
            [0.58, 0.18, 0.30, 0.58],
            [0.08, 0.18, 0.26, 0.68],
        ]
    else:
        candidates = [
            [0.55, 0.30, 0.35, 0.50],
            [0.56, 0.18, 0.36, 0.52],
            [0.58, 0.12, 0.34, 0.36],
            [0.14, 0.66, 0.72, 0.24],
        ]
    for candidate in candidates:
        parsed = _parse_bbox(candidate)
        if parsed and _bbox_delta(current, parsed) >= 0.08:
            return parsed
    return None


def _region_zone(region: Optional[List[float]]) -> str:
    if not region:
        return "unknown"
    x, y, w, h = region
    cx = x + w / 2
    cy = y + h / 2
    if y >= 0.44:
        return "bottom"
    if y + h <= 0.54:
        return "top"
    if x + w <= 0.52:
        return "left"
    if x >= 0.48:
        return "right"
    if 0.34 <= cx <= 0.66 and 0.30 <= cy <= 0.70:
        return "center"
    return "mixed"


def _template_preserving_repair_position(
    spec: Dict[str, Any],
    slot_id: str,
    suggested: List[float],
) -> List[float]:
    """Keep repair close to the template's chosen media zone when possible."""
    elem = ((spec.get("elements") or {}).get(slot_id) or {})
    reason = str(elem.get("auto_layout_reason") or "")
    if "template-aware" not in reason and not spec.get("template_layout_profile"):
        return suggested
    current = _parse_bbox(elem.get("position") or elem.get("computed_bbox") or elem.get("bbox"))
    if not current:
        return suggested
    current_zone = _region_zone(current)
    suggested_zone = _region_zone(suggested)
    if current_zone == suggested_zone or current_zone in {"unknown", "mixed"}:
        return suggested

    detail_level = _external_asset_detail_level(spec, slot_id, elem)
    large = detail_level in {"high", "critical"}
    zone_candidates = {
        "left": [0.06, 0.08, 0.44, 0.84] if large else [0.06, 0.14, 0.40, 0.72],
        "right": [0.50, 0.08, 0.44, 0.84] if large else [0.54, 0.14, 0.40, 0.72],
        "bottom": [0.08, 0.44, 0.84, 0.50] if large else [0.10, 0.54, 0.80, 0.36],
        "top": [0.08, 0.08, 0.84, 0.50] if large else [0.10, 0.10, 0.80, 0.36],
        "center": [0.20, 0.12, 0.60, 0.76],
    }
    preserved = _parse_bbox(zone_candidates.get(current_zone))
    return preserved or suggested


def review_external_overlay_with_vision(output_dir: str, slide_number: int) -> Optional[Dict[str, Any]]:
    """Use VISION_* model to inspect whether real overlays cover important content."""
    trace = _trace_dir(output_dir, slide_number)
    step3 = trace / "step3-generated-background.png"
    step4 = trace / "step4-final-overlay-preview.png"
    manifest_path = trace / "manifest.json"
    if not (step3.is_file() and step4.is_file() and manifest_path.is_file()):
        return None
    try:
        sys.path.insert(0, str(SCRIPT_DIR))
        from template_analyzer import VisionClient
    except Exception as e:
        print(f"(!)  无法加载 vision 客户端,跳过贴图质检: {e}")
        return None

    try:
        client = VisionClient()
    except Exception as e:
        print(f"(!)  未配置 VISION_*,跳过贴图质检: {e}")
        return None

    manifest = _load_trace_manifest(manifest_path)
    slots = manifest.get("final_overlay_slots") or manifest.get("slots") or []
    user_text = (
        "请比较两张图:第一张是 gpt-image-2 生成的背景页,第二张是按代码坐标贴入真实图片后的最终预览。\n"
        "判断真实图片是否覆盖标题、正文、数字、图标、重要装饰或主体视觉;判断是否出现白色/浅色底图、占位框、遮罩矩形。\n"
        "白色/浅色底图只指生成背景或额外对象里出现的占位块;如果白色区域来自真实图片文件本身(例如白底图表、论文页、架构图截图),"
        "不要把它判为 white_placeholder_issue。\n"
        "还要判断真实图片本身是否足够大:如果真实图片是论文截图、表格、架构图、流程图、图表、代码或公式截图,"
        "必须能作为页面重点被清楚阅读;过小、只能当缩略图、细节不可辨,也应判为 ok=false,并给出更大但不遮挡内容的 suggested_position。\n"
        "对这类高细节真实图,宁可让页面正文更短、放到左侧窄栏,也要保证真实图占据足够大的主视觉区域。\n"
        "同时判断整体版式结构是否合理:如果最终页出现大片无意义空白、图文比例明显失衡、文字被挤到不自然角落、"
        "模板原有分栏/上下结构被破坏、装饰线条断裂或真实图位置让页面视觉重心明显怪异,也应判为 ok=false。"
        "这种情况下请给出既能保持模板结构、又能改善空白和比例的 suggested_position。\n"
        "注意:真实图片本身是矩形是正常现象,不要因此判为占位框。\n"
        f"当前 slots manifest: {json.dumps(slots, ensure_ascii=False)}\n"
        "只返回 JSON:{\n"
        '  "ok": boolean,\n'
        '  "cover_issue": string,\n'
        '  "white_placeholder_issue": boolean,\n'
        '  "layout_issue": string,\n'
        '  "blank_space_issue": boolean,\n'
        '  "recommendation": string,\n'
        '  "suggested_position": [x,y,w,h] 或 null,\n'
        '  "confidence": 0到1\n'
        "}\n"
        "如果建议位置,请优先返回 0..1 归一化坐标;若无法判断则返回 null。"
    )
    try:
        result = client.chat_json(
            system="你是严格的 PPT 视觉质检模型,只返回 JSON。",
            user_text=user_text,
            images=[str(step3), str(step4)],
            temperature=0.1,
        )
    except Exception as e:
        print(f"(!)  vision 贴图质检失败 slide {slide_number}: {e}")
        result = {
            "ok": False,
            "cover_issue": "",
            "white_placeholder_issue": False,
            "recommendation": f"vision overlay review failed: {str(e)[:240]}",
            "suggested_position": None,
            "confidence": 0.0,
            "vision_error": True,
            "slide_number": slide_number,
        }
        _write_json(trace / "overlay_review.json", result)
        return result
    if isinstance(result, list) and result and isinstance(result[0], dict):
        result = result[0]
    if not isinstance(result, dict):
        print(f"(!)  vision 贴图质检返回非对象 slide {slide_number}: {str(result)[:200]}")
        return None
    suggested = _coerce_suggested_position(result.get("suggested_position"))
    if suggested:
        result["suggested_position"] = suggested
    elif result.get("suggested_position") not in (None, "", []):
        result["suggested_position_raw"] = result.get("suggested_position")
        result["suggested_position"] = None
    result["slide_number"] = slide_number
    review_path = trace / "overlay_review.json"
    _write_json(review_path, result)
    print(
        f"🔎 slide {slide_number} overlay review: ok={result.get('ok')} "
        f"white_placeholder={result.get('white_placeholder_issue')} "
        f"position={result.get('suggested_position')}"
    )
    return result


def review_external_overlays(metadata: Dict[str, Any], output_dir: str, slide_numbers: List[int]) -> Dict[int, Dict[str, Any]]:
    reviews: Dict[int, Dict[str, Any]] = {}
    for n in slide_numbers:
        spec = _get_latest_slide_spec(metadata, n)
        if not _slots_with_real_sources(_collect_external_image_slots(spec), output_dir):
            continue
        result = review_external_overlay_with_vision(output_dir, n)
        if result:
            reviews[n] = result
    return reviews


def _first_external_slot_id(spec: Dict[str, Any]) -> Optional[str]:
    items = _external_element_items(spec)
    return items[0][0] if items else None


def sanitize_external_image_regions(
    output_dir: str,
    slide_number: int,
    slide_spec: Optional[Dict[str, Any]],
) -> Optional[str]:
    """Deterministically clear external-image regions in the generated slide.

    Image models may turn the spatial guide into a photo frame, card, or even a
    synthesized replacement photo. This fallback is opt-in via
    `sanitize_background: true`; the default path keeps image2 output untouched
    and relies on prompt/reference quality plus the final real-image overlay.
    """
    slide_spec = prepare_external_image_slots(slide_spec, output_dir)
    slots = [
        slot for slot in _slots_with_real_sources(_collect_external_image_slots(slide_spec), output_dir)
        if bool(slot.get("sanitize_background"))
    ]
    if not slots:
        return None
    try:
        from PIL import Image, ImageDraw
    except ImportError:
        return None

    img_path = Path(output_dir) / "images" / f"slide-{slide_number:02d}.png"
    if not img_path.is_file():
        return None

    trace = _trace_dir(output_dir, slide_number)
    trace.mkdir(parents=True, exist_ok=True)
    raw_path = trace / "step3-image2-raw.png"
    sanitized_path = trace / "step3-sanitized-background.png"

    img = Image.open(img_path).convert("RGB")
    if not raw_path.exists():
        img.save(raw_path)

    width, height = img.size
    draw = ImageDraw.Draw(img)
    cleanup_slots = []
    for slot in slots:
        cleanup_rect = slot.get("cleanup_rect")
        if cleanup_rect:
            rect_norm = _parse_bbox(cleanup_rect)
        else:
            asset_path = _resolve_asset_path(slot.get("source"), output_dir)
            if asset_path:
                final_rect_px = _compute_final_image_rect_px(slot, asset_path, width, height)
                rect_norm = [
                    final_rect_px[0] / width,
                    final_rect_px[1] / height,
                    final_rect_px[2] / width,
                    final_rect_px[3] / height,
                ]
            else:
                rect_norm = slot.get("bbox")
        if not rect_norm:
            continue
        x, y, w, h = rect_norm
        mask_bleed = max(0.0, float(slot.get("mask_bleed") or 0.0))
        x1 = max(0.0, x - mask_bleed)
        y1 = max(0.0, y - mask_bleed)
        x2 = min(1.0, x + w + mask_bleed)
        y2 = min(1.0, y + h + mask_bleed)
        rect_px = [
            int(round(x1 * width)),
            int(round(y1 * height)),
            int(round(x2 * width)),
            int(round(y2 * height)),
        ]
        fill_rgb = _hex_to_rgb(slot.get("mask_fill") or slot.get("fill"), (247, 247, 245))
        draw.rectangle(rect_px, fill=fill_rgb)
        cleanup_slots.append({
            "id": slot.get("id"),
            "cleanup_rect_norm": [x1, y1, x2 - x1, y2 - y1],
            "cleanup_rect_px": [
                rect_px[0],
                rect_px[1],
                max(0, rect_px[2] - rect_px[0]),
                max(0, rect_px[3] - rect_px[1]),
            ],
            "fill": "#%02X%02X%02X" % fill_rgb,
        })

    img.save(img_path)
    img.save(sanitized_path)

    manifest_path = trace / "manifest.json"
    manifest = _load_trace_manifest(manifest_path)
    manifest.update({
        "step3_image2_raw": str(raw_path),
        "step3_sanitized_background": str(sanitized_path),
        "sanitized_slide_image": str(img_path),
        "cleanup_slots": cleanup_slots,
    })
    _write_json(manifest_path, manifest)
    return str(sanitized_path)


# =============================================================================
# Image Generation
# =============================================================================

def generate_slide(
    prompt: str,
    slide_number: int,
    output_dir: str,
    reference_image_path: Optional[Union[str, List[str]]] = None,
    backend: str = "openai",
) -> Optional[str]:
    """Generate a single PPT slide image using gpt-image-2.

    backend:
      "openai" (default) -- direct /v1/images or /v1/chat calls, needs OPENAI_API_KEY
      "codex"            -- shell out to `codex exec`, reuses codex CLI auth
    """
    sys.path.insert(0, str(SCRIPT_DIR))
    if backend == "codex":
        from codex_backend import CodexImageBackend as _Backend
    else:
        from image_generator import GptImage2Generator as _Backend

    print(f"  Generating slide {slide_number} via {backend} backend ...")

    generator = _Backend(aspect_ratio="16:9")
    image_path = os.path.join(output_dir, "images", f"slide-{slide_number:02d}.png")

    scene_data = {
        "index": slide_number,
        "image_prompt": prompt,
    }
    generator.generate_scene_image(
        scene_data=scene_data,
        output_path=image_path,
        reference_image_path=reference_image_path,
    )
    print(f"  Slide {slide_number} saved: {image_path}")
    return image_path


# =============================================================================
# Output Generation
# =============================================================================

def save_prompts(output_dir: str, prompts_data: Dict[str, Any]) -> str:
    """Save all prompts to JSON file."""
    prompts_path = os.path.join(output_dir, "prompts.json")
    with open(prompts_path, "w", encoding="utf-8") as f:
        json.dump(prompts_data, f, ensure_ascii=False, indent=2)
    print(f"  Prompts saved: {prompts_path}")
    return prompts_path


def _load_existing_prompts(output_dir: str) -> Optional[Dict[str, Any]]:
    prompts_path = os.path.join(output_dir, "prompts.json")
    if not os.path.isfile(prompts_path):
        return None
    try:
        with open(prompts_path, "r", encoding="utf-8") as f:
            data = json.load(f)
        if isinstance(data, dict):
            return data
    except Exception as e:
        print(f"(!)  读取旧 prompts.json 失败,将重建本次 prompts: {e}")
    return None


def _merge_prompts_data(existing: Optional[Dict[str, Any]], current: Dict[str, Any]) -> Dict[str, Any]:
    """Merge incremental prompt records without replacing real prompts by skip stubs."""
    if not existing or not isinstance(existing.get("slides"), list):
        return current

    merged_by_slide: Dict[int, Dict[str, Any]] = {}
    for slide in existing.get("slides", []):
        if not isinstance(slide, dict):
            continue
        try:
            n = int(slide.get("slide_number"))
        except (TypeError, ValueError):
            continue
        merged_by_slide[n] = slide

    for slide in current.get("slides", []):
        if not isinstance(slide, dict):
            continue
        try:
            n = int(slide.get("slide_number"))
        except (TypeError, ValueError):
            continue
        if str(slide.get("prompt", "")).startswith("(skipped") and n in merged_by_slide:
            merged_by_slide[n]["image_path"] = slide.get("image_path") or merged_by_slide[n].get("image_path")
            continue
        merged_by_slide[n] = slide

    merged = copy.deepcopy(current)
    merged["slides"] = [merged_by_slide[n] for n in sorted(merged_by_slide)]
    return merged


def generate_pptx(
    output_dir: str,
    slide_numbers: List[int],
    title: str = "Untitled",
    metadata: Optional[Dict[str, Any]] = None,
) -> Optional[str]:
    """把 images/slide-XX.png 打包成 16:9 .pptx,每页填满。

    如果 metadata/slide_spec 中声明了 external_image 元素,会额外:
    1. 可选地在同一个 bbox 上画代码确定性的槽位框/底色;
    2. 把 source 指向的真实图片作为独立 PPT picture object 贴入。

    注意:不要把 step4-final-overlay-preview.png 或手工合成图作为 PPT
    背景图打包;那会把真实图片烘焙进整页 PNG,PowerPoint 里无法单独
    选中/拖动真实图片。

    需要 python-pptx;如果没装就跳过并提示。
    """
    try:
        from pptx import Presentation
        from pptx.util import Inches, Emu
    except ImportError:
        print("(!)  跳过 .pptx 生成(缺 python-pptx,pip install python-pptx 后重试)")
        return None

    prs = Presentation()
    # 标准 16:9 PPT 尺寸:13.333 x 7.5 英寸(1280x720pt)
    prs.slide_width = Inches(13.333)
    prs.slide_height = Inches(7.5)
    blank = prs.slide_layouts[6]  # 完全空白布局

    img_dir = os.path.join(output_dir, "images")
    if metadata is None:
        meta_path = os.path.join(output_dir, METADATA_FILENAME)
        if os.path.isfile(meta_path):
            try:
                metadata = _load_metadata(output_dir)
            except SystemExit:
                metadata = None

    added = 0
    overlay_added = 0
    for i in slide_numbers:
        img_path = os.path.join(img_dir, f"slide-{i:02d}.png")
        if not os.path.exists(img_path):
            print(f"  跳过 slide-{i:02d}.png(文件不存在)")
            continue
        slide = prs.slides.add_slide(blank)
        # 图片填满整页(如果原图比例不是 16:9,python-pptx 默认按指定 width/height 拉伸)
        slide.shapes.add_picture(img_path, 0, 0, width=prs.slide_width, height=prs.slide_height)
        if metadata:
            spec = _get_latest_slide_spec(metadata, i)
            if spec:
                overlay_added += _add_external_image_overlays(prs, slide, i, spec, output_dir)
                create_final_overlay_trace(output_dir, i, spec)
        added += 1

    if added == 0:
        print("(!)  没有可用图片,未生成 .pptx")
        return None

    # 文件名用 plan title(去除非法字符)
    safe_title = re.sub(r"[^\w\u4e00-\u9fff\-]+", "_", title)[:60] or "deck"
    pptx_path = os.path.join(output_dir, f"{safe_title}.pptx")
    prs.save(pptx_path)
    overlay_msg = f", {overlay_added} external image overlays" if overlay_added else ""
    print(f"  📑 PPTX generated: {pptx_path}  ({added} slides{overlay_msg})")
    return pptx_path


def resolve_editable_scene_dir(args: argparse.Namespace, output_dir: Union[str, Path]) -> Optional[Path]:
    """Resolve editable scenes only when the explicit opt-in mode is active."""
    if not getattr(args, "editable", False):
        return None
    explicit = getattr(args, "editable_scenes", None)
    candidate = Path(explicit) if explicit else Path(output_dir) / "editable_scenes"
    if not candidate.is_dir():
        raise ValueError(
            "可编辑模式缺少 scene 目录。请传 --editable-scenes DIR,"
            f"或创建 {Path(output_dir) / 'editable_scenes'}"
        )
    return candidate


# =============================================================================
# Commands (edit, rollback, ingest, list-sessions)
# =============================================================================

def cmd_list_sessions(args: argparse.Namespace) -> None:
    """List all generation sessions."""
    base_dir = args.output or str(CWD / OUTPUT_BASE_DIR)
    sessions = _find_sessions(base_dir)
    if not sessions:
        print("No sessions found.")
        return
    print(f"{'Session':<20} {'Slides':<8} Title")
    print("-" * 60)
    for s in sessions:
        print(f"{s['timestamp']:<20} {s['slide_count']:<8} {s['title']}")


def cmd_ingest_pptx(args: argparse.Namespace) -> None:
    """Ingest an external PPTX file and prepare it for editing.

    Renders the PPTX to PNGs, creates a session directory, and writes
    an initial metadata.json with placeholder slide_specs.  The Agent
    should then Read each page PNG and fill in the actual slide_specs.
    """
    pptx_path = args.ingest_pptx
    if not os.path.isfile(pptx_path):
        print(f"[X] File not found: {pptx_path}")
        sys.exit(1)

    # Render PPTX to PNGs
    sys.path.insert(0, str(SCRIPT_DIR))
    from render_template import render_pptx_to_pngs

    print(f"Ingesting: {pptx_path}")
    images_dir = render_pptx_to_pngs(pptx_path)
    print(f"Rendered to: {images_dir}")

    # Create session directory
    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    if args.session:
        session_id = args.session
    else:
        stem = Path(pptx_path).stem
        session_id = f"{timestamp}_{stem}"
    session_dir = args.output or str(CWD / OUTPUT_BASE_DIR / session_id)
    session_images = os.path.join(session_dir, "images")
    os.makedirs(session_images, exist_ok=True)

    # Copy rendered PNGs as version 1 images
    import glob as _glob
    import shutil as _shutil

    png_files = sorted(_glob.glob(os.path.join(images_dir, "page-*.png")))
    slide_order: List[int] = []
    for i, png in enumerate(png_files, start=1):
        dest = os.path.join(session_images, f"slide-{i:02d}_v0001.png")
        _shutil.copy2(png, dest)
        # Also set as current
        current = os.path.join(session_images, f"slide-{i:02d}.png")
        _shutil.copy2(png, current)
        slide_order.append(i)

    # Build initial metadata with placeholder specs
    slides_meta: Dict[str, Any] = {}
    for i in slide_order:
        slides_meta[str(i)] = {
            "slide_number": i,
            "page_type": "content",
            "current_version": 1,
            "image_snapshot": f"images/slide-{i:02d}.png",
            "versions": [
                {
                    "version": 1,
                    "action": "ingest",
                    "spec": {
                        "layout": "(待 Agent 分析填充)",
                        "elements": {},
                    },
                    "prompt_file": "",
                    "image_snapshot": f"images/slide-{i:02d}_v0001.png",
                    "source_pptx": os.path.basename(pptx_path),
                }
            ],
        }

    metadata: Dict[str, Any] = {
        "version": 1,
        "title": Path(pptx_path).stem,
        "source_pptx": pptx_path,
        "slide_order": slide_order,
        "ingested_at": datetime.now().isoformat(),
        "slides": slides_meta,
    }
    _save_metadata(metadata, session_dir)

    print(f"Session created: {session_dir}")
    print(f"  {len(slide_order)} slides ingested")
    print(f"  metadata.json written with placeholder specs")
    print()
    print("Next: Agent should Read each page PNG and fill in slide_specs.")
    print("  For each slide, describe elements with type/content/position/style.")
    print("  Then use --edit to refine individual slides, or --plan to regenerate.")
    print(f"  Session timestamp: {session_id}")


def cmd_edit_slide(args: argparse.Namespace) -> None:
    """Edit a specific slide in an existing session.

    Reads the current slide_spec from metadata.json, applies element updates,
    constructs an edit prompt, and regenerates the slide with the original
    image as reference.
    """
    import shutil as _shutil

    session_dir = _resolve_session(args.session)
    metadata = _load_metadata(session_dir)
    images_dir = os.path.join(session_dir, "images")
    os.makedirs(images_dir, exist_ok=True)

    slide_key = str(args.edit)
    if slide_key not in metadata.get("slides", {}):
        print(f"[X] Slide {args.edit} not found in session {args.session}")
        sys.exit(1)

    slide_data = metadata["slides"][slide_key]
    current_version = slide_data["current_version"]
    page_type = slide_data.get("page_type", "content")

    # Get the current spec
    current_spec = _get_latest_slide_spec(metadata, args.edit)
    if not current_spec:
        print(f"[X] No spec found for slide {args.edit} (version {current_version})")
        print("    This session may not have slide_spec data. Consider regenerating.")
        sys.exit(1)

    # Apply element updates if provided
    element_updates: Dict[str, Any] = {}
    if args.element_updates:
        try:
            element_updates = json.loads(args.element_updates)
        except json.JSONDecodeError as e:
            print(f"[X] Invalid element-updates JSON: {e}")
            sys.exit(1)

    updated_spec = apply_spec_updates(current_spec, element_updates)
    updated_spec = prepare_external_image_slots(updated_spec, session_dir) or updated_spec

    # Construct edit prompt
    external_slot_repair = bool(args.external_slot_repair)
    if external_slot_repair:
        edit_prompt = args.edit_prompt or construct_external_slot_repair_prompt(updated_spec, element_updates)
    elif args.edit_prompt:
        edit_prompt = args.edit_prompt
        if not element_updates:
            print("(!) Warning: --edit-prompt used without --element-updates.")
            print("    The slide_spec in metadata will NOT be updated.")
            print("    Future structured edits may reference stale content.")
    elif element_updates:
        edit_prompt = construct_edit_prompt(current_spec, element_updates)
    else:
        print("[X] No edit prompt or element updates provided")
        sys.exit(1)

    # Get reference image (current slide image)
    ref_path = os.path.join(session_dir, slide_data.get("image_snapshot", ""))
    if not os.path.isfile(ref_path):
        ref_path = os.path.join(images_dir, f"slide-{args.edit:02d}.png")
    if not os.path.isfile(ref_path):
        print(f"(!) Reference image not found at {ref_path}, generating without reference")
        ref_path = None

    reference_images: Optional[Union[str, List[str]]] = ref_path
    asset_reference_image = None
    if external_slot_repair:
        asset_reference_image = create_asset_reference_skeleton(session_dir, args.edit, updated_spec)
        if asset_reference_image and ref_path:
            reference_images = [ref_path, asset_reference_image]
        elif asset_reference_image:
            reference_images = asset_reference_image
        else:
            print("(!) 未找到可用外部图片 source,无法生成槽位 skeleton;将只用当前页作为参考。")

    # Backup current image and build new version
    new_version = current_version + 1
    current_img = os.path.join(images_dir, f"slide-{args.edit:02d}.png")
    versioned_img = os.path.join(images_dir, f"slide-{args.edit:02d}_v{current_version:04d}.png")
    if os.path.exists(current_img):
        _shutil.copy2(current_img, versioned_img)
    _stabilize_version_snapshots(slide_data, args.edit, images_dir)

    # Save edit prompt
    prompt_rel = f"images/slide-{args.edit:02d}_v{new_version:04d}.txt"
    prompt_abs = os.path.join(session_dir, prompt_rel)
    with open(prompt_abs, "w", encoding="utf-8") as f:
        f.write(edit_prompt)

    print(f"Editing slide {args.edit} (v{current_version} -> v{new_version})")
    if element_updates:
        for elem_id, changes in element_updates.items():
            for k, v in changes.items():
                old = current_spec.get("elements", {}).get(elem_id, {}).get(k, "?")
                print(f"  {elem_id}.{k}: {old} -> {v}")
    print(f"  Reference: {reference_images or '(none)'}")
    print(f"  Edit prompt: {edit_prompt[:200]}...")

    # Generate new image
    image_path = generate_slide(
        edit_prompt, args.edit, session_dir,
        reference_image_path=reference_images,
        backend=args.backend,
    )

    if not image_path:
        print("[X] Edit generation failed")
        sys.exit(1)

    # Also save versioned copy of the new image
    versioned_new = os.path.join(images_dir, f"slide-{args.edit:02d}_v{new_version:04d}.png")
    _shutil.copy2(current_img, versioned_new)

    # Update metadata
    _add_slide_version(
        slide_data=slide_data,
        new_version=new_version,
        spec=updated_spec,
        action="edit",
        image_snapshot=f"images/slide-{args.edit:02d}_v{new_version:04d}.png",
        prompt_file=prompt_rel,
        edit_instruction=args.edit_instruction or args.edit_prompt or "",
        reference_version=current_version,
    )

    _save_metadata(metadata, session_dir)

    # Regenerate PPTX
    slide_nums = _collect_slide_numbers(metadata)
    if not args.no_pptx:
        generate_pptx(session_dir, slide_nums, title=metadata.get("title", "Untitled"), metadata=metadata)

    print(f"Slide {args.edit} updated to v{new_version}")
    print(f"  Image: {image_path}")
    print(f"  Metadata saved")


def cmd_rollback_slide(args: argparse.Namespace) -> None:
    """Rollback a slide to a previous version.

    Reads the target version's spec, regenerates from it (optionally with
    the target version's image as reference), and saves as a new version.
    """
    import shutil as _shutil

    session_dir = _resolve_session(args.session)
    metadata = _load_metadata(session_dir)
    images_dir = os.path.join(session_dir, "images")

    slide_key = str(args.rollback)
    if slide_key not in metadata.get("slides", {}):
        print(f"[X] Slide {args.rollback} not found in session {args.session}")
        sys.exit(1)

    slide_data = metadata["slides"][slide_key]
    current_version = slide_data["current_version"]
    target_version = args.to_version

    target = _get_version_info(metadata, args.rollback, target_version)
    if not target:
        print(f"[X] Version {target_version} not found for slide {args.rollback}")
        available = sorted(v.get("version", 0) for v in slide_data.get("versions", []))
        print(f"    Available versions: {available}")
        sys.exit(1)

    target_spec = target.get("spec", {})
    target_image_rel = target.get("image_snapshot", "")

    # Construct generation prompt from target spec
    # Use style from metadata (stored during generation), fallback to --style arg
    style_template = ""
    stored_style = metadata.get("style", "")
    if stored_style:
        # Try the stored path; it may be relative to CWD or SCRIPT_DIR
        for candidate_path in (stored_style, str(SCRIPT_DIR / stored_style)):
            if os.path.isfile(candidate_path):
                style_template = load_style_template(candidate_path)
                break
    if not style_template and hasattr(args, "style") and args.style:
        style_template = load_style_template(args.style)

    if target_spec.get("elements"):
        prompt = generate_prompt_from_spec(
            style_template or "按以下元素描述生成幻灯片页",
            target_spec,
            slide_data.get("page_type", "content"),
            args.rollback,
            len(metadata.get("slides", {})),
        )
    else:
        # Fallback: use stored prompt if available
        prompt_path = os.path.join(session_dir, target.get("prompt_file", ""))
        if prompt_path and os.path.isfile(prompt_path):
            with open(prompt_path, "r", encoding="utf-8") as f:
                prompt = f.read()
        elif target_image_rel:
            # Ingested slide with placeholder spec: regenerate from reference image
            ref_abs = os.path.join(session_dir, target_image_rel)
            if os.path.isfile(ref_abs):
                print(f"  Spec has no elements; using reference image as visual guide")
                prompt = (
                    "请生成一张与参考图视觉风格完全一致的幻灯片页面。\n"
                    "保持相同的布局、配色、字体和装饰元素。\n"
                    "如果参考图上有文字,保留其内容和位置。"
                )
            else:
                print(f"[X] No elements in spec and no reference image found for version {target_version}")
                sys.exit(1)
        else:
            print(f"[X] No elements in spec and no prompt file or reference image for version {target_version}")
            print(f"    This often happens with ingested slides before the Agent fills in slide_specs.")
            print(f"    Have the Agent Read each page PNG and fill in the spec elements first.")
            sys.exit(1)

    # Get reference image from target version
    ref_path = os.path.join(session_dir, target_image_rel) if target_image_rel else None
    if ref_path and not os.path.isfile(ref_path):
        print(f"(!) Reference image not found, regenerating without reference")
        ref_path = None

    # Backup current image
    new_version = current_version + 1
    current_img = os.path.join(images_dir, f"slide-{args.rollback:02d}.png")
    versioned_img = os.path.join(images_dir, f"slide-{args.rollback:02d}_v{current_version:04d}.png")
    if os.path.exists(current_img):
        _shutil.copy2(current_img, versioned_img)
    _stabilize_version_snapshots(slide_data, args.rollback, images_dir)

    # Save prompt
    prompt_rel = f"images/slide-{args.rollback:02d}_v{new_version:04d}.txt"
    prompt_abs = os.path.join(session_dir, prompt_rel)
    with open(prompt_abs, "w", encoding="utf-8") as f:
        f.write(prompt)

    print(f"Rolling back slide {args.rollback}: v{current_version} -> v{new_version} (from v{target_version})")

    image_path = generate_slide(
        prompt, args.rollback, session_dir,
        reference_image_path=ref_path,
        backend=args.backend,
    )

    if not image_path:
        print("[X] Rollback generation failed")
        sys.exit(1)

    # Save versioned copy of new image
    versioned_new = os.path.join(images_dir, f"slide-{args.rollback:02d}_v{new_version:04d}.png")
    _shutil.copy2(current_img, versioned_new)

    # Update metadata
    _add_slide_version(
        slide_data=slide_data,
        new_version=new_version,
        spec=target_spec,
        action="rollback",
        image_snapshot=f"images/slide-{args.rollback:02d}_v{new_version:04d}.png",
        prompt_file=prompt_rel,
        edit_instruction=f"Rollback to version {target_version}",
        reference_version=target_version,
    )

    _save_metadata(metadata, session_dir)

    # Regenerate PPTX
    slide_nums = _collect_slide_numbers(metadata)
    if not args.no_pptx:
        generate_pptx(session_dir, slide_nums, title=metadata.get("title", "Untitled"), metadata=metadata)

    print(f"Slide {args.rollback} rolled back (v{new_version}, based on v{target_version})")


# =============================================================================
# Main Entry Point
# =============================================================================

def create_argument_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        description="PPT Generator - Generate PPT images using OpenAI gpt-image-2",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Example usage:
  # Generate
  python scripts/generate_ppt.py --plan slides_plan.json --style styles/initial/gradient-glass.md
  python scripts/generate_ppt.py --plan slides_plan.json --style styles/initial/clean-tech-blue.md --slides 1,3,5
  python scripts/generate_ppt.py --plan slides_plan.json --style styles/initial/gradient-glass.md --editable --editable-scenes editable_scenes/

  # Edit
  python scripts/generate_ppt.py --edit 3 --session 20240523_143052 --element-updates '{"subtitle":{"content":"新内容"}}'

  # Rollback
  python scripts/generate_ppt.py --rollback 3 --to-version 1 --session 20240523_143052

  # Ingest external PPTX
  python scripts/generate_ppt.py --ingest-pptx path/to/deck.pptx

  # List sessions
  python scripts/generate_ppt.py --list-sessions

Environment variables:
  OPENAI_BASE_URL:        Images API base URL (default: https://api.openai.com)
  OPENAI_API_KEY:         API key (required)
  GPT_IMAGE_MODEL_NAME:   Model name (default: gpt-image-2)
  GPT_IMAGE_QUALITY:      low / medium / high / auto (default: high)
""",
    )

    parser.add_argument("--plan", help="Path to slides plan JSON file")
    parser.add_argument("--style", help="Path to style template file (与模板输入二选一)")
    parser.add_argument("--output", help="Output directory path (default: outputs/TIMESTAMP)")
    parser.add_argument(
        "--template-pptx",
        help="用户的 .pptx 模板路径,启用「仿模板」模式",
    )
    parser.add_argument(
        "--template-images",
        help="模板每页 PNG 所在目录(强烈建议传,没有则只读 .pptx XML,不能跑 vision)",
    )
    parser.add_argument(
        "--template-profile",
        help="预先分析好的 TemplateProfile JSON。多模态 agent / 原生 Codex 可自己看图生成它,从而不需要 VISION_*。",
    )
    parser.add_argument(
        "--template-strict",
        action="store_true",
        help="高保真模式:把模板对应页作为 image reference 传给 gpt-image-2 出新图",
    )
    parser.add_argument(
        "--rebuild-template-cache",
        action="store_true",
        help="无视模板缓存重新跑 vision",
    )
    parser.add_argument(
        "--slides",
        help="Only generate specific slides, e.g. '1,3,5'",
    )
    parser.add_argument(
        "--concurrency",
        type=int,
        default=int(os.getenv("GPT_IMAGE_CONCURRENCY", "10")),
        help="并发请求数(默认 10,可用 GPT_IMAGE_CONCURRENCY 环境变量覆盖)",
    )
    parser.add_argument(
        "--no-pptx",
        action="store_true",
        help="不生成 .pptx 文件(默认会自动打包成 16:9 PPTX)",
    )
    parser.add_argument(
        "--prepare-only",
        action="store_true",
        help="只通过统一 RuntimeProfile 编译 prompts/metadata,不调用图片生成后端、不打包 PPTX",
    )
    parser.add_argument(
        "--editable",
        action="store_true",
        help="生成可编辑对象版 PPTX;需要 PowerPoint/Keynote/LibreOffice 回渲染,默认关闭",
    )
    parser.add_argument(
        "--editable-scenes",
        help="slide-XX.scene.json 所在目录;仅与 --editable 一起使用",
    )
    parser.add_argument(
        "--backend",
        choices=["openai", "codex"],
        default=os.getenv("GPT_IMAGE_BACKEND", "openai"),
        help="图片生成后端:openai=直调 OpenAI API(需 OPENAI_API_KEY,默认);"
             "codex=启动本地 codex exec 子进程(非当前 Codex 原生 tool;更慢,仅作备用)",
    )

    # Edit / rollback / ingest commands
    parser.add_argument(
        "--edit",
        type=int,
        metavar="SLIDE_NUMBER",
        help="Edit a specific slide (requires --session). Use with --edit-prompt, --element-updates, or --external-slot-repair.",
    )
    parser.add_argument(
        "--session",
        help="Session timestamp or path (for --edit / --rollback). e.g. '20240523_143052'",
    )
    parser.add_argument(
        "--edit-prompt",
        help="Full edit prompt to send to gpt-image-2 for the edited slide",
    )
    parser.add_argument(
        "--external-slot-repair",
        action="store_true",
        help="Repair an edited slide by passing the current slide plus external-image slot skeleton as references.",
    )
    parser.add_argument(
        "--auto-review-overlays",
        action="store_true",
        help="After PPTX packaging, use VISION_* to review real-image overlays for collisions/placeholders.",
    )
    parser.add_argument(
        "--auto-repair-overlays",
        action="store_true",
        help="After review, automatically run bounded external-slot repair rounds for slides with overlay issues.",
    )
    parser.add_argument(
        "--edit-instruction",
        help="Human-readable description of the edit (stored in metadata)",
    )
    parser.add_argument(
        "--element-updates",
        help="JSON mapping element_id -> {key: new_value} to update the slide_spec."
             " e.g. '{\"subtitle\": {\"content\": \"新副标题\"}}'",
    )
    parser.add_argument(
        "--rollback",
        type=int,
        metavar="SLIDE_NUMBER",
        help="Rollback a slide to a previous version (requires --session --to-version)",
    )
    parser.add_argument(
        "--to-version",
        type=int,
        help="Target version number for rollback",
    )
    parser.add_argument(
        "--ingest-pptx",
        metavar="PPTX_PATH",
        help="Ingest an external PPTX file, render to PNGs, and create a session for editing",
    )
    parser.add_argument(
        "--list-sessions",
        action="store_true",
        help="List all generation sessions",
    )

    return parser


def main() -> None:
    load_skill_env()

    parser = create_argument_parser()
    args = parser.parse_args()

    if args.editable_scenes and not args.editable:
        parser.error("--editable-scenes 只能与 --editable 一起使用")
    if args.editable and args.no_pptx:
        parser.error("--editable 与 --no-pptx 不能同时使用")
    if args.prepare_only and args.editable:
        parser.error("--prepare-only 与 --editable 不能同时使用")

    # ── 命令分发 ────────────────────────────────────────────
    if args.list_sessions:
        cmd_list_sessions(args)
        return

    if args.ingest_pptx:
        cmd_ingest_pptx(args)
        return

    if args.edit:
        if not args.session:
            parser.error("--edit requires --session")
        cmd_edit_slide(args)
        return

    if args.rollback:
        if not args.session:
            parser.error("--rollback requires --session")
        if not args.to_version:
            parser.error("--rollback requires --to-version")
        cmd_rollback_slide(args)
        return

    if args.editable:
        from editable_pptx.workflow import require_editable_render_backend
        try:
            require_editable_render_backend()
        except RuntimeError as exc:
            parser.error(str(exc))

    # ── 生成模式:必须提供 --plan ───────────────────────────
    if not args.plan:
        parser.error("必须传 --plan(生成模式),或使用 --edit / --rollback / --ingest-pptx / --list-sessions")

    # 校验:style 与 template source 至少有一个
    use_template = bool(args.template_pptx or args.template_images or args.template_profile)
    if not use_template and not args.style:
        parser.error("必须传 --style 或 --template-pptx / --template-images / --template-profile 至少其一")

    style_template = ""
    style_runtime_profile: Optional[Dict[str, Any]] = None
    if args.style:
        style_path = args.style
        if not os.path.isabs(style_path):
            candidate = SCRIPT_DIR / style_path
            if candidate.exists():
                style_path = str(candidate)
        style_template = load_style_template(style_path)
        try:
            style_runtime_profile = load_style_runtime_profile(style_path, style_template)
        except ValueError as exc:
            parser.error(str(exc))
    else:
        style_path = "(template-derived)"

    # Every visual source compiles to one RuntimeProfile. Template input has
    # precedence; a failed template analysis genuinely falls back to --style.
    runtime_profile: Optional[Dict[str, Any]] = None
    if use_template:
        sys.path.insert(0, str(SCRIPT_DIR))
        if args.template_profile:
            with open(args.template_profile, "r", encoding="utf-8") as f:
                raw_template_profile = json.load(f)
            runtime_profile = _normalize_template_profile_references(
                raw_template_profile, args.template_profile
            )
            print(f"📦 使用预分析模板 profile: {args.template_profile}")
        else:
            # 只给了 .pptx 没给 PNG -> 自动渲染到 <cwd>/template_renders/<stem>/
            if args.template_pptx and not args.template_images:
                from render_template import render_pptx_to_pngs
                print(f"🖨️  --template-images 未指定,自动渲染 {args.template_pptx}")
                args.template_images = str(render_pptx_to_pngs(args.template_pptx))
            from template_analyzer import analyze_template
            try:
                raw_template_profile = analyze_template(
                    pptx_path=args.template_pptx,
                    images_dir=args.template_images,
                    rebuild=args.rebuild_template_cache,
                )
                runtime_profile = normalize_runtime_profile(
                    raw_template_profile,
                    source_kind="template-clone",
                    profile_path=args.template_pptx or None,
                )
            except ValueError as e:
                msg = str(e)
                if "VISION_BASE_URL" in msg or "VISION_API_KEY" in msg:
                    print("[X] 模板克隆需要先获得 TemplateProfile。")
                    print("    多模态 agent / 原生 Codex:请先看 template_renders/page-*.png,生成 profile JSON 后用 --template-profile 传入。")
                    print("    纯文本 agent(如 DeepSeek):请配置 VISION_BASE_URL / VISION_API_KEY / VISION_MODEL_NAME。")
                raise
        if not runtime_profile or not runtime_profile.get("layouts"):
            print("(!)  模板分析未产出 layouts(缺 --template-images?),将回退到结构化 style RuntimeProfile")
            runtime_profile = select_runtime_profile(None, style_runtime_profile)
            if not runtime_profile:
                print("[X] 模板输入不可用且未提供 --style,无法构造有效生成风格。")
                print("    请提供有效 --template-profile / VISION_*,或额外传 --style 作为 fallback。")
                sys.exit(1)
            print(
                f"↩️  已切换到 style RuntimeProfile: "
                f"{runtime_profile.get('source')} ({runtime_profile.get('source_kind')})"
            )
        elif args.template_strict:
            missing_refs = [
                lay.get("id", f"layout-{i + 1:02d}")
                for i, lay in enumerate(runtime_profile.get("layouts", []))
                if not lay.get("reference_image") or not os.path.exists(str(lay.get("reference_image")))
            ]
            if missing_refs:
                print("(!)  --template-strict 已启用,但部分 layout 没有 reference_image,相关页会退化为纯 prompt 仿作。")
                print(f"    缺 reference_image 的 layout: {', '.join(missing_refs[:8])}")
    else:
        runtime_profile = select_runtime_profile(None, style_runtime_profile)
        if runtime_profile and runtime_profile.get("source_kind") == "distilled-style":
            print(f"📚 使用内置 style layout bank: {runtime_profile.get('source')}")
        elif runtime_profile:
            print(f"📚 使用 style RuntimeProfile: {runtime_profile.get('source')}")

    if runtime_profile is None:
        raise RuntimeError("RuntimeProfile resolution failed")

    strict_reference_mode = bool(
        args.template_strict
        and runtime_profile.get("source_kind") == "template-clone"
    )

    with open(args.plan, "r", encoding="utf-8") as f:
        slides_plan = json.load(f)

    if args.output:
        output_dir = args.output
    else:
        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
        # 默认输出到调用者当前工作目录,而不是 skill 安装目录
        output_dir = str(CWD / OUTPUT_BASE_DIR / timestamp)

    os.makedirs(os.path.join(output_dir, "images"), exist_ok=True)
    existing_prompts_data = _load_existing_prompts(output_dir)

    slides = slides_plan["slides"]
    total_slides = len(slides)

    if args.slides:
        target_nums = set(int(x.strip()) for x in args.slides.split(","))
        slides = [s for s in slides if s.get("slide_number") in target_nums]

    selected_slide_numbers = [s["slide_number"] for s in slides]

    print("=" * 60)
    print("PPT Generator (gpt-image-2) Started")
    print("=" * 60)
    print(f"Style: {style_path}")
    print(
        f"RuntimeProfile: {runtime_profile.get('source')} "
        f"(kind={runtime_profile.get('source_kind')}, "
        f"strategy={runtime_profile.get('prompt_strategy')}, "
        f"hash={runtime_profile.get('source_hash')}, "
        f"{len(runtime_profile.get('layouts', []))} layouts)"
    )
    print(f"Strict reference mode: {strict_reference_mode}")
    print(f"Slides: {len(slides)} / {total_slides}")
    print(f"Output: {output_dir}")
    print(f"Concurrency: {args.concurrency}")
    print(f"Backend: {args.backend}")
    print("=" * 60)
    print()

    prompts_data: Dict[str, Any] = {
        "metadata": {
            "title": slides_plan.get("title", "Untitled Presentation"),
            "total_slides": total_slides,
            "model": os.getenv("GPT_IMAGE_MODEL_NAME", "gpt-image-2"),
            "style": style_path,
            "template": (
                runtime_profile.get("source")
                if runtime_profile.get("source_kind") == "template-clone"
                else None
            ),
            "template_strict": strict_reference_mode,
            "runtime_profile": runtime_profile_summary(runtime_profile),
            "generated_at": datetime.now().isoformat(),
        },
        "slides": [],
    }

    # ── metadata.json(slide_spec 版本历史)──────────────────
    # If output_dir reuses an existing session, merge rather than overwrite
    existing_meta_path = os.path.join(output_dir, METADATA_FILENAME)
    if os.path.isfile(existing_meta_path):
        metadata = _load_metadata(output_dir)
        existing_order = list(metadata.get("slide_order", []))
        existing_seen = set()
        for raw in existing_order:
            try:
                existing_seen.add(int(raw))
            except (TypeError, ValueError):
                pass
        new_order = [n for n in selected_slide_numbers if int(n) not in existing_seen]
        if new_order:
            metadata["slide_order"] = existing_order + new_order
        metadata["generated_at"] = datetime.now().isoformat()
        metadata["runtime_profile"] = runtime_profile_summary(runtime_profile)
        print(f"Merging with existing metadata ({len(existing_order)} existing + {len(new_order)} new slides)")
    else:
        metadata = {
            "version": 1,
            "title": slides_plan.get("title", "Untitled Presentation"),
            "style": style_path,
            "model": os.getenv("GPT_IMAGE_MODEL_NAME", "gpt-image-2"),
            "generated_at": datetime.now().isoformat(),
            "runtime_profile": runtime_profile_summary(runtime_profile),
            "slide_order": selected_slide_numbers,
            "slides": {},
        }

    from template_analyzer import (
        match_layout,
        assign_layouts,
        check_layout_reuse,
    )
    reuse_warnings = check_layout_reuse(slides, runtime_profile)
    if reuse_warnings:
        print()
        print("=" * 60)
        print("📐 Layout 复用检测(建议尽量做到 1 page : 1 layout)")
        print("=" * 60)
        for w in reuse_warnings:
            print(w)
        print("=" * 60)
        print()
    assigned_layouts = assign_layouts(slides, runtime_profile)

    # 收集所有待跑任务(跳过已存在的)
    pending_tasks = []
    for slide_info in slides:
        slide_number = slide_info["slide_number"]
        page_type = slide_info.get("page_type", "content")
        content_text = slide_info.get("content", "")
        raw_slide_spec = slide_info.get("slide_spec")
        matched_layout = assigned_layouts.get(slide_number) or match_layout(
            slide_info, runtime_profile
        )
        matched_layout_id = matched_layout.get("id") if matched_layout else None
        if matched_layout:
            raw_slide_spec = attach_template_layout_profile(raw_slide_spec, matched_layout)
        slide_spec = prepare_external_image_slots(raw_slide_spec, output_dir)
        external_slots = _slots_with_real_sources(_collect_external_image_slots(slide_spec), output_dir)
        generation_reference_images = _collect_generation_reference_images(slide_spec, output_dir)

        existing = os.path.join(output_dir, "images", f"slide-{slide_number:02d}.png")
        if os.path.exists(existing) and not args.prepare_only:
            print(f"Slide {slide_number}: already exists, skipping.")
            prompts_data["slides"].append({
                "slide_number": slide_number,
                "page_type": page_type,
                "content": content_text,
                "prompt": "(skipped - already exists)",
                "image_path": existing,
            })
            # Also add to metadata for skipped slides (only if not already present)
            if slide_spec and str(slide_number) not in metadata.get("slides", {}):
                metadata["slides"][str(slide_number)] = _init_slide_metadata(
                    slide_number, page_type, slide_spec,
                    prompt_file="",
                    image_path=f"images/slide-{slide_number:02d}.png",
                )
            continue

        reference_image = None
        prompt = compile_runtime_slide_prompt(
            runtime_profile,
            matched_layout,
            slide_info,
            external_slots=external_slots,
        )
        if strict_reference_mode and matched_layout:
            reference_image = matched_layout.get("reference_image")

        if generation_reference_images:
            prompt += _format_generation_reference_constraint(generation_reference_images)

        asset_reference_image = create_asset_reference_skeleton(output_dir, slide_number, slide_spec)
        if generation_reference_images:
            reference_image = _merge_reference_images(reference_image, generation_reference_images)
            print(f"Slide {slide_number}: 使用 {len(generation_reference_images)} 张真实图作为生成参考(不作为 PPT 独立对象后贴)。")
        if asset_reference_image and reference_image:
            if isinstance(reference_image, list):
                reference_image = [*reference_image, asset_reference_image]
            else:
                reference_image = [reference_image, asset_reference_image]
            print(f"Slide {slide_number}: 使用模板 reference + 外部图片槽位骨架 reference。")
        elif asset_reference_image:
            reference_image = asset_reference_image

        pending_tasks.append({
            "slide_number": slide_number,
            "page_type": page_type,
            "content": content_text,
            "prompt": prompt,
            "reference_image": reference_image,
            "generation_reference_images": generation_reference_images,
            "asset_reference_image": asset_reference_image,
            "layout_id": matched_layout_id,
            "slide_spec": slide_spec,
        })

    if pending_tasks:
        results: Dict[int, Optional[str]] = {}
        if args.prepare_only:
            print(f"🧭 已通过统一 RuntimeProfile 编译 {len(pending_tasks)} 页;跳过图片生成。\n")
        else:
            from concurrent.futures import ThreadPoolExecutor, as_completed

            worker_count = max(1, min(args.concurrency, len(pending_tasks)))
            print(f"📦 派发 {len(pending_tasks)} 个任务到 {worker_count} 个并发 worker...\n")

            def _run(task):
                n = task["slide_number"]
                print(f">️  [slide {n}] start ({task['page_type']}{' / ref' if task.get('reference_image') else ''})")
                try:
                    path = generate_slide(
                        task["prompt"], n, output_dir,
                        reference_image_path=task.get("reference_image"),
                        backend=args.backend,
                    )
                    if not path:
                        raise RuntimeError("generator returned empty image path")
                    sanitize_external_image_regions(output_dir, n, task.get("slide_spec"))
                    print(f"[OK] [slide {n}] done")
                    return n, path
                except Exception as e:
                    print(f"[X] [slide {n}] failed: {e}")
                    return n, None

            with ThreadPoolExecutor(max_workers=worker_count) as executor:
                futures = [executor.submit(_run, t) for t in pending_tasks]
                for fut in as_completed(futures):
                    n, path = fut.result()
                    results[n] = path

        # 按原顺序写回 prompts_data,同时填充 metadata
        for task in pending_tasks:
            n = task["slide_number"]
            image_path = results.get(n)
            prompts_data["slides"].append({
                "slide_number": n,
                "page_type": task["page_type"],
                "content": task["content"],
                "layout_id": task.get("layout_id"),
                "reference_image": task.get("reference_image"),
                "generation_reference_images": task.get("generation_reference_images"),
                "asset_reference_image": task.get("asset_reference_image"),
                "prompt": task["prompt"],
                "image_path": image_path,
                "slide_spec": task.get("slide_spec"),
                "prepared_only": args.prepare_only,
            })

            # metadata.json: save slide_spec + version history
            spec = task.get("slide_spec") or {}
            prompt_rel = f"images/slide-{n:02d}_v0001.txt"
            img_rel = f"images/slide-{n:02d}_v0001.png"
            prompt_abs = os.path.join(output_dir, prompt_rel)
            os.makedirs(os.path.dirname(prompt_abs), exist_ok=True)
            with open(prompt_abs, "w", encoding="utf-8") as pf:
                pf.write(task["prompt"])

            if image_path:
                import shutil as _shutil
                versioned_initial = os.path.join(output_dir, img_rel)
                _shutil.copy2(image_path, versioned_initial)

                metadata["slides"][str(n)] = _init_slide_metadata(
                    n, task["page_type"], spec, prompt_rel, img_rel
                )
            elif args.prepare_only:
                metadata["slides"][str(n)] = _init_slide_metadata(
                    n, task["page_type"], spec, prompt_rel, ""
                )
            # For failed slides, still record the spec but no image
            elif spec:
                metadata["slides"][str(n)] = _init_slide_metadata(
                    n, task["page_type"], spec, "", ""
                )

    # 按 slide_number 排序,保证 prompts.json 与播放顺序一致
    prompts_data["slides"].sort(key=lambda s: s["slide_number"])
    print()

    # Save compiled prompts and structured metadata from the same RuntimeProfile.
    prompts_data = _merge_prompts_data(existing_prompts_data, prompts_data)
    save_prompts(output_dir, prompts_data)
    _save_metadata(metadata, output_dir)

    if args.prepare_only:
        print("[OK] Prompt preparation complete (no image API calls were made).")
        print(f"Prompts: {os.path.join(output_dir, 'prompts.json')}")
        print(f"Metadata: {os.path.join(output_dir, METADATA_FILENAME)}")
        return

    failed_slides = sorted(
        slide["slide_number"]
        for slide in prompts_data["slides"]
        if not slide.get("image_path")
    )
    if failed_slides:
        failed_str = ", ".join(str(n) for n in failed_slides)
        print(f"[X] 生成失败,未继续产出 PPTX。失败页:{failed_str}")
        print(f"    metadata.json 已保存,修复后可 --edit 继续。")
        sys.exit(1)

    pptx_path = None
    if not args.no_pptx:
        pptx_path = generate_pptx(
            output_dir,
            _collect_slide_numbers(metadata),
            title=slides_plan.get("title", "Untitled"),
            metadata=metadata,
        )

    if not args.no_pptx and (args.auto_review_overlays or args.auto_repair_overlays):
        slide_nums = _collect_slide_numbers(metadata)
        reviews = review_external_overlays(metadata, output_dir, slide_nums)
        if args.auto_repair_overlays:
            max_repair_rounds = int(os.getenv("PPT_OVERLAY_REPAIR_ROUNDS", "3"))
            for repair_round in range(1, max_repair_rounds + 1):
                repair_updates: Dict[int, Dict[str, Any]] = {}
                for n, review in reviews.items():
                    if _overlay_review_passed(review):
                        continue
                    if review and review.get("vision_error"):
                        continue
                    spec = _get_latest_slide_spec(metadata, n)
                    slot_id = _first_external_slot_id(spec)
                    if not slot_id:
                        continue
                    vision_suggested = _coerce_suggested_position(review.get("suggested_position"))
                    suggested = vision_suggested or _fallback_repair_position(spec, slot_id)
                    if not suggested:
                        continue
                    if vision_suggested:
                        suggested = _template_preserving_repair_position(spec, slot_id, suggested)
                    if not vision_suggested:
                        suggested = _expand_position_for_readability(spec, slot_id, suggested)
                    repair_updates[n] = {
                        slot_id: {
                            "position": suggested,
                            "tailor_to_asset": False,
                            "slot_strategy": "exact",
                            "layout_intent": "manual",
                        }
                    }

                if not repair_updates:
                    break

                print()
                print("=" * 60)
                print(f"🔧 自动贴图修复 第 {repair_round}/{max_repair_rounds} 轮:{len(repair_updates)} 页")
                print("=" * 60)
                for n, updates in repair_updates.items():
                    print(f"slide {n}: {updates}")
                    cmd_args = copy.copy(args)
                    cmd_args.edit = n
                    cmd_args.session = output_dir
                    cmd_args.external_slot_repair = True
                    cmd_args.element_updates = json.dumps(updates, ensure_ascii=False)
                    cmd_args.edit_prompt = None
                    cmd_args.edit_instruction = f"auto external overlay repair round {repair_round}"
                    cmd_args.no_pptx = True
                    cmd_edit_slide(cmd_args)
                    metadata = _load_metadata(output_dir)

                pptx_path = generate_pptx(
                    output_dir,
                    _collect_slide_numbers(metadata),
                    title=slides_plan.get("title", "Untitled"),
                    metadata=metadata,
                )
                reviews = review_external_overlays(metadata, output_dir, _collect_slide_numbers(metadata))

        failed_reviews = {
            n: review for n, review in reviews.items()
            if not _overlay_review_passed(review)
        }
        if failed_reviews:
            print()
            print("[X] 贴图质检未通过,未交付为成功结果。")
            for n, review in sorted(failed_reviews.items()):
                issue = review.get("cover_issue") or review.get("recommendation") or "unknown overlay issue"
                print(f"    slide {n}: {issue}")
            print(f"    Trace: {os.path.join(output_dir, 'external_image_trace')}")
            sys.exit(1)

    editable_pptx_path = None
    editable_render_dir = None
    if args.editable and not args.no_pptx:
        try:
            scene_dir = resolve_editable_scene_dir(args, output_dir)
            from editable_pptx.workflow import build_editable_output

            editable_result = build_editable_output(
                scene_dir,
                _collect_slide_numbers(metadata),
                output_dir,
                slides_plan.get("title", "Untitled"),
            )
            editable_pptx_path = str(editable_result.pptx_path)
            editable_render_dir = str(editable_result.render_dir)
        except (ValueError, OSError, RuntimeError, json.JSONDecodeError) as exc:
            print()
            print(f"[X] 可编辑 PPTX 构建失败:{exc}")
            print(f"    普通 PPTX 与已有 scene 证据已保留在:{output_dir}")
            sys.exit(1)

    print()
    print("=" * 60)
    print("Generation Complete!")
    print("=" * 60)
    print(f"Output directory: {output_dir}")
    print(f"Metadata:    {os.path.join(output_dir, 'metadata.json')}")
    if pptx_path:
        print(f"PPTX file:   {pptx_path}")
    if editable_pptx_path:
        print(f"Editable:    {editable_pptx_path}")
    if editable_render_dir:
        print(f"Editable render: {editable_render_dir}")
    print()


if __name__ == "__main__":
    main()
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall