图片版 PPT 导演 Skill（完整可安装版）

# 图片版 PPT 导演 Skill（完整可安装版） 这篇是补充版。上一篇讲了为什么要做 `image-ppt-director`，这一篇把真正能学习、能安装、能复刻的 Skill 内容放出来。 ## 下载完整 Skill 包 ```text http://openenergy.top:3001/downloads/skills/image-ppt-director.zip ``` 安装方式： ```bash mkdir -p ~/.codex/skills cd ~/.codex/skills curl -O http://openenergy.top:3001/downloads/skills/image-ppt-director.zip unzip image-ppt-director.zip ``` 安装后路径： ```text ~/.codex/skills/image-ppt-director ``` > 注意：Skill 包里不包含任何 API Key。调用 GPT-Image-2 时，请在本地通过环境变量提供 `OPENAI_API_KEY`。 --- ## 1. SKILL.md ```markdown --- name: image-ppt-director description: Create image-based PPT decks where each slide is a complete generated 16:9 image, using a GPT-Image-2/OpenAI-compatible image API plus deterministic local compositing for exact assets. Use when the user asks for 图片版PPT, GPT-Image-2 PPT, 企业介绍PPT, 宣传PPT, 方案PPT, 课件PPT, or wants slide text and visuals generated directly into full-page images instead of editable text boxes. --- # Image PPT Director Use this skill to create full-image presentation decks: generate one finished slide image per page, then place each image full-bleed into a PPTX. This is best for fast, high-polish decks where visual atmosphere matters more than later text editing. ## Core Rule Let GPT-Image-2 generate the whole slide image, including short Chinese titles and labels. Do not add ordinary slide text afterward. Use local compositing only for assets that must be exact: - QR codes and contact cards - official certificates - real logos or product screenshots - exact photos provided by the user Never write API keys into skill files. Pass credentials through environment variables. ## Workflow 1. Read source materials: user request, DOCX/Markdown, provided images, previous slides or posters. 2. Apply U-type thinking: identify audience, core promise, proof objects, and a concise claim spine. 3. Plan 6-12 slides. Prefer 8 slides for company introductions: - cover - overview - capability/platform - process - scope/metrics - scene/gallery - proof/qualification - contact/closing 4. Write `slides.json` following `references/slides-schema.md`. 5. Generate slide images with `scripts/generate_image_ppt.py`. 6. Review the contact sheet. Regenerate weak pages with shorter prompts if text is wrong or cluttered. 7. Composite exact QR/certificate/logo assets locally using `asset_overlays`. 8. Export PPTX. Each slide should contain exactly one full-bleed raster image. ## API Defaults Use OpenAI-compatible image APIs. Default values: - `OPENAI_BASE_URL`: `https://api.supertoken.cc/v1` - `model`: `gpt-image-2` - slide size: `1536x864` - quality: `medium` The user or environment must provide `OPENAI_API_KEY`. If not set, ask for it or run `--dry-run`. ## Prompting Rules Keep per-slide prompts focused. Long prompts increase timeout and text errors. Use this shape: ```text 16:9 premium corporate presentation slide, full-slide image with native Chinese text. Company/topic: <name>. Slide title: <short Chinese title>. Key text: <3-8 short labels or one short subtitle>. Visual: <specific scene and proof object>. Style: <user style>, professional, coherent, print quality. Requirements: correct readable Chinese headings, no watermark, no random letters, no clutter. ``` For detailed prompt patterns, read `references/prompt-patterns.md`. ## Script Run: ```bash OPENAI_BASE_URL="https://api.supertoken.cc/v1" \ OPENAI_API_KEY="$OPENAI_API_KEY" \ python /Users/yuanjingshijie/.codex/skills/image-ppt-director/scripts/generate_image_ppt.py \ --spec slides.json \ --out-dir output/ppt/<project-slug> ``` Useful options: - `--dry-run`: validate paths and print planned image requests without API calls. - `--skip-existing`: reuse existing slide images. - `--force`: overwrite existing generated images and deck. - `--no-generate`: build PPTX/contact sheet from existing slide images only. Outputs: - `slides/slide-XX-*.png` - `<deck-title>.pptx` - `contact-sheet.png` - `prompts.json` ## Quality Gates Before final response: - Confirm PPTX exists and has the expected slide count. - Open or preview the contact sheet. - Check the final contact/closing page contains the real QR code if requested. - Report that normal text is image-native and not editable. - Mention any known risk: GPT-generated small Chinese text may be imperfect. ``` --- ## 2. slides.json 模板 ```markdown # Slides JSON Schema Create a JSON file with this structure: ```json { "deck_title": "四川卫安衡检验检测有限公司-企业介绍图片版PPT", "theme": "专业、健康、安全、科技感，蓝白金配色", "api": { "base_url": "https://api.supertoken.cc/v1", "model": "gpt-image-2", "size": "1536x864", "quality": "medium" }, "slides": [ { "id": "01-cover", "title": "科学检测 · 守护安全", "prompt": "16:9 premium corporate presentation slide...", "reference_images": ["path/to/reference.png"], "out": "slide-01-cover.png" }, { "id": "08-contact", "title": "联系方式", "prompt": "16:9 closing slide with a blank QR placeholder...", "asset_overlays": [ { "type": "qr", "image": "path/to/qr.png", "box": [1005, 317, 260, 260], "border": "green" } ], "out": "slide-08-contact.png" } ] } ``` ## Fields - `deck_title`: output PPTX filename stem. - `theme`: common style direction; the agent should merge it into each prompt. - `api.base_url`: optional; defaults to `OPENAI_BASE_URL` or `https://api.supertoken.cc/v1`. - `api.model`: defaults to `gpt-image-2`. - `api.size`: defaults to `1536x864`. - `api.quality`: defaults to `medium`. - `slides[].id`: stable slide identifier. - `slides[].title`: human-readable planning title. - `slides[].prompt`: complete image prompt. - `slides[].reference_images`: optional list of local images passed to image edit endpoint. - `slides[].out`: optional output filename. - `slides[].asset_overlays`: optional deterministic local overlays after generation. ## Asset Overlay Types ### QR ```json { "type": "qr", "image": "path/to/qr.png", "box": [1005, 317, 260, 260], "border": "green" } ``` Use for real QR codes. The script places the QR inside a white card and draws a border. ### Image ```json { "type": "image", "image": "path/to/certificate.jpg", "box": [420, 210, 300, 420], "fit": "contain", "border": "gold" } ``` Use for real certificates, logos, screenshots, or photos. Coordinates are pixels on the generated slide image, usually `1536x864`. ``` --- ## 3. Prompt 模板 ```markdown # Prompt Patterns Keep visible Chinese short. Use strong nouns and 3-8 labels rather than paragraphs. ## Cover ```text 16:9 premium corporate presentation cover slide, full-slide image with native Chinese text. Company: <company>. Main title: <title>. Subtitle: <one-line positioning>. Visual: one powerful hero scene, <industry proof object>, clean negative space, cinematic but professional. Style: <style>, coherent brand system, print quality. Requirements: correct readable Chinese headings, no watermark, no random letters, no clutter. ``` ## Company Overview ```text 16:9 premium corporate presentation slide, full-slide image with native Chinese text. Slide title: 公司概况. Key text: <fact 1>｜<fact 2>｜<fact 3>｜<fact 4>. Visual: modern workspace/lab/field scene, four concise fact cards, credible and calm. Requirements: readable Chinese, no long paragraphs. ``` ## Capability / Platform ```text Slide title: 检测能力与仪器平台. Key labels: <instrument 1>, <instrument 2>, <instrument 3>, <capability 1>, <capability 2>. Visual: advanced instruments, data HUD, molecule/spectrum diagrams, professional operators. ``` ## Process ```text Slide title: 标准化检测流程. Show a clean left-to-right process map: <step 1>, <step 2>, <step 3>, ... Visual: SOP quality control, connected nodes, subtle lab background. ``` ## Scope / Matrix ```text Slide title: 检测指标覆盖. Create a clean matrix/table infographic with categories: <category list>. Visual: icons, samples, charts, scientific but not dense. ``` ## Gallery / Scene ```text Slide title: 实验室工作环境. Visual: premium photo-collage style with real-work atmosphere, clean frames, concise labels. ``` ## Qualification / Proof ```text Slide title: 资质背书 · 安心可见. Visual: certificate wall, official frames, shield, gold accents, credible lab background. Text badges: <badge 1>, <badge 2>, <badge 3>. ``` Use real certificates as local overlays when available. ## Closing / Contact ```text 16:9 premium corporate presentation closing slide, full-slide image with native Chinese text. Main title: <closing sentence>. Subtitle: <three-part promise>. Contact text: <address>; <phone>. Leave a clean white square QR code placeholder on the right side, empty inside for real QR insertion. Visual: bright professional scene, warm trustworthy closing atmosphere. Requirements: no fake QR pattern inside placeholder. ``` Always overlay the real QR locally after generation. ``` --- ## 4. 核心脚本节选 完整脚本在 zip 包里： ```text image-ppt-director/scripts/generate_image_ppt.py ``` 节选如下： ```python #!/usr/bin/env python3 """Generate a full-image PPT deck from a slides JSON spec.""" from __future__ import annotations import argparse import base64 import json import os import re import shutil import sys from pathlib import Path from typing import Any, Dict, Iterable, List, Optional, Tuple from PIL import Image, ImageDraw, ImageFilter, ImageOps from pptx import Presentation from pptx.util import Inches DEFAULT_BASE_URL = "https://api.supertoken.cc/v1" DEFAULT_MODEL = "gpt-image-2" DEFAULT_SIZE = "1536x864" DEFAULT_QUALITY = "medium" def die(message: str) -> None: raise SystemExit(f"ERROR: {message}") def slugify(value: str) -> str: value = re.sub(r"[^\w\u4e00-\u9fff.-]+", "-", value.strip()) value = re.sub(r"-{2,}", "-", value).strip("-") return value or "image-ppt" def load_json(path: Path) -> Dict[str, Any]: with path.open("r", encoding="utf-8") as f: return json.load(f) def parse_size(size: str) -> Tuple[int, int]: try: w, h = size.lower().split("x", 1) return int(w), int(h) except Exception as exc: raise ValueError(f"Invalid size {size!r}; expected WIDTHxHEIGHT") from exc def resolve_path(value: str, base_dir: Path) -> Path: p = Path(value).expanduser() if not p.is_absolute(): p = (base_dir / p).resolve() return p def ensure_parent(path: Path) -> None: path.parent.mkdir(parents=True, exist_ok=True) def create_openai_client(base_url: str): try: from openai import OpenAI except ImportError: die("openai package is not installed in the active Python environment") return OpenAI(base_url=base_url) def decode_image_result(result: Any, out_path: Path) -> None: if not getattr(result, "data", None): die("image API returned no data") item = result.data[0] b64 = getattr(item, "b64_json", None) if b64: ensure_parent(out_path) out_path.write_bytes(base64.b64decode(b64)) return url = getattr(item, "url", None) if not url: die("image API returned neither b64_json nor url") try: import requests except ImportError: die("requests is required to download URL image responses") resp = requests.get(url, timeout=300) resp.raise_for_status() ensure_parent(out_path) out_path.write_bytes(resp.content) def generate_slide( client: Any, slide: Dict[str, Any], out_path: Path, spec_dir: Path, api: Dict[str, Any], ) -> None: prompt = slide.get("prompt") if not prompt: die(f"slide {slide.get('id') or slide.get('title')} is missing prompt") model = slide.get("model") or api.get("model") or DEFAULT_MODEL size = slide.get("size") or api.get("size") or DEFAULT_SIZE quality = slide.get("quality") or api.get("quality") or DEFAULT_QUALITY refs = [resolve_path(p, spec_dir) for p in slide.get("reference_images", [])] if refs: files = [p.open("rb") for p in refs] try: result = client.images.edit( model=model, image=files, prompt=prompt, size=size, quality=quality, ) finally: for f in files: f.close() else: result = client.images.generate( model=model, prompt=prompt, size=size, quality=quality, ) decode_image_result(result, out_path) def fit_contain(img: Image.Image, size: Tuple[int, int]) -> Image.Image: img = ImageOps.exif_transpose(img).convert("RGBA") img.thumbnail(size, Image.Resampling.LANCZOS) canvas = Image.new("RGBA", size, (255, 255, 255, 255)) canvas.alpha_composite(img, ((size[0] - img.width) // 2, (size[1] - img.height) // 2)) return canvas def overlay_qr(canvas: Image.Image, item: Dict[str, Any], spec_dir: Path) -> None: image_path = resolve_path(item["image"], spec_dir) x, y, w, h = map(int, item["box"]) qr = Image.open(image_path).convert("RGBA") card = Image.new("RGBA", (w, h), (255, 255, 255, 255)) inner = fit_contain(qr, (max(1, w - 24), max(1, h - 24))) card.alpha_composite(inner, ((w - inner.width) // 2, (h - inner.height) // 2)) shadow = Image.new("RGBA", (w + 16, h + 16), (0, 0, 0, 0)) sd = ImageDraw.Draw(shadow) sd.rounded_rectangle((8, 8, w + 8, h + 8), radius=12, fill=(0, 0, 0, 55)) shadow = shadow.filter(ImageFilter.GaussianBlur(6)) canvas.alpha_composite(shadow, (x - 8, y - 4)) canvas.alpha_composite(card, (x, y)) color = (25, 150, 82, 255) if item.get("border") == "green" else (214, 173, 94, 255) d = ImageDraw.Draw(canvas) d.rounded_rectangle((x, y, x + w, y + h), radius=10, outline=color, width=4) def overlay_image(canvas: Image.Image, item: Dict[str, Any], spec_dir: Path) -> None: image_path = resolve_path(item["image"], spec_dir) x, y, w, h = map(int, item["box"]) source = Image.open(image_path) fitted = fit_contain(source, (w, h)) shadow = Image.new("RGBA", (w + 12, h + 12), (0, 0, 0, 0)) sd = ImageDraw.Draw(shadow) sd.rounded_rectangle((6, 6, w + 6, h + 6), radius=4, fill=(0, 0, 0, 40)) shadow = shadow.filter(ImageFilter.GaussianBlur(4)) canvas.alpha_composite(shadow, (x - 6, y - 3)) canvas.alpha_composite(fitted, (x, y)) if item.get("border"): color = (214, 173, 94, 255) if item.get("border") == "gold" else (25, 150, 82, 255) d = ImageDraw.Draw(canvas) d.rectangle((x, y, x + w - 1, y + h - 1), outline=color, width=2) def apply_overlays(image_path: Path, slide: Dict[str, Any], spec_dir: Path) -> None: overlays = slide.get("asset_overlays") or [] if not overlays: return canvas = Image.open(image_path).convert("RGBA") for item in overlays: typ = item.get("type") if typ == "qr": overlay_qr(canvas, item, spec_dir) elif typ == "image": overlay_image(canvas, item, spec_dir) else: die(f"unsupported overlay type: {typ}") canvas.convert("RGB").save(image_path, quality=95) def create_pptx(images: List[Path], out_path: Path) -> None: prs = Presentation() prs.slide_width = Inches(13.333333) prs.slide_height = Inches(7.5) blank = prs.slide_layouts[6] for image in images: slide = prs.slides.add_slide(blank) slide.shapes.add_picture(str(image), 0, 0, width=prs.slide_width, height=prs.slide_height) # ... 后半部分在 zip 包 scripts/generate_image_ppt.py 中，包含 PPTX 导出、contact sheet 和 CLI 参数处理。 ``` --- ## 5. 最小使用示例 ```bash OPENAI_BASE_URL="https://api.supertoken.cc/v1" OPENAI_API_KEY="$OPENAI_API_KEY" python ~/.codex/skills/image-ppt-director/scripts/generate_image_ppt.py --spec slides.json --out-dir output/ppt/my-project ``` 如果只是检查结构，不想立刻生图： ```bash python ~/.codex/skills/image-ppt-director/scripts/generate_image_ppt.py --spec slides.json --out-dir output/ppt/my-project --dry-run ``` 如果已经有每页图片，只想生成 PPT： ```bash python ~/.codex/skills/image-ppt-director/scripts/generate_image_ppt.py --spec slides.json --out-dir output/ppt/my-project --no-generate ``` --- ## 6. 这个 Skill 的关键原则 ```text 氛围交给模型，事实交给本地合成。 ``` 也就是说： - 每页整体视觉、标题、短标签，可以让 GPT-Image-2 原生生成。 - 真实二维码、证书、Logo、产品图、合同级联系方式，必须本地合成。 - 最后 PPTX 里每页只放一张满版图片，不后贴普通文字。 这样既能保留图片版 PPT 的高级感，又能避免关键事实被模型画错。 --- ## 7. 适合复刻的指令 以后可以这样对 Codex 说： ```text 用 image-ppt-director，基于这个 docx 做一套 8 页企业介绍 PPT。 风格：科技感、高端、健康安全、蓝白金。 要求：每页整图生成，不后贴文字，最后页放真实二维码。 ``` 这就是这次沉淀的完整可学习版本。