/stage-design

name: stage-design
title: "课堂设计"
description: The baseline method for building ONE stage — a single classroom — with this runtime. Covers how the plan is settled in conversation, the order the generation tools are called in, how the classroom roster is written, when narration has to be re-synthesized, and what must be true before a stage is called done. Load this before generating or rebuilding any stage from scratch, whatever its subject; it is the floor the topic skills build on, not an alternative to them.

Building one stage

A stage is one classroom: one settled plan, one roster, one deck of pages. This is how a stage is built here, whatever its subject.

A topic skill (`deep-interactive`, `vocational`, `deep-research`, `teacher-style-clone`, …) may shape what the stage contains — its structure, its page types, how scenes are named — and where one is active its instructions win on those questions. The sequence below is not one of those questions: it is the same under every topic skill. Read this one first, then the topic skill.

Nothing here applies to a stage that already has pages. A stage with persisted pages is edited, not built (see `pro-editing`).

The build sequence

Build a NEW stage only when there are no persisted pages yet. Then, in this order:

1. **Plan the stage in the conversation.** Propose the page plan yourself — each page with its `title`, `type` (`slide` / `quiz` / `interactive` / `pbl`) and `brief` (this page's teaching intent and content outline, the same information a planned outline slot used to carry) — in page order. Settle one design style for the whole course in the same plan: background treatment, palette with a role for each colour (title, accent, panels, text), type scale (title, heading and body sizes), where the title sits, and the recurring layout grammar (panel and card treatment, column patterns, spacing). Every slide is generated on its own and sees only its own call, so this style is what makes the pages one deck: decide it once, keep it fixed, and let only each page's layout vary with its content. Settle the plan with the user through `ask_user` before creating anything: there is no outline tool to plan with, so the plan is your words and their sign-off. Skip that confirmation round when the user already gave a complete page structure or explicitly asked you to go ahead directly — their message is the sign-off. A topic skill's structural constraints are a diagnostic the runtime checks against the real stage after each page; you decide how to act on it. 2. **`create_stage`** with the settled course title (pass the series folder's `folderId` when the stage is part of a series, so it is filed in the same call). From here on, pass the returned stageId to every stage tool. 3. **`set_roster`**, before any page is generated. Write the classroom the user settled: exactly one teacher, at least two agents in total, each with a concrete persona (2-3 sentences on personality and teaching/learning style, in the stage language) and a voice — call `list_voices` first and bind one of the returned `providerId::voiceId` pairs, or the exact pair `register_voice` returned for a cloned voice; omit the binding when no usable voice exists. Every page's content and narration is written for the roster that exists when the page is generated, so a roster settled late is a roster half the stage never saw. 4. **`generate_scene` for EACH settled page, in ascending order** — one page per call, never more. Pass the page's settled `title`, `type` and `brief` (plus `materialFacts` when the page's content comes from attached material); no planned outline is needed. For a `slide`, also pass `design`: the course style restated in full, then this page's own layout — what the learner must see at a glance, the regions with rough proportions, and which content sits where in what form (table, steps, cards, diagram, chart, formula). Keep content and look apart: `brief` and `materialFacts` carry what the page says, `design` only how it looks, referring to the content by role instead of repeating it. A `pbl` page is generated the same way and lands as a full PBL project (`projectV2`) from its brief; a failed generation reports an error and writes nothing. Each call is the durable checkpoint for its page: the page survives an interruption only once the call has returned. As soon as a page's `generate_scene` succeeds, call `generate_tts` on that page, then go on to the next page.

**First page first.** The user is waiting to see the classroom take shape, so get page 1 persisted as early as possible: once the stage and roster exist, generate page 1 before any work that page does not need. Research a page relies on comes before that page. Media is made just in time for the page that uses it: the images for page N are generated right before page N's `generate_scene`, never as a batch for the whole course before its first page exists. 5. **`list_scenes`** to verify every page you settled is actually persisted.

None of the planning steps is a place to stop: a turn ends when a page actually landed, when `ask_user` is waiting on the user, or when the stage is done by the check below. Reporting what you have planned, imported or confirmed leaves the user holding an empty deck.

When `generate_scene` fails

Track generation attempts by `stageId + order`. Changing the title or brief, or generating another page in between, does not reset the attempt.

• For `prompt-unavailable` or another deterministic failure, do not repeat the

same call.

• For `invalid-model-output`, change the brief without changing the settled

teaching intent, then retry once. Retry once for a clearly transient provider failure too.

• If that retry fails, do not call `generate_scene` again for that target during

this run. Leave the page unwritten, continue with lat