pptx-import git:20260827.0462157A

Immutable. This exact content is served forever at /api/v1/blob/f62f063784886b75.

---
name: pptx-import
title: 'PPT 导入'
description: 会话里有上传的 .pptx，且用户要把这份幻灯片填进一节已建的课（先 create_stage 建课，再 import_pptx 把页面追加进这节课堂，保留原版排版；课堂标题以 create_stage 为准，PPT 不接管）。随后逐页检查（有 render_scene_preview 就渲染看）并修 bad case，理解整课之后才写旁白/spotlight，最后 TTS。仅在用户要求时插入 quiz 或 interactive。不要重新规划整课。
---

# PPT import as appended pages of a stage

Fill an uploaded PowerPoint's slides INTO the stage the user created with
`create_stage`: the slides become appended pages (or pages inserted at
`atOrder`), keeping the original layout. The stage keeps its own title and its
existing pages — the PPT is content, not the classroom's identity. Import,
**inspect and repair the pages**, **understand the course**, then write
classroom actions. Do not skip from import to TTS.

The learner-facing name is 「PPT 导入成课」. Never say "clone", "style
transfer", or "rewrite from the PPT".

Do **not** replan the imported deck. Do **not** call `generate_scene` on an
imported slide — that rebuilds the page and throws the original layout away.

## Order (do not rearrange)

1. `create_stage` for the classroom, then import the deck into it.
2. Roster.
3. Inspect every page (read, and render when the tool exists). Load
   `pro-editing` to fix visual bad cases. **Do not patch `/actions` yet.**
4. From that inspection, form a course reading (what it teaches, page roles,
   flow). Then write actions page by page.
5. `generate_tts`.
6. Quiz / interactive only if the user asked.

## Step 1 — create the stage, then import the deck

1. `create_stage` with the classroom's own title and brief. The stage — not the
   PPT — is the classroom: import never changes its title.
2. `list_materials`. Find the source `.pptx` (`mat_` id, mime or filename).
3. If several PowerPoints are attached, ask which one, unless the user already
   named it.
4. Call `import_pptx` with that source `mat_` id and the `stageId` from
   `create_stage`. Pages append after the existing ones, numbered
   consecutively. Pass `atOrder` to insert them at a position instead: pages at
   that order and beyond shift back. Existing pages are a normal premise — the
   PPT is one content source among others, never a reason to refuse.
5. A retry of the same material is idempotent — take the reused result and
   continue from Step 2; do not re-parse. If the user wants the same PPT again
   on purpose, delete its imported pages first (`edit_deck` `delete`), then
   retry.
6. Want pages beyond the deck (quiz, interactive, extra slides)? Insert a stub
   with `edit_deck` `insert`, then `generate_scene` that new page only with its
   explicit `type` and `brief` — do not
   re-import the deck to get more pages.

If there is no `.pptx`, say so and stop. Do not extract a PDF/DOCX and pretend
it was a slide import.

Speaker notes may already have become speech actions. Treat them as **drafts**.
Do not TTS them yet; they are rewritten in Step 4 after you understand the
course.

## Step 2 — roster

If the import result says no roster exists, settle the cast in conversation and
call `set_roster`. Voices are needed later for
TTS, not for the inspection pass.

## Step 3 — inspect pages, then fix bad cases

`list_scenes` is the map. Then **inspect before you edit**.

### 3a. Read

`read_stage` every imported page at `path:/scenes/<order|id>`. Record, in your own notes:

- title vs first real heading;
- element inventory (overflow candidates, empty boxes, missing `src`);
- garbled text;
- whether imported speaker-notes speech exists and whether it actually
  teaches this page.

A deck of more than 20 pages: still `list_scenes` fully; `read_stage` the
cover, every section-looking page, and every page whose title/excerpt looks
thin, garbled, or like a dump. Do not skip a page that looks empty.

### 3b. Render when the tool exists

If `render_scene_preview` is registered, **use it**. A `read_stage detail:"tree"` inventory
cannot see overlap, clipping, or a table running off the canvas.

- First pass: preview every imported page you read with `read_stage`. Look at the
  PNG, then decide whether that page needs a fix.
- After a visual fix: preview that page again (look → edit → look). At most
  **two extra previews per page**.
- If the tool is **not** registered, say so in one short sentence and inspect
  from `read_stage` only. Do not invent a screenshot.

Do not call `render_scene_preview` on pages you have not read, and do not
preview quiz/interactive stubs you have not inserted yet.

