dsh-motion 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-motion contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,15 @@
+# Third-party notices
+
+本包不包含以下项目的源码，但会调用或与其配合；分发或商用前请自行遵守各自许可。
+
+| 项目 | 许可 | 关系 |
+|---|---|---|
+| [HyperFrames](https://github.com/heygen-com/hyperframes) | Apache-2.0 | 交付管线（组装 / 字幕 / 编码）；通过 `npx hyperframes` 调用，不打包 |
+| [Manim Community](https://github.com/ManimCommunity/manim) | MIT | 可选渲染后端 |
+| [manimgx](https://github.com/academa-labs/manimgx) | MIT | 默认渲染后端 |
+| [SymPy](https://github.com/sympy/sympy) | BSD-3-Clause | `formula_check` |
+| [FFmpeg](https://ffmpeg.org) | LGPL/GPL（取决于构建） | 渲染、后期、抽帧；**不打包**，由用户自行安装 |
+
+字体不随包分发；若你的 `DESIGN.md` 指定了第三方字体，请确认其许可（OFL / 商用授权）。
+
+本包自身的代码以 MIT 许可发布（见 `LICENSE`）。

package/README.md

@@ -1,3 +1,152 @@
-# Temporary Holding Version
+# dsh-motion
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+![npm](https://img.shields.io/npm/v/dsh-motion)
+
+> **Unofficial community plugin.** Not affiliated with or endorsed by DeepSeek.
+> The name is descriptive (`motion` = animation); if the upstream project needs it, this package will be renamed.
+
+**代码生成的数学 / 科普动画**，给 [DeepSeek Harness](https://github.com/deepseek-ai) 用的插件。
+画面由代码逐帧生成，不经过任何文生视频（text-to-video）模型。
+
+提供四个工具：
+
+| 工具 | 作用 |
+|---|---|
+| `motion_doctor` | 环境自检（Node / FFmpeg / Python venv / manimgx / sympy / Chrome / HyperFrames） |
+| `motion_render` | 渲染 Manim / manimgx 场景，可加运动模糊、颗粒、暗角、调色 |
+| `motion_probe` | 抽帧拼 contact sheet，报告全黑 / 过曝的空镜 |
+| `formula_check` | 用 SymPy 判断两个表达式是否恒等 |
+
+外加三个技能：`animation-router`（题材路由）、`design-spec`（写 DESIGN.md）、`qa-rubric`（交付自检）。
+
+## 安装
+
+```bash
+# npm
+npm install -g dsh-motion
+
+# 或在 DSH 插件管理器里安装 dsh-motion
+```
+
+安装后重启 DeepSeek Harness，然后先跑一次自检：
+
+```
+motion_doctor
+```
+
+## 依赖
+
+| 依赖 | 是否必需 | 说明 |
+|---|---|---|
+| Node.js ≥ 22 | 必需 | `engines` 声明 |
+| FFmpeg + ffprobe | 必需 | 渲染与后期；不随包分发 |
+| Python 3 + venv | 数学功能需要 | `manimgx`、`sympy` |
+| Chrome | 成片渲染需要 | HyperFrames 优先复用系统 Chrome |
+| HyperFrames 0.8.193 | 成片需要 | `npx hyperframes@0.8.193`，不随包分发 |
+
+### 准备 Python 环境
+
+```bash
+python3 -m venv ~/.dsh/data/dsh-motion/venv
+~/.dsh/data/dsh-motion/venv/bin/pip install manimgx sympy
+```
+
+Windows 把 `bin/` 换成 `Scripts\`，可执行文件加 `.exe`。
+
+## 配置
+
+插件配置（或在 profile 的 `cordis.patch.yml` 里传入）：
+
+```yaml
+- insert:
+    - id: motion
+      name: dsh-motion
+      config:
+        motionHome: ~/.dsh/data/dsh-motion
+        venv: ~/.dsh/data/dsh-motion/venv
+        ffmpeg: /opt/homebrew/bin/ffmpeg
+```
+
+解析顺序：插件配置 → 环境变量（`MOTION_HOME` / `MOTION_VENV` / `MOTION_FFMPEG`）→ 默认目录 → 系统 PATH。
+
+## 快速开始
+
+### 1. 写一个 Manim 场景
+
+```python
+# scenes/derivative.py
+import manimgx as m
+from manimgx import *
+
+class Derivative(Scene):
+    def construct(self):
+        ax = Axes(x_range=[-2, 2], y_range=[-1, 4])
+        self.play(Create(ax))
+        self.wait(1)
+```
+
+### 2. 渲染
+
+```jsonc
+// motion_render
+{ "file": "/abs/path/scenes/derivative.py", "scene": "Derivative", "width": 1920, "height": 1080, "fps": 30 }
+```
+
+### 3. 自检
+
+```jsonc
+// motion_probe
+{ "video": "/abs/path/scenes/derivative.mp4", "frames": 12 }
+```
+
+### 4. 公式先验
+
+```jsonc
+// formula_check
+{ "left": "diff(0.5*exp(x), x)", "right": "0.5*exp(x)" }
+```
+
+## 和 HyperFrames 的关系
+
+本插件**不是**渲染框架。成片（合成、字幕、音频混流、编码）交给 HyperFrames：
+
+```bash
+npx hyperframes@0.8.193 init <project> --example swiss-grid --video <clip>.mp4
+npx hyperframes@0.8.193 check <project>
+npx hyperframes@0.8.193 render <project> -o out.mp4 --quality delivery
+```
+
+字幕建议“一份 transcript 出两个产物”：烧录进画面 + 独立 `.srt`。
+
+## 故障排除
+
+| 现象 | 原因 | 处理 |
+|---|---|---|
+| `找不到 Python 虚拟环境` | 未建 venv | 按上文创建，并 `pip install manimgx sympy` |
+| `找不到渲染器: …/manimgx` | venv 里没装 | `pip install manimgx` |
+| 渲染断字 / 字体回退 | 字体未声明 `@font-face` | 把 `.woff2` 放工程 `assets/fonts/` 并声明 |
+| `ffprobe` 缺失 | 只装了 ffmpeg | 装完整 FFmpeg，插件会退回 `ffmpeg -i` 解析 |
+| 抽帧全黑 | 片头/片尾空镜 | 用 `tpad=stop_mode=clone` 补帧，或剪掉 |
+
+## 发版（维护者）
+
+首次发布会把名字与 2FA 绑好；之后用 GitHub Actions 的 Trusted Publishing，不需要 token，也不需要 OTP。
+
+1. 在 npm 包设置里绑定可信发布者：**Package → Settings → Trusted Publisher → GitHub Actions**
+   - owner: `cogito0823`
+   - repository: `dsh-motion`
+   - workflow: `release.yml`
+2. 然后：
+
+```bash
+npm version patch          # 0.1.0 -> 0.1.1
+git push --follow-tags     # 触发 release.yml
+```
+
+工作流会校验 tag 与 `package.json` 一致、跑 check/smoke，再 `npm publish --provenance`。
+
+若工作流失败，退回手动发布：`npm publish --access public`（需 passkey 或 OTP）。
+
+## 许可
+
+MIT（见 `LICENSE`）。第三方依赖与调用关系见 `NOTICE.md`。

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+- insert:
+    - id: motion
+      name: ./lib/index.js
+      config: {}

package/lib/doctor.js

@@ -0,0 +1,91 @@
+/**
+ * 环境自检：装完插件先跑这个，别等渲染时报错。
+ * 只读，不改任何东西；返回结构化表格 + 修法。
+ */
+
+import { execFile } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { promisify } from 'node:util'
+
+import {
+  chromePath,
+  findHyperframes,
+  hasVenv,
+  motionHome,
+  resolveBinary,
+  resolveVenv,
+  venvBinary,
+} from './env.js'
+
+const exec = promisify(execFile)
+
+async function runVersion(bin, args) {
+  try {
+    const { stdout, stderr } = await exec(bin, args, { timeout: 15_000 })
+    const line = `${stdout || ''}\n${stderr || ''}`.trim().split('\n')[0]
+    if (line) return line.slice(0, 80)
+  } catch (err) {
+    const line = String(err.stderr || err.stdout || '').trim().split('\n')[0]
+    if (line && /version/i.test(line)) return line.slice(0, 80)
+  }
+  return null
+}
+
+async function version(bin, args) {
+  if (Array.isArray(args)) return runVersion(bin, args)
+  for (const form of [['--version'], ['-version'], ['version']]) {
+    const found = await runVersion(bin, form)
+    if (found) return found
+  }
+  return null
+}
+
+export async function doctor(config = {}) {
+  const rows = []
+  const add = (item, ok, detail, fix) => rows.push({ item, ok, detail, fix })
+
+  const nodeMajor = Number(process.versions.node.split('.')[0])
+  add('Node.js', nodeMajor >= 22, `v${process.versions.node}`, nodeMajor >= 22 ? null : '升级到 Node 22 或更高')
+
+  const ffmpeg = resolveBinary(config, 'ffmpeg')
+  const ffmpegVersion = await version(ffmpeg)
+  add('FFmpeg', Boolean(ffmpegVersion), ffmpegVersion ?? ffmpeg, ffmpegVersion ? null : '安装 FFmpeg（macOS: brew install ffmpeg）')
+
+  const ffprobe = resolveBinary(config, 'ffprobe')
+  const ffprobeVersion = await version(ffprobe)
+  add('ffprobe', Boolean(ffprobeVersion), ffprobeVersion ?? ffprobe, ffprobeVersion ? null : '随 FFmpeg 一起安装')
+
+  const venv = resolveVenv(config)
+  const py = hasVenv(config)
+  add('Python venv', py, venv, py ? null : `python3 -m venv ${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`)
+  }
+
+  const chrome = chromePath()
+  add('Chrome', Boolean(chrome), chrome ?? '未找到', chrome ? null : '安装 Chrome，或让 HyperFrames 自行下载渲染浏览器')
+
+  const hf = findHyperframes()
+  add('HyperFrames', Boolean(hf), hf ? '已缓存（用于组装/字幕/编码）' : '未安装', hf ? null : 'npx hyperframes@0.8.193 --version')
+
+  add('输出目录', true, motionHome(config), null)
+
+  const ready = {
+    math: Boolean(ffmpegVersion && py),
+    delivery: Boolean(ffmpegVersion && chrome),
+  }
+
+  return {
+    ready,
+    summary: ready.math
+      ? '数学渲染与成片可用'
+      : ready.delivery
+        ? '成片可用；数学渲染缺少 Python venv'
+        : '缺少 FFmpeg：渲染不可用',
+    rows,
+  }
+}

package/lib/env.js

@@ -0,0 +1,94 @@
+/**
+ * 路径与外部命令解析。不写死任何本机路径。
+ *
+ * 解析顺序：插件配置 → 环境变量 → 默认目录 → 系统 PATH。
+ */
+
+import { accessSync, constants, existsSync, readdirSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { delimiter, join } from 'node:path'
+
+export function motionHome(config = {}) {
+  return config.motionHome
+    ?? process.env.MOTION_HOME
+    ?? join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'data', 'dsh-motion')
+}
+
+export function isExecutable(file) {
+  try {
+    accessSync(file, constants.X_OK)
+    return statSync(file).isFile()
+  } catch {
+    return false
+  }
+}
+
+/** 在 PATH 里查找可执行文件，不经过 shell。 */
+export function findOnPath(name) {
+  const dirs = (process.env.PATH ?? '').split(delimiter).filter(Boolean)
+  const exts = process.platform === 'win32'
+    ? (process.env.PATHEXT ?? '.EXE;.CMD;.BAT').split(';').filter(Boolean)
+    : ['']
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const candidate = join(dir, name + ext)
+      if (isExecutable(candidate)) return candidate
+    }
+  }
+  return null
+}
+
+/** venv 根目录：配置 > 环境变量 > $DSH_HOME/data/dsh-motion/venv */
+export function resolveVenv(config = {}) {
+  return config.venv ?? process.env.MOTION_VENV ?? join(motionHome(config), 'venv')
+}
+
+export function venvBinary(config, name) {
+  const root = resolveVenv(config)
+  return process.platform === 'win32'
+    ? join(root, 'Scripts', `${name}.exe`)
+    : join(root, 'bin', name)
+}
+
+export function hasVenv(config = {}) {
+  return isExecutable(venvBinary(config, 'python'))
+}
+
+/** 外部命令：配置 > 环境变量 > PATH > 常见安装位置。 */
+export function resolveBinary(config = {}, name) {
+  const key = name.toLowerCase()
+  const configured = config[key]
+    ?? process.env[`MOTION_${key.toUpperCase()}`]
+  if (configured) return configured
+  const found = findOnPath(name)
+  if (found) return found
+  const fallbacks = process.platform === 'darwin'
+    ? ['/opt/homebrew/bin', '/usr/local/bin', '/usr/bin']
+    : ['/usr/local/bin', '/usr/bin', '/bin']
+  for (const dir of fallbacks) {
+    const candidate = join(dir, name)
+    if (isExecutable(candidate)) return candidate
+  }
+  return name
+}
+
+export function chromePath() {
+  const candidates = process.platform === 'darwin'
+    ? ['/Applications/Google Chrome.app/Contents/MacOS/Google Chrome']
+    : process.platform === 'win32'
+      ? ['C:/Program Files/Google/Chrome/Application/chrome.exe']
+      : ['/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser']
+  return candidates.find((p) => existsSync(p)) ?? null
+}
+
+/** 最新 npx 缓存里的 hyperframes（只用于 doctor 报告，不作为依赖）。 */
+export function findHyperframes() {
+  const npxRoot = join(process.env.HOME ?? homedir(), '.npm', '_npx')
+  if (existsSync(npxRoot)) {
+    for (const dir of readdirSync(npxRoot)) {
+      const candidate = join(npxRoot, dir, 'node_modules', 'hyperframes', 'package.json')
+      if (existsSync(candidate)) return candidate
+    }
+  }
+  return findOnPath('hyperframes')
+}

package/lib/index.js

@@ -0,0 +1,140 @@
+/**
+ * dsh-motion —— 代码生成的数学 / 科普动画
+ *
+ * 四个工具：
+ *   motion_doctor   环境自检（先跑这个）
+ *   motion_render   渲染 Manim / manimgx 场景
+ *   motion_probe    抽帧自检（空镜 / 过曝）
+ *   formula_check   公式恒等校验（sympy）
+ *
+ * 知识层在 skills/ 里：animation-router / design-spec / qa-rubric。
+ */
+
+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'
+
+export const name = 'motion'
+export const inject = ['tools']
+
+const LOG_DIR = join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'logs')
+
+function log(message) {
+  try {
+    mkdirSync(LOG_DIR, { recursive: true })
+    appendFileSync(join(LOG_DIR, 'motion.log'), `${new Date().toISOString()} ${message}\n`)
+  } catch {
+    // 日志失败不影响工具
+  }
+}
+
+function asText(value) {
+  const text = typeof value === 'string' ? value : JSON.stringify(value, null, 2)
+  return [{ type: 'text', text }]
+}
+
+const textOutput = { schema: { type: 'string' }, render: (_args, value) => asText(value) }
+
+export function apply(ctx, config = {}) {
+  ctx.tools.register({
+    name: 'motion_doctor',
+    description:
+      '检查代码动画需要的环境：Node、FFmpeg、Python venv、manimgx、sympy、Chrome、HyperFrames。装完插件或渲染报错时先跑这个，返回表格与修法。',
+    parameters: { type: 'object', properties: {}, additionalProperties: false },
+    output: textOutput,
+    timeoutMs: 120_000,
+    async execute() {
+      const result = await doctor(config)
+      log(`doctor ready=${JSON.stringify(result.ready)}`)
+      return JSON.stringify(result, null, 2)
+    },
+  })
+
+  ctx.tools.register({
+    name: 'motion_render',
+    description:
+      '渲染一支数学/科普场景。engine="manimgx"（默认，数学/公式/坐标，无需 LaTeX，自带 layout 检查）或 "manim"（Manim CE 回退）。post 可加运动模糊/颗粒/暗角。返回时长/体积/布局问题清单。',
+    parameters: {
+      type: 'object',
+      properties: {
+        file: { type: 'string', description: '场景 .py 文件的绝对路径' },
+        scene: { type: 'string', description: '场景类名；文件里只有一个场景时可省略' },
+        engine: { type: 'string', enum: ['manimgx', 'manim'], description: '渲染器，默认 manimgx' },
+        post: {
+          type: 'object',
+          description: '管线层后期：运动模糊/颗粒/暗角/调色。subframes=3 表示 3 倍帧率渲染后 tmix 合成。',
+          properties: {
+            subframes: { type: 'integer', description: '子帧数 1-8，默认 1' },
+            grain: { type: 'number', description: '颗粒强度 0-30，0 为关' },
+            vignette: { type: 'number', description: '暗角强度 2-8，0 为关' },
+            grade: { type: 'string', enum: ['', 'cinematic', 'warm'], description: '调色预设' },
+          },
+          additionalProperties: false,
+        },
+        width: { type: 'integer', description: '像素宽，默认 1920' },
+        height: { type: 'integer', description: '像素高，默认 1080' },
+        fps: { type: 'integer', description: '帧率，默认 30，上限 60' },
+        out: { type: 'string', description: '输出 mp4 路径，默认与场景同目录' },
+      },
+      required: ['file'],
+      additionalProperties: false,
+    },
+    output: textOutput,
+    timeoutMs: 900_000,
+    async execute(args) {
+      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)
+    },
+  })
+
+  ctx.tools.register({
+    name: 'motion_probe',
+    description:
+      '成片自检：等间隔抽帧拼成 contact sheet，并报告全黑/过曝的空镜帧。正式交付前先跑一遍，看过图再收工。',
+    parameters: {
+      type: 'object',
+      properties: {
+        video: { type: 'string', description: '要检查的 mp4 绝对路径' },
+        frames: { type: 'integer', description: '抽帧数量，默认 12（2–24）' },
+        out: { type: 'string', description: 'contact sheet 输出路径' },
+      },
+      required: ['video'],
+      additionalProperties: false,
+    },
+    output: textOutput,
+    timeoutMs: 300_000,
+    async execute(args) {
+      const result = await probeVideo(config, args)
+      log(`probe ${result.video} frames=${result.framesAnalyzed} blank=${result.blankFrames.length}`)
+      return JSON.stringify(result, null, 2)
+    },
+  })
+
+  ctx.tools.register({
+    name: 'formula_check',
+    description:
+      '数学正确性门：用 sympy 判断两个表达式是否恒等（自动化简差值）。渲染任何公式之前先过这一关，例如 left="diff(0.6*x**3-1.8*x, x)"、right="1.8*x**2-1.8"。',
+    parameters: {
+      type: 'object',
+      properties: {
+        left: { type: 'string', description: '左表达式（sympy 语法）' },
+        right: { type: 'string', description: '右表达式（sympy 语法）' },
+      },
+      required: ['left', 'right'],
+      additionalProperties: false,
+    },
+    output: textOutput,
+    timeoutMs: 60_000,
+    async execute(args) {
+      const result = await checkMath(config, args)
+      log(`formula_check equal=${result.equal}`)
+      return JSON.stringify(result, null, 2)
+    },
+  })
+
+  log('registered 4 tools')
+}

package/lib/ops.js

@@ -0,0 +1,222 @@
+/**
+ * 机制层：所有"不变量"都在这里，模型只能传有限的参数。
+ *
+ * 设计原则
+ *  - 渲染规格（分辨率、fps、编码器、crf）只接受枚举和数字上限；
+ *  - 每个函数返回结构化摘要（时长/体积/layout 问题），不让模型 grep 日志；
+ *  - 外部命令全部走 execFile + 超时，不经 shell。
+ */
+
+import { execFile } from 'node:child_process'
+import { existsSync, statSync } from 'node:fs'
+import { basename, dirname, join, resolve } from 'node:path'
+import { promisify } from 'node:util'
+
+import { hasVenv, resolveBinary, resolveVenv, venvBinary } from './env.js'
+
+const exec = promisify(execFile)
+
+function binaryOf(config, name) {
+  return resolveBinary(config, name)
+}
+
+function requireVenv(config) {
+  if (!hasVenv(config)) {
+    throw new Error(
+      `找不到 Python 虚拟环境：${resolveVenv(config)}\n`
+      + '数学功能需要 manimgx 与 sympy。创建方式：\n'
+      + `  python3 -m venv ${resolveVenv(config)}\n`
+      + `  ${venvBinary(config, 'pip')} install manimgx sympy\n`
+      + '或在插件配置里指定 venv 路径 / 设置 MOTION_VENV。',
+    )
+  }
+}
+
+/** 从渲染器 stdout 里抽布局问题和产物信息。 */
+export function summarizeRender(stdout, stderr) {
+  const text = `${stdout}\n${stderr}`
+  const problems = [...text.matchAll(/^\s*\[(\d+)\]\s*(.+)$/gm)].map((m) => m[2].trim())
+  const line = text.match(/^(.*\.mp4)\s+([\d.]+) s,\s*(\d+)x(\d+) at ([\d.]+) fps,\s*([\d.]+) MB(?:.*rendered in ([\d.]+) s)?/m)
+  return {
+    video: line?.[1] ?? null,
+    durationSec: line ? Number(line[2]) : null,
+    width: line ? Number(line[3]) : null,
+    height: line ? Number(line[4]) : null,
+    fps: line ? Number(line[5]) : null,
+    megabytes: line ? Number(line[6]) : null,
+    renderedSec: line?.[7] ? Number(line[7]) : null,
+    layoutProblems: problems,
+  }
+}
+
+/** 渲染一支场景。engine = manimgx（默认，无需 LaTeX）或 manim（Manim CE 回退）。 */
+export async function renderScene(config, args) {
+  const file = resolve(args.file)
+  if (!existsSync(file)) throw new Error(`场景文件不存在: ${file}`)
+
+  const engine = args.engine ?? 'manimgx'
+  if (engine !== 'manimgx' && engine !== 'manim') {
+    throw new Error('engine 只支持 manimgx 或 manim')
+  }
+
+  const width = clampInt(args.width ?? 1920, 320, 4096)
+  const height = clampInt(args.height ?? 1080, 320, 4096)
+  const fps = clampInt(args.fps ?? 30, 10, 60)
+  const out = resolve(args.out ?? join(dirname(file), `${basename(file, '.py')}.mp4`))
+
+  requireVenv(config)
+  const venv = resolveVenv(config)
+  const binDir = join(venv, process.platform === 'win32' ? 'Scripts' : 'bin')
+  const command = venvBinary(config, engine === 'manim' ? 'manim' : 'manimgx')
+  if (!existsSync(command)) {
+    throw new Error(`找不到渲染器: ${command}\n请在 venv 里安装：${venvBinary(config, 'pip')} install ${engine === 'manim' ? 'manim' : 'manimgx'}`)
+  }
+
+  const argv = engine === 'manim'
+    ? [file, ...(args.scene ? [args.scene] : []), '-o', basename(out)]
+    : ['render', file, ...(args.scene ? [args.scene] : []), '-r', `${width}x${height}`, '--fps', String(fps), '-o', out]
+
+  const post = normalizePost(args.post)
+  if (post.subframes > 1 && engine === 'manimgx') {
+    const i = argv.indexOf('--fps')
+    if (i >= 0) argv[i + 1] = String(fps * post.subframes)
+  }
+
+  const started = Date.now()
+  const { stdout, stderr } = await exec(command, argv, {
+    timeout: 900_000,
+    maxBuffer: 8 * 1024 * 1024,
+    env: { ...process.env, PATH: `${binDir}${process.platform === 'win32' ? ';' : ':'}${process.env.PATH ?? ''}` },
+    cwd: dirname(file),
+  })
+
+  const summary = summarizeRender(stdout, stderr)
+  summary.engine = engine
+  summary.output = out
+
+  if (post.enabled) {
+    const finalOut = out.replace(/\.mp4$/, '') + '-post.mp4'
+    await applyPost(config, out, finalOut, fps, post)
+    summary.post = { ...post, output: finalOut }
+    summary.output = finalOut
+    summary.video = finalOut
+  }
+
+  summary.wallSec = Number(((Date.now() - started) / 1000).toFixed(1))
+  return summary
+}
+
+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)
+  const vignette = p.vignette === true ? 4 : Number(p.vignette ?? 0)
+  const grade = typeof p.grade === 'string' ? p.grade : ''
+  return {
+    subframes,
+    grain: Number.isFinite(grain) ? grain : 0,
+    vignette: Number.isFinite(vignette) ? vignette : 0,
+    grade,
+    enabled: subframes > 1 || grain > 0 || vignette > 0 || Boolean(grade),
+  }
+}
+
+/** 管线层后期：tmix 运动模糊 + 颗粒 + 暗角 + 调色，不写进场景代码。 */
+async function applyPost(config, input, output, fps, post) {
+  const chain = []
+  if (post.subframes > 1) chain.push(`tmix=frames=${post.subframes}`, `fps=${fps}`)
+  if (post.vignette > 0) chain.push(`vignette=PI/${post.vignette}`)
+  if (post.grain > 0) chain.push(`noise=alls=${Math.round(post.grain)}:allf=t`)
+  if (post.grade === 'cinematic') chain.push('eq=contrast=1.06:saturation=1.12', 'curves=preset=medium_contrast')
+  if (post.grade === 'warm') chain.push('eq=contrast=1.03:saturation=1.06', 'colorbalance=rs=.04:bs=-.03')
+  if (chain.length === 0) return
+  await exec(binaryOf(config, 'ffmpeg'), [
+    '-y', '-loglevel', 'error', '-i', input,
+    '-vf', chain.join(','), '-c:v', 'libx264', '-crf', '19', '-pix_fmt', 'yuv420p',
+    '-an', output,
+  ], { timeout: 900_000, maxBuffer: 8 * 1024 * 1024 })
+}
+
+/** 抽帧自检：等间隔取 n 帧拼 contact sheet，并报告全黑/过曝帧。 */
+export async function probeVideo(config, args) {
+  const video = resolve(args.video)
+  if (!existsSync(video)) throw new Error(`视频不存在: ${video}`)
+  const n = clampInt(args.frames ?? 12, 2, 24)
+  const sheet = resolve(args.out ?? join(dirname(video), `${basename(video, '.mp4')}-contact.png`))
+  const ffmpeg = binaryOf(config, 'ffmpeg')
+
+  const duration = await readDuration(config, video)
+  const step = Math.max(1, Math.floor((duration * 30) / n))
+  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`,
+    '-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=-',
+    '-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)
+
+  return {
+    video,
+    durationSec: duration,
+    framesAnalyzed: avgs.length,
+    contactSheet: sheet,
+    blankFrames: blank.slice(0, 8),
+  }
+}
+
+async function readDuration(config, video) {
+  try {
+    const { stdout } = await exec(binaryOf(config, 'ffprobe'), [
+      '-v', 'error', '-show_entries', 'format=duration', '-of', 'default=nw=1:nk=1', video,
+    ], { timeout: 60_000 })
+    const n = Number(stdout.trim())
+    if (Number.isFinite(n) && n > 0) return n
+  } catch {
+    // ffprobe 不可用时退回 ffmpeg -i 的 stderr 解析
+  }
+  const { stderr } = await exec(binaryOf(config, 'ffmpeg'), ['-hide_banner', '-i', video], { timeout: 60_000 })
+    .catch((err) => ({ stderr: String(err.stderr ?? '') }))
+  const m = /Duration:\s*(\d+):(\d+):(\d+\.\d+)/.exec(stderr)
+  if (!m) throw new Error('无法读取视频时长：ffprobe 与 ffmpeg 都失败')
+  return Number(m[1]) * 3600 + Number(m[2]) * 60 + Number(m[3])
+}
+
+/** 用 sympy 判两个表达式是否恒等（数学正确性门）。 */
+export async function checkMath(config, args) {
+  requireVenv(config)
+  const venv = resolveVenv(config)
+  const python = venvBinary(config, 'python')
+  const script = `
+import sys, sympy as sp
+from sympy.parsing.sympy_parser import parse_expr, standard_transformations, implicit_multiplication_application
+t = standard_transformations + (implicit_multiplication_application,)
+x, y, t_ = sp.symbols('x y t')
+local = {'x': x, 'y': y, 't': t_, 'pi': sp.pi, 'e': sp.E}
+left = sp.nsimplify(parse_expr(sys.argv[1], transformations=t, local_dict=local), rational=True)
+right = sp.nsimplify(parse_expr(sys.argv[2], transformations=t, local_dict=local), rational=True)
+diff = sp.simplify(left - right)
+print('EQUAL' if diff == 0 else 'DIFF')
+print(sp.srepr(diff)[:400])
+`
+  const { stdout } = await exec(python, ['-c', script, args.left, args.right], {
+    timeout: 60_000,
+    maxBuffer: 1024 * 1024,
+    env: {
+      ...process.env,
+      PATH: `${join(venv, process.platform === 'win32' ? 'Scripts' : 'bin')}${process.platform === 'win32' ? ';' : ':'}${process.env.PATH ?? ''}`,
+    },
+  })
+  const [verdict, rest] = stdout.trim().split('\n')
+  return { equal: verdict === 'EQUAL', difference: rest ?? '', left: args.left, right: args.right }
+}
+
+function clampInt(value, min, max) {
+  const n = Math.trunc(Number(value))
+  if (!Number.isFinite(n)) return min
+  return Math.min(max, Math.max(min, n))
+}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "dsh-motion",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Code-generated math & science animations for DeepSeek Harness: render Manim clips, probe frames, verify formulas.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "skills",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE",
+    "NOTICE.md"
+  ],
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "animation",
+    "manim",
+    "science",
+    "video",
+    "code-animation"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "check": "node --check lib/index.js && node --check lib/ops.js && node --check lib/env.js && node --check lib/doctor.js",
+    "smoke": "node scripts/smoke.mjs",
+    "check:meta": "node scripts/check-meta.mjs",
+    "prepack": "npm run check && npm run smoke"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cogito0823/dsh-motion.git"
+  },
+  "homepage": "https://github.com/cogito0823/dsh-motion#readme",
+  "bugs": {
+    "url": "https://github.com/cogito0823/dsh-motion/issues"
+  }
+}

package/skills/animation-router/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: animation-router
+description: 做代码动画/科普视频的总入口：先判题材（关系还是意象），再选画面层与交付管线。任何"做个动画/视频/讲清楚一个概念"的请求都先看这里。
+---
+
+# 总入口：先分题材，再选画面层
+
+## 1. 判题材
+
+| 题材 | 观众记住 | 判据 |
+|---|---|---|
+| 数学讲解 | 一个**关系** | 公式、坐标、推导、表格 |
+| 科普叙事 | 一个**意象** | 画面、比喻、节奏、材质 |
+
+## 2. 选画面层
+
+| 画面层 | 适合 | 不用它的理由 |
+|---|---|---|
+| Manim 片段（clip） | 公式、坐标系、几何变换 | 纯叙事片会显得呆板 |
+| Canvas 2D 逐帧 | 光、影、粒子、材质、转场 | 文字排版成本高 |
+| HTML / SVG | 排版、图文、简单图示 | 做不出辉光与颗粒 |
+
+三者都只是素材层；**交付统一在 HyperFrames 工程里完成**。
+
+## 3. 固定顺序
+
+```
+1. DESIGN.md（design spec）  ← 先定颜色/字体/禁用项
+2. 分镜表（storyboard）      ← 拍/秒/画面/旁白/验收点，先给用户确认
+3. 画面
+4. hyperframes check          ← 0 error 才算过
+5. motion_probe               ← 抽 12 帧看空镜/叠字
+6. 旁白 + 字幕 + −14 LUFS
+```
+
+## 4. 三条硬规则
+
+1. **没有 DESIGN.md 或参考语法，不开工**——否则每次都是同一个默认 look；
+2. **字幕放在 composition 层**，不烧进 Manim 或 canvas；
+3. **公式先过 `formula_check`**，再进画面。

package/skills/design-spec/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: design-spec
+description: 为动画片写 DESIGN.md（设计规范）：配色、字体、间距、禁用清单，以及从参考片/主题世界取语法。觉得画面丑、要统一系列风格、或开工前，读这个。
+---
+
+# 写一份 DESIGN.md
+
+## 为什么必须写
+
+HyperFrames 的 look 文档原话：**不给外部输入，相同的 brief 每次都会得到同一个 look；禁掉它只会滑到下一个默认。**
+
+外部输入按优先级：
+
+| 顺位 | 来源 | 科普片适用性 |
+|---|---|---|
+| 1 | 项目根 `DESIGN.md` / `frame.md` | ✅ 首选 |
+| 2 | 真实品牌 | ❌ 一般不适用 |
+| 3 | 参考片 / 参考图 | ✅ 只取语法，不取内容 |
+| 4 | 主题自身的世界 | ✅ 年代、材质、展示场景 |
+| 5 | 官方预设（preset） | ⚠️ 幻灯片语言，仅点名或做 deck 时用 |
+
+## 最小形态
+
+```markdown
+---
+colors:
+  ground: "#F3ECDD"
+  ink: "#20302A"
+  accent: "#B8442A"
+typography:
+  display: { family: "Georgia", weight: 400 }
+  body:    { family: "Helvetica Neue", weight: 400 }
+spacing: { margin: 140, rule: 2 }
+---
+
+# <片名> · <语言>
+
+## Do
+- 图形先有墨线，再有填充；线宽 2–3px
+- 只用 3–5 个颜色
+- 运动是"生长"，缓动一律 ease-out
+
+## Don't
+- 不用高饱和色、渐变球、发光、投影
+- 不把整段文字堆成卡片
+- 不用 Inter / Space Grotesk 做标题（生成式默认字体）
+
+## 版面
+- 页边距、标题基线、图注与字幕不重叠
+
+## 参考
+- 具体到某类图版、某支片、某个年代的印刷品
+```
+
+## 三种已验证的语言
+
+| 语言 | 适合 | 关键手段 |
+|---|---|---|
+| 纸感植物图版 | 生物 / 博物 | 纸纤维、水洗叠色、墨线、引线标注 |
+| 暗场发光 | 物理 / 天文 / 微观 | 近黑底、细线辉光、粒子、颗粒 + 暗角 |
+| 编辑排版 | 数学 / 数据 / 概念 | 网格、字阶、单一强调色 |

package/skills/qa-rubric/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: qa-rubric
+description: 代码动画交付前的自检清单：环境、公式、工程、画面、音频、字幕。渲染完但还没交付时使用。
+---
+
+# 交付前自检
+
+## 1. 环境
+
+先跑 `motion_doctor`，`ready.math` 与 `ready.delivery` 都为 true 再继续。
+
+## 2. 公式（仅数学题材）
+
+- 所有上屏公式先过 `formula_check`；
+- 逐条对照代码与画面，确认没有手改过的常数。
+
+## 3. 工程
+
+```bash
+npx hyperframes check
+```
+
+- 0 error 才算过；
+- 关注 lint（缺 `@font-face`）、layout（文字裁切/重叠）、contrast（对比度 < 3:1）。
+
+## 4. 画面
+
+```bash
+motion_probe --video <mp4>
+```
+
+- 看 contact sheet：无叠字、无出画、无空白帧；
+- `blankFrames` 里的帧逐一看过再决定是否重渲。
+
+## 5. 音频
+
+- 旁白最后一字早于结论画面；
+- 响度 ≈ −14 LUFS（±1），真峰值 ≤ −1.5 dBTP；
+- 没有爆音、没有截断。
+
+## 6. 字幕
+
+- 烧录字幕不遮挡主体；
+- `.srt` 与音频对齐，单行 ≤ 18 个汉字；
+- 烧录与 `.srt` 来自同一份 transcript。
+
+## 7. 交付
+
+mp4 + `.srt` + 场景源码 + `DESIGN.md` + 分镜表。