dsh-motion 0.3.0 → 0.4.1

package/scripts/test-approvals.mjs

@@ -0,0 +1,64 @@
+import assert from 'node:assert/strict'
+import { execFileSync } from 'node:child_process'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+const SCRIPT = new URL('./approvals.mjs', import.meta.url).pathname
+const project = mkdtempSync(join(tmpdir(), 'dsh-approvals-'))
+let failed = 0
+
+function run(args) {
+  try {
+    const out = execFileSync(process.execPath, [SCRIPT, ...args], { encoding: 'utf8', stdio: 'pipe' })
+    return { code: 0, out }
+  } catch (error) {
+    return { code: error.status ?? 1, out: `${error.stdout ?? ''}${error.stderr ?? ''}` }
+  }
+}
+
+function test(name, fn) {
+  try {
+    fn()
+    console.log(`ok   ${name}`)
+  } catch (error) {
+    failed++
+    console.log(`FAIL ${name}`)
+    console.error(`     ${String(error.message).split('\n')[0]}`)
+  }
+}
+
+run(['init', project, '--mode', 'light'])
+
+test('刚 init 时 check 不通过', () => {
+  assert.equal(run(['check', project]).code, 1)
+})
+
+test('不能跳过前置阶段', () => {
+  assert.equal(run(['set', project, 'script_storyboard', 'approved']).code, 1)
+})
+
+test('按顺序全部确认后 check 通过', () => {
+  assert.equal(run(['set', project, 'requirements', 'approved', '--note', '需求']).code, 0)
+  assert.equal(run(['set', project, 'script_storyboard', 'approved', '--note', '脚本+分镜']).code, 0)
+  assert.equal(run(['set', project, 'look', 'approved', '--note', '3 帧']).code, 0)
+  assert.equal(run(['set', project, 'start', 'approved', '--note', '可以开始']).code, 0)
+  assert.equal(run(['check', project]).code, 0)
+})
+
+test('standard 模式包含独立脚本/分镜/交付', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'dsh-approvals-std-'))
+  assert.equal(run(['init', dir, '--mode', 'standard']).code, 0)
+  assert.match(run(['show', dir]).out, /脚本/)
+  assert.match(run(['show', dir]).out, /分镜/)
+  assert.match(run(['show', dir]).out, /交付清单/)
+  rmSync(dir, { recursive: true, force: true })
+})
+
+rmSync(project, { recursive: true, force: true })
+
+if (failed > 0) {
+  console.error(`\n${failed} test(s) failed`)
+  process.exit(1)
+}
+console.log('\ntest-approvals passed')

package/scripts/test-ops.mjs

