Cn Academic Spark Ppt Engine

CN Academic Spark PPT Engine

document explanation(It doesn't affect the process, it only helps with understanding）：本文件是 skill 主入口；当用户提供学术材料并要求生成中文学术 PPT 时触发；它串联 source 解析、模板选择、学术大纲、图片获取、内置 TechnicalRoute、SVG 生成、质检和 PPTX 导出。

Core Contract

Output a real editable .pptx, not a Markdown outline and not flattened slide screenshots. Generate editable SVG pages first, then convert them to native DrawingML using scripts/svg_to_pptx.py.

Hard requirements:

• Run steps serially. Each step's output is the next step's input.
• Stop at blocking checkpoints when user confirmation is required.
• Re-read project spec_lock.md before generating every SVG page.
• The main agent writes the final SVG pages sequentially. Do not delegate bulk SVG generation to subagents.
• Use mixed-font <tspan> segmentation for Chinese / Latin / numeric SVG text. See references/academic/citation-style.md.
• Keep design_spec.md and spec_lock.md keys in English. Field values may be Chinese.
• Do not load or call any external technicalroute skill. Use the internal scripts/technicalroute/, references/technicalroute/, and templates/technicalroute/ folders only.
• Academic decks require internal TechnicalRoute A/B by default. Generated project files may not opt out with technicalroute_required: false, technical_route_required: false, skip_technicalroute: true, or similar wording. Create <project_path>/technicalroute/route_01/ during planning; a missing technicalroute/ folder is a blocking failure, not an optional omission.
• Cover slides are metadata-only: show the material title/topic, report type, presenter/defense candidate, advisor, institution, date, and paper/source/DOI when applicable. Do not place source figures, formulas, route diagrams, result charts, method summaries, or research-content teasers on the cover.
• Language policy is Chinese-first. If the user input/source package is Chinese, every PPT text object must be Chinese. If the source paper is English, the cover must show a Chinese translated paper title plus the original English title as secondary/original-title metadata; all non-cover generated PPT text must be Chinese except source-figure pixels, formula variables, DOI/citations, journal names, author names, and explicitly marked original-title metadata. svg_quality_checker.py blocks English-dominant generated titles/body text.

Main Scripts

Template Indexes

Always inspect templates/resource_index.json first, then the resource-specific index before choosing assets:

• templates/resource_index.json: compact map of resource indexes, selection stages, and downstream consumers.
• templates/layouts/layouts_index.json: deck layout templates.
• templates/charts/charts_index.json: reusable chart and framework SVGs.
• templates/formula/formula_templates_index.json: formula explanation block templates; use for one PNG containing formula title, formula, and variable interpretation.
• templates/technicalroute/templates/templates_index.json: editable TechnicalRoute SVG skeletons.
• templates/technicalroute/Custom_gallery/: style anchors for AI-generated route diagrams.
• templates/icons/: icon libraries.

Academic defaults: academic_defense for defense / group meeting / journal club, medical_university for medicine and life science, and government_blue for proposal defense.

References To Load On Demand

Academic references:

• references/academic/paper-type-guidance.md: classify paper type, choose narrative, and write numbered slide titles.
• references/academic/route-academic-paper.md: Route A, single academic paper.
• references/academic/route-course-report.md: Route B, course report or case / policy report.
• references/academic/route-proposal.md: Route C, proposal / research plan.
• references/academic/route-literature-review.md: Route D, literature review.
• references/academic/citation-style.md: GB/T 7714 citation footer and mixed-font SVG rules.
• references/academic/speaker-notes.md: spoken notes rules.
• references/academic/layout-library.md: academic content_type layout mapping.
• references/academic/formula-rendering.md: mandatory formula extraction, LaTeX rendering, PNG embedding, and formula QA.
• references/academic/executor-academic.md: academic executor additions; read in Step 6 with references/executor-base.md.

TechnicalRoute references:

• references/technicalroute/content-schema.md
• references/technicalroute/diagram-contract.md
• references/technicalroute/archetype-thinking.md
• references/technicalroute/archetype-method.md
• references/technicalroute/archetype-workflow.md
• references/technicalroute/color-typography.md
• references/technicalroute/shape-recipes.md
• references/technicalroute/seed_sites.json
• references/technicalroute/seed_urls.md
• references/technicalroute/image-templatedraw.md
• references/technicalroute/image-aigenerate.md
• references/technicalroute/handling-no-references.md
• references/technicalroute/qa-checklist.md

Conditional Workflows

Load these only when the trigger matches:

Workflow

Step 1 - Parse Source Material

Gate: the user has provided a PDF, DOCX, EPUB, URL, Markdown file, pasted text, or existing notes. If the user only provides a topic and no source material, run conditional-workflows/topic-research.md first with citeable academic or authoritative sources, then return here.

Commands:

Academic PDF figure extraction defaults to rendered clipping, because embedded-only extraction can lose vector layers, arrows, axes, and captions. Use --image-extract embed only when legacy behavior is required, or --images none when figures are not needed.

Step 2 - Initialize Project

python3 scripts/project_manager.py init <project_name> --format ppt169
python3 scripts/project_manager.py import-sources <project_path> <source_files...> --move

Checkpoint: projects/<name>/ exists with sources/, templates/, images/, svg_output/, and notes/.

Step 3 - Select Template

Read templates/layouts/layouts_index.json. Do not default to free design unless the user explicitly asks for it or every candidate scores below threshold.

Score candidates by scenario match, style / audience match, palette fit, and school / institution identity. Write the Top 3 candidates into design_spec.md section I with original summary, matched keywords, rationale, and copy command. Ask the user to choose candidate 1 / 2 / 3 or free design at Step 4.2.

After template choice, copy the template SVGs, design_spec.md, and images into the project. Read the copied template design_spec.md and merge its Color, Typography, and Page Roster into project design_spec.md and spec_lock.md.

If the selected template came from a user-provided PPTX, its detected aesthetics and parameters have the highest priority: master/layout placeholder geometry, title position, title box size, font family, font size, bold settings, colors, logo position, footer rhythm, page-number position, and page density. Use the template in master-placeholder fill mode: replace placeholder prompt text inside the corresponding master/layout/slide-local slots and inherit that slot's geometry and text style. Add source figures, formula PNGs, charts, and route images into the matching picture/content placeholders. Do not overlay new text on top of template prompt text. Do not create extra free-floating shapes, text boxes, or image frames when a suitable template slot exists. If a slot is unusable, choose another imported layout; only fall back to the built-in template library after recording the fallback in spec_lock.md. Treat school name, college name, logos, page numbers, footer marks, and authored master graphics as protected regions. Run overlap/placeholder cleanup before export and block export if any prompt such as Click to edit..., 单击此处..., or 演讲者/课程名称 remains visible.

Before generating pages from a user-provided PPTX template, read manifest.json / templateBinding and copy the manifest-derived editableContentRegion into design_spec.md and spec_lock.md. Center body content inside editableContentRegion.primary, keep titles inside the imported title slot / titleRegion, and keep citations, footer marks, and page numbers inside the imported footer slots. If the editable region is missing, zero-sized, or overlaps logo / school-name / footer protected regions, run scripts/template_import/layout_guard.py and block SVG generation until the template contract is fixed. A user-template deck is invalid if any slide has more than one visible page number.

Template import or creation uses conditional-workflows/create-template.md.

Step 4 - Strategist Stage

Read:

references/strategist.md
references/academic/executor-academic.md

Classify the deck route first and read only the matching route reference:

After Route A / B / C / D is selected, read:

references/academic/paper-type-guidance.md

Use it to classify the paper type, choose the narrative framework, and then organize modules and slide titles. This reference is the local copy of the Paper-Type Guidance logic; do not read external skill paths during execution. Body slide titles must use:

<module_number> <module_title>: <slide_subtitle_or_evidence_conclusion>

Examples: 4 Model Results: Variable Importance Ranking; 4 Model Results: Network ALE Structure Analysis. Cover, agenda, section divider, acknowledgements, and reference pages may omit this format.

Blocking confirmation: ask once for canvas, template choice, page count, audience, style goal, palette, icon style, typography, and image policy. Page count means editable/report-content PPT pages; the TechnicalRoute Version B AI reference image page is extra and does not count against the requested page target. Record the user's number as user_requested_page_count and requested_regular_page_count in design_spec.md / spec_lock.md; if the user asks for 18 pages, build 18 regular editable/report pages and export 19 total slides after the Version B direct image page is inserted.

Step 5 - Image Acquisition

Gate: design_spec.md contains any Acquire Via: ai or Acquire Via: web, or source figures / complex tables are available. Read as needed:

references/image-base.md
references/image-generator.md
references/image-searcher.md
references/image-layout-spec.md

Academic image priorities:

• Reuse every extracted paper figure/table that is marked ppt_required in image_manifest.json; mechanism diagrams, principle/model diagrams, workflow figures, result figures, and complex table screenshots are high-priority evidence and should not be silently dropped.
• Run scripts/analyze_images.py to create captions, placement recommendations, figure roles, and targeted-explanation requirements before writing the slide roster.
• For each reused paper figure/table, add a concise slide-specific Chinese explanation tied to the paper's mechanism, method, data, or result. In SVG, tag the image or explanation with data-source-figure="<filename>" / data-explains-image="<filename>" when possible so svg_quality_checker.py can verify coverage.
• Label embedded source figures with citation markers.
• For self-drawn research route, framework, thinking map, or full-paper workflow diagrams, switch to Step 5.5.

High-priority visual coverage rule: except TechnicalRoute pages, summary pages, and planning / implication pages, every slide must contain at least one meaningful image, source figure, complex table screenshot, chart, or mathematical formula.

Formula rule: when the source contains equations, read references/academic/formula-rendering.md. Analyze the user text, extract main academic steps, keep the important formulas under those steps whenever possible, transcribe each formula as LaTeX, write the formula title and variable meanings, render the title + complete formula + interpretation as one PNG with scripts/latex_formula_to_png.py --block-json, and insert that PNG via <image data-formula-png="true" data-formula-block-png="true">. This is mandatory for both user-provided PPTX templates and built-in template-library decks. Do not render formulas or their interpretation as separate SVG text boxes. Put at most five formula blocks on one slide and separate adjacent formula blocks with gray 1.5pt dashed lines. Use low-resolution formula screenshots only when LaTeX transcription fails and the limitation is recorded.

Step 5.5 - Internal TechnicalRoute Dual Output

Gate: academic decks require this step by default. Generated design_spec.md, spec_lock.md, outline, notes, SVG pages, or QA text may not bypass it with technicalroute_required: false, technical_route_required: false, skip_technicalroute: true, or equivalent wording. Any resource or page that requires technical_route, research_framework, thinking_map, whole_paper_workflow, concept_framework, mechanism diagram, principle diagram, or embed_technicalroute: true also counts as this gate. A page roster item, slide title, notes line, or final QA item named Technical Route, Research Workflow, Workflow, Pipeline, 技术路线, 技术路线页, 全文方法链条, or equivalent Chinese wording counts as this gate; a locally hand-drawn workflow page is not a substitute for the required A/B TechnicalRoute output. svg_quality_checker.py blocks export when an academic project has no TechnicalRoute A/B output, even if the agent forgot to declare the route page in design_spec.md.

For every required route diagram, generate two consecutive PPT pages:

Page-count rule: Version B is an extra reference page, not part of the user's requested slide count. If the user asks for 18 PPT pages, generate exactly 18 regular editable/report-content pages, then insert the direct Version B AI reference page through _direct_image_slides.json, so the final PPTX must contain 19 slides. Report this clearly in ppt_outline_cn.md / final QA as “AI 技术路线参考图页，不计入用户页数指标；用户要求 18 页时最终导出 19 页”. The manifest entry must include page_count_policy: extra_reference_page_not_counted, counts_against_user_page_count: false, and page_count_delta: 1.

Execution order:

1. Create <project_path>/technicalroute/route_01/ immediately when planning the deck, then read references/technicalroute/diagram-contract.md and create <route_workdir>/contract.md with generate_route_image.py contract. Ask the user only for blocking ambiguity or explicit pre-approval requests; otherwise record conservative assumptions and continue.
2. Classify archetype and sub_variant, then read exactly one matching archetype file: archetype-thinking.md, archetype-method.md, or archetype-workflow.md.
3. Read references/technicalroute/content-schema.md and write <route_workdir>/content.yaml from the source and confirmed spec only. No Custom_gallery or literature-reference text may enter content.yaml.
4. Read references/technicalroute/color-typography.md and references/technicalroute/shape-recipes.md; write route spec_lock.md with inherited deck colors, user PPTX template palette priority, shape radius, template_key, slot_map, color_var_map, gallery_refs, and forbidden additions.
5. Read references/technicalroute/seed_urls.md for the branch rules, and treat references/technicalroute/seed_sites.json as the only source of online academic-search sites. First run literature_search.py emit-plan --topic <paper title/keywords> --archetype <thinking|method|workflow> --out <route_workdir>/style_refs, execute the generated search_plan.json with academic search over seed_sites.json, inspect similar papers for mechanism diagrams / model-principle diagrams / technical-route or workflow figures, download accepted raster figures, and record them with literature_search.py record. Then run literature_search.py prepare-ai-refs --topic <paper title/keywords> --discipline <discipline> --archetype <thinking|method|workflow> --out <route_workdir>/style_refs. If usable literature refs exist, refs must contain only those manifest-listed raster figures. Only after the seed-site search completed and produced zero usable raster refs may prepare-ai-refs --allow-gallery-fallback-after-search --search-completed select raster anchors from templates/technicalroute/Custom_gallery/gallery_index.json; if no exact gallery match exists, it must choose the highest-scoring nearest-intent gallery raster and record selection_policy: nearest_intent_within_custom_gallery_only. The refs list must never mix literature and gallery sources. Do not hard-code sites or use SVG/PPTX/editable route pages as AI references.
6. Inspect templates/technicalroute/Custom_gallery/ only through prepare-ai-refs fallback output; record the selected gallery_refs from route_ai_refs.json, do not invent files, and do not copy reference text.
7. Read references/technicalroute/image-templatedraw.md; select a template from templates/technicalroute/templates/templates_index.json, complete the slot map, and generate Version A with generate_route_image.py assemble.
8. Read references/technicalroute/image-aigenerate.md; build prompt_ai.md from the article outline / content.yaml, then generate Version B with generate_route_image.py run-ai-variant --refs-plan <route_workdir>/style_refs/route_ai_refs.json. Let run-ai-variant write <project_path>/svg_output/_direct_image_slides.json automatically, or pass --direct-slide-manifest <project_path>/svg_output/_direct_image_slides.json --after-svg-stem <NN>_route_template, so the generated PNG is inserted by the PPTX exporter as a direct picture slide without any SVG wrapper. --refs-plan is the single allowed reference bridge: it must be either literature_only with seed-site manifest raster refs, or gallery_only_fallback with Custom_gallery raster anchors only when the seed-site search completed, produced no usable refs, and both gallery_fallback_after_search and seed_search_completed are true. Mixing the two classes, manual --refs, SVG, PPTX, and screenshots of Version A are forbidden. Version B is prompt/reference independent from Version A; never feed route_template_svg_path, pipeline_with_stages.svg, assembled SVGs, PPT exports, or screenshots into the AI image call. If image_gen.py fails, stop and fix .env / provider credentials / references; do not generate or insert a deterministic local fallback PNG. Backend/model selection follows .env.example: set IMAGE_BACKEND plus provider-specific keys/model variables in the process environment or .env. run-ai-variant blocks --backend / --model overrides so the agent cannot bypass the configured image backend. Keep --aspect_ratio 16:9 --image_size 4K; the script then normalizes the PNG to at least 330ppi full-slide target pixels before PPT insertion.
9. Verify route_ai_image_path exists, <route_workdir>/output/<route_ai_stem>_generation_meta.json records generator: image_gen.py, local_fallback: false, backend_prompt_path, refs_plan_path, and reference_flow: academic_search_then_gallery_fallback, and <project_path>/svg_output/_direct_image_slides.json contains a technicalroute_ai entry whose image_path points to that PNG, whose after_svg_stem points to the Version A route template slide, and whose page-count fields mark Version B as one extra non-counted reference page. create-ai-slide --out-svg is blocked by default and must not be used in production. Normal execution must not wrap Version B in SVG; scripts/svg_to_pptx.py reads _direct_image_slides.json and inserts the PNG as the next PPTX picture slide directly. Run references/technicalroute/qa-checklist.md before export.
10. Run the mandatory TechnicalRoute stage gate before Step 6 or any downstream finalize_svg.py / svg_to_pptx.py call:

python3 scripts/technicalroute/generate_route_image.py gate --project <project_path> --route-workdir <route_workdir> --after-svg-stem <NN>_route_template

The gate must return OK: technicalroute_gate = PASS. If Version A editable SVG, Version B AI PNG, image_gen success metadata, route_ai_refs.json, _direct_image_slides.json, or the A/B consecutive insertion anchor is missing or invalid, stop immediately and fix Step 5.5. Do not proceed to Step 6, finalize, notes export, or PPTX export with only one TechnicalRoute version.

TechnicalRoute output record:

contract_path: <route_workdir>/contract.md
content_yaml_path: <route_workdir>/content.yaml
route_spec_lock_path: <route_workdir>/spec_lock.md
route_template_svg_path: <route_workdir>/output/route_template_<id>.svg
route_ai_image_path: <route_workdir>/output/route_ai_<id>.png
audit_report_path: <route_workdir>/audit_report.md
route_template_slide_svg_path: <project_path>/svg_output/<NN>_route_template.svg
route_ai_direct_slide_manifest: <project_path>/svg_output/_direct_image_slides.json
route_ai_page_count_policy: extra_reference_page_not_counted
user_requested_page_count: <regular editable/report-content page count>
final_pptx_page_count: <user_requested_page_count + number_of_route_ai_direct_picture_pages>
reference_mode: literature_only | gallery_only_fallback
gallery_refs: []
style_refs_manifest: <route_workdir>/style_refs/manifest.json

Academic integrity lock: TechnicalRoute Version B may use only literature-search rasters listed in route_ai_refs.json or Custom_gallery fallback rasters selected by prepare-ai-refs; offline user reference images, SVG/PPT/PPTX files, exported slides, and Version A screenshots are forbidden. All visible labels, formulas, data names, method names, place names, author names, citations, and numeric values must come from the uploaded paper, user material, or confirmed design_spec.md.