@ninkch/dsh-infinite-canvas 0.18.6 → 0.19.0

package/index.js

@@ -276,12 +276,16 @@ function ensureSchema(db, root) {
   }
 }
 
-/** 项目文档摘要（列表页用，避免每次列表都解析全量 doc）。 */
+/** 项目文档摘要（列表页用，避免每次列表都解析全量 doc）。类型按合并类型输出。 */
 function docSummary(d) {
   const nodes = Object.values(d.nodes || {}).map((n) => ({
-    id: n.id, type: n.type, label: (n.data && n.data.label) || '', status: (n.data && n.data.status) || 'idle',
+    id: n.id, type: normalizeNodeType(n.type), label: (n.data && n.data.label) || '', status: (n.data && n.data.status) || 'idle',
   }));
-  return { nodeIds: Object.keys(d.nodes || {}), nodes, source: d.source || 'app' };
+  return {
+    nodeIds: Object.keys(d.nodes || {}), nodes, source: d.source || 'app', canvases: canvasRegistry(d),
+    // 默认画布名（缺省 '默认画布'，旧项目零迁移）与"默认画布已删除"标记（只剩子画布时）
+    defaultCanvasName: defaultCanvasNameForApi(d), defaultCanvasDeleted: !defaultCanvasExists(d),
+  };
 }
 
 /** v1 → v2 一次性迁移：文档按 updatedAt 新者胜合并；资产索引照抄（媒体文件原地保留，rel 指针不动——零风险迁移）。 */
