ppt-master-plus
Generate or redesign editable presentations, preserve and edit an existing native PPTX, or create a new PPTX from a user-supplied PPTX design template. Supports the Plus Step 1–7 confirmation workflow, native round-trip editing, template-aware page planning, Live Preview, notes, narration, motion, and quality validation. Use when the user asks to create, edit, beautify, fill, or narrate a PPT/PPTX/presentation, says "生成PPT" or "做PPT", or mentions "ppt-master-plus".
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/gnuhpc--ppt-master-plus)HTML
<a href="/listings/gnuhpc--ppt-master-plus"><img src="/api/listings/gnuhpc--ppt-master-plus/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
复制以下 prompt,发给你的 AI Agent 即可完成安装:
请安装并使用 ppt-master-plus skill:https://github.com/gnuhpc/ppt-master-plus 可选伴侣 skill(按需安装,缺失时自动降级回内置 SVG): - fireworks-tech-graph(正式技术架构图):https://github.com/yizhiyanhua-ai/fireworks-tech-graph - excalidraw(手绘/白板风格):https://github.com/Agents365-ai/excalidraw-skill - Mermaid(流程图/时序图/ER 图):https://github.com/Agents365-ai/creating-mermaid-diagrams - PlantUML(UML/组件图):https://github.com/Agents365-ai/plantuml-skill - draw.io(拓扑/云厂商图标):https://github.com/Agents365-ai/drawio-skill - tldraw(tldraw 白板):https://github.com/Agents365-ai/tldraw-skill
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 805 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- ---
- name: ppt-master-plus
- description: >
- Generate or redesign editable presentations, preserve and edit an existing
- native PPTX, or create a new PPTX from a user-supplied PPTX design template.
- Supports the Plus Step 1–7 confirmation workflow, native round-trip editing,
- template-aware page planning, Live Preview, notes, narration, motion, and
- quality validation. Use when the user asks to create, edit, beautify, fill,
- or narrate a PPT/PPTX/presentation, says "生成PPT" or "做PPT", or mentions
- "ppt-master-plus".
- ---
- # PPT Master Plus
- > Produce editable presentations with a choice of per-slide confirmed refinement
- > or fully automatic one-pass execution, backed by the PPT Master SVG/PPTX toolchain.
- ## Three Public Routes
- Read [`workflows/routing.md`](workflows/routing.md) first and select exactly one:
- 1. [`Generate PPTX`](workflows/generate-pptx.md) — generate or redesign visible pages.
- 2. [`Edit Native PPTX`](workflows/edit-native-pptx.md) — preserve the supplied deck and modify it.
- 3. [`Import Brand PPTX`](workflows/import-brand-pptx.md) — import an explicitly user-provided `.pptx` file as a reusable Brand asset plus a confirmed native Page Kit. This does not create a presentation project or generate slides.
- For Import Brand PPTX, chart, table, infographic, and diagram styling defaults
- to the Skill's built-in visualization catalogs. On an explicit user request,
- `--register-icon-layout <id>` or `--register-chart-layout <id>` creates a
- narrow companion Layout for icon or chart visual grammar. Such a Layout may
- guide icon treatment or chart type, series palette, axes, gridlines, legend, and label rules;
- it never carries source data, page topology, object geometry, or sample copy.
- The import itself is always a Brand: it contributes locked identity tokens and
- reusable brand assets.
- This route starts only from a `.pptx` file path explicitly supplied by the user.
- It is a standalone asset-import route: use `scripts/import_brand.py <file>
- --brand-id <id>` to materialize identity tokens and a linked, user-confirmed
- Page Kit under `templates/brands/<id>/` and `templates/layouts/`. Do not create a `projects/` entry,
- resolve a bare template name, or choose an internal Brand/Style/Layout/Pack asset.
- The source PPTX and unconfirmed page topology are never registered. The importer
- always launches Brand Import Web and waits for the user to confirm extracted
- color and typography rules plus the exact cover, TOC, section-transition,
- content Master/Layout, and closing pages. Only those confirmed rows may be registered.
- For a confirmed content row, registration removes every slide-local object and
- keeps only its linked Master/Layout layer, including Master background images,
- Master text, and Master/Layout placeholders. On an equally
- explicit request, `--register-icon-layout <id>` and
- `--register-chart-layout <id>` create separate companion Layouts for icon or
- chart visual grammar only.
- The Step 1–7 procedure below is the frozen Generate implementation. The template
- route adapts the same governance checkpoints and executes as a new-page Generate
- branch under the imported Brand; the native-edit route owns its own plan
- confirmation. SVG hand-writing rules apply to Generate and the imported-Brand
- branch.
- **Production modes**: **逐页确定精修** (`gated`) means every slide stops in Live Preview for user confirmation before the next slide; **全自动一次性生成** (`continuous`) means the deck proceeds continuously after the required design confirmation.
- **Core Pipeline**: `Source Document → Create Project → [Template] → Strategist → [Image_Generator] → Executor Live Preview → Quality Check → 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, subsequent non-BLOCKING steps may proceed automatically only in `continuous` mode. In `gated` / 逐页精修 mode, every page checkpoint is a new ⛔ BLOCKING stop.)
- > 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
- > 8. **SPEC_LOCK RE-READ PER PAGE** — Before generating each SVG page, Executor MUST `read_file <project_path>/spec_lock.md`. All colors / fonts / icons / images MUST come from this file — no values from memory or invented on the fly. Executor MUST also look up the current page's `page_rhythm` (`anchor` / `dense` / `breathing`), `page_layouts` (which template SVG to inherit, if any), and `page_charts` (which chart template to adapt, if any). Empty / absent entries are intentional Strategist signals — see executor-base.md §2.1. This rule exists to resist context-compression drift on long decks and to break the uniform "every page is a card grid" default
- > 9. **SVG MUST BE HAND-WRITTEN, NOT SCRIPT-GENERATED** — Every SVG page is written by the main agent directly, one page at a time (see rules 6 and 7). Writing or running a Python / Node / shell script that produces the SVG files in batch — looping over pages, templating from data, or emitting them via a generator — is FORBIDDEN, including under "save tokens", "quick draft", or "user is in a hurry" pretexts. The script-generation path was tried on a feature branch and abandoned: cross-page visual consistency depends on per-page authoring with full upstream context, which a generator script cannot reproduce
- > 10. **ROOT SVG CANVAS IS NON-OPTIONAL** — Before writing every slide, take its exact canvas dimensions from `spec_lock.md`; the root `<svg>` MUST include `xmlns`, unitless `width`, unitless `height`, and `viewBox`, with `width` / `height` exactly equal to the final two `viewBox` values. A missing `width` or `height` is a hard authoring failure even when the `viewBox` is correct: repair the root element before opening or advancing Live Preview. Follow `references/shared-standards.md §4` exactly.
- > [!IMPORTANT]
- > ## 🌐 Language & Communication Rule
- >
- > - **Response language**: match the user's input and source materials. Explicit user override (e.g., "请用英文回答") takes precedence.
- > - **Template format**: `design_spec.md` MUST follow its original English template structure (section headings, field names) regardless of conversation language. Content values may be in the user's language.
- > [!IMPORTANT]
- > ## 🔌 Compatibility With Generic Coding Skills
- >
- > - `ppt-master-plus` is a repository-specific workflow, not a general application scaffold
- > - Do NOT create `.worktrees/`, `tests/`, branch workflows, or generic engineering structure by default
- > - On conflict with a generic coding skill, follow this skill unless the user explicitly says otherwise
- Optional diagram companions are soft dependencies. Read
- [`references/diagram-routing.md`](references/diagram-routing.md) only when a
- slide may benefit from a formal technical diagram or an Excalidraw-style sketch.
- PPT Master 5.1 capabilities are provided by the unified engine. Read
- [`references/ppt-master-capability-overlay.md`](references/ppt-master-capability-overlay.md)
- only when the request or project needs native charts/tables/formulas/hyperlinks,
- structured Master/Layout output, layered round-trip import, advanced effects,
- or advanced motion/video. These capabilities never replace this file's Step 1–7
- sequence, Eight Confirmations, `gated` / `continuous` behavior, Confirm UI, or
- Live Preview. `--quick-generate` is unsupported in PPT Master Plus.
- ## Main Pipeline Scripts
- | Script | Purpose |
- |--------|---------|
- | `${SKILL_DIR}/scripts/source_to_md/pdf_to_md.py` | PDF to Markdown |
- | `${SKILL_DIR}/scripts/source_to_md/doc_to_md.py` | Documents to Markdown — native Python for DOCX/HTML/EPUB/IPYNB, pandoc fallback for legacy formats (.doc/.odt/.rtf/.tex/.rst/.org/.typ) |
- | `${SKILL_DIR}/scripts/source_to_md/excel_to_md.py` | Excel workbooks to Markdown — supports .xlsx/.xlsm; legacy .xls should be resaved as .xlsx |
- | `${SKILL_DIR}/scripts/source_to_md/ppt_to_md.py` | PowerPoint to Markdown |
- | `${SKILL_DIR}/scripts/pptx_intake.py` | PPTX intake; `--intent template` adds template manifest, tokens, archetypes, assets, and previews |
- | `${SKILL_DIR}/scripts/brand_import_ui/server.py` | Brand Import Web; confirm the only special-page prototypes and content Master/Layout shells allowed into a linked Page Kit |
- | `${SKILL_DIR}/scripts/source_to_md/web_to_md.py` | Web page to Markdown (supports WeChat via `curl_cffi`) |
- | `${SKILL_DIR}/scripts/project_manager.py` | Project init / validate / manage |
- | `${SKILL_DIR}/scripts/import_brand.py` | Standalone user-PPTX → reusable Brand plus confirmed native Page Kit; creates no presentation project |
- | `${SKILL_DIR}/scripts/icon_sync.py` | Copy chosen library icons into `<project>/icons/` at selection time; missing names reported + non-zero (re-pick gate) |
- | `${SKILL_DIR}/scripts/analyze_images.py` | Image analysis |
- | `${SKILL_DIR}/scripts/latex_render.py` | LaTeX formula rendering (manifest-driven PNG assets) |
- | `${SKILL_DIR}/scripts/image_gen.py` | AI image generation (multi-provider) |
- | `${SKILL_DIR}/scripts/svg_quality_checker.py` | SVG quality check |
- | `${SKILL_DIR}/scripts/check_speaker_notes.py` | Speaker-note coverage and delivery-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/pptx_to_svg.py` | Native source-preserving round-trip import |
- | `${SKILL_DIR}/scripts/svg_authoring_view.py` | Refresh/adopt objects in the native authoring view |
- | `${SKILL_DIR}/scripts/native_preview.py` | Connect native authoring pages to the frozen Live Preview UI |
- | `${SKILL_DIR}/scripts/svg_to_pptx.py` | Export to PPTX |
- | `${SKILL_DIR}/scripts/update_spec.py` | Propagate a `spec_lock.md` color / font_family change across all generated SVGs |
- | `${SKILL_DIR}/scripts/export_video.py` | Export slide SVGs with Speaker Notes TTS audio narration into an MP4 video presentation |
- | `${SKILL_DIR}/scripts/critic_audit.py` | Run independent adversarial Critic audit (WCAG contrast, Claim Ledger, Footer Band Protection, Placeholders) |
- For complete tool documentation, see `${SKILL_DIR}/scripts/README.md`.
- > **Windows note**: if a `python3 ...` command fails (common on python.org installs, which provide `python.exe` but not `python3.exe`), rerun the same command with `python` instead.
- ## Template Index
- | Index | Path | Purpose |
- |-------|------|---------|
- | Layout templates | `${SKILL_DIR}/templates/layouts/layouts_index.json` | Query available page layout templates |
- | Brand presets | `${SKILL_DIR}/templates/brands/brands_index.json` | Query available brand identity presets (color / typography / logo / voice, includes `swiss_grid`) |
- | Visualization templates | `${SKILL_DIR}/templates/charts/charts_index.json` | Query available visualization SVG templates (charts, infographics, diagrams, frameworks, includes `diagram_shell` and `code_diff`) |
- | Communication styles | `${SKILL_DIR}/templates/styles/styles_index.json` | Query reusable method/design-default workspaces only after an explicit Style path is supplied |
- | Native table templates | `${SKILL_DIR}/templates/tables/tables_index.json` | Query stable row/column table structures when the page requires one |
- | Motion sounds | `${SKILL_DIR}/templates/sounds/sounds_index.json` | Query licensed sounds only inside an explicitly requested animation/video workflow |
- | Icon library | `${SKILL_DIR}/templates/icons/` | See `${SKILL_DIR}/templates/icons/README.md`; search icons on demand with `ls templates/icons/<library>/ \| grep <keyword>` |
- ## Profiles, Stages, Modules, and Internal Tools
- | Class | Entries |
- |---|---|
- | Generate Profiles | `profiles/faithful-beautify.md`, `profiles/image-to-pptx.md` |
- | Source Adapter | `adapters/humanize-ppt-bridge.md` |
- | Stages | topic research, refine spec, resume execute, Live Preview, visual review, chart verification, animations, audio |
- | Edit Native modules | `page_plan`, `content_edit`, `notes`, `narration`, `transitions`, `animations`, `visible_content_locked` |
- | Internal maintenance | `internal/template-authoring/` for Brand, Style, Layout, and Pack assets |
- These are not additional public workflows. `gated-production.md` is a Generate
- execution mode. Old native-enhance, native-narration, and template-fill entrypoints
- do not exist in this breaking version.
- ---
- ## 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).
- > **No source content?** When the user supplies only a topic name or requirements without any file or substantive description, run the [`topic-research`](workflows/stages/topic-research.md) workflow first, then return here with its products as input.
- When the user provides non-Markdown content, convert immediately:
- | User Provides | Command |
- |---------------|---------|
- | PDF file | `python3 ${SKILL_DIR}/scripts/source_to_md/pdf_to_md.py <file>` |
- | DOCX / Word / Office document | `python3 ${SKILL_DIR}/scripts/source_to_md/doc_to_md.py <file>` |
- | XLSX / XLSM / Excel workbook | `python3 ${SKILL_DIR}/scripts/source_to_md/excel_to_md.py <file>` |
- | CSV / TSV | Read directly as plain-text table source |
- | PPTX / PowerPoint deck | `python3 ${SKILL_DIR}/scripts/source_to_md/ppt_to_md.py <file>` for Markdown content; after Step 2 `import-sources`, standard PPTX intake is also written to `<project>/analysis/` |
- | EPUB / HTML / LaTeX / RST / other | `python3 ${SKILL_DIR}/scripts/source_to_md/doc_to_md.py <file>` |
- | Web link | `python3 ${SKILL_DIR}/scripts/source_to_md/web_to_md.py <URL>` |
- | WeChat / high-security site | `python3 ${SKILL_DIR}/scripts/source_to_md/web_to_md.py <URL>` (requires `curl_cffi`, included in `requirements.txt`) |
- | Markdown | Read directly |
- > **Office vector assets (EMF/WMF) from DOCX/PPTX sources**:
- > `doc_to_md.py` / `ppt_to_md.py` extract embedded Office vector images (.emf/.wmf)
- > alongside bitmap images. After `import-sources`, these land in `images/`
- > together with `image_manifest.json` and are first-class assets in §VIII Image Resource List.
- >
- > **Do NOT convert EMF/WMF to PNG.** The PPT Master pipeline preserves them as external
- > references (`finalize_svg.py` skips them) and `svg_to_pptx.py` embeds them as
- > PPTX-native media via `image/x-emf` / `image/x-wmf` MIME — PowerPoint renders them at full vector fidelity.
- > Converting via LibreOffice/Inkscape introduces CJK font substitution drift and
- > rasterization loss; the original EMF/WMF is always higher fidelity than the converted PNG.
- >
- > Browser-based live preview cannot render EMF (will show blank) — this is expected;
- > the PPTX output is the source of truth.
- **✅ 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 |
- For PPTX sources, `import-sources` automatically runs the standard intake enrichment:
- ```bash
- python3 ${SKILL_DIR}/scripts/pptx_intake.py <project_path>/sources/<source.pptx> -o <project_path>/analysis
- ```
- For each PPTX it writes `<stem>.identity.json` (canvas, theme palette/fonts, observed usage) and `<stem>.slide_library.json` (text slots, geometry, native tables, native chart caches), and merges that deck's Strategist-facing digest into the single multi-deck index `analysis/source_profile.json` (`decks[]`, one self-contained entry per source deck, with prefixed artifact pointers). In the main generation path these are source facts and recommendation candidates, not replica constraints; the faithful-beautify workflow decides separately which fields become locked constraints.
- For generic PPTX beautification, `analysis/source_profile.json` is context only. It may suggest canvas, chart/table presence, source images, and brand signals, but it must not lock page count, slide order, text wording, source palette, fonts, or master/layout preservation. The Markdown extracted by `ppt_to_md.py` is the content source; Strategist rebuilds the deck.
- Multi-deck: several PPTX files may be imported into one main-pipeline project — each gets its own `<stem>.*` artifacts and a deck entry in `source_profile.json`. `source_profile.json` stays the single must-read index (one entry for a one-deck project, several for a combined-source project). Stems must be distinct; re-importing the same stem replaces that deck's entry. The faithful-beautify workflow remains single-deck (1:1 to one chosen source deck) and reads that deck's `<stem>.*` artifacts.
- > ⚠️ **MUST use `--move`** (not copy): all source files — Step 1's generated Markdown, original PDFs / MDs / images — go into `sources/` via `import-sources --move`. After execution they no longer exist at the original location. Intermediate artifacts (e.g., `_files/`) are handled automatically.
- **✅ Checkpoint — Confirm project structure created successfully, `sources/` contains all source files, converted materials are ready. Proceed to Step 3.**
- ---
- ### Step 3: Template Option
- 🚧 **GATE**: Step 2 complete; project directory structure is ready.
- **Default — free design.** Proceed directly to Step 4. Do NOT query any `*_index.json` unless triggered. Do NOT ask the user. Do NOT proactively suggest, hint at, or fuzzy-match any template based on content, slug-like words, or vague style descriptions.
- **Template flow triggers ONLY on explicit internal template directory paths** supplied by the user in their initial message. The path must resolve under `${SKILL_DIR}/templates/{brands,styles,layouts,packs}/`; arbitrary user-provided or external template directories are not accepted. Legacy Plus packages expose `design_spec.md` at the selected root; current additive workspaces expose `templates/design_spec.md`. The trigger rule is mechanical, not interpretive:
- | User input contains | Step 3 action |
- |---|---|
- | One or more explicit internal template directory paths under `${SKILL_DIR}/templates/{brands,styles,layouts,packs}/` (each resolves to either `design_spec.md` or `templates/design_spec.md` with `kind: brand` / `kind: style` / `kind: layout` / `kind: pack` in its YAML frontmatter) | Read each spec's `kind`; expand a Pack to its referenced components, then dispatch the resolved Brand/Style/Layout set |
- | Anything else — bare template names ("用 academic_defense"), style descriptions ("麦肯锡风格"), brand mentions ("招商银行风格"), vague intent ("想用个模板"), or silence | Skip Step 3, free design |
- There is no slug matching, no name lookup, no fuzzy resolution. A name without a path does not trigger — the user must give an internal bundled-template path the AI can `cd` into.
- > An external/uploaded PPTX used as a design skeleton does not enter Generate
- > Step 3; route it to [`Import Brand PPTX`](workflows/import-brand-pptx.md).
- > Other arbitrary external template directories are not accepted by this Generate step.
- > Style descriptions ("麦肯锡风格" / "Keynote 风" / "极简风" / etc.) never trigger Step 3. They flow into Strategist's Eight Confirmations as a style brief (color / typography / tone in confirmations e–g).
- > Bare names ("academic_defense", "招商银行", "anthropic") do NOT trigger Step 3 even if a matching directory exists in the library. The user must give a path. AI must not "helpfully" resolve a name to a path.
- > "What templates exist?" is out-of-band Q&A — answer by listing entries from `brands_index.json`, `styles_index.json`, `layouts_index.json`, and `packs_index.json` together with their paths. Listing alone does not advance the pipeline; the user must send a path back to trigger Step 3.
- > Brand, Style, Layout, and Pack asset authoring is an internal maintenance task
- > under `workflows/internal/template-authoring/`, not a user-facing route.
- #### Four template kinds
- The architecture has four independent reference bundles. Full schema in [`docs/zh/templates-architecture.md`](references/templates-architecture.md). Summary:
- | Kind | Physical dir | Contains | Frontmatter |
- |---|---|---|---|
- | **brand** | `templates/brands/<id>/` | identity-only segment: color / typography / logo / voice / icon style | `kind: brand` |
- | **style** | `templates/styles/<id>/` | reusable communication method and design defaults; no identity or SVG roster | `kind: style` |
- | **layout** | `templates/layouts/<id>/` | structure-only segment: canvas / page structure / page types / SVG roster | `kind: layout` |
- | **pack** | `templates/packs/<id>/` | metadata-only references to at least two of Brand / Style / Layout; no design fields or assets | `kind: pack` |
- **Segment ownership**:
- | Segment | Sections | Owner kind on fusion |
- |---|---|---|
- | Identity | Color Scheme / Typography / Logo / Voice & Tone / Icon Style | brand |
- | Structure | Canvas / Page Structure / Page Types / SVG Roster | layout |
- | Combination metadata | Component ids, discovery summary, keywords | pack; never consumed as a design segment |
- #### Single-path dispatch
- | User path's `kind` | Step 3 action |
- |---|---|
- | `kind: brand` | `design_spec.md` + non-image assets → `<project>/templates/`; logo / illustration / icon **bitmaps** → `<project>/images/`. Strategist locks identity segment as truth; structure stays free. |
- | `kind: style` | Install the Style spec as a method/default input under `<project>/templates/`; it may seed argument flow, evidence discipline, density, and visual defaults, but never locks identity, page count, page order, geometry, or SVG prototypes. |
- | `kind: layout` | `design_spec.md` + SVG roster → `<project>/templates/`; any **bitmap** assets → `<project>/images/`. Strategist locks structure; identity decided in Eight Confirmations e–g. |
- | `kind: pack` | Validate the Pack, expand its `brand_id` / `style_id` / `layout_id`, install the referenced components, and retain `design_spec.pack.<id>.md` only for provenance and resume. Pack never supplies design values itself. |
- ```bash
- TEMPLATE_DIR=<internal bundled template path under ${SKILL_DIR}/templates>
- # Bitmaps join the project's single runtime image pool (images/, referenced as
- # ../images/); the spec + template SVGs + other non-image assets stay in
- # templates/ as design reference the Strategist/Executor read but never render.
- cp -r ${TEMPLATE_DIR}/* <project_path>/templates/
- find <project_path>/templates -type f \( -iname '*.png' -o -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.gif' -o -iname '*.webp' -o -iname '*.bmp' \) -exec mv {} <project_path>/images/ \;
- ```
- Brand and Layout may contribute assets; bitmaps always land in `images/`, while specs, Layout SVGs, and other non-image assets stay in `templates/`. Style and Pack are metadata-only. Template SVGs are reference material; rendered pages live in `svg_output/`.
- #### Multi-path fusion
- When the user supplies a Pack, resolve it first. A user-supplied explicit Brand, Style, or Layout replaces the Pack's reference of the same kind; unoverridden Pack references remain. At most one Pack may be selected, and the resolved set contains at most one Brand, one Style, and one Layout.
- Override priority by segment:
- | Resolved input | Identity | Direction / method | Structure |
- |---|---|---|---|
- | brand only | Brand | current project | free |
- | style only | current project | Style | free |
- | layout only | current project | current project | Layout |
- | pack | referenced or explicit Brand | referenced or explicit Style | referenced or explicit Layout |
- | explicit components + pack | explicit component wins its kind | explicit component wins its kind | explicit component wins its kind |
- Field-level micro-adjustment (e.g. "use anthropic brand but primary changed to #FF0000") is **not** part of Step 3 fusion — it flows into Strategist Eight Confirmations e–g as a normal user request.
- #### Same-kind multiple paths — conflict resolution
- When the user gives two paths of the **same kind** (e.g. `brands/anthropic` + `brands/google`), Step 3 surfaces a conflict prompt before fusing — like resolving a git merge conflict:
- ```
- AI: 你给了两个 brand,检测到段级冲突:
- - Color Scheme(Anthropic 橙红 vs Google 多色)
- - Typography(Styrene/AnthropicSans vs GoogleSans/Roboto)
- - Logo(Anthropic 标 vs Google 标)
- - Voice & Tone(restrained vs friendly)
- - Icon Style(stroke vs filled)
- 要 (a) 全部按 Anthropic / (b) 全部按 Google / (c) 逐段挑?
- ```
- Rules:
- - Default: no implicit ordering — every cross-source segment difference is reported as a conflict
- - Only when the user picks `(c)` does AI walk through each segment one by one
- - Field-level conflicts are out of scope — segment-level only
- - Three or more same-kind paths are not supported — ask the user to converge to at most two
- #### Fused spec provenance
- When a Pack or multiple components are installed, keep one qualified spec per kind and record the resolved set in the template handoff:
- ```markdown
- > **Resolved from Pack:** `传统行业_商业汇报全场景`
- > - brand: none
- > - style: `operating-review`
- > - layout: `传统行业_商业汇报全场景`
- ```
- Pack provenance never overrides component contents. Strategist reads only Brand, Style, and Layout as design inputs.
- **✅ Checkpoint — Default path proceeds to Step 4 without user interaction. If the user supplied one or more explicit internal template paths, those have been dispatched (or fused) into `<project_path>/templates/` before advancing.**
- ---
- ### Step 4: Strategist Phase (MANDATORY — cannot be skipped)
- 🚧 **GATE**: Step 3 complete; default free-design path taken, or (if triggered) template files copied into the project.
- First, read the role definition:
- ```
- Read references/strategist.md
- ```
- > ⚠️ **Mandatory gate**: before writing `design_spec.md`, Strategist MUST `read_file templates/design_spec_reference.md` and follow its full I–XI section structure. See `strategist.md` Section 1.
- **`<project_path>/analysis/` is the project's intermediate-analysis folder: the canonical home for machine-extracted source/asset facts — the PPTX intake bundle (`source_profile.json` index + per-deck `<stem>.identity.json` / `<stem>.slide_library.json`) and `image_analysis.csv`. It holds facts, not design contracts — `design_spec.md` / `spec_lock.md` stay at the project root.** The MUST-read contract covers only the **compact structured data files (`.json` / `.csv`)**; other artifacts that may live under `analysis/` (e.g. a faithful-beautify `source_svg_import/` vector reference package) are NOT bulk-read — they are read selectively only when a specific workflow step calls for them. Before the Eight Confirmations, Strategist MUST read the auto-extracted fact files already in `analysis/` — currently `source_profile.json` (PPTX intake), when present. This file is the multi-deck index: read it once for the `decks[]` digests (canvas / chart / table entries per source deck), then open a specific deck's `<stem>.identity.json` / `<stem>.slide_library.json` only if you need its full raw facts. Use these entries as **factual source context** (format default + content facts); when several decks are present, synthesize across all of them. For generic PPTX beautification, `analysis/source_profile.json` is context only. It may suggest canvas, chart/table presence, source images, and brand signals, but it must not lock page count, slide order, text wording, source palette, fonts, or master/layout preservation. The Markdown extracted by `ppt_to_md.py` is the content source; Strategist rebuilds the deck. The source's **palette / typography / visual identity are a reference, not a constraint**: the main pipeline may inherit them where they fit the content and the confirmed style, or design fresh where they don't — the Strategist's judgment, never an obligation to either keep or discard. (Faithful beautify defaults to the source identity but still follows the confirmed values; the main pipeline treats source identity as reference only and defaults to fresh design.) (`image_analysis.csv` lands later, at the image-analysis step below, and is the authoritative regenerated image-fact view there — re-derived from the live `images/` folder, not a durable store.)
- **Channel ownership — read each fact once from its owning channel.** In the main pipeline the **content contract is the Markdown** (`sources/<stem>.md`): text, tables, and chart data values all come from there (`ppt_to_md` now transcribes native chart data into Markdown tables). The `analysis/` chart / table entries are a **structural digest** for outline decisions (which slides carried charts, type, series names) — not a second copy of the values; do NOT also pull chart values from `<stem>.slide_library.json` in the main pipeline. The `<stem>.slide_library.json` full structured data is owned by faithful beautify for native chart / table data while keeping slide text from the Markdown.
- **Eight Confirmations** (full template: `templates/design_spec_reference.md`):
- ⛔ **BLOCKING**: present the Eight Confirmations and **wait for explicit user confirmation or modification** before outputting Design Specification & Content Outline. This is the single core confirmation gate — once the final confirmation lands, all subsequent steps proceed automatically. The default Confirm UI delivers the gate in **two tiers** (anchors → re-derive → realization; see below); the chat fallback mirrors the same two steps.
- 1. Canvas format
- 2. Page count range
- 3. Target audience
- 4. Style objective
- 5. Color scheme
- 6. Icon usage approach
- 7. Typography plan, including formula rendering policy
- 8. Image usage approach
- **Confirm UI Auto-Launch (Mandatory — default visual confirmation surface)**: by default the Eight Confirmations are presented through an interactive local page in **two tiers within one browser session** — Tier 1 confirms the *anchors*; the AI then re-derives the realization layer from the **user's actual** anchors; Tier 2 confirms that layer. Color swatches, live font previews, candidate picks; the chat path is the always-valid fallback. The split (full field rules: [`scripts/docs/confirm_ui.md`](scripts/docs/confirm_ui.md)):
- | Tier | Confirms | Driven by |
- |---|---|---|
- | **1 — anchors** | canvas · **brand** *(optional — `"none"` = free design; a brand id drives color / typography / icon style in Tier 2)* · audience + core message + `content_divergence` + `delivery_purpose` *(PPT only — omitted on non-PPT canvases)* (all §c key info) · `mode` + `visual_style` | the source + user intent |
- | **2 — realization** (re-derived from Tier 1) | page count · color · typography (font + size) · icons · formula policy · image usage + strategy · generation mode · transition effect · refine-spec toggle | the confirmed Tier 1 |
- > **Why two tiers.** Every realization field is anchored by the same few choices (`visual_style` anchors color / icon / typography / image; a confirmed **brand** preset anchors color / typography / icon style from its `design_spec.md`; `delivery_purpose` sets the body size, page density, **and** the page-count recommendation). Confirming anchors first, then re-deriving, means Tier 2's candidates fit the user's *real* anchors instead of your originals — the coherence reconciliation below is done by construction on this path. Page count is a **derived** field (content volume × `delivery_purpose`), which is why it lives in Tier 2, not up front. For generic PPTX beautification, `content_divergence` is the primary control for how close the rebuilt deck stays to the source. Blank means balanced redesign.
- **Selected Brand → Tier 2 candidate contract (Mandatory)**: when Tier 1 confirms a Brand other than `none`, read that exact `templates/brands/<brand_id>/design_spec.md` before writing Tier 2. The Web page must receive the Brand identity as **visible, selectable first candidates**, never merely as a hidden influence on generated alternatives:
- - `color.candidates[0]` is named `"<Brand> 官方配色"`, carries the Brand's literal `## II. Color Scheme` values, and cites the Brand spec in its visible note. Map `bg → background`, `primary → primary`, `accent → accent`, and `text-body | text → body_text`; use a published neutral/surface for `secondary_bg` and a published non-white secondary or next accent for `secondary_accent`. Do not invent or replace published Brand HEX values.
- - `typography.candidates[0]` is named `"<Brand> 官方字体规范"`, maps the Brand's title/body/Latin families and weights from `## III. Typography` into the heading/body fields, and states the source family, weight, and type scale visibly in its note. When a Brand publishes sizes in pt, normalize them once for the px-only candidate (`px = pt × 4 / 3`, rounded to two decimals), seeding `body_size` and `sizes.title` / `sizes.subtitle` / `sizes.annotation`; retain the source pt scale only in the visible provenance note, never in `result.json`, `spec_lock.md`, or SVG.
- - These official candidates are selected by default. The normal ≥3-candidate rule still applies: provide at least two distinct coherent alternatives plus Custom. If a Brand omits a specific color, font, weight, or scale fact, disclose that gap in the candidate note and do not fabricate an “official” value.
- - The user’s Tier 2 choice is authoritative. Choosing another candidate or editing an official value is an explicit confirmed deviation; do not silently revert to the Brand after confirmation.
- Steps:
- > ⛔ **Steps 2 → 3 → 4 are ONE uninterrupted run — do NOT yield to the user mid-flow.** When the tier-1 `--wait` (step 2) returns, the AI **immediately and autonomously** continues to step 3 (re-derive + write Tier 2) and step 4 (`--wait-only`) in the **same turn**: do **not** summarize, ask a question, report progress, or end the turn in between. The browser is sitting on a "deriving…" spinner polling for the Tier 2 you must write next — stopping here strands the page and the user must prod you in chat to finish (a bug, not the intended flow). **The tier-1 confirmation is an intermediate machine handoff, not a stopping point.** The single ⛔ BLOCKING wait is the **final** confirmation at the end of step 4. (Chat-fallback path — only when the page never opened — is the exception: there you do present each tier in chat and wait for a reply.)
- 1. **Write Tier 1** to `<project_path>/confirm_ui/recommendations.json` with `"tier": 1` and only the anchor fields. Enumerable anchors (`canvas` / `brand` / `mode` / `visual_style` / `delivery_purpose`) name a recommended canonical `id` in a `recommend` block (the page lists common options from `confirm_ui/static/catalogs.json`; brands are synced live from `templates/brands/brands_index.json` — `brand` recommends `"none"` for free design, or a brand id like `"apsara_yunqi_26_light"`); `visual_style` also carries the ≥3-style `visual_style_spectrum` (safe / shifted / bold — same hard rule as h.5). `audience` and `content_divergence` are plain `{ "value": "<free text>" }`. `content_divergence` is the **free-text** field shown under audience in §c — how closely to follow the source vs how freely to reshape it (blank = balanced; facts stay sourced at every level); it is consumed by Strategist when authoring `§IX`, recorded in `design_spec.md §I`, carries no page-count coupling, and is **not** written to `spec_lock.md`. Set `lang` to the page language; visible text matches `lang`, or provide bilingual `name_zh` / `name_en` + `note_zh` / `note_en`.
- 2. **Launch + wait for Tier 1.** Background launch; the parent returns when the page writes the tier-1 `result.json`. **Long tool timeout — 600000 ms** (the `--wait` ≈590 s budget):
- ```bash
- python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --daemon --wait
- ```
- Page opens at `http://localhost:5050` — the **same port as the Step 6 live preview** (they never run at once: this page shuts down at the end of Step 4). If 5050 is held, the launcher **auto-advances** (5051, …) — read the actual URL from the launch log and report it. The page does **not** close after Tier 1: it shows a "deriving…" state and polls for Tier 2. **Launch or wait failure is non-fatal**: if it fails or times out (flask missing, port blocked, no GUI / remote / web host), do **NOT** troubleshoot — **on any non-zero exit, re-check `result.json` once** (a fresh `status: tier1-confirmed`) before dropping to the chat fallback. **On success (exit 0 with a tier-1 result), do not pause or report — go straight to step 3 in the same turn.**
- 3. **Re-derive Tier 2 from the confirmed anchors, then write it — immediately, same turn (the page is polling for it).** Read the tier-1 `result.json` (`status: tier1-confirmed`). Using the user's **actual** confirmed anchors (not your originals), author the realization candidates and **overwrite** `recommendations.json` with `"tier": 2`: page count (content volume × `delivery_purpose`); when a brand is confirmed (not `"none"`), read its `templates/brands/<id>/design_spec.md` and derive color candidates, typography candidates, and icon recommendation from the brand's identity segment (the brand's palette / fonts / icon style are the primary candidates, but the user still sees ≥3 choices — the brand palette is candidate 1, and ≥2 coherent alternatives are derived from the visual_style / content); color, typography, and generated-image style as **generative ≥3-candidate** fields (creative recommendations always offer real choice — same rule as h.5; fewer than 3 only on the honest-shortfall exception, with a stated reason; color: core `palette` with background/secondary_bg/primary/accent/secondary_accent/body_text; typography: CJK + Latin for `heading` and `body` with `css` preview stacks + `body_size` as the body baseline in **px** (every canvas) — **one fixed value per confirmed `delivery_purpose`** (`text` 20 / `balanced` 24 / `presentation` 32), not a range; images: `image_strategy.candidates` rendering × palette from h.5); enumerable `icons` / `formula_policy` / `generation_mode` (recommended `id`) / `transition_effect` (recommended `none` unless the user explicitly asked for page transitions); `image_usage` (`ai` / `web` / `provided` / `placeholder` / `none`, or a custom prose plan when several sources mix — never bare `"custom"`; write `image_ai_path` only when the plan includes AI). The still-open page polls, renders Tier 2, and preserves the user's Tier 1 picks. Closed fields (`image_ai_path`, `formula_policy`, `generation_mode`, `transition_effect`, `refine_spec`) stay finite; open fields (`icons`, `image_usage`, typography custom text) show a Custom box.
- The selected Brand candidate contract above is a **hard serialization requirement**: “primary candidate” means index `0`, selected by default, carrying the actual Brand values in `recommendations.json`; a prose recommendation or a visually similar generated palette/font does not satisfy it.
- 4. **Wait for the final confirmation** — attach to the already-running page, do **not** relaunch (same 600000 ms budget):
- ```bash
- python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --wait-only
- ```
- This is the ⛔ BLOCKING completion: returns when the page writes the final `result.json` (`status: confirmed`, `stage: final`, carrying all Tier 1 + Tier 2 fields). On a non-zero exit, re-check `result.json` once. Confirmed sizes are **already px** (the system is px-only — no pt anywhere, no conversion): write `result.json` `typography.body_size` / `sizes` into `design_spec.md` / `spec_lock.md` / SVG verbatim. `generation_mode: "split"` / `transition_effect` / `refine_spec: true` are explicit user choices.
- 5. **Close the confirm page (Mandatory cleanup — every path).** Shut the server down before leaving Step 4 so it cannot keep holding port 5050 (which Step 6 live preview reuses):
- ```bash
- python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --shutdown
- ```
- **Idempotent and required regardless of whether Confirm was clicked**: clicking the final Confirm already shuts the page down (then a no-op); the chat-fallback path leaves it running. Run it after reading the confirmation, before Step 5.
- **Confirm → Live Preview → Slide Construction Gate (Mandatory)**: after the final Confirm page result is accepted (and after Step 5, when image acquisition is required), the *next production action* must be the Step 6 Live Preview startup. Do **not** write, copy, sketch, or otherwise create any slide/SVG before that service has started successfully. Reading the executor references and preparing the confirmed specification is allowed; creating a presentation page is not. This ordering applies to every `svg_generate` branch, including imported Brand/Page Kit projects and resumed execution.
- **Always also print each tier's recommendations + URL in chat** as the always-valid fallback. **The chat fallback is two-step too**: if the page never opens or a wait times out with no fresh result, present Tier 1 in chat → get confirmation → re-derive → present Tier 2 → get confirmation → take those values. Either path converges.
- **Honoring the confirmation (result.json is authoritative — Mandatory)**: the confirmed values **override your own recommendations** when you write `design_spec.md` / `spec_lock.md`. A user who changed any field changed it on purpose. In particular, map `image_usage` to §VIII `Acquire Via` (its value names differ from §h options — translate):
- | `result.json.image_usage` | §VIII `Acquire Via` | h.5 + Step 5 generation |
- |---|---|---|
- | `ai` (or a custom plan that includes AI) | `ai` rows | Run h.5 (lock rendering + palette); Step 5 generates |
- | `web` | `web` rows | None |
- | `provided` | **`user`** rows | None — never generate |
- | `placeholder` | `placeholder` rows | None |
- | `none` | no image rows (§h option A) | None |
- When the confirmed `image_usage` is not `ai` (and the plan has no AI part), do **NOT** run h.5, do **NOT** write `ai` rows, and do **NOT** generate images in Step 5 — regardless of what you recommended. The same "confirmed value wins" rule applies to every field (color → §III, typography → §IV, etc.).
- **Upstream override → re-derive untouched downstream (Mandatory — chat-fallback / single-pass path).** On the **two-tier page path this is already handled** (Step 3 re-derives Tier 2 from the user's actual anchors). It still applies whenever anchors and realization are confirmed **together** — the two-step chat fallback collapsed into one bundle, or a legacy single-pass `result.json`. "Confirmed value wins" governs each field's *own* value — never recompute a value the user set (a size, canvas, or palette they edited stays verbatim). But a single-pass `result.json` can carry a changed **anchor** beside downstream fields still holding your original — now incoherent — recommendation (e.g. switched to `dark-tech` while the light palette you proposed is untouched). Before writing the spec, reconcile: when the user changed an anchor, re-derive the downstream fields the user did **not** themselves edit so they realize the new anchor; fields the user pinned stay as confirmed.
- | Anchor the user changed | Re-derive (only the downstream fields the user left at your recommendation) |
- |---|---|
- | `visual_style` (§d Layer 2 — anchors e–h) | color neutral tiers (§e), icon library / stroke (§f), typography character (§g), image rendering (§h.5) |
- | `brand` (brand preset `design_spec.md` — anchors e / f / g) | color palette (§e — brand primary / secondary / accent become candidate 1), icon style (§f — brand icon preference), typography character (§g — brand font families and weights) |
- | `mode` (§d Layer 1) | outline structure + register (§IX) |
- | `delivery_purpose` (§g) | body baseline + per-page density / rhythm (§6.1) |
- | `audience` / core message (§c) | tone across e–h, outline emphasis (§IX) |
- | `color` HEX (§e) | h.5 palette (re-filter for the new HEX) |
- Reconcile **without a new blocking wait** — fold the coherent values into `design_spec.md` / `spec_lock.md` and state the adjustment in the §8 next-step handoff (e.g. "you switched to `dark-tech`; the light palette you had left no longer fit, so background / accent were re-derived — tell me if you wanted the original"). Canvas is the explicit exception: font sizes are deliberately **not** rescaled on a canvas change (see strategist §g).
- **Mandatory Web Confirmation Page Launch (Unless Headless)**: When a user initiates a PPT generation request, launching / popping up the web confirmation page (Confirm UI) is **ALWAYS MANDATORY** — skipping the web confirmation page launch is ONLY permitted if the user/environment is headless (`headless` / CLI environment with no GUI). Chat-only confirmation is strictly a fallback for headless environments or launch execution failures.
- The page is a **confirmation surface only** — Strategist still authors every recommendation; the page never generates content.
- **Mandatory — split-mode note** (not a ninth confirmation): after listing the eight confirmation details, you MUST append exactly one short line (rendered in the user's language, prefixed with 💡) about generation mode. Pick the variant by qualitative read of Phase A signals — recommended page count, source-material bulk, whether `topic-research` ran with substantial web-fetch accumulation:
- | Signal read | Line content |
- |---|---|
- | Heavy (long page count / bulky sources / heavy web-fetch accumulation) | State estimated page count and large source size; recommend switching to [split mode](workflows/stages/resume-execute.md) after Step 5 — if the PPTX will be long, create a new chat/session and input `继续生成 projects/<project_name>` to enter Phase B (SVG generation + export), which avoids contaminating the final production context with planning history; if the deck is not large or the user wants to continue here, proceed to final production in the current chat. No response or "continue" = default continuous mode. |
- | Normal (default) | State scale is moderate, default continuous mode generates in one go; if the deck is short or moderate, continue into final production in this chat. If the user still wants a cleaner production context, they may input `继续生成 projects/<project_name>` after Step 5 in a new chat/session to switch to [split mode](workflows/stages/resume-execute.md). |
- This line is required output every run — the user must always see the mode choice exists. Whether to act on it is the user's call. When the Confirm UI is used, this choice also appears as the in-page generation-mode toggle and is captured in `result.json` (`generation_mode`); the chat-summary fallback still prints this line.
- **Mandatory — page-transition choice**: Tier 2 MUST include `transition_effect` with default/recommended value `none`. The user should confirm whether they need page transition animation; no response or unchanged default means **no transition animation**. Only when the user explicitly confirms an effect (`fade`, `push`, `wipe`, `split`, `strips`, `cover`, or `random`) should export enable it.
- **Mandatory — spec-refinement note** (not a ninth confirmation): after the split-mode line, you MUST append one short opt-in line (rendered in the user's language, prefixed with 💡) telling the user they may **refine the spec first** — Strategist will produce the full design spec, then stop for review/revision of any part of it before any generation, via the [refine-spec](workflows/stages/refine-spec.md) workflow. Default is OFF: no request → the spec is written in one go and the pipeline auto-proceeds as usual. Only when the user explicitly asks in chat (e.g. "refine the spec first") or confirms `refine_spec: true` through Confirm UI does the [refine-spec](workflows/stages/refine-spec.md) workflow take over after the Eight Confirmations. This line, like the split-mode line, is required output every run — the user must see the choice exists; whether to act on it is theirs. When the Confirm UI is used, this choice also appears as the in-page refine-spec toggle and is captured in `result.json` (`refine_spec`); the chat-summary fallback still prints this line.
- **Formula rendering policy lives inside item 7 (Typography plan)**:
- | Policy | Behavior |
- |---|---|
- | `mixed` (default) | Strategist renders complex formula-worthy expressions as PNG assets; simple inline expressions remain editable text / Unicode |
- | `render-all` | Strategist renders every formula-worthy expression as PNG assets |
- | `text-only` | No formula rendering; formulas remain editable text / Unicode |
- After the Eight Confirmations are approved and **before outputting `design_spec.md` / `spec_lock.md`**, if the confirmed formula policy is `mixed` or `render-all` and the content contains formula-worthy expressions, Strategist MUST:
- 1. Identify explicit LaTeX and any source expressions that should be faithfully structured as formulas.
- 2. Write `<project_path>/images/formula_manifest.json` with only the formulas selected for rendering.
- 3. Run:
- ```bash
- python3 ${SKILL_DIR}/scripts/latex_render.py <project_path>
- ```
- 4. Include the rendered formula PNGs as `Acquire Via: formula`, `Status: Rendered`, `Type: Latex Formula` rows in `design_spec.md §VIII Image Resource List`; also list them in `spec_lock.md images` with `| no-crop`.
- The formula renderer uses a provider fallback chain by default: `codecogs,quicklatex,mathpad,wikimedia`. The first three are color-aware; Wikimedia is an availability fallback. Formula PNGs are transparent by default: manifest `background` is the temporary render matte and transparency-removal reference, not a retained final background unless `transparent: false` is set for that item. Do not scan `spec_lock.md` for `$...$` or `$$...$$`. Dollar-delimited math in source material is only a signal for Strategist; the renderer consumes the explicit manifest.
- If the user provided images or formula PNGs were rendered, run analysis **before outputting the design spec**. It writes `analysis/image_analysis.csv` — the authoritative regenerated image-fact view in the `analysis/` folder, which MUST be read before authoring §VIII:
- ```bash
- python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images
- ```
- > 🔁 **Image facts are regenerated on demand, never a durable store.** `images/` is a live working folder — pictures are extracted from the source at import, the user may drop or replace files at any time, and Step 5 writes web/AI images into it. The single source of truth is therefore the **current contents of `images/`**, and `analysis/image_analysis.csv` is a *regenerated view* of it, not a fact to keep in sync. Re-run `analyze_images.py <project_path>/images` immediately **before any step that reads image facts** so the view reflects the live folder: before the §h image-usage recommendation (see [strategist.md](references/strategist.md) §h), here before authoring §VIII, after Step 5 acquisition (so web/AI files join the view), and again any time the user says they added or replaced images. This is the staleness strategy — re-derive on use, no cache to invalidate.
- > ⚠️ **Image handling**: NEVER directly read / open / view image files (`.jpg`, `.png`, etc.). All image info comes from `analyze_images.py` output (`analysis/image_analysis.csv`) or the Design Spec's Image Resource List.
- **Output**:
- - `<project_path>/design_spec.md` — human-readable design narrative
- - `<project_path>/spec_lock.md` — machine-readable execution contract (skeleton: `templates/spec_lock_reference.md`); Executor re-reads before every page. **Mandatory**: copy `generation_mode` from `result.json` into `spec_lock.md` (default `continuous` when absent) and copy `transition_effect` (default `none` when absent).
- When an additive PPT Master capability is active, add only its optional fields
- defined in [`ppt-master-capability-overlay.md`](references/ppt-master-capability-overlay.md).
- Their absence means legacy flat Plus behavior. Do not add fields merely because
- the vendored engine supports them, and never add a Confirm UI field for them.
- **✅ Checkpoint — Phase deliverables complete, auto-proceed to next step**:
- ```markdown
- ## ✅ Strategist Phase Complete
- - [x] Read the auto-extracted facts already in `analysis/` (e.g. `source_profile.json`) before the Eight Confirmations
- - [x] Eight Confirmations completed (user confirmed via Confirm UI `result.json` or chat fallback)
- - [x] Split-mode note appended below the eight items (heavy or normal variant)
- - [x] Spec-refinement opt-in line appended (default OFF; only the user's explicit request enters the refine-spec workflow)
- - [x] Design Specification & Content Outline generated
- - [x] Execution lock (spec_lock.md) generated
- - [ ] **Next**: Auto-proceed to [Image_Generator / Executor] phase
- ```
- ---
- ### Step 5: Image Acquisition Phase (Conditional)
- 🚧 **GATE**: Step 4 complete; Design Specification & Content Outline generated and user confirmed. Any formula rows already have `Acquire Via: formula` and `Status: Rendered`.
- > **Trigger**: At least one row in the resource list has `Acquire Via: ai` and/or `Acquire Via: web`. If every row is `user`, `formula`, or `placeholder`, skip to Step 6.
- **Always load the common framework**:
- ```
- Read references/image-base.md
- ```
- Then **lazy-load the path-specific reference** for each row that actually needs it:
- | Acquire Via | Load reference (only if any such row exists) | Run |
- |---|---|---|
- | `ai` | `references/image-generator.md` | `python3 ${SKILL_DIR}/scripts/image_gen.py --manifest <project_path>/images/image_prompts.json` |
- | `web` | `references/image-searcher.md` | `python3 ${SKILL_DIR}/scripts/image_search.py ...` (≥2 web rows → `--batch images/image_queries.json`) |
- | `user` / `placeholder` | (skip) | (skip) |
- A deck with only `ai` rows never loads `image-searcher.md`; a deck with only `web` rows never loads `image-generator.md`. A mixed deck loads both, processes each row through its own path, and writes both `image_prompts.json` and `image_sources.json`.
- > ⚠️ **In-pipeline ai path MUST use manifest mode** — even when only 1 ai row exists. Write `images/image_prompts.json` first, then run `image_gen.py --manifest`, then `image_gen.py --render-md` to produce the `image_prompts.md` sidecar. The positional form (`image_gen.py "prompt" ...`) is reserved for **out-of-pipeline one-off testing / single-image fixups** — it skips manifest + sidecar, leaving no audit trail.
- > ⚠️ **web path — batch multiple rows**: when ≥2 rows are `Acquire Via: web`, write all queries into `images/image_queries.json` and run `image_search.py --batch` once (concurrent acquisition, status written back), instead of one CLI call per row. A single web row may use the positional single-query form. See [image-searcher.md](references/image-searcher.md) §5.
- > ⚠️ **Honor the confirmed image source**: the `ai` generation path (Path A = `image_gen.py` API / Path B = host-native tool / Offline Manual) is **not** auto-only — a confirmed choice other than `auto` wins, whether it came from chat (canonical) or, when the page was used, `result.json.image_ai_path`. `host-native` forces Path B even when `IMAGE_BACKEND` is configured; `api` forces Path A; `manual` forces offline. The `--manifest` command above is Path A. Full selection rule: [image-generator.md](references/image-generator.md) §7 Path Selection.
- Workflow:
- 1. Extract all rows with `Status: Pending` and `Acquire Via ∈ {ai, web}` from the design spec
- 2. Generate prompts (ai rows) and/or run search (web rows) per [image-base.md](references/image-base.md) §2 dispatch table
- 3. Verify every row reaches a terminal status: `Generated` (ai success), `Sourced` (web success), or `Needs-Manual`
- 4. Re-derive image facts now that web / AI files are in the folder — `python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images` — so `analysis/image_analysis.csv` reflects every acquired image (real measured sizes) before the Executor lays them out. Image facts are regenerated on use, never a stale store (see Step 4's image-facts note).
- **✅ Checkpoint — Confirm acquisition attempted for every row**:
- ```markdown
- ## ✅ Image Acquisition Phase Complete
- - [x] image_prompts.json created (when any ai rows processed)
- - [x] image_prompts.md sidecar rendered (when any ai rows processed)
- - [x] image_sources.json created (when any web rows processed)
- - [x] Each row: status is `Generated` / `Sourced` / `Needs-Manual` (no `Pending` remaining)
- - [x] analyze_images.py re-run so image_analysis.csv covers the acquired web / AI images
- ```
- **Default — auto-proceed to Step 6.** Only when the user's Step 4 response explicitly opted into split mode (in chat or via Confirm UI `result.json` with `generation_mode: "split"`), output the Phase A hand-off below and stop this conversation:
- When `generation_mode: "gated"` (逐页精修, from `result.json` or stated in chat): auto-proceed to Step 6 — but the Executor MUST follow the **Per-slide Gate** from `workflows/gated-production.md` during Visual Construction (one slide → Live Preview → apply any feedback/annotations → explicit approval → next slide). Do NOT generate all slides in one pass, and do NOT treat Step 4 confirmation as permission to skip per-slide approval.
- ```markdown
- ## ✅ Phase A Complete
- - [x] Spec: `design_spec.md`, `spec_lock.md`
- - [x] Resources: `sources/`, `images/`, `templates/`
- - [ ] **Next**: if this is a long PPTX, create a new chat/session and input `继续生成 projects/<project_name>` to enter Phase B via the [`resume-execute`](workflows/stages/resume-execute.md) workflow, keeping the final production context clean. If the deck is not large, continue into final production in this chat.
- ```
- > On acquisition failure, do NOT halt — follow the Failure Handling rule in [image-base.md](references/image-base.md) §5: retry once, then mark the row `Needs-Manual`, report to user, and continue to the checkpoint above.
- ---
- ### Step 6: Executor Phase
- 🚧 **GATE**: Step 4 (and Step 5 if triggered) complete; all prerequisite deliverables are ready.
- 🚧 **LIVE PREVIEW STARTUP GATE**: no slide/SVG/page may be authored until the browser editor has been launched with `--live --daemon`, returned exit code 0, and printed its reachable actual URL. A launcher failure, missing URL, or unavailable preview is a hard stop for slide production; fix/restart the preview first. An already-running preview for the *same project* may be reused only after reading its URL from `live_preview/lock.json` and confirming the process is live.
- Read the execution references for this deck's locked `mode` + `visual_style` (from `spec_lock.md`):
- ```
- Read references/executor-base.md # REQUIRED: common guidelines
- Read references/shared-standards.md # REQUIRED: SVG/PPT technical constraints
- Read references/modes/<locked-mode>.md # narrative skeleton (spec_lock.md `mode`)
- Read references/visual-styles/<locked-style>.md # aesthetic (spec_lock.md `visual_style`)
- ```
- > Read executor-base + shared-standards + the one locked mode file + the one locked visual-style file. For `mode: custom` or `visual_style: custom`, skip that preset file and follow `mode_behavior` / `visual_style_behavior` from `spec_lock.md` instead. Never glob `modes/` or `visual-styles/`.
- For local traditional-industry templates, also load the matching specialized
- Executor guidance when the selected template or approved route calls for it:
- `references/executor-general.md`, `references/executor-consultant.md`, or
- `references/executor-consultant-top.md`. These extend, but never replace,
- `executor-base.md` and `shared-standards.md`.
- If `spec_lock.md` or the page plan activates an additive native/structured
- capability, read only its matching row from
- [`references/ppt-master-capability-overlay.md`](references/ppt-master-capability-overlay.md)
- and the linked core references before authoring that object/page. This adds an
- authoring contract; it does not change the Plus generation cadence or preview
- gate.
- **Design Parameter Confirmation (Mandatory)**: before the first SVG, output key design parameters from the spec (canvas dimensions, color scheme, font plan, body font size). See executor-base.md §2.
- **Live Preview Auto-Startup (Mandatory)**: this is the first production action after the Confirm → Live Preview → Slide Construction Gate. Before the first SVG, automatically start the browser editor in live mode and keep it running continuously through Executor + Step 7 export:
- ```bash
- python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live --daemon
- ```
- - Start it immediately when Executor begins; `svg_output/` may be empty. The daemon performs its own reachability check; proceed only after its exit code is 0 and it reports the actual URL. Editor opens at `http://localhost:5050`; if another project already holds it, the launcher **auto-advances to the next free port** — read the actual URL from the launch log and report that.
- - Run it as a long-running side process/session; do not wait for it to exit before generating SVG pages. Do not wait for user confirmation after startup.
- - **Service must keep running** until one of: (a) the user clicks **Exit preview** in the browser, or (b) the user explicitly asks in chat to stop it. Generation continues even if the user closes the editor.
- - **Apply annotations automatically after the browser saves them.** Users may annotate at any time and may submit multiple rounds. During Executor, keep a continuous `--wait-annotation` loop attached to the running preview service; when the user clicks **Apply changes** with annotations, pause at the current safe checkpoint and run [`workflows/live-preview.md`](workflows/live-preview.md) Step 2 immediately, including before Step 7. After each repair, delete the ready flag and immediately arm a fresh `--wait-annotation` listener before resuming, so a second or third batch of browser annotations is captured automatically. The user does not need to paste the browser prompt back into chat; the prompt is only a manual fallback if the wait loop is not running. In `Gated` mode, finish the annotation repair, re-check the SVG, preview the affected slide again, and then wait for explicit approval before moving on. In `Continuous` mode, resume generation after the repair passes SVG checks.
- - **Desktop agent adapter (Codex / non-CLI tools)**: browser events do not wake the AI by themselves. After starting `--live --daemon`, immediately start a separate long-running wait tool session:
- ```bash
- python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --wait-annotation --timeout 0
- ```
- Keep that session open while generating. Poll or resume it between page checkpoints and after each slide write; when it exits 0, run the Live Preview Step 2 repair flow, delete `<project_path>/live_preview/annotations_ready.flag`, then start a fresh `--wait-annotation --timeout 0` session before continuing. Repeat this re-arm cycle after every repair until the user stops preview or the workflow ends. In Codex Desktop this means an `exec_command` / terminal session remains blocked in the background specifically for annotation saves; do not wait for the user to paste the fallback prompt.
- - The editor also supports **staged direct edits** (text content + SVG element attributes previewed immediately, then written to `svg_output/` only when the user clicks **Apply changes**; `Ctrl+Z` / Undo drops staged edits) alongside annotation; re-export stays chat-driven. Full scope and editor details: see [`workflows/live-preview.md`](workflows/live-preview.md) Notes.
- **Pre-generation Batch Read (Mandatory)**: before the first SVG, batch-read every distinct layout SVG referenced in `spec_lock.page_layouts` and every distinct chart SVG referenced in `spec_lock.page_charts` (plus any §VII backup charts). One read per file, up front — do not re-read these during page generation. See executor-base.md §1.0.
- > Image facts: trust the `analysis/image_analysis.csv` regenerated at the end of Step 5. If `images/` changed since (the user swapped or added files), re-run `python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images` before laying images out — facts are re-derived on use, never a stale store (Step 4 image-facts note).
- **Per-page spec_lock re-read (Mandatory)**: before **each** SVG page, `read_file <project_path>/spec_lock.md` and use only its colors / fonts / icons / images, plus the per-page `page_rhythm` / `page_layouts` / `page_charts` lookups (resolves to template SVGs already loaded in the batch read above). Resists context-compression drift on long decks. See executor-base.md §2.1.
- **Per-page root SVG audit (Mandatory)**: immediately after writing each SVG, inspect its opening `<svg>` tag before previewing or continuing. It must have `xmlns="http://www.w3.org/2000/svg"`, `width="<canvas-width>"`, `height="<canvas-height>"`, and `viewBox="0 0 <canvas-width> <canvas-height>"`, where both dimensions are copied exactly from `spec_lock.md`. Do not defer a missing root `width` / `height` to the deck-wide quality gate; add the attributes and re-check that page immediately.
- > ⚠️ **Main-agent only**: SVG generation MUST stay in the current main agent — page design depends on full upstream context. Do NOT delegate to sub-agents.
- > ⚠️ **Generation rhythm**: generate pages sequentially, one at a time, in the same continuous context. Do NOT batch (e.g., 5 per group).
- **Visual Construction Phase**: generate SVG pages sequentially, one at a time → `<project_path>/svg_output/`
- > **Mode branch** — check `spec_lock.md` → `generation_mode` (fall back to `confirm_ui/result.json` if absent):
- > - **`continuous`** (default): one uninterrupted pass — generate all slides without stopping.
- > - **`gated`** (逐页精修): apply the **Per-slide Gate** from [`workflows/gated-production.md`](workflows/gated-production.md) — after generating each slide, show it in Live Preview, apply any saved browser annotations or chat feedback, re-preview the repaired slide, and wait for explicit user approval before proceeding to the next slide. Do NOT generate multiple slides in one turn.
- > - **`split`**: already halted at Step 5; treat as `continuous` if reached here.
- **Quality Check Gate (Mandatory)** — after all SVGs and any requested pre-export annotation repairs, BEFORE final speaker-note validation:
- ```bash
- python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path>
- ```
- - Any `error` (banned SVG features, viewBox mismatch, spec_lock drift, etc.) MUST be fixed before proceeding — return to Visual Construction, regenerate that page, re-run check.
- - `warning` entries (low-res image, non-PPT-safe font tail, etc.): fix when straightforward, otherwise acknowledge and release.
- - Run against `svg_output/` (not after `finalize_svg.py` — finalize rewrites SVG and masks violations).
- **Logic Construction Phase**: generate speaker notes → `<project_path>/notes/total.md`.
- Follow `references/speaker-notes.md`, then validate the complete talk track:
- ```bash
- python3 ${SKILL_DIR}/scripts/check_speaker_notes.py <project_path>
- ```
- Fix every error before export. Whenever slide content changes materially,
- update its notes and rerun the checker.
- **✅ Checkpoint — Confirm all SVGs and notes are fully generated and quality-checked. Proceed directly to Step 7 post-processing**:
- ```markdown
- ## ✅ Executor Phase Complete
- - [x] Live preview started and kept available at the reported URL
- - [x] All SVGs generated to svg_output/
- - [x] svg_quality_checker.py passed (0 errors)
- - [x] Speaker notes generated at notes/total.md
- - [x] check_speaker_notes.py passed (0 errors)
- ```
- > **Chart pages?** If this deck contains data charts (bar / line / pie / radar / etc.), run the standalone [`verify-charts`](workflows/stages/verify-charts.md) workflow before Step 7 to calibrate coordinates. AI models routinely introduce 10–50 px errors when mapping data to pixel positions; verify-charts eliminates that class of error. Skip if no chart pages.
- > **Visual self-check (opt-in)?** If the user explicitly asked for a per-page visual re-pass on the SVGs ("跑一下视觉自检 / 视觉回看", "visual review", "check pages visually", etc.), run the standalone [`visual-review`](workflows/stages/visual-review.md) workflow before Step 7. Do NOT run it by default and do NOT recommend it based on inferred model capability or deck size — trigger is user request only. In `Gated` / 逐页确定精修 mode, the per-slide style approval surface is Live Preview itself; do not render PNGs/screenshots for a model-based visual re-check as part of each slide confirmation.
- ---
- ### Step 7: Post-processing & Export
- 🚧 **GATE**: Step 6 complete; all SVGs generated to `svg_output/`; speaker notes
- `notes/total.md` generated; `check_speaker_notes.py` passed with zero errors.
- 🚧 **Image readiness GATE** (when Step 5 left ai rows in `Needs-Manual`): every expected file must exist at `project/images/<filename>` before running 7.1.
- > If files are missing: PAUSE, list the missing filenames, point the user to `images/image_prompts.md` (each `### Image N:` block is paste-ready for ChatGPT / Gemini / Midjourney; auto-generated from `image_prompts.json`) and the required placement `project/images/<filename>`. Resume Step 7.1 only after all expected files are in place. `finalize_svg.py` and `svg_to_pptx.py` do not detect missing files at this layer — proceeding with gaps produces a deck with broken image references.
- > ⚠️ Run the three sub-steps **one at a time** — each must complete successfully before the next.
- > ❌ **NEVER** combine them into a single code block or shell invocation.
- Canonical three-command pipeline (mirrors `references/shared-standards.md` §5):
- **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>
- # Output (default-flow mode):
- # exports/<project_name>_<timestamp>.pptx ← native pptx (canonical output, reads svg_output/)
- # backup/<timestamp>/svg_output/ ← Executor SVG source backup (always written)
- #
- # Add --svg-snapshot to additionally emit the SVG-image preview pptx alongside the native pptx:
- # exports/<project_name>_<timestamp>_svg.pptx ← SVG preview pptx (reads svg_final/)
- ```
- The public exporter always uses the unified engine. A project without a
- structured/native contract remains a flat export; semantic markers and optional
- arguments enable only the corresponding native feature. `--master-core` is not
- a public argument.
- > **Faithful beautify + preserve_master**: for faithful-beautify projects where `spec_lock.md` declares `preserve_master: true`, the script automatically reads `base_pptx` from `spec_lock.md` and applies the source master/layout mapping — **no `--base-pptx` flag needed**. After the command exits, verify the console output contains:
- > ```
- > [spec_lock] preserve_master=true → auto base-pptx: .../sources/<source.pptx>
- > Master/layout preservation: enabled (source slide N layout -> output slide N)
- > ```
- > If either line is missing, the master was **not** applied (the export used a blank base). Re-check `spec_lock.md` for `preserve_master: true` and a valid `base_pptx:` path, then re-run. Pass `--base-pptx <path>` explicitly only as a last resort when spec_lock.md auto-detection fails.
- > The native pptx consumes `svg_output/` directly so the converter can preserve
- > high-fidelity primitives (icon `<use>` placeholders, image `preserveAspectRatio`
- > → `srcRect`, rounded rect `rx/ry` → `prstGeom roundRect`). The `svg_output/`
- > snapshot in `backup/<timestamp>/` is always written so the project can be
- > re-exported from frozen SVG sources without re-running the LLM. The SVG-rendered
- > preview pptx is opt-in via `--svg-snapshot` — live preview already provides the
- > SVG visual reference, so it's only needed when you want a self-contained file
- > to share. Pass `-s output` or `-s final` to force a single source if you need it.
- > **Paragraph editability vs line fidelity** — by default, mergeable dy-stacked
- > paragraph blocks collapse into one editable PowerPoint text frame with multiple
- > `<a:p>`, improving body-text editing and resize/reflow behavior. Add `--no-merge`
- > only when the user explicitly asks for strict line-layout fidelity or when a
- > layout-tight page must keep every dy-stacked line as its own text frame. The
- > merge detector is conservative; mixed-layout text falls back to per-line frames.
- **Optional animation flags** (page transitions are off by default; per-element entrance is off by default — turn either on only when the user asks for it or confirms it):
- - `-t <effect>` — page transition. Default `none`. Options: `fade` / `push` / `wipe` / `split` / `strips` / `cover` / `random` / `none`. Use the confirmed `transition_effect` from `result.json` / `spec_lock.md`; pass `-t none` when absent or confirmed as `none`.
- - `-a <effect>` — per-element entrance animation. **Default `none`** — pages appear as a whole, no auto-firing element builds (the unsolicited cascade reads as the "AI deck" tell). Opt in with `auto` (map effect from group id: chart→wipe, card-/step-/pillar-→fly, title/takeaway→fade; image-like ids `hero` / `figure-` / `image` / `img-` / `kpi` cycle a richer pool — zoom / dissolve / circle / box / diamond / wheel — so multiple images vary across the deck), a specific effect like `fade`, or `mixed` for the legacy 16-effect cycle. Requires top-level `<g id="...">` groups (already required by Executor).
- - `--animation-trigger {on-click,with-previous,after-previous}` — Start mode (matches PowerPoint's animation-pane Start dropdown). Default `after-previous` (click-free cascade; pace via `--animation-stagger`). Use `on-click` for presenter-paced reveals, or `with-previous` for all-at-once.
- - `--animation-config <path>` — optional object-level sidecar. Default: `<project_path>/animations.json` when present.
- - `--auto-advance <seconds>` — kiosk-style auto-play.
- **Optional custom animations** (only when the user asks to tune animation order/effects/timing for specific objects):
- Run the standalone [`customize-animations`](workflows/stages/customize-animations.md) workflow. Default export applies no page transition and no per-element entrance animation; create `animations.json` (or pass `-a auto`) only when the user asks for element animation or object-level customization.
- **Optional recorded narration** (only when the user asks for narrated/video export):
- Run the standalone [`generate-audio`](workflows/stages/generate-audio.md) workflow. The AI picks a narration backend (`edge` by default, or a configured cloud provider such as ElevenLabs / MiniMax / Qwen / CosyVoice for high-quality or cloned voices), asks the user once (backend + voice + rate/settings + embed-or-not, all with recommended values), then executes `notes_to_audio.py` and (if chosen) re-exports the PPTX with `--recorded-narration audio`.
- Do NOT call `notes_to_audio.py` directly without going through the workflow — `--voice` / `--voice-id` is required and the workflow produces the locale/provider-aware recommendation that makes the choice meaningful.
- Full effect list, anchor logic, and limits: [`references/animations.md`](references/animations.md).
- > ❌ **NEVER** substitute `cp` for `finalize_svg.py` — finalize performs multiple critical processing steps
- > ❌ **NEVER** force `-s output` for the legacy/preview pptx (PowerPoint's internal SVG parser drops icons and rounded corners). The default auto-split already gives native the high-fidelity source it needs without touching legacy.
- > ❌ **NEVER** use `--only` (it suppresses one of the two output files)
- > **Annotation repair window**: the preview service from Step 6 remains available during generation and usually after export. When the user clicks **Apply changes** with annotations, the running `--wait-annotation` loop should return and the AI MUST run [`live-preview`](workflows/live-preview.md) Step 2 at the current checkpoint without requiring a pasted chat prompt. If the user does paste the browser fallback prompt or says "apply my annotations" / "应用注解", treat it as the same trigger. Pre-export repairs are checked and previewed without forcing a partial PPTX export; post-export repairs are checked, finalized, and re-exported.
- > **Direct edits in the browser**: the user may also stage text / SVG attribute edits in the preview. These land in `svg_output/` only after the user clicks **Apply changes**. Before the first export, run the SVG quality checker and continue the current page/deck workflow; after an export exists, a request to "re-export" / "重新导出" runs Step 7.2–7.3. No annotation-application step is needed unless AI-needed annotation markers were also saved.
- > **Preview not running?** Any time the user mentions "live preview", "preview", "看效果", or wants to select/click a slide element and the service is not running, run [`live-preview`](workflows/live-preview.md) Step 1 to start it. If the service is already running, just point them at the URL — do not restart.
- ---
- ## Role Switching Protocol
- Before switching roles, **MUST first read** the corresponding reference file. 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-text layout patterns (Primary structures + Modifier layers — combine freely) | `references/image-layout-patterns.md` |
- | Image layout sizing (math for side-by-side container dimensions) | `references/image-layout-spec.md` |
- | SVG image embedding | `references/svg-image-embedding.md` |
- | Icon library | `templates/icons/README.md` |
- ---
- ## Notes
- - Local preview: `python3 -m http.server -d <project_path>/svg_final 8000`
- - **Troubleshooting**: on generation issues (layout overflow, export errors, blank images, etc.), check `docs/faq.md` for known solutions
README.md · README · 423 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # PPT Master Plus
- 
- `ppt-master-plus` 是一个面向高质量、可编辑 PPTX 生产的通用 AI agent skill。它以 [`ppt-master`](https://github.com/hugohe3/ppt-master) 的 SVG→PPTX 方法论和制作链路为底座,在本仓库中补强 PPTX intake、保真美化、原生编辑、Confirm UI、可复用设计资产和软依赖绘图路由。
- 它的目标不是”快速吐几页幻灯片”,而是把资料理解、叙事组织、视觉规范、逐页制作、讲稿质检和最终导出串成一条可控的生产线。
- 用户只需选择三类目标:重新生成/设计页面走 **Generate PPTX**;保留现有
- 演示文稿并局部修改走 **Edit Native PPTX**;显式导入用户给定的 `.pptx`
- 文件作为品牌参考、再用另一组内容生成新文件走 **Import Brand PPTX**。详细判定见
- [`workflows/routing.md`](workflows/routing.md)。
- ## 安装
- 复制以下 prompt,发给你的 AI Agent 即可完成安装:
- ```
- 请安装并使用 ppt-master-plus skill:https://github.com/gnuhpc/ppt-master-plus
- 可选伴侣 skill(按需安装,缺失时自动降级回内置 SVG):
- - fireworks-tech-graph(正式技术架构图):https://github.com/yizhiyanhua-ai/fireworks-tech-graph
- - excalidraw(手绘/白板风格):https://github.com/Agents365-ai/excalidraw-skill
- - Mermaid(流程图/时序图/ER 图):https://github.com/Agents365-ai/creating-mermaid-diagrams
- - PlantUML(UML/组件图):https://github.com/Agents365-ai/plantuml-skill
- - draw.io(拓扑/云厂商图标):https://github.com/Agents365-ai/drawio-skill
- - tldraw(tldraw 白板):https://github.com/Agents365-ai/tldraw-skill
- ```
- ## 与 ppt-master 的功能对比
- `ppt-master-plus` 是在 `ppt-master` 的基础上进行了全方位能力扩充的进阶版本。以下是核心功能的对比:
- | 功能维度 | `ppt-master` (标准版) | `ppt-master-plus` (进阶版) |
- | :--- | :--- | :--- |
- | **定位与重点** | 严格串行的多源资料→SVG→PPTX 生产链,强调内容理解、模板/规范锁定、逐页手写 SVG、质量检查和原生可编辑 PPTX 导出。 | 在同一方法论上扩展为更完整的 PPTX 生产系统,重点补强已有 PPTX 处理、逐页确认、批注回修、讲稿门禁、原生增强和多源技术图路由。 |
- | **生成模式控制** | 默认在八项设计确认后连续生成整份 PPT;长文档可在 Step 5 后用 `resume-execute` 跨对话进入 Phase B。 | 把 `continuous` / `gated` / `split` 明确纳入 Confirm UI 与 `spec_lock.md`:可全自动一次性生成,也可逐页确定精修,长文档仍可跨对话生产。 |
- | **网页配置端与批注机制** | 有 Confirm UI 作为八项设计确认界面,也有 Live Preview;生成期继续按串行流程推进,注解主要在导出后按 `live-preview` 工作流统一处理。 | Confirm UI 升级为两阶段确认,覆盖 `content_divergence`、`generation_mode`、`transition_effect`、`refine_spec` 等字段;生成期通过 `--wait-annotation` 监听 **Apply changes**,可在安全检查点自动读取批注并回修。 |
- | **Live Preview 页内直接编辑** | 支持浏览器实时预览、staged direct edits(文本与 SVG 属性暂存后应用)和批注回收;导出后可按工作流处理注解并重新导出。 | 保留这些能力,并把它们接入 Gated/Continuous 生产闭环:逐页门禁下每页可确认、批注、修复、再确认;Continuous 下也能在生成安全点捕获批注并自动重挂监听。新增快速标注浮窗(预设问题标签 + 自由文本)、整页标注、Shift+单击多选、右键重叠元素选择器、键盘导航和快捷键提示栏。 |
- | **演讲稿在线编辑** | 生成 speaker notes,并通过 `total_md_split.py` 拆分进 PPTX;主要由 Agent/文件流程维护讲稿。 | Live Preview 左侧面板内置 **目录 / 演讲稿** 切换标签:可直接编辑当前页讲稿,点击 **保存** 后写入 `notes/<slide>.md`,无需 Apply changes。 |
- | **PPTX intake / source profile** | PPTX 可经 `ppt_to_md.py` 提取为 Markdown 后作为普通资料进入主流程。 | `import-sources` 会额外运行 `pptx_intake.py`,生成 `analysis/source_profile.json`、`<stem>.identity.json`、`<stem>.slide_library.json`,把画布、主题、几何、表格和图表事实提供给 Strategist 作上下文。 |
- | **美化入口路由** | 既有 PPTX 作为资料输入主生产流程,Strategist 可自由重构叙事、页数、页序和视觉系统;不单独区分“保留原稿”的美化契约。 | 路由边界更清晰:重新设计 → Generate PPTX;保留原生设计并局部修改 → [`Edit Native PPTX`](workflows/edit-native-pptx.md);显式 1:1 重排 → [`faithful-beautify`](workflows/profiles/faithful-beautify.md)。 |
- | **保真美化(Faithful Beautify)** | 不提供独立 1:1 保真美化路线;若输入 PPTX,仍按资料重建,不把原页数、页序、逐页文字或母版当作锁定契约。 | 专属工作流 [`beautify-pptx.md`](workflows/profiles/faithful-beautify.md):<br>• **画布原尺寸**:`beautify_identity.py` 从 PPTX `p:sldSz` 读取精确像素尺寸,不强制归一化到 1280×720<br>• **内容冻结契约**:`pptx_intake.py` + `beautify_inventory.py` 生成逐页台账(文字/图表数据/表格/图片),文字逐字冻结,数据值锁定,严格 1:1 页数映射<br>• **源身份提取**:`analysis/<stem>.identity.json` 含主题调色板、实际观察字体/字号;Confirm UI 以源 PPT 风格预填,用户可确认或覆盖<br>• **`preserve_master`**:OOXML 级逐页保留,源第 N 页的 slideLayout/master 映射到输出第 N 页,主版式背景/Logo/页脚等 PPT 原生元素由母版承载<br>• **输出验证**:对导出 PPTX 重跑 `ppt_to_md.py`,逐页核对文字保真度和页数 |
- | **Template Pack** | 无独立 Pack 概念。 | **21 套**:把可复用 Style 与 Layout 组合成一键预设;Pack 自身不携带颜色、字体、SVG 或示例内容。 |
- | **图表 / 信息图 SVG** | 当前索引 33 个。 | **139 个**,冲突项以 Plus 资产为准。 |
- | **Layout 骨架** | 当前索引 7 组。 | **54 组**,包含迁移后的 21 套中文行业结构原型及关联 Page Kit。 |
- | **Brand / Style preset** | 20 套 Brand、12 套 Style。 | **38 套 Brand、12 套 Style**;包括 `apsara_yunqi_26_light`、`ffa_shenzhen`、飞天发布、中国电信、中汽研、中国电建、招商银行、重庆大学与 `flink_ai_style`。 |
- | **Table / Sound** | 6 个 Table、186 个 Sound。 | 同步并入 **6 个 Table、186 个 Sound**,仅在显式原生对象或音视频工作流中启用。 |
- | **图标库** | 12,027 个 SVG,含 chunk-filled / phosphor-duotone / simple-icons / tabler-filled / tabler-outline 五套图标库。 | 同款 5 套图标库、同等规模(12,027 个);图标检索和复制流程相同。 |
- | **外部绘图路由** | 主要依靠内置 SVG、图表模板和图标库完成图解表达。 | **软依赖绘图路由器**:可按场景分流到 `fireworks-tech-graph`、`excalidraw`(手绘风格可编辑源文件)、`Mermaid`、`PlantUML`、`draw.io` 或 `tldraw`;环境缺失时自动降级回内置 SVG,绝不阻塞主流程。 |
- | **讲稿与质检** | 支持生成 speaker notes,并通过 `total_md_split.py` 拆分后随 PPTX 导出;SVG 质量检查是导出前的重要门禁。 | 在此基础上新增讲稿专项规范与校验脚本([`check_speaker_notes.py`](scripts/check_speaker_notes.py) 与 [`speaker-notes.md`](references/speaker-notes.md));讲稿检查是导出前的**硬性门禁**,零错误才允许进入后处理。 |
- | **原生 PPTX 编辑** | 给定 PPTX 通常先提取为 Markdown 再走 SVG 重建流程。 | 统一路线 [`Edit Native PPTX`](workflows/edit-native-pptx.md):通过 v5.1 round-trip 保留原生 Master/Layout、关系、图表、表格、媒体和未改对象,按模块执行页面计划、内容替换、备注、旁白、转场与动画。 |
- | **默认动画策略** | 导出时默认启用元素入场动画(`-a auto`),AI 自动按组别匹配效果。 | 导出时**默认关闭动画**(`-a none`),整页一次性出现,避免"AI 痕迹"感知;仅在用户明确要求时才开启入场动画或页面转场。 |
- | **用户配置文件夹** | 使用 `~/.ppt-master` 存储配置与密钥。 | 使用新路径 `~/.ppt-master-plus`,并**支持平滑回退**以读取旧的 `~/.ppt-master` 配置文件。 |
- | **自动化契约测试** | 无专门的自动化合约测试套件。 | **新增契约测试**([`test_skill_contract.py`](scripts/tests/test_skill_contract.py)),自动验证 Gated/Continuous 流程、Live Preview 交互细节及 OOXML 母版媒体完整性。 |
- ## 推荐 AI Agent 与模型
- 这个 skill 适合在支持本地文件、脚本执行和长上下文工作的 AI agent 环境中使用。推荐入口:
- | AI Agent | 推荐模型 / 档位 | 适用场景 |
- |---|---|---|
- | GLM | **`GLM 5.3`(首推)** / `GLM 5.2` | 完整端到端 PPTX 生产、中文资料理解、长上下文规划和逐页制作 |
- | Antigravity CLI | `gemini-flash 3.5` / `high` | 长资料 intake、连续制稿、需要较强吞吐和上下文保持的 PPTX 生产 |
- | Codex | `gpt5.5` / `medium` | 叙事重构、设计确认、逐页 SVG 制作和质量检查的均衡配置 |
- 首选 `GLM 5.3`;环境或版本约束下可使用 `GLM 5.2`。也可以按任务阶段切换:Antigravity CLI 处理资料量大、连续生产压力高的项目;Codex 处理需要精修判断、文件修订和质量检查的项目。
- ## 基本概念与内置内容
- ### 先区分路线、模板和资源
- **Route(路线)** 是一次任务的交付方式;**Template(模板)** 是一类可复用设计参考的总称;**Resource(资源)** 是可在页面中选用的图表、表格、图标或音效。它们不是同一层概念。
- | 概念 | 作用 | 当前内置 / 可用内容 |
- |---|---|---|
- | **Generate PPTX** | 从内容新建或重新设计页面 | 固定 Step 1–7、两层 Confirm UI、`gated` / `continuous` / `split` 三种生产模式、逐页 Live Preview。 |
- | **Edit Native PPTX** | 保留原 PPTX 的母版、版式和对象结构,做局部修改 | `page_plan`、`content_edit`、`notes`、`narration`、`transitions`、`animations`、`visible_content_locked` 七个模块。 |
- | **Import Brand PPTX** | 将用户明确提供的 PPTX 只读导入为项目级 Brand,并以新内容生成新的 PPTX;明确要求长期复用时可注册为共享 Brand | `imported_brand` Profile;可选 Brand Page Kit 会以 `edit_native` 复用经批准的封面、目录、过渡、正文/封底原型,并只替换声明的内容槽位。 |
- ### Template 是总称,不是第五种资产
- 内置 Template 资产有四种 `kind`。Brand、Style、Layout 是基础能力,Pack 是它们的组合预设。
- ```mermaid
- flowchart LR
- B[Brand\n品牌身份] --> R[Resolved Template\n项目模板状态]
- S[Style\n表达方法与视觉默认] --> R
- L[Layout\n页面结构与 SVG 原型] --> R
- P[Pack\n组合引用] -.展开为引用.-> B
- P -.展开为引用.-> S
- P -.展开为引用.-> L
- R --> O[Generate PPTX\n新的演示文稿]
- ```
- Pack 是正式的第四种 Kind,但不成为第四个设计所有者:它只保存组件 ID、摘要和关键词,选择后先展开,再由 Brand、Style、Layout 分别承担身份、方法和结构。
- | `kind` | 解决的问题 | 不负责什么 | 当前内置 |
- |---|---|---|---:|
- | **Brand** | 统一品牌身份:颜色、字体、Logo、Icon、背景资产、语气 | 不锁定页面结构或 SVG 页面原型 | **38** 套 |
- | **Style** | 统一表达方法:叙事方式、证据纪律、信息密度、视觉默认值 | 不锁定品牌身份、页数、页序、几何或 SVG 原型 | **12** 套 |
- | **Layout** | 统一结构:画布、网格、页面类型、SVG 页面骨架;也可承载显式导入的 Icon / Chart 视觉语法或 Brand Page Kit | 不携带机构 Logo、官方配色或表达方法 | **54** 套 |
- | **Pack** | 一键组合已注册的 Brand、Style、Layout | 不拥有设计字段,不携带 SVG、图片或嵌套 Pack | **21** 套 |
- `Import Brand PPTX` 中的“PPTX”默认是项目级参考文件;用户明确要求长期复用时,可通过 `--register-brand <id>` 生成共享 `kind: brand` 包。Brand 索引可选地关联一个独立的 Brand Page Kit Layout;选择该 Brand 时,Confirm UI 显示“使用页面套件 / 仅使用品牌身份”。前者仅克隆被批准的原生页面并替换声明槽位,后者只使用颜色、字体、Logo 和图标身份。用户也可显式使用 `--register-icon-layout <id>` 或 `--register-chart-layout <id>` 创建配套 Layout:前者仅保存 Icon 处理语法,后者仅保存图表类型、数据系列调色板、图例、坐标轴、网格线和标签规则。图表/表格始终使用当前内容数据;除 Page Kit 已批准页面外,不复用示例内容、对象几何或原始 PPTX 页面。
- ### 其他工作流概念
- | 概念 | 含义 | 当前内置 |
- |---|---|---|
- | **Engine(引擎)** | 实际制作路径 | `svg_generate`(新页面生成)与 `edit_native`(原生 round-trip 编辑)。 |
- | **Profile(配置)** | 某条路线的专用策略,不是独立用户入口 | `faithful_beautify`、`image_to_pptx`、`imported_brand`。 |
- | **Stage(阶段)** | 按需插入主流程的能力 | Topic Research、Refine Spec、Resume Execute、Live Preview、Visual Review、Chart Verification、Customize Animations、Generate Audio。 |
- | **Module(模块)** | Edit Native PPTX 中可组合启用的编辑能力 | 页面管理、内容替换、备注、旁白、转场、动画、可见内容锁定。 |
- | **`design_spec.md` / `spec_lock.md`** | 前者说明设计与叙事,后者是每页执行前必须重读的机器可执行约束 | 每个 Generate 项目都会生成;它们不是模板资产本身。 |
- ### 内置资源库
- | 资源 | 数量 | 用法边界 |
- |---|---:|---|
- | 图表 / 信息图 / 图解 / 框架 SVG | **139** | 按语义从内置目录选型;默认不继承用户 PPTX 的图表样式。用户显式选中导入的 chart-grammar Layout 时,可继承数据系列调色板、图例、坐标轴、网格线和标签规则,但不会继承示例数据。 |
- | 原生表格结构 | **6** | 仅在需要稳定行列结构或原生表格语义时启用。 |
- | 图标 | **12,027** 个,5 个库 | `chunk-filled`、`phosphor-duotone`、`simple-icons`、`tabler-filled`、`tabler-outline`。 |
- | 音效 | **186** 个 | 仅在用户明确要求动画或视频工作流时启用。 |
- | 外部绘图路由 | 6 类可选伴侣 skill | Fireworks、Excalidraw、Mermaid、PlantUML、draw.io、tldraw;缺失时回退内置 SVG。 |
- 在 Generate 的 Step 3 中,内部 Template 资产只会在用户明确提供仓库内目录路径时使用;仅说名称或风格不会触发自动匹配。完整的融合规则见 [`references/templates-architecture.md`](references/templates-architecture.md)。
- ## 主要功能
- - 从 PDF、DOCX、XLSX、PPTX、URL、Markdown 或粘贴文本创建新的 PPTX。
- - 支持两种生产模式:
- - 逐页确定精修:每生成一页都停下来,用户在 Live Preview 中确认或批注修复后,才继续下一页。
- - 全自动一次性生成:完成必要设计确认后自动进入制作,不逐页等待。
- - 支持已有 PPTX 的多种路线:
- - 普通美化:将 PPTX 当作资料重新组织成新故事。
- - 保真美化:显式保留页序、页数、文字和可选母版。
- - 对成品 PPTX 追加讲稿、音频、自动播放和转场等原生增强。
- - 支持浏览器实时预览、页面注解回收、SVG 质量检查、讲稿质量检查和 PPTX 导出验证。
- - 统一使用 PPT Master 5.1 引擎,按需启用原生图表/表格、公式、超链接、预设与布尔形状、高级 SVG 效果、结构化 Master/Layout、分层 round-trip 及更完整的交付检查;旧项目未声明结构化/原生语义时保持 flat 输出。
- - 支持可选绘图路由:
- - 普通展示图、图表、信息图默认走内置 SVG,保证和 PPTX 导出链路最稳。
- - [`fireworks-tech-graph`](https://github.com/yizhiyanhua-ai/fireworks-tech-graph):正式、规整的架构图和技术流程图。
- - [`excalidraw`](https://github.com/Agents365-ai/excalidraw-skill):手绘、白板、头脑风暴风格,并保留可编辑源文件。
- - [`Mermaid`](https://github.com/Agents365-ai/creating-mermaid-diagrams) / [`PlantUML`](https://github.com/Agents365-ai/plantuml-skill) / [`draw.io`](https://github.com/Agents365-ai/drawio-skill) / [`tldraw`](https://github.com/Agents365-ai/tldraw-skill) 作为更专门的外部图资产路线,仅在用户明确需要或内容非常匹配时使用。
- - 缺失依赖时回退到内置 SVG,不安装、不阻塞。
- ## 常见使用方式
- 关于用户使用时候的具体动作和交互指令,请首先参阅 **[最佳实践指南](references/best-practices.md)**。
- ### 1. 从文档创建新的 PPTX
- 适合把 PDF、DOCX、XLSX、PPTX、网页、Markdown 或一段文字重新组织成一份新的演示文稿。这个路线会把资料当作内容来源,由 Strategist 重新梳理叙事、页数、结构和视觉风格;原始文档的页序不需要保留,必要时可以合并、拆分、删减或重排内容。
- 典型输入动作:
- ```text
- 使用 ppt-master-plus,把 /path/to/report.pdf 做成一份 12 页左右的路演 PPT,面向投资人,风格专业克制,走逐页确定精修。
- ```
- 用户核心动作流程:
- 1. 告知 Agent 生产模式(`逐页确定精修` 或 `全自动一次性生成`)和源文件。
- 2. 配合完成画布、页数、受众、风格、配色、图标、字体、图片策略等全局设计决策。
- 3. 顺序制作并预览 SVG 页;如果选择逐页确定精修,每页确认通过后才继续下一页。
- ### 2. 普通美化已有 PPTX
- 适合已经有一份 PPTX,希望让它更专业、更有重点,但没有要求原页数、原页序和每页文字完全不变。这个路线走主生产流程:PPTX 被当作资料来源,Strategist 可以重新梳理叙事、调整页数、拆分/合并页面并重做视觉系统。
- 典型输入动作:
- ```text
- 使用 ppt-master-plus,美化 /path/to/deck.pptx,让它更适合客户汇报,整体更专业、更有重点。
- ```
- 用户核心动作流程:
- 1. 配合 Confirm UI 确认 `content_divergence`:希望多贴近源 PPT,还是允许更自由重构。
- 2. 配合完成画布、页数、受众、风格、配色、图标、字体、图片策略等全局设计决策。
- 3. 预览并核对重新生成的 SVG 效果,确认后导出原生可编辑 PPTX。
- ### 3. 保真美化已有 PPTX
- 适合必须保留原页数、原页序、每页文字和数据,只优化版式、层级、留白、对齐、图表呈现和整体专业度。这个路线走 `faithful-beautify`,可选择是否保留源 PPTX 母版/版式。
- 典型输入动作:
- ```text
- 使用 ppt-master-plus,美化 /path/to/deck.pptx,保留每页文字和页序不变,只重新排版,让它更专业。
- ```
- 用户核心动作流程:
- 1. 明确要求保留原有的页数、页序、每页文字和数据值。
- 2. 配合 Confirm UI 网页端确认是否保留原 PPT 各页面的母版与版式。
- 3. 预览并核对 1:1 重新版面排布后的 SVG 效果,确认后导出原生可编辑 PPTX。
- ### 4. 从用户 PPTX 导入 Brand 并生成新 PPTX
- 适合用户给出一份 PPTX,希望沿用其品牌身份,但用另一组内容重新生成页面。该 PPTX 不会被当作可复制页面模板:系统只读分析其颜色、字体、Logo、Icon、背景资产与视觉语气;页面结构重新规划,图表与表格默认从内置资源选型。用户明确要求时,图标或图表视觉语法可另存为配套 Layout。
- 典型输入动作:
- ```text
- 使用 ppt-master-plus,Import Brand PPTX:/path/to/brand-reference.pptx;
- 基于 /path/to/new-content.md 做一份面向客户的 10 页方案汇报。
- ```
- 用户核心动作流程:
- 1. 同时提供明确的 PPTX 文件和新内容材料。
- 2. 确认受众、核心信息、页数/页面计划与生产模式;品牌身份默认锁定。
- 3. 在 Live Preview 中按 `gated` 或 `continuous` 审阅新生成页面;输出不会改写源 PPTX。
- ## 浏览器确认、预览与反馈
- 在生成过程中,系统会自动提示并引导您打开本地浏览器进行配置和预览确认。具体的交互细节请参考 **[最佳实践指南](references/best-practices.md)**。
- ### 设计确认页面(Confirm UI)
- * **动作**:在 Strategist 阶段,系统提示后在浏览器中打开 `http://localhost:5050`。
- * **动作**:在 Tier 1 选择并确认画布、受众、交付目的等大方向后,点击下一步。
- * **动作**:在 Tier 2 选择并微调自动推荐的配色、字体、图片、图标策略和是否需要页面转场动画,点击确认。转场动画默认不需要。
- ### 逐页预览与微调页面(Live Preview)
- * **动作**:在幻灯片制作阶段,在网页端查看实时生成的 slide 效果。
- * **动作(直改)**:直接在预览页面上选中文字或形状,通过右侧属性面板微调文本或属性,点击 **Apply changes** 应用回项目。
- * **动作(批注)**:选中元素后按 **Tab** 打开快速标注浮窗,可勾选预设问题标签(文字遮挡、文字溢出、图例遮挡等)并填写补充说明;也可点击标注列表旁的 **+** 按钮对整页进行标注。完成后点击 **Apply changes**;AI 会自动读取保存到 `svg_output/` 的批注并开始修复。在 Codex Desktop 这类桌面端工具中,Agent 会保持一个后台 `--wait-annotation --timeout 0` 监听会话来捕获点击事件;每轮修复完成后会重新挂起监听,所以可以继续提交第二批、第三批修改意见。页面中的复制提示仅作为自动监听失效时的备用触发方式。
- **Live Preview 键鼠操作速查**:
- | 操作 | 说明 |
- |---|---|
- | 单击元素 | 选中 |
- | Shift+单击 | 多选 |
- | 右键 | 重叠元素选择器(Shift+单击可在列表中多选) |
- | Tab | 打开标注浮窗 |
- | ← → | 前一页 / 后一页 |
- | ↑ ↓ | 在左侧目录中上下浏览 |
- | Del | 删除选中元素的标注 |
- | Esc | 关闭浮窗 / 取消选择 |
- ### 回到 Agent 修改
- * **动作**:您也可以随时跳过网页,在聊天里直接描述修改要求(例如:“第 3 页标题改成‘增长飞轮’,重新导出。”),Agent 将自动修改并更新。
- ## 已有 PPTX 的处理边界
- 给定一个 `.pptx`,先判断它是待修改的演示文稿,还是新演示文稿的设计骨架。
- | 用户意图 | 支持情况 | 路线 |
- |---|---|---|
- | 普通美化 / 优化 / 更专业,没有显式保留约束 | 支持 | 主生产流程 |
- | 保留原页数、页序、每页文字和数据,只优化版式、层级、留白和视觉一致性 | 支持 | `faithful-beautify` |
- | 把 PPTX 当作资料来源,重新组织故事、拆分/合并页面、调整页数或重排结构 | 支持 | 主生产流程 |
- | 对成品 PPTX 追加讲稿、音频、自动播放、转场等,不改变可见内容和布局 | 支持 | `Edit Native PPTX` |
- | 用户显式给定一个 `.pptx` 文件作为品牌参考,再填入另一批新内容 | 支持 | `Import Brand PPTX`:先只读导入为 Brand,模板与内容分离,在锁定品牌身份下生成新的 PPTX |
- 模板路线不把示例文字当内容,也不只依赖 PowerPoint placeholder。系统会提取
- 规范页、普通文本框/形状/图片/组合中的品牌身份线索;无法安全识别的内容不会
- 进入输出。导入的 PPTX **一律归类为 Brand,不归类为 Pack 或 Layout**:仅复用画布、配色、
- 字体、Logo、Icon、背景资产与视觉语气,不复用页面原型、母版/版式、对象几何或
- 模板示例内容。图表、表格、信息图和流程/框架图默认从 Skill 内置图表/表格目录选择,
- 再适配到锁定的品牌令牌中;用户明确选中导入的 chart-grammar Layout 时,可采用其
- 数据系列调色板、图例、坐标轴、网格线和标签规则。模板中的示例数据同样不会进入最终内容。
- 该路线不按模板名称搜索,也不从 Skill 内部 Brand、Style、Layout 或 Pack
- 资产中代选模板;未提供明确 `.pptx` 文件时,必须先请用户提供文件。
- ### 从用户 PPTX 导入模板
- `Import Brand PPTX` 的来源必须是用户明确提供的 `.pptx` 文件,先导入
- 项目并只读保存,再进行品牌身份和资产分析:
- ```bash
- python3 scripts/project_manager.py init <project_name> --format ppt169
- python3 scripts/project_manager.py import-template <project_path> /path/to/user-template.pptx
- ```
- 导入会生成 `analysis/template_manifest.json`、`template_design_tokens.json`、
- `template_archetypes.json`、`template_assets.json` 和页面预览;原始文件不移动、不覆盖,
- 项目副本标记为只读。`template_archetypes.json` 默认仅用于诊断;用户显式注册 Brand Page Kit 时,只有高置信度且批准的封面、目录、过渡、正文或封底原型会进入独立 Layout,其余页面绝不成为页面原型库。
- 品牌名称可以由用户显式声明(例如 `FFA`),但不会从模板示例文字或文件名猜测;后续
- 生成时,导入 Brand 默认负责身份令牌和资产,页面版式自由规划;若 Confirm UI 选择“使用页面套件”,则原生 round-trip 执行器只复用该 Brand 关联 Page Kit 的已批准页面,并保留背景、Logo、装饰、裁切、层级和母版;图表/表格/信息图默认由
- Skill 内置可视化目录提供。需要长期保留图标或图表的视觉语法时,显式传入
- `--register-icon-layout <id>` 或 `--register-chart-layout <id>` 并注册为 Layout;图表 Layout
- 不会保存示例数据、页面位置或品牌 Logo。
- ## 与 ppt-master 的模板与资源对比
- 这里的“模板”是 Brand、Style、Layout、Pack 四类资产的总称;图表、表格、图标和音效属于资源库。以下是可复用资产的逐项对比:
- | 资产类型 | `ppt-master` | `ppt-master-plus` | 说明 |
- |---|---:|---:|---|
- | Pack | — | **21 套** | 一键展开为已注册 Style + Layout;可选 Brand,本批迁移 Pack 均不绑定 Brand |
- | 其中:传统行业组合 | — | **21 套** | `ppt-master-plus` 专有,适合中文商业场景、课件、述职、答辩、项目架构等 |
- | 图表 / 信息图 SVG | 33 个 | **139 个** | 合并索引与文件,ID 冲突保留 Plus |
- | Layout 骨架 | 7 组 | **54 组** | 包含 21 套从旧完整模板中拆出的结构资产及关联 Page Kit |
- | Brand | 20 套 | **38 套** | 包含 `apsara_yunqi_26_light`、`ffa_shenzhen`、`飞天发布`、机构/学校身份预设并保护 `flink_ai_style` |
- | Style | 12 套 | **12 套** | 仅在显式 Style 路径被提供时启用 |
- | Table / Sound | 6 / 186 | **6 / 186** | 原生表格与音视频工作流按需启用 |
- | 图标库(SVG 数量) | 12,027 个 | 12,027 个(同) | chunk-filled / phosphor-duotone / simple-icons / tabler-filled / tabler-outline 五套 |
- 这些内置资产不是单纯的静态素材库。Generate 只在用户明确选择内部模板路径时使用;用户显式给定的 `.pptx` 文件先由独立的 Import Brand PPTX 路线只读导入为项目级 Brand。用户明确要求沉淀时,`--register-brand <id>` 会将其身份令牌与母版/版式品牌资产注册为可选 Brand;只有明确请求 `--register-icon-layout <id>` 或 `--register-chart-layout <id>` 时,才会额外生成配套 Layout,且仅保存对应视觉语法,不保存页面或示例数据。
- ## 基本架构
- ```text
- Source Materials
- ↓
- Intake
- - PDF / DOCX / XLSX / PPTX / Web / Markdown 转 Markdown
- - PPTX intake 抽取画布、页结构、表格、图表和版式事实
- ↓
- Production Mode Gate
- - 逐页确定精修:每页停下确认,应用批注修复后再继续
- - 全自动一次性生成:确认设计后连续生产
- ↓
- Strategist
- - 资料理解
- - 叙事重构
- - 八项设计确认
- - design_spec.md + spec_lock.md
- ↓
- Optional Assets
- - AI / Web / User / Formula 图片资源
- - Fireworks / Excalidraw / 内置 SVG 图示路由
- ↓
- Executor
- - 顺序逐页手写 SVG
- - 实时预览
- - 质量检查
- ↓
- Post-processing
- - SVG 修整
- - 讲稿检查
- - PPTX 导出
- - 可选原生增强
- ```
- 核心入口是 [`SKILL.md`](SKILL.md)。分阶段生产流程在 [`workflows/gated-production.md`](workflows/gated-production.md),上游与本地合并记录在 [`references/upstream.md`](references/upstream.md)。关于模板设计架构请参考 [`references/templates-architecture.md`](references/templates-architecture.md),系统技术架构设计参考 [`references/technical-design.md`](references/technical-design.md)。
- ## 更新记录
- ### 最近更新 (2026-09)
- - **Brand Page Kit 原生母版套件与可视化导入界面 (Brand Import Web)**
- - **可视化角色原型确认**:新增 Brand Import Web 可视化工具([`scripts/brand_import_ui/`](scripts/brand_import_ui/) 与 [`scripts/import_brand.py`](scripts/import_brand.py)),导入用户提供的 PPTX 模板时,可通过 Web 界面核对并确认封面、目录、章节/过渡、正文与封底原型。
- - **原生 PPTX 槽位替换执行器**:支持将已批准的原型页面注册为配套 Page Kit Layout(如 `飞天发布_page_kit`),配合 `native_page_kit_fill.py` 以及 `execute-brand-page-kit` / `activate-brand-page-kit` 原生 round-trip 机制,直接克隆源 PPT 页面并仅替换声明的内容槽位,原汁原味保留源 PPTX 的背景设计、矢量修饰、Logo 与母版关系。
- - **模板资产架构解耦重构 (Deck → Pack / Layout / Style)**
- - **传统行业模板全面解耦**:将原有 21 套耦合了行业样式的模板拆分为品牌无关的 21 组 Layout 骨架(`templates/layouts/传统行业_*`)与 21 套组合 Pack(`templates/packs/`),并规范归属至 7 大核心表达 Style。
- - **四类资产严格分工**:Pack 作为正式的第 4 种模板 kind,提供一键展开为 Style + Layout 的预设体验,且自身不持有设计字段与私有资产。资产库全量扩容并校验为 **38 套 Brand、12 套 Style、54 组 Layout、21 套 Pack 及 139 个图表/信息图 SVG**。
- - **三大顶层公共路由与执行上下文收敛**
- - **顶层公共路由确定性收敛**:严格规范为 `Generate PPTX`、`Edit Native PPTX`、`Import Brand PPTX` 三大公开入口,内部维护工具收敛于 `workflows/internal/template-authoring/`(新增 `create-pack.md`)。
- - **导入路由语义统一**:统一使用 `import_brand_pptx` 规范,配合 Brand Page Kit 形成完整的“只读导入品牌 → 确认原型 → 原生填充/新生成”闭环。
- - **工程完备性与自动化测试**
- - 新增 Brand Page Kit 执行计划契约测试([`test_page_kit_execution_plan.py`](vendor/ppt-master/scripts/tests/test_page_kit_execution_plan.py)),全套 24 项能力合约测试([`test_skill_contract.py`](scripts/tests/test_skill_contract.py))全量绿灯,保障 OOXML 导出与多路由调度的高可用。
- ### 2026-08
- - **Live Preview 主题持久化与演示者模式讲稿实时编辑**
- - **主题选择与品牌动态挂载**:SVG Editor / Live Preview 主题库新增 8 款精选预设主题(`swiss_grid` 瑞士网格, `linear_dark` 暗夜极简, `notion_paper` 温润纸感, `stripe_indigo` 经典深蓝, `apple_minimal` 极简白, `cyberpunk_neon` 赛博朋克, `emerald_forest` 翡翠深绿, `anthropic_warm` 陶土暖色),并支持动态扫描与挂载品牌库 `brands_index.json` 主题。
- - **主题偏好记忆与全屏自适应**:基于 `localStorage` (`ppt_theme`) 实现主题配置自动恢复与持久化,换肤 CSS 变量作用域自适应覆盖主视图、演示屏顶部容器与全屏展示框。
- - **演示者模式讲稿实时编辑**:全屏演示/彩排模式下,讲稿面板升级为实时交互编辑器(`fullscreen-notes-editor`),演讲者可直接在全屏模式下微调修改演讲稿内容。
- - **TTS 语音朗读与视频演示导出 (`export_video.py`)**
- - 新增 `export_video.py` 自动化导出工具,结合幻灯片 SVG 渲染与演讲稿 (Speaker Notes) TTS 语音合成,一键生成带高品质配音朗读的 MP4 视频演示文稿。
- - **独立对抗性 Critic 质检工具 (`critic_audit.py`)**
- - 新增对抗性质检审查脚本 `critic_audit.py`,包含四大判定硬性标准:WCAG 无障碍色彩对比度校验、Claims Ledger 事实断言核对、Footer Band 页脚 48px 防遮挡保护区校验及未替换占位符(Placeholder)审查。
- - **动画质量审计与节奏质检 (`animation_quality_auditor.py`)**
- - 提供独立的动画节奏、效果、持续时间及元素层级质量审计工具,提升入场与转场动画的视觉流畅度。
- - **品牌预设、架构图模板与 Layout 骨架库全面扩展**
- - **品牌预设扩充**:新增 `swiss_grid`、`apple`、`black_gold`、`code_terminal`、`cool_white`、`dark_blue_mag`、`dark_graph`、`energy_growth`、`glassmorphism`、`gold_index`、`linear`、`magazine`、`neon_tech`、`neumorphism`、`notion`、`sonic_neon`、`spectrum_chart`、`stripe`、`swiss_style` 等 20+ 款高保真品牌与排版预设。
- - **图表与架构 SVG 模板**:新增 `diagram_shell.svg`、`code_diff.svg` 等代码比对与架构图表达组件。
- - **Layout 布局模板**:新增 `black_gold_comparison.svg`、`code_architecture_flow.svg`、`double_diamond_process.svg`、`glass_metrics_grid.svg`、`neumorphic_cards.svg` 及 `swiss_style` / `magazine` 完整套图布局。
- - **视觉排版与专业设计规范文档库 (`references/`)**
- - **设计工程规范 (`design-engineering-craft.md`)**:制定现代 UI/PPT 视觉工程标准,包含网格系统、留白比例、视知觉层级与文字防拥挤规范。
- - **学术答辩模式 (`academic.md`)**:新增学术开题/毕业答辩专用模式规范与结构模板。
- - **界面截图包装规范 (`screenshot-framing.md`)**:提供产品 UI 截图阴影、外壳包装、设备框选与高亮聚焦的标准指导。
- - **风格规范补全 (`swiss_style.md`, `magazine.md`)**:补充瑞士平面设计风(International Typographic Style)与高品质杂志风(Editorial Magazine)专项指导。
- - **新增重构与桥接工作流 (`workflows/`)**
- - **图片/PDF 截图重构 ([`image-to-pptx.md`](workflows/profiles/image-to-pptx.md))**:支持将图片、PDF 截图、AI 海报重构为原生可编辑 PPTX 矢量文本框与形状。
- - **Humanize PPT 桥接 ([`humanize-ppt-bridge.md`](workflows/adapters/humanize-ppt-bridge.md))**:对接 humanize-ppt 产出的结构化 Outline、Brief、AST 提纲与 Speaker Intent。
- - **Web 确认页 (Confirm UI) 启动契约规范**
- - 在 `SKILL.md` 中强化规定:用户发起生成请求时必须强弹 Confirm UI,仅在 Pure Headless / CLI 终端无 GUI 环境下才允许降级为 Chat 纯文本确认。
- ### 2026-07
- - **实时演讲稿自动检测与同步**
- - 在编辑和播放模式下增加对磁盘讲稿文件 `notes_mtime` 修改时间的定时轮询检测,当讲稿被上游 AI Agent 重新修润并覆写时,浏览器会自动实时载入最新讲稿,无需手动点击或刷新。
- - 内置编辑区输入焦点防打扰逻辑(如果当前正在输入,则推迟自动同步),完美保证操作的流畅性。
- - **全模板一键主题换肤与手/自动切换**
- - 将 Astryx-style 的动态换肤扩展到了全部 23 套 Layout 骨架模板,支持手/自动任一模板主题的一键重配 Repaint。
- - 完美提供“原片展示模式 (Default Theme)”:切换回原片时会直接还原最原始的 SVG 结构并删除一切 inline style,零偏色无损呈现。
- - **一键换肤自适应对比度与线框优化**
- - **智能对比度适配**:引入 WCAG 相对亮度算法,在切换到深色背景(如 `Academic Defense`)时,所有黑色/暗灰色文字及图例线条自动一键调亮为浅白色;原白色卡片底色(`#ffffff`)自动降噪为深色半透明(`#1e293b`)。
- - **连线与细框专属自适应变量 (`--color-border`)**:对流程连线、细线和边框进行了分类处理并绑定专属自适应变量,切换深色主题时自动渐变为蓝灰色,浅色主题时自动渐变为温和淡灰/淡绿,彻底解决以往换肤后线条看不清的情况。
- - **极简视图控制与真·全屏演示**
- - 在播放模式的右上角控制条中,将“分屏模式”、“仅片子 (100% 高度 + 0内边距完美撑满全屏)”、“仅讲稿 (100% 高度)”整合成一个极简的 **单键 Toggle 按钮**,一键循环切换。
- - 右上角操作控制条支持 3 秒无操作自动向上收起和淡出隐藏,鼠标在全屏移动时立刻淡入浮现,保证零元素干扰的高保真演示。
- - **原生 PPTX 编辑能力收敛**
- - 保留原文件的局部修改、讲稿、旁白、转场和动画统一进入 `Edit Native PPTX`;用户提供的 PPTX 若用于新内容生成,则只导入为 Brand,不会自动产生 Layout 或 Pack。
- - **模板与图表资产库大幅扩容**
- - **模板扩充**:21 套传统行业页面体系已拆分为 Layout + Style,并通过同名 Pack 保留一键选择;机构、学校和活动身份资产统一收敛为 Brand。
- - **图表扩充**:持续合并并去重 SVG 图表/信息图,当前索引为 **139 个**,涵盖更多行业可视化场景。
- - **Layout 骨架扩充**:新增 16 组 Layout 骨架,使骨架总数从 7 组扩充至 **23 组**,包含极简商务、编辑性衬线、水彩多彩、产品发布等风格。
- - **新增品牌预设**:增加 `flink_ai_style` 品牌风格预设。
- - **Confirm UI 与 Live Preview 网页交互终端重构与体验优化**
- - **两阶段确认**:Confirm UI 升级,支持更精细的 `content_divergence`、`generation_mode`、`transition_effect`、`refine_spec` 控制。
- - **逐页精修 (Gated Mode)**:新增 `gated` 生产模式,每生成一页将暂停等待用户在浏览器中预览、批注、重新修复并显式确认后,再行继续。
- - **Live Preview 功能增强**:
- - 内置**演讲稿 (Speaker Notes) 直接编辑与实时保存**功能。
- - 新增底部键盘与鼠标快捷操作提示栏(键盘导航、←/→翻页、右键重叠元素选择器等)。
- - 支持 Shift+点击多选、Tab 快速标注等操作。
- - **母版保留功能 (Preserve Master) 原生支持**
- - 原生支持 `preserve_master: true`(保真美化模式),通过 `svg_to_pptx.py` 自动应用源 PPT 幻灯片的母版布局。
- - 制定并自动执行了严格的背景/图表容器透明度规范,避免全画布大卡片(Full-canvas wrapper card)遮挡底色,确保局部重构元素与原生母版完美融合。
- - **质量检验与自动化合约测试**
- - 新增自动化合约测试套件 `test_skill_contract.py`,保证 Gated 流程、Live Preview 交互以及 OOXML 结构的稳定性。
- - 优化转场与动画配置默认值:转场效果默认关闭 (`-t none`),避免不必要的 AI 痕迹。
- ## 致敬 ppt-master
- `ppt-master-plus` 继承并致敬 [`ppt-master`](https://github.com/hugohe3/ppt-master):它保留了原有 skill 对“原生可编辑 PPTX”“高质量 SVG 页面”“模板驱动制作”和“中文汇报场景”的执着,同时将 21 套传统行业页面体系拆分为品牌无关的 Layout、可复用 Style 与组合 Pack,扩充 Brand 身份预设、图表 SVG 与 Layout 骨架,并新增讲稿质检能力和更严格的生产流程。
- 这个 `plus` 不是推翻,而是延展:在 [`ppt-master`](https://github.com/hugohe3/ppt-master) 的地基上,把新的 intake / beautify / enhance 工具链、分阶段审核、PPTX 原生增强、软依赖绘图路由和更严格的生产纪律合并到一条更完整的工作流里。
- 感谢 [`ppt-master`](https://github.com/hugohe3/ppt-master) 打下的底层方法论:先理解内容,再设计叙事;先锁定规范,再逐页制作;最终交付的不是图片截图,而是可编辑、可演示、可继续加工的 PowerPoint。
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.