dsh-motion 0.1.1 → 0.3.0

package/lib/index.js

@@ -1,10 +1,11 @@
 /**
  * dsh-motion —— 代码生成的数学 / 科普动画
  *
- * 四个工具：
+ * 五个工具：
  *   motion_doctor   环境自检（先跑这个）
+ *   motion_frames   极简模式：直接从场景出帧（默认，不生成视频）
  *   motion_render   渲染 Manim / manimgx 场景
- *   motion_probe    抽帧自检（空镜 / 过曝）
+ *   motion_probe    成片抽帧自检（空镜 / 过曝）
  *   formula_check   公式恒等校验（sympy）
  *
  * 知识层在 skills/ 里：animation-router / design-spec / qa-rubric。
@@ -14,8 +15,12 @@ import { appendFileSync, mkdirSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 
-import { doctor } from './doctor.js'
-import { checkMath, probeVideo, renderScene } from './ops.js'
+import { importFresh } from './fresh.js'
+
+const OPS_URL = new URL('./ops.js', import.meta.url)
+const DOCTOR_URL = new URL('./doctor.js', import.meta.url)
+
+const ops = () => importFresh(OPS_URL)
 
 export const name = 'motion'
 export const inject = ['tools']
@@ -47,12 +52,42 @@ export function apply(ctx, config = {}) {
     output: textOutput,
     timeoutMs: 120_000,
     async execute() {
+      const { doctor } = await importFresh(DOCTOR_URL)
       const result = await doctor(config)
       log(`doctor ready=${JSON.stringify(result.ready)}`)
       return JSON.stringify(result, null, 2)
     },
   })
 
+  ctx.tools.register({
+    name: 'motion_frames',
+    description:
+      '极简模式（默认先用它）：直接从场景渲染关键帧，不生成视频、不用 HyperFrames。返回 storyboard PNG 路径与 layout 问题，几秒完成；先看帧改画面，满意后再决定是否渲染。',
+    parameters: {
+      type: 'object',
+      properties: {
+        file: { type: 'string', description: '场景 .py 文件的绝对路径' },
+        scene: { type: 'string', description: '场景类名；文件里只有一个场景时可省略' },
+        times: {
+          type: 'array',
+          items: { type: 'string' },
+          description: '要看的时间点（秒）或 "end"，如 ["1.2","4.5","end"]；省略则采样每个 play 的结束帧',
+        },
+        out: { type: 'string', description: 'storyboard PNG 输出路径，默认与场景同目录' },
+      },
+      required: ['file'],
+      additionalProperties: false,
+    },
+    output: textOutput,
+    timeoutMs: 300_000,
+    async execute(args) {
+      const { inspectFrames } = await ops()
+      const result = await inspectFrames(config, args)
+      log(`frames ${result.file} samples=${result.requestedTimes.length || 'auto'} issues=${result.layoutProblems.length} ${result.wallSec}s`)
+      return JSON.stringify(result, null, 2)
+    },
+  })
+
   ctx.tools.register({
     name: 'motion_render',
     description:
@@ -85,6 +120,7 @@ export function apply(ctx, config = {}) {
     output: textOutput,
     timeoutMs: 900_000,
     async execute(args) {
+      const { renderScene } = await ops()
       const result = await renderScene(config, args)
       log(`render ${result.output} ${result.durationSec}s engine=${result.engine} problems=${result.layoutProblems.length}`)
       return JSON.stringify(result, null, 2)
@@ -94,7 +130,7 @@ export function apply(ctx, config = {}) {
   ctx.tools.register({
     name: 'motion_probe',
     description:
-      '成片自检：等间隔抽帧拼成 contact sheet，并报告全黑/过曝的空镜帧。正式交付前先跑一遍，看过图再收工。',
+      '成片自检：已有 mp4 时等间隔抽帧拼 contact sheet，报告全黑/过曝的空镜。写场景阶段请用 motion_frames 直接看帧，不必先渲染视频。',
     parameters: {
       type: 'object',
       properties: {
@@ -108,6 +144,7 @@ export function apply(ctx, config = {}) {
     output: textOutput,
     timeoutMs: 300_000,
     async execute(args) {
+      const { probeVideo } = await ops()
       const result = await probeVideo(config, args)
       log(`probe ${result.video} frames=${result.framesAnalyzed} blank=${result.blankFrames.length}`)
       return JSON.stringify(result, null, 2)
@@ -130,11 +167,12 @@ export function apply(ctx, config = {}) {
     output: textOutput,
     timeoutMs: 60_000,
     async execute(args) {
+      const { checkMath } = await ops()
       const result = await checkMath(config, args)
       log(`formula_check equal=${result.equal}`)
       return JSON.stringify(result, null, 2)
     },
   })
 
-  log('registered 4 tools')
+  log('registered 5 tools')
 }

package/lib/ops.js

@@ -97,6 +97,8 @@ export async function renderScene(config, args) {
   if (post.enabled) {
     const finalOut = out.replace(/\.mp4$/, '') + '-post.mp4'
     await applyPost(config, out, finalOut, fps, post)
+    // post 会改帧率与体积：摘要必须以成片为准，而不是中间产物
+    Object.assign(summary, await probeOutput(config, finalOut))
     summary.post = { ...post, output: finalOut }
     summary.output = finalOut
     summary.video = finalOut
@@ -106,7 +108,8 @@ export async function renderScene(config, args) {
   return summary
 }
 
-function normalizePost(raw) {
+/** 归一化后期参数：枚举/上限之外的值一律夹到合法区间，交给 ffmpeg 之前就把脏输入挡掉。 */
+export function normalizePost(raw) {
   const p = raw && typeof raw === 'object' ? raw : {}
   const subframes = clampInt(p.subframes ?? 1, 1, 8)
   const grain = p.grain === true ? 7 : Number(p.grain ?? 0)
@@ -137,6 +140,132 @@ async function applyPost(config, input, output, fps, post) {
   ], { timeout: 900_000, maxBuffer: 8 * 1024 * 1024 })
 }
 
