dsh-motion 0.1.1 → 0.2.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.2.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,11 @@
   },
   "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",
     "smoke": "node scripts/smoke.mjs",
+    "dev": "node scripts/dev.mjs",
     "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

@@ -20,21 +20,27 @@ description: 做代码动画/科普视频的总入口：先判题材（关系还
 | Canvas 2D 逐帧 | 光、影、粒子、材质、转场 | 文字排版成本高 |
 | HTML / SVG | 排版、图文、简单图示 | 做不出辉光与颗粒 |
 
-三者都只是素材层；**交付统一在 HyperFrames 工程里完成**。
+三者都只是素材层；**需要交付时**再统一进 HyperFrames 工程，默认的极简模式不经过 HF。
 
-## 3. 固定顺序
+## 3. 固定顺序（默认极简，先帧后片）
 
 ```
-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 做体检的，不要用它替代看帧。
+
+## 4. 四条硬规则
 
 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

@@ -52,10 +52,34 @@ spacing: { margin: 140, rule: 2 }
 - 具体到某类图版、某支片、某个年代的印刷品
 ```
 
-## 三种已验证的语言
+## 先出三张风格帧
+
+DESIGN.md 写完不等于风格成立。挑 3 个关键时刻（开场、转折、结论），用**真实绘制代码**出帧，对照 spec 检查：
+
+- 用 `motion_frames` 直接出帧，不渲染视频；
+- 三张里至少一张是 signature shot；
+- 两轮还不对，就换更接近的参考语法，而不是继续调参。
+
+## 六种已验证的语言
 
 | 语言 | 适合 | 关键手段 |
 |---|---|---|
 | 纸感植物图版 | 生物 / 博物 | 纸纤维、水洗叠色、墨线、引线标注 |
 | 暗场发光 | 物理 / 天文 / 微观 | 近黑底、细线辉光、粒子、颗粒 + 暗角 |
 | 编辑排版 | 数学 / 数据 / 概念 | 网格、字阶、单一强调色 |
