Skill: vincentlau2046-sudo/pptx-master (version 1.2.3)

--- name: pptx-master description: >- 专业级 AI 驱动 SVG 内容生成系统。支持 PDF/DOCX/URL/Markdown 转换为原生可编辑的 PPTX。 多角色协作流程，输出高质量演示文稿，适合财报分析、技术汇报、商业演示等专业场景。 版本 v1.2.3，新增 XML 实体自动转义（修复孤立 & 符号导致解析失败），支持 HUAWEI、red grey 等新模板。 read_when: - 用户说"生成 PPT"、"做 PPT"、"制作演示文稿"、"做个 PPT" - 用户提供 PDF 文件要求转换成 PPT - 用户提供 DOCX/Word 文档要求转换成 PPT - 用户提供 URL 要求提取内容生成 PPT - 用户需要专业演示文稿（财报、技术汇报、商业演示） - 用户明确要求"原生可编辑"、"可修改"的 PPT - 用户提到"pptx-master"、"ppt pro" metadata: openclaw: emoji: 📊 priority: high category: content-generation tags: - ppt - presentation - slides - 演示文稿 conflicts_with: - ppt-video - fireworks-tech-graph clawhub: license: MIT-0 tags: latest=1.2.3 --- # PPT Master Skill > AI-driven multi-format SVG content generation system. Converts source documents into high-quality SVG pages through multi-role collaboration and exports to PPTX. **Core Pipeline**: `Source Document → Create Project → Template Option → Strategist → [Image_Generator] → Executor → Post-processing → Export` > [!CAUTION] > ## 🚨 Global Execution Discipline (MANDATORY) > > **This workflow is a strict serial pipeline. The following rules have the highest priority — violating any one of them constitutes execution failure:** > > 1. **SERIAL EXECUTION** — Steps MUST be executed in order; the output of each step is the input for the next. Non-BLOCKING adjacent steps may proceed continuously once prerequisites are met, without waiting for the user to say "continue" > 2. **BLOCKING = HARD STOP** — Steps marked ⛔ BLOCKING require a full stop; the AI MUST wait for an explicit user response before proceeding and MUST NOT make any decisions on behalf of the user > 3. **NO CROSS-PHASE BUNDLING** — Cross-phase bundling is FORBIDDEN. (Note: the Eight Confirmations in Step 4 are ⛔ BLOCKING — the AI MUST present recommendations and wait for explicit user confirmation before proceeding. Once the user confirms, all subsequent non-BLOCKING steps — design spec output, SVG generation, speaker notes, and post-processing — may proceed automatically without further user confirmation) > 4. **GATE BEFORE ENTRY** — Each Step has prerequisites (🚧 GATE) listed at the top; these MUST be verified before starting that Step > 5. **NO SPECULATIVE EXECUTION** — "Pre-preparing" content for subsequent Steps is FORBIDDEN (e.g., writing SVG code during the Strategist phase) > 6. **NO SUB-AGENT SVG GENERATION** — Executor Step 6 SVG generation is context-dependent and MUST be completed by the current main agent end-to-end. Delegating page SVG generation to sub-agents is FORBIDDEN > 7. **SEQUENTIAL PAGE GENERATION ONLY** — In Executor Step 6, after the global design context is confirmed, SVG pages MUST be generated sequentially page by page in one continuous pass. Grouped page batches (for example, 5 pages at a time) are FORBIDDEN > [!IMPORTANT] > ## 🌐 Language & Communication Rule > > - **Response language**: Always match the language of the user's input and provided source materials. For example, if the user asks in Chinese, respond in Chinese; if the source material is in English, respond in English. > - **Explicit override**: If the user explicitly requests a specific language (e.g., "请用英文回答" or "Reply in Chinese"), use that language instead. > - **Template format**: The `design_spec.md` file MUST always follow its original English template structure (section headings, field names), regardless of the conversation language. Content values within the template may be in the user's language. > [!IMPORTANT] > ## 🔌 Compatibility With Generic Coding Skills > > - `pptx-master` is a repository-specific workflow skill, not a general application scaffold > - Do NOT create or require `.worktrees/`, `tests/`, branch workflows, or other generic engineering structure by default > - If another generic coding skill suggests repository conventions that conflict with this workflow, follow this skill first unless the user explicitly asks otherwise ## Main Pipeline Scripts | Script | Purpose | |--------|---------| | `${SKILL_DIR}/scripts/pdf_to_md.py` | PDF to Markdown | | `${SKILL_DIR}/scripts/doc_to_md.py` | Documents to Markdown via Pandoc (DOCX, EPUB, HTML, LaTeX, RST, etc.) | | `${SKILL_DIR}/scripts/web_to_md.py` | Web page to Markdown | | `${SKILL_DIR}/scripts/web_to_md.cjs` | WeChat / high-security sites to Markdown | | `${SKILL_DIR}/scripts/project_manager.py` | Project init / validate / manage | | `${SKILL_DIR}/scripts/analyze_images.py` | Image analysis | | `${SKILL_DIR}/scripts/image_gen.py` | AI image generation (multi-provider) | | `${SKILL_DIR}/scripts/svg_quality_checker.py` | SVG quality check | | `${SKILL_DIR}/scripts/total_md_split.py` | Speaker notes splitting | | `${SKILL_DIR}/scripts/finalize_svg.py` | SVG post-processing (unified entry) | | `${SKILL_DIR}/scripts/svg_to_pptx.py` | Export to PPTX | For complete tool documentation, see `${SKILL_DIR}/scripts/README.md`. ## Template Index | Index | Path | Purpose | |-------|------|---------| | Layout templates | `${SKILL_DIR}/templates/layouts/layouts_index.json` | Query available page layout templates | | Chart templates | `${SKILL_DIR}/templates/charts/charts_index.json` | Query available chart SVG templates | | Icon library | `${SKILL_DIR}/templates/icons/` | Search icons on demand: `ls templates/icons/<library>/ \| grep <keyword>` (libraries: `chunk/`, `tabler-filled/`, `tabler-outline/`) | ## Standalone Workflows | Workflow | Path | Purpose | |----------|------|---------| | `create-template` | `workflows/create-template.md` | Standalone template creation workflow | --- ## Workflow ### Step 1: Source Content Processing 🚧 **GATE**: User has provided source material (PDF / DOCX / EPUB / URL / Markdown file / text description / conversation content — any form is acceptable). When the user provides non-Markdown content, convert immediately: | User Provides | Command | |---------------|---------| | PDF file | `python3 ${SKILL_DIR}/scripts/pdf_to_md.py <file>` | | DOCX / Word / Office document | `python3 ${SKILL_DIR}/scripts/doc_to_md.py <file>` | | EPUB / HTML / LaTeX / RST / other | `python3 ${SKILL_DIR}/scripts/doc_to_md.py <file>` | | Web link | `python3 ${SKILL_DIR}/scripts/web_to_md.py <URL>` | | WeChat / high-security site | `node ${SKILL_DIR}/scripts/web_to_md.cjs <URL>` | | Markdown | Read directly | **✅ Checkpoint — Confirm source content is ready, proceed to Step 2.** --- ### Step 2: Project Initialization 🚧 **GATE**: Step 1 complete; source content is ready (Markdown file, user-provided text, or requirements described in conversation are all valid). ```bash python3 ${SKILL_DIR}/scripts/project_manager.py init <project_name> --format <format> ``` Format options: `ppt169` (default), `ppt43`, `xhs`, `story`, etc. For the full format list, see `references/canvas-formats.md`. Import source content (choose based on the situation): | Situation | Action | |-----------|--------| | Has source files (PDF/MD/etc.) | `python3 ${SKILL_DIR}/scripts/project_manager.py import-sources <project_path> <source_files...> --move` | | User provided text directly in conversation | No import needed — content is already in conversation context; subsequent steps can reference it directly | > ⚠️ **MUST use `--copy`**: All source files (original PDF / MD / images) MUST be **copied** (not moved) into `sources/` for archiving. > - Markdown files generated in Step 1, original PDFs, original MDs — **all** must be copied into the project via `import-sources --copy` > - Intermediate artifacts (e.g., `_files/` directories) are handled automatically by `import-sources` > - Original source files remain at their original location after copying **✅ Checkpoint — Confirm project structure created successfully, `sources/` contains all source files, converted materials are ready. Proceed to Step 3.** --- ### Step 3: Template Selection 🚧 **GATE**: Step 2 complete; project directory structure is ready. ⛔ **BLOCKING**: If the user has not yet clearly expressed whether to use a template, you MUST present options and **wait for an explicit user response** before proceeding. If the user has previously stated "no template" or specified a particular template, skip this prompt and proceed directly. **⚡ Early-exit**: If the user has already stated "no template" / "不使用模板" / "自由设计" (or equivalent) at any prior point in the conversation, **do NOT query `layouts_index.json`** — skip directly to Step 4. This avoids unnecessary token consumption. **Template recommendation flow** (only when the user has NOT yet decided): Query `${SKILL_DIR}/templates/layouts/layouts_index.json` to list available templates and their style descriptions. Note: New templates include HUAWEI and red grey layouts. **When presenting options, you MUST provide a professional recommendation based on the current PPT topic and content** (recommend a specific template or free design, with reasoning), then ask the user: > 💡 **AI Recommendation**: Based on your content topic (brief summary), I recommend **[specific template / free design]** because... > > Which approach would you prefer? > **A) Use an existing template** (please specify template name or style preference - note: new options include HUAWEI and red grey templates) > **B) No template** — free design After the user confirms option A, copy template files to the project directory: ```bash cp ${SKILL_DIR}/templates/layouts/<template_name>/*.svg <project_path>/templates/ cp ${SKILL_DIR}/templates/layouts/<template_name>/design_spec.md <project_path>/templates/ cp ${SKILL_DIR}/templates/layouts/<template_name>/*.png <project_path>/images/ 2>/dev/null || true cp ${SKILL_DIR}/templates/layouts/<template_name>/*.jpg <project_path>/images/ 2>/dev/null || true ``` After the user confirms option B, proceed directly to Step 4. > To create a new global template, read `workflows/create-template.md` **✅ Checkpoint — User has responded with template selection, template files copied (if option A). Proceed to Step 4.** --- ### Step 4: Strategist Phase (MANDATORY — cannot be skipped) 🚧 **GATE**: Step 3 complete; user has confirmed template selection. First, read the role definition: ``` Read references/strategist.md ``` **Must complete the Eight Confirmations** (refer to `templates/design_spec_reference.md` for the template structure): ⛔ **BLOCKING**: The Eight Confirmations MUST be presented to the user as a bundled set of recommendations, and you MUST **wait for the user to confirm or modify** before outputting the Design Specification & Content Outline. This is one of only two core confirmation points in the workflow (the other is template selection). Once confirmed, all subsequent script execution and slide generation should proceed fully automatically. 1. Canvas format 2. Page count range 3. Target audience 4. Style objective 5. Color scheme 6. Icon usage approach 7. Typography plan 8. Image usage approach If the user has provided images, run the analysis script **before outputting the design spec** (do NOT directly read/open image files — use the script output only): ```bash python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images ``` > ⚠️ **Image handling rule**: The AI must NEVER directly read, open, or view image files (`.jpg`, `.png`, etc.). All image information must come from the `analyze_images.py` script output or the Design Specification's Image Resource List. **Output**: `<project_path>/design_spec.md` **✅ Checkpoint — Phase deliverables complete, auto-proceed to next step**: ```markdown ## ✅ Strategist Phase Complete - [x] Eight Confirmations completed (user confirmed) - [x] Design Specification & Content Outline generated - [ ] **Next**: Auto-proceed to [Image_Generator / Executor] phase ``` --- ### Step 5: Image_Generator Phase (Conditional) 🚧 **GATE**: Step 4 complete; Design Specification & Content Outline generated and user confirmed. > **Trigger condition**: Image approach includes "AI generation". If not triggered, skip directly to Step 6 (Step 6 GATE must still be satisfied). Read `references/image-generator.md` 1. Extract all images with status "pending generation" from the design spec 2. Generate prompt document → `<project_path>/images/image_prompts.md` 3. Generate images (CLI tool recommended): ```bash python3 ${SKILL_DIR}/scripts/image_gen.py "prompt" --aspect_ratio 16:9 --image_size 1K -o <project_path>/images ``` **✅ Checkpoint — Confirm all images are ready, proceed to Step 6**: ```markdown ## ✅ Image_Generator Phase Complete - [x] Prompt document created - [x] All images saved to images/ ``` --- ### Step 6: Executor Phase 🚧 **GATE**: Step 4 (and Step 5 if triggered) complete; all prerequisite deliverables are ready. Read the role definition based on the selected style: ``` Read references/executor-base.md # REQUIRED: common guidelines Read references/executor-general.md # General flexible style Read references/executor-consultant.md # Consulting style Read references/executor-consultant-top.md # Top consulting style (MBB level) ``` > Only need to read executor-base + one style file. **Design Parameter Confirmation (Mandatory)**: Before generating the first SVG, the Executor MUST review and output key design parameters from the Design Specification (canvas dimensions, color scheme, font plan, body font size) to ensure spec adherence. See executor-base.md Section 2 for details. > ⚠️ **Main-agent only rule**: SVG generation in Step 6 MUST remain with the current main agent because page design depends on full upstream context (source content, design spec, template mapping, image decisions, and cross-page consistency). Do NOT delegate any slide SVG generation to sub-agents. > ⚠️ **Generation rhythm rule**: After confirming the global design parameters, the Executor MUST generate pages sequentially, one page at a time, while staying in the same continuous main-agent context. Do NOT split Step 6 into grouped page batches such as 5 pages per batch. **Visual Construction Phase**: - Generate SVG pages sequentially, one page at a time, in one continuous pass → `<project_path>/svg_output/` **Logic Construction Phase**: - Generate speaker notes → `<project_path>/notes/total.md` **✅ Checkpoint — Confirm all SVGs and notes are fully generated. Proceed directly to Step 7 post-processing**: ```markdown ## ✅ Executor Phase Complete - [x] All SVGs generated to svg_output/ - [x] Speaker notes generated at notes/total.md ``` --- ### Step 7: Post-processing & Export 🚧 **GATE**: Step 6 complete; all SVGs generated to `svg_output/`; speaker notes `notes/total.md` generated. > ⚠️ 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. **Step 7.1** — Split speaker notes: ```bash python3 ${SKILL_DIR}/scripts/total_md_split.py <project_path> ``` **Step 7.2** — SVG post-processing (icon embedding / image crop & embed / text flattening / rounded rect to path): ```bash python3 ${SKILL_DIR}/scripts/finalize_svg.py <project_path> ``` **Step 7.3** — Export PPTX (embeds speaker notes by default): ```bash python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path> -s final # Default: generates two files — native shapes (.pptx) + SVG reference (_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 > ❌ **NEVER** export directly from `svg_output/` — MUST use `-s final` to export from `svg_final/` > ❌ **NEVER** add extra flags like `--only` --- ## Role Switching Protocol Before switching roles, you **MUST first read** the corresponding reference file — skipping is FORBIDDEN. Output marker: ```markdown ## [Role Switch: <Role Name>] 📖 Reading role definition: references/<filename>.md 📋 Current task: <brief description> ``` --- ## Reference Resources | Resource | Path | |----------|------| | Shared technical constraints | `references/shared-standards.md` | | Canvas format specification | `references/canvas-formats.md` | | Image layout specification | `references/image-layout-spec.md` | | SVG image embedding | `references/svg-image-embedding.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`

