sn-ppt-entry

sn-ppt-entry

Uniformly receive PPT generation requests, establish a unique task directory, and prepare materials. Standard first completes targeted external evidence supplementation, Deep first completes full Research,The next step must call sn-ppt-story to generate the common outline.md, then distribute according to choices.output to sn-ppt-standard、sn-ppt-dazzle or sn-ppt-creative。

This is the entry point of a Skill set, not a standalone runtime. Text understanding, visual understanding, and reasoning use the host Agent's existing capabilities. For ordinary search, image search, and image generation, prefer the host's native tools; only when native capabilities do not exist or actual calls are unavailable, use the sn-ppt-toolsbundled with the entire PPT package. The user must not be required to separately configure a model client, and model_client.py、stage.py must not be called, nor may a CLI scheduling layer be recreated for this process.

Box-Agent compatible entry

In Box-Agent, obtain the Entry's absolute Skill Root from the Skill prompt loaded this time, recorded as <ENTRY_SKILL_ROOT>. All deterministic scripts of the Entry must be invoked using python "<ENTRY_SKILL_ROOT>/scripts/<name>.py" ; it is forbidden to use $SKILL_DIR, the current working directory, or a relative skills/ path. All task artifacts must still be written to the same absolute $DECK_DIR, and this path must be reused verbatim when calling the Story and exit Skills.

Three independent choices

Execution depth

draft: form a viewable directional draft as quickly as possible. By default, no external fact search is performed, and production begins directly after the outline is completed.
standard: balance between quality and waiting time. Before Story, Entry performs targeted external search and evidence supplementation, without running the full sn-deep-research; before generation, let the user see outline.md。
deep: first complete sn-deep-research, then generate the formal outline.md; before generation, let the user confirm.

Entry recommends a tier based on task complexity, fact timeliness, material completeness, and the user's wording, while displaying Draft / Standard / Deep. The user can override; if the user does not override, the recommendation is adopted, and no blocking question-and-answer round is added for this choice.

Output format

static_html -> sn-ppt-standard
dynamic_html -> sn-ppt-dazzle
creative -> sn-ppt-creative

When the user provides an existing PPTX, template, or semi-finished product and requests modifications, go directly to sn-ppt-edit, rather than first going through the generation exit. Static HTML is still post-processed by sn-ppt-standard itself (by default exporting PPTX). Entry is only responsible for routing, verifying real files, and registering artifacts.

Design richness

restrained(restrained): government and enterprise, academic, legal, financial, or when simplicity is explicitly required.
rich(rich): default, suitable for most business reports, product introductions, and formal presentations.
high_creative(highly creative): launch events, brand communication, creative proposals, or when strong visuals are explicitly required.

If the user explicitly specifies it, adopt it directly; otherwise recommend based on scenario, audience, output format, and wording. Display the current choice and the three tier names, but do not block separately. When the user overrides before generation, during outline confirmation, or in subsequent modifications, update the same task_pack.json. Richness only determines visual investment and does not change fact standards or Story compliance requirements.

Unique directory rule

For new tasks, the output location follows the already verified and stable original Entry rule and must not be re-inferred:

First execute pwd -P, and record thecomplete absolute path actually returnedby that command verbatim as workspace_root. The session workspace, repo root, or other path labels displayed by the host cannot replace the result of this pwd -P ; in particular, directory names such as output、workspace at the end of the returned path must not be deleted on one's own.
The unique parent directory is <workspace_root>/ppt_decks/。
The directory name is <topic_concise>_<YYYYMMDD_HHMMSS>。
After creation, in the same command use pwd -P/ the absolutized result is echoed back deck_dir, immediately write task_pack.deck_dir, and thereafter the entire chain only reuses this value verbatim; it is forbidden to re-assemble it based on framework workspace information.
Do not use the user home root, Skill directory, repo root,/tmp, another workspace, or PPT_DECK_ROOT。
When <workspace_root>/ppt_decks/ cannot be created, stop and report the permission issue; do not continue in a different location.

The file tool relative root for Box-Agent is usually <session_workspace>/output, while the workspace in the session metadata may be its parent directory. The two are not the same path. When creating task_pack.json、info_pack.json、outline.md and subsequent artifacts, you must always use the same deck_dirmentioned above; the absolute on-disk path returned by each file tool must be located in that directory. If the returned path is inconsistent, stop immediately and correct the path; do not continue between the two ppt_decks/ . Write JSON and Markdown directly using the file tool; do not use execute_code to embed a re-derived absolute path.

