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），旁白先出、画面按每句时长对拍。
示例成片：一个方法讲成 8 拍
点封面播放（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 的包装：
- 媒体目录归插件管 —— 不会往工作区写
./media/…，工作区只收到一个 .mp4
- 进度机器可读 —— 每段动画边界与动画内 ~0.25 秒发一个 NDJSON 事件，面板才有真正的进度条
- 有 plan 阶段 —— 关绘制 + 1fps 先把
construct() 跑一遍，几秒内量出段数与总时长，
长渲染之前先快速失败
- 不依赖 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
把运行时指到插件目录之外（此时需自行清理该目录）。
成片列表怎么来的
「文件」菜单列两类东西，合起来才是"这个工作区里能看的片子"：
- 渲染索引：本插件在这台机器上渲过的任务（记录在插件
cache/index）；
- 磁盘扫描：
<工作区>/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。
