dsh-creation-mode 3.0.0 → 3.0.1

package/references/typography.md

@@ -0,0 +1,276 @@
+# 中文排版
+
+画面上的字是观众唯一会「读」的东西。画得再好，字排得散，整条片子就掉档。
+
+这一份讲：字号怎么定、中文的坑在哪、文字怎么量、怎么排、怎么动。
+
+---
+
+## 一、字号阶梯
+
+不要给每个元素随便定字号。整条片子最多四级，比例固定：
+
+| 层级 | 相对大小 | 1080p 下的字号 | 用途 |
+|---|---|---|---|
+| 主标题 | 1.0 | 88–112px | 一场只有一句 |
+| 副标题 | 0.55 | 48–60px | 补充主标题 |
+| 正文 / 字幕 | 0.38 | 34–42px | 信息 |
+| 角标 / 注释 | 0.26 | 22–28px | 来源、时间、编号 |
+
+**两条硬规则：**
+
+1. 相邻两级的比例不能小于 1.4 倍。1.2 倍的差距在画面上看起来像「没对齐」，
+   不像「分级」。
+2. 一条片子里只用四级。出现第五级，说明信息结构没想清楚。
+
+### 竖屏
+
+9:16 的片子以宽度定字号（1080 宽为基准），比横屏小 15–20%。
+手机观看距离近，但屏幕小，字号不能照搬横屏。
+
+| 层级 | 1080×1920 竖屏 |
+|---|---|
+| 主标题 | 72–88px |
+| 副标题 | 44–52px |
+| 字幕 | 32–38px |
+| 角标 | 22–26px |
+
+---
+
+## 二、中文的六条硬规矩
+
+### 2.1 行高
+
+1.4–1.6。低于 1.3 上下行会「粘」在一起，高于 1.8 会散成两段。
+
+```js
+const lineHeight = fontSize * 1.5;
+```
+
+### 2.2 字距
+
+默认 0。**中文字距一拉大就散架**，因为每个字是等宽的方块，拉开后字与字之间的
+空隙和字内部笔画之间的空隙接近，视觉上会「碎」。
+
+只有两种情况可以加：
+
+- 主标题想强调：`letter-spacing: 0.08em`（不能再大）
+- 全大写的英文副标：`0.12em`
+
+### 2.3 单行长度
+
+不超过 18 个汉字。超过必须换行，不要靠缩小字号硬塞——缩到 28px 以下，
+在手机上就看不清了。
+
+竖屏不超过 12 个汉字。
+
+### 2.4 安全边距
+
+左右各 8%，上下各 10%。贴边的字在播放器里会被裁掉一部分（尤其是竖屏底部
+有控制条）。
+
+```js
+const padX = W * 0.08;
+const padY = H * 0.10;
+const maxWidth = W - padX * 2;
+```
+
+### 2.5 中英混排
+
+中文和英文/数字之间留半个字宽的空隙，视觉上才不打架：
+
+```js
+// 「3.2秒」→「3.2 秒」
+// 「B3风格」→「B3 风格」
+const mix = (s) => s.replace(/([A-Za-z0-9])([\u4e00-\u9fa5])/g, '$1 $2')
+                     .replace(/([\u4e00-\u9fa5])([A-Za-z0-9])/g, '$1 $2');
+```
+
+### 2.6 标点
+
+| 规则 | 说明 |
+|---|---|
+| 句末不加句号 | 字幕不是文章，句号显得死板 |
+| 逗号用全角「，」 | 半角「,」在中文里像排版错误 |
+| 破折号用两个全角横线「——」 | 不要用 `--` 或单个「—」 |
+| 省略号用「……」 | 六个点，不是三个 |
+| 引号用「」或“” | 全文统一一种 |
+
+---
+
+## 三、量文字
+
+Canvas 不会自动换行，必须自己量。
+
+### 3.1 单行宽度
+
+```js
+ctx.font = '700 96px "PingFang SC", "Microsoft YaHei", sans-serif';
+const w = ctx.measureText('创作模式').width;
+```
+
+注意：**先设 `font` 再量**。`measureText` 用的是当前 `ctx.font`。
+
+### 3.2 自动换行
+
+```js
+function wrapText(ctx, text, maxWidth) {
+  const lines = [];
+  let line = '';
+  for (const ch of text) {
+    const test = line + ch;
+    if (ctx.measureText(test).width > maxWidth && line) {
+      lines.push(line);
+      line = ch;
+    } else {
+      line = test;
+    }
+  }
+  if (line) lines.push(line);
+  return lines;
+}
+```
+
+逐字断行对中文是对的（中文可以在任意字之间断），英文要按词断，混排时优先在
+空格处断。
+
+### 3.3 垂直居中
+
+`textBaseline` 的三个值差别很大：
+
+| 值 | 基线位置 | 适合 |
+|---|---|---|
+| `alphabetic` | 字母底部（默认） | 精确对齐西文 |
+| `middle` | 文字视觉中心偏上 | 单行居中（中文慎用，会偏上） |
+| `top` | 字体顶部 | 多行排版 |
+
+中文单行垂直居中，用 `middle` 后还要再往下挪 `fontSize * 0.08` 才真正居中。
+
+---
+
+## 四、排版样式
+
+### 4.1 字重比字号更有效
+
+想强调一个词，优先加粗或换色，而不是放大。放大破坏节奏，加粗只改变视觉重量。
+
+```js
+ctx.font = '400 42px ...';   // 正文
+ctx.font = '700 42px ...';   // 强调（字号不变）
+```
+
+字体族只用系统字体，**不要引用任何网络字体**：离线渲染拿不到，会退回默认字体，
+排版全乱。
+
+```js
+const FONT = '"PingFang SC", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif';
+```
+
+### 4.2 对齐
+
+- 标题左对齐，起点固定在一个 x 上（不要居中——居中会让每行起点跳动）
+- 多行正文左对齐，右端不齐是正常的
+- 数字右对齐（小数点对齐），尤其是数据对比
+
+### 4.3 描边与阴影
+
+深色背景上的白字，加一层极淡的阴影让边缘清晰：
+
+```js
+ctx.shadowColor = 'rgba(0,0,0,0.35)';
+ctx.shadowBlur = 12;
+ctx.shadowOffsetY = 2;
+ctx.fillText(text, x, y);
+ctx.shadowBlur = 0; ctx.shadowOffsetY = 0;   // 用完立刻复位
+```
+
+描边（`strokeText`）超过 2px 会显得廉价，只在超大标题上用 1–2px。
+
+---
+
+## 五、文字动画
+
+### 5.1 逐字进场
+
+三条限制：
+
+1. 每个字的延迟 **20–40ms**。超过 60ms 就变成「一个一个蹦」，慢得难受。
+2. 进场位移不超过字高的 30%。位移太大像在掉字。
+3. 最后一个字落定后，**至少留 6 帧静止**再切走，否则观众读不完。
+
+```js
+function drawChars(t, text, x, y, start, perChar = 0.03) {
+  let cursor = x;
+  for (let i = 0; i < text.length; i++) {
+    const u = tween(t, start + i * perChar, 0.35);
+    if (u <= 0) { cursor += ctx.measureText(text[i]).width; continue; }
+    const alpha = easeOutCubic(u);
+    const dy = 12 * (1 - easeOutBack(u));
+    ctx.globalAlpha = alpha;
+    ctx.fillText(text[i], cursor, y + dy);
+    cursor += ctx.measureText(text[i]).width;
+  }
+  ctx.globalAlpha = 1;
+}
+```
+
+### 5.2 打字机
+
+逐字显示 + 一个光标。光标要闪，但**不要用 `Math.sin(t*10)` 这种连续值**，
+用方波：
+
+```js
+const blink = Math.floor(t * 2) % 2 === 0;   // 每 0.5s 切换
+```
+
+### 5.3 数字滚动
+
+数字从 0 滚到目标值，末尾要减速，否则读不出最终值：
+
+```js
+const u = tween(t, start, 0.9);
+const shown = Math.round(target * easeOutQuint(u));
+```
+
+千分位、单位、正负号在滚动过程中就要固定，不要到最后才出现。
+
+### 5.4 遮罩揭示
+
+文字从下往上「擦」出来，比淡入有力：
+
+```js
+ctx.save();
+ctx.beginPath();
+ctx.rect(0, y - fontSize, W, fontSize * 1.3 * u);   // 逐渐露出
+ctx.clip();
+ctx.fillText(text, x, y);
+ctx.restore();
+```
+
+---
+
+## 六、常见错误
+
+| 错误 | 后果 | 修正 |
+|---|---|---|
+| 字号 28px 以下放正文 | 手机上看不清 | 缩内容，不缩字 |
+| 行高 1.0 | 上下行粘连 | 1.4–1.6 |
+| 中文字距 0.2em | 字散成碎片 | 0，或 ≤0.08em |
+| 引用 Google Fonts | 离线渲染退回默认字体 | 只用系统字体 |
+| 文字贴边 | 播放器裁切 | 左右 8% 安全边距 |
+| 一句字幕 30 字 | 读不完 | ≤ 镜头时长 × 5.5 字 |
+| 每行都居中 | 起点跳动，像 PPT | 左对齐 |
+| 阴影 blur 30px | 糊成一团 | 8–14px |
+
+---
+
+## 七、自检清单
+
+- [ ] 字号只有四级，相邻级差 ≥ 1.4 倍？
+- [ ] 行高在 1.4–1.6？
+- [ ] 单行 ≤ 18 字（竖屏 ≤ 12 字）？
+- [ ] 左右留了 8% 安全边距？
+- [ ] 中英之间有空格？
+- [ ] 用的是系统字体，没有网络字体？
+- [ ] 逐字动画的字间隔 20–40ms，末尾留了 6 帧静止？
+- [ ] 深色背景上的字有没有加淡阴影保证边缘清晰？

