---
title: 0.5.0 版本规划：配音落地、工具产出打磨与表达力扩面
---

# 0.5.0 版本规划：配音落地、工具产出打磨与表达力扩面

> 0.1.0 打通「模型 → AnimationSpec IR → MP4」全链路，0.2.0 把工作台「亮出来」，0.3.0 把图层类型从 4 种撑到 13 种并补上资产管线与导演 preset，0.4.0 把产能做厚（增量渲染、实例常驻、音轨/字幕/退场）。
> 0.5.0 的主题是**兑现**：把前四个版本一路挂账到「0.5」的东西逐一兑现——0.1 就在 IR 里预留的 TTS 配音、0.4 真机挂起的 jobs 后台化、0.4 §4.8 让路完毕的打字机与 video 图层；同时把「模型 ↔ 工具」配合再打磨一轮：回执更丰富（批量读取、时间线摘要、单幕直放）、纠错更前置。四条主线：
> 1. **清账**：遗留问题逐条盘点处置，每条给出去向（落地 / 评估后销账 / 正式放弃），不留悬账；
> 2. **配音**：TTS 语音合成落地——Provider seam + 外部命令通道（edge-tts / piper 配方），旁白 cue 从「显示」升级为「发声 + 显示」，音画对齐以「报告 + 缓存」落地；
> 3. **稳与丰**：工具产出稳定性与丰富性——`anim_get` 批量与摘要视图、单幕预览直放、渲染回执拼贴图、写库纠错持续收敛；
> 4. **表达力**：元素与属性扩面——video 图层、文本段落排版与逐字打字机、lineDash、渐变填充、缓动 in/inOut 变体。

---

## 1. 遗留问题盘点与处置

### 1.1 0.4.0 收尾时挂起的账

| # | 遗留 | 现状核实（2026-09-18） | 0.5.0 处置 |
| --- | --- | --- | --- |
| 1 | **jobs 服务对插件上下文不可见（`jobsOnCtx=false`）**，preview/render 真机走同步回退，后台票据全链路从未在真机跑过 | 0.4.0 §5.5 真机实证（dsh 0.1.6-alpha.1）；同步路径已事件化，实际痛点收敛为「模型回合被渲染挂住」 | **M0 真机调查**（§2.1）：确认 dsh-tool-jobs 对插件上下文暴露的确切条件（preset/宿主组合加载？宿主版本演进？），能启用则真机验收后台票据；宿主侧确实无解则结论落档，维持同步回退为设计内形态 |
| 2 | **媒体路由白名单无音频扩展**：`MEDIA_TYPES` 只有 mp4/webm/mov/png/jpg/jpeg/gif/webp/svg，audio 图层落地后资产卡与成片都无法试听 | `packages/tools/src/web.ts:202-211` 实证；0.4.0 §1.1 #3 预告过「按需补充」未做 | **本版本落地**（§2.2）：白名单补 `.mp3/.wav/.ogg/.m4a/.flac`，AssetCard 与成片卡补试听控件 |
| 3 | vite CJS 弃用告警降为「每进程一次」后仍现（来源 MC vite 插件依赖链，非本插件配置） | 0.4.0 M0 真机记录，观察项 | 维持观察；若 MC/宿主升级顺带复核，无独立动作 |
| 4 | dsh 版本跟进：0.1.6-alpha.2 兼容性已验证（挂载冒烟全绿），新 alpha/rc 持续发布 | 最新 commit `548a299` | 持续跟进：每个新 alpha/rc 跑一遍挂载冒烟 + 真机出片，破坏性变更对比记进本文件；peer 依赖维持 `>=0.1.5-rc.2` |
| 5 | **loopback RPC 直改 spec**：0.3 推迟→0.4 评估条件是「followup 路径真机跑稳」——条件已达成（0.4 M3 端到端验收通过） | 面板按钮现经 `session/prompt` 走模型回合执行 | **M0 评估销账**（§2.4）：真机测面板指令的回合延迟与 token 成本，给出「做/不做」的明确结论并记档；倾向——若延迟可接受则正式销账不做（「模型是唯一写者」的简单性值得保留），仅当实测不可接受才落直改 PoC |

### 1.2 0.4.0 §8「明确不做（推到 0.5+）」逐项处置

| # | 项 | 0.5.0 处置 |
| --- | --- | --- |
| 1 | TTS 语音合成与音画自动对齐 | **本版本主体之一**（§5）：Provider seam + 外部命令通道 + 音画对齐报告。IR 增量刻意最小——`narration.cues[].voice` 字段 0.1 起已预留 |
| 2 | 多会话并行渲染 | 维持不做。SwiftShader 吃 CPU，并行收益不稳；增量渲染已吃掉大部分重复渲染量 |
| 3 | loopback RPC 直改 spec | 移交 §1.1 #5：M0 评估后销账 |
| 4 | Remotion / Manim 渲染 Provider | 继续推迟。渲染 seam 就绪但多后端维护成本高，本轮继续把 Motion Canvas 单后端做厚 |
| 5 | 图表 / 思维导图等复合图层 | **部分解冻**：最小 chart 图层（bar/line）进评估（§4.6，P2，真机验证不过则退回 preset 配方路线并销账）；思维导图继续不做 |
| 6 | 逐字打字机入场（0.4 §4.8 让路完毕） | **本版本落地**（§4.3）：与配音天然搭配（旁白发声时逐字出现） |
| 7 | video 图层（0.4 §4.8「真机验证后再定排期」到期） | **本版本真机验证后落地**（§4.4）：headless 导出的帧同步是唯一硬门槛，验证不过则顺延并落档原因 |
| 8 | 画布拖拽式编辑、3D / 粒子效果 | 维持不做 |
| 9 | 场景相机 | 维持放弃（不挂账） |
| 10 | store 快照优化 | 维持观察。sidecar fold 至今未成为可测瓶颈 |

