dsh-drawai 0.3.0 → 0.3.1

package/lib/index.js

@@ -16,9 +16,13 @@
 
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises'
-import { existsSync, rmSync, writeFileSync, appendFileSync, renameSync } from 'node:fs'
-import { randomUUID } from 'node:crypto'
-import { isAbsolute, resolve as resolvePath, join as joinPath, dirname as dirnamePath, basename as basenamePath } from 'node:path'
+import { existsSync, rmSync, writeFileSync, appendFileSync, renameSync, realpathSync } from 'node:fs'
+import { randomUUID, createHash } from 'node:crypto'
+import { createDocumentCoordinator, createMediaWorkSlots } from './task-coordinator.js'
+import { createDrawingTaskManager } from './drawing-tasks.js'
+import { applyDrawingResult } from './drawing-results.js'
+import { createTaskPatchJournal, applyTaskPatches } from './task-patches.js'
+import { isAbsolute, resolve as resolvePath, join as joinPath, dirname as dirnamePath, basename as basenamePath, relative as relativePath } from 'node:path'
 import { createVideoTracePool } from './video-trace-pool.js'
 import { videoTraceOptions, exactVideoFrameKey } from './video-trace-reuse.js'
 import { createPerformanceLog } from './performance-log.js'
@@ -31,7 +35,6 @@ import {
   resolveTraceOptions,
   summarizeTraceForAi,
   toLosslessJson,
-  traceRasterToSvg,
   traceRasterForToolbar,
 } from './trace-image.js'
 import {
@@ -962,7 +965,7 @@ async function applyOps(doc, ops, out, opctx) {
       } catch (error) {
         throw new Error(where + ': ' + messageOf(error))
       }
-      const traced = traceRasterToSvg(tracedFrom, resolved.options)
+      const traced = await opctx.traceRaster(tracedFrom, resolved.options)
       const metrics = traced.metrics
       if (traced.svg.length > SVG_MARKUP_LIMIT) {
         throw new Error(
@@ -1874,8 +1877,8 @@ async function applyOps(doc, ops, out, opctx) {
             stills: stills.length,
             plan:
               plan !== null
-                ? Object.assign({}, plan, { note: '已把抽帧计划挂给画布：它在浏览器里解码视频写 stills/' })
-                : { every: every, max: max, note: '带上 seconds/fps/width 下发抽帧计划，浏览器会写入 stills/' },
+                ? Object.assign({}, plan, { note: '已交给宿主后台抽帧，完成后写入 stills/' })
+                : { every: every, max: max, note: '带上 seconds/fps/width 提交宿主抽帧任务' },
           })
           // 计划由 applyOps 收集、由外层挂到画布轮询上（见 diagram_apply 尾部）。
           if (plan !== null) out.extract = Object.assign({ clip: resolved.meta.clip }, plan)
@@ -1905,7 +1908,7 @@ async function applyOps(doc, ops, out, opctx) {
           throw new Error(where + ': ' + messageOf(error) + ' —— 先 extractFrames 下发抽帧计划并等待 stills/ 写出')
         }
         const raster = await decodeRaster(png)
-        const traced = traceRasterToSvg(raster, op)
+        const traced = await opctx.traceRaster(raster, op)
         if (traced.svg.length > MAX_FRAME_SVG_CHARS) {
           throw new Error(where + ': traced svg too long (' + traced.svg.length + ' > ' + MAX_FRAME_SVG_CHARS + ')')
         }
@@ -2665,6 +2668,7 @@ async function listCanvases(root, cwd, dir) {
 
 
 export function apply(ctx) {
+  const documents = createDocumentCoordinator(), mediaSlots = createMediaWorkSlots(2), taskPatches = createTaskPatchJournal()
   function sessionOf(sessionId) {
     try {
       if (typeof sessionId !== 'string' || sessionId.length === 0) return undefined
@@ -2755,6 +2759,8 @@ export function apply(ctx) {
       pageCount: parsed.pageCount,
       pageIndex: parsed.pageIndex,
       pageNames: parsed.pageNames,
+      pageId: parsed.pageId,
+      pageIds: parsed.pageIds,
     }
   }
 
@@ -3664,6 +3670,7 @@ export function apply(ctx) {
       const out = {}
       const opctx = {
         drawioPath: loaded.absolute,
+        traceRaster: (raster, options) => videoTracePool.runRaster(raster, { ...options, mode: 'raw-image' }),
         ensureClips: [],
         /**
          * traceImage 的图片读取：走**同一个工作区解析器**（相对路径按会话根解析），
@@ -3732,7 +3739,7 @@ export function apply(ctx) {
         exportRequests.set(sessionId, { requestId: requestId, absolute: loaded.absolute, format: out.export.format, name: out.export.name })
         exportResults.delete(sessionId)
       }
-      // 抽帧计划：同样挂成请求 —— 真正解码视频的是画布那一半（浏览器）。
+      // The host owns extraction; the browser receives status only.
       if (out.extract !== undefined && out.extract !== null) {
         const requestId = 'm' + Date.now().toString(36) + Math.random().toString(36).slice(2, 8)
         extractRequests.set(sessionId, {
@@ -3744,6 +3751,7 @@ export function apply(ctx) {
           fps: out.extract.fps,
           width: out.extract.width,
           max: out.extract.max,
+          host: true,
         })
         extractResults.delete(sessionId)
       }
@@ -3755,6 +3763,7 @@ export function apply(ctx) {
         Array.isArray(out.changed) && out.changed.length > 0 &&
         ops.some((op) => op !== null && typeof op === 'object' && (op.op === 'setMediaMeta' || op.op === 'importMedia' || op.op === 'setFrame' || op.op === 'traceFrame'))
       if (noDocEdit && mediaChangedDoc === false) {
+        if (out.extract) await startHostExtraction(sessionId, loaded, out.extract)
         // toLosslessJson：宿主对工具输出做 isJsonValue，自有属性值为 undefined / -0 会整次打回
         // （表现为 `returned invalid output: value is not lossless JSON`）。
         return toLosslessJson({
@@ -3809,6 +3818,7 @@ export function apply(ctx) {
       if (revertDepth(snapshotKey(sessionId, loaded.absolute)) > 0) {
         notes.push('↩ 这次改动可以退回（还能退 ' + revertDepth(snapshotKey(sessionId, loaded.absolute)) + ' 步）：界面上「编辑 → 撤销 AI 改动」')
       }
+      if (out.extract) await startHostExtraction(sessionId, loaded, out.extract)
       return toLosslessJson({
         path: loaded.absolute,
         revision: doc.revision,
@@ -4070,7 +4080,7 @@ function sanitizeNewName(raw) {
     }
     const done = extractResults.get(sessionId)
     if (done === undefined || done.absolute !== absolute) return undefined
-    if (done.error.length > 0) return { status: 'failed', clip: done.clip, written: done.written, error: done.error }
+    if (done.error?.length > 0) return { status: 'failed', clip: done.clip, written: done.written, error: done.error }
     return { status: 'done', clip: done.clip, written: done.written }
   }
 
@@ -4181,8 +4191,136 @@ function sanitizeNewName(raw) {
   // 临时复刻包只由持有本次令牌的会话管理，取消不触及已有媒体。
   const videoTraceJobs = new Map()
   const videoUploadJobs = new Map()
-  const videoExports = createVideoExportManager()
+  const videoExports = createVideoExportManager({ slots: mediaSlots })
   const videoTracePool = createVideoTracePool()
+  const drawingTasks = createDrawingTaskManager({ pool: videoTracePool, slots: mediaSlots,
+    commit: commitDrawingTask, undo: undoDrawingTask,
+    publishExtraction: (job, action) => documents.run(job.scope.drawioAbs, async () => {
+      const loaded = await loadTaskDocument(job)
+      const source = loaded.doc.nodes.find((node) => node.id === job.source.id)
+      if (videoMetaFromData(source?.data)?.clip !== job.source.clip) throw new Error('抽帧来源已更改，结果已保留在任务目录')
+      await checkVideoInput(job)
+      return action()
+    }),
+    extracted: (job, output) => {
+      extractRequests.delete(job.scope.sessionId)
+      extractResults.set(job.scope.sessionId, { absolute: job.scope.drawioAbs, clip: job.source.clip, written: output.written, taskId: job.id })
+    },
+    failed: (job) => {
+      if (job.kind === 'extract') {
+        extractRequests.delete(job.scope.sessionId)
+        extractResults.set(job.scope.sessionId, { absolute: job.scope.drawioAbs, clip: job.source.clip, written: job.done, error: job.error || '抽帧已取消' })
+      }
+    },
+  })
+  const signature = (value) => createHash('sha256').update(value).digest('hex')
+  const stableValue = (value) => JSON.stringify(value, (_key, item) => item && typeof item === 'object' && !Array.isArray(item)
+    ? Object.fromEntries(Object.keys(item).sort().map((key) => [key, item[key]])) : item)
+  async function loadTaskDocument(job) {
+    let loaded = await loadDoc(job.scope.drawioAbs, job.scope.sessionId, job.scope.page)
+    if (!loaded.exists) throw new Error('原画布已删除，结果已保留')
+    if (job.scope.pageId) {
+      const page = loaded.pageIds.indexOf(job.scope.pageId)
+      if (page < 0 || loaded.pageIds.filter((id) => id === job.scope.pageId).length !== 1) throw new Error('原页面已删除或身份冲突，结果已保留')
+      if (page !== loaded.pageIndex) loaded = await loadDoc(job.scope.drawioAbs, job.scope.sessionId, page)
+    } else if (JSON.stringify(loaded.pageNames) !== JSON.stringify(job.scope.pageNames)) throw new Error('页面身份已改变，结果已保留')
+    return loaded
+  }
+  async function writeTaskDocument(job, loaded, node, removed = []) {
+    const policy = policyFor(job.scope.sessionId)
+    if (policy?.mode === 'read-only') throw new Error('当前会话为只读，绘制结果已保留')
+    const rendered = renderDocText(loaded.text, loaded.doc, { page: loaded.pageIndex })
+    // The coordinator serializes plugin writers; a fresh check also detects
+    // external edits which happened while an asynchronous source check ran.
+    if (contentHash(await ctx.fs.readText(loaded.target)) !== contentHash(loaded.text)) throw new Error('文件已被其他编辑器修改，请重试加入结果')
+    const savedNode = node ? normalizeDoc(parseMxfile(rendered.text, { page: loaded.pageIndex }).doc).nodes.find((item) => item.id === node.id) : null
+    if (savedNode) drawingTasks.recordCommit(job, savedNode)
+    await ctx.fs.writeText(loaded.target, rendered.text, undefined, undefined, policy)
+    taskPatches.record(loaded.absolute, contentHash(loaded.text), rendered.revision, loaded.pageIndex, savedNode ? [savedNode] : [], removed, removed.length && job.createdNode ? [job.createdNode] : [])
+    return { nodeId: savedNode?.id, node: savedNode, page: loaded.pageIndex }
+  }
+  async function commitDrawingTask(job, output) {
+    return documents.run(job.scope.drawioAbs, async () => {
+      const loaded = await loadTaskDocument(job)
+      const existing = loaded.doc.nodes.find((node) => node.data?.drawaiTaskId === job.id)
+      if (existing) return { nodeId: existing.id, node: job.createdNode, page: loaded.pageIndex }
+      const source = loaded.doc.nodes.find((node) => node.id === job.source.id)
+      if (!source) throw new Error('来源节点已删除，结果已保留')
+      const image = job.kind === 'image' ? imageValueFromStyle(source.style || '') : ''
+      if (job.kind === 'image' && signature(image) !== job.source.signature) throw new Error('原图已更改，结果已保留')
+      if (job.kind === 'video') {
+        await checkVideoInput(job)
+      }
+      const node = applyDrawingResult(loaded.doc, { ...job, source: { ...job.source, image } }, output)
+      loaded.doc.meta = { ...loaded.doc.meta, pinned: true }
+      return writeTaskDocument(job, loaded, node)
+    })
+  }
+  async function checkVideoInput(job) {
+    const dir = clipDirFor(job.scope.drawioAbs, job.source.clip), original = findSourceFile(dir, readManifest(dir))
+    if (!original) throw new Error('原视频已删除，结果已保留')
+    const rel = relativePath(realpathSync(dir), realpathSync(original.abs))
+    if (isAbsolute(rel) || rel.startsWith('..') || signature(await readFile(original.abs)) !== job.inputHash) throw new Error('原视频内容或路径已更改，结果已保留')
+  }
+  async function undoDrawingTask(job) {
+    return documents.run(job.scope.drawioAbs, async () => {
+      const loaded = await loadTaskDocument(job)
+      const node = loaded.doc.nodes.find((item) => item.data?.drawaiTaskId === job.id)
+      if (!node) return
+      if (stableValue(node) !== stableValue(job.createdNode)) throw new Error('生成节点已被修改，请在画布中撤销或删除，避免丢失后续编辑')
+      if (loaded.doc.edges.some((edge) => edge.from === node.id || edge.to === node.id)) throw new Error('生成节点已连接新连线，请在画布中处理')
+      loaded.doc.nodes = loaded.doc.nodes.filter((item) => item.id !== node.id)
+      loaded.doc.drawOrder = (loaded.doc.drawOrder || []).filter((id) => id !== node.id)
+      await writeTaskDocument(job, loaded, null, [node.id])
+    })
+  }
+  async function enqueueDrawing(scope, body) {
+    return documents.run(scope.drawioAbs, async () => {
+      if (policyFor(scope.sessionId)?.mode === 'read-only') throw new Error('当前会话为只读，无法创建绘制任务')
+      if (!Number.isInteger(body.page ?? 0) || (body.page ?? 0) < 0) throw new Error('页面位置无效')
+      const loaded = await loadDoc(scope.drawioAbs, scope.sessionId, body.page || 0)
+      if (loaded.pageIndex !== (body.page || 0)) throw new Error('页面已不存在')
+      if (!loaded.exists) throw new Error('请先创建画布')
+      if (body.revision && body.revision !== loaded.doc.revision) throw new Error('画布版本已更新，请等待同步后重试')
+      const kind = body.kind
+      if (!['image', 'video', 'extract'].includes(kind)) throw new Error('未知绘制类型')
+      const source = loaded.doc.nodes.find((node) => node.id === body.sourceId)
+      if (!source) throw new Error('来源节点不存在')
+      const options = { level: 'medium', preset: 'default', colors: 12, removeBg: false, ...(body.options || {}) }
+      if (!['low', 'medium', 'high'].includes(options.level) || !TRACE_PRESET_NAMES.includes(options.preset) ||
+          !Number.isInteger(Number(options.colors)) || options.colors < 2 || options.colors > 24 || typeof options.removeBg !== 'boolean') throw new Error('绘制参数无效')
+      const taskScope = { ...scope, page: loaded.pageIndex, pageId: loaded.pageId, pageNames: loaded.pageNames,
+        pageName: loaded.pageNames[loaded.pageIndex] }
+      let input, taskSource
+      if (kind === 'image') {
+        const image = imageValueFromStyle(source.style || '')
+        if (!isRasterDataUri(image)) throw new Error('请选择位图来源')
+        input = Buffer.from(image.slice(image.indexOf(',') + 1), 'base64')
+        taskSource = { id: source.id, signature: signature(image) }
+      } else {
+        const meta = videoMetaFromData(source.data)
+        if (meta?.kind !== 'raster') throw new Error('请选择原视频来源')
+        const dir = clipDirFor(scope.drawioAbs, meta.clip), original = findSourceFile(dir, readManifest(dir))
+        if (!original) throw new Error('原视频文件缺失')
+        const mediaRel = relativePath(realpathSync(scope.workspaceRoot), realpathSync(dir))
+        if (isAbsolute(mediaRel) || mediaRel.startsWith('..')) throw new Error('视频媒体目录超出工作区')
+        const file = realpathSync(original.abs), rel = relativePath(realpathSync(dir), file)
+        if (isAbsolute(rel) || rel.startsWith('..')) throw new Error('原视频路径超出媒体包')
+        input = file
+        taskSource = { id: source.id, clip: meta.clip, extension: /\.[a-z0-9]+$/i.exec(file)?.[0] || '.mp4', signature: meta.clip + ':' + signature(await readFile(file)) }
+      }
+      return drawingTasks.enqueue(taskScope, { kind, options, source: taskSource, label: source.label || (kind === 'image' ? '图片' : '视频') + ' · ' + source.id }, input)
+    })
+  }
+  async function startHostExtraction(sessionId, loaded, plan) {
+    const current = await loadDoc(loaded.absolute, sessionId, loaded.pageIndex)
+    const source = current.doc.nodes.find((node) => videoMetaFromData(node.data)?.clip === plan.clip)
+    if (!source) throw new Error('抽帧来源节点已不存在')
+    const job = await enqueueDrawing({ sessionId, path: loaded.absolute, drawioAbs: loaded.absolute, workspaceRoot: workspaceRootOf(sessionId) },
+      { kind: 'extract', sourceId: source.id, page: current.pageIndex, options: { ...plan, range: 'segment' } })
+    const pending = extractRequests.get(sessionId)
+    if (pending) pending.taskId = job.id
+  }
   const wakeVideoTrace = (job) => {
     const waiters = job.waiters || []
     job.waiters = []
@@ -4215,9 +4353,8 @@ function sanitizeNewName(raw) {
       job.cancelled = true
       wakeVideoTrace(job)
     }
-    videoTracePool.close()
     videoTraceJobs.clear(); videoUploadJobs.clear()
-    return videoExports.dispose()
+    return Promise.all([drawingTasks.close(), videoExports.dispose()]).finally(() => videoTracePool.close())
   })
   async function handleSave(req, res) {
     if (req.method !== 'POST') {
@@ -4269,9 +4406,35 @@ function sanitizeNewName(raw) {
       return
     }
 
+    try {
+      const lockAction = body.action === undefined || ['create', 'revert', 'media-cleanup', 'media-video-export-start'].includes(body.action)
+      if (lockAction && typeof (body.path || body.name) === 'string' && workspaceRootOf(body.sessionId)) {
+        const target = await resolveTarget(body.path || body.name, body.sessionId)
+        return await documents.run(absoluteHint(target, body.path || body.name), () => dispatchSave(body, res))
+      }
+      return await dispatchSave(body, res)
+    } catch (error) { sendJson(res, 400, { ok: false, error: messageOf(error) }) }
+  }
+
+  async function dispatchSave(body, res) {
+
     const sessionId = typeof body.sessionId === 'string' ? body.sessionId : undefined
     const rawPath = typeof body.path === 'string' ? body.path : undefined
 
+    if (typeof body.action === 'string' && body.action.startsWith('drawing-task-')) {
+      if (!sessionOf(sessionId) || !workspaceRootOf(sessionId) || !rawPath?.toLowerCase().endsWith('.drawio')) throw new Error('绘制任务需要当前工作区画布')
+      const target = await resolveTarget(rawPath, sessionId), root = workspaceRootOf(sessionId)
+      if (!ctx.fs.contains(await ctx.fs.resolve(root), target)) throw new Error('画布路径超出工作区')
+      const scope = { sessionId, path: rawPath, drawioAbs: absoluteHint(target, rawPath), workspaceRoot: root }
+      let result
+      if (body.action === 'drawing-task-start') result = { job: await enqueueDrawing(scope, body) }
+      else if (body.action === 'drawing-task-list') result = { jobs: drawingTasks.list(scope) }
+      else if (body.action === 'drawing-task-result') result = drawingTasks.result(scope, body.taskId)
+      else if (body.action === 'drawing-task-command') result = { job: await drawingTasks.command(scope, body.taskId, body.command, body.value) }
+      else throw new Error('未知绘制任务操作')
+      sendJson(res, 200, { ok: true, ...result }); return
+    }
+
     // 仅计算图像节点的 SVG；由客户端通过同一历史/保存通道应用结果。
     if (body.action === 'trace-node-image') {
       if (sessionId === undefined || sessionOf(sessionId) === undefined || workspaceRootOf(sessionId) === undefined) {
@@ -4449,7 +4612,7 @@ function sanitizeNewName(raw) {
         // AI 下发的抽帧计划同理：画布取走后用浏览器解码视频、写 stills/，完成后 POST 回 media-extract-result。
         const pendingExtract = extractRequests.get(sessionId)
         const extractForThis =
-          pendingExtract !== undefined && pendingExtract.absolute === loaded.absolute
+          pendingExtract !== undefined && !pendingExtract.host && pendingExtract.absolute === loaded.absolute
             ? {
                 requestId: pendingExtract.requestId,
                 clip: pendingExtract.clip,
@@ -4471,6 +4634,8 @@ function sanitizeNewName(raw) {
           pageCount: loaded.pageCount,
           pageIndex: loaded.pageIndex,
           pageNames: loaded.pageNames,
+          backgroundPatch: typeof body.revision === 'string' && body.revision !== loaded.doc.revision
+            ? taskPatches.between(loaded.absolute, body.revision, loaded.doc.revision, loaded.pageIndex) : null,
           highlight: Array.isArray(pendingHighlight) ? pendingHighlight : [],
           canRevert: revertDepth(snapshotKey(sessionId, loaded.absolute)) > 0,
           // 用户当前的选区（客户端可选地用来做提示；AI 侧由工具读回）。
@@ -4589,10 +4754,12 @@ function sanitizeNewName(raw) {
       }
       let revertTarget
       let revertAbsolute
+      let revertCurrent
       try {
         const loaded = await loadDoc(rawPath, sessionId)
         revertTarget = loaded.target
         revertAbsolute = loaded.absolute
+        revertCurrent = loaded.text
       } catch (error) {
         sendJson(res, 400, { ok: false, error: '这个文件读不出画布：' + messageOf(error) })
         return
@@ -4604,6 +4771,16 @@ function sanitizeNewName(raw) {
         sendJson(res, 200, { ok: false, error: '这张画布没有可退回的 AI 改动了' })
         return
       }
+      if (contentHash(revertCurrent) !== snapshot.revision) {
+        const taskNodes = (text) => {
+          const first = parseMxfile(text), nodes = []
+          for (let page = 0; page < first.pageCount; page++) nodes.push(...parseMxfile(text, { page }).doc.nodes.filter((node) => node.data?.drawaiTaskId))
+          return nodes
+        }
+        if (stableValue(taskNodes(revertCurrent)) !== stableValue(taskNodes(snapshot.text))) {
+          sendJson(res, 409, { ok: false, error: 'AI 改动后已有后台生成或编辑的结果，请先在任务队列中撤销生成，避免整页回退丢失结果' }); return
+        }
+      }
       const policy = policyFor(sessionId)
       try {
         if (policy === undefined) await ctx.fs.writeText(revertTarget, snapshot.text)
@@ -4907,8 +5084,7 @@ function sanitizeNewName(raw) {
           let result
           switch (body.action) {
             case 'media-video-export-start': result = await videoExports.start(scope, body.format); break
-            case 'media-video-export-chunk': result = videoExports.chunk(scope, body); break
-            case 'media-video-export-frame': result = videoExports.frame(scope, body); break
+            case 'media-video-export-list': result = { jobs: videoExports.list(scope) }; break
             case 'media-video-export-finish': result = videoExports.finish(scope, body.token); break
             case 'media-video-export-status': result = videoExports.status(scope, body.token); break
             case 'media-video-export-read': result = videoExports.read(scope, body.token, body.offset); break
@@ -5336,8 +5512,15 @@ function sanitizeNewName(raw) {
           return
         }
         if (body.action === 'media-cleanup') {
-          const doc = body.doc
-          const removed = cleanupUnreferencedClips(drawioAbs, doc)
+          const current = await loadDoc(drawioAbs, sessionId, 0)
+          const nodes = [...(body.doc?.nodes || [])]
+          for (let page = 0; page < current.pageNames.length; page++) {
+            const parsed = page === 0 ? current : await loadDoc(drawioAbs, sessionId, page)
+            nodes.push(...parsed.doc.nodes)
+          }
+          const leases = new Set([...drawingTasks.leases(drawioAbs, { workspaceRoot: mediaRoot }), ...videoExports.leases(drawioAbs)])
+          for (const job of videoTraceJobs.values()) if (job.drawioAbs === drawioAbs) leases.add(job.clip)
+          const removed = cleanupUnreferencedClips(drawioAbs, { nodes }, leases)
           sendJson(res, 200, { ok: true, removed: removed })
           return
         }
@@ -5508,14 +5691,18 @@ function sanitizeNewName(raw) {
       sendJson(res, 409, { ok: false, error: 'already exists', path: absolute })
       return
     }
+    let backgroundPatch = null
     if (baseRevision !== undefined && exists && contentHash(originalText) !== baseRevision) {
-      sendJson(res, 409, { ok: false, error: 'revision conflict', currentRevision: contentHash(originalText) })
-      return
+      backgroundPatch = taskPatches.between(absolute, baseRevision, contentHash(originalText), Number(body.page) || 0)
+      if (!backgroundPatch) {
+        sendJson(res, 409, { ok: false, error: 'revision conflict', currentRevision: contentHash(originalText) }); return
+      }
     }
 
     // 人工编辑一律打 pinned：从此这张画布是人摆过版面的，AI 的自动布局不该再冲掉它。
     // （空文件 → 从零生成；已有文件 → 无损写回，见 renderDocText。）
     const next = normalizeDoc(doc)
+    if (backgroundPatch) applyTaskPatches(next, backgroundPatch, true)
     next.meta = Object.assign({}, next.meta, { pinned: true })
     let rendered
     try {
@@ -5544,13 +5731,18 @@ function sanitizeNewName(raw) {
         // 媒体复制失败不回滚画布写入：海报仍在；播放时会报媒体包缺失。
       }
     }
-    sendJson(res, 200, { ok: true, revision: rendered.revision, path: absolute, dropped: rendered.dropped })
+    sendJson(res, 200, { ok: true, revision: rendered.revision, path: absolute, dropped: rendered.dropped, ...(backgroundPatch ? { backgroundPatch } : {}) })
   }
 
   ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: SAVE_PATH, handler: handleSave }), 'drawai: ' + SAVE_PATH)
 
   ctx.effect(() => ctx.tools.register(readTool))
-  ctx.effect(() => ctx.tools.register(applyTool))
+  ctx.effect(() => ctx.tools.register({ ...applyTool, execute: async (args, exec) => {
+    const sessionId = sessionIdOf(exec)
+    const path = typeof args.path === 'string' && args.path ? args.path : focusedPathFor(sessionId) || DEFAULT_PATH
+    const target = await resolveTarget(path, sessionId)
+    return documents.run(absoluteHint(target, path), () => applyTool.execute(args, exec))
+  } }))
 
   // 把"怎么用这张画布"注册成**内嵌技能**（见 SKILL_BODY 的注释）：
   // 换了电脑、只装了插件（没有源码/README/tools）时，模型依然知道该怎么操作。

package/lib/media.js

@@ -209,7 +209,9 @@ export function readManifest(clipDir) {
 export function writeManifest(clipDir, manifest) {
   mkdirSync(clipDir, { recursive: true })
   const next = syncDuration(normalizeManifest(manifest))
-  writeFileSync(join(clipDir, MANIFEST_NAME), JSON.stringify(next, null, 2) + '\n', 'utf8')
+  const path = join(clipDir, MANIFEST_NAME)
+  writeFileSync(path + '.tmp', JSON.stringify(next, null, 2) + '\n', 'utf8')
+  renameSync(path + '.tmp', path)
   return next
 }
 
@@ -399,8 +401,9 @@ export function collectReferencedClips(doc) {
   return used
 }
 
-export function cleanupUnreferencedClips(drawioPath, doc) {
+export function cleanupUnreferencedClips(drawioPath, doc, protectedClips = []) {
   const used = collectReferencedClips(doc)
+  for (const clip of protectedClips) used.add(clip)
   const all = listClipIds(drawioPath)
   const removed = []
   for (let i = 0; i < all.length; i += 1) {

package/lib/mxfile.js

@@ -532,6 +532,7 @@ function analyzeMxfile(source, pageIndex) {
     pageCount: diagrams.length,
     pageIndex: idx,
     pageNames: pageNames,
+    pageIds: diagrams.map((item) => attr(item[1], 'id') || null),
     // 纸张尺寸（drawio 挂在 `mxGraphModel` 上的属性）：AI 做布局/导出建议时要看它 ——
     // 850×1100 是 drawio 的 A4 竖版缺省，但不代表用户这份文件就是那个尺寸。
     pageSize: readPageSize(modelXml),
@@ -975,7 +976,8 @@ export function parseMxfile(text, options) {
   if (existing !== null && existing.meta !== undefined && existing.meta !== null && existing.meta.pinned === true) {
     doc.meta.pinned = true
   }
-  return { doc: doc, notes: notes, pageCount: pageCount, pageIndex: info.pageIndex, pageNames: info.pageNames }
+  return { doc: doc, notes: notes, pageCount: pageCount, pageIndex: info.pageIndex, pageNames: info.pageNames,
+    pageId: (info.pageIds || [])[info.pageIndex] || null, pageIds: info.pageIds || [null] }
 }
 
 // ---- 单元的 XML 生成（新单元、以及从零生成一份文件时共用）--------------------

package/lib/performance-log.js

@@ -11,7 +11,7 @@ function environmentInfo() {
   if (!environment) {
     const cpu = cpus()
     let sourceSha256 = null
-    try { sourceSha256 = createHash('sha256').update(['trace-image.js', 'raster.js', 'video-trace-worker.js', 'video-trace-pool.js', 'video-trace-reuse.js', 'video-export.js']
+    try { sourceSha256 = createHash('sha256').update(['trace-image.js', 'raster.js', 'video-trace-worker.js', 'video-trace-pool.js', 'video-trace-reuse.js', 'video-export.js', 'video-export-worker.js']
       .map((file) => readFileSync(new URL(file, import.meta.url))).join('')).digest('hex') } catch {}
     environment = { node: process.version, platform: process.platform, arch: process.arch, cpu: cpu[0]?.model,
       logicalCpus: cpu.length, totalMemoryBytes: totalmem(), sourceSha256 }

package/lib/task-coordinator.js

@@ -0,0 +1,54 @@
+/* 由 tools/build.mjs 生成 —— 请勿直接编辑；改 src/ 下的源文件。 */
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { resolve } from 'node:path'
+import { realpathSync } from 'node:fs'
+
+export function createDocumentCoordinator() {
+  const tails = new Map(), local = new AsyncLocalStorage()
+  const keyOf = (path) => {
+    let key = resolve(path)
+    try { key = realpathSync(key) } catch {}
+    return process.platform === 'win32' ? key.toLowerCase() : key
+  }
+  return { keyOf, async run(path, action) {
+    const key = keyOf(path)
+    if (local.getStore() === key) return action()
+    const previous = tails.get(key) || Promise.resolve()
+    let release
+    const gate = new Promise((resolve) => { release = resolve })
+    const tail = previous.catch(() => {}).then(() => gate)
+    tails.set(key, tail)
+    await previous.catch(() => {})
+    try { return await local.run(key, action) }
+    finally { release(); if (tails.get(key) === tail) tails.delete(key) }
+  } }
+}
+
+// A shared, abortable budget for user-level drawing and export jobs. Individual
+// drawing tasks reuse the existing bounded frame Worker pool.
+export function createMediaWorkSlots(limit = 2) {
+  let active = 0
+  const queue = []
+  function pump() {
+    while (active < limit && queue.length) {
+      const item = queue.shift()
+      item.signal?.removeEventListener('abort', item.abort)
+      if (item.signal?.aborted) { item.reject(new Error('已取消任务')); continue }
+      active++
+      let released = false
+      item.resolve(() => { if (!released) { released = true; active--; pump() } })
+    }
+  }
+  return { acquire(signal) {
+    return new Promise((resolve, reject) => {
+      const item = { signal, resolve, reject, abort: () => {
+        const index = queue.indexOf(item)
+        if (index >= 0) queue.splice(index, 1)
+        reject(new Error('已取消任务'))
+      } }
+      if (signal?.aborted) { reject(new Error('已取消任务')); return }
+      signal?.addEventListener('abort', item.abort, { once: true })
+      queue.push(item); pump()
+    })
+  } }
+}

package/lib/task-patches.js

@@ -0,0 +1,59 @@
+/* 由 tools/build.mjs 生成 —— 请勿直接编辑；改 src/ 下的源文件。 */
+import { createHash } from 'node:crypto'
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+// Rebase only changes known to consist of generated-node patches. Unknown
+// edits remain revision conflicts, never a license to overwrite a snapshot.
+export function createTaskPatchJournal() {
+  const cache = new Map()
+  const fileOf = (path) => join(dirname(path), '.drawai-cache', 'task-patches', createHash('sha256').update(path.toLowerCase()).digest('hex') + '.json')
+  function entries(path) {
+    if (!cache.has(path)) {
+      let values = []
+      try { values = JSON.parse(readFileSync(fileOf(path), 'utf8')) } catch {}
+      cache.set(path, Array.isArray(values) ? values.slice(-32) : [])
+    }
+    return cache.get(path)
+  }
+  return {
+    record(path, from, to, page, added = [], removed = [], removedNodes = []) {
+      const list = entries(path); list.push({ from, to, page, added, removed, removedNodes }); if (list.length > 32) list.shift()
+      const file = fileOf(path); mkdirSync(dirname(file), { recursive: true })
+      writeFileSync(file + '.tmp', JSON.stringify(list)); renameSync(file + '.tmp', file)
+    },
+    between(path, from, to, page) {
+      const list = entries(path), changes = []; let revision = from
+      for (let attempt = 0; revision !== to && attempt < 32; attempt++) {
+        const entry = list.find((item) => item.from === revision)
+        if (!entry) return null
+        if (entry.page === page) changes.push(entry)
+        revision = entry.to
+      }
+      if (revision !== to) return null
+      return { added: changes.flatMap((item) => item.added), removed: changes.flatMap((item) => item.removed), changes }
+    },
+  }
+}
+
+export function applyTaskPatches(doc, patch, strict = false) {
+  const stable = (value) => JSON.stringify(value, (_key, item) => item && typeof item === 'object' && !Array.isArray(item)
+    ? Object.fromEntries(Object.keys(item).sort().map((key) => [key, item[key]])) : item)
+  for (const change of patch.changes || [patch]) {
+    const removed = new Set(change.removed || [])
+    if (strict) {
+      for (const before of change.removedNodes || []) {
+        const current = doc.nodes.find((node) => node.id === before.id)
+        if (current && stable(current) !== stable(before)) throw new Error('后台撤销与本地节点编辑冲突，本地编辑已保留')
+      }
+      if ((doc.edges || []).some((edge) => removed.has(edge.from) || removed.has(edge.to))) throw new Error('后台撤销与本地连线冲突，本地编辑已保留')
+    }
+    doc.nodes = doc.nodes.filter((node) => !removed.has(node.id))
+    if (Array.isArray(doc.drawOrder)) doc.drawOrder = doc.drawOrder.filter((id) => !removed.has(id))
+    for (const node of change.added || []) if (!doc.nodes.some((item) => item.id === node.id)) {
+      doc.nodes.push(JSON.parse(JSON.stringify(node)))
+      if (Array.isArray(doc.drawOrder) && !doc.drawOrder.includes(node.id)) doc.drawOrder.push(node.id)
+    }
+  }
+  return doc
+}

package/lib/video-export-worker.js

@@ -0,0 +1,58 @@
+/* 由 tools/build.mjs 生成 —— 请勿直接编辑；改 src/ 下的源文件。 */
+import { parentPort, workerData } from 'node:worker_threads'
+import { readFileSync, writeFileSync, realpathSync, statSync } from 'node:fs'
+import { resolve, relative, isAbsolute, join } from 'node:path'
+import { Resvg } from '@resvg/resvg-js'
+import { MAX_FRAME_SVG_CHARS } from './media.js'
+
+// Rendering must not acquire filesystem/network resources referenced by SVGs.
+export function validateExportSvg(svg) {
+  if (svg.length > MAX_FRAME_SVG_CHARS || !/<svg\b/i.test(svg)) throw new Error('导出帧不是有效尺寸的 SVG')
+  if (/<!DOCTYPE|<!ENTITY|<\?xml-stylesheet|@import|<foreignObject\b/i.test(svg)) throw new Error('导出帧包含不支持的外部资源或 foreignObject')
+  for (const match of svg.matchAll(/(?:\b(?:xlink:)?href)\s*=\s*(["'])(.*?)\1/gis)) {
+    if (!/^(?:#|data:image\/(?:png|jpe?g|gif|webp);base64,)/i.test(match[2].trim())) throw new Error('导出帧不能引用外部图片或文件')
+  }
+  for (const match of svg.matchAll(/url\(\s*(["']?)(.*?)\1\s*\)/gis)) {
+    if (!match[2].trim().startsWith('#')) throw new Error('导出帧不能引用外部 CSS 资源')
+  }
+}
+
+export function renderExportFrame(svg, width, height) {
+  validateExportSvg(svg)
+  // Parse the actual document first: an invalid nested SVG image would
+  // otherwise be silently omitted by the outer viewport wrapper.
+  const normalized = new Resvg(svg, { font: { loadSystemFonts: /<text\b/i.test(svg) } }).toString()
+  // Match drawImage(..., w, h): stretch the intrinsic SVG viewport to the
+  // manifest dimensions, retaining its own viewBox/clip behavior inside it.
+  const wrapper = '<svg xmlns="http://www.w3.org/2000/svg" width="' + width + '" height="' + height + '">' +
+    '<image width="100%" height="100%" preserveAspectRatio="none" href="data:image/svg+xml;base64,' +
+    Buffer.from(normalized).toString('base64') + '"/></svg>'
+  const image = new Resvg(wrapper, { background: 'white', font: { loadSystemFonts: false } }).render()
+  if (image.width !== width || image.height !== height) throw new Error('宿主渲染尺寸与视频不一致')
+  return image.asPng()
+}
+
+if (parentPort) {
+  try {
+    const root = realpathSync(workerData.dir)
+    let bytes = 0, last = 0
+    for (let index = 0; index < workerData.frames.length; index++) {
+      const file = workerData.frames[index].file
+      if (typeof file !== 'string' || isAbsolute(file)) throw new Error('导出帧路径无效')
+      const absolute = realpathSync(resolve(root, file))
+      const rel = relative(root, absolute)
+      if (isAbsolute(rel) || rel === '..' || rel.startsWith('../') || rel.startsWith('..\\')) throw new Error('导出帧路径超出媒体包')
+      if (statSync(absolute).size > MAX_FRAME_SVG_CHARS * 4) throw new Error('导出帧 SVG 过大')
+      const begin = performance.now()
+      const png = renderExportFrame(readFileSync(absolute, 'utf8'), workerData.w, workerData.h)
+      writeFileSync(join(workerData.temp, 'frame-' + String(index).padStart(8, '0') + '.png'), png)
+      bytes += png.length
+      parentPort.postMessage({ type: 'timing', ms: performance.now() - begin })
+      if (Date.now() - last > 100 || index + 1 === workerData.frames.length) {
+        parentPort.postMessage({ type: 'progress', rendered: index + 1, bytes }); last = Date.now()
+      }
+    }
+    parentPort.postMessage({ type: 'done', rendered: workerData.frames.length, bytes })
+  } catch (error) { parentPort.postMessage({ type: 'error', error: String(error.message || error) }) }
+  parentPort.close()
+}