powerpoint-generator（幻灯片生成器）

PPT Agent -- Professional Full-Process Presentation Generation

Core Philosophy

Mimics the complete workflow of a professional PPT design company (priced at 10,000+ RMB per page), not "give an outline and apply a template":

1. Research before generation -- Fill content with real data, never fabricate
2. Separate planning from design -- Verify information structure first, then apply visual packaging
3. Content-driven layout -- Bento Grid card-style layout, each page's layout determined by its content
4. Consistent global style -- Lock in style first, then generate page by page, ensuring cross-page consistency
5. Smart illustrations -- Use image generation capabilities to add illustrations for each page (available in most environments)

Environment Setup [Required for First Use]

Node.js Environment

China Mainland mirror installation (must set, otherwise puppeteer Chrome binary download will fail):

export PUPPETEER_DOWNLOAD_HOST=https://storage.googleapis.com.cnpmjs.org
npm install -g puppeteer --unsafe-perm
npm install -g dom-to-svg esbuild

Verification: node -e "require('puppeteer'); console.log('puppeteer OK')"

If full puppeteer fails to install (Chrome download blocked in China mainland), scripts will automatically fall back to puppeteer-core with system Chrome at /usr/bin/google-chrome. You can also install it directly:

npm install -g puppeteer-core

Python Environment

pip install python-pptx lxml Pillow

Pipeline Mandatory Declaration [Red Lines]

The following rules must not be violated. Any bypass will cause severe degradation in output quality.

Six-Step Pipeline Order is Fixed, No Skipping

Step 1 → Step 2 → Step 3 → Step 4 → Step 5 → Step 6

Prohibited Behaviors

• ❌ Skip Step 1 and directly generate PPT
• ❌ Enter Step 5c without a planning draft
• ❌ Stop at preview.html without executing SVG and PPTX
• ❌ Use other tools/pipelines to replace this workflow

Only Allowed Degradation

• Node.js unavailable → Skip SVG branch, output preview.html only. Notify user.
• Python unavailable → Skip SVG + PNG + PPTX branches, output preview.html only. Notify user and wait for feedback.
• Puppeteer unavailable → Skip PNG branch (visual QA also skipped). SVG branch continues.
• Vision model unavailable → Skip visual audit in visual_qa.py, DOM assertion still runs.

Step Enforcement Levels

Environment Awareness

Self-reflect on the agent's tool capabilities before starting work:

Principle: Check the actually callable tool list, use whatever is available.

Path Conventions

Paths used repeatedly throughout the process. Determine immediately after Step 1:

All subsequent paths are based on these two variables and will not be explained again.

Input Modes and Complexity Assessment

Entry Detection

Skip Rules

When skipping pre-requisite steps, must complete corresponding dependent outputs:

Complexity Adaptation

Automatically adjust process granularity based on target page count:

Breakpoint Recovery

The workflow is stateless. After interruption, the Main Agent scans existing artifacts on disk to determine the recovery point automatically.

Recovery Logic

def find_recovery_point(run_dir: Path) -> str:
    """Scan existing artifacts to determine recovery point."""
    milestones = [
        ("presentation-svg.pptx", "P5-SVG-DONE"),
        ("presentation-png.pptx", "P5-PNG-DONE"),
        ("png/slide-*.png", "P4-VisualQA-DONE"),
        ("slides/slide-*.html", "P4-PAGE-DONE"),
        ("style.json", "P3.5-STYLE-LOCKED"),
        ("outline.txt", "P3-OUTLINE-DONE"),
        ("search.txt", "P2-SEARCH-DONE"),
        ("requirements-interview.txt", "P1-REQUIREMENTS-DONE"),
    ]
    for pattern, step in reversed(milestones):
        matches = list(run_dir.glob(pattern))
        if matches:
            return step
    return "P0-START"

Recovery Rules

Artifact Existence = Milestone Reached

Subagent Scheduling (Subagent Dispatch)

Each stage has a dedicated Subagent to avoid Context pollution. Context isolation ensures each Subagent only carries its own stage's information.

Subagent Architecture

Main Agent (Decision + Dispatch)
    │
    ├── ResearchAgent ──→ search.txt
    │       Model: MUST pass --model parameter
    │
    ├── OutlineAgent ──→ outline.txt
    │       Model: MUST pass --model parameter
    │
    ├── StyleAgent ──→ style.json
    │       Model: MUST pass --model parameter
    │
    ├── PlanningAgent ──→ planning-N.json (per page)
    │       Model: MUST pass --model parameter
    │
    ├── PageAgent-1 ──→ slide-1.html (parallel)
    ├── PageAgent-2 ──→ slide-2.html (parallel)
    │         ... (all pages parallel)
    └── PageAgent-N ──→ slide-N.html (parallel)
        Model: MUST pass --model parameter for each

Main Agent ← All Subagents complete ← Step 6 Post-processing

Subagent Rules

Artifact Naming Convention

6-Step Pipeline

