dsh-drawai 0.3.0 → 0.3.1

package/lib/drawing-results.js

@@ -0,0 +1,36 @@
+/* 由 tools/build.mjs 生成 —— 请勿直接编辑；改 src/ 下的源文件。 */
+import { imageValueFromStyle, styleWithSvgMarkup, styleGet } from './style-kernel.js'
+import { videoMetaFromData } from './media.js'
+
+export function applyDrawingResult(doc, job, output) {
+  const existing = doc.nodes.find((node) => node.data?.drawaiTaskId === job.id)
+  if (existing) return existing
+  const source = doc.nodes.find((node) => node.id === job.source.id)
+  if (!source) throw new Error('来源节点已删除，结果已保留')
+  const layer = (doc.layers || []).find((item) => item.id === source.layer)
+  if (layer?.locked || source.locked || styleGet(source.style || '', 'locked', '0') === '1') throw new Error('来源图层或节点已锁定，结果已保留')
+  const seen = new Set([source.id])
+  for (let parent = source.parent; parent;) {
+    if (seen.has(parent)) throw new Error('来源分组结构无效')
+    seen.add(parent)
+    const ancestor = doc.nodes.find((node) => node.id === parent)
+    if (!ancestor) break
+    if (ancestor.locked || styleGet(ancestor.style || '', 'locked', '0') === '1') throw new Error('来源分组已锁定，结果已保留')
+    parent = ancestor.parent
+  }
+  if (job.kind === 'image' && imageValueFromStyle(source.style || '') !== job.source.image) throw new Error('原图已更改，结果已保留')
+  if (job.kind === 'video' && videoMetaFromData(source.data)?.clip !== job.source.clip) throw new Error('原视频已更改，结果已保留')
+  const id = 'draw-' + job.id
+  if (doc.nodes.concat(doc.edges || [], doc.layers || [], doc.labels || []).some((cell) => cell.id === id)) throw new Error('绘制结果 ID 冲突')
+  const node = { ...source, id, x: source.x + source.w + 24, data: { ...source.data, drawaiTaskId: job.id } }
+  if (job.kind === 'image') node.style = styleWithSvgMarkup(source.style || '', output.svg, styleGet(source.style || '', 'imageAspect', '1'))
+  else {
+    node.label = (source.label || '视频') + ' · SVG 复刻'
+    node.style = styleWithSvgMarkup(source.style || '', output.poster, '1')
+    node.data = { ...node.data, drawaiMedia: '1', mediaKind: 'svg', mediaClip: output.clip,
+      mediaFps: String(output.fps), mediaW: String(output.w), mediaH: String(output.h), mediaPosterFrame: '0' }
+  }
+  const order = Array.isArray(doc.drawOrder) ? doc.drawOrder.slice() : (doc.edges || []).concat(doc.nodes).map((item) => item.id)
+  doc.nodes.push(node); doc.drawOrder = [...order.filter((value) => value !== id), id]
+  return node
+}

package/lib/drawing-runner.js