@@ -0,0 +1,269 @@
+/**
+ * 纯 Node 单元测试：不联网、不跑 Python、不碰视频。
+ *
+ * 钉住 lib/ 里那些"模型看不到的不变量"：
+ *   - summarizeRender 能否从渲染器输出里稳定抽出时长/分辨率/布局问题；
+ *   - normalizePost 是否把脏参数挡在 ffmpeg 之前；
+ *   - probe 的网格、亮度解析与空镜判据是否符合 limited range；
+ *   - pluginSource 报的是不是当前这份代码。
+ *
+ * 用法：node scripts/test-ops.mjs
+ */
+import assert from 'node:assert/strict'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, utimesSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { assertApproved, readApprovals } from '../lib/approvals.js'
+import { pluginSource } from '../lib/doctor.js'
+import { importFresh } from '../lib/fresh.js'
+import {
+  isBlankFrame,
+  normalizePost,
+  normalizeTimes,
+  parseInspectOutput,
+  parseSignalStats,
+  summarizeRender,
+  tileGrid,
+} from '../lib/ops.js'
+
+let failed = 0
+
+function test(name, fn) {
+  try {
+    fn()
+    console.log(`ok   ${name}`)
+  } catch (error) {
+    failed++
+    console.log(`FAIL ${name}`)
+    console.error(`     ${String(error.message).split('\n')[0]}`)
+  }
+}
+
+// —— summarizeRender：真实渲染器输出的一行摘要 ——
+test('summarizeRender 读出声画参数', () => {
+  const summary = summarizeRender(
+    'Derivative.mp4 12.5 s, 1280x720 at 30 fps, 4.2 MB, rendered in 61.3 s\n',
+    '',
+  )
+  assert.equal(summary.video, 'Derivative.mp4')
+  assert.equal(summary.durationSec, 12.5)
+  assert.equal(summary.width, 1280)
+  assert.equal(summary.height, 720)
+  assert.equal(summary.fps, 30)
+  assert.equal(summary.megabytes, 4.2)
+  assert.equal(summary.renderedSec, 61.3)
+  assert.deepEqual(summary.layoutProblems, [])
+})
+
+test('summarizeRender 也认 stderr', () => {
+  const summary = summarizeRender('', 'out.mp4 1.0 s, 640x360 at 15 fps, 0.1 MB')
+  assert.equal(summary.video, 'out.mp4')
+  assert.equal(summary.durationSec, 1)
+  assert.equal(summary.renderedSec, null)
+})
+
+test('summarizeRender 抽布局问题', () => {
+  const summary = summarizeRender(
+    'noise\n  [1] Text "Euler" overflows the frame\n  [2] Axes label collides\n',
+    '',
+  )
+  assert.deepEqual(summary.layoutProblems, [
+    'Text "Euler" overflows the frame',
+    'Axes label collides',
+  ])
+  assert.equal(summary.video, null)
+  assert.equal(summary.durationSec, null)
+})
+
+test('summarizeRender 不把无关方括号当问题', () => {
+  const summary = summarizeRender('[build] starting\n[1]ok\n', '')
+  assert.deepEqual(summary.layoutProblems, ['ok'])
+})
+
+// —— normalizePost：脏参数一律夹到合法区间 ——
+test('normalizePost 默认关闭', () => {
+  const post = normalizePost()
+  assert.deepEqual(post, {
+    subframes: 1,
+    grain: 0,
+    vignette: 0,
+    grade: '',
+    enabled: false,
+  })
+})
+
+test('normalizePost 夹住 subframes', () => {
+  assert.equal(normalizePost({ subframes: 99 }).subframes, 8)
+  assert.equal(normalizePost({ subframes: 0 }).subframes, 1)
+  assert.equal(normalizePost({ subframes: -3 }).subframes, 1)
+  assert.equal(normalizePost({ subframes: 'abc' }).subframes, 1)
+  assert.equal(normalizePost({ subframes: 3 }).subframes, 3)
+})
+
+test('normalizePost 接受布尔简写', () => {
+  assert.equal(normalizePost({ grain: true }).grain, 7)
+  assert.equal(normalizePost({ vignette: true }).vignette, 4)
+  assert.equal(normalizePost({ grain: true }).enabled, true)
+})
+
+test('normalizePost 不把负数当"开启"', () => {
+  const post = normalizePost({ grain: -5, vignette: -2 })
+  assert.equal(post.grain, -5)
+  assert.equal(post.enabled, false)
+})
+
+test('normalizePost 只认已知调色预设', () => {
+  assert.equal(normalizePost({ grade: 'warm' }).enabled, true)
+  assert.equal(normalizePost({ grade: 42 }).enabled, false)
+})
+
+// —— tileGrid：网格要装得下请求的帧数 ——
+test('tileGrid 按帧数选网格', () => {
+  assert.equal(tileGrid(2), '2x1')
+  assert.equal(tileGrid(4), '2x2')
+  assert.equal(tileGrid(6), '3x2')
+  assert.equal(tileGrid(9), '3x3')
+  assert.equal(tileGrid(12), '4x3')
+  assert.equal(tileGrid(16), '4x4')
+  assert.equal(tileGrid(24), '6x4')
+})
+
+// —— signalstats：从 ffmpeg 的 metadata 输出里读回每帧亮度范围 ——
+const SIGNAL_FIXTURE = `frame:0    pts:0       pts_time:0
+lavfi.signalstats.YMIN=16
+lavfi.signalstats.YLOW=16
+lavfi.signalstats.YAVG=16
+lavfi.signalstats.YHIGH=16
+lavfi.signalstats.YMAX=16
+frame:1    pts:512     pts_time:0.017
+lavfi.signalstats.YMIN=16
+lavfi.signalstats.YLOW=40
+lavfi.signalstats.YAVG=120.5
+lavfi.signalstats.YHIGH=200
+lavfi.signalstats.YMAX=235
+`
+
+test('parseSignalStats 逐帧读回 YMIN/YAVG/YMAX', () => {
+  const frames = parseSignalStats(SIGNAL_FIXTURE)
+  assert.equal(frames.length, 2)
+  assert.deepEqual(frames[0], { frame: 0, ymin: 16, yavg: 16, ymax: 16 })
+  assert.deepEqual(frames[1], { frame: 1, ymin: 16, yavg: 120.5, ymax: 235 })
+})
+
+test('parseSignalStats 空输出不报错', () => {
+  assert.deepEqual(parseSignalStats(''), [])
+})
+
+// —— 空镜判据：limited range 的黑是 16、白是 235 ——
+test('isBlankFrame 认得出纯黑与纯白', () => {
+  assert.equal(isBlankFrame({ ymin: 16, ymax: 16 }), true)
+  assert.equal(isBlankFrame({ ymin: 16, yavg: 16, ymax: 18 }), true)
+  assert.equal(isBlankFrame({ ymin: 235, ymax: 235 }), true)
+  assert.equal(isBlankFrame({ ymin: 232, yavg: 234, ymax: 235 }), true)
+})
+
+test('isBlankFrame 不误杀正常画面', () => {
+  // 深色画面：黑底 16 + 亮线 235，是最常见的正常帧
+  assert.equal(isBlankFrame({ ymin: 16, yavg: 30, ymax: 235 }), false)
+  assert.equal(isBlankFrame({ ymin: 16, yavg: 120, ymax: 200 }), false)
+  assert.equal(isBlankFrame({}), false)
+})
+
+// —— 极简模式：解析 manimgx inspect 的输出，只出帧不编码 ——
+const INSPECT_FIXTURE = `/tmp/scene.py: T, 3.70 s, 3 plays
+storyboard: /tmp/sheet.png, /tmp/sheet-2.png
+  #0   0.00– 1.20s  scene.py:13  Create(Axes)
+layout: 1 problem
+  [1] t=0.3–1.5s (scene.py:5)  t (Text '长标题'): 1.48 past the right edge
+`
+
+test('parseInspectOutput 读出片名/时长/多张 sheet 与 layout 问题', () => {
+  const parsed = parseInspectOutput(INSPECT_FIXTURE)
+  assert.equal(parsed.scene, 'T')
+  assert.equal(parsed.durationSec, 3.7)
+  assert.equal(parsed.plays, 3)
+  assert.deepEqual(parsed.storyboard, ['/tmp/sheet.png', '/tmp/sheet-2.png'])
+  assert.equal(parsed.layoutOk, false)
+  assert.equal(parsed.layoutProblems.length, 1)
+  assert.match(parsed.layoutProblems[0], /past the right edge/)
+})
+
+test('parseInspectOutput 认 0 problem 与空输出', () => {
+  const ok = parseInspectOutput('scene.py: T, 1.00 s, 1 play\nstoryboard: a.png\nlayout: no problems in 4 samples\n')
+  assert.equal(ok.layoutOk, true)
+  assert.deepEqual(ok.layoutProblems, [])
+  assert.equal(parseInspectOutput('').scene, null)
+})
+
+test('normalizeTimes 只放行秒数与 end', () => {
+  assert.deepEqual(normalizeTimes(['1.5', 'end', 2]), ['1.5', 'end', '2'])
+  assert.deepEqual(normalizeTimes(undefined), [])
+  assert.throws(() => normalizeTimes(['-1']))
+  assert.throws(() => normalizeTimes(['abc']))
+  assert.throws(() => normalizeTimes(Array.from({ length: 25 }, (_, i) => String(i))))
+})
+
+// —— pluginSource：报的就是当前这份代码 ——
+test('pluginSource 版本与 lib 路径自洽', () => {
+  const source = pluginSource()
+  const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+  assert.equal(source.version, pkg.version)
+  assert.ok(['npm 安装', '本地 checkout'].includes(source.kind))
+  assert.ok(existsSync(join(source.lib, 'index.js')))
+  assert.ok(existsSync(join(source.lib, 'doctor.js')))
+})
+
+// —— approvals：工具层的开工确认硬门 ——
+{
+  const dir = mkdtempSync(join(tmpdir(), 'dsh-approvals-gate-'))
+  const scene = join(dir, 'scene.py')
+  writeFileSync(scene, 'pass\n')
+  let missing = false
+  try { assertApproved(scene) } catch { missing = true }
+  if (missing) console.log('ok   assertApproved 拒绝缺少 APPROVALS.json')
+  else { failed++; console.log('FAIL assertApproved 拒绝缺少 APPROVALS.json') }
+
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(join(dir, 'APPROVALS.json'), JSON.stringify({
+    mode: 'standard',
+    stages: {
+      requirements: { label: '需求', status: 'approved' },
+      delivery: { label: '交付清单', status: 'pending' },
+      start: { label: '开工', status: 'pending' },
+    },
+  }))
+  const report = readApprovals(scene)
+  if (report.status === 'pending' && report.missing.includes('交付清单')) {
+    console.log('ok   readApprovals 报出缺失的交付清单')
+  } else { failed++; console.log('FAIL readApprovals 报出缺失的交付清单') }
+
+  let blocked = false
+  try { assertApproved(scene) } catch { blocked = true }
+  if (blocked) console.log('ok   assertApproved 拒绝 pending 阶段')
+  else { failed++; console.log('FAIL assertApproved 拒绝 pending 阶段') }
+}
+
+// —— importFresh：改文件后按 mtime 重新 import（热加载的基础） ——
+{
+  const dir = mkdtempSync(join(tmpdir(), 'dsh-fresh-'))
+  const file = join(dir, 'mod.mjs')
+  const url = new URL(`file://${file}`)
+  writeFileSync(file, 'export const value = 1\n')
+  const first = await importFresh(url)
+  writeFileSync(file, 'export const value = 2\n')
+  utimesSync(file, new Date(), new Date(Date.now() + 2000))
+  const second = await importFresh(url)
+  if (first.value === 1 && second.value === 2) {
+    console.log('ok   importFresh 按 mtime 重新加载')
+  } else {
+    failed++
+    console.log('FAIL importFresh 按 mtime 重新加载')
+  }
+}
+
+if (failed > 0) {
+  console.error(`\n${failed} test(s) failed`)
+  process.exit(1)
+}
+console.log('\ntest-ops passed')