path: CHANGELOG.md
content: # PPT Master 版本历史

## v1.2.3 (2026-05-07) - XML 实体自动转义

**修复内容：**

### 1. 架构级 XML 容错设计
- ✅ 新增 `escape-xml` 处理步骤（finalize_svg.py Step 1.5）
- ✅ 自动转义 SVG 中孤立的 `&` 符号
- ✅ 使用负向前瞻正则，避免重复转义已转义实体

### 2. 技术实现
- 新增函数：`escape_xml_entities(svg_file)`
- 正则模式：`r'&(?!amp;|lt;|gt;|quot;|apos;|nbsp;|#\d+;|#x[0-9a-fA-F]+;)'`
- 处理流程：复制 svg_output → svg_final 后立即执行转义
- 默认启用：`escape_xml: True`

### 3. 测试验证
- 孤立 `&` → `&amp;` ✅
- 已转义实体不被修改 ✅
- `&&` → `&amp;&amp;` ✅
- XML 语法验证通过 ✅

**根本原因：**
- 批量生产的容错设计必须在架构层解决，不能靠事后修补
- 之前的 PPT 生成任务中，SVG 包含 `&` 符号导致 XML 解析失败

**预期收益：**
- 所有 PPT 生成的 SVG 自动转义，无需人工干预
- 避免导出 PPTX 时 XML 解析错误
- 架构级预防，而非事后修补

**文件变更：**
- `scripts/finalize_svg.py` - 新增 escape_xml_entities() 和 Step 1.5
- `.learnings/LEARNINGS.md` - 记录修复过程

---

## v1.2.2 (2026-04-25) - 技能选择机制优化

**优化内容：**

### 1. YAML Front Matter 重构
- ✅ 新增独立的 `read_when` 字段，明确触发词列表
- ✅ 新增 `metadata.openclaw` 配置：
  - `priority: high` - 高优先级，在多技能匹配时优先选择
  - `category: content-generation` - 分类标签
  - `tags` - 技能标签（ppt, presentation, slides, 演示文稿）
  - `conflicts_with` - 冲突技能列表（ppt-video, fireworks-tech-graph）

### 2. 触发词明确化
- 新增 10+ 个明确的中文触发词
- 区分不同场景：
  - 直接生成："生成 PPT"、"做 PPT"、"制作演示文稿"
  - 文件转换：PDF → PPT、DOCX → PPT、URL → PPT
  - 专业场景：财报、技术汇报、商业演示
  - 特定要求："原生可编辑"、"可修改"

### 3. 中文友好
- description 改为中文优先
- 触发词以中文为主，符合用户习惯

### 4. 冲突处理
- 明确标注与 `ppt-video`、`fireworks-tech-graph` 的冲突关系
- Agent 在选择时可避免误判

**预期收益：**
- 提高技能选择准确率
- 减少技能冲突
- 优先选择 pptx-master（priority: high）
- 中文场景更友好

**文件变更：**
- `SKILL.md` - YAML front matter 重构

---

## v1.2.1 (2026-04-19) - XML Validation Enhancement

**Fixed:**
- **SVG Content Checker** now validates XML syntax before content analysis
- Detects mismatched tags (e.g., `<tspan>...</text>`)
- Catches malformed SVG that would cause rendering failures

**Technical Details:**
- Added `xml.etree.ElementTree.fromstring()` validation in `_check_content_elements()`
- XML parse errors now block the workflow with clear error messages
- Prevents false-positive "passes" on malformed SVG files

**Issue Resolved:**
- Page 7 of AI Weekly Report PPT was blank due to XML tag mismatch
- Root cause: `<tspan>` closed with `</text>` instead of `</tspan>`
- Old checker missed it because it only counted string occurrences

---

## v1.2.0 (2026-04-18) - Content Review & Auto-Repair

**Added:**
- **SVG Content Checker** (`scripts/svg_content_checker.py`)
  - Blank page detection (text elements < 2 AND file size < 500 bytes)
  - Content density scoring (0-100%)
  - Design consistency checking (colors, fonts)
  - Structure completeness evaluation
- **SVG Repair Coordinator** (`scripts/svg_repair_coordinator.py`)
  - Automatic repair workflow
  - Regeneration prompt generation for blank pages
  - Fallback to placeholder pages when repair fails