### 1.3 README「已知限制与说明」逐条处置

| # | 现有条目 | 0.5.0 处置 |
| --- | --- | --- |
| 1 | 图层类型 14 种 | 扩为 15 种（+`video`，§4.4）；chart 若评估通过再增 |
| 2 | 转场与缓动族 | 缓动补 `bounce/elastic/back` 的 in/inOut 变体（§4.5）；转场族不动 |
| 3 | 旁白字幕：无 TTS（规划在 0.5） | **兑现**（§5）：README 该条目本版本删除 |
| 4 | 远端 http(s) 字体 URL 需 CORS | 维持文档，无代码动作 |
| 5 | 后台任务依赖宿主暴露 jobs 服务 | §2.1 调查后刷新表述 |
| 6 | 媒体放行扩展名白名单 | 补音频扩展（§2.2），README 同步 |
| 7 | 插件事件不进宿主会话日志 | 维持（fail-closed 约束不变），无代码动作 |
| 8 | 渲染环境（MC 3.17 编辑器 UI 自动化等） | 维持，无代码动作 |
| 9 | Windows `dsh plugin add` 的 pnpm 转发 | 维持文档绕过方案，无代码动作 |

### 1.4 本轮体检新发现（2026-09-18，为 0.5.0 规划做的全库复查）

> 复查范围：`packages/{spec,store,render-mc,tools,client}` 源码 + README + 三份真机文档。编号 N1~N3；后续体检发现续编。

| # | 发现 | 证据 | 处置 |
| --- | --- | --- | --- |
| N1 | **`anim_get` 单 path**：schema 只收一个 JSON Pointer（`register.ts:492-495`），模型查「某幕的图层清单 + 某资产 + 全局 theme」要烧 3 个来回；且没有「时间线摘要」视图——想看全局起止结构只能拉大块 JSON | `register.ts` anim_get 参数表 | **批量 + 摘要视图**（§3.1）：`paths` 数组一次取多段；`view:'summary'` 返回全片时间线摘要（幕起止 / 图层数 / 轨道跨度 / 音频字幕清单），省来回省 token |
| N2 | **段缓存已产出「每幕一段 mp4」，面板却只能看抽帧图墙**：0.4 M1 的增量渲染天然留下单幕成片段（`work/<specId>/segments/`），「预览这一幕」按钮仍走低分辨率抽帧——段缓存命中时本可直接内嵌播放单幕原画质短视频 | `adapter.ts` 增量段产物；`PreviewCard` 仅 FrameGrid | **单幕直放**（§3.2）：段命中时「预览这一幕」升级为段视频内嵌播放，未命中回退抽帧（预期管理不变：抽帧无音频） |
| N3 | **纠错知识只进代码不进「模型面」**：coerceScene / 别名表是被动补丁（0.3 O20/O21 补一批、0.4 §2.1 收敛成表），但「已收编的错形清单」没有沉淀到 preset 方法论与工具描述的对照区——模型换会话后还会再犯新错形，老错形靠 coerce 兜底、新错形靠报错回修 | `ops.ts` coerceScene；`config/agent-presets/` | **纠错对照表进 preset**（§3.4）：persona 增「高频手误 → 规范写法」对照段（冒烟锚点校验沿用既有模式），coerce 扩展照真机错形按需做 |

---

## 2. 主体 A：遗留清账与真机基线（M0）

### 2.1 jobs 后台化真机调查（§1.1 #1）

- 真机排查 dsh-tool-jobs 的加载路径：它是否需要宿主 profile 显式启用、能否经 preset/宿主组合让插件上下文拿到 `ctx.jobs`；顺带核对 0.1.6-alpha.2+ 是否已变化；
- 代码面已就绪（opRender/opPreview 同一降级链、BackgroundTicket/PreviewTicket、任务簿 `/api/state`），**本项零插件代码改动**——结论只有两种：能启用 → 真机验收后台票据全链路（进度条、job_output 收集、job_kill 终止）；不能启用 → 结论落档本文件，同步回退正式定性为「当前部署的设计内形态」，README 表述刷新；
- 附加产出：同步路径下「模型回合被渲染挂住」的实测时长记录（为 §2.4 的 loopback 评估提供对照数据）。

### 2.2 面板音频试听（N1 的另一半，低成本）

- `MEDIA_TYPES` 补 `.mp3/.wav/.ogg/.m4a/.flac`（MIME 表齐全即可，放行规则不变：outputDir 内或回执精确路径 + 白名单）；
- AssetCard：audio 资产给 `<audio controls>`（source 走 `/dsh-anim/media?p=`）；RenderCard：成片卡已有 `<video>` 自带播放，补「音轨清单」展示（`audioTracks` 字段已贯通）；
- 冒烟：MIME 表断言（音频扩展可达 + 可达扩展的 Content-Type 正确）。

### 2.3 真机基线复验（开工第一件事）

沙箱无浏览器，渲染侧一切改动的对照基线沿用 0.4 的结论数字（冷 24.6s / 暖 15.2s / 增量 8.2s / 全命中 0.1s）。本版本开工时在 dsh 0.1.6-alpha.2+ 复跑一遍 examples 全链路出片，确认基线数字未漂移；漂移则先归因再动工。