### 3c. Fix only bad cases

**Load `pro-editing` first.** `read` its SKILL.md (the path is in
`<available_skills>`), then follow that skill's surgical loop for every
visual repair: `read_stage`, the smallest `patch_stage` / `edit_deck` op,
`render_scene_preview` look → edit → look. Stay in `pro-editing` until the
bad cases below are done. Do not skip the load and invent a parallel edit
style.

| Problem                                       | Tool                                                                                                                             |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Empty or garbage title                        | `edit_deck` `retitle` from the first real heading                                                                                |
| Overlap or overflow                           | `patch_stage` `set` on that element's `/content/canvas/.../left` / `top` / `width` / `height`, one number per op                  |
| Leftover empty boxes                          | `patch_stage` `delete_element`                                                                                                    |
| Broken or missing image                       | `patch_stage` `set` on `/content/canvas/elements/N/src`, only if you have a real replacement URL; otherwise leave it and mention it |
| Garbled text, leftover font-substitution junk | `read_stage detail:"source"`, then `patch_stage` `set` on that element's rich-text path                                           |

Rules:

- Keep the original visual language. Do not restyle the deck to "look more
  like OpenMAIC".
- Change only what is broken or unreadable.
- **Do not write or rewrite actions in this step.** Layout first.
- When the layout pass is done, return here for Step 4. Do not continue
  `pro-editing` into narration.

## Step 4 — understand the course, then write actions

Only after Step 3. You now have a page list, inventories, and (if available)
previews. Form a short course reading before touching actions:

- What is the course arguing or teaching, in order?
- Which pages are cover / section / content / recap?
- What should the teacher **say** on each page (not what the slide already
  prints)?
- Which element should be spotlighted while that line is spoken?

Then write playback actions with `generate_actions` **page by page, in order**
(it drafts the full action set from the page content and course context, and
synthesizes audio by default — reserve `patch_stage` on `/actions/...` + `generate_tts` for
line-level fixes afterwards):

- `insert_speech` / `set_speech`: one or a few teacher lines that teach this
  page. Do not read the slide aloud verbatim. Speaker notes are a draft to
  rewrite, not a script to keep if they are outline-speak or leftover PPT
  comments.
- `set_spotlight`: bind the line to the element it is about (`elementId`
  from `read_stage detail:"source"`). Skip spotlight when the page is a title-only cover.
- `delete` imported speech that does not teach.

Do **not** call `generate_scene` to "generate actions". That regenerates the
slide.

## Step 5 — TTS

After a page's actions are settled, `generate_tts` that page (default mode
fills missing `audioId` only). Reworded speech has no audio until this runs.

Before saying the import is ready to teach: every page that has speech must
have `audioId`. `read_stage detail:"source"` shows it.

## Step 6 — add quiz / interactive only on request

If the user did **not** ask for quiz, interactive, or extra pages, stop after
Step 5. One sentence is enough: they can ask to insert a quiz or an
interactive page next.

If they did ask:

1. Say which pages you will insert, where, and why — then do it.
2. `edit_deck` `insert` with `type=quiz` or `type=interactive` at the chosen
   `atOrder`. This creates an empty stub; it does not copy a PPT slide.
3. `generate_scene` **only that new page**, with the explicit page `type` and
   `brief` plus
   `materialFacts` taken from the surrounding imported slides. Never
   regenerate an imported slide in this step.
4. A new interactive page must have a real `widgetType` and a filled
   `widgetOutline`. A quiz must have real questions, answers, and analysis.
5. `generate_tts` the new page if it has narration.

Do not sprinkle quizzes through the deck "for engagement" when nobody asked.

## Closing

1. `list_scenes` — imported slides still in order, plus any pages you inserted.
2. Touched speech has `audioId`.
3. Tell the user in one or two sentences what was imported, what you fixed
   visually, and that narration is in. Do not dump a page-by-page changelog.

## Hard rules

- `import_pptx` is the source of visual truth. Replanning the imported deck is
  the wrong workflow for this skill.
- Inspect and repair **before** writing actions. Actions **after** you
  understand the course.
- `generate_scene` is allowed only for **newly inserted** quiz/interactive
  stubs, or when the user explicitly asked to rebuild one imported page.
- Do not extract the PPT with `extract_material` and teach from the text.
- Do not invent images, citations, or slide content that was not in the file.
- If import fails, report the tool error. Do not fall back to an AI rewrite
  unless the user then asks for that different path.