@@ -0,0 +1,213 @@
+/* 由 tools/build.mjs 生成 —— 请勿直接编辑；改 src/ 下的源文件。 */
+import { spawn } from 'node:child_process'
+import { readFileSync, writeFileSync, copyFileSync, existsSync, mkdirSync, renameSync, mkdtempSync, rmSync, realpathSync } from 'node:fs'
+import { join, relative, isAbsolute } from 'node:path'
+import { createHash } from 'node:crypto'
+import { ffmpegBinary } from './video-export.js'
+import { ensureClipPack, writeManifest, clipDirFor, mediaRootFor, frameFileName, STILLS_DIR, stillFileName } from './media.js'
+
+function checkMediaDirectory(job, path) {
+  const rel = relative(realpathSync(job.scope.workspaceRoot), realpathSync(path))
+  if (isAbsolute(rel) || rel.startsWith('..')) throw new Error('媒体目录超出工作区')
+}
+
+export async function runMediaCommand(args, signal, onProgress, binary = ffmpegBinary()) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(binary, ['-hide_banner', '-nostdin', '-nostats', ...args], { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] })
+    let stdout = '', stderr = ''
+    const abort = () => child.kill()
+    signal?.addEventListener('abort', abort, { once: true }); if (signal?.aborted) abort()
+    child.stdout.on('data', (bytes) => {
+      stdout = (stdout + bytes.toString()).slice(-65536)
+      const matches = [...stdout.matchAll(/frame=(\d+)/g)]; if (matches.length) onProgress?.(Number(matches.at(-1)[1]))
+    })
+    child.stderr.on('data', (bytes) => { stderr = (stderr + bytes.toString()).slice(-32768) })
+    child.on('error', (error) => { signal?.removeEventListener('abort', abort); reject(new Error(error.code === 'ENOENT' ? '未找到 FFmpeg，请安装或设置 DRAWAI_FFMPEG_PATH' : error.message)) })
+    child.on('close', (code) => {
+      signal?.removeEventListener('abort', abort)
+      if (signal?.aborted) reject(new Error('已取消任务'))
+      else if (code !== 0) reject(new Error('FFmpeg 处理失败：' + stderr.trim()))
+      else resolve({ stdout, stderr })
+    })
+  })
+}
+
+const inputArgs = (file) => ['-protocol_whitelist', 'file,pipe', '-format_whitelist', 'mov,matroska,webm', '-i', file]
+
+export async function probeDrawingVideo(file, signal, binary) {
+  // Only FFmpeg is required. The null pass reports the actual decoded endpoint
+  // (including fractional duration), unlike the rounded "Duration:" header.
+  const result = await runMediaCommand([...inputArgs(file), '-map', '0:v:0', '-an', '-sn', '-fps_mode', 'passthrough',
+    '-progress', 'pipe:1', '-f', 'null', '-'], signal, null, binary)
+  const times = [...result.stdout.matchAll(/out_time_us=(\d+)/g)]
+  const videos = [...result.stderr.matchAll(/Video:[^\r\n]*?\b(\d{1,5})x(\d{1,5})\b([^\r\n]*)/g)]
+  const video = videos.at(-1)
+  if (!video || !times.length) throw new Error('无法探测视频尺寸或时长')
+  const sar = /SAR (\d+):(\d+)/.exec(video[3])
+  const w = Math.round(Number(video[1]) * (sar ? Number(sar[1]) / Number(sar[2]) : 1))
+  const h = Number(video[2]), duration = Number(times.at(-1)[1]) / 1000000
+  if (!(w > 0 && h > 0 && duration > 0)) throw new Error('视频尺寸或时长无效')
+  return { w, h, duration }
+}
+
+export function planDrawingVideo(options, info, extract = false) {
+  const from = options.range === 'all' ? 0 : Number(options.from || 0)
+  const end = options.range === 'all' || options.end === '' ? info.duration : options.end !== undefined ? Number(options.end) : from + Number(options.seconds)
+  const fps = Number(options.fps)
+  const width = options.resolution === undefined || options.resolution === 'custom' ? Number(options.width) : Number(options.resolution)
+  if (!Number.isFinite(from) || from < 0 || from >= info.duration || !Number.isFinite(end) || end <= from) throw new Error('绘制时间范围无效')
+  if (!Number.isFinite(fps) || fps <= 0 || !Number.isInteger(width) || width < 0 || width > 16384 || (options.resolution === 'custom' && !width)) throw new Error('帧率或采样尺寸无效')
+  const raw = (Math.min(end, info.duration) - from) * fps
+  let count = Math.max(1, Math.ceil(raw - Math.min(1e-7, raw * Number.EPSILON * 4)))
+  if (extract) {
+    const max = options.max ?? 1200
+    if (!Number.isInteger(max) || max < 1 || max > 1200) throw new Error('抽帧数量上限必须为 1 至 1200')
+    count = Math.min(count, max)
+  }
+  if (!Number.isSafeInteger(count) || count > 1000000) throw new Error('预计帧数超出 100 万帧上限')
+  const scale = width === 0 ? 1 : extract ? width / info.w : Math.min(1, width / Math.max(info.w, info.h))
+  const w = Math.max(1, Math.round(info.w * scale)), h = Math.max(1, Math.round(info.h * scale))
+  if (w * h > 16000000 || Math.max(w, h) > 16384) throw new Error('单帧处理上限为 1600 万像素、长边 16384px')
+  return { from, fps, count, w, h, maxBytes: options.level === 'low' ? 60000 : options.level === 'high' ? 248000 : 120000 }
+}
+
+async function* rawVideoFrames(job, signal, binary, perf) {
+  const decodeDone = perf?.start('decodePipelineWall')
+  const { plan } = job, offset = job.done || 0
+  const child = spawn(binary || ffmpegBinary(), ['-hide_banner', '-nostdin', '-loglevel', 'error',
+    '-ss', String(plan.from), ...inputArgs(job.input), '-map', '0:v:0', '-an', '-sn',
+    '-filter_threads', '1', '-vf', 'tpad=stop_mode=clone:stop_duration=' + (1 / plan.fps) + ',fps=fps=' + plan.fps + ':start_time=0:round=near,scale=' + plan.w + ':' + plan.h + ':flags=bicubic,setsar=1,format=rgba,trim=start_frame=' + offset + ',setpts=PTS-STARTPTS',
+    '-frames:v', String(plan.count - offset), '-fps_mode', 'passthrough', '-threads', '1', '-pix_fmt', 'rgba', '-f', 'rawvideo', 'pipe:1'],
+  { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] })
+  let stderr = '', error
+  const abort = () => child.kill()
+  signal.addEventListener('abort', abort, { once: true }); if (signal.aborted) abort()
+  child.stderr.on('data', (bytes) => { stderr = (stderr + bytes.toString()).slice(-8000) })
+  const completed = new Promise((resolve) => {
+    child.on('error', (value) => { error = value; resolve(-1) }); child.on('close', resolve)
+  })
+  const size = plan.w * plan.h * 4
+  let frame = Buffer.alloc(size), filled = 0
+  try {
+    for await (const chunk of child.stdout) {
+      for (let offset = 0; offset < chunk.length;) {
+        const take = Math.min(size - filled, chunk.length - offset)
+        chunk.copy(frame, filled, offset, offset + take); offset += take; filled += take
+        if (filled === size) { yield frame; frame = Buffer.alloc(size); filled = 0 }
+      }
+    }
+    const code = await completed
+    if (signal.aborted) throw new Error('已取消任务')
+    if (code !== 0 || filled) throw new Error(error?.message || '视频解码失败或像素帧不完整：' + stderr)
+  } finally { signal.removeEventListener('abort', abort); child.kill(); await completed; decodeDone?.() }
+}
+
+export async function executeDrawing(job, context) {
+  const { pool, signal, update, checkpoint, perf } = context
+  if (job.kind === 'image') {
+    update({ phase: 'tracing', total: 1, message: '正在分析图片与生成色块' })
+    const output = await pool.run(readFileSync(job.input), { ...job.options, mode: 'image', profile: perf?.enabled }, { token: job.id })
+    perf?.merge('worker.', output.performance); perf?.add('workerQueueWait', output.queueWaitMs)
+    job.done = 1; checkpoint(); return output
+  }
+  if (!job.info) {
+    update({ phase: 'probing', message: '正在探测视频与采样范围' })
+    const probeDone = perf?.start('videoProbe')
+    job.info = await probeDrawingVideo(job.input, signal, context.ffmpegPath)
+    probeDone?.()
+    job.plan = planDrawingVideo(job.options, job.info, job.kind === 'extract'); checkpoint()
+  }
+  const plan = job.plan
+  update({ phase: 'decoding', total: plan.count, message: '正在抽帧并绘制' })
+  if (job.kind === 'extract') {
+    const out = join(job.directory, 'stills'); mkdirSync(out, { recursive: true })
+    await runMediaCommand(['-y', '-ss', String(plan.from), ...inputArgs(job.input), '-map', '0:v:0', '-an', '-filter_threads', '1',
+      '-vf', 'tpad=stop_mode=clone:stop_duration=' + (1 / plan.fps) + ',fps=fps=' + plan.fps + ':start_time=0,scale=' + plan.w + ':' + plan.h + ',setsar=1',
+      '-frames:v', String(plan.count), '-threads', '1', '-start_number', '1', '-progress', 'pipe:1', join(out, '%04d.png')],
+    signal, (done) => update({ done, total: plan.count }), context.ffmpegPath)
+    for (let i = 0; i < plan.count; i++) if (!existsSync(join(out, stillFileName(i)))) throw new Error('抽帧结果不完整')
+    await (context.publishExtraction || (async (action) => action()))(() => {
+      const clipDir = clipDirFor(job.scope.drawioAbs, job.source.clip)
+      checkMediaDirectory(job, clipDir)
+      const target = join(clipDir, STILLS_DIR), stage = mkdtempSync(join(clipDir, '.stills-')), backup = stage + '.previous'
+      try {
+        for (let i = 0; i < plan.count; i++) {
+          if (signal.aborted) throw new Error('已取消抽帧')
+          copyFileSync(join(out, stillFileName(i)), join(stage, stillFileName(i)))
+        }
+        if (existsSync(target)) renameSync(target, backup)
+        try { renameSync(stage, target) }
+        catch (error) { if (existsSync(backup) && !existsSync(target)) renameSync(backup, target); throw error }
+        rmSync(backup, { recursive: true, force: true })
+      } finally { rmSync(stage, { recursive: true, force: true }) }
+    })
+    job.done = plan.count; checkpoint(); return { written: plan.count, clip: job.source.clip }
+  }
+  const clip = job.outputClip || ('trace-' + job.id)
+  const mediaRoot = mediaRootFor(job.scope.drawioAbs)
+  if (existsSync(mediaRoot)) checkMediaDirectory(job, mediaRoot)
+  const pack = ensureClipPack(job.scope.drawioAbs, clip, { kind: 'svg', w: plan.w, h: plan.h, fps: plan.fps })
+  checkMediaDirectory(job, pack.dir)
+  if (!job.outputClip) { job.outputClip = clip; checkpoint() }
+  // Audio is immutable input owned by this task, not a live reference to the browser.
+  const sourceName = 'source' + (job.source.extension || '.mp4')
+  if (!existsSync(join(pack.dir, sourceName))) copyFileSync(job.input, join(pack.dir, sourceName))
+  let manifest = { ...pack.manifest, source: sourceName, sourceOffset: plan.from, frames: pack.manifest.frames.slice(0, job.done || 0) }
+  if (manifest.frames.length !== (job.done || 0)) throw new Error('绘制检查点缺少连续帧，请重新开始')
+  let chain = ''
+  for (let i = 0; i < manifest.frames.length; i++) {
+    if (manifest.frames[i].file !== 'frames/' + frameFileName(i)) throw new Error('检查点帧顺序无效，请重新开始')
+    const svg = readFileSync(join(pack.dir, manifest.frames[i].file), 'utf8')
+    chain = createHash('sha256').update(chain).update(svg).digest('hex')
+  }
+  if (job.done && chain !== job.frameChain) throw new Error('检查点帧已变化，请重新开始')
+  let previous = job.lastFrame ? Promise.resolve({ svg: readFileSync(join(pack.dir, 'frames', frameFileName(job.done - 1)), 'utf8'), paletteShared: false }) : null
+  let previousHash = job.lastFrame || '', index = job.done || 0
+  const pending = []
+  const inFlight = Math.max(1, Math.min(pool.size, Math.floor(64 * 1024 * 1024 / (plan.w * plan.h * 8))))
+  let checkpointAt = Date.now(), checkpointFrame = job.done || 0
+  const flush = () => {
+    writeManifest(pack.dir, manifest); checkpoint()
+    checkpointAt = Date.now(); checkpointFrame = job.done
+  }
+  const commit = async () => {
+    const item = pending.shift(), result = await item.promise
+    if (signal.aborted) throw new Error('已取消任务')
+    if (!item.reused) { perf?.merge('worker.', result.performance); perf?.add('workerQueueWait', result.queueWaitMs) }
+    const commitDone = perf?.start('frameCommit')
+    const file = join(pack.dir, 'frames', frameFileName(item.index))
+    writeFileSync(file + '.tmp', result.svg); renameSync(file + '.tmp', file)
+    manifest.frames.push({ file: 'frames/' + frameFileName(item.index), t: item.index / plan.fps })
+    job.frameChain = createHash('sha256').update(job.frameChain || '').update(result.svg).digest('hex')
+    if (!result.paletteShared && result.palette && !item.reused) { job.palette = result.palette; job.paletteIndex = item.index }
+    job.done = item.index + 1; job.lastFrame = item.hash
+    if (result.detailReduced) job.reducedFrames = (job.reducedFrames || 0) + 1
+    if (!item.index) { job.poster = result.svg; writeFileSync(join(pack.dir, 'poster.svg'), result.svg) }
+    update({ phase: 'tracing', done: job.done, total: plan.count, message: '已绘制 ' + job.done + '/' + plan.count + ' 帧' })
+    if (!item.index || job.done === plan.count || job.done - checkpointFrame >= 30 || Date.now() - checkpointAt >= 500) flush()
+    commitDone?.()
+  }
+  try {
+    if (index < plan.count) for await (const rgba of rawVideoFrames(job, signal, context.ffmpegPath, perf)) {
+      if (signal.aborted) throw new Error('已取消任务')
+      if (context.pauseRequested()) break
+      const hash = createHash('sha256').update(rgba).digest('hex')
+      const shared = previous && hash === previousHash
+      const options = { ...job.options, width: plan.w, height: plan.h, maxBytes: plan.maxBytes, profile: perf?.enabled }
+      if (job.palette && index - job.paletteIndex < Math.max(1, Math.min(120, Math.round(plan.fps * 2)))) options.paletteOverride = job.palette
+      const promise = shared ? previous : pool.runRaster({ width: plan.w, height: plan.h, data: rgba }, options, { token: job.id })
+      // Attach immediately: a later frame can fail before an earlier one is awaited.
+      promise.catch(() => {})
+      pending.push({ index, promise, hash, reused: !!shared }); previous = promise; previousHash = hash; index++
+      if (pending.length >= inFlight) await commit()
+      if (index >= plan.count) break
+    }
+    while (pending.length) await commit()
+    if (context.pauseRequested()) return null
+    if (job.done !== plan.count) throw new Error('输出帧数不完整：预期 ' + plan.count + '，实际 ' + job.done)
+    return { clip, ...plan, reducedFrames: job.reducedFrames || 0, poster: job.poster || readFileSync(join(pack.dir, 'poster.svg'), 'utf8') }
+  } finally {
+    await Promise.allSettled(pending.map((item) => item.promise))
+    if (job.done !== checkpointFrame) flush()
+  }
+}

