@wji.ai/cli 0.9.1 → 0.9.2

package/skill/short-drama/reference/prompt-audit.mjs

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+/**
+ * prompt-audit.mjs — reference-binding proofreader for AI short-drama video prompts.
+ *
+ * It does NOT rewrite the prompt. It reads the prompt as TEXT, compares it with what the
+ * project says must be on screen (cuts → characters / props / scene), and reports every place
+ * where the model could mistake which @imageN is a person, which is the room, which is a prop,
+ * or where a shot simply never mentions the reference it depends on.
+ *
+ * usage:
+ *   node prompt-audit.mjs --project <dir> --ep 1 --segment E01-02 --prompt <file> [--json]
+ *
+ * exit code: 0 clean (warnings allowed), 1 errors found.
+ */
+
+import { readFileSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+
+// ── args ────────────────────────────────────────────────────────────────────
+const argv = process.argv.slice(2);
+const arg = (name, fallback = null) => {
+  const i = argv.indexOf(`--${name}`);
+  return i >= 0 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : fallback;
+};
+const PROJECT = arg('project');
+const EP = Number(arg('ep', 1));
+const SEGMENT = arg('segment');
+const PROMPT_FILE = arg('prompt');
+const AS_JSON = argv.includes('--json');
+if (!PROJECT || !SEGMENT || !PROMPT_FILE) {
+  console.error('usage: node prompt-audit.mjs --project <dir> --ep 1 --segment E01-02 --prompt <file> [--json]');
+  process.exit(2);
+}
+
+const project = JSON.parse(readFileSync(resolve(PROJECT, 'project.json'), 'utf8'));
+const epFile = join(resolve(PROJECT, 'episodes'), `E${String(EP).padStart(2, '0')}.json`);
+const episode = JSON.parse(readFileSync(epFile, 'utf8'));
+const prompt = readFileSync(resolve(PROMPT_FILE), 'utf8')
+  .split('\n')
+  .filter((l) => !l.startsWith('#'))          // drop `prompt` command's header comment line
+  .join('\n')
+  .trim();
+
+const seg = (episode.storyboard?.segments || []).find((s) => s.id === SEGMENT);
+if (!seg) {
+  console.error(`no segment ${SEGMENT} in ${epFile}`);
+  process.exit(2);
+}
+const scene = (episode.scenes || [])[Number(seg.sceneIndex) - 1] || {};
+const params = project.params || {};
+const charById = (id) => (project.characters || []).find((c) => c.id === id);
+const sceneById = (id) => (project.scenes || []).find((s) => s.id === id);
+const propById = (id) => (project.props || []).find((p) => p.id === id);
+
+// ── what the project says the segment needs ────────────────────────────────
+/** Reference plan in connection order, the same way the engine derives it (env → people → props → voices). */
+function planOf(seg) {
+  const imgs = [];
+  if (Array.isArray(seg.refOverride) && seg.refOverride.length) {
+    for (const r of seg.refOverride) imgs.push({ entity: r.entity, asset: r.asset || 'sheet', declared: r.role || null });
+  } else {
+    if (scene.sceneId) {
+      imgs.push({ entity: scene.sceneId, asset: 'sheet', declared: 'scene' });
+      const se = sceneById(scene.sceneId);
+      if (scene.lighting && se?.wji?.assets?.lighting?.[scene.lighting]) imgs.push({ entity: scene.sceneId, asset: `lighting:${scene.lighting}`, declared: 'lighting' });
+    }
+    const seen = new Set();
+    for (const c of seg.cuts || []) for (const id of c.characters || []) if (!seen.has(id)) { seen.add(id); imgs.push({ entity: id, asset: 'sheet', declared: 'character' }); }
+    for (const c of seg.cuts || []) for (const id of c.props || []) if (!seen.has(id)) { seen.add(id); imgs.push({ entity: id, asset: 'sheet', declared: 'prop' }); }
+  }
+  imgs.forEach((r, i) => (r.label = `@image${i + 1}`));
+  const speakers = [];
+  for (const c of seg.cuts || []) for (const id of c.characters || []) if (id !== 'VO' && !speakers.includes(id)) speakers.push(id);
+  const voices = speakers.map((id, i) => ({ entity: id, label: `@audio${i + 1}`, kind: 'audio' }));
+  return { imgs, voices };
+}
+
+const roleOfEntity = (id, asset, declared) => {
+  if (declared) return declared;
+  if (/^lighting:/.test(String(asset))) return 'lighting';
+  if (/^S/i.test(id)) return 'scene';
+  if (/^P/i.test(id)) return 'prop';
+  if (/^C/i.test(id)) return 'character';
+  return 'unknown';
+};
+
+const plan = planOf(seg);
+for (const r of plan.imgs) r.role = roleOfEntity(r.entity, r.asset, r.declared);
+
+// ── identity tokens: how a legend can prove WHICH person a picture is ──────
+const CN_STOP = new Set(['男的', '女的', '一個', '一个', 'the', 'and', 'with', 'her', 'his', 'man', 'woman']);
+function tokensOf(ch) {
+  const t = new Set();
+  const add = (s) => {
+    for (const w of String(s || '').toLowerCase().split(/[^a-z0-9\u4e00-\u9fff]+/)) if (w.length > 2 && !CN_STOP.has(w)) t.add(w);
+    for (const run of String(s || '').match(/[\u4e00-\u9fff]+/g) || []) {
+      if (run.length <= 3) t.add(run);
+      for (let i = 0; i + 1 < run.length && run.length > 3; i++) t.add(run.slice(i, i + 2));
+      for (let i = 0; i + 2 < run.length; i++) t.add(run.slice(i, i + 3));
+    }
+  };
+  add(ch.identityEn);
+  add(ch.profile?.appearance);
+  add(ch.profile?.identity);
+  const g = ch.profile?.gender;
+  if (g) t.add(g === '男' ? '男' : '女');
+  return t;
+}
+
+// ── prompt parsing ─────────────────────────────────────────────────────────
+const SHOT_RE = /(?:^|\n)[ \t]*(?:镜头|鏡頭|Shot)[ \t]*(\d+)/g;
+const shotMarks = [];
+for (let m; (m = SHOT_RE.exec(prompt)); ) shotMarks.push({ k: Number(m[1]), at: m.index + (m[0].startsWith('\n') ? 1 : 0) });
+const firstShotAt = shotMarks.length ? shotMarks[0].at : prompt.length;
+const head = prompt.slice(0, firstShotAt);              // legend + global blocks
+const shots = shotMarks.map((s, i) => ({
+  k: s.k,
+  text: prompt.slice(s.at, i + 1 < shotMarks.length ? shotMarks[i + 1].at : prompt.length),
+}));
+const legend = head.split('\n').filter((l) => /@image\d+/.test(l)).join('\n');
+
+const IMG_RE = /@image(\d+)/g;
+const labelPositions = new Map();       // label -> { first, count, span }
+const legendLines = head.split('\n').filter((l) => /^@image\d+\b/.test(l.trim()));
+{
+  const all = [...head.matchAll(IMG_RE)];
+  for (let i = 0; i < all.length; i++) {
+    const label = `@image${all[i][1]}`;
+    const from = all[i].index;
+    const to = i + 1 < all.length ? all[i + 1].index : head.length;
+    const prev = labelPositions.get(label);
+    const mine = legendLines.filter((l) => l.trim().startsWith(label));
+    const lines = mine.length;
+    const span = lines ? mine[0].trim().slice(label.length) : head.slice(from, to);
+    labelPositions.set(label, { first: from, count: (prev?.count || 0) + 1, lines, span });
+  }
+}
+
+const countIn = (text, label) => (text.match(new RegExp(`${label}(?!\\d)`, 'g')) || []).length;
+
+// ── checks ─────────────────────────────────────────────────────────────────
+const issues = [];
+const add = (level, code, msg) => issues.push({ level, code, msg });
+const ROLE_EN = /\b(scene|environment|character|person|prop|lighting|light reference|moment|action reference|style)\b/i;
+const ROLE_ZH = /(場景|场景|環境|环境|人物|角色|道具|光影|光線|光线|瞬間|瞬间|撞擊|撞击|動作參考|动作参考|風格|风格|車廂|车厢)/;
+const BIND_EN = /\b(match|as in|from|same as|use)\b/i;
+const BIND_ZH = /(照|參照|参照|跟|用|依|係|是)/;
+const NEG_EN = /\b(not|only|do not|don't)\b/i;
+const NEG_ZH = /(唔照|不要照|唔好照|只照|只取|唔要|不要|只係|只是|只)/;
+const hasCJK = (t) => /[\u4e00-\u9fff]/.test(String(t || ''));
+const ROLE_WORDS = { test: (t) => (hasCJK(t) ? ROLE_ZH : ROLE_EN).test(t) };
+const BIND_WORDS = { test: (t) => (hasCJK(t) ? BIND_ZH : BIND_EN).test(t) };
+const NEG_WORDS = { test: (t) => (hasCJK(t) ? NEG_ZH : NEG_EN).test(t) };
+
+// R1 legend exists
+if (!/@image\d+/.test(head)) add('error', 'R1-legend-missing', 'prompt 首段冇 @imageN legend：模型唔知邊張圖係咩');
+
+// R2 every planned image is in the legend, exactly once
+for (const r of plan.imgs) {
+  const p = labelPositions.get(r.label);
+  if (!p) add('error', 'R2-legend-missing-label', `${r.label}（${r.role}：${r.entity}）已接但 legend 冇提`);
+  else if (p.lines > 1) add('warn', 'R2-legend-duplicate', `${r.label} 有 ${p.lines} 條 legend 行 — 一張圖一行，重覆會令模型重新解讀角色`);
+  else if (p.lines === 0) add('warn', 'R2-legend-inline', `${r.label} 夾在一句裡面，冇自己一行 — 一張圖一行，「@image2、@image3 是人物圖」係模型撈亂嘅溫床`);
+}
+
+// R3 prompt uses labels the plan does not have (extra hand-connected refs)
+const maxPlanned = plan.imgs.length;
+for (const label of labelPositions.keys()) {
+  const n = Number(label.slice(6));
+  if (n > maxPlanned) add('warn', 'R3-extra-ref', `${label} 唔在項目派生嘅引用次序（只有 ${maxPlanned} 張圖）— 額外接嘅圖要寫入 segment.refOverride，否則重跑 prompt 就對唔上`);
+}
+
+// R4 role words per label + R5 negative instruction on non-character refs
+for (const r of plan.imgs) {
+  const p = labelPositions.get(r.label);
+  if (!p) continue;
+  if (!ROLE_WORDS.test(p.span)) add('warn', 'R4-role-unsaid', `${r.label} 冇講明係咩角色（場景／人物／道具／光影／瞬間）— 模型只會當「一張參考圖」`);
+  if (r.role !== 'character' && !NEG_WORDS.test(p.span)) add('warn', 'R5-no-negative', `${r.label}（${r.role}）冇寫「只照…唔照…」：非人物圖一定要講明唔好抄佢嘅構圖／人物，唔係模型會連人一齊抄`);
+}
+
+// R6 legend must let the model tell one person from another
+const segChars = [];
+for (const c of seg.cuts || []) for (const id of c.characters || []) if (id !== 'VO' && !segChars.includes(id)) segChars.push(id);
+const charImgs = plan.imgs.filter((r) => r.role === 'character');
+if (segChars.length >= 2 && charImgs.length >= 2) {
+  const total = new Map();
+  for (const id of segChars) for (const t of tokensOf(charById(id) || {})) total.set(t, (total.get(t) || 0) + 1);
+  const assigned = new Map();
+  for (const r of charImgs) {
+    const span = (labelPositions.get(r.label)?.span || '').toLowerCase();
+    let best = null, bestScore = 0;
+    for (const id of segChars) {
+      if (assigned.has(id)) continue;
+      let score = 0;
+      for (const t of tokensOf(charById(id) || {})) if (span.includes(t) && (total.get(t) || 0) <= 1) score += 2;
+      const g = charById(id)?.profile?.gender;
+      if (g && span.includes(g) && segChars.filter((x) => charById(x)?.profile?.gender === g).length === 1) score += 1;
+      if (score > bestScore) { best = id; bestScore = score; }
+    }
+    if (best && bestScore >= 2) assigned.set(best, r.label);
+  }
+  if (assigned.size < segChars.length) {
+    const missing = segChars.filter((id) => !assigned.has(id)).map((id) => charById(id)?.name || id);
+    add('error', 'R6-identity-unresolvable', `legend 冇寫到分辨特徵，無法對應邊張圖係邊個人（對唔到：${missing.join('、')}）。` +
+      `人物圖必須逐張寫「係邊個」——性別、年齡、髮型、衣著各一句；寫成「@image2、@image3 是人物參考圖」模型就會互換面孔`);
+  }
+  // two people described in one legend sentence, with no per-picture role
+  for (const line of legendLines) {
+    const labels = line.match(/@image\d+/g) || [];
+    const people = labels.filter((l) => charImgs.some((r) => r.label === l));
+    if (people.length >= 2 && !/not its|never its|只照|不要照/i.test(line.replace(/@image\d+/g, ''))) {
+      add('warn', 'R6b-shared-clause', `legend 一句寫咗幾個人（${people.join('、')}）又冇逐個講明 — 一張圖一句，否則模型會互換`);
+    }
+  }
+}
+
+// R7 per-shot binding: person / prop / scene
+const cuts = seg.cuts || [];
+if (shots.length !== cuts.length) add('warn', 'R0-shot-count', `prompt 有 ${shots.length} 個鏡頭，分鏡有 ${cuts.length} 個 cut — 冇法逐鏡核對（人名／道具綁定會漏）`);
+const deriveOrder = (() => {
+  // when the legend is ambiguous, fall back to the engine's derivation order to still give per-shot advice
+  const m = new Map();
+  for (const r of plan.imgs) if (r.role === 'character') m.set(r.entity, r.label);
+  return m;
+})();
+const unboundChar = new Map();   // entity -> {label, shots: []}
+for (let i = 0; i < cuts.length && i < shots.length; i++) {
+  const c = cuts[i];
+  const s = shots[i];
+  for (const id of c.characters || []) {
+    const label = deriveOrder.get(id);
+    if (!label) continue;
+    if (!countIn(s.text, label)) {
+      if (!unboundChar.has(id)) unboundChar.set(id, { label, shots: [] });
+      unboundChar.get(id).shots.push(s.k);
+    }
+  }
+  for (const id of c.props || []) {
+    const label = plan.imgs.find((r) => r.entity === id)?.label;
+    if (label && !countIn(s.text, label)) add('error', 'R7-prop', `鏡頭 ${s.k}：道具 ${propById(id)?.name || id} 在畫面內，但鏡頭文冇 ${label} — 道具外觀會由模型自創`);
+  }
+  if (i === 0) {
+    const sceneLabel = plan.imgs.find((r) => r.role === 'scene')?.label;
+    if (sceneLabel && !countIn(head + '\n' + shots.map((x) => x.text).join('\n'), sceneLabel) && !countIn(prompt.slice(firstShotAt), sceneLabel)) {
+      add('warn', 'R7-scene', `${sceneLabel} 只在 legend 出現，冇任何鏡頭講明照佢嘅空間／材質 — 每個 segment 至少講一次「整段都在 ${sceneLabel} 的空間裡」`);
+    }
+  }
+}
+
+for (const [id, bad] of unboundChar) {
+  add('error', 'R7-char', `${charById(id)?.name || id} 在鏡頭 ${bad.shots.join('、')} 畫面內，但鏡頭文冇 ${bad.label}` +
+    ` — 模型會沿用上一鏡嘅樣或者自己編。每個有佢嘅鏡頭都要寫一次 ${bad.label}`);
+}
+// R8 every image ref is actually used somewhere outside the legend (people are covered by R7)
+const bodyText = prompt.slice(firstShotAt);
+for (const r of plan.imgs) {
+  if (r.role === 'character' || r.role === 'scene') continue;
+  if (!countIn(bodyText, r.label)) add('error', 'R8-unused-ref', `${r.label}（${r.role}：${r.entity}）接咗但鏡頭文一次都冇用 — 等於冇參考`);
+}
+
+// R9 dialogue still carries its voice label (mirrors the engine's own rule)
+const dialogues = [];
+for (const c of cuts) {
+  for (let b = (c.beats?.[0] || 1) - 1; b <= (c.beats?.[1] || 1) - 1; b++) {
+    const beat = (scene.flow || [])[b];
+    if (beat?.speaker) dialogues.push({ speaker: beat.speaker, line: beat.line });
+  }
+}
+const norm = (t) => String(t).replace(/[…⋯]/g, '...').replace(/[“”「」『』"]/g, '').replace(/\s+/g, '');
+const flat = norm(prompt);
+for (const l of dialogues) {
+  const needle = norm(l.line);
+  const at = flat.indexOf(needle);
+  if (at < 0) { add('error', 'R9-dialogue-missing', `台詞「${l.line}」逐字唔見（引擎逐字對，標點差異都算唔同）`); continue; }
+  const around = flat.slice(Math.max(0, at - 160), at + needle.length + 60);
+  if (!/@audio\d/.test(around)) add('error', 'R9-voice-unbound', `台詞「${l.line}」附近冇 @audioN — 模型會用預設聲`);
+}
+
+// R10 hygiene: no names, subtitles off
+for (const ch of project.characters || []) if (ch.name && prompt.includes(ch.name)) add('warn', 'R10-name-leak', `prompt 出現角色名「${ch.name}」（引擎 prompt-hygiene 會當錯；描述性名字可以留，但要預期被擋）`);
+if (!params.subtitles && !/(全程无字幕|no subtitles)/i.test(prompt)) add('warn', 'R10-subtitles', 'prompt 冇寫「無字幕／no subtitles」');
+
+// R11 ambiguity sweep: a whole sentence that names several pictures without saying what each is for
+for (const s of shots) {
+  for (const sentence of s.text.split(/[。；;\n]/)) {
+    const body = sentence.replace(/^\s*(?:Shot|镜头|鏡頭)\s*\d+\s*\([^)]*\)\s*:?/, '');
+    const labels = body.match(/@image\d+/g) || [];
+    if (labels.length >= 2 && !BIND_WORDS.test(body.replace(/@image\d+/g, '')) && body.length > 40) {
+      add('warn', 'R11-ambiguous-clause', `鏡頭 ${s.k}「${body.trim().slice(0, 44)}…」一句有 ${labels.length} 張圖但冇逐張講用途 — 拆開寫`);
+    }
+  }
+}
+
+// ── report ─────────────────────────────────────────────────────────────────
+const errors = issues.filter((x) => x.level === 'error');
+const warns = issues.filter((x) => x.level === 'warn');
+if (AS_JSON) {
+  console.log(JSON.stringify({ segment: SEGMENT, shots: shots.length, cuts: cuts.length, plan: plan.imgs, issues }, null, 2));
+} else {
+  console.log(`\n== prompt-audit · ${SEGMENT} ==`);
+  console.log(`refs (derived order): ${plan.imgs.map((r) => `${r.label}=${r.role}:${r.entity}`).join('  ')}`);
+  console.log(`shots in prompt: ${shots.length} · cuts in storyboard: ${cuts.length} · images declared: ${labelPositions.size}\n`);
+  for (const x of errors) console.log(`❌ [${x.code}] ${x.msg}`);
+  for (const x of warns) console.log(`⚠️  [${x.code}] ${x.msg}`);
+  if (!issues.length) console.log('✅ 冇發現引用綁定問題');
+  console.log(`\n${errors.length} error(s), ${warns.length} warning(s)`);
+}
+process.exit(errors.length ? 1 : 0);

package/skill/short-drama/reference/reference-binding.md

@@ -0,0 +1,84 @@
+# Reference binding — 參考圖綁定
+
+A video prompt is **one string** read by a model that has never seen the storyboard, the project
+or the canvas. It cannot tell `@image2` from `@image3`, cannot tell the room from a prop, and
+defaults to whatever it saw in the previous shot for anything the shot does not name. So the
+picture plan has to be written twice: once as a legend that says **what each picture is**, and once
+inside every shot that depends on it.
+
+Gate: `ref-binding` (stage `storyboard`, sheets mode). Proofreader for text that is not in the
+project file: `prompt-audit.mjs` (shipped in `reference/`).
+
+## The six roles — and what may not be copied from each
+
+| Role | Legend says | Take | Explicitly NOT take |
+| --- | --- | --- | --- |
+| 場景 environment | `@image1` 係邊個場景 | 佈局、材質、磨損、比例 | 人物（場景圖本身冇人） |
+| 光影 lighting | `@image5` 係光影參考 | 光比、反差、色溫、光源位置 | 構圖、人物、衣著 |
+| 人物 character | `@image2` 係邊個人 | 面容、髮型、衣著 | 其他鏡頭嘅表情／姿勢 |
+| 道具 prop | `@image4` 係邊件道具 | 外形、材質、尺寸、標記 | 枱面、背景、手 |
+| 瞬間 moment | `@image6` 係「撞擊一瞬間」 | 打光方向、反差、剪影形狀 | 背景細節、其他鏡頭嘅走位 |
+| 風格 style | `@image7` 係風格板 | 質感、顆粒、調色 | 題材、人物、構圖 |
+
+Two consequences the model actually obeys:
+
+- **一張圖一行。** 兩張人物圖寫在同一句（`@image2、@image3 是人物參考圖`）＝ 兩張圖冇分別 ＝ 面孔互換。
+- **唔係人物嘅圖，一定要寫「唔照」。** 光影圖／瞬間圖如果唔寫「只照光比，不要照它的構圖與人物」，
+  模型會連圖裡面嘅人一齊抄落去。
+
+## Legend — good and bad
+
+```
+✗ @image2、@image3 是人物參考圖，照他們的面容、髮型與衣著
+✗ @image4 is the character sheet of one person in this segment — match face, hair and clothes exactly
+```
+
+```
+✓ @image2 是女主角三視圖（二十五六歲，齊蔭 bob 頭、oversized 黑 tee、白波鞋）：只照面容、髮型、衣著
+✓ @image3 是男主角三視圖（二十七八歲，豎起黑髮、小鬍子、白 tee）：只照面容、髮型、衣著
+✓ @image1 是車廂場景（右軚電動車、近黑、中控屏微光）：只照空間、材質、磨損，場景圖裡沒有人
+✓ @image4 是白衣女鬼服裝與妝容參考：濕透白袍、長濕黑髮、赤腳
+✓ @image5 是車廂光影參考：只照光比、反差、色溫、光源位置，不要照它的構圖與人物
+✓ @image6 是「車撞女鬼一瞬間」：只照打光方向、反差與剪影形狀，不要照它的背景
+✓ @image7 是風格板：只照質感、顆粒、調色
+```
+
+Every character line must carry at least two facts from the character bible (age / gender / hair /
+clothes), because that is the only thing that makes two sheets distinguishable.
+
+## Shot binding — the shot names what it depends on
+
+```
+✓ 鏡頭 1（…）：@image2 坐直指住屏幕，@image3 單手扶軚伸手去點…
+✓ 鏡頭 4（…）：@image4 走出馬路正中間（照 @image6 的剪影與打光）…
+✓ 鏡頭 8（…）：@image4 的白臉貼喺玻璃外；屏幕上的導航界面照 @image5 的 UI
+✓ 整段都在 @image1 的空間裡：佈局、材質與舊痕不變，不要重新設計場景。
+```
+
+- 每個有角色／道具嘅鏡頭，**逐個 label 寫一次**；唔係寫喺 legend 就當夠。
+- 場景 label 每段講一次就夠（「整段都在 @image1 的空間裡」）。
+- Handheld / 行車感 / 鏡頭語言呢類**全段共通**嘅指令，用獨立一段寫，唔好混入逐鏡描述。
+- Hand-written production prompts: run `prompt-audit.mjs` before generation; it reports unbound
+  people and props per shot, indistinguishable legend lines, unused pictures, and refs that are not
+  in the derived plan (so the canvas will renumber them).
+
+```bash
+node reference/prompt-audit.mjs --project <project> --ep 1 --segment E01-02 --prompt prompt.txt
+```
+
+## Ref budget
+
+- **≤ 4 pictures per segment** unless every extra picture has a role from the table above.
+- More than 3 people in one shot → every person in that shot is named; a group sheet still needs
+  the individual labels if faces must be right.
+- The engine caps a segment by model (`minimax-h3-ref` 9, `seedance-2.5-ref` 30, `wan-3.0-ref` 10);
+  the gate `ref-binding` now also fails a sheets segment over the model's cap.
+
+## Checklist before generating
+
+1. 每張圖有一行 legend，寫明係邊個／邊件／邊度／邊種參考。
+2. 兩張人物圖唔會讀起來一樣（年齡、性別、髮型、衣著至少兩樣）。
+3. 非人物圖有「唔照」句。
+4. 場景每段講一次；每個出場人物、每件道具喺自己嘅鏡頭有 label。
+5. 額外接嘅圖（光影／瞬間／風格）寫入 `segment.refOverride`，否則 canvas 一接線全部編號會移。
+6. `$SD validate --stage storyboard` 綠；或者 `prompt-audit.mjs` 零 error。

package/skill/short-drama/reference/schema.md

@@ -65,7 +65,7 @@ All commands accept either the directory or the `project.json` path.
 | `maxVideoRefs` / `maxAudioRefs` | per mode | how many clip / voice references the model takes; set them lower to tighten, never higher |
 | `lookPhraseZh` | empty | the same look phrase in the drama's language, gated in a **Chinese** prompt (`wan`) where the English `lookPhrase` would be both out of place and extra length for the content filter to judge |
 | `speechLeadSeconds` | 0.5 | added to a cut's dialogue seconds before the fit check — the mouth opens after the cut starts; also where a line starts in the `full` soundtrack prompt |
-| `audioTrack` | `post` | where the soundtrack is made. **`post`** (the default): the clips carry dialogue, ambience and in-picture sfx but **no music** (`No music.` / `non_diegetic_music: N/A` / `无配乐`) and no `post: true` sfx — music and sound design cannot carry across separately generated segments, so they are made once over the **edited episode**, on its timecode (`prompt score E01`, then `mix-over-video.md`); no per-segment audio node. `bed` (ambience + sfx + timed music, no voices) / `full` (the bed plus every line in the connected `@Audio1..3` voices — at most three speakers): a Seed Audio node per segment, music in the clip prompt. `none`: no soundtrack work |
+| `audioTrack` | `post` | where the soundtrack is made. **`post`** (the default): the clips carry dialogue, ambience and in-picture sfx but **no music** (`No music.` / `non_diegetic_music: N/A` / `无配乐`) and no `post: true` sfx — music and sound design cannot carry across separately generated segments, so they are made once over the **edited episode**, on its timecode (`prompt score E01`, then `../short-drama-sound/reference/mix-over-video.md`); no per-segment audio node. `bed` (ambience + sfx + timed music, no voices) / `full` (the bed plus every line in the connected `@Audio1..3` voices — at most three speakers): a Seed Audio node per segment, music in the clip prompt. `none`: no soundtrack work |
 | `foregroundLevel` | `medium`; `high` for 唯美 / 美感优先 (`composition: art-first`, `cinematography: sweet-romance` or `costume-idol`, a genre naming 唯美 or 美感) | how often a cut shoots past a foreground, measured across the episode: `low` up to 25 % of the cuts, `medium` 25–50 %, `high` 50 % or more (gate `photography`; `--foreground` at init). Which cuts: `stage-storyboard.md` |
 | `scoreFps` | 24 | frame rate `prompt score` writes SMPTE `HH:MM:SS:FF` at (`--fps` overrides); set it to the edit's real fps |
 | `subtitles` | false | `true` drops the subtitles-off sentence requirement from the prompts |
@@ -87,6 +87,7 @@ All commands accept either the directory or the `project.json` path.
 | `turnSeconds` | 30 | the longest stretch allowed between turn points — the hook, every beat marked `turn: true`, the 爽点 and the cliff |
 | `maxConsecutiveLines` | 3 | line beats in a row without an action beat between them |
 | `minActionRatio` | 0.35 | action beats ÷ line beats over an episode with ≥ 5 lines (谈话+行动) |
+| `dialogueReview` | `required` | `required`: every episode's lines are reviewed against the `w-film-dialogue-editor` guide of their 语体 before the storyboard (gate `dialogue-review`); `off`: no review — only when the user asks |
 | `maxLineWords` / `maxNameCallsPerScene` | 20 / 2 | English registers only: words per line, and how often another character is addressed by name in one scene (advisory) |
 | `charsPerSecond` / `actionSeconds` | 4.5 / 2.5 | script duration math: a line takes `nonWhitespaceChars ÷ charsPerSecond` s, an action beat takes `actionSeconds` |
 | `tolerance` | 0.15 | ±15 % for episode duration gates |
@@ -203,7 +204,7 @@ id or list) and `gag` (`setup` / `build` / `punchline`) with `runningGag`.
 ```json
 {
   "id": "S01", "name": "便利店店内", "primary": true, "reusePlan": "",
-  "summary": "设计意图…", "anchors": [{ "name": "闪烁的关东煮灯箱", "desc": "…" }],
+  "summary": "设计意图…", "condition": "lived-in", "conditionReason": "这家店每晚都在营业，是用旧了而不是残破", "anchors": [{ "name": "闪烁的关东煮灯箱", "desc": "…" }],
   "lighting": [{ "state": "凌晨冷白光", "prompt": "…" }],
   "image": { "prompt": "…", "negativePrompt": "…", "sheet": "…", "tags": [] },
   "variantOf": "", "changes": "",
@@ -217,13 +218,20 @@ paintable and checkable), `lighting` (≥1, prompts in `imagePromptLang`, derive
 episodes it appears in), `image.*` (`imagePromptLang`, **empty scene — negative prompt
 must ban people**), `variantOf` + `changes` for variants of a parent scene.
 `wji.nodes.lighting` / `wji.assets.lighting` are keyed by lighting `state`.
+`condition` is `new`, `lived-in` or `worn`, and `conditionReason` says why the story gives it
+that condition — the same two fields are required on every prop. Realism is materials, light and
+detail, not wear. A luxury interior, a set just built, a prop the organisers have just issued,
+and every national or regional flag are `new` and accurate. Anchors follow the condition: do not
+add peeling paint, rust or fading by default. Only `worn` may ban `brand-new` or `showroom-clean`
+in `negativePrompt`. A `new` asset fails when an anchor or prompt says worn, rust, faded, chipped,
+torn, frayed, peeling, stain, 殘舊, 生鏽, 褪色 or 剝落.
 
 ### props[]
 
 ```json
 {
   "id": "P01", "name": "旧监控硬盘", "function": "全剧悬念核心：里面到底录了什么",
-  "beatIds": ["B02"], "scale": "handheld", "summary": "…",
+  "beatIds": ["B02"], "scale": "handheld", "summary": "…", "condition": "worn", "conditionReason": "三年前的硬盘，标签撕掉、接口生锈",
   "anchors": [{ "name": "…", "desc": "…" }], "states": [{ "state": "封在防静电袋里", "prompt": "…" }],
   "relatedScenes": ["S01"], "carriedBy": ["林小夏"],
   "image": { "prompt": "…", "negativePrompt": "…", "sheet": "…", "tags": [] },
@@ -295,6 +303,7 @@ prompt bans hands**). At most `thresholds.maxProps` (8).
 | `flow[].turn` | `true` on a beat that brings new information, an obstacle, a counter or a choice; the `rhythm` gate measures hook → turns → 爽点 → cliff against `turnSeconds` |
 | `scenes[].sceneId` / `lighting` / `characters` / `props` | must exist in `project.json`; `lighting` must be a state of that scene |
 | `flow[]` | alternating **action beats** `{action}` (narrative, one thing per beat, **common actions only**, no quotes) and **line beats** `{speaker, line, delivery?}`; `speaker` ∈ scene `characters` or `VO` (an off-screen voice: it gets no `@audio` reference, the prompt calls it off-screen and keeps every visible mouth closed while it speaks); `line` ≤ `maxLineChars` non-whitespace characters; `delivery` names nobody when the video prompt carries it (a Chinese `wan` prompt, or an English delivery) — gate `beat-flow` |
+| `dialogueReview` | the 对白校对 record (gate `dialogue-review`, required unless `params.dialogueReview: off`), seeded by `seed dialogue`: `{ level: 轻修 \| 中修 \| 重修, guides: ["lang-zh-hk.md", …] (every speaker's 语体 guide of `w-film-dialogue-editor`), diagnosis: { goal, conflict, subtext, voice, rhythm }, rows: [{ scene, beat, speaker, original, issue, revised, reason, note, delivery? }] (one per line beat, 1-based positions; `revised` must equal the script's line — `apply dialogue` writes it; `note` a playable action), selfCheck: [{ item, ok, note }] (the guide's 自检清单, ≥ 3) }` |
 
 Duration: `Σ lines (chars ÷ charsPerSecond) + Σ actions × actionSeconds`.
 
@@ -322,7 +331,7 @@ Duration: `Σ lines (chars ÷ charsPerSecond) + Σ actions × actionSeconds`.
 | `motion` | `{ trigger, action, result }` — cue, one visible state chain, landing (or `hold`); English unless the prompt language is Chinese; no names, no inferred states, ≤ 3 hand verbs — gate `motion` |
 | `cameraNote` | `{ motivation, trigger, path, endFraming }` on any move (`motivation` ∈ `reveal / pressure / alignment / relationship / transition / stillness`), `{ hold }` on a `Static Shot` — gate `motion` |
 | `frame` | English prompt for the moment: composition, this moment's positions and poses, the size phrase, the style's `framePhrase` (`photorealistic cinematic film still` / `cinematic film still` / `hand-painted anime film still`), **and verbatim** the camera phrase (`shot on an ARRI ALEXA Mini LF with a Zeiss Supreme Prime 75mm at T1.5`), the light-direction phrase and the foreground, and under a `cinematography` preset also its `framePhrase` and the `light.source`; **no names** — identity comes from the sheet references |
-| `prompt` | the video prompt, shape by `params.video` (below); gate `prompt-hygiene` (no `…`, no ids / paths / notes, subtitles off unless `params.subtitles`, H3 lips-closed clause, sheets-mode `@imageK` per shot) |
+| `prompt` | the video prompt, shape by `params.video` (below); gate `prompt-hygiene` (no `…`, no ids / paths / notes, subtitles off unless `params.subtitles`, H3 lips-closed clause, sheets-mode `@imageK` per shot) and gate `ref-binding` (one legend line per picture saying **what** it is — a person by age / hair / clothes from the bible, a room by its name, a prop by its name; every non-person picture carries a *take only … / not its composition or its people* clause; every prop and person is bound by its label again inside its own shot; the room is named once per segment; no connected picture unused; sheets-mode picture cap) |
 | `segments[].axis` | `{ between: [C01, C02], workingSide, screenLeft, screenRight }`, required when two or more people appear in the segment |
 | `segments[].grammar` / `exceptions` | `grammar` (a string or an array) says how the segment is cut — `drama` · `action` · `faceslap` · `comedy`; missing, it is `params.grammar`; the old `action: true` means `action`. Each grammar's rules apply (gates `grammar`, `action`, `faceslap`, `comedy`; advisory `action-advice`, `grammar-advice`) and the prompt carries each grammar's line. `exceptions: [{ rule, reason }]` waives one rule for this segment when the user asks — rules `open-wide` `one-move` `impact-reaction` `no-graphic` `reveal-insert` `reaction-chain` `punchline-reaction` `setup-first` (the old `actionExceptions` still works) |
 | `cuts[].idle` | sheets mode: `{ <id>: "shifts her weight" }`, a small motion in place for a person other than the one carrying the action, or `"still"` (breathing and blinking only). In a cut with two or more visible people, all but one need one (gate `idle-motion`) |
@@ -330,7 +339,7 @@ Duration: `Σ lines (chars ÷ charsPerSecond) + Σ actions × actionSeconds`.
 | `cuts[].ots` | the person whose shoulder is near the lens in an over-the-shoulder; `characters` holds both people; counts as a foreground; that person needs no `eyeline` |
 | `segments[].sound` | `{ ambience, sfx: [{ cut, event, post? }], music }` — ambience identical across a scene's segments; `music` is `N/A`, an intent string, or `{ intent, cues: [{ at: <cut number \| "10.5s">, do: enter \| swell \| duck \| drop \| silence \| out, note }] }` — gate `sound`. An sfx with `post: true` is **sound design outside the story world** (stinger, riser, whoosh, impact hit, reverse cymbal) — never in the clip prompt, made over the edit. In `audioTrack: post` the `music` is the **spotting intent** for the episode score: it never enters the clip, and `prompt score E01` lays it, the post sfx, the lines and the scene beds on the episode timeline. In `bed` / `full`, `prompt audio E01-01` derives the segment's Seed Audio soundtrack prompt from it (timecoded `[start s:end s]` ambience / sfx / music, plus the lines with `--full`) — gate `audio-track` |
 | `wji.assets.edit` / `wji.assets.mix` (episode) | `audioTrack: post` only — the locked edit of the episode (clips cut together, no music) and the final mixed episode (edit + score + sound design). `manifest` asks for the edit once every clip is bound, then for the mix |
-| `segments[].refOverride[]` | optional — the Director pins this segment's **picture** references instead of the derived set (environment, people, props): `[{ entity, asset?: "sheet" \| "headshot" \| "lighting:<state>", faceOf?, why?, use?, zh? }]` in the order they will be connected (`@image1…`). `faceOf: "C01"` says this picture supplies that character's face, so their lines bind to it even when a body sheet of theirs comes later. Voices and the previous clip are still appended after the pictures. An empty array means "derived" |
+| `segments[].refOverride[]` | optional — the Director pins this segment's **picture** references instead of the derived set (environment, people, props): `[{ entity, asset?: "sheet" \| "headshot" \| "lighting:<state>", role?, faceOf?, why?, take?, takeZh?, notTake?, use?, zh? }]` in the order they will be connected (`@image1…`). `role` is `environment` · `lighting` · `character` · `prop` · `moment` · `style`; `take` / `notTake` write the legend line for a reference that is not simply the place, a person or the prop — e.g. `{ role: "lighting", take: "only its light ratios, contrast and colour temperature", notTake: "its composition and its people" }` renders as *take only what it is for, not its composition and its people* (gate `ref-binding` requires the negative clause on every non-person picture). `use` / `zh` override the whole line. `faceOf: "C01"` says this picture supplies that character's face, so their lines bind to it even when a body sheet of theirs comes later. Voices and the previous clip are still appended after the pictures. An empty array means "derived" |
 | `storyboard.visualPlans[]` | `{ sceneIndex, turn, alignment, pressure, progression, rhythm, landing, sound }` for the 爽点 scene and the cliff scene (seeded) — gate `visual-plan` |
 | `props[].textPolicy` | optional `{ mode: readable \| symbolic \| blank, text }` — gate `text-policy` |
 

package/skill/short-drama/reference/stage-characters.md

@@ -40,7 +40,7 @@ relationship carries a `secret` — that is where the reversals come from.
 
 **`bible.speech` is the source of the voice.** `voice.pace` / `videoDirection` and every line's
 `delivery` are written from `rhythm`, `silence` and `forbiddenWords`; `seed script` prints them in
-the `seedNote` and `render dialogue` puts them beside each line for the polish pass.
+the `seedNote` and `render dialogue` puts them beside each line for the dialogue review.
 
 ## Image prompts (English, always)
 

package/skill/short-drama/reference/stage-script.md

@@ -19,6 +19,20 @@ budget. **Before writing: `render guideline`, then the scene bibles (anchors, li
 the speakers' `render character` — the bible's `speech` is where the lines come from** (see
 `dialogue-craft.md`). Delete `seedNote` when the scenes are written.
 
+`seedNote.dialogue` points at the user's dialogue skill, **`w-film-dialogue-editor`** (installed
+beside this one): the revision framework, the language guide of every 语体 in the episode
+(`lang-zh-hk.md`, `lang-zh-cn.md`, `lang-zh-tw.md`, `lang-zh-hk-mandarin.md`, `lang-zh-period.md`,
+`lang-en.md`) and, per speaker, the corpus query for someone of their age:
+
+```bash
+node <skills>/w-film-dialogue-editor/scripts/ref.mjs --lang zh-hk list --age young --limit 30
+node <skills>/w-film-dialogue-editor/scripts/ref.mjs --lang zh-hk search 搞掂       # one word
+```
+
+Read the guide before writing the first line and pull phrasing from the corpus — particles, slang,
+swearing levels and trade talk come from there, never from memory. The corpus is a vocabulary of
+real usage, not lines to paste: a line still grows from the person and the moment.
+
 ## Hard rules (all gated)
 
 1. **The duration budget is the wall.** Lines cost `chars ÷ 4.5` s, action beats 2.5 s; the
@@ -95,13 +109,46 @@ scene rather than hopping four.
 | omniscience | lines explain everything | move information into action and delivery |
 | flat ending | ends calm | last beat becomes the cliff, even just a whistle |
 
-## Polish (`render dialogue --ep N`)
+## Dialogue review — required after the script (`dialogue-review`)
+
+A script is not done when its structural gates are green: every line is then reviewed against the
+语体 guide, the way `w-film-dialogue-editor` reviews a scene, and the review is kept in the episode.
+The storyboard stage cannot start until it is (`validate --stage storyboard` runs the script gates
+too). `params.dialogueReview: off` skips it — only when the user asks.
+
+```bash
+node {baseDir}/scripts/short-drama.mjs seed  <project> dialogue --ep 1   # dialogueReview: one row per line + the guides to read
+node {baseDir}/scripts/short-drama.mjs apply <project> dialogue --ep 1   # write the revised lines (and deliveries) into the flow
+node {baseDir}/scripts/short-drama.mjs validate <project> --stage script --ep 1
+node {baseDir}/scripts/short-drama.mjs render <project> dialogue --ep 1  # the filled 对白校对 table
+```
 
-When the user asks for a polish, when the dialogue is the visible weakness, or when the register
-gate keeps noting the same scene: `render dialogue --ep 1` prints the 逐句校对表 (原句 / 问题 / 修改句 /
-修改理由 / 导演／演员提示) with each speaker's speech rules in the last column. Fill it per
-`dialogue-craft.md` §3, apply the changes to the flow, re-validate, and append the filled table to
-the screenplay dataset under `## 对白校对`.
+1. **Read** the framework (`references/dialogue_revision_framework.md`) and the guide of every 语体
+   `seed dialogue` prints; query the corpus for each speaker it lists.
+2. **Diagnose the episode first** (`diagnosis`: `goal` 场面目标, `conflict` 主要冲突, `subtext` 潜台词核心,
+   `voice` 角色声音问题, `rhythm` 节奏问题) and pick `level` 轻修 / 中修 / 重修. A scene with no goal,
+   obstacle or turn is a script problem — fix the beats, not the words.
+3. **Every row**: `issue` (the problem, or `无：<why it stands>`), `revised` (the new line, or the
+   same line), `reason` when it changed, `note` — the 导演／演员提示 as a playable action
+   ("你不是解释，你是在逼对方认错"), never a mood (自然一点 / 生气 are refused). A row may set
+   `delivery` to replace the beat's parenthetical.
+4. **`selfCheck`**: the guide's 自检清单, item by item (`{ item, ok, note }`, at least three); an
+   item that fails says why it stands or the lines are fixed. `lang-zh-hk.md` has no section called
+   自检: for 粤语 the checklist is its §九 (书面中文 → 港式粤语 and the 三个硬指标) plus the skill's
+   `SKILL.md` 品质检查.
+5. `apply dialogue`, then re-validate — a shorter or longer line moves the duration and the dialogue
+   fit downstream.
+
+Editing a line later reopens it: the gate compares every row's `revised` with the script, so a
+changed line fails until it is reviewed again. `seed dialogue` re-run keeps the rows of unchanged
+lines and opens only the moved ones (`--force` resets them all). Cutting or adding a line is done in
+the flow first, then re-seed.
+
+The gate checks: a review exists, the level, all five diagnosis fields, the guide of every speaker's
+语体 listed in `guides`, one row per line and none for a beat that is not a line, the revision
+applied, an issue on every row, a reason on every change, a playable note on every row, and the
+self-check. `render dialogue` prints the filled table — append it to the screenplay dataset under
+`## 对白校对`; `render script`'s 创作自检 gains the row 对白是否已按语体 guide 逐句校对.
 
 ## Sync
 
@@ -115,7 +162,7 @@ wji fs set <id> --merge content=@/tmp/E01-script.md --merge viewMode=content --m
 ## Gates
 
 `script-shape` · `beat-flow` · `duration` · `hook-cliff` · `beats-claimed` · `script-design` ·
-`rhythm` · `filmable` · `dialogue-register` (advisory).
+`rhythm` · `filmable` · `dialogue-review` · `dialogue-register` (advisory).
 
 `render script` writes the reference's episode format — `△（from-to秒）` action lines with the
 seconds derived, `角色（delivery）：line`, `【爽点标记】` after the 爽点, `【钩子标记】` at the end — and