package/scripts/test-plan.mjs

@@ -0,0 +1,94 @@
+import assert from 'node:assert/strict'
+import { planQuestions } from './plan-questions.mjs'
+
+let failed = 0
+function test(name, fn) {
+  try {
+    fn()
+    console.log(`ok   ${name}`)
+  } catch (error) {
+    failed++
+    console.log(`FAIL ${name}`)
+    console.error(`     ${String(error.message).split('\n')[0]}`)
+  }
+}
+
+const vertical = planQuestions('做一条竖屏抖音短片，讲导数，要旁白')
+
+test('竖屏 + 旁白：已推断的画幅/交付不再问', () => {
+  const ids = vertical.questions.map((q) => q.id)
+  assert.deepEqual(ids, ['style', 'audience', 'narration'])
+  assert.equal(vertical.assumptions.aspect, '9:16')
+  assert.equal(vertical.assumptions.delivery, 'narrated')
+  assert.equal(vertical.assumptions.captions, true)
+})
+
+test('风格选项来自路由，至少两个', () => {
+  const style = vertical.questions.find((q) => q.id === 'style')
+  assert.ok(style)
+  assert.ok(style.options.length >= 2)
+  assert.match(style.options[0].label, /数据叙事/)
+})
+
+test('受众选项按竖屏平台排序', () => {
+  const audience = vertical.questions.find((q) => q.id === 'audience')
+  assert.ok(audience)
+  assert.match(audience.options[0].label, /大众科普/)
+  assert.equal(vertical.assumptions.audience, 'general')
+})
+
+test('旁白给语言 + 声音选项', () => {
+  const narration = vertical.questions.find((q) => q.id === 'narration')
+  assert.ok(narration)
+  assert.match(narration.options[0].label, /中文 · 中性/)
+  assert.equal(vertical.assumptions.narration.voice, 'neutral')
+})
+
+test('点名风格时不再问风格', () => {
+  const named = planQuestions('用 3b1b 讲矩阵')
+  assert.equal(named.questions.some((q) => q.id === 'style'), false)
+  assert.equal(named.assumptions.style, '3b1b')
+})
+
+test('几何证明：风格优先 blueprint，且不超过 4 题', () => {
+  const p = planQuestions('三角形 证明')
+  const style = p.questions.find((q) => q.id === 'style')
+  assert.ok(style)
+  assert.match(style.options[0].label, /蓝图/)
+  assert.ok(p.questions.length <= 4)
+})
+
+test('完全没命中时给默认 + 让你决定', () => {
+  const unknown = planQuestions('做个咖啡广告')
+  const style = unknown.questions.find((q) => q.id === 'style')
+  assert.ok(style)
+  assert.ok(style.options.some((o) => o.label.includes('让你决定')))
+  assert.equal(unknown.questions.some((q) => q.id === 'audience'), false)
+})
+
+test('时长从 brief 推断', () => {
+  assert.equal(planQuestions('做一条 30 秒的几何证明').assumptions.durationSec, 30)
+})
+
+test('brief 已说明画幅时不重复问', () => {
+  const p = planQuestions('做一条 16:9 的欧拉公式短片')
+  assert.equal(p.questions.some((q) => q.id === 'aspect'), false)
+  assert.equal(p.assumptions.aspect, '16:9')
+})
+
+test('gateMode 按体量/旁白推断', () => {
+  assert.equal(vertical.assumptions.gateMode, 'standard')
+  assert.equal(planQuestions('做一条 10 秒欧拉公式，静音').assumptions.gateMode, 'light')
+  assert.equal(planQuestions('做一条 90 秒的微积分讲解').assumptions.gateMode, 'full')
+})
+
+test('brief 已说明英文旁白时不重复问', () => {
+  const p = planQuestions('做一条英文旁白的导数短片')
+  assert.equal(p.questions.some((q) => q.id === 'narration'), false)
+})
+
+if (failed > 0) {
+  console.error(`\n${failed} test(s) failed`)
+  process.exit(1)
+}
+console.log('\ntest-plan passed')

