YJLTF/dsh-animation-studio

dsh Animation Studio

为 DeepSeek Harness（DSH） 打造的教学动画制作工作台插件：一套内置在教学会话里的“教学视频 agent”。

你用自然语言说“做一支讲梯度下降的 30 秒短片”，AI 就通过 10 个 anim_ 工具完成 分镜 → 时间线 → 动画 → 预览 → 微调 → 渲染出 MP4 的完整流程——中途可以随时抽查画面、把某个关键帧挪几百毫秒、或者撤销上一步。模型全程不写动画代码，只读写一份数据文档。

基于 dsh 0.1.6-alpha.1 真机实证开发（类型开发基线 0.1.5-rc.2，peer 依赖声明为 >=0.1.5-rc.2），0.1.6-alpha.2 兼容性已验证——宿主挂载冒烟（工具注册、执行链路、sidecar 落盘、会话恢复、web 路由、client 卡片）在其内置生态（cordis 4.0.2 / dsh-tools 0.1.6-alpha.2 / schemastery 3.18.2）下全绿。可无缝配合 dsh-plugin-offline-packager 打成自包含离线安装包。

模型 ──anim_工具──▶ AnimationSpec (JSON IR) ──▶ 渲染适配器 ──▶ MP4
│                   │                           │
│ 每步变更落 anim/* 事件                           └── Motion Canvas（首发）
│ （插件自有 sidecar，不碰宿主日志）                    后续可换 Remotion / Manim
└── 会话卡片读回执/presentationMeta 即得状态，
视频预览走插件自有的 /dsh-anim 同源路由

设计选型、平台事实与各版本迭代过程的完整记录在 docs/（设计草案 + 各版本规划文档），本 README 只讲“是什么、有什么、怎么用”。

核心特性

- 模型只读写 JSON，不写动画代码：时间线是一份 AnimationSpec IR——所有时间都是场景内绝对毫秒，可动画属性统一收进轨道关键帧，内置 linear / easeIn/Out/InOut / cubicBezier / spring / bounce / elastic / back 缓动。于是“微调 = 改一个数字”（一条 JSON Patch，而不是重写 800 行代码），换渲染后端不动工具，每一步天然可回放、可撤销、可分叉。
- 10 个面向模型的工具：anim_diagnose（环境自检）、anim_create_spec、anim_plan（分镜大纲 + 节奏体检）、anim_draft_scene（逐幕写入）、anim_get（按 JSON Pointer 精确读取）、anim_patch（结构化补丁，返回 inverse）、anim_undo、anim_asset_import（图片/svg/音频/字体素材登记）、anim_preview（降分辨率抽帧）、anim_render（整片 MP4）。详见工具一览。
- 写入走 JSON Patch，撤销不用重新推理：改完整份校验，不通过整批回滚；每次修改同时记录正向 ops 与反向 inverse，anim_undo 直接回放 inverse。坏 op 在边界上以可读的报错返回。
- 事件溯源 + 会话恢复：spec 的每次变更都是一条自包含事件，foldEvents 从事件流还原状态（含撤销历史）。事件按会话写进插件自有 sidecar（/sessions/.jsonl），不写宿主会话日志——宿主读回对未知事件类型 fail-closed，写进去会毒化整个会话。宿主重启、会话重开后，旧 spec 照常修改与撤销。
- 开箱即用的 Motion Canvas 渲染：自动处理 Motion Canvas 3.17 无官方 CLI、WebGL 上下文、headless 出帧、尾部静止提前停帧等一整串坑；渲染默认 headless 无窗口，超时或中断显式报错，绝不静默产出残片。段缓存默认开启（未变的幕直接复用），长片渲染耗时以分钟计。
- 渲染与预览自动后台化：宿主提供 ctx.jobs 时立即返回 jobId，进度以事件可见，模型用 job_output / job_kill（dsh-tool-jobs）收集与终止；宿主没有 jobs 服务时自动退回同步执行（可用 anim_diagnose 的 host 报告确认）。渲染过程落 anim/render-start / anim/render-progress / anim/render-finished 事件，面板与回放都能重建进度。
- 会话内工作台卡片 + 视频预览（dsh Web）：每个 anim_ 工具调用渲染成富卡片；anim_render 的成片直接内嵌  播放（Range 拖动、下载、定位文件），anim_preview 的抽帧渲染成缩略图墙；转后台的任务卡片自动轮询进度条，出片后原地变成播放器。headless（无 webServer）形态下整条路由不存在，零副作用。
- 卡片带最简交互按钮：anim_plan 卡「渲染成片」、anim_draft_scene 卡「预览这一幕」、anim_patch 卡「撤销这步」。点击即把一条结构化指令（稳定前缀 [anim-studio 面板指令] + JSON）经宿主 session/prompt API 发回会话，agent 空闲则立即执行、运行中则排队；处理契约声明在 anim-studio 预设。详见工作台面板。
- 旁白字幕：/narration/cues 写[{ atMs, text }]（全片绝对毫秒），渲染自动出底部字幕条——字号按画布高度自适应，超宽自动折行、底条随行数增高；底部字幕带是保留区，正文图层压进来时渲染会给软警告。TTS 语音合成规划在 0.5。
- 渲染器可替换：渲染能力是一个标准 seam（注册表 + provideRenderer），想接 Remotion/Manim 就写一个 Provider 顶掉默认项，工具与事件零改动。
- 离线分发友好：dsh.bundle 声明 + esbuild 单文件构建，工作区内部包用 alias 内联、与包管理器无关，配合 offline-packager 一条命令打成自包含 tgz。

包结构

| 目录 | 职责 |
| --- | --- |
| packages/spec | AnimationSpec IR：类型、零依赖校验、时间线求值、patch 引擎。纯数据层，host / client 共享 |
| packages/store | spec 状态容器：内存 store + 事件流 fold（含撤销历史）。纯逻辑，host / client 共享同一份状态还原 |
| packages/render-mc | Motion Canvas 渲染适配器：codegen.ts（IR→源码，零渲染依赖）+ adapter.ts/runtime.ts（vite + 浏览器 + ffmpeg） |
| packages/tools | dsh 宿主插件：anim_ 工具、spec store、会话事件、渲染 seam、/dsh-anim 媒体与状态路由 |
| packages/client | 浏览器面（lib/client.js）：anim_* 工具的会话卡片（React），经 keyed tool.call.toolview 插槽认领渲染权 |
| examples/hello-gradient | 端到端样例：一份中文教学动画 spec → MP4 |
| config/agent-presets/anim-studio | 会话级 agent preset：导演 persona + 分镜方法论提示词（拷到 ~/.dsh/.agent-presets/ 启用） |
| scripts/ | 冒烟测试（smoke.ts 纯逻辑 + smoke-host.mjs 真实 cordis 挂载）与旧会话日志修复脚本 |
| docs/ | 设计草案（平台事实、IR 设计、事件模型、踩坑）与各版本规划/迭代记录 |

环境要求

- Node.js ≥ 22，已安装 DSH ≥ 0.1.5-rc.2（dsh CLI 可用）
- 包管理器必须用 pnpm（在 pnpm 12 上验证）：工作区包互相依赖用的是 workspace: 协议，npm 不支持该协议（装不上），且根脚本直接调用 pnpm -r / pnpm --filter
- 渲染需要（不渲染只做脚本可以不装）：
- ffmpeg（帧合成 MP4）
- Chrome / Edge / Chromium 任一；非常见安装位置时用 CHROME_PATH 指定
- Linux 服务器还需要 Xvfb（apt install xvfb）与中文字体（apt install fonts-noto-cjk）；Windows/macOS 有系统显示即可，中文字体一般已具备

安装

方式一：从源码安装

git clone  dsh-animation-studio
cd dsh-animation-studio
pnpm install
pnpm build            # esbuild 打包出 lib/index.js（宿主面）+ lib/client.js（浏览器面）

挂进你的 dsh profile（web 为例；注意路径用绝对路径）
dsh plugin --profile web add F:\path\to\dsh-animation-studio

重启 DSH 后，会话里就会出现 10 个 anim_ 工具；dsh web 下每次工具调用还会渲染成会话卡片（含视频预览）。

方式二：打包成离线安装包（无网络环境）

在联网机器上用 dsh-plugin-offline-packager 打包，推荐直接在 DSH Web UI 里说：

请将 F:/path/to/dsh-animation-studio 打包为离线安装包

打包器会：复制源码到暂存目录（跳过 node_modules / .git）→ npm install 生产依赖（@deepseek-ai/ 是 peer，由 dsh 宿主提供，不打入）→ 通过 bundleDependencies 把 vite、puppeteer-core、Motion Canvas、@lezer/ 语言包等全部运行时依赖闭包塞进 tarball → 出自包含的 dsh-animation-studio-.tgz。package.json 的 files 白名单保证包内只有 lib/ 与 cordis.patch.yml，干净且小。构建环节免维护：源码目录里已跑过 pnpm build 就直接用现成的 lib/，没跑过打包器也会自动构建。

拷到离线机器后：

dsh plugin --profile web add ./dsh-animation-studio-.tgz

两个已知的坑（都来自 offline-packager 的 README，装不上时先查这里）：
- pnpm ≥ 11 的离线环境需要先在 profile 的 pnpm-workspace.yaml 里设置 minimumReleaseAge: 0，否则 pnpm add 会联网校验发布时间元数据而失败；
- Windows 下离线 tgz 的存放路径不能包含空格（dsh plugin add 的转发限制）。

配置

cordis.yml 或 profile patch
- id: dsh-anim-studio
name: dsh-animation-studio
config:
outputDir: ./.dsh/anim   # 渲染产物与中间工作目录的根，默认 ./.dsh/anim

验证安装

装好后先让 AI 调一次 anim_diagnose，它会逐项报告浏览器、ffmpeg、中文字体的就绪状态，并给出缺什么装什么的建议。

使用

让 AI 做一支片子

在 DSH 会话里直接说需求即可，典型流程是：

你：用动画讲一下"梯度下降"的直觉，30 秒以内，中文。
AI：anim_diagnose   → 环境自检
anim_create_spec → 建立时间线文档（30fps，1280x720）
anim_plan        → 写分镜大纲，工具做节奏体检（太短/太长/缺意图会提示）
anim_draft_scene → 逐幕写入图层与关键帧（可反复调用）
anim_preview     → 低分辨率抽几帧自查
anim_patch       → "第二个关键帧挪到 1.8s""小球改橙色"
anim_render      → 渲染成 MP4，报告输出路径

每个工具回执都带"下一步该做什么"的引导；anim_patch 返回的 inverse 可以直接喂回给 anim_patch 撤销，anim_undo 则是它的快捷方式。

用 anim-studio 预设（推荐）

仓库自带一个会话级 agent preset：config/agent-presets/anim-studio/，给会话配上「教学动画导演」身份 + 分镜方法论系统提示词（自检 → 分镜 → 逐幕细化 → 预览 → 微调 → 出片，含面板指令处理契约与字幕安全区等排版守则），让模型一句话主题就能按正确姿势出片。安装：

把预设目录拷到你的 DSH_HOME（默认 ~/.dsh）下的 .agent-presets/
cp -r config/agent-presets/anim-studio ~/.dsh/.agent-presets/anim-studio

然后在 dsh web 新开一个会话，预设选择器里选「动画制作工作台」（preset 是会话级快照，已开的会话不生效）。说明：

- anim_ 工具由插件在宿主层注册、对所有会话可见，preset 不再重复挂载插件（重复挂载会再起一份 store / 路由）；
- preset 的增量是 persona 方法论提示词；不选它、直接在普通会话里说需求也能出片，只是没有这套导演式引导。

工作台面板（dsh Web）

在 dsh web 里，每次 anim_ 工具调用不再是原始 JSON，而是一张会话卡片：anim_create_spec → 片子名片；anim_plan → 分镜大纲 + 节奏体检；anim_patch / anim_undo → 修改历史；anim_preview → 抽帧缩略图墙；anim_render → 成片内嵌播放（Range 拖动、"在新标签打开 / 下载 / 定位文件"）；转后台的任务卡先显示进度条，出片后原地变成播放器 / 缩略图墙，失败/终止显示原因。卡片带三个交互按钮：「渲染成片」「预览这一幕」「撤销这步」。

实现上有两条数据通道 + 一条指令通道，都不经过模型：

1. 卡片数据：host 工具用 output.presentationMeta 把结构化回执投影到 tool/result.meta（随会话日志持久化），浏览器卡片优先读 meta、回退解析回执文本——刷新、回放旧会话，卡片照常重建；
2. 媒体与状态：插件向宿主 webServer 注册 /dsh-anim 前缀路由：GET /dsh-anim/media?p= 把渲染产物送进浏览器（Range / ETag / 304 齐全），放行规则是「outputDir 内」或「工具回执里出现过的路径」，扩展名白名单，其余一律 404；GET /dsh-anim/api/state 输出工作台状态（specs + 渲染/预览任务簿），后台卡片的进度条与缩略图重建靠它；
3. 面板指令：卡片按钮 → 同源 POST /api/session/prompt（与官方 client 同款信封，cookie 自动携带）→ 宿主 agent 收件箱 → 下一回合执行 anim_* 工具 → 事件流与卡片呈现结果。指令带会话章（sessionId），没有该章的旧卡片（分叉/回放产生）按钮整行隐藏。

面板功能依赖 dsh web（webServer 路由 + 浏览器插槽），headless CLI 会话只有工具回执、没有卡片。

工具一览

| 工具 | 作用 |
| --- | --- |
| anim_diagnose | 环境自检：后端、ffmpeg、浏览器、中文字体、宿主 jobs 服务 |
| anim_create_spec | 新建一份时间线文档，返回 specId |
| anim_plan | 记录分镜大纲 + 节奏体检 |
| anim_draft_scene | 逐幕写入图层与关键帧 |
| anim_get | 按 JSON Pointer 精确读取 spec 片段 |
| anim_patch | 结构化补丁修改（唯一写途径），返回 inverse |
| anim_undo | 撤销上一次修改 |
| anim_asset_import | 素材登记（image/svg/audio/font 四类均接通渲染）：image/svg 用 src="asset:" 引用；font 导入后 text/code 的 fontFamily 填 assetId；audio 用 audio 图层引用 |
| anim_preview | 低分辨率抽帧检查效果（只渲染到最晚抽帧点，不渲整片；抽帧无音频） |
| anim_render | 渲染成 MP4（段缓存默认开启，回执 incremental 报告命中；spec 带 audio 图层时自动混音；宿主支持时转后台任务） |

不装 DSH 也能跑：样例工程

examples/hello-gradient 是一条约 14 秒的中文教学片《梯度下降：直觉理解》（5 幕，含代码演化 / zoomIn / fade 退场 / 旁白字幕演示幕），走通"IR → Motion Canvas 源码 → MP4"全链路：

pnpm install
cd examples/hello-gradient
node --import tsx scripts/generate.ts   # spec → Motion Canvas 源码（src/ 下）
node --import tsx scripts/render.ts     # 源码 → output/output.mp4（需要渲染环境）

开发

pnpm install
pnpm typecheck   # 全工作区类型检查（对真实 @deepseek-ai/dsh-tools 类型）
pnpm build       # esbuild 打包插件 → lib/index.js（宿主面）+ lib/client.js（浏览器面）
pnpm smoke       # 纯逻辑冒烟 + 构建 + 真实 cordis 宿主挂载冒烟（含无损 JSON 事件校验，无需浏览器）
冒烟覆盖 spec 校验 / patch 可逆 / 时间线展开与截短 / codegen 结构（含字幕折行与字幕安全区）/ store 回滚撤销 / 事件流 fold / 渲染注册表 / 渲染与预览后台化 / 面板指令信封 / /dsh-anim 请求内核，以及构建产物在真实 cordis 环境里的挂载、执行、会话恢复与卡片注册契约。浏览器渲染链路不在冒烟范围内，由 examples/hello-gradient 的 scripts/render.ts 走与 anim_render 完全相同的运行时路径，可当渲染链路的手动诊断入口用。

已知限制与说明

- 图层类型：text / rect / circle / ellipse / image / line / arrow / polygon / star / svg / code / math / group / audio。要点：circle/ellipse 用 size（radius 自动换算）；line/arrow 用 points 定折线、endArrow 内建箭头；polygon/star 由 sides+size 生成；svg 内嵌字符串；image src 写 asset:；code 用 code+language（自动高亮，{{片段}} 着色，props.code 多关键帧即代码演化 morph）；math 用 tex 写 LaTeX；group 用 children 引用成员；audio 引用音频资产（渲染尾步 ffmpeg 混入成片，不进画面）。不支持的属性以警告降级，不失败。
- 转场与缓动：transition.kind 支持 none/fade/slideLeft/slideUp/slideRight/slideDown/zoomIn；scene.exit（fade/slide 系列）在幕尾整体退场；缓动另有 bounce/elastic/back（强调类入场）。
- 旁白字幕：无 TTS（规划在 0.5）。字幕字号按画布高度约 4% 自适应（与正文字号解耦），超宽自动折行；底部字幕带是保留区，建议一条 cue ≤40 字、正文图层的 y 避开字幕带（重叠时渲染给软警告）。
- 字体：font 资产导入后 text/code 图层 fontFamily 填 assetId 即生效；远端 http(s) 字体 URL 需要目标服务器允许跨源（CORS）。
- 后台任务依赖宿主把 jobs 服务暴露给插件上下文；未暴露时 anim_render / anim_preview 自动走同步路径（设计内行为），anim_diagnose 的 host 报告（jobsOnCtx）可确认当前部署的形态。
- 媒体放行：/dsh-anim/media 只放行「outputDir 内」或「工具回执里出现过的精确路径」+ 扩展名白名单（mp4/webm/mov/png/jpg/jpeg/gif/webp/svg）。
- 插件事件不进宿主会话日志：宿主读回对未知事件类型 fail-closed，而宿主 session.append 不提供 ignorable 入口，写 anim/* 事件会毒化整个会话；事件因此只写插件 sidecar。极旧版本写入过 anim/* 事件的宿主日志，用 python scripts/repair-session-log.py  补 ignorable 标记后仍可作恢复回退源（自动备份）。完整事故记录见 docs/。
- 渲染环境：渲染依赖 Motion Canvas 3.17 的编辑器 UI 自动化（官方无 CLI）；Edge 152+ 的新 headless 配合 SwiftShader 可完整出帧；headless: false 仅作调试后门（Linux 无显示时需要 Xvfb）。浏览器与 vite dev server 常驻复用（空闲 10 分钟回收）。
- Windows 安装：dsh plugin add 在部分 Windows 环境会把 pnpm 转发给 cmd 执行；若 cmd 按 PATH 找不到 pnpm，直接在 profile 目录里 pnpm add  并把插件名写进 profile package.json 的 dsh.profile.bundles 即可。

文档

- docs/设计草案.md：dsh 平台事实、AnimationSpec IR 设计、事件模型、选型与踩坑
- docs/0.2.0-规划.md / docs/0.3.0-规划.md / docs/0.3.x-优化清单.md / docs/0.4.0-规划.md：各版本的范围、验收与迭代记录