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

fix(skill): make skills/ppt-master self-contained for standalone install

hugohe3df9c1bc480ce
diff --git a/.env.example b/.env.example
index 8795934d..dac130da 100644
--- a/.env.example
+++ b/.env.example
@@ -6,6 +6,15 @@
# Current process environment variables take precedence over this file.
# 当前文件是 image_gen.py 的可选 fallback 配置来源。
# 当前进程环境变量优先于这个文件。
+#
+# Resolution order (only the FIRST existing file is read; keys are NOT merged across files):
+# 1. ./.env in your current working directory
+# 2. <repo-root>/.env (when running from a clone)
+# 3. ~/.ppt-master/.env (user-level config)
+# 查找顺序(只读第一个存在的文件,多个 .env 之间不合并):
+# 1. 当前工作目录下的 ./.env
+# 2. 仓库根目录下的 .env(仅在 clone 模式下)
+# 3. ~/.ppt-master/.env(用户级配置)
# Active backend (required) / 当前启用后端(必需)
# Recommended core backends: openai / gemini / qwen / zhipu / volcengine
diff --git a/README.md b/README.md
index 90863c36..2a2369b8 100644
--- a/README.md
+++ b/README.md
@@ -38,7 +38,7 @@ English | [中文](./README_CN.md)
Drop in a PDF, DOCX, URL, or Markdown — get back a **natively editable PowerPoint** with real shapes, real text boxes, and real charts. Not images. Click anything and edit it.
-> **Animations** — exported decks support **page transitions** and **per-element entrance animations** as real OOXML, not embedded video. Click-by-click cascade in PowerPoint and Keynote, no extra tooling. See [Animations & Transitions →](./docs/animations.md).
+> **Animations** — exported decks support **page transitions** and **per-element entrance animations** as real OOXML, not embedded video. Click-by-click cascade in PowerPoint and Keynote, no extra tooling. See [Animations & Transitions →](./skills/ppt-master/references/animations.md).
> **How it works** — PPT Master is a workflow (a "skill") that works inside AI IDEs like Claude Code, Cursor, VS Code + Copilot, or Codebuddy. You chat with the AI — "make a deck from this PDF" — and it follows the workflow to produce a real editable `.pptx` on your computer. No coding on your side; the IDE is just where the conversation happens.
>
@@ -238,7 +238,7 @@ Multiple backends are supported across Core / Extended / Experimental tiers. Run
| 📖 | [SKILL.md](./skills/ppt-master/SKILL.md) | Core workflow and rules |
| 🎨 | [Create a Custom Template](./skills/ppt-master/workflows/create-template.md) | Standalone workflow for building your own brand or industry template |
| 📐 | [Canvas Formats](./skills/ppt-master/references/canvas-formats.md) | PPT 16:9, Xiaohongshu, WeChat, and 10+ formats |
-| 🎬 | [Animations & Transitions](./docs/animations.md) | Page transitions and per-element entrance animations |
+| 🎬 | [Animations & Transitions](./skills/ppt-master/references/animations.md) | Page transitions and per-element entrance animations |
| 🛠️ | [Scripts & Tools](./skills/ppt-master/scripts/README.md) | All scripts and commands |
| 💼 | [Examples](./examples/README.md) | 22 projects, 309 pages |
| 🏗️ | [Technical Design](./docs/technical-design.md) | Architecture, design philosophy, why SVG |
diff --git a/docs/faq.md b/docs/faq.md
index 8d20e0c0..f6c441c3 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -66,7 +66,7 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation mixed #
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fade --animation-trigger after-previous # cascade without clicks
```
-Full effect list, anchor logic (top-level `<g id="...">`), fallback behavior, and limitations: see [Animations & Transitions](./animations.md).
+Full effect list, anchor logic (top-level `<g id="...">`), fallback behavior, and limitations: see [Animations & Transitions](../skills/ppt-master/references/animations.md).
## Q: Which AI model works best?
diff --git a/requirements.txt b/requirements.txt
index 7268947f..4346dde9 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,99 +1,11 @@
# PPT Master Dependencies / PPT Master 依赖
# =============================================
#
-# Most tools use only the Python standard library. Below are optional dependencies.
-# 大部分工具仅使用 Python 标准库,以下为可选依赖。
+# Full list lives inside the skill so installing the skill alone gives full capability.
+# 完整依赖列表已内置于 skill 内部,单独安装 skill 即可获得完整能力。
#
# Install / 安装方式:
-# pip install -r requirements.txt
-
-# ─────────────────────────────────────────────────────────────
-# SVG to PPTX tool / SVG 转 PPTX 工具 (skills/ppt-master/scripts/svg_to_pptx.py)
-# ─────────────────────────────────────────────────────────────
-# Batch-convert SVG files to PowerPoint presentations.
-# 用于将 SVG 文件批量转换为 PowerPoint 演示文稿
-# Uses Office-compatible mode (PNG + SVG dual format) by default, supports all Office versions.
-# 默认使用 Office 兼容模式(PNG + SVG 双格式),支持所有 Office 版本
-python-pptx>=0.6.21
-
-# Office compatibility dependencies (choose one, CairoSVG preferred)
-# Office 兼容模式依赖(二选一,优先使用 cairosvg)
-# Converts SVG to PNG fallback images for Office LTSC 2021 etc.
-# 用于将 SVG 转换为 PNG 后备图片,确保 Office LTSC 2021 等版本正常显示
+# pip install -r requirements.txt # from repo root / 仓库根目录
+# pip install -r skills/ppt-master/requirements.txt # from anywhere / 任意位置
#
-# Option A / 方案 A: CairoSVG (recommended / 推荐, ~25MB, full gradient/filter support)
-# pip install cairosvg
-# macOS: brew install cairo
-#
-# Option B / 方案 B: svglib (lightweight / 轻量, ~5MB, some gradients may be lost)
-svglib>=1.5.0
-reportlab>=4.0.0
-
-# ─────────────────────────────────────────────────────────────
-# PDF to Markdown tool / PDF 转 Markdown 工具 (skills/ppt-master/scripts/source_to_md/pdf_to_md.py)
-# ─────────────────────────────────────────────────────────────
-# Converts PDF to Markdown with text, image, and table extraction.
-# 用于将 PDF 文件转换为 Markdown 格式,支持文本、图片、表格提取
-PyMuPDF>=1.23.0
-
-# ─────────────────────────────────────────────────────────────
-# Document to Markdown tool / 文档转 Markdown 工具 (skills/ppt-master/scripts/source_to_md/doc_to_md.py)
-# ─────────────────────────────────────────────────────────────
-# Native (pure-Python) paths — no external binary required:
-# 原生路径(纯 Python,无需外部程序):
-# .docx → mammoth
-# .html → markdownify (+ beautifulsoup4, listed below)
-# .epub → ebooklib (+ markdownify)
-# .ipynb → nbconvert
-mammoth>=1.6.0
-markdownify>=0.11.6
-ebooklib>=0.18
-nbconvert>=7.0.0
-
-# ─────────────────────────────────────────────────────────────
-# Excel to Markdown tool / Excel 转 Markdown 工具 (skills/ppt-master/scripts/source_to_md/excel_to_md.py)
-# ─────────────────────────────────────────────────────────────
-# Converts .xlsx/.xlsm workbooks to Markdown while preserving sheet structure.
-# 用于将 .xlsx/.xlsm 工作簿转换为 Markdown,并保留工作表结构。
-openpyxl>=3.1.0
-#
-# Fallback path — only needed for less common formats
-# (.doc .odt .rtf .tex/.latex .rst .org .typ).
-# Not required if you only convert the four native formats above.
-# 备用路径 —— 仅在需要处理以下小众格式时才用到
-# (.doc .odt .rtf .tex/.latex .rst .org .typ)。
-# 如果只处理上述四种原生格式,无需安装。
-# macOS: brew install pandoc
-# Ubuntu: sudo apt install pandoc
-# Windows: https://pandoc.org/installing.html
-
-# ─────────────────────────────────────────────────────────────
-# Image processing tools / 图片处理工具
-# ─────────────────────────────────────────────────────────────
-# fix_image_aspect.py - Fix image aspect ratio (prevent stretching during PPT shape conversion)
-# fix_image_aspect.py - 修复图片宽高比(防止 PPT 转形状时拉伸)
-# gemini_watermark_remover.py - Remove watermarks from Gemini-generated images
-# gemini_watermark_remover.py - 去除 Gemini 生成图片的水印
-Pillow>=9.0.0
-numpy>=1.20.0
-
-# ─────────────────────────────────────────────────────────────
-# Web to Markdown tool / 网页转 Markdown 工具 (skills/ppt-master/scripts/source_to_md/web_to_md.py)
-# ─────────────────────────────────────────────────────────────
-requests>=2.31.0
-beautifulsoup4>=4.12.0
-# Optional — TLS fingerprint impersonation for sites that block Python's
-# default TLS fingerprint (e.g., WeChat mp.weixin.qq.com). If installed,
-# web_to_md.py uses it automatically; otherwise falls back to requests.
-# Install this to avoid needing Node.js for WeChat / portal pages.
-# 可选 —— 用于绕过 TLS 指纹屏蔽(例如微信公众号等)。装了之后 web_to_md.py
-# 会自动启用;不装则回退到 requests。装了它就不必再装 Node.js。
-curl_cffi>=0.7.0
-
-# ─────────────────────────────────────────────────────────────
-# AI image generation tool / AI 图片生成工具 (skills/ppt-master/scripts/image_gen.py)
-# ─────────────────────────────────────────────────────────────
-# Gemini backend / Gemini 后端 (IMAGE_BACKEND=gemini)
-google-genai>=1.0.0
-# OpenAI-compatible backend / OpenAI 兼容后端 (IMAGE_BACKEND=openai)
-openai>=1.0.0
+-r skills/ppt-master/requirements.txt
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index 49d33209..a9b779ea 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -311,7 +311,7 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path> -s final
- `--animation-trigger {on-click,with-previous,after-previous}` — Start mode (matches PowerPoint's animation-pane Start dropdown). Default `on-click`. Use `after-previous` (with `--animation-stagger`) for click-free cascade, or `with-previous` for all-at-once.
- `--auto-advance <seconds>` — kiosk-style auto-play.
-Full effect list, anchor logic, and limits: [`docs/animations.md`](../../docs/animations.md).
+Full effect list, anchor logic, and limits: [`references/animations.md`](references/animations.md).
> ❌ **NEVER** substitute `cp` for `finalize_svg.py` — finalize performs multiple critical processing steps
> ❌ **NEVER** export from `svg_output/` — MUST use `-s final` (exports from `svg_final/`)
diff --git a/docs/animations.md b/skills/ppt-master/references/animations.md
similarity index 98%
rename from docs/animations.md
rename to skills/ppt-master/references/animations.md
index 9d627a02..13de8264 100644
--- a/docs/animations.md
+++ b/skills/ppt-master/references/animations.md
@@ -108,4 +108,4 @@ Executors should wrap logical sections in `<g id>` regardless of whether you pla
| Slower per-element reveal | `--animation-duration 0.5` |
| Wider gap in after-previous | `--animation-stagger 0.8` |
-See also: [`scripts/docs/svg-pipeline.md`](../skills/ppt-master/scripts/docs/svg-pipeline.md) for the full `svg_to_pptx.py` reference.
+See also: [`scripts/docs/svg-pipeline.md`](../scripts/docs/svg-pipeline.md) for the full `svg_to_pptx.py` reference.
diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.md
index 997a0d42..bc2f43a8 100644
--- a/skills/ppt-master/references/shared-standards.md
+++ b/skills/ppt-master/references/shared-standards.md
@@ -314,7 +314,7 @@ python3 scripts/svg_to_pptx.py <project_path> -s final
- `--animation-trigger {on-click,with-previous,after-previous}` — Start mode matching PowerPoint's animation-pane Start dropdown. Default `on-click`; `after-previous` cascades on slide entry (pace via `--animation-stagger <seconds>`); `with-previous` plays all groups together.
- `--auto-advance <seconds>` — kiosk-style auto-play
-Full reference: [`docs/animations.md`](../../../docs/animations.md).
+Full reference: [`animations.md`](animations.md).
**Prohibited**:
- NEVER use `cp` as a substitute for `finalize_svg.py`
diff --git a/skills/ppt-master/requirements.txt b/skills/ppt-master/requirements.txt
new file mode 100644
index 00000000..7268947f
--- /dev/null
+++ b/skills/ppt-master/requirements.txt
@@ -0,0 +1,99 @@
+# PPT Master Dependencies / PPT Master 依赖
+# =============================================
+#
+# Most tools use only the Python standard library. Below are optional dependencies.
+# 大部分工具仅使用 Python 标准库,以下为可选依赖。
+#
+# Install / 安装方式:
+# pip install -r requirements.txt
+
+# ─────────────────────────────────────────────────────────────
+# SVG to PPTX tool / SVG 转 PPTX 工具 (skills/ppt-master/scripts/svg_to_pptx.py)
+# ─────────────────────────────────────────────────────────────
+# Batch-convert SVG files to PowerPoint presentations.
+# 用于将 SVG 文件批量转换为 PowerPoint 演示文稿
+# Uses Office-compatible mode (PNG + SVG dual format) by default, supports all Office versions.
+# 默认使用 Office 兼容模式(PNG + SVG 双格式),支持所有 Office 版本
+python-pptx>=0.6.21
+
+# Office compatibility dependencies (choose one, CairoSVG preferred)
+# Office 兼容模式依赖(二选一,优先使用 cairosvg)
+# Converts SVG to PNG fallback images for Office LTSC 2021 etc.
+# 用于将 SVG 转换为 PNG 后备图片,确保 Office LTSC 2021 等版本正常显示
+#
+# Option A / 方案 A: CairoSVG (recommended / 推荐, ~25MB, full gradient/filter support)
+# pip install cairosvg
+# macOS: brew install cairo
+#
+# Option B / 方案 B: svglib (lightweight / 轻量, ~5MB, some gradients may be lost)
+svglib>=1.5.0
+reportlab>=4.0.0
+
+# ─────────────────────────────────────────────────────────────
+# PDF to Markdown tool / PDF 转 Markdown 工具 (skills/ppt-master/scripts/source_to_md/pdf_to_md.py)
+# ─────────────────────────────────────────────────────────────
+# Converts PDF to Markdown with text, image, and table extraction.
+# 用于将 PDF 文件转换为 Markdown 格式,支持文本、图片、表格提取
+PyMuPDF>=1.23.0
+
+# ─────────────────────────────────────────────────────────────
+# Document to Markdown tool / 文档转 Markdown 工具 (skills/ppt-master/scripts/source_to_md/doc_to_md.py)
+# ─────────────────────────────────────────────────────────────
+# Native (pure-Python) paths — no external binary required:
+# 原生路径(纯 Python,无需外部程序):
+# .docx → mammoth
+# .html → markdownify (+ beautifulsoup4, listed below)
+# .epub → ebooklib (+ markdownify)
+# .ipynb → nbconvert
+mammoth>=1.6.0
+markdownify>=0.11.6
+ebooklib>=0.18
+nbconvert>=7.0.0
+
+# ─────────────────────────────────────────────────────────────
+# Excel to Markdown tool / Excel 转 Markdown 工具 (skills/ppt-master/scripts/source_to_md/excel_to_md.py)
+# ─────────────────────────────────────────────────────────────
+# Converts .xlsx/.xlsm workbooks to Markdown while preserving sheet structure.
+# 用于将 .xlsx/.xlsm 工作簿转换为 Markdown,并保留工作表结构。
+openpyxl>=3.1.0
+#
+# Fallback path — only needed for less common formats
+# (.doc .odt .rtf .tex/.latex .rst .org .typ).
+# Not required if you only convert the four native formats above.
+# 备用路径 —— 仅在需要处理以下小众格式时才用到
+# (.doc .odt .rtf .tex/.latex .rst .org .typ)。
+# 如果只处理上述四种原生格式,无需安装。
+# macOS: brew install pandoc
+# Ubuntu: sudo apt install pandoc
+# Windows: https://pandoc.org/installing.html
+
+# ─────────────────────────────────────────────────────────────
+# Image processing tools / 图片处理工具
+# ─────────────────────────────────────────────────────────────
+# fix_image_aspect.py - Fix image aspect ratio (prevent stretching during PPT shape conversion)
+# fix_image_aspect.py - 修复图片宽高比(防止 PPT 转形状时拉伸)
+# gemini_watermark_remover.py - Remove watermarks from Gemini-generated images
+# gemini_watermark_remover.py - 去除 Gemini 生成图片的水印
+Pillow>=9.0.0
+numpy>=1.20.0
+
+# ─────────────────────────────────────────────────────────────
+# Web to Markdown tool / 网页转 Markdown 工具 (skills/ppt-master/scripts/source_to_md/web_to_md.py)
+# ─────────────────────────────────────────────────────────────
+requests>=2.31.0
+beautifulsoup4>=4.12.0
+# Optional — TLS fingerprint impersonation for sites that block Python's
+# default TLS fingerprint (e.g., WeChat mp.weixin.qq.com). If installed,
+# web_to_md.py uses it automatically; otherwise falls back to requests.
+# Install this to avoid needing Node.js for WeChat / portal pages.
+# 可选 —— 用于绕过 TLS 指纹屏蔽(例如微信公众号等)。装了之后 web_to_md.py
+# 会自动启用;不装则回退到 requests。装了它就不必再装 Node.js。
+curl_cffi>=0.7.0
+
+# ─────────────────────────────────────────────────────────────
+# AI image generation tool / AI 图片生成工具 (skills/ppt-master/scripts/image_gen.py)
+# ─────────────────────────────────────────────────────────────
+# Gemini backend / Gemini 后端 (IMAGE_BACKEND=gemini)
+google-genai>=1.0.0
+# OpenAI-compatible backend / OpenAI 兼容后端 (IMAGE_BACKEND=openai)
+openai>=1.0.0
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index 2cd1d23e..855f7e8e 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -110,6 +110,6 @@ python3 scripts/update_repo.py --skip-pip
- [SVG Pipeline Tools](./docs/svg-pipeline.md)
- [Image Tools](./docs/image.md)
- [Troubleshooting](./docs/troubleshooting.md)
-- [AGENTS Guide](../../../AGENTS.md)
+- [Skill Entry](../SKILL.md)
_Last updated: 2026-04-09_
diff --git a/skills/ppt-master/scripts/image_backends/backend_bfl.py b/skills/ppt-master/scripts/image_backends/backend_bfl.py
index 9f979c44..be168505 100644
--- a/skills/ppt-master/scripts/image_backends/backend_bfl.py
+++ b/skills/ppt-master/scripts/image_backends/backend_bfl.py
@@ -145,7 +145,7 @@ def generate(prompt: str, negative_prompt: str = None,
"""Generate an image with retries using the BFL backend."""
api_key = require_api_key(
"BFL_API_KEY",
- message="No API key found. Set BFL_API_KEY in the current environment or the project-root .env.",
+ message="No API key found. Set BFL_API_KEY in the current environment or a .env file.",
)
base_url = os.environ.get("BFL_BASE_URL") or DEFAULT_BASE_URL
resolved_model = model or os.environ.get("BFL_MODEL") or DEFAULT_MODEL
diff --git a/skills/ppt-master/scripts/image_backends/backend_fal.py b/skills/ppt-master/scripts/image_backends/backend_fal.py
index 790d24ac..726461ba 100644
--- a/skills/ppt-master/scripts/image_backends/backend_fal.py
+++ b/skills/ppt-master/scripts/image_backends/backend_fal.py
@@ -95,7 +95,7 @@ def generate(prompt: str, negative_prompt: str = None,
api_key = require_api_key(
"FAL_KEY",
"FAL_API_KEY",
- message="No API key found. Set FAL_KEY or FAL_API_KEY in the current environment or the project-root .env.",
+ message="No API key found. Set FAL_KEY or FAL_API_KEY in the current environment or a .env file.",
)
base_url = os.environ.get("FAL_BASE_URL") or DEFAULT_ENDPOINT
resolved_model = model or os.environ.get("FAL_MODEL") or DEFAULT_MODEL
diff --git a/skills/ppt-master/scripts/image_backends/backend_gemini.py b/skills/ppt-master/scripts/image_backends/backend_gemini.py
index 962ce41d..9a3990a4 100644
--- a/skills/ppt-master/scripts/image_backends/backend_gemini.py
+++ b/skills/ppt-master/scripts/image_backends/backend_gemini.py
@@ -163,7 +163,7 @@ def generate(prompt: str, negative_prompt: str = None,
"""
Gemini image generation with automatic retry.
- Reads credentials from the current process environment or the project-root `.env`:
+ Reads credentials from the current process environment or a `.env` file:
GEMINI_API_KEY
GEMINI_BASE_URL
GEMINI_MODEL (optional override)
@@ -186,7 +186,7 @@ def generate(prompt: str, negative_prompt: str = None,
if not api_key:
raise ValueError(
- "No API key found. Set GEMINI_API_KEY in the current environment or the project-root .env."
+ "No API key found. Set GEMINI_API_KEY in the current environment or a .env file."
)
if model is None:
diff --git a/skills/ppt-master/scripts/image_backends/backend_ideogram.py b/skills/ppt-master/scripts/image_backends/backend_ideogram.py
index e96176bd..7c1d4d66 100644
--- a/skills/ppt-master/scripts/image_backends/backend_ideogram.py
+++ b/skills/ppt-master/scripts/image_backends/backend_ideogram.py
@@ -120,7 +120,7 @@ def generate(prompt: str, negative_prompt: str = None,
"""Generate an image with retries using the Ideogram backend."""
api_key = require_api_key(
"IDEOGRAM_API_KEY",
- message="No API key found. Set IDEOGRAM_API_KEY in the current environment or the project-root .env.",
+ message="No API key found. Set IDEOGRAM_API_KEY in the current environment or a .env file.",
)
base_url = os.environ.get("IDEOGRAM_BASE_URL") or DEFAULT_BASE_URL
resolved_model = model or os.environ.get("IDEOGRAM_MODEL") or DEFAULT_MODEL
diff --git a/skills/ppt-master/scripts/image_backends/backend_minimax.py b/skills/ppt-master/scripts/image_backends/backend_minimax.py
index d8e4cd6e..87146fe7 100644
--- a/skills/ppt-master/scripts/image_backends/backend_minimax.py
+++ b/skills/ppt-master/scripts/image_backends/backend_minimax.py
@@ -174,7 +174,7 @@ def generate(prompt: str, negative_prompt: str = None,
"""Generate an image with retries using the MiniMax backend."""
api_key = require_api_key(
"MINIMAX_API_KEY",
- message="No API key found. Set MINIMAX_API_KEY in the current environment or the project-root .env.",
+ message="No API key found. Set MINIMAX_API_KEY in the current environment or a .env file.",
)
base_url = os.environ.get("MINIMAX_BASE_URL") or DEFAULT_ENDPOINT
resolved_model = model or os.environ.get("MINIMAX_MODEL") or DEFAULT_MODEL
diff --git a/skills/ppt-master/scripts/image_backends/backend_openai.py b/skills/ppt-master/scripts/image_backends/backend_openai.py
index 57d8a84f..a1fc0d8f 100644
--- a/skills/ppt-master/scripts/image_backends/backend_openai.py
+++ b/skills/ppt-master/scripts/image_backends/backend_openai.py
@@ -252,7 +252,7 @@ def generate(prompt: str, negative_prompt: str = None,
"""
OpenAI-compatible image generation with automatic retry.
- Reads credentials from the current process environment or the project-root `.env`:
+ Reads credentials from the current process environment or a `.env` file:
OPENAI_API_KEY
OPENAI_BASE_URL
OPENAI_MODEL (optional override)
@@ -275,7 +275,7 @@ def generate(prompt: str, negative_prompt: str = None,
if not api_key:
raise ValueError(
- "No API key found. Set OPENAI_API_KEY in the current environment or the project-root .env."
+ "No API key found. Set OPENAI_API_KEY in the current environment or a .env file."
)
if model is None:
diff --git a/skills/ppt-master/scripts/image_backends/backend_openrouter.py b/skills/ppt-master/scripts/image_backends/backend_openrouter.py
index 875bb037..0ba27978 100644
--- a/skills/ppt-master/scripts/image_backends/backend_openrouter.py
+++ b/skills/ppt-master/scripts/image_backends/backend_openrouter.py
@@ -135,7 +135,7 @@ def generate(prompt: str, negative_prompt: str = None,
"""
OpenRouter image generation with automatic retry.
- Reads credentials from the current process environment or the project-root `.env`:
+ Reads credentials from the current process environment or a `.env` file:
OPENROUTER_API_KEY
OPENROUTER_BASE_URL
OPENROUTER_MODEL (optional override)
@@ -145,7 +145,7 @@ def generate(prompt: str, negative_prompt: str = None,
if not api_key:
raise ValueError(
- "No API key found. Set OPENROUTER_API_KEY in the current environment or the project-root .env."
+ "No API key found. Set OPENROUTER_API_KEY in the current environment or a .env file."
)
if model is None:
diff --git a/skills/ppt-master/scripts/image_backends/backend_qwen.py b/skills/ppt-master/scripts/image_backends/backend_qwen.py
index 5b0e135a..550bb477 100644
--- a/skills/ppt-master/scripts/image_backends/backend_qwen.py
+++ b/skills/ppt-master/scripts/image_backends/backend_qwen.py
@@ -165,7 +165,7 @@ def generate(prompt: str, negative_prompt: str = None,
api_key = require_api_key(
"QWEN_API_KEY",
"DASHSCOPE_API_KEY",
- message="No API key found. Set QWEN_API_KEY or DASHSCOPE_API_KEY in the current environment or the project-root .env.",
+ message="No API key found. Set QWEN_API_KEY or DASHSCOPE_API_KEY in the current environment or a .env file.",
)
base_url = os.environ.get("QWEN_BASE_URL") or DEFAULT_ENDPOINT
resolved_model = model or os.environ.get("QWEN_MODEL") or DEFAULT_MODEL
diff --git a/skills/ppt-master/scripts/image_backends/backend_replicate.py b/skills/ppt-master/scripts/image_backends/backend_replicate.py
index 76c39320..70dd4076 100644
--- a/skills/ppt-master/scripts/image_backends/backend_replicate.py
+++ b/skills/ppt-master/scripts/image_backends/backend_replicate.py
@@ -139,7 +139,7 @@ def generate(prompt: str, negative_prompt: str = None,
api_key = require_api_key(
"REPLICATE_API_KEY",
"REPLICATE_API_TOKEN",
- message="No API key found. Set REPLICATE_API_KEY or REPLICATE_API_TOKEN in the current environment or the project-root .env.",
+ message="No API key found. Set REPLICATE_API_KEY or REPLICATE_API_TOKEN in the current environment or a .env file.",
)
base_url = os.environ.get("REPLICATE_BASE_URL") or DEFAULT_BASE_URL
resolved_model = model or os.environ.get("REPLICATE_MODEL") or DEFAULT_MODEL
diff --git a/skills/ppt-master/scripts/image_backends/backend_siliconflow.py b/skills/ppt-master/scripts/image_backends/backend_siliconflow.py
index bdf87abf..a8ae0b0f 100644
--- a/skills/ppt-master/scripts/image_backends/backend_siliconflow.py
+++ b/skills/ppt-master/scripts/image_backends/backend_siliconflow.py
@@ -148,7 +148,7 @@ def generate(prompt: str, negative_prompt: str = None,
"""Generate an image with retries using the SiliconFlow backend."""
api_key = require_api_key(
"SILICONFLOW_API_KEY",
- message="No API key found. Set SILICONFLOW_API_KEY in the current environment or the project-root .env.",
+ message="No API key found. Set SILICONFLOW_API_KEY in the current environment or a .env file.",
)
base_url = os.environ.get("SILICONFLOW_BASE_URL") or DEFAULT_ENDPOINT
resolved_model = model or os.environ.get("SILICONFLOW_MODEL") or DEFAULT_MODEL
diff --git a/skills/ppt-master/scripts/image_backends/backend_stability.py b/skills/ppt-master/scripts/image_backends/backend_stability.py
index d6b82941..ecba2505 100644
--- a/skills/ppt-master/scripts/image_backends/backend_stability.py
+++ b/skills/ppt-master/scripts/image_backends/backend_stability.py
@@ -111,7 +111,7 @@ def generate(prompt: str, negative_prompt: str = None,
"""Generate an image with retries using the Stability backend."""
api_key = require_api_key(
"STABILITY_API_KEY",
- message="No API key found. Set STABILITY_API_KEY in the current environment or the project-root .env.",
+ message="No API key found. Set STABILITY_API_KEY in the current environment or a .env file.",
)
base_url = os.environ.get("STABILITY_BASE_URL") or DEFAULT_BASE_URL
resolved_model = model or os.environ.get("STABILITY_MODEL") or DEFAULT_MODEL
diff --git a/skills/ppt-master/scripts/image_backends/backend_volcengine.py b/skills/ppt-master/scripts/image_backends/backend_volcengine.py
index 692f1e98..3bc20f66 100644
--- a/skills/ppt-master/scripts/image_backends/backend_volcengine.py
+++ b/skills/ppt-master/scripts/image_backends/backend_volcengine.py
@@ -155,7 +155,7 @@ def generate(prompt: str, negative_prompt: str = None,
api_key = require_api_key(
"VOLCENGINE_API_KEY",
"ARK_API_KEY",
- message="No API key found. Set VOLCENGINE_API_KEY or ARK_API_KEY in the current environment or the project-root .env.",
+ message="No API key found. Set VOLCENGINE_API_KEY or ARK_API_KEY in the current environment or a .env file.",
)
base_url = os.environ.get("VOLCENGINE_BASE_URL") or DEFAULT_ENDPOINT
resolved_model = model or os.environ.get("VOLCENGINE_MODEL") or DEFAULT_MODEL
diff --git a/skills/ppt-master/scripts/image_backends/backend_zhipu.py b/skills/ppt-master/scripts/image_backends/backend_zhipu.py
index dd4c84d1..ac5c3943 100644
--- a/skills/ppt-master/scripts/image_backends/backend_zhipu.py
+++ b/skills/ppt-master/scripts/image_backends/backend_zhipu.py
@@ -156,7 +156,7 @@ def generate(prompt: str, negative_prompt: str = None,
api_key = require_api_key(
"ZHIPU_API_KEY",
"BIGMODEL_API_KEY",
- message="No API key found. Set ZHIPU_API_KEY or BIGMODEL_API_KEY in the current environment or the project-root .env.",
+ message="No API key found. Set ZHIPU_API_KEY or BIGMODEL_API_KEY in the current environment or a .env file.",
)
base_url = os.environ.get("ZHIPU_BASE_URL") or DEFAULT_ENDPOINT
resolved_model = model or os.environ.get("ZHIPU_MODEL") or DEFAULT_MODEL
diff --git a/skills/ppt-master/scripts/image_gen.py b/skills/ppt-master/scripts/image_gen.py
index 3dd7966a..21e7be86 100644
--- a/skills/ppt-master/scripts/image_gen.py
+++ b/skills/ppt-master/scripts/image_gen.py
@@ -19,9 +19,12 @@ Backend selection (`IMAGE_BACKEND` in `.env` or the current process environment)
IMAGE_BACKEND=replicate -> Replicate backend
IMAGE_BACKEND=openrouter -> OpenRouter backend
-Configuration source:
+Configuration source (process env wins, `.env` is the fallback layer):
1. Current process environment variables
- 2. Project-root `.env` as a fallback layer
+ 2. The first `.env` found among:
+ - Current working directory
+ - Repo root (when running from a clone)
+ - `~/.ppt-master/.env` (user-level config)
Supported keys:
IMAGE_BACKEND (required) backend name
@@ -42,7 +45,25 @@ import sys
import argparse
from pathlib import Path
-ENV_PATH = Path(__file__).resolve().parents[3] / ".env"
+def _resolve_env_path() -> Path:
+ """
+ Locate a `.env` file across the deploy modes PPT Master supports.
+
+ Returns the first existing candidate; if none exist, returns the CWD path
+ (used purely as a non-existent fallback so `_load_image_env_file` no-ops).
+ """
+ candidates = [
+ Path.cwd() / ".env", # working directory (skill mode)
+ Path(__file__).resolve().parents[3] / ".env", # repo root (clone mode)
+ Path.home() / ".ppt-master" / ".env", # user-level config
+ ]
+ for candidate in candidates:
+ if candidate.exists():
+ return candidate
+ return candidates[0]
+
+
+ENV_PATH = _resolve_env_path()
IMAGE_ENV_PREFIXES = (
"IMAGE_",
"GEMINI_",
@@ -200,7 +221,7 @@ def _strip_env_quotes(value: str) -> str:
def _load_image_env_file() -> None:
"""
- Load image generation config from the project-root `.env` as a fallback layer.
+ Load image generation config from the resolved `.env` as a fallback layer.
Existing process environment variables win over `.env`.
"""