package/tools.js

@@ -8,10 +8,10 @@
  * No second model call happens here: the Agent that already holds the user's
  * context is the one that authors the animation.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
-import { OUTPUT_DIR, STILLS_DIR, catalog, defaultMusicFor, describe, searchStyles, styleById } from './data.js';
+import { KEEP_SAVES, OUTPUT_DIR, REFERENCES, REFERENCES_DIR, STILLS_DIR, catalog, defaultMusicFor, describe, searchStyles, styleById } from './data.js';
 
 const MAX_HTML_BYTES = 2 * 1024 * 1024;
 const MAX_STILLS_PER_CALL = 4;
@@ -105,6 +105,67 @@ function round(value, digits = 2) {
   return Math.round(Number(value) * factor) / factor;
 }
 
+/**
+ * 只留成品：一次创作只保留最近一次保存，不留中间稿。
+ *
+ * 动画是 `anim-<title>-<ts>.{html,score.js,json}`，分镜是 `sb-<title>-<ts>.json`，
+ * 同一个前缀下的文件按 id 归组，除这次刚存的 `keepId` 外，最多再留 KEEP_SAVES-1 份。
+ *
+ * `keepId` 直接算在名额里，所以 KEEP_SAVES = 1 就是「只留这一次」。这一点很重要：
+ * 清理发生在落盘之前还是之后都不影响结果，也不会因为两次保存落在同一毫秒
+ * （mtime 相同、排序谁前谁后说不准）而多留一份。
+ *
+ * @returns 被删掉的文件名，用于在工具返回值里如实说明。
+ */
+function pruneSaves(prefix, keepId) {
+  let names = [];
+  try { names = readdirSync(OUTPUT_DIR); } catch { return []; }
+
+  const sets = new Map();
+  for (const name of names) {
+    if (!name.startsWith(prefix)) continue;
+    const matched = /^(.+?)\.(html|score\.js|json)$/.exec(name);
+    if (!matched) continue;
+    const id = matched[1];
+    const entry = sets.get(id) || { id, mtime: 0 };
+    try { entry.mtime = Math.max(entry.mtime, statSync(join(OUTPUT_DIR, name)).mtimeMs); } catch { /* 读不到时间就按 0 算 */ }
+    sets.set(id, entry);
+  }
+
+  const older = [...sets.values()]
+    .filter((entry) => entry.id !== keepId)
+    .sort((a, b) => b.mtime - a.mtime || b.id.localeCompare(a.id));
+  const keep = new Set([keepId, ...older.slice(0, Math.max(0, KEEP_SAVES - 1)).map((x) => x.id)]);
+
+  const removed = [];
+  for (const id of sets.keys()) {
+    if (keep.has(id)) continue;
+    for (const ext of ['.html', '.score.js', '.json']) {
+      const file = join(OUTPUT_DIR, `${id}${ext}`);
+      if (!existsSync(file)) continue;
+      try { unlinkSync(file); removed.push(`${id}${ext}`); } catch { /* 删不掉就留着，不影响这次保存 */ }
+    }
+  }
+  return removed;
+}
+
+/** 最近一次保存的 id，用作 base 兜底（旧稿已被清理时仍能返工）。 */
+function latestSave(prefix, ext) {
+  try {
+    let best = '';
+    let bestTime = -1;
+    for (const name of readdirSync(OUTPUT_DIR)) {
+      if (!name.startsWith(prefix) || !name.endsWith(ext)) continue;
+      let mtime = 0;
+      try { mtime = statSync(join(OUTPUT_DIR, name)).mtimeMs; } catch { /* 忽略 */ }
+      if (mtime > bestTime) { bestTime = mtime; best = name.slice(0, -ext.length); }
+    }
+    return best;
+  } catch {
+    return '';
+  }
+}
+
 /**
  * Phrases that make on-screen copy read as machine-written.
  *
@@ -213,6 +274,56 @@ export function registerCreationTools(deps) {
     : () => deps.attachments;
   const disposers = [];
 
+  disposers.push(tools.register({
+    name: 'get_reference',
+    description: [
+      '取一份工艺参考：缓动、转场、排版、调色、音画同步、音色配方、文案标准。',
+      '这些是写画面和配乐的具体做法，按需加载，不占每轮的上下文。',
+      '写动画之前至少取 motion；画面里有中文标题取 typography；要片子感取 color；',
+      '写 score_js 之前取 timbre 和 audio；写分镜文案之前取 copy。',
+      '同一份取过一次就不必再取。',
+    ].join('\n'),
+    parameters: {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          description: '参考名：motion / transitions / typography / color / audio / timbre / copy。',
+        },
+      },
+      required: ['name'],
+      additionalProperties: false,
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          name: { type: 'string' },
+          title: { type: 'string' },
+          body: { type: 'string', description: '参考全文（Markdown）。' },
+        },
+        required: ['name', 'title', 'body'],
+        additionalProperties: false,
+      },
+      render: (_args, value) => [{ type: 'text', text: value.body }],
+      presentationMeta: (_args, value) => value,
+    },
+    async execute(args) {
+      const name = String(args?.name || '').trim().toLowerCase();
+      const hit = REFERENCES[name];
+      if (!hit) {
+        throw new Error(`没有这份参考：${name || '(空)'}。可用：${Object.keys(REFERENCES).join(' / ')}`);
+      }
+      let body;
+      try {
+        body = readFileSync(join(REFERENCES_DIR, `${name}.md`), 'utf8');
+      } catch {
+        throw new Error(`参考文件缺失：references/${name}.md`);
+      }
+      return { name, title: hit, body };
+    },
+  }));
+
   disposers.push(tools.register({
     name: 'list_styles',
     description: [
@@ -515,7 +626,10 @@ export function registerCreationTools(deps) {
       const { warnings, totalSeconds } = inspectShots(shots, duration);
       const music = resolveMusic(args?.music, style);
 
-      const id = `sb-${slug(args?.title)}-${Date.now().toString(36)}`;
+      // 同一毫秒内保存两次会撞 id，后一份会覆盖前一份：探测到空闲的名字为止。
+      const stem = `sb-${slug(args?.title)}-${Date.now().toString(36)}`;
+      let id = stem;
+      for (let n = 2; existsSync(join(OUTPUT_DIR, `${id}.json`)); n++) id = `${stem}-${n}`;
       const storyboard = {
         id,
         title: String(args?.title || '分镜'),
@@ -543,6 +657,12 @@ export function registerCreationTools(deps) {
       };
 
       mkdirSync(OUTPUT_DIR, { recursive: true });
+
+      // 只留成品：分镜也只保留最新这一份，改一次覆盖一次，不堆中间稿。
+      // 先清理再落盘，这样新分镜的 warnings 里能如实写上清了几个文件。
+      const removed = pruneSaves('sb-', id);
+      if (removed.length) storyboard.warnings = [...warnings, `已清理 ${removed.length} 个旧分镜文件，只保留这一份`];
+
       writeFileSync(join(OUTPUT_DIR, `${id}.json`), JSON.stringify(storyboard, null, 2), 'utf8');
       return storyboard;
     },
@@ -555,6 +675,7 @@ export function registerCreationTools(deps) {
       '调用前应当已经完成：风格拍板（get_style）与分镜拍板（save_storyboard）。把分镜 id 传进 storyboard_id，卡片会带上分镜信息。',
       'HTML 必须满足：单个完整文件、只含原生 HTML/JS/Canvas、不引用任何外部库或图片、实现 window.renderAt(t)（t 为秒，同一 t 渲染同一帧）、使用固定种子随机、不启用 requestAnimationFrame 自播。',
       '生成后用 renderAt 检查首帧、中段、尾帧，确认不是黑屏或静止。',
+      '每次保存都会覆盖上一版：工作区里只留最新这一份动画（html + 配乐 + 元数据），旧稿自动删除，不要指望旧版文件还在。',
     ].join('\n'),
     parameters: {
       type: 'object',
@@ -605,7 +726,16 @@ export function registerCreationTools(deps) {
         },
         duration: { type: 'number', description: '片长（秒），用于预览进度条与导出。默认 8。' },
         fps: { type: 'integer', description: '帧率，默认 30。' },
-        html: { type: 'string', description: '完整的动画 HTML 文件正文。' },
+        base_id: {
+          type: 'string',
+          description: [
+            '返工时用：上一版动画的 id（save_animation 返回值里的 id）。',
+            '给了它就可以省略 html，系统会读回上一版正文，只改你这次传的字段。',
+            '只换配乐时，传 base_id + 新的 score_js 即可，不必重发整份 HTML。',
+            '工作区只保留最新一版，所以 base_id 写错或已被清理时，系统会自动退到最近一版继续。',
+          ].join(''),
+        },
+        html: { type: 'string', description: '完整的动画 HTML 文件正文。给了 base_id 时可省略。' },
         score_js: {
           type: 'string',
           description: [
@@ -618,11 +748,13 @@ export function registerCreationTools(deps) {
             '把声音接到 dest 上，并在绝对时间点上 schedule（用 start(t)）。',
             '所有节点必须按 duration 收尾，不要在函数里 await。',
             '卡点用 beats 里的 time：它来自动画代码本身，比 cuts 准。',
-            '留空则退回内置合成引擎。',
+            '禁止做低频扫频底鼓（正弦从一两百赫兹滑到三四十赫兹）：听感像放屁。',
+            '要重音就给固定频率的低正弦加鼓皮噪声，让包络做冲击，不要让频率滑。',
+            '必填：没有兜底引擎，不传这段代码这片子就没有声音。',
           ].join(''),
         },
       },
-      required: ['title', 'html'],
+      required: [],
       additionalProperties: false,
     },
     output: {
@@ -638,7 +770,7 @@ export function registerCreationTools(deps) {
           cuts: { type: 'array', items: { type: 'number' }, description: '切点秒数，配乐按这些点卡拍。' },
           cues: { type: 'array', items: { type: 'object', additionalProperties: true }, description: '精确卡点列表' },
           beats: { type: 'array', items: { type: 'object', additionalProperties: true }, description: '从动画代码导出的节奏点' },
-          scoreUrl: { type: 'string', description: '模型自写配乐的地址；空串表示使用内置引擎。' },
+          scoreUrl: { type: 'string', description: '模型自写配乐的地址。' },
           duration: { type: 'number' },
           fps: { type: 'integer' },
           url: { type: 'string' },
@@ -656,6 +788,7 @@ export function registerCreationTools(deps) {
           value.warnings.length ? `注意：${value.warnings.join('；')}` : '',
           `地址：${value.url}`,
           `配乐：${value.music}`,
+          value.scoreUrl ? `配乐地址：${value.scoreUrl}` : '',
           `卡点对齐：${value.cuts.length} 个分镜切点${value.cues && value.cues.length ? ` + ${value.cues.length} 个镜头重点` : ''}已毫秒级精准对齐`,
           '对话末尾已显示预览卡片：点击播放音画同步出声，点击导出直接一键下载成片。',
         ].filter(Boolean).join('\n'),
@@ -663,8 +796,37 @@ export function registerCreationTools(deps) {
       presentationMeta: (_args, value) => value,
     },
     async execute(args) {
-      const html = stripWrappers(args?.html);
-      if (!html) throw new Error('html 为空');
+      // A revision reuses the previous cut: only the parts the caller actually changed
+      // travel over the wire, so "just change the music" stays a two-field call.
+      const notes = [];
+      let baseId = String(args?.base_id || '').trim();
+      // 旧稿会被自动清理，所以 base_id 指向的那一版可能已经不在了：退到最近一版，
+      // 让「只换配乐」这类返工不会因为文件被清掉而直接失败。
+      if (baseId && !existsSync(join(OUTPUT_DIR, `${baseId}.html`))) {
+        const newest = latestSave('anim-', '.html');
+        if (newest) {
+          notes.push(`上一版 ${baseId} 已随旧稿清理，已改用最近一版 ${newest} 作为底稿`);
+          baseId = newest;
+        } else {
+          baseId = '';
+        }
+      }
+      let base;
+      if (baseId) {
+        try {
+          base = JSON.parse(readFileSync(join(OUTPUT_DIR, `${baseId}.json`), 'utf8'));
+        } catch { /* no sidecar: fall back to the html alone */ }
+      }
+
+      let html = stripWrappers(args?.html);
+      if (!html && baseId) {
+        try { html = readFileSync(join(OUTPUT_DIR, `${baseId}.html`), 'utf8'); } catch { /* reported below */ }
+      }
+      if (!html) {
+        throw new Error(baseId
+          ? `找不到上一版 ${baseId} 的正文，请改用完整 html 重新提交`
+          : 'html 为空');
+      }
       const bytes = Buffer.byteLength(html, 'utf8');
       if (bytes > MAX_HTML_BYTES) throw new Error(`HTML 过大（${(bytes / 1048576).toFixed(1)} MB），上限 2 MB`);
 