- **Step 6.5** in workflow: Content Review & Auto-Repair
  - Automatic check after SVG generation
  - Non-blocking: warnings allow continuation
  - Blocking: blank pages trigger repair workflow

**Changed:**
- `SKILL.md`: Added Step 6.5 between SVG generation and post-processing
- Tool list: Added svg_content_checker.py and svg_repair_coordinator.py

**Use Case:**
- Automatically detect blank pages before PPTX export
- Generate repair prompts for manual regeneration
- Ensure presentation quality before delivery


path: README.md
content: # PPT Master

AI-driven multi-format SVG content generation system for professional presentations.

## Version History

### v1.2.1 (2026-04-19) - XML Validation Enhancement

**Fixed:**
- **SVG Content Checker** now validates XML syntax before content analysis
- Detects mismatched tags (e.g., `<tspan>...</text>`)
- Catches malformed SVG that would cause rendering failures

**Technical Details:**
- Added `xml.etree.ElementTree.fromstring()` validation in `_check_content_elements()`
- XML parse errors now block the workflow with clear error messages
- Prevents false-positive "passes" on malformed SVG files

**Issue Resolved:**
- Page 7 of AI Weekly Report PPT was blank due to XML tag mismatch
- Root cause: `<tspan>` closed with `</text>` instead of `</tspan>`
- Old checker missed it because it only counted string occurrences

---

### v1.2.0 (2026-04-18) - Content Review & Auto-Repair

**Added:**
- **SVG Content Checker** (`scripts/svg_content_checker.py`)
  - Blank page detection (text elements < 2 AND file size < 500 bytes)
  - Content density scoring (0-100%)
  - Design consistency checking (colors, fonts)
  - Structure completeness evaluation
- **SVG Repair Coordinator** (`scripts/svg_repair_coordinator.py`)
  - Automatic repair workflow
  - Regeneration prompt generation for blank pages
  - Fallback to placeholder pages when repair fails
- **Step 6.5** in workflow: Content Review & Auto-Repair
  - Automatic check after SVG generation
  - Non-blocking: warnings allow continuation
  - Blocking: blank pages trigger repair workflow

**Changed:**
- `SKILL.md`: Added Step 6.5 between SVG generation and post-processing
- Tool list: Added svg_content_checker.py and svg_repair_coordinator.py

**Use Case:**
- Automatically detect blank pages before PPTX export
- Generate repair prompts for manual regeneration
- Ensure presentation quality before delivery

---

### v1.1.1 (2026-04-11) - Huawei Template Integration

**Added:**
- Huawei Technologies brand template (`华为技术`)
- New `enterprise` quick lookup category in template index
- Template count updated to 21

**Changed:**
- `layouts_index.json`: Added Huawei template to brand category and technology/enterprise lookups
- `README.md`: Updated template index with Huawei template details

**Use Case:**
- Enterprise reports, solution showcases, annual reports, B2B client communication
- Minimalist tech style with Huawei red accents and professional gray tones

---

### v1.1.0 (2026-04-09) - Source File Handling Update

**Changed:**
- Source files are now **copied** (not moved) to `sources/` directory by default
- Original files are preserved at their source location
- Use `--move` flag if you want to move files instead of copying

**Previous behavior (v1.0.x):**
- Source files were moved to `sources/`, removing them from original location

**Rationale:**
- Safer default behavior - originals are preserved
- Users can still opt-in to move behavior with `--move` flag
- Reduces risk of accidental data loss

---

### v1.0.0 (2026-04-08) - Initial Release

**Features:**
- Multi-format input support (PDF, DOCX, EPUB, HTML, URL, Markdown)
- Professional SVG generation with design system
- Template-based and free-design modes
- Eight Confirmations design specification
- PPTX export with speaker notes
- Icon embedding and image processing

---

## Usage

```bash
# Initialize project
python3 scripts/project_manager.py init <project_name> --format ppt169

# Import source files (default: copy, preserve originals)
python3 scripts/project_manager.py import-sources <project_path> <source_files...>

# Import source files (move mode - remove originals)
python3 scripts/project_manager.py import-sources <project_path> <source_files...> --move

# Generate PPTX
python3 scripts/svg_to_pptx.py <project_path> -s final
```

## License

MIT


path: RESOURCES.md
content: # pptx-master - 资源清单

**生成时间**: 2026-04-16 11:04:12  
**技能目录**: `/home/Vincent/.openclaw/workspace/skills/pptx-master`  
**扫描深度**: 3 层

---

## 📊 资源总览

| 资源类型 | 数量 | 关键文件 |
|----------|------|----------|
| Templates | 55 | `templates/charts/charts_index.json, templates/layouts/layouts_index.json, templates/icons/tabler-outline/uv-index.svg` |
| Scripts | 55 | `scripts/` |
| Configs | 0 | `无` |
| Assets | 2 | `assets/` |

---

## 🎨 Templates (模板)

### templates/charts/charts_index.json

- **总数**: 33
- **格式**: ppt169
- **更新**: 2026-03-22

**分类**:

- **comparison** (Comparison): 8 个
- **trend** (Trend): 4 个
- **composition** (Composition): 3 个
- **metrics** (Metrics): 3 个
- **analysis** (Analysis): 8 个
- **process** (Project Management / Relationships): 5 个
- **strategy** (Strategic Frameworks): 2 个

---

### templates/layouts/layouts_index.json

- **总数**: 22
- **格式**: ppt169
- **更新**: 2026-03-22

**分类**:

- **brand** (Brand Style Templates): 10 个
- **general** (General Style Templates): 3 个
- **scenario** (Scenario-Specific Templates): 5 个
- **government** (Government/Enterprise Templates): 3 个
- **special** (Special Style Templates): 1 个

---

## 🛠️ Scripts (脚本)

### 核心脚本

- `scripts/project_manager.py`

### 转换脚本

- `scripts/doc_to_md.py`
- `scripts/pdf_to_md.py`
- `scripts/web_to_md.py`
- `scripts/svg_to_pptx.py`
- `scripts/svg_finalize/svg_rect_to_path.py`
- `scripts/svg_to_pptx/drawingml_context.py`
- `scripts/svg_to_pptx/pptx_notes.py`
- `scripts/svg_to_pptx/drawingml_elements.py`
- `scripts/svg_to_pptx/drawingml_utils.py`
- `scripts/svg_to_pptx/drawingml_styles.py`
- `scripts/svg_to_pptx/pptx_discovery.py`
- `scripts/svg_to_pptx/drawingml_paths.py`
- `scripts/svg_to_pptx/pptx_dimensions.py`
- `scripts/svg_to_pptx/pptx_slide_xml.py`
- `scripts/svg_to_pptx/pptx_builder.py`
- `scripts/svg_to_pptx/pptx_cli.py`
- `scripts/svg_to_pptx/pptx_media.py`
- `scripts/svg_to_pptx/drawingml_converter.py`
- `scripts/svg_to_pptx/__init__.py`

### 工具脚本

- `scripts/analyze_images.py`
- `scripts/update_repo.py`
- `scripts/generate_examples_index.py`
- `scripts/image_gen.py`
- `scripts/svg_quality_checker.py`
- `scripts/batch_validate.py`
- `scripts/rotate_images.py`
- `scripts/svg_position_calculator.py`
- `scripts/gemini_watermark_remover.py`
- `scripts/total_md_split.py`
- `scripts/finalize_svg.py`
- `scripts/pptx_template_import.py`
- `scripts/pptx_animations.py`
- `scripts/config.py`
- `scripts/project_utils.py`
- `scripts/error_helper.py`
- `scripts/svg_finalize/embed_icons.py`
- `scripts/svg_finalize/embed_images.py`
- `scripts/svg_finalize/fix_image_aspect.py`
- `scripts/svg_finalize/flatten_tspan.py`
- `scripts/svg_finalize/crop_images.py`
- `scripts/svg_finalize/__init__.py`
- `scripts/image_backends/backend_fal.py`
- `scripts/image_backends/backend_siliconflow.py`
- `scripts/image_backends/backend_bfl.py`
- `scripts/image_backends/backend_volcengine.py`
- `scripts/image_backends/backend_zhipu.py`
- `scripts/image_backends/backend_common.py`
- `scripts/image_backends/backend_stability.py`
- `scripts/image_backends/backend_qwen.py`
- `scripts/image_backends/backend_ideogram.py`
- `scripts/image_backends/backend_gemini.py`
- `scripts/image_backends/backend_openai.py`
- `scripts/image_backends/__init__.py`
- `scripts/image_backends/backend_replicate.py`

---

## 📦 Assets (素材)

### Scripts

- `scripts/assets/bg_96.png`
- `scripts/assets/bg_48.png`

---

## 💡 使用建议

### 规划阶段

1. **读取索引文件** - 快速了解可用模板和图表
2. **匹配场景** - 根据用户需求选择最合适的模板
3. **检查依赖** - 确认所需脚本和配置存在

### 执行阶段

1. **按顺序调用** - 遵循技能定义的工作流
2. **质量检查** - 使用提供的质量检查脚本
3. **错误处理** - 参考脚本中的错误处理逻辑

### 扩展阶段

1. **添加模板** - 在 templates/ 目录下创建新模板
2. **更新索引** - 修改对应的 index.json 文件
3. **测试验证** - 运行测试脚本确保兼容性

---

**自动生成**: skill-resource-scanner.py  
**手动更新**: 请在添加新资源后重新运行扫描器


path: SVG_BEST_PRACTICES.md
content: # PPT Master SVG 最佳实践

**版本**: v1.0  
**创建时间**: 2026-04-16  
**目的**: 规范 pptx-master 技能中 SVG 生成的最佳实践，避免常见问题

---

## ⭐ 核心原则

### 1. 使用图标库代替 emoji

**问题**: 直接在 SVG 中使用 emoji 字符（💰🔬📎）会导致 XML 解析失败

**解决**: 使用图标库中的 SVG icon

