@uzooai/anime-ai-cli 0.0.0-stage → 0.5.0

package/src/video-clip.js

@@ -0,0 +1,381 @@
+import crypto from 'node:crypto'
+import path from 'node:path'
+import { atomic, json, root, safeName } from './store.js'
+import { scopedCanvas } from './materials.js'
+import { readSource } from './generation-input.js'
+import { segment } from './workflows.js'
+
+const text = (value) => String(value ?? '').trim()
+const hash = (value) => crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex')
+const fail = (code, message, diagnostic) =>
+  Object.assign(new Error(message), { code, ...(diagnostic ? { diagnostic } : {}) })
+const positiveId = (value) => /^[1-9]\d*$/.test(text(value)) && Number.isSafeInteger(Number(value))
+export const clipPath = (profile, operation) =>
+  path.join(root(), 'video-clips', safeName(profile), safeName(operation) + '.json')
+export function clipInput(value) {
+  if (
+    !value ||
+    typeof value !== 'object' ||
+    Array.isArray(value) ||
+    Object.keys(value).some(
+      (key) => !['doc_id', 'node_id', 'space', 'team_uid', 'start_ms', 'end_ms'].includes(key)
+    )
+  )
+    throw new Error('剪辑输入无效或包含未接入字段')
+  if (!text(value.doc_id) || !text(value.node_id)) throw new Error('剪辑缺少来源 doc_id/node_id')
+  if (
+    ![value.start_ms, value.end_ms].every(Number.isSafeInteger) ||
+    value.start_ms < 0 ||
+    value.end_ms - value.start_ms < 500 ||
+    value.end_ms - value.start_ms > 120000
+  )
+    throw new Error('剪辑区间必须为整数毫秒、起点非负，片段时长 500–120000ms')
+  return { ...value }
+}
+async function identity(client) {
+  const me = await client.raw('/auth/me'),
+    owner = text(me.uid ?? me.id)
+  if (!owner) throw new Error('剪辑账号信息缺少 UID')
+  return owner
+}
+async function context(client, input) {
+  const doc = await scopedCanvas(client, input.doc_id, input.space, input.team_uid)
+  const node = doc.nodes.find((candidate) => candidate.id === input.node_id)
+  if (
+    !node ||
+    !['video', 'video_upload'].includes(node.type) ||
+    node.data?.extra?.repaint ||
+    node.data?.extra?.video_remake ||
+    node.data?.extra?.clip_redraw
+  )
+    throw new Error('当前剪辑只支持普通视频生成/素材节点，派生流程须专门接入')
+  const source = readSource(node),
+    data = node.data || {}
+  if (!source.url || source.uploading || source.uploadError)
+    throw new Error('源视频缺少已上传完成的真实输出')
+  const taskId =
+    data.sourceTaskId ||
+    data.extra?.source_task_id ||
+    data.lastTaskId ||
+    data.last_task_id ||
+    data.runtime?.taskId
+  if (!positiveId(taskId))
+    throw new Error('当前剪辑要求同画布真实任务关联；无任务的素材库 source_ref 路线待接入')
+  const refs = [
+    data.resultFileRef,
+    data.fileRef,
+    data.file_ref,
+    data.extra?.file_ref,
+    data.result?.file_ref,
+    data.node_output?.file_ref
+  ]
+    .map(text)
+    .filter(Boolean)
+  const task = await client.raw('/canvas/generations/' + segment(taskId))
+  if (new Set(refs).size !== 1 || refs[0] !== text(task.result?.file_ref))
+    throw new Error('源视频引用与原任务结果不一致；先核对当前媒体')
+  if (
+    String(task.task_id ?? task.id) !== String(taskId) ||
+    task.doc_id !== doc.id ||
+    task.segment_type !== 'video' ||
+    task.status !== 'completed'
+  )
+    throw new Error('剪辑来源与同画布已完成视频任务不匹配')
+  const duration = Number(task.result?.duration || data.duration)
+  if (!Number.isFinite(duration) || duration <= 0 || input.end_ms > Math.round(duration * 1000))
+    throw new Error('剪辑结束点超出源视频时长，或缺少真实时长')
+  return {
+    doc,
+    node,
+    ref: refs[0],
+    body: { source_task_id: Number(taskId), start_ms: input.start_ms, end_ms: input.end_ms }
+  }
+}
+function normalizeClip(clip, record) {
+  if (
+    !positiveId(clip?.id) ||
+    Number(clip.source_task_id) !== record.body.source_task_id ||
+    clip.start_ms !== record.body.start_ms ||
+    clip.end_ms !== record.body.end_ms ||
+    clip.duration_ms !== record.body.end_ms - record.body.start_ms ||
+    !clip.url ||
+    !clip.file_ref ||
+    !text(clip.mime_type).startsWith('video/')
+  )
+    throw fail(
+      'CLIP_RESULT_UNKNOWN',
+      '剪辑响应的来源/区间/媒体引用不完整；先查询原片段，不再次剪辑'
+    )
+  if (clip.canvas_task_id != null && !positiveId(clip.canvas_task_id))
+    throw fail('CLIP_RESULT_UNKNOWN', '片段的真实画布任务关联无效；不把片段 ID 当任务 ID')
+  return structuredClone(clip)
+}
+const summary = (record) => ({
+  operation: record.operation,
+  state: record.state,
+  doc_id: record.input.doc_id,
+  source_node_id: record.input.node_id,
+  result_node_id: record.resultNodeId,
+  clip_id: record.clip?.id || null,
+  canvas_task_id: record.clip?.canvas_task_id || null,
+  canvas_synced: record.canvasSynced === true,
+  ...(record.clip ? { clip: record.clip } : {}),
+  ...(record.lastFailure ? { last_failure: record.lastFailure } : {})
+})
+async function bound(client, profile, operation) {
+  const record = await json(clipPath(profile, operation), null)
+  if (!record) throw new Error('未找到原剪辑 operation')
+  if (record.baseUrl !== client.baseUrl || record.owner !== (await identity(client)))
+    throw new Error('剪辑 operation 的账号或服务不匹配')
+  const current = await context(client, record.input)
+  if (hash(current.body) !== hash(record.body) || current.ref !== record.sourceRef)
+    throw new Error('剪辑源任务/视频引用已变化，停止恢复')
+  return { record, current }
+}
+export async function listClips(client, limit = 50, offset = 0) {
+  if (
+    !Number.isSafeInteger(limit) ||
+    limit < 1 ||
+    limit > 200 ||
+    !Number.isSafeInteger(offset) ||
+    offset < 0
+  )
+    throw new Error('片段分页参数无效')
+  return client.raw('/clip-redraw/clips?' + new URLSearchParams({ limit, offset }))
+}
+async function synchronize(client, profile, record, current) {
+  const { doc, node: source } = current,
+    clip = record.clip
+  if (!clip) return summary(record)
+  // Never restore a node already observed as saved and subsequently deleted.
+  const existing = doc.nodes.find((node) => node.id === record.resultNodeId)
+  if (record.canvasSavedOnce && !existing) throw new Error('剪辑结果节点已被删除；停止，不自动重建')
+  if (existing) {
+    if (
+      text(existing.data?.extra?.file_ref) !== clip.file_ref ||
+      (clip.canvas_task_id && String(existing.data?.last_task_id) !== String(clip.canvas_task_id))
+    )
+      throw new Error('结果节点已存在且素材关联变化；保留当前内容')
+    const edge = doc.edges.find(
+      (edge) =>
+        edge.source === source.id &&
+        edge.target === existing.id &&
+        edge.data?.role === 'video-clip-link'
+    )
+    if (!edge) throw new Error('剪辑连线已被删除或变更；不自动重建连线')
+    record.canvasSynced = true
+    record.canvasSavedOnce = true
+    record.state = 'completed'
+    await atomic(clipPath(profile, record.operation), record)
+    return summary(record)
+  }
+  if (!Number.isSafeInteger(doc.version) || !doc.viewport || !doc.meta || !Array.isArray(doc.edges))
+    throw new Error('剪辑画布快照不完整，停止保存')
+  const taskId = clip.canvas_task_id
+  const aspect = clip.width && clip.height ? clip.width + ':' + clip.height : ''
+  const output = {
+    url: clip.url,
+    file_ref: clip.file_ref,
+    mime_type: clip.mime_type,
+    filename: clip.file_name,
+    file_size: clip.file_size,
+    width: clip.width,
+    height: clip.height,
+    duration: clip.duration_ms / 1000,
+    status: 'completed',
+    ...(taskId ? { task_id: taskId } : {})
+  }
+  const result = {
+    id: record.resultNodeId,
+    type: 'video_upload',
+    position: {
+      x: Math.round((source.position?.x || 0) + (source.width || 486) + 80),
+      y: Math.round(source.position?.y || 0)
+    },
+    data: {
+      title: clip.file_name || '视频剪辑',
+      mediaType: 'video',
+      url: clip.url,
+      file_ref: clip.file_ref,
+      file_name: clip.file_name || '',
+      file_size: clip.file_size || 0,
+      mime_type: clip.mime_type,
+      duration: clip.duration_ms / 1000,
+      width: clip.width,
+      height: clip.height,
+      hasAudio: clip.has_audio === true,
+      clipId: clip.id,
+      clip,
+      result: output,
+      ...(taskId
+        ? { last_task_id: taskId, sourceTaskId: String(taskId), status: 'completed' }
+        : {}),
+      extra: {
+        node_kind: 'asset',
+        file_ref: clip.file_ref,
+        aspect_ratio: aspect,
+        clip,
+        ...(taskId ? { source_task_id: String(taskId) } : {})
+      }
+    }
+  }
+  const edge = {
+    id: 'clip-link-' + record.resultNodeId,
+    source: source.id,
+    target: result.id,
+    sourceHandle: '',
+    targetHandle: '',
+    type: 'default',
+    data: { role: 'video-clip-link' }
+  }
+  // Mark the save attempt before sending. If its response is lost, recovery only
+  // accepts the persisted node; absence then needs investigation, never recreation.
+  record.canvasSavedOnce = true
+  await atomic(clipPath(profile, record.operation), record)
+  let saved
+  try {
+    saved = await client.raw(
+      '/canvas/docs/' + segment(doc.id),
+      {
+        method: 'PUT',
+        body: {
+          version: doc.version,
+          name: doc.name,
+          viewport: doc.viewport,
+          nodes: [...doc.nodes, result],
+          edges: [...doc.edges, edge],
+          meta: doc.meta
+        }
+      },
+      { retry: false }
+    )
+  } catch (error) {
+    // A known CAS rejection did not save the node; permit explicit recovery from
+    // the fresh document without invoking clipping again.
+    if (error.status === 409 || error.apiCode === 3002) record.canvasSavedOnce = false
+    record.state = 'sync_pending'
+    await atomic(clipPath(profile, record.operation), record)
+    throw fail(
+      'CLIP_SYNC_PENDING',
+      '原片段已保存，画布同步未确认；先检查连接和最新画布，再恢复原 operation，不再次剪辑'
+    )
+  }
+  const savedNode = saved.nodes?.find((node) => node.id === result.id)
+  if (
+    saved.id !== doc.id ||
+    saved.version <= doc.version ||
+    savedNode?.data?.extra?.file_ref !== clip.file_ref ||
+    !saved.edges?.some((edge) => edge.id === 'clip-link-' + record.resultNodeId)
+  )
+    throw fail('CLIP_SYNC_PENDING', '剪辑保存响应不完整；读回原结果节点，不重复截取')
+  record.canvasSynced = true
+  record.state = 'completed'
+  await atomic(clipPath(profile, record.operation), record)
+  return summary(record)
+}
+export async function startClip(client, profile, value, operation, confirmed = false) {
+  const input = clipInput(value),
+    file = clipPath(profile, operation)
+  const existing = await json(file, null)
+  if (existing) {
+    if (hash(existing.input) !== hash(input)) throw new Error('原剪辑 operation 不可修改输入')
+    return getClip(client, profile, operation) // Never replay the synchronous POST.
+  }
+  const owner = await identity(client),
+    current = await context(client, input)
+  if (!confirmed)
+    return {
+      operation,
+      submitted: false,
+      generation_submitted: false,
+      wallet: { space: input.space, team_uid: input.team_uid || null },
+      ...current.body,
+      duration_ms: input.end_ms - input.start_ms,
+      next: '核对源视频与区间、暂停同画布编辑后，加 --yes 截取并保存新素材节点；不是片段重拍'
+    }
+  const baseline = await listClips(client, 1, 0)
+  if (!Array.isArray(baseline.items)) throw new Error('片段列表响应不完整，停止提交')
+  const record = {
+    operation,
+    owner,
+    input,
+    body: current.body,
+    sourceRef: current.ref,
+    baseUrl: client.baseUrl,
+    baselineId: Math.max(0, ...baseline.items.map((clip) => Number(clip.id) || 0)),
+    resultNodeId: 'clip-' + crypto.randomUUID(),
+    state: 'submitting',
+    createdAt: new Date().toISOString()
+  }
+  await atomic(file, record)
+  try {
+    record.clip = normalizeClip(
+      await client.raw('/video/clips', { method: 'POST', body: record.body }, { retry: false }),
+      record
+    )
+  } catch (error) {
+    record.state = 'unknown'
+    record.lastFailure = {
+      ...(Number.isInteger(error.status) ? { http_status: error.status } : {}),
+      ...(Number.isFinite(error.apiCode) ? { api_code: error.apiCode } : {}),
+      ...(error.requestId ? { request_id: error.requestId } : {})
+    }
+    await atomic(file, record)
+    throw fail(
+      'CLIP_RESULT_UNKNOWN',
+      '剪辑提交结果未确认；先检查后端连接并查询片段列表，原 operation 不重新 POST',
+      record.lastFailure
+    )
+  }
+  record.state = 'clipped'
+  await atomic(file, record)
+  return recoverClip(client, profile, operation)
+}
+export async function getClip(client, profile, operation) {
+  const { record, current } = await bound(client, profile, operation)
+  if (record.canvasSavedOnce && record.clip) {
+    const result = current.doc.nodes.find((node) => node.id === record.resultNodeId)
+    const line = current.doc.edges.some(
+      (edge) =>
+        edge.source === record.input.node_id &&
+        edge.target === record.resultNodeId &&
+        edge.data?.role === 'video-clip-link'
+    )
+    if (!result || result.data?.extra?.file_ref !== record.clip.file_ref || !line)
+      return {
+        ...summary(record),
+        state: 'canvas_changed',
+        canvas_synced: false,
+        next: '原剪辑已产出，但结果节点或连线已删除/变化；核对用户编辑，不自动重建或再次剪辑'
+      }
+  }
+  return {
+    ...summary(record),
+    ...(!record.clip
+      ? {
+          next: '查询 video clips；确认原片段 ID 后 clip-recover 原 operation --clip-id ID，不重新截取'
+        }
+      : {})
+  }
+}
+export async function recoverClip(client, profile, operation, clipId) {
+  const { record, current } = await bound(client, profile, operation)
+  if (clipId !== undefined) {
+    if (!positiveId(clipId) || Number(clipId) <= record.baselineId)
+      throw new Error('恢复片段 ID 无效或早于本次截取，不关联旧片段')
+    if (record.clip && Number(record.clip.id) !== Number(clipId))
+      throw new Error('原 operation 已关联另一个真实片段')
+    let found
+    for (let offset = 0; offset < 2000; offset += 200) {
+      const page = await listClips(client, 200, offset)
+      found = page.items?.find((clip) => String(clip.id) === String(clipId))
+      if (found || (page.items?.length || 0) < 200) break
+    }
+    if (!found) throw new Error('未在当前账号片段列表找到指定片段；停止，不重新截取')
+    record.clip = normalizeClip(found, record)
+    await atomic(clipPath(profile, operation), record)
+  }
+  if (!record.clip) return getClip(client, profile, operation)
+  normalizeClip(record.clip, record)
+  return synchronize(client, profile, record, current)
+}

