dshmath-manim

DeepSeek Harness（dsh）数学动画插件 —— 基于 Manim CE 将数学概念渲染为动画视频。

「一切皆插件」：本插件以 Cordis 插件形式提供一组 Tool，模型通过自然语言即可生成数学动画。

架构

┌─────────────────────────────────────────────────────────────┐
│  DeepSeek Harness (dsh)                                     │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ dshmath-manim (TS / Cordis 插件)                     │  │
│  │   tools: list_math_templates / render_math_scene      │  │
│  │          render_math_code / validate_math_code        │  │
│  └──────────────────────┬────────────────────────────────┘  │
│                         │ spawn python3 (沙箱子进程)        │
└─────────────────────────┼───────────────────────────────────┘
                          ▼
          py/manim_runner.py（渲染执行器）
            ├── 模板系统（JSON 声明参数模式 + Python 场景代码）
            ├── AST 静态安全校验（拦截 os/import/eval 等）
            └── manim CLI 渲染（low/medium/high/ultra）

目录结构

dshmath-manim/
├── math-manim.cordis.yml     # 插件加载配置
├── package.json / tsconfig   # TS 插件（tools 注册）
├── src/
│   ├── index.ts              # 插件入口，注册 4 个工具
│   └── runner.ts             # TS ⇄ Python 桥接（子进程 + 超时 + 安全环境）
└── py/
    ├── manim_runner.py       # 渲染执行器（模板/校验/渲染，JSON 输出）
    ├── templates/            # 数学动画模板
    │   ├── function_plot     # 函数绘图（一/二元函数）
    │   ├── derivative_tangent# 导数与切线（数值斜率）
    │   ├── definite_integral # 定积分（曲线下面积）
    │   ├── geometry          # 几何图形（三角形/圆/正多边形）
    │   ├── polar_plot        # 极坐标曲线（心形线等）
    │   └── surface_3d        # 3D 曲面（ThreeDScene）
    └── examples/             # 自定义场景示例（走 render_math_code 自由代码路径）
        ├── spring_mass_oscillator.py  # 弹簧振荡（简谐运动，含 x(t) 轨迹同步）
        ├── spring_oscillator.py       # 弹簧振子（位移-时间）
        └── bouncing_ball.py           # 小球弹跳

数学动画向导（零代码使用）

面向只懂数学、不懂代码的用户。启动后浏览器打开即可使用：

python3 py/wizard_server.py --port 8321
# 打开 http://127.0.0.1:8321

流程：选择场景卡片（函数图像/导数切线/定积分/几何/极坐标/3D 曲面）→ 填写数学参数（全中文表单）→ 点击「生成动画」→ 预览并下载视频。全程无任何代码。

