SuperAPI AI Directory
Partner中文AI newsFavorites
Skillssn-ppt-standard

sn-ppt-standard

General & other

View repository

Updated 10-15 16:56

About this skill

sn-ppt-standard

Treat this file as aroadmap, not as a complete specification set to be memorized all at once. Only read the Entry/Story handoff of prepared tasks, the references and responsibility cards required by that path.

Box-Agent compatible entry

When the current harness exposes sub_agent、inspect_images、generate_image、bash and other Box-Agent native tools, before starting any production action you must fully read references/box-agent-tool-contract.md. That contract only covers tool names, parameters, script paths, delegation methods, and permission boundaries; the facts, design, quality, and delivery standards of this file and each responsibility card remain in effect. When delegating any role, you must explicitly require it in task to first read the same contract and its own subagents/<role>.md。

Hermes environment equivalent tools

Hermes does not expose Box-Agent tool names, but provides equivalent capabilities. In the Hermes host, the bash / inspect_images / generate_image / sub_agent calls appearing in the main text below are all translated according to the table below before execution, and there is no need to read references/box-agent-tool-contract.md(that contract is only used for the Box-Agent harness):

Box-Agent notation (main text) Hermes equivalent tool Translation key points
bash(command, timeout) terminal(command, timeout) Parameters correspond directly; Hermes-specific parameters (workdir/pty) are used as needed
inspect_images(image_paths=[...], instruction=..., strategy="native") vision_analyze(image_url=<单张路径>, question=<instruction>) One call per image;strategy parameter does not exist in Hermes, ignore it
generate_image(prompt, output_path, size, watermark=false) image_generate(prompt, aspect_ratio=<按尺寸取>) No output_path, after generation read back the returned path to verify it was written to disk
sub_agent(title, task, required_tools, write_scope, budget) delegate_task(goal=<task>, context=<背景>) Use the Hermes parameter form; the requirements for a self-contained task, language contract, absolute paths, and dual-read verification of artifacts remain unchanged

Delegation still requires subtasks to be self-contained, carry the language contract and the absolute path of the responsibility card, and use read_file / search_files to verify the declared artifacts; the stage division, quality standards, and delivery requirements in the main text are not relaxed due to host changes.

Entry / Story input contract (highest priority)

This Skill does not accept bare queries and does not create task directories on its own. It only accepts absolute DECK_DIR, and there must exist task_pack.json、info_pack.json and outline.md。 choices.output must be static_html, and ppt_mode must be standard. At start and on resume, re-read from disk outline.md; you must not conduct your own Research, re-parse materials, rewrite the outline, add or remove pages, reorder pages, or add new facts. If the input does not satisfy this, return Entry.

1. Contract shared by all modes

1.1 Orchestrator responsibilities and boundaries

The Orchestrator is only responsible for:Reading the Entry/Story handoff, planning, delegation, merging, acceptance, and deterministic wrap-up。

  • May write:plan/、base.css, knowledge summaries, and build artifacts.
  • Does not directly write:slides/slide_NN.html; pages are modified by Slide or Review.
  • Do not fake tool capabilities, and do not write planned actions as completed actions.
  • Every subagent must have an explicit label; results that fail, time out, or do not conclude naturally must not be treated as completed work.
  • sub_agent(title, task, skills, required_tools, files, write_scope, budget) is responsible for delegation; the structured contract, artifact paths, and handoff_path it returns are the parent-level handoff truth; the Orchestrator does not read the sub-Agent's messages.json、tool_log.json or system/tool snapshots to poll progress. The parent is responsible for using inspect_images Complete the visual inspection, as well as the deterministic wrap-up via bash, render, build, and export.

1.2 Roles

Role Count and Timing Sole Responsibility
Image Parallelize by asset volume Acquire or generate bitmap assets, return the actual paths
Slide For new creation or complex edits, parallelize by design-affinity page groups Only produce/redo its own page groups and complete the intra-group pixel closed loop
Review 1 first acceptance, at most 2 re-verifications after fixes; also the executor for simple edits Diagnose first, then centralized fixes, batch re-render, and final script closure

All roles read their own subagents/<role>.mdin full before starting work. When any selected file or section shows a truncation notice, keep reading to the end;references not hit by routing are not read。

1.3 Language and Capabilities

Lock in before starting:

  • response_language: language for the process and final replies;
  • deliverable_language: language for on-screen display, planning, and script;
  • capability status for attachments, web, real image acquisition, image generation, rendering, vision, file writing, etc.

By default, use the primary language of the user query; when the user explicitly specifies a delivery language, override separately. Only plan capabilities that are actually available. inspect_images(image_paths=["/absolute/path/to/slide_NN.png"], instruction="复述第一眼焦点、阅读路径、主要视觉载体、溢出与裁切", strategy="native") is used by the current role; visual judgment, the issue ledger, and replies after viewing images use response_language, and must not switch due to the model's default language; on-screen original text and proper nouns may retain their original language.

1.4 Workspace Source of Truth

task_pack.json
info_pack.json
outline.md
plan/design-brief.md
plan/deck.md
plan/slide_NN.md
base.css
assets/
slides/slide_NN.html
renders/slide_NN.png
speech.md
present.html   ← 必交付产物：由 `deck.py build` 生成，缺失即技术故障
`<DECK_DIR>/<DECK_ID>.pptx`   ← 必交付产物（`static_postprocess` 含 `pptx` 时）：只能由 `scripts/export_pptx/html_to_pptx.mjs` 生成

outline.md is the source of truth for page facts, page count, page order, titles, conclusions, and content relationships;grounded-knowledge.md is only the research summary generated for Entry/Story, is read-only for Standard, and must not override outline.md。 design-brief.md is the source of truth for visuals; slide_NN.md is the page content contract; base.css is the global design system; The final judgment must be based on the latest PNG, not just HTML.

