Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

fix(image): honor host-native generation path

hugohe38b7e1d848d3d
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index 2755df3b..a91b488b 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -496,20 +496,20 @@ Then **lazy-load the path-specific reference** for each row that actually needs
| Acquire Via | Load reference (only if any such row exists) | Run |
|---|---|---|
-| `ai` | `references/image-generator.md` | `python3 ${SKILL_DIR}/scripts/image_gen.py --manifest <project_path>/images/image_prompts.json` |
+| `ai` | `references/image-generator.md` | write `<project_path>/images/image_prompts.json`, then follow `image-generator.md §7 Path Selection` (`image_gen.py --manifest` is **Path A only**) |
| `web` | `references/image-searcher.md` | `python3 ${SKILL_DIR}/scripts/image_search.py ...` (≥2 web rows → `--batch images/image_queries.json`) |
| `slice` | `references/image-generator.md` §4.3 | derived — **after** the parent `ai` sheet row is `Generated`, run `python3 ${SKILL_DIR}/scripts/slice_images.py <project_path>/images/<sheet>.png --grid RxC --names ... --trim --alpha` (see workflow step 2.5) |
| `user` / `formula` / `placeholder` | (skip) | (skip) |
A deck with only `ai` rows never loads `image-searcher.md`; a deck with only `web` rows never loads `image-generator.md`. A mixed deck loads both, processes each row through its own path, and writes both `image_prompts.json` and `image_sources.json`.
-> ⚠️ **In-pipeline ai path MUST use manifest mode** — even when only 1 ai row exists. Write `images/image_prompts.json` first, then run `image_gen.py --manifest`, then `image_gen.py --render-md` to produce the `image_prompts.md` sidecar. The positional form (`image_gen.py "prompt" ...`) is reserved for **out-of-pipeline one-off testing / single-image fixups** — it skips manifest + sidecar, leaving no audit trail.
+> ⚠️ **In-pipeline ai rows MUST use the manifest contract** — even when only 1 ai row exists. Always write `images/image_prompts.json` first and render `image_prompts.md` with `image_gen.py --render-md`. Then execute the confirmed path from `image-generator.md §7`: `image_gen.py --manifest` is **Path A only**; `host-native` is **Path B** and MUST skip `--manifest`; `manual` writes the prompts and stops for external generation. The positional form (`image_gen.py "prompt" ...`) is reserved for **out-of-pipeline one-off testing / single-image fixups** — it skips manifest + sidecar, leaving no audit trail.
> ⚠️ **web path — batch multiple rows**: when ≥2 rows are `Acquire Via: web`, write all queries into `images/image_queries.json` and run `image_search.py --batch` once (concurrent acquisition, status written back), instead of one CLI call per row. A single web row may use the positional single-query form. See [image-searcher.md](references/image-searcher.md) §5.
> 💡 **ai path — spot illustrations as one sheet**: when the §VIII image resource plan needs ≥3 same-family spot illustrations as decorative accessories, generate **one grid sheet** (a single `ai` sheet row) instead of one row per element, then slice it (workflow step 2.5 below). Choose sheet geometry from intended placement: `1xN` / `Nx1` are useful for extreme portrait / landscape cells, and a designed `MxN` grid is valid when its cell ratio fits the planned elements. The sheet row is generated but not placed; each cut **element row** (`Acquire Via: slice`) is placed and must appear in `spec_lock.md images`. One generation = one coherent style across all pieces. Resource contract + the geometry rules: [image-generator.md](references/image-generator.md) §4.3.
-> ⚠️ **Honor the confirmed image source**: the `ai` generation path (Path A = `image_gen.py` API / Path B = host-native tool / Offline Manual) is **not** auto-only — a confirmed choice other than `auto` wins, whether it came from chat (canonical) or, when the page was used, `result.json.image_ai_path`. `host-native` forces Path B even when `IMAGE_BACKEND` is configured; `api` forces Path A; `manual` forces offline. The `--manifest` command above is Path A. Full selection rule: [image-generator.md](references/image-generator.md) §7 Path Selection.
+> ⚠️ **Honor the confirmed image source before running any generation command**: the `ai` generation path (Path A = `image_gen.py` API / Path B = host-native tool / Offline Manual) is **not** auto-only — a confirmed choice other than `auto` wins, whether it came from chat (canonical) or, when the page was used, `result.json.image_ai_path`. `host-native` forces Path B even when `IMAGE_BACKEND` is configured; `api` forces Path A; `manual` forces offline. Never run `image_gen.py --manifest` when the confirmed value is `host-native` or `manual`. Full selection rule: [image-generator.md](references/image-generator.md) §7 Path Selection.
Workflow:
diff --git a/skills/ppt-master/references/image-generator.md b/skills/ppt-master/references/image-generator.md
index 1c90f6a8..9c911718 100644
--- a/skills/ppt-master/references/image-generator.md
+++ b/skills/ppt-master/references/image-generator.md
@@ -130,9 +130,9 @@ For each `Acquire Via: ai` row in `design_spec.md §VIII`:
The assembled prompt is **one cohesive paragraph**, not a bulleted list of tags. See §4 for the assembly template.
-### Step 4 — Write the manifest and generate
+### Step 4 — Write the manifest and execute the confirmed path
-Write `project/images/image_prompts.json` per §6. Then run `image_gen.py --manifest` (§7 Path A). The CLI iterates `items[]`, writes status back, and re-renders the Markdown sidecar.
+Write `project/images/image_prompts.json` per §6. Then follow §7 Path Selection. `image_gen.py --manifest` is Path A only; confirmed `host-native` runs the host image tool directly, and confirmed `manual` renders the Markdown sidecar and hands off without API generation.
---
@@ -461,7 +461,7 @@ Write `project/images/image_prompts.json` with this shape:
## 7. Generation Execution
-> Prerequisite: §3 Steps 1-3 complete; `images/image_prompts.json` exists and validates.
+> Prerequisite: §3 Steps 1-3 complete; `images/image_prompts.json` exists and validates. The manifest is the shared audit/source contract for all modes. It does **not** imply that `image_gen.py --manifest` should run; that command is Path A only.
### Path Selection (Deterministic)
@@ -477,8 +477,8 @@ C (AI-generated) supports three implementation modes sharing one `image_prompts.
0. **Confirmed override (wins)** — honor the confirmed image source. The **chat choice is canonical**; the Confirm UI is only a convenience surface that, when used, records the same choice to `<project>/confirm_ui/result.json` as `image_ai_path` (so there is no `result.json` on the chat path — read the choice from the conversation). From either channel, if the choice is set and not `auto`, honor it directly, **even when it contradicts `IMAGE_BACKEND`**:
- `api` → **Path A** (`image_gen.py --manifest`).
- - `host-native` → **Path B** (host's native image tool) — skip A *even if `IMAGE_BACKEND` is configured*.
- - `manual` → **Offline Manual** (write prompts, hand off).
+ - `host-native` → **Path B** (host's native image tool) — skip A and do **not** run `image_gen.py --manifest`, *even if `IMAGE_BACKEND` is configured*.
+ - `manual` → **Offline Manual** (write prompts, render the Markdown sidecar, hand off; do **not** run `image_gen.py --manifest`).
("use Codex's image tool" / "走接口生成" in chat = `host-native` / `api`.) If the chosen path turns out unavailable (e.g. `host-native` but the host has no image tool), fall through along the chain below from that point. Only when no source named a path (chat silent, and `image_ai_path` `auto` / absent) does the automatic chain decide.
1. **Try Path A** — if `IMAGE_BACKEND` is configured (env or `.env`), run `image_gen.py --manifest`. If it fails twice in a row, fall to Path B.
2. **Try Path B** — if `IMAGE_BACKEND` was not configured (A skipped), or A failed, and the host has a native image tool (Codex / Antigravity / Claude Code / similar), the agent invokes the host's image capability directly.
@@ -552,6 +552,8 @@ Precedence:
Triggered automatically when `IMAGE_BACKEND` is not configured (or Path A fails) **and** the host provides a native image generation tool (Codex, Antigravity, Claude Code's image tool, and similar). No user prompting required — the agent detects the host capability and proceeds. The user may also explicitly name this path ("use Codex's image tool") to force it even when `IMAGE_BACKEND` is configured.
- Agent invokes the host's native image tool directly; prompts come from `items[].prompt`
+- Do **not** run `image_gen.py --manifest` in Path B. That command is Path A and may use configured API/proxy backends even when the user confirmed host-native.
+- Still run `python3 scripts/image_gen.py --render-md project/images/image_prompts.json` so the human-readable sidecar exists without touching any backend.
- **Batch for speed, mind the rate**: when the host can run independent tool calls in parallel (e.g. Claude Code issues independent calls concurrently), fire several generations together in modest groups — a few rows at a time (~3–4), not the whole manifest at once — so their latency overlaps without flooding the host's image quota. When the host only runs tools serially, generate one row at a time. This mirrors Path A's default concurrency of 3.
- Outputs **must** land at `project/images/<filename-from-resource-list>` with dimensions matching the Image Resource List
- Mark each item's `status` `Generated` in the manifest the moment its file lands — as each completes, not in one pass at the end (so an interrupted batch leaves accurate state)
@@ -633,7 +635,7 @@ Diagnose the failure category, adjust the **one specific dimension** responsible
**Variant workflow**:
1. Set the unsatisfactory item's `status` back to `Pending` and update its `prompt` in place
-2. Re-run `image_gen.py --manifest` — only that item is re-processed
+2. Re-run the same confirmed path used for the original item: Path A may re-run `image_gen.py --manifest` (only that item is re-processed); Path B uses the host-native tool again for that item; Offline Manual re-renders the sidecar and hands off
3. To try multiple stylistic approaches, append additional items with distinct filenames (e.g. `cover_bg_v2.png`) rather than overwriting
---
diff --git a/skills/ppt-master/scripts/docs/image.md b/skills/ppt-master/scripts/docs/image.md
index 7927a1f0..16ec6696 100644
--- a/skills/ppt-master/scripts/docs/image.md
+++ b/skills/ppt-master/scripts/docs/image.md
@@ -40,6 +40,12 @@ Output files land directly under `project/images/`. Formula filenames should use
Unified image generation entry point.
+This script is the **Path A** API/proxy executor for generated images. In the
+PPT pipeline, always check the confirmed `image_ai_path` before running manifest
+mode: `host-native` uses the host's image tool directly and must not run
+`image_gen.py --manifest`; use `image_gen.py --render-md` only for its
+read-only Markdown sidecar.
+
```bash
python3 scripts/image_gen.py "A modern futuristic workspace"
python3 scripts/image_gen.py "Abstract tech background" --aspect_ratio 16:9 --image_size 4K
diff --git a/skills/ppt-master/scripts/image_gen.py b/skills/ppt-master/scripts/image_gen.py
index 919bcd43..ae41496b 100644
--- a/skills/ppt-master/scripts/image_gen.py
+++ b/skills/ppt-master/scripts/image_gen.py
@@ -343,6 +343,50 @@ def _resolve_backend() -> tuple[object, str]:
sys.exit(1)
+def _confirmed_image_ai_path_for_manifest(manifest_path: str) -> str | None:
+ """Return confirmed image_ai_path for a project manifest, if present."""
+ path = Path(manifest_path).resolve()
+ if path.parent.name != "images":
+ return None
+ result_file = path.parent.parent / "confirm_ui" / "result.json"
+ if not result_file.exists():
+ return None
+ try:
+ data = json.loads(result_file.read_text(encoding="utf-8"))
+ except (OSError, json.JSONDecodeError):
+ return None
+ value = data.get("image_ai_path")
+ if not isinstance(value, str):
+ return None
+ return value.strip().lower().replace("_", "-")
+
+
+def _guard_confirmed_non_api_path(manifest_path: str) -> None:
+ """Prevent accidental Path A execution after host-native/manual was confirmed."""
+ image_ai_path = _confirmed_image_ai_path_for_manifest(manifest_path)
+ if image_ai_path not in {"host-native", "manual"}:
+ return
+ if image_ai_path == "host-native":
+ print(
+ "Error: confirmed image_ai_path is 'host-native'.\n"
+ "\n"
+ "Do NOT run image_gen.py --manifest for this project. That command is Path A\n"
+ "and may use the configured API/proxy backend. Use the host's native image\n"
+ "generation tool with prompts from images/image_prompts.json, save outputs to\n"
+ "images/<filename>, update each item status to Generated, then run:\n"
+ " python3 scripts/image_gen.py --render-md images/image_prompts.json\n"
+ )
+ else:
+ print(
+ "Error: confirmed image_ai_path is 'manual'.\n"
+ "\n"
+ "Do NOT run image_gen.py --manifest for this project. Render the Markdown\n"
+ "sidecar and hand images/image_prompts.md to the user for external generation:\n"
+ " python3 scripts/image_gen.py --render-md images/image_prompts.json\n"
+ )
+ sys.exit(1)
+
+
DEFAULT_MANIFEST_CONCURRENCY = 3
STATUS_PENDING = "Pending"
@@ -708,6 +752,9 @@ def main() -> None:
print(f"Rendered Markdown sidecar: {md_path}")
return
+ if args.manifest:
+ _guard_confirmed_non_api_path(args.manifest)
+
try:
_load_image_env_file()
_validate_runtime_config()