An existing task must reuse the absolute task_pack.json in the existing deck_dir; continuing a task must not create a new directory. All Skill installation directories are read-only.

`task_pack.json`

Write immediately after creating the directory, and update in place at each stage boundary. It is still retained after the task is completed, for progress display, task interruption recovery, and subsequent editing. Keep the fields few and stable:

{
  "schema_version": "ppt_task_v2",
  "deck_id": "topic_20260729_143015",
  "deck_dir": "/absolute/workspace/ppt_decks/topic_20260729_143015",
  "workspace_root": "/absolute/workspace",
  "ppt_mode": "standard",
  "params": {
    "role": "...",
    "audience": "...",
    "scene": "...",
    "page_count": 8,
    "language": "zh-Hans",
    "image_source": "auto",
    "infographic_source": "echarts"
  },
  "request": {
    "query": "...",
    "source_files": []
  },
  "choices": {
    "execution_depth": "standard",
    "output": "static_html",
    "design_richness": "rich",
    "static_postprocess": ["pptx"]
  },
  "state": {
    "status": "preparing",
    "current_stage": "entry",
    "completed_stages": [],
    "research": {
      "required": false,
      "executor": null,
      "mode": null
    },
    "capabilities": {},
    "artifacts": {},
    "last_error": null,
    "updated_at": "ISO-8601"
  },
  "created_at": "ISO-8601"
}

When choices.output is static_html ,ppt_mode must be standard，static_postprocess The default must be ["pptx"]. Only when the user explicitly says "only HTML" or "no PPTX" should you write []。

For the post-processing fields of other output outlets, write [], which does not trigger Static post-processing.

ppt_mode is a compatibility field for the old outlet:

`choices.output`	`ppt_mode`
`static_html`	`standard`
`dynamic_html`	`dazzle`
`creative`	`creative`

A stage update only modifies the relevant fields; it does not rewrite the user's choices or historically completed items. When starting a stage, write current_stage/status/updated_at; when completing, add the stage to completed_stages and write the absolute path of the real artifact into artifacts; when failing, write last_error. Real artifacts in the file system take precedence over outdated status fields.

`info_pack.json`

It carries only materials and factual information; it does not copy runtime state:

{
  "user_query": "...",
  "user_assets": {
    "reference_images": [],
    "reference_image_captions": {},
    "reference_docs": [],
    "reference_docs_failed": []
  },
  "document_digest": {
    "topic_summary": "...",
    "key_sections": [],
    "key_points": [],
    "data_highlights": [],
    "conflicts": [],
    "open_questions": [],
    "inherited_tables": [],
    "inherited_images": []
  },
  "raw_documents": "/absolute/deck/raw_documents.json",
  "research_report": null
}

document_digest is written directly by the host Agent after reading the complete materials, without going through an additional model API. Numbers, proper nouns, times, units, and conflicts between materials must be preserved faithfully. Uploaded images and images within documents continue to follow the original capability of "understand each image only once": after the host Agent reads them using its native vision capability, it caches the uploaded image descriptions to reference_image_captions[absolute_path], and caches the image descriptions within documents to raw_documents.documents[].inherited_images[].visual_summary. When a cache already exists and the image has not changed, skip it; downstream reads the cache uniformly; do not create an independent caption service.

Optional search and image capabilities

Resolve the sibling directory of the current Skill as the skills root, and fix it:

PPT_TOOLS_DIR = <skills root>/sn-ppt-tools

When a certain capability is needed, start by reading <PPT_TOOLS_DIR>/references/capability-policy.md, and select according to native -> bundled -> none .sn-ppt-tools is part of the complete PPT package; do not make an "is it installed" determination, and do not scan other repositories. Only write the source, status, non-sensitive error summary, and update time of each type of capability into task_pack.state.capabilities; do not record keys or Authorization headers.