```svg
<!-- ❌ 错误：直接使用 emoji -->
<text x="0" y="0">💰 投融资</text>
<text x="0" y="0">🔬 技术突破</text>
<text x="0" y="0">📎 附录</text>

<!-- ✅ 正确：使用图标库 -->
<image x="0" y="0" width="24" height="24" href="templates/icons/tabler-filled/money.svg"/>
<text x="30" y="17">投融资</text>
```

### 2. 特殊字符转义

**问题**: XML 特殊字符需要转义

```svg
<!-- ❌ 错误 -->
<text>A & B > C</text>

<!-- ✅ 正确 -->
<text>A &amp; B &gt; C</text>
```

### 3. 中文字体声明

**问题**: 中文字体需要明确声明

```svg
<!-- ✅ 推荐 -->
<text font-family="Microsoft YaHei, sans-serif">中文内容</text>
```

---

## 📚 图标库使用指南

### 图标库位置

```
/home/Vincent/.openclaw/workspace/skills/pptx-master/templates/icons/
├── chunk/          # Chunk 图标库（填充风格）
├── tabler-filled/  # Tabler 填充风格
└── tabler-outline/ # Tabler 轮廓风格
```

### 常用图标映射表

| 场景 | 推荐图标 | 文件名 | 库 |
|------|----------|--------|-----|
| **投融资** | 💰 | `money.svg`, `dollar.svg` | tabler-filled |
| **技术/科研** | 🔬 | `microscope.svg`, `flask.svg` | tabler-filled |
| **附录/附件** | 📎 | `paperclip.svg`, `attachment.svg` | tabler-filled |
| **趋势/增长** | 📈 | `trending-up.svg`, `chart.svg` | tabler-filled |
| **警告/注意** | ⚠️ | `alert-triangle.svg` | tabler-filled |
| **成功/完成** | ✅ | `check-circle.svg` | tabler-filled |
| **错误/失败** | ❌ | `x-circle.svg` | tabler-filled |
| **信息/提示** | ℹ️ | `info-circle.svg` | tabler-filled |
| **时间/日历** | 📅 | `calendar.svg` | tabler-filled |
| **用户/人员** | 👤 | `user.svg` | tabler-filled |
| **设置/配置** | ⚙️ | `settings.svg` | tabler-filled |
| **搜索/查找** | 🔍 | `search.svg` | tabler-filled |
| **下载** | 📥 | `download.svg` | tabler-filled |
| **上传** | 📤 | `upload.svg` | tabler-filled |
| **链接** | 🔗 | `link.svg` | tabler-filled |

### 图标使用示例

```svg
<?xml version="1.0" encoding="UTF-8"?>
<svg width="1280" height="720" viewBox="0 0 1280 720" xmlns="http://www.w3.org/2000/svg">
  <!-- 背景 -->
  <rect width="1280" height="720" fill="#f5f5f5"/>
  
  <!-- 标题 + 图标 -->
  <g transform="translate(100, 60)">
    <!-- 图标 -->
    <image x="0" y="0" width="32" height="32" href="../templates/icons/tabler-filled/money.svg"/>
    <!-- 标题文字 -->
    <text x="40" y="24" font-family="Microsoft YaHei, sans-serif" font-size="24" font-weight="bold" fill="#333333">
      投融资和行业事件
    </text>
  </g>
</svg>
```

---

## 🔧 常见问题排查

### 问题 1: SVG 转换失败，报错"not well-formed"

**原因**: 
- 使用了 emoji 字符
- XML 特殊字符未转义
- 编码问题

**解决**:
1. 移除所有 emoji，改用图标库
2. 转义特殊字符：`&` → `&amp;`, `<` → `&lt;`, `>` → `&gt;`
3. 确保文件编码为 UTF-8

### 问题 2: 中文显示为方框

**原因**: 字体未正确声明

**解决**:
```svg
<text font-family="Microsoft YaHei, sans-serif">中文内容</text>
```

### 问题 3: 图标不显示

**原因**: 
- 图标路径错误
- 图标文件不存在

**解决**:
1. 检查图标路径是否正确
2. 使用 `ls templates/icons/<library>/` 确认图标存在
3. 使用相对路径或绝对路径

---

## 📋 检查清单

在导出 PPTX 前，检查以下项目：

- [ ] 所有 emoji 已替换为图标库 SVG
- [ ] XML 特殊字符已转义
- [ ] 中文字体已声明
- [ ] 图标路径正确
- [ ] SVG 文件格式正确（UTF-8 编码）
- [ ] 所有页面页码正确

---

## 🎯 快速参考

### emoji → 图标映射速查

```
💰 → money.svg
🔬 → microscope.svg
📎 → paperclip.svg
📈 → trending-up.svg
⚠️ → alert-triangle.svg
✅ → check-circle.svg
❌ → x-circle.svg
ℹ️ → info-circle.svg
📅 → calendar.svg
👤 → user.svg
⚙️ → settings.svg
🔍 → search.svg
```

### 图标库快速搜索

```bash
# 搜索特定图标
ls templates/icons/tabler-filled/ | grep money
ls templates/icons/tabler-filled/ | grep chart
ls templates/icons/tabler-filled/ | grep user
```

---

**创建者**: 零壹  
**创建时间**: 2026-04-16  
**状态**: 正式版本 v1.0


path: VERSION_UPDATE.md
content: # Version Update: 1.0.0 → 1.0.1

## Update Summary
This document outlines the changes made to upgrade the pptx-master skill from version 1.0.0 to 1.0.1.

## Changes Made

### 1. Project Initialization Behavior
- **Changed**: Source content handling from MOVE to COPY
- **Previous**: Files were moved (`--move`) from original location to `sources/` directory
- **New**: Files are copied (`--copy`) to `sources/` directory, preserving original files
- **Impact**: Original source files now remain in their original location after import

### 2. Template Library Expansion
- **Added**: Two new layout templates - HUAWEI and red grey
- **Enhanced**: Template selection step to include new options
- **Updated**: Template recommendation flow to mention new options

### 3. Version Identification
- **Updated**: Description to reflect version 1.0.1
- **Added**: Reference to enhanced template options and source content handling

## Implementation Details

### Modified Sections
1. Step 2: Project Initialization - Updated file handling instruction
2. Step 3: Template Selection - Enhanced template recommendation flow
3. Header: Updated description to reflect version and enhancements

## Backward Compatibility
The changes maintain full backward compatibility:
- Existing workflows continue to function as before
- Only the source file handling behavior has changed (copy vs move)
- All existing templates remain available
- New templates are additional options

## Testing Recommendations
- Verify source files remain in original location after project initialization
- Test new HUAWEI and red grey template options
- Confirm all existing functionality remains intact

path: references/canvas-formats.md
content: # Canvas Format Specification

> See shared-standards.md for SVG basic rules.

## Format Quick Reference

| Format | viewBox | Ratio | Use Case |
|--------|---------|-------|----------|
| PPT 16:9 | `0 0 1280 720` | 16:9 | Business presentations, meetings |
| PPT 4:3 | `0 0 1024 768` | 4:3 | Traditional projectors, academic talks |
| Xiaohongshu (RED) | `0 0 1242 1660` | 3:4 | Image-text sharing, knowledge posts |
| WeChat Moments / IG | `0 0 1080 1080` | 1:1 | Square posters, brand showcases |
| Story / TikTok | `0 0 1080 1920` | 9:16 | Vertical stories, short video covers |
| WeChat Article Header | `0 0 900 383` | 2.35:1 | WeChat article cover images |
| Landscape Banner | `0 0 1920 1080` | 16:9 | Web banners, digital screens |
| Portrait Poster | `0 0 1080 1920` | 9:16 | Phone screens, elevator ads |
| A4 Print | `0 0 1240 1754` | 1:sqrt(2) | Print posters, flyers |

## Format Selection Decision Tree

```
Content purpose?
├── Presentation
│   ├── Modern devices → PPT 16:9 (1280x720)
│   └── Traditional devices → PPT 4:3 (1024x768)
├── Social sharing
│   ├── Xiaohongshu (RED) → 1242x1660
│   ├── WeChat Moments / IG → 1080x1080
│   └── Story / TikTok → 1080x1920
└── Marketing materials
    ├── WeChat Article Header → 900x383
    ├── Banner → 1920x1080
    └── Print → 1240x1754
```

## Layout Principles

### Landscape (16:9, 4:3, 2.35:1)
- Visual flow: Z-pattern, left to right
- Margins: 40-80px
- Layouts: multi-column, left-right split, grid
- Card dimensions (16:9): single-row 530-600px, double-row 265-295px

### Portrait (3:4, 9:16)
- Visual flow: top to bottom
- Margins: 60-120px
- Layouts: single-column, top-bottom split, card stacking
- Card dimensions (3:4): height 400-600px, gap 40-60px

### Square (1:1)
- Visual flow: center-radiating
- Margins: 60-100px
- Core area: ~800x800px

## Format-specific Design

| Format | Title Area | Content Area | Special Notes |
|--------|-----------|--------------|---------------|
| PPT | 80-100px | Full width utilization | Page number bottom-right |
| Xiaohongshu (RED) | 180-240px (bold) | Generous top/bottom whitespace | Brand area at bottom 120-160px |
| WeChat Moments | 200-280px | Center 500-600px | QR code area at bottom 150-200px |
| Story | — | Middle 1500px | Top safe zone 120px, bottom 180px |
| WeChat Article Header | Center/left-aligned 48-72px | — | Image on right or as background |

## ViewBox Examples

```xml
<svg width="1280" height="720" viewBox="0 0 1280 720">   <!-- PPT 16:9 -->
<svg width="1242" height="1660" viewBox="0 0 1242 1660"> <!-- Xiaohongshu -->
<svg width="1080" height="1080" viewBox="0 0 1080 1080"> <!-- WeChat Moments -->
<svg width="1080" height="1920" viewBox="0 0 1080 1920"> <!-- Story -->
<svg width="900" height="383" viewBox="0 0 900 383">     <!-- WeChat Article Header -->
```