每个模板在 py/templates/*.json 中带有 ui 元数据（中文标签、参数提示、控件类型、下拉选项），向导页面由此自动生成表单。

提供的工具（模型可见）

零代码技能包（Skill，核心推荐）

插件加载时会自动向 ctx.skills 注册两个技能（skills/<name>/SKILL.md，每份都是一份完整提示词）：

双轨自动决策：math-animation 技能内置决策树，模板覆盖得了的需求走模板（安全、成功率高）；覆盖不了或连续失败时，自动加载 manim-codegen 切换自由代码。用户视角始终是零代码。

使用者视角（零代码，完全不用接触代码）

在 dsh 对话中直接说数学/物理语言即可，例如：

• 「画一个正弦函数和余弦函数在同一坐标系里的对比动画」
• 「y=x² 在 x=1 处的切线，标出导数」
• 「画出 sin x 从 0 到 π 的定积分，涂上面积」
• 「画一个蓝色三角形，标 ∠ABC」
• 「画心形线 r=1+cosθ」
• 「画马鞍面 z=x²-y²，能旋转的」
• 「弹簧振子的位移-时间图像」（物理 → 自动翻译为简谐运动曲线）

模型会加载技能 → 翻译成模板参数 → 调用 render_math_scene → 返回视频。超出模板时自动切换 manim-codegen 写代码渲染。技能内置：

• 口语 → 表达式翻译表（"x 的平方"→x**2，极坐标、3D 双变量同样覆盖）
• 模板选择决策树（需求类型 → 模板）
• 精细动画加分项（标题智能渲染：数学公式走 LaTeX、含中文自动走 Pango 文本渲染，中文标题无忧；贴合函数形状的坐标区间、多曲线配色、low 预览→high 出片）
• 自愈循环（参数校验/表达式/LaTeX 报错 → 自动修正重试，连续 2 次失败才询问用户）

技能启用方式（二选一）

# 方式 A：加载本插件，技能随插件自动注册（推荐，零配置）
dsh --patch /path/to/dshmath-manim/math-manim.cordis.yml

# 方式 B：不加载插件，直接把技能文件放入技能根目录
mkdir -p ~/.dsh/skills && cp -r skills/math-animation skills/manim-codegen ~/.dsh/skills/

技能遵循 dsh「渐进披露」：默认只向模型暴露 name + description 摘要（小 token）， 模型判定需要时才通过 skill 工具展开完整 <skill_content>，不占日常对话预算。 用户也可直接输入 /math-animation 显式注入技能全文。

快速开始

1. Python 依赖

pip install manim numpy

2. 独立验证 Python 后端（无需 dsh）

# 列出模板
python3 py/manim_runner.py templates

# 渲染函数绘图（sin + x²）
python3 py/manim_runner.py render \
  --template function_plot \
  --params '{"functions": ["np.sin(x)", "x**2"], "title": "y=\\sin(x),\\ y=x^2"}' \
  --quality low --outdir out

# 校验模型代码（拦截危险调用）
python3 py/manim_runner.py validate --code 'import os; os.system("rm -rf /")'

3. 在 DeepSeek Harness 中加载

# 方式 A：本地 patch（在 dsh 仓库目录）
dsh --patch /path/to/dshmath-manim/math-manim.cordis.yml

# 方式 B：作为 npm 插件发布后按名字加载
# - insert:
#     - id: dshmath-manim
#       name: 'dshmath-manim'

clone 后无需编译，但要装一次依赖：dist/ 已随仓库提供（不再被 .gitignore 忽略）， clone 下来即可加载。插件运行时需要 dsh 的插件 API 包可解析，执行一次完整安装即可：

npm install     # 装上 @deepseek-ai/dsh-tools / @deepseek-ai/schemastery（声明在 devDependencies，同时是 dsh 的 peer 依赖）

• 报 Cannot find package '@deepseek-ai/...' → 漏了这一步。
• 不要用 npm install --omit=dev：那两个包不在 dependencies 里，--omit=dev 会一个都不装， 插件照样起不来（实测）。
• 只有改动 src/ 之后才需要 npm run build，并请把重建后的 dist/ 一起提交。 npm run verify:dist 可以一条命令查出产物是否过期（重建后 dist/ 若发生变化即失败）。
• 走 GitHub 安装（dsh plugin add github:...）见下文「方式三」。

依赖要求：本插件依赖世代对齐 @deepseek-ai/dsh@0.2.0-rc.2 —— @deepseek-ai/cordis@~4.0.4、 @deepseek-ai/dsh-tools@^0.2.0-rc.2、@deepseek-ai/dsh-skill@^0.2.0-rc.2、 @deepseek-ai/schemastery@~3.18.4。package.json 已按此声明 peerDependencies， 并采用同名 Config + Schemastery Schema 配置格式，与较新的 dsh web 兼容。 dsh 自 0.2.0 起会在加载时按 peerDependencies 校验插件兼容性：用 0.1.5 世代的 dsh 加载本版本 会被整包跳过并给出原因。插件用到的 defineTool、ctx.tools.register、ctx.skills.register 在新旧世代并未变化；需要跑在 0.1.5 上时请装本插件的 0.1.5 版本，或把 peer 区间放宽后自行验证。

加载后启动 npx @deepseek-ai/dsh web，在对话中即可使用，例如：

"用曼哈顿比例绘制 y = sin(x) 和 y = x² 的动画，并标注函数名"

模型会调用 list_math_templates → render_math_scene 完成渲染。

打包与发布（让其他使用者安装）

插件是标准的 dsh bundle 包：package.json 声明 dsh.bundle.patch 指向 math-manim.cordis.yml， files 字段保证 dist/（编译产物）、py/（Python 渲染后端与模板）、skills/（技能提示词）全部随包分发。 dist/ 同时入库（便于 clone 即用），npm 侧发布时由 prepack 重新构建，保证发布产物总是最新。

方式一：npm 发布（推荐，使用者一行安装）

cd dshmath-manim
npm run build            # 编译 dist/
npm publish              # 发布到 npm（会先跑 build）
# 使用者侧：
dsh plugin --profile web add dshmath-manim

方式二：tarball 交付（内部/私有分发）

npm pack                 # 生成 dshmath-manim-0.2.0.tgz
# 使用者侧：
dsh plugin add ./dshmath-manim-0.2.0.tgz

方式三：GitHub 安装

给仓库打 dsh-plugin 话题即可进入社区生态；使用者可 dsh plugin add github:you/dshmath-manim。 仓库已直接提供 dist/，且 package.json 不再带 prepare 构建脚本，因此 git 安装不需要在 pnpm-workspace.yaml 的 allowBuilds 中授权构建即可加载（若你自行加回构建脚本，则需授权）。

使用者安装后的效果

安装成功后，使用者只需在 dsh 对话中说数学/物理语言，例如「画一个蓝色三角形标 ∠ABC」或 「弹簧振子的动画」，模型会加载插件注册的两个技能（math-animation 模板路径 / manim-codegen 自由代码路径）自动生成动画。使用者侧无需安装任何 Python 依赖 —— 但渲染需要本机已安装 manim + numpy（见上「Python 依赖」），或后续可内置自动检测提示。

安全模型

• 模板渲染：参数只做 {key} 文本替换 + JSON 字面量序列化，绝不 eval 模型输入
• 模型代码：AST 静态校验，拦截 os/subprocess/eval/open 等危险符号后才渲染
• 进程隔离：渲染始终在 Python 子进程内执行，带超时与取消信号（exec.signal）
• 环境隔离：子进程清除 IDE 注入的钩子（CODEBUDDY_SAFE_DELETE_*），避免 TeX 临时文件清理被拦截

自愈循环（与 dsh agent loop 协同）

模型写出场景 → validate_math_code 检查 → 失败则根据 violations 重写 → render_math_scene/render_math_code 渲染 → 渲染错误（含 LaTeX 报错）作为 tool result 回喂 → 模型修正。错误信息被裁剪到末尾 2000 字符返回，避免上下文爆炸。

路线图

• [x] Python 渲染后端 + 6 个数学模板（本地验证通过）
• [x] TS 插件（4 个工具注册）
• [x] 零代码技能包：math-animation Skill（模板路径：提示词引导参数翻译）
• [x] 进阶技能包：manim-codegen Skill（自由代码路径：模型直接写 Manim 场景代码）
• [ ] dsh 仓库内集成测试（需在 deepseek-harness 仓库中 pnpm 安装验证）
• [ ] UI 卡片（presentResult 内嵌视频预览）
• [ ] 对话式增量修改（改模板参数重渲染）