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

docs(image-search): refine web image prompt rules

hugohe3a7f84a76f852
diff --git a/skills/ppt-master/references/image-searcher.md b/skills/ppt-master/references/image-searcher.md
index 2dcfc5da..214cac54 100644
--- a/skills/ppt-master/references/image-searcher.md
+++ b/skills/ppt-master/references/image-searcher.md
@@ -68,17 +68,29 @@ Web image APIs match keywords against image metadata, not semantic embeddings. `
1. Strips HEX color codes (`#1E3A5F`) and parentheticals (`(corporate vibe)`)
2. Drops hard-noise words: brand names, generic filler
-3. Drops soft-noise words (`ai`, `tech`, `platform`, `system`, `digital`) — only when concrete nouns remain
+3. Drops soft-noise words (`ai`, `tech`, `platform`, `professional`, `editorial`, `photo`, `background`) — only when concrete nouns remain
4. Caps at 4 words
5. **Fail-open**: if filtering empties the query, return the original
Then `build_query_progression` tries: original → simplified (4 words) → simplified (3 words). First non-empty hit wins.
+**Per-row web Reference grammar**:
+
+| Segment | Rule |
+|---|---|
+| Subject | Put the concrete subject/place/object first: `offshore wind farm`, `Xiamen skyline`, `boardroom meeting` |
+| Quality cues | Add 1-3 cues after the subject: `professional editorial photography`, `clean composition`, `natural light`, `high-resolution` |
+| Language | Use official Chinese names for China-specific landmarks; use English nouns for generic stock concepts |
+
+**Forbidden — web negative prompts**: `not tourist snapshot`, `no amateur photo`, `avoid low quality`.
+
+> Note: Keyword APIs search negative words literally.
+
| ✅ Good Reference (intent) | ❌ Avoid |
|---|---|
-| "Aerial view of offshore wind farm at dusk" | "aerial offshore wind 4 keywords" (already keyword-shaped) |
-| "Diverse engineering team collaborating around a laptop" | "use Openverse, search 'team'" (provider mechanics) |
-| "Sunlit forest path in autumn" | "Hero image, dramatic lighting" (composition jargon, no subject) |
+| "Offshore wind farm at dusk, aerial view, professional editorial photography" | "professional editorial photography background" |
+| "Diverse engineering team collaborating around a laptop, modern office, natural light" | "use Openverse, search 'team'" |
+| "Sunlit forest path in autumn, clean composition, high-resolution photography" | "Hero image, dramatic lighting" |
---
diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.md
index 9296a418..50401b05 100644
--- a/skills/ppt-master/references/strategist.md
+++ b/skills/ppt-master/references/strategist.md
@@ -206,24 +206,37 @@ Selections may be mixed at the row level — e.g. a deck can use C for hero illu
| Status | Initial status must be `Pending`, `Existing`, or `Placeholder`; see [`svg-image-embedding.md`](svg-image-embedding.md) for the full status enum |
| **Reference** | Free-form **intent description** (NOT a search query); feeds Image_Generator (ai) or Image_Searcher (web) |
-**Reference field — write intent, not mechanics**:
+**Reference field**: Write visual intent, not provider mechanics.
-This field is consumed by either Image_Generator (which expands it into an AI prompt) or Image_Searcher (which simplifies it into 2–5 keywords). The Strategist's job is to describe the **visual intent**:
+| ✅ Intent description | ❌ Avoid |
+|---|---|
+| "Diverse engineering team collaborating around a laptop, modern office, natural light" | "team laptop office" |
+| "Abstract flowing digital waves in deep navy (#1E3A5F) to midnight blue gradient, subtle particle effects, clean center area for text overlay" | "use openverse, search 'office'" |
+| "Sunlit forest path in autumn" | "team photo" |
-- ✅ "Diverse engineering team collaborating around a laptop, modern office, natural light"
-- ✅ "Abstract flowing digital waves in deep navy (#1E3A5F) to midnight blue gradient, subtle particle effects, clean center area for text overlay"
-- ✅ "Sunlit forest path in autumn"
-- ❌ "team laptop office" (already keyword-shaped — let Image_Searcher do that)
-- ❌ "use openverse, search 'office'" (provider mechanics are not a Strategist concern)
-- ❌ "team photo" (too thin)
+**Per-row Reference grammar**:
-For `ai` rows, include subject + style + colors (HEX) + composition. For `web` rows, prioritize concrete nouns and visual descriptors — but you can still write the description naturally; `simplify_query` strips noise words automatically.
+| Acquire Via | Reference pattern |
+|---|---|
+| `ai` | Subject + style + colors (HEX) + composition |
+| `web` | Concrete subject/place/object first, then 1-3 quality descriptors |
-| Good examples (work for both ai and web) |
-|---------------|
-| "Professional team of 4 diverse people collaborating at a modern office desk, natural lighting, laptop visible" |
-| "Abstract flowing digital waves in deep navy (#1E3A5F) to midnight blue gradient, subtle particle effects, clean center area for text overlay" |
-| "Clean flowchart showing 4 sequential steps connected by arrows, flat design, light gray background, blue accent nodes" |
+**Allowed web quality descriptors**:
+
+| Descriptor | Use |
+|---|---|
+| `professional editorial photography` | Stock-style photography |
+| `clean composition` | Covers, section dividers, image-text layouts |
+| `natural light` | People, workplace, travel, lifestyle scenes |
+| `high-resolution` | Large visual areas |
+
+**Forbidden — web negative prompts**: `not tourist snapshot`, `no phone photo`, `avoid amateur style`.
+
+| Mode | Good Reference |
+|---|---|
+| `web` | "Diverse team collaborating at a modern office desk, professional editorial photography, natural light, laptop visible" |
+| `ai` | "Abstract flowing digital waves in deep navy (#1E3A5F) to midnight blue gradient, subtle particle effects, clean center area for text overlay" |
+| `ai` | "Clean flowchart showing 4 sequential steps connected by arrows, flat design, light gray background, blue accent nodes" |
**Image type descriptions**:
diff --git a/skills/ppt-master/scripts/docs/image.md b/skills/ppt-master/scripts/docs/image.md
index 0cc71508..105e9932 100644
--- a/skills/ppt-master/scripts/docs/image.md
+++ b/skills/ppt-master/scripts/docs/image.md
@@ -105,6 +105,14 @@ Providers (Openverse and Wikimedia work with no key; Pexels and Pixabay are opti
Default search chain (when `--provider` is unset): zero-config providers first, then keyed providers whose API key is set in the environment. Keyed providers without a key are silently skipped.
+Query guidance:
+
+| Case | Pattern |
+|---|---|
+| Generic stock concept | `boardroom meeting, professional editorial photography, natural light` |
+| China-specific landmark | Official Chinese place name + concrete scene |
+| Avoid | Negative prompt wording such as `not tourist snapshot` |
+
License filter:
- **Default**: search all providers with `cc0,pdm,pexels,pixabay,cc by,cc by-sa` allowed together. The chosen image may be `no-attribution` or `attribution-required`; Executor adds an inline credit only when needed.
diff --git a/skills/ppt-master/scripts/image_sources/provider_common.py b/skills/ppt-master/scripts/image_sources/provider_common.py
index f79d0875..bb879d69 100644
--- a/skills/ppt-master/scripts/image_sources/provider_common.py
+++ b/skills/ppt-master/scripts/image_sources/provider_common.py
@@ -246,8 +246,18 @@ _SOFT_NOISE_WORDS = frozenset({
"ai", "code", "software", "system", "digital", "platform", "solution",
"application", "interface", "framework", "algorithm", "api", "sdk",
"assistant", "tool", "service", "technology", "tech", "program",
+ # Visual-quality / usage terms. These are helpful in the full provider
+ # query, but should not consume the 3-4 keyword fallback budget or
+ # dominate relevance scoring over the real subject.
+ "professional", "editorial", "commercial", "premium", "stock",
+ "photo", "photograph", "photography", "image", "picture", "visual",
+ "background", "hero", "cover", "banner", "wallpaper",
+ "high", "quality", "resolution", "sharp", "clean", "cinematic",
+ "dramatic", "lighting", "light", "modern", "natural", "visible",
})
+_TOKEN_STRIP_CHARS = ".,;:!?\"'()[]{},。;:!?、"
+
def simplify_query(query: str, max_words: int = 4) -> str:
"""Trim a verbose query into a short keyword phrase.
@@ -262,7 +272,8 @@ def simplify_query(query: str, max_words: int = 4) -> str:
"""
cleaned = re.sub(r"#[0-9a-fA-F]{3,8}", "", query)
cleaned = re.sub(r"\([^)]*\)", "", cleaned)
- words = [w for w in cleaned.split() if len(w) > 2]
+ words = [w.strip(_TOKEN_STRIP_CHARS) for w in cleaned.split()]
+ words = [w for w in words if len(w) > 2]
after_hard = [w for w in words if w.lower() not in _NOISE_WORDS]
after_soft = [w for w in after_hard if w.lower() not in _SOFT_NOISE_WORDS]
@@ -321,7 +332,8 @@ def _query_tokens(query: str) -> list[str]:
"""
cleaned = re.sub(r"#[0-9a-fA-F]{3,8}", "", query.lower())
cleaned = re.sub(r"\([^)]*\)", "", cleaned)
- words = [w for w in cleaned.split() if len(w) > 2 and w.isascii()]
+ words = [w.strip(_TOKEN_STRIP_CHARS) for w in cleaned.split()]
+ words = [w for w in words if len(w) > 2 and w.isascii()]
if not words:
return []
after_hard = [w for w in words if w not in _NOISE_WORDS]