@@ -672,8 +834,18 @@ export function registerCreationTools(deps) {
       assertRecordable(html);
 
       const warnings = inspectHtml(html);
-      const style = args?.style_id ? styleById(args.style_id) : undefined;
-      const storyboardId = String(args?.storyboard_id || '');
+      const styleId = args?.style_id || base?.styleId;
+      const style = styleId ? styleById(styleId) : undefined;
+      let storyboardId = String(args?.storyboard_id || base?.storyboardId || '');
+
+      // 分镜同样只留最新一份，旧 id 可能已被清理：退到最近一版分镜，别让卡点凭空消失。
+      if (storyboardId && !existsSync(join(OUTPUT_DIR, `${storyboardId}.json`))) {
+        const newestBoard = latestSave('sb-', '.json');
+        if (newestBoard) {
+          notes.push(`分镜 ${storyboardId} 已随旧稿清理，已改用最近一版 ${newestBoard}`);
+          storyboardId = newestBoard;
+        }
+      }
 
       // The storyboard supplies both the score choice and the cut points; without it
       // the score still works, it just has no edits to land on.
@@ -688,7 +860,7 @@ export function registerCreationTools(deps) {
         warnings.push('没有关联分镜：这版动画未经用户拍板');
       }
 
-      const music = resolveMusic(args?.music || (board && board.music), style);
+      const music = resolveMusic(args?.music || base?.music || (board && board.music), style);
       const cuts = Array.isArray(board?.shots)
         ? board.shots
           .map((shot) => round(Number(shot.start) || 0))
@@ -710,8 +882,10 @@ export function registerCreationTools(deps) {
           }
         }
       }
