dsh-motion 0.4.1 → 0.4.3

package/README.md

@@ -13,7 +13,7 @@
 | 工具 | 作用 |
 |---|---|
 | `motion_frames` | **极简模式（默认）**：直接从场景出帧，不生成视频、不用 HF；几秒拿到 storyboard PNG 与 layout 问题 |
-| `motion_doctor` | 环境自检（Node / FFmpeg / Python venv / manimgx / sympy / Chrome / HyperFrames） |
+| `motion_doctor` | **环境预检（一次调用）**：运行时 + 中文字体 + 公式转换 + 常用 API 签名；按指纹缓存 12 h |
 | `motion_render` | 渲染 Manim / manimgx 场景；未通过 `APPROVALS.json` 确认门的项目会拒绝渲染 |
 | `motion_probe` | 成片抽帧拼 contact sheet，报告全黑 / 过曝的空镜 |
 | `formula_check` | 用 SymPy 判断两个表达式是否恒等 |
@@ -99,12 +99,14 @@ npm install -g dsh-motion
 # 或在 DSH 插件管理器里安装 dsh-motion
 ```
 
-安装后重启 DeepSeek Harness，然后先跑一次自检：
+安装后重启 DeepSeek Harness，然后先跑一次预检：
 
 ```
 motion_doctor
 ```
 
+它把运行时、中文字体、公式转换和常用 API 签名一次带回（按机器指纹缓存 12 小时，重复调用几乎不耗时）。
+
 ## 依赖
 
 | 依赖 | 是否必需 | 说明 |

package/docs/performance-budget.md

@@ -45,8 +45,9 @@
 
 已完成：
 
-- [x] `motion_frames` 按场景 fps 取帧：各风格 `theme.py` 在模块层设置 `m.config.frame_rate`；
-- [x] post 强制 CFR，并校验成片时长（`tpad + CFR` 修正后复验）；
+- [x] 环境预检合并为一次 `motion_doctor`：字体 + 公式转换 + API 签名进同一个 Python 进程，整份报告按指纹缓存 12 h（冷 0.5 s / 热 4 ms）。旧流程是 4–5 条独立 bash，光模型往返就 40–60 s；
+- [x] 格式契约：`apply_config()` 只设背景色，不再覆盖分辨率/帧率；`motion_render` 的 `width/height/fps` 与 CLI 的 `-r/--fps` 生效；
+- [x] CFR：post 强制 CFR；所有成片按 `nb_read_frames` 对比期望帧数，少帧时用 `tpad + CFR` 补齐并复验；
 - [x] storyboard 顶部 caption 条加提示，避免误判“裁切”。
 
 明确不做：
@@ -67,7 +68,8 @@
 
 ```text
 first_frame_s, total_s, model_s, tool_s, render_s,