path: references/executor-base.md
content: # Executor Common Guidelines

> Style-specific content is in the corresponding `executor-{style}.md`. Technical constraints are in shared-standards.md.

---

## 1. Template Adherence Rules

If template files exist in the project's `templates/` directory, the template structure must be followed:

| Page Type | Corresponding Template | Adherence Rules |
|-----------|----------------------|-----------------|
| Cover | `01_cover.svg` | Inherit background, decorative elements, layout structure; replace placeholder content |
| Chapter | `02_chapter.svg` | Inherit numbering style, title position, decorative elements |
| Content | `03_content.svg` | Inherit header/footer styles; **content area may be freely laid out** |
| Ending | `04_ending.svg` | Inherit background, thank-you message position, contact info layout |
| TOC | `02_toc.svg` | **Optional**: Inherit TOC title, list styles |

### Page-Template Mapping Declaration (Required Output)

Before generating each page, you must explicitly output which template (or "free design") is used:

```
📝 **Template mapping**: `templates/01_cover.svg` (or "None (free design)")
🎯 **Adherence rules / layout strategy**: [specific description]
```

- **Content pages**: Templates only define header and footer; the content area is freely laid out by the Executor
- **No template**: Generate entirely per the Design Specification & Content Outline

---

## 2. Design Parameter Confirmation (Mandatory Step)

> Before generating the first SVG page, you **must review the key design parameters from the Design Specification & Content Outline** to ensure all subsequent generation strictly follows the spec.

Must output confirmation including: canvas dimensions, body font size, color scheme (primary/secondary/accent HEX values), font plan.

**Why is this step mandatory?** Prevents the "spec says one thing, execution does another" disconnect.

---

## 3. Execution Guidelines

- **Proximity principle**: Place related elements close together to form visual groups; increase spacing between unrelated groups to reinforce logical structure
- **Absolute spec adherence**: Strictly follow the color, layout, canvas format, and typography parameters in the spec
- **Follow template structure**: If templates exist, inherit the template's visual framework
- **Main-agent ownership**: SVG generation must be performed by the current main agent, not delegated to sub-agents, because each page depends on shared upstream context and cross-page visual continuity
- **Generation rhythm**: First lock the global design context, then generate pages sequentially one by one in the same continuous context; grouped page batches (for example, 5 pages at a time) are not allowed
- **Phased batch generation** (recommended):
  1. **Visual Construction Phase**: Generate all SVG pages continuously in sequential page order, ensuring high consistency in design style and layout coordinates (Visual Consistency)
  2. **Logic Construction Phase**: After all SVGs are finalized, batch-generate speaker notes to ensure narrative coherence (Narrative Continuity)
- **Technical specifications**: See [shared-standards.md](shared-standards.md) for SVG technical constraints and PPT compatibility rules
- **Visual depth**: Use filter shadows, glow effects, gradient fills, dashed strokes, and gradient overlays from shared-standards.md to create layered depth — flat pages without elevation or emphasis look unfinished

### SVG File Naming Convention

File naming format: `<number>_<page_name>.svg`

- **Chinese content** → Chinese naming: `01_封面.svg`, `02_目录.svg`, `03_核心优势.svg`
- **English content** → English naming: `01_cover.svg`, `02_agenda.svg`, `03_key_benefits.svg`
- **Number rules**: Two-digit numbers, starting from 01
- **Page name**: Concise and descriptive, matching the page title in the Design Specification & Content Outline

---

## 4. Icon Usage

Four approaches: **A: Emoji** (`<text>🚀</text>`) | **B: AI-generated** (SVG basic shapes) | **C: Built-in library** (`templates/icons/` 6000+ icons, recommended) | **D: Custom** (user-specified)

**Built-in icons — Placeholder method (recommended)**:

```xml
<!-- tabler-filled library (fill, 24px) -->
<use data-icon="tabler-filled/home" x="100" y="200" width="48" height="48" fill="#005587"/>
<!-- tabler-outline library (stroke, 24px) -->
<use data-icon="tabler-outline/home" x="100" y="200" width="48" height="48" fill="#005587"/>
```

> No need to manually run `embed_icons.py`; `finalize_svg.py` post-processing tool will auto-embed icons.

**Two icon libraries**:

| Library | Style | Count | Prefix | Best for |
|---------|-------|-------|--------|----------|
| `tabler-filled` | fill/solid | 1000+ | `tabler-filled/` | Modern solid icons |
| `tabler-outline` | stroke/line | 5000+ | `tabler-outline/` | Light, elegant style |

**Searching for icons** — use terminal, zero token cost:
```bash
ls skills/pptx-master/templates/icons/tabler-filled/ | grep home
ls skills/pptx-master/templates/icons/tabler-outline/ | grep chart
```

**Abstract concept → icon name** (for concepts whose meaning isn't obvious from the filename):

| Concept | tabler-filled | tabler-outline |
|---------|---------------|----------------|
| Growth / Increase | `arrow-trend-up` | `arrow-trend-up` |
| Decline / Decrease | `arrow-trend-down` | `arrow-trend-down` |
| Success / Complete | `circle-check` | `circle-check` |
| Warning / Risk | `alert-triangle` | `alert-triangle` |
| Innovation / Idea | `bulb` | `bulb` |
| Strategy / Goal | `target` | `target` |
| Efficiency / Speed | `bolt` | `bolt` |
| Collaboration / Team | `users` | `users` |
| Settings / Config | `settings` | `settings` |
| Security / Trust | `shield` | `shield` |
| Money / Finance | `currency-dollar` | `currency-dollar` |
| Time / Deadline | `clock` | `clock` |
| Location / Region | `map-pin` | `map-pin` |
| Communication | `message` | `message` |
| Analysis / Data | `chart-bar` | `chart-bar` |
| Process / Flow | `refresh` | `refresh` |
| Global / World | `world` | `world` |
| Excellence / Award | `star` | `star` |
| Expand / Scale | `maximize` | `maximize` |
| Problem / Issue | `bug` | `bug` |

> For self-evident names (home, user, file, search, arrow, etc.) — just `grep` directly without consulting the table.

> ⚠️ **Icon validation rule**: If the Design Specification includes an icon inventory list, Executor may **only** use icons from that approved list. Before using any icon, verify it exists via `ls | grep` search. **Mixing fill and outline icons in the same presentation is FORBIDDEN** — use only the style specified in the Design Spec.

---

## 5. Chart Reference

When the Design Spec includes a **VII. Chart Reference List**, read the referenced SVG templates from `templates/charts/` to understand common chart patterns.

**Adaptation rules**:
- **Must preserve**: Chart type (bar/line/pie etc.) as specified in the Design Spec
- **Must adapt**: Data values, labels, colors (match the project's color scheme), and dimensions to fit the page layout
- **May adjust**: Axis ranges, grid lines, legend position, spacing — as long as the chart remains accurate and readable
- **Must NOT**: Change chart type without Design Spec justification, or remove data points specified in the outline

> Chart templates: `templates/charts/` (33 types). Index: `templates/charts/charts_index.json`

---

## 6. Image Handling

Handle images based on their status in the Design Specification's "Image Resource List":

| Status | Source | Handling |
|--------|--------|----------|
| **Existing** | User-provided | Reference images directly from `../images/` directory |
| **AI-generated** | Generated by Image_Generator | Images already in `../images/`, reference directly |
| **Placeholder** | Not yet prepared | Use dashed border placeholder |

**Reference**: `<image href="../images/xxx.png" ... preserveAspectRatio="xMidYMid slice"/>`

**Placeholder**: Dashed border `<rect stroke-dasharray="8,4" .../>` + description text

---

## 7. Font Usage

Apply corresponding fonts for different text roles based on the font plan in the Design Specification & Content Outline:

| Role | Chinese Recommended | English Recommended |
|------|--------------------|--------------------|
| Title font | Microsoft YaHei / KaiTi / SimHei | Arial / Georgia |
| Body font | Microsoft YaHei / SimSun | Calibri / Times |
| Emphasis font | SimHei | Arial Black / Consolas |
| Annotation font | Microsoft YaHei / SimSun | Arial / Times |

---

## 8. Speaker Notes Generation Framework

### Task 1. Generate Complete Speaker Notes Document

After **all SVG pages are generated and finalized**, enter the "Logic Construction Phase" and generate the complete speaker notes document in `notes/total.md`.

**Why not generate page-by-page?** Batch-writing notes allows planning transitions like a script, ensuring coherent presentation logic.

**Format**: Each page starts with `# <number>_<page_title>`, separated by `---` between pages. Each page includes: script text (2-5 sentences), `Key points: ① ② ③`, `Duration: X minutes`. Except for the first page, each page's text starts with a `[Transition]` phrase.

**Basic stage direction markers** (common to all styles):

| Marker | Purpose |
|--------|---------|
| `[Pause]` | Whitespace after key content, letting the audience absorb |
| `[Transition]` | Standalone paragraph at the start of each page's text, bridging from the previous page |

> Each style may extend with additional markers (`[Interactive]`/`[Data]`/`[Scan Room]`/`[Benchmark]` etc.), see `executor-{style}.md`.

**Language consistency rule**: All structural labels and stage direction markers in speaker notes **MUST match the presentation's content language**. When the presentation content is non-English, localize every label — do NOT mix English labels with non-English content.

| English | 中文 | 日本語 | 한국어 |
|---------|------|--------|--------|
| `[Transition]` | `[过渡]` | `[つなぎ]` | `[전환]` |
| `[Pause]` | `[停顿]` | `[間]` | `[멈춤]` |
| `[Interactive]` | `[互动]` | `[問いかけ]` | `[상호작용]` |
| `[Data]` | `[数据]` | `[データ]` | `[데이터]` |
| `[Scan Room]` | `[观察]` | `[観察]` | `[관찰]` |
| `[Benchmark]` | `[对标]` | `[ベンチマーク]` | `[벤치마크]` |
| `Key points:` | `要点：` | `要点：` | `핵심 포인트:` |
| `Duration:` | `时长：` | `所要時間：` | `소요 시간:` |
| `Flex:` | `弹性：` | `調整：` | `조정:` |

> For languages not listed above, translate each label to the corresponding natural term in that language.

**Requirements**:

- Notes should be conversational and flow naturally
- Highlight each page's core information and presentation key points
- Users can manually edit and override in the `notes/` directory

### Task 2. Split Into Per-Page Note Files

Automatically split `notes/total.md` into individual speaker note files in the `notes/` directory.

**File naming convention**:

- **Recommended**: Match SVG names (e.g., `01_cover.svg` → `notes/01_cover.md`)
- **Compatible**: Also supports `slide01.md` format (backward compatibility)

---

## 9. Next Steps After Completion

> **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)):

