dsh-drawai 0.3.3 → 0.4.0

package/README.md

@@ -8,15 +8,24 @@
 
 ## 功能一览
 
-`dsh-drawai` 把可编辑画布放进 DeepSeek Harness 右侧栏，并给模型两个改图工具；人和 AI 读写的是同一份原生 `.drawio`。
+`dsh-drawai` 把可编辑画布放进 DeepSeek Harness 右侧栏，并给模型两个改图工具；人和 AI 读写同一份画布。新建默认使用 `.drawai` 原生 JSON，旧 `.drawio` 在界面打开时自动迁移并保留原稿。
 
-1. **右侧栏可编辑画布** —— 打开 / 新建工作区 `.drawio`：画节点、连边、就地改字、分层、排序、对齐、导出；双击即可改标签。
+原生格式、媒体目录、自动迁移和兼容说明见[原生画布文档](docs/native-canvas.md)。
+
+1. **右侧栏可编辑画布** —— 打开 / 新建工作区 `.drawai` 或 `.drawio`：画节点、连边、就地改字、分层、排序、对齐、导出；双击即可改标签。
 2. **自然语言改图** —— 对话里说需求，模型用 `diagram_read` / `diagram_apply` 读现状、结构化改图、自动布局并原子写回。
 3. **选区感知与回退** —— 你在画布上选中什么，模型就知道什么；模型改动最多可退 8 步。
 4. **SVG 图形节点** —— 图标 / logo 可直接当节点内容，拼流程图与示意图。
 5. **位图矢量化（`traceImage`）** —— 照着工作区图片逐像素描成 SVG 节点，不是凭印象手写近似图。
-6. **原生 `.drawio` 载体** —— 无需导入导出；画布读不懂的单元逐字节保留，文件可直接用 drawio / diagrams.net 继续编辑。
+6. **原生文档与 drawio 兼容** —— `.drawai` 保存多页、节点扩展和叠放顺序；旧画布迁移保留完整 XML 与原媒体，支持另存为 `.drawio`。
 7. **视频复刻** —— 选中已导入视频，点击悬浮工具条「绘制复刻」自主设置画质、帧率、完整视频或起止范围，自动抽帧并绘制成 SVG 视频；显示预计帧数、实际进度与帧预览，支持取消，原视频保留。支持 SVG 帧序列包，以及保留原帧率、白底和片段音频的 MP4 / WebM 离线导出；也可导出白底、循环播放的无声 GIF。渲染、编码和保存由宿主后台执行，切换标签或刷新网页后仍继续，完成文件自动保存到画布旁（编码需 FFmpeg）。详见[视频节点说明](docs/video-nodes.md)。
+8. **文生图** —— 0.4.0 暂未开放，已有图片节点仍可显示和编辑。
+
+9. **节点绘制视频** —— 选中视频节点，先用 `shotcraft_search` 挑几张镜头卡连到它（连线顺序=镜头顺序，卡片时长=段长；**卡必须连**，断连的卡会被 `motion_project create` 直接拒绝），再说一句要做什么：`motion_project` 按卡片排好时间轴，并把**分镜表**（每镜做什么/屏幕上出现什么/配什么字）写进工程；先只写 `scene-0`、`motion_preview` 看一张**定调帧**把风格定住，再铺开写其余场景。AI 在对话里直接读写 `scene-*.tsx`，`motion_render` 在后台渲染，完成后 `motion_render apply` 把成片落成画布上能播的 clip pack。**只有对话里这一个 agent**：没有第二套后台 agent、不需要轮询、不用等任务面板。详见[动效视频说明](docs/motion-video.md)。
+
+10. **音频、音效、旁白与踩点** —— 把 BGM、旁白挂进时间轴（`motion_audio add`），渲染时由画面侧一起播放，淡入淡出与「旁白期间压低 BGM」都在音量曲线上算；旁白用 `motion_voice` 合成（脚本一句一行，台词决定镜头多长，字幕自动进 `timeline.subtitles`）；音效可用 `motion_sfx` 从 Freesound 搜（**不按许可过滤**，每条结果带许可标签，用哪条由人决定），下载时保存来源和许可信息至音频素材索引，需署名时根据索引自行整理。`motion_audio analyze` 给出 BPM 与等距节拍网格，`motion_audio apply` 把切镜吸到拍子上，`motion_audio_verify` 再从成片音轨回测对拍误差。详见[声音制作说明](docs/motion-audio.md)。
+
+11. **素材捕获与看帧验收** —— 图片、音频、视频可捕获进工程 `assets/`（`motion_assets`，附尺寸、色板、峰值），**产品界面还能用 `motion_assets page` 让无头 Chrome 把一段 HTML 模板或网址截成 2 倍图**（截到登录页/错误页/空白页会直接报错，不会静默存一张假界面），场景里用 `staticFile()` 引用；`motion_preview` 一次渲染多帧拼成一张图直接回给对话，不用等整片渲染就能看版式。详见[动效视频说明](docs/motion-video.md)。
 
 ![整体界面：右侧栏画布与多标签](docs/picture/整体界面图.png)
 
@@ -44,8 +53,9 @@ dsh plugin --profile web add github:fourzkw/dsh-drawai
 
 | 装好后的变化 | 出现在哪里 |
 |---|---|