Media capabilities are not mandatory prerequisites for Entry. When missing, continue according to policy; only when Creative has been explicitly selected and neither native nor built-in image generation is available, pause the Creative exit and retain all prerequisite artifacts, without automatically switching exits. When the user needs to handle configuration, only prompt to run sn-ppt-doctor; do not repeat the variable list in Entry. Doctor will show the user-level .envactually read by Hermes/OpenClaw, missing items, and configuration templates.

New task flow

Enter and identify: echo that Entry has been entered. Extract the role, audience, scenario, page count, language, attachments, explicit design requirements, and whether the user explicitly requires Static to deliver only HTML. Do not ask again for information already provided.
Route existing PPTX: if the task is editing, optimizing, continuing, or template filling, hand it to sn-ppt-edit. If it is generating from scratch, continue this flow.
Recommend three choices: determine execution depth, output format, and design richness. Ask only when the output intent truly cannot be determined and would produce completely different deliverables; in other cases, give recommendations first and continue.
Create fixed directories: strictly follow the "unique directory rule" to create directories and the initial task_pack.json。
Parse attachments: for PDF, DOCX, MD, TXT, execute:
```
python "<ENTRY_SKILL_ROOT>/scripts/parse_user_docs.py" \
  --files <absolute paths...> \
  --output "<deck_dir>/raw_documents.json" \
  --asset-dir "<deck_dir>/source_assets"
```
Markdown tables and local image references, DOCX tables and embedded images, PDF text,inherited_images as well as on-demand generated page_visuals must all be retained;page_visuals[].path must be an absolute path under $DECK_DIR/source_assets/ and handed over together withraw_documents.json . When page images have not been generated, the Figure page cropping task must return blocked. When one file fails, record it to reference_docs_failed, and continue processing other files.
Understand all materials: read all body text, tables, and image indexes in raw_documents.json ; read in segments when necessary, but do not read only the beginning. Use the host Agent's native visual capabilities to understand relevant uploaded images and images within documents one by one, cache them according to the above compatible fields, and continue after recording failed items. Then generate document_digest, write info_pack.json. Story and exits must not repeatedly understand images that already have cached understanding, unless the file changes or the current task truly needs to re-verify visual details.
Start the generation progress workbench：task_pack.json and info_pack.json both already exist, immediately call sn-ppt-workbench/scripts/open_workbench.py, always passing the current task's absolute deck_dir and the available same-session agent parameters. After successful startup, immediately provide the user with the returned generation_url(fixed as /progress); if startup fails or returns skipped , briefly explain the reason and continue generation, and do not block Research, Story, or page production because of this. Do not run npm, build Workbench, or switch task directories in this step.
Decide the external evidence path：
- Draft: skip by default, write required=false、executor=null、mode=null. When the user explicitly requests verification of a certain fact, you may directly use ordinary search to complete that verification, but do not start full Deep Research for Draft.
- Standard: write by default required=true、executor=entry、mode=null. Do not skip just because "the user's materials look sufficient"; as long as the user has not prohibited internet access and ordinary search is available, at least one real ordinary search must be performed before Story.
- Deep: write required=true、executor=sn-deep-research; default mode=normal, complex, multi-dimensional, controversial, highly time-sensitive, or high-risk tasks use heavy。quick / normal / heavy belongs only to sn-deep-research, and is not used to describe Standard.
- When the user explicitly prohibits external search or requires using only the given materials, do not go online; write required=false、 executor=null、mode=null and skipped_reason=user_forbidden, and perform only evidence audit within the materials.
complete external evidence supplementation: first determine the ordinary search source according to the optional capability rules: when the host's native web search is available, use it directly; otherwise call <PPT_TOOLS_DIR>/scripts/web_search.py。
- Standard uses the Entry current Agent to do targeted search and does not call sn-deep-research, and does not do scout, multi-dimensional decomposition, supplementary research loops, or full research report orchestration. Search targets come only from the user query, time-sensitive risks in the materials, key facts, and obvious gaps that will affect the narrative; prioritize official and primary sources, and record titles, URLs, dates, supported conclusions, and unresolved limitations. The stopping condition is that the key evidence required for the Story has been covered or the gaps have been clearly identified, and do not roam for the sake of expansion. Write concise results to <deck_dir>/research/report.md。
- Deep gives the ordinary search source, absolute report_dir=<deck_dir>/research and the current task materials to sn-deep-research, and runs completely according to mode=normal|heavy .sn-ppt-tools serves only as a search capability fallback, not another Research process.
- After both paths are completed, write the same <deck_dir>/research/report.md to info_pack.research_report and task_pack.state.artifacts.research_report, then enter Story.
- When neither native nor built-in search is available, do not fake Research, and do not block the PPT: write the fact coverage limitations in state.research.required=false、state.research.executor=null、 state.research.skipped_reason=search_unavailable and info_pack.document_digest.open_questions clearly, then directly enter Story.
- When the search capability exists but Research itself has not yet been completed, a formal outline must still not be written first.
Call Story: give the same deck_dir to sn-ppt-story. Story reads the query, info_pack.json、raw_documents.json and existing Research, and generates the sole <deck_dir>/outline.md。
Outline interaction: Draft continues production by default while informing of the outline path; Standard / Deep displays a one-line overall narrative and path, and waits for the user to modify or confirm. Before continuing, reread outline.mdon disk; the old copy in the chat must not be used.
Exit dispatch: After Story is complete and the current disk outline.md has been confirmed according to this tier, call the sole corresponding Skill according to choices.output :static_html call sn-ppt-standard， dynamic_html call sn-ppt-dazzle，creative call sn-ppt-creative. Always pass the absolute deck_dir. It is forbidden to bypass Story and hand the raw query directly to any exit; all three exits only do expression and artifact production, and no longer research, rearrange pages, or rewrite the Story.
Post-processing and wrap-up: Static HTML is exported to PPTX by default after the page is completed by the built-in exporter of sn-ppt-standard (scripts/export_pptx/html_to_pptx.mjs); this exitmust simultaneously deliver both artifacts present.html and PPTX, and missing either is a technical failure(when the user explicitly requests only HTML, PPTX may be missing, andpresent.html must still exist). PPTX can onlyGenerated by this built-in exporter: do not substitute python-pptx, a custom script, or host-native tools. Entry finally writes the real artifacts generated by each outlet back to task_pack.state.artifacts; if conversion fails, keep the existing HTML artifacts, set status to partial and truthfully explain; do not start over to supplement outputs or forge a PPTX path.

