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(workflow): streamline PPT Master guidance
hugohe31793bafe04cc
diff --git a/AGENTS.md b/AGENTS.mdindex 7f00bf57..2a61e9b5 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -1,6 +1,8 @@# AGENTS.md-This file serves as the project entry point for general AI agents. Before executing PPT generation tasks, **you MUST first read `skills/ppt-master/SKILL.md`** for the complete workflow and rules.+This file is the project entry point for general AI agents.++Before executing any PPT generation task, **you MUST first read [`skills/ppt-master/SKILL.md`](skills/ppt-master/SKILL.md)**. That file is the authoritative workflow for project creation, role switching, strict serial execution, quality gates, post-processing, and export.## Project Overview@@ -8,93 +10,54 @@ PPT Master is an AI-driven presentation generation system. Through multi-role co**Core Pipeline**: `Source Document → Create Project → Template Option → Strategist Eight Confirmations → [Image_Generator] → Executor → Post-processing → Export PPTX`-**Execution Requirements**:+## Execution Requirements-- Before starting a PPT task, read `skills/ppt-master/SKILL.md` first-- To create a template independently, read `skills/ppt-master/workflows/create-template.md`-- Role-specific rules and technical constraints are in `skills/ppt-master/references/`-- ⚠️ **Strict serial execution**: Every Step in the pipeline MUST be executed sequentially — bundling, batching, or parallelizing Steps is FORBIDDEN-- ⚠️ **SVG generation must stay in the main agent**: During Executor Step 6, SVG pages MUST be generated by the current main agent with full project context. Delegating SVG generation to sub-agents is FORBIDDEN-- ⚠️ **SVG generation rhythm**: In Executor Step 6, first lock the global design context, then generate SVGs sequentially page by page in one continuous pass. Generating pages in grouped batches (for example, 5 pages at a time) is FORBIDDEN+- Read [`skills/ppt-master/SKILL.md`](skills/ppt-master/SKILL.md) before starting a PPT task.+- For standalone template creation, read [`skills/ppt-master/workflows/create-template.md`](skills/ppt-master/workflows/create-template.md).+- Role-specific rules live in [`skills/ppt-master/references/`](skills/ppt-master/references/).+- Technical SVG/PPT constraints live in [`skills/ppt-master/references/shared-standards.md`](skills/ppt-master/references/shared-standards.md).+- Canvas choices live in [`skills/ppt-master/references/canvas-formats.md`](skills/ppt-master/references/canvas-formats.md).+- Icon library details live in [`skills/ppt-master/templates/icons/README.md`](skills/ppt-master/templates/icons/README.md).## Compatibility Boundary-- This repository is a workflow/skill package, not a conventional app or service scaffold-- Do NOT assume repository-local conventions such as `.worktrees/`, `tests/`, or mandatory branch setup unless the user explicitly requests them-- If a generic coding skill conflicts with this repository's instructions, prioritize `skills/ppt-master/SKILL.md` and this file for work inside this repository+- This repository is a workflow/skill package, not a conventional app or service scaffold.+- Do NOT assume repository-local conventions such as `.worktrees/`, `tests/`, or mandatory branch setup unless the user explicitly requests them.+- If a generic coding skill conflicts with this repository's instructions, prioritize [`skills/ppt-master/SKILL.md`](skills/ppt-master/SKILL.md) and this file for work inside this repository.++## Command Quick Reference-## Common Commands+These commands are a convenience summary only. The full step-by-step workflow remains in [`skills/ppt-master/SKILL.md`](skills/ppt-master/SKILL.md).```bash# Source content conversionpython3 skills/ppt-master/scripts/source_to_md/pdf_to_md.py <PDF_file>-python3 skills/ppt-master/scripts/source_to_md/doc_to_md.py <DOCX_or_other_file> # Native: .docx/.html/.epub/.ipynb; pandoc fallback: .doc/.odt/.rtf/.tex/.rst/.org/.typ+python3 skills/ppt-master/scripts/source_to_md/doc_to_md.py <DOCX_or_other_file>python3 skills/ppt-master/scripts/source_to_md/ppt_to_md.py <PPTX_file>-python3 skills/ppt-master/scripts/source_to_md/web_to_md.py <URL> # auto-uses curl_cffi if installed (covers WeChat etc.)-node skills/ppt-master/scripts/source_to_md/web_to_md.cjs <URL> # fallback only; use if curl_cffi is unavailable+python3 skills/ppt-master/scripts/source_to_md/web_to_md.py <URL># Project managementpython3 skills/ppt-master/scripts/project_manager.py init <project_name> --format ppt169python3 skills/ppt-master/scripts/project_manager.py import-sources <project_path> <source_files_or_URLs...> --movepython3 skills/ppt-master/scripts/project_manager.py validate <project_path>-# Image tools+# Image tools and SVG quality checkpython3 skills/ppt-master/scripts/analyze_images.py <project_path>/imagespython3 skills/ppt-master/scripts/image_gen.py "prompt" --aspect_ratio 16:9 --image_size 1K -o <project_path>/images--# SVG quality checkpython3 skills/ppt-master/scripts/svg_quality_checker.py <project_path>-# Post-processing pipeline (MUST run sequentially, one at a time — NEVER batch)+# Post-processing pipeline: run sequentially, one command at a timepython3 skills/ppt-master/scripts/total_md_split.py <project_path>-# ✅ Confirm no errors before running the next commandpython3 skills/ppt-master/scripts/finalize_svg.py <project_path>-# ✅ Confirm no errors before running the next commandpython3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> -s final-# Output: exports/<project_name>_<timestamp>.pptx + exports/<project_name>_<timestamp>_svg.pptx-# Use --only native or --only legacy to generate just one version```## Core Directories-- `skills/ppt-master/SKILL.md` — Main entry point and complete workflow-- `skills/ppt-master/workflows/create-template.md` — Standalone template workflow-- `skills/ppt-master/references/` — Role definitions and technical specifications-- `skills/ppt-master/scripts/` — Tool scripts-- `skills/ppt-master/scripts/docs/` — Topic-focused script docs (`conversion`, `project`, `svg-pipeline`, `image`, `troubleshooting`)-- `skills/ppt-master/templates/` — Layout templates, chart templates, icon library-- `examples/` — Example projects-- `projects/` — User project workspace--## SVG Technical Constraints--**Banned features**: `mask` | `<style>` | `class` | external CSS | `<foreignObject>` | `textPath` | `@font-face` | `<animate*>` | `<script>` | `<iframe>` | `<symbol>`+`<use>` (`id` inside `<defs>` is a legitimate reference and is NOT banned)--**Conditionally allowed**: `marker-start` / `marker-end` — the referenced `<marker>` must live in `<defs>`, use `orient="auto"`, and its shape must be a triangle (3-vertex closed path/polygon), diamond (4-vertex), or circle/ellipse. The converter maps these to native DrawingML `<a:headEnd>` / `<a:tailEnd>`. See `shared-standards.md` §1.1 for full constraints.--**Conditionally allowed**: `clipPath` on `<image>` — the referenced `<clipPath>` must live in `<defs>` and contain a single shape child (circle, ellipse, rect with rx/ry, path, or polygon). The converter maps these to native DrawingML picture geometry (`<a:prstGeom>` or `<a:custGeom>`). Only supported on `<image>` elements. See `shared-standards.md` §1.2 for full constraints.--**PPT compatibility alternatives**:--| Banned | Alternative |-|--------|-------------|-| `rgba()` | `fill-opacity` / `stroke-opacity` |-| `<g opacity>` | Set opacity on each child element individually |-| `<image opacity>` | Overlay with a mask layer |--## Canvas Format Quick Reference--| Format | viewBox |-|--------|---------|-| PPT 16:9 | `0 0 1280 720` |-| PPT 4:3 | `0 0 1024 768` |-| Xiaohongshu (RED) | `0 0 1242 1660` |-| WeChat Moments | `0 0 1080 1080` |-| Story | `0 0 1080 1920` |--## Post-processing Notes--- **NEVER** use `cp` as a substitute for `finalize_svg.py`-- **NEVER** export directly from `svg_output/` — MUST export from `svg_final/` (use `-s final`)-- Do NOT add extra flags like `--only` to the post-processing commands-- **NEVER** run the three post-processing steps in a single code block or single shell invocation+- `skills/ppt-master/SKILL.md` — main workflow authority.+- `skills/ppt-master/references/` — role definitions and technical specifications.+- `skills/ppt-master/scripts/` — runnable tool scripts.+- `skills/ppt-master/scripts/docs/` — topic-focused script docs.+- `skills/ppt-master/templates/` — layout templates, chart templates, icon library.+- `examples/` — example projects.+- `projects/` — user project workspace.diff --git a/CLAUDE.md b/CLAUDE.mdindex 353bde3e..5132f71e 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -1,6 +1,8 @@# CLAUDE.md-This file provides a project overview for Claude Code. Before executing PPT generation tasks, **you MUST first read `skills/ppt-master/SKILL.md`** for the complete workflow and rules.+This file is the project entry point for Claude Code.++Before executing any PPT generation task, **you MUST first read [`skills/ppt-master/SKILL.md`](skills/ppt-master/SKILL.md)**. That file is the authoritative workflow for project creation, role switching, strict serial execution, quality gates, post-processing, and export.## Project Overview@@ -8,78 +10,54 @@ PPT Master is an AI-driven presentation generation system. Through multi-role co**Core Pipeline**: `Source Document → Create Project → Template Option → Strategist Eight Confirmations → [Image_Generator] → Executor → Post-processing → Export PPTX`-## Common Commands+## Execution Requirements++- Read [`skills/ppt-master/SKILL.md`](skills/ppt-master/SKILL.md) before starting a PPT task.+- For standalone template creation, read [`skills/ppt-master/workflows/create-template.md`](skills/ppt-master/workflows/create-template.md).+- Role-specific rules live in [`skills/ppt-master/references/`](skills/ppt-master/references/).+- Technical SVG/PPT constraints live in [`skills/ppt-master/references/shared-standards.md`](skills/ppt-master/references/shared-standards.md).+- Canvas choices live in [`skills/ppt-master/references/canvas-formats.md`](skills/ppt-master/references/canvas-formats.md).+- Icon library details live in [`skills/ppt-master/templates/icons/README.md`](skills/ppt-master/templates/icons/README.md).++## Compatibility Boundary++- This repository is a workflow/skill package, not a conventional app or service scaffold.+- Do NOT assume repository-local conventions such as `.worktrees/`, `tests/`, or mandatory branch setup unless the user explicitly requests them.+- If a generic coding skill conflicts with this repository's instructions, prioritize [`skills/ppt-master/SKILL.md`](skills/ppt-master/SKILL.md) and this file for work inside this repository.++## Command Quick Reference++These commands are a convenience summary only. The full step-by-step workflow remains in [`skills/ppt-master/SKILL.md`](skills/ppt-master/SKILL.md).```bash# Source content conversionpython3 skills/ppt-master/scripts/source_to_md/pdf_to_md.py <PDF_file>-python3 skills/ppt-master/scripts/source_to_md/doc_to_md.py <DOCX_or_other_file> # Native: .docx/.html/.epub/.ipynb; pandoc fallback: .doc/.odt/.rtf/.tex/.rst/.org/.typ+python3 skills/ppt-master/scripts/source_to_md/doc_to_md.py <DOCX_or_other_file>python3 skills/ppt-master/scripts/source_to_md/ppt_to_md.py <PPTX_file>-python3 skills/ppt-master/scripts/source_to_md/web_to_md.py <URL> # auto-uses curl_cffi if installed (covers WeChat etc.)-node skills/ppt-master/scripts/source_to_md/web_to_md.cjs <URL> # fallback only; use if curl_cffi is unavailable+python3 skills/ppt-master/scripts/source_to_md/web_to_md.py <URL># Project managementpython3 skills/ppt-master/scripts/project_manager.py init <project_name> --format ppt169python3 skills/ppt-master/scripts/project_manager.py import-sources <project_path> <source_files_or_URLs...> --movepython3 skills/ppt-master/scripts/project_manager.py validate <project_path>-# Image tools+# Image tools and SVG quality checkpython3 skills/ppt-master/scripts/analyze_images.py <project_path>/imagespython3 skills/ppt-master/scripts/image_gen.py "prompt" --aspect_ratio 16:9 --image_size 1K -o <project_path>/images--# SVG quality checkpython3 skills/ppt-master/scripts/svg_quality_checker.py <project_path>-# Post-processing pipeline (MUST run sequentially, one at a time — NEVER batch)+# Post-processing pipeline: run sequentially, one command at a timepython3 skills/ppt-master/scripts/total_md_split.py <project_path>-# ✅ Confirm no errors before running the next commandpython3 skills/ppt-master/scripts/finalize_svg.py <project_path>-# ✅ Confirm no errors before running the next commandpython3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> -s final-# Output: exports/<project_name>_<timestamp>.pptx + exports/<project_name>_<timestamp>_svg.pptx-# Use --only native or --only legacy to generate just one version```## Architecture-- `skills/ppt-master/references/` — AI role definitions and technical specifications-- `skills/ppt-master/scripts/` — Runnable tool scripts-- `skills/ppt-master/scripts/docs/` — Topic-focused script docs-- `skills/ppt-master/templates/` — Layout templates, chart templates, 640+ vector icons-- `examples/` — Example projects-- `projects/` — User project workspace--## SVG Technical Constraints (Non-negotiable)--**Text characters (must be well-formed XML)**: typography & symbols (em dash, en dash, ©, ®, →, NBSP, full-width punctuation, emoji…) MUST be written as raw Unicode characters; HTML named entities like ` ` `—` `©` `–` `®` are forbidden. XML reserved characters (`&` `<` `>` `"` `'`) inside text or attribute values MUST be escaped as `&` `<` `>` `"` `'` (e.g. `R&D`, `error < 5%`). See `shared-standards.md` §1.0 for full rules.--**Banned features**: `mask` | `<style>` | `class` | external CSS | `<foreignObject>` | `textPath` | `@font-face` | `<animate*>` | `<script>` | `<iframe>` | `<symbol>`+`<use>` (`id` inside `<defs>` is a legitimate reference and is NOT banned)--**Conditionally allowed**: `marker-start` / `marker-end` — the referenced `<marker>` must live in `<defs>`, use `orient="auto"`, and its shape must be a triangle (3-vertex closed path/polygon), diamond (4-vertex), or circle/ellipse. The converter maps these to native DrawingML `<a:headEnd>` / `<a:tailEnd>`. See `shared-standards.md` §1.1 for full constraints.--**Conditionally allowed**: `clipPath` on `<image>` — the referenced `<clipPath>` must live in `<defs>` and contain a single shape child (circle, ellipse, rect with rx/ry, path, or polygon). The converter maps these to native DrawingML picture geometry (`<a:prstGeom>` or `<a:custGeom>`). Only supported on `<image>` elements. See `shared-standards.md` §1.2 for full constraints.--**PPT compatibility alternatives**:--| Banned | Alternative |-|--------|-------------|-| `rgba()` | `fill-opacity` / `stroke-opacity` |-| `<g opacity>` | Set opacity on each child element individually |-| `<image opacity>` | Overlay with a mask layer |--## Canvas Format Quick Reference--| Format | viewBox |-|--------|---------|-| PPT 16:9 | `0 0 1280 720` |-| PPT 4:3 | `0 0 1024 768` |-| Xiaohongshu (RED) | `0 0 1242 1660` |-| WeChat Moments | `0 0 1080 1080` |-| Story | `0 0 1080 1920` |--## Post-processing Notes--- **NEVER** use `cp` as a substitute for `finalize_svg.py`-- **NEVER** export directly from `svg_output/` — MUST export from `svg_final/` (use `-s final`)-- Do NOT add extra flags like `--only` to the post-processing commands-- **NEVER** run the three post-processing steps in a single code block or single shell invocation+- `skills/ppt-master/SKILL.md` — main workflow authority.+- `skills/ppt-master/references/` — role definitions and technical specifications.+- `skills/ppt-master/scripts/` — runnable tool scripts.+- `skills/ppt-master/scripts/docs/` — topic-focused script docs.+- `skills/ppt-master/templates/` — layout templates, chart templates, icon library.+- `examples/` — example projects.+- `projects/` — user project workspace.diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.mdindex a8602401..e17cb052 100644--- a/skills/ppt-master/SKILL.md+++ b/skills/ppt-master/SKILL.md@@ -67,7 +67,7 @@ For complete tool documentation, see `${SKILL_DIR}/scripts/README.md`.|-------|------|---------|| Layout templates | `${SKILL_DIR}/templates/layouts/layouts_index.json` | Query available page layout templates || Visualization templates | `${SKILL_DIR}/templates/charts/charts_index.json` | Query available visualization SVG templates (charts, infographics, diagrams, frameworks) |-| Icon library | `${SKILL_DIR}/templates/icons/` | Search icons on demand: `ls templates/icons/<library>/ \| grep <keyword>` (libraries: `chunk/`, `tabler-filled/`, `tabler-outline/`) |+| Icon library | `${SKILL_DIR}/templates/icons/` | See `${SKILL_DIR}/templates/icons/README.md`; search icons on demand with `ls templates/icons/<library>/ \| grep <keyword>` |## Standalone Workflows@@ -212,7 +212,7 @@ python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/imagesRead `references/image-generator.md`-1. Extract all images with status "pending generation" from the design spec+1. Extract all images with status `Pending` from the design spec2. Generate prompt document → `<project_path>/images/image_prompts.md`3. Generate images (CLI tool recommended):```bash@@ -283,6 +283,8 @@ python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path>> ⚠️ The following three sub-steps MUST be **executed individually one at a time**. Each command must complete and be confirmed successful before running the next.> ❌ **NEVER** put all three commands in a single code block or single shell invocation.+Run the canonical three-command pipeline (same as `references/shared-standards.md` §5):+**Step 7.1** — Split speaker notes:```bashpython3 ${SKILL_DIR}/scripts/total_md_split.py <project_path>@@ -297,8 +299,6 @@ python3 ${SKILL_DIR}/scripts/finalize_svg.py <project_path>```bashpython3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path> -s final# Output: exports/<project_name>_<timestamp>.pptx + exports/<project_name>_<timestamp>_svg.pptx-# Use --only native to skip SVG reference version-# Use --only legacy to only generate SVG image version```> ❌ **NEVER** use `cp` as a substitute for `finalize_svg.py` — it performs multiple critical processing steps@@ -327,11 +327,11 @@ Before switching roles, you **MUST first read** the corresponding reference file| Canvas format specification | `references/canvas-formats.md` || Image layout specification | `references/image-layout-spec.md` || SVG image embedding | `references/svg-image-embedding.md` |+| Icon library | `templates/icons/README.md` |---## Notes-- Do NOT add extra flags like `--only` to the post-processing commands — run them as-is- Local preview: `python3 -m http.server -d <project_path>/svg_final 8000`- **Troubleshooting**: If the user encounters issues during generation (layout overflow, export errors, blank images, etc.), recommend checking `docs/faq.md` — it contains known solutions sourced from real user reports and is continuously updateddiff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.mdindex 5b6b6345..1ed145a5 100644--- a/skills/ppt-master/references/executor-base.md+++ b/skills/ppt-master/references/executor-base.md@@ -103,7 +103,7 @@ File naming format: `<number>_<page_name>.svg`## 4. Icon Usage-Four approaches: **A: Emoji** (`<text>🚀</text>`) | **B: AI-generated** (SVG basic shapes) | **C: Built-in library** (`templates/icons/` 11000+ icons, recommended) | **D: Custom** (user-specified)+Strategist chooses the icon approach and approved inventory. Executor only implements the approved choice. Built-in library details and the one-library rule are documented in [`../templates/icons/README.md`](../templates/icons/README.md); this section defines the SVG placeholder syntax.**Built-in icons — Placeholder method (recommended)**:@@ -134,20 +134,6 @@ Four approaches: **A: Emoji** (`<text>🚀</text>`) | **B: AI-generated** (SVG b>> No need to manually run `embed_icons.py`; `finalize_svg.py` post-processing tool will auto-embed icons.-**Five icon libraries** — four stylistic + one brand-logo:--| Library | Style | Count | Prefix | When to use |-|---------|-------|-------|--------|-------------|-| `chunk` | fill · straight-line geometry (sharp corners, rectilinear) | 640 | `chunk/` | ✅ **Default** — most scenarios |-| `tabler-filled` | fill · bezier-curve forms (smooth, rounded contours) | 1000+ | `tabler-filled/` | When design calls for smooth, rounded, organic icon forms |-| `tabler-outline` | stroke/line | 5000+ | `tabler-outline/` | Screen-only decks needing a light, elegant aesthetic |-| `phosphor-duotone` | duotone · single color + 0.2-opacity backplate | 1200+ | `phosphor-duotone/` | Modern SaaS / fintech / product launches — soft depth without solid weight |-| `simple-icons` | **brand logos** (real company / product marks) | 3400+ | `simple-icons/` | Brand-logo inset — see exception rule below |--> ⚠️ **One presentation = one stylistic library** — pick `chunk` / `tabler-filled` / `tabler-outline` / `phosphor-duotone` and use it exclusively for all generic icons (home, chart, users, etc.). If the chosen library lacks an exact icon, find the closest available alternative within that same library.->-> **Brand-logo exception (`simple-icons`)**: `simple-icons` is NOT a stylistic library and does NOT participate in the "one library" rule. Use it **alongside** the chosen stylistic library, but **only** for real company / product / service brand marks (customer logos, tech-stack icons, social handles). Do **not** use `simple-icons` to substitute for a missing icon in the primary library — that's still a violation.-**Searching for icons** — use terminal, zero token cost:```bashls skills/ppt-master/templates/icons/chunk/ | grep home@@ -209,15 +195,16 @@ When the Design Spec includes a **VII. Visualization Reference List**, read the## 6. Image Handling-Handle images based on their status in the Design Specification's "Image Resource List":+Handle images based on their status in the Design Specification's "Image Resource List". Status names and lifecycle are defined in [`svg-image-embedding.md`](svg-image-embedding.md).| Status | Source | Handling ||--------|--------|----------|| **Existing** | User-provided | Reference images directly from `../images/` directory |-| **AI-generated** | Generated by Image_Generator | Images already in `../images/`, reference directly |+| **Generated** | Generated by Image_Generator | Reference images directly from `../images/` directory |+| **Needs-Manual** | Generation failed and file is absent | Use dashed border placeholder unless the expected file exists || **Placeholder** | Not yet prepared | Use dashed border placeholder |-**Reference**: `<image href="../images/xxx.png" ... preserveAspectRatio="xMidYMid slice"/>`+**Reference syntax**: see [`svg-image-embedding.md`](svg-image-embedding.md).**Placeholder**: Dashed border `<rect stroke-dasharray="8,4" .../>` + description text@@ -289,7 +276,7 @@ Automatically split `notes/total.md` into individual speaker note files in the `> **Auto-continuation**: After Visual Construction Phase (all SVG pages) and Logic Construction Phase (all notes) are complete, the Executor proceeds directly to the post-processing pipeline.-**Post-processing & Export** (see [shared-standards.md](shared-standards.md)):+**Post-processing & Export** (same canonical pipeline as [shared-standards.md §5](shared-standards.md)):```bash# 1. Split speaker notesdiff --git a/skills/ppt-master/references/image-generator.md b/skills/ppt-master/references/image-generator.mdindex cf566d8a..7f1645e7 100644--- a/skills/ppt-master/references/image-generator.md+++ b/skills/ppt-master/references/image-generator.md@@ -28,6 +28,8 @@ Receive the "Image Resource List" from the Design Specification & Content Outlin|----------|-----------|---------|------|--------|----------------------|| cover_bg.png | 1920x1080 | Cover background | Background | Pending | Modern tech abstract background, deep blue gradient |+ Status values are defined in [`svg-image-embedding.md`](svg-image-embedding.md). Image_Generator consumes only `Pending` rows and changes them to `Generated` or `Needs-Manual`.+### Output| Deliverable | Path / Description | Requirements |@@ -35,7 +37,7 @@ Receive the "Image Resource List" from the Design Specification & Content Outlin| Prompt document | `project/images/image_prompts.md` | **Must** be saved using file write tool — cannot just be output in conversation || Optimized prompts | Individual prompt per image | Directly usable with AI image generation tools; doubles as alt text || Image files | `project/images/` directory | Named per the resource list filenames |-| Updated list | Status changes | `Pending` → `Generated` (success) or `Pending` → `Needs-Manual` (generation attempted and failed) |+| Updated list | Status changes | `Pending` -> `Generated` (success) or `Pending` -> `Needs-Manual` (generation attempted and failed) |---@@ -328,7 +330,7 @@ If the user chooses to generate manually on a platform that watermarks outputs (- Agent must NOT claim an image is generated without producing an actual file at the expected path- Agent must NOT mark an image as `Needs-Manual` without a real generation attempt having failed-- Status transitions are evidence-driven: `Pending` → `Generated` (file exists at expected path) or `Pending` → `Needs-Manual` (generation attempted and failed after one retry)+- Status transitions are evidence-driven: `Pending` -> `Generated` (file exists at expected path) or `Pending` -> `Needs-Manual` (generation attempted and failed after one retry)### 4.4 Verification Phasediff --git a/skills/ppt-master/references/image-layout-spec.md b/skills/ppt-master/references/image-layout-spec.mdindex 690810cb..ffb0f8bb 100644--- a/skills/ppt-master/references/image-layout-spec.md+++ b/skills/ppt-master/references/image-layout-spec.md@@ -182,9 +182,22 @@ Image positions:----## SVG Image Embedding Code+## Handoff Fields-### Complete Display (recommended for data charts)+This spec only defines layout calculation. Write the computed layout fields into the Image Resource List defined in [`svg-image-embedding.md`](svg-image-embedding.md):++| Field | Meaning |+|-------|---------|+| `Ratio` | Original image width / height |+| `Layout plan` | Top-bottom / left-right / grid, including split ratio when relevant |+| `Image area` | Computed display rectangle size |+| `Text area` | Computed remaining text area size |++For SVG `<image>` syntax, path rules, `preserveAspectRatio`, external references, and Base64 embedding, use [`svg-image-embedding.md`](svg-image-embedding.md).++### SVG Image Embedding Examples++Complete display, recommended for data charts and side-by-side images where content must not be cropped:```xml<image href="../images/xxx.png"@@ -192,7 +205,7 @@ Image positions:preserveAspectRatio="xMidYMid meet"/>```-### Crop-to-Fill (backgrounds only)+Crop-to-fill, for backgrounds and hero images only:```xml<image href="../images/bg.png"@@ -202,25 +215,6 @@ Image positions:----## Image Resource List Template--In the Design Specification & Content Outline, the image resource list must include:--| Field | Description | Example |-|-------|-------------|---------|-| Filename | Image filename | `p12_0.png` |-| Original dimensions | Width x Height | 1524x968 |-| Ratio | Width / Height | 1.57 |-| Page | Usage page number | Page 5 |-| Type | Visual type | Background / Photography / Illustration / Diagram / Decorative |-| Layout plan | Top-bottom/Left-right + split ratio | Top-bottom 6:4 or Left-right 7:3 |-| Image area | Image display dimensions | 1160x420 or 780x446 |-| Text area | Remaining space dimensions | 1160x200 or 360x600 |--**The Type field is used by Image_Generator to select the appropriate prompt strategy.**------## Automation Tool```bashdiff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.mdindex 93f3d756..4ca4a8f4 100644--- a/skills/ppt-master/references/strategist.md+++ b/skills/ppt-master/references/strategist.md@@ -88,15 +88,9 @@ Proactively provide a color scheme (HEX values) based on content characteristics| **C** | Built-in icon library | Professional scenarios (recommended) || **D** | Custom icons | Has brand assets |-Built-in library contains 11000+ icons across five libraries — four stylistic + one brand-logo:+The built-in icon library contains multiple stylistic libraries plus a brand-logo library:-| Library | Style | Count | Prefix | When to use |-|---------|-------|-------|--------|-------------|-| `chunk` | fill · straight-line geometry (sharp corners, rectilinear) | 640 | `chunk/` | Sharp, structured, engineered feel |-| `tabler-filled` | fill · bezier-curve forms (smooth, rounded contours) | 1000+ | `tabler-filled/` | Warm, rounded, organic feel |-| `tabler-outline` | stroke/line | 5000+ | `tabler-outline/` | Light, elegant, screen-only aesthetic |-| `phosphor-duotone` | duotone · single color + 0.2-opacity backplate | 1200+ | `phosphor-duotone/` | Soft depth without solid weight — modern SaaS / fintech / product launches |-| `simple-icons` | **brand logos** (real company / product marks) | 3400+ | `simple-icons/` | Brand-logo inset — coexists with the chosen stylistic library, never replaces it |+See [`../templates/icons/README.md`](../templates/icons/README.md) for the current library inventory, counts, prefixes, and SVG placeholder details.> **Mandatory rules when choosing C**:> 1. **Pick exactly one stylistic library based on content tone** (reference mappings — not hard rules):@@ -209,7 +203,7 @@ Selection principle: Baseline choice is driven by **content density**, not desig| Layout suggestion | e.g., `Wide landscape (suitable for full-screen/illustration)` || Purpose | e.g., `Cover background` || Type | Background / Photography / Illustration / Diagram / Decorative pattern |-| Status | Pending generation / Existing / Placeholder |+| Status | Initial status must be `Pending`, `Existing`, or `Placeholder`; see [`svg-image-embedding.md`](svg-image-embedding.md) for the full status enum || Generation description | Fill in detailed description for AI generation |**Generation description quality guide** — the description is the seed for Image_Generator's prompt, so specificity matters:@@ -260,7 +254,7 @@ Core logic (side-by-side only): the container's aspect ratio must closely match> **Multi-image slides**: When multiple images appear on one page, use the grid formulas in the "Multi-Image Layout" section of `references/image-layout-spec.md`.-> **Pipeline handoff**: When C) AI generation is selected, after outputting the design spec, prompt the user to invoke Image_Generator. Once images are collected in `images/`, proceed to Executor.+> **Pipeline handoff**: When C) AI generation is selected, Image_Generator consumes `Pending` rows and updates them to `Generated` or `Needs-Manual` before Executor proceeds. Status names are defined in [`svg-image-embedding.md`](svg-image-embedding.md).### Visualization Reference (Non-blocking — Strategist recommends, no user confirmation needed)diff --git a/skills/ppt-master/references/svg-image-embedding.md b/skills/ppt-master/references/svg-image-embedding.mdindex 80c55f45..78b33f50 100644--- a/skills/ppt-master/references/svg-image-embedding.md+++ b/skills/ppt-master/references/svg-image-embedding.md@@ -8,23 +8,25 @@ Technical specifications and recommended workflow for adding images to SVG files## Image Resource List Format-Defined in the Design Specification & Content Outline; each image has a status annotation. If the image approach includes "B) User-provided", you must run `analyze_images.py` immediately after the Strategist completes the Eight Confirmations, and complete the list before outputting the design spec.+Defined in the Design Specification & Content Outline; each image has a status annotation. This file is the authority for image status names and SVG image embedding behavior. If the image approach includes "B) User-provided", run `analyze_images.py` immediately after the Strategist completes the Eight Confirmations, and complete the list before outputting the design spec.```markdown-| Filename | Dimensions | Purpose | Status | Generation Description |-|----------|-----------|---------|--------|----------------------|-| cover_bg.png | 1280x720 | Cover background | Pending | Modern tech abstract background, deep blue gradient |-| product.png | 600x400 | Page 3 | Existing | - |-| team.png | 600x400 | Page 5 | Placeholder | Team collaboration scene (to be added later) |+| Filename | Dimensions | Purpose | Type | Status | Generation Description |+|----------|------------|---------|------|--------|------------------------|+| cover_bg.png | 1280x720 | Cover background | Background | Pending | Modern tech abstract background, deep blue gradient |+| product.png | 600x400 | Page 3 product photo | Photography | Existing | - |+| team.png | 600x400 | Page 5 team scene | Illustration | Placeholder | Team collaboration scene to be added later |```-### Three Status Types+### Image Status Enum| Status | Meaning | Executor Handling ||--------|---------|-------------------|-| **Pending** | Needs AI generation, has description | Generate image first into `images/`, then reference with `<image>` |+| **Pending** | Needs AI generation, has a generation description | Image_Generator must attempt generation before Executor; should not remain in the list after Step 5 |+| **Generated** | AI-generated file exists at the expected path | Reference directly from `../images/` |+| **Needs-Manual** | Generation was attempted once plus one retry and failed | Use a dashed placeholder unless the user has manually supplied the expected file || **Existing** | User already has image | Place in `images/`, reference with `<image>` |-| **Placeholder** | Not yet processed | Use dashed border placeholder; replace later |+| **Placeholder** | Image intentionally not prepared yet | Use dashed border placeholder; replace later |---@@ -32,14 +34,12 @@ Defined in the Design Specification & Content Outline; each image has a status a```1. Strategist defines image needs → Add image resource list, annotate each status-2. Image preparation (pending/existing) → Place in project/images/+2. Image preparation (Pending / Existing) → Place available files in project/images/3. Executor generates SVGs (svg_output/)- ├── Existing/Pending → <image href="../images/xxx.png" .../>- └── Placeholder → Dashed border + description text+ ├── Existing / Generated → <image href="../images/xxx.png" .../>+ └── Placeholder / Needs-Manual without file → Dashed border + description text4. Preview: python3 -m http.server -d <project_path> 8000 → /svg_output/<filename>.svg-5. Post-processing & Export- ├── python3 scripts/finalize_svg.py <project_path>- └── python3 scripts/svg_to_pptx.py <project_path> -s final+5. Post-processing & Export → follow shared-standards.md §5```> Recommended: During generation, keep external references in `svg_output/`. Post-processing via `finalize_svg.py` auto-embeds images into `svg_final/`, then export PPTX from `svg_final/`.@@ -114,11 +114,11 @@ python3 -m http.server -d <project_path> 8000## Conversion Process-### Recommended: Use finalize_svg.py (Unified Pipeline)+Use the unified post-processing pipeline in [shared-standards.md §5](shared-standards.md). It runs `finalize_svg.py` before export so image references from `svg_output/` become embedded assets in `svg_final/`.```bash-python3 scripts/finalize_svg.py <project_path> # Icons, images, text, rounded rects — all in one pass-python3 scripts/svg_to_pptx.py <project_path> -s final # Export PPTX from final version+python3 scripts/finalize_svg.py <project_path>+python3 scripts/svg_to_pptx.py <project_path> -s final```### Standalone: embed_images.py (Advanced Usage)@@ -157,14 +157,9 @@ project/### Rounded Corner / Non-rectangular Image Cropping-`clipPath` **on `<image>` elements** is conditionally allowed — the converter maps qualifying clip shapes to native DrawingML picture geometry (`<a:prstGeom>` / `<a:custGeom>`), so rounded corners, circular avatars, hexagonal portraits, etc. are fully supported end-to-end.+`clipPath` **on `<image>` elements** is conditionally allowed. The authoritative constraints are in [shared-standards.md §1.2](shared-standards.md); do not restate or relax them here.-Constraints (see [shared-standards.md §1.2](shared-standards.md) for the authoritative list):-- The `<clipPath>` must live inside `<defs>` and contain exactly **one** shape child — `circle`, `ellipse`, `rect` with `rx`/`ry`, `path`, or `polygon`.-- `clip-path` may appear **only** on `<image>` elements. Using it on shapes / groups / text is an error — draw the target geometry directly with the matching native element (`<circle>` / `<ellipse>` / `<rect rx="...">` / `<polygon>` / `<path>`). A rect clipped to a circle is just a `<circle>`.-- PowerPoint's own SVG renderer does not render `clipPath` correctly. The Native PPTX converter handles it, but the SVG reference version in the `_svg.pptx` backup will display the image uncropped.--Alternative for the rare case where `clipPath` does not fit (e.g. shape needs clipping): bake the rounded corners into the source image (PNG with alpha) before embedding.+Alternative for the rare case where `clipPath` does not fit: bake the rounded corners into the source image (PNG with alpha) before embedding.---