### 2.4 loopback RPC 直改 spec：评估销账（§1.1 #5）

- 测量：真机走一遍「面板按钮 → session/prompt → 模型回合 → anim_patch 落库」全链路，记录端到端延迟与 token 消耗；
- 判据：延迟秒级内且 token 成本可忽略 → **正式销账不做**（「模型是唯一写者」保证 coerce/对账/事件语义单一出口，简单性价值高于延迟收益），结论记进本文件；延迟不可接受 → 落「撤销这步」单按钮直改 PoC（undo 是唯一无歧义、无需 coerce 的操作），其余按钮维持 followup；
- 无论结论如何，本项在 0.5.0 内闭环，不再挂账。

---

## 3. 主体 B：工具产出的稳定性与丰富性（稳·丰）

### 3.1 `anim_get` 批量读取 + 摘要视图（N1）

- **批量**：schema 增 `paths: string[]`（与单 `path` 并存，单数形式向后兼容），回执按 path 分段返回，单段截断口径与现状一致；一个来回拿齐「图层 + 资产 + theme」；
- **摘要**：`view: 'summary'` 返回时间线摘要——各幕 `{id, startMs, durationMs, 图层数, 音频图层}`、全片总时长、narration cues 数、资产清单（id/kind/引用计数）；模型做「节奏体检复查」「删资产前的引用检查」不再需要拉整段 JSON；
- 摘要由 spec 包新增纯函数产出（store 与 client 面板可复用同一份）；冒烟：批量多段返回 / 摘要字段口径 / 单数形式兼容。

### 3.2 单幕预览直放（N2）

- 「预览这一幕」按钮与 `anim_preview` 增加段缓存快路径：目标幕的段文件存在且指纹命中 → 直接把段 mp4 走媒体路由内嵌播放（原画质、带音频），卡片从 FrameGrid 升级为 VideoPanel；
- 未命中（无段缓存 / 指纹失配 / 无渲染产物）回退现有抽帧路径，预期管理表述不变；
- 段缓存是渲染副产品，此能力**零新增渲染开销**——只是把已有的东西送到面板；
- 边界：段文件与现行渲染参数（fps/scale/分辨率）不一致时不得直放（指纹已含渲染参数，天然覆盖）。

### 3.3 渲染回执拼贴图（contact sheet）

- `anim_render` 收尾按幕均匀抽 4~8 帧拼成一张 contact sheet（ffmpeg tile 滤镜，落 `outputDir/<specId>/contact-<hash>.jpg`），回执与卡片带路径；
- 价值面：模型回执可见「成片结构是否对」（幕序、留白、字幕带占用），用户在面板一键看到全片概览——补上「渲染完成 → 只能逐帧翻 preview」的空档；
- 拼贴失败只降级警告（不出片失败），不阻塞渲染回执；文件命名带内容 hash，重渲自然覆盖不堆积。

### 3.4 纠错对照表进 preset + coerce 持续收敛（N3）

- preset persona 增「高频手误对照」段：ease 字符串 / type 大小写 / strokeWidth 别名 / color 别名 / 字幕带占用 / atMs 全片绝对毫秒口径等已收编错形的「错误写法 → 规范写法」对照表；冒烟锚点校验沿用既有模式；
- coerceScene / 别名表按真机新错形按需扩充（0.5 候选：atMs 秒-毫秒量级混淆的软警告、十六进制颜色缩写归一）——原则不变：只修无歧义、不丢内容的错，repairs 随回执回报；
- 工具描述与 preset 的口径由冒烟断言钉住（描述示例可解析、可过校验、codegen 零警告的既有断言扩展到对照表）。

---

## 4. 主体 C：元素与属性扩面（广）

### 4.1 文本段落排版（低成本，真机经验直接复用）

- text 图层静态属性增 `maxWidth` + `textWrap`（MC Txt / Layout 原生 signal，直通 STATIC_PROPS 即生效）——正文长段落自动折行，不再只能靠模型手工断句；
- 0.4 字幕折行趟过的两个坑直接复用为已知约束：`\n` 需要 `textWrap:'pre'` 才生效、`lineHeight` 数字语义是 px（倍数传字符串）——写进工具描述与 preset 对照表；
- 冒烟：STATIC_PROPS 扩展 + 折行生成物断言。

### 4.2 lineDash 直通与渐变填充（P1）

- line/arrow 增 `lineDash`（MC Curve 内建 signal，直通）——虚线/辅助线的教学表达；
- `fill` 支持渐变描述对象：`{ type:'linear', from:[x,y], to:[x,y], stops:[[offset,color],…] }`（或 MC 实际 API 形态为准，**真机核实 MC 3.17 的 LinearGradient 构造签名后定稿**），codegen 把对象翻译成渐变实例；不支持渐变的属性位维持现状告警降级；
- 真机首验：渐变在 rect/text/code 的观感与 headless 出帧稳定性；验证不过则本项缩回 lineDash 单独落地，渐变顺延并落档。

### 4.3 逐字打字机 reveal（0.4 §4.8 让路完毕）

- text 图层 `props.reveal` 轨道（0→1）由 codegen 特判：生成按进度裁剪文本的 signal（复用字幕折行已验证的文本度量路径），实现逐字/逐词浮现；
- 与配音（§5）天然搭配：旁白发声 + 逐字出现是教学片的标准形态；
- 文本度量风险沿用 0.4 收口时的判断：涉及估宽，先做**字符数近似**（CJK 等宽假设），真机验收形态不达标再上精确度量；
- 冒烟：reveal 轨道生成物断言（普通文本轨道不受影响）。

