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、0.1.7-alpha.1 与 0.1.7-rc.2 兼容性已验证——宿主挂载冒烟（工具注册、执行链路、sidecar 落盘、会话恢复、web 路由、client 卡片）在其内置生态（cordis 4.0.2 / dsh-tools 0.1.6-alpha.2 / schemastery 3.18.2）下全绿；0.6.1 针对 0.1.7 手风琴 DOM 的样式变更（mask 裁剪 fixed 定位）把卡片灯箱迁到 <dialog> 顶层渲染，并对宿主 DOM 结构不再做假设（详见 docs/0.6.1-规划.md）；0.6.2 适配 0.1.7-rc.2 对 presentationMeta 的无损 JSON 校验（注册层统一清洗 undefined 字段，详见 docs/0.6.2-规划.md）。可无缝配合 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（<outputDir>/sessions/<sessionId>.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 的成片直接内嵌 <video> 播放（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.0）：逐 cue 合成语音（按内容缓存，重渲零重合成）、在 atMs 处混入成片、字幕时长跟随实测语音；回执 speechNotes 报告每条语音实测时长与溢出，时间线调整由模型用 anim_patch 决策（工具不自动改时间轴）。首发走外部命令通道（edge-tts / piper 配方见配音配置），不内置云 SDK。
• 渲染器可替换：渲染能力是一个标准 seam（注册表 + provideRenderer），想接 Remotion/Manim 就写一个 Provider 顶掉默认项，工具与事件零改动。
• 离线分发友好：dsh.bundle 声明 + esbuild 单文件构建，工作区内部包用 alias 内联、与包管理器无关，配合 offline-packager 一条命令打成自包含 tgz。