Step 1: Requirements Interview [STOP -- Cannot Skip]

Cannot skip. No matter how simple the topic, must ask questions and wait for user reply before continuing. Do not make decisions for the user.

Execute: Use references/prompts.md Prompt #1

1. Search topic background information (3-5 items)
2. Based on complexity, choose full 7 questions or abbreviated 3 questions, send to user in one go
3. Wait for user reply (blocking point)
4. Organize into requirements JSON

7-Question Three-Tier Structure (light mode only asks questions 1, 2, 7):

Output: Requirements JSON (topic + requirements)

Step 2: Information Gathering

Take inventory of all information retrieval capabilities and use them all.

Execute:

1. Plan queries based on topic (quantity reference complexity table)
2. Use all available information retrieval tools for parallel search
3. Summarize each group of results

Output: Search results collection JSON

Step 3: Outline Planning

Execute: Use references/prompts.md Prompt #2 (Outline Architect v2.0)

Methodology: Pyramid Principle -- Conclusion first, above to below, categorize and group, logical progression

Self-check: Page count meets requirements / each part >= 2 pages / key points have data support

Output: [PPT_OUTLINE] JSON

Step 4: Content Allocation + Planning Draft [Cannot Skip -- Must Wait for User Confirmation of Outline]

Combine content allocation and planning draft generation into one step. While thinking about what content each page should have, also decide layout and card types, making it more natural and efficient.

Execute: Use references/prompts.md Prompt #3 (Content Allocation and Planning Draft)

Key Points:

• Precisely map search materials to each page
• Design multi-layer content structure for each page (main card 40-100 chars + data highlight + supporting points)
• Also determine page_type / layout_hint / cards[] structure
• Each content page at least 3 cards + 2 card_types + 1 data card
• Layout selection reference references/bento-grid.md decision matrix

Show planning draft overview to user, recommend waiting for user confirmation before entering Step 5.

Output: Per-page planning card JSON array -> Save as OUTPUT_DIR/planning.json

Step 5: Style Decision + Design Draft Generation

Split into three sub-steps, order cannot be reversed:

5a. Style Decision

Execute: Read references/style-system.md, select or infer style

Match one of 8 preset styles based on topic keywords (dark tech / xiaomi orange / blue white business / royal red / fresh green / luxury purple / minimal gray / vibrant rainbow), detailed matching rules and full JSON definitions in references/style-system.md.

Output: Style definition JSON -> Save as OUTPUT_DIR/style.json

5b. Smart Illustrations [Execute Based on Step 1 Question 7 Answer]

If user selected "no illustrations needed" in Step 1, skip this entire section.

Step 1 Answer Routing:

Illustration Timing

Before generating each page's HTML, generate that page's illustration first. At least 1 per page (cover page, section cover must have), save to OUTPUT_DIR/images/.

⚠️ Image Path Rule -- MUST FOLLOW: All images must be downloaded to OUTPUT_DIR/images/ before generating HTML. Use <img src="images/xxx.png"> with relative paths in HTML. Never reference external URLs (Unsplash etc.) directly in HTML -- they cannot load under file:// protocol.

Degradation Chain (automatic degradation, no need to ask user again):

AI generation (image_generate)
  └─ Tool available → Generate image
  └─ Tool unavailable/failed → Unsplash API
                                 └─ Key configured → Search and get
                                 └─ Key not configured/failed → Pure CSS decoration degradation

User provides images
  └─ Path valid and semantically matches → Use that image
  └─ Path invalid/semantically mismatched → Degrade to Unsplash or CSS decoration

Unsplash
  └─ UNSPLASH_ACCESS_KEY configured → Call API
  └─ Key not configured/failed → Pure CSS decoration degradation

Image Quantity by Page Type:

Output: Illustration files under OUTPUT_DIR/images/ (if any)

image_generate Prompt Construction Formula

Prompt must satisfy 4 dimensions simultaneously, assembled by formula:

[Content Topic] + [Visual Style] + [Image Composition] + [Technical Constraints]

Style and Illustration Keyword Mapping

Adjustment by Page Type

Prohibited Items