```bash
# 1. Split speaker notes
python3 scripts/total_md_split.py <project_path>

# 2. SVG post-processing (auto-embed icons, images, etc.)
python3 scripts/finalize_svg.py <project_path>

# 3. Export PPTX
python3 scripts/svg_to_pptx.py <project_path> -s final
# Default: generates native shapes (.pptx) + SVG reference (_svg.pptx)
```


path: references/executor-consultant-top.md
content: # Executor Consultant Top — Top-tier Consulting Style (MBB Level)

> Common guidelines: executor-base.md. Technical constraints: shared-standards.md.

---

## Role Definition

An MBB-level (McKinsey / Bain / BCG) top-tier consulting style SVG design executor. Suitable for strategic planning, board presentations, investment roadshows, C-suite decision support, and other **premium consulting** scenarios. Core characteristics: data-driven insights, pyramid-structured narrative, extreme simplicity. Output targets C-level decision-makers.

---

## SCQA Framework (Narrative Structure)

Every MBB-level presentation follows the SCQA narrative structure:

| Element | Purpose | Typical Pages |
|---------|---------|---------------|
| **S - Situation** | Establish shared context | Cover / Pages 1-2 |
| **C - Complication** | Introduce the problem / tension | Pages 2-3 |
| **Q - Question** | The implicit or explicit question to solve | Transition page |
| **A - Answer** | Core solution | All body pages |

**Page sequencing**: Cover embodies S+C → Executive Summary answers Q → Chapters develop A → Closing revisits S

**Title writing**:

| SCQA Element | Weak Title | MBB-level Title |
|-------------|------------|-----------------|
| S | "Industry Background" | "Digital penetration surpasses 60%, industry enters deep waters" |
| C | "Challenges Faced" | "Yet three structural contradictions constrain scaled deployment" |
| Q | "Strategic Question" | "How to move from pilot to full deployment within 18 months?" |
| A | "Solution" | "Three-phase path: Focus, Expand, Scale" |

---

## Data Contextualization (Never Present Data in Isolation)

> **Golden Rule**: Never display a single data point in isolation. Every number needs context.

| Method | Pattern | Visual Implementation |
|--------|---------|----------------------|
| **Time comparison** | "From X to Y" | Line chart + arrow annotating magnitude of change |
| **Benchmark** | "X vs industry average Y" | Bar chart with gray dashed baseline |
| **Competitive comparison** | "Us X vs Competitor Y" | Side-by-side bar chart, highlight own data |
| **Target gap** | "Actual X / Target Y" | Progress bar + gap annotation |
| **Ranking** | "Ranked #N of M" | Horizontal bar chart + highlight marker |

**Data annotation three essentials**: Every data visualization must include (1) The value itself (large bold font) (2) Comparison reference (baseline / prior period / competitor) (3) Meaning interpretation ("So what?")

```xml
<text x="160" y="280" text-anchor="middle" font-size="42" font-weight="bold" fill="#1E293B">97.3%</text>
<text x="160" y="310" text-anchor="middle" font-size="13" fill="#64748B">Industry avg 82% | Competitor A 89%</text>
<text x="160" y="335" text-anchor="middle" font-size="12" fill="#059669">Leading industry by 15.3 percentage points</text>
```

---

## Pyramid Principle (Conclusion First)

> Executives don't care about your *process* — they care about *results*.

```
         ┌─────────────────┐
         │  Core Conclusion │   ← Page title / Takeaway
         └────────┬────────┘
      ┌───────────┼───────────┐
  ┌───┴───┐  ┌───┴───┐  ┌───┴───┐
  │ Arg 1 │  │ Arg 2 │  │ Arg 3 │   ← Key supporting points
  └───────┘  └───────┘  └───────┘
```

| Level | Position | Font Size |
|-------|----------|-----------|
| Core conclusion | Takeaway Box | 16-18px bold |
| Arguments | Content area body | 14-16px |
| Supporting data | Charts / cards | 12-14px |

**Contrast**: Title "Market Research Results" (wrong) → "Metaverse needs 5-10 years to reach scale" (right); Body "We researched... and found..." (wrong) → "Three arguments: (1)... (2)... (3)..." (right)

---

## MBB-level Layout Patterns

### Content Page Standard Structure (1280x720)

```
┌──────────────────────────────────┐
│ Gradient top bar (0,0 → 1280,6)  │
├──────────────────────────────────┤
│ Assertion title (x=40, y=50, 24px)│
├──────────────────────────────────┤
│ Takeaway Box (x=40, y=75,        │  ← Dark background + white text, one-sentence conclusion
│   w=1200, h=45)                  │
├──────────────────────────────────┤
│ Content area (x=40, y=140,       │  ← Charts / data / analysis
│   w=1200, h=520)                 │
├──────────────────────────────────┤
│ Source | CONFIDENTIAL | Page #    │  ← y=700, 10px
└──────────────────────────────────┘
```

### Strategic Roadmap

Three phases laid out horizontally, `<rect rx="8">` + title + action list, `<polygon>` arrows connecting:

```
Focus Core (0-6mo)  ──>  Expand Capability (6-12mo)  ──>  Scale Up (12-18mo)
x=40,w=380              x=450,w=380                     x=860,w=380
```

### Benchmarking Matrix

Horizontal table; own row highlighted in theme color, others in gray. Leading indicators marked green, lagging marked red. Use `<circle>` or `<rect>` to build score points.

### Waterfall Chart (Change Attribution)

Start → increase/decrease factors → End. Positive factors green bars, negative factors red bars, start/end points dark bars, cumulative line as dashed connector.

---

## Strategic Use of Color

MBB-level color usage is extremely restrained — color serves information:

| Purpose | Method |
|---------|--------|
| **Focus** | Target data in theme color, everything else gray |
| **Reduce cognitive load** | Same series differentiated by opacity (`fill-opacity` 1.0/0.6/0.3) |
| **Semantics** | Green = positive, Red = negative, Gray = baseline |
| **Branding** | Gradient top bar / decorative lines in brand color |

**Commandments**: No more than 3 primary colors; accent color used at most 2-3 places globally; data series use same-hue depth variations, not different colors; background white or very light gray.

---

## Chart vs Table Selection Matrix

| Scenario | Recommended Form | Reason |
|----------|-----------------|--------|
| Comparing 2-7 categories | **Bar chart** | Visual comparison is intuitive |
| Time trends | **Line chart** | Time series clarity |
| Precise values / large rankings | **Table** | 50 data points in a bar chart would be chaotic |
| Proportional composition | **Donut chart** | More modern than pie charts |
| Two-dimensional positioning | **2x2 matrix** | Strategic quadrant analysis |
| Change attribution | **Waterfall chart** | Factor decomposition |

---

## Speaker Notes Style

### Narrative Tone

Targeting **executives / decision-makers**. Pyramid structure — every sentence carries information. Composed, authoritative, and insightful tone.

### Stage Direction Markers

| Marker | Purpose | Example |
|--------|---------|---------|
| `[Pause]` | Silence after key insight, let executives absorb | "This means we are missing a billion-dollar market. [Pause]" |
| `[Scan Room]` | Observe decision-makers' reactions, decide whether to elaborate | "[Scan Room] If there are questions, I can elaborate." |
| `[Data]` | Conversational number delivery | "[Data] 63% → nearly two-thirds" |
| `[Benchmark]` | Emphasize comparison baseline | "[Benchmark] Compared to the industry average of 12%, our 23% is nearly double" |
| `[Transition]` | Bridge from previous page, at start of each page's text | "[Transition] Building on the strategic framework, let's drill into the implementation path." |

### Notes Writing Guidelines

- **Pyramid structure**: Conclusion → Arguments → Details
- **Data contextualization**: Every number has a comparison reference
- **Executive language**: "The strategic implication is...", "The core insight is..."
- **Flex mechanism**: Annotate "content that can be skipped if time is tight" for flexible duration
- **Key points structure**: `Key points: (1) Core insight (2) Data support (3) Strategic implication`

### Notes Example

```markdown
# 03_strategic_path

[Transition] Having clarified the problem and the opportunity, now comes the most critical part — our response path.

We recommend a three-phase strategy. [Pause]

Phase one: Focus. Over the next six months, concentrate resources on conquering the Eastern China market.
[Data] Eastern China contributes nearly two-thirds of industry growth, [Benchmark] yet our penetration rate is only half of Competitor A's. [Pause]

Phase two: Expand. Use Eastern China as a template, replicate to Southern and Northern China.
Phase three: Scale. Leverage a digital platform for nationwide coverage.

[Scan Room] The resource allocation for phase one is in the appendix — would you like me to walk through it now?

Key points: (1) Focus-Expand-Scale three-phase approach (2) Data-backed Eastern China priority (3) 18-month full deployment
Duration: 3 minutes
Flex: [If time is tight, skip phase two and three details and go straight to financial impact]
```

---

## MBB-level Quality Checklist Supplement

### Content Level

- [ ] **SCQA complete**: Overall follows Situation-Complication-Question-Answer structure
- [ ] **Data contextualized**: Every data point has a comparison reference
- [ ] **Conclusion first**: Every page's Takeaway Box has a one-sentence conclusion
- [ ] **MECE principle**: Categorized analysis is mutually exclusive and collectively exhaustive