+/** 按帧数选一个接近方形的网格：2→2x1、4→2x2、6→3x2、12→4x3、24→6x4。 */
+export function tileGrid(n) {
+  const cols = n <= 2 ? 2 : n <= 4 ? 2 : n <= 6 ? 3 : n <= 9 ? 3 : n <= 12 ? 4 : n <= 16 ? 4 : 6
+  return `${cols}x${Math.ceil(n / cols)}`
+}
+
+/** 解析 signalstats 的 metadata=print 输出：每帧一段 `frame:N` + 若干 `lavfi.signalstats.*`。 */
+export function parseSignalStats(text) {
+  const frames = []
+  let current
+  for (const raw of text.split('\n')) {
+    const line = raw.trim()
+    const head = /^frame:(\d+)/.exec(line)
+    if (head) {
+      current = { frame: Number(head[1]) }
+      frames.push(current)
+      continue
+    }
+    const kv = /^lavfi\.signalstats\.(YMIN|YMAX|YAVG)=([\d.]+)$/.exec(line)
+    if (kv && current) current[kv[1].toLowerCase()] = Number(kv[2])
+  }
+  return frames
+}
+
+/**
+ * 归一化帧时间点：秒数或 "end"。`motion_frames` 只画这些帧，不编码视频。
+ * 上限 24 个：再多也看不过来，而且 manimgx 会拆成多张 sheet。
+ */
+export function normalizeTimes(raw) {
+  const list = raw == null ? [] : Array.isArray(raw) ? raw : [raw]
+  if (list.length > 24) throw new Error('times 最多 24 个')
+  return list.map((item) => {
+    if (typeof item === 'string' && item.trim().toLowerCase() === 'end') return 'end'
+    const n = Number(item)
+    if (!Number.isFinite(n) || n < 0 || n > 3600) {
+      throw new Error(`无效时间点：${item}（秒或 "end"）`)
+    }
+    return String(n)
+  })
+}
+
+/** 解析 manimgx inspect 的 stdout：片名/时长、storyboard 路径、layout 问题。 */
+export function parseInspectOutput(stdout) {
+  const text = String(stdout ?? '')
+  const head = text.match(/^(.+?):\s+([A-Za-z_][\w.]*),\s+([\d.]+)\s*s,\s+(\d+)\s+plays?\b/m)
+  const sheet = text.match(/^storyboard:\s*(.+)$/m)
+  const layout = text.match(/^layout:\s*(.+)$/m)
+  const problems = [...text.matchAll(/^\s*\[\d+\]\s+(.+)$/gm)].map((m) => m[1].trim())
+  return {
+    scene: head?.[2] ?? null,
+    durationSec: head ? Number(head[3]) : null,
+    plays: head ? Number(head[4]) : null,
+    storyboard: sheet
+      ? sheet[1].split(',').map((s) => s.trim()).filter(Boolean)
+      : [],
+    layout: layout ? layout[1].trim() : null,
+    layoutOk: layout ? /no problems/.test(layout[1]) : null,
+    layoutProblems: problems,
+  }
+}
+
+/**
+ * 极简模式：直接从场景出帧，不生成视频、不依赖 HyperFrames。
+ *
+ * manimgx inspect 只画请求的时刻并做版式检查，通常几秒完成；返回的
+ * storyboard PNG 可以直接交给模型读图。退出码 1 表示有 layout 问题，
+ * 仍是有效结果，不当失败。
+ */
+export async function inspectFrames(config, args) {
+  const file = resolve(args.file)
+  if (!existsSync(file)) throw new Error(`场景文件不存在: ${file}`)
+
+  requireVenv(config)
+  const venv = resolveVenv(config)
+  const command = venvBinary(config, 'manimgx')
+  if (!existsSync(command)) {
+    throw new Error(
+      `找不到渲染器: ${command}\n请在 venv 里安装：${venvBinary(config, 'pip')} install manimgx`,
+    )
+  }
+
+  const times = normalizeTimes(args.times)
+  const out = args.out ? resolve(args.out) : null
+  const argv = ['inspect', file, ...(args.scene ? [args.scene] : [])]
+  if (times.length) argv.push('-t', times.join(','))
+  if (out) argv.push('-o', out)
+
+  const binDir = join(venv, process.platform === 'win32' ? 'Scripts' : 'bin')
+  const started = Date.now()
+  let stdout = ''
+  try {
+    ({ stdout } = await exec(command, argv, {
+      timeout: 300_000,
+      maxBuffer: 8 * 1024 * 1024,
+      cwd: dirname(file),
+      env: {
+        ...process.env,
+        PATH: `${binDir}${process.platform === 'win32' ? ';' : ':'}${process.env.PATH ?? ''}`,
+      },
+    }))
+  } catch (error) {
+    // 有 layout 问题时 manimgx 返回 1，stdout 仍然是完整报告。
+    if (error.code !== 1 || !error.stdout) throw error
+    stdout = error.stdout
+  }
+
+  const parsed = parseInspectOutput(stdout)
+  return {
+    file,
+    mode: 'frames',
+    requestedTimes: times,
+    ...parsed,
+    wallSec: Number(((Date.now() - started) / 1000).toFixed(1)),
+  }
+}
+
+/**
+ * 空镜判据：yuv420p limited range 黑=16、白=235，用接近 0/255 的阈值永远判不出来。
+ * 看内容范围而不是平均值：全黑帧 YMAX 仍在 16 附近，全白帧 YMIN 在 235 附近。
+ */
+export function isBlankFrame(frame) {
+  if (Number.isFinite(frame.ymax) && frame.ymax < 20) return true
+  if (Number.isFinite(frame.ymin) && frame.ymin > 230) return true
+  return false
+}
+
 /** 抽帧自检：等间隔取 n 帧拼 contact sheet，并报告全黑/过曝帧。 */
 export async function probeVideo(config, args) {
   const video = resolve(args.video)
@@ -146,29 +275,56 @@ export async function probeVideo(config, args) {
   const ffmpeg = binaryOf(config, 'ffmpeg')
 
   const duration = await readDuration(config, video)
-  const step = Math.max(1, Math.floor((duration * 30) / n))
+  // 用 fps 滤镜按整段时长重采样：与源帧率无关，60 fps 的成片也不会只覆盖前半段
+  const rate = (n / Math.max(duration, 0.001)).toFixed(6)
   await exec(ffmpeg, [
     '-y', '-loglevel', 'error', '-i', video,
-    '-vf', `select='not(mod(n\\,${step}))',scale=270:-2,tile=4x3:margin=6:padding=4:color=0x222222`,
+    '-vf', `fps=${rate},scale=270:-2,tile=${tileGrid(n)}:margin=6:padding=4:color=0x222222`,
     '-frames:v', '1', sheet,
   ], { timeout: 120_000 })
 
   const { stdout } = await exec(ffmpeg, [
-    '-hide_banner', '-i', video, '-vf', 'signalstats,metadata=print:key=lavfi.signalstats.YAVG:file=-',
+    '-hide_banner', '-i', video, '-vf', 'signalstats,metadata=print:file=-',
     '-f', 'null', '-',
-  ], { timeout: 120_000, maxBuffer: 32 * 1024 * 1024 })
-  const avgs = [...stdout.matchAll(/YAVG=([\d.]+)/g)].map((m) => Number(m[1]))
-  const blank = avgs.map((v, i) => ({ frame: i, yavg: v })).filter((x) => x.yavg < 8 || x.yavg > 250)
+  ], { timeout: 120_000, maxBuffer: 64 * 1024 * 1024 })
+  const frames = parseSignalStats(stdout)
+  const blank = frames
+    .filter(isBlankFrame)
+    .map(({ frame, yavg, ymin, ymax }) => ({ frame, yavg, ymin, ymax }))
 
   return {
     video,
     durationSec: duration,
-    framesAnalyzed: avgs.length,
+    framesAnalyzed: frames.length,
+    // 只回前 8 条明细，但总数要能看到——否则 300 个空镜和 3 个空镜长得一样
+    blankCount: blank.length,
     contactSheet: sheet,
     blankFrames: blank.slice(0, 8),
   }
 }
 