### 4.4 video 图层（0.4 §4.8 到期，真机验证 gate）

- asset kind 增 `video`（`anim_asset_import` 白名单与 copyAssetsToPublic 跟随）；图层 `type:'video'`，props：`src`（`asset:<id>`）、`volume`、`loop`——映射 MC Video 节点；
- **唯一硬门槛是真机验证**：headless 导出下 Video 节点的帧同步（MC 3.17 有 Video 节点但 headless 出帧行为未验证）。M2 开工首日验证，不过则整项顺延 0.6 并落档原因，不做半吊子；
- 验证通过后：STATIC_PROPS/COMPONENT/ANIMATABLE_BY_TYPE 三表 + 工具描述 + preset 同步（三表 Record 类型钉死，漏改编译期就炸）；音视频混合时间线的预期管理写进描述（实拍片段与动画时间轴的对齐口径）。

### 4.5 缓动 in/inOut 变体（低成本）

- `EaseSpec` 增 `bounceIn/bounceInOut`、`elasticIn/elasticInOut`、`backIn/backInOut`，映射 MC 对应导出（0.4 的「映射表 × MC .d.ts 实际导出」静态断言模式照搬，防升级漂移）；
- `coerceScene` 的 ease 字符串包装对新品类自动生效；工具描述与 preset 对照表同步。

### 4.6 chart 图层评估（P2，评估制）

- 教学片高频需求（数据讲解、对比图表），但复合图层的历史结论是「preset 配方教学覆盖」——0.5 只做**评估**：最小范围（bar/line 两种，`data` 数组 + 自动坐标轴 + 数值动画入场）的真机 PoC，评估「codegen 生成量、MC 实现路径（Rect/Line 组合 vs 第三方）」；
- PoC 立住 → 正式入 IR 排 0.6（本版本不进稳定面）；立不住 → 销账「不做」，维持 preset 配方路线（用 rect 轨道摆柱状图的技巧进 §4.7 技巧包）。

### 4.7 视频技巧包更新（零代码）

- preset 方法论与 examples 随新能力增补：虚线辅助线、渐变底版、打字机旁白、（若 4.6 走配方路线）rect 柱状图配方；examples 增 0.5.0 演示幕。

---

## 5. 主体 D：配音 TTS（本版本头牌）

### 5.1 架构原则：Provider seam，宿主外置

- TTS 能力是与渲染 seam 同构的标准接口：`TtsProvider`（`synthesize(text, opts) → { filePath, durationMs }`）+ 注册表 + `provideTts()`——想接云服务/本地引擎就写一个 Provider 顶掉默认项，工具与 IR 零改动；
- **首发不内置任何云 SDK / API key**：默认 Provider 是「外部命令」通道——配置模板 `tts.command`（占位符 `{text}` `{outFile}` `{voice}` `{rate}`），进程执行、产物落盘、ffprobe 实测时长；edge-tts（免费、需网络）与 piper（完全离线）作为 README 配方，契合离线分发定位；
- `anim_diagnose` 增 TTS 报告：命令是否配置、可否执行（dry-run 探测）、缓存放；未配置时报告「字幕照常、无配音」的设计内形态。

### 5.2 IR 最小增量

- `narration` 增可选 `tts?: { voice?: string; rate?: number; volume?: number }`（全片默认）；cue 级 `voice` 字段 0.1 起已预留（`types.ts:264`），本版本接通消费，cue 可覆盖默认 voice；
- **语义不变式**：TTS 关闭时 IR 渲染结果与 0.4 完全一致（`tts` 缺省即纯字幕模式）；`subtitles` 字段维持预留不动；
- spec `version` 仍为 1（增量全为可选字段，存量 spec 天然兼容）。

### 5.3 渲染接线与缓存

- 渲染入口发现 `narration.tts` 且 Provider 可用 → 逐 cue 合成：缓存键 = 稳定序列化（text, voice, rate）的 hash，产物落 `work/<specId>/tts/<hash>.<ext>`——同文重渲零重合成（段缓存同款纪律）；
- 合成产物实测时长（ffprobe）加入音轨清单：起点 = cue 的全片绝对 `atMs`，与 BGM/audio 图层同一 mux 管线（`adelay` 对齐 + `amix`，0.4 M2 已验证多轨混音）；
- 字幕显示时长跟随实测音频：`cue 展示时长 = max(估算时长, 实测音频时长)`——避免「字没了声还在」；语音溢出进下一幕起始时间的冲突给软警告（点名 cue 与毫秒数）；
- **音画自动对齐 v1 口径：报告而非改时间线**——渲染回执带每条 cue 的 `{ text, atMs, audioMs, 溢出 ms }` 清单，需要挪时间/改文案由模型 `anim_patch` 决策。自动伸缩场景时长明确不做（时间线是模型的领地，自动改会破坏指纹、大纲对账与增量缓存的语义）。

### 5.4 失败与降级（红线不变）

- 单条 cue 合成失败：该条降级为纯字幕 + 警告进回执与事件，**不阻塞出片、绝不静默**；
- 命令整体不可用（未配置/执行失败）：全片降级纯字幕模式 + 一条汇总警告；
- 隐私说明写进 README 与 `anim_diagnose` 报告：TTS 会把旁白文本送进配置的外部命令（可能出网），离线环境用 piper 类本地引擎。

### 5.5 真机验收