### Visual Level

- [ ] **Color with intent**: Colors serve information delivery
- [ ] **Ample whitespace**: Not crowded; information can "breathe"
- [ ] **Visual hierarchy**: Conclusion > Arguments > Details, differentiated by font size/weight
- [ ] **Brand consistency**: Gradient top bar and footer unified throughout

### Notes Level

- [ ] **Pyramid structure**: Every page is conclusion-first
- [ ] **Stage markers complete**: [Pause] and [Scan Room] at key positions
- [ ] **Flex content annotated**: Supports flexible duration


path: references/executor-consultant.md
content: # Executor Consultant — Consulting Style

> Common guidelines: executor-base.md. Technical constraints: shared-standards.md.

---

## Role Definition

A data-driven, consulting-style SVG design executor. Suitable for business analysis reports, market research, operational reviews, strategic recommendations, and other **general consulting** scenarios. Emphasizes structured information presentation and data visualization; clean, clear, and professional style.

---

## Consultant-specific Data Visualization Techniques

### 1. KPI Dashboard Design

KPI cards are the most common element in consulting reports. Standard layout (1280x720):

```
4-card layout: each card 280x180, gap 30
  Card 1: x=45,  y=160
  Card 2: x=355, y=160
  Card 3: x=665, y=160
  Card 4: x=975, y=160
```

**Card internal structure** (top to bottom):

| Area | Content | Font Size | Style |
|------|---------|-----------|-------|
| Icon row | data-icon icon | 32x32 | Theme color |
| Metric name | "Monthly Active Users" | 14px | Gray #64748B |
| Core number | "1.2M" | 36-42px | Bold, dark color |
| Trend annotation | "+12.3% vs last month" | 12px | Green=up / Red=down |

**Trend arrow conventions**:
- Up: `arrow-trend-up` icon + green text
- Down: `arrow-trend-down` icon + red text
- Flat: horizontal line icon + gray text

### 2. Chart Color Conventions

Consulting-style charts use **monochromatic depth gradients** rather than rainbow colors:

```
Primary series:   Theme color 100% opacity
Comparison series: Theme color 60% opacity
Baseline:         #94A3B8 (gray dashed line)
Highlight:        Accent color (only for key data points)
```

### 3. Data Annotation Principles

- **Direct data labels**: Place values at the top of bar charts — no legend needed
- **Annotated trend lines**: Add text notes at key inflection points ("Policy change", "Product launch")
- **Comparison baselines**: Mark industry average / target values with gray dashed lines
- **Consistent units**: Maintain the same numeric units and precision within a chart

### 4. Table Design

Consulting reports frequently use tables for precise data:

| Design Element | Specification |
|----------------|---------------|
| Header | Dark background + white text, font-weight="bold" |
| Zebra striping | Alternate rows with `fill-opacity="0.05"` light background |
| Number alignment | Numbers right-aligned, text left-aligned |
| Highlighted row | Mark key rows with accent color `fill-opacity="0.1"` |
| Borders | Use horizontal lines only to separate rows; avoid full grid lines |

---

## Consulting-specific Layout Patterns

### MECE Decomposition Tree

Main trunk on the left, branches expanding rightward — mutually exclusive, collectively exhaustive:

```
Main metric ──┬── Branch A (45%)
              ├── Branch B (30%)
              ├── Branch C (20%)
              └── Branch D (5%)
```

- Use `<line>` to connect trunk to branches
- Each branch has a `<rect>` container + percentage annotation
- Sum must = 100% (or explicitly label "Other")

### Driver Factor Tree

Top-level metric → decomposed factors → actions. Ideal for performance attribution analysis:

```
Revenue growth 15%
  ├── Average order value +8%  → Premium product line expansion
  ├── Customer count +5%       → New channel acquisition
  └── Repurchase rate +2%      → Loyalty program optimization
```

### Left-chart Right-text (Chart Interpretation)

Core consulting report layout: chart on the left, key insights on the right:

```
Chart area: x=40, y=120, w=700, h=480
Insight area: x=780, y=120, w=460, h=480
  - Core conclusion (bold, 16px)
  - 3-5 bullet points (14px)
  - Data source (12px, gray)
```

---

## Professional Expression Standards

### Page Titles

Consulting-style page titles should be **assertion headlines**, not descriptive titles:

| Type | Descriptive (avoid) | Assertion (recommended) |
|------|---------------------|------------------------|
| Market | "Market Overview" | "Domestic market grows 23% YoY, significantly outpacing global average" |
| Competition | "Competitive Analysis" | "Three major competitors show clear weaknesses in channel coverage" |
| Finance | "Financial Data" | "Gross margin improved for four consecutive quarters, breaking industry ceiling" |

### Data Source Attribution

Every data-containing page must include a source note at the bottom:

```xml
<text x="40" y="700" font-size="10" fill="#94A3B8">
  Source: National Bureau of Statistics 2025 Annual Report; Internal team analysis
</text>
```

### Key Takeaway Box

Consulting-style content pages should include a **Takeaway Box** below the title:

```
Position: x=40, y=80, w=1200, h=50
Background: Light theme color (fill-opacity="0.08")
Text: 14-16px, one-sentence summary of the page's core takeaway
```

---

## Speaker Notes Style

### Narrative Tone

Consultant-style speaker notes use a **conclusion-driven** approach — state the conclusion first, then present supporting evidence. Professional, concise, and persuasive tone.

### Stage Direction Markers

| Marker | Purpose | Example |
|--------|---------|---------|
| `[Pause]` | Silence after key conclusions, let the audience absorb | "This means our market share is being eroded. [Pause]" |
| `[Data]` | Cue to verbalize numbers conversationally | "[Data] 85% → more than eight out of ten customers reported this issue" |
| `[Transition]` | Bridge from previous page, must be at start of each page's text | "[Transition] Based on that analysis, let's look at specific recommendations." |

### Notes Writing Guidelines

- **Conclusion first**: The first sentence of each page's notes is the core takeaway
- **Conversational data**: 30% → "roughly one-third", 85% → "more than eight out of ten", 2.5x → "two and a half times"
- **Evidence follows immediately**: After the conclusion, provide 2-3 supporting data points/facts
- **Professional terminology**: Use terms like "insight", "driver", "key lever" etc.
- **Key points structure**: `Key points: (1) Core conclusion (2) Supporting data (3) Next steps`

### Notes Example

```markdown
# 03_key_findings

[Transition] Based on our market scan, we have distilled three key findings.

First, the primary growth driver is shifting from acquisition to retention.
[Data] New customer acquisition cost rose nearly 40% year-over-year, yet improved repurchase rates contributed over 60% of revenue growth. [Pause]

Second, lower-tier market growth significantly outpaces tier-1 and tier-2 cities.
Third, the 25-35 female user segment has an ARPU 1.8x the overall average.

Key points: (1) Growth engine shifting from acquisition to retention (2) Lower-tier market opportunity window (3) High-value user persona
Duration: 2 minutes
```

---

## Self-check Supplement (Consultant-specific)

- [ ] Data matches source data — no fabrication
- [ ] Every data page has a source attribution at the bottom
- [ ] Page titles are assertion-based, not descriptive
- [ ] KPI cards have trend arrows and comparison annotations
- [ ] Chart colors are unified, using monochromatic scheme rather than rainbow
- [ ] Notes are conclusion-first with conversational data


path: references/executor-general.md
content: # Executor General — Creative Versatile Style

> Common guidelines: executor-base.md. Technical constraints: shared-standards.md.

---

## Role Definition

A creative, versatile-style SVG design executor. Suitable for product introductions, training materials, proposal presentations, marketing campaigns, and other **non-consulting** scenarios. Emphasizes visual impact and information engagement, striking a balance between professionalism and approachability.

---

## General-specific Layout Techniques

### 1. Flexible and Varied Layouts

The General style is not confined to fixed templates; layouts can be freely chosen based on content:

| Layout | Use Case | Layout Details (1280x720) |
|--------|----------|--------------------------|
| Full-image background + text overlay | Covers, emotional pages | `<image>` fills canvas + semi-transparent overlay + centered title |
| Left-right split (image-text mix) | Feature introductions, comparisons | Left x=40,w=580 / Right x=660,w=580 |
| Three-column cards | Feature lists, team introductions | x=40,450,860 each w=380, equal-height cards |
| Top-bottom split | Timelines, process flows | Top area: title+description h=250 / Bottom area: charts+content h=420 |
| Center-radiating | Core concepts, ecosystem diagrams | Center element + 4-6 surrounding nodes, lines pointing to center |
| Waterfall / Z-pattern | Storytelling, case studies | Content blocks alternate left-right, guiding the eye in a Z-pattern |

### 2. Visual Rhythm Control

- **Information density alternation**: Follow a data-heavy page with a "breathing page" (large image / quote / transition) to prevent audience fatigue
- **Visual weight balance**: Dark/large-area elements are "heavy", light/small elements are "light" — balance left-right/top-bottom
- **Repetition and variation**: Maintain layout consistency within a chapter; vary between chapters to maintain freshness

### 3. Decorative Element Usage

| Element | Usage | Notes |
|---------|-------|-------|
| Gradient blocks | Background zones, title backing | Use `<linearGradient>` / `<radialGradient>`, limit to 2-3 colors |
| Rounded rectangle cards | Content containers, feature modules | `rx="12"` with light shadow (simulate with lighter rect) |
| Icon accents | List item prefixes, feature markers | Use `data-icon` placeholders, size 32-48px |
| Numbered circles | Step flows, ranked lists | `<circle>` + centered `<text>`, theme color fill |
| Divider lines | Content separation | `<line>` or `<rect height="2">`, opacity 0.2-0.3 |

---

## Visual Strategy

### Color Usage