package/scripts/test-route.mjs

@@ -0,0 +1,63 @@
+import assert from 'node:assert/strict'
+import { loadRegistry, routeStyle } from './route-style.mjs'
+
+const registry = loadRegistry()
+let failed = 0
+
+function test(name, fn) {
+  try {
+    fn()
+    console.log(`ok   ${name}`)
+  } catch (error) {
+    failed++
+    console.log(`FAIL ${name}`)
+    console.error(`     ${String(error.message).split('\n')[0]}`)
+  }
+}
+
+test('点名风格优先', () => {
+  const r = routeStyle('用 3b1b 风格讲单位圆', registry)
+  assert.equal(r.recommendation, '3b1b')
+  assert.equal(r.confidence, 'high')
+})
+
+test('几何证明路由到 blueprint', () => {
+  const r = routeStyle('三角形 证明', registry)
+  assert.equal(r.recommendation, 'blueprint')
+  assert.equal(r.confidence, 'high')
+})
+
+test('欧拉公式路由到 swiss', () => {
+  assert.equal(routeStyle('欧拉公式', registry).recommendation, 'swiss-motion')
+})
+
+test('科学解释路由到 whiteboard', () => {
+  assert.equal(routeStyle('为什么 天空 是 蓝的', registry).recommendation, 'whiteboard')
+})
+
+test('无命中时回退默认并要求确认', () => {
+  const r = routeStyle('做个咖啡广告', registry)
+  assert.equal(r.recommendation, registry.default)
+  assert.equal(r.needsConfirmation, true)
+})
+
+test('返回 top 3', () => {
+  assert.equal(routeStyle('切线', registry).ranked.length, 3)
+})
+
+test('registry 元数据与 Lemo style.json 对齐', () => {
+  const slugs = registry.styles.map((s) => s.slug).sort()
+  assert.deepEqual(slugs, ['3b1b', 'blueprint', 'dataviz', 'swiss-motion', 'whiteboard'])
+  for (const style of registry.styles) {
+    assert.ok(style.num, `${style.slug} 缺少 num`)
+    assert.ok(style.name_en && style.name_cn, `${style.slug} 缺名字`)
+    assert.ok(style.category_cn, `${style.slug} 缺分类`)
+    assert.ok(Array.isArray(style.uses) && style.uses.length > 0)
+  }
+})
+
+if (failed > 0) {
+  console.error(`\n${failed} test(s) failed`)
+  process.exit(1)
+}
+console.log('\ntest-route passed')