package/lib/drawing-tasks.js

@@ -0,0 +1,230 @@
+/* 由 tools/build.mjs 生成 —— 请勿直接编辑；改 src/ 下的源文件。 */
+import { randomUUID, createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, readdirSync, rmSync, statSync, realpathSync } from 'node:fs'
+import { copyFile, readFile } from 'node:fs/promises'
+import { join, resolve, relative, isAbsolute } from 'node:path'
+import { executeDrawing } from './drawing-runner.js'
+import { createPerformanceLog } from './performance-log.js'
+
+const algorithm = createHash('sha256').update(Buffer.concat(['trace-image.js', 'video-trace-reuse.js', 'drawing-runner.js', 'video-trace-worker.js', 'style-kernel.js', 'raster.js']
+  .map((name) => readFileSync(new URL(name, import.meta.url))))).digest('hex')
+const terminal = (job) => ['succeeded', 'failed', 'cancelled', 'interrupted', 'paused'].includes(job.status)
+const digest = (value) => createHash('sha256').update(value).digest('hex')
+const fileIdentity = (path) => {
+  let value = resolve(path)
+  try { value = realpathSync(value) } catch {}
+  return process.platform === 'win32' ? value.toLowerCase() : value
+}
+function atomic(path, value) { writeFileSync(path + '.tmp', JSON.stringify(value)); renameSync(path + '.tmp', path) }
+
+export function createDrawingTaskManager(options) {
+  const jobs = new Map(), loaded = new Set(), paused = new Map()
+  let active, closed = false, pumping = false, sequence = Date.now()
+  const nextOrder = () => (sequence = Math.max(Date.now(), sequence + 1))
+  const contained = (root, path) => { const rel = relative(realpathSync(root), realpathSync(path)); return !isAbsolute(rel) && rel !== '..' && !rel.startsWith('..\\') && !rel.startsWith('../') }
+  const rootOf = (scope) => {
+    const path = join(scope.workspaceRoot, '.drawai-cache', 'drawing-tasks')
+    mkdirSync(path, { recursive: true })
+    if (!contained(scope.workspaceRoot, path)) throw new Error('任务目录超出工作区')
+    return path
+  }
+  const ownerKey = (scope) => fileIdentity(scope.workspaceRoot) + '\0' + scope.sessionId
+  const policyPath = (scope) => join(rootOf(scope), 'queue-' + digest(scope.sessionId).slice(0, 24) + '.json')
+  function persist(job) {
+    const { control, promise, deliveryPromise, poster, ...data } = job
+    atomic(join(job.directory, 'job.json'), data)
+  }
+  function view(job) {
+    return { id: job.id, kind: job.kind, label: job.label, scope: { path: job.scope.path, page: job.scope.page,
+      pageId: job.scope.pageId, pageName: job.scope.pageName }, options: job.options, status: job.status, delivery: job.delivery,
+    phase: job.phase, done: job.done || 0, total: job.total || job.plan?.count || 1, reducedFrames: job.reducedFrames || 0, createdAt: job.createdAt,
+    startedAt: job.startedAt, finishedAt: job.finishedAt, error: job.error || '', message: job.message || '',
+    pauseRequested: !!job.pauseRequested, outputClip: job.outputClip, nodeId: job.nodeId, resultPath: job.resultPath,
+    queuePaused: !!paused.get(ownerKey(job.scope)), sourceId: job.source.id }
+  }
+  function load(scope) {
+    const key = ownerKey(scope)
+    if (loaded.has(key)) return
+    const root = rootOf(scope); mkdirSync(root, { recursive: true })
+    const names = readdirSync(root)
+    loaded.add(key)
+    try { paused.set(key, JSON.parse(readFileSync(policyPath(scope))).paused === true) } catch {}
+    for (const name of names) {
+      if (!/^[a-f0-9-]{36}$/.test(name) || jobs.has(name)) continue
+      try {
+        const directory = join(root, name), data = JSON.parse(readFileSync(join(directory, 'job.json'), 'utf8'))
+        if (data.id !== name || !contained(root, directory) || !contained(directory, join(directory, 'job.json'))) continue
+        const rel = relative(resolve(scope.workspaceRoot), resolve(data.scope.drawioAbs))
+        if (data.scope.sessionId !== scope.sessionId || fileIdentity(data.scope.workspaceRoot) !== fileIdentity(scope.workspaceRoot) ||
+            isAbsolute(rel) || rel === '..' || rel.startsWith('..\\') || rel.startsWith('../')) continue
+        const job = { ...data, directory, input: join(directory, 'input.bin'), control: new AbortController() }
+        if (job.status !== 'succeeded' && !contained(directory, job.input)) continue
+        if (job.status === 'succeeded' && job.delivery === 'pending') {
+          job.delivery = 'conflict'; job.error = '绘制产物已保存，宿主曾停止，请重试加入原画布'
+        }
+        if (job.resultPath) job.resultPath = join(directory, 'result.json')
+        if (['running', 'queued', 'cancelling'].includes(job.status)) {
+          job.status = 'interrupted'; job.message = '宿主曾停止，可继续检查点或重新开始'
+        }
+        sequence = Math.max(sequence, Number(job.order) || 0)
+        jobs.set(job.id, job); persist(job)
+      } catch { /* A damaged record must not prevent other tasks from loading. */ }
+    }
+  }
+  function owned(scope, id) {
+    load(scope)
+    const job = jobs.get(id)
+    if (!job || ownerKey(job.scope) !== ownerKey(scope)) throw new Error('任务不存在或不属于当前会话')
+    return job
+  }
+  async function deliver(job) {
+    if (job.status !== 'succeeded' || job.kind === 'extract') return
+    try {
+      const output = JSON.parse(readFileSync(job.resultPath, 'utf8'))
+      const result = await options.commit(job, output)
+      job.delivery = 'applied'; job.nodeId = result.nodeId; job.createdNode = result.node; job.error = ''
+      if (result.page !== undefined) job.scope.page = result.page
+    } catch (error) { job.delivery = 'conflict'; job.error = String(error.message || error) }
+    persist(job)
+  }
+  async function run(job) {
+    let release
+    const perf = createPerformanceLog(job.scope.workspaceRoot, job.kind + '-background', { ...job.options, workerCount: options.pool.size, algorithm })
+    perf.add('queueWait', Date.now() - job.createdAt)
+    job.control = new AbortController(); job.pauseRequested = false
+    job.status = 'running'; job.startedAt ||= Date.now(); job.phase = 'preparing'; job.error = ''; persist(job)
+    const checkpoint = () => { job.updatedAt = Date.now(); persist(job) }
+    try {
+      release = await options.slots?.acquire(job.control.signal)
+      const verifyDone = perf.start('inputVerification')
+      if (digest(await readFile(job.input)) !== job.inputHash) throw new Error('任务素材摘要已变化，请重新提交')
+      verifyDone()
+      job.control.signal.throwIfAborted()
+      const output = await executeDrawing(job, { pool: options.pool, signal: job.control.signal, ffmpegPath: options.ffmpegPath, perf,
+        publishExtraction: (action) => options.publishExtraction ? options.publishExtraction(job, action) : action(),
+        pauseRequested: () => job.pauseRequested, checkpoint,
+        update: (patch) => { Object.assign(job, patch); job.updatedAt = Date.now() },
+      })
+      if (job.control.signal.aborted) throw new Error('已取消任务')
+      if (!output) { job.status = 'paused'; job.message = '已在完整帧边界暂停'; checkpoint(); return }
+      job.resultPath = join(job.directory, 'result.json'); atomic(job.resultPath, output)
+      if (output.svg) writeFileSync(join(job.directory, 'result.svg'), output.svg)
+      job.status = 'succeeded'; job.delivery = job.kind === 'extract' ? 'applied' : 'pending'; job.finishedAt = Date.now()
+      job.phase = 'finished'; job.message = '绘制产物已保存'; checkpoint()
+      rmSync(job.input, { force: true })
+      release?.(); release = null
+      if (job.kind === 'extract') await options.extracted?.(job, output)
+      else job.deliveryPromise = deliver(job).catch((error) => { job.delivery = 'conflict'; job.error = String(error.message || error) })
+    } catch (error) {
+      job.status = closed ? 'interrupted' : job.control.signal.aborted ? 'cancelled' : 'failed'
+      job.error = job.status === 'cancelled' ? '' : String(error.message || error)
+      job.finishedAt = Date.now(); checkpoint()
+      await options.failed?.(job)
+    } finally { release?.(); perf.count('committedFrames', job.done || 0); perf.finish(job.status, { count: job.total, width: job.plan?.w, height: job.plan?.h }) }
+  }
+  function pump() {
+    if (closed || active || pumping) return
+    pumping = true
+    queueMicrotask(() => {
+      pumping = false
+      if (closed || active) return
+      const job = [...jobs.values()].filter((item) => item.status === 'queued' && !paused.get(ownerKey(item.scope)))
+        .sort((a, b) => a.order - b.order)[0]
+      if (!job) return
+      active = job; job.promise = run(job).finally(() => { active = null; pump() })
+    })
+  }
+  async function enqueue(scope, data, input) {
+    if (closed) throw new Error('绘制服务已关闭')
+    load(scope)
+    const history = [...jobs.values()].filter((job) => ownerKey(job.scope) === ownerKey(scope) &&
+      ['succeeded', 'failed', 'cancelled'].includes(job.status) && job.delivery !== 'conflict' && !(job.status === 'succeeded' && job.delivery === 'pending')).sort((a, b) => a.order - b.order)
+    for (const job of history.slice(0, Math.max(0, history.length - 63))) {
+      jobs.delete(job.id); rmSync(job.directory, { recursive: true, force: true })
+    }
+    const optionsKey = JSON.stringify(data.options)
+    const same = [...jobs.values()].find((job) => ownerKey(job.scope) === ownerKey(scope) &&
+      fileIdentity(job.scope.drawioAbs) === fileIdentity(scope.drawioAbs) && (scope.pageId ? job.scope.pageId === scope.pageId : job.scope.page === scope.page) &&
+      job.source.signature === data.source.signature && job.source.id === data.source.id && job.kind === data.kind &&
+      JSON.stringify(job.options) === optionsKey && ['queued', 'running', 'paused'].includes(job.status))
+    if (same) return view(same)
+    const pending = [...jobs.values()].filter((job) => !['succeeded', 'failed', 'cancelled'].includes(job.status))
+    if (pending.length >= 16) throw new Error('队列已满（最多 16 个未完成任务）')
+    const bytes = Buffer.isBuffer(input) ? input.length : statSync(input).size
+    const retainedBytes = [...jobs.values()].filter((job) => job.status !== 'succeeded' && existsSync(job.input)).reduce((sum, job) => sum + job.inputBytes, 0)
+    if (bytes > 64 * 1024 * 1024) throw new Error('单个绘制素材不能超过 64MiB')
+    if (retainedBytes + bytes > 256 * 1024 * 1024) throw new Error('任务素材缓存超出 256MiB 预算，请移除已结束记录或完成部分任务')
+    const id = randomUUID(), directory = join(rootOf(scope), id); mkdirSync(directory)
+    const job = { id, scope: { ...scope }, ...data, algorithm, directory, input: join(directory, 'input.bin'), inputBytes: bytes,
+      createdAt: Date.now(), order: nextOrder(), status: 'queued', delivery: 'pending', phase: 'queued', done: 0, total: 1, control: new AbortController() }
+    try {
+      if (Buffer.isBuffer(input)) writeFileSync(job.input, input)
+      else await copyFile(input, job.input)
+      job.inputHash = digest(await readFile(job.input)); persist(job); jobs.set(id, job); pump(); return view(job)
+    } catch (error) { rmSync(directory, { recursive: true, force: true }); throw error }
+  }
+  return {
+    enqueue,
+    recordCommit(job, node) { job.createdNode = node; persist(job) },
+    list(scope) { load(scope); return [...jobs.values()].filter((job) => ownerKey(job.scope) === ownerKey(scope)).sort((a, b) => a.order - b.order).map(view) },
+    result(scope, id) { const job = owned(scope, id); if (!job.resultPath || !existsSync(job.resultPath)) throw new Error('结果尚未生成'); return { job: view(job), output: JSON.parse(readFileSync(job.resultPath, 'utf8')) } },
+    async command(scope, id, action, value) {
+      load(scope)
+      if (action === 'pause-queue') {
+        paused.set(ownerKey(scope), value === true); atomic(policyPath(scope), { paused: value === true }); pump(); return { queuePaused: value === true }
+      }
+      const job = owned(scope, id)
+      if (action === 'pause') {
+        if (job.status === 'queued') job.status = 'paused'
+        else if (job.status === 'running') { job.pauseRequested = true; job.message = '等待在途帧完成后暂停' }
+      } else if (action === 'resume' || action === 'retry') {
+        if (!['paused', 'failed', 'cancelled', 'interrupted'].includes(job.status)) throw new Error('当前任务不可继续')
+        if (job.algorithm !== algorithm) throw new Error('算法已更新，请选择重新开始')
+        job.status = 'queued'; job.error = ''; job.pauseRequested = false; job.order = nextOrder()
+      } else if (action === 'restart') {
+        if (!terminal(job) || job.status === 'succeeded') throw new Error('请先停止当前任务')
+        job.status = 'cancelled'; persist(job)
+        return enqueue(job.scope, { kind: job.kind, label: job.label, source: job.source, options: job.options }, job.input)
+      } else if (action === 'cancel') {
+        if (job.status === 'running') { job.status = 'cancelling'; job.control.abort(); options.pool.cancelToken(job.id) }
+        else if (!['succeeded', 'failed'].includes(job.status)) job.status = 'cancelled'
+      } else if (action === 'apply') { await job.deliveryPromise; await deliver(job) }
+      else if (action === 'undo') {
+        await job.deliveryPromise
+        if (job.delivery !== 'applied' || job.kind === 'extract') throw new Error('此任务没有可撤销的生成节点')
+        await options.undo(job); job.delivery = 'undone'; job.error = ''
+      } else if (action === 'remove') {
+        if (!terminal(job)) throw new Error('请先取消运行中的任务')
+        await job.deliveryPromise
+        jobs.delete(job.id); rmSync(job.directory, { recursive: true, force: true }); return { removed: true }
+      } else if (action === 'move') {
+        if (job.status !== 'queued') throw new Error('只有等待中的任务可以排序')
+        const waiting = [...jobs.values()].filter((item) => ownerKey(item.scope) === ownerKey(scope) && item.status === 'queued').sort((a, b) => a.order - b.order)
+        const next = waiting[waiting.indexOf(job) + (value < 0 ? -1 : 1)]
+        if (next) { const order = job.order; job.order = next.order; next.order = order; persist(next) }
+      } else throw new Error('未知队列操作')
+      persist(job); pump(); return view(job)
+    },
+    leases(drawioAbs, scope) {
+      const clips = [...jobs.values()].filter((job) => fileIdentity(job.scope.drawioAbs) === fileIdentity(drawioAbs)).flatMap((job) => [job.source.clip, job.outputClip])
+      if (scope) {
+        const root = rootOf(scope)
+        for (const name of readdirSync(root)) if (/^[a-f0-9-]{36}$/.test(name)) {
+          try {
+            const directory = join(root, name)
+            if (!contained(root, directory)) continue
+            const job = JSON.parse(readFileSync(join(directory, 'job.json'), 'utf8'))
+            if (fileIdentity(job.scope.drawioAbs) === fileIdentity(drawioAbs)) clips.push(job.source.clip, job.outputClip)
+          } catch {}
+        }
+      }
+      return new Set(clips.filter(Boolean))
+    },
+    async close() {
+      closed = true
+      if (active) { active.control.abort(); options.pool.cancelToken(active.id); await active.promise }
+      await Promise.allSettled([...jobs.values()].map((job) => job.deliveryPromise))
+      for (const job of jobs.values()) if (job.status === 'queued') { job.status = 'interrupted'; persist(job) }
+    },
+  }
+}