前言¶
在 Harness 里做公式推导、几何证明或数据结论类内容时，常见做法是描述画面、让模型写 Manim 场景，再手工装 Python、FFmpeg 和渲染器，或在 workspace 里反复试错。文生视频模型能出片，但公式与排版往往不可控，也不方便逐帧核对。
下面介绍社区插件 dsh-motion（维护者 cogito0823）。它把「写场景 → 出帧预览 → 可选渲染成片 → 抽帧体检 → 公式校验」收成一组 Harness 工具；画面由 Manim / manimgx 代码逐帧生成，不经过 text-to-video 模型。插件在 README 中标明为 Unofficial community plugin，与 DeepSeek 无隶属或背书关系；社区目录 SkillHub 也是独立站点，并非官方应用商店。
这是什么¶
dsh-motion 面向 DeepSeek Harness 的「模型推理」类插件：为智能体提供代码驱动的数学 / 科普动画能力。当前 npm 版本为 0.10.2（MIT 许可证，要求 Node.js ≥ 22）。
核心思路是 frames-first：默认用 motion_frames 在数秒内得到 storyboard PNG，改到满意后再决定是否走交付模式的 motion_render。另带三个技能（animation-router、design-spec、qa-rubric），安装后通过 ctx.skills 注册，会出现在会话技能目录，无需再复制到 ~/.dsh/skills。
核心功能¶
六个工具¶
| 工具 | 作用 |
|---|---|
motion_frames |
极简模式（默认）：按时间点直接出帧，不生成视频、不用 HyperFrames；输出在 <project>/out/frames |
motion_doctor |
环境预检（一次调用）：运行时、可用字体、公式转换、API/函数/rate；按指纹缓存 12 小时 |
motion_setup |
环境自愈：建 venv、安装 manimgx/sympy（tts=true 时加 edge-tts）；在宿主进程执行，不受模型 bash 沙箱限制 |
motion_render |
渲染 Manim / manimgx 场景；须有 motion.project.json，APPROVALS.json 为前置账本 |
motion_probe |
对已有成片抽帧拼 contact sheet，报告全黑/过曝，并给出 fps/帧数/VFR/CFR |
formula_check |
用 SymPy 判断两个表达式是否恒等 |
两种模式¶
| 极简模式（默认） | 交付模式 | |
|---|---|---|
| 画面来源 | motion_frames 出 PNG |
motion_render → MP4 → HyperFrames 合成 |
| 是否需要 HyperFrames | 不需要 | 需要（字幕、编码等） |
| 典型耗时 | 约 2–6 秒/次 | 数秒至数十秒；HF 合成可达分钟级 |
| 适用阶段 | 写场景、调节奏、改版式 | 定稿后出片 |
motion_probe 针对已有视频做体检，不是默认流水线的一步。
项目与审批¶
一个项目对应一部片子，放在会话工作目录下的 dsh-motion-projects/<目录名>（可用环境变量 MOTION_PROJECTS_HOME 或插件配置 workspace 修改）。工具通过 ctx.workingDirectory.ensure() / session.header.cwd 定位路径，而不是插件 profile 目录。
正式渲染需要项目根 motion.project.json 与账本 APPROVALS.json。需求、脚本、分镜、设计稿与开工确认有固定顺序；motion_frames 在需求项（时长、画幅、帧率、交付、风格、受众、旁白等）未落全时也会拒绝出帧。账本全部 approved 后，motion_render 不再逐次弹窗，仅在审计中记 ledger-approved；若希望每次渲染都确认，可在配置中设置 confirmEveryRender: true。
风格库¶
默认 swiss-motion；另提供 dataviz、blueprint、whiteboard、3b1b 四套题材向风格（部分改编自 Lemo-Opuscar 与 Manim 社区规范，见仓库 styles/）。可用 node scripts/route-style.mjs "<题材>" 做显式路由。
安装与启用¶
README 给出的安装方式如下。SkillHub 目录页则建议让 Harness 读取安装计划后安装插件 cogito0823/dsh-motion（表述为「请安装 DSH 插件 cogito0823/dsh-motion」）。
# npm
npm install -g dsh-motion
# 或在 DSH 插件管理器里安装 dsh-motion
安装后重启 DeepSeek Harness，先调用一次预检工具 motion_doctor。若 ready.math=false，应使用 motion_setup（或仓库内 npm run setup），不要在 workspace 内手工建 venv——venv 位于 workspace 外，容易被沙箱拒绝。
可选插件配置示例（亦可通过 MOTION_HOME、MOTION_PROJECTS_HOME 等环境变量覆盖）：
- insert:
- id: motion
name: dsh-motion
config:
motionHome: ~/.dsh/data/dsh-motion
workspace: <会话 cwd>/dsh-motion-projects
venv: ~/.dsh/data/dsh-motion/venv
tts: false
confirmEveryRender: true # 可选；恢复每次渲染都审批
依赖概览：Node ≥ 22 必需；数学出帧需 Python venv 与 manimgx/sympy；成片与探针需 FFmpeg；交付模式还需 HyperFrames（npx hyperframes）及使用 HF 时的 Chrome。
典型用法¶
1. 脚手架与预检¶
新项目建议用脚手架，不要从空白目录硬写：
node scripts/scaffold.mjs my-film --title "欧拉公式" --duration 30
node scripts/timeline-check.mjs dsh-motion-projects/my-film --strict
开工前可跑需求推断（会结合 ask_user_question）：
npm run plan -- "竖屏抖音，讲导数，要旁白"
2. 先出帧¶
在会话中调用 motion_frames，例如对项目目录名出指定时间点的帧：
{ "file": "demo", "times": ["1.2", "4.5", "end"] }
帧落在 <project>/out/frames，适合读图改 layout，无需 HyperFrames。
3. 环境准备¶
npm run setup
npm run setup -- --tts # 旁白需要 edge-tts / numpy
或在 Harness 里调用 motion_setup。
4. 定稿后渲染与质检¶
账本通过后调用 motion_render，输出在 <project>/out/render。对已有 MP4 可用 motion_probe 检查黑场、过曝与帧率；若报告 vfr:true，交付前应通过 assemble.py 或正式渲染归一为 CFR。
公式步骤可用 formula_check 在渲染前核对两个 SymPy 表达式是否恒等。
仓库 showcase/ 下按五类题材各有一支 10 秒内演示（如 showcase/swiss-euler），运行时可设 MOTION_PROJECTS_HOME=showcase。
适用场景与注意¶
适合：需要在 Harness 对话里迭代 Manim 场景、先帧后片、带审批与时间轴自检的数学 / 科普短视频；需要 SymPy 恒等校验的推导类脚本。
注意：
- 插件以当前 DSH 进程权限运行，安装前请阅读 GitHub 源码 与 MIT 许可证，确认 venv、FFmpeg、HyperFrames 等外部依赖符合你的环境策略。
- 极简模式与交付模式依赖不同；未装 HF 时不应假设能直接出最终 MP4。
- 桌面 App 独占
desktopprofile，CLI 不能用dsh plugin --profile desktop管理该 profile 的插件（README 说明会直接报错）。
结尾¶
dsh-motion 把代码动画的预检、出帧、渲染、探针和公式校验接到 Harness 工具层，并配合账本与风格库约束交付流程。若要安装或查版本，可看社区目录 cogito0823/dsh-motion 与仓库 github.com/cogito0823/dsh-motion；版本细节以 GitHub Releases 为准。
