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

feat(image_gen): render Markdown sidecar from JSON manifest

hugohe31dea399982ba
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index 18b14d18..e1ee3597 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -337,7 +337,7 @@ python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path>
🚧 **Image readiness GATE** (when Step 5 left ai rows in `Needs-Manual`): every expected file must exist at `project/images/<filename>` before running 7.1.
-> If files are missing: PAUSE, list the missing filenames, point the user to `images/image_prompts.json` (the `prompt` field of each `Needs-Manual` item is paste-ready for ChatGPT / Gemini / Midjourney) and the required placement `project/images/<filename>`. Resume Step 7.1 only after all expected files are in place. `finalize_svg.py` and `svg_to_pptx.py` do not detect missing files at this layer — proceeding with gaps produces a deck with broken image references.
+> If files are missing: PAUSE, list the missing filenames, point the user to `images/image_prompts.md` (each `### Image N:` block is paste-ready for ChatGPT / Gemini / Midjourney; auto-generated from `image_prompts.json`) and the required placement `project/images/<filename>`. Resume Step 7.1 only after all expected files are in place. `finalize_svg.py` and `svg_to_pptx.py` do not detect missing files at this layer — proceeding with gaps produces a deck with broken image references.
> ⚠️ Run the three sub-steps **one at a time** — each must complete successfully before the next.
> ❌ **NEVER** combine them into a single code block or shell invocation.
diff --git a/skills/ppt-master/references/image-base.md b/skills/ppt-master/references/image-base.md
index 4944d703..74534b53 100644
--- a/skills/ppt-master/references/image-base.md
+++ b/skills/ppt-master/references/image-base.md
@@ -75,7 +75,7 @@ After all rows reach terminal status:
1. Try once
2. On recoverable failure (network, no candidates, license rejection, rate limit), retry once with broadened parameters
3. On second failure, set `Status: Needs-Manual`, log the reason in conversation, continue
-4. After the phase completes, summarize all `Needs-Manual` rows for the user — list filenames, where prompts live (`images/image_prompts.json` `items[].prompt` for ai rows), and where to place generated files (`project/images/<filename>`)
+4. After the phase completes, summarize all `Needs-Manual` rows for the user — list filenames, where prompts live (`images/image_prompts.md` paste-ready blocks for ai rows; refresh via `image_gen.py --render-md` if stale), and where to place generated files (`project/images/<filename>`)
`Needs-Manual` is also the entry status for **Offline Manual Mode** (no `IMAGE_BACKEND` configured, no host-native image tool in use). Affected ai rows are marked `Needs-Manual` from the start without a failed attempt — see [`image-generator.md`](./image-generator.md) §3.2.
diff --git a/skills/ppt-master/references/image-generator.md b/skills/ppt-master/references/image-generator.md
index 38540906..f3d54595 100644
--- a/skills/ppt-master/references/image-generator.md
+++ b/skills/ppt-master/references/image-generator.md
@@ -186,8 +186,11 @@ For each image with `Acquire Via: ai` and `Status: Pending`:
4. **Apply type-specific key points** → Reference §2's table for that type
5. **Generate optimized prompt** → §1.1 schema; prepend the §1.6 Deck Style Anchor
6. **Save manifest** → **Must** write to `project/images/image_prompts.json` with `status: "Pending"` for every new entry
+7. **Render Markdown sidecar** → **Must** run `python3 scripts/image_gen.py --render-md project/images/image_prompts.json` to produce the read-only `image_prompts.md` view
-> The manifest is machine-consumed by `image_gen.py --manifest`. The `prompt` field of each entry doubles as a paste-ready string for the Offline Manual handoff (§3.2).
+**Hard rule**: `image_prompts.md` is auto-generated. Never hand-edit it — re-run `--render-md` (or `--manifest`, which re-renders on completion) to refresh.
+
+> The JSON manifest is machine-consumed by `image_gen.py --manifest`. The Markdown sidecar is the human-readable / paste-ready fallback used in Offline Manual Mode (§3.2).
### 3.2 Image Generation Phase
@@ -267,6 +270,7 @@ Precedence:
- Default 3 concurrent requests, halves on the first rate-limit response, minimum 1 (= serial fallback)
- Rate-limited items requeue automatically; per-item failures are recorded with `last_error` and skipped
- Interrupting mid-run is safe — completed items keep `status: Generated` and are skipped on re-run
+- On normal completion the Markdown sidecar is re-rendered automatically; if the run is interrupted, run `--render-md` manually to refresh the sidecar
#### Path B — Host-Native Image Tool (On Explicit User Request)
@@ -288,7 +292,7 @@ Triggered only when the user explicitly asks the skill to use the host's built-i
3. Continue to Step 6 — SVG references `images/<filename>` optimistically; Step 7 entry verifies presence
4. Print one consolidated handoff to the user:
- Filenames awaiting manual generation
- - Pointer to `images/image_prompts.json`: each `items[].prompt` is paste-ready for ChatGPT / Gemini / Midjourney
+ - Pointer to `images/image_prompts.md` (paste-ready `### Image N:` block per item) or `image_prompts.json` (`items[].prompt`)
- Target placement: `project/images/<filename>` matching the resource list exactly
- Resume command: re-run Step 7 once all expected files exist
diff --git a/skills/ppt-master/scripts/image_gen.py b/skills/ppt-master/scripts/image_gen.py
index 4e407f59..dd928925 100644
--- a/skills/ppt-master/scripts/image_gen.py
+++ b/skills/ppt-master/scripts/image_gen.py
@@ -541,6 +541,90 @@ def _resolve_concurrency(cli_value: int | None) -> int:
return DEFAULT_MANIFEST_CONCURRENCY
+def render_manifest_md(manifest: dict) -> str:
+ """Render a manifest into the paste-ready Markdown view.
+
+ The output is a read-only snapshot of the JSON manifest, intended as a
+ fallback so a user can copy `Prompt` blocks into ChatGPT / Midjourney
+ when `--manifest` cannot run (no key, no backend, network down).
+ """
+ lines: list[str] = []
+ lines.append("# Image Generation Prompts")
+ lines.append("")
+ lines.append("> Auto-generated from `image_prompts.json` by `image_gen.py --render-md`.")
+ lines.append("> Do not hand-edit — re-run the command to refresh.")
+ lines.append("")
+
+ project = manifest.get("project")
+ generated_at = manifest.get("generated_at")
+ color_scheme = manifest.get("color_scheme") or {}
+ anchor = manifest.get("deck_style_anchor")
+
+ if project:
+ lines.append(f"> Project: {project}")
+ if generated_at:
+ lines.append(f"> Generated: {generated_at}")
+ if color_scheme:
+ cs = " | ".join(
+ f"{k.capitalize()} {v}" for k, v in color_scheme.items()
+ )
+ lines.append(f"> Color scheme: {cs}")
+ if anchor:
+ lines.append(f"> Deck Style Anchor: {anchor}")
+ lines.append("")
+ lines.append("---")
+ lines.append("")
+
+ for i, item in enumerate(manifest["items"], start=1):
+ lines.append(f"### Image {i}: {item['filename']}")
+ lines.append("")
+ lines.append("| Attribute | Value |")
+ lines.append("|---|---|")
+ for label, key in (
+ ("Purpose", "purpose"),
+ ("Type", "type"),
+ ("Aspect ratio", "aspect_ratio"),
+ ("Image size", "image_size"),
+ ("Status", "status"),
+ ):
+ value = item.get(key)
+ if value:
+ lines.append(f"| {label} | {value} |")
+ if item.get("last_error"):
+ lines.append(f"| Last error | {item['last_error']} |")
+ lines.append("")
+ lines.append("**Prompt**:")
+ lines.append("")
+ lines.append(item["prompt"])
+ lines.append("")
+ if item.get("negative_prompt"):
+ lines.append("**Negative Prompt**:")
+ lines.append("")
+ lines.append(item["negative_prompt"])
+ lines.append("")
+ if item.get("alt_text"):
+ lines.append("**Alt Text**:")
+ lines.append(f"> {item['alt_text']}")
+ lines.append("")
+ lines.append("---")
+ lines.append("")
+
+ return "\n".join(lines).rstrip() + "\n"
+
+
+def render_manifest_md_to_file(manifest_path: str, manifest: dict | None = None) -> str:
+ """Render the manifest's Markdown sidecar next to the JSON file.
+
+ Returns the written path. If `manifest` is omitted, it is loaded from
+ `manifest_path` first.
+ """
+ if manifest is None:
+ manifest = load_manifest(manifest_path)
+ md_path = str(Path(manifest_path).with_suffix(".md"))
+ Path(md_path).write_text(render_manifest_md(manifest), encoding="utf-8")
+ return md_path
+
+
def main() -> None:
"""Run the CLI entry point."""
parser = argparse.ArgumentParser(
@@ -593,6 +677,13 @@ def main() -> None:
"Auto-halves on rate-limit; 1 is the serial fallback."
),
)
+ parser.add_argument(
+ "--render-md", dest="render_md", default=None, metavar="IMAGE_PROMPTS_JSON",
+ help=(
+ "Render <json>'s read-only Markdown sidecar (image_prompts.md) "
+ "next to the manifest, then exit. No backend / network needed."
+ ),
+ )
args = parser.parse_args()
@@ -600,6 +691,19 @@ def main() -> None:
_print_backend_list()
return
+ if args.render_md:
+ if not os.path.isfile(args.render_md):
+ print(f"Error: manifest file not found: {args.render_md}")
+ sys.exit(1)
+ try:
+ manifest = load_manifest(args.render_md)
+ except ValueError as e:
+ print(f"Error: {e}")
+ sys.exit(1)
+ md_path = render_manifest_md_to_file(args.render_md, manifest)
+ print(f"Rendered Markdown sidecar: {md_path}")
+ return
+
try:
_load_image_env_file()
_validate_runtime_config()
@@ -636,6 +740,8 @@ def main() -> None:
except KeyboardInterrupt:
print("\n\nInterrupted by user. Partial progress preserved in manifest.")
sys.exit(130)
+ md_path = render_manifest_md_to_file(args.manifest, manifest)
+ print(f"Rendered Markdown sidecar: {md_path}")
sys.exit(1 if failed else 0)
try: