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

package/src/repaint.js

@@ -0,0 +1,326 @@
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { setTimeout as sleep } from 'node:timers/promises'
+import { atomic, json, root, safeName } from './store.js'
+import { request, requestFile, cancellation } from './api.js'
+import { segment } from './workflows.js'
+import { spaceContext } from './canvas.js'
+import { object, repaintOf, mediaUrl, readCanvas, assertJob, jobPath, assertAvailable, claimRepaint, syncRepaintGraph } from './repaint-graph.js'
+
+const hash = value => crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex')
+const persist = record => atomic(recordPath(record.profile, record.operation), record)
+export const recordPath = (profile, operation) => path.join(root(), 'repaint', safeName(profile), `${safeName(operation)}.json`)
+const api = (client, endpoint, options = {}, controls) => client.raw(endpoint, { ...options, headers: { ...options.headers, 'X-Client-Source': 'canvas' } }, controls)
+const failUnknown = message => { const e = new Error(message); e.code = 'SUBMISSION_UNKNOWN'; return e }
+function inputBody(value) {
+  if (!object(value)) throw new Error('转绘输入必须是 JSON 对象')
+  const allowed = ['doc_id', 'source_node_id', 'entry_node_id', 'space', 'team_uid', 'segmentation_mode', 'uniform_interval_seconds']
+  if (Object.keys(value).some(k => !allowed.includes(k))) throw new Error('转绘输入含未知字段；本阶段不支持字幕、附件或自动视频生成')
+  for (const field of ['doc_id', 'source_node_id', 'entry_node_id']) if (typeof value[field] !== 'string' || !value[field].trim()) throw new Error(`转绘输入缺少 ${field}`)
+  const context = spaceContext({ space: value.space, teamUid: value.team_uid })
+  const mode = value.segmentation_mode || 'intelligent'
+  if (!['intelligent', 'uniform'].includes(mode)) throw new Error('segmentation_mode 必须是 intelligent 或 uniform')
+  if (mode === 'uniform' && (!Number.isFinite(value.uniform_interval_seconds) || value.uniform_interval_seconds < 4 || value.uniform_interval_seconds > 15)) throw new Error('uniform 模式必须明确提供 4–15 秒 uniform_interval_seconds')
+  if (mode === 'intelligent' && value.uniform_interval_seconds !== undefined) throw new Error('智能模式不能传均匀切分间隔')
+  return { doc_id: value.doc_id, source_node_id: value.source_node_id, entry_node_id: value.entry_node_id,
+    space: value.space, ...context, segmentation_mode: mode,
+    ...(mode === 'uniform' ? { uniform_interval_seconds: value.uniform_interval_seconds } : {}) }
+}
+async function identity(client) {
+  const me = await client.raw('/auth/me')
+  const owner = String(me?.uid ?? me?.id ?? '')
+  if (!owner) throw new Error('账号响应缺少 uid/id，无法绑定流程')
+  return owner
+}
+async function loadRecord(client, profile, operation) {
+  const record = await json(recordPath(profile, operation), null)
+  if (!record) throw new Error('未找到转绘 operation；先运行 repaint start 预估')
+  if (record.schema !== 1 || record.operation !== operation || record.profile !== profile || !object(record.input) || record.baseUrl !== client.baseUrl || record.owner !== await identity(client)) throw new Error('operation 与当前服务、账号或记录版本不一致')
+  return record
+}
+function sourceKey(doc, input) {
+  const source = doc.nodes.find(n => n.id === input.source_node_id)
+  return hash({ id: source.id, type: source.type, url: mediaUrl(source), file_ref: source.data?.extra?.file_ref || '', file_size: source.data?.file_size || 0, last_task_id: source.data?.last_task_id || null })
+}
+async function checkSource(client, record, allowMissingDetail = false) {
+  const doc = await readCanvas(client, record.input)
+  if (sourceKey(doc, record.input) !== record.sourceKey) throw new Error('源视频已变化，停止原流程；不能将旧任务接到新素材')
+  if (record.lastStatus && !allowMissingDetail && !doc.nodes.some(node => node.id === record.detailId)) throw new Error('流程详情已被删除，停止；经用户明确授权后才可用 repaint recover NAME --restore-detail 预览恢复')
+  return doc
+}
+async function initialEstimate(client, input, doc) {
+  const pricing = await api(client, '/video-segmentation/pricing')
+  const credits = input.segmentation_mode === 'intelligent' ? pricing?.base_processing_credits : 0
+  if (pricing?.currency !== 'OO' || !Number.isSafeInteger(credits) || credits < 0 ||
+    (input.segmentation_mode === 'uniform' && pricing.manual_segmentation?.base_processing_free !== true)) throw new Error('分割价格响应不完整，不能提交')
+  return { currency: 'OO', credits, phase: 'analysis', wallet: input.space === 'team' ? 'team' : 'personal',
+    team_uid: input.team_uid || null, team_name: doc.team_name || null, segmentation_mode: input.segmentation_mode,
+    uniform_interval_seconds: input.uniform_interval_seconds ?? null, reserve_on: pricing.base_processing?.reserve_on || 'analysis_submit',
+    excludes: ['reverse_prompt', 'delivery_prompt', 'video_generation'] }
+}
+export function repaintDurationPreview(duration, input, limits) {
+  const seconds = typeof duration === 'number' && Number.isFinite(duration) && duration > 0 ? duration : null
+  if (seconds !== null &&
+      ((Number.isFinite(limits.min_duration_seconds) && seconds < limits.min_duration_seconds) ||
+       (Number.isFinite(limits.max_duration_seconds) && seconds > limits.max_duration_seconds)))
+    throw new Error('源视频实际时长不符合当前上传限制；未提交分析')
+  return {
+    source_duration_seconds: seconds,
+    duration_verified: false,
+    duration_evidence: seconds === null ? 'unavailable' : 'stored_media_metadata',
+    ...(input.segmentation_mode === 'uniform' ? {
+      minimum_segment_seconds: 4,
+      maximum_possible_segments: seconds === null ? null : Math.floor(seconds / 4),
+      segment_count_verified: false,
+      note: seconds !== null && seconds < 8
+        ? '按每段至少4秒，当前源片不能分为两段；末段余量会合并。实际段数以服务端方案为准'
+        : '间隔不保证段数；每段至少4秒，末段可能合并或重分。缺少可信媒体时长时先核验，不承诺多段'
+    } : {})
+  }
+}
+async function limitsFor(client) {
+  const limits = await api(client, '/video-segmentation/upload-limits')
+  if (!Number.isSafeInteger(limits?.max_size_bytes) || limits.max_size_bytes < 1 || !Array.isArray(limits.allowed_mime_types) || !limits.allowed_mime_types.length) throw new Error('上传限制响应不完整')
+  return limits
+}
+async function downloadSource(client, doc, input, limits, dir) {
+  const source = doc.nodes.find(n => n.id === input.source_node_id)
+  const response = await requestFile(new URL(mediaUrl(source), client.baseUrl), client.timeout)
+  const mime = (response.headers.get('content-type') || '').split(';')[0].trim().toLowerCase()
+  if (!response.ok || !limits.allowed_mime_types.includes(mime)) { await response.body?.cancel(); throw new Error('源视频读取失败或 MIME 不符合上传限制；未提交分析，请先更新可访问的视频素材地址') }
+  const length = Number(response.headers.get('content-length'))
+  if (length > limits.max_size_bytes) { await response.body?.cancel(); throw new Error('源视频超过上传限制') }
+  const file = path.join(dir, 'source')
+  const handle = await fs.open(file, 'wx', 0o600)
+  let size = 0
+  const digest = crypto.createHash('sha256')
+  try {
+    for await (const chunk of response.body) {
+      size += chunk.length
+      if (size > limits.max_size_bytes) throw new Error('源视频超过上传限制，未提交分析')
+      digest.update(chunk); await handle.writeFile(chunk)
+    }
+  } finally { await handle.close() }
+  if (!size || (length && !response.headers.get('content-encoding') && size !== length)) throw new Error('源视频下载不完整，未提交分析')
+  const filename = path.basename(String(source.data.file_name || source.data.fileName || `source.${mime === 'video/quicktime' ? 'mov' : 'mp4'}`)).replaceAll('\\', '_')
+  return { file, size, mime, filename, sha256: digest.digest('hex') }
+}
+function validateSession(session, source) {
+  const count = Math.ceil(source.size / session?.part_size)
+  if (!session?.upload_id || !session.job_id || !session.object_key || !Number.isSafeInteger(session.part_size) || session.part_size <= 0 || session.part_size > 100 * 1024 * 1024 ||
+    count !== session.total_parts || session.presigned_parts?.length !== count || session.presigned_parts.some((p, i) => p.part_number !== i + 1 || typeof p.url !== 'string')) throw new Error('分片会话无效，未执行分析提交')
+}
+async function uploadParts(client, record, source) {
+  const session = record.session
+  validateSession(session, source)
+  if (record.sourceHash && record.sourceHash !== source.sha256) throw new Error('源视频内容与原上传不同，停止')
+  record.sourceHash = source.sha256
+  record.parts ||= []
+  record.state = 'uploading'; await persist(record)
+  const handle = await fs.open(source.file, 'r')
+  try {
+    for (const part of session.presigned_parts) {
+      if (record.parts.some(p => p.part_number === part.part_number)) continue
+      const offset = (part.part_number - 1) * session.part_size, length = Math.min(session.part_size, source.size - offset)
+      const buffer = Buffer.alloc(length)
+      let read = 0
+      while (read < length) { const { bytesRead } = await handle.read(buffer, read, length - read, offset + read); if (!bytesRead) throw new Error('源视频缓存被截断'); read += bytesRead }
+      const response = await request(part.url, { method: 'PUT', headers: { 'Content-Type': source.mime }, body: buffer }, client.timeout)
+      const etag = response.headers.get('etag'); await response.body?.cancel()
+      if (!response.ok || !etag) throw new Error('分片上传失败或缺少 ETag，未执行分析提交；保留原 operation')
+      record.parts.push({ part_number: part.part_number, etag: etag.replaceAll('"', '') }); await persist(record)
+    }
+  } finally { await handle.close() }
+  record.state = 'uploaded'; await persist(record)
+}
+async function getJob(client, record) {
+  if (!record.jobId) throw new Error('尚无可查询任务 ID；未发起分析，上传会话创建结果不明时不会自动新建')
+  let job
+  try { job = await api(client, jobPath(record.jobId)) }
+  catch (error) {
+    if (['submitting', 'unknown'].includes(record.state)) throw failUnknown('原任务尚无法确认；保留 operation 稍后 repaint recover，勿再次 complete 或更换 operation 重提')
+    throw error
+  }
+  assertJob(job, record)
+  return job
+}
+async function sync(client, record, job, options = {}) {
+  await checkSource(client, record, options.restoreDetail === true)
+  const canvas = await syncRepaintGraph(client, record, job, options)
+  record.state = canvas.materialized ? 'materialized' : ['failed', 'cancelled'].includes(job.status) ? 'failed' : job.status === 'awaiting_review' ? 'awaiting_review' : 'running'
+  record.lastStatus = job.status
+  record.lastPlanVersion = job.plan_version
+  await persist(record)
+  return { operation: record.operation, job, canvas }
+}
+export async function startRepaint(client, profile, rawInput, operation, confirmed = false) {
+  safeName(operation)
+  const input = inputBody(rawInput), owner = await identity(client)
+  let record = await json(recordPath(profile, operation), null)
+  const inputHash = hash(input)
+  if (record && (record.schema !== 1 || record.inputHash !== inputHash || record.baseUrl !== client.baseUrl || record.owner !== owner)) throw new Error('operation 已绑定其他参数、服务或账号，不可复用')
+  if (record?.jobId && !['uploading', 'uploaded'].includes(record.state)) {
+    if (record.state === 'session_creating') throw new Error('上传会话结果未确认，不会自动重建')
+    return recoverRepaint(client, profile, operation)
+  }
+  if (record?.state === 'session_creating') throw new Error('上传会话结果未确认；本次未提交分析，不会自动新建上传会话')
+  const doc = await readCanvas(client, input), key = sourceKey(doc, input)
+  assertAvailable(doc, { input, operation, jobId: record?.jobId })
+  const existing = doc.nodes.find(n => repaintOf(n).role === 'split-detail' && repaintOf(n).sourceNodeId === input.source_node_id && repaintOf(n).parentNodeId === input.entry_node_id && n.id !== record?.detailId)
+  if (existing) throw new Error('该入口与源视频已有分段详情；先使用既有流程，不新建分析')
+  if (record && record.sourceKey !== key) throw new Error('operation 的源视频已变化，不可复用')
+  const estimate = await initialEstimate(client, input, doc), limits = await limitsFor(client)
+  const sourceNode = doc.nodes.find(n => n.id === input.source_node_id)
+  // A generation node's requested duration is not the media's actual duration.
+  const duration = sourceNode.data?.result?.duration ??
+    (sourceNode.type === 'video_upload' ? sourceNode.data?.duration : null)
+  const sourcePreview = repaintDurationPreview(duration, input, limits)
+  if (!record) {
+    if (confirmed) throw new Error('先运行不带 --yes 的 repaint start 展示参数、钱包和费用，再确认提交')
+    const prefix = `cli-repaint-${crypto.randomUUID()}`
+    record = { schema: 1, profile: safeName(profile), operation, input, inputHash, sourceKey: key, baseUrl: client.baseUrl, owner,
+      prefix, detailId: `${prefix}-detail`, groupId: `${prefix}-group`, createdAt: new Date().toISOString(), state: 'prepared' }
+  }
+  if (!confirmed) {
+    record.estimate = estimate; record.estimateHash = hash(estimate); await persist(record)
+    return { submitted: false, operation, input, estimate, limits, source_preview: sourcePreview, next: '展示本次参数、付款钱包和费用，明确确认后使用同一 operation 加 --yes；先核验素材实际时长，不按间隔承诺段数' }
+  }
+  if (hash(estimate) !== record.estimateHash) throw new Error('预估费用或钱包已变化；重新运行不带 --yes 的 start 并取得本次确认')
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'uzoo-repaint-'))
+  try {
+    const source = await downloadSource(client, doc, input, limits, dir)
+    await checkSource(client, record)
+    if (!record.session) {
+      record.state = 'session_creating'; await persist(record)
+      const fields = new URLSearchParams({ filename: source.filename, file_size: String(source.size), mime_type: source.mime,
+        segmentation_mode: input.segmentation_mode, scope: input.space, canvas_doc_id: input.doc_id, canvas_node_id: record.detailId,
+        ...(input.team_uid ? { team_uid: input.team_uid } : {}),
+        ...(input.uniform_interval_seconds !== undefined ? { uniform_interval_seconds: String(input.uniform_interval_seconds) } : {}) })
+      const session = await api(client, '/video-segmentation/upload-sessions', { method: 'POST', body: fields }, { retry: false })
+      // Retain the allocated ID even when validating a malformed session fails.
+      record.session = session; record.jobId = String(session?.job_id || ''); record.state = 'uploading'; await persist(record)
+      validateSession(session, source)
+    }
+    await uploadParts(client, record, source)
+    // Upload may take minutes; recheck ownership, source and pricing before the billable complete.
+    const currentDoc = await checkSource(client, record)
+    if (hash(await initialEstimate(client, input, currentDoc)) !== record.estimateHash) throw new Error('上传后价格或钱包已变化；未 complete，请重新预估并确认')
+    await claimRepaint(client, record)
+    record.state = 'submitting'; await persist(record)
+    let job
+    try {
+      job = await api(client, `/video-segmentation/upload-sessions/${segment(record.session.upload_id)}/complete`, {
+        method: 'POST', body: { object_key: record.session.object_key, expected_parts: record.parts.length, parts: record.parts },
+      }, { retry: false })
+      assertJob(job, record)
+    } catch {
+      record.state = 'unknown'; await persist(record)
+      throw failUnknown(`分析提交结果未确认；使用 repaint recover ${operation} 查询预分配的原任务，勿再次 complete`)
+    }
+    record.state = 'submitted'; await persist(record)
+    return { submitted: true, estimate, ...await sync(client, record, job) }
+  } finally { await fs.rm(dir, { recursive: true, force: true }) }
+}
+export async function repaintGet(client, profile, operation) {
+  const record = await loadRecord(client, profile, operation)
+  await checkSource(client, record, true)
+  const job = await getJob(client, record)
+  return { operation, state: record.state, job }
+}
+export async function confirmRepaint(client, profile, operation, planVersion, confirmed = false) {
+  if (!Number.isSafeInteger(planVersion) || planVersion < 1) throw new Error('--plan-version 必须为正整数')
+  const record = await loadRecord(client, profile, operation)
+  await checkSource(client, record)
+  let job = await getJob(client, record)
+  if (['plan_updating', 'plan_unknown'].includes(record.state)) throw failUnknown('上次方案修改结果未明；先 repaint recover 核对，不继续确认切片')
+  if (job.plan_version !== planVersion) throw new Error('方案版本已变化，重新读取并展示方案')
+  if (job.confirmed_at && job.confirmed_plan_version === planVersion && ['queued', 'rendering', 'completed'].includes(job.status)) return sync(client, record, job)
+  if (['confirming', 'confirmation_unknown'].includes(record.state)) throw failUnknown('上次确认结果未明；先 repaint recover，不能自动再次确认')
+  if (job.status !== 'awaiting_review' || !job.plan?.segments?.length || job.plan.valid === false) throw new Error('任务尚无可确认的有效分割方案')
+  const digest = hash({ plan: job.plan, plan_version: job.plan_version })
+  if (!confirmed) {
+    record.confirmPreview = digest; await persist(record)
+    return { submitted: false, operation, phase: 'confirm_segments', plan_version: planVersion, plan: job.plan,
+      next: '确认分段方案后加 --yes；只启动切片，不提交反推、提示词或视频生成' }
+  }
+  if (record.confirmPreview !== digest) throw new Error('先运行不带 --yes 的 confirm 展示当前分段方案并取得确认')
+  record.confirmVersion = planVersion; record.state = 'confirming'; await persist(record)
+  try {
+    job = await api(client, `${jobPath(record.jobId)}/confirm`, { method: 'POST', body: { plan_version: planVersion } }, { retry: false })
+    assertJob(job, record)
+  } catch {
+    record.state = 'confirmation_unknown'; await persist(record)
+    throw failUnknown('切片确认结果未明；使用 repaint recover 核对原任务，不重复调用 confirm')
+  }
+  record.state = 'running'; await persist(record)
+  return sync(client, record, job)
+}
+export async function updateRepaintPlan(client, profile, operation, body, confirmed = false) {
+  if (!object(body) || Object.keys(body).some(k => !['plan_version', 'boundaries_ms'].includes(k)) ||
+    !Number.isSafeInteger(body.plan_version) || body.plan_version < 1 || !Array.isArray(body.boundaries_ms) || body.boundaries_ms.length < 2 || body.boundaries_ms.length > 64 ||
+    body.boundaries_ms[0] !== 0 || body.boundaries_ms.some((n, i) => !Number.isSafeInteger(n) || n < 0 || (i && n <= body.boundaries_ms[i - 1]))) throw new Error('方案输入必须为 plan_version 和从 0 开始严格递增的整数 boundaries_ms（2–64 个）')
+  const record = await loadRecord(client, profile, operation)
+  await checkSource(client, record)
+  const job = await getJob(client, record)
+  if (['confirming', 'confirmation_unknown'].includes(record.state)) throw failUnknown('上次切片确认结果未明；先 repaint recover 核对，不继续修改方案')
+  if (['plan_updating', 'plan_unknown'].includes(record.state)) throw failUnknown('方案保存结果未明；先 repaint get 核对当前方案，不能重复提交旧版本')
+  if (job.status !== 'awaiting_review' || job.plan_version !== body.plan_version) throw new Error('只能修改当前待确认方案，版本必须一致')
+  if (body.boundaries_ms.at(-1) !== job.plan?.duration_ms) throw new Error('最后一个切点必须等于真实视频总时长')
+  if (!confirmed) return { submitted: false, operation, plan: job.plan, proposed: body, next: '确认切点后加 --yes 保存；保存后重新读取方案版本再 confirm' }
+  record.state = 'plan_updating'; record.proposedPlan = body; await persist(record)
+  let updated
+  try {
+    updated = await api(client, `${jobPath(record.jobId)}/plan`, { method: 'PATCH', body }, { retry: false })
+    assertJob(updated, record)
+  } catch {
+    record.state = 'plan_unknown'; await persist(record)
+    throw failUnknown('方案保存结果未明；使用 repaint recover 核对当前方案，不重放旧版本')
+  }
+  delete record.confirmPreview
+  return sync(client, record, updated)
+}
+export async function recoverRepaint(client, profile, operation, options = {}) {
+  const restoreDetail = options.restoreDetail === true
+  if (options.confirmed && !restoreDetail) throw new Error('--yes仅用于明确的--restore-detail恢复')
+  const record = await loadRecord(client, profile, operation)
+  await checkSource(client, record, restoreDetail)
+  const job = await getJob(client, record)
+  if (restoreDetail) {
+    if (job.status !== 'awaiting_review' || record.state === 'materialized' || record.lastStatus === 'completed') throw new Error('仅支持原待审核任务的详情恢复；不能重建已切片节点链')
+    if (!options.confirmed) return { operation, submitted: false, restoration_saved: false,
+      phase: 'restore_analysis_detail', job_id: job.id, detail_id: record.detailId,
+      plan_version: job.plan_version, next: '协调暂停画布编辑，经用户明确授权后加--restore-detail --yes；仅恢复原任务详情/系统线，不重新分析或确认切片' }
+  }
+  if (['confirming', 'confirmation_unknown'].includes(record.state) &&
+    !(job.confirmed_at && job.confirmed_plan_version === record.confirmVersion && ['queued', 'rendering', 'completed', 'failed', 'cancelled'].includes(job.status))) throw failUnknown('尚不能确认上次切片请求是否生效；保留原记录，不自动重提')
+  if (['plan_updating', 'plan_unknown'].includes(record.state) &&
+    !(job.plan_version > record.proposedPlan.plan_version && JSON.stringify(job.plan?.boundaries_ms) === JSON.stringify(record.proposedPlan.boundaries_ms))) throw failUnknown('尚不能确认上次方案保存是否生效；先核对当前任务方案，不自动重提')
+  return sync(client, record, job, { restoreDetail })
+}
+export async function waitRepaint(client, profile, operation, interval = 3000, timeout = 600000) {
+  const record = await loadRecord(client, profile, operation)
+  if (!Number.isSafeInteger(interval) || interval < 1 || !Number.isSafeInteger(timeout) || timeout < 1) throw new Error('等待间隔和超时必须为正整数')
+  const deadline = Date.now() + timeout
+  while (Date.now() < deadline) {
+    await checkSource(client, record)
+    const job = await getJob(client, record)
+    if (['awaiting_review', 'completed', 'failed', 'cancelled'].includes(job.status)) {
+      const result = await recoverRepaint(client, profile, operation)
+      if (['failed', 'cancelled'].includes(job.status)) { const e = new Error(`任务已${job.status}；已同步状态，使用 repaint get 查看，不自动重做`); e.code = 'TASK_FAILED'; throw e }
+      return result
+    }
+    await sleep(Math.min(interval, Math.max(1, deadline - Date.now())), undefined, { signal: cancellation.signal })
+  }
+  const error = new Error(`等待超时；使用 repaint wait/recover ${operation} 继续原任务，不重新分析`)
+  error.code = 'WAIT_TIMEOUT'; throw error
+}
+export async function listRepaints(profile) {
+  const dir = path.join(root(), 'repaint', safeName(profile))
+  const files = await fs.readdir(dir).catch(error => { if (error.code === 'ENOENT') return []; throw error })
+  return Promise.all(files.filter(f => f.endsWith('.json')).map(async f => {
+    const { operation, state, jobId, createdAt } = await json(path.join(dir, f))
+    return { operation, state, job_id: jobId || null, created_at: createdAt }
+  }))
+}