@@ -747,6 +751,9 @@ function sqlDeleteProjectRows(db, id, root) {
   try {
     db.prepare('DELETE FROM assets WHERE project_id = ?').run(id);
     db.prepare('DELETE FROM projects WHERE id = ?').run(id);
+    // 多画布：项目下的子画布行随项目一起清掉（否则删项目后画布文档残留成孤行）
+    const canvasPattern = String(id).replace(/[\\%_]/g, '\\$&') + CANVAS_ID_SEP + '%';
+    db.prepare("DELETE FROM projects WHERE id LIKE ? ESCAPE '\\'").run(canvasPattern);
   } catch (e) { result.errors.push('delete rows: ' + String((e && e.message) || e)); }
   if (root) {
     const seen = new Set();
@@ -768,6 +775,24 @@ function sqlDeleteProjectRows(db, id, root) {
   if (result.errors.length) result.ok = false;
   return result;
 }
+/** 子画布文档镜像：数据目录 projects/<项目名文件夹>/canvases/<canvasId>.json。
+ *  子画布共用项目文件夹（资产/设定集按项目维度）；失败不影响主存储。 */
+function mirrorCanvasDocToDataRoot(projectId, canvasId, doc) {
+  const root = dataRoot();
+  if (!root) return;
+  const projectDoc = readDocOrNull(projectId) || {};
+  let folder = null;
+  try { folder = ensureProjectFolder(projectId, projectDoc.name || projectId); } catch { return; }
+  if (!folder) return;
+  try {
+    const dir = path.join(root, 'projects', folder, 'canvases');
+    mkdirSync(dir, { recursive: true });
+    const f = path.join(dir, String(canvasId) + '.json');
+    const tmp = f + '.' + process.pid + '.tmp';
+    writeFileSync(tmp, JSON.stringify(doc, null, 1), 'utf8');
+    renameSync(tmp, f);
+  } catch { /* 镜像失败不影响主存储 */ }
+}
 /** 一次性迁移/对齐数据目录布局：旧 pid 文件夹 → 项目名文件夹，并镜像全部项目文档。 */
 function dataRootMigrate() {
   const root = dataRoot();
@@ -775,7 +800,7 @@ function dataRootMigrate() {
   let ids = [];
   try {
     ids = existsSync(PROJECTS_DIR)
-      ? readdirSync(PROJECTS_DIR).filter((f) => f.endsWith('.json')).map((f) => f.replace(/\.json$/, ''))
+      ? readdirSync(PROJECTS_DIR).filter((f) => f.endsWith('.json')).map((f) => f.replace(/\.json$/, '')).filter((id) => !isCanvasDocId(id))
       : [];
   } catch { ids = []; }
   let filesMoved = 0;
@@ -837,6 +862,7 @@ function dataRootImport() {
     ? readdirSync(projectsDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name)
     : [];
   const imported = [];
+  const importedCanvases = [];
   const assets = {};
   for (const folder of dirs) {
     const dir = path.join(projectsDir, folder);
@@ -856,8 +882,26 @@ function dataRootImport() {
       const list = JSON.parse(readFileSync(path.join(dir, 'assets.json'), 'utf8'));
       if (Array.isArray(list)) assets[id] = list;
     } catch { /* 无资产索引 */ }
+    // 多画布：画布文档镜像在 projects/<项目文件夹>/canvases/*.json（updatedAt 新者胜）
+    try {
+      const cvDir = path.join(dir, 'canvases');
+      for (const f of readdirSync(cvDir)) {
+        if (!f.endsWith('.json')) continue;
+        let cdoc = null;
+        try { cdoc = JSON.parse(readFileSync(path.join(cvDir, f), 'utf8')); } catch { continue; }
+        const cid = normalizeCanvasId(cdoc && cdoc.canvasId);
+        if (!cid) continue;
+        const target = canvasDocId(id, cid);
+        let curC = null;
+        try { curC = JSON.parse(readFileSync(projectFile(target), 'utf8')); } catch { /* 本机没有该画布 */ }
+        if (!curC || (curC.updatedAt || 0) < (cdoc.updatedAt || 0)) {
+          writeIcDoc(target, { ...cdoc, id: target, projectId: id, canvasId: cid, updatedAt: Date.now() });
+          importedCanvases.push({ id, canvasId: cid, name: String(cdoc.name || cid) });
+        }
+      }
+    } catch { /* 无画布镜像 */ }
   }
-  return { ok: true, imported, assets };
+  return { ok: true, imported, canvases: importedCanvases, assets };
 }
 /** 设定集字段规范化（世界观/风格 + 角色/场景/道具条目，条目可携带链接资产 assetIds）。 */
 function normalizeBible(raw) {
@@ -922,6 +966,9 @@ const MIME_BY_EXT = {
   webm: 'video/webm', mp4: 'video/mp4', mov: 'video/quicktime', mkv: 'video/x-matroska',
   wav: 'audio/wav', mp3: 'audio/mpeg', m4a: 'audio/mp4', ogg: 'audio/ogg',
   json: 'application/json', srt: 'text/plain; charset=utf-8', txt: 'text/plain; charset=utf-8',
+  // js/mjs：浏览器动态 import() 只认 text/javascript —— 导演台引擎模块（assets/director/engine.js）
+  // 走 plugin-asset 路由加载，没有这个 MIME 会被浏览器拒载（"Failed to fetch dynamically imported module"）
+  js: 'text/javascript; charset=utf-8', mjs: 'text/javascript; charset=utf-8',
 };
 function mimeOf(p) {
   const m = /\.([a-z0-9]+)$/i.exec(p);
@@ -977,13 +1024,76 @@ function pickFolderDialog() {
 // 客户端是内容权威（编辑后推送全量文档）；Agent 经工具在 Host 侧追加节点；客户端轮询合并。
 const PROJECTS_DIR = process.env.DSH_IC_PROJECTS_DIR || path.join(os.homedir(), '.dsh', 'infinite-canvas', 'projects');
 function projectFile(id) {
-  if (!/^[A-Za-z0-9_-]{1,64}$/.test(String(id || ''))) throw new Error('非法项目 id');
-  return path.join(PROJECTS_DIR, String(id) + '.json');
+  const s = String(id || '');
+  const seg = isCanvasDocId(s) ? splitCanvasDocId(s) : { projectId: s, canvasId: null };
+  const okProject = /^[A-Za-z0-9_-]{1,96}$/.test(seg.projectId || '');
+  const okCanvas = seg.canvasId === null || /^[A-Za-z0-9_-]{1,64}$/.test(seg.canvasId || '');
+  if (!okProject || !okCanvas) throw new Error('非法项目 id');
+  return path.join(PROJECTS_DIR, s + '.json');
+}
+// ---------- 多画布（项目下子目录 = 独立画布文档）----------
+// 默认画布：canvasId = null，文档 id 仍是 projectId（旧数据零迁移）。
+// 子画布：文档 id = `${projectId}__cv__${canvasId}`，项目文档里登记 canvases: [{id,name,createdAt}]；
+// 资产/设定集仍以 projectId 为维度共享，不随画布分割。
+const CANVAS_ID_SEP = '__cv__';
+function canvasDocId(projectId, canvasId) {
+  const cid = normalizeCanvasId(canvasId);
+  return cid ? (String(projectId) + CANVAS_ID_SEP + cid) : String(projectId);
+}
+function isCanvasDocId(docId) { return String(docId || '').includes(CANVAS_ID_SEP); }
+function splitCanvasDocId(docId) {
+  const s = String(docId || '');
+  const i = s.indexOf(CANVAS_ID_SEP);
+  if (i < 0) return { projectId: s, canvasId: null };
+  return { projectId: s.slice(0, i), canvasId: s.slice(i + CANVAS_ID_SEP.length) || null };
+}
+function normalizeCanvasId(v) {
+  const s = String(v == null ? '' : v).trim();
+  if (!s) return null;
+  if (!/^[A-Za-z0-9_-]{1,64}$/.test(s)) throw new Error('非法画布 id: ' + s);
+  return s;
+}
+function canvasRegistry(projectDoc) {
+  return Array.isArray(projectDoc && projectDoc.canvases)
+    ? projectDoc.canvases.filter((c) => c && c.id).map((c) => ({ id: String(c.id), name: String(c.name || '').slice(0, 80), createdAt: Number(c.createdAt) || 0 }))
+    : [];
+}
+/** 规范化画布清单（Host 侧唯一写入口）：丢弃非法 id、同名去重、最多 200 个画布。 */
+function sanitizeCanvases(list) {
+  const out = [];
+  const seen = new Set();
+  for (const raw of (Array.isArray(list) ? list : [])) {
+    let cid;
+    try { cid = normalizeCanvasId(raw && raw.id); } catch { continue; }
+    if (!cid || seen.has(cid)) continue;
+    seen.add(cid);
+    out.push({ id: cid, name: String((raw && raw.name) || cid).slice(0, 80), createdAt: Number(raw && raw.createdAt) || Date.now() });
+  }
+  return out.slice(0, 200);
+}
+// ---- 默认画布（canvasId=null）：名字存项目文档 defaultCanvasName；删除后 defaultCanvasDeleted=true ----
+const DEFAULT_CANVAS_NAME = '默认画布';
+/** 默认画布名：缺省 '默认画布'（旧项目无该字段 → 零迁移）。 */
+function defaultCanvasNameOf(doc) {
+  const n = String((doc && doc.defaultCanvasName) || '').trim();
+  return (n || DEFAULT_CANVAS_NAME).slice(0, 80);
+}
+/** 默认画布是否还存在（尚未删除）。 */
+function defaultCanvasExists(doc) { return !(doc && doc.defaultCanvasDeleted === true); }
+/** API 返回的默认画布名：默认画布已删除 → 空字符串（storage 里已清空）。 */
+function defaultCanvasNameForApi(doc) { return defaultCanvasExists(doc) ? defaultCanvasNameOf(doc) : ''; }
+/** 项目画布总数 = 默认画布（若还在）+ 子画布。 */
+function canvasTotal(projectDoc) { return canvasRegistry(projectDoc).length + (defaultCanvasExists(projectDoc) ? 1 : 0); }
+/** 项目下全部画布名（默认画布 + 子画布）：重名判定用。 */
+function allCanvasNames(projectDoc) {
+  const names = defaultCanvasExists(projectDoc) ? [defaultCanvasNameOf(projectDoc)] : [];
+  return names.concat(canvasRegistry(projectDoc).map((c) => c.name));
 }
 function projectsList() {
   if (sqlActive()) {
     const db = getDb();
-    const rows = db.prepare('SELECT id, name, created_at, updated_at, bible_updated_at, summary, tombstones FROM projects ORDER BY updated_at DESC').all();
+    const rows = db.prepare('SELECT id, name, created_at, updated_at, bible_updated_at, summary, tombstones FROM projects ORDER BY updated_at DESC').all()
+      .filter((r) => !isCanvasDocId(r.id)); // 子画布行不是项目：不出现在项目列表（画布清单在项目文档里）
     return rows.map((r) => {
       let sum = {};
       try { sum = JSON.parse(r.summary || '{}'); } catch { /* 旧行/损坏摘要 */ }
@@ -991,8 +1101,13 @@ function projectsList() {
       try { tombs = JSON.parse(r.tombstones || '[]'); } catch { /* 旧行 */ }
       return {
         id: r.id, name: r.name, createdAt: r.created_at || 0, updatedAt: r.updated_at || 0,
-        source: sum.source || 'app', nodeIds: sum.nodeIds || [], nodes: sum.nodes || [],
+        source: sum.source || 'app', nodeIds: sum.nodeIds || [],
+        // 旧版本摘要里可能是旧类型名：输出时按合并类型归一（image / video）
+        nodes: (sum.nodes || []).map((n) => ({ ...n, type: normalizeNodeType(n && n.type) })),
         tombstones: Array.isArray(tombs) ? tombs : [], bibleUpdatedAt: r.bible_updated_at || 0,
+        canvases: canvasRegistry(sum),
+        defaultCanvasName: defaultCanvasNameForApi(sum),
+        defaultCanvasDeleted: !defaultCanvasExists(sum),
       };
     });
   }
@@ -1001,6 +1116,7 @@ function projectsList() {
   const list = [];
   for (const f of files) {
     const id = f.slice(0, -5);
+    if (isCanvasDocId(id)) continue; // 子画布文档不是项目（由所属项目的 canvases 清单表达）
     try {
       let d;
       try {
@@ -1011,10 +1127,10 @@ function projectsList() {
         continue;
       }
       const nodes = Object.values(d.nodes || {}).map((n) => ({
-        id: n.id, type: n.type, label: (n.data && n.data.label) || '',
+        id: n.id, type: normalizeNodeType(n.type), label: (n.data && n.data.label) || '',
         status: (n.data && n.data.status) || 'idle',
       }));
-      list.push({ id: d.id || id, name: d.name || id, createdAt: d.createdAt || 0, updatedAt: d.updatedAt || 0, source: d.source || 'app', nodeIds: Object.keys(d.nodes || {}), nodes, tombstones: d.tombstones || [], bibleUpdatedAt: d.bibleUpdatedAt || 0 });
+      list.push({ id: d.id || id, name: d.name || id, createdAt: d.createdAt || 0, updatedAt: d.updatedAt || 0, source: d.source || 'app', nodeIds: Object.keys(d.nodes || {}), nodes, tombstones: d.tombstones || [], bibleUpdatedAt: d.bibleUpdatedAt || 0, canvases: canvasRegistry(d), defaultCanvasName: defaultCanvasNameForApi(d), defaultCanvasDeleted: !defaultCanvasExists(d) });
     } catch { /* 单文件损坏跳过 */ }
   }
   return list.sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
@@ -1024,9 +1140,13 @@ async function projectsPut(args) {
   // 项目删除墓碑（长效）：删除后迟到的全量推送（450ms 防抖竞速 / 启动 pushAllProjectsToHost 快照）
   // 一律拒收——否则项目原地复活（资产/设定集已清，复活即残废）。客户端不会复用项目 id，拒收永不误伤。
   if (deletedProjectIds().includes(id)) return { ok: true, id, deleted: true };
-  const f = projectFile(id);
+  // 多画布：canvasId 缺省 = 项目默认画布（文档 id 仍是 projectId，旧数据零迁移）；
+  // 子画布写到独立文档 id，项目文档只保留名称/设定集/画布清单/默认画布图。
+  const canvasId = normalizeCanvasId(args && args.canvasId);
+  const targetId = canvasId ? canvasDocId(id, canvasId) : id;
+  projectFile(targetId); // 非法 id 早失败（画布文档 id 走同一套校验）
   const doc = (args && args.doc) || {};
-  let prev = readDocOrNull(id) || {};
+  let prev = readDocOrNull(targetId) || {};
   // 墓碑：对话删除的节点 + 客户端本地删除的节点（客户端删除时也会写入 tombstones）。
   // tombstoneAt 记录每个墓碑的创建时刻：只有**推送时间戳（doc.ts）不早于墓碑时刻**的推送
   // 才被认定为"撤销恢复"允许清墓碑；陈旧推送（快照早于删除、无 ts 或 ts 更老）不得借
@@ -1112,8 +1232,7 @@ async function projectsPut(args) {
   const keptEdgeTomb = edgeTombstones.slice(-400);
   const pruneStamp = (m, keep) => { const o = {}; for (const k of keep) { if (m[k] !== undefined) o[k] = m[k]; } return o; };
   const out = {
-    id,
-    name: String((args && args.name) || prev.name || id).slice(0, 80),
+    id: targetId,
     createdAt: prev.createdAt || (doc && doc.createdAt) || Date.now(),
     updatedAt: Date.now(),
     source: prev.source || 'app',
@@ -1125,8 +1244,27 @@ async function projectsPut(args) {
     tombstoneAt: pruneStamp(tombstoneAt, keptTomb),
     edgeTombstoneAt: pruneStamp(edgeTombstoneAt, keptEdgeTomb),
   };
+  if (canvasId) {
+    out.projectId = id;
+    out.canvasId = canvasId; // 子画布文档：不带 name/canvases/bible（项目级字段只在项目文档）
+  } else {
+    out.name = String((args && args.name) || prev.name || id).slice(0, 80);
+    out.canvases = sanitizeCanvases((args && args.canvases) !== undefined ? args.canvases : prev.canvases);
+    // 默认画布的项目级字段：名字（缺省 '默认画布'，不写字段即零迁移）与"已删除"标记
+    const dnRaw = (args && args.defaultCanvasName !== undefined) ? args.defaultCanvasName : prev.defaultCanvasName;
+    if (dnRaw !== undefined && dnRaw !== null && String(dnRaw).trim()) out.defaultCanvasName = String(dnRaw).trim().slice(0, 80);
+    const ddRaw = (args && args.defaultCanvasDeleted !== undefined) ? args.defaultCanvasDeleted : prev.defaultCanvasDeleted;
+    if (ddRaw) out.defaultCanvasDeleted = true;
+    else if (prev.defaultCanvasDeleted) out.defaultCanvasDeleted = true; // 客户端未带该字段时保留"已删除"（防旧推送把默认画布复活）
+  }
   // 设定集随文档一起同步（世界观/风格/角色/场景/道具）：对话侧可读写
-  if (doc.bible !== undefined) {
+  let canvasBible = null;
+  if (canvasId) {
+    // 设定集是项目级：子画布推送里携带的 bible 落到项目文档（画布文档不存 bible）
+    const projectDoc = readDocOrNull(id) || {};
+    if (doc.bible !== undefined) canvasBible = { bible: normalizeBible(doc.bible), bibleUpdatedAt: Date.now() };
+    else if (projectDoc.bible !== undefined) canvasBible = { bible: projectDoc.bible, bibleUpdatedAt: projectDoc.bibleUpdatedAt || 0 };
+  } else if (doc.bible !== undefined) {
     out.bible = normalizeBible(doc.bible);
     out.bibleUpdatedAt = Date.now();
   } else if (prev.bible !== undefined) {
@@ -1134,23 +1272,47 @@ async function projectsPut(args) {
     out.bibleUpdatedAt = prev.bibleUpdatedAt || 0;
   }
   // 设定集有更新时重算全部分镜表的一致性告警（客户端侧设定集编辑也走这条路径）
-  if (out.bible !== undefined) {
+  const bibleForWarn = canvasId ? (canvasBible && canvasBible.bible) : out.bible;
+  if (bibleForWarn !== undefined) {
     try {
       const assetNames = readAssetIndexNames(id);
       for (const nd of Object.values(merged)) {
         if (nd && nd.type === 'storyboard' && Array.isArray(nd.data && nd.data.shots) && nd.data.shots.length) {
-          const nextW = storyboardConsistencyWarnings(out.bible, nd.data.shots, assetNames);
+          const nextW = storyboardConsistencyWarnings(bibleForWarn, nd.data.shots, assetNames);
           if (JSON.stringify(nextW) !== JSON.stringify(nd.data.warnings || [])) nd.data.warnings = nextW;
         }
       }
     } catch { /* 重算失败不影响保存 */ }
   }
   mkdirSync(PROJECTS_DIR, { recursive: true });
-  writeIcDoc(id, out); // 统一走原子写 + 数据目录镜像（此前直写绕过了镜像与原子性）
-  return { ok: true, id, updatedAt: out.updatedAt };
+  writeIcDoc(targetId, out); // 统一走原子写 + 数据目录镜像（此前直写绕过了镜像与原子性）
+  if (canvasId) {
+    // 项目级字段（名称/设定集/画布清单）始终只写项目文档：项目文档缺失时补一份最小项目
+    const projectDoc = readDocOrNull(id);
+    if (!projectDoc) {
+      const canvases = sanitizeCanvases((args && args.canvases) || []);
+      if (!canvases.some((c) => c.id === canvasId)) canvases.push({ id: canvasId, name: canvasId, createdAt: Date.now() });
+      writeIcDoc(id, {
+        id, name: String((args && args.name) || id).slice(0, 80), createdAt: Date.now(), updatedAt: Date.now(),
+        nodes: {}, edges: [], view: { x: 60, y: 40, scale: 1 }, tombstones: [], canvases,
+        defaultCanvasName: defaultCanvasNameOf({ defaultCanvasName: args && args.defaultCanvasName }),
+        ...(canvasBible ? { bible: canvasBible.bible, bibleUpdatedAt: canvasBible.bibleUpdatedAt } : {}),
+      });
+    } else {
+      const patch = {};
+      if (canvasBible) { patch.bible = canvasBible.bible; patch.bibleUpdatedAt = canvasBible.bibleUpdatedAt; }
+      if (args && args.canvases !== undefined) patch.canvases = sanitizeCanvases(args.canvases);
+      if (Object.keys(patch).length) patchProjectDoc(id, patch);
+    }
+  }
+  return { ok: true, id, ...(canvasId ? { canvasId } : {}), updatedAt: out.updatedAt };
 }
 async function projectsGet(args) {
-  return readDoc(String((args && args.id) || ''));
+  const id = String((args && args.id) || '');
+  const canvasId = normalizeCanvasId(args && args.canvasId);
+  if (!canvasId) return readDoc(id);
+  // 默认画布/子画布同一入口：子画布返回独立文档 + 项目级字段（名称/设定集/画布清单）
+  return readCanvasDoc(id, canvasId);
 }
 /** 长效项目删除墓碑（区别于 projectsSync 的一次性 deletedProjects 通知信号）：
  *  删除后任何迟到的 projectsPut 都被拒收，直到 dataRootImport 显式恢复该 id。 */
@@ -1244,6 +1406,7 @@ async function projectsDelete(args) {
     cleanup = sqlDeleteProjectRows(getDb(), id, dataRoot());
   } else {
     try { unlinkSync(projectFile(id)); } catch { /* 已不存在视为成功 */ }
+    try { deleteCanvasDocsForProject(id); } catch { /* 子画布清理失败不影响删除 */ }
     try { removeDataRootProject(id); } catch { /* 数据目录镜像清理失败不影响删除 */ }
   }
   try { addDeletedProjectId(id); } catch { /* 墓碑写失败不影响删除 */ }
@@ -1267,6 +1430,100 @@ function defaultLabel(text) {
   const line = String(text || '').trim().split(/\r?\n/)[0] || '';
   return line.length > 18 ? line.slice(0, 18) + '…' : (line || '未命名');
 }
+/** 旧节点类型 → 合并类型（与客户端 client.js 同一映射）：
+ *  image-gen / image-asset → image，video-gen / video-asset → video。
+ *  旧项目文档读入时统一归一（只改 type，节点 data / 连线端点原样保留：有 assetId 就是资产，有 prompt 就是提示词）。 */
+const LEGACY_NODE_TYPES = { 'image-gen': 'image', 'image-asset': 'image', 'video-gen': 'video', 'video-asset': 'video' };
+function normalizeNodeType(type) { return LEGACY_NODE_TYPES[type] || type; }
+function normalizeNode(n) {
+  if (n && typeof n === 'object') {
+    const t = normalizeNodeType(n.type);
+    if (t !== n.type) n.type = t;
+  }
+  return n;
+}
+function normalizeDocNodes(doc) {
+  if (!doc || typeof doc !== 'object') return doc;
+  for (const n of Object.values(doc.nodes || {})) {
+    normalizeNode(n);
+    normalizeMediaNodeSize(n); // 与客户端同一几何规则：媒体节点外框 = 预览区 + 标题栏 +（有结果时）操作栏
+  }
+  return doc;
+}
+const MERGED_NODE_TYPES = ['image', 'video'];
+// ---- 媒体节点几何（必须与 client.js 的 NODE_HDR_H / NODE_FOOT_H / MEDIA_PREVIEW_SHORT / MEDIA_MAX_LONG 一致）----
+// 媒体节点三段：标题栏（固定）+ 预览区（盒比 = 画面比例，短边 360、长边 ≤800）+ 操作栏（固定，有结果才有）。
+const NODE_HDR_H = 32;
+const NODE_FOOT_H = 32;
+const MEDIA_PREVIEW_SHORT = 360;
+const MEDIA_MAX_LONG = 800;
+const RATIOS = ['16:9', '9:16', '1:1', '4:3', '3:4', '21:9'];
+const ratioIsValid = (r) => {
+  const [rw, rh] = String(r || '').split(':').map(Number);
+  return rw > 0 && rh > 0;
+};
+/** 画面比例 → 预览区尺寸（不含标题栏/操作栏）。 */
+function mediaPreviewSize(ratio) {
+  const [rw, rh] = String(ratio == null ? '' : ratio).split(':').map(Number);
+  if (!rw || !rh) return { w: MEDIA_PREVIEW_SHORT, h: MEDIA_PREVIEW_SHORT };
+  let w; let h;
+  if (rw >= rh) { h = MEDIA_PREVIEW_SHORT; w = Math.round(MEDIA_PREVIEW_SHORT * rw / rh); }
+  else { w = MEDIA_PREVIEW_SHORT; h = Math.round(MEDIA_PREVIEW_SHORT * rh / rw); }
+  const long = Math.max(w, h);
+  if (long > MEDIA_MAX_LONG) { const k = MEDIA_MAX_LONG / long; w = Math.round(w * k); h = Math.round(h * k); }
+  return { w, h };
+}
+/** 媒体节点外框尺寸 = 预览区尺寸 + 固定栏高度（hasFooter 只在有 assetId 时为 true）。 */
+function mediaNodeSize(ratio, hasFooter) {
+  const pv = mediaPreviewSize(ratio);
+  return { w: pv.w, h: pv.h + NODE_HDR_H + (hasFooter ? NODE_FOOT_H : 0) };
+}
+/** 像素尺寸 → 比例（吸附到 RATIOS 档，3% 容差；否则约分）。 */
+function ratioFromDims(w, h) {
+  const aw = Number(w) || 0;
+  const ah = Number(h) || 0;
+  if (!(aw > 0 && ah > 0)) return '16:9';
+  const want = aw / ah;
+  let best = null;
+  for (const r of RATIOS) {
+    const [rw, rh] = r.split(':').map(Number);
+    const diff = Math.abs(rw / rh - want) / want;
+    if (!best || diff < best.diff) best = { ratio: r, diff };
+  }
+  if (best && best.diff <= 0.03) return best.ratio;
+  const gcd = (a, b) => (b ? gcd(b, a % b) : a);
+  const k = gcd(Math.round(aw), Math.round(ah)) || 1;
+  return Math.round(aw / k) + ':' + Math.round(ah / k);
+}
+/** 媒体节点应使用的画面比例：记录值 → 资产实测尺寸 → 默认 16:9。 */
+function mediaRatioOf(n) {
+  const d = (n && n.data) || {};
+  if (ratioIsValid(d.ratio)) return d.ratio;
+  const aw = Number(d.assetW);
+  const ah = Number(d.assetH);
+  if (aw > 0 && ah > 0) return ratioFromDims(aw, ah);
+  return '16:9';
+}
+/** 文档读入时的幂等归一：媒体节点外框必须满足「预览区比例 = 画面比例」，
+ *  否则按记录比例重算（用户等比拉伸过的预览区比例已正确 → 保留）。
+ *  与 client.js normalizeMediaNodeSize 同一规则，Host 侧建节点/读文档也保持一致。 */
+function normalizeMediaNodeSize(n) {
+  if (!n || (normalizeNodeType(n.type) !== 'image' && normalizeNodeType(n.type) !== 'video')) return n;
+  const d = n.data || (n.data = {});
+  const hasFooter = !!d.assetId;
+  const ratio = mediaRatioOf(n);
+  if (!ratioIsValid(d.ratio)) d.ratio = ratio;
+  const [rw, rh] = String(ratio).split(':').map(Number);
+  const want = rw / rh;
+  const pw = Number(n.w) || 0;
+  const ph = (Number(n.h) || 0) - NODE_HDR_H - (hasFooter ? NODE_FOOT_H : 0);
+  const okPreview = pw > 0 && ph > 0 && Math.abs(pw / ph - want) / want <= 0.02;
+  if (!okPreview) {
+    const sz = mediaNodeSize(ratio, hasFooter);
+    n.w = sz.w; n.h = sz.h;
+  }
+  return n;
+}
 /** 构造与客户端 newNode() 完全一致的节点（形状不一致会导致渲染异常）。 */
 function agentNode(kind, text, x, y, label) {
   const id = 'na' + Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
@@ -1275,20 +1532,22 @@ function agentNode(kind, text, x, y, label) {
     ? { status: 'idle', error: null, text: String(text ?? '') }
     : { status: 'idle', error: null, idea: String(text ?? ''), output: '', aiStatus: 'idle', aiError: null };
   if (label) data.label = String(label).slice(0, 40);
-  return { id, type: isText ? 'text' : 'script', x, y, w: isText ? 260 : 320, h: 100, data };
+  // 与客户端一致：所有节点默认 360×360（文本/剧本/分镜固定这个尺寸，不随内容变化；尺寸持久化进文档）
+  return { id, type: isText ? 'text' : 'script', x, y, w: 360, h: 360, data };
 }
 /** 新节点布局（用户设计）：
  *  1) 有 connectFrom 源 → 放在源节点右侧同一行（串联节点横向成对）；
  *  2) 无连线 → 同类型竖向成列（排在该类型最后一个节点下方，新起一行）；
  *  3) 碰撞检测：候选位置与任何现有节点（含最小间距 28px）相交 → 自动下移到该节点下方，绝不重叠。 */
-function nextNodePos(doc, type, connectFromId) {
+function nextNodePos(doc, type, connectFromId, size) {
   const GAP_X = 60, GAP_Y = 40, MIN_GAP = 28;
   const H = (n) => Number(n && n.h) || 160;
   const W = (n) => Number(n && n.w) || 280;
   const nodes = Object.values(doc.nodes || {});
-  const EST_H = { storyboard: 560, 'video-gen': 620, 'image-gen': 560, script: 420, finalcut: 420, text: 220 };
-  const estH = EST_H[type] || 300;
-  const estW = type === 'finalcut' ? 300 : 280;
+  const EST_H = { storyboard: 360, video: 360, image: 360, script: 360, finalcut: 360, text: 360 };
+  // 媒体节点的真实外框比 360 高/宽（预览区按比例 + 固定栏）：建节点时传 size，避免估小后与邻居重叠
+  const estH = (size && Number(size.h)) || EST_H[type] || 360;
+  const estW = (size && Number(size.w)) || 360;
   const same = nodes.filter((n) => n.type === type);
   let x = 80;
   let y = 40;
@@ -1405,8 +1664,8 @@ function canvasCreateProject(args) {
  */
 function canvasWriteNode(args) {
   const id = String((args && args.projectId) || '');
-  const f = projectFile(id);
-  const doc = readDoc(id);
+  const canvasId = toolCanvasId(args);
+  const doc = readToolDoc(args);
   const text = String((args && args.text) || '');
   const target = (args && args.target) === 'output' ? 'output' : 'idea';
   const nodeId = String((args && args.nodeId) || '');
@@ -1457,7 +1716,8 @@ function canvasWriteNode(args) {
     if (idea !== null && node.type === 'script') node.data.idea = idea;
     if (name) node.data.label = name;
   };
-  const save = () => { doc.updatedAt = Date.now(); writeIcDoc(id, doc); markDocChanged(id); };
+  const save = () => { doc.updatedAt = Date.now(); writeToolDoc(args, doc); };
+  const withCanvas = (o) => (canvasId ? { ...o, canvasId } : o);
   /** 该节点是否已有会被 target=output 覆盖的内容（剧本=成稿；分镜=镜头列表；文本=正文）。 */
   const hasExisting = (node) => {
     if (!node || !node.data) return false;
@@ -1475,14 +1735,14 @@ function canvasWriteNode(args) {
     guardOverwrite(node);
     writeInto(node);
     save();
-    return { ok: true, projectId: id, nodeId, updated: true, label: node.data.label || '' };
+    return withCanvas({ ok: true, projectId: id, nodeId, updated: true, label: node.data.label || '' });
   }
   if ((args && args.kind) === 'text') {
     const pos = nextNodePos(doc);
     const n = agentNode('text', text, pos.x, pos.y, name || defaultLabel(text));
     doc.nodes[n.id] = n;
     save();
-    return { ok: true, projectId: id, nodeId: n.id, label: n.data.label || '' };
+    return withCanvas({ ok: true, projectId: id, nodeId: n.id, label: n.data.label || '' });
   }
   const scripts = Object.values(doc.nodes || {}).filter((n) => n.type === 'script');
   let reuse = null;
@@ -1499,7 +1759,7 @@ function canvasWriteNode(args) {
     }
     writeInto(reuse);
     save();
-    return { ok: true, projectId: id, nodeId: reuse.id, updated: true, reused: true, label: reuse.data.label || '' };
+    return withCanvas({ ok: true, projectId: id, nodeId: reuse.id, updated: true, reused: true, label: reuse.data.label || '' });
   }
   const pos = nextNodePos(doc);
   const n = agentNode('script', target === 'output' ? '' : text, pos.x, pos.y, name || defaultLabel(text));
@@ -1507,14 +1767,15 @@ function canvasWriteNode(args) {
   if (idea !== null) n.data.idea = idea;
   doc.nodes[n.id] = n;
   save();
-  return { ok: true, projectId: id, nodeId: n.id, label: n.data.label || '' };
+  return withCanvas({ ok: true, projectId: id, nodeId: n.id, label: n.data.label || '' });
 }
 /** 读取项目文档：把"文件不存在/内容损坏"变成用户和模型都读得懂的报错（不泄漏绝对路径）。 */
 function readDoc(id) {
   if (sqlActive()) {
     const doc = readDocOrNull(id);
     if (!doc) throw new Error('项目不存在：' + id + '（先用 canvas_list_projects 查看可用项目 id）');
-    return doc;
+    // 旧项目兼容：读入即归一旧节点类型（image-gen/image-asset → image，video-gen/video-asset → video）
+    return normalizeDocNodes(doc);
   }
   const f = projectFile(id);
   let raw;
@@ -1524,13 +1785,16 @@ function readDoc(id) {
     throw new Error('项目不存在：' + id + '（先用 canvas_list_projects 查看可用项目 id）');
   }
   try {
-    return JSON.parse(raw);
+    return normalizeDocNodes(JSON.parse(raw));
   } catch {
     throw new Error('项目文件损坏，无法解析：' + id + '（可考虑重建该项目）');
   }
 }
-/** 原子写项目文档：SQL 模式走单行事务；文件模式先写临时文件再改名，避免半写导致项目"消失"。 */
+/** 原子写项目/画布文档：SQL 模式走单行事务；文件模式先写临时文件再改名，避免半写导致项目"消失"。
+ *  子画布文档（id 含 __cv__）不重复登记项目文件夹、不镜像 project.json——项目级 meta 只属于默认画布行。 */
 function writeIcDoc(id, doc) {
+  const canvasRef = splitCanvasDocId(id);
+  const isCanvas = isCanvasDocId(id);
   if (sqlActive()) {
     const db = getDb();
     db.prepare(`INSERT INTO projects (id, name, created_at, updated_at, bible_updated_at, summary, tombstones, doc)
@@ -1539,19 +1803,115 @@ function writeIcDoc(id, doc) {
                   bible_updated_at = excluded.bible_updated_at, summary = excluded.summary,
                   tombstones = excluded.tombstones, doc = excluded.doc`)
       .run(
-        id, String(doc.name || id).slice(0, 80), doc.createdAt || Date.now(), doc.updatedAt || Date.now(),
-        doc.bibleUpdatedAt || 0, JSON.stringify(docSummary(doc)), JSON.stringify(doc.tombstones || []), JSON.stringify(doc),
+        id,
+        String((doc && doc.name) || (isCanvas ? canvasRef.projectId : id)).slice(0, 80),
+        (doc && doc.createdAt) || Date.now(), (doc && doc.updatedAt) || Date.now(),
+        (doc && doc.bibleUpdatedAt) || 0, JSON.stringify(docSummary(doc)), JSON.stringify((doc && doc.tombstones) || []), JSON.stringify(doc),
       );
     // SQL 模式也要保证数据目录里有 meta 映射（craft 清理/物理落盘按 folder 定位）：
-    // 目录与 project.json 镜像不再是主存储，但 folder 登记是 /api/asset 落盘与 ArtCraft 基准的前提。
-    try { ensureProjectFolder(id, (doc && doc.name) || id); } catch { /* meta 写失败不阻塞主存储 */ }
+    // 子画布共用项目的物理文件夹，不单独登记。
+    if (!isCanvas) {
+      try { ensureProjectFolder(id, (doc && doc.name) || id); } catch { /* meta 写失败不阻塞主存储 */ }
+    }
     return;
   }
   const f = projectFile(id);
   const tmp = f + '.' + process.pid + '.tmp';
   writeFileSync(tmp, JSON.stringify(doc, null, 1), 'utf8');
   renameSync(tmp, f);
-  mirrorProjectToDataRoot(id, doc); // 数据目录镜像（含设定集/assetIds 绑定）：失败不影响主存储
+  // 数据目录镜像（含设定集/assetIds 绑定）：失败不影响主存储；子画布镜像到项目文件夹下 canvases/，不写 project.json
+  if (!isCanvas) mirrorProjectToDataRoot(id, doc);
+  else mirrorCanvasDocToDataRoot(canvasRef.projectId, canvasRef.canvasId, doc);
+}
+/** 读取画布文档（多画布）：默认画布 = 项目文档；子画布 = 独立文档 + 合并项目级字段（名称/设定集/画布清单）。 */
+function readCanvasDoc(projectId, canvasId) {
+  const pid = String(projectId || '');
+  const cid = normalizeCanvasId(canvasId);
+  const projectDoc = readDocOrNull(pid);
+  if (!projectDoc) throw new Error('项目不存在：' + pid + '（先用 canvas_list_projects 查看可用项目 id）');
+  if (!cid) {
+    if (!defaultCanvasExists(projectDoc)) throw new Error('默认画布已删除：请指定 canvasId（先用 canvas_list_projects 查看可用画布）');
+    return normalizeDocNodes({
+      ...projectDoc, canvases: canvasRegistry(projectDoc),
+      defaultCanvasName: defaultCanvasNameOf(projectDoc), defaultCanvasDeleted: false,
+    });
+  }
+  const rec = canvasRegistry(projectDoc).find((c) => c.id === cid);
+  if (!rec) throw new Error('画布不存在：' + cid + '（项目 ' + pid + '；先用 canvas_list_projects 查看可用画布）');
+  const raw = readDocOrNull(canvasDocId(pid, cid)) || {};
+  const doc = { ...raw, id: pid, projectId: pid, canvasId: cid, name: projectDoc.name || pid };
+  doc.nodes = raw.nodes || {};
+  doc.edges = raw.edges || [];
+  doc.view = raw.view || { x: 60, y: 40, scale: 1 };
+  if (projectDoc.bible !== undefined) { doc.bible = projectDoc.bible; doc.bibleUpdatedAt = projectDoc.bibleUpdatedAt || 0; }
+  doc.canvases = canvasRegistry(projectDoc);
+  doc.defaultCanvasName = defaultCanvasNameForApi(projectDoc);
+  doc.defaultCanvasDeleted = !defaultCanvasExists(projectDoc);
+  return normalizeDocNodes(doc);
+}
+/** 写画布文档：默认画布写项目文档；子画布写独立文档（项目级字段剔除）。 */
+function writeCanvasDoc(projectId, canvasId, doc) {
+  const pid = String(projectId || '');
+  const cid = normalizeCanvasId(canvasId);
+  if (!cid) {
+    writeIcDoc(pid, { ...doc, id: pid });
+    return;
+  }
+  const out = { ...doc, id: canvasDocId(pid, cid), projectId: pid, canvasId: cid, updatedAt: Date.now() };
+  delete out.bible;
+  delete out.bibleUpdatedAt;
+  delete out.canvases;
+  delete out.name;
+  writeIcDoc(canvasDocId(pid, cid), out);
+}
+/** 更新项目级字段（名称/设定集/画布清单）——只作用于默认画布那份项目文档。 */
+function patchProjectDoc(projectId, patch) {
+  const pid = String(projectId || '');
+  const cur = readDocOrNull(pid);
+  if (!cur) throw new Error('项目不存在：' + pid);
+  writeIcDoc(pid, { ...cur, ...patch, id: pid });
+}
+/** 工具入口统一的画布参数解析：args.canvasId 缺省 = 项目默认画布（null）；非法 id 直接报错不静默降级。 */
+function toolCanvasId(args) {
+  return normalizeCanvasId(args && args.canvasId);
+}
+/** 工具读文档：默认画布读项目文档，子画布读子文档（项目级字段已合并进来）。 */
+function readToolDoc(args) {
+  const pid = String((args && args.projectId) || '');
+  return readCanvasDoc(pid, toolCanvasId(args));
+}
+/** 工具写文档：默认画布写项目文档、子画布写子文档，并标记画布级变更信号。返回 canvasId。 */
+function writeToolDoc(args, doc) {
+  const pid = String((args && args.projectId) || '');
+  const cid = toolCanvasId(args);
+  writeCanvasDoc(pid, cid, doc);
+  markDocChanged(pid, cid);
+  return cid;
+}
+/** 删除项目的全部子画布文档（项目删除时清干净，避免残留行/文件被列出）。 */
+function deleteCanvasDocsForProject(projectId) {
+  const pid = String(projectId || '');
+  if (!pid) return 0;
+  let removed = 0;
+  if (sqlActive()) {
+    try {
+      const db = getDb();
+      const ids = db.prepare('SELECT id FROM projects WHERE instr(id, ?) > 0').all(CANVAS_ID_SEP).map((r) => r.id)
+        .filter((id) => splitCanvasDocId(id).projectId === pid);
+      const del = db.prepare('DELETE FROM projects WHERE id = ?');
+      for (const id of ids) { try { del.run(id); removed++; } catch { /* 单行失败不影响其他 */ } }
+    } catch { /* 清理失败不影响项目删除 */ }
+    return removed;
+  }
+  try {
+    for (const f of readdirSync(PROJECTS_DIR)) {
+      if (!f.endsWith('.json')) continue;
+      const id = f.slice(0, -5);
+      if (!isCanvasDocId(id) || splitCanvasDocId(id).projectId !== pid) continue;
+      try { unlinkSync(path.join(PROJECTS_DIR, f)); removed++; } catch { /* 文件占用/已删 */ }
+    }
+  } catch { /* 无目录 */ }
+  return removed;
 }
 /** 读取设定集（对话侧"设定集先行"的前提）。 */
 async function canvasGetBible(args) {
@@ -1613,29 +1973,38 @@ async function canvasUpdateBible(args) {
   markDocChanged(id);
   return { projectId: id, bible: doc.bible, bibleUpdatedAt: doc.bibleUpdatedAt };
 }
-/** 通用建节点（供对话建角色/场景/道具参考图等）；支持 script/text/image-gen/video-gen/storyboard/finalcut。 */
+/** 通用建节点（供对话建角色/场景/道具参考图等）；支持 script/text/image/video/storyboard/finalcut。
+ *  image / video 是合并类型：有 assetId 即资产节点、有 prompt 即待生成的空节点；旧名
+ *  image-gen / image-asset / video-gen / video-asset 仍接受，内部一律映射为合并类型。 */
 function canvasCreateNode(args) {
   const id = String((args && args.projectId) || '');
-  const f = projectFile(id);
-  const doc = readDoc(id);
-  const type = String((args && args.type) || 'text');
-  if (!['script', 'text', 'image-gen', 'video-gen', 'storyboard', 'finalcut'].includes(type)) throw new Error('不支持的节点类型: ' + type);
+  const canvasId = toolCanvasId(args);
+  const doc = readToolDoc(args);
+  const rawType = String((args && args.type) || 'text');
+  const type = normalizeNodeType(rawType);
+  if (!['script', 'text', 'image', 'video', 'storyboard', 'finalcut'].includes(type)) throw new Error('不支持的节点类型: ' + rawType);
+  const legacyType = rawType !== type ? rawType : '';
   const label = args && args.name ? String(args.name).slice(0, 40) : '';
   const prompt = String((args && args.prompt) || '');
   const connectFrom = String((args && args.connectFrom) || '');
-  const pos = nextNodePos(doc, type, connectFrom);
+  // 媒体节点：空态按「预览区比例 + 标题栏」给外框（没有操作栏就不加 NODE_FOOT_H），
+  // 布点时用真实外框做碰撞检测，避免按 360×360 估小后与同列邻居重叠。
+  const mediaSize = (type === 'image' || type === 'video')
+    ? mediaNodeSize((args && args.ratio) || '16:9', false)
+    : null;
+  const pos = nextNodePos(doc, type, connectFrom, mediaSize);
   let connected = null;
   let autoConnected = null;
   let node;
-  if (type === 'image-gen') {
-    node = agentNode('text', '', pos.x, pos.y, label || '图片生成');
-    node.type = 'image-gen';
-    node.w = 280;
-    node.data = { ...node.data, status: 'idle', error: null, prompt, assetId: null, demo: false, size: (args && args.size) || '2K', ratio: (args && args.ratio) || '16:9' };
-  } else if (type === 'video-gen') {
-    node = agentNode('text', '', pos.x, pos.y, label || '视频生成');
-    node.type = 'video-gen';
-    node.w = 280;
+  if (type === 'image') {
+    node = agentNode('text', '', pos.x, pos.y, label || '图片节点');
+    node.type = 'image';
+    node.w = mediaSize.w; node.h = mediaSize.h;
+    node.data = { ...node.data, status: 'idle', error: null, prompt, assetId: null, demo: false, size: (args && args.size) || '2K', ratio: (args && args.ratio) || '16:9', imageCount: 1 };
+  } else if (type === 'video') {
+    node = agentNode('text', '', pos.x, pos.y, label || '视频节点');
+    node.type = 'video';
+    node.w = mediaSize.w; node.h = mediaSize.h;
     // 多镜头工作流（结构性强制）：项目里已有**拆解过镜头**的分镜表 → 一律自动连线分镜表、prompt 忽略。
     // 一个分镜表 = 一个完整视频，镜头清单只从分镜表读取；对话侧手写 prompt 绕过分镜表是高频错误，这里直接封死。
     const sbs = Object.values(doc.nodes || {}).filter((n) => n.type === 'storyboard');
@@ -1667,7 +2036,7 @@ function canvasCreateNode(args) {
   } else if (type === 'finalcut') {
     node = agentNode('text', '', pos.x, pos.y, label || '成片');
     node.type = 'finalcut';
-    node.w = 300;
+    node.w = 360; node.h = 360;
     node.data = { ...node.data, status: 'idle', error: null, resolution: (args && args.resolution) || '720P', ratio: (args && args.ratio) || '16:9', transition: 'none', progress: null, assetId: null, subs: {}, keepAudio: true };
   } else if (type === 'script') {
     node = agentNode('script', prompt, pos.x, pos.y, label || defaultLabel(prompt));
@@ -1684,22 +2053,26 @@ function canvasCreateNode(args) {
     const defaultToPort = (type === 'storyboard' && (srcType === 'text' || srcType === 'script')) ? 'script' : undefined;
     const edge = connectEdge(doc, connectFrom, node.id, args && args.connectFromPort, (args && args.connectToPort) || defaultToPort);
     connected = edge.id;
-  } else if (autoConnected && (type === 'storyboard' || type === 'video-gen')) {
-    // 未指定连线但上游已存在（分镜表→剧本 / 视频生成→分镜表）→ 默认自动连线（工作流的默认形态，不依赖 Agent 记得）
+  } else if (autoConnected && (type === 'storyboard' || type === 'video')) {
+    // 未指定连线但上游已存在（分镜表→剧本 / 视频节点→分镜表）→ 默认自动连线（工作流的默认形态，不依赖 Agent 记得）
     const edge = connectEdge(doc, autoConnected.from, node.id, undefined, type === 'storyboard' ? 'script' : undefined);
     connected = edge.id;
   }
   doc.updatedAt = Date.now();
-  writeIcDoc(id, doc);
-  markDocChanged(id);
+  writeToolDoc(args, doc);
   const note = autoConnected && autoConnected.ignoredPrompt
-    ? (type === 'video-gen'
+    ? (type === 'video'
       ? '⚠️ 已强制连线到分镜表（多镜头工作流：一个分镜表 = 一个完整视频，镜头清单从分镜表读取），传入的 prompt 已忽略——不要手写视频提示词绕过分镜表。'
       : '已自动连线到上游剧本节点，传入的 prompt 被忽略（内容从连线取）。')
     : (autoConnected && autoConnected.emptyShots
       ? '已连线到分镜表；该分镜表尚未拆解镜头（shots 为空）——先 canvas_run_node 分镜表生成镜头，再生成视频。'
       : '');
-  return { ok: true, projectId: id, nodeId: node.id, type: node.type, label: (node.data && node.data.label) || '', edgeId: connected || undefined, note: note || undefined };
+  return {
+    ok: true, projectId: id, ...(canvasId ? { canvasId } : {}), nodeId: node.id, type: node.type, label: (node.data && node.data.label) || '',
+    edgeId: connected || undefined, note: note || undefined,
+    // 旧名（image-gen / image-asset / video-gen / video-asset）已映射为合并节点：明确告诉 Agent 实际类型
+    mergedType: legacyType ? (legacyType + ' → ' + node.type + '（合并节点：有 assetId 即资产，空节点在画布点开面板生成）') : undefined,
+  };
 }
 
 /** 一键重排：按「行」布局——横向数据流决定列，竖向端口（prev/frame）不参与分列；
@@ -1707,9 +2080,10 @@ function canvasCreateNode(args) {
  *  行高取行内最高节点、行间保留间距，绝不重叠。 */
 function canvasRelayout(args) {
   const id = String((args && args.projectId) || '');
-  const doc = readDoc(id);
+  const canvasId = toolCanvasId(args);
+  const doc = readToolDoc(args);
   const nodes = Object.values(doc.nodes || {});
-  if (!nodes.length) return { ok: true, projectId: id, moved: 0, rows: 0 };
+  if (!nodes.length) return { ok: true, projectId: id, ...(canvasId ? { canvasId } : {}), moved: 0, rows: 0 };
   const VERT = new Set(['prev', 'frame']);
   const byId = new Map(nodes.map((n) => [n.id, n]));
   const depth = new Map(nodes.map((n) => [n.id, 0]));
@@ -1754,9 +2128,8 @@ function canvasRelayout(args) {
     cy += rowH + 40;
   }
   doc.updatedAt = Date.now();
-  writeIcDoc(id, doc);
-  markDocChanged(id);
-  return { ok: true, projectId: id, moved, rows: rowList.length };
+  writeToolDoc(args, doc);
+  return { ok: true, projectId: id, ...(canvasId ? { canvasId } : {}), moved, rows: rowList.length };
 }
 async function canvasDeleteProject(args) {
   const id = String((args && args.projectId) || '');
@@ -1769,6 +2142,7 @@ async function canvasDeleteProject(args) {
     cleanup = sqlDeleteProjectRows(getDb(), id, dataRoot());
   } else {
     try { unlinkSync(projectFile(id)); } catch { /* 已删除 */ }
+    try { deleteCanvasDocsForProject(id); } catch { /* 子画布清理失败不影响删除 */ }
     try { removeDataRootProject(id); } catch { /* 数据目录镜像清理失败不影响删除 */ }
   }
   // 通知客户端把这个项目也从本地删掉，否则下次推送会把它复活 + 长效墓碑：拒收迟到的推送
@@ -1787,29 +2161,29 @@ async function canvasDeleteProject(args) {
 async function canvasDeleteNode(args) {
   const id = String((args && args.projectId) || '');
   const nodeId = String((args && args.nodeId) || '');
-  const f = projectFile(id);
-  const doc = readDoc(id);
+  const canvasId = toolCanvasId(args);
+  const doc = readToolDoc(args);
   if (!doc.nodes[nodeId]) throw new Error('节点不存在: ' + nodeId);
   delete doc.nodes[nodeId];
   doc.edges = (doc.edges || []).filter((e) => e.fromNode !== nodeId && e.toNode !== nodeId);
   doc.tombstones = [...new Set([...(doc.tombstones || []), nodeId])].slice(-100);
   doc.tombstoneAt = { ...(doc.tombstoneAt || {}), [nodeId]: Date.now() }; // 记录墓碑创建时刻：撤销恢复的推送（ts 更新）才允许清墓碑
   doc.updatedAt = Date.now();
-  writeIcDoc(id, doc);
-  markDocChanged(id);
-  return { ok: true, projectId: id, nodeId };
+  writeToolDoc(args, doc);
+  return { ok: true, projectId: id, ...(canvasId ? { canvasId } : {}), nodeId };
 }
 /** 运行节点：写一次性请求，画布客户端轮询消费后用画布内配置的模型/接口真实执行。 */
 async function canvasRunNode(args) {
   const pid = String((args && args.projectId) || '');
   const nodeId = String((args && args.nodeId) || '');
-  const doc = readDoc(pid);
+  const canvasId = toolCanvasId(args);
+  const doc = readToolDoc(args);
   const node = doc.nodes[nodeId];
   if (!node) throw new Error('节点不存在: ' + nodeId);
   const cfg = readIcConfig();
-  cfg.ui = { ...(cfg.ui || {}), runRequest: { projectId: pid, nodeId, at: Date.now() } };
+  cfg.ui = { ...(cfg.ui || {}), runRequest: { projectId: pid, canvasId, nodeId, at: Date.now() } };
   writeIcConfig(cfg);
-  return { ok: true, projectId: pid, nodeId, type: node.type, label: (node.data && node.data.label) || '' };
+  return { ok: true, projectId: pid, ...(canvasId ? { canvasId } : {}), nodeId, type: node.type, label: (node.data && node.data.label) || '' };
 }
 /** 读取节点运行状态与产物（画布执行完成后会把结果推回 Host 文档）。 */
 /** 分镜一致性检查（与客户端 checkShotConsistency 同规则，Host 供状态查询/设定集更新后重算）：
@@ -1877,7 +2251,8 @@ function readAssetIndexNames(pid) {
 async function canvasNodeStatus(args) {
   const pid = String((args && args.projectId) || '');
   const nodeId = String((args && args.nodeId) || '');
-  const doc = readDoc(pid);
+  const canvasId = toolCanvasId(args);
+  const doc = readToolDoc(args);
   const n = doc.nodes[nodeId];
   if (!n) throw new Error('节点不存在: ' + nodeId);
   // 分镜表：返回镜头清单（结构化）——对话侧据此组织视频提示词，绝不自行推导/编造镜头表
@@ -1906,7 +2281,7 @@ async function canvasNodeStatus(args) {
     : undefined;
   const d = n.data || {};
   return {
-    projectId: pid, nodeId, type: n.type, label: d.label || '',
+    projectId: pid, ...(canvasId ? { canvasId } : {}), nodeId, type: n.type, label: d.label || '',
     status: d.status || 'idle',
     aiStatus: d.aiStatus || 'idle',
     // 文档级时间戳：canvas_generate_node 的等待循环用它区分「本轮真的跑过」与「上一次的残留终态」
@@ -1954,7 +2329,8 @@ const NODE_PATCH_FIELDS = ['prompt', 'idea', 'output', 'text', 'script', 'requir
 function canvasUpdateNode(args) {
   const pid = String((args && args.projectId) || '');
   const nodeId = String((args && args.nodeId) || '');
-  const doc = readDoc(pid);
+  const canvasId = toolCanvasId(args);
+  const doc = readToolDoc(args);
   const n = doc.nodes[nodeId];
   if (!n) throw new Error('节点不存在: ' + nodeId + '（先用 canvas_list_projects 查看节点 id）');
   const patch = (args && args.patch) || {};
@@ -2013,24 +2389,24 @@ function canvasUpdateNode(args) {
     throw new Error('没有可应用的字段（允许：' + NODE_PATCH_FIELDS.join(' / ') + ' / shots）；收到：' + keys.join(' / '));
   }
   doc.updatedAt = Date.now();
-  writeIcDoc(pid, doc);
-  markDocChanged(pid);
-  return { projectId: pid, nodeId, type: n.type, label: n.data.label || '', applied, skipped, prompt: String(n.data.prompt || '').slice(0, 400) };
+  writeToolDoc(args, doc);
+  return { projectId: pid, ...(canvasId ? { canvasId } : {}), nodeId, type: n.type, label: n.data.label || '', applied, skipped, prompt: String(n.data.prompt || '').slice(0, 400) };
 }
 /** 触发节点执行并（可选）等待到终态：对话侧"改完提示词 → 点生成 → 拿结果"的一站式入口。
  *  执行发生在画布侧（需要浏览器开着画布页面消费运行请求），等待超时不代表失败。 */
 async function canvasGenerateNode(args) {
   const pid = String((args && args.projectId) || '');
   const nodeId = String((args && args.nodeId) || '');
+  const canvasId = toolCanvasId(args);
   const waitSec = Math.max(0, Math.min(600, Number((args && args.waitSeconds) || 0)));
   // 触发前快照：canvasRunNode 只写一次性 runRequest，真正的执行要等画布下一个 3s 同步 tick
   // 才开始（状态才翻成 running）；而下面的首轮轮询在 2.5s 就发生——对**曾经跑过**的节点，
   // 首轮会读到上一次的 done/error 并误当本次结果（页面关闭 100%、页开约 17% 触发）。
   // 因此终态只有在「本轮确实跑过」时才可信：轮询中见过 running，或文档在触发后被写过
   //（快进完成的短任务可能整体落在两次轮询之间，用文档时间戳兜底）。
-  const baseline = await canvasNodeStatus({ projectId: pid, nodeId }).catch(() => null);
+  const baseline = await canvasNodeStatus({ projectId: pid, canvasId, nodeId }).catch(() => null);
   const baseUpdatedAt = Number(baseline && baseline.docUpdatedAt) || 0;
-  const run = await canvasRunNode({ projectId: pid, nodeId });
+  const run = await canvasRunNode({ projectId: pid, canvasId, nodeId });
   if (!waitSec) {
     return { ok: true, triggered: true, finished: false, projectId: pid, nodeId, type: run.type, label: run.label, status: 'running', note: '已触发执行；画布需处于打开状态才会真正执行，可用 canvas_node_status 查询进度' };
   }
@@ -2039,7 +2415,7 @@ async function canvasGenerateNode(args) {
   let sawRunning = false;
   while (Date.now() < deadline) {
     await new Promise((r) => setTimeout(r, 2500));
-    try { last = await canvasNodeStatus({ projectId: pid, nodeId }); } catch { continue; }
+    try { last = await canvasNodeStatus({ projectId: pid, canvasId, nodeId }); } catch { continue; }
     const st = String(last.status || '');
     const ai = String(last.aiStatus || '');
     if (st === 'running' || ai === 'running') { sawRunning = true; continue; }
@@ -2062,35 +2438,137 @@ async function canvasGenerateNode(args) {
 }
 async function canvasOpen(args) {
   const pid = String((args && args.projectId) || '');
+  const canvasId = toolCanvasId(args);
   if (pid) {
-    // 项目必须真实存在：否则工具回"✅ 已打开"，而前端因为找不到项目什么都不做（假成功）
-    if (!docExists(pid)) throw new Error('项目不存在：' + pid + '（先用 canvas_list_projects 查看可用项目 id）');
+    // 项目（以及指定画布）必须真实存在：否则工具回"✅ 已打开"，而前端因为找不到项目什么都不做（假成功）
+    if (canvasId) readCanvasDoc(pid, canvasId);
+    else if (!docExists(pid)) throw new Error('项目不存在：' + pid + '（先用 canvas_list_projects 查看可用项目 id）');
   }
   const cfg = readIcConfig();
-  cfg.ui = { ...(cfg.ui || {}), openRequest: { projectId: pid || null, at: Date.now() } };
+  cfg.ui = { ...(cfg.ui || {}), openRequest: { projectId: pid || null, canvasId: pid ? canvasId : null, at: Date.now() } };
   writeIcConfig(cfg);
-  return { ok: true, projectId: pid || null };
+  return { ok: true, projectId: pid || null, ...(canvasId ? { canvasId } : {}) };
 }
 
-/** 与客户端一致的端口表（连线校验用）。 */
+/** 画布清单（多画布目录树的数据源）：默认画布不登记在 canvases 里（客户端用 canvasId=null 表达），
+ *  返回 projectId + 默认画布名/是否已删除 + canvases（子画布）。 */
+async function canvasesList(args) {
+  const pid = String((args && args.projectId) || '');
+  const doc = readDoc(pid);
+  return {
+    projectId: pid, name: doc.name || pid,
+    canvases: canvasRegistry(doc),
+    defaultCanvasName: defaultCanvasNameForApi(doc),
+    defaultCanvasDeleted: !defaultCanvasExists(doc),
+  };
+}
+/** 新建子画布：必须命名；画布 id 由 Host 生成（cv 前缀，避免与项目 id 混淆）。
+ *  新画布首次打开是空白画布（没有文档行，readCanvasDoc 会兜底空图）。 */
+async function canvasCreate(args) {
+  const pid = String((args && args.projectId) || '');
+  const name = String((args && args.name) || '').trim();
+  if (!name) throw new Error('需要画布名称（新建画布必须命名）');
+  const projectDoc = readDoc(pid);
+  const list = canvasRegistry(projectDoc);
+  const defaultCanvasName = defaultCanvasNameForApi(projectDoc);
+  // 同名复用：重复点击/重试不产生一堆同名画布
+  const dup = list.find((c) => String(c.name).trim() === name);
+  if (dup) return { ok: true, projectId: pid, canvasId: dup.id, name: dup.name, reused: true, defaultCanvasName };
+  if (allCanvasNames(projectDoc).some((n) => n.trim() === name)) throw new Error('同名画布已存在：' + name);
+  if (list.length >= 200) throw new Error('一个项目最多 200 个画布');
+  // 客户端可自带 id（本地已登记、目录树已显示的路径）：合法且未占用就采用，避免两端 id 不一致
+  const wantId = normalizeCanvasId(args && args.canvasId);
+  const cid = (wantId && !list.some((c) => c.id === wantId)) ? wantId : ('cv' + Date.now().toString(36) + Math.random().toString(36).slice(2, 6));
+  const next = sanitizeCanvases([...list, { id: cid, name: name.slice(0, 80), createdAt: Date.now() }]);
+  patchProjectDoc(pid, { canvases: next });
+  return { ok: true, projectId: pid, canvasId: cid, name: name.slice(0, 80), reused: false, defaultCanvasName };
+}
+/** 重命名画布：canvasId=null 表示默认画布（写项目文档 defaultCanvasName）；必须命名、同名（除自己）拒绝。 */
+async function canvasRename(args) {
+  const pid = String((args && args.projectId) || '');
+  const cid = normalizeCanvasId(args && args.canvasId);
+  const name = String((args && args.name) || '').trim();
+  if (!name) throw new Error('需要画布名称');
+  const projectDoc = readDoc(pid);
+  const list = canvasRegistry(projectDoc);
+  if (!cid) {
+    if (!defaultCanvasExists(projectDoc)) throw new Error('默认画布已删除，无法重命名');
+    if (list.some((c) => String(c.name).trim() === name)) throw new Error('同名画布已存在：' + name);
+    patchProjectDoc(pid, { defaultCanvasName: name.slice(0, 80) });
+    return { ok: true, projectId: pid, canvasId: null, name: name.slice(0, 80), defaultCanvasName: name.slice(0, 80) };
+  }
+  const target = list.find((c) => c.id === cid);
+  if (!target) throw new Error('画布不存在：' + cid);
+  const defNameApi = defaultCanvasNameForApi(projectDoc);
+  if (defNameApi && String(defNameApi).trim() === name) throw new Error('同名画布已存在：' + name);
+  if (list.some((c) => c.id !== cid && String(c.name).trim() === name)) throw new Error('同名画布已存在：' + name);
+  const next = list.map((c) => (c.id === cid ? { ...c, name: name.slice(0, 80) } : c));
+  patchProjectDoc(pid, { canvases: sanitizeCanvases(next) });
+  return { ok: true, projectId: pid, canvasId: cid, name: name.slice(0, 80), defaultCanvasName: defaultCanvasNameForApi(projectDoc) };
+}
+/** 删除画布。canvasId=null 删除默认画布（清图 + defaultCanvasName + 标记 defaultCanvasDeleted，项目保留）；
+ *  子画布沿用原逻辑。画布总数 = 1 时拒绝删除（客户端已隐藏按钮，Host 兜底）。 */
+async function canvasDelete(args) {
+  const pid = String((args && args.projectId) || '');
+  const cid = normalizeCanvasId(args && args.canvasId);
+  const projectDoc = readDoc(pid);
+  const list = canvasRegistry(projectDoc);
+  const total = canvasTotal(projectDoc);
+  if (total <= 1) throw new Error('至少要保留一个画布');
+  if (!cid) {
+    if (!defaultCanvasExists(projectDoc)) throw new Error('默认画布已删除');
+    const desiredName = defaultCanvasNameOf(projectDoc);
+    const nextDoc = {
+      ...projectDoc,
+      nodes: {}, edges: [],
+      view: { x: 60, y: 40, scale: 1 },
+      tombstones: [], edgeTombstones: [], tombstoneAt: {}, edgeTombstoneAt: {},
+      defaultCanvasDeleted: true,
+      defaultCanvasName: '',
+      updatedAt: Date.now(),
+    };
+    writeIcDoc(pid, nextDoc);
+    const nextCanvasId = list[0] ? list[0].id : null;
+    return { ok: true, projectId: pid, canvasId: null, deletedName: desiredName, defaultCanvasName: '', defaultCanvasDeleted: true, nextCanvasId };
+  }
+  const targetId = canvasDocId(pid, cid);
+  const inList = list.some((c) => c.id === cid);
+  const hasDoc = Boolean(readDocOrNull(targetId));
+  // 幂等：客户端先删本地登记再发删除请求时，Host 可能只剩文档或只剩登记
+  if (!inList && !hasDoc) throw new Error('画布不存在：' + cid);
+  if (inList) patchProjectDoc(pid, { canvases: sanitizeCanvases(list.filter((c) => c.id !== cid)) });
+  try {
+    if (sqlActive()) getDb().prepare('DELETE FROM projects WHERE id = ?').run(targetId);
+    else unlinkSync(projectFile(targetId));
+  } catch { /* 文档不存在视为已删除 */ }
+  return {
+    ok: true, projectId: pid, canvasId: cid,
+    defaultCanvasName: defaultCanvasNameForApi(projectDoc),
+    defaultCanvasDeleted: !defaultCanvasExists(projectDoc),
+  };
+}
+
+/** 与客户端一致的端口表（连线校验用）。image / video 是合并类型（旧生成/资产节点归一到这里）：
+ *  image 输入 prompt+ref、输出 out；video 输入 prompt+frame+ref、输出 out/tailpick/last。 */
 const PORT_TABLE = {
   'text': { inputs: [], outputs: [{ id: 'out', kind: 'text' }] },
   'shot': { inputs: [{ id: 'char', kind: 'image' }, { id: 'scene', kind: 'image' }, { id: 'prop', kind: 'image' }], outputs: [{ id: 'visual', kind: 'text' }, { id: 'motion', kind: 'text' }] },
   'script': { inputs: [], outputs: [{ id: 'out', kind: 'text' }] },
   'storyboard': { inputs: [{ id: 'prev', kind: 'text' }, { id: 'script', kind: 'text' }], outputs: [{ id: 'out', kind: 'text' }, { id: 'tail', kind: 'text' }] },
-  'image-gen': { inputs: [{ id: 'prompt', kind: 'text' }, { id: 'ref', kind: 'image' }], outputs: [{ id: 'out', kind: 'image' }] },
-  'video-gen': { inputs: [{ id: 'prompt', kind: 'text' }, { id: 'frame', kind: 'image' }, { id: 'ref', kind: 'image' }], outputs: [{ id: 'out', kind: 'video' }, { id: 'tailpick', kind: 'image' }, { id: 'last', kind: 'image' }] },
-  'image-asset': { inputs: [{ id: 'in', kind: 'image' }], outputs: [{ id: 'out', kind: 'image' }] },
-  'video-asset': { inputs: [{ id: 'in', kind: 'video' }], outputs: [{ id: 'out', kind: 'video' }, { id: 'tailpick', kind: 'image' }, { id: 'last', kind: 'image' }] },
+  'image': { inputs: [{ id: 'prompt', kind: 'text' }, { id: 'ref', kind: 'image' }], outputs: [{ id: 'out', kind: 'image' }] },
+  'video': { inputs: [{ id: 'prompt', kind: 'text' }, { id: 'frame', kind: 'image' }, { id: 'ref', kind: 'image' }], outputs: [{ id: 'out', kind: 'video' }, { id: 'tailpick', kind: 'image' }, { id: 'last', kind: 'image' }] },
   'finalcut': { inputs: [{ id: 'in', kind: 'video' }], outputs: [] },
   'group': { inputs: [], outputs: [] },
 };
 const MULTI_INPUT_PORTS = new Set(['ref', 'char', 'scene', 'prop']);
-/** Agent 改动了项目文档：记一次性信号，让画布在几秒内拉回合并（否则画布上看不到 Agent 的改动）。 */
-function markDocChanged(projectId) {
+/** Agent 改动了项目文档：记一次性信号，让画布在几秒内拉回合并（否则画布上看不到 Agent 的改动）。
+ *  canvasId 记录是哪个画布被改（缺省/默认画布 = null），客户端只刷新当前画布。 */
+function markDocChanged(projectId, canvasId) {
   try {
     const cfg = readIcConfig();
-    cfg.ui = { ...(cfg.ui || {}), docChanged: { projectId, at: Date.now() } };
+    let cid = null;
+    try { cid = normalizeCanvasId(canvasId); } catch { cid = null; }
+    cfg.ui = { ...(cfg.ui || {}), docChanged: { projectId, canvasId: cid, at: Date.now() } };
     writeIcConfig(cfg);
   } catch { /* 配置写失败不影响主流程 */ }
 }
@@ -2103,14 +2581,42 @@ function connectEdge(doc, fromId, toId, fromPort, toPort) {
   if (fromId === toId) throw new Error('不能把节点连到自己');
   const outs = (PORT_TABLE[from.type] && PORT_TABLE[from.type].outputs) || [];
   const ins = (PORT_TABLE[to.type] && PORT_TABLE[to.type].inputs) || [];
-  const fp = String(fromPort || (outs[0] && outs[0].id) || '');
+  let fp = String(fromPort || '').trim();
   // 目标端口缺省时按语义选择，而不是死板取第一个输入口：
   // 剧本/文本 → 分镜表 = 剧本来源（script）；分镜表 → 分镜表 = 承接上一镜（prev）；其余取第一个输入口
   let tp = String(toPort || '').trim();
   if (!tp) {
-    if (to.type === 'storyboard' && (from.type === 'text' || from.type === 'script')) tp = 'script';
-    else if (to.type === 'storyboard' && from.type === 'storyboard') tp = 'prev';
-    else tp = String((ins[0] && ins[0].id) || '');
+    // 目标端口缺省时按语义选择（与客户端「端口单点、系统自动选口」同一套规则）：
+    // 文本 → 分镜表 script；分镜表 → 分镜表 prev；文本 → 图片/视频 prompt；
+    // 图片 → 图片/视频 ref；视频 → 视频 frame 或成片 in。
+    if (to.type === 'storyboard') {
+      tp = from.type === 'storyboard' ? 'prev' : ((from.type === 'text' || from.type === 'script') ? 'script' : String((ins[0] && ins[0].id) || ''));
+    } else if (to.type === 'image') {
+      tp = (from.type === 'image' || from.type === 'image-asset' || from.type === 'image-gen') ? 'ref' : 'prompt';
+    } else if (to.type === 'video') {
+      if (from.type === 'video' || from.type === 'video-asset' || from.type === 'video-gen') tp = 'frame';
+      else if (from.type === 'image' || from.type === 'image-asset' || from.type === 'image-gen') tp = 'ref';
+      else tp = 'prompt';
+    } else if (to.type === 'finalcut') {
+      tp = 'in';
+    } else {
+      tp = String((ins[0] && ins[0].id) || '');
+    }
+  }
+  if (!fp) {
+    const want = ins.find((p) => p.id === tp);
+    const same = want ? outs.filter((o) => o.kind === want.kind) : [];
+    if (tp === 'prev') {
+      const tail = same.find((o) => o.id === 'tail');
+      fp = String((tail && tail.id) || (same[0] && same[0].id) || (outs[0] && outs[0].id) || '');
+    } else if (want && want.kind === 'image') {
+      // 视频 → 视频的 frame：优先尾帧最佳选帧，退到真·最后帧
+      const pick = same.find((o) => o.id === 'tailpick');
+      const last = same.find((o) => o.id === 'last');
+      fp = String((pick && from.data && from.data.lastPickAssetId ? 'tailpick' : '') || (last && last.id) || (same[0] && same[0].id) || (outs[0] && outs[0].id) || '');
+    } else {
+      fp = String((same[0] && same[0].id) || (outs[0] && outs[0].id) || '');
+    }
   }
   const outDef = outs.find((p) => p.id === fp);
   const inDef = ins.find((p) => p.id === tp);
@@ -2130,7 +2636,8 @@ function connectEdge(doc, fromId, toId, fromPort, toPort) {
 /** 在两个节点间连线（画布工作流的关键：剧本→分镜→图→视频靠连线组织，不要复制文本）。 */
 function canvasConnect(args) {
   const id = String((args && args.projectId) || '');
-  const doc = readDoc(id);
+  const canvasId = toolCanvasId(args);
+  const doc = readToolDoc(args);
   const fromId = String((args && args.fromNode) || '');
   const toId = String((args && args.toNode) || '');
   const already = (doc.edges || []).some((e) => e.fromNode === fromId && e.toNode === toId);
@@ -2140,10 +2647,9 @@ function canvasConnect(args) {
   const fromLabel = String((from.data && from.data.label) || fromId);
   const toLabel = String((to.data && to.data.label) || toId);
   doc.updatedAt = Date.now();
-  writeIcDoc(id, doc);
-  markDocChanged(id);
+  writeToolDoc(args, doc);
   return {
-    ok: true, projectId: id, edgeId: edge.id, already,
+    ok: true, projectId: id, ...(canvasId ? { canvasId } : {}), edgeId: edge.id, already,
     text: '✅ 已连线：「' + fromLabel + '」(' + edge.fromPort + ') → 「' + toLabel + '」(' + edge.toPort + ')。' + (already ? '（此前已连过，本次未重复建线）' : ''),
   };
 }
@@ -2269,7 +2775,7 @@ async function updateInstall() {
 export const inject = ['webServer', 'tools'];
 
 // 仅供诊断 / 自动化测试（不属于 RPC 面，运行时行为不受影响）
-export const _internals = { updateCheck, updateInstall, npmLatestVersion, cmpVer, findPnpm, getProfileDir: () => PROFILE_DIR, getVersion: () => VERSION, dataRoot, setDataRoot, dataRootMigrate, dataRootImport, ensureProjectFolder, physicalRel, mirrorProjectToDataRoot, writeAssetIndex, removeAssetIndexEntry, readDataRootMeta, removeDataRootProject, sqlDeleteProjectRows, deletedProjectIds, addDeletedProjectId, clearDeletedProjectId, fetchProxyForward, storyboardConsistencyWarnings, readAssetIndexNames, safeJoin, mimeOf, pipeFile, getIcConfigPath: () => CONFIG_PATH, canvasCreateProject, canvasWriteNode, canvasConnect, canvasDeleteProject, canvasDeleteNode, canvasRunNode, canvasNodeStatus, canvasGetBible, canvasUpdateBible, canvasCreateNode, canvasOpen, projectsList, projectsPut, projectsGet, projectsDelete, projectsSync, sqliteAvailable: () => !!SQLITE, getDb, closeDb, dbAssetsList, dbAssetsGet, dbAssetNames, dbAssetCreate, dbAssetUpdate, dbAssetDelete, objectAbsFor, ftsReconcile, readDocOrNull, docExists, sqlActive, rpcMethods: () => _rpcMethods, canvasUpdateNode, canvasGenerateNode };
+export const _internals = { updateCheck, updateInstall, npmLatestVersion, cmpVer, findPnpm, getProfileDir: () => PROFILE_DIR, getVersion: () => VERSION, dataRoot, setDataRoot, dataRootMigrate, dataRootImport, ensureProjectFolder, physicalRel, mirrorProjectToDataRoot, writeAssetIndex, removeAssetIndexEntry, readDataRootMeta, removeDataRootProject, sqlDeleteProjectRows, deletedProjectIds, addDeletedProjectId, clearDeletedProjectId, fetchProxyForward, storyboardConsistencyWarnings, readAssetIndexNames, safeJoin, mimeOf, pipeFile, getIcConfigPath: () => CONFIG_PATH, canvasCreateProject, canvasWriteNode, canvasConnect, canvasDeleteProject, canvasDeleteNode, canvasRunNode, canvasNodeStatus, canvasGetBible, canvasUpdateBible, canvasCreateNode, canvasOpen, canvasesList, canvasCreate, canvasRename, canvasDelete, canvasDocId, isCanvasDocId, splitCanvasDocId, normalizeCanvasId, canvasRegistry, sanitizeCanvases, readCanvasDoc, writeCanvasDoc, deleteCanvasDocsForProject, projectsList, projectsPut, projectsGet, projectsDelete, projectsSync, sqliteAvailable: () => !!SQLITE, getDb, closeDb, dbAssetsList, dbAssetsGet, dbAssetNames, dbAssetCreate, dbAssetUpdate, dbAssetDelete, objectAbsFor, ftsReconcile, readDocOrNull, docExists, sqlActive, rpcMethods: () => _rpcMethods, canvasUpdateNode, canvasGenerateNode };
 
 function resolveModel(providers, want) {
   const byProvider = want && want.provider
@@ -2419,6 +2925,17 @@ export function apply(ctx) {
       );
     }
 
+    /** 懒加载导演台引擎（纯 ESM 函数/常量，无 DOM 依赖），供导演台工具读取姿态/动作清单。 */
+    let _directorEngine = null;
+    const loadDirectorEngine = async () => {
+      if (_directorEngine) return _directorEngine;
+      try {
+        const url = new URL('./assets/director/engine.js', import.meta.url).href;
+        _directorEngine = await import(url);
+      } catch { _directorEngine = null; }
+      return _directorEngine;
+    };
+
     const methods = {
       async ping() { return { ok: true, version: VERSION }; },
       async llmOptions() { return listLlmOptions(); },
@@ -2455,6 +2972,30 @@ export function apply(ctx) {
        *  客户端知道自己要删哪个项目，Host 按项目物理文件夹定位（与 projectDirGet 同一基准），
        *  只删 projects/<folder>/craft 这一个子目录——绝不碰项目镜像、其他项目、数据根其他内容。
        *  幂等：目录不存在也是成功；失败可见（removed=false + reason），不静默吞。 */
+      /** 导演台场景规格：AI / 脚本写入，客户端打开导演台时自动套用（存 <projectDir>/craft/director-stage.json）。 */
+      async directorStageSave(args) {
+        const dir = await methods.projectDirGet({ projectId: args && args.projectId });
+        if (!dir || !dir.ok) return { ok: false, error: (dir && dir.error) || '项目目录不可用' };
+        const craftDir = path.join(dir.abs, 'craft');
+        try { mkdirSync(craftDir, { recursive: true }); } catch { /* 交给写入报错 */ }
+        const file = path.join(craftDir, 'director-stage.json');
+        const spec = (args && args.spec) || null;
+        if (!spec || typeof spec !== 'object') return { ok: false, error: '缺少 spec 对象' };
+        const payload = { ok: true, savedAt: Date.now(), spec };
+        try { writeFileSync(file, JSON.stringify(payload, null, 2), 'utf8'); }
+        catch (e) { return { ok: false, error: '写入失败: ' + String((e && e.message) || e) }; }
+        return { ok: true, projectId: String(args.projectId), file, bytes: Buffer.byteLength(JSON.stringify(payload)) };
+      },
+      async directorStageLoad(args) {
+        const dir = await methods.projectDirGet({ projectId: args && args.projectId });
+        if (!dir || !dir.ok) return { ok: false, error: (dir && dir.error) || '项目目录不可用' };
+        const file = path.join(dir.abs, 'craft', 'director-stage.json');
+        if (!existsSync(file)) return { ok: true, found: false, file };
+        try {
+          const doc = JSON.parse(readFileSync(file, 'utf8'));
+          return { ok: true, found: true, file, savedAt: doc.savedAt || null, spec: doc.spec || null };
+        } catch (e) { return { ok: false, found: false, file, error: '读取失败: ' + String((e && e.message) || e) }; }
+      },
       async projectCraftRemove(args) {
         const root = dataRoot();
         const pid = String((args && args.projectId) || '');
@@ -2627,6 +3168,10 @@ export function apply(ctx) {
       async canvasRunNode(args) { return canvasRunNode(args); },
       async canvasNodeStatus(args) { return canvasNodeStatus(args); },
       async canvasOpen(args) { return canvasOpen(args); },
+      async canvasesList(args) { return canvasesList(args); },
+      async canvasCreate(args) { return canvasCreate(args); },
+      async canvasRename(args) { return canvasRename(args); },
+      async canvasDelete(args) { return canvasDelete(args); },
       async assetDelete(args) {
         const id = String((args && args.id) || '');
         if (!id) return { ok: true };
@@ -2717,7 +3262,7 @@ export function apply(ctx) {
         };
         reg({
           name: 'canvas_list_projects',
-          description: '列出无限画布的项目及其节点（节点 id/类型/名称/状态）。用户提到画布项目、想看有哪些项目、或要指定某个项目/节点时使用。',
+          description: '列出无限画布的项目、每个项目下的画布（多画布：默认画布 + 子画布）及其节点（节点 id/类型/名称/状态）。用户提到画布项目、想看有哪些项目/画布、或要指定某个项目/画布/节点时使用。子画布用 canvasId 标识（缺省 = 默认画布）。',
           parameters: { type: 'object', properties: { keyword: { type: 'string', description: '按项目名称过滤（可选）' } }, additionalProperties: false },
           output: {
             schema: { type: 'object', properties: { count: { type: 'integer' }, text: { type: 'string' } }, required: ['count', 'text'] },
@@ -2729,8 +3274,13 @@ export function apply(ctx) {
             const list = projectsList().filter((p) => !kw || String(p.name).toLowerCase().includes(kw));
             const lines = [];
             for (const p of list) {
-              lines.push('- 「' + p.name + '」 id=' + p.id + ' · ' + p.nodes.length + ' 节点 · 更新于 ' + new Date(p.updatedAt).toLocaleString());
+              const canvases = Array.isArray(p.canvases) ? p.canvases : [];
+              const defTxt = p.defaultCanvasDeleted
+                ? '默认画布已删除'
+                : '默认画布「' + (p.defaultCanvasName || '默认画布') + '」canvasId=null';
+              lines.push('- 「' + p.name + '」 id=' + p.id + ' · ' + defTxt + ' · ' + canvases.length + ' 个子画布 · ' + p.nodes.length + ' 节点 · 更新于 ' + new Date(p.updatedAt).toLocaleString());
               for (const n of p.nodes) lines.push('    · [' + n.type + '] ' + (n.label || '(未命名)') + ' id=' + n.id + ' status=' + n.status);
+              for (const c of canvases) lines.push('    ▸ 画布「' + (c.name || c.id) + '」 canvasId=' + c.id + '（用 canvasId 参数指定；资产与设定集按项目共享）');
             }
             const text = lines.length ? ('共 ' + list.length + ' 个项目：\n' + lines.join('\n')) : '画布上还没有项目。可调用 canvas_create_project 创建。';
             return { count: list.length, text };
@@ -2767,6 +3317,7 @@ export function apply(ctx) {
             type: 'object',
             properties: {
               projectId: { type: 'string', description: '项目 id（来自 canvas_list_projects 或 canvas_create_project）' },
+              canvasId: { type: 'string', description: '可选：画布 id（项目下子画布；缺省 = 项目默认画布。多画布项目必须显式指定目标画布）' },
               text: { type: 'string', description: '要写入的内容（按 target 与节点类型决定写哪里）' },
               kind: { type: 'string', enum: ['script', 'text'], description: '新节点类型：script=剧本（默认），text=纯文本' },
               target: { type: 'string', enum: ['idea', 'output'], description: '写哪一部分：idea=提示词/创作意图（默认），output=成稿' },
@@ -2793,6 +3344,7 @@ export function apply(ctx) {
             type: 'object',
             properties: {
               projectId: { type: 'string', description: '项目 id' },
+              canvasId: { type: 'string', description: '可选：画布 id（项目下的子画布；缺省 = 项目默认画布。来自 canvas_list_projects 的画布清单）' },
               nodeId: { type: 'string', description: '节点 id（来自 canvas_list_projects）' },
             },
             required: ['projectId', 'nodeId'],
@@ -2812,13 +3364,14 @@ export function apply(ctx) {
             type: 'object',
             properties: {
               projectId: { type: 'string', description: '项目 id' },
+              canvasId: { type: 'string', description: '可选：画布 id（项目下的子画布；缺省 = 项目默认画布）' },
               nodeId: { type: 'string', description: '节点 id' },
             },
             required: ['projectId', 'nodeId'],
             additionalProperties: false,
           },
           output: {
-            schema: { type: 'object', properties: { ok: { type: 'boolean' }, text: { type: 'string' }, status: { type: 'string' }, assetId: { type: 'string' }, prompt: { type: 'string' }, ratio: { type: 'string' }, size: { type: 'string' }, duration: { type: 'number' }, resolution: { type: 'string' }, frameMode: { type: 'string' }, imageModel: { type: 'string' }, videoModel: { type: 'string' }, genWarn: { type: 'string' }, chainFrom: { type: 'string' }, seam: { type: 'object', properties: { ok: { type: 'boolean' }, sim: { type: 'number' }, thr: { type: 'number' }, note: { type: 'string' } } }, tailPickAssetId: { type: 'string' }, historyAssetIds: { type: 'array', items: { type: 'string' } }, warnings: { type: 'array', items: { type: 'string' } }, shots: { type: 'array', items: { type: 'object', properties: { index: { type: 'number' }, title: { type: 'string' }, duration: { type: 'number' }, visual: { type: 'string' }, motion: { type: 'string' }, tail: { type: 'string' }, cam: { type: 'string' }, start: { type: 'string' }, seg: { type: 'string' }, characters: { type: 'array', items: { type: 'string' } }, scene: { type: 'string' }, props: { type: 'array', items: { type: 'string' } } } } } }, required: ['ok', 'text'] },
+            schema: { type: 'object', properties: { ok: { type: 'boolean' }, text: { type: 'string' }, type: { type: 'string' }, status: { type: 'string' }, assetId: { type: 'string' }, prompt: { type: 'string' }, ratio: { type: 'string' }, size: { type: 'string' }, duration: { type: 'number' }, resolution: { type: 'string' }, frameMode: { type: 'string' }, imageModel: { type: 'string' }, videoModel: { type: 'string' }, genWarn: { type: 'string' }, chainFrom: { type: 'string' }, seam: { type: 'object', properties: { ok: { type: 'boolean' }, sim: { type: 'number' }, thr: { type: 'number' }, note: { type: 'string' } } }, tailPickAssetId: { type: 'string' }, historyAssetIds: { type: 'array', items: { type: 'string' } }, warnings: { type: 'array', items: { type: 'string' } }, shots: { type: 'array', items: { type: 'object', properties: { index: { type: 'number' }, title: { type: 'string' }, duration: { type: 'number' }, visual: { type: 'string' }, motion: { type: 'string' }, tail: { type: 'string' }, cam: { type: 'string' }, start: { type: 'string' }, seg: { type: 'string' }, characters: { type: 'array', items: { type: 'string' } }, scene: { type: 'string' }, props: { type: 'array', items: { type: 'string' } } } } } }, required: ['ok', 'text'] },
             render: (args, value) => [{ type: 'text', text: String(value.text || '') }],
           },
           timeoutMs: 30000,
@@ -2870,7 +3423,7 @@ export function apply(ctx) {
             if (s.seam) lines.push('接缝校验: ' + (s.seam.ok ? '通过' : '偏跳') + (s.seam.sim != null ? '（相似度 ' + s.seam.sim + '，阈值 ' + s.seam.thr + '）' : '') + (s.seam.note ? ' — ' + s.seam.note : ''));
             if (s.tailPick && s.tailPickAssetId) lines.push('尾帧最佳选帧: ' + Number(s.tailPick.t || 0).toFixed(2) + 's 处（得分 ' + s.tailPick.score + '）资产 ' + s.tailPickAssetId);
             return {
-              ok: true, status: s.status, assetId: s.assetId || undefined,
+              ok: true, type: s.type, status: s.status, assetId: s.assetId || undefined,
               prompt: s.prompt || undefined, ratio: s.ratio || undefined, size: s.size || undefined,
               duration: s.duration == null ? undefined : s.duration, resolution: s.resolution || undefined,
               frameMode: s.frameMode || undefined, imageModel: s.imageModel || undefined, videoModel: s.videoModel || undefined,
@@ -2890,12 +3443,13 @@ export function apply(ctx) {
             type: 'object',
             properties: {
               projectId: { type: 'string', description: '项目 id' },
+              canvasId: { type: 'string', description: '可选：画布 id（项目下的子画布；缺省 = 项目默认画布）' },
               nodeId: { type: 'string', description: '节点 id（来自 canvas_list_projects）' },
               patch: {
                 type: 'object',
                 description: '要修改的字段（只传需要改的，其余保持不动）',
                 properties: {
-                  prompt: { type: 'string', description: '图片/视频生成节点的提示词（对话框内容）' },
+                  prompt: { type: 'string', description: '图片/视频节点的提示词（对话框内容）' },
                   idea: { type: 'string', description: '剧本节点的创作意图' },
                   output: { type: 'string', description: '剧本节点的成稿' },
                   text: { type: 'string', description: '文本节点的正文' },
@@ -2934,6 +3488,7 @@ export function apply(ctx) {
             type: 'object',
             properties: {
               projectId: { type: 'string', description: '项目 id' },
+              canvasId: { type: 'string', description: '可选：画布 id（项目下的子画布；缺省 = 项目默认画布）' },
               nodeId: { type: 'string', description: '节点 id' },
               waitSeconds: { type: 'number', description: '可选：等待秒数（0=只触发；上限 600）' },
             },
@@ -2956,7 +3511,7 @@ export function apply(ctx) {
           description: '删除无限画布项目中的一个节点（连同它的连线）。用于清理误创建的节点。',
           parameters: {
             type: 'object',
-            properties: { projectId: { type: 'string', description: '项目 id' }, nodeId: { type: 'string', description: '节点 id' } },
+            properties: { projectId: { type: 'string', description: '项目 id' }, canvasId: { type: 'string', description: '可选：画布 id（缺省 = 项目默认画布）' }, nodeId: { type: 'string', description: '节点 id' } },
             required: ['projectId', 'nodeId'],
             additionalProperties: false,
           },
@@ -2972,7 +3527,7 @@ export function apply(ctx) {
           description: '一键重排画布节点布局（消除重叠）：按「行」排列——横向数据流决定列（文本→分镜表→视频→资产），竖向关系（衔接 prev / 首帧 frame）不参与分列；每行 = 一个横向连通组（如「场N文本 ↔ 场N分镜表」同行对齐），行高取行内最高节点、行间保留间距。节点重叠、或批量建点后布局混乱时调用。',
           parameters: {
             type: 'object',
-            properties: { projectId: { type: 'string', description: '项目 id' } },
+            properties: { projectId: { type: 'string', description: '项目 id' }, canvasId: { type: 'string', description: '可选：画布 id（缺省 = 项目默认画布）' } },
             required: ['projectId'],
             additionalProperties: false,
           },
@@ -2983,6 +3538,76 @@ export function apply(ctx) {
             return { ok: true, projectId: r.projectId, text: '✅ 已重排 ' + r.moved + ' 个节点（' + r.rows + ' 行，无重叠）。' };
           },
         });
+        reg({
+          name: 'canvas_director_stage',
+          description: '3D 导演台（预演场景）的总控工具：用一段 JSON 规格直接生成/更新整场预演，无需手动搭场景。\n' +
+            'action=apply：把 spec 写入项目并落盘（客户端打开导演台时自动套用；再点「导出视频」即得白模预演片）。\n' +
+            'action=get：读回当前项目的规格。\n' +
+            'action=help：返回规格 schema 与可用姿态/预设清单。\n' +
+            'spec 结构：{ title, duration, env{preset,bg,ground,grid,exposure,tonemap}, ' +
+            'characters[{name,pos:[x,y,z],rotY,h,pose,color,material{roughness,metallic,specular},path:[[x,z]...],pathFace,poseAnim[{t,pose}],loop,loopPeriod,keys[{t,pos,rotY}]}], ' +
+            'props[{preset,pos,scale,color}], cameras[{name,pos,target,fov,keys[{t,pos,target}]}], shots[{camera,start,end}] }。\n' +
+            'pose 取值见 action=help 的 poses；道具 preset 见 presets。坐标两维数组 [x,z] 自动补 y=0。',
+          parameters: {
+            type: 'object',
+            properties: {
+              action: { type: 'string', enum: ['apply', 'get', 'help', 'brief'], description: '操作类型' },
+              brief: { type: 'string', description: '一句话描述（action=brief 时用，如「两人在巷子里打斗，8秒」）；会套用打斗/追逐/对话模板生成规格并落盘' },
+              template: { type: 'string', enum: ['fight', 'chase', 'dialogue'], description: '强制指定模板（不传则按 brief 关键词自动判断）' },
+              duration: { type: 'number', description: '时长秒数（不传则从 brief 里抓「N秒」，否则用模板默认值）' },
+              projectId: { type: 'string', description: '项目 id' },
+              spec: { type: 'object', description: '场景规格（action=apply 时必填）' },
+            },
+            required: ['action'],
+            additionalProperties: false,
+          },
+          output: textOutput,
+          timeoutMs: 30000,
+          async execute(args) {
+            const action = String((args && args.action) || 'get');
+            if (action === 'help') {
+              const eng = await loadDirectorEngine();
+              return {
+                ok: true,
+                text: '✅ 导演台规格说明\n' +
+                  '· 姿态 id：none, arms_up, punch, kick, flip, fly(轻功), crouch(下蹲), fight, walk, run, jump, hit, fall, walk_a, walk_b, run_a, run_b\n' +
+                  '· 道具 preset：box, sphere, cylinder, cone, plane, capsule, torus, pyramid, disc, arc\n' +
+                  '· 循环动作：poseAnim 首尾 pose 相同即可循环（如 walk_a→walk_b→walk_a）\n' +
+                  '· 路径：path 为二维地面点数组，物体沿路径运动并按切线自动转向（pathFace:false 关闭）\n' +
+                  '· 角色一律使用资产库的真实关节人偶（assetId=xbot）：characters[].preset 可填 actors 列表里的体型，未填默认 m_standard',
+                poses: (eng && eng.BONE_POSES ? eng.BONE_POSES.map((p) => ({ id: p.id, zh: p.zh, en: p.en })) : []),
+                presets: ['box', 'sphere', 'cylinder', 'cone', 'plane', 'capsule', 'torus', 'pyramid', 'disc', 'arc'],
+                actors: (eng && eng.ACTOR_PRESETS ? eng.ACTOR_PRESETS.map((p) => ({ preset: p.id, zh: p.zh, en: p.en, h: p.h })) : []),
+                sequences: (eng && eng.ACTION_SEQUENCES ? eng.ACTION_SEQUENCES.map((s2) => ({ id: s2.id, zh: s2.zh, loop: !!s2.loop })) : []),
+              };
+            }
+            if (action === 'brief') {
+              const brief = String((args && args.brief) || '').trim();
+              if (!brief) throw new Error('action=brief 需要 brief 一句话描述');
+              const eng2 = await loadDirectorEngine();
+              if (!eng2 || typeof eng2.specFromBrief !== 'function') throw new Error('引擎未就绪');
+              const spec2 = eng2.specFromBrief(brief, { template: args.template, duration: args.duration });
+              const r4 = await methods.directorStageSave({ projectId: args.projectId, spec: spec2 });
+              if (!r4.ok) throw new Error(r4.error || '保存失败');
+              return {
+                ok: true, projectId: String(args.projectId || ''), spec: spec2,
+                text: '✅ 已按「' + (spec2.title || brief) + '」生成预演规格并写入项目（' + (spec2.characters || []).length + ' 角色 / ' + (spec2.cameras || []).length + ' 机位 / ' + (spec2.shots || []).length + ' 分镜 / ' + spec2.duration + 's）。打开或刷新 3D 导演台即可看到；点「导出视频」出片。',
+              };
+            }
+            if (action === 'get') {
+              const r2 = await methods.directorStageLoad({ projectId: args.projectId });
+              return { ok: !!r2.ok, projectId: String(args.projectId || ''), spec: r2.spec || undefined, text: r2.found ? '✅ 已读取导演台规格（savedAt=' + new Date(r2.savedAt || Date.now()).toISOString() + '）' : '（该项目还没有导演台规格）' };
+            }
+            if (!args || !args.spec || typeof args.spec !== 'object') throw new Error('action=apply 需要 spec 对象');
+            const r3 = await methods.directorStageSave({ projectId: args.projectId, spec: args.spec });
+            if (!r3.ok) throw new Error(r3.error || '保存失败');
+            return {
+              ok: true, projectId: String(args.projectId || ''), file: r3.file,
+              text: '✅ 导演台规格已写入（' + r3.bytes + ' 字节）。打开/刷新画布的 3D 导演台会自动套用该场景；点「导出视频」即可产出白模预演片。',
+            };
+          },
+        });
+
         reg({
           name: 'canvas_delete_project',
           description: '删除无限画布上的一个项目（含其全部节点）。用户明确要求删除项目、或清理误创建的空项目时使用；删除前请先用 canvas_list_projects 确认 id。',
@@ -3055,12 +3680,13 @@ export function apply(ctx) {
         });
         reg({
           name: 'canvas_create_node',
-          description: '在项目画布上新建指定类型的节点（image-gen 图片生成 / video-gen 视频生成 / storyboard 分镜表 / finalcut 成片 / script 剧本 / text 文本）。【分镜必须用 type:"storyboard" 的分镜表节点，绝不要用剧本节点装分镜】。【工作流铁律】实际生成由节点完成：你只负责写提示词、连线（connectFrom）、canvas_run_node 触发，不要把成稿直接填进 output。分镜表用 connectFrom 连到上游剧本节点（内容来自连线，不要复制剧本全文）；image-gen/video-gen 没有上游提示词时才在 prompt 里写内容，有上游时靠连线取。',
+          description: '在项目画布上新建指定类型的节点（image 图片节点 / video 视频节点 / storyboard 分镜表 / finalcut 成片 / script 剧本 / text 文本）。图片与视频是**合并节点**：有 assetId 就是已有素材（资产），空节点在画布上点开生成面板填写提示词后生成；旧类型名 image-gen / image-asset / video-gen / video-asset 仍可用，会被自动映射为 image / video。【分镜必须用 type:"storyboard" 的分镜表节点，绝不要用剧本节点装分镜】。【工作流铁律】实际生成由节点完成：你只负责写提示词、连线（connectFrom）、canvas_run_node 触发，不要把成稿直接填进 output。分镜表用 connectFrom 连到上游剧本节点（内容来自连线，不要复制剧本全文）；image/video 没有上游提示词时才在 prompt 里写内容，有上游时靠连线取。',
           parameters: {
             type: 'object',
             properties: {
               projectId: { type: 'string', description: '项目 id' },
-              type: { type: 'string', enum: ['script', 'text', 'image-gen', 'video-gen', 'storyboard', 'finalcut'], description: '节点类型' },
+              canvasId: { type: 'string', description: '可选：画布 id（项目下的子画布；缺省 = 项目默认画布）' },
+              type: { type: 'string', enum: ['script', 'text', 'image', 'video', 'storyboard', 'finalcut', 'image-gen', 'image-asset', 'video-gen', 'video-asset'], description: '节点类型（image/video 为合并类型；旧名 image-gen 等仍接受并自动映射）' },
               name: { type: 'string', description: '节点名字（建议填写，如"角色-陈拾 参考图"）' },
               prompt: { type: 'string', description: '提示词（图片/视频用画面提示词；剧本用创作意图；文本用正文）' },
               size: { type: 'string', description: '可选：图片清晰度 1K/2K/4K' },
@@ -3080,20 +3706,30 @@ export function apply(ctx) {
           timeoutMs: 30000,
           async execute(args) {
             const r = canvasCreateNode(args);
-            return { ok: true, projectId: r.projectId, nodeId: r.nodeId, label: r.label || undefined, text: '✅ 已新建[' + r.type + ']节点「' + (r.label || r.nodeId) + '」（id=' + r.nodeId + '）。可用 canvas_run_node 触发执行。' };
+            const kindHint = r.type === 'image'
+              ? '（图片节点：有 assetId 即资产；空节点在画布上点开生成面板写提示词后生成）'
+              : r.type === 'video'
+                ? '（视频节点：有 assetId 即资产；空节点在画布上点开生成面板写提示词后生成）'
+                : '';
+            return {
+              ok: true, projectId: r.projectId, nodeId: r.nodeId, label: r.label || undefined,
+              text: '✅ 已新建[' + r.type + ']节点「' + (r.label || r.nodeId) + '」（id=' + r.nodeId + '）。' + kindHint
+                + (r.mergedType ? '\n注：旧类型 ' + r.mergedType : '') + (r.note ? '\n' + r.note : ''),
+            };
           },
         });
         reg({
           name: 'canvas_connect',
-          description: '在项目画布上把两个节点连成工作流连线（剧本 → 分镜表 → 图片/视频 → 成片）。【工作流铁律】分镜表的内容来自连线的上游剧本节点，不要把剧本全文复制进分镜表节点；生成类节点（image-gen/video-gen）没有上游提示词时才在 prompt 里写内容，有上游时靠连线取。端口类型必须匹配（text→text、image→image、video→video），不匹配会报错；单线输入端口（script/prompt/frame/in）重复连线会替换旧线，ref 类端口允许多条。',
+          description: '在项目画布上把两个节点连成工作流连线（剧本 → 分镜表 → 图片/视频 → 成片）。【工作流铁律】分镜表的内容来自连线的上游剧本节点，不要把剧本全文复制进分镜表节点；图片/视频节点没有上游提示词时才在 prompt 里写内容，有上游时靠连线取。端口类型必须匹配（text→text、image→image、video→video），不匹配会报错；单线输入端口（script/prompt/frame/in）重复连线会替换旧线，ref 类端口允许多条。目标端口缺省时按语义自动选：文本→分镜表 script、分镜表→分镜表 prev、文本→图片/视频 prompt、图片→图片/视频 ref、视频→视频 frame / 成片 in。',
           parameters: {
             type: 'object',
             properties: {
               projectId: { type: 'string', description: '项目 id' },
+              canvasId: { type: 'string', description: '可选：画布 id（项目下的子画布；缺省 = 项目默认画布）' },
               fromNode: { type: 'string', description: '源节点 id（连出方）' },
               fromPort: { type: 'string', description: '可选：源端口，默认该节点第一个输出端口（剧本/文本/图片/视频都是 out）' },
               toNode: { type: 'string', description: '目标节点 id（连入方）' },
-              toPort: { type: 'string', description: '可选：目标端口，默认该节点第一个输入端口（分镜表=script、图片/视频=prompt、成片=in）' },
+              toPort: { type: 'string', description: '可选：目标端口，缺省按语义自动选择（分镜表=script/prev、图片=prompt/ref、视频=prompt/ref/frame、成片=in）' },
             },
             required: ['projectId', 'fromNode', 'toNode'],
             additionalProperties: false,
@@ -3108,7 +3744,7 @@ export function apply(ctx) {
         reg({
           name: 'canvas_open',
           description: '打开无限画布页面并跳到指定项目（画布侧会在几秒内自动切换）。用户想查看/编辑画布时使用。',
-          parameters: { type: 'object', properties: { projectId: { type: 'string', description: '要打开的项目 id（缺省只打开画布页）' } }, additionalProperties: false },
+          parameters: { type: 'object', properties: { projectId: { type: 'string', description: '要打开的项目 id（缺省只打开画布页）' }, canvasId: { type: 'string', description: '可选：要打开的画布 id（缺省 = 项目默认画布）' } }, additionalProperties: false },
           output: textOutput,
           timeoutMs: 30000,
           async execute(args) {
@@ -3278,7 +3914,7 @@ export function apply(ctx) {
         path: `/${NAME}/api/file`,
         async handler(req, res) {
           try {
-            if (req.method !== 'GET') { res.statusCode = 405; res.end('仅接受 GET'); return; }
+            if (req.method !== 'GET' && req.method !== 'HEAD') { res.statusCode = 405; res.end('仅接受 GET/HEAD'); return; }
             const root = dataRoot();
             if (!root) { res.statusCode = 404; res.end('未设置数据根目录'); return; }
             const u = new URL(req.url, 'http://localhost');
@@ -3291,6 +3927,13 @@ export function apply(ctx) {
             res.setHeader('content-type', mimeOf(abs));
             res.setHeader('accept-ranges', 'bytes');
             res.setHeader('cache-control', 'no-cache');
+            // HEAD：只回应元信息（node fetch HEAD 探针用），不读文件、不占解码/内存
+            if (req.method === 'HEAD') {
+              res.statusCode = 200;
+              res.setHeader('content-length', String(st.size));
+              res.end();
+              return;
+            }
             const m = /^bytes=(\d*)-(\d*)$/.exec(String(req.headers.range || ''));
             if (m && (m[1] !== '' || m[2] !== '')) {
               let start;
@@ -3317,6 +3960,45 @@ export function apply(ctx) {
           }
         },
       }),
+      // 视频静态封面（poster）落盘：body 为 jpeg/png 字节，写入 `<rel>.poster.jpg`。
+      // 有 poster 后画布视频节点默认只画一张 img（浏览器磁盘缓存、零视频解码），播放时才挂 <video>。
+      ctx.webServer.register({
+        kind: 'exact',
+        path: `/${NAME}/api/poster`,
+        async handler(req, res) {
+          res.setHeader('content-type', 'application/json; charset=utf-8');
+          try {
+            if (req.method !== 'POST' && req.method !== 'PUT') {
+              res.statusCode = 405;
+              res.end(JSON.stringify({ error: '仅接受 POST/PUT' }));
+              return;
+            }
+            const root = dataRoot();
+            if (!root) throw new Error('未设置数据根目录');
+            const u = new URL(req.url, 'http://localhost');
+            const rawRel = String(u.searchParams.get('rel') || '').trim();
+            if (!rawRel) throw new Error('缺少 rel');
+            if (/\.poster\.jpg$/i.test(rawRel)) throw new Error('rel 不应包含 poster 后缀');
+            const rel = physicalRel(rawRel) || rawRel; // 逻辑路径（pid）→ 物理路径（项目名文件夹）
+            const { abs, clean } = safeJoin(root, rel + '.poster.jpg'); // safeJoin 会拒绝 ../ 与绝对路径
+            mkdirSync(path.dirname(abs), { recursive: true });
+            const chunks = [];
+            let size = 0;
+            const MAX_POSTER = 8 * 1024 * 1024; // 封面只应是缩略 JPEG，8MB 足够且防无界写盘
+            for await (const c of req) {
+              size += c.length;
+              if (size > MAX_POSTER) { res.statusCode = 413; res.end(JSON.stringify({ error: 'poster 过大（上限 8MB）' })); return; }
+              chunks.push(c);
+            }
+            if (!size) throw new Error('poster 内容为空');
+            await fs.writeFile(abs, Buffer.concat(chunks));
+            res.end(JSON.stringify({ ok: true, rel: clean, size }));
+          } catch (e) {
+            res.statusCode = 400;
+            res.end(JSON.stringify({ error: String((e && e.message) || e) }));
+          }
+        },
+      }),
       // CAS 对象库读路径（0.18）：0.18.0–0.18.4 上传的媒体仍在 objects/ 里，必须继续可读。
       // IC-08 起写路径已退役（POST/PUT 一律 405），只有 GET。
       ctx.webServer.register({