- edge-tts 配方端到端：中文旁白出片有人声、音画对齐（adelay 起点准确）、字幕跟随语音时长、二次渲染缓存命中不重合成（耗时对照落档）；
- 失败注入：坏命令 / 超时 → 降级警告可见、成片照常；
- piper 离线配方至少文档级验证（沙箱装不了则真机补验并记档）。

---

## 6. 里程碑与验收

| 里程碑 | 内容 | 验收标准 |
| --- | --- | --- |
| **M0 遗留清账** | §2 全部：jobs 调查、音频试听、真机基线复验、loopback 评估销账 | jobs 结论落档（启用或定性）；音频扩展可在面板试听；alpha.2+ 基线数字复验无漂移；loopback 有做/不做的明确结论 |
| **M1 稳·丰** | §3 全部：批量+摘要、单幕直放、拼贴图、纠错对照表 | `anim_get` 批量/摘要冒烟全绿；段命中时单幕直放（真机）；渲染回执带 contact sheet；preset 对照表有锚点断言 |
| **M2 表达力** | §4.1~4.5 + §4.7（video 4.4 真机 gate 首日判定；chart 4.6 只出评估结论） | maxWidth 折行 / lineDash / reveal 打字机 / in-inOut 缓动出片；video 图层 gate 结论落档（过→三表同步出片，不过→顺延记档） |
| **M3 配音** | §5 全部 | edge-tts 端到端有人声、音画对齐、缓存命中零重合成、失败降级警告可见；README「无 TTS」条目删除 |

版本内顺序：M0 → M1 → M2 → M3；M3 的 seam 与 mux 接线无前置依赖，可与 M1/M2 并行开工（真机验收仍在 M3 窗口）。分支 `feat/0.5.0-voice`；发版前跑离线打包验证（offline-packager → tgz → 安装 → 出片）。peer 依赖维持 `>=0.1.5-rc.2`。

## 7. 风险

| 风险 | 等级 | 应对 |
| --- | --- | --- |
| jobs 服务启用条件在宿主侧无解（插件上下文持续拿不到 `ctx.jobs`） | 中 | 本项定位就是「调查 + 定性」：结论落档后同步回退即设计内形态，插件不自带后台执行器（重复造 job 体系的收益不抵维护成本） |
| video 图层 headless 帧同步不过（MC Video 在导出管线的行为未验证） | 中 | M2 首日 gate：不过即顺延，零沉没成本（三表类型钉死，未合入即无残留） |
| 渐变填充对 MC 3.17 API 形态的假设偏差 | 低 | 真机核实构造签名后再定稿 IR 描述；不过则缩回 lineDash 单独落地 |
| 打字机文本度量在 CJK/拉丁混排下形态不佳 | 中 | v1 字符数近似 + 真机验收；不达标退回「逐词」粒度并在描述收窄建议场景 |
| TTS 外部命令的跨平台差异（Windows 引号转义、超时、编码） | 中 | 命令模板走数组形式规避 shell 解析；超时显式报错；真机 Windows 首验 |
| TTS 合成时长与字幕/场景时长普遍冲突（语速不可控） | 中 | v1 明确「报告 + 手动 patch」；回执清单让模型一次看全偏差，避免逐条试探 |
| 摘要视图口径与真实求值不一致（摘要说 A、渲染出 B） | 低 | 摘要函数与时间线求值同源（spec 包同一套 timeline 计算），冒烟断言两者口径一致 |
| dsh 0.1.x 破坏性变更（持续风险） | 持续 | 锁 verified 版本；IR / 工具层与宿主解耦的既有策略不变；新 alpha/rc 进 §1.1 #4 台账 |

## 8. 明确不做（推到 0.6+ 或正式放弃）

多会话并行渲染（维持不做）、Remotion / Manim 渲染 Provider（继续推迟）、思维导图 / 复合图层全家桶（chart 只做最小评估）、自动伸缩时间线的音画对齐（报告制）、画布拖拽式编辑、3D / 粒子效果、场景相机（维持放弃）、store 快照优化（维持观察）、云端 TTS SDK 内置（走 Provider seam 与命令通道，SDK 由使用者自行提供）、字幕双语/多轨道（`subtitles` 字段继续预留）。

---

## 9. 实施进度

分支：`feat/0.5.0-voice`。

