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: surface the web image search path in user-facing docs
hugohe3a14d3b89a1cd
diff --git a/.env.example b/.env.exampleindex dac130da..770e97f1 100644--- a/.env.example+++ b/.env.example@@ -126,3 +126,17 @@## Switch providers by changing IMAGE_BACKEND only.# 切换提供商时,只改 IMAGE_BACKEND 即可。++# ─────────────────────────────────────────────────────────────+# Web image search (image_search.py) / 网络图片搜索+# ─────────────────────────────────────────────────────────────+# Used by scripts/image_search.py — separate from IMAGE_BACKEND above.+# image_search.py 用,与上面的 IMAGE_BACKEND 互不影响。+#+# Openverse and Wikimedia work with no key. Pexels and Pixabay are+# OPTIONAL — set their key only if you want to broaden the provider chain.+# Openverse 和 Wikimedia 无需 Key。Pexels / Pixabay 可选,仅在希望扩展+# provider 范围时配置。+#+# PEXELS_API_KEY=your-pexels-key # signup: https://www.pexels.com/api/+# PIXABAY_API_KEY=your-pixabay-key # signup: https://pixabay.com/api/docs/diff --git a/README.md b/README.mdindex 43da57a8..7acc2098 100644--- a/README.md+++ b/README.md@@ -213,21 +213,15 @@ The AI handles everything — content analysis, visual design, SVG generation, a> **Something went wrong?** Check the **[FAQ](./docs/faq.md)** — it covers model selection, layout issues, export problems, and more. Continuously updated from real user reports.-### 5. AI Image Generation (Optional)+### 5. Image Acquisition (Optional)-```bash-cp .env.example .env # then edit with your API key-```+Two paths for non-user images, mixable per row in the same deck:-```env-IMAGE_BACKEND=openai # required — must be set explicitly-OPENAI_API_KEY=sk-xxx-OPENAI_MODEL=gpt-image-2-```+**A) AI generation** — `image_gen.py`. Copy `.env.example` to `.env`, set `IMAGE_BACKEND` plus the provider's `*_API_KEY` (`OPENAI_API_KEY`, `GEMINI_API_KEY`, etc.), and the pipeline calls it automatically. Run `python3 skills/ppt-master/scripts/image_gen.py --list-backends` for the full backend list. `gpt-image-2` is currently the best default.-Multiple backends are supported across Core / Extended / Experimental tiers. Run `python3 skills/ppt-master/scripts/image_gen.py --list-backends` to see the full list. Environment variables override `.env`. Use provider-specific keys (`OPENAI_API_KEY`, `GEMINI_API_KEY`, etc.) — global `IMAGE_API_KEY` is not supported.+**B) Web image search** — `image_search.py`. **Zero-config**, no API key. Searches openly-licensed images across Openverse and Wikimedia Commons; defaults to CC0 / Public Domain so the deck stays clean. Falls back to CC BY / CC BY-SA only when nothing in the public domain matches — Executor then adds a small inline credit on those slides. Optional `PEXELS_API_KEY` / `PIXABAY_API_KEY` (both free) broaden the chain.-> **Tip:** `gpt-image-2` currently delivers the best overall quality. Gemini is also supported — download full size and remove the watermark with `scripts/gemini_watermark_remover.py`.+> Full reference: [`image-generator.md`](./skills/ppt-master/references/image-generator.md) (AI) · [`image-searcher.md`](./skills/ppt-master/references/image-searcher.md) (web).---diff --git a/README_CN.md b/README_CN.mdindex 2e26b046..14e059df 100644--- a/README_CN.md+++ b/README_CN.md@@ -217,21 +217,15 @@ AI 全程处理——内容分析、视觉设计、SVG 生成、PPTX 导出。> **遇到问题?** 查看 **[常见问题](./docs/zh/faq.md)** — 涵盖模型选择、排版问题、导出异常等,基于真实用户反馈持续更新。-### 5. AI 生图配置(可选)+### 5. 图片获取(可选)-```bash-cp .env.example .env # 然后填入你的 API Key-```+非用户自带图片有两条路径,可在同一份 deck 里按行混用:-```env-IMAGE_BACKEND=openai # 必填——必须显式指定-OPENAI_API_KEY=sk-xxx-OPENAI_MODEL=gpt-image-2-```+**A) AI 生图** — `image_gen.py`。`cp .env.example .env`,设置 `IMAGE_BACKEND` 和对应 `*_API_KEY`(`OPENAI_API_KEY`、`GEMINI_API_KEY` 等),流程会自动调用。`python3 skills/ppt-master/scripts/image_gen.py --list-backends` 查看完整后端清单。`gpt-image-2` 目前综合质量最佳。-支持多家后端,按 Core / Extended / Experimental 分级。运行 `python3 skills/ppt-master/scripts/image_gen.py --list-backends` 查看完整清单。环境变量优先于 `.env`。使用各家独立的 Key(`OPENAI_API_KEY`、`GEMINI_API_KEY` 等)——不支持全局 `IMAGE_API_KEY`。+**B) 网络图片搜索** — `image_search.py`。**零配置**、无需 API Key。在 Openverse 和 Wikimedia Commons 中搜索开放许可可商用图片;默认只搜 CC0 / 公有领域以保持视觉干净。只有公有领域找不到合适图时才回落到 CC BY / CC BY-SA,并由 Executor 在该幻灯片自动添加小字署名。可选的 `PEXELS_API_KEY` / `PIXABAY_API_KEY`(都免费申请)能扩展搜索范围。-> **建议:** `gpt-image-2` 目前综合质量最佳。Gemini 同样支持——下载 full size 后可用 `scripts/gemini_watermark_remover.py` 去水印。+> 完整说明:[`image-generator.md`](./skills/ppt-master/references/image-generator.md)(AI)·[`image-searcher.md`](./skills/ppt-master/references/image-searcher.md)(网络)。---diff --git a/docs/faq.md b/docs/faq.mdindex aa4e9f08..a0861d6b 100644--- a/docs/faq.md+++ b/docs/faq.md@@ -30,6 +30,12 @@ PPT Master works with any AI coding agent that can read files and run shell commYes. PPT Master includes a built-in image generation script that supports multiple providers (Gemini, OpenAI, FLUX, Qwen, Zhipu, etc.). During the Strategist phase, if you choose "AI generation" for the image approach, the pipeline will automatically generate images based on your content. You can also provide your own images — just place them in the project's `images/` folder.+## Q: I don't have an image-generation API key — can I still get images?++Yes — pick "Web-sourced" in the Strategist's Image Usage step. PPT Master ships a zero-config `image_search.py` that searches openly-licensed images across Openverse and Wikimedia Commons (no API key needed). It defaults to CC0 / Public Domain so the deck stays visually clean, and only falls back to CC BY / CC BY-SA when no public-domain match exists — in which case the Executor adds a small inline credit on the affected slide.++You can mix the two paths in one deck (e.g. AI for hero illustrations, web for team photos). For better contemporary stock photography, set `PEXELS_API_KEY` or `PIXABAY_API_KEY` in `.env` (both are free) and the search will include them automatically.+## Q: Can I edit the generated presentations?Yes. The main `.pptx` (native PowerPoint shapes — all text, graphics, and colors directly editable without any conversion) is saved to `exports/` with a timestamp. The SVG snapshot `_svg.pptx` plus a copy of `svg_output/` (the Executor's raw SVG source) are archived to `backup/<timestamp>/`, so you can revisit the visual reference or rebuild the pptx via `finalize_svg → svg_to_pptx` without re-running the LLM. `backup/<timestamp>/` directories can be deleted manually when no longer needed. Requires **Office 2016** or later.diff --git a/docs/zh/faq.md b/docs/zh/faq.mdindex 79649c7a..5777cb25 100644--- a/docs/zh/faq.md+++ b/docs/zh/faq.md@@ -30,6 +30,12 @@ PPT Master 可以在任何能读取文件和执行命令的 AI 编程代理中可以。PPT Master 内置了图片生成脚本,支持多个供应商(Gemini、OpenAI、FLUX、通义千问、智谱等)。在策略师阶段选择"AI 生图"方案后,流程会根据内容自动生成配图。你也可以使用自己的图片——只需放到项目的 `images/` 目录下即可。+## Q: 没有生图 API Key,还能配图吗?++可以——在策略师的"图片方案"步骤选择"网络图片"。PPT Master 内置了零配置的 `image_search.py`,在 Openverse 和 Wikimedia Commons 中搜索可商用的开放许可图片(无需 API Key)。默认只搜 CC0 / 公有领域,避免幻灯片视觉污染;只有公有领域找不到合适图时才回落到 CC BY / CC BY-SA,并由 Executor 在该幻灯片自动添加就地小字署名。++两种路径可以在同一份 deck 里混用(比如 hero 图用 AI 生成、团队照片用网络搜索)。如果想要更现代的商业风照片,可在 `.env` 里设置 `PEXELS_API_KEY` 或 `PIXABAY_API_KEY`(都是免费申请),搜索会自动把它们纳入。+## Q: 生成的 PPT 可以编辑吗?可以。主 `.pptx`(原生 PowerPoint 形状,文字、图形、颜色均可直接编辑,无需转换)以时间戳命名保存至 `exports/`。SVG 快照版 `_svg.pptx` 与 Executor 原始 SVG 源(`svg_output/` 副本)一同归档至 `backup/<timestamp>/`,便于回溯视觉参考或基于该版重跑 `finalize_svg → svg_to_pptx` 重建 pptx,无需再走 LLM。`backup/<timestamp>/` 目录可手动清理。需要 **Office 2016** 或更高版本。diff --git a/skills/ppt-master/scripts/docs/image.md b/skills/ppt-master/scripts/docs/image.mdindex fa88cf02..07da71c1 100644--- a/skills/ppt-master/scripts/docs/image.md+++ b/skills/ppt-master/scripts/docs/image.md@@ -1,6 +1,6 @@# Image Tools-Image tools cover prompt-based generation, image inspection, and Gemini watermark removal.+Image tools cover prompt-based AI generation, web image search, image inspection, and Gemini watermark removal.## `image_gen.py`@@ -84,6 +84,57 @@ python3 scripts/analyze_images.py <project_path>/imagesUse this instead of opening image files directly when following the project workflow.+## `image_search.py`++Zero-config web image search across openly-licensed providers. Sister tool to `image_gen.py` — used when the resource list row has `Acquire Via: web`.++```bash+python3 scripts/image_search.py "offshore wind farm" \+ --filename cover_bg.jpg --slide 01_cover \+ --orientation landscape -o projects/demo/images+```++Providers (Openverse and Wikimedia work with no key; Pexels and Pixabay are optional):++| Provider | Config | Strength |+|---|---|---|+| `openverse` | zero-config | aggregator: Wikimedia + Flickr + museums + rawpixel |+| `wikimedia` | zero-config | educational, scientific, geographic, historical |+| `pexels` | needs `PEXELS_API_KEY` | modern stock photography |+| `pixabay` | needs `PIXABAY_API_KEY` | broad type coverage including illustrations |++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.++Two-stage license filter:++- **Stage 1 (default)**: search all providers with `cc0,pdm,pexels,pixabay` filter — no on-slide attribution needed.+- **Stage 2 (fallback)**: re-run with `cc by, cc by-sa` added; the chosen image is flagged `attribution-required` so the Executor adds an inline credit on the slide.+- `--strict-no-attribution` skips Stage 2 — useful for full-bleed hero images or templates that cannot host a credit element.++Pin a provider, refuse attribution, or override the manifest path:++```bash+# Pin Wikimedia+python3 scripts/image_search.py "Olympics opening ceremony" \+ --filename event.jpg --provider wikimedia \+ --orientation landscape -o projects/demo/images++# Strict mode — refuse CC BY / CC BY-SA, fail rather than fall back+python3 scripts/image_search.py "abstract gradient" \+ --filename hero.jpg --strict-no-attribution \+ -o projects/demo/images+```++Output:++- Image saved to the specified output directory (auto-converts webp → jpg via Pillow when the filename extension demands)+- `image_sources.json` manifest with full provenance (provider, license, license_tier, author, source URL, dimensions, attribution_text)+- Manifest is idempotent on `filename` — rerunning replaces that entry only++Allowed licenses (default): CC0, Public Domain, Pexels License, Pixabay Content License, CC BY, CC BY-SA. Auto-rejected: CC BY-NC, CC BY-ND, CC BY-NC-SA, CC BY-NC-ND, all rights reserved, unknown.++The full role-level reference (intent → query translation, on-slide attribution visual specification) is in [`references/image-searcher.md`](../../references/image-searcher.md).+## `gemini_watermark_remover.py`Remove Gemini watermark assets after manual download.