package/skills/animation-router/SKILL.md

@@ -5,6 +5,27 @@ description: 做代码动画/科普视频的总入口：先判题材（关系还
 
 # 总入口：先分题材，再选画面层
 
+## 0. 需求卡点（只问一次）
+
+开工前先推断；能从 brief 看出来的，不要问。需要问时：
+
+```bash
+node scripts/plan-questions.mjs "<brief>" --json
+```
+
+把返回的 `questions` 原样交给 `ask_user_question`，`assumptions` 作为默认值。规则：
+
+- **画幅**：brief 已说"竖屏/横屏/16:9"就跳过；没说才问，只给推断出的 2 个；
+- **交付**：brief 已说"要旁白"或"静音"就跳过；没说才问；
+- **风格**：从 `styles/registry.json` 路由出的 top 2–3；用户点名则跳过；
+- **受众**：只对数学/科学题材、且 brief 没提"高中/大学/大众"时问；选项按平台排（抖音→大众科普，B站→高中）；
+- **旁白**：只在交付为旁白、且 brief 没说"中文/英文/双语"时问；选项是"语言 + 声音"；
+- **时长**：从 brief 提取（"30 秒"/"1 分钟"），不单独问；
+- 最多 4 题，问完不再追问；没回答的按 `assumptions` 执行。**问完不等于开工**，接着进 §4 确认门。
+
+选项是**推出来的**，不是固定清单：画幅看平台线索，交付看有无旁白，风格看 registry 命中，受众看题材与平台。
+用户也可以直接在 `Other` 里写别的。
+
 ## 1. 判题材
 
 | 题材 | 观众记住 | 判据 |