Resume rules

When the user provides a deck directory, or when a clear task package exists in the current directory:

Read task_pack.json、info_pack.json and the actual files on disk.
When the current outline.md exists, the disk version is the Story truth.
When the Research report, outline, pages, rendered images, and final artifacts exist, do not redo them just because the status field is lagging.
Continue from the earliest stage where a "necessary artifact is indeed missing".
After the user modifies the outline, only invalidate the affected pages after Story and their derived PPTX; Research and material parsing are not automatically rerun; if HTML, PNG, script, and player are all complete and only the PPTX is missing, rerun only the exporter for the corresponding outlet.
Do not create task_pack_v2.json、outline_v2.md or a second deck directory.

Progress feedback

Work lasting more than about 30 seconds must let the user see progress. Echo at least one sentence at each of the following boundaries:

task identified and three choices;
established deck_dir；
attachment parsing started/completed;
generation progress workbench started and provided /progress, or explain the non-blocking reason for skipping;
Research started/completed or explicitly skipped;
Story started/outline.md generated;
waiting for confirmation or already entered the outlet;
page production progress; after a page is completed, echo the real paths of present.html, PNG, script, and player.
post-processing and final artifacts; if PPTX fails, keep HTML, PNG, script, and player, with status partial, do not forge a PPTX path, and write the failure reason into task_pack.state.last_error。

Progress should mainly use stage descriptions the user can understand, and should not expose internal prompts, model calls, or granular status fields.

Hard rules

Existing capabilities must be retained unless explicitly removed.
Do not generate pages, images, or visual plans in Entry.
Outlets are not allowed to independently search or re-decide page order, titles, and core conclusions.
Do not silently switch output format or design tier.
If optional search or image capability fails, try native once and built-in once at most; then execute the policy's no-tool path.
Do not use mock numbers to impersonate facts; gaps should return to Research/Story or be clearly marked.
Do not delete usable HTML, images, or PPTX because Static's default PPTX post-processing fails.
Do not add external model clients, extra API configuration, a general state machine, or large orchestration scripts.
Workbench startup is a best-effort auxiliary capability of the generation process; failure must not change the output choice or abort generation.