dsh-manim · 动画工作室

把论文、方法或任何流程说明渲染成带旁白的讲解视频，全程在编辑器里完成。

一个 DSH 插件，提供：

• 左侧栏「动画」入口 + 右侧栏「动画工作室」面板（场景列表 / 画质 / 渲染 / 播放 / 分镜 / 实时日志）
• 四个 agent 工具：manim_scene · manim_render · manim_frames · manim_voice
• 一份随包 skill manim-explainer：怎么把一篇论文拆成 4–8 拍、版式与节奏纪律、常见坑
• 成片 .mp4 在右侧栏文件树里点开就能播（本插件注册了视频预览渲染器；官方自带的预览集不含视频）

渲染器是 Manim 0.22，装在插件自己的虚拟环境里，不碰系统 Python。 旁白用系统/在线 TTS，不需要下载任何语音模型。

---

预览

左侧对话里说一句「把这个做成动画视频」，右侧「动画工作室」自己出现在工作区里：场景列表、画质、 渲染与取消、成片播放器、分镜条、实时日志都在一个面板里。

示例成片

下面这条 78 秒讲解片（1920×1080 @ 60fps，含中文旁白）就是用它做的 —— 把一个方法拆成 8 拍：问题 → 为什么难 → 核心想法 → 两条支路 → 结果， 公式用 mathtex() 排版（不需要 LaTeX），旁白先出、画面按每句时长对拍。

点封面播放（docs/demo-sample.mp4）。示例内容基于已发表论文 UNETR++（IEEE TMI 2024）的公开方法。

---

环境要求

需要	版本 / 说明
Node.js	^22.19.0 || >=24
Python	≥ 3.10，只用来创建插件自己的 venv（不会往你的解释器里装东西）
DSH 宿主	本插件是 DSH 插件（注册侧边栏槽位 + agent 工具），需要宿主才能运行

不需要装的东西（这是本插件刻意设计的）：

不需要	为什么
LaTeX / TeX 发行版	公式走 manimkit.mathtex()（matplotlib 的 mathtext 引擎），不需要 latex、不需要 dvisvgm。检测到可用 LaTeX 时会自动升级成真正的 MathTex，但没有也完全能用
ffmpeg	manim 0.22 用 PyAV 在进程内编码；旁白的 mp3 也由 PyAV 转成 WAV
任何语音模型	旁白走 Edge 朗读（联网、免费、免 key）或 Windows SAPI（离线）
额外的 npm 运行时依赖	两侧只用宿主已提供的包（react、@deepseek-ai/dsh-client-* 由 DSH 宿主注入）；npm install 装的只是构建与测试用的 devDependencies

---

安装

git clone https://github.com/Strivy-ZSY/dsh-manim.git
cd dsh-manim

npm install            # 只为构建与测试装 esbuild / react（运行时不需要）
npm run setup:runtime  # 建 runtime/venv，装 manim 0.22 + matplotlib 与 manimkit 的路径
npm run build          # src/ → lib/（面板 bundle + 宿主半边）

npm run setup:runtime 可用参数：

node runtime/setup-runtime.mjs --check          # 只检查，不安装
node runtime/setup-runtime.mjs --python <exe>   # 指定基础解释器

网络不稳时怎么装（ERR_PNPM_GIT_FETCH_FAILED / SSL_ERROR_SYSCALL / early EOF）

这些是 GitHub 传输链路的报错，不是仓库坏了。按顺序试，通常第 1 条就够：

1. 让 git 容忍慢链路

git config --global http.version HTTP/1.1
git config --global http.postBuffer 524288000
git config --global http.lowSpeedLimit 0
git config --global http.lowSpeedTime 999999
# 再重跑 pnpm add

后两条是关键：early EOF / SSL_ERROR_SYSCALL 多半是链路被限速后 git 自己判超时。

2. 给 pnpm 更多耐心

pnpm add https://github.com/Strivy-ZSY/dsh-manim --fetch-retries=5 --fetch-timeout=600000

3. 走镜像（把 github.com 换成镜像主机，任选其一）

pnpm add https://ghfast.top/https://github.com/Strivy-ZSY/dsh-manim.git
pnpm add https://gitclone.com/github.com/Strivy-ZSY/dsh-manim.git

4. 用压缩包代替 git 协议（少一次协议握手，通常最稳）