@@ -34,25 +55,59 @@ description: 做代码动画/科普视频的总入口：先判题材（关系还
 
 三者都只是素材层；**需要交付时**再统一进 HyperFrames 工程，默认的极简模式不经过 HF。
 
-## 4. 固定顺序（默认极简，先帧后片）
+## 4. 确认门（阻塞，分档）
+
+写完整场景、出全片之前，按项目体量选一档，逐项确认。**不要跳步，不要用“我先做起来”代替确认。**
+
+| 模式 | 适用 | 阶段 |
+|---|---|---|
+| `light`（默认） | ≤15 s、无旁白、一个结论 | 需求 → **脚本+分镜（合并）** → 视觉 → 开工 |
+| `standard` | 15–60 s，或有旁白 | 需求 → 脚本 → 分镜 → 视觉 → 交付 → 开工 |
+| `full` | >60 s、多段、复杂旁白 | 需求 → 脚本 → 分镜 → **animatic** → 视觉 → 交付 → 开工 |
+
+- 脚本：逐句旁白、上屏文字、公式（先过 `formula_check`）；
+- 分镜：镜头号、起止秒、画面、运动、字幕/旁白、验收点；
+- 视觉：`DESIGN.md` + 3 张风格帧（真实代码，只出帧）；
+- 交付清单：画幅 / fps / 时长 / 文件 / 音频 / 字幕；
+- animatic：带时长的分镜 + 临时旁白，只在 `full` 或用户要求时做。
+
+用账本记录，别靠上下文记忆：
+
+```bash
+node scripts/approvals.mjs init <project> --mode light
+node scripts/approvals.mjs set <project> script_storyboard approved --note "用户确认"
+node scripts/approvals.mjs check <project>   # 未全部 approved 时退出 1
+```
+
+- `check` 不通过，不进入执行；
+- `start` 是独立阶段，只有用户**明确**说“可以开始 / 开始做 / 按这个执行 / 开工”才能置为 approved；
+- “好 / 可以 / 行”如果只是回答某个选项，**不算**整体开工；
+- 不确定就问：“脚本、分镜、风格帧都确认了，现在开始执行吗？”
+
+模板与清单见 [references/confirmation.md](references/confirmation.md)。
+
+## 5. 执行顺序（确认后才开始）
 
 ```
-1. DESIGN.md（design spec）      ← 先定颜色/字体/禁用项/参考
-2. formula_check（数学题材）      ← 每条上屏公式先验
-3. 画面 + motion_frames           ← 默认：按秒出 3–6 帧，看帧改，不渲染视频
-4. 分镜表（仅用户要时）            ← 关键镜头，用真实代码出帧，等确认
-5. motion_render                  ← 定稿后才编码 mp4
-6. HyperFrames composition        ← 字幕/旁白/混音/排版（需要时才进）
-7. hyperframes check / motion_probe ← 只检查已经生成的成片
+0. 最小场景：只放 6–8 个关键构图，motion_frames 出 sheet（首帧预算 ≤60s）
+1. 补全场景代码 + formula_check
+2. motion_frames（3–6 帧，局部改动后）
+3. 确认过的分镜帧（6–9 帧，若要）
+4. motion_render（draft → final）
+5. HyperFrames composition（字幕/旁白/混音；需要时才进）
+6. hyperframes check / motion_probe（只对最终成片跑一次）
 ```
 