1.5 Reference Routing

Scenario Read
Scenario tone-setting design-rules.md §T1–T3, §1–3 + matched theme sections;design-styles.md table of contents + one style family
Global and per-page planning planning-contract.md; for each page read only the layout-patterns.md corresponding page type
Edit an existing deck editing-contract.md
Slide its own per-page plan,base.css、quality-checklist.md"I. Single-page check" and the matched sections for this page
Review Read in full quality-checklist.md: first use "I. Single-page check" to verify visual semantics, then do "II. Full-deck check" and "III. Machine-checkable lint items"

Fonts are read only when the default role is insufficient or the occasion is sensitive fonts.md. Do not scan all design, style, layout, and font documents before starting work.

Regardless of whether fonts.mdis read, Chinese eyebrow tags, department names, footers, sources, and metadata must not use monospaced fonts or Latin ALL CAPS with loose letter spacing: use --font-sans / --font-serif, keep letter spacing at 0–0.03em。--font-mono、--tracking-caps、.is-latin-label only for purely Latin technical identifiers, code, coordinates, and real numbers.

The same Chinese title, conclusion, or label must use the same font family; emphasis words establish hierarchy only through color, weight, size, or underline, and it is forbidden to switch some of the characters to cartoon, handwriting, or another display font.The total number of font families across the deck ≤ 3 and must be uniform across the deck: The same character uses the same family on every page, and does not switch fonts temporarily because of the page subject matter; rigorous types converge to 1–2 families. Font selection is subject to the scenario and Style Lock—Chinese body text/tables/footers/headers are uniformly --font-sans(rigorous serif may be --font-serif），Chinese must never be placed in --font-mono(IBM Plex Mono has no Chinese glyphs and will fall back to a cartoonish font);--font-mono serves only pure Latin code, coordinates, and IDs.playful, rounded playful, handwriting, and calligraphy fonts are enabled only when the theme and audience truly support them (occupying at most 1 accent slot among those 3 families), and add .is-expressive-type or data-type-intent="expressive"to the corresponding element, so that the rendering check confirms this is an intentional choice.

1.6 Visual Media Priority

Choose media according to content:

  1. Real people, places, products, events: real photos;
  2. Atmosphere, metaphor, story scenes, visual key visuals: generated images or high-quality bitmaps;
  3. Data: ECharts;
  4. Large processes, architecture, mechanisms, relationship diagrams:Canvas-drawn geometry + HTML text layer, or "text-free image + HTML annotations";
  5. SVG: only for icons, logos, arrows, markers, and small decorations.

For ordinary content pages, as long as there is a visible subject such as a person, place, product, work, activity, experience, natural/urban environment, story scene, or emotional image, prioritize letting a substantial real/generated bitmap become the key visual, rather than replacing it with color blocks, icons, or abstract wireframes. The number of images is subject to the narrative and should not be mechanically padded; however, bitmap opportunities that can increase recognition, evidence, presence, or emotional value must not be silently abandoned.

**By default, it is forbidden to use hand-written SVG as a hero, half-screen/full-screen key visual, or large diagram.** SVG only handles small auxiliary graphics; if a complex non-bitmap key visual truly requires programmatic expression, prioritize Canvas geometry + HTML text layer. The only exceptions are when the user explicitly requests vector delivery, or when accurate vector assets provided by the user must be reused. For detailed implementation, see design-rules.md §5 and layout-patterns.md the Canvas diagram chapter.

2. Create a New PPT

Stage 0: Parse the Task

  1. Read task_pack.json、info_pack.json and the current disk outline.md; page count, page order, titles, conclusions, facts, and content relationships are all based on outline.md , while scenario, audience, materials, and Research path are based on the task/info pack.
  2. Lock the language, capabilities, attachment list, and delivery scope, do not ask the user about non-blocking preferences, and explicitly record reasonable assumptions in the plan.
  3. static_html The new creation process does not start Research or Material, and only reads the artifacts already generated by Entry/Story; if the required Research report is missing, return to Entry, and when facts are insufficient, do not fabricate numbers or rewrite the Story,grounded-knowledge.md serves only as a production summary.

Stage 1: Ground as Needed

Grounding gate

After the Entry/Story artifacts are handed off, the Orchestrator first verifies info_pack.json, the Entry/Story Research report, and the current disk outline.md; if a required report is missing, return to Entry, and do not redo Research, parse materials, or rewrite facts within Standard. After verification passes, write the unique plan/grounded-knowledge.md, and use read_file to verify file integrity; before completion, do not enter design-brief.md, Style Lock, or page-by-page planning. The file only organizes the already handed-off user facts, external verification, orchestrator assumptions, illustrations, conflicts, and unconfirmed items, and does not add new facts without sources.

What the attachment provides isFacts and reusable material boundaries, not the default design ceiling. During merging, also organize the reusable page images, embedded images, chart structures, and brand cues in the materials; then in design-brief.md specify material_visual_mode：facts-only、visual-reuse、style-reference or as explicitly requested by the user faithful-restyle. For each image attachment, separately write attachment_visual_map, deciding must-show / reuse / reference-only / omit, on-screen pages, and handling method; the paper's full-page visual and the in-page named Figure must be distinguished as page-facsimile and figure-crop. This judgment is independent of the external image search/generation image_opportunity. Except for faithful-restyle , do not inherit the attachment's small font sizes, dense tables, ordinary document layout, or low-quality visuals; still re-tone according to audience, occasion, and narrative.

Stage 2: Scene tone-setting and Style Lock

  1. Read visual rules according to the Reference routing, without scanning the entire library.
  2. First lock scene_register(solemn report / editorial narrative / product launch / teaching explanation / cultural experience, etc.) and one clear primary style; the style must be able to explain "why it suits this audience, occasion, and content," not merely write abstract adjectives, and do not stitch multiple style numbers into a compromise package. Borrowing one supporting craft is allowed, but the whole deck must be explainable in one visual thesis.
  3. Write plan/design-brief.md#Style Lock：
    • scene；
    • primary_style；
    • supporting_craft (at most one);
    • visual_thesis / signature_visual；
    • palette / typography / numeric_voice；
    • image_language / image_opportunity_map / composition_grammar；
    • background_system: first, based on the scene, explain whether the background should lean toward "restrained order" or "atmospheric expression," then define one base_canvas_family that runs through the content pages and the visual states allowed to vary (brightness, color field, ambient light, texture, image proportion, density, and section state); for each state, clearly write the narrative purpose, applicable pages, and entry/exit transitions. Scenes such as academic, group meeting, compliance, and serious review can be quieter, but still need typography and evidence visuals; other scenes should not treat the same solid color background for the whole deck as a safe default. Unity does not equal the same background color throughout the deck; variation also cannot depart from the same canvas family;
    • motif_role: explain on which pages the theme motif serves as the main visual, on which pages it is only a secondary thread, and on which pages it is deliberately absent. The same decorative motif must not carry the main visual for the cover, section pages, and most content pages; consistency mainly comes from typography, color semantics, image treatment, and composition grammar. Technical notes, coordinates, continuity notes, archive numbers, etc. may become motifs only when they convey real and useful information, and must not fabricate pseudo-metadata to create a "premium feel";
    • special_pages；
    • avoid；
    • spatial_rhythm: how content pages unfold, how breathing pages focus, and where the peak pages are;
    • special_page_system: what design DNA the cover, section pages, and ending page share, and what compositional action each uses.
    • material_visual_mode (when there are attachments): which are only facts, which images/charts can be directly reused, and which style cues are worth retaining.
    • attachment_visual_map (when there are image attachments): original path, must-show / reuse / reference-only / omit,material_asset_type, formal asset path, on-screen pages, crop/full-image/cutout/color grading and reasons. Paper Figure N must record the source page and boundaries of figure-crop, and must not directly reuse the full-page PDF PNG.
  4. When the user does not specify a style, actively judge by theme × audience × occasion. Do not enter planning without a Style Lock; without a visible signature_visual fulfillment page, also do not treat a generic color palette and font list as completed tone-setting.

image_language First clarify which colors themselves carry identification, evidence, or instructional information, then decide on unified treatment. Real subjects such as people, animals, plants, works, products, venues, and experimental outputs retain meaningful original colors by default; the sense of unity comes first from image selection, cropping, color temperature, local color overlays, borders, and background. Use full-image grayscale or duotone only when the user explicitly requests black-and-white/duotone, or when the visual thesis of this volume genuinely depends on that treatment and it will not harm recognizability or evidentiary value; "academic feel," "premium feel," or "for the sake of unity" do not by themselves constitute a reason to desaturate all real images in the volume. For images that carry identification, evidence, or main-visual responsibilities, also define lightweight crop_contract: focal point, subject parts/in-image information that must be retained, background allowed to be cropped, and recommended fit; do not just write the aspect ratio and let Slide guess the crop.

What Style Lock locks is thevisual language and judgment boundaries, not a fixed HTML template, and it does not lock down the geometry of every page. It must clearly distinguish:

  • Stable language: font roles, color semantics, spacing rhythm, background grammar, image cropping/color grading, graphic grammar, and kinship with special pages;
  • Controlled variation: each page's main focus, composition direction, media proportions, information density, whitespace placement, and section state;
  • Prohibited items: temporarily introducing new fonts, new color schemes, theme-less decoration, or copying the previous page's geometry while only changing the copy.

It should be like executable Art Direction: specific enough that different Slides can produce pages within the same world; yet leave enough space for each page to choose the best composition according to its content. No need to create a separate template file or shared decorative assets.

image_opportunity_map First conduct a "visible subject scan" independent of the implementation method: does this page have people, venues, products, works, activities, experiential scenes, fictional characters, or emotional main visuals worth seeing; first explain the evidentiary, identification, immersive, or emotional value the image can add, then choose real images, generated images, or code visuals. Do not first favor CSS/Canvas and then work backward to "no image opportunity."

When the core content of the page is a set ofnamed real people, key creators, guests, or team members, by default treat "person recognizability" as a real image opportunity and hand it to Image for batch retrieval of portraits, official profile photos, event photos, or team group photos. "Should not generate fake real people" only means that generated portraits cannot be used to impersonate the actual person; it cannot be used on that basis to reclassify the page as image_opportunity: none. If only some people's photos can be reliably obtained, prefer using one credible team/institutional scene image with a small number of key portraits, or reduce the number of people and restructure the narrative; do not fill in the gaps with unidentified similar faces. Only when, after real retrieval, there is still no recognizable, downloadable material suitable for on-screen use, and the images would not add identification value, use pure typography, and record the gap and the reason for downgrading in the plan.

Likewise examine named works, software/products, production processes, and cases: retrievable official visuals, interfaces, behind-the-scenes production images, process breakdowns, physical objects, or on-site photos usually establish identification and credibility better than small icons and empty cards. Every ordinary content page should have a main visual carrier commensurate with its content—real/generated images, charts, explanatory Canvas, or a typographic main visual that can truly stand on its own. Borders, empty panels, tiny icons, and decorative lines do not count as main visual carriers; pure typography only works when the text itself is intentionally enlarged, organized, and forms a clear focal point. Adding illustrations is not the same as adding scattered points: prefer one substantial main image or a set of assets with a consistent visual treatment, and let other elements quietly serve it.

When there are attachments, perform a full scan as well: prioritize reusing images that genuinely carry informational value and are clear; if the attachments have no real-scene, people, or brand images, only state "there are no real attachment images"—this does not equal "generated images would fabricate, so accompanying images are prohibited." Generated images used for atmosphere, vision, conceptual experience, or non-specific scenes can be used as an expression layer, while accurate facts, numbers, and relationships remain in the HTML / chart layer. Keep factual fidelity separate from visual imagination; do not mechanically move material summaries into a wall of cards.

Image attachments must not simply be "understood and then redrawn" and disappear by default. When the user explicitly requests creation based on a certain image, or when that image itself is the only product, person, location, work, evidence, before-and-after comparison, or overall process diagram, mark it as must-show, and have it appear on at least one page as a recognizable full image or a faithful crop; for complex flowcharts, the original image can first establish the overall picture, then Canvas/HTML can be used to redraw it step by step. Only omit when it is duplicated, irrelevant, unreadable, or the user explicitly does not want it shown.image_opportunity: none only means no new external/generated bitmaps are added; it cannot override attachment_visual_map。

The recognition and evidence of real objects, the immediacy of scenes, the credibility of people and products, and the anchors of story and emotion are all valid opportunities for accompanying images. Fictional characters, conceptual scenes, unbuilt spaces, and stylized key visuals are precisely suitable subjects for generated images, and should not be replaced with colored squares, abstract symbols, or pure CSS placeholders just because they are not real objects. "CSS is more controllable," "there are no user-shot photos," "worry about AI generation errors," and "for stylistic consistency" cannot by themselves be reasons for none ; these issues should be resolved through routing real images/generated images separately, prompt constraints, and unified cropping and color grading. Only when bitmaps truly add no value for the audience, or would be more ambiguous than charts, Canvas, or typography, should nonebe chosen. If a volume has multiple clearly visible subjects but is judged overall as having no bitmaps or only one image on the cover, this scan must be redone before freezing the plan. There is no image quantity quota here, and images are not added for decoration.

When image search or image generation capability is available,the entire volume having all none or only one image on the cover is an anomaly that needs to be justified, not the default safe route. Data, business, technical, academic, or code subjects also cannot therefore cause the entire volume to fall back to a card wall: factual pages can use charts/Canvas, but among the cover, chapter transitions, cases, scenes, vision, or conclusion, at least two nodes that can truly benefit from images should be selected, with executable search/generation briefs; for short volumes, at least one content node should be ensured, not just the cover. Only when the user explicitly requests pure typography/pure charts, or when it is proven page by page that bitmaps would reduce accuracy and readability, is a whole-volume bitmap-free approach allowed, and in plan/deck.md write the page-by-page exception reasons. This is the minimum coverage line to prevent misjudgment, not for padding numbers; factual real images and non-evidentiary atmospheric generated images must be clearly routed separately. Style descriptions such as card, minimalist, academic, or business do not equal a prohibition on bitmaps, nor can they be used as a reason to skip accompanying images. Only when the user's original text explicitly requests "plain text," "no images," or a fully semantically equivalent restriction can explicit_user_request be used as the basis for an image exemption; do not infer on your own from style labels that the user rejects images.

The visible subject scan must be written to disk simultaneously as plan/image-strategy.json, for deterministic acceptance by the generation workflow before Slide delegation. When image opportunities exist, write status: images_required、visible_subject_scan_complete: true and the complete image_opportunity_pages; when the entire volume has no bitmaps, you must write status: bitmap_exception、visible_subject_scan_complete: true, the reviewed_pagescovering all planned pages, an exception_reasonof no less than 20 characters, and one of explicit_user_request | pure_typography | pure_chart | wireframe | accuracy_critical as the exception_basis. This file cannot be replaced by a natural-language summary.

Background is not equivalent to a solid color, nor to randomly changing the skin on every page. In scenarios such as academic, group meeting, compliance, and serious review, a quiet canvas can be used to support facts; in expressive scenarios such as product, brand, investment promotion, cultural tourism, culture, story, course introduction, events, and mass communication, an environmental design layer compatible with the theme should be actively considered rather than falling back to a solid color for the entire deck: it can be a directional soft light field, local halos, low-contrast themed textures such as grain/halftone/paper texture/terrain, an image background, or a background uniformly generated by Image. A halo is valid only when it can explain the light source, the theme, and the visual focus, and when its shape and position are related to the composition; a circular blurred light spot reflected and copied behind a title still counts as a theme-less glow. First determine the base canvas family that runs through ordinary content pages, then choose a small number of compatible techniques to form the background grammar. Section differences should preferably be expressed through local large color fields, image color grading, bands, or motif states; only when a section page, hero, ending, or narrative truly requires a full scene change should the entire page canvas be replaced, and the previous or next page should retain continuity in color, texture, image treatment, or compositional direction. Images or generated backgrounds must enter image_opportunity_map and the asset brief, and paths must not be invented on the fly by Slide. Avoid several pages suddenly looking like another deck and then switching back without transition, and avoid treating deep navy, neon blue-purple gradients, or generic tech glow as the default "premium feel".

The subsequent main chain has only one path:Style Lock → 全册计划 + prepare → Image 分片并行 → 素材路径一次回填 → Slide 页组并行 → Review 诊断/有限返修 → 讲稿同步 + build → Review 查看 build 后最终像素并返回合同. If the source of truth for the previous node has not been frozen, do not start downstream tasks that depend on it; tasks at the same level that do not depend on one another are dispatched in parallel at once.build may crop fonts, update base.css and re-render the entire deck, so Vision before build can only be used for diagnosis, not as final pixel evidence.

Phase 3: Global planning and font pre-positioning

Read completely references/planning-contract.md, then proceed in order:

If materials/font-config.jsonexists, read it once first and use its title/body/number/annotation roles as the font input for Style Lock; user-uploaded fonts take priority over automatic font selection, characters not covered are automatically fallback-handled by the delivery font package, and it is forbidden to switch to a local font that was not uploaded based on the font name.

  1. Complete design-brief.md；
  2. Write plan/deck.md；
  3. Copy base-template.css as base.css and fill in the tokens;
  4. Write all of plan/slide_NN.mdin one pass, with each page carrying its own Reference route;
  5. In plan/deck.md define Production groups: all transition pages are dividers, and the cover and ending are bookends; content pages are first grouped byproduction method and compositional affinity, then narrative continuity is considered, and section affiliation is considered last. A group should share the same production problem, rather than cramming different media such as cards, complex Canvas, data charts, and real photos into one Agent merely because they belong to the same section; having the same section name does not constitute a reason for grouping. For each group also write boundary_handoff, explaining the canvas, brightness, color field, and motif state before entering this group and after leaving it; after grouping is complete, review once against the page-by-page table to ensure each page belongs to exactly one group, and that page types such as section pages and interactive pages are not misassigned.
  6. References and the ending page have separate responsibilities: sources that need to appear on screen use independent references pages or preceding content pages; closing is only responsible for converging the proposition, action, or question, and is not merged with long reference lists, detailed recaps, or multi-column summaries.
  7. Before starting Image or Slide, write a short ## Repetition & rhythm preflight: Compare canvas states, title anchors, composition direction, medium, image proportion, information density, and motif role page by page; at the same time, compare the page script of each chapter vertically, and do not mechanically copy the same set of "pain point—before case—after case—steps—tools" into different chapters. A shared rhythm can create kinship, but each chapter should still have its own problem perspective, evidence tasks, and reading actions; when a page has no independent responsibility, merge or restructure it. When repetition or flat rhythm is found, first change the page map, Style Lock, or Production groups, then freeze the plan.
  8. Do onceContent sufficiency and screen-display semantic deduplication: For each ordinary content page, first write clearly the irreplaceable takeaway for the audience, then continue explaining with the evidence, mechanism, comparison, case, action, or boundary best suited to that page; there is no fixed number of items, but a page with only a topic sentence, synonymous subtitle, and status badge does not count as content being established. If there is no new supporting layer, merge pages, change the narrative responsibility, or turn it into a transition/breathing page with a truly single focus; do not use large areas of responsibility-free blank space or repeated labels to stretch thin content into a page. Confirm page by page that the main visual carrier matches spatial_budget ; do not rely on large borders, equal-height cards, or empty panels to "fill" geometrically while pinning short text to the edges and leaving large internal blank areas that do not participate in reading. Compare titles, kicker / subtitle, image corner labels, badge, callout, legend, and footer page by page; usually choose only one strongest carrier for the same phrase, while other areas supplement the object, reason, change, or result. Repeat only when navigation or same-screen comparison truly requires it, and each appearance must serve a different function.dense is not a one-line label: if the main content is squeezed into only half a canvas or a narrow band, and the remaining space has no focus or direction, the spatial plan must be redone.
  9. Do once screen-copy firewall: Distinguish page by page between "what the audience must see" and "what is only for production use." Speaker/Audience/Occasion/Objective, page responsibility, production group, visual acceptance, material route, evidence number, assumptions, file names, and Research/Material sources all remain in the plan or script, and must not automatically enter ## 最终屏显文案. Only when the page topic itself truly discusses the target audience, project objectives, or research methods should the related content be rewritten into a narrative the audience can understand, rather than displaying 受众：…、主体：…、页面角色：… and other internal labels. Screen-display copy and HTML do not use emoji / Unicode icons (such as 👀 ✋ 💡 ✨ ★ ✦); when icons are needed, use local small SVGs consistent with the Style Lock, CSS shapes, or direct text expression. Generic decorations such as sparkles, hearts, and confetti must not be scattered across most pages as "whole-book embellishment," and should appear only on pages where they truly have a compositional responsibility.
  10. Use one deterministic command to synchronize the script and prepend the font package from the plan:
python "$SKILL_ROOT/scripts/deck.py" prepare "$DECK_DIR" --expected <总页数>

Planning freeze conditions: facts, page order, screen-display copy, visual medium, page-by-page image opportunities, material brief, background treatment, sources, script, page types, and fonts are all determined,plan/image-strategy.json has been written in, and content sufficiency, screen-display semantic deduplication, and screen-copy firewall have been passed. Before freezing, specifically disprove all image_opportunity: none: if the page already has a visual subject or scene, do not exclude it merely because "code is more controllable." When screen-display copy or font tokens change, first synchronize the plan before rerunning deck.py prepare。

The page-by-page plan must also complete one spatial rehearsal and visual acceptance rehearsal: write clearly which areas the main visual and text each occupy, how the main information uses the safe area, why the remaining space exists, and which objects, directions, domain evidence, and conclusions the audience should read from the final pixels.deck.md It must not contradict the media planned page by page. For an ordinary content page, if the rehearsal result is "the subject is shrunk in the middle with a large expanse of unassigned blank space around it", "it can only be crammed in with small text", or "generic geometry can only be used to stand in for domain evidence", revise the plan first; do not leave the problem to Slide. For a section transition page, rehearse "main information cluster + visual counterweight + whitespace responsibility": keep the content concise, but do not place only a small cluster of text in one local area and let the rest of the canvas become undesigned pure blank space.

Stage 4: Materials and Page Production

  1. Aggregate all image briefs judged to be real images or generated images, then start the Image subagent; each goal explicitly carries a stable group_id、response_language and deliverable_language。Before the first Image delegation, each plan/slide_NN.md 's unique ## 视觉实现 must already have a complete single-line machine field - image_opportunity: <枚举>; pages with bitmaps additionally use a sibling independent line to write - presentation: <四枚举之一>, must not be written as an empty image_opportunity: parent block, must not put full-bleed / framed-scene into image_opportunity, and must not put split-media and other layout values into presentation. When fields are missing, directly fix the plan and retry; do not search for or modify runtime code. As long as a valid image opportunity exists in the plan, the Image stage must not be silently skipped; if the plan requires images but there is currently no Image Worker, it must be replanned as a genuinely valid non-bitmap expression, or an Image Agent must be additionally dispatched; it must not go directly to the completed state. Materials with the same visual recipe that can be reviewed together in one contact sheet are grouped into the same shard, and multiple generated images are submitted in parallel in the same tool round. Image and Slide must not be dispatched in the same sub_agent : first complete and accept the materials, then start page production.
  2. First copy and register the source of the images marked must-show / reuse in attachment_visual_map , then hand them to the corresponding Image group; for paper-named Figures, Image first uses deck.py material-figure to generate independent, traceable Figure crops from the page image; the full-page PNG is only used as positioning context. Each Image group binds candidate paths to a stable asset_id, and deck.py asset-contact generates one ID-bearing material contact sheet, with only one whole-group Vision by default; only materials that are marked red, require cutout, have suspicious proportions, or whose subject completeness cannot be judged from the thumbnail are opened for single-image review. After Image uses asset-review to write back the final state, the Orchestrator only backfills the page-by-page plan according to ready 's asset_id → actual path + origin + crop_contract ; candidates, replaced images, and discarded images do not count as formal materials.assets/catalog.json is the single source of truth for materials and must preserve download URLs, generation models, user attachment paths, and derivation relationships; Image's natural-language summary cannot replace the catalog. For page-by-page images, first lock presentation: subject-only | framed-scene | full-bleed | evidence-crop(this is the display/background handling contract for bitmaps;only these four enums are allowed；split-media/right-half/cards/split-screen etc. are layout, not presentation; put them in layout；pages without bitmaps omit presentation entirely, do not write 无/none placeholders): any image that is to float, be stacked across color fields, or serve as an independent character/object belongs to subject-only, and Image must complete the transparency check, subject cutout, final Alpha check, and necessary single-image Vision before backfilling a usable *-cutout.png; ordinary RGB images must not be returned as transparent assets ready. A background image may only be used as a deliberate framed scene, full-bleed crop, or evidence crop; its white/cream rectangular background must not be accidentally pasted onto another canvas. Slides do not do temporary background removal, nor do they use CSS mask/multiply to fake it. When the mapping is genuinely problematic, hand it back to the same Image for re-review. For failed assets, first switch to a viable real-image or generated-image route; only when truly unavailable should you downgrade to Canvas or layout, and state the reason clearly, leaving no placeholder. Before a Slide starts, Image must have status: ready completion contract, and all planned asset_id in the catalog must be ready, the actual files must exist, and the paths and crop contracts must have been backfilled into the per-page plan.
  3. One Production group delegates one Slide, and they may execute in parallel; the first line of the goal must be written exactly as Slide Group <group_id> [NN,NN]:, for example Slide Group bookends [01,20]:. Page ownership is based on the frozen production_group ; do not replace the group ID and standard page header with narratives such as "responsible for the cover and ending" or "the first group of pages." Explicitly include response_language、deliverable_language and that group's boundary_handoff. Do not split an already frozen multi-page group into "one Slide per page" just to increase concurrency; delegate a single page only when the plan itself truly defines it as a single-page group. The same group must simultaneously satisfy narrative affinity, design affinity, and production-load compatibility; complex Canvas, standalone data charts, or heavy image-composition pages should be grouped separately when they do not truly share a composition system. Grouping provides shared design memory, not batch precision reduction: the same Slide completes each page's closed loop serially in the group's page order.
  4. The Slide first reads the Style Lock and group contract, then for each page sequentially executes "complete first draft → parent single-page render → parent inspect_images(strategy=\"native\") → at most one merge fix → parent re-render and re-check"; only after the current page reaches ready does it proceed to the next page. After all pages are complete, then batch-render this group and view all final PNGs in the group to confirm affinity and obvious regressions, but do not open a new loop for aesthetic preferences. The cover, each section page, and the ending page must each complete their own single-page closed loop. The "merge changes → re-render → re-check" after the first image viewing counts as one refine round, with at most 1 round per page; if real hard defects remain, switch to a more stable structure or return blocked. After the final modification, if there is no re-render and image viewing, you must not return ready.
  5. Wait until all pages are complete before starting the first Review. During new creation or complex editing, do not additionally delegate simple_edit or review-fix roles; the Orchestrator must not chase cjkTypography、crowded, bbox/contrast candidates, minor line-break/punctuation and other advisories, nor open an aesthetic gate-clearing loop before Review. When Review finds real hard defects with fresh pixel/DOM evidence, hand them back only to the original Slide Group they belong to; each group may be repaired at most 2 times, and on each failure the runtime restores that group's last viewed version. Only after repair may the next Review be started, with a total of at most 3 Reviews.

Phase 5: Full-deck Review and Delivery

The goal of each Review must begin with the following language contract, then state the specific diagnostic scope:

Review:
Response language: <response_language>
Deliverable language: <deliverable_language>
mode=final_review

Do not merely imply the language in the parent task or system, and do not omit it and let Review guess on its own. Then execute strictly in two stages:

  1. **Complete diagnosis:** first look at the overview, then in batches by review-contact.json view all contact sheets and necessary single pages; record the covered page numbers and findings for each batch into the same _trace/review-issues.md. Before full-deck coverage and freezing the ledger, modification or rendering is prohibited; do not skip subsequent batches just because the Deck has many pages.

  2. **Content fidelity verification:** When the task includes attachments or uses Research, before pixel modifications, compare the on-screen facts of each page with grounded-knowledge.md ; when there are attachments, also compare with the Material summary and coverage ledger, and write _trace/content-fidelity.md. When numbers, names, dates, units, product identities, direct quotes, or relationships cannot be traced or are self-contradictory, correct them or mark as blocked. Generated images may only serve as conceptual/atmospheric expression; if used for identification of a named real product, person, or case, the page must clearly be labeled "conceptual illustration" and must not be used as factual evidence. Only when there are neither attachments nor Research nor high-risk external facts maycontent_fidelity be not-applicable. When Review is stalled and closing out, the only formal artifacts permitted to be supplemented or updated are _trace/review-issues.md and _trace/content-fidelity.md; at runtime, writing these two files explicitly required by the final acceptance contract must not be prohibited, and continued modification of pages must not be allowed during the closing-out phase.

  3. **Centralized fixes:** Review both diagnoses and directly fixes issues within the current boundary that can be safely resolved; issues resolvable with the current files and existing assets must not merely be reported to the Orchestrator. Address common root causes globally first, then locally, and perform unified batch rendering only after all modifications are complete. This entire batch of "modification → batch rendering → focus re-verification" counts as 1 round of Review refine. Any HTML/base.css modification invalidates old PNGs, and Vision must not be called again before re-rendering; Canvas/SVG/HTML overlay pages must synchronously correct CSS dimensions, Canvas attributes, SVG viewBox, JS coordinates, and node anchors, and must not merely enlarge the outer container. In machine checks, boxoverflow, bbox intersections, and decorative intersections are only locating candidates; if fresh pixels show no real occlusion, cropping, or unreadability, do not shrink text, compress the subject, or delete compositionally functional elements to clear warnings.

  4. When base.css/fonts have been changed, batch the entire deck; when only local changes are made, batch the page. This batch rendering is used to confirm that fixes have not regressed, not as final delivery evidence.

  5. Generate a focus contact sheet once to confirm the changed pages. A single Review performs only 1 round of refine; if visible hard defects remain, return blocked, and the Orchestrator will hand the evidenced hard defects back to the original page group. The original page group retains the last verified version, performs one consolidated fix and re-renders for review; if the new version regresses or remains unresolved, restore the verified version. After fixes, start a new Review re-verification, forming at most 3 Reviews, without adding new aesthetic goals.

  6. After fixes are confirmed, first synchronize the script, then execute one deck.py build. Then regenerate renders/review-contact.json and the final contact sheet, and use Vision to cover all final pixels after build; if build changes base.css, fonts, or the rendering of any page, all PNGs viewed before build are considered expired. After the final image review, only updating _trace/review-issues.md / _trace/content-fidelity.md and the return contract is allowed; pages, rendering, or build must not be changed further.

  7. Artifact verification (hard gate): After Review returns ready , the parent must confirm item by item that outline.md, all HTML/PNG, the script,present.html and the player all exist, and confirm that DECK_DIR/present.html can be opened.present.html is generated by step 6 deck.py build ,must not be replaced by other files or by PPTX alone; if missing, it is a technical failure and must not be delivered。

  8. PPTX export (mandatory step, not optional): When static_postprocess contains pptx ,mustExecute the following sole export command; do not skip it and do not switch to any other tool:

    node "$SKILL_ROOT/scripts/export_pptx/html_to_pptx.mjs" --deck-dir "$DECK_DIR" --pages-dir "$DECK_DIR/slides" --output "$DECK_DIR/<DECK_ID>.pptx" --force
    • This is the only legitimate output path for the PPTX: it is forbidden to substitute python-pptx, a self-written python script, the host Agent's native presentation tool, or manual PPTX reconstruction; if the export fails, these methods must not be used to "supplement the output" either, and only the failure branch below may be followed.
    • On Linux, if this command reports a chromium launch failure / Target page, context or browser has been closed / a missing dynamic library (such as libnspr4.so), first execute export LD_LIBRARY_PATH="$HOME/.box-agent/runtime/linux-libs${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" and then rerun the same command, retrying at most once; if it still fails, enter the failure branch.
    • If it succeeds and DECK_DIR/<DECK_ID>.pptx does indeed exist, register state.artifacts.pptx; if it fails, write state.last_error(retaining the original error text), set state.status to partial, retain all HTML artifacts and report truthfully to the user,do not fabricate the PPTX path。

If Review times out, returns blocked, lacks final pixel re-verification, or does not naturally return a contract, first enter the limited recovery process rather than immediately marking the entire task as failed. After reaching 3 Reviews or 2 rework budget rounds per affected page group, stop continuing to revise pages, retain _trace/review-issues.md, restore the last verified version of each group and execute the deterministic build. As long as all slides, non-empty final renders,speech.md and an openable present.html exist, the task is delivered as "Complete (with improvements)" and carries warnings; it is judged failed only for unusable technical faults such as missing pages, missing/blank renders, the player failing to build/open, ormissing present.html etc.static_postprocess contains pptx , when export fails register according to step 8 partial and truthfully deliver the HTML version;do not use substitute tools such as python-pptx to produce another PPTX and pass it off as complete。

Review should not only check "whether there is overflow", but also compare the fulfillment of the design across the whole deck: whether the cover has a dominant focal point and the necessary hierarchy, whether section pages both share affinity and show section progression, whether the ending responds to the opening; whether ordinary pages fully use the canvas under projection type scale and form a clear reading path; whether each section boundary still belongs to the same base canvas family, and whether full-page transitions have clear entry and exit handoffs; whether the on-screen display leaks internal planning fields, sources, filenames, or pseudo-metadata with no audience value. The parent must actually call inspect_images(strategy=\"native\") to view the final pixels; if not called, it must be blocked.

python "$SKILL_ROOT/scripts/deck.py" build "$DECK_DIR" --expected <总页数>

deck.py build Generate and validate present.html(missing means an error, deck.py:1294-1295).present.html is a mandatory deliverable: build must not be omitted, and no other file may be substituted for it at delivery. When Review is ready, deliver as ready. If Review still ultimately has hard flaws but all pages, renders, speaker notes and present.html are usable, deliver as needs_improvement and show the issue ledger; usable finished work must not be discarded because of advisories, sub-Agent text wrap-up, or an imperfect Review contract.

3. Edit the PPT

First read references/editing-contract.mdin full, inspect the existing plan, HTML, materials, speaker notes and rendered images in read-only mode, establish a list of affected files/pages, and then choose the editing path.

3.1 Determining simple vs. complex

Simple editingSatisfies all of the following:

  • Does not change the core argument, page order, page responsibilities, or cross-page narrative;
  • Does not require new Research, Material or Image;
  • Do not change the global Style Lock, font system, or multiple arches;
  • It can be completed safely within a small number of pages, and the impact boundary is clear.

If any condition is not satisfied, handle it as a complex edit. Page count is only a signal, not the sole criterion.

3.2 Review Quick Fix

A simple edit delegates only one Review, with the goal specifying mode=simple_edit, the user's original modification request, the target pages, and the immutable items.

Review：

  1. Look at the existing overview and the final PNG of the target pages;
  2. List all modification items for this round at once;
  3. Read the target page plan and HTML, and make centralized modifications;
  4. Update the affected plans/scripts;
  5. Use render.py --batch --pages to re-render once and look at focus, confirming the modifications have not regressed;
  6. Sync the script and execute deck.py build, then regenerate focus, view the final pixels after build, and return ready/blocked; after the final image review, do not modify or build again.

Do not dispatch Slide, Image, Research, or a second Review.

3.3 Orchestrator Rework

Complex edits are handled by the Orchestrator:

  1. Write an impact map: what is affected for facts, narrative, page order, Style Lock, base.css, assets, pages, and script respectively;
  2. Only reuse existing results that are still valid; do not overwrite unrelated pages from scratch;
  3. Only within the already existing outline.md、info_pack.json、raw_documents.json and existing research boundaries, delegate the affected Image/Slide page groups; during the Standard phase, do not delegate Research or Material, and do not modify on your ownoutline.md. If new facts, new attachments, or missing figures for paper figure pages are found, immediately return to Entry/Story, wait for Entry to update materials/research and for Story to cover the same outline.md , and then re-enter Standard; Image/Slide tasks that do not depend on each other can still run in parallel;
  4. Update the affected plans and run deck.py prepare；
  5. Only redo the affected pages; when global tokens change, batch re-render the entire deck;
  6. Finally delegate a single Review, using mode=final_review for full-deck consistency and script finalization.

Complex edits do not allow Review to rewrite the narrative on its own or fabricate assets out of thin air, nor do they allow the Orchestrator to directly modify page HTML. When an edit changes facts, page order, page responsibilities, or core conclusions, you must first return to Entry → Story; Standard is only responsible for expression, rendering, Review, build, and Standard exporter finalization.

3.4 Edit Delivery Gate

  • The user's requests must be traceable item by item to the modification results;
  • Unaffected pages and assets remain unchanged;
  • New and old pages are consistent in style, page numbers, script, and player;
  • All changed pages have had their final pixels reviewed;
  • Font package, render freshness,speech.md、present.html pass again.

4. Hard Red Lines

  • Charts must use ECharts; do not use generated images to fake data charts.
  • AI-generated images do not carry text that needs to be presented accurately; put text in the HTML layer.
  • SVG is only for small elements, not for large structural diagrams or key visuals.
  • slides/ Keep only the official slide_NN.html, no backups or temporary pages.
  • The fixed page skeleton, footer safe area, minimum font size, contrast, and no overflow are hard gates. The body text read by the audience must not be smaller than 20px, and annotations, sources, and auxiliary explanations must not be smaller than 18px; if the font token specifies a larger value, the larger value prevails. When content does not fit, reduce the number of cards, cut repeated on-screen text, adjust the information hierarchy, or split pages; do not keep shrinking the font.
  • Internal planning labels, sources, file paths, production status, and pseudo-metadata with no audience value must not appear in on-screen content.
  • The final judgment is based on the PNG; after modifications, if it has not been re-rendered and the new pixels have not been viewed, you must not claim completion.
  • Review at most 3 controlled instances; re-verification is allowed only after the page has actually been modified and re-rendered. Once the budget is reached, stop rework and deliver a usable final draft with warnings.

5. Deterministic scripts

Script Purpose
stage_materials.py Does not participate in the new Entry → Story → Standard pipeline; material parsing is done by Entry, and Standard only reads artifacts already handed off by Entry/Story
font_bundle.py Retain: the OFL whitelist, official sources, license bundled with the package, character trimming, delivery validation, and render freshness are independent high-risk capabilities
render.py Retain: single-page diagnostics;--batch Reuse the same Chromium to render the entire book or specified pages
image_cutout.py Retain: check Alpha, remove baked checkerboard/solid-color backgrounds, and when needed use GrabCut to generate standalone subject PNGs; do not overwrite the source original images
deck.py Retain:prepare Complete planned script and font preparation in one pass;asset-register register sources;asset-assign / asset-contact / asset-review manage semantic assets, grouped contact sheets, and final status;contact generate page contact sheets;build validate sources and generate the player;sync Only for use when only the script is changed
install.sh Retain: cross-environment dependencies, fonts, and Chromium installation cannot be reliably replaced by runtime scripts; the dependency manifest has been inlined

First deployment depends on resolving the venv, PyMuPDF, distributable fonts, FontTools/Brotli, and Playwright Chromium; use scripts/install.sh to install. When running scripts, if the skill mount path differs, use the actual skill root.