Add Stage2 prompt assembler with word-budget truncation (T7)

buildStage2Prompt() renders MVCP M.15's confirmed one-step six-section template and enforces the two dynamic risks M.15.1 flagged: caps appearanceDescriptor/garmentDescriptor at ~40 words each, and truncates motionDescriptor if it alone would push detailed_description past H6's 500-word cap (the only placeholder that lands in that section). Also fixes the footwear-drift the S1 spike found (model self-selected shoes when the prompt didn't constrain them) — pins footwear to <Picture 1> in both subject_definitions and retention_analysis, and says <Picture 2> doesn't affect it. Propagated the same fix into the M.15 template in the MVCP doc so the doc and the code don't drift. Tests check the mechanical M.15.1 items that are checkable from the rendered string (H1/H5/H6/H9) plus the truncation behavior and the footwear fix. H13 (reference counts) is a submission-payload concern, covered by T8's tests instead.

Add Stage2 prompt assembler with word-budget truncation (T7)
buildStage2Prompt() renders MVCP M.15's confirmed one-step six-section template and enforces the two dynamic risks M.15.1 flagged: caps appearanceDescriptor/garmentDescriptor at ~40 words each, and truncates motionDescriptor if it alone would push detailed_description past H6's 500-word cap (the only placeholder that lands in that section). Also fixes the footwear-drift the S1 spike found (model self-selected shoes when the prompt didn't constrain them) — pins footwear to <Picture 1> in both subject_definitions and retention_analysis, and says <Picture 2> doesn't affect it. Propagated the same fix into the M.15 template in the MVCP doc so the doc and the code don't drift. Tests check the mechanical M.15.1 items that are checkable from the rendered string (H1/H5/H6/H9) plus the truncation behavior and the footwear fix. H13 (reference counts) is a submission-payload concern, covered by T8's tests instead.
yibo
1 parent 2cc989c9
Showing 3 changed files with 165 additions and 10 deletions
docs/todo/dressup-dance-room-mvcp.md
prompt-template.js
prompt-template.test.js
@@ -280,18 +280,19 @@ erDiagram
 `spike/s1-s2-s4-2026-09-02/RESULTS.md`），原来为兜底两步法保留的
 `<Picture 1>`=合成图版本已删除，不再维护两份模板。
  
-⚠️ **实测中发现的一个副作用**：产出视频里角色的鞋子是模型自己选的（本次
-测试自作主张配了黑色短靴），prompt 里没提鞋子这条约束。跟
-`CODEX-IMAGEGEN.md` 记录的 Stage1 图片编辑"鞋子自作主张"是同一类问题——
-**正式模板应在 `detailed_description` 或 `retention_analysis` 里显式规定
-鞋子处理方式**（沿用人物图的鞋、还是随衣服图搭配、还是不入镜），避免同一
-角色不同视频里鞋子不一致。下面的模板尚未加入这条修正，留给实现时补上。
+⚠️ **实测中发现的一个副作用，已在下面的模板里修正（T7，2026-09-02）**：
+产出视频里角色的鞋子原本是模型自己选的（S1 实测自作主张配了黑色短靴），
+prompt 里没提鞋子这条约束。跟 `CODEX-IMAGEGEN.md` 记录的 Stage1 图片编辑
+"鞋子自作主张"是同一类问题——**规则定为"沿用人物图 `<Picture 1>` 的鞋，
+`<Picture 2>` 衣服图不影响鞋子"**，已写进 `subject_definitions`/
+`retention_analysis` 两段（各加一句，不占 `detailed_description` 的词数
+预算）。
  
 ```
 subject_definitions:
 <Subject 1> is the young woman whose visual identity is defined by <Picture 1>: {{appearanceDescriptor}}. Preserve her face, hairstyle, and body exactly as shown; only her outfit, pose, motion, and framing change in the target video.
-<Picture 1> is the character reference frame for <Subject 1>, showing her face, hairstyle, and body in a neutral standing pose, wearing a neutral outfit that does not appear in the target video.
-<Picture 2> is the garment reference image: {{garmentDescriptor}}, laid flat with no person wearing it. Only its garment attributes (silhouette, color, fabric, trim, cut) transfer onto <Subject 1>; no other content of this image appears in the target video.
+<Picture 1> is the character reference frame for <Subject 1>, showing her face, hairstyle, and body in a neutral standing pose, wearing a neutral outfit that does not appear in the target video; her footwear as shown here is retained unchanged in the target video.
+<Picture 2> is the garment reference image: {{garmentDescriptor}}, laid flat with no person wearing it. Only its garment attributes (silhouette, color, fabric, trim, cut) transfer onto <Subject 1>; no other content of this image appears in the target video, and it does not affect her footwear.
 <Video 1> is the reference choreography clip. It defines the dance structure, phrasing, and camera rhythm that the target video follows; it is not a visual identity source, and none of its performer, background, or imagery appears in the target video.
 <Audio 1> is the background music track carried on <Video 1>, reused verbatim as the music bed of the target video. It contains no speech.
  
@@ -299,8 +300,8 @@ summary:
 [reference generation + attribute transfer + audio reuse] The target video shows <Subject 1>, now wearing the outfit transferred from <Picture 2>, performing {{motionDescriptor}} in a vertical studio setting, following the pacing and camera rhythm established in <Video 1>, with the music of <Audio 1> reused as its track.
  
 retention_analysis:
-<Subject 1> (appears in [Shot 1]): fully_preserved - her face, hairstyle, and body are retained unchanged throughout; her outfit changes to the garment shown in <Picture 2>.
-<Picture 1>: fully_preserved - it supplies the face, hairstyle, and body of <Subject 1> and the opening framing of the shot.
+<Subject 1> (appears in [Shot 1]): fully_preserved - her face, hairstyle, and body are retained unchanged throughout; her outfit changes to the garment shown in <Picture 2>, her footwear stays as shown in <Picture 1>.
+<Picture 1>: fully_preserved - it supplies the face, hairstyle, body, and footwear of <Subject 1> and the opening framing of the shot.
 <Picture 2>: attribute_transfer - only the garment's silhouette, color, fabric, and trim transfer onto <Subject 1>; the image itself does not appear.
 <Video 1>: weak_reference - only the choreography phrasing and the camera rhythm are referenced; no performer, background, or imagery from it is retained.
 <Audio 1>: fully_copy - the music track is reused verbatim as the non-diegetic music bed.
+// Stage2 six-section prompt assembler (dev-plan.md T7; template source of
+// truth: docs/todo/dressup-dance-room-mvcp.md M.15, one-step version
+// confirmed by the S1 spike). Includes the footwear fix M.15 flagged as
+// still outstanding ("her footwear... is retained unchanged" / "does not
+// affect her footwear") so the same "shoes self-selected" drift the S1
+// spike hit doesn't recur.
+const MAX_DESCRIPTOR_WORDS = 40; // ~2-3 concrete features, per docs/h3skill.md's own guidance
+const DETAILED_DESCRIPTION_MAX_WORDS = 500; // H6
+
+function words(text) {
+  return text.trim().split(/\s+/).filter(Boolean);
+}
+
+function truncateWords(text, maxWords) {
+  const w = words(text);
+  return w.length <= maxWords ? text.trim() : w.slice(0, maxWords).join(" ");
+}
+
+function wordCount(text) {
+  return words(text).length;
+}
+
+function extractSection(prompt, name, nextName) {
+  const re = new RegExp(`^${name}:\\n([\\s\\S]*?)\\n\\n${nextName}:`, "m");
+  const match = prompt.match(re);
+  return match ? match[1] : "";
+}
+
+function render({ appearanceDescriptor, garmentDescriptor, motionDescriptor }) {
+  return `subject_definitions:
+<Subject 1> is the young woman whose visual identity is defined by <Picture 1>: ${appearanceDescriptor}. Preserve her face, hairstyle, and body exactly as shown; only her outfit, pose, motion, and framing change in the target video.
+<Picture 1> is the character reference frame for <Subject 1>, showing her face, hairstyle, and body in a neutral standing pose, wearing a neutral outfit that does not appear in the target video; her footwear as shown here is retained unchanged in the target video.
+<Picture 2> is the garment reference image: ${garmentDescriptor}, laid flat with no person wearing it. Only its garment attributes (silhouette, color, fabric, trim, cut) transfer onto <Subject 1>; no other content of this image appears in the target video, and it does not affect her footwear.
+<Video 1> is the reference choreography clip. It defines the dance structure, phrasing, and camera rhythm that the target video follows; it is not a visual identity source, and none of its performer, background, or imagery appears in the target video.
+<Audio 1> is the background music track carried on <Video 1>, reused verbatim as the music bed of the target video. It contains no speech.
+
+summary:
+[reference generation + attribute transfer + audio reuse] The target video shows <Subject 1>, now wearing the outfit transferred from <Picture 2>, performing ${motionDescriptor} in a vertical studio setting, following the pacing and camera rhythm established in <Video 1>, with the music of <Audio 1> reused as its track.
+
+retention_analysis:
+<Subject 1> (appears in [Shot 1]): fully_preserved - her face, hairstyle, and body are retained unchanged throughout; her outfit changes to the garment shown in <Picture 2>, her footwear stays as shown in <Picture 1>.
+<Picture 1>: fully_preserved - it supplies the face, hairstyle, body, and footwear of <Subject 1> and the opening framing of the shot.
+<Picture 2>: attribute_transfer - only the garment's silhouette, color, fabric, and trim transfer onto <Subject 1>; the image itself does not appear.
+<Video 1>: weak_reference - only the choreography phrasing and the camera rhythm are referenced; no performer, background, or imagery from it is retained.
+<Audio 1>: fully_copy - the music track is reused verbatim as the non-diegetic music bed.
+
+detailed_description:
+A vibrant, mobile-first vertical dance video with warm, glossy studio lighting, saturated color, and a clean contemporary look sustained from the first frame to the last. [Shot 1] The shot begins from <Picture 1>, with <Subject 1> now wearing the outfit transferred from <Picture 2>. She stands centered in a medium-full vertical frame against a softly lit seamless backdrop that falls off into gentle shadow toward the edges. A warm key light sits slightly camera-left, a cooler rim light separates her shoulders and hair from the background, and a soft fill keeps her face evenly exposed. She begins in a relaxed neutral stance, weight settled on her back foot, hands loose at her sides, chin level with the lens. On the first musical accent she starts ${motionDescriptor}, and the routine unfolds continuously from there with no cut. Her weight transfers smoothly from foot to foot on the beat, hips leading each transfer and shoulders following a fraction behind, so the movement reads as one connected chain rather than a series of separate poses. Her arms trace clean, unhurried arcs that extend fully at the peak of each phrase and soften on the release, wrists relaxed and fingers naturally extended. Between phrases she adds small directional changes: a quarter turn away from the lens and back, a step that closes distance with the camera, a shift of gaze that returns to the lens on the downbeat. The camera holds a Static Shot through the opening beats, then performs a slow Push In with small amplitude at slow speed, tightening from medium-full to medium while keeping her head and hands inside the frame at every point of the routine. Her expression stays confident and playful, with a light smile and eyes that meet the lens at the end of each phrase. The fabric of the transferred outfit swings and settles naturally with each step, turn, and arm extension, and her hair carries the momentum of her head movement half a beat behind it. The pacing, phrasing, and camera rhythm follow the structure established in <Video 1>: the routine builds energy through the middle of the clip, reaches its widest and fastest movement around the two-thirds point, then settles back toward stillness. The closing beats return her to a stance, framing, and lighting that closely match her opening position, so the clip loops cleanly for repeated live playback. No text, graphics, watermarks, or overlays appear anywhere in the frame at any point.
+
+overall_soundscape:
+Soft ambient room tone of an enclosed studio sits under the music, with faint fabric rustle as <Subject 1> moves and light rhythmic footfall on the floor as her weight transfers. No speech, no crowd, and no off-screen sound events occur at any point.
+
+non_diegetic_music:
+An upbeat instrumental track drives the routine from the first frame to the last; its tempo, instrumentation, and dynamics are copied verbatim from <Audio 1>. Its accents align with the weight transfers and arm extensions of <Subject 1>, and its energy build through the middle of the clip matches the build in her movement.`;
+}
+
+// Builds the Stage2 prompt from a character/garment/dance-ref triple,
+// truncating descriptors that would blow the word budgets in M.15.1.
+// character/garment/danceRef are the raw store records (M.3/M.4/M.5).
+function buildStage2Prompt({ character, garment, danceRef }) {
+  let appearanceDescriptor = truncateWords(character.appearanceDescriptor, MAX_DESCRIPTOR_WORDS);
+  let garmentDescriptor = truncateWords(garment.appearanceDescriptor, MAX_DESCRIPTOR_WORDS);
+  let motionDescriptor = danceRef.motionDescriptor;
+
+  let prompt = render({ appearanceDescriptor, garmentDescriptor, motionDescriptor });
+  const detailedDescriptionWords = wordCount(extractSection(prompt, "detailed_description", "overall_soundscape"));
+
+  // motionDescriptor is the only placeholder inside detailed_description
+  // (H6's 350-500 word section) — if it alone pushes the section over
+  // budget, trim it and re-render. It appears in `summary` too, but that
+  // section has no word cap (H10 caps it by sentence count, not words).
+  if (detailedDescriptionWords > DETAILED_DESCRIPTION_MAX_WORDS) {
+    const excess = detailedDescriptionWords - DETAILED_DESCRIPTION_MAX_WORDS;
+    const motionWords = wordCount(motionDescriptor);
+    motionDescriptor = truncateWords(motionDescriptor, Math.max(1, motionWords - excess));
+    prompt = render({ appearanceDescriptor, garmentDescriptor, motionDescriptor });
+  }
+
+  return { prompt, appearanceDescriptor, garmentDescriptor, motionDescriptor };
+}
+
+module.exports = { buildStage2Prompt, truncateWords, wordCount, extractSection, MAX_DESCRIPTOR_WORDS, DETAILED_DESCRIPTION_MAX_WORDS };
+// Checks the Stage2 prompt assembler (dev-plan.md T7) against the
+// mechanical items from MVCP M.15.1, plus the truncation behavior and the
+// footwear fix (S1 spike finding). Run: node --test prompt-template.test.js
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const { buildStage2Prompt, truncateWords, wordCount, extractSection, MAX_DESCRIPTOR_WORDS } = require("./prompt-template.js");
+
+const SAMPLE = {
+  character: { appearanceDescriptor: "shoulder-length straight black hair, a slender build, natural fair skin, and a friendly neutral expression" },
+  garment: { appearanceDescriptor: "a fitted red qipao-style dress with gold trim embroidery and a side slit" },
+  danceRef: { motionDescriptor: "a lively hip-hop inspired routine with hip sways and raised-arm turns" },
+};
+
+test("truncateWords/wordCount behave as expected", () => {
+  assert.equal(wordCount("one two three"), 3);
+  assert.equal(truncateWords("one two three", 5), "one two three");
+  assert.equal(truncateWords("one two three four five six", 3), "one two three");
+});
+
+test("M.15.1 H6: detailed_description is 350-500 words for a representative fill", () => {
+  const { prompt } = buildStage2Prompt(SAMPLE);
+  const n = wordCount(extractSection(prompt, "detailed_description", "overall_soundscape"));
+  assert.ok(n >= 350 && n <= 500, `detailed_description word count ${n} outside 350-500`);
+});
+
+test("M.15.1 H1: total prompt stays well under the 7000-character cap", () => {
+  const { prompt } = buildStage2Prompt(SAMPLE);
+  assert.ok(prompt.length < 7000, `prompt is ${prompt.length} chars`);
+});
+
+test("M.15.1 H9: retention_analysis only uses whitelisted relation markers", () => {
+  const { prompt } = buildStage2Prompt(SAMPLE);
+  const analysis = extractSection(prompt, "retention_analysis", "detailed_description");
+  const WHITELIST = ["fully_preserved", "weak_reference", "fully_copy", "attribute_transfer"];
+  const found = analysis.match(/- ([a-z_]+) -|: ([a-z_]+) -/g) || [];
+  assert.ok(found.length > 0, "expected to find relation markers in retention_analysis");
+  for (const marker of WHITELIST) assert.ok(analysis.includes(marker), `expected marker "${marker}" to appear`);
+});
+
+test("M.15.1 H5: single-shot clip (every [Shot N] reference is shot 1), no MM:SS timestamps", () => {
+  const { prompt } = buildStage2Prompt(SAMPLE);
+  const shotRefs = prompt.match(/\[Shot (\d+)\]/g) || [];
+  assert.ok(shotRefs.length > 0, "expected at least one [Shot N] reference");
+  assert.ok(shotRefs.every((s) => s === "[Shot 1]"), `expected every shot reference to be [Shot 1], got: ${shotRefs}`);
+  assert.doesNotMatch(prompt, /At \d{2}:\d{2}\.\d{3}/);
+});
+
+test("footwear fix (S1 spike finding): prompt pins footwear to <Picture 1> and says <Picture 2> doesn't affect it", () => {
+  const { prompt } = buildStage2Prompt(SAMPLE);
+  assert.match(prompt, /footwear.*retained unchanged/);
+  assert.match(prompt, /does not affect her footwear/);
+});
+
+test("appearanceDescriptor/garmentDescriptor over the word budget get truncated", () => {
+  const longDescriptor = Array.from({ length: 100 }, (_, i) => `word${i}`).join(" ");
+  const { prompt, appearanceDescriptor, garmentDescriptor } = buildStage2Prompt({
+    character: { appearanceDescriptor: longDescriptor },
+    garment: { appearanceDescriptor: longDescriptor },
+    danceRef: SAMPLE.danceRef,
+  });
+  assert.equal(wordCount(appearanceDescriptor), MAX_DESCRIPTOR_WORDS);
+  assert.equal(wordCount(garmentDescriptor), MAX_DESCRIPTOR_WORDS);
+  assert.ok(!prompt.includes("word99"), "expected the tail of the long descriptor to be gone");
+});
+
+test("an oversized motionDescriptor is truncated so detailed_description stays within the 500-word H6 cap", () => {
+  const longMotion = Array.from({ length: 300 }, (_, i) => `move${i}`).join(" ");
+  const { prompt, motionDescriptor } = buildStage2Prompt({ ...SAMPLE, danceRef: { motionDescriptor: longMotion } });
+  const n = wordCount(extractSection(prompt, "detailed_description", "overall_soundscape"));
+  assert.ok(n <= 500, `detailed_description word count ${n} exceeds 500 after truncation`);
+  assert.ok(wordCount(motionDescriptor) < 300, "expected motionDescriptor itself to have been shortened");
+});