@wji.ai/cli 0.1.0 → 0.2.0

package/skill/short-drama/SKILL.md

@@ -0,0 +1,305 @@
+---
+name: short-drama
+description: Produce an AI short drama (短劇) on the WJI platform end to end — write it the way a commercial 短剧 is written (创作简报, 创作指引, 人物圣经, 分集目录 with 爽点 and 钩子, the 15-second hook and 30-second turns, 谈话+行动, the right 语体), adapt a story or novel into an outline, character / scene / prop bibles, per-episode scripts and storyboards, then generate the sheets, keyframes and video clips through the `wji` CLI, with data stored as workspace datasets and the work laid out on canvases (characters, scenes, one per episode). Every stage is gated by `scripts/short-drama.mjs validate`. Use whenever a task mentions short drama, 短劇 / 短剧, 分集 / 分镜 / 剧本 for AI video, or producing a serialised video story on WJI. Works together with the `wji` skill.
+---
+
+# Short drama on WJI
+
+Five stages, one project directory, one workspace. The **model writes the design fields**; the
+**script checks them** (`validate`), derives what can be derived (`seed`, `prompt`) and keeps the
+local ↔ WJI bindings (`manifest`, `bind`). Nothing is generated until its stage is green.
+
+```
+outline ──▶ characters ──▶ art ──▶ script (per episode) ──▶ storyboard (per episode)
+   │            │            │           │                        │
+ story/      character/   location/    story/                   shot/E01/  datasets
+ dataset     datasets +   prop/        screenplay               + E01 canvas: keyframes → video
+             `characters` datasets +   dataset
+             canvas       `scenes` canvas
+```
+
+`{baseDir}` = this directory. Script: `node {baseDir}/scripts/short-drama.mjs <cmd> …` (zero
+dependencies). Read `{baseDir}/reference/schema.md` before writing any JSON and
+`{baseDir}/reference/workspace-layout.md` before touching WJI. The `wji` skill governs every CLI
+call (auth, confirmations, spending policy, model choice) — this skill only says what to build.
+
+**How the drama is written** comes from `{baseDir}/reference/craft-story.md` (the 短剧 method:
+brief, three phases, 分集目录, 爽点 / 钩子 libraries, the episode formula, the character bible) and
+`{baseDir}/reference/dialogue-craft.md` (lines as action, 语体 rules, the polish pass). Read the
+first before stage 1 and the second before stage 4. The gates encode what those two can check.
+
+**Re-read the guideline.** The 创作指引 (`render guideline`) is the drama's top rule document.
+Print it before writing any character, any episode and any storyboard, and print the speakers'
+`render character` before writing their lines — a script that drifts from the guideline is wrong
+even when every gate is green. When the user changes a core requirement (genre, register, length,
+ending), change the guideline first, then the episodes.
+
+## Before anything else
+
+1. **Preflight WJI**: `wji auth whoami --json`, the version check from the `wji` skill,
+   `wji profile wallet` (a drama is many generations — know the balance).
+2. **Scan the message for `-auto`** (spending waiver, see the `wji` skill). Without it: one image
+   runs, video and batches ask first.
+3. **Ask the parameters once**, in one message: episodes × minutes per episode, genre, adapt
+   mode (原创 / 忠实 / 抽核 / 借壳), the 语体 (`register`: 粤语 / 大陆普通话 / 台湾国语 / 港式普通话 /
+   古装 / 年代 / 英文美式 / 英文英式 — it decides how the lines are written and the accent the video
+   model speaks), ratio (default 9:16). Offer the defaults you will use unless
+   told otherwise: `video: h3` (MiniMax H3 ref), `style: realistic`, **`references: sheets`** (no
+   storyboard images) and **`videoDuration: auto`**. Do not start Stage 1 without the first two.
+
+   **The video mode decides how the plot is cut up.** A segment is one video generation, so its
+   length is whatever the provider accepts — and that differs by a factor of two:
+
+   | `--video` | model | segment | images | voices | auto duration | prompt |
+   | --- | --- | --- | --- | --- | --- | --- |
+   | `h3` | `minimax-h3-ref` | **5–15 s** | 9 | 3 | ✗ — always `fixed` | English, keyframe-pinned |
+   | `seedance` | `seedance-2.5-ref` | **4–30 s** | 30 | 10 | ✓ | English, `@imageN` |
+   | `seedance2` | `seedance-2.0-ref` | **4–15 s** | 9 | 3 | ✓ | English, `@imageN` |
+   | `seedance2fast` | `seedance-2.0-fast-ref` | **4–15 s** | 9 | 3 | ✓ | English, `@imageN` |
+   | `wan` | `wan-3.0-ref` | **2–30 s** | 10 | 5 | ✓ | Chinese prose, **speaks the dialogue itself** |
+
+   All five take **whole seconds only**, and each has its own resolution tiers (h3: 480P / 768P /
+   2K / 4K — note there is no 720P; the Seedance pair is lowercase; wan: 480P / 720P / 1080P).
+   `validate` checks the spelling against the model. Pick the mode **before** the storyboard: the
+   same 90-second episode is 7 generations on a 15 s model and 3 on a 30 s one, and
+   `seed storyboard` computes that split for you. With `wan`, set `speechAccent` (e.g.
+   台湾口音国语) because the model speaks the lines.
+
+   **Style**: `photoreal` for a live-action drama, `realistic` for semi-realistic painterly,
+   `ghibli` for hand-painted anime. **References** (default `sheets`): the video node references
+   the character/scene sheets directly and no storyboard images are generated — fewer images to
+   pay for and approve, and continuity comes from the sheets. Choose `keyframes` (one generated
+   image per cut) only when a shot has to be composed exactly; h3 needs it for its keyframe-pinned
+   prompt. **Duration** (default `auto`): the model matches the clip to the prompt; `fixed` sends
+   `-d` = Σ cuts and is forced on models without an auto duration.
+
+   **The camera package** is `params.camera` — body, lens family and working stop, default
+   `ARRI ALEXA Mini LF` / `Zeiss Supreme Prime` / `T1.5`. Every shot prompt names it verbatim, so
+   the drama looks shot on one rig; a cut can override the focal and the stop. A look the user asks
+   for on top of that (大光圈, 背景虛化, 前景模糊…) goes in `lookPhrase`.
+4. **Locate or create the project directory** (the user's choice, else next to the source):
+   ```bash
+   node {baseDir}/scripts/short-drama.mjs init <dir> --title "<title>" --episodes N --minutes M --genre "<genre>" --register 台湾国语 [--adapt 抽核] [--ratio 9:16] [--video h3|seedance|seedance2|seedance2fast|wan] [--resolution 480P|…] [--accent "台湾口音国语"] [--style photoreal|realistic|ghibli] [--references sheets|keyframes] [--duration auto|fixed] [--look "<lens phrase>"] [--lang zh]
+   # params.camera (body / lens / aperture) is edited in project.json
+   ```
+   An existing `project.json` means a resumed run: `validate` and `manifest` tell you where it stands.
+5. **Workspace**: reuse the one bound in `project.json`; otherwise create it and bind the ids
+   (`wji ws create "<title>" -r <ratio>` → `wji ws use` → find the semantic
+   folders → `bind`). Details in `reference/workspace-layout.md`.
+
+## The loop every stage follows
+
+```
+write JSON → validate --stage <stage> → fix until green → render → sync datasets → build canvas → generate → bind ids
+```
+
+- **Validate before spending.** `validate` exits 1 with the failing gates; fix each one, re-run.
+  Never generate from a red stage.
+- **Sync = publish.** `render` produces the markdown for the dataset's `content.content`; the
+  entity JSON goes to `metadata.shortDrama`; prompts to `image_prompt` / `video_prompt` /
+  `audio_prompt` (a character's voice brief). Use
+  `wji fs set --merge …` (never `--content`), `--add-images` (never `--images` on an existing node).
+- **Bind immediately.** Every id `wji` returns goes into `project.json` / `episodes/E<nn>.json`
+  with `bind` before the next command. `manifest` lists what is still unbound; run it before creating
+  anything so a resumed run never duplicates.
+- **Look at what you generated.** `wji asset download <id> -o <dir>` and open the image before
+  approving a sheet or moving to the next segment. The reference-repo lesson: one wrong sheet
+  corrupts every shot after it.
+
+## Stage 1 — Outline
+
+Read `{baseDir}/reference/stage-outline.md`.
+
+1. **Brief first**: `outline.brief` — the six judgements (logline, audience, 爽点 engine, main
+   hook, the pressures on both sides, emotional line, promise). If the user gave one line, ask
+   the focusing questions; do not invent a genre.
+2. **Skeleton**: `outline.core/keep/cut/merge/risks`, `characters[]` (id/name/tier/role/arc/from),
+   `scenes[]` (id/name/primary/reusePlan), `props[]` (id/name/function/beatIds), `beats[]`,
+   `outline.structure` (golden / escalation / climax with episode ranges) and `outline.guideline`
+   (tone, intensity, dialogue style, visual style, limits, ≥ 3 forbidden, 3–5 priorities).
+   `validate --stage outline` will still fail on `episodes` — that is expected at this point; read
+   the other gates.
+3. **Sign-off ⛔**: show the user the brief, what was cut, who was merged, where the major beats
+   land (`cutNote` / `mergeNote`) and the guideline's priorities. Do not write episode synopses
+   before they agree — a wrong skeleton wastes every downstream stage.
+4. **Episodes** in batches of ≤10 — design before prose: `function` / `task` / `change` /
+   `satisfaction` / `hookType` (the 分集目录; episode 1 grabs, 2 proves the 爽点, 3 widens the line,
+   the finale settles), then `synopsis` / `hook` / `suspense` / ids / `crowdPlan` / `warnings`;
+   `validate --stage outline` until green.
+5. Sync: `render outline` → `story/` dataset (type `outline`, `viewMode=content`), bind
+   `wji.outlineDatasetId`; `render guideline` → its own `story/` dataset `<title> 创作指引`
+   (type `outline`), bind `wji.guidelineDatasetId`.
+
+## Stage 2 — Characters
+
+Read `{baseDir}/reference/stage-characters.md`.
+
+1. Fill `oneLiner`, `profile` (with the 关系网 in `relationships`: surface / real / power / secret),
+   **`bible`** (剧情功能, 一句话人物钩子, Want vs Need, 核心误信, 核心矛盾, 受压反应, `speech` — and for leads
+   the wound, past choices, forbidden / mustFace and the arc; `craft-story.md` §7), `identityEn`,
+   `image` (portrait prompt, negative, 16:9 sheet prompt, tags) and `voice` for every character;
+   `validate --stage characters`. Two of those exist purely so a video prompt can talk about the
+   person: **`identityEn`** is the name-free way to refer to them (`the woman in her mid thirties
+   in headphones`) and **`voice.videoDirection`** is one English clause on how they speak, pasted
+   beside every line they say in every clip — written from `bible.speech`.
+2. Sync each character to a `character/` dataset (description = oneLiner, content = `render
+   character C01`, `image_prompt` = the sheet prompt, `audio_prompt` = `prompt voice C01`,
+   metadata = the JSON).
+3. `characters` canvas (`wji canvas create characters` once): per character a title node, a
+   **headshot** image node (1:1, portrait prompt), a **sheet** image node (16:9, `--from` the headshot,
+   sheet prompt prefixed with `@image1 is the face to match`), and a **voice** audio node
+   (`seed-audio-1.0`, `--from` the headshot — the model reads the face and invents a voice for it;
+   the composed prompt asks for a dry voice, because the same model also makes rooms, scores and
+   sound effects — that is what its stage-5 soundtrack nodes are for;
+   `prompt voice C01` composes the text: a parenthetical carrying age, identity, personality,
+   timbre, pitch, pace, accent and emotion, then the acted line).
+   Recipes in `reference/canvas-recipes.md`.
+4. Generate headshots first (single images run without asking; a batch of them is a batch — quote
+   the total), inspect, then sheets and voices from the approved headshots. Listen to each voice.
+   Attach all three assets — the asset list takes audio too:
+   `fs set <dataset> --add-images <headshot> <sheet> <voice> --icon <headshot> --set primaryAudio=<voice>`; bind node and asset ids.
+
+## Stage 3 — Art (scenes + props)
+
+Read `{baseDir}/reference/stage-art.md`.
+
+1. Scenes: `summary`, 3–5 `anchors`, `lighting` states derived from the episodes the scene appears
+   in, empty-scene `image.*`; variants via `variantOf` + `changes`. Props (only narrative ones):
+   `scale`, `anchors`, `states`, white-background `image.*`. `validate --stage art`.
+2. Sync to `location/` and `prop/` datasets; `scenes` canvas: one sheet node per scene / prop
+   (16:9), variant and state nodes `--from` the parent sheet. Generate, inspect (no people in a
+   scene, no hands on a prop, one space across all panels), attach as `icon`, bind.
+
+## Stage 4 — Script (per episode, batches of ≤3)
+
+Read `{baseDir}/reference/stage-script.md`.
+
+1. `render guideline` and the speakers' `render character` first. Then `seed script --ep N`
+   writes `episodes/E0N.json` with target seconds, hook/cliff, claimed beats, the episode design
+   (`function` / `task` / `change` / `hookType`, `satisfactionBeat` to set) and a `seedNote`
+   (synopsis, the 爽点 to realise, register, guideline priorities, every speaker's `bible.speech`,
+   ids, previous cliff, budget). Fill `scenes[].flow` — action beats and line beats alternating,
+   **common actions only**, hook image inside the first 3 beats and by 15 s, a `turn: true` beat
+   at least every 30 s, the 爽点 on an action (`satisfactionBeat`), cliff as the last beat; lines
+   in the register, from each speaker's `speech` (`dialogue-craft.md`). Delete `seedNote` when done.
+2. `validate --stage script --ep N` — duration math, line length, speakers, hook window, the
+   rhythm, the design, filmability, upstream ids; the register gate only advises. Over budget: cut
+   actions first; under: add conflict, not small talk. When dialogue is the weakness, run the
+   polish pass: `render dialogue --ep N` → fill the 逐句校对表 → apply → re-validate.
+3. Sync: `render script --ep N` (the 短剧 episode format with the 创作自检 table) → `story/` dataset
+   `E0N 剧本` (type `screenplay`, `viewMode=content`); bind `wji.screenplayDatasetId` with `--ep N`.
+
+## Stage 5 — Storyboard (per episode)
+
+Read `{baseDir}/reference/stage-storyboard.md`.
+
+Every cut is a set-up, so besides its beats and framing it carries the **lens** (`focal`, or let the
+shot size pick it), the **key light relative to the camera** (`light.direction` from the vocabulary
+plus `light.note` saying what it picks out, what fills the shadow side and how it changes over the
+cut) and the **foreground** to throw out of focus. All three are gated and all three go into the
+prompt, alongside the camera package and each speaker's delivery.
+
+**And every cut is a shot with a job** — read `{baseDir}/reference/craft-shots.md` and
+`{baseDir}/reference/craft-motion.md` before the first storyboard. In both reference modes a cut
+carries its `purpose` (kind + what changes), its three framing axes (`angle`, `height`, `axisSide`
+against the segment's declared `axis`), its `start` / `end` boundaries (positions, facing, gaze,
+hands, held props per person — the next cut and the next segment begin where these end), its
+`motion` (cue → one visible action → landing) and `cameraNote` (a lock-off says what still moves, a
+move says why and where it ends); the segment carries its `sound` (ambience chained across the
+scene, sfx per cut, music intent) and the 爽点 / cliff scenes a `visualPlan`. `frame` stays the
+frozen start instant. `prompt segment` composes all of it into the prompt, and the prompt is
+delivery text: no ids, files or notes, subtitles off, the other person's lips closed while one
+speaks (H3), everyone bound by `@imageK` in their own shot (sheets).
+
+**Everything the node references is addressed by its label, everywhere it applies.** WJI numbers
+connected references per type, each series from 1: `@image1…` the sheets or keyframes, `@video1…`
+the previous clip when `params.videoReferences: previous` is on (continuity of grade and camera
+language — opt-in), `@audio1…` the voice samples of whoever speaks. The legend says what each one
+is, and then each label is used where it belongs — `@imageK` in the shot that anchors on it,
+`@videoK` in the sentence saying what to carry over, and **every line a character speaks names
+their `@audioN`**, at each line rather than once in the legend, because the model picks a voice per
+line. All of it is gated. `prompt segment` prints the references in the exact order the video node
+must be connected: pictures, then clips, then voices.
+
+1. `seed storyboard --ep N` adds `storyboard.plan`, `storyboard.seedScenes` (every beat with its
+   computed seconds, an axis hint per scene) and `storyboard.visualPlans` (the worksheet for the
+   爽点 scene and the cliff scene — fill it before cutting them). **Follow the plan**: it reads the chosen model's duration range and says how
+   many segments each scene needs and how long each should be — the split follows the model, not
+   the story's own rhythm, because a segment is one generation and cannot outlast what the provider
+   accepts. Then cut the episode into those **segments** (one scene each,
+   `minSegmentSeconds`–`maxSegmentSeconds`, whole seconds) of **cuts** (2–5 s, claiming consecutive
+   beats). Per cut: `purpose`, `angle` / `height` / `axisSide`, `start` (first cut) and `end`,
+   `motion`, `cameraNote`, light / foreground / `background`, then the `frame` (the start instant);
+   per segment `axis` and `sound`. Then the segment `prompt` — take the skeleton from
+   `prompt <project> segment E0N-01` and fill in the descriptions. Delete `seedScenes` and `plan`
+   when done. `validate --stage storyboard --ep N` (the advisory `storyboard-advice` only notes).
+2. Sync: shot folder `shot/E0N`, one `shot` dataset per segment (`video_prompt` = the prompt,
+   content = `render segment E0N-01` — the 分镜 with one `### SHOT k` block per cut).
+3. `E0N` canvas (`wji canvas create E0N`): display nodes for every sheet the episode uses
+   (`canvas add image --asset …`, keyed in `wji.displayNodes`). Then, in the default `sheets` mode,
+   the video node per segment straight from those display nodes (`--from` them in the order
+   `prompt segment` prints the legend — the order is the legend, so a reconnect must redo the whole
+   set). With `references: keyframes`, first a keyframe node per cut (`--from` the display nodes,
+   ratio = `params.ratio`), then the video node `--from` the keyframes in cut order.
+   Either way the video node takes the mode's model, `--resolution params.videoResolution`,
+   `--prompt-file`, and `-d` = Σ cut seconds **only in `fixed` duration mode** — in `auto` leave
+   `-d` off and let the model match the clip to the prompt.
+4. In `sheets` mode go straight to generating the clips. With `keyframes`, **generate the first
+   segment's keyframes only**, download, check: same world as the scene sheet, same faces as the
+   character sheets, the right shot size, nobody extra in frame. Regenerate what is off, then
+   continue segment by segment. Keyframes for one segment are a batch (quote the total); each video
+   is a video (ask, or `-auto`). Stay under the queue cap (`wji` skill *Limits*): submit up to the
+   cap, `wji history get <id> --wait`, continue.
+5. **Soundtrack node** per segment (`params.audioTrack`, default `bed`): `prompt audio E0N-01`
+   derives a Seed Audio prompt from `segment.sound` — timecoded `[start s:end s]` ambience, sfx on
+   their cuts, music that enters / swells / ducks / falls silent at the cues you wrote on
+   `sound.music.cues` — and `canvas add audio -m seed-audio-1.0 --prompt-file …` makes it (~0.15
+   credits a minute, no `--from`; `--full` adds the lines in the connected `@Audio1..3` voices).
+   Seed Audio is the voice-sample model, but it is an audio-scene generator: one prompt is a whole
+   track. Attach the asset to the shot dataset; bind `wji.nodes.track` / `wji.assets.track`.
+6. After each clip: `fs set <shot dataset> --add-images <keyframes…> <track> --set primaryVideo=<clip>`;
+   bind asset ids. `manifest --ep N` must come back clean before you call the episode done.
+
+- **A failed generation is not always a bad prompt.** `wan-3.0-ref` rejections from DashScope's
+  content filter (`DataInspectionFailed`) charge nothing and are partly random — retry the same node
+  8–12 times, then **shorten** the prompt (that, not rewording, is what clears a stuck one).
+
+## Reporting
+
+One line per stage when you stop: what exists (counts), what was generated and the credits
+actually charged (the `credits` line of each result, not the estimate), what `manifest` still
+lists, and any gate you had to fix. If a generation failed, say which and why — never resubmit a
+node whose status is `generating`.
+
+## Rules specific to this skill
+
+- **The user signs off the brief + outline skeleton and the first segment's keyframes.**
+  Everything else runs on the `wji` spending table.
+- **The guideline outranks a good idea.** A single episode's idea that conflicts with
+  `outline.guideline` is either dropped or the guideline is changed with the user first.
+- **Ids are stable.** Never renumber `C01` / `S01` / `P01` / `B01` / `E01-01` after a dataset or node
+  is bound; add new ids at the end.
+- **Prompts never carry names.** Faces come from the sheet references; `validate` rejects a name
+  or alias in any English prompt.
+- **The voice sample is a reference, not a deliverable.** 3–5 s, acted, generated from the
+  headshot; it connects to later video nodes as `@audio1` to hold the timbre the way the sheet
+  holds the face.
+- **In `wan` mode the dialogue audio also comes from the video model** — the video model speaks the lines from the segment
+  prompt's 音频 line. Fill the `voice` fields anyway; they are the register, and the gate wants them.
+- **One style for the whole drama** (`params.style`). Changing it later means regenerating every
+  sheet — say so before doing it.
+- **Keyframes at `params.ratio`, sheets at 16:9.** A 9:16 drama still gets landscape sheets.
+- **Don't fight a gate by loosening `params`** unless the user asks; the thresholds encode
+  production limits (H3 15 s, 2–5 s attention span, one breath per line).
+
+## Self-test
+
+```bash
+node {baseDir}/scripts/selftest.mjs      # no model calls, every gate has a breaking case
+node {baseDir}/scripts/short-drama.mjs validate {baseDir}/examples/night-shift
+```
+
+`examples/night-shift` — 《夜班便利店》, 3 × 1 min, three characters, two scenes, one prop, episode 1
+scripted and storyboarded in H3 mode — passes every gate (the register gate is advisory and clean)
+and is the reference for the shape of every field, the brief, the guideline and the bibles
+included.