package/src/video-frame.js

@@ -0,0 +1,296 @@
+import crypto from 'node:crypto'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { atomic, json, root, safeName } from './store.js'
+import { scopedCanvas } from './materials.js'
+import { readSource } from './generation-input.js'
+import { segment } from './workflows.js'
+import { imageOutputWorkflow } from './image-output.js'
+import { mediaTools, downloadVideo, extractFrames, hashFile, sameVideoReferences } from './media.js'
+const defaultMedia = { mediaTools, downloadVideo, extractFrames }
+
+const text = (value) => String(value ?? '').trim()
+const digest = (value) => crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex')
+export const framePath = (profile, operation) =>
+  path.join(root(), 'video-frames', safeName(profile), safeName(operation) + '.json')
+export function frameInput(value) {
+  if (
+    !value ||
+    typeof value !== 'object' ||
+    Array.isArray(value) ||
+    Object.keys(value).some(
+      (key) => !['doc_id', 'node_id', 'space', 'team_uid', 'times_ms'].includes(key)
+    )
+  )
+    throw new Error('截帧输入无效或包含未接入字段')
+  if (!text(value.doc_id) || !text(value.node_id)) throw new Error('截帧缺少 doc_id/node_id')
+  if (
+    !Array.isArray(value.times_ms) ||
+    !value.times_ms.length ||
+    value.times_ms.length > 3 ||
+    value.times_ms.some((t) => !Number.isSafeInteger(t) || t < 0) ||
+    new Set(value.times_ms).size !== value.times_ms.length
+  )
+    throw new Error('截帧 times_ms 须为 1–3 个不重复的非负整数毫秒')
+  return { ...value, times_ms: [...value.times_ms].sort((a, b) => a - b) }
+}
+async function identity(client) {
+  const me = await client.raw('/auth/me'),
+    owner = text(me.uid ?? me.id)
+  if (!owner) throw new Error('截帧账号响应缺少 UID')
+  return owner
+}
+async function context(client, input) {
+  const doc = await scopedCanvas(client, input.doc_id, input.space, input.team_uid)
+  const node = doc.nodes.find((node) => node.id === input.node_id)
+  if (
+    !node ||
+    !['video', 'video_upload'].includes(node.type) ||
+    node.data?.extra?.repaint ||
+    node.data?.extra?.video_remake ||
+    node.data?.extra?.clip_redraw
+  )
+    throw new Error('截帧仅支持普通视频/视频素材节点')
+  const source = readSource(node),
+    data = node.data || {}
+  const refs = [
+    data.resultFileRef,
+    data.fileRef,
+    data.file_ref,
+    data.extra?.file_ref,
+    data.result?.file_ref,
+    data.node_output?.file_ref
+  ]
+    .map(text)
+    .filter(Boolean)
+  if (!source.url || source.uploading || source.uploadError || new Set(refs).size !== 1)
+    throw new Error('源视频未上传完成或媒体引用不一致')
+  const taskId = text(
+    data.sourceTaskId || data.extra?.source_task_id || data.last_task_id || data.lastTaskId
+  )
+  if (!/^[1-9]\d*$/.test(taskId))
+    throw new Error('本轮截帧要求同画布真实视频任务关联，缺少任务的素材路线待接入')
+  const task = await client.raw('/canvas/generations/' + segment(taskId))
+  if (
+    String(task.task_id ?? task.id) !== taskId ||
+    task.doc_id !== doc.id ||
+    task.segment_type !== 'video' ||
+    task.status !== 'completed'
+  )
+    throw new Error('截帧源任务/画布/视频引用不匹配')
+  if (!(await sameVideoReferences(client, refs[0], task.result?.file_ref)))
+    throw new Error('截帧源视频与任务结果不是同一媒体；停止，不替换当前素材')
+  const duration = Number(task.result?.duration || data.duration)
+  if (
+    !Number.isFinite(duration) ||
+    duration <= 0 ||
+    input.times_ms.some((t) => t >= duration * 1000)
+  )
+    throw new Error('截帧时刻超出已知视频时长或位于末尾')
+  return {
+    doc,
+    node,
+    url: client.baseUrl + '/files/' + encodeURIComponent(refs[0]),
+    binding: { task_id: taskId, file_ref: refs[0] }
+  }
+}
+const fileName = (title, time) =>
+  (String(title || 'video')
+    .trim()
+    .replace(/[\\/:*?"<>|]+/g, '_')
+    .slice(0, 80) || 'video') +
+  '-frame-' +
+  time +
+  '.jpg'
+const titleAt = (time) =>
+  '截图 ' +
+  String(Math.floor(time / 60000)).padStart(2, '0') +
+  ':' +
+  ((time % 60000) / 1000).toFixed(2).padStart(5, '0')
+export function placeFrame(nodes, source) {
+  const base = {
+    x: Math.round((source.position?.x || 0) + (Number(source.width) || 320) + 80),
+    y: Math.round(source.position?.y || 0)
+  }
+  let position = { ...base }
+  for (let attempt = 0; attempt <= nodes.length; attempt++) {
+    const overlaps = nodes.some((node) => {
+      const left = Number(node.position?.x) || 0,
+        top = Number(node.position?.y) || 0
+      return (
+        position.x < left + (Number(node.width) || 320) + 32 &&
+        position.x + 352 > left &&
+        position.y < top + (Number(node.height) || 300) + 32 &&
+        position.y + 332 > top
+      )
+    })
+    if (!overlaps) return position
+    position = { x: base.x, y: position.y + 332 }
+  }
+  throw new Error('无法为截帧分配无重叠位置')
+}
+const summary = (record) => ({
+  operation: record.operation,
+  state: record.state,
+  generation_submitted: false,
+  library_saved: false,
+  doc_id: record.input.doc_id,
+  source_node_id: record.input.node_id,
+  items: record.items.map((item) => ({
+    node_id: item.nodeId,
+    time_ms: item.time,
+    frame_time_ms: item.local?.frame_time_ms ?? null,
+    state: item.state,
+    canvas_bound: item.bound === true,
+    task_id: item.response?.task_id || null,
+    width: item.local?.width || null,
+    height: item.local?.height || null
+  })),
+  next:
+    record.state === 'completed'
+      ? '读取画布和图片核验；不会自动入库'
+      : '先检查后端连接和原节点；frame-recover 原 operation --yes 只恢复已知阶段，不重发未知 complete'
+})
+const { persistNodes, runUploads } = imageOutputWorkflow({
+  recordPath: framePath,
+  readContext: context,
+  nodeTitle: (item) => titleAt(item.time),
+  nodePosition: placeFrame,
+  edgeRole: 'video-frame-capture-link',
+  edgePrefix: 'frame-link-',
+  codePrefix: 'FRAME',
+  mime: 'image/jpeg',
+  summarize: summary
+})
+async function bound(client, profile, operation) {
+  const record = await json(framePath(profile, operation), null)
+  if (!record) throw new Error('未找到截帧 operation')
+  if (record.baseUrl !== client.baseUrl || record.owner !== (await identity(client)))
+    throw new Error('截帧 operation 的账号或服务不匹配')
+  const current = await context(client, record.input)
+  if (digest(record.binding) !== digest(current.binding))
+    throw new Error('截帧源素材/任务已变化，停止恢复')
+  return { record, current }
+}
+async function prepareLocal(client, profile, record, current, toolsOptions, media = defaultMedia) {
+  if (record.items.every((item) => item.local)) return
+  const tools = await media.mediaTools(toolsOptions)
+  await fs.mkdir(record.directory, { recursive: true })
+  const sourceFile = path.join(record.directory, 'source.mp4')
+  if (!record.download) {
+    // An interrupted download is local and reversible; remove only our fixed cached file.
+    await fs.rm(sourceFile, { force: true })
+    record.download = await media.downloadVideo(client, current.url, sourceFile)
+    await atomic(framePath(profile, record.operation), record)
+  } else if (digest(await hashFile(sourceFile)) !== digest(record.download))
+    throw new Error('本地源视频缓存发生变化')
+  // A failed local extraction has no remote side effects. Re-export only the
+  // operation-owned unfinished JPEGs, never alter a completed/uploaded artifact.
+  for (const item of record.items)
+    await fs.rm(path.join(record.directory, item.fileName), { force: true })
+  const frames = await media.extractFrames(
+    sourceFile,
+    record.input.times_ms,
+    record.items.map((item) => path.join(record.directory, item.fileName)),
+    tools
+  )
+  record.items.forEach((item, index) => {
+    item.local = frames[index]
+  })
+  record.state = 'local_ready'
+  await atomic(framePath(profile, record.operation), record)
+}
+export async function startFrames(
+  client,
+  profile,
+  value,
+  operation,
+  confirmed = false,
+  toolsOptions = {},
+  media = defaultMedia
+) {
+  const input = frameInput(value),
+    file = framePath(profile, operation),
+    old = await json(file, null)
+  if (old) {
+    if (digest(old.input) !== digest(input)) throw new Error('原截帧 operation 不可修改输入')
+    return getFrames(client, profile, operation)
+  }
+  const tools = await media.mediaTools(toolsOptions),
+    current = await context(client, input),
+    owner = await identity(client)
+  if (!confirmed)
+    return {
+      operation,
+      submitted: false,
+      generation_submitted: false,
+      library_saved: false,
+      source_task_id: current.binding.task_id,
+      times_ms: input.times_ms,
+      output_format: 'image/jpeg',
+      media_tools: 'available',
+      next: '核对时间与源视频、暂停画布编辑后，加 --yes 本地截帧并上传画布；不入素材库'
+    }
+  const directory = path.join(path.dirname(file), safeName(operation) + '-files')
+  const record = {
+    operation,
+    input,
+    owner,
+    baseUrl: client.baseUrl,
+    binding: current.binding,
+    directory,
+    state: 'preparing',
+    items: input.times_ms.map((time) => ({
+      time,
+      nodeId: 'frame-' + crypto.randomUUID(),
+      fileName: fileName(current.node.data?.title, time),
+      state: 'prepared'
+    })),
+    createdAt: new Date().toISOString()
+  }
+  await atomic(file, record)
+  await prepareLocal(client, profile, record, current, tools, media)
+  const fresh = await context(client, input)
+  if (digest(fresh.binding) !== digest(record.binding))
+    throw new Error('截帧期间源素材已变化，停止上传')
+  await persistNodes(client, profile, record, fresh)
+  return runUploads(client, profile, record)
+}
+export async function getFrames(client, profile, operation) {
+  const { record, current } = await bound(client, profile, operation),
+    result = summary(record)
+  for (const item of result.items)
+    if (item.canvas_bound) {
+      const original = record.items.find((frame) => frame.nodeId === item.node_id)
+      const node = current.doc.nodes.find((n) => n.id === item.node_id)
+      if (
+        node?.data?.extra?.file_ref !== original.response.result.file_ref ||
+        !current.doc.edges.some(
+          (e) =>
+            e.source === record.input.node_id &&
+            e.target === item.node_id &&
+            e.data?.role === 'video-frame-capture-link'
+        )
+      ) {
+        item.canvas_bound = false
+        item.state = 'canvas_changed'
+        result.state = 'canvas_changed'
+      }
+    }
+  return result
+}
+export async function recoverFrames(
+  client,
+  profile,
+  operation,
+  confirmed = false,
+  tools = {},
+  media = defaultMedia
+) {
+  if (!confirmed) return getFrames(client, profile, operation)
+  const { record, current } = await bound(client, profile, operation)
+  if (record.state === 'completed') return getFrames(client, profile, operation)
+  await prepareLocal(client, profile, record, current, tools, media)
+  await persistNodes(client, profile, record, (await bound(client, profile, operation)).current)
+  return runUploads(client, profile, record)
+}