-      if (Array.isArray(args?.cues)) {
-        for (const c of args.cues) {
+      const cueSource = Array.isArray(args?.cues) && args.cues.length ? args.cues
+        : (Array.isArray(base?.cues) ? base.cues : []);
+      if (cueSource.length) {
+        for (const c of cueSource) {
           const t = round(Number(c.time) || 0);
           if (t > 0.05 && t < (Number(args?.duration) || board.duration || 8)) {
             cues.push({ time: t, type: c.type || 'hit', label: c.label || '' });
@@ -719,12 +893,14 @@ export function registerCreationTools(deps) {
         }
       }
 
-      const duration = Math.max(1, Math.min(Number(args?.duration) || board?.duration || 8, 120));
-      const fps = Math.max(1, Math.min(Number(args?.fps) || board?.fps || 30, 60));
+      const duration = Math.max(1, Math.min(Number(args?.duration) || base?.duration || board?.duration || 8, 120));
+      const fps = Math.max(1, Math.min(Number(args?.fps) || base?.fps || board?.fps || 30, 60));
 
       // Beats come from the animation code the model just wrote, so they are the most
       // trusted sync points: keep sub-second precision rather than rounding like cues.
-      const beats = (Array.isArray(args?.beats) ? args.beats : [])
+      const beatSource = Array.isArray(args?.beats) && args.beats.length ? args.beats
+        : (Array.isArray(base?.beats) ? base.beats : []);
+      const beats = beatSource
         .map((b) => ({
           time: Math.round((Number(b.time) || 0) * 1000) / 1000,
           type: String(b.type || 'hit'),
@@ -734,35 +910,50 @@ export function registerCreationTools(deps) {
         .filter((b) => b.time > 0.02 && b.time < duration)
         .sort((a, b) => a.time - b.time);
 
-      const id = `anim-${slug(args?.title)}-${Date.now().toString(36)}`;
+      // 配乐必须由模型当场写。没有兜底引擎：拿不到 score_js 就报错，让 Agent 重写，
+      // 绝不悄悄换成一段通用配乐。校验放在写文件之前，否则被拒的那次会留下孤儿 HTML。
+      let scoreJs = stripScore(args?.score_js);
+      if (!scoreJs && baseId && base?.scoreUrl) {
+        try { scoreJs = readFileSync(join(OUTPUT_DIR, `${baseId}.score.js`), 'utf8'); } catch { /* 下面统一报错 */ }
+      }
+      if (!scoreJs) {
+        throw new Error('缺少 score_js：配乐必须由你为这个片子当场写，没有兜底引擎。'
+          + '返工时可以传 base_id 沿用上一版配乐，但首版必须自带 score_js。');
+      }
+      if (!/createOscillator|createBufferSource|createGain|createBiquadFilter/.test(scoreJs)) {
+        throw new Error('score_js 里没有创建任何音频节点（createOscillator / createBufferSource / '
+          + 'createGain / createBiquadFilter），这段代码发不出声音。');
+      }
 
+      // Two saves inside the same millisecond would otherwise share an id and the
+      // second would silently overwrite the first, so probe until the name is free.
       mkdirSync(OUTPUT_DIR, { recursive: true });
+      const stem = `anim-${slug(args?.title || base?.title)}-${Date.now().toString(36)}`;
+      let id = stem;
+      for (let n = 2; existsSync(join(OUTPUT_DIR, `${id}.html`)); n++) id = `${stem}-${n}`;
+
       writeFileSync(join(OUTPUT_DIR, `${id}.html`), html, 'utf8');
 
-      // A model-written score replaces the built-in engine entirely for this clip.
-      let scoreUrl = '';
-      const scoreJs = stripScore(args?.score_js);
-      if (scoreJs) {
-        if (!/createOscillator|createBufferSource|createGain|createBiquadFilter/.test(scoreJs)) {
-          warnings.push('自写配乐里没有创建任何音频节点，已退回内置引擎');
-        } else {
-          writeFileSync(join(OUTPUT_DIR, `${id}.score.js`), scoreJs, 'utf8');
-          scoreUrl = `/code-animation-api/score/${id}`;
-        }
-      }
+      writeFileSync(join(OUTPUT_DIR, `${id}.score.js`), scoreJs, 'utf8');
+      const scoreUrl = `/code-animation-api/score/${id}`;
 
       // Without beats the score has to infer where the picture peaks, which is exactly
       // the guessing the beats parameter exists to remove.
-      if (scoreUrl && !beats.length) {
+      if (!beats.length) {
         warnings.push('配乐没有收到 beats：卡点只能靠 cuts 推，精度会差一些');
       }
 
+      // 只留成品：这一版已经落盘，再把之前的动画稿（html + 配乐 + sidecar）全部删掉。
+      // 必须写在所有写入之后，否则新稿会被自己的清理逻辑扫到。
+      const removed = pruneSaves('anim-', id);
+      if (removed.length) notes.push(`已清理 ${removed.length} 个旧稿文件，只保留这一版`);
+
       const value = {
         id,
-        title: String(args?.title || '动画'),
+        title: String(args?.title || base?.title || '动画'),
         styleId: style ? style.id : '',
         styleName: style ? style.name : '',
-        music: scoreUrl ? '模型自写配乐' : music,
+        music: music && music !== 'none' ? music : '模型自写配乐',
         cuts,
         cues,
         beats,
@@ -771,9 +962,12 @@ export function registerCreationTools(deps) {
         fps,
         url: `/code-animation-api/animation/${id}`,
         bytes,
-        warnings,
+        warnings: notes.length ? [...notes, ...warnings] : warnings,
       };
       if (storyboardId) value.storyboardId = storyboardId;
+
+      // Keep a sidecar so a later revision can inherit everything it did not resend.
+      writeFileSync(join(OUTPUT_DIR, `${id}.json`), JSON.stringify({ ...value, baseId: baseId || undefined }, null, 2), 'utf8');
       return value;
     },
   }));