-output_tokens, context_peak, image_reads, full_rewrites, probes, renders
+output_tokens, context_peak, image_reads, full_rewrites, probes, renders,
+preflight_calls（目标 1）
 ```
 
 复测时用同一台机器、同一支 30 s 片，先对比“首帧”和“输出 tokens”，再看总时长。

package/lib/cache.js

@@ -0,0 +1,54 @@
+/**
+ * 极简 JSON 缓存：文件指纹一致且未过期才算命中。
+ *
+ * 只用于「重跑一次也不该花掉一个回合」的东西（环境预检）。
+ * 指纹里带 mtime + size，所以升级 manimgx、改探针脚本、换 venv 都会自动失效。
+ */
+
+import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+/** 文件指纹；不存在时是 'missing'，不会被误当成命中。 */
+export function statSig(file) {
+  try {
+    const stat = statSync(file)
+    return `${stat.mtimeMs.toFixed(0)}:${stat.size}`
+  } catch {
+    return 'missing'
+  }
+}
+
+/** 目录指纹：只取 mtime，够用来发现「包被升级/重装」。 */
+export function dirSig(dir) {
+  try {
+    return `dir:${statSync(dir).mtimeMs.toFixed(0)}`
+  } catch {
+    return 'missing'
+  }
+}
+
+export function readCache(file, fingerprint, ttlMs) {
+  let raw
+  try {
+    raw = JSON.parse(readFileSync(file, 'utf8'))
+  } catch {
+    return null
+  }
+  if (!raw || typeof raw !== 'object') return null
+  if (JSON.stringify(raw.fingerprint) !== JSON.stringify(fingerprint)) return null
+  const ageMs = Date.now() - Number(raw.at ?? 0)
+  // TTL 是上界：ttlMs=0 表示永不用缓存，不能靠「写读之间过了 1ms」才失效。
+  if (!Number.isFinite(ageMs) || ageMs < 0 || ageMs >= ttlMs) return null
+  return { value: raw.value, ageMs }
+}
+
+/** 写入成功返回路径；被沙箱/权限挡住时返回 null（调用方不该因此失败）。 */
+export function writeCache(file, fingerprint, value) {
+  try {
+    mkdirSync(dirname(file), { recursive: true })
+    writeFileSync(file, JSON.stringify({ fingerprint, at: Date.now(), value }), 'utf8')
+    return file
+  } catch {
+    return null
+  }
+}

package/lib/doctor.js

@@ -1,10 +1,15 @@
 /**
- * 环境自检：装完插件先跑这个，别等渲染时报错。
- * 只读，不改任何东西；返回结构化表格 + 修法。
+ * 环境自检：装完插件、或渲染报错时跑这个。
+ *
+ * 一次调用给全：Node / FFmpeg / venv / manimgx / sympy / Chrome / HyperFrames
+ * + 中文字体 + 公式转换 + 常用 API 签名（后三项在 probe_env.py 里，一个进程）。
+ *
+ * 结果按文件指纹缓存（默认 12 h）：同一台机器第二次调用不再 spawn python。
+ * 需要强制重测：MOTION_PREFLIGHT=force，或 config.preflightForce = true。
  */
 
 import { execFile } from 'node:child_process'
-import { existsSync, readFileSync } from 'node:fs'
+import { readFileSync } from 'node:fs'
 import { dirname, join, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { promisify } from 'node:util'
@@ -18,6 +23,7 @@ import {
   resolveVenv,
   venvBinary,
 } from './env.js'
+import { cacheCandidates, fingerprint, probeRuntime, readAnyCache, writeAnyCache } from './preflight.js'
 
 const exec = promisify(execFile)
 
@@ -25,6 +31,8 @@ const exec = promisify(execFile)
 const LIB_DIR = dirname(fileURLToPath(import.meta.url))
 const PACKAGE_ROOT = dirname(LIB_DIR)
 
+const DEFAULT_TTL_SEC = 12 * 60 * 60
+
 /**
  * 报告"正在跑的是哪一份 dsh-motion"：版本 + lib 路径 + 安装形态。
  * 用 import.meta.url 推导，符号链接会被 Node 解析成真实路径，所以 link 安装会显示仓库路径。
@@ -61,7 +69,43 @@ async function version(bin, args) {
   return null
 }
 
+function summarizeProbe(probe) {
+  const fonts = probe?.fonts ?? []
+  const formulas = probe?.formulas ?? []
+  return {
+    fonts,
+    formulas,
+    fontsOk: fonts.length > 0 && fonts.every((row) => row.ok),
+    formulasOk: formulas.length > 0 && formulas.every((row) => row.ok),
+  }
+}
+
+function firstFormulaError(probe) {
+  const row = (probe?.formulas ?? []).find((item) => !item.ok && item.error)
+  return row?.error ?? probe?.errors?.[0] ?? null
+}
+
 export async function doctor(config = {}) {
+  const started = Date.now()
+  const fp = fingerprint(config)
+  const force = config.preflightForce === true || process.env.MOTION_PREFLIGHT === 'force'
+  const ttlSec = Math.max(
+    0,
+    Number(config.preflightTtlSec ?? process.env.MOTION_PREFLIGHT_TTL ?? DEFAULT_TTL_SEC) || 0,
+  )
+  const candidates = cacheCandidates(config)
+
+  if (!force && ttlSec > 0) {
+    const hit = readAnyCache(candidates, fp, ttlSec * 1000)
+    if (hit) {
+      return {
+        ...hit.value,
+        cached: { hit: true, ageSec: Number((hit.ageMs / 1000).toFixed(1)), ttlSec, file: hit.file },
+        elapsedMs: Date.now() - started,
+      }
+    }
+  }
+
   const rows = []
   const add = (item, ok, detail, fix) => rows.push({ item, ok, detail, fix })
 
@@ -83,11 +127,38 @@ export async function doctor(config = {}) {
   const py = hasVenv(config)
   add('Python venv', py, venv, py ? null : `python3 -m venv ${venv}`)
 
+  let probe = { ok: false, fonts: [], formulas: [], api: {}, errors: ['venv 不可用，未运行探针'] }
   if (py) {
-    const manimgx = await version(venvBinary(config, 'manimgx'))
-    add('manimgx', Boolean(manimgx), manimgx ?? '未安装', manimgx ? null : `${venvBinary(config, 'pip')} install manimgx`)
-    const sympy = await version(venvBinary(config, 'python'), ['-c', 'import sympy; print(sympy.__version__)'])
-    add('sympy', Boolean(sympy), sympy ?? '未安装', sympy ? null : `${venvBinary(config, 'pip')} install sympy`)
+    probe = await probeRuntime(config)
+
+    for (const [name, found, fix] of [
+      ['manimgx', probe.manimgx, `${venvBinary(config, 'pip')} install manimgx`],
+      ['sympy', probe.sympy, `${venvBinary(config, 'pip')} install sympy`],
+    ]) {
+      add(name, Boolean(found), found ?? '未安装', found ? null : fix)
+    }
+
+    const { fonts, formulas, fontsOk, formulasOk } = summarizeProbe(probe)
+
+    const fontDetail = fonts.length
+      ? fonts.map((row) => `${row.family} ${row.ok ? '✓' : '✗'}`).join(' · ')
+      : (probe.errors?.[0] ?? '探针失败')
+    add('中文字体', fontsOk, fontDetail, fontsOk ? null : '安装 manimgx-fonts-cjk；macOS 需有 PingFang SC')
+
+    const formulaDetail = formulas.length
+      ? formulasOk
+        ? `${formulas.length}/${formulas.length} 条样本转换成功（Typst/mitex）`
+        : firstFormulaError(probe) ?? '公式转换失败'
+      : '未运行'
+    add('公式转换', formulasOk, formulaDetail, formulasOk ? null : '检查 Typst 后端；`\\lim_{...}` 这类写法在正式场景里再验一次')
+
+    const apiNames = Object.keys(probe.api ?? {})
+    add(
+      '渲染器 API',
+      apiNames.length > 0,
+      apiNames.length ? `${apiNames.length} 个签名已随报告返回：${apiNames.join(' / ')}` : '未取到签名',
+      null,
+    )
   }
 
   const chrome = chromePath()
@@ -98,19 +169,36 @@ export async function doctor(config = {}) {
 
   add('输出目录', true, motionHome(config), null)
 
+  const { fontsOk, formulasOk } = summarizeProbe(probe)
   const ready = {
     math: Boolean(ffmpegVersion && py),
     delivery: Boolean(ffmpegVersion && chrome),
+    fonts: fontsOk,
+    formulas: formulasOk,
   }
 
-  return {
+  const summary = !ready.math
+    ? ready.delivery
+      ? '成片可用；数学渲染缺少 Python venv'
+      : '缺少 FFmpeg：渲染不可用'
+    : ready.fonts && ready.formulas
+      ? '数学渲染与成片可用；字体与公式已过构造检查'
+      : '数学渲染与成片可用；字体或公式有问题（见下表）'
+
+  const report = {
     ready,
     source,
-    summary: ready.math
-      ? '数学渲染与成片可用'
-      : ready.delivery
-        ? '成片可用；数学渲染缺少 Python venv'
-        : '缺少 FFmpeg：渲染不可用',
+    summary,
     rows,
+    probe,
+    fingerprint: fp,
+    created: new Date().toISOString(),
+  }
+  const written = writeAnyCache(candidates, fp, report)
+
+  return {
+    ...report,
+    cached: { hit: false, ageSec: 0, ttlSec, file: written },
+    elapsedMs: Date.now() - started,
   }
 }

package/lib/index.js

@@ -48,14 +48,14 @@ export function apply(ctx, config = {}) {
   ctx.tools.register({
     name: 'motion_doctor',
     description:
-      '检查代码动画需要的环境：Node、FFmpeg、Python venv、manimgx、sympy、Chrome、HyperFrames。装完插件或渲染报错时先跑这个，返回表格与修法。',
+      '环境预检：一次调用给出 Node / FFmpeg / venv / manimgx / sympy / Chrome / HyperFrames，以及中文字体、公式转换（Typst）和常用 API 签名。开工前跑一次即可（结果按指纹缓存 12 h，重复调用几乎不耗时）；渲染报错时也先跑这个。',
     parameters: { type: 'object', properties: {}, additionalProperties: false },
     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)}`)