package/src/resource.js

@@ -0,0 +1,110 @@
+import { upload } from './workflows.js'
+import { writeNode } from './canvas.js'
+
+// Persist the same canonical media fields that the website saves. Binding only
+// reuses the confirmed upload response; it never uploads the file again.
+export async function bindUpload(client, { docId, nodeId, result, imageNode = false }) {
+  if (
+    result?.source_doc_id !== docId ||
+    result?.source_node_id !== nodeId ||
+    !['image', 'video', 'audio'].includes(result.segment_type)
+  )
+    throw new Error('上传响应与画布/节点绑定不一致')
+  const media = result.result
+  if (!media?.url || !media.file_ref) throw new Error('上传响应缺少真实资源引用；先查询原上传记录')
+  const doc = await client.raw(`/canvas/docs/${encodeURIComponent(docId)}`)
+  const node = doc.nodes?.find((n) => n.id === nodeId)
+  const kind = node?.data?.extra?.node_kind
+  if (
+    !node ||
+    (!node.type.endsWith('_upload') &&
+      kind !== 'asset' &&
+      !(imageNode && node.type === 'image' && result.segment_type === 'image')) ||
+    node.data?.extra?.repaint ||
+    node.data?.extra?.video_remake ||
+    node.data?.extra?.clip_redraw
+  )
+    throw new Error('上传绑定仅支持普通素材节点')
+  const data = node.data || {}
+  if (imageNode && !/^[1-9]\d*$/.test(String(result.task_id || '')))
+    throw new Error('图片处理结果缺少真实上传任务')
+  if ((data.mediaType || node.type.replace('_upload', '')) !== result.segment_type)
+    throw new Error('上传媒体类型与素材节点不一致')
+  const ref = data.file_ref || data.extra?.file_ref || data.result?.file_ref
+  if (ref && ref !== media.file_ref) throw new Error('节点已引用其他素材；停止以保留用户编辑')
+  const patch = {
+    data: {
+      uploading: false,
+      uploadError: '',
+      url: media.url,
+      file_ref: media.file_ref,
+      mime_type: media.mime_type,
+      mediaType: result.segment_type,
+      file_name: media.filename,
+      file_size: media.file_size,
+      ...(media.duration ? { duration: media.duration } : {}),
+      result: {
+        ...media,
+        status: 'completed',
+        ...(result.task_id ? { task_id: result.task_id } : {})
+      },
+      status: 'completed',
+      ...(imageNode
+        ? {
+            runtime: {
+              status: 'completed',
+              operation: '',
+              progress: 100,
+              taskId: result.task_id,
+              error: ''
+            }
+          }
+        : {}),
+      ...(result.task_id ? { last_task_id: result.task_id } : {}),
+      extra: {
+        node_kind: imageNode ? 'generation' : 'asset',
+        file_ref: media.file_ref,
+        ...(media.width && media.height ? { aspect_ratio: `${media.width}:${media.height}` } : {})
+      }
+    }
+  }
+  return writeNode(client, {
+    docId,
+    nodeId,
+    patch,
+    update: true,
+    expectedSpace: doc.team_uid ? 'team' : 'personal',
+    expectedTeamUid: doc.team_uid,
+    expectedVersion: doc.version
+  })
+}
+export async function uploadAndBind(client, args) {
+  if (args.node) {
+    const doc = await client.raw(`/canvas/docs/${encodeURIComponent(args.doc)}`)
+    const node = doc.nodes?.find((n) => n.id === args.node)
+    if (
+      !node ||
+      !(node.type.endsWith('_upload') || node.data?.extra?.node_kind === 'asset') ||
+      node.data?.extra?.repaint ||
+      node.data?.extra?.video_remake ||
+      node.data?.extra?.clip_redraw
+    )
+      throw new Error('请选择普通素材节点后上传')
+    if ((node.data?.mediaType || node.type.replace('_upload', '')) !== args.type)
+      throw new Error('上传类型与素材节点不一致')
+  }
+  const result = await upload(client, args)
+  if (!args.node) return result
+  try {
+    const bound = await bindUpload(client, { docId: args.doc, nodeId: args.node, result })
+    return { ...result, document_version: bound.version, canvas_bound: true }
+  } catch (error) {
+    // Upload itself already succeeded; preserve its real response for repair.
+    return {
+      ...result,
+      canvas_bound: false,
+      binding_error: error.message,
+      next: '文件已上传，勿重复上传；保存本响应后 resource bind --input FILE 仅修复节点引用'
+    }
+  }
+}