academic-ppt-master

# Academic PPT Master Skill > Converts academic source material into high-quality SVG pages, verifies the visual output, and exports the result as a natively editable PPTX deck. **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, all subsequent non-BLOCKING steps — design spec output, SVG generation, speaker notes, and post-processing — may proceed automatically without further user confirmation) > 4. **GATE BEFORE ENTRY** — Each Step has prerequisites (🚧 GATE) listed at the top; these MUST be verified before starting that Step > 5. **NO SPECULATIVE EXECUTION** — "Pre-preparing" content for subsequent Steps is FORBIDDEN (e.g., writing SVG code during the Strategist phase) > 6. **NO SUB-AGENT SVG GENERATION** — Executor Step 6 SVG generation is context-dependent and MUST be completed by the current main agent end-to-end. Delegating page SVG generation to sub-agents is FORBIDDEN > 7. **SEQUENTIAL PAGE GENERATION ONLY** — In Executor Step 6, after the global design context is confirmed, SVG pages MUST be generated sequentially page by page in one continuous pass. Grouped page batches (for example, 5 pages at a time) are FORBIDDEN > 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 > [!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 > > - `academic-ppt-master` 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 ## 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/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/analyze_images.py` | Image analysis | | `${SKILL_DIR}/scripts/latex_render.py` | LaTeX formula rendering (manifest-driven PNG assets) | | `${SKILL_DIR}/scripts/formula_audit.py` | Formula safety audit for SVG output before PPTX export | | `${SKILL_DIR}/scripts/image_gen.py` | AI image generation (multi-provider) | | `${SKILL_DIR}/scripts/svg_quality_checker.py` | SVG quality check | | `${SKILL_DIR}/scripts/total_md_split.py` | Speaker notes splitting | | `${SKILL_DIR}/scripts/finalize_svg.py` | SVG post-processing (unified entry) | | `${SKILL_DIR}/scripts/svg_to_pptx.py` | Export to PPTX | | `${SKILL_DIR}/scripts/update_spec.py` | Propagate a `spec_lock.md` color / font_family change across all generated SVGs | 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) | | Visualization templates | `${SKILL_DIR}/templates/charts/charts_index.json` | Query available visualization SVG templates (charts, infographics, diagrams, frameworks) | | Icon library | `${SKILL_DIR}/templates/icons/` | See `${SKILL_DIR}/templates/icons/README.md`; search icons on demand with `ls templates/icons/<library>/ \| grep <keyword>` | ## Standalone Workflows | Workflow | Path | Purpose | |----------|------|---------| | `topic-research` | `workflows/topic-research.md` | Pre-pipeline — gather web sources when the user supplies only a topic with no source files | | `template-fill` | `workflows/template-fill-pptx.md` | Give a native PPTX template deck plus source material; select fitting pages (a page may be reused for several output slides) and fill text back without SVG conversion | | `create-template` | `workflows/create-template.md` | Standalone layout template creation workflow | | `create-brand` | `workflows/create-brand.md` | Standalone brand-only template creation (identity preset; no SVG page roster) | | `resume-execute` | `workflows/resume-execute.md` | Phase B entry — resume execution in a fresh chat after Phase A (Step 1–5) completed in another session (split mode) | | `verify-charts` | `workflows/verify-charts.md` | Chart coordinate calibration — run after SVG generation if the deck contains data charts | | `customize-animations` | `workflows/customize-animations.md` | Object-level PPTX animation customization — run only when the user explicitly asks to tune animation order/effects/timing | | `live-preview` | `workflows/live-preview.md` | Browser-based live preview — auto-started during generation and re-enterable any time the user mentions "live preview", "preview", "看效果", or wants to click/select a slide element | | `visual-review` | `workflows/visual-review.md` | Per-page rubric-based visual self-check — run only when the user explicitly asks for a visual re-pass on the generated SVGs (between Executor and post-processing). Opt-in only; never invoked by the main pipeline. | --- ## 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/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>` | | 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 Academic 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 | > ⚠️ **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 directory paths** supplied by the user in their initial message. The trigger rule is mechanical, not interpretive: | User input contains | Step 3 action | |---|---| | One or more explicit template directory paths (each resolves to a directory containing `design_spec.md` with `kind: brand` / `kind: layout` / `kind: deck` in its YAML frontmatter) | Read each spec's `kind`, dispatch per the kind matrix below, fuse if multiple | | 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 a path the AI can `cd` into. > 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", "academic-blue") 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` / `layouts_index.json` / `decks_index.json` together with their paths. Listing alone does not advance the pipeline; the user must send a path back to trigger Step 3. > To create a new layout or deck, read [`workflows/create-template.md`](workflows/create-template.md). To create a new brand, read [`workflows/create-brand.md`](workflows/create-brand.md). #### Three template kinds The architecture has three independent reference bundles. Full schema in [`docs/zh/templates-architecture.md`](../../docs/zh/templates-architecture.md). Summary: | Kind | Physical dir | Contains | Frontmatter | |---|---|---|---| | **brand** | `templates/brands/<id>/` | identity-only segment: color / typography / logo / voice / icon style | `kind: brand` | | **layout** | `templates/layouts/<id>/` | structure-only segment: canvas / page structure / page types / SVG roster | `kind: layout` | | **deck** | `templates/decks/<id>/` | full replica: identity + structure + middle (template overview) segments | `kind: deck` | **Segment ownership** (governs fusion override priority): | 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 | | Middle | Template Overview (use cases / design intent) | deck (no other kind writes this) | #### Single-path dispatch | User path's `kind` | Step 3 action |