dsh-motion 0.1.1 → 0.2.0

package/NOTICE.md

@@ -8,6 +8,7 @@
 | [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` |
+| [Lemo-Opuscar](https://github.com/lemomo-ai/lemo-opuscar) | MIT（风格文档/代码）· CC BY 4.0（demo 静帧） | `swiss-motion` / `dataviz` / `blueprint` 三个风格的改编来源；只取语法与规范，不打包 demo 代码 |
 | [FFmpeg](https://ffmpeg.org) | LGPL/GPL（取决于构建） | 渲染、后期、抽帧；**不打包**，由用户自行安装 |
 
 字体不随包分发；若你的 `DESIGN.md` 指定了第三方字体，请确认其许可（OFL / 商用授权）。

package/README.md

@@ -8,17 +8,54 @@
 **代码生成的数学 / 科普动画**，给 [DeepSeek Harness](https://github.com/deepseek-ai) 用的插件。
 画面由代码逐帧生成，不经过任何文生视频（text-to-video）模型。
 
-提供四个工具：
+提供五个工具：
 
 | 工具 | 作用 |
 |---|---|
+| `motion_frames` | **极简模式（默认）**：直接从场景出帧，不生成视频、不用 HF；几秒拿到 storyboard PNG 与 layout 问题 |
 | `motion_doctor` | 环境自检（Node / FFmpeg / Python venv / manimgx / sympy / Chrome / HyperFrames） |
 | `motion_render` | 渲染 Manim / manimgx 场景，可加运动模糊、颗粒、暗角、调色 |
-| `motion_probe` | 抽帧拼 contact sheet，报告全黑 / 过曝的空镜 |
+| `motion_probe` | 成片抽帧拼 contact sheet，报告全黑 / 过曝的空镜 |
 | `formula_check` | 用 SymPy 判断两个表达式是否恒等 |
 
 外加三个技能：`animation-router`（题材路由）、`design-spec`（写 DESIGN.md）、`qa-rubric`（交付自检）。
 
+## 两种模式
+
+| | 极简模式（默认） | 交付模式 |
+|---|---|---|
+| 画面来源 | `motion_frames`：按时间点直接出 PNG | `motion_render` → MP4 → HyperFrames 合成 |
+| 是否需要 HF | 不需要 | 需要（字幕、旁白、混音、编码） |
+| 检查方式 | 看帧（读图），没有"渲染完再抽帧" | `motion_probe` / `hyperframes check` |
+| 典型耗时 | 2–6 秒/次 | 数秒–数十秒；HF 合成为分钟级 |
+| 什么时候用 | 写场景、调节奏、改版式 | 定稿后出片 |
+
+先出帧、改到满意，再决定要不要渲染成片。`motion_probe` 是给已经存在的视频做体检的，不是默认步骤。
+
+## 风格库
+
+默认 **瑞士动态排版（swiss-motion）**；另外两套按题材选。全部改编自 [Lemo-Opuscar](https://github.com/lemomo-ai/lemo-opuscar)（MIT），不是自创。
+
+| 风格 | 适合 | 规范 |
+|---|---|---|
+| `swiss-motion`（默认） | 公式、定义、数据结论 | [STYLE](styles/swiss-motion/STYLE.md) · [tokens](styles/swiss-motion/tokens.json) |
+| `dataviz` | 趋势、比较、分布、科学数据 | [STYLE](styles/dataviz/STYLE.md) · [tokens](styles/dataviz/tokens.json) |
+| `blueprint` | 几何证明、结构、尺寸关系 | [STYLE](styles/blueprint/STYLE.md) · [tokens](styles/blueprint/tokens.json) |
+
+**参考与示例统一用 HyperFrames 的库**：[examples](https://hyperframes.heygen.com/examples)、[catalog](https://hyperframes.heygen.com/catalog)、[frame.md](https://hyperframes.heygen.com/prompting/design-systems)。本仓库不再内置样片/分集；`showcase/` 只放可复现的演示。
+
+项目 `DESIGN.md` 头部写 `style: swiss-motion` + `style_version: 1.0.0`。风格来源、HF 集成、抽帧能力与 Lemo 调研见 [docs/ai-native-motion.md](docs/ai-native-motion.md)。
+
+## 演示
+
+三个类别各一支 10 秒内短片，记录出帧/渲染耗时：
+
+- 公式：[showcase/swiss-euler](showcase/swiss-euler)
+- 数据：[showcase/dataviz-secant](showcase/dataviz-secant)
+- 几何：[showcase/blueprint-pythagoras](showcase/blueprint-pythagoras)
+
+汇总见 [showcase/README.md](showcase/README.md)。
+
 ## 安装
 
 ```bash
@@ -39,10 +76,10 @@ 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 3 + venv | 数学功能需要 | `manimgx`、`sympy`；极简出帧只需这一项 |
+| FFmpeg + ffprobe | 成片/探针需要 | 后期与抽帧；出帧不需要；不随包分发 |
+| Chrome | 用了 HF 才需要 | HyperFrames 优先复用系统 Chrome |
+| HyperFrames | 交付模式需要 | `npx hyperframes`，不随包分发 |
 
 ### 准备 Python 环境
 
@@ -85,18 +122,20 @@ class Derivative(Scene):
         self.wait(1)
 ```
 
-### 2. 渲染
+### 2. 先出帧（默认，不需要 HF）
 
 ```jsonc
-// motion_render
-{ "file": "/abs/path/scenes/derivative.py", "scene": "Derivative", "width": 1920, "height": 1080, "fps": 30 }
+// motion_frames
+{ "file": "/abs/path/scenes/derivative.py", "times": ["1.2", "4.5", "end"] }
 ```
 
-### 3. 自检
+返回 `storyboard` PNG 路径与 layout 问题清单（实测 3–4 帧约 3–5 秒）。看图改场景，不满意就再来一轮；这一步不生成 mp4，也不需要 HyperFrames。
+
+### 3. 需要成片时再渲染
 
 ```jsonc
-// motion_probe
-{ "video": "/abs/path/scenes/derivative.mp4", "frames": 12 }
+// motion_render
+{ "file": "/abs/path/scenes/derivative.py", "scene": "Derivative", "width": 1920, "height": 1080, "fps": 60 }
 ```
 
 ### 4. 公式先验
@@ -108,14 +147,20 @@ class Derivative(Scene):
 
 ## 和 HyperFrames 的关系
 
-本插件**不是**渲染框架。成片（合成、字幕、音频混流、编码）交给 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
+npx hyperframes init my-video
+npx hyperframes add data-chart          # 约 450 个现成 block / component
+npx hyperframes check                   # 运行时、版式、对比度
+npx hyperframes render -o out.mp4
 ```
 
+- **风格契约**：HF 用 `frame.md`（`DESIGN.md` 的超集）做 brand truth；本仓库的 `DESIGN.md` / `styles/<name>/` 是同一套思路的轻量版，两边可以互读。
+- **参考库**：不要把参考片塞进本仓库；直接看 HF 的 [examples](https://hyperframes.heygen.com/examples)、[catalog](https://hyperframes.heygen.com/catalog) 和 [frame.md templates](https://hyperframes.dev/design)。
+- **分工**：manimgx 负责公式/坐标/几何这类确定性画面；HF 负责排版、图文、字幕、音频与交付。
+- **HF 不必先出片再截图**：`npx hyperframes snapshot <project> --at 2.9,10.4` 直接抓指定时刻的 PNG；`--frames 10 --review` 出 contact sheet；只有要完整序列时才 `render --format png-sequence`。
+
 字幕建议“一份 transcript 出两个产物”：烧录进画面 + 独立 `.srt`。
 
 ## 故障排除
@@ -124,28 +169,66 @@ npx hyperframes@0.8.193 render <project> -o out.mp4 --quality delivery
 |---|---|---|
 | `找不到 Python 虚拟环境` | 未建 venv | 按上文创建，并 `pip install manimgx sympy` |
 | `找不到渲染器: …/manimgx` | venv 里没装 | `pip install manimgx` |
+| `motion_frames` 报 layout 问题 | 压字 / 出画 / 字号过小 | 按返回的 `[n]` 逐条改场景；退出码 1 是“有问题”，不是崩溃 |
 | 渲染断字 / 字体回退 | 字体未声明 `@font-face` | 把 `.woff2` 放工程 `assets/fonts/` 并声明 |
 | `ffprobe` 缺失 | 只装了 ffmpeg | 装完整 FFmpeg，插件会退回 `ffmpeg -i` 解析 |
 | 抽帧全黑 | 片头/片尾空镜 | 用 `tpad=stop_mode=clone` 补帧，或剪掉 |
 
+## 本地开发（维护者）
+
+桌面 App **独占** `desktop` profile，CLI 不能管理它（`dsh plugin --profile desktop` 会直接报错）。
+把插件切到当前 checkout 的完整步骤、验证命令和禁忌清单记在
+[MAINTAINING.md](https://github.com/cogito0823/dsh-motion/blob/main/MAINTAINING.md)。
+
+一句话版本：插件管理器里**卸载** `dsh-motion` → **安装本地目录** `/path/to/dsh-motion` → `⌘⇧R` 重启；
+之后 `motion_doctor` 第一行的「插件来源」会直接说明当前跑的是本地 checkout 还是 npm 安装。
+
+日常改代码**不需要重装**：link 安装一次后，改 `lib/ops.js` / `lib/doctor.js` 会在下一次工具调用时按 mtime 热加载；只有改工具名/参数 schema 才需要 `⌘⇧R`。风格、`tokens.json`、场景文件本来就是运行时读取，不用重启。详见 [docs/dev-loop.md](docs/dev-loop.md)，也可以完全绕开 Harness：
+
+```bash
+node scripts/dev.mjs frames showcase/swiss-euler/scene.py 1,3,end
+node scripts/dev.mjs render showcase/swiss-euler/scene.py --fps 30
+```
+
 ## 发版（维护者）
 
-首次发布会把名字与 2FA 绑好；之后用 GitHub Actions 的 Trusted Publishing，不需要 token，也不需要 OTP。
+首次发布会把包名与 2FA 绑好；之后走 GitHub Actions 的 **Trusted Publishing**（OIDC），不需要 token、不需要 OTP，自动附带 **provenance 签名**。
+
+### 一次性绑定
+
+npm 包设置 → **Settings → Trusted Publisher → GitHub Actions**：
 
-1. 在 npm 包设置里绑定可信发布者：**Package → Settings → Trusted Publisher → GitHub Actions**
-   - owner: `cogito0823`
-   - repository: `dsh-motion`
-   - workflow: `release.yml`
-2. 然后：
+| 字段 | 值 |
+|---|---|
+| Organization or user | `cogito0823` |
+| Repository | `dsh-motion` |
+| Workflow filename | `release.yml` |
+| Environment | 留空 |
+
+Allowed actions：勾 **`npm publish`** 即可（`npm dist-tag` 用不到）。
+
+### 发一版
 
 ```bash
 npm version patch          # 0.1.0 -> 0.1.1
-git push --follow-tags     # 触发 release.yml
+git push --follow-tags     # 触发 .github/workflows/release.yml
 ```
 
-工作流会校验 tag 与 `package.json` 一致、跑 check/smoke，再 `npm publish --provenance`。
+工作流会：校验 tag 与 `package.json` 版本一致 → `check` + `smoke` → `npm publish --provenance --access public`。
+
+### 两个必须知道的坑
+
+1. **npm CLI 必须 ≥ 11.5.1**。Node 22 自带的 npm 10 不支持 OIDC，会把占位 token 发出去，registry 返回误导性的 `404 not in this registry`。工作流里已加 `npm install -g npm@latest`。
+2. **发布后不是立刻可见**。CLI 会打印 `Your package is being processed and may take a few minutes to become available`，通常 1–2 分钟后 `npm view` 才查得到。这不是失败。
+
+### 验证
+
+```bash
+npm view dsh-motion version
+npm view dsh-motion@<version> dist.attestations   # 应含 provenance / SLSA v1
+```
 
-若工作流失败，退回手动发布：`npm publish --access public`（需 passkey 或 OTP）。
+npm 包页面会出现 **“Built and signed on GitHub Actions”**。
 
 ## 许可
 

package/docs/ai-native-motion.md

@@ -0,0 +1,233 @@
+# AI 原生动效：风格、HyperFrames 与极简模式
+
+调研时间 2026-10-25。结论先行：
+
+1. **风格不是形容词，是外部输入。** 通行做法是给 agent 一份可引用的 truth（`frame.md` / `DESIGN.md` / 参考片），把它写成规范，再用**真实代码出的风格帧**验收；不是让模型"感觉一下"。
+2. **风格库是常见基础设施。** HyperFrames 有 catalog（约 450 个 block/component）和 `frame.md` 模板；[Lemo-Opuscar](https://github.com/lemomo-ai/lemo-opuscar) 有 59 个纯代码影片风格，每个是一份 `STYLE.md`（style prompt）+ 一支 demo。
+3. **极简模式 = 先出帧。** 在写场景的阶段直接渲染关键帧（不编码视频、不进 Chrome/HF），看过再继续；视频只在定稿后生成。
+
+## 1. 通行做法：风格怎么确定
+
+### 1.1 先给 truth，再谈风格
+
+HyperFrames 的 [design systems 文档](https://hyperframes.heygen.com/prompting/design-systems) 说得很直接：让 agent "make it on-brand" 是最模糊的指令，agent 只能自己发明一个 brand。修法永远是给一份 **source of brand truth**：design spec、线上站点或 Figma 文件。
+
+`frame.md` 的 frontmatter 是"机器可读的品牌"：精确 hex、字体家族、字重关系；正文写 intent 与 Do/Don't。文档给了一个可复用的边界：
+
+- **严格**：品牌色、字体、字重关系、底色；
+- **为视频放大**：字号、装饰透明度、描边宽度；
+- **交给 agent 编排**：版面、间距、运动。
+
+原话是 "Pin the palette and typography. Delegate the frame."——这也解释了为什么我们的 `STYLE.md` 把版面坐标写死、却允许分集覆盖局部：**token 是契约，构图是创作**。
+
+### 1.2 风格帧先于视频
+
+Lemo-Opuscar 的 [DIRECTOR.md](https://github.com/lemomo-ai/lemo-opuscar/blob/main/DIRECTOR.md) 把这一步叫 **"Prove the look"**：
+
+- 有角色：一张 model sheet + 两张风格帧；
+- 无角色：三张风格帧，其中一张是 signature shot；
+- 必须用**真实绘制代码**渲染，不是 mock-up；先对照 `STYLE.md` 自检，再往下走；
+- 分镜（6–9 张关键镜头拼一张 sheet）**只在用户要求时**才做，做完等确认。
+
+这与"渲染完再抽帧检查"是两件事：前者在写代码的循环里，成本是秒级；后者在成片之后，成本是分钟级。
+
+### 1.3 风格库的两种形态
+
+| 形态 | 例子 | 作用 |
+|---|---|---|
+| 组件/区块库 | HF catalog（约 450 个 block / component） | 不手搓转场、字幕条、图表、3D 相机 |
+| 风格库 | Lemo 59 个 `STYLE.md` | 定语气、材质、颜色逻辑、运动语法 |
+
+Lemo 的每个风格文件是一份 **style prompt**：定位与"不是什么"、材料与渲染、颜色逻辑、字体与字幕、运动质量、相机语法、声音、native moves、媒介陷阱、引擎、变化空间。它不写具体故事——故事是用户的。这和本仓库 `STYLE.md` 的结构同源。
+
+### 1.4 都建立在确定性上
+
+HF 的卖点是 "same input, same frames, same output"：HTML + 可 seek 的动画，headless Chrome 逐帧截，FFmpeg 编码。Lemo 同样要求 `render(t)` 是纯函数：没有 `Date.now()`、没有未播种随机、任意帧可单独渲染。**风格可复现的前提是画面可复现。**
+
+## 2. 要不要用 Lemo 这类风格库
+
+用它的**方法**，不必用它的**素材**：
+
+- Lemo-Opuscar 明确写着风格是为 Claude Opus 5.5 调的，别的模型不一定复现得好；代码 MIT、demo 与静帧 CC BY 4.0；
+- 它的 59 个风格覆盖纸感、印刷、像素、3D、纪录片等，适合当"语言菜单"，不适合直接当品牌规范；
+- 可借鉴的三件事：`STYLE.md` 作为 style prompt、三张风格帧验收、分镜只在被要求时做；
+- 授权上，demo 静帧可商用但需署名 LemoLab；风格文件本身是 MIT。
+
+本仓库的选择：删除自创的 `dark-editorial`，改为 3 套改编自 Lemo 的风格（`swiss-motion` / `dataviz` / `blueprint`），每套按 `STYLE.md` + `tokens.json` + `theme.py` + `preview.jpg` 落地；外部参考统一指向 HF。
+
+## 3. 和 HyperFrames 怎么结合
+
+HF 是"HTML → MP4"的合成/渲染层，不是绘制层；本插件是绘制层。
+
+| 层 | 负责 | 产物 |
+|---|---|---|
+| manimgx / dsh-motion | 公式、坐标、几何、逐帧确定性画面 | PNG 帧 / MP4 clip |
+| HyperFrames | 排版、字幕、旁白、混音、转场、编码 | 成片 MP4 / WebM / PNG sequence |
+| 共享契约 | `DESIGN.md` / `frame.md` | 颜色、字体、禁用项、语气 |
+
+接入方式（按成本从低到高）：
+
+1. **只借规范**：HF 的 `frame.md` 与本仓库 `DESIGN.md` 互读；不装 HF 也能用同一套 token。
+2. **借组件**：`npx hyperframes add <block>` 取现成图表、字幕、转场，不必重画。
+3. **整片合成**：把 `motion_render` 的 clip 放进 HF composition，字幕走 composition 层，最后 `npx hyperframes render`。
+
+```bash
+npx hyperframes init my-video
+npx hyperframes add data-chart
+npx hyperframes check
+npx hyperframes render -o out.mp4
+```
+
+HF **不需要先生成视频再截图**。它有三条不产出 mp4 的路径：
+
+| 命令 | 产出 | 用途 |
+|---|---|---|
+| `npx hyperframes snapshot <project> --at 2.9,10.4,18.7` | 指定时刻的 PNG | 版式/关键帧检查，最接近"抽帧" |
+| `npx hyperframes snapshot <project> --frames 10 --review` | 等间隔帧 + contact sheet + 转场接缝帧 | 通看全片 |
+| `npx hyperframes render --format png-sequence` | 完整 RGBA 帧序列 | 需要每一帧时 |
+| `npx hyperframes check` | 运行时/版式/对比度/运动的报告 | 不开视频的体检 |
+
+`snapshot` 的说明原话是 "Capture specific frames as PNGs, without waiting for a full render"：它会 bundle 项目、起 headless Chrome、seek 到指定时刻截图，但不编码视频。`--zoom` 还能裁局部、`--against` 能和参考片逐帧对比。
+
+所以结论是：**HF 可以抽帧，而且 snapshot 就是为这件事做的**；只有需要完整序列时才用 png-sequence。对本插件来说，`motion_frames`（manimgx inspect）仍然是更轻的一层，因为它连浏览器都不用起。
+
+## 4. 极简模式：直接拿到帧
+
+### 4.1 通用实现
+
+manimgx 自带 `inspect`：只画请求的时刻，做版式检查，**不编码视频**。
+
+```bash
+manimgx inspect scene.py -t 1.2,4.5,end
+```
+
+- 输出一张（或多张）storyboard PNG，每格标注 `#play t=… file:line`；
+- 同时报 layout 问题：压字、出画、字号过小、线/填充盖字；
+- 有 layout 问题时退出码为 1，但报告仍然完整。
+
+本仓库把它包成 `motion_frames`，返回结构化 JSON（`storyboard` 路径、`layoutProblems`、`durationSec`、`wallSec`），模型可以直接读图。实测 4 帧约 3–5 秒；同一支 10 秒 / 60fps 场景渲染约 6 秒。渲染成本随**时长**线性增长，看帧成本只跟**采样数**有关，长片差距才明显（对比 HF 合成则是分钟级）。
+
+### 4.2 推荐循环
+
+```
+DESIGN.md
+  → motion_frames（3–6 帧：开场 / 转折 / 结论）
+  → 改场景 → 再出帧（秒级）
+  → 需要给用户看分镜时：6–9 帧（真实代码）
+  → formula_check
+  → motion_render（定稿后）
+  → 需要字幕/旁白/混音：进 HF
+  → motion_probe / hyperframes check（只对成片）
+```
+
+### 4.3 为什么快
+
+| 做法 | 成本 | 什么时候发现版式问题 |
+|---|---|---|
+| `motion_frames` | 2–6 秒（与时长无关） | 写场景时 |
+| `motion_render` + `motion_probe` | 5 秒–1 分钟（随时长） | 渲染后 |
+| HF `check` / `png-sequence` | 分钟级（起浏览器 + 跑 composition） | 合成后 |
+
+关键不是"抽帧"本身，而是**把检查点前移**：帧是绘制的直接产物，视频只是帧的编码；在编码之前检查，就省掉了编码、起浏览器、解码抽帧这几次搬运，而且检查成本不再随时长膨胀。
+
+### 4.4 建议的默认
+
+- 默认工具链：`motion_frames`（不装 HF 也能跑）；
+- 默认检查：看 storyboard PNG + `layoutProblems`，不看 `blankFrames`（还没有视频）；
+- 默认不生成：mp4、HF 工程、视频抽帧 contact sheet；
+- 需要交付时才升级到 `motion_render` / HF；
+- 成片检查（`motion_probe`）只在已经有 mp4 时运行，不做"为了检查而渲染"。
+
+## 参考
+
+- [HyperFrames design systems](https://hyperframes.heygen.com/prompting/design-systems)
+- [HyperFrames examples](https://hyperframes.heygen.com/examples) · [catalog](https://hyperframes.heygen.com/catalog)
+- [HyperFrames CLI rendering](https://hyperframes.heygen.com/guides/rendering)
+- [Lemo-Opuscar](https://github.com/lemomo-ai/lemo-opuscar) · [DIRECTOR.md](https://github.com/lemomo-ai/lemo-opuscar/blob/main/DIRECTOR.md) · [TECHNIQUE.md](https://github.com/lemomo-ai/lemo-opuscar/blob/main/TECHNIQUE.md)
+- 本地 `manimgx inspect --help`（manimgx 0.1.1）
+
+## 4.5 效率：大家怎么缩短时间
+
+共识是**把检查点前移、把渲染延后**：
+
+| 做法 | 出处 | 效果 |
+|---|---|---|
+| 先出静帧/contact sheet，不先出片 | Lemo `still.mjs` + `sheet.py`；HF `snapshot`；本仓库 `motion_frames` | 秒级看版式，省掉编码 |
+| 指定时刻抽帧，而不是等整段 | HF `snapshot --at` / `--frames` / `--review` | 不渲染整条时间线 |
+| 低分辨率 / draft 预览，定稿才 full | HF `--quality draft`、`--resolution`；Lemo 先 still | 迭代快、画质最后再提 |
+| 并行渲染 | Lemo `video.mjs --workers 3`；HF GPU / Lambda / Cloud Run | 线性缩短编码时间 |
+| 只重渲改动镜头 | 帧是 `render(t)` 纯函数，可单帧/单段重跑 | 不重做全片 |
+| 独立 rubric 评审代替反复肉眼 | mg-styles-15 的 7 维 rubric、Lemo 的 review loop | 一轮改到点上 |
+| 确定性 + 缓存 | HF `same input, same frames`；Lemo 无随机/无时钟 | 可回归、可并发 |
+
+本仓库三个 demo 的实测（同一台机器）：
+
+- 出 3 帧：**2.4–4.3 s**；渲染 6–10 秒成片：**2.8–5.0 s**；
+- 关键不是"帧比视频快多少"，而是**看帧成本与片长无关**，且不经过编码、起浏览器、抽帧三次搬运；
+- 如果已经在 HF 里，用 `hyperframes snapshot` 而不是"先 render 再 ffmpeg 截图"。
+
+## 4.6 开发调试
+
+服务端插件没有 HMR，但也不需要每次重装：
+
+- `link:` 安装一次即可；改 `lib/ops.js` / `lib/doctor.js` 由 mtime 热加载，下一次工具调用生效；
+- 改 `styles/*`、场景、tokens 本来就不用重启；
+- 只有工具名/描述/参数 schema 变化才 `⌘⇧R`；
+- 可以完全绕开 Harness：`node scripts/dev.mjs frames|render|probe|doctor ...`。
+
+细节见 [dev-loop.md](dev-loop.md)。
+
+## 5. 现成的风格体系（2026-10 可直接采用）
+
+不必从零写风格文档。这个生态已经沉淀出几套公开、可复用的体系：
+
+| 体系 | 规模 | 提供什么 | 适合拿什么 |
+|---|---|---|---|
+| [Lemo-Opuscar](https://github.com/lemomo-ai/lemo-opuscar) | 59 个库内风格 + OPUSCAR 98 的 98 个 | 每个风格 `style.json`（slug / 中英文名 / 分类 / uses / 时长）+ `STYLE.md`（11 节：定位、材料、颜色逻辑、字体、运动、相机、声音、native moves、陷阱、引擎、变化空间）+ demo 片 + `DIRECTOR.md` / `TECHNIQUE.md` + 改风格流程 | 整套 schema、风格索引、选风格与改风格的方法 |
+| [mg-styles-15](https://github.com/Vincentwei1021/mg-styles-15) | 15 个 10 秒风格 | 每个风格：完整 prompt + 全部源码 + 成片；[template.md](https://github.com/Vincentwei1021/mg-styles-15/blob/main/template.md) 四段式（Output / Technical route / Creative seed / Signature features）；[rubric.md](https://github.com/Vincentwei1021/mg-styles-15/blob/main/rubric.md) 独立评审 + 两轮修改 | 写新风格的模板、可检验的 signature features、评审 rubric |
+| [javascript-animation-skills](https://github.com/iart-ai/javascript-animation-skills) | 1 个 skill 包，多种画风 | 从题材推导 look、beat grid / shot list 数据化、contact sheet 自检、零素材审计 | agent 工作流与自检清单 |
+| [opus-video-skills](https://github.com/tuzhechen2005/opus-video-skills) | 2 个风格 | 每个风格一个 skill：`SKILL.md` + 可运行 `template/` + worked example | 风格即 skill 的工程组织方式 |
+| [HyperFrames frame.md](https://hyperframes.heygen.com/prompting/design-systems) | 一组设计模板（画廊，数量未逐一核对） | 品牌 token（frontmatter）+ 意图/Do-Don't + 模板画廊 | 品牌/版式契约与交付层 |
+| [ClaudeAnimationBase](https://github.com/JohnHeibel/ClaudeAnimationBase) | 基础引擎 | 帧为时间纯函数、headless 渲染、逐镜头评审 | 底层渲染约定 |
+
+### 共同做法
+
+1. **风格 = 不变量 + 自由故事。** `STYLE.md` 锁死 look、颜色、字体、运动、声音；故事、镜头、节奏由导演决定（Lemo 的 AGENTS.md 原话：`STYLE.md` is fixed；everything else is yours to direct）。
+2. **风格按名字选，不按形容词选。** 用户说 "swiss-motion" / "瑞士动态排版"，agent 查索引、读 `STYLE.md`；没选就推荐 2–3 个最接近的。
+3. **风格文档有固定骨架。** Lemo 是 11 节；mg-styles-15 是四段式，其中 signature features 必须可检验（"cubic-bezier(0.34,1.56,0.64,1)，错峰 2–4 帧"，不是"要有弹性"）。
+4. **先风格帧，后分镜，最后成片。** 三张真实代码出的风格帧 → 用户要看才做 6–9 张分镜 → 成片；风格帧不过不往下走。
+5. **独立评审。** 另一个 AI 用 rubric 按 7 个维度打分（风格保真、概念、运动、排版、质感、声画同步、技术），给 5–10 条带时间码的修改，再改两轮。
+6. **确定性。** 帧是 `render(t)` 的纯函数；同一输入同一输出，便于批量与回归。
+
+### 对本仓库的建议
+
+不要搬 59 套，也不要再自己发明一套写法。按 Lemo 的 schema 升级 `styles/`。
+
+**筛选标准**（按顺序）：
+
+1. **内容原语**：公式/排版、图表/数据、几何/工程、流程/空间、概念/文字——每个原语一套，避免重叠；
+2. **可实现性**：只需 2D 矢量、文字、坐标轴、标注；不依赖照片、实拍、角色绑定、重着色器；
+3. **去重**：已有 `swiss-motion` 占住“排版/公式”，就不再接同角色的风格；
+4. **证据**：`style.json` 的 `uses` 对得上，再用 `motion_frames` 出 3 张风格帧验收；不过就换。
+
+按这套标准（2026-10-25 查 `style.json`）：
+
+| 风格 | `uses` | 判定 |
+|---|---|---|
+| `swiss-motion` | Brand identity / Events / Design education | **核心**：公式与排版 |
+| `dataviz` | Data journalism / Reports / Climate & science | **核心**：图表与数据 |
+| `blueprint` | Engineering / Hardware launches / Tech explainers | **核心**：几何与工程 |
+| `whiteboard` | Explainers / Online courses / Science | 可选：科学讲解；手绘笔画成本中等 |
+| `iso-infographic` | Process explainers / Supply chains / Annual reports | 可选：流程/空间；等距投影成本中等 |
+| `pictogram-motion` | Sports events / Visual identity / Event openers | 不选：偏活动/体育，公式场景弱 |
+| `dark-keynote` | Product launches / SaaS / Keynotes | 不选：与 `swiss-motion` 的排版角色重叠 |
+
+已落 **3 个核心**（`swiss-motion` / `dataviz` / `blueprint`）；`whiteboard`、`iso-infographic` 留作可选，等有真实题材再验。这个列表是筛选结果，不是永久名单——风格帧验收不过就换。
+
+落地方式：
+
+1. 每个风格一个目录：`style.json`（元数据）+ `STYLE.md`（不变量，按 Lemo 结构）+ `tokens.json` + `theme.py` + `preview.jpg`；
+2. 用 mg-styles-15 的四段式模板写**新**风格，用它的 rubric 做评审；
+3. 画面仍由 manimgx 画，不复制它们的 Canvas/WebGL demo 代码，只取语法与 prompt；
+4. 交付层继续交给 HF，`frame.md` 只做品牌/版式契约；
+5. 标注来源与许可：Lemo 代码/文档 MIT，demo 静帧 CC BY 4.0（署名 LemoLab）；mg-styles-15 MIT；HF Apache-2.0。

package/docs/dev-loop.md

@@ -0,0 +1,55 @@
+# 开发调试：不重启插件
+
+## 先分清哪些改动需要重启
+
+| 改动 | 是否需要重启 Harness | 原因 |
+|---|---|---|
+| `styles/*`（STYLE / tokens / theme / preview） | **不需要** | 场景运行时才读 Python/JSON |
+| `showcase/*` 场景 | **不需要** | manimgx 每次执行都重新加载 |
+| `lib/ops.js`、`lib/doctor.js` | **不需要**（本仓库已做 mtime 热加载） | 工具每次调用按 mtime 重新 import |
+| 工具名 / 描述 / 参数 schema（`lib/index.js`） | 需要 | 注册发生在 `apply()` 启动时 |
+| `lib/fresh.js`、`lib/env.js` | 需要 | 前者是加载器本身，后者被静态 import 缓存 |
+| 安装方式变化（link ↔ npm） | 需要，且要重装 | profile 清单只有一个依赖字段 |
+
+所以"改代码就要重装"是误判：**link 安装一次之后不用再重装**；只有改工具 schema 才需要 `⌘⇧R`。
+
+## 方案 1：mtime 热加载（已内置）
+
+`lib/fresh.js` 按文件 mtime 重新 import：
+
+```js
+const mtime = statSync(new URL(href)).mtimeMs
+if (hit && hit.mtime === mtime) return hit.module
+return import(`${href}?t=${mtime}`)
+```
+
+`lib/index.js` 里所有工具实现都走 `importFresh()`：
+
+- 改 `ops.js` 的函数体 → 下一次 `motion_frames` / `motion_render` 调用就生效；
+- 改 `doctor.js` → 下一次 `motion_doctor` 生效；
+- 没有变化时命中缓存，额外开销是一次 `statSync`。
+
+一次性的代价：这个机制本身要重启一次才能加载；之后改实现不用再重启。
+
+## 方案 2：不走 Harness 的 dev CLI
+
+```bash
+node scripts/dev.mjs frames showcase/swiss-euler/scene.py 1,3,end
+node scripts/dev.mjs render showcase/swiss-euler/scene.py --fps 30
+node scripts/dev.mjs probe out.mp4
+node scripts/dev.mjs doctor
+```
+
+它直接 import `lib/ops.js`，不经过插件注册，适合调参数、量耗时、跑回归。改完再让工具层调用同一份代码。
+
+## 方案 3：把变化关在数据里
+
+- 风格：只改 `tokens.json` / `STYLE.md`，场景 import theme，本来就不用重启；
+- 场景：改 `.py` 直接重跑 `manimgx`；
+- 交付：HF 的 `snapshot` / `check` 也不依赖本插件。
+
+## 不要做的事
+
+- 每次改代码都卸载/重装插件：link 安装不需要；
+- 在 `lib/index.js` 里写实现：它一改就要重启；实现放 `ops.js` / `doctor.js`；
+- 改 `env.js` 后指望热加载：它是静态 import，仍要重启。

package/lib/doctor.js

@@ -4,7 +4,9 @@
  */
 
 import { execFile } from 'node:child_process'
-import { existsSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { promisify } from 'node:util'
 
 import {
@@ -19,6 +21,25 @@ import {
 
 const exec = promisify(execFile)
 
+/** 当前这份代码所在的 lib 目录与包根（npm 安装还是本地 checkout 一眼可辨）。 */
+const LIB_DIR = dirname(fileURLToPath(import.meta.url))
+const PACKAGE_ROOT = dirname(LIB_DIR)
+
+/**
+ * 报告"正在跑的是哪一份 dsh-motion"：版本 + lib 路径 + 安装形态。
+ * 用 import.meta.url 推导，符号链接会被 Node 解析成真实路径，所以 link 安装会显示仓库路径。
+ */
+export function pluginSource() {
+  let version = 'unknown'
+  try {
+    version = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8')).version ?? 'unknown'
+  } catch {
+    // 读不到 package.json 时只报路径
+  }
+  const kind = LIB_DIR.includes(`${sep}node_modules${sep}`) ? 'npm 安装' : '本地 checkout'
+  return { version, kind, lib: LIB_DIR }
+}
+
 async function runVersion(bin, args) {
   try {
     const { stdout, stderr } = await exec(bin, args, { timeout: 15_000 })
@@ -44,6 +65,9 @@ export async function doctor(config = {}) {
   const rows = []
   const add = (item, ok, detail, fix) => rows.push({ item, ok, detail, fix })
 
+  const source = pluginSource()
+  add('插件来源', true, `${source.version} · ${source.kind} · ${source.lib}`, null)
+
   const nodeMajor = Number(process.versions.node.split('.')[0])
   add('Node.js', nodeMajor >= 22, `v${process.versions.node}`, nodeMajor >= 22 ? null : '升级到 Node 22 或更高')
 
@@ -81,6 +105,7 @@ export async function doctor(config = {}) {
 
   return {
     ready,
+    source,
     summary: ready.math
       ? '数学渲染与成片可用'
       : ready.delivery

package/lib/fresh.js

@@ -0,0 +1,21 @@
+/**
+ * 开发期热加载：按文件 mtime 重新 import，避免每次改 lib 都重启 Harness。
+ *
+ * 只对"实现"生效（ops/doctor）；工具名、描述、参数 schema 在 apply() 时
+ * 注册，改这些仍然需要重启。样式、场景、tokens 是运行时读取的，本来就不用重启。
+ */
+
+import { statSync } from 'node:fs'
+
+const cache = new Map()
+
+export async function importFresh(url) {
+  const href = typeof url === 'string' ? url : url.href
+  if (process.env.DSH_MOTION_NO_FRESH === '1') return import(href)
+  const mtime = statSync(new URL(href)).mtimeMs
+  const hit = cache.get(href)
+  if (hit && hit.mtime === mtime) return hit.module
+  const module = await import(`${href}?t=${mtime}`)
+  cache.set(href, { mtime, module })
+  return module
+}