pnpm add https://ghfast.top/https://github.com/Strivy-ZSY/dsh-manim/archive/refs/heads/main.tar.gz

仓库里带了一段 7.6 MB 的演示视频（docs/demo-sample.mp4，只用于 README 展示，安装不需要它）， 所以 clone 的体积比代码本身大。链路很窄时，第 4 条最省事。

面板从哪里打开

插件不在左侧栏加自己的一行：官方客户端的左栏是它自己的（插件 / 自动化任务 / …）， 第三方插件塞一行进去显得突兀。面板作为右侧栏的一个 tab 注册，通过右侧栏的标签页 控件或「开始」页里的入口打开。

如果你的宿主只能在左栏列出插件，可以在 profile patch 里显式要求那一行：

- id: dsh-manim
  name: 'dsh-manim'
  config:
    sidebarEntry: true    # 默认 false；宿主把插件配置传给浏览器半边时生效

装进 DSH

官方客户端（推荐） —— 侧栏「插件」→「添加插件」，把仓库地址贴进「包名或地址」→ 安装 → 启用：

https://github.com/Strivy-ZSY/dsh-manim

本仓库是一个组合包（bundle）：package.json 里声明 dsh.bundle.patch，随包带一份 cordis.patch.yml。DSH 安装后按包名插入一行并挂载浏览器半边，不需要手改任何 profile 文件。

本地开发（pnpm add <本地目录>，或手工在 profile patch 里加一行）：

- insert:
    - id: dsh-manim
      name: 'dsh-manim'      # 必须是包名：浏览器半边只认「行说明符 === 包名」

首次使用还要建渲染运行时（一次性，约 500 MB 的 Python 依赖，装进插件自己的 runtime/venv）：

cd <安装目录>/node_modules/dsh-manim
node runtime/setup-runtime.mjs

装好后：左侧栏出现「动画」行，右侧栏出现「动画工作室」tab，四个 manim_* 工具进入会话工具表。 运行时没建时面板会报「运行时未就绪」并给出解释器路径 —— 跑上面那条命令即可，不需要重装插件。

---

用法

面板：点「动画」→ 选一个场景文件（扫整个工作区的 .py）→ 选画质 → 渲染。 渲染完可拖动播放、点分镜条跳到某一刻；日志实时滚动，可随时取消。

会话里：

manim_scene(action='template', name='MyExplainer')   # 从模板起一个场景
manim_render(path='animations/MyExplainer.py', quality='draft')
manim_frames(path='animations/MyExplainer.py', count=6)
manim_voice(action='list')                            # 看可用音色

工作顺序建议 audio-first：先出旁白拿到每句时长，再写画面。

配音

manim_voice 提供两条路，engine='auto' 优先第一条：

引擎	音质	需要什么	音色
edge	接近真人	联网，免费、免 key	14 个中文，含 zh-CN-XiaoxiaoNeural
sapi	机械	完全离线（Windows）	Microsoft Huihui Desktop 等

生成 animations/voice/*.wav + cues.json（每句的 at 与 duration），场景里两行挂上：

from manimkit import find_cue_sheet, hold, narration

def construct(self):
    sheet = find_cue_sheet("voice/cues.json")
    cues = narration(self, sheet) if sheet is not None else None
    self.play(Write(title), run_time=1.0)
    if cues is not None:
        hold(self, cues, "b1")     # 画面撑到第 1 句说完

narration() 按 cue sheet 自己的位置解析路径，从哪渲染都不会失联。

不想用 TTS 就直接替换 cues.json 与音频文件（结构 {"cues":[{"id","text","file","duration","at"}]}），场景代码一个字都不用改。

---

公式：为什么不需要 LaTeX

manim 自带的 Tex / MathTex 会 shell out 到 latex 再 dvisvgm——这个组合要求一整套 TeX 发行版，在很多机器上缺失或损坏（Windows 尤其常见），一旦缺了就在第一个公式处抛 ValueError: latex error converting to dvi。

所以本插件默认用 manimkit.mathtex()：走 matplotlib 的 mathtext（就是画 $…$ 轴标签那个引擎）， 支持 \frac \sqrt \sum \int \mathbb \mathcal \hat、上下标、\left(/\right)， 不需要任何外部程序。它渲染成透明底 PNG 再包成 ImageMobject。

• 若机器上确实有可用的 LaTeX，has_latex() 会自动改走真正的 MathTex，场景文件不用改
• 可用 DSH_MANIM_TEX=1 / =0 强制开关
• mathtex() 里不要写中文（matplotlib 数学字体没有 CJK，会画成空框）——中文用 text() 单独放

---

目录

src/
  config.ts            配置 + 画质预设 + 默认解释器路径
  engine.ts            渲染引擎：spawn 驱动、读 NDJSON 事件、任务表
  service.ts           工作区门控、场景扫描、渲染编排、抽帧、模板
  routes.ts            /dsh-manim 路由（POST JSON + GET Range 流）
  tools.ts             manim_scene / manim_render / manim_frames / manim_voice
  skills.ts            把 skills/**/SKILL.md 交给 skill 注册表
  index.ts             apply()：路由 + 工具 + skill + 正向 attach 标记
  client/              面板：studio.tsx / panel-row.tsx / 图标 / i18n
runtime/
  setup-runtime.mjs    建 venv、装 manim + matplotlib、写 manimkit 的 .pth
  engine/driver.py     渲染驱动：plan / render / list / frames / probe，stdout 为 NDJSON
  manimkit/            主题与版式：theme.py / mathkit.py / layout.py
templates/starter.py   起始场景（面板的「新场景」与 manim_scene(template) 共用）
skills/manim-explainer/ 方法：怎么拆拍、版式与节奏纪律、常见坑
tools/                 build.mjs / test-offline.mjs / check-panel-markup.mjs

为什么自带虚拟环境

插件不往系统解释器里装东西：runtime/venv 由 setup-runtime.mjs 建一次，之后渲染是确定性的。 manim==0.22.0 钉在 requirements 里，换机器结果一致；你的 numpy / scipy / opencv 不受影响。

为什么驱动单独写

runtime/engine/driver.py 不是 python -m manim render 的包装：

1. 媒体目录归插件管 —— 不会往工作区写 ./media/…，工作区只收到一个 .mp4
2. 进度机器可读 —— 每段动画边界与动画内 ~0.25 秒发一个 NDJSON 事件，面板才有真正的进度条
3. 有 plan 阶段 —— 关绘制 + 1fps 先把 construct() 跑一遍，几秒内量出段数与总时长， 长渲染之前先快速失败
4. 不依赖 PATH 上的 ffmpeg

事件契约写在 driver.py 模块注释里，改任何一边都要同步。

---

配置

patch 里可覆盖的键（全部有默认值，config: {} 也能跑）：

键	默认	说明
agentTools	四个全开	暴露给模型的工具；'*' 或 []
pythonPath	runtime/venv/Scripts/python.exe	换解释器（Linux/macOS 为 runtime/venv/bin/python）
driverPath	runtime/engine/driver.py	换驱动
cacheDir	<插件>/cache	渲染缓存（manim 的 partial_movie 也在里面）
outputDir	animations	成片复制到工作区哪个子目录；'' = 不复制
background	#10141c	场景背景色
defaultQuality	1080p60	默认画质
maxSceneBytes	512 KB	超过此大小的 .py 不扫描
jobTtlSeconds	1800	任务记录保留时长
renderTimeoutSeconds	3600	单次渲染硬上限

---

开发与测试

npm run build                        # 打两个 bundle
node tools/test-offline.mjs --fast   # 纯逻辑（几秒）
node tools/test-offline.mjs          # 含一次真实草稿渲染 + 抽帧 + HTTP 路由（约一分钟）
node tools/check-panel-markup.mjs    # 把面板 view 渲染成 HTML 串断言结构

离线测试跑的是已构建的 lib/index.js（不是源码副本），验证的是真正会加载的那份代码： 静态场景扫描、工作区门控、路由信封与 403/404、Range 请求、真实 mp4 落盘、抽帧、工具主要动作。

esbuild / react / react-dom / @deepseek-ai/dsh-tools（宿主包，npm 上公开）都是 devDependencies，只在构建与测试时需要。两条检查都会优雅降级而不是假装通过： check-panel-markup 没装 react 时打印 SKIP 并以 0 退出；test-offline 在没有 runtime/venv 时跳过 probe 相关断言并提示去跑 npm run setup:runtime。

---

故障排查

现象	原因与处理
no python interpreter found	装 Python ≥3.10，或用 --python <路径> 指定
esbuild not found	没跑 npm install；或用 DSH_ESBUILD_ROOT=<node_modules 路径> 指一份现成的
SKIP: react / react-dom not installed	同上，npm install 后该检查会真正执行
npm install 之后 node_modules 几乎是空的	你的 npm 配置了 omit=dev，改用 npm install --include=dev
渲染报 latex error converting to dvi	场景里用了 MathTex/Tex 而机器没有可用 LaTeX ⇒ 改用 manimkit.mathtex()
加旁白报 pydub/ffmpeg 相关错误	add_sound 只吃 WAV；manim_voice 产出的就是 WAV，自己塞 mp3 需先转
公式渲染报 PIL / Pillow 相关错	Pillow 13 会破坏 manim 0.22 的 ImageMobject 路径。跑 node runtime/setup-runtime.mjs --repair 把依赖拉回钉住的版本（pillow>=11,<13），不要手工 pip install
成片结尾旁白被切掉	manim 混流用 shortest=1；驱动会比对音视频时长并告警，把画面加长或旁白缩短
面板一片空白	先 npm run build（lib/ 是构建产物），再确认宿主加载的是 lib/index.js

---

卸载与清理

渲染器（runtime/venv，约 500 MB）与渲染缓存（runtime/../cache）都在插件目录内， 所以卸载插件就把它们一起删掉了，不会留下占地方的残留。

留在外面的只有你自己工作区里的成片（<工作区>/animations/*.mp4 与 voice/）——那是你的成果， 卸载插件不该动它，按需自行删除。

代价要说清楚：因为运行时在包内，升级插件（卸载重装）会连带删掉渲染器，装完需要重新点一次 「安装渲染器」。这是「卸载必须干净」换来的取舍。想避免重复下载，可以用 config.runtimeDir 把运行时指到插件目录之外（此时需自行清理该目录）。

成片列表怎么来的

「文件」菜单列两类东西，合起来才是"这个工作区里能看的片子"：

1. 渲染索引：本插件在这台机器上渲过的任务（记录在插件 cache/index）；
2. 磁盘扫描：<工作区>/animations 下的 mp4/webm/mov/m4v，加上工作区里其它目录（深度 ≤3，跳过 node_modules、虚拟环境、库源码检出等）找到的视频。

第 2 类是为了"从别处拷来的成片"——换机器、换 DSH home、或手动导出的片子，索引里当然没有， 但用户显然期望它出现在菜单里。

已知限制

• 公式走位图（mathtex()），大幅推近会糊；要矢量公式就得装可用的 LaTeX
• plan 阶段会把 construct() 跑两遍（同进程，省掉再 import manim 的 ~8 秒）
• 运行时需手工建一次：插件安装不会自动 pip install（那会在 pnpm install 里触发构建脚本审批， 且 500 MB 下载不该藏在一个静默依赖步骤里）——首次要跑 node runtime/setup-runtime.mjs
• 任务表在内存里：宿主重启丢任务记录，但成片与索引在磁盘上，面板重开还能播
• 没有 GPU 加速（cairo 渲染器），4K60 很慢

---

致谢

本插件的动画能力全部来自 Manim —— 由 The Manim Community Developers 与 Grant "3Blue1Brown" Sanderson（Manim 的创造者） 以 MIT 许可开源（本插件用 manim==0.22.0）。Scene/Mobject/Animation 这套抽象、 以及「用代码控制每一帧」的思路，都是他们的设计。

公式排版用 matplotlib 的 mathtext，文字排版用 ManimPango，视频编码与音频转换用 PyAV（因此不需要 ffmpeg），旁白可选 edge-tts（LGPL-3.0，仅在 engine='edge' 时用到， 不随本仓库分发）。

完整的组件清单、版本与许可见 THIRD-PARTY-NOTICES.md。

License

本仓库自己的代码（src/ lib/ runtime/manimkit/ runtime/engine/ tools/ skills/ templates/）以 MIT 发布 —— 见 LICENSE。

运行时依赖（pip 装进 runtime/venv 的 manim / matplotlib / PyAV 等）各自保留其许可， 本仓库不分发它们；详见 THIRD-PARTY-NOTICES.md。