--- title: 0.6.0 版本规划：会话收束防护、图表图层与工作台交互升级 --- # 0.6.0 版本规划：会话收束防护、图表图层与工作台交互升级 > 0.1.0 打通「模型 → AnimationSpec IR → MP4」全链路，0.2.0 把工作台「亮出来」，0.3.0 元素扩面与导演 preset，0.4.0 产能做厚（增量渲染、常驻实例、音轨字幕），0.5.0 兑现配音与工具产出打磨。 > 0.6.0 的主题是**收束、再丰、再亮**：0.5 真机抓到的「渲染完成后模型反复抽帧、会话无法收尾」退化循环，护栏从一层软提示升级为四层防御；元素表达力二次扩面——0.5 §4.6 评估销账的 chart 图层**正式解冻**（理由与 gate 记档于 §5.1），连同 curve/grid 图层与 filters/shadow/运动路径等 MC 3.17 已实证的能力；UI 侧把 `/dsh-anim/api/state` 里沉睡的数据亮成工作台总览页，卡片补上放大、跳转、终止、重试这些「用户本来就想点」的交互。五条主线： > 1. **清账**：0.5 收尾挂起账逐条盘点处置，每条给出去向，不留悬账； > 2. **收束防护**：会话无法结束 bug 的根治性自救——spec 级渲染状态 + 完成时刻收束指引 + 护栏归一化与硬闸（本版本头牌）； > 3. **稳**：工具产出稳定性——渲染前预检、回执卫生、段缓存版本纪律； > 4. **丰**：元素类别与属性扩面——chart/curve/grid 三种新图层，filters/shadow/letterSpacing/motion path 等属性； > 5. **亮**：UI 交互升级——`/dsh-anim/` 工作台总览页、卡片交互补全、轮询纪律统一。 --- ## 1. 遗留问题盘点与处置 ### 1.1 0.5.0 收尾挂起的账 | # | 遗留 | 现状核实（2026-09-20） | 0.6.0 处置 | | --- | --- | --- | --- | | 1 | **wait_agent 死循环护栏只是软提示**：同参第 3 次起附纠正文案，但签名含 atMs/scale 精确串（微调参数即重置计数）、状态在进程内 WeakMap（重启清零）、且只提示不拦截——真机 70+ 次循环时护栏每次都说话、模型每次都不听 | `packages/tools/src/ops.ts:591-662` 实证 | **本版本主体 B**（§3）：状态投影 + 收束指引 + 签名归一化 + 第二层计数 + 升级硬闸 | | 2 | **宿主会话恢复（session 捕获）暂未接**：懒恢复链路不受影响，但宿主重启后渲染任务簿（内存态）清空，后台卡片进度条与 `/api/state` 出现空窗 | 0.5.0 §9 真机端到端遗留观察 | **M0 评估**（§2.2）：调查宿主 session 捕获接口面与渲染簿持久化代价；能接则接，不能则把「重启后进度簿清空」正式定性为设计内形态并落档 UI 降级口径 | | 3 | 面板指令回合延迟 ~57s（LLM 生成占 ~42s） | 0.5.0 §2.4 已按判据销账「不做 loopback 直改」 | 维持观察（模型速度收益），无代码动作；主体 E 的「终止/重试」按钮走既有面板指令通道，不得绕开已销账的结论 | | 4 | vite CJS 弃用告警（MC vite 插件依赖链） | 0.4 M0 记录，来源非本插件配置 | 维持观察；MC/宿主升级时顺带复核，无独立动作 | | 5 | dsh 新 alpha/rc 持续发布 | 0.1.6-alpha.2 已验证，peer 维持 `>=0.1.5-rc.2` | 开工基线复验（§2.1）；每个新版本跑挂载冒烟 + 真机出片，破坏性变更记进本文件 | ### 1.2 0.5.0 §8「明确不做（推到 0.6+ 或正式放弃）」逐项处置 | # | 项 | 0.6.0 处置 | | --- | --- | --- | | 1 | 自动伸缩时间线的音画对齐 | 维持报告制不做（speechNotes 对账清单已够用） | | 2 | 云端 TTS SDK 内置 | 维持 Provider seam + 外部命令通道不做 | | 3 | 字幕双语/多轨道（`subtitles` 字段预留） | 维持预留；真机需求密度出现再评估，本轮无动作 | | 4 | 多会话并行渲染 | 维持不做（同进程串行闸兜正确性，跨会话并行收益不稳） | | 5 | Remotion / Manim 渲染 Provider | 继续推迟，本轮继续把 Motion Canvas 单后端做厚 | | 6 | 思维导图 / 复合图层全家桶 | **chart 图层单独解冻**（§5.1）：0.5 §4.6「不进 IR」的销账结论本轮正式推翻，理由与 gate 记档；思维导图等其余复合图层继续不做 | | 7 | 画布拖拽式编辑 | 维持不做；主体 E 提供浅交互替代（缩略图放大、点帧跳转视频），不引入画布编辑面 | | 8 | 3D / 粒子效果 | 维持不做 | | 9 | 场景相机 | 维持放弃（不挂账） | | 10 | store 快照优化 | 维持观察（sidecar fold 至今无可测瓶颈） | ### 1.3 README「已知限制与说明」逐条处置 | # | 现有条目 | 0.6.0 处置 | | --- | --- | --- | | 1 | 图层类型 15 种 | 扩面（§5：chart/curve/grid + 评估项），README 同步刷新 | | 2 | 转场与缓动族 | 维持；转场新 kind 仅作低优先小步评估（§5.5） | | 3 | 旁白字幕（TTS 已落地） | 维持，无代码动作 | | 4 | 远端字体 CORS | 维持文档，无代码动作 | | 5 | 后台任务依赖宿主 jobs | §2.2 调查后按结论刷新表述 | | 6 | 媒体放行白名单 | 维持，无代码动作 | | 7 | 插件事件不进宿主会话日志 | 维持（fail-closed 约束不变） | | 8 | 渲染环境（MC 3.17 编辑器自动化） | 维持，无代码动作 | | 9 | Windows `dsh plugin add` pnpm 转发 | 维持文档绕过方案 | ### 1.4 本轮体检新发现（2026-09-20，为 0.6.0 规划做的全库复查） > 复查范围：`packages/{spec,store,render-mc,tools,client}` 源码 + node_modules 里 MC 3.17 的 .d.ts 实证 + README + 0.5.0 真机追记。编号 N1~N8；后续体检发现续编。 | # | 发现 | 证据 | 处置 | | --- | --- | --- | --- | | N1 | **渲染完成后无 spec 级「已渲染」状态**：SpecRecord 只有 version/patches/outline/events，没有阶段字段；工具层无法判断「该 spec 是否刚渲染完成」，渲染成功后再调 anim_preview / anim_render 没有任何语境提示 | `packages/store/src/index.ts:37-48` | 主体 B §3.1：fold 投影 `lastRender` | | N2 | **完成时刻恰无收束指引**：票据 `next` 是「发起时」的正确姿势（job_output），而模型真正拿到完成结果的三个位置——job_output 产物（即 RenderResultView）、`anim/render-finished` 事件载荷、同步渲染成功回执（`RenderResultView` 无 `next` 字段）——都不带「报告用户并结束回合」的话 | `packages/tools/src/ops.ts:792-817`（无 next）、`events.ts:133` | 主体 B §3.2 | | N3 | **护栏可绕过且无升级**：签名对参数精确敏感（换 atMs 即重置）；只有同参一个维度，无 spec 维度总量闸；只有软提示没有硬拒绝 | `ops.ts:632`（签名构造） | 主体 B §3.3 | | N4 | **`/api/state` 全量数据无 UI 消费**：specs 的幕结构/时长/版本史/渲染簿都已吐出，但客户端只有按 jobId 捞单条 render 的用法，没有跨会话的总览视图——「我的所有片子」只能翻会话流 | `packages/tools/src/web.ts:326-351`；client 无页面消费 | 主体 E §6.1 | | N5 | **轮询实现重复且粗粒度**：PreviewTicket 与 BackgroundTicket 是两份几乎相同的 ~60 行轮询；且都逐条 fetch 全量 `/api/state` 找单个 job，state 变大后浪费 | `client/src/cards/preview.tsx:67-108` vs `render.tsx:32-74` | 主体 E §6.4 | | N6 | **卡片交互短板一揽子**：缩略图/contact sheet 只能新标签开原图（无放大、无对比）；contact sheet 点帧不能让视频跳到对应时间；运行中任务卡无「终止」按钮（终止只存在于模型侧 job_kill）；失败态只有一行 error 无重试；媒体加载失败静默隐藏图块 | `preview.tsx:23`、`primitives.tsx:117`、`protocol.ts:208-218`（仅三种 action） | 主体 E §6.2 | | N7 | **MC 3.17 弹药库未接**（已逐一核对 node_modules .d.ts，非文档推测）：Node 级 CSS filters（blur/brightness/contrast/saturate/grayscale/hue/invert/sepia）与 shadow* 信号、Txt `letterSpacing`、`Grid` 组件、`Spline` 平滑曲线、`Curve.getPointAtPercentage`（运动路径采样） | `2d/lib/partials/Filter.d.ts`、`Node.d.ts:29-34`、`Layout.d.ts:161`、`Grid.d.ts`、`Spline.d.ts`、`Curve.d.ts:183` | 主体 D §5 的候选弹药 | | N8 | **MC `Icon` 组件与离线分发定位冲突**：Icon 运行时从 iconify 在线源拉取 15 万图标，离线渲染环境不可用 | `2d/lib/components/Icon.d.ts` | 评估制 gate（§5.5） | --- ## 2. 主体 A：遗留清账与真机基线（M0） ### 2.1 dsh 基线复验（开工第一件事） 在当前 verified 的 dsh 版本上复跑 examples 全链路出片，对照 0.5 基线数字（426 帧 / 冷启动数字见 0.5 §9）确认无漂移；漂移则先归因再动工。每个新 alpha/rc 照此台账跟进。 ### 2.2 宿主会话恢复与渲染簿持久化调查（§1.1 #2） - 调查宿主 session 捕获接口面：插件能否在宿主恢复会话时重建渲染任务簿（0.5 的「捕获子插件」模式是否适用于 session 服务）； - 评估渲染簿 sidecar 持久化的代价与收益：进程内 RenderTracker 换成 sidecar 落盘（或 fold 时从 `anim/render-*` 事件重建进行中状态）——注意「进行中任务」跨进程恢复的正确性很可疑（宿主重启时子进程已死，恢复出的「进行中」是谎言），**倾向结论：只恢复「已完成」产物记录，进行中任务重启后如实显示「已中断」**；最终以调查结论为准，落档本文件； - 产出同时服务主体 E：总览页与后台卡片的重启降级口径在此定稿。 ### 2.3 其余台账落档 vite CJS 告警（维持观察）、Remotion/Manim（继续推迟）、字幕多轨（维持预留）等逐条在 §1 表格内给出处置结论，无独立代码动作；本版本收尾时在 §10 记账。 --- ## 3. 主体 B：会话收束与防循环强化（本版本头牌） > 设计立场：0.5 真机 turn 17 的退化循环（preview → wait_agent 空转 → preview，70+ 次）根因是模型行为退化，**根治在宿主侧**（回合步数上限 / 同参工具调用去重），插件无法替代；但插件可以把自救从一层软提示做成四层防御：**状态 → 指引 → 软提示 → 硬闸**。 > 红线：硬闸只打两种退化特征——「同参高频」与「同 spec 超高频」；合法的「修改 → 抽帧复查」循环靠 spec version 重置与保守阈值豁免。拒绝永远给出路（改参数 / 等窗口过期 / 请用户确认），绝不把用户显式要求的工作堵死。 ### 3.1 spec 级渲染状态投影（N1） - store fold 时把 `anim/render-finished` 事件投影为 SpecRecord 派生字段 `lastRender: { outputPath, finishedAt, specVersionAtRender }`——事件溯源同源，零新事件类型，会话恢复后依然成立（sidecar 事件流本来就是恢复源）； - `specVersionAtRender !== 当前 version` 即「渲染后已修改」，这是 3.3 里「合法复查豁免」的判据； - `anim_preview` / `anim_render` 入口读取该状态；`anim_diagnose` 不动（它管环境不管 spec）。 ### 3.2 完成时刻的收束指引（N2） - `RenderResultView` 增 `next` 字段（同步成功回执补齐）；`anim/render-finished` 事件载荷带同一份 `next`——后台路径 job_output 拿到的产物就是 RenderResultView，自动继承，三处出口一次覆盖； - 措辞（冒烟锚点钉住）：「成片已就绪 ``——请直接向用户报告结果并结束本回合；如需修改，先用 anim_patch 改时间线再 anim_render 重渲，不要对未修改的 spec 反复抽帧」； - preset 增「收尾纪律」段：渲染完成后报告即收尾；修改 → patch → 重渲是唯一再动渲染/预览工具的理由；锚点校验沿用既有模式。 ### 3.3 护栏升级：归一化、第二层计数与硬闸（N3） - **签名归一化**：atMs 数组排序去重 + 秒级量化后入签名——「挪 200ms 绕护栏」不再重置计数，而一次调用内取多个抽帧点本就合法（数组语义），不受影响； - **第 3 次软提示**：现役 `repeatGuardNote` 保留不动； - **第 6 次同参硬拒绝**（阈值建议值，配置可调）：直接抛 `AnimOpError`，文案含已拦截次数、正确姿势（job_output / 结束回合）与出路（修改参数语义 / 等窗口过期 / 请用户确认）；preview 与 render 两条路径全覆盖（直放、后台票据、同步三条返回路径在入口统一闸）； - **第二层 spec 维度闸**：10 分钟窗口内同 spec 同工具 preview 超 15 次给软提示、超 30 次硬拒绝——治「每次都换一点参数」的绕行；spec version 变更即重置该 spec 计数（修改后的正当复查不受误伤）； - **持久化评估**：倾向维持进程内（退化循环发生在同一进程的同一回合里，重启即断环；持久化反而让「用户明天想重抽一帧」撞上昨天的计数），结论落档；若 3.1 的 lastRender 走事件投影后计数顺带可得持久性，再评估，不作为目标； - 冒烟：3 软 / 6 硬路径、归一化后换参仍计数、version 变更重置、spec 维度阈值、拒绝文案含出路、四条返回路径闸位一致。 ### 3.4 宿主侧根治建议持续落档 回合步数上限 / 同参去重继续在 dsh 0.1.x 台账反馈；插件侧四层防御的定位写进 README 已知限制（「护栏是自救不是根治」），避免使用者误以为插件能兜住所有模型退化。 --- ## 4. 主体 C：工具产出的稳定性 ### 4.1 渲染前预检（pre-flight） - `anim_render` 开跑前做一轮零渲染开销的快检，结果以「预检」分组进回执 warnings： - 资产引用完整性：`asset:` 指向的文件不存在 → **硬错误快速失败**（替代渲染中后段的隐晦报错）； - 0 帧幕（durationMs 不足一帧）、字幕带占用、语音 cue 溢出的汇总（现散落各处的软警告在渲染入口聚合一份）； - 预检不改变任何渲染语义，只把「注定失败的渲染」提前到毫秒级暴露。 ### 4.2 回执卫生 - `anim_preview` 的 atMs 超出全片时长：先核实现行为，越界点钳制到片尾并附警告（真机先验证再定稿）； - `anim_render` 的 `scenes` 切片越界 / 空数组：报错人话化（点名合法索引范围）； - coerceScene / 别名表按真机新错形常态化收敛（0.5 模式延续，不设独立条目）。 ### 4.3 段缓存与版本纪律 - 主体 D 落地 → `CODEGEN_VERSION` 5→6，旧段缓存全量失效一次属预期（正是版本号的设计用途），记档； - TTS displayMs 段指纹口径（0.5 M1 修过的失配）保持冒烟回归，防止新图层改动再次踩偏。 ### 4.4 回归资产扩充 - `scripts/m05-verify.ts` 增防循环段（同参连发触发软/硬闸、version 重置解除）与预检段（缺资产快速失败）； - 冒烟在 92 项基础上扩展（预估 +15 项左右），typecheck 五包全绿照旧作为合入门禁。 --- ## 5. 主体 D：元素与属性扩面（chart 正式解冻） > **为什么推翻 0.5 §4.6 的销账结论**：当时的评估是「MC 3.17 无图表组件，最小 bar/line 也需 300+ 行生成器，preset 配方（rect+scale 轨道）可达同视觉」。0.6 重评估的增量证据：① 教学侧数据讲解是高频刚需，配方路线无数值轴、无自动布局、模型每根柱子手摆，负担与出错率都高，表达力天花板低；② 生成器成本被 0.4 以来的表驱动架构（STATIC_PROPS / normalize / PROP_ALIASES）摊薄，且坐标轴刻度计算是纯函数、可冒烟钉死；③ 折线「生长」动画可复用 line 图层已验证的 `start/end` 画线进度语义，柱体生长可复用 scale 轨道——不需要新动画机制。 > **为什么不是接入 ECharts / Chart.js 这类图表组件**：它们产 canvas 快照，进 MC 只能当一张图，逐元素教学动画（柱子依次长高、折线描画）全部丢失；且依赖重量与离线打包冲突。本项目的「图表绘制组件」= codegen 用 MC 基础节点组合生成的图表 emits——动画语义天然进既有轨道模型。 > **Gate 不变**：PoC 不立则退回 preset 配方路线并二次销账（第三次解冻需要宿主级图表能力或 MC 升级，写进档案）。 ### 5.1 chart 图层（gate 制，D 主体头牌） - IR：`type:'chart'`，props：`chartType: 'bar' | 'line'`、`data: [{ label, value }]`、可选 `maxValue`（缺省按数据自动）、`showAxis`（坐标轴显隐，默认 true）、`palette`（系列色板，缺省内置色板）；**v1 单系列**； - codegen：组合生成 Rect/Txt（bar）或 Line/Txt（line，数值标注）+ 自动坐标轴（刻度与布局为纯函数，冒烟单测）； - 入场动画：图层 `props.progress` 轨道（0→1）——bar 驱动柱体 scaleY 生长 + 数值淡入；line 驱动画线进度（`start`/`end` 语义复用）；无 progress 轨道时静态整图； - gate：M2 首日 PoC——生成量、headless 出帧稳定性、真机观感；不过则退回配方路线，技巧包收录「rect 摆柱状图」进阶配方； - pie / 多系列 / 面积图 → 明确不做（推 0.7+，视 bar/line 立住与否）。 ### 5.2 curve 平滑曲线图层（低成本，MC Spline 直通） - `type:'curve'`，props：`points`（同 line 折线语义）、`smoothness`、`endArrow` 等——平滑曲线是函数图象（配 math 图层讲函数）、思维轨迹批注的基础件；MC `Spline` 组件直通，STATIC_PROPS/COMPONENT 两表登记即可。 ### 5.3 grid 网格图层（低成本，MC Grid 直通） - `type:'grid'`，props：`spacing`、`width/height`、`stroke/lineWidth`——坐标系与对齐参考的教学表达，与 chart/curve/math 天然搭配。 ### 5.4 属性丰富度（MC 3.17 已实证信号，静态直通为主） - **`filters`**：全部图层增 CSS 滤镜集 `{ blur?, brightness?, contrast?, saturate?, grayscale?, hue?, invert?, sepia? }`（静态直通 Node `filters` 信号）——高亮聚焦（blur 周边弱化）、灰度弱化是教学高频手法；**滤镜的逐帧动画性（轨道化）本轮评估不落地**（数组信号与标量轨道模型不合）；headless 出帧行为 gate 首验，不过则缩回 shadow 单独落地（0.4 渐变的先例）； - **`shadow`**：`shadowColor/shadowBlur/shadowOffset` 直通——卡片/重点框立体感； - **text `letterSpacing`** 直通；**image `radius`**（Layout 圆角裁切）直通； - **motion path 沿路径运动**：图层 props 增 `followPath: ` + `progress` 轨道（0→1），codegen 生成 `pathRef.getPointAtPercentage(progress)` 驱动位置（MC `Curve` API 已实证）——粒子沿函数曲线运动、箭头沿流程走位的表达力大头；validate 前置校验：悬空 id、自引用、被引用图层不是 line/curve 皆报错； - 全部新属性进工具描述与 preset 对照表，冒烟断言沿用「描述示例可解析、可过校验、codegen 零警告」模式。 ### 5.5 评估项（gate 制，不预设结论） - **Icon 图层**（N8）：MC `Icon` 直通成本极低，但运行时依赖 iconify 在线源——真机验证 headless 出帧 + 离线可用性；预期结论「在线环境可选能力、离线环境用 svg 图层内嵌替代」，按 gate 结果落地或落档； - **转场新 kind**（wipe/move 变体）：低优先，按 MC 实际能力小步评估，不立不动。 ### 5.6 三包接线纪律与技巧包 - 新图层类型的接线清单照 0.6 体检基线执行：`spec/types.ts` LAYER_TYPES → `render-mc/codegen.ts` 三表（编译期钉死，漏改编译报错）→ `tools/register.ts` 工具描述（冒烟断言盯住）→ `ops.ts` coerceScene（如需）→ preset 对照表 → README 图层清单；client 卡片零改动（回执驱动）； - 每批生成语义变更 `CODEGEN_VERSION` +1；examples 增 0.6.0 演示幕（chart/curve/grid/filters/motion path）。 --- ## 6. 主体 E：UI 交互升级 ### 6.1 工作台总览页 `/dsh-anim/`（N4，零宿主插槽依赖） - 插件自有路由直接 serve 一个独立单页（client 包新增 entry，esbuild 双产物），消费既有 `/api/state`：specs 总览（名片 / 版本 / 时长 / 幕数 / 最近成片缩略）、渲染任务簿、最近产物媒体墙；同源 cookie 天然鉴权，headless 形态整页不存在（与现路由同纪律）； - 宿主导航集成点（能否在 dsh web 外壳加入口）M3 首日调查；fallback：anim_render / anim_create_spec 卡片放「工作台」链接 + README 口径； - 重启降级口径沿用 §2.2 调查结论（已完成产物可恢复展示，进行中任务如实显示「已中断」）。 ### 6.2 卡片交互升级（N6） - **Lightbox**：缩略图墙与 contact sheet 点开模态放大、键盘/按钮翻页（v1 不做前后版本对比，数据源问题记入评估）； - **点帧跳转**：RenderCard 的 contact sheet 点某帧 → 同卡 `