• No text in images (AI-generated text quality is poor)
• No colors conflicting with page color scheme (dark theme with dark images, light theme with light images)
• No irrelevant decorative images (every image must be semantically related to that page's content)
• No duplicate prompts (each page's image must be unique)

Output: Illustration files under OUTPUT_DIR/images/

5c. PageAgent Parallel Generation

Cannot skip planning draft and directly generate. Each page must first have Step 4's structure JSON.

Parallel Scheduling: All pages are generated in parallel via PageAgent-N subagents. Each PageAgent is responsible for one page only.

Parallel Strategy:

PageAgent Workflow:

PageAgent-N
    │
    ├── 1. Read planning-N.json
    ├── 2. Read style.json
    ├── 3. Read images/planning-N.png (if exists)
    ├── 4. Generate slide-N.html
    ├── 5. DOM self-check (overflow / pseudo-elements / hardcoded colors)
    └── 6. Output: --- PAGE N COMPLETE ---

Failure Handling:

• Single page failure does not affect other pages
• Failed page enters PagePatchAgent retry queue (max 2 retries)
• Main Agent waits for all PageAgents to complete before proceeding to Step 6

Per-Page Prompt Assembly Formula:

Prompt #4 template
+ Style definition JSON (5a output) [required]
+ That page's planning draft JSON (Step 4 output, containing cards[]/card_type/position/layout_hint) [required]
+ That page's content text (Step 4 output) [required]
+ Illustration path (5b output) [optional -- omit IMAGE_INFO block when no illustration]

Core Design Constraints (complete checklist in Prompt #4):

• Canvas 1280x720px, overflow:hidden
• All colors referenced via CSS variables, no hardcoding
• All visually visible elements must be real DOM nodes, graphics prefer inline SVG
• Prohibited: ::before/::after pseudo-elements for visual decoration, conic-gradient, CSS border triangles
• Illustration integration: fade blend / tinted overlay / ambient background / crop viewport / circular crop (techniques in Prompt #4)

Cross-Page Visual Narrative:

Output: One HTML file per page -> OUTPUT_DIR/slides/

Step 6: Post-Processing [Must Do -- Execute Immediately After HTML Generation]

Cannot skip, must execute. After HTML generation, must immediately execute the following pipeline steps.

slides/*.html
  ├── html_packager.py --> preview.html
  ├── html2svg.py --> svg/*.svg --> svg2pptx.py --> presentation-svg.pptx
  └── html2png.py --> png/*.png --> png2pptx.py --> presentation-png.pptx

Dependency check (auto-execute on first run):

pip install python-pptx lxml Pillow 2>/dev/null
npm install puppeteer dom-to-svg 2>/dev/null

Execute in order:

1. Merge Preview -- Run html_packager.py

   python SKILL_DIR/scripts/html_packager.py OUTPUT_DIR/slides/ -o OUTPUT_DIR/preview.html

1. SVG Conversion -- Run html2svg.py (DOM direct to SVG, preserves editable <text>)

> Important: HTML design drafts must comply with pipeline compatibility rules in references/pipeline-compat.md, otherwise element loss and position misalignment will occur after conversion.

   python SKILL_DIR/scripts/html2svg.py OUTPUT_DIR/slides/ -o OUTPUT_DIR/svg/

Uses dom-to-svg underneath (auto-installs), esbuild bundles on first run. Degradation: If dom-to-svg installation fails, SVG branch will abort and notify user. PNG branch continues independently.

1. SVG PPTX Export -- Run svg2pptx.py (OOXML native SVG embedding, PPT 365 editable)

   python SKILL_DIR/scripts/svg2pptx.py OUTPUT_DIR/svg/ -o OUTPUT_DIR/presentation-svg.pptx --html-dir OUTPUT_DIR/slides/

In PPT 365, right-click image -> "Convert to Shape" to edit text and shapes.

1. PNG Screenshot -- Run html2png.py (Puppeteer screenshot, parallel execution)

   python SKILL_DIR/scripts/html2png.py OUTPUT_DIR/slides/ -o OUTPUT_DIR/png/ --concurrency 4

Uses Puppeteer for pixel-perfect screenshots. Concurrency controls parallel screenshot threads. Degradation: If Node.js/Puppeteer unavailable, skip PNG branch entirely.

1. PNG PPTX Export -- Run png2pptx.py (PNG as background, cross-platform 100% visual fidelity)

   python SKILL_DIR/scripts/png2pptx.py OUTPUT_DIR/png/ -o OUTPUT_DIR/presentation-png.pptx

PNG fills each slide as background. Text is not editable but visuals are pixel-perfect.

1. Notify User -- Inform output location and usage:

- preview.html -- Open in browser for paginated preview - presentation-svg.pptx -- PPTX with editable text and shapes (SVG vectors) - presentation-png.pptx -- PPTX with pixel-perfect visuals (PNG backgrounds, text not editable) - svg/ -- Each SVG can also be dragged individually into PPT - png/ -- PNG screenshots (for Visual QA reference) - If SVG branch was skipped, explain reason and tell user they can install Node.js and rerun - If PNG branch was skipped, note that PNG screenshots are used for Visual QA only

Output: preview.html + svg/*.svg + png/*.png + presentation-svg.pptx + presentation-png.pptx

Output Directory Structure

ppt-output/
  slides/                  # Per-page HTML
  svg/                     # Vector SVG (importable into PPT for editing)
  png/                     # PNG screenshots (for Visual QA + PNG PPTX export)
  images/                  # AI illustrations
  preview.html             # Paginated preview
  presentation-svg.pptx    # Editable PPTX (SVG vectors, PPT 365 "Convert to Shape")
  presentation-png.pptx    # Pixel-perfect PPTX (PNG backgrounds, not editable)
  outline.json             # Outline
  planning.json            # Planning draft
  style.json               # Style definition

Quality Self-Check

Reference File Index