| 项 | 状态 | 说明 |
| --- | --- | --- |
| 0.5.0 规划 | ✅ 完成 | 本文件：遗留盘点（0.4 挂账 5 条 + §8 推迟 10 条 + 本轮体检 N1~N3）+ 四大主体 + 里程碑 |
| M0 遗留清账 | ✅ 完成（2026-09-19，代码 + 真机验收） | **§2.2 音频试听**：`MEDIA_TYPES` 补 `.mp3/.wav/.ogg/.m4a/.flac`，AssetCard 音频资产就地 `<audio controls>` 试听（资产在 outputDir/assets/ 内天然可服务），冒烟加五类扩展 MIME 断言。**§2.1 jobs 真机调查（本版本最重要的排障）**：静态排查发现宿主 dsh-base bundle 在 alpha.2 已加载 jobs 三件套（jobs-local + tool-jobs + client-ui-jobs），0.4 的 `jobsOnCtx=false` 另有原因——深挖 cordis 4 源码定位根因：**上下文代理按 inject 声明生成服务隔离键，未声明的服务属性访问直接抛 `cannot get property without inject`**，插件从未声明 jobs，探测恒 undefined。两条弯路记档：① 把 jobs 写进主插件 inject——cordis 对缺失声明服务会**延迟挂载直到可用**（冒烟实证：裸 cordis 上插件永不启动，工具列表为空），不可用；② 直接属性探测被许可门控挡死。**最终方案「捕获子插件」**：挂一个只声明 `inject:['jobs']` 的子插件，宿主有 jobs 时子插件启动、把服务捕进 box 并从同层 ctx 调 `attachController('dsh-anim-studio')`；宿主没有则子插件静默不启动、主插件照常挂载。真机（dsh 0.1.6-alpha.2 web profile 独立测试实例）验证：`jobsOnCtx` false→**true**；`anim_render` 回执 `kind:"background"`、`jobId:"anim-render-1"`，任务簿 completed 100%、`/api/state` 可查——**后台化在真机首次端到端跑通**。附带发现：jobs.start 的 servesOwner 门控还要求 controller 覆盖 owner/无主两档，tool-jobs 的 controller 挂在它自己的 scope 里 serve 不到我们，署名 controller 是必要补丁；start 失败原因现落宿主日志（原先静默吞掉）。**§2.3 基线复验**：examples 全链路出片 426 帧（30fps×14.2s）无漂移。**§2.4 loopback 评估销账**：真机实测面板指令全链路（POST /api/session/prompt → inbox spliced +56ms → 模型回合 → 工具执行 → 回报）总耗时 ~57s，其中 LLM 生成 ~42s、preview 抽帧 ~7s——投递是毫秒级、延迟大头是模型回合本身；按规划判据**正式销账「不做」**：「模型是唯一写者」保证 coerce/对账/事件语义单一出口，直改通道最多省 LLM 时间却要承担绕过整套边界校验的架构代价；档案结论：若未来实测不可接受，「撤销这步」单按钮直改是唯一值得做的 PoC |
| M1 稳·丰 | ✅ 完成（2026-09-19，代码 + 真机验收） | **§3.1 批量+摘要**：spec 包新增 `summary.ts`（`summarizeSpec`：幕起止/图层规模/audio 清单/字幕数/资产引用计数，口径与 timeline 求值同源）；`anim_get` 增 `paths` 批量（单段错误不拖垮其余段）与 `view:"summary"`。**§3.2 单幕直放**：渲染 seam 增可选 `findSceneSegment`（与增量渲染同口径指纹：展开字幕场景 JSON + fps/缩放/分辨率 + CODEGEN_VERSION；scale 不匹配时按全分辨率兜底再查），`previewClipFastPath` 单幕命中即回放段视频；PreviewCard 命中时升级为 VideoPanel（原画质带音频），回执 9ms 级返回（对比抽帧 ~7s）——真机在宿主会话里验证命中（`clip.path` 指向 segments 段文件）。**真机抓到并修复一个失配**：TTS 渲染的段指纹带 displayMs（字幕跟随语音时长 → 场景 JSON 变），`findSceneSegment` 查段时必须带同一份 displayMs 才能命中，快路径现与渲染链同口径（缓存命中近零开销）。**§3.3 拼贴图**：渲染收尾 ffmpeg `fps=N/时长` 均匀采样 8 帧 tile 4×2，与成片同目录 `.contact.jpg`（重渲覆盖不堆积）；失败降级警告；RenderCard/任务簿贯通展示。**§3.4 纠错对照表**：preset persona 增「高频手误对照表」（ease 字符串/type 大小写/strokeWidth、color 别名/秒毫秒混淆/字幕带占用等七条），冒烟锚点护航；`validateSpec` 增 durationMs<34ms「疑似把秒写成毫秒」软警告（亚帧时长渲染静默 0 帧是真实 footgun） |
| M2 表达力 | ✅ 完成（2026-09-19，代码 + 真机验收；video gate 通过） | **§4.1 文本段落**：text 增 `maxWidth`+`textWrap`。真机连抓两个 MC 语义坑：① 独立 Txt 只给 maxWidth 不参与布局就不 reflow——normalize 同步落到 width（STATIC_PROPS.text 补 width 白名单，否则被「不支持」丢弃——冒烟抓过一次）；② `textWrap:'pre'` 映射 CSS white-space:pre **不折行**，自动折行要 `true`（IR 语义文档化：true=折行 / 'pre'=只认显式 \n）。真机抽帧确认 620px 段落折 3 行。**§4.2 lineDash 与渐变**：line/arrow/rect 增 `lineDash`（Shape 基类 signal 直通，真机虚线可见）；`fill` 支持渐变对象 `GradientSpec`（tuple stops `[[offset,"#色"]]`），codegen 生成 `new Gradient({...})`，非法形态写库即报、生成期告警摘除——真机渐变底版观感确认。**§4.3 打字机**：text 的 `props.reveal` 0→1 轨道特判生成 `createSignal` + 文本裁剪函数，逐字浮现真机逐帧确认（1.2s 处 5 字/2.0s 处 15 字，进度与 easeInOut 曲线吻合）。**§4.5 缓动变体**：bounce/elastic/back 各补 In/InOut 共 6 个新 kind（映射×MC .d.ts 导出断言沿用），真机 bounceIn/backInOut 出片。**§4.4 video 图层（gate 通过）**：asset kind 增 video（mp4/webm/mov），`LayerType` 增 `video` → MC `Video` 组件（固定注入 `play={true}`，否则 headless 导出 time 停在起点；`time`/`playbackRate`/`loop` 直通；volume 无对应 signal 会告警降级），真机 gate 首验通过：ffmpeg 生成 testsrc 测试片 → video 图层渲进成片，抽帧确认实拍画面在片中。CODEGEN_VERSION 3→5（中途 v4/v5 两次生成语义变更各失效一次旧段，正是版本号的设计用途）。**§4.6 chart 评估销账**：MC 3.17 无图表组件，最小 bar/line 也需 codegen 组合 Rect/Line/Text + 数值刻度计算 + 数值动画（估 300+ 行生成器与配套校验面），而同视觉结果经 preset 配方（rect+scale 轨道摆柱状图）即可达成——**结论：不进 IR，维持 preset 配方路线，正式销账**。**§4.7 技巧包**：preset 增 lineDash/maxWidth 折行/打字机/视频嵌入等技巧与手误对照表 |
| M3 配音 | ✅ 完成（2026-09-19，代码 + 真机验收） | **§5.1 seam**：tools 包新增 `tts.ts`——`TtsSynthesizer` 接口 + `createTtsService`（外部命令模板，数组形式 execFile 不经 shell、占位符 `{text}/{outFile}/{voice}/{rate}/{stdin}`、voices 映射表、超时、ffprobe 实测时长）；`anim_diagnose` 报告 `tts.configured`。**§5.2 IR**：`narration.tts` 可选默认（voice/rate/volume），cue 级 `voice`（0.1 预留）接通；tts 缺省 = 纯字幕模式，IR/渲染行为与 0.4 完全一致。**§5.3 渲染接线**：`opRender` 生成 speech 载荷（Promise——后台渲染时合成发生在 job 内，不占模型回合；job_kill 时序补了「信号已中止不再进渲染」的防线，冒烟的 unsettled-await 抓到）；逐 cue 合成按 sha256(text|voice|rate) 缓存于 `work/<specId>/tts/`；字幕显示时长 = max(估算, 实测)（`expandNarration` 接 displayMs）；语音轨道与 BGM 同一 adelay+amix 管线；`speechNotes` 报告每条 cue 实测时长与溢出毫秒（**报告制，不自动改时间线**）。**§5.4 降级**：单条失败降级纯字幕+警告、空文本跳过、坏命令整体降级，均不阻塞出片。**真机验收**（edge-tts 7.2.8，zh-CN-XiaoxiaoNeural +8%）：① `scripts/m05-verify.ts` 端到端——双 cue 合成 4080/4224ms、成片 h264+aac、speechTracks=2、缓存命中零重合成（第二次渲染合成命令 0 次调用）、坏命令降级 2 条警告；② 宿主会话 E2E——profile 配置 tts.command 后 `tts.configured:true`，模型自主完成建 spec→写旁白→渲染，成片双流 mean_volume -20.4dB（人声混入确凿），speechNotes 溢出警告与对账清单可见；③ 隐私口径进 README 与配置描述 |
| 真机端到端 | ✅ 完成（2026-09-19，独立测试 profile） | 环境：dsh 0.1.6-alpha.2 web profile 派生测试实例（不动用户 web profile，独立端口 + 独立 outputDir + tts 配置注入）。API 驱动全链路（launch token 认证 → session/create 挂 anim-studio preset → session/prompt queue → session/page 翻页核验）：① 模型自主导演流程 diagnose→create→plan→patch→draft→get→preview→patch→render 全通，含一次自动回修；② 后台渲染（见 M0）；③ 面板指令预览直放（见 M1）；④ TTS 出片有声（见 M3）；⑤ 冒烟 87 项 + typecheck 五包 + 宿主挂载冒烟全绿。**遗留观察**：面板指令回合延迟 ~57s 中 LLM 占 ~42s——preset 已约定「直接执行不反问」，后续可观察新模型的速度收益；宿主会话恢复（session 捕获）暂未接，懒恢复链路不受影响 |
| 真机追记：TTS 声音被服务端拒 + 缓存污染修复 | ✅ 完成（2026-09-19，用户 web 实会话抓到） | **现象**：用户 Transformer 讲解片渲染，8 条旁白 cue 全部 `NoAudioReceived` 降级纯字幕（前一天 m05 验收同机同链路是好的）。**根因隔离**（换声音/换文本对照实验）：失败跟声音走不跟文本走——`zh-CN-XiaoxiaoMultilingualNeural` 与 `en-US-AriaNeural/GuyNeural/JennyNeural` 全部 0 字节，`zh-CN-XiaoxiaoNeural/XiaoyiNeural/YunxiNeural/YunyangNeural` 全部正常出声；`--list-voices` 正常、edge-tts 7.2.8 已是最新——**微软 Edge 非公开接口阶段性掐掉了 Multilingual 与 en-US 类声音**，报错文案（"verify that your parameters are correct"）极具误导性。**暴露的两个代码缺陷当场修复**：① 失败残留污染缓存——引擎抛错前已建出 0 字节产物，`existsSync` 判缓存命中 → ffprobe 必败 → 服务恢复也永久降级；现失败即清产物 + 缓存命中先实测时长、读不出就删掉重合成（自愈）；② 无重试——网络引擎瞬时拒绝直接降级，现 `runWithRetries` 默认再试 2 次（500ms/1500ms 退避，`tts.retries` 可调）。冒烟新增 2 检（坏缓存自愈 / 重试语义）共 89 项。**配置侧**：用户 profile 旁白音换 `zh-CN-XiaoxiaoNeural`（中英混排实测无碍），声音避坑经验进 README 与 preset |
| 真机追记：同会话并发渲染互踩 + 串行闸收口 | ✅ 完成（2026-09-19，用户 web 实会话抓到） | **现象**：TTS 修复重启后（08:54 成片渲染 8 条音轨全部成功——上一条追记的修复真机确认生效），模型 11:47~11:51 连发 6 个 preview + 1 个 render，渲染任务簿七个任务排队推进；成片渲染（全量路径）在 ffmpeg 处暴毙：「Could find no file or sequence … %06d.png index 0-4」——帧目录被清空。**根因**：串行闸（0.3.x O2）只圈住了抽帧，`encodeFrames` 在闸外跑；排队的下一个管线进闸第一件事 resetDir 清共享帧目录，正好清在上一个任务「抽完帧、未编码完」的窗口里（预览的抽样帧路径同样指向共享帧目录，被后续管线清掉后卡片取图落空）。**修复**（render-mc/adapter）：① 全量渲染「抽帧 + encodeFrames」同闸；② 预览「抽帧 + 抽样帧拷贝进稳定 `preview/` 目录」同闸，回执路径不再指向会被清的共享目录；③ `encodeFrames`/`encodeFrameRange` 起编码前先验首帧，把「找不到序列」翻译成「抽帧没产出或帧被清空」的人话。**回归**：m05-verify 新增 F 段——假 runtime 复刻「进闸先清目录」语义，断言并发渲染+预览排队双成功、预览帧在第三个任务清目录后幸存（事件序 A→B→C 严格串行）；冒烟 89 项 + typecheck 五包全绿。**口径更新**：§8「多会话并行渲染不做」指跨会话；同进程内的工具并发由渲染器串行闸兜底，属正确性红线而非性能取舍 |
| 真机追记：后台任务等待误用 wait_agent 死循环 + 护栏 | ✅ 完成（2026-09-19，用户 web 实会话抓到） | **现象**：mux 修复重启后 turn 17「重新渲染完整成片」——渲染 21:41 即成功落盘（64.5s/1936 帧，音轨流 61.58s 覆盖至最后一条 cue 结束，**mux 修复真机确认生效**），但模型回合永不收尾：`anim_preview{atMs:[1000]}` → `wait_agent` → 再 preview……同一参数机械重复 70+ 次（preview-6→78+），会话 UI 表现为「一个预览工具调用无法结束」。**根因**：模型想「等后台任务完成」，却用了 wait_agent——那是 Agent Team 等**队友**的工具，无队友时**立即**返回 noProgress（根本不等待），于是 preview（秒回票据）→ wait_agent（秒回空转）→ 无限循环；票据 next 里的正确姿势（job_output）从未被采纳。工具侧每次调用都正常返回，属**模型行为退化**，但护栏该工具来加。**修复**：① 票据 next 动态带 jobId 并显式写明「不要用 wait_agent 等待本任务，不要重复发起同一渲染/预览」；② 同参重复发起护栏 `repeatGuardNote`（按插件实例 WeakMap 隔离）：同签名 10 分钟窗口内第 3 次起，票据/回执（后台与同步、直放命中四条路径全覆盖）附加纠正指引——任务照常执行不拒绝，只把正确姿势递到模型眼前；③ preset 增「后台任务纪律」段（job_output 轮询、完成判定看 status、严禁 wait_agent/重复发起）。**回归**：smoke 新增护栏检查共 92 项；typecheck 五包 + m05 全量（A-G）全绿。**遗留观察**：此类模型退化循环的根治在宿主侧（回合步数上限/同参工具调用去重），插件侧护栏只能提高自救概率 |
| 真机追记：多轨 mux 时序 bug + solo 切片覆盖正片 | ✅ 完成（2026-09-19，用户 web 实会话抓到） | **现象**：用户成片「只有第一句有配音」，但渲染回执声称 8 条 speech 音轨全部混入。**排查**（渲染簿 + ffmpeg 逐窗响度实测）：① 盘上成片其实是**8 秒第一幕 solo 切片**——模型用 `scenes:[0]` 渲染时走了默认输出路径，把 64.5s 正片覆盖了（回执 speechNotes 仍是全片 8 条 cue 口径，加重误判）；② 音轨流时长仅 6.024s（= 各 cue durationMs 最大值），cue0 窗口 -18.8dB 有人声、其余窗口 -91dB 数字静音——**mux 滤镜序 bug**：链序是 `adelay(位移) → atrim(钳长)`，而 atrim 的时钟是滤镜链当前时间轴，先位移再钳长保留下来的恰好是「前导静音」段，人声整段被裁；cue0（起点 200ms < 时长）碰巧残留 2.87s 人声所以可听。该 bug 0.4 的 audio 图层时代已埋下（无人给 BGM 设过延迟起点），0.5 TTS 让延迟轨成为常态才炸出；m05 B 段未抓住是因为测试片有 BGM 垫满音轨时长。**修复**：① mux 链序改 `atrim → asetpts → volume → adelay`（先钳 cue 自身时长归零、再位移到绝对起点）；② `scenes` 切片渲染默认落 `<specId>-solo-<indices>.mp4`，绝不覆盖正片（显式 outputPath 由调用者决定）；③ 切片渲染的语音载荷按选中幕原始时段过滤并平移到切片时轴（`sliceSpeechForScenes`，notes 同步过滤、displayMs 保持与 narration 全量对齐）。**回归**：m05 新增 G 段——真 ffmpeg 三条错峰音轨逐窗 volumedetect 实测（修复前第二条起全静音）；smoke 新增 2 检共 91 项（solo 路径不覆盖正片 / 切片语音过滤平移）；typecheck 五包全绿 |