-| 「DrawAI 画布」面板，负责打开 `**/*.drawio` | 右侧栏 |
-| `diagram_read` / `diagram_apply` | 模型工具集 |
+| 「DrawAI 画布」面板，负责打开 `**/*.drawai` 和 `**/*.drawio` | 右侧栏 |
+| `diagram_read` / `diagram_apply` / `shotcraft_search` | 模型工具集 |
+| `motion_project` / `motion_preview` / `motion_render` / `motion_assets` / `motion_audio` | 视频工程工具 |
 | `drawai-canvas` 技能 | 会话技能目录（模型按需取全文） |
 
 - 两种装法都不需要 `allowBuilds` 构建授权：npm 包是预构建的；GitHub 源码包里 `lib/` 也已提交、没有 `prepare` / `postinstall` 脚本。
@@ -53,13 +63,22 @@ dsh plugin --profile web add github:fourzkw/dsh-drawai
 
 ## 使用 / Usage
 
-一块画布、两个工具、一份文件：人改的、模型改的、drawio 改的，最后都落在同一个 `.drawio` 上。
+人和模型共享同一画布文档；对话可直接编排节点、建视频工程、改场景、看预览和出片。迁移后以 `.drawai` 为主，原 `.drawio` 作为保留原稿；外部编辑原稿会提示版本冲突。
 
 | 入口 | 你能得到什么 |
 |---|---|
 | **右侧栏画布** | 打开或新建画布、画节点与连线、就地改字、图层、分区、顺序、多选对齐、查找、微移、多页切换、复制粘贴、导出 SVG / PNG / 透明 PNG（4×，含导出选中） |
 | **`diagram_apply`** | 让模型按 ops 改图：增删改、重接边、复制、排序、分层、导出；支持 `ids` 批量、`as` 别名、`expectRevision` |
 | **`diagram_read`** | 让模型看见图的结构与样式、图层与父级、页面尺寸、你此刻的选区、文件指纹 `revision` |
+| **`motion_project`** | 建/打开视频工程：按挂上来的镜头卡排时间轴，写 `timeline.json` 与 `scene-*.tsx` 桩 |
+| **`motion_preview`** | 渲染指定几帧并拼成一张图直接回图（首次打包 10–30 秒，之后复用缓存） |
+| **`motion_render`** | `start` 立刻返回 jobId、后台渲染；`status`/`list`/`cancel`；`apply` 把成片回填成画布 clip pack |
+| **`motion_assets`** | `list` 看工程素材，`library` 搜插件纹理和乐器采样，`use` 按需导入；另支持 `capture`、`crop`、`palette`、`page` 等 |
+| **`motion_audio`** | 音轨增删与对齐：`list`/`add`/`remove`/`analyze`（节拍网格）/`apply`（钉帧） |
+| **`motion_sfx`** | 音效采购：`search`（Freesound，不按许可过滤，结果带许可）/`get`（下载 + 详情页许可复核 + 署名清单）/`list` |
+| **`motion_audio_verify`** | 从成片音轨回测每拍偏差，超过 2 帧判不合格 |
+| **`motion_voice`** | 旁白：`plan`（脚本→估时长→重排镜头→写字幕，不合成）/`say`（合成后再按真实时长重排）/`align`（只按已有音频重排）/`list`。脚本 `voice.script.md` 一节一句，台词决定镜头多长 |
+| **`motion_task`** | 旧任务记录：`list`/`status`/`cancel`/`focus`/`remove`（新流程不用它开工） |
 | **选中与回退** | 你选中什么模型就知道什么；模型的每一轮改动都能在界面上退回去 |
 
 ## 🗂️ 画布面板 / The canvas panel
@@ -72,7 +91,8 @@ dsh plugin --profile web add github:fourzkw/dsh-drawai
 | **SVG 图形节点** | 节点内容直接是一段 **SVG 标记**（图标 / logo / 示意图这种形状词汇表里没有的东西）：右键「SVG 内容…」贴进去即可，或让模型用 `addNode {shape:"svg", svg:"<svg viewBox…>…</svg>"}`。落盘是 drawio **原生**的图片形状（`shape=image` + `image=data:image/svg+xml,<百分号编码>`），所以 drawio 桌面版打开同样画得出来；标记只喂给 `<image>`（独立文档，脚本不执行、也不碰页面 DOM） |
 | **内嵌位图** | 从剪贴板粘贴或拖入 PNG / JPEG / GIF / WebP，画布会**真的画出来**（同为 `shape=image` + data URI）。`diagram_read` 把 base64 省略成 `«image N 字符»`，不撑爆上下文 |
 | **位图矢量化 traceImage** | 让模型照着工作区里一张图**逐像素**描成 SVG 内容节点（读像素 → 按必填的 `removeBg` 决定是否泛洪抠底 → k-means 调色板 → 3× 超采样归类 → 按颜色取像素级闭合轮廓 → 每色一条 nonzero path）。形状词汇表表达不了的照片 / 插画走这条，而不是让模型手写一段近似 SVG 冒充复刻 |
-| **文本** | 双击节点就地改字。「T 文字」是独立的文字节点；支持字号与字色。图片和视频节点不显示文字 |
+| **文本** | 双击节点就地改字。独立文字和普通图形标签可对选中文字设置粗体、斜体、下划线、删除线、字色和字号；图片和视频节点不显示文字 |
+| **表格** | 元素条可新建表格；Markdown 表格与已有分镜表显示为网格，双击或选中后可逐格编辑。分镜仍以 Markdown 保存在一个节点中供视频工程读取 |
 | **连线** | 四选一画法（直线 / 直角折线 / 圆角折线 / 曲线）× 线型（含虚线间距）× 箭头（单向 / 双向 / 无 / 反向）× 颜色 × 引出段长度；自环；悬空端（从节点脱开后成为自由端点，还能再拖回去） |
 | **连线上的文字** | 双击改、按住拖（半格 + 贴线吸附）、右键「标签居中」；**线在文字的位置真的断开**（不盖白底） |
 | **选中与移动** | 框选 / Shift 加选 / `Ctrl+A`；整体拖动（折点与自由端点跟着同一个位移走）；对齐辅助线；多选对齐与分布 |
