dsh-motion

dsh plugin --profile web add dsh-motion

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 用的插件。

画面由代码逐帧生成，不经过任何文生视频（text-to-video）模型。

提供六个工具：

工具 · 作用

motion_frames · 极简模式（默认）：直接从场景出帧，不生成视频、不用 HF；几秒拿到 storyboard PNG 与 layout 问题；输出落 <project>/out/frames

motion_doctor · 环境预检（一次调用）：运行时 + 真实可用字体清单 + 公式转换 + API/函数/rate；按指纹缓存 12 h（不再按 Node 版本分叉）

motion_setup · 环境自愈：建 venv、装 manimgx/sympy（tts=true 加 edge-tts）；在宿主进程执行，不受模型 bash 沙箱限制

motion_render · 渲染 Manim / manimgx 场景；必须有 motion.project.json，APPROVALS.json 是前置账本（已通过就直接渲，未通过才走一次平台审批）；输出落 <project>/out/render

motion_probe · 成片自检：逐帧扫描全片（默认下采样到 480p，判据不变、不抽样）报告全黑/过曝，拼 contact sheet，并给出 fps/帧数/VFR/CFR

formula_check · 用 SymPy 判断两个表达式是否恒等

外加三个技能：animation-router（题材路由 + API/命令速查）、design-spec（写 DESIGN.md）、qa-rubric（交付自检）。

它们由插件通过 ctx.skills 注册，安装后自动出现在会话技能目录，不需要再复制到 ~/.dsh/skills。

模块边界、进程拓扑、数据流与不变量见 [ARCHITECTURE.md](ARCHITECTURE.md)；设计理由与外部调研见

[docs/ai-native-motion.md](docs/ai-native-motion.md)。

版本与发布说明

npm 页面只渲染 README，不提供每个版本的 release note；完整记录在

GitHub Releases。下面是当前版本摘要：

版本 · 日期 · 主要内容

0.10.3 · 2026-10-29 · 性能：motion_probe 帧数改读容器头、空镜扫描改 480p 下采样（逐帧不抽样），600 s 片 112 s → 12 s；新增 scanWidth 与 --full

0.10.2 · 2026-10-26 · 修复：会话工作目录改走 workingDirectory.ensure / session.header.cwd，取不到就报错；报错不再暗示“把项目搬到某处”

0.10.1 · 2026-10-26 · 修复：项目集按 exec.agent.session.cwd 定位，不再误用插件进程 cwd（~/.dsh/profiles/<p>）；metrics 也走同一坐标系

0.10.0 · 2026-10-26 · 需求卡点固定七题（含时长/帧率/受众/风格/旁白）；项目集收敛到会话工作区的 dsh-motion-projects/，解析不越界/不嵌套/无 legacy；账本通过后渲染不再逐次弹窗

0.9.1 · 2026-10-26 · 文档：README 增加版本摘要与 Releases 链接（docs-only）

0.9.0 · 2026-10-26 · 项目根 manifest、审批门与审计、时间轴自检、TTS 缓存、VFR/CFR、运行账本、showcase 标准化

0.6.0 · 2026-10-26 · 免费 edge-tts 旁白、词级 timing、SRT、混音

0.5.0 · 2026-10-25 · requirements brief 硬门；无锁定时 motion_frames 拒绝出帧

0.4.3 · 2026-10-25 · 预检合并为一次 motion_doctor，指纹缓存；TTL 边界修复

0.4.2 · 2026-10-25 · render 规格生效；按帧数强制 CFR

0.4.1 · 2026-10-25 · 未 approved checkpoint 拒绝 render

0.4.0 · 2026-10-25 · 分档确认门、APPROVALS.json、pre-flight、CFR

0.3.0 · 2026-10-25 · 风格路由 registry/CLI；3b1b + whiteboard

0.2.0 · 2026-10-25 · Lemo 风格库、frames-first、showcase、probe/doctor 改进

0.1.1 · 2026-10-25 · OIDC Trusted Publishing、npm badge、unofficial 标记

0.1.0 · 2026-10-25 · 首个公开版本：4 个工具、3 个 skill

0.7.0 / 0.8.0 未单独发布，改动已并入 0.9.0。

两种模式

· 极简模式（默认） · 交付模式

画面来源 · motion_frames：按时间点直接出 PNG · motion_render → MP4 → HyperFrames 合成

是否需要 HF · 不需要 · 需要（字幕、编码；旁白/混音也可走本地免费路线）

检查方式 · 看帧（读图），没有"渲染完再抽帧" · motion_probe / hyperframes check

典型耗时 · 2–6 秒/次 · 数秒–数十秒；HF 合成为分钟级

什么时候用 · 写场景、调节奏、改版式 · 定稿后出片

先出帧、改到满意，再决定要不要渲染成片。motion_probe 是给已经存在的视频做体检的，不是默认步骤。

项目骨架、时间轴与账本

新项目用脚手架起，不要从空白开始：

node scripts/scaffold.mjs my-film --title "欧拉公式" --duration 30
node scripts/timeline-check.mjs dsh-motion-projects/my-film --strict
node scripts/run-report.mjs dsh-motion-projects/my-film --wall 752

• 模板生成 motion.project.json / scene.py / timeline.json / timeline.py / narration.json / assemble.py / DESIGN.md；
• 一个项目 = 一部片子，放在会话工作目录下的 dsh-motion-projects/<目录名>（可用 MOTION_PROJECTS_HOME 改）；

工具路径用 ctx.workingDirectory.ensure() / session.header.cwd 定位（不是插件进程的 cwd，那是 profile 目录；都取不到就直接报错）；

• 项目集只有这一层：dsh-motion-projects/registry.json 是可删可重建的索引，不参与寻址；
• motion.project.json 是唯一项目根，id 在这里，目录改名不影响身份；APPROVALS.json / out/ / audio/ / .dsh-motion/ 都相对它；
• 解析不越界、不向上找：workspace 外的 scene.py 一律 unmanaged；子目录里的项目会被拒绝（不允许嵌套）；
• 正式 motion_render 必须有项目根；临时场景只能出帧，或用 --explore 调试；
• 工具入参可以给项目目录名（{"file": "my-film"}）或场景文件的绝对路径；
• 仓库自带的 showcase/* 不在项目集内，跑它们用 MOTION_PROJECTS_HOME=showcase；
• 管理项目集：node scripts/projects.mjs list|show|repair|rename|registry；
• timeline.py 的 TimedScene.cue() 在运行时对比 self.time，落后超过 0.35s 打印 [late]；
• timeline-check 检查 cue 乱序/越界、旁白晚于画面、旁白压到下一拍；
• 每个项目写 <project>/.dsh-motion/metrics.jsonl，run-report 汇总 active / wall，避免把 compute 百分比当端到端收益；
• motion_probe 报 vfr:true 时，raw 只是中间片，交付前用 assemble.py 或 motion_render 归一成 CFR。

旁白 narrate 默认按文本/音色/语速缓存并并发 3 句；mix --report-gaps 输出每个旁白间隙的 dB。

风格库

默认 瑞士动态排版（swiss-motion）；另外四套按题材选。四套改编自 Lemo-Opuscar，3b1b 来自 Manim 社区，均非自创。

风格 · 适合 · 规范

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/blu

…(truncated)