+| 瑞士动态排版 | 公式 / 概念 | 12 栏网格、单一信号色、精确缓动 |
+| 数据叙事 | 数据 / 科学 | 图表操作即转场、注释钉在数据上、蓝红语义 |
+| 蓝图工程制图 | 几何 / 工程 | 青晒纸、白线、制图顺序、一次红印章 |
+
+本仓库现有三套，全部改编自 [Lemo-Opuscar](https://github.com/lemomo-ai/lemo-opuscar)（MIT）：
+
+- [`styles/swiss-motion/`](../../styles/swiss-motion/)：公式/排版，默认；
+- [`styles/dataviz/`](../../styles/dataviz/)：图表/数据；
+- [`styles/blueprint/`](../../styles/blueprint/)：几何/工程。
+
+规范在 `STYLE.md`，数值在 `tokens.json`，`theme.py` 提供 `apply_config()` 与 `backdrop()`。
+项目 `DESIGN.md` 里写 `style: swiss-motion`（或 `dataviz` / `blueprint`）与 `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/README.md

@@ -0,0 +1,23 @@
+# 风格库
+
+可复用的视觉语言。当前有 3 套，全部**改编自 Lemo-Opuscar** 的公开风格（MIT），不是自创：
+
+| 风格 | 适合 | 来源 | 入口 |
+|---|---|---|---|
+| `swiss-motion` / 瑞士动态排版（默认） | 公式、定义、数据结论 | [Lemo](https://github.com/lemomo-ai/lemo-opuscar/tree/main/styles/swiss-motion) | [STYLE](swiss-motion/STYLE.md) · [tokens](swiss-motion/tokens.json) · [theme](swiss-motion/theme.py) |
+| `dataviz` / 数据叙事 | 趋势、比较、分布、科学数据 | [Lemo](https://github.com/lemomo-ai/lemo-opuscar/tree/main/styles/dataviz) | [STYLE](dataviz/STYLE.md) · [tokens](dataviz/tokens.json) · [theme](dataviz/theme.py) |
+| `blueprint` / 蓝图工程制图 | 几何证明、结构、尺寸关系 | [Lemo](https://github.com/lemomo-ai/lemo-opuscar/tree/main/styles/blueprint) | [STYLE](blueprint/STYLE.md) · [tokens](blueprint/tokens.json) · [theme](blueprint/theme.py) |
+
+## 约定
+
+- 每个风格目录：`style.json`（元数据）+ `STYLE.md`（不变量）+ `tokens.json` + `theme.py` + `preview.jpg`；
+- `STYLE.md` 是**改编**，必须在上游基础上写清楚差异；不复制 demo 代码；
+- 颜色、字体、时间表、音频以 `tokens.json` 为准；版面坐标与组件配方写在 `STYLE.md`；
+- 新片在自己的项目目录写 `DESIGN.md`，头部 `style: swiss-motion` + `style_version: 1.0.0`；
+- 参考与示例统一用 HyperFrames 的 [examples](https://hyperframes.heygen.com/examples) / [catalog](https://hyperframes.heygen.com/catalog)，不在仓库里放样片（`showcase/` 只放可复现的演示）。
+
+## 许可
+
+- 上游风格文档：MIT，署名 LemoLab；
+- 上游 demo 静帧：CC BY 4.0，商用需署名；
+- 本仓库的 `theme.py` / `tokens.json` / 场景代码：MIT。

package/styles/blueprint/STYLE.md

@@ -0,0 +1,59 @@
+---
+name: blueprint
+version: 1.0.0
+source: https://github.com/lemomo-ai/lemo-opuscar/tree/main/styles/blueprint
+license: MIT（上游风格文档）；demo 静帧 CC BY 4.0（LemoLab）
+status: adapted
+---
+
+# Blueprint · 蓝图 / 工程制图
+
+> 上游：Lemo-Opuscar `styles/blueprint`（MIT）。保留青晒纸、白线、制图顺序与一次红色印章；
+> 去掉了 WebGL 纸纹与 3D 投影。
+
+## 1. 定位
+
+工程图在青晒纸上活起来：普鲁士蓝上的白色技术线，按制图顺序画出，标注会动。
+
+- 适合：几何证明、工程结构、尺寸关系、专利/发明叙事；
+- 不适合：需要真实材质、角色表演、实拍的题材。
+
+## 2. 不变量
+
+| 项 | 规则 |
+|---|---|
+| 桌 | 深色绘图桌 `#0D1116` |
+| 纸 | 青晒蓝 `#18336B → #2A58A6`，可有轻微不均 |
+| 线 | 白 `#E7F0F9`；四种线宽（轮廓/细节/细/发丝）；虚线有制图含义 |
+| 印章 | 全片只有一个非蓝颜色：红 `#B5442E`，只盖一次 |
+| 字体 | 手写体注释（Chalkboard SE）；技术字段（Menlo）；公式 New Computer Modern |
+| 运动 | draw-on：中心线 → 轮廓 → 细节 → 尺寸 → 标注；不做 3D 旋转、不做辉光 |
+| 声音 | 纸张、钢笔、尺规、机械；−14 LUFS |
+
+## 3. manimgx 映射
+
+- `theme.py`：`apply_config()`、`backdrop()`（青晒纸渐变 + 噪点）、`sheet()`、`title_block()`；
+- 用 `Line`、`Polygon`、`DoubleArrow`、`Create` 实现制图与 draw-on；
+- 上游的 3D 斜投影、纸纹 shader 没有实现；用 2D 制图语言近似；
+- 字体替换：Architects Daughter → Chalkboard SE；B612 → Menlo。
+
+## 4. Do / Don't
+
+**Do**
+
+- 按制图顺序画：先中心线，再轮廓，最后尺寸与标注；
+- 红色印章只出现一次，承担结论；
+- 尺寸线、引出线、编号气球让画面“像图”；
+- 标题块写图号/状态。
+
+**Don't**
+
+- 不做 3D 渲染、辉光、全息 HUD；
+- 不用第二个非蓝颜色；
+- 不让主线贴边；文字不压线。
+
+## 5. 与上游的差异
+
+- 上游是 WebGL2 纸纹 + 3D 斜投影；这里是 2D 平涂 + 渐变；
+- 上游 24 fps、30–60 秒；本实现 30 fps、7 秒量级；
+- 上游手写字体不随包分发；这里用 Chalkboard SE / Menlo 近似。

package/styles/blueprint/style.json

@@ -0,0 +1,11 @@
+{
+  "slug": "blueprint",
+  "en": "Blueprint",
+  "cn": "蓝图 / 工程制图",
+  "category_en": "Graphic & Type",
+  "category_cn": "图形与排版",
+  "uses": ["Engineering", "Hardware launches", "Tech explainers"],
+  "source": "https://github.com/lemomo-ai/lemo-opuscar/tree/main/styles/blueprint",
+  "license": "style doc MIT; demo stills CC BY 4.0 (LemoLab)",
+  "implementation": "manimgx (theme.py + tokens.json)"
+}

package/styles/blueprint/theme.py

@@ -0,0 +1,65 @@
+"""blueprint 1.0.0 — Lemo-Opuscar 的 Blueprint，manimgx 实现层。
+
+上游规范（MIT）：styles/blueprint/STYLE.md
+普鲁士蓝纸 + 白线 + 一次红色印章；不做 3D、不做辉光。
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import numpy as np
+
+import manimgx as m
+
+TOKENS = json.loads(Path(__file__).with_name("tokens.json").read_text(encoding="utf-8"))
+
+TABLE = TOKENS["colors"]["table"]
+PAPER = TOKENS["colors"]["paper"]
+PAPER_LIGHT = TOKENS["colors"]["paper_light"]
+LINE = TOKENS["colors"]["line"]
+MUTED = TOKENS["colors"]["muted"]
+STAMP = TOKENS["colors"]["stamp"]
+LAYOUT = TOKENS["layout"]
+
+
+def apply_config(width: int = 1920, height: int = 1080, fps: int = 30) -> None:
+    m.config.pixel_width = width
+    m.config.pixel_height = height
+    m.config.frame_rate = fps
+    m.config.background_color = TABLE
+
+
+def backdrop(seed: int = 11) -> m.ImageMobject:
+    """青晒纸：两档普鲁士蓝 + 轻微噪点，压在深色绘图桌上。"""
+    w, h = m.config.pixel_width, m.config.pixel_height
+    yy, xx = np.mgrid[0:h, 0:w]
+    u = xx / (w - 1)
+    v = yy / (h - 1)
+    glow = np.exp(-(((u - 0.48) ** 2) / 0.16 + ((v - 0.44) ** 2) / 0.10))
+    dark = np.array([24, 51, 107], dtype=float)
+    light = np.array([42, 88, 166], dtype=float)
+    rgb = dark + glow[..., None] * (light - dark)
+    rng = np.random.default_rng(seed)
+    rgb = np.clip(rgb + rng.normal(0, 2.1, rgb.shape), 0, 255).astype(np.uint8)
+    img = m.ImageMobject(rgb, scale_to_resolution=min(w, h), resampling_algorithm=3)
+    return img.move_to(m.ORIGIN)
+
+
+def sheet() -> m.Rectangle:
+    """纸边：一条细白线，标出图幅。"""
+    return m.Rectangle(
+        width=LAYOUT["frame"]["width"] - 0.9,
+        height=LAYOUT["frame"]["height"] - 0.9,
+        color=LINE,
+        stroke_width=1.2,
+    )
+
+
+def title_block() -> m.VGroup:
+    x, y = LAYOUT["title_block"]["x"], LAYOUT["title_block"]["y"]
+    box = m.Rectangle(width=3.3, height=1.15, color=LINE, stroke_width=1.0).move_to([x, y, 0])
+    name = m.Text("DRAWING 001", font="Menlo", font_size=21, color=LINE).move_to([x - 0.35, y + 0.27, 0])
+    status = m.Text("STATUS: VERIFIED", font="Menlo", font_size=20, color=MUTED).move_to([x - 0.05, y - 0.27, 0])
+    return m.VGroup(box, name, status)