easyslides

# Academic PPTX Skill > Generate and edit academic/research PPTX presentations with native editable DrawingML shapes. EasySlides is a **project-backed skill**. This file is the agent entrypoint and task router; real deck generation depends on the full repository: `scripts/`, `workflows/`, `templates/`, `references/`, tests, and local runtime dependencies. Installing only `SKILL.md` is enough for routing guidance, but not enough to generate or validate PPTX files. Read `ARCHITECTURE.md` for the layer model and capability paths. Read `INSTALL.md` for minimal skill, full local runtime, and developer installation modes. ## Route Authority Default onboarding is a conversation, not a browser workflow. Ask targeted native popup questions, one consequential question at a time, adapting to each answer until the brief is executable. Skip known facts; resolve conflicting requirements; then summarize and proceed. Follow `skills/easyslides-clarify/SKILL.md`. Open HTML guides or browser confirmation pages only when explicitly requested. Before choosing an implementation path, read `workflows/routing.md`. It owns deterministic route selection for main generation, raw PPTX template fill, native PPTX enhancement, reusable template creation, slide-image reconstruction, audio, preview, and chart verification. The workflow registry is `workflows/index.md`. Before selecting a route, invoke the clarification gate in `skills/easyslides-clarify/SKILL.md`. If the request leaves more than one reasonable interpretation that would affect the route, story, page count, template, visible wording, or visual fidelity, ask the user to choose from explicit options. Do not write a deck plan or generate slide files while a blocking choice remains unanswered. ## Mandatory production-scheme choice For every new or regenerated PPT, an unspecified production scheme is a blocking choice even when the topic, template and content are otherwise clear. MUST ask the user to choose and wait before planning slides or generating images/SVG/PPTX. Follow `workflows/clarification-gate.md` for the exact three options and examples. No automatic default. Reuse only the user's explicit choice for the same task. ## Mandatory reconstruction-mode choice In both choice rounds, MUST show Token 消耗 and 耗时 levels for every option before the user chooses. Explain that levels are relative estimates adjusted for scope and complexity, not exact usage or promised time; disclose image generation separately. Follow the cost and time disclosure in the clarification workflow. For image reconstruction, confirm 全图矢量重建 (`full_vector`) or 保留复杂配图 (`preserve_complex_images`) through `workflows/clarification-gate.md` before execution. No automatic default, even for “快点做”; reuse only an explicit choice in the same task. Both modes require native PPT text boxes. Preserve one source line in one text box, merging OCR fragments and using text runs for mixed styling; keep independent labels and table cells separate. Full-vector mode needs approval before any raster exception. Partial rebuilds apply this within selected regions. ## Image-reference templates Read the lightweight registry metadata first; load only the user's selected reference PNG. Do not preload the whole image library or batch-OCR templates. Use compressed previews for browsing. The installed library shares the project directory via a local junction; do not duplicate assets when syncing the plugin. For the image-based schemes, select visual references from `templates/image_references/registry.json` or user-supplied images, independently of the native editable template library. Follow the image-reference routing in `workflows/routing.md`; reference PPT-to-contact-sheet work does not distill a native template or generate a new deck. ## Chinese wording defaults Use “垂听” instead of “聆听” in assistant-authored Chinese PPT text by default. For example, write “感谢垂听，敬请讨论”. This user wording preference applies to all three production schemes, including slide copy, imagegen prompts, SVG/native text, speaker notes and final wording checks. It is a user preference, not a claim about universal language usage. A later explicit user instruction can override it; do not rewrite verbatim source quotations or archived files. ## Core Capabilities 1. **Create from scratch**: Source content → SVG pages → DrawingML shapes → editable PPTX 2. **Edit existing PPTX**: Unpack → edit XML → validate → repack 3. **HTML/JSX authoring path**: Use HTML/JSX as an experimental upstream authoring layer, then normalize into EasySlides-compatible SVG or shape IR before the existing DrawingML backend 4. **Academic scenario/template system**: Scenario-first academic planning with template-extensible output. The official template set is `academic_general`, `academic_scqa`, `defense_leftnav`, `defense_topnav`, `literature_minimal`, `nsfc_defense`, and `thu_speech`; `templates/template_policy.json` is authoritative. 5. **71 visualization templates**: Charts, infographics, diagrams, strategic frameworks, and tables 6. **11,635 icons**: Six SVG icon families for consistent academic and business visuals, with `lucide` preferred for new generic icons and emoji replacement 7. **Template Asset Bank**: Convert many real PPTX templates into exact-reuse slide modules for manual-template-substitution quality 8. **PPT Master Page Recipe Library**: whole-page SVG layout archetypes with fixed regions, text slots, diversity rules, and strict SVG slot measurement 9. **Card Component Library**: 13 fixed-size card styles plus PPT Master-style visual recipes with slot capacity contracts, agent selection rules, prompt skeletons, and PPTX preview export 10. **PPT Master compatibility mode**: Strict serial Strategist/Executor workflow, hand-written SVG pages, native DrawingML export, rebuildable backups, and gate checks via `scripts/ppt_master_pipeline.py` 11. **Native PPTX template fill route**: Raw PowerPoint templates route to `workflows/template-fill-pptx.md` instead of the SVG pipeline. 12. **Native PPTX enhancement route**: Finished decks route to `workflows/native-enhance-pptx.md` for notes/audio/timing/transition patches without visible-slide regeneration. 13. **Confirmation page**: Package deck-plan assumptions with `scripts/confirm_ui.py` before visual execution when the user wants a reviewable confirmation page. 14. **Visual review package**: Render or reuse slide PNGs through `scripts/visual_review.py` to produce a review manifest, local HTML page, and contact sheet. 15. **Brand presets**: Register reusable palette/typography/logo inputs with `scripts/create_brand.py` under `templates/brands/`. 16. **Clarification gate**: Resolve result-affecting ambiguity through explicit user choices before route selection and execution. ## Backend-Centered Architecture EasySlides has one production backend: normalized SVG/shape IR converted to editable DrawingML/PPTX by the local `scripts/svg_to_pptx/` pipeline. Multiple authoring frontends may feed that backend, but do not introduce a second production PPTX backend unless a dedicated spike proves better editable output, Office compatibility, and lower maintenance cost. ### Path A: Create from Scratch (SVG → DrawingML → PPTX) When no template PPTX exists, use the SVG-to-DrawingML pipeline: ``` Source Content → Project Init → Strategist (Deck Plan + Design Spec) → SVG Generation → Quality Check → Export PPTX ``` **Key advantage**: Every SVG element becomes an editable DrawingML shape — text is selectable, colors are changeable, shapes are movable. ### Path B: Edit Existing PPTX (XML Unpack/Edit/Repack) When a template PPTX exists: ``` Template PPTX → Unpack XML → Edit Content → Clean Orphans → Validate → Repack PPTX ``` **Key advantage**: Preserves all template formatting, animations, and layout structure. If the user asks to improve the look of an existing PPTX while preserving slide count, order, and visible wording, route through `workflows/beautify-pptx.md`. That route currently supports inspection plus a conservative native theme-color patch; stronger layout repair must not silently restructure the deck through the main generation path. ### Path C: HTML/JSX Authoring (Experimental Upstream) When the source is a rendered HTML page, dashboard, report, or SVG-heavy technical slide, use HTML/JSX only as an authoring and measurement layer: ``` HTML/JSX source -> browser measurement / component declarations -> normalized SVG or shape IR -> EasySlides validation -> DrawingML export ``` **Key advantage**: HTML/JSX is easier for LLMs to author for complex layouts, component reuse, dashboards, and architecture diagrams. The output still flows through the EasySlides checker and DrawingML backend. **Boundary**: `@artifact-kit/pptxgenjs-jsx` and `html-to-pptx-skill` may be used as references or in isolated spikes, but they are not main-path dependencies of EasySlides. Prefer integrating their DOM measurement and JSX authoring ideas upstream of the existing SVG/DrawingML backend. Use `workflows/html-jsx-authoring.md` when evaluating this path. ### Path D: PPT Master Compatibility Mode When the user explicitly asks to reproduce PPT Master, use the PPT Master workflow, or prioritize PPT Master-style SVG execution, follow `workflows/ppt-master-compat.md`. This mode keeps EasySlides' local converter stack but mirrors PPT Master's operating contract: ``` Source -> project init -> Strategist design_spec/spec_lock -> optional images -> Executor hand-writes SVG pages sequentially -> svg_quality_checker -> validate_svg_text_slots -> notes/total.md -> ppt_master_pipeline export -> editable PPTX ``` The Executor must write SVG pages directly into `svg_output/`; do not create a batch script that generates all pages. Use `references/ppt-master-compat.md` for execution rules, `templates/page_layouts/ppt-master-page-recipes-manual.md` for whole-page layout selection, and `templates/cards/assembly-manual.md` for nested card selection. For a large library of PPTX templates, prefer the Template Asset Bank harness: ``` PPTX templates → pptx_template_import.py workspaces → template_asset_bank.json → exact slide-module reuse ``` Use `workflows/template-asset-bank.md` and `scripts/template_asset_bank.py` when the goal is to mimic manual template substitution: fixed geometry, fixed decorative structure, and only text/image/chart data replaced. ### Path E: Slide Image Reconstruction When the source of truth is a slide screenshot, exported slide PNG, or AI mockup image, use `workflows/slide-image-to-editable-pptx.md`. This is an upstream analysis and QA contract for the existing EasySlides backend: first classify every visible source-image element into Layer A visual assets, Layer B native structure, or Layer C editable text; then assemble through SVG/shape IR and DrawingML export. This path explicitly forbids full-slide screenshot backgrounds, baked text in image assets, and dirty rectangular crops. Validate the Phase 1 element inventory with `scripts/slide_image_inventory.py`, then validate the final deck with `scripts/validate_image_reconstruction_pptx.py` alongside the normal text layout and render-diff gates. Use `scripts/project_manager.py init <name> --kind slide_image_reconstruction` and `scripts/image_reconstruction_pipeline.py init/qa` as the standard project facade for this path. Default QA mode is `pixel-strict`: editable text, native structure, asset safety, provenance and source-render differences block delivery. `--mode faithful-practical` is diagnostic only; a visual failure sets `delivery_ready=false` and a failing CLI exit code. Always inspect actual renders. For generated complete slides, follow the host-call and generation-manifest contract in `workflows/slide-image-to-editable-pptx.md`. Attach the selected template image and original evidence to the actual ImageGen call. Reconstruct each approved output as its sole visual source; do not reuse native page shells. Complex raster illustrations that become ugly as vectors should use `preserve_source_frame`; closed/circular source assets should use masked source assets with clipping checks. The image route also carries a shared alignment contract: Layer C source boxes map to absolute 1280x720 canvas coordinates, editable text stays outside transformed parent groups, and center-locked labels are checked against the actual native PPTX frame after export. Cover, content, navigation, and ending-page chrome use the same contract, so a visually hidden SVG offset cannot pass the final gate. ### Path F: Native PPTX Template Fill When the user provides a raw PowerPoint template and asks to fill it with new material or a new topic, route to `workflows/template-fill-pptx.md`. This path preserves the source deck as a native slide library and patches cloned slides directly through OOXML. Do not convert the raw PPTX template into SVG for a one-off fill request. ### Path G: Native PPTX Enhancement When the user provides a finished PPTX and asks only for speaker notes, narration audio, auto-advance timings, or page transitions, route to `workflows/native-enhance-pptx.md`. This path is append-oriented and must not regenerate or rewrite visible slide content. ### Path H: Visual Review and Brand Presets When the user asks for a confirmation page or checklist before visual execution, route to `workflows/confirm-ui.md`. When the user asks for a visual self-check, shareable preview, or review page for an existing deck, route to `workflows/visual-review.md`. When the user asks to create, register, or inspect a reusable brand palette/logo, route to `workflows/create-brand.md`. --- ## Academic Scenario-First Template Contract Use **scenario first, template second** for academic work. In plain terms: scenario first, template second. The academic scenario defines the argument structure, evidence obligations, audience state, and page roles; the template route defines visual containers, geometry, palette, chrome, and reusable slide modules. - A **template route is not a scenario**: template route is not a scenario. Do not infer "thesis defense" just because a defense-looking template is selected, and do not infer "literature report" just because a literature-style shell is available. - The built-in scenario ids are **seed profiles** for routing, not a closed taxonomy. If the user's academic use case is not an exact match, select the nearest profile and record `scenario_variant` in `deck_plan.json` and `design_spec.md`. - Preserve the selected profile's hard and required rules, then explicitly note which recommended or relaxable rules change for the `scenario_variant`. - When no matching visual template exists, do not force a defense or literature-report template. Use free academic design, a general academic pack, a domain pack, or a user-provided template path while keeping source traceability, citation retention, text fit, and PPTX deliverability intact. - For every academic task, read `references/academic-orchestration.md` before intake and planning. Audience-State-Transfer and source-backed narrative are shared planning capabilities across templates and production schemes; SCQA is an optional spine. Respect user outlines and approved image pages. ## Source Material Policy Before planning or generating a deck, classify the user's input: - **No supplied source materials**: establish whether the user will supply materials or wants agent research. An explicit research request already resolves this choice. For authorized research, run `workflows/topic-research.md`. You may gather web text and download relevant openly licensed images as PPT assets, then import the research document and image folder as source materials with provenance. - **Provided mature source materials**: if the user supplies a journal paper, thesis/dissertation, mature report, existing deck, or similar file/URL with substantive text, figures, tables, or captions, treat that material as the source of truth. Build from its claims, structure, figures, tables, captions, and user-provided assets. Do not replace extracted figures, invent substitute evidence visuals, change the source claims, or add outside material unless the user explicitly asks; any added generic background/icon must remain decorative and never stand in for source evidence. ## Path A: Create from Scratch ### Step 1: Requirements & Project Init ```bash python scripts/project_manager.py init <project_name> --format ppt169 python scripts/project_manager.py import-sources <path> <files...> --move ``` Supported source formats: PDF, DOCX, XLSX, PPTX, URL, Markdown. **MinerU PDF Preprocessing**: When importing PDFs, the system automatically tries [MinerU](https://mineru.net) for structural extraction before falling back to PyMuPDF. MinerU provides richer output: Markdown with figure/table identification, layout JSON, and extracted images — enabling better PPTX generation with automatic figure extraction. | Method | Token Required | Output | Limits | |--------|---------------|--------|--------| | Precision Extract API | Yes (`MINERU_API_TOKEN` env or `.mineru_token` file) | Markdown + JSON + images | ≤200 MB, ≤600 pages | | Agent Lightweight API | No (IP-rate limited) | Markdown only | ≤10 MB, ≤20 pages | | PyMuPDF fallback | No | Text + images (heuristic) | None | To enable MinerU: set `MINERU_API_TOKEN` environment variable or create a `.mineru_token` file in the project root. ### Paper-Report Intake For single-paper report decks, run the paper-report intake after importing sources and before Strategist writes the final deck plan: ```bash python scripts/paper_intake.py <project_path> --json ``` The intake reads `<project_path>/sources/`, Markdown converted from the PDF, MinerU/PyMuPDF-side manifests when present, and `<project_path>/images/`. It drafts `deck_plan.json` with a `source_map` for the main paper plus extracted figures, then validates the draft with `scripts/deck_plan_contract.py`. Strategist should treat the output as a traceable starting point: verify the paper title, figure captions, claims, and slide roles before writing the final `design_spec.md` and `spec_lock.md`. The intake also records source-located evidence blocks in each page's `content_contract` (`conclusion`, `evidence`, `explanation`) and summarizes `content_quality` (`status`, evidence count, source-text length, and material types). The component planner uses these signals to select an argument stack, evidence split, overview mosaic, process roadmap, comparison, or matrix from the template's verified body variants. Thin and placeholder pages remain explicit review items; generic filler should not be used to make a page look full. For Chinese硕博士毕业答辩, pass --scenario-profile thesis_defense to activate scenario_variant `cn_degree_defense_v4`. The intake then records thesis chapter hierarchy, duration-based page bands, an A-D source-figure index, high-resolution figure review flags, and the four stages source planning -> editable master -> editable sample -> full editable deck. Image2 is off by default; use the explicit --visual-exploration flag only for upstream style exploration. ### Single-Paper Literature-Report Flow Selection Before deriving the outline for `single_paper_report`, read `references/literature-report-flow-selection.md`. If the user provides a page outline, speaking script, learning notes, or slide-by-slide plan, that structure is the primary story contract. Preserve the user's page order and speaking logic, then use the paper/SI to verify claims and source figures. Do not replace the user's structure with an automatic long-form literature-report flow unless the user explicitly asks for a rebuild. If no outline or script is provided, choose or present two flow options: - `paper_ppt_concise`: concise, figure-first 6-10 slide paper report inspired by `xiao634zhang/paper-ppt-skill`. - `literature_report_deep_dive`: 20+ slide deep literature-report planning flow inspired by `fangyuanopus/literature-report-ppt-builder`, with `figure_source_manifest`, `deck_order_map`, and `page_briefs` before visual execution. Both options still use EasySlides' editable SVG/shape-IR -> DrawingML backend as the production path. ### Scenario Profiles and Rule Layers Before the confirmation step for academic decks, load the scenario profile catalog from `references/scenario_profiles.json`. ```bash python scripts/scenario_profiles.py --list --json python scripts/scenario_profiles.py --profile <profile_id> --json ``` Seed academic profiles are `single_paper_report`, `multi_paper_review`, `thesis_defense`, `proposal_or_fund`, `lab_progress`, `workshop_training`, and `conference_talk`. Pick the nearest profile from the source material, audience, and occasion, then state it as a recommendation during confirmations. If the deck is an academic scenario outside these seeds, keep the nearest profile as the rule base and record a `scenario_variant` rather than squeezing the deck into defense or literature-report wording. ### Chinese NSFC Proposal Defense When the user asks for a Chinese National Natural Science Foundation proposal defense and selects `nsfc_defense`, activate `scenario_id: nsfc_grant_cn`. This is a user-facing intent, not a request for the user to learn plan fields: the agent records the scenario contract internally and keeps the conversation in natural language. For a full deck, organize the argument as: (1) rationale and scientific question, (2) three research contents and their technical route, and (3) innovation, feasibility, and implementation plan. Every page must have one declared narrative responsibility, and the template binds that responsibility to a reviewed content variant. A table-of-contents page is optional; never add one merely because the template has a TOC shell. Ask with explicit choices before generation only when the request leaves a result-affecting decision unresolved, such as whether this is a project application or a progress defense, whether the user wants a full or concise deck, or whether supplied material may be supplemented by external research. Do not ask the user for `grant_role`, `body_variant_id`, coordinates, or other implementation details. Apply rule layers in this order: - `hard_rules`: always enforce; source faithfulness, traceability, citations, text fit, template geometry integrity, and PPTX deliverability. - `required_rules`: enforce for the selected scenario unless the user changes the scenario. - `recommended_rules`: default guidance such as action titles or ghost-deck checks; apply when useful, but let templates and content needs override. - `relaxable_rules`: soft defaults that can yield to venue, template, or teaching/activity format. Templates control visual containers; scenario profiles control content organization. Template colors, title treatment, page chrome, icon style, and layout density may override profile recommendations only when allowed by `template_may_override`; they must not override protected items in `template_must_not_override`.