+/** 用 ffprobe 重新读成片参数（post 之后帧率、时长、体积都可能与中间产物不同）。 */
+export async function probeOutput(config, file) {
+  const { stdout } = await exec(binaryOf(config, 'ffprobe'), [
+    '-v', 'error', '-select_streams', 'v:0',
+    '-show_entries', 'stream=width,height,r_frame_rate:format=duration,size',
+    '-of', 'json', file,
+  ], { timeout: 60_000, maxBuffer: 1024 * 1024 })
+  const data = JSON.parse(stdout)
+  const stream = data.streams?.[0] ?? {}
+  const [num, den = '1'] = String(stream.r_frame_rate ?? '0/1').split('/')
+  const rate = Number(num) / Number(den)
+  const duration = Number(data.format?.duration)
+  const size = Number(data.format?.size)
+  return {
+    durationSec: Number.isFinite(duration) ? Math.round(duration * 100) / 100 : null,
+    width: stream.width ?? null,
+    height: stream.height ?? null,
+    fps: Number.isFinite(rate) && rate > 0 ? Math.round(rate * 100) / 100 : null,
+    megabytes: Number.isFinite(size) ? Math.round(size / 1e5) / 10 : null,
+  }
+}
+
 async function readDuration(config, video) {
   try {
     const { stdout } = await exec(binaryOf(config, 'ffprobe'), [

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-motion",
-  "version": "0.1.1",
-  "description": "Code-generated math & science animations for DeepSeek Harness: render Manim clips, probe frames, verify formulas.",
+  "version": "0.3.0",
+  "description": "Code-generated math & science animations for DeepSeek Harness: frames-first preview, Manim clips, formula checks.",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -15,6 +15,8 @@
   "files": [
     "lib",
     "skills",
+    "styles",
+    "docs",
     "cordis.patch.yml",
     "README.md",
     "LICENSE",
@@ -36,9 +38,14 @@
   },
   "scripts": {
     "check": "node --check lib/index.js && node --check lib/ops.js && node --check lib/env.js && node --check lib/doctor.js",
+    "test": "node scripts/test-ops.mjs && node scripts/test-route.mjs",
     "smoke": "node scripts/smoke.mjs",
+    "dev": "node scripts/dev.mjs",
+    "route": "node scripts/route-style.mjs",
+    "styles:index": "node scripts/build-style-index.mjs",
+    "styles:check": "node scripts/build-style-index.mjs --check",
     "check:meta": "node scripts/check-meta.mjs",
-    "prepack": "npm run check && npm run smoke"
+    "prepack": "npm run check && npm test && npm run smoke"
   },
   "repository": {
     "type": "git",

package/skills/animation-router/SKILL.md

@@ -12,7 +12,19 @@ description: 做代码动画/科普视频的总入口：先判题材（关系还
 | 数学讲解 | 一个**关系** | 公式、坐标、推导、表格 |
 | 科普叙事 | 一个**意象** | 画面、比喻、节奏、材质 |
 
-## 2. 选画面层
+## 2. 选风格
+
+先读 `styles/registry.json`，再按顺序：
+
+1. **用户点名**（"用 3b1b / 瑞士动态排版"）→ 直接用，不再打分；
+2. 没有点名 → `node scripts/route-style.mjs "<题材>" --json`；
+3. `confidence: high` → 写进 `DESIGN.md` 的 `style:`；
+4. `medium` / `low` / `needsConfirmation: true` → 给用户 top 2–3 和理由，等确认；
+5. 完全不命中 → 默认 `swiss-motion`，并说明这是默认。
+
+不要用"感觉像"选风格；理由是 registry 的关键词/uses 命中，不是形容词。
+
+## 3. 选画面层
 
 | 画面层 | 适合 | 不用它的理由 |
 |---|---|---|
@@ -20,21 +32,27 @@ description: 做代码动画/科普视频的总入口：先判题材（关系还
 | Canvas 2D 逐帧 | 光、影、粒子、材质、转场 | 文字排版成本高 |
 | HTML / SVG | 排版、图文、简单图示 | 做不出辉光与颗粒 |
 
-三者都只是素材层；**交付统一在 HyperFrames 工程里完成**。
+三者都只是素材层；**需要交付时**再统一进 HyperFrames 工程，默认的极简模式不经过 HF。
 
-## 3. 固定顺序
+## 4. 固定顺序（默认极简，先帧后片）
 
 ```
-1. DESIGN.md（design spec）  ← 先定颜色/字体/禁用项
-2. 分镜表（storyboard）      ← 拍/秒/画面/旁白/验收点，先给用户确认
-3. 画面
-4. hyperframes check          ← 0 error 才算过
-5. motion_probe               ← 抽 12 帧看空镜/叠字
-6. 旁白 + 字幕 + −14 LUFS
+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 ← 只检查已经生成的成片
 ```
 
-## 4. 三条硬规则
+**默认不使用 HyperFrames**：只有需要字幕、旁白、混音、复杂图文编排时才进第 6 步。
+`motion_frames` 内部是 `manimgx inspect`，只画请求的时刻并做版式检查，几秒出图；
+`motion_probe` 是给已有 mp4 做体检的，不要用它替代看帧。
+
+## 5. 四条硬规则
 
 1. **没有 DESIGN.md 或参考语法，不开工**——否则每次都是同一个默认 look；
-2. **字幕放在 composition 层**，不烧进 Manim 或 canvas；
-3. **公式先过 `formula_check`**，再进画面。
+2. **默认先帧后片**：先用 `motion_frames` 把画面改对，再决定要不要渲染；
+3. **字幕放在 composition 层**，不烧进 Manim 或 canvas；
+4. **公式先过 `formula_check`**，再进画面。

package/skills/design-spec/SKILL.md

@@ -19,6 +19,10 @@ HyperFrames 的 look 文档原话：**不给外部输入，相同的 brief 每
 | 4 | 主题自身的世界 | ✅ 年代、材质、展示场景 |
 | 5 | 官方预设（preset） | ⚠️ 幻灯片语言，仅点名或做 deck 时用 |
 
+## 先路由
+
+写 spec 之前先确定风格：`node scripts/route-style.mjs "<题材>"`。点名风格优先；没有点名就按 `styles/registry.json` 打分；`high` 才直接写，`medium`/`low` 先给用户 top 2–3 确认。
+
 ## 最小形态
 
 ```markdown
@@ -52,10 +56,38 @@ spacing: { margin: 140, rule: 2 }
 - 具体到某类图版、某支片、某个年代的印刷品
 ```
 
-## 三种已验证的语言
+## 先出三张风格帧
+
+DESIGN.md 写完不等于风格成立。挑 3 个关键时刻（开场、转折、结论），用**真实绘制代码**出帧，对照 spec 检查：
+
+- 用 `motion_frames` 直接出帧，不渲染视频；
+- 三张里至少一张是 signature shot；
+- 两轮还不对，就换更接近的参考语法，而不是继续调参。
+
+## 八种已验证的语言
 
 | 语言 | 适合 | 关键手段 |
 |---|---|---|
 | 纸感植物图版 | 生物 / 博物 | 纸纤维、水洗叠色、墨线、引线标注 |
 | 暗场发光 | 物理 / 天文 / 微观 | 近黑底、细线辉光、粒子、颗粒 + 暗角 |
 | 编辑排版 | 数学 / 数据 / 概念 | 网格、字阶、单一强调色 |
+| 瑞士动态排版 | 公式 / 概念 | 12 栏网格、单一信号色、精确缓动 |
+| 数据叙事 | 数据 / 科学 | 图表操作即转场、注释钉在数据上、蓝红语义 |
+| 蓝图工程制图 | 几何 / 工程 | 青晒纸、白线、制图顺序、一次红印章 |
+| 白板讲解 | 科学 / 课程 | 暖白板、三色马克笔、书写顺序 |
+| 3b1b 暗场数学 | 线代 / 微积分 | 近黑底、蓝黄语义、先直觉后公式 |
+
+本仓库现有五套，除 `3b1b` 外均改编自 [Lemo-Opuscar](https://github.com/lemomo-ai/lemo-opuscar)（MIT）：
+
+- [`styles/swiss-motion/`](../../styles/swiss-motion/)：公式/排版，默认；
+- [`styles/dataviz/`](../../styles/dataviz/)：图表/数据；
+- [`styles/blueprint/`](../../styles/blueprint/)：几何/工程；
+- [`styles/whiteboard/`](../../styles/whiteboard/)：科学/白板讲解；
+- [`styles/3b1b/`](../../styles/3b1b/)：暗场数学（Manim 社区 3b1b skill）。
+
+规范在 `STYLE.md`，数值在 `tokens.json`，`theme.py` 提供 `apply_config()` 与 `backdrop()`。
+项目 `DESIGN.md` 里写 `style: swiss-motion`（或 `dataviz` / `blueprint` / `whiteboard` / `3b1b`）与 `style_version: 1.0.0`。
+
+参考与示例统一从 HyperFrames 取：[examples](https://hyperframes.heygen.com/examples)、
+[catalog](https://hyperframes.heygen.com/catalog)、[frame.md](https://hyperframes.heygen.com/prompting/design-systems)。
+本仓库不再内置分集/样片。

package/skills/qa-rubric/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qa-rubric
-description: 代码动画交付前的自检清单：环境、公式、工程、画面、音频、字幕。渲染完但还没交付时使用。
+description: 代码动画的自检清单：环境、公式、画面、音频、字幕。默认先看帧（motion_frames），有成片时才查视频。
 ---
 
 # 交付前自检
@@ -14,28 +14,34 @@ description: 代码动画交付前的自检清单：环境、公式、工程、
 - 所有上屏公式先过 `formula_check`；
 - 逐条对照代码与画面，确认没有手改过的常数。
 
-## 3. 工程
+## 3. 工程（仅当用了 HyperFrames）
 
 ```bash
 npx hyperframes check
 ```
 
 - 0 error 才算过；
-- 关注 lint（缺 `@font-face`）、layout（文字裁切/重叠）、contrast（对比度 < 3:1）。
+- 关注 lint（缺 `@font-face`）、layout（文字裁切/重叠）、contrast（对比度 < 3:1）；
+- 没进 HF 的极简流程跳过本节。
 
 ## 4. 画面
 
-```bash
-motion_probe --video <mp4>
+**先帧后片**：场景阶段用 `motion_frames`，直接看 manimgx 画出的帧，不等视频。
+
+```jsonc
+// motion_frames
+{ "file": "/abs/path/scene.py", "times": ["1.2", "4.5", "end"] }
 ```
 
-- 看 contact sheet：无叠字、无出画、无空白帧；
-- `blankFrames` 里的帧逐一看过再决定是否重渲。
+- 返回的 storyboard PNG 逐张看过：无叠字、无出画、字号可读；
+- `layoutProblems` 每一条都要处理或明确接受；
+- 已经生成了 mp4 时，才用 `motion_probe` 抽 contact sheet + 查 `blankFrames`；
+- 用了 HyperFrames 的项目，用 `npx hyperframes snapshot <project> --at 2.9,10.4` 抽帧，不要先 render 再截图。
 
 ## 5. 音频
 
 - 旁白最后一字早于结论画面；
-- 响度 ≈ −14 LUFS（±1），真峰值 ≤ −1.5 dBTP；
+- 响度 ≈ −14 LUFS（±1），真峰值 ≤ −1 dBTP；具体以该片 STYLE.md 为准；
 - 没有爆音、没有截断。
 
 ## 6. 字幕

package/styles/3b1b/STYLE.md

@@ -0,0 +1,68 @@
+---
+name: 3b1b
+version: 1.0.0
+source: https://github.com/subinium/3b1b-style-animation-skill
+license: MIT（上游风格 skill）；非 3Blue1Brown 官方项目
+status: adapted
+---
+
+# 3Blue1Brown Style · 3b1b
+
+> 配色表取自 [subinium/3b1b-style-animation-skill](https://github.com/subinium/3b1b-style-animation-skill)（MIT）；
+> 教学法与动画模式参考 [adithya-s-k/manim_skill](https://github.com/adithya-s-k/manim_skill)（MIT，约 1.2k stars，是这类 skill 里用得最多的）。
+> 本文件是改编，不是原样复制；只保留不变量，实现换成 manimgx。
+
+## 1. 定位
+
+先建立直觉，再给公式。画面为“暗场 + 蓝黄高亮”的数学解释：
+
+- 适合：线性代数、微积分、概率、神经网络、算法；
+- 不适合：没有“为什么”的产品宣传、角色叙事。
+
+## 2. 不变量
+
+| 项 | 规则 |
+|---|---|
+| 底色 | `#1c1c1c`（近黑灰，**不用纯黑**） |
+| 主色 | 蓝 `#3b82f6`：主对象、向量、节点 |
+| 强调 | 黄 `#fbbf24`：高亮、结论、公式 |
+| 语义色 | 绿 `#22c55e` 正 / 红 `#ef4444` 负 / 灰 `#9ca3af` 非活动 |
+| 公式 | 黄色 `#fde047` 或白色；一屏最多 4–5 种颜色 |
+| 字体 | 无衬线（Noto Sans）；公式 New Computer Modern |
+| 运动 | `Create` / `FadeIn` / `Transform`；相关元素**同时**出现（`LaggedStartMap` 式级联），不要一个个 `play()` |
+| 收尾 | 结尾至少 `wait(2)`，给结论停留 |
+
+## 3. 教学法
+
+1. **Hook**：先问一个有意思的问题；
+2. **Intuition**：用图形建立直觉，先不写公式；
+3. **Concrete**：用一个具体数字走一遍；
+4. **Formalization**：最后才给公式/命名。
+
+## 4. manimgx 映射
+
+- `theme.py`：`apply_config()` 设 `#1c1c1c`、`backdrop()` 返回平涂底；
+- 用 `Axes`、`Dot`、`Arrow`、`Line`、`always_redraw` 做旋转/投影/变换；
+- 用 `MathTex` 排版公式，`Text` 做标题与注释；
+- manimgx 的 `Write` 已经足够接近 Manim 的 `Write`；不需要 LaTeX 环境。
+
+## 5. Do / Don't
+
+**Do**
+
+- 先画“正在发生什么”，再写“它叫什么”；
+- 蓝=对象，黄=高亮/结论；颜色有语义；
+- 一次只讲一个变换；结尾停 2 秒。
+
+**Don't**
+
+- 不用纯黑 `#000000`；
+- 不用高饱和纯红/纯绿/纯蓝；
+- 不在建立直觉前抛公式；
+- 不把每个元素拆成单独的 `play()`。
+
+## 6. 与上游的差异
+
+- 上游是 ManimCE/ManimGL skill，包含 40+ 条规则；这里只抽取配色、运动与教学法；
+- 上游使用 Manim 的 `LaggedStartMap` 等 API；manimgx 用 `AnimationGroup`/`LaggedStart` 近似；
+- 不是 3Blue1Brown 官方风格指南，只是社区通行做法的整理。

package/styles/3b1b/style.json

@@ -0,0 +1,50 @@
+{
+  "slug": "3b1b",
+  "en": "3Blue1Brown Style",
+  "cn": "3b1b 数学动画",
+  "category_en": "Math explainer",
+  "category_cn": "数学讲解",
+  "uses": [
+    "Linear algebra",
+    "Calculus",
+    "Probability",
+    "Neural networks"
+  ],
+  "source": "https://github.com/subinium/3b1b-style-animation-skill",
+  "secondary_source": "https://github.com/adithya-s-k/manim_skill",
+  "license": "MIT (style skills); unofficial tribute",
+  "implementation": "manimgx (theme.py + tokens.json)",
+  "num": "05",
+  "film": "Rotation on the Unit Circle",
+  "line": "A rotation on the unit circle that lands on e^{iθ} = cosθ + i sinθ.",
+  "line_cn": "单位圆上的一次旋转，收束到 e^{iθ} = cosθ + i sinθ。",
+  "uses_cn": [
+    "线代",
+    "微积分",
+    "概率",
+    "神经网络"
+  ],
+  "keywords": [
+    "向量",
+    "矩阵",
+    "特征值",
+    "旋转",
+    "复数",
+    "单位圆",
+    "线代",
+    "概率",
+    "微积分",
+    "神经网络"
+  ],
+  "avoid": [
+    "产品发布",
+    "纯排版"
+  ],
+  "demo": "showcase/3b1b-unit-circle",
+  "demo_duration_sec": 10.3,
+  "aspect": [
+    "16:9"
+  ],
+  "fps": 30,
+  "complexity": "medium"
+}