+      log(`doctor ready=${JSON.stringify(result.ready)} cached=${result.cached?.hit ?? false} ${result.elapsedMs ?? '?'}ms`)
       return JSON.stringify(result, null, 2)
     },
   })

package/lib/ops.js

@@ -106,7 +106,7 @@ export async function renderScene(config, args) {
 
   // post/ffmpeg 可能因 tmix/丢帧把时长压短；用 CFR 补齐并校验，避免"30s 变 27.4s"。
   if (summary.durationSec) {
-    const fixed = await ensureDuration(config, summary, fps)
+    const fixed = await ensureCfr(config, summary, fps)
     if (fixed) summary.normalized = true
   }
 
@@ -114,22 +114,25 @@ export async function renderScene(config, args) {
   return summary
 }
 
-/** 成片时长与渲染器报告的时长不一致时，用 tpad + CFR 修正；返回是否修过。 */
-async function ensureDuration(config, summary, fps) {
+/** 成片时长或帧数不对（VFR 少帧）时，用 tpad + CFR 修正；返回是否修过。 */
+async function ensureCfr(config, summary, fps) {
   const expected = Number(summary.durationSec)
   if (!Number.isFinite(expected) || expected <= 0) return false
   const file = summary.output
   const before = await probeOutput(config, file)
-  const delta = expected - before.durationSec
-  if (!Number.isFinite(delta) || Math.abs(delta) <= 0.08) return false
+  const expectedFrames = Math.round(expected * fps)
+  const frameGap = Number.isFinite(before.frames) ? Math.abs(before.frames - expectedFrames) : 0
+  const durationGap = Math.abs(expected - before.durationSec)
+  if (frameGap <= 1 && durationGap <= 0.08) return false
 
+  const delta = expected - before.durationSec
   const tmp = `${file}.cfr.mp4`
   const chain = []
   if (delta > 0.05) chain.push(`tpad=stop_mode=clone:stop_duration=${delta.toFixed(3)}`)
   chain.push(`fps=${fps}`)
   const args = [
     '-y', '-loglevel', 'error', '-i', file,
-    '-vf', chain.join(','), '-fps_mode', 'cfr',
+    '-vf', chain.join(','), '-fps_mode', 'cfr', '-r', String(fps),
     '-c:v', 'libx264', '-crf', '18', '-pix_fmt', 'yuv420p', '-an',
   ]
   if (delta < -0.05) args.push('-t', expected.toFixed(3))
@@ -137,8 +140,9 @@ async function ensureDuration(config, summary, fps) {
   await exec(binaryOf(config, 'ffmpeg'), args, { timeout: 900_000, maxBuffer: 8 * 1024 * 1024 })
 
   const after = await probeOutput(config, tmp)
-  if (!Number.isFinite(after.durationSec) || Math.abs(after.durationSec - expected) > 0.12) {
-    throw new Error(`CFR 修正后时长仍不对：期望 ${expected}s，实际 ${after.durationSec}s（${tmp}）`)
+  const afterGap = Number.isFinite(after.frames) ? Math.abs(after.frames - expectedFrames) : 0
+  if (afterGap > 1 || Math.abs(after.durationSec - expected) > 0.05) {
+    throw new Error(`CFR 修正后仍不对：期望 ${expectedFrames} 帧 / ${expected}s，实际 ${after.frames} 帧 / ${after.durationSec}s（${tmp}）`)
   }
   renameSync(tmp, file)
   Object.assign(summary, after)
@@ -348,10 +352,10 @@ export async function probeVideo(config, args) {
 /** 用 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',
+    '-v', 'error', '-count_frames', '-select_streams', 'v:0',
+    '-show_entries', 'stream=width,height,r_frame_rate,avg_frame_rate,nb_read_frames:format=duration,size',
     '-of', 'json', file,
-  ], { timeout: 60_000, maxBuffer: 1024 * 1024 })
+  ], { timeout: 120_000, maxBuffer: 4 * 1024 * 1024 })
   const data = JSON.parse(stdout)
   const stream = data.streams?.[0] ?? {}
   const [num, den = '1'] = String(stream.r_frame_rate ?? '0/1').split('/')
@@ -363,6 +367,10 @@ export async function probeOutput(config, file) {
     width: stream.width ?? null,
     height: stream.height ?? null,
     fps: Number.isFinite(rate) && rate > 0 ? Math.round(rate * 100) / 100 : null,
+    avgFps: Number.isFinite(Number(stream.avg_frame_rate?.split?.('/')[0]))
+      ? Math.round((Number(stream.avg_frame_rate.split('/')[0]) / Number(stream.avg_frame_rate.split('/')[1] ?? 1)) * 100) / 100
+      : null,
+    frames: Number.isFinite(Number(stream.nb_read_frames)) ? Number(stream.nb_read_frames) : null,
     megabytes: Number.isFinite(size) ? Math.round(size / 1e5) / 10 : null,
   }
 }

package/lib/preflight.js

@@ -0,0 +1,115 @@
+/**
+ * 环境预检：一次调用问清「能不能开工」。
+ *
+ * 为什么不是多次：每个独立检查都是一次模型往返（5–15 s），而不是一次 0.3 s 的子进程。
+ * 所以字体验证、公式转换、常用 API 签名、渲染器版本全部塞进 probe_env.py 一个进程，
+ * 外层再按文件指纹缓存整份报告——同一台机器上第二次调用直接命中，不再 spawn python。
+ *
+ * 只看「构造」不看「渲染」：渲染由项目自己的最小场景（首帧预算 ≤60 s）验证。
+ */
+
+import { execFile } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { readdirSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { promisify } from 'node:util'
+
+import { dirSig, readCache, statSig, writeCache } from './cache.js'
+import { motionHome, resolveVenv, venvBinary } from './env.js'
+
+const exec = promisify(execFile)
+
+const PROBE_SCRIPT = join(dirname(fileURLToPath(import.meta.url)), 'probe_env.py')
+
+/** venv 里 manimgx 包的位置：Unix 是 lib/python3.x/site-packages，Windows 是 Lib/site-packages。 */
+function packageDir(venv) {
+  try {
+    for (const entry of readdirSync(join(venv, 'lib'))) {
+      if (!entry.startsWith('python')) continue
+      const candidate = join(venv, 'lib', entry, 'site-packages', 'manimgx')
+      return candidate
+    }
+  } catch {
+    // 落到 Windows 布局
+  }
+  return join(venv, 'Lib', 'site-packages', 'manimgx')
+}
+
+/**
+ * 指纹：换机器、升级 manimgx、改探针脚本、重装 venv 都会变。
+ * 只做 stat，不起进程，所以命中判定本身是微秒级。
+ */
+export function fingerprint(config = {}) {
+  const venv = resolveVenv(config)
+  return {
+    node: process.versions.node,
+    platform: `${process.platform}-${process.arch}`,
+    venv,
+    python: statSig(venvBinary(config, 'python')),
+    manimgx: dirSig(packageDir(venv)),
+    probe: statSig(PROBE_SCRIPT),
+  }
+}
+
+/**
+ * 缓存落点，按顺序尝试：显式配置 → 系统临时目录 → MOTION_HOME。
+ *
+ * 为什么不是 MOTION_HOME：Harness 的文件沙箱是 workspace-write，`~/.dsh` 通常写不进去
+ * （EPERM）。临时目录可写、且同一台机器跨会话有效，所以排在前面。
+ */
+export function cacheCandidates(config = {}) {
+  const list = []
+  const explicit = config.cacheFile ?? process.env.MOTION_CACHE_FILE
+  if (explicit) list.push(explicit)
+  const tag = createHash('sha1').update(resolveVenv(config)).digest('hex').slice(0, 8)
+  list.push(join(tmpdir(), `dsh-motion-preflight-${tag}.json`))
+  list.push(join(motionHome(config), 'preflight.json'))
+  return list
+}
+
+/** 命中第一个指纹一致且未过期的缓存。 */
+export function readAnyCache(candidates, fingerprintValue, ttlMs) {
+  for (const file of candidates) {
+    const hit = readCache(file, fingerprintValue, ttlMs)
+    if (hit) return { ...hit, file }
+  }
+  return null
+}
+
+/** 写入第一个可写落点；全被挡住时返回 null，不影响报告本身。 */
+export function writeAnyCache(candidates, fingerprintValue, value) {
+  for (const file of candidates) {
+    const written = writeCache(file, fingerprintValue, value)
+    if (written) return written
+  }
+  return null
+}
+
+/** 跑一次 Python 探针。返回 {ok, fonts, formulas, api, ...}，失败时带 errors。 */
+export async function probeRuntime(config = {}) {
+  const venv = resolveVenv(config)
+  const python = venvBinary(config, 'python')
+  const binDir = join(venv, process.platform === 'win32' ? 'Scripts' : 'bin')
+
+  try {
+    const { stdout } = await exec(python, [PROBE_SCRIPT], {
+      timeout: 30_000,
+      maxBuffer: 2 * 1024 * 1024,
+      env: { ...process.env, PATH: `${binDir}${process.platform === 'win32' ? ';' : ':'}${process.env.PATH ?? ''}` },
+    })
+    const line = stdout.trim().split('\n').filter(Boolean).pop() ?? ''
+    const parsed = JSON.parse(line)
+    return { ok: parsed.ok !== false, ...parsed }
+  } catch (err) {
+    const detail = String(err.stderr || err.stdout || err.message || '').trim().split('\n').slice(-2).join(' ')
+    return {
+      ok: false,
+      errors: [`probe failed: ${detail.slice(0, 300)}`],
+      fonts: [],
+      formulas: [],
+      api: {},
+    }
+  }
+}

package/lib/probe_env.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""环境探针：一个进程内回答「字体能不能排、公式能不能转、API 长什么样」。
+
+由 lib/doctor.js 调用（venv 里的 python），不单独给用户跑。
+只构造对象，不渲染、不写盘：约 0.25 s。真正的渲染验证留给项目自己的最小场景。
+
+stdout 必须是单行 JSON。任何未捕获异常都由 JS 侧兜成 "probe failed"。
+"""
+
+import json
+import sys
+
+# 代表三条最容易踩的路径：极限/分式、微分记号、积分。
+MATH_SAMPLES = [
+    ("lim", r"f'(x)=\lim_{\Delta x\to 0}\frac{f(x+\Delta x)-f(x)}{\Delta x}"),
+    ("differential", r"dy=f'(x)\,dx"),
+    ("integral", r"\int_0^1 x^2\,dx"),
+]
+
+FONT_SAMPLES = [
+    ("PingFang SC", "微分：把曲线拉成直线", "cjk"),
+    ("Helvetica Neue", "ABC 123", "latin"),
+]
+
+# agent 常为这几个去翻 site-packages 源码；签名直接放进报告。
+API_NAMES = ["MathTex", "Text", "DecimalNumber", "ValueTracker", "Axes"]
+
+
+def package_version(name):
+    try:
+        from importlib.metadata import version
+
+        return version(name)
+    except Exception:
+        return None
+
+
+def check_fonts(text_cls):
+    rows = []
+    for family, sample, kind in FONT_SAMPLES:
+        row = {"family": family, "kind": kind, "ok": False}
+        try:
+            obj = text_cls(sample, font=family, font_size=34)
+            row["ok"] = float(obj.width) > 0 and float(obj.height) > 0
+            row["width"] = round(float(obj.width), 2)
+        except Exception as exc:  # noqa: BLE001 - 报告里要原文
+            row["error"] = f"{type(exc).__name__}: {exc}"[:160]
+        rows.append(row)
+    return rows
+
+
+def check_formulas(math_tex_cls):
+    rows = []
+    for label, tex in MATH_SAMPLES:
+        row = {"label": label, "ok": False}
+        try:
+            obj = math_tex_cls(tex, font_size=40)
+            row["ok"] = float(obj.width) > 0
+        except Exception as exc:  # noqa: BLE001
+            row["error"] = f"{type(exc).__name__}: {exc}"[:160]
+        rows.append(row)
+    return rows
+
+
+def api_signatures(module):
+    import inspect
+
+    out = {}
+    for name in API_NAMES:
+        cls = getattr(module, name, None)
+        if cls is None:
+            continue
+        try:
+            sig = str(inspect.signature(cls.__init__))
+        except (TypeError, ValueError):
+            sig = "(signature unavailable)"
+        # 去掉 self，太长就截断：要的是参数名，不是注解全文。
+        sig = sig.removeprefix("(self, ").removeprefix("(self)")
+        out[name] = sig[:320]
+    return out
+
+
+def main():
+    out = {"ok": True, "python": sys.version.split()[0], "errors": []}
+
+    try:
+        import manimgx as motion
+        from manimgx import Axes, DecimalNumber, MathTex, Text, ValueTracker  # noqa: F401
+    except Exception as exc:  # noqa: BLE001
+        out["ok"] = False
+        out["errors"].append(f"import manimgx: {type(exc).__name__}: {exc}"[:300])
+        print(json.dumps(out, ensure_ascii=False))
+        return 0
+
+    out["manimgx"] = package_version("manimgx")
+    out["sympy"] = package_version("sympy")
+    out["fonts"] = check_fonts(Text)
+    out["formulas"] = check_formulas(MathTex)
+    out["api"] = api_signatures(motion)
+
+    if not any(row["ok"] for row in out["fonts"]):
+        out["ok"] = False
+        out["errors"].append("字体全部构造失败：检查 manimgx-fonts 与系统字体")
+    if not all(row["ok"] for row in out["formulas"]):
+        out["ok"] = False
+
+    print(json.dumps(out, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-motion",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Code-generated math & science animations for DeepSeek Harness: frames-first preview, Manim clips, formula checks.",
   "license": "MIT",
   "type": "module",
@@ -38,8 +38,8 @@
     }
   },
   "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 && node scripts/test-plan.mjs && node scripts/test-approvals.mjs",
+    "check": "node --check lib/index.js && node --check lib/ops.js && node --check lib/env.js && node --check lib/doctor.js && node --check lib/preflight.js && node --check lib/cache.js",
+    "test": "node scripts/test-ops.mjs && node scripts/test-route.mjs && node scripts/test-plan.mjs && node scripts/test-approvals.mjs && node scripts/test-preflight.mjs",
     "smoke": "node scripts/smoke.mjs",
     "dev": "node scripts/dev.mjs",
     "route": "node scripts/route-style.mjs",

package/scripts/check-meta.mjs

@@ -12,7 +12,7 @@ if (pkg.private) problems.push('package.json 里 private 仍为 true')
 if (!pkg.license) problems.push('缺少 license')
 if (!pkg.engines?.node) problems.push('缺少 engines.node')
 
-for (const file of ['lib/index.js', 'lib/ops.js', 'lib/env.js', 'lib/doctor.js']) {
+for (const file of ['lib/index.js', 'lib/ops.js', 'lib/env.js', 'lib/doctor.js', 'lib/preflight.js', 'lib/cache.js']) {
   const text = readFileSync(join(process.cwd(), file), 'utf8')
   if (/\/Users\/[^\s'"]+/.test(text)) problems.push(`${file} 含绝对路径 /Users/…`)
 }

package/scripts/dev.mjs

@@ -5,7 +5,7 @@
  *   node scripts/dev.mjs frames <scene.py> [t1,t2,...]
  *   node scripts/dev.mjs render <scene.py> [--fps 30] [--out path]
  *   node scripts/dev.mjs probe <video.mp4>
- *   node scripts/dev.mjs doctor
+ *   node scripts/dev.mjs doctor [--force]
  */
 import { mkdirSync } from 'node:fs'
 import { basename, dirname, join } from 'node:path'
@@ -62,7 +62,10 @@ if (cmd === 'frames') {
   const started = Date.now()
   console.log(JSON.stringify({ ...(await probeVideo({}, { video: file })), elapsed: elapsed(started) }, null, 2))
 } else if (cmd === 'doctor') {
-  console.log(JSON.stringify(await doctor({}), null, 2))
+  if (rest.includes('--force')) process.env.MOTION_PREFLIGHT = 'force'
+  const started = Date.now()
+  const report = await doctor({})
+  console.log(JSON.stringify({ ...report, elapsed: elapsed(started) }, null, 2))
 } else {
   fail(`未知命令: ${cmd}`)
 }

package/scripts/smoke.mjs

@@ -15,6 +15,9 @@ const required = [
   'lib/env.js',
   'lib/doctor.js',
   'lib/fresh.js',
+  'lib/preflight.js',
+  'lib/probe_env.py',
+  'lib/cache.js',
   'skills/animation-router/SKILL.md',
   'skills/animation-router/references/confirmation.md',
   'skills/design-spec/SKILL.md',

package/scripts/test-preflight.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * 预检缓存单元测试：指纹失效、TTL、坏文件不炸、落点顺序。
+ * 不依赖 Python 与网络：只测 cache.js / preflight.js 的纯逻辑。
+ */
+import assert from 'node:assert/strict'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { readCache, statSig, writeCache } from '../lib/cache.js'
+import { cacheCandidates } from '../lib/preflight.js'
+
+const dir = mkdtempSync(join(tmpdir(), 'dsh-motion-preflight-'))
+const file = join(dir, 'cache.json')
+const fp = { node: '26.0.0', venv: '/tmp/venv', probe: '1:2' }
+
+try {
+  // 缺失文件
+  assert.equal(statSig(join(dir, 'nope.json')), 'missing')
+
+  // 写→读
+  assert.equal(writeCache(file, fp, { ready: { math: true } }), file)
+  const hit = readCache(file, fp, 60_000)
+  assert.ok(hit, '同指纹应命中')
+  assert.equal(hit.value.ready.math, true)
+  assert.ok(hit.ageMs >= 0 && hit.ageMs < 60_000)
+
+  // 指纹变了就失效
+  assert.equal(readCache(file, { ...fp, probe: '1:3' }, 60_000), null, '指纹变化应失效')
+
+  // 过期就失效
+  assert.equal(readCache(file, fp, 0), null, 'TTL=0 应失效')
+
+  // 坏文件不抛
+  writeFileSync(file, '{not json')
+  assert.equal(readCache(file, fp, 60_000), null, '坏 JSON 应返回 null')
+
+  // 写不进去返回 null，不抛
+  assert.equal(writeCache('/dev/null/nested/x.json', fp, {}), null)
+
+  // 落点：显式配置优先；否则临时目录在这台机器上比 MOTION_HOME 更可能可写
+  const explicit = cacheCandidates({ cacheFile: join(dir, 'explicit.json') })
+  assert.equal(explicit[0], join(dir, 'explicit.json'))
+  assert.ok(explicit.length >= 2, '至少两个候选落点')
+  assert.ok(cacheCandidates({}).some((p) => p.startsWith(tmpdir())), '应包含临时目录')
+} finally {
+  rmSync(dir, { recursive: true, force: true })
+}
+
+console.log('ok  preflight cache: fingerprint / ttl / corrupt / fallback')

package/skills/animation-router/SKILL.md

@@ -26,6 +26,24 @@ node scripts/plan-questions.mjs "<brief>" --json
 选项是**推出来的**，不是固定清单：画幅看平台线索，交付看有无旁白，风格看 registry 命中，受众看题材与平台。
 用户也可以直接在 `Other` 里写别的。
 
+## 0.5 环境预检：跑一次，别再拆
+
+开工前只调用**一次** `motion_doctor`。它一口气返回：
+
+- 运行时：Node / FFmpeg / venv / manimgx / sympy / Chrome / HyperFrames；
+- **字体**：PingFang SC、Helvetica Neue 的构造结果；
+- **公式**：`\lim_{}\frac{}{}`、微分记号、积分三条样本的 Typst 转换；
+- **API 签名**：`probe.api` 里的 MathTex / Text / DecimalNumber / ValueTracker / Axes。
+
+规则：
+
+- `ready.math` / `ready.delivery` / `ready.fonts` / `ready.formulas` 全为 true 才开工；
+- **不要**把字体、公式、模块版本拆成多条 bash 去查：每条都是一次模型往返（5–15 s），而这次预检本身约 0.5 s；
+- 结果按文件指纹缓存 12 h。`cached.hit: true` 表示环境没变，直接信；升级 venv / manimgx 会自动失效，要手动重测用 `MOTION_PREFLIGHT=force`；
+- 要库 API 先看 `probe.api`，**不要读 site-packages 源码**；签名不够时用一条命令补：`python -c "import inspect, manimgx; print(inspect.signature(manimgx.DecimalNumber.__init__))"`；
+- 构造通过 ≠ 画面没问题：排版仍以第一帧（`motion_frames`）为准；
+- 所以**不要再单独写 probe 场景做冒烟渲染**：项目的第一帧就是冒烟，一次就够。
+
 ## 1. 判题材
 
 | 题材 | 观众记住 | 判据 |
@@ -101,7 +119,7 @@ node scripts/approvals.mjs check <project>   # 未全部 approved 时退出 1
 `motion_frames` 内部是 `manimgx inspect`，只画请求的时刻并做版式检查；
 `motion_probe` 是给已有 mp4 做体检的，不要用它替代看帧。
 
-## 6. 五条硬规则
+## 6. 硬规则（逐条对照）
 
 1. **没有明确开工指令，不执行**：没听到“可以开始”就不写完整场景、不出全片；
 2. **没有 DESIGN.md 或参考语法，不开工**——否则每次都是同一个默认 look；
@@ -110,4 +128,5 @@ node scripts/approvals.mjs check <project>   # 未全部 approved 时退出 1
 5. **公式先过 `formula_check`**，再进画面；
 6. **首帧预算 ≤60s**：先最小场景 + 构图 sheet，60s 看不到第一帧就停；
 7. **只做局部 edit**：改动 <50% 不重写整个文件；
-8. **图片/上下文预算**：每次迭代 1 张 sheet（约 960px），上下文 ≤100k。
+8. **图片/上下文预算**：每次迭代 1 张 sheet（约 960px），上下文 ≤100k；
+9. **预检只跑一次**：`motion_doctor` 已含字体/公式/API 签名并缓存 12 h，不拆成多条 bash，也不读库源码。

package/skills/qa-rubric/SKILL.md

@@ -14,9 +14,14 @@ description: 代码动画的自检清单：环境、公式、画面、音频、
 
 详见 [performance-budget.md](../../docs/performance-budget.md)。
 
-## 1. 环境
+## 1. 环境（一次调用）
 
-先跑 `motion_doctor`，`ready.math` 与 `ready.delivery` 都为 true 再继续。
+开工前跑**一次** `motion_doctor`：运行时 + 中文字体 + 公式转换 + API 签名一起返回。
+
+- `ready.math` / `ready.delivery` / `ready.fonts` / `ready.formulas` 全 true 再继续；
+- `cached.hit: true` 表示环境未变（指纹含 venv / manimgx mtime），不必重跑；
+- 不要为字体、公式、模块版本各跑一条 bash，也不要读 site-packages 查 API：签名在 `probe.api`；
+- 换 venv 或升级 manimgx 后，用 `MOTION_PREFLIGHT=force motion_doctor` 强制重测。
 
 ## 2. 公式（仅数学题材）
 

package/styles/3b1b/theme.py

@@ -13,9 +13,6 @@ import manimgx as m
 
 TOKENS = json.loads(Path(__file__).with_name("tokens.json").read_text(encoding="utf-8"))
 
-# inspect 在 import 时读 config.frame_rate；必须放在模块层，不能只在 construct 里。
-m.config.frame_rate = int(TOKENS["motion"]["fps"])
-
 BG = TOKENS["colors"]["bg"]
 TEXT = TOKENS["colors"]["text"]
 LABEL = TOKENS["colors"]["label"]
@@ -30,11 +27,13 @@ AXIS = TOKENS["colors"]["axis"]
 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 = BG
+def apply_config(background: str = BG) -> None:
+    """只设背景色；分辨率/帧率由 CLI（-r / --fps）或调用方决定。
+
+    不要在场景里写死 1920x1080/30：那会覆盖 motion_render 的 width/height/fps，
+    也是 1280x720 崩溃与 --fps 60 静默变 5s 的根因。
+    """
+    m.config.background_color = background
 
 
 def backdrop() -> m.Rectangle:

package/styles/README.md

@@ -18,7 +18,7 @@
 - `STYLE.md` 是**改编**，必须在上游基础上写清楚差异；不复制 demo 代码；
 - 颜色、字体、时间表、音频以 `tokens.json` 为准；版面坐标与组件配方写在 `STYLE.md`；
 - 中文文本不做字符级 `ReplacementTransform` / `Transform`（会出字形碎片）；用 Fade/Write/Indicate，换词用 FadeOut+FadeIn；
-- `theme.py` 必须在**模块 import 时**设置 `m.config.frame_rate`（不能只在 `construct` 里），否则 `manimgx inspect` 会按默认 60fps 取帧，30fps 场景的后半段会报 no frame；
+- **不要在场景/`theme.py` 里写死 1920×1080 / fps**：`apply_config()` 只设背景色；分辨率与帧率交给 `motion_render` 的 `width/height/fps` 或 CLI 的 `-r/--fps`。写死会覆盖 CLI，导致 `-r 1280x720` 崩溃、`--fps 60` 静默变 5s；
 - 路由：`styles/registry.json` 是元数据，`node scripts/route-style.mjs "<题材>"` 打分；点名优先，低置信度/并列先问用户；
 - 新片在自己的项目目录写 `DESIGN.md`，头部 `style: <slug>` + `style_version: 1.0.0`；
 - 参考与示例统一用 HyperFrames 的 [examples](https://hyperframes.heygen.com/examples) / [catalog](https://hyperframes.heygen.com/catalog)，不在仓库里放样片（`showcase/` 只放可复现的演示）。

package/styles/blueprint/theme.py

@@ -15,9 +15,6 @@ import manimgx as m
 
 TOKENS = json.loads(Path(__file__).with_name("tokens.json").read_text(encoding="utf-8"))
 
-# inspect 在 import 时读 config.frame_rate；必须放在模块层，不能只在 construct 里。
-m.config.frame_rate = int(TOKENS["motion"]["fps"])
-
 TABLE = TOKENS["colors"]["table"]
 PAPER = TOKENS["colors"]["paper"]
 PAPER_LIGHT = TOKENS["colors"]["paper_light"]
@@ -27,11 +24,13 @@ 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 apply_config(background: str = TABLE) -> None:
+    """只设背景色；分辨率/帧率由 CLI（-r / --fps）或调用方决定。
+
+    不要在场景里写死 1920x1080/30：那会覆盖 motion_render 的 width/height/fps，
+    也是 1280x720 崩溃与 --fps 60 静默变 5s 的根因。
+    """
+    m.config.background_color = background
 
 
 def backdrop(seed: int = 11) -> m.ImageMobject:

package/styles/dataviz/theme.py

@@ -13,9 +13,6 @@ import manimgx as m
 
 TOKENS = json.loads(Path(__file__).with_name("tokens.json").read_text(encoding="utf-8"))
 
-# inspect 在 import 时读 config.frame_rate；必须放在模块层，不能只在 construct 里。
-m.config.frame_rate = int(TOKENS["motion"]["fps"])
-
 PAPER = TOKENS["colors"]["paper"]
 PAPER_SHADOW = TOKENS["colors"]["paper_shadow"]
 INK = TOKENS["colors"]["ink"]
@@ -28,11 +25,13 @@ MONO = TOKENS["typography"]["mono"]["family"]
 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 = PAPER
+def apply_config(background: str = PAPER) -> None:
+    """只设背景色；分辨率/帧率由 CLI（-r / --fps）或调用方决定。
+
+    不要在场景里写死 1920x1080/30：那会覆盖 motion_render 的 width/height/fps，
+    也是 1280x720 崩溃与 --fps 60 静默变 5s 的根因。
+    """
+    m.config.background_color = background
 
 
 def backdrop() -> m.Rectangle:

package/styles/swiss-motion/theme.py

@@ -13,9 +13,6 @@ import manimgx as m
 
 TOKENS = json.loads(Path(__file__).with_name("tokens.json").read_text(encoding="utf-8"))
 
-# inspect 在 import 时读 config.frame_rate；必须放在模块层，不能只在 construct 里。
-m.config.frame_rate = int(TOKENS["motion"]["fps"])
-
 GROUND = TOKENS["colors"]["ground"]
 PAPER = TOKENS["colors"]["paper"]
 INK = TOKENS["colors"]["ink"]
@@ -27,11 +24,13 @@ MOTION = TOKENS["motion"]
 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 = GROUND
+def apply_config(background: str = GROUND) -> None:
+    """只设背景色；分辨率/帧率由 CLI（-r / --fps）或调用方决定。
+
+    不要在场景里写死 1920x1080/30：那会覆盖 motion_render 的 width/height/fps，
+    也是 1280x720 崩溃与 --fps 60 静默变 5s 的根因。
+    """
+    m.config.background_color = background
 
 
 def backdrop() -> m.Rectangle:

package/styles/whiteboard/theme.py

@@ -15,9 +15,6 @@ import manimgx as m
 
 TOKENS = json.loads(Path(__file__).with_name("tokens.json").read_text(encoding="utf-8"))
 
-# inspect 在 import 时读 config.frame_rate；必须放在模块层，不能只在 construct 里。
-m.config.frame_rate = int(TOKENS["motion"]["fps"])
-
 BOARD = TOKENS["colors"]["board"]
 BOARD_EDGE = TOKENS["colors"]["board_edge"]
 INK = TOKENS["colors"]["ink"]
@@ -28,11 +25,13 @@ GHOST = TOKENS["colors"]["ghost"]
 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 = BOARD
+def apply_config(background: str = BOARD) -> None:
+    """只设背景色；分辨率/帧率由 CLI（-r / --fps）或调用方决定。
+
+    不要在场景里写死 1920x1080/30：那会覆盖 motion_render 的 width/height/fps，
+    也是 1280x720 崩溃与 --fps 60 静默变 5s 的根因。
+    """
+    m.config.background_color = background
 
 
 def backdrop(seed: int = 5) -> m.ImageMobject: