动画讲解工作室 Strivy-ZSY/dsh-manim

dsh-manim · 动画工作室（DSH 写的）

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

一个 DSH 插件，提供：

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

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

预览

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

动画工作室面板

示例成片

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

示例成片：一个方法讲成 8 拍

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

环境要求

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

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

| 不需要 | 为什么 |
| 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 524288000bash
git config --global http.lowSpeedLimit 0
git config --global http.lowSpeedTime 999999

再重跑 pnpm add

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

2. 给 pnpm 更多耐心 bash
pnpm add https://github.com/Strivy-ZSY/dsh-manim --fetch-retries=5 --fetch-timeout=600000

3. 走镜像（把 github.com 换成镜像主机，任选其一） bash
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 协议（少一次协议握手，通常最稳） bash
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 里显式要求那一行： yaml
- 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 里加一行）： yaml
- insert:
- id: dsh-manim
name: 'dsh-manim' # 必须是包名：浏览器半边只认「行说明符 === 包名」

首次使用还要建渲染运行时（一次性，约 500 MB 的 Python 依赖，装进插件自己的 runtime/venv）： bash
cd <安装目录>/node_modules/dsh-manim
node runtime/setup-runtime.mjs

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

用法

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

会话里： python
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），场景里两行挂上： python 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 | 单次渲染硬上限 |

开发与测试 bash
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。