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-search): add isolated thumbnail review
hugohe3452babbd98d5
diff --git a/skills/ppt-master/references/image-searcher.md b/skills/ppt-master/references/image-searcher.mdindex 1f03cb4a..ba638865 100644--- a/skills/ppt-master/references/image-searcher.md+++ b/skills/ppt-master/references/image-searcher.md@@ -192,16 +192,10 @@ Do not tune this into a visual taste engine. The scorer removes obvious metadataA metadata-ranked top hit is *downloadable and token-relevant*, not necessarily *visually suitable* — `score_candidate` never sees pixels. Review it against the active Reference and Crop Policy before it is trusted:-- **Multimodal model**: run `--save-candidates`. The tool aggregates explicit query variants, deduplicates them, and saves at most the first **8** ranked previews under `candidates/<stem>/review/`; `review_sheet.jpg` contains only that page and no original is downloaded. Use the sheet for triage, then open an individual `review/candidate_NN.jpg` when exact identity or fine detail is uncertain. Only after one candidate passes should `--promote` download that original. If `has_more_candidates` is true and none passes, fetch `--candidate-page 2` before changing the query.+- **Multimodal review available**: run `--save-candidates`. The tool aggregates explicit query variants, deduplicates them, and saves at most the first **8** ranked previews under `candidates/<stem>/review/`; `review_sheet.jpg` contains only that page and no original is downloaded. Run [`web-image-review.md`](../workflows/stages/web-image-review.md): use one isolated vision reviewer for the current batch when available, otherwise review locally. Only the active image owner may use the returned candidate filename with `--promote`. If `has_more_candidates` is true and none passes, fetch `--candidate-page 2` before changing the query.- **Non-multimodal model (no vision)**: omit `--save-candidates`; the tool excludes every `visual-verification-required` near match, downloads only the first candidate that passes all strict metadata / license / dimension gates, and records `selection_method: metadata-ranked`. Do **not** describe this as visual confirmation. If no strict candidate exists, or the active Reference requires a viewpoint, crop, expression, or fine identity detail that metadata cannot establish, mark the row `Needs-Manual`; Quick does not open an acquisition-time interaction.-Apply this order during multimodal selection:--1. pre-selection hard gates — allowed license, exact subject/identity, readable preview, and upstream dimensions when known;-2. page fit — requested orientation, focal placement, crop safety, and usable quiet region;-3. expression fit — the Reference's requested view, action, and mood;-4. tie-breakers — higher expected usable resolution / lower crop loss, then no-attribution;-5. post-selection hard gate — download only the winner and verify its actual readable dimensions before provenance is committed.+The review stage owns pixel-inspection gates, bounded detail reads, and the compact decision receipt. It receives only the locked row intent plus candidate sidecars/sheets; it never receives the full planning or acquisition context.If no thumbnail on the current page passes, download no original. When`has_more_candidates` is true, advance to `next_candidate_page` first. Only@@ -216,7 +210,7 @@ Never treat a generic `required_terms` pass as acceptance. For example, matching**Replacement ladder when the first round is not right**:-1. With vision, promote one passing thumbnail from the current page; this is the first original-image request.+1. With vision, promote the one passing thumbnail selected under the review-stage contract; this is the first original-image request.2. If none passes and `has_more_candidates` is true, fetch the next ranked page (8 by default). Candidate numbers continue globally, so page 2 starts at `candidate_09`; do not repeat page 1 or download an original.3. After the current pool is exhausted, add materially different query variants for identity wording, official translation, alias, viewpoint, or disambiguation and generate a fresh pool; do not repeat a semantically exhausted query.4. **manual URL replace (universal, model-agnostic)** — use a user-supplied URL and swap it in:@@ -233,8 +227,6 @@ Never treat a generic `required_terms` pass as acceptance. For example, matching([`executor-web-image.md`](./executor-web-image.md) §1);5. When the query variants, ranked pages, configured provider chain, and permitted license stages are exhausted and no user-confirmed manual URL is available, mark the row `Needs-Manual`.-Web search is far cheaper than AI generation, so this review pass is well worth it.-**This review never opens an acquisition-time interaction** ([`image-base.md`](./image-base.md) §6). Default Generate may build a placeholder and continue to Step 6. Quick Generate finishes all permitted automated strategies, records `Needs-Manual`, and blocks direct export when the unresolved image is required.### Visual selection candidates (multimodal Generate; standalone opt-in)diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.mdindex 80d8d7c2..e2685c18 100644--- a/skills/ppt-master/references/strategist.md+++ b/skills/ppt-master/references/strategist.md@@ -279,13 +279,15 @@ owns SVG authoring under [`native-hyperlinks.md`](./native-hyperlinks.md).|---|---|---|| `none` | No images | Data reports or process documentation whose visual burden is fully served by charts / native SVG || `provided` | User-provided assets | Existing images carry factual, brand, product, or narrative authority |-| `ai` | AI-generated | Custom illustrations, backgrounds, metaphors, or a coherent spot family are needed |-| `web` | Web-sourced | Real-world editorial or stock-style reference imagery is needed |+| `ai` | AI-generated | Invented or deliberately stylized illustrations, backgrounds, metaphors, or a coherent spot family are needed |+| `web` | Web-sourced | A named or evidence-bearing real-world subject must appear as itself || `placeholder` | Deferred | The image is required but will be supplied later |**Current inventory**: If `images/` is non-empty, run `python3 scripts/analyze_images.py <project_path>/images` and read `analysis/image_analysis.csv` before recommending a source. Re-run after that folder changes.-**Recommendation output**: Write `recommend.image_usage` as one source id or an array for mixed sources. Put page roles, authoritative assets, preferred/avoided imagery, and placeholder tolerance in `image_notes.value`. `none` is exclusive. Human-scale topics such as family life, education, wellness, or children lean `ai` when no supplied asset carries the story; regulated investor decks, B2B finance reports, and data-only dashboards remain eligible for `none` by judgment.+**Default — evidence before synthesis (may override when explicit source constraints or the communication intent require another permitted source)**: Prefer `provided` when supplied assets already carry authority. Propose `web` when the actual appearance of an externally verifiable subject is material; propose `ai` when custom expression matters more than documentary identity. Mixed sources may serve different page roles. This is a source-fit decision, not an image quota.++**Recommendation output**: Write `recommend.image_usage` as one source id or an array for mixed sources. Put page roles, authoritative assets, preferred/avoided imagery, and placeholder tolerance in `image_notes.value`. `none` is exclusive. Generic human-scale topics such as family life, education, wellness, or children lean `ai` when no supplied asset carries the story; regulated investor decks, B2B finance reports, and data-only dashboards remain eligible for `none` by judgment.**Confirmed value wins**: Accept the confirmed legacy string or multi-select array. Map `ai→ai`, `web→web`, `provided→user`, and `placeholder→placeholder` into §VIII `Acquire Via`. Every direction already carries a rendering candidate whether or not AI is proposed; generated images inherit the deck colors and never introduce a second image-palette choice.diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.jsonindex c6e0a4b9..a08e2fc7 100644--- a/skills/ppt-master/scripts/prompt_audit_manifest.json+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json@@ -362,6 +362,7 @@"include": ["route.generate.quick-generate","stage.generate.image.web",+ "stage.generate.image.web-review","stage.generate.executor.web-image"],"files": [],@@ -602,7 +603,8 @@"stage.generate.executor.flat","stage.generate.executor.web-image","stage.generate.executor.notes",- "stage.generate.image.web"+ "stage.generate.image.web",+ "stage.generate.image.web-review"],"files": [],"max_tokens": 190000@@ -801,6 +803,14 @@],"max_tokens": 11000},+ "stage.generate.image.web-review": {+ "description": "Compact isolated-or-local multimodal review contract for bounded web-image thumbnail pages.",+ "scope": "incremental",+ "files": [+ "skills/ppt-master/workflows/stages/web-image-review.md"+ ],+ "max_tokens": 1000+ },"stage.generate.resume-execute": {"description": "Fresh-session resume plus the flat Executor core and post-SVG notes rules.","scope": "fresh-session",diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.mdindex ae46c003..8b2ee200 100644--- a/skills/ppt-master/workflows/generate-pptx.md+++ b/skills/ppt-master/workflows/generate-pptx.md@@ -518,7 +518,7 @@ A deck with only `ai` rows never loads `image-searcher.md`; a deck with only `we> ⚠️ **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.-> **Default — bounded multimodal web thumbnail selection**: when the current agent can inspect images, add `--save-candidates` to the single or batch web command. Author explicit `query_variants` for materially different official translations, spellings, aliases, or Chinese names; the tool aggregates and deduplicates them, then saves only the first ranked page (8 previews by default), writes `candidates/<stem>/review_sheet.jpg`, marks the batch row `Needs-Selection`, and downloads no original. Review the sheet against the locked Reference/Crop Policy; only a passing `--promote` choice may download one original and write provenance (pass the same `--batch images/image_queries.json` to reconcile its row to `Sourced`). If none passes and `has_more_candidates` is true, advance that row to `next_candidate_page` before changing the query. Only after the pool is exhausted may the row receive materially different query variants and return to `Pending`. A non-multimodal agent omits `--save-candidates`: best-only mode may download only a strict metadata-verified candidate, records `selection_method: metadata-ranked`, and otherwise stops at `Needs-Manual` without claiming visual confirmation.+> **Default — bounded multimodal web thumbnail selection**: when either the current agent or an available isolated reviewer can inspect images, add `--save-candidates` to the single or batch web command. Author explicit `query_variants` for materially different official translations, spellings, aliases, or Chinese names; the tool aggregates and deduplicates them, then saves only the first ranked page (8 previews by default), writes `candidates/<stem>/review_sheet.jpg`, marks the batch row `Needs-Selection`, and downloads no original. Run [`web-image-review`](stages/web-image-review.md): dispatch exactly one isolated reviewer for all current sheets when supported, passing only each row's locked Reference/Crop Policy plus candidate sidecar/sheet paths; otherwise the active image owner reads that stage and reviews locally. Only a stage-selected passing candidate may be used with `--promote` to download one original and write provenance (pass the same `--batch images/image_queries.json` to reconcile its row to `Sourced`). If none passes and `has_more_candidates` is true, advance that row to `next_candidate_page` before changing the query. Only after the pool is exhausted may the row receive materially different query variants and return to `Pending`. When no available context has vision, omit `--save-candidates`: best-only mode may download only a strict metadata-verified candidate, records `selection_method: metadata-ranked`, and otherwise stops at `Needs-Manual` without claiming visual confirmation.> **Default — short provider query (may override for a complete entity name or necessary disambiguation)**: keep §VIII `Reference` as the locked subject/focal/crop intent and author a separate concrete `image_queries.json.query`. Search/review never rewrites the Design Spec or lock to fit a candidate.diff --git a/skills/ppt-master/workflows/stages/web-image-review.md b/skills/ppt-master/workflows/stages/web-image-review.mdnew file mode 100644index 00000000..de9a6616--- /dev/null+++ b/skills/ppt-master/workflows/stages/web-image-review.md@@ -0,0 +1,87 @@+---+description: Conditional isolated multimodal review of bounded web-image thumbnail pages.+---++# Web Image Review Stage++> Supporting Generate stage for choosing from thumbnail pages already prepared+> by the web-image acquisition path. It reviews pixels only: it never searches,+> downloads, changes the locked image intent, or writes project artifacts.++## When to Run++| Review capability | Action |+|---|---|+| An isolated worker can inspect the declared local images | Dispatch exactly one reviewer for all pending sheets in the current acquisition batch |+| Only the active image owner can inspect images | Read this stage and review the same batch locally |+| No available context can inspect images | Skip this stage and use the strict metadata-only acquisition path |++Run after `--save-candidates` has produced `Needs-Selection` rows and before any+`--promote` command. When the host supports follow-up messages, reuse the same+reviewer for later candidate pages in that acquisition run; never dispatch one+reviewer per resource row.++---++## Execution Context++**Default — isolate thumbnail pixels when available**: The active image owner+retains query, search, pagination, promotion, status, and provenance ownership.+Supply the reviewer only this stage's absolute path and these per-row records:++| Input | Required value |+|---|---|+| Row identity | Resource filename or stable batch-row identifier |+| Acceptance intent | Exact locked `Reference` and `Crop Policy` |+| Candidate state | Current page, `has_more_candidates`, and `next_candidate_page` when present |+| Local evidence | Absolute `review_sheet.jpg` and `candidates.json` paths |++The isolated reviewer reads this file completely, then inspects only the+declared sidecars and review images. It does not read `image-base.md`,+`image-searcher.md`, the Design Spec, the lock, or source files. It runs no+network request, command, or project write. If any declared path is unreadable+or image inspection is unavailable, return `blocked` with the exact reason.++---++## Review Contract++Apply the gates in order for every row:++| Order | Gate |+|---:|---|+| 1 | Reject a candidate unless its `license_tier` is `no-attribution` or `attribution-required`; also reject unreadable previews or known dimensions that cannot serve the planned placement |+| 2 | Confirm the exact subject or identity; `visual-verification-required` passes only when the pixels establish the missing identity evidence |+| 3 | Check orientation, focal placement, crop safety, and usable quiet region against the locked intent |+| 4 | Check the requested view, action, and mood |+| 5 | Among passing candidates, prefer lower expected crop loss and higher usable resolution, then no-attribution |++**Mandatory — bounded detail inspection**: Triage with `review_sheet.jpg`.+Open an individual `review/candidate_NN.jpg` only when exact identity or a fine+detail cannot be resolved from the sheet; never bulk-open every candidate.++**Hard rule — no least-bad promotion**: Select only a candidate that passes all+applicable gates. When none passes, return `no-pass`; do not weaken the locked+Reference or Crop Policy.++---++## Receipt and Hand-off++Return one compact table and no embedded images:++```markdown+| row | decision | candidate | reason | next |+|---|---|---|---|---|+| <id> | selected / no-pass / blocked | candidate_NN.jpg / — | <short evidence> | promote / next-page / pool-exhausted / repair-input |+```++For `selected`, name exactly one candidate from that row's current page. For+`no-pass`, use `next-page` when `has_more_candidates` is true; otherwise use+`pool-exhausted`. Keep the entire chat receipt under 200 words.++The active image owner validates every selected filename against+`candidates.json`, runs `--promote`, and verifies the downloaded original's+readable dimensions and provenance. A no-pass row advances to the next ranked+page before query replacement. An invalid receipt returns to the same reviewer+for correction; it never authorizes an arbitrary promotion.