-**默认不使用 HyperFrames**：只有需要字幕、旁白、混音、复杂图文编排时才进第 6 步。
-`motion_frames` 内部是 `manimgx inspect`，只画请求的时刻并做版式检查，几秒出图；
+`motion_frames` 内部是 `manimgx inspect`，只画请求的时刻并做版式检查；
 `motion_probe` 是给已有 mp4 做体检的，不要用它替代看帧。
 
-## 5. 四条硬规则
+## 6. 五条硬规则
 
-1. **没有 DESIGN.md 或参考语法，不开工**——否则每次都是同一个默认 look；
-2. **默认先帧后片**：先用 `motion_frames` 把画面改对，再决定要不要渲染；
-3. **字幕放在 composition 层**，不烧进 Manim 或 canvas；
-4. **公式先过 `formula_check`**，再进画面。
+1. **没有明确开工指令，不执行**：没听到“可以开始”就不写完整场景、不出全片；
+2. **没有 DESIGN.md 或参考语法，不开工**——否则每次都是同一个默认 look；
+3. **默认先帧后片**：先用 `motion_frames` 把画面改对，再决定要不要渲染；
+4. **字幕放在 composition 层**，不烧进 Manim 或 canvas；
+5. **公式先过 `formula_check`**，再进画面；
+6. **首帧预算 ≤60s**：先最小场景 + 构图 sheet，60s 看不到第一帧就停；
+7. **只做局部 edit**：改动 <50% 不重写整个文件；
+8. **图片/上下文预算**：每次迭代 1 张 sheet（约 960px），上下文 ≤100k。