@@ -82,7 +102,7 @@ dsh plugin --profile web add github:fourzkw/dsh-drawai
 | **导出** | SVG / PNG(4×) / 透明 PNG(4×)；「看一眼画布效果」走 DSH 附件服务，**不在工作区落文件** |
 | **回退** | 「编辑 → 撤销 AI 改动」最多可以连着退 8 步 |
 
-## 🤖 两个工具 / The two tools
+## 🤖 模型工具 / Model tools
 
 ### `diagram_apply` —— 模型怎么改图
 
@@ -195,6 +215,10 @@ dsh plugin --profile web add github:fourzkw/dsh-drawai
 画布是自己实现的：纯 SVG + DOM，没有 iframe，也不依赖任何外部编辑器资源。换来的是每个单元都有
 id / layer / parent、选区能上报给模型、写回是逐单元的、画布本身能被模型驱动；代价是只覆盖这个格式的一个子集。
 
+## 🎨 文生图（暂未开放）
+
+0.4.0 暂时关闭文生图的新增、生成和服务设置入口；旧画布中的图片和节点数据继续保留。
+
 ## ⚙️ 配置与默认值 / Configuration
 
 **目前还没有设置页**：下面这些默认值都写在代码里；能通过 AI 侧改的，在右列给出等价做法。
@@ -209,6 +233,7 @@ id / layer / parent、选区能上报给模型、写回是逐单元的、画布
 | 主题跟随 DSH 的明暗 | —— |
 | 显示层、当前层 | 「图层」菜单（会写进文件） |
 
+
 **右侧常驻元素条**：按类型（图形 / 文字 / 分区 / SVG / 图片）放置，点画布落下**一次**即卸工具；
 「图形」的矩形、圆角、菱形等是同族变体，只在侧面板展开，不全部铺在主条上。选中图形后可换同族形状；悬停画布节点不会触发右侧工具栏浮窗。
 
@@ -234,6 +259,10 @@ id / layer / parent、选区能上报给模型、写回是逐单元的、画布
 
 **就地文字编辑**：双击节点或连线标签开始编辑，`Enter` / `Shift+Enter` 换行，点击外部或 `Ctrl+Enter`（Mac 为 `Command+Enter`）完成，`Esc` 取消。输入法确认文字不会提前完成编辑。
 
+独立文字和普通图形标签支持部分 draw.io 富文本格式，并可在 `.drawai` 保存及 `.drawio` 往返中保留。导入的复杂 HTML 经安全过滤后显示，完整 HTML 表格和连线富文本等仍不完整；混合字号的换行与对齐可能和 draw.io 不完全一致。表格节点的单元格编辑会以纯文字保存，若原有局部样式会在编辑器中提示。
+
+选中文字节点后调整「字色」或「字号」，会统一整段文字的对应属性，保留粗体、斜体等其他格式；双击进入编辑并选中部分文字后设置格式，仅影响选中的文字。工具栏与弹出面板会尽量留在窗口内。
+
 编辑框与显示标签共用文字区域、字体、行高和缩放：普通节点居中，分区标题左上对齐；换行在浏览器中按实际字体宽度计算，编辑中的节点撑高会先预览再提交。连线标签也支持多行显示，并按实际字号设置编辑框与连线避让区域。
 
 **连线工具与修改入口**：悬停右侧连线图标选择直线、直角折线、圆角折线或曲线，然后在空白处拖拽确定起终点；直接点击连线图标使用上次选择的类型。连线工具用于新建；修改已有连线请选中后使用浮动工具栏的「线型」，也可使用右键菜单。
@@ -244,7 +273,8 @@ id / layer / parent、选区能上报给模型、写回是逐单元的、画布
 - **生效方式**：宿主侧只在 `dsh web` 启动时加载，换 `lib/index.js` 必须**重启**；客户端是独立 bundle，刷新页面即可。
 - **界面语言**：目前只有简体中文，还没有 i18n。
 - **大图性能**：几百个单元时的重渲染与路由开销还没测过。
-- **数据与网络**：插件只读写工作区里的 `.drawio` 文件；不发网络请求、不读凭据，也没有安装期脚本。
+- **数据与网络**：画布文件和视频工程保存在工作区；音效搜索会访问 Freesound，网页素材收集会访问指定网站及品牌素材服务，Edge TTS 旁白和首次获取 Chromium 也可能联网。API key 存在浏览器 localStorage，宿主进程不保存；没有安装期脚本。
+- **视频素材**：动效用的 46 个字体与 102 个乐器采样 / 9 张纹理**不在 npm 包里**（约 200MB），第一次用到动效功能时会从 GitHub Release 下载一次（约 145MB），逐文件校验后缓存在 `~/.dsh/drawai-assets/v1/`，之后离线可用。下载失败或素材缺失时工具会返回可照做的中文指引；画布与图片功能不受影响。缓存位置与镜像地址可用 `DRAWAI_ASSETS_DIR` / `DRAWAI_ASSETS_URL` 覆盖；素材来源与许可集中记录在 [统一说明](LICENSE)。通过 `motion_assets library` 检索，再用 `motion_assets use` 导入当前工程，不依赖其他工程或固定磁盘路径；文件与上游哈希不一致时会提示并使用本地文件。导入图片和音频时需要可用的 FFmpeg。
 
 ## 已知限制 / Limitations
 