- **Bold use of theme color**: Covers and chapter pages can use large areas of theme color background
- **Gradients enhance depth**: Title bars and card backgrounds can use same-hue gradients
- **Contrast creates focus**: Key numbers/words use accent color, creating contrast with surroundings
- **Color-mood matching**: Cool tones for tech feel, warm tones for energy, dark tones for gravitas

### Image Handling Strategy

| Scenario | Strategy | SVG Implementation |
|----------|----------|-------------------|
| Full-screen background | Image fills + dark gradient overlay | `preserveAspectRatio="xMidYMid slice"` + gradient rect |
| Portrait image display | Place left/right, maintain original ratio | Control width, height adapts |
| Multi-image grid | Grid arrangement, uniform sizing | Equal-width equal-height `<image>` matrix |
| Person photo | Circular crop effect | `<circle>` background + square image overlay (post-processing crops) |

### Typography Hierarchy

```
Title layer   → 28-36px, bold, theme color or white
Subtitle layer → 20-24px, medium weight, secondary color
Body layer    → 16-18px, regular, dark gray
Annotation layer → 12-14px, light gray, bottom-aligned
```

---

## Speaker Notes Style

### Narrative Tone

General style speaker notes use **conversational narration** — like talking with the audience, not reading a report. Natural tone with rhythm, using rhetorical devices where appropriate.

### Stage Direction Markers

| Marker | Purpose | Example |
|--------|---------|---------|
| `[Pause]` | Silence after key reveal, letting the audience absorb | "What does this number mean? [Pause] It means 1 in every 3 users..." |
| `[Interactive]` | Ask questions or guide audience participation | "[Interactive] How many of you have used this feature?" |
| `[Transition]` | Bridge from previous page, must be at start of each page's text | "[Transition] Now that we understand the context, let's see how it works." |

### Notes Writing Guidelines

- **Tell stories**: Use "scenario-conflict-resolution" structure for each page's narrative
- **Use metaphors**: Make abstract concepts tangible ("It's like adding a turbocharger to the system")
- **Create suspense**: Pose questions at the right time, answer on the next page
- **Conversational data**: 30% → "nearly one-third", 2.5x → "more than doubled"
- **Key points structure**: `Key points: (1) Core message (2) Supporting evidence (3) Call to action`

### Notes Example

```markdown
# 03_key_advantages

[Transition] Having covered the market landscape, you might be wondering: where is our opportunity?

Our core advantages can be summed up in three words: Fast, Accurate, Efficient.
Fast — deployment time cut from 3 months to 2 weeks; [Pause]
Accurate — recognition accuracy at 97.3%, far exceeding the industry average of 82%;
Efficient — overall costs reduced by nearly one-third.

[Interactive] If you were the decision-maker, which of these three numbers would impress you most?

Key points: (1) Three differentiating advantages (2) Quantitative data support (3) Prompt for reflection
Duration: 2 minutes
```

---

## Self-check Supplement (General-specific)

- [ ] Visual rhythm is reasonable: data-dense pages alternate with breathing pages
- [ ] Decorative elements are moderate: serving content, not overshadowing it
- [ ] Image-text ratio is appropriate: not just text walls, visual highlights present
- [ ] Notes are conversational: reads like speaking, not reading a script


path: references/image-layout-spec.md
content: > See shared-standards.md for common technical constraints.

# Image Layout Specification (Mandatory)

Layout rules for pages containing images. Both the Strategist planning phase and Executor generation phase must follow these rules.

**Core principle: Calculate layout based on the image's original aspect ratio, ensuring the image is displayed completely without excess whitespace or cropping.**

---

## Layout Decision Flow

```
1. Get image original dimensions → Calculate ratio (width/height)
2. Select layout type based on ratio
3. Calculate maximum display size for the image
4. Allocate remaining space for text area
5. Fill results into the Design Specification's image resource list
```

**When to execute**: If the image approach includes "B) User-provided", after the Strategist completes the Eight Confirmations and before content analysis and outlining, the scan must be run and the image resource list populated.

---

## Layout Type Selection (Mandatory)

| Image Ratio | Layout Type | Image Position | Description |
|-------------|-------------|----------------|-------------|
| > 2.0 (ultra-wide) | Top-bottom split | Top full-width | Image spans canvas width, height proportional |
| 1.5-2.0 (wide) | Top-bottom split | Top | Image width = content area width, height proportional |
| 1.2-1.5 (standard) | Left-right split | Left | Image height-first fit, width proportional |
| 0.8-1.2 (square) | Left-right split | Left | Image takes content area height, width proportional |
| < 0.8 (portrait) | Left-right split | Left | Image height = content area height, width proportional |

> Edge cases: When ratio is at a boundary (e.g., 1.5), decide based on text volume. More text → left-right; less text → top-bottom.

---

## Dimension Calculation Formulas

### PPT 16:9 (1280x720) Canvas Parameters

```
Canvas: 1280 x 720 px
Content area: 1160 x 640 px (left/right margin 60px, top/bottom margin 40px)
Title area height: 60 px
Content start: y = 80 px (title + spacing)
```

### Top-Bottom Layout Calculation

```
Image width = W = 1160 px
Image height = W / R = 1160 / R px
Text area height = H - image height - gap(20px)

Validation: Text area height >= 150px (at least 3-4 lines of text)
If not satisfied → Switch to left-right layout
```

### Left-Right Layout Calculation

**Method 1 (height-first, suitable for portrait images)**:
```
Image height = H = 600 px
Image width = H x R = 600 x R px
Text area width = W - image width - gap(20px)
```

**Method 2 (width-constrained, for wide images converted to left-right)**:
```
Image width = W x 0.7 = 812 px
Image height = image width / R
Text area width = W - image width - gap(20px)
```

**Validation**: Text area width >= 280px; otherwise reduce image area width.

---

## Layout Examples

### Ultra-wide Image (ratio 2.45)

```
Original: 1960x800, R=2.45 → Top-bottom split
Image: 1160x473, Text area: 1160x147 → 7:3 top-bottom
```

### Standard Landscape (ratio 1.38)

```
Original: 1614x1171, R=1.38 → Left-right split
Image: 773x560 (left), Text area: 367x560 (right) → 7:3 left-right
```

### Wide Image Edge Case (ratio 1.75)

```
Original: 1820x1040, R=1.75
Try top-bottom: image height=663, text area=-43 ❌
Switch to left-right: image 780x446 (left), text area 360x600 (right) → 7:3 left-right
```

---

## Prohibited Practices

| Prohibited | Correct Approach |
|-----------|-----------------|
| Fixed 50:50 or arbitrary ratios | Dynamic calculation based on image ratio |
| Forcing wide image into square container | Use top-bottom layout or increase image area width |
| Placing portrait image in narrow horizontal strip | Use left-right layout, image on left |
| Image whitespace exceeding 10% | Recalculate layout or choose alternative approach |
| Cropping key image content | Use `preserveAspectRatio="xMidYMid meet"` |
| Text area too small to read | Ensure text area >= 150px (top-bottom) or >= 280px (left-right) |

---

## SVG Image Embedding Code

### Complete Display (recommended for data charts)

```xml
<image href="../images/xxx.png"
       x="60" y="80" width="780" height="446"
       preserveAspectRatio="xMidYMid meet"/>
```

### Crop-to-Fill (backgrounds only)

```xml
<image href="../images/bg.png"
       x="0" y="0" width="1280" height="720"
       preserveAspectRatio="xMidYMid slice"/>
```

---

## 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

```bash
python3 scripts/analyze_images.py <project_path>/images
```

Output includes dimensions, ratios, and layout recommendations (Markdown table), which can be directly used to populate the image resource list.

---

## Role Responsibilities

| Role | Responsibility |
|------|---------------|
| **Strategist** | Run analyze_images.py, calculate layout per this spec, populate image resource list |
| **Executor** | Strictly follow the layout plan and dimensions in the image resource list when generating SVGs |


path: scripts/docs/troubleshooting.md
content: # Troubleshooting

## Validation Failed

1. Run:

```bash
python3 scripts/project_manager.py validate <project_path>
```

2. Fix missing files or invalid directories reported by the validator.
3. Re-run validation before post-processing or export.

## SVG Preview Looks Wrong

1. Check the file path and filename.
2. Confirm naming conventions are consistent.
3. Preview via a local server if browser file loading is inconsistent:

```bash
python3 -m http.server --directory <svg_output_path> 8000
```

## Speaker Notes Do Not Split

Check `total.md`:
- headings must start with `# `
- heading text must match SVG filenames
- sections must be separated by `---`

Then rerun:

```bash
python3 scripts/total_md_split.py <project_path>
```

## PPT Export Quality Issues

Preferred sequence:

```bash
python3 scripts/total_md_split.py <project_path>
python3 scripts/finalize_svg.py <project_path>
python3 scripts/svg_to_pptx.py <project_path> -s final
```

Do not export directly from `svg_output/` when `svg_final/` exists.

## Dependency Checklist

Most tools use the standard library. Install extra dependencies only when needed:

```bash
pip install -r requirements.txt
```

Important optional packages:
- `python-pptx` for PPTX export
- `Pillow` for image utilities
- `numpy` for watermark removal
- `PyMuPDF` for PDF conversion
- `google-genai` / `openai` for image generation backends


path: scripts/image_backends/__init__.py
content: """Internal backend implementations for image_gen.py."""


path: scripts/svg_finalize/__init__.py
content: """Internal SVG finalize helpers used by finalize_svg.py and compatibility wrappers."""


path: scripts/svg_to_pptx/__init__.py
content: """svg_to_pptx — SVG to PPTX conversion package.

Public API:
    - main(): CLI entry point
    - convert_svg_to_slide_shapes(): SVG -> DrawingML slide XML
    - create_pptx_with_native_svg(): Build PPTX from SVG files
"""

from .pptx_cli import main
from .drawingml_converter import convert_svg_to_slide_shapes
from .pptx_builder import create_pptx_with_native_svg

__all__ = [
    'main',
    'convert_svg_to_slide_shapes',
    'create_pptx_with_native_svg',
]


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)