package/skills/animation-router/references/confirmation.md

@@ -0,0 +1,82 @@
+# 确认门清单
+
+在写完整场景、出全片之前，逐项确认。每一轮只推进一项；用户改了哪项，就回到哪项重确认。
+
+## 0. 选模式
+
+| 模式 | 适用 | 阶段 |
+|---|---|---|
+| `light` | ≤15 s、无旁白、一个结论 | 需求 → 脚本+分镜 → 视觉 → 开工 |
+| `standard` | 15–60 s，或有旁白 | 需求 → 脚本 → 分镜 → 视觉 → 交付 → 开工 |
+| `full` | >60 s、多段、复杂旁白 | 需求 → 脚本 → 分镜 → animatic → 视觉 → 交付 → 开工 |
+
+`light` 把“脚本”和“分镜”合成一张表：每个镜头一行，写秒数、画面、上屏文字/公式。
+
+## 1. 需求
+
+- [ ] 画幅与像素：16:9 / 9:16 / 1:1
+- [ ] 时长
+- [ ] 交付：先出帧 / 静音 mp4 / 旁白 + 字幕（HF）
+- [ ] 风格（或“你决定”）
+- [ ] 受众（数学/科学题材）
+- [ ] 旁白语言与声音（仅旁白交付）
+
+## 2. 脚本 / 文案
+
+| # | 旁白（逐句） | 上屏文字 | 公式 | 备注 |
+|---|---|---|---|---|
+| 1 |  |  |  |  |
+
+- 公式先过 `formula_check`；
+- 旁白按“一句一个意思”拆，标出预计秒数；
+- 没有旁白就只填上屏文字与公式。
+
+## 3. 分镜
+
+| # | 起止秒 | 画面 | 运动 | 字幕 / 旁白 | 验收点 |
+|---|---|---|---|---|---|
+| 1 | 0.0–2.0 |  |  |  |  |
+
+- 镜头数按内容定，不为了凑时长加镜头；
+- 每个镜头写清“观众看到什么变化”；
+- 结论镜头要留够阅读时间（≥1.2 s）。
+
+## 4. 视觉
+
+- [ ] `DESIGN.md`：颜色、字体、禁用项、参考
+- [ ] 3 张风格帧：开场 / 转折 / 结论（真实代码出帧，不渲染视频）
+- [ ] 风格帧通过 `motion_frames` 的 layout 检查
+
+## 5. 交付清单
+
+- [ ] 尺寸 / fps / 时长
+- [ ] 文件：mp4 / `.srt` / 场景源码 / DESIGN.md / 分镜表
+- [ ] 音频：无 / 旁白 / 音乐；响度目标
+- [ ] 字幕：烧录 / 外挂 / 两者
+
+## 6. 账本
+
+```bash
+node scripts/approvals.mjs init <project> --mode light
+node scripts/approvals.mjs set <project> <stage> approved --note "用户确认"
+node scripts/approvals.mjs check <project>
+```
+
+`check` 未全部 approved 时退出 1；不能跳过前置阶段；`start` 必须是用户明确授权。
+
+## 7. 开工指令
+
+只有用户**明确**说出下面这类话，才进入执行：
+
+- “可以开始”
+- “开始做”
+- “按这个执行”
+- “开工”
+
+以下**不算**整体开工：
+
+- 对某个选项说“好 / 可以 / 行”；
+- 确认了脚本或分镜；
+- 说“看着办”但没有明确授权执行。
+
+不确定时问一句：“脚本、分镜、风格帧都确认了，现在开始执行吗？”