@@ -252,7 +282,10 @@ id / layer / parent、选区能上报给模型、写回是逐单元的、画布
 - 独立 `edgeLabel` 单元只读；`entityRelation` 等其它 edgeStyle、箭头字形、旋转 / 翻转 / 透明、stencil 形状只保留、不渲染；`.drawio.svg` / `.png` / `.html` 内嵌载体不支持。
 - **图片**：内嵌 SVG（`data:image/svg+xml,…`）与内嵌位图（PNG/JPEG/GIF/WebP data URI）都会画出来；**外链 / 相对路径**图片仍按矩形占位，单元原样保留（工作区磁盘上的图片文件画布直接读不到——要复刻请用 `traceImage`）。
 - 导出支持 SVG 与 PNG（透明背景、倍数或指定尺寸）：没有 PDF。
+- **文生图**：0.4.0 暂未开放。
 - 交互细节：对齐辅助线只跟节点比（不与折点、端点对齐）；单条选中的连线不能复制。
+- **视频**：动效视频节点是「画布上的一个工程目录」，成片靠 `motion_render` 后台渲染（首帧要打包，第一次通常 20–40 秒），渲染完成后用 `motion_render apply` 回填成 clip pack 才能在卡片里播放。节点不支持 `video_player` 式的自由播放控件（逐帧 / 跳转），要精确对照请用 `motion_preview` 或 `motion_render` 的 `frames` 参数看静帧。单帧渲染比整片省时，但每次仍要过一次打包（源码或素材变了才会重建缓存）。
+- **声音**：`motion_audio` 只做「分析节拍 + 挂到轴 + 钉拍」，不生成音乐；旁白靠 `motion_voice` 合成（edge-tts，需要本机 Python 3 + `edge_tts` 包；拿不到就退回 Windows SAPI，音色是老式播音腔）。整片渲完会自动过一次响度归一 + 限幅（`loudnorm` + `alimiter`，默认 −16 LUFS / 真峰值 −1.5 dBFS），目标可以在 `timeline.audioMix` 里改；画布上的音频节点只是素材库里的文件，不参与渲染。
 
 完整的取舍与实现细节在 [docs/design.md](docs/design.md)。
 
@@ -262,7 +295,7 @@ id / layer / parent、选区能上报给模型、写回是逐单元的、画布
 npm run watch   # 常驻：监听 src/，变化即重建 lib/
 npm run build   # 一次性构建
 npm run check   # 安装前烟测（含 lib 与 src 是否同步）
