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-search): add isolated thumbnail review

hugohe3452babbd98d5
diff --git a/skills/ppt-master/references/image-searcher.md b/skills/ppt-master/references/image-searcher.md
index 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 metadata
A 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.md
index 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.json
index 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.md
index 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.md
new file mode 100644
index 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.