-npm test        # 六份自测（mxfile 编解码 / 路由预览 / 宿主行为 / 渲染 / 组件 / 矢量化），1716 项断言
+npm test        # 多份自测（mxfile 编解码 / 路由预览 / 宿主行为 / 渲染 / 组件 / 矢量化 / 视频 / 文生图 provider 与宿主路由）
 ```
 
 > ⚠️ **绝不改 `lib/` 下的文件** —— 它们是构建产物，会被覆盖。改 `src/`。

package/lib/audio-media.js

@@ -0,0 +1,147 @@
+/* 由 tools/build.mjs 生成 —— 请勿直接编辑；改 src/ 下的源文件。 */
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { randomUUID, createHash } from 'node:crypto'
+import { mkdirSync, readFileSync, writeFileSync, copyFileSync, statSync, realpathSync, existsSync, renameSync, unlinkSync } from 'node:fs'
+import { join, dirname, basename, relative, isAbsolute } from 'node:path'
+import { searchSfx, getSfx } from './motion/sfx.js'
+import { ffmpegBinary } from './video-export.js'
+import { clipDirFor, ensureClipPack, mediaRootFor } from './media.js'
+import { audioNodeData, audioNodeSettings, validateAudioTimeline } from './motion-core.js'
+const exec = promisify(execFile)
+const MAX_BYTES = 32 * 1024 * 1024
+const sha = bytes => createHash('sha256').update(bytes).digest('hex')
+const run = (args,signal,timeout=120000) => exec(ffmpegBinary(),args,{windowsHide:true,timeout,maxBuffer:2*1024*1024,signal})
+
+export function audioScopeDirectory(drawioAbs,directory,create=false) {
+  const root=realpathSync(dirname(drawioAbs))
+  let ancestor=directory
+  while(!existsSync(ancestor)){const parent=dirname(ancestor);if(parent===ancestor)throw new Error('音频目录无效');ancestor=parent}
+  const inside=value=>{const rel=relative(root,realpathSync(value));if(isAbsolute(rel)||rel==='..'||rel.startsWith('..\\')||rel.startsWith('../'))throw new Error('音频真实路径超出画布目录')}
+  inside(ancestor)
+  if(create)mkdirSync(directory,{recursive:true})
+  if(existsSync(directory))inside(directory)
+  return directory
+}
+
+export function frozenAudioFile(drawioAbs,clip) {
+  const directory=realpathSync(audioScopeDirectory(drawioAbs,clipDirFor(drawioAbs,clip))),file=realpathSync(join(directory,'audio.wav'))
+  const rel=relative(directory,file)
+  if(isAbsolute(rel)||rel.startsWith('..'))throw new Error('音频文件超出媒体包')
+  const manifest=JSON.parse(readFileSync(audioScopeDirectory(drawioAbs,join(directory,'audio.json')),'utf8'))
+  if(sha(readFileSync(file))!==manifest.sha256)throw new Error('音频文件已改变，请重新导入')
+  return {file,manifest}
+}
+
+export async function analyzeAudio(file,signal) {
+  const {stderr}=await run(['-hide_banner','-i',file,'-map','0:a:0','-af','volumedetect','-f','null','-'],signal)
+  const duration=/Duration:\s*(\d+):(\d+):([\d.]+)/.exec(stderr)
+  if(!duration)throw new Error('无法读取音频时长')
+  const seconds=Number(duration[1])*3600+Number(duration[2])*60+Number(duration[3])
+  const peak=/max_volume:\s*(-?[\d.]+|-inf) dB/.exec(stderr)?.[1]
+  return {duration:seconds,samplePeakDb:peak==='-inf'?null:Number(peak),hasAudio:true,measurement:'sample peak; not true peak or LUFS',log:stderr}
+}
+
+export async function importAudioFile(drawioAbs,source,{name=basename(source),role='sfx',provenance={provider:'upload'},signal}={}) {
+  audioNodeData(role)
+  if(statSync(source).size>MAX_BYTES)throw new Error('音频源文件不能超过32MB')
+  const before=await analyzeAudio(source,signal)
+  if(before.duration<=0||before.duration>600)throw new Error('音频时长须在0–600秒内')
+  audioScopeDirectory(drawioAbs,mediaRootFor(drawioAbs),true)
+  const clip='audio-'+randomUUID(),{dir}=ensureClipPack(drawioAbs,clip,{kind:'raster'})
+  await run(['-hide_banner','-loglevel','error','-y','-i',source,'-map','0:a:0','-vn','-ac','2','-ar','48000','-c:a','pcm_s16le',join(dir,'audio.wav')],signal)
+  await run(['-hide_banner','-loglevel','error','-y','-i',join(dir,'audio.wav'),'-c:a','aac','-b:a','128k','-movflags','+faststart',join(dir,'preview.m4a')],signal)
+  const bytes=readFileSync(join(dir,'audio.wav'))
+  if(bytes.length>128*1024*1024)throw new Error('标准化音频过大')
+  const {log,...analysis}=await analyzeAudio(join(dir,'audio.wav'),signal)
+  const manifest={version:1,name:String(name).slice(0,240),sha256:sha(bytes),sourceSha256:sha(readFileSync(source)),...analysis,provenance,
+    changes:['Decoded to stereo 48kHz PCM for mixing'],createdAt:new Date().toISOString()}
+  writeFileSync(join(dir,'audio.json'),JSON.stringify(manifest,null,2))
+  return {clip,manifest,data:{...audioNodeData(role),audioClip:clip,audioName:manifest.name,audioDuration:String(manifest.duration),audioSha256:manifest.sha256}}
+}
+
+export function defaultAudioPlan(input,composition,assets) {
+  const fps=composition.fps,total=composition.durationFrames
+  const cues=input.refs.filter(ref=>ref.role==='audio').map(ref=>{
+    const data=ref.nodes.find(node=>node.data?.drawaiAudio==='1')?.data||{},settings=audioNodeSettings(data)
+    const duration=Number(assets[ref.id]?.[0]?.duration||data.audioDuration)
+    if(!duration)throw new Error('音频还未上传：'+ref.id)
+    const from=Math.round(settings.at*fps),end=settings.trimEnd||duration
+    const length=Math.min(total-from,settings.loop?total:Math.max(1,Math.floor((end-settings.trimStart)*fps)))
+    return {referenceId:ref.id,offsetFrames:from,durationFrames:length,trimStart:settings.trimStart,
+      gainDb:settings.gainDb,fadeIn:Math.min(settings.fadeIn,length/fps),fadeOut:Math.min(settings.fadeOut,length/fps),loop:settings.loop,action:'节点设置：'+settings.role}
+  })
+  return validateAudioTimeline({cues},composition,input)
+}
+
+export async function mixMotionAudio({input,composition,assets,publicDir,packDir,signal,plateSource}) {
+  const plan=validateAudioTimeline(composition.audio,composition,input),fps=composition.fps,seconds=composition.durationFrames/fps
+  const source=join(packDir,'source.mp4'),picture=join(packDir,'picture.mp4')
+  const logs=[]
+  if((plateSource||plan.cues.length)&&plateSource!==picture){
+    const result=await run(['-hide_banner','-y','-i',plateSource||source,'-map','0:v:0','-c:v','copy','-an',picture],signal)
+    logs.push(result.stderr)
+  }
+  if(!plan.cues.length){
+    if(plateSource)copyFileSync(picture,source)
+    mkdirSync(join(packDir,'project'),{recursive:true})
+    writeFileSync(join(packDir,'project','audio-plan.json'),JSON.stringify(plan,null,2))
+    return {status:'silent',listening:'not-performed',variants:{picture:plateSource?'picture.mp4':'source.mp4',full:'source.mp4'}}
+  }
+  const manifest=[]
+  const validateAsset=cue=>{
+    const asset=assets[cue.referenceId]?.[0]
+    if(asset?.kind!=='audio'||!/^asset-\d+\.wav$/.test(asset.src))throw new Error('音频快照不存在：'+cue.referenceId)
+    const root=realpathSync(publicDir),file=realpathSync(join(root,asset.src)),rel=relative(root,file)
+    if(isAbsolute(rel)||rel.startsWith('..'))throw new Error('音频快照超出工程')
+    if(sha(readFileSync(file))!==asset.sha256)throw new Error('音频快照哈希不一致')
+    return {asset,file}
+  }
+  async function mix(cues,filename){
+    if(!cues.length){copyFileSync(picture,join(packDir,filename));return}
+    const args=['-hide_banner','-y','-i',picture],filters=[],voices=cues.filter(cue=>cue.role==='voice')
+    cues.forEach((cue,index)=>{
+      const {asset,file}=validateAsset(cue),length=cue.durationFrames/fps,end=Number(asset.trimEnd||asset.duration)
+      if(cue.trimStart>=end||end>asset.duration+.011)throw new Error('音频裁切超出素材：'+cue.referenceId)
+      args.push('-i',file)
+      const chain=[`atrim=start=${cue.trimStart}:end=${end}`,'asetpts=PTS-STARTPTS']
+      if(cue.loop)chain.push(`aloop=loop=-1:size=${Math.max(1,Math.round((end-cue.trimStart)*48000))}`)
+      chain.push(`atrim=duration=${length}`,`volume=${Math.pow(10,cue.gainDb/20)}`)
+      if(cue.fadeIn)chain.push(`afade=t=in:st=0:d=${cue.fadeIn}`)
+      if(cue.fadeOut)chain.push(`afade=t=out:st=${Math.max(0,length-cue.fadeOut)}:d=${cue.fadeOut}`)
+      if(cue.role==='bgm'&&voices.length){
+        const windows=voices.map(voice=>`between(t,${(voice.from-cue.from)/fps},${(voice.from+voice.durationFrames-cue.from)/fps})`).join('+')
+        chain.push(`volume='if(gt(${windows},0),0.28,1)':eval=frame`)
+      }
+      chain.push(`apad=pad_dur=${length}`,`atrim=duration=${length}`,`adelay=${Math.round(cue.from/fps*48000)}S:all=1`)
+      filters.push(`[${index+1}:a]${chain.join(',')}[a${index}]`)
+      manifest.push({referenceId:cue.referenceId,sha256:asset.sha256,provenance:asset.provenance})
+    })
+    filters.push(cues.map((_,index)=>`[a${index}]`).join('')+`amix=inputs=${cues.length}:normalize=0,alimiter=limit=0.95:level=0:latency=1,apad,atrim=duration=${seconds}[mix]`)
+    const script=join(packDir,'project','mix-'+filename+'.txt');mkdirSync(dirname(script),{recursive:true});writeFileSync(script,filters.join(';\n'))
+    const temporary=join(packDir,filename+'.mixing.mp4')
+    try {
+    const result=await run([...args,'-filter_complex_script',script,'-map','0:v:0','-map','[mix]','-c:v','copy','-c:a','aac','-ar','48000','-b:a','192k','-t',String(seconds),'-movflags','+faststart',temporary],signal,180000)
+    logs.push(result.stderr);renameSync(temporary,join(packDir,filename))
+    } finally { if(existsSync(script))unlinkSync(script); if(existsSync(temporary))unlinkSync(temporary) }
+  }
+  await mix(plan.cues,'source.mp4')
+  if(plan.cues.some(cue=>cue.role==='bgm'))await mix(plan.cues.filter(cue=>cue.role!=='bgm'),'no-bgm.mp4')
+  const {log,...analysis}=await analyzeAudio(source,signal);logs.push(log)
+  writeFileSync(join(packDir,'project','audio-plan.json'),JSON.stringify(plan,null,2))
+  writeFileSync(join(packDir,'project','audio-manifest.json'),JSON.stringify([...new Map(manifest.map(item=>[item.referenceId,item])).values()],null,2))
+  return {status:'mixed',...analysis,listening:'not-performed',warnings:analysis.samplePeakDb===null||analysis.samplePeakDb<=-90?['成片音轨几乎静音，请试听检查']:[],
+    variants:{full:'source.mp4',picture:'picture.mp4',...(plan.cues.some(cue=>cue.role==='bgm')?{noBgm:'no-bgm.mp4'}:{})}}
+}
+
+// 两个音效入口共用 JS 下载器，避免 Python 分支的许可拦截与重复清单。
+export async function sourceFreesound(action,args,directory,signal) {
+  signal?.throwIfAborted()
+  if(action==='search') {
+    const found=await searchSfx({...args,signal})
+    return {provider:'freesound',query:found.query,results:found.results.map(row=>({...row,name:row.title,duration:row.seconds,license_label:row.licenseLabel}))}
+  }
+  const result=await getSfx(directory,[args.id],{persist:false,signal})
+  signal?.throwIfAborted()
+  return {...result,results:result.results.map(row=>row.ok?{...row,asset:{...row.asset,file:'assets/'+row.asset.file}}:row)}
+}

package/lib/audio-service.js

@@ -0,0 +1,66 @@
+/* 由 tools/build.mjs 生成 —— 请勿直接编辑；改 src/ 下的源文件。 */
+import { randomUUID } from 'node:crypto'
+import { mkdirSync, writeFileSync, appendFileSync, readFileSync, statSync, existsSync, rmSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { importAudioFile, frozenAudioFile, sourceFreesound, audioScopeDirectory } from './audio-media.js'
+import { audioNodeData } from './motion-core.js'
+import { clipDirFor } from './media.js'
+
+export function createAudioService() {
+  const uploads=new Map()
+  const cache=scope=>audioScopeDirectory(scope.drawioAbs,join(dirname(scope.drawioAbs),'.drawai-cache','audio'),true)
+  const owner=(scope,token)=>{
+    const job=uploads.get(token)
+    if(!job||job.sessionId!==scope.sessionId||job.drawioAbs!==scope.drawioAbs)throw new Error('音频上传令牌不属于当前画布或会话')
+    return job
+  }
+  return {
+    async search(scope,args,signal){return sourceFreesound('search',args,join(cache(scope),'search'),signal)},
+    async get(scope,args,signal){
+      const directory=join(cache(scope),'freesound-'+randomUUID())
+      try{
+        const result=await sourceFreesound('get',args,directory,signal)
+        const row=result.results?.find(item=>item.ok)?.asset
+        if(!row||!/^assets\/sfx\/fs-\d+\.mp3$/.test(row.file))throw new Error('未下载到可用音效')
+        return await importAudioFile(scope.drawioAbs,join(directory,row.file),{name:row.name||row.title||row.file,role:'sfx',provenance:row,signal})
+      }finally{rmSync(audioScopeDirectory(scope.drawioAbs,directory),{recursive:true,force:true})}
+    },
+    start(scope,args){
+      for(const [token,job]of uploads)if(!job.finishing&&Date.now()-job.time>3600000){rmSync(audioScopeDirectory(job.drawioAbs,job.directory),{recursive:true,force:true});uploads.delete(token)}
+      audioNodeData(args.role||'sfx')
+      if(uploads.size>=16)throw new Error('音频上传任务已满')
+      if(!Number.isInteger(args.size)||args.size<1||args.size>32*1024*1024||!['mp3','wav','m4a','aac','ogg','flac','webm'].includes(args.extension))throw new Error('请选择32MB以内的音频文件')
+      const token=randomUUID(),directory=join(cache(scope),'upload-'+token),file=join(directory,'source.'+args.extension)
+      mkdirSync(directory,{recursive:true});writeFileSync(file,'')
+      uploads.set(token,{...scope,directory,file,size:args.size,received:0,name:String(args.name||'音频').slice(0,240),role:args.role||'sfx',time:Date.now()})
+      return {token}
+    },
+    chunk(scope,args){
+      const job=owner(scope,args.token)
+      if(job.finished||job.finishing||args.offset!==job.received||typeof args.base64!=='string'||args.base64.length>1400000||/[^A-Za-z0-9+/=]/.test(args.base64))throw new Error('音频分块顺序或格式无效')
+      const bytes=Buffer.from(args.base64,'base64')
+      if(bytes.toString('base64')!==args.base64)throw new Error('音频分块编码无效')
+      if(bytes.length<1||bytes.length>1024*1024||job.received+bytes.length>job.size)throw new Error('音频分块超出范围')
+      audioScopeDirectory(scope.drawioAbs,job.file)
+      appendFileSync(job.file,bytes);job.received+=bytes.length;job.time=Date.now()
+      return {received:job.received}
+    },
+    async finish(scope,args,signal){
+      const job=owner(scope,args.token)
+      if(job.finished)return job.result
+      if(job.received!==job.size)throw new Error('音频尚未上传完整')
+      if(job.finishing)throw new Error('音频正在处理')
+      job.finishing=true
+      try{job.result=await importAudioFile(scope.drawioAbs,job.file,{name:job.name,role:job.role,signal});job.finished=true;return job.result}
+      finally{job.finishing=false}
+    },
+    release(scope,args){const job=owner(scope,args.token);if(job.finishing)throw new Error('音频仍在处理');rmSync(audioScopeDirectory(scope.drawioAbs,job.directory),{recursive:true,force:true});uploads.delete(args.token);return {}},
+    read(scope,clip){
+      const {manifest}=frozenAudioFile(scope.drawioAbs,clip),file=join(clipDirFor(scope.drawioAbs,clip),'preview.m4a')
+      audioScopeDirectory(scope.drawioAbs,file)
+      if(statSync(file).size>16*1024*1024)throw new Error('音频预览过大')
+      return {manifest,mime:'audio/mp4',base64:readFileSync(file).toString('base64')}
+    },
+    leases(scope){return [...uploads.values()].filter(job=>job.drawioAbs===scope.drawioAbs&&job.result).map(job=>job.result.clip)},
+  }
+}

package/lib/canvas-format.js

@@ -0,0 +1,134 @@
+/* 由 tools/build.mjs 生成 —— 请勿直接编辑；改 src/ 下的源文件。 */
+/** Native JSON document codec. XML is retained only as a compatibility capsule. */
+import { randomUUID } from 'node:crypto'
+import { existsSync, lstatSync, readdirSync, mkdirSync, copyFileSync, readFileSync, writeFileSync, renameSync, constants } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { mediaRootFor } from './media.js'
+import { parseMxfile, applyDocToMxfile, buildMxfile, contentHash } from './mxfile.js'
+import { cloneDocument, normalizeDocument } from './document-core.js'
+
+export const CANVAS_SCHEMA_VERSION = 1
+export const isCanvasPath = (path) => typeof path === 'string' && /\.(drawai|drawio)$/i.test(path)
+export const isNativeCanvasPath = (path) => typeof path === 'string' && /\.drawai$/i.test(path)
+export const nativeCanvasPath = (path) => path.replace(/\.drawio$/i, '.drawai')
+const nativeText = (text) => String(text).trimStart().startsWith('{')
+
+function decode(text) {
+  const project = JSON.parse(text)
+  if (project.format !== 'dsh-drawai' || project.schemaVersion !== CANVAS_SCHEMA_VERSION) throw new Error('不支持的 DrawAI 文档版本')
+  if (typeof project.id !== 'string' || !Array.isArray(project.pages) || !project.pages.length) throw new Error('DrawAI 文档缺少项目或页面')
+  const ids = new Set()
+  for (const page of project.pages) {
+    if (!page || typeof page.id !== 'string' || ids.has(page.id) || !Array.isArray(page.doc?.nodes) || !Array.isArray(page.doc?.edges)) throw new Error('DrawAI 页面结构或身份无效')
+    ids.add(page.id)
+  }
+  return project
+}
+
+function encode(project) { return JSON.stringify(project, null, 2) + '\n' }
+function stored(doc) { const copy = cloneDocument(doc); delete copy.revision; return copy }
+
+export function migrateMxfile(text, sourcePath = '') {
+  const first = parseMxfile(text)
+  const project = { format: 'dsh-drawai', schemaVersion: CANVAS_SCHEMA_VERSION, id: randomUUID(), pages: [],
+    compat: { drawio: text }, migration: { sourcePath, sourceHash: contentHash(text) } }
+  for (let i = 0; i < first.pageCount; i++) {
+    const page = parseMxfile(text, { page: i })
+    project.pages.push({ id: page.pageId || 'page-' + i, name: page.pageNames[i], doc: stored(page.doc), notes: page.notes })
+  }
+  const result = encode(project)
+  decode(result)
+  return result
+}
+
+export function parseCanvas(text, options = {}) {
+  if (!nativeText(text)) return parseMxfile(text, options)
+  const project = decode(text)
+  const index = Math.max(0, Math.min(project.pages.length - 1, Math.floor(Number(options.page) || 0)))
+  const page = project.pages[index]
+  const doc = normalizeDocument(page.doc)
+  doc.revision = contentHash(text)
+  doc.meta = { ...doc.meta, pageIndex: index, pageCount: project.pages.length, pageNames: project.pages.map((item) => item.name) }
+  return { doc, notes: page.notes || [], pageCount: project.pages.length, pageIndex: index,
+    pageNames: project.pages.map((item) => item.name), pageId: page.id, pageIds: project.pages.map((item) => item.id) }
+}
+
+export function applyCanvas(text, doc, options = {}) {
+  if (!nativeText(text)) return applyDocToMxfile(text, doc, options)
+  const project = decode(text)
+  const index = options.page === undefined ? 0 : Number(options.page)
+  if (!Number.isInteger(index) || !project.pages[index]) throw new Error('页面不存在')
+  project.pages[index].doc = stored(normalizeDocument(doc))
+  return { text: encode(project), dropped: [] }
+}
+
+export function buildCanvas(doc, options = {}) {
+  if (options.format !== 'drawai') return buildMxfile(doc, options)
+  return { text: encode({ format: 'dsh-drawai', schemaVersion: CANVAS_SCHEMA_VERSION, id: randomUUID(),
+    pages: [{ id: randomUUID(), name: options.name || '第 1 页', doc: stored(normalizeDocument(doc)) }] }), dropped: [] }
+}
+
+export function exportCanvasToMxfile(text) {
+  if (!nativeText(text)) return text
+  const project = decode(text)
+  if (!project.compat?.drawio) {
+    if (project.pages.length !== 1) throw new Error('缺少多页 drawio 兼容模板')
+    return buildMxfile(project.pages[0].doc, { name: project.pages[0].name }).text
+  }
+  let xml = project.compat.drawio
+  for (let page = 0; page < project.pages.length; page++) xml = applyDocToMxfile(xml, project.pages[page].doc, { page }).text
+  return xml
+}
+
+export function forkNativeCanvas(text) {
+  const project = decode(text)
+  project.id = randomUUID()
+  delete project.migration
+  return encode(project)
+}
+
+/** Runs through the host filesystem service, preserving its workspace/policy checks. */
+export async function migrateCanvasFile({ fs, source, destination, sourcePath, destinationPath, policy }) {
+  const original = await fs.readText(source)
+  if (await fs.stat(destination)) {
+    const existing = await fs.readText(destination)
+    const project = decode(existing)
+    if (project.migration?.sourcePath !== sourcePath || project.migration.sourceHash !== contentHash(original)) throw new Error('迁移目标已存在或旧画布已更改；请先处理两个版本')
+    return { text: existing, reused: true }
+  }
+  const text = migrateMxfile(original, sourcePath)
+  if (destinationPath) copyMigrationMedia(sourcePath, destinationPath, contentHash(original))
+  if (await fs.readText(source) !== original) throw new Error('迁移期间源画布已更改，请重新打开')
+  if (await fs.stat(destination)) throw new Error('迁移目标已存在')
+  await fs.writeText(destination, text, undefined, undefined, policy)
+  return { text, reused: false }
+}
+
+// Never share mutable media with the retained original. Publish the complete copy
+// by directory rename; an unrelated existing destination is never overwritten.
+function copyMigrationMedia(source, destination, sourceHash) {
+  const from = mediaRootFor(source), to = mediaRootFor(destination)
+  if (!existsSync(from)) return
+  const marker = '.drawai-migration.json'
+  if (existsSync(to)) {
+    if (lstatSync(to).isSymbolicLink()) throw new Error('迁移媒体目录不能为符号链接')
+    const saved = JSON.parse(readFileSync(join(to, marker), 'utf8'))
+    if (saved.source !== source || saved.sourceHash !== sourceHash) throw new Error('迁移媒体目录已存在')
+    return
+  }
+  const temporary = join(dirname(to), '.drawai-migration-' + randomUUID())
+  function copyDirectory(input, output) {
+    if (lstatSync(input).isSymbolicLink()) throw new Error('迁移媒体不支持符号链接')
+    mkdirSync(output)
+    for (const entry of readdirSync(input, { withFileTypes: true })) {
+      const src = join(input, entry.name), dst = join(output, entry.name)
+      if (entry.isSymbolicLink()) throw new Error('迁移媒体不支持符号链接')
+      if (entry.isDirectory()) copyDirectory(src, dst)
+      else copyFileSync(src, dst, constants.COPYFILE_EXCL)
+    }
+  }
+  copyDirectory(from, temporary)
+  writeFileSync(join(temporary, marker), JSON.stringify({ source, sourceHash }), { flag: 'wx' })
+  if (existsSync(to)) throw new Error('迁移媒体目录已存在')
+  renameSync(temporary, to)
+}