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

package/src/matting.js

@@ -0,0 +1,170 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import {isDeepStrictEqual as same} from 'node:util'
+import {root,safeName,json,atomic} from './store.js'
+import {mattingInput} from './image-matting.js'
+import {readImageSource} from './image-crop.js'
+import {requireServiceReady} from './service.js'
+import {multipartText} from './multipart.js'
+import {materialScope} from './materials.js'
+import {requestFile} from './api.js'
+import {inspectAlphaPng} from './png-alpha.js'
+
+export const mattingPath=(profile,operation)=>path.join(root(),'image-matting',safeName(profile),safeName(operation),'operation.json')
+const persist=r=>atomic(mattingPath(r.profile,r.operation),r)
+const fail=(code,message,cause)=>Object.assign(Error(message,{cause}),{code})
+const summary=r=>({operation:r.operation,state:r.state,doc_id:r.input.doc_id,source_node_id:r.input.node_id,
+ result_node_id:r.nodeId,source_task_id:r.binding.task_id,processing_submitted:!!r.attempted,generation_submitted:false,library_saved:false,
+ canvas_written:false,canvas_verified:r.state==='completed',credit_cost:r.cost??null,output:r.output||null,
+ ...(r.image?{image:r.image}:{}),...(r.transport?{transport:r.transport,job_id:r.jobId||null,job_status:r.jobStatus||null,reported_credit_cost:r.reportedCreditCost??null}:{}),recovery:{known_result_reference:!!r.receipt?.['x-result-ref'],unknown_submission_replay:false,
+  server_lookup_available:r.transport==='async-job'&&!!r.jobId},...(r.diagnostic?{diagnostic:r.diagnostic}:{})})
+async function context(client,input){
+ await requireServiceReady(client)
+ const c=await readImageSource(client,input),me=await client.raw('/auth/me')
+ if(!me.uid)throw Error('抠图账号缺少UID')
+ const team=input.space==='team'?me.teams?.find(t=>String(t.uid)===input.team_uid&&t.status==='active'):null
+ if(input.space==='team'&&!team)throw Error('抠图目标团队成员身份无效')
+ return {...c,owner:String(me.uid),wallet:{scope:input.space,...(team?{team_uid:input.team_uid,team_name:team.name,shared:true}:{}),
+  balance_snapshot:(team||me).oo_balance??(team||me).credit_balance??null,currency:'OO'}}
+}
+async function bound(client,profile,operation){
+ const r=await json(mattingPath(profile,operation),null)
+ if(!r||r.schema!==1||r.profile!==profile||r.operation!==operation||r.baseUrl!==client.baseUrl)throw Error('抠图operation不存在或服务不匹配')
+ const c=await context(client,mattingInput(r.input))
+ if(c.owner!==r.owner)throw Error('抠图账号不匹配')
+ if(!same(c.node,r.sourceNode)||String(c.binding.task_id)!==String(r.binding.task_id)||c.binding.width!==r.binding.width||c.binding.height!==r.binding.height)
+  throw Error('原图片节点／任务已变化；保留原产物，不覆盖或重发抠图')
+ if(r.output!==path.join(path.dirname(mattingPath(profile,operation)),'response.png'))throw Error('抠图缓存路径不匹配')
+ return {r,c}
+}
+export async function validateMattingBackground(client,profile,operation){
+ const {r,c}=await bound(client,profile,operation)
+ if(r.attempted)throw Error('原抠图已尝试提交；仅查询／恢复，不启动新后台请求')
+ if(r.state!=='prepared'||r.version!==c.doc.version)throw Error('后台执行须使用仍匹配当前画布版本的预览')
+ return r
+}
+export function mattingResultNode(r){
+ const ref=r.receipt['x-result-ref'],url=new URL('/api/v1/files/'+encodeURIComponent(ref),r.baseUrl).href
+ return {id:r.nodeId,type:'image_upload',position:{x:Math.round(Number(r.sourceNode.position?.x||0)+Number(r.sourceNode.width||486)+80),y:Math.round(Number(r.sourceNode.position?.y||0))},
+  width:486,height:300,data:{title:(r.sourceNode.data.title||'图片')+'（抠图）',mediaType:'image',url,file_name:'matting.png',file_size:r.image.bytes,
+   aspect_ratio:r.image.width+':'+r.image.height,status:'completed',last_task_id:null,
+   result:{url,file_ref:ref,mime_type:'image/png',width:r.image.width,height:r.image.height,status:'completed'},
+   extra:{node_kind:'asset',file_ref:ref,matting:{status:'completed',progress:100,error:'',creditCost:String(r.cost)}}}}
+}
+export function mattingResultMatches(r,doc){
+ const node=doc.nodes.find(n=>n.id===r.nodeId),edge=doc.edges.find(e=>e.id===r.edgeId),d=node?.data||{}
+ if(!node||!edge||node.type!=='image_upload'||d.extra?.node_kind!=='asset'||d.mediaType!=='image'||
+  d.extra?.file_ref!==r.receipt?.['x-result-ref']||d.file_name!==r.pendingNode?.data.file_name||d.file_size!==r.image?.bytes||
+  d.title!==r.pendingNode.data.title||(d.last_task_id||d.lastTaskId||d.runtime?.taskId)||
+  edge.source!==r.input.node_id||edge.target!==r.nodeId||edge.data?.role!=='matting-link')return false
+ try{
+  const wanted=new URL('/api/v1/files/'+encodeURIComponent(r.receipt['x-result-ref']),r.baseUrl)
+  const actual=new URL(d.url||d.result?.url,r.baseUrl)
+  return actual.origin===wanted.origin&&actual.pathname===wanted.pathname&&!actual.username&&!actual.password
+ }catch{return false}
+}
+const matches=(r,c)=>mattingResultMatches(r,c.doc)
+async function saveResult(client,r,c,confirmed){
+ if(r.saveAttempted){
+  const verified=matches(r,c)
+  if(verified){r.state='completed';await persist(r)}
+  return {...summary(r),canvas_verified:verified,state:!verified&&r.state==='completed'?'canvas_changed':r.state,version:c.doc.version,
+   canvas_exactly_matches:same(c.doc.nodes.find(n=>n.id===r.nodeId),r.pendingNode)&&same(c.doc.edges.find(e=>e.id===r.edgeId),r.pendingEdge)}
+ }
+ if(!confirmed)return summary(r)
+ if(c.doc.nodes.some(n=>n.id===r.nodeId)||c.doc.edges.some(e=>e.id===r.edgeId))throw Error('抠图结果ID已存在，不覆盖')
+ if(!Number.isSafeInteger(c.doc.version)||!c.doc.viewport||!c.doc.meta||!Array.isArray(c.doc.edges)||new Set(c.doc.nodes.map(n=>n.id)).size!==c.doc.nodes.length)throw Error('抠图画布快照无效')
+ r.pendingNode=mattingResultNode(r)
+ r.pendingEdge={id:r.edgeId,source:r.input.node_id,target:r.nodeId,sourceHandle:'',targetHandle:'',type:'default',data:{role:'matting-link',system:true}}
+ r.beforeSave=c.doc;r.saveAttempted=true;r.state='saving';await persist(r)
+ try{
+  const d=c.doc,saved=await client.raw('/canvas/docs/'+encodeURIComponent(d.id),{method:'PUT',body:{version:d.version,name:d.name,viewport:d.viewport,
+   nodes:[...d.nodes,r.pendingNode],edges:[...d.edges,r.pendingEdge],meta:d.meta}},{retry:false})
+  if(saved.version!==d.version+1)throw Error('抠图保存响应版本无效')
+  const after=await context(client,r.input)
+  if(!matches(r,after)||!same(after.doc.nodes.filter(n=>n.id!==r.nodeId),d.nodes)||!same(after.doc.edges.filter(e=>e.id!==r.edgeId),d.edges)||
+   !['name','viewport','meta'].every(k=>same(after.doc[k],d[k])))throw Error('抠图保存读回不一致')
+  r.state='completed';await persist(r)
+  return {...summary(r),canvas_written:true,version:after.doc.version}
+ }catch(error){r.state=error.status===409||error.apiCode===3002?'conflict':'save_unknown';await persist(r);throw fail('MATTING_SYNC_PENDING','抠图结果保存未确认；原matting-recover只读核对，不重放保存',error)}
+}
+async function validateCached(r){
+ const bytes=await fs.readFile(r.output),image=inspectAlphaPng(bytes)
+ if(image.width!==r.binding.width||image.height!==r.binding.height)throw Error('抠图结果尺寸与原图不同；保留结果，不重发')
+ if(r.image&&!same(r.image,image))throw Error('抠图缓存摘要或透明像素统计变化')
+ r.image=image;r.state='result_ready';await persist(r)
+}
+export async function startMatting(client,profile,value,operation,confirmed=false,{backgroundId,deferCanvas=false}={}){
+ const input=mattingInput(value),old=await json(mattingPath(profile,operation),null)
+ if(old){
+  if(!same(old.input,input))throw Error('原抠图operation输入不可更改')
+  if(old.backgroundId&&backgroundId!==old.backgroundId&&!old.attempted)throw fail('MATTING_BACKGROUND_ACTIVE','原operation已交给后台；使用matting-status查询，不并行提交')
+  if(old.attempted)return recoverMatting(client,profile,operation,confirmed)
+ }
+ const c=await context(client,input)
+ if(old&&(old.baseUrl!==client.baseUrl||old.owner!==c.owner))throw Error('抠图operation已绑定其他服务或账号')
+ if(!confirmed){
+  const r={schema:1,profile,operation,baseUrl:client.baseUrl,owner:c.owner,input,sourceNode:c.node,binding:c.binding,version:c.doc.version,
+   nodeId:old?.nodeId||'matting-'+crypto.randomUUID(),edgeId:old?.edgeId||'matting-link-'+crypto.randomUUID(),
+   output:path.join(path.dirname(mattingPath(profile,operation)),'response.png'),state:'prepared',createdAt:old?.createdAt||new Date().toISOString()}
+  await persist(r)
+  return {...summary(r),source:c.source,wallet:c.wallet,expected_credit_cost:0,pricing_policy:{mode:'free',basis:'user-confirmed product contract',response_verified:false},
+   expected_version:c.doc.version,next:'确认免费处理及目标画布关闭后，同operation加--yes；未知响应绝不重发'}
+ }
+ if(!old)throw Error('抠图须先预览同一operation')
+ const {r,c:current}=await bound(client,profile,operation)
+ if(current.doc.version!==r.version)throw Error('预览后画布版本变化，先重新预览')
+ const form=multipartText({file_ref:current.binding.file_ref,model:'general',...materialScope(input.space,input.team_uid)})
+ r.attempted=true;r.state='submitting';await persist(r)
+ let response
+ try{response=await client.raw('/matting',{method:'POST',...form},{retry:false,binaryPng:true})}
+ catch(error){
+  r.state=[2001,2010,2011,2012,2205].includes(error.apiCode)||[400,401,403,404,422].includes(error.status)?'rejected':'submission_unknown'
+  r.diagnostic={...(error.status?{http_status:error.status}:{}),...(error.apiCode?{api_code:error.apiCode}:{}),...(error.requestId?{request_id:error.requestId}:{})}
+  await persist(r);throw fail('MATTING_SUBMISSION_PENDING','抠图未取得原结果；保留operation，不重发推理。明确拒绝／未知响应分别见state',error)
+ }
+ r.receipt=response.headers;r.state='response_received';await persist(r)
+ // Cache the original bytes before validating any server metadata, including cost.
+ await fs.writeFile(r.output,response.body,{flag:'wx',mode:0o600})
+ const ref=r.receipt['x-result-ref'],source=r.receipt['x-source-ref'],cost=r.receipt['x-credit-cost']
+ if(!/^fr1_[A-Za-z0-9_-]+={0,2}$/.test(ref||'')||source!==current.binding.file_ref||cost!=='0'){
+  r.state='receipt_unverified';await persist(r);throw Error('抠图结果引用／源引用／免费费用响应不匹配；已保留原字节，不自动落图或重发')
+ }
+ r.cost=0
+ try{await validateCached(r)}catch(error){r.state='result_unverified';await persist(r);throw error}
+ if(deferCanvas)return {...summary(r),next:'后台已缓存原结果；确认画布关闭后，用原matting-recover --yes落图，不重做抠图'}
+ const checked=await bound(client,profile,operation)
+ return saveResult(client,r,checked.c,true)
+}
+export async function recoverMatting(client,profile,operation,confirmed=false){
+ const stored=await json(mattingPath(profile,operation),null)
+ if(stored?.transport==='async-job'){
+  const {recoverMattingJob}=await import('./matting-jobs.js')
+  return recoverMattingJob(client,profile,operation,confirmed)
+ }
+ const {r,c}=await bound(client,profile,operation)
+ if(r.saveAttempted)return saveResult(client,r,c,false)
+ if(['prepared','submitting','submission_unknown','rejected','receipt_unverified','result_unverified'].includes(r.state))return summary(r)
+ if(!r.receipt?.['x-result-ref']||r.receipt['x-credit-cost']!=='0'||r.receipt['x-source-ref']!==r.binding.file_ref)return summary(r)
+ r.cost=0
+ await cacheMattingReference(client,r,confirmed)
+ await validateCached(r)
+ return saveResult(client,r,c,confirmed)
+}
+async function cacheMattingReference(client,r,confirmed){
+ try{await fs.access(r.output)}catch(error){
+  if(error.code!=='ENOENT'||!confirmed)throw error
+  const response=await requestFile(new URL('/api/v1/files/'+encodeURIComponent(r.receipt['x-result-ref']),client.baseUrl),client.timeout)
+  if(!response.ok||!/^image\/png(?:;|$)/i.test(response.headers.get('content-type')||'')) {await response.body?.cancel();throw Error('原抠图结果GET不可用；不重新处理')}
+  const chunks=[];let size=0
+  for await(const chunk of response.body){size+=chunk.length;if(size>128*1024*1024)throw Error('原结果超过128MB');chunks.push(chunk)}
+  await fs.writeFile(r.output,Buffer.concat(chunks,size),{flag:'wx',mode:0o600})
+ }
+}
+
+// Shared verified-result pipeline for transport adapters. Transport-specific
+// submission and task lookup must not bypass account/source binding, PNG
+// validation, or the single-attempt canvas save contract.
+export {bound as readBoundMatting,summary as mattingSummary,persist as persistMatting,
+ validateCached as validateMattingCache,saveResult as saveMattingResult,cacheMattingReference}

package/src/media-copy.js

@@ -0,0 +1,53 @@
+// Persistent canvas protocol counterpart of clipboard.js and copiedNodeHistory.js.
+// Source task IDs in copied history are provenance, never the copy's running task.
+const text = value => String(value ?? '').trim()
+export function captureMediaHistory(node) {
+  const d=node.data, e=d.extra||{}, r=d.result||{}
+  const history=structuredClone(d.copiedGenerationHistory ?? e.copied_generation_history ?? [])
+  if(!Array.isArray(history))throw Error('复制来源历史格式无效')
+  const url=text(d.resultUrl||r.url)
+  if(!url||history.some(h=>h.url===url))return history
+  const task=text(d.lastTaskId||d.last_task_id||d.runtime?.taskId||d.sourceTaskId||e.source_task_id)
+  const modes={text2image:'text-to-image',image2image:'image-to-image',text_to_video:'text-to-video',image_reference:'image-reference',video_reference:'video-reference',audio_reference:'audio-reference',combined_reference:'combined-reference',video_editing:'video-editing',video_extension:'video-extension'}
+  const mode=d.imageMode||d.videoMode||modes[e.generation_mode]||(node.type==='image'?'text-to-image':'text-to-video')
+  const raw={id:task||`copied-${node.id}`,task_no:text(d.taskNo||d.runtime?.taskNo||r.task_no||e.task_no),source:'copied',node_id:node.id,
+    status:'completed',progress:100,prompt:d.effectivePrompt||d.prompt||'',model_name:d.model||d.model_name,
+    generation_mode:mode,aspect_ratio:d.aspectRatio||e.aspect_ratio||'',
+    resolution:d.resolution||e.resolution||'',quality:d.quality||e.quality||null,extra:{image_count:Number(d.imageCount||e.image_count)||0},
+    result:{...r,url,file_ref:d.resultFileRef||r.file_ref||e.file_ref||'',width:d.imageWidth||d.videoWidth,height:d.imageHeight||d.videoHeight}}
+  // Match the frontend normalized history shape. JSON round trip omits optional
+  // absent raw fields exactly as they are omitted by the API serializer.
+  const item={id:'copied:'+raw.id,taskId:task,taskNo:raw.task_no,docId:'',nodeId:node.id,segmentType:'',contentType:'',source:'copied',jobId:'',segmentIndex:null,taskVersion:null,
+    status:'completed',progress:100,creditCost:0,draft:null,url,fileRef:text(raw.result.file_ref),mimeType:text(r.mime_type||r.mimeType),width:Number(raw.result.width)||null,height:Number(raw.result.height)||null,duration:Number(r.duration)||null,
+    text:'',structured:null,structuredRender:null,structuredMeta:null,model:text(raw.model_name||r.model),prompt:text(raw.prompt),referenceImageUrls:[],referenceVideoUrls:[],referenceAudioUrls:[],referenceAssetIds:[],
+    mode:text(raw.generation_mode),aspectRatio:text(raw.aspect_ratio),resolution:text(raw.resolution),quality:text(raw.quality),imageCount:Number(raw.extra.image_count)||1,error:'',generatedAt:'',createdAt:'',completedAt:'',raw}
+  return JSON.parse(JSON.stringify([item,...history]))
+}
+
+export function buildMediaCopy(source) {
+  const d=source?.data||{},e=d.extra||{}
+  const asset=source?.type?.endsWith('_upload')||e.node_kind==='asset'
+  const type=asset?(d.mediaType||source.type.replace('_upload','')):source?.type
+  if(!['image','video',...(asset?['audio']:[])].includes(type))throw Error('复制仅支持普通文本、图片/视频生成节点及图片/视频/音频素材')
+  if(d.generation_config||d.node_output)throw Error('当前节点配置协议未接入复制')
+  const copy=structuredClone(source),data=copy.data
+  if(asset){
+    // Upload task association identifies the original uploaded file, not a new
+    // generation. Keep it for review/library reuse, as the web clipboard does.
+    data.extra={...e,node_kind:'asset'}
+    return {copy,kind:'asset',source_task_id:text(d.sourceTaskId||e.source_task_id||d.last_task_id||d.lastTaskId||d.runtime?.taskId)}
+  }
+  const history=captureMediaHistory(source)
+  const task=text(d.lastTaskId||d.last_task_id||d.runtime?.taskId||d.result?.task_id||d.sourceTaskId||e.source_task_id)
+  const complete=(d.runtime?.status||d.status)==='completed'||Boolean((d.resultUrl||d.result?.url)&&history.length)
+  for(const key of ['lastTaskId','last_task_id','taskId','task_id','taskNo','task_no','progress','error_message','errorMessage'])delete data[key]
+  data.status=complete?'completed':null
+  if(data.runtime)data.runtime={status:complete?'completed':'idle',progress:complete?100:0,taskId:'',taskNo:'',error:''}
+  if(data.result&&typeof data.result==='object')for(const key of ['taskId','task_id','taskNo','task_no'])delete data.result[key]
+  data.extra={...e}
+  delete data.extra.task_no
+  if(history.length){data.extra.copied_generation_history=history;data.extra.source_task_id=task;data.extra.node_kind='generation'}
+  // Canonical persistent fields avoid divergent camel/snake histories.
+  delete data.copiedGenerationHistory;delete data.sourceTaskId
+  return {copy,kind:'generation',source_task_id:task,copied_history_count:history.length}
+}

package/src/media.js

@@ -0,0 +1,343 @@
+import { spawn } from 'node:child_process'
+import fs from 'node:fs/promises'
+import crypto from 'node:crypto'
+import { requestFile, cancellation } from './api.js'
+
+const mediaError = (message) => Object.assign(new Error(message), { code: 'MEDIA_UNAVAILABLE' })
+export async function runMedia(
+  exe,
+  args,
+  { timeout = 120000, maxBytes = 16 * 1024 * 1024, cwd } = {}
+) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(exe, args, {
+      windowsHide: true,
+      shell: false,
+      ...(cwd ? { cwd } : {}),
+      stdio: ['ignore', 'pipe', 'pipe']
+    })
+    const chunks = []
+    let bytes = 0,
+      settled = false
+    const finish = (error, output) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      cancellation.signal.removeEventListener('abort', abort)
+      error ? reject(error) : resolve(output)
+    }
+    const abort = () => {
+      child.kill()
+      finish(mediaError('媒体处理已中断；保留原操作，未提交生成'))
+    }
+    const timer = setTimeout(() => {
+      child.kill()
+      finish(mediaError('媒体处理超时；请检查源文件与解码工具'))
+    }, timeout)
+    cancellation.signal.addEventListener('abort', abort, { once: true })
+    if (cancellation.signal.aborted) abort()
+    child.stdout.on('data', (chunk) => {
+      bytes += chunk.length
+      if (bytes > maxBytes) {
+        child.kill()
+        finish(mediaError('媒体元数据超过可处理范围，停止解析'))
+      } else chunks.push(chunk)
+    })
+    // Do not echo arbitrary media metadata, paths or decoder stderr into CLI logs.
+    child.stderr.resume()
+    child.on('error', (error) =>
+      finish(
+        Object.assign(mediaError('无法运行媒体工具；请检查依赖、路径与执行权限'), {
+          toolFailure: error.code === 'ENOENT' ? 'missing' : 'unavailable'
+        })
+      )
+    )
+    child.on('close', (code) =>
+      code === 0
+        ? finish(null, Buffer.concat(chunks))
+        : finish(mediaError('媒体解码工具执行失败；检查格式、完整性及工具版本，不自动上传'))
+    )
+  })
+}
+export async function mediaTools(options = {}) {
+  const tools = { ffmpeg: options.ffmpeg || 'ffmpeg', ffprobe: options.ffprobe || 'ffprobe' }
+  const checks = []
+  for (const [kind, executable] of Object.entries(tools)) {
+    try {
+      const output = (
+        await runMedia(executable, ['-version'], { timeout: 10000, maxBytes: 65536 })
+      ).toString()
+      checks.push({
+        tool: kind,
+        status: output.startsWith(kind + ' version') ? 'available' : 'invalid_response'
+      })
+    } catch (error) {
+      if (cancellation.signal.aborted) throw error
+      checks.push({ tool: kind, status: error.toolFailure || 'unavailable' })
+    }
+  }
+  if (checks.some((check) => check.status !== 'available')) {
+    const missing = checks.filter((check) => check.status === 'missing').map((check) => check.tool)
+    const installable =
+      missing.length > 0 && checks.every((check) => ['available', 'missing'].includes(check.status))
+    throw Object.assign(
+      mediaError(
+        installable
+          ? '无法运行媒体工具：未找到 ' +
+              missing.join('、') +
+              '。本地媒体处理需要 FFmpeg（包含 ffmpeg 和 ffprobe）；请先询问用户是否安装，或由用户提供已有工具路径，同意安装后才能执行安装并继续原任务'
+          : '媒体工具未通过检查；先核对已有工具路径、执行权限与版本，再决定处理方式'
+      ),
+      {
+        dependency: {
+          status: installable ? 'awaiting_dependency_installation' : 'dependency_unavailable',
+          package: 'FFmpeg',
+          required_tools: ['ffmpeg', 'ffprobe'],
+          missing_tools: missing,
+          checks,
+          installation_requires_confirmation: true,
+          installation_performed: false,
+          next: installable ? 'ask_user_to_install_or_provide_paths' : 'check_existing_tools'
+        }
+      }
+    )
+  }
+  return tools
+}
+export async function hashFile(file) {
+  const handle = await fs.open(file, 'r')
+  try {
+    const stat = await handle.stat(),
+      hash = crypto.createHash('sha256')
+    for await (const chunk of handle.createReadStream({ autoClose: false })) hash.update(chunk)
+    return { bytes: stat.size, sha256: hash.digest('hex') }
+  } finally {
+    await handle.close()
+  }
+}
+export async function downloadMedia(client, url, target, type = 'video') {
+  const destination = new URL(url, new URL(client.baseUrl).origin)
+  const response = await requestFile(destination, client.timeout)
+  const length = Number(response.headers.get('content-length')) || 0
+  const max = 500 * 1024 * 1024
+  if (
+    !response.ok ||
+    !response.headers
+      .get('content-type')
+      ?.toLowerCase()
+      .startsWith(type + '/') ||
+    length > max
+  ) {
+    await response.body?.cancel()
+    throw new Error('源媒体不是可下载的媒体或超过 500MB；未开始处理或上传')
+  }
+  const handle = await fs.open(target, 'wx', 0o600)
+  let bytes = 0
+  try {
+    for await (const chunk of response.body) {
+      bytes += chunk.length
+      if (bytes > max) throw new Error('源媒体超过 500MB，停止下载')
+      await handle.writeFile(chunk)
+    }
+    if (!bytes || (length && !response.headers.get('content-encoding') && bytes !== length))
+      throw new Error('源媒体下载不完整，停止处理')
+  } finally {
+    await handle.close()
+  }
+  return hashFile(target)
+}
+export const downloadVideo = (client, url, target) => downloadMedia(client, url, target, 'video')
+export const downloadImage = (client, url, target) => downloadMedia(client, url, target, 'image')
+// Signed references may be reissued for the same immutable media across days.
+// Verify bytes through the normal anonymous file proxy, never decode tokens or
+// compare only filenames/dimensions. Cache only within this client invocation.
+const referenceChecks = new WeakMap()
+async function sameMediaReferences(client, left, right, type) {
+  if (left === right) return true
+  if (![left, right].every((ref) => typeof ref === 'string' && /^fr1_[A-Za-z0-9_=-]+$/.test(ref)))
+    return false
+  let checks = referenceChecks.get(client)
+  if (!checks) referenceChecks.set(client, (checks = new Map()))
+  const fingerprint = (ref) => {
+    const cacheKey = type + ':' + ref
+    if (!checks.has(cacheKey)) {
+      const promise = (async () => {
+        const response = await requestFile(
+          client.baseUrl + '/files/' + encodeURIComponent(ref),
+          client.timeout
+        )
+        const length = Number(response.headers.get('content-length')) || 0
+        const max = 500 * 1024 * 1024
+        if (
+          !response.ok ||
+          !response.headers
+            .get('content-type')
+            ?.toLowerCase()
+            .startsWith(type + '/') ||
+          length > max
+        ) {
+          await response.body?.cancel()
+          throw new Error('无法核验更新的媒体引用；停止，不跳过来源校验')
+        }
+        const hash = crypto.createHash('sha256')
+        let bytes = 0
+        for await (const chunk of response.body) {
+          bytes += chunk.length
+          if (bytes > max) throw new Error('引用核验的媒体超过 500MB')
+          hash.update(chunk)
+        }
+        if (!bytes || (length && !response.headers.get('content-encoding') && bytes !== length))
+          throw new Error('引用核验的媒体读取不完整')
+        return { bytes, sha256: hash.digest('hex') }
+      })()
+      checks.set(cacheKey, promise)
+      promise.catch(() => checks.delete(cacheKey))
+    }
+    return checks.get(cacheKey)
+  }
+  const a = await fingerprint(left),
+    b = await fingerprint(right)
+  return a.bytes === b.bytes && a.sha256 === b.sha256
+}
+export const sameVideoReferences = (client, left, right) =>
+  sameMediaReferences(client, left, right, 'video')
+export const sameImageReferences = (client, left, right) =>
+  sameMediaReferences(client, left, right, 'image')
+export async function probeMedia(file, tools) {
+  const bytes = await runMedia(tools.ffprobe, [
+    '-v',
+    'error',
+    '-protocol_whitelist',
+    'file,pipe',
+    '-select_streams',
+    'v:0',
+    '-show_streams',
+    '-show_format',
+    '-of',
+    'json',
+    file
+  ])
+  let data
+  try {
+    data = JSON.parse(bytes)
+  } catch {
+    throw mediaError('媒体元数据响应无效')
+  }
+  const stream = data.streams?.[0]
+  const duration = Number(stream?.duration || data.format?.duration)
+  if (
+    !stream ||
+    !Number.isSafeInteger(stream.width) ||
+    !Number.isSafeInteger(stream.height) ||
+    stream.width <= 0 ||
+    stream.height <= 0 ||
+    stream.width * stream.height > 64000000
+  )
+    throw mediaError('源媒体缺少有效尺寸或超过 6400 万像素')
+  const [a, b] = String(stream.avg_frame_rate || '')
+    .split('/')
+    .map(Number)
+  return {
+    width: stream.width,
+    height: stream.height,
+    duration,
+    fps: b ? a / b : 0,
+    codec: stream.codec_name,
+    rotation: Number(
+      stream.side_data_list?.find((item) => item.rotation !== undefined)?.rotation ||
+        stream.tags?.rotate ||
+        0
+    ),
+    orientation: Number(stream.tags?.orientation || 1)
+  }
+}
+export async function extractFrames(source, times, targets, tools) {
+  const metadata = await probeMedia(source, tools)
+  if (
+    !Number.isFinite(metadata.duration) ||
+    metadata.duration <= 0 ||
+    times.some((ms) => ms >= metadata.duration * 1000)
+  )
+    throw new Error('截帧时刻必须早于实际视频末尾')
+  const tolerance = Math.max(1, 500 / (metadata.fps > 0 ? metadata.fps : 30))
+  if (
+    times.some((time, index) =>
+      times.slice(0, index).some((other) => Math.abs(time - other) < tolerance)
+    )
+  )
+    throw new Error('截帧时刻过近，属于重复选帧；请按视频帧步长选择')
+  // Match the frame whose presentation interval contains the requested time,
+  // rather than seeking to the next frame or assuming a constant frame rate.
+  const raw = await runMedia(tools.ffprobe, [
+    '-v',
+    'error',
+    '-protocol_whitelist',
+    'file,pipe',
+    '-select_streams',
+    'v:0',
+    '-show_frames',
+    '-show_entries',
+    'frame=best_effort_timestamp_time',
+    '-of',
+    'json',
+    source
+  ])
+  let frames
+  try {
+    frames = JSON.parse(raw).frames
+  } catch {
+    throw mediaError('视频帧时间戳无效')
+  }
+  const stamps = frames?.map((frame) => Number(frame.best_effort_timestamp_time))
+  if (
+    !stamps?.length ||
+    stamps.some((t) => !Number.isFinite(t)) ||
+    stamps.some((t, i) => i && t < stamps[i - 1])
+  )
+    throw mediaError('视频缺少单调的帧时间戳，不能准确截帧')
+  const origin = stamps[0],
+    entries = []
+  for (let i = 0; i < times.length; i++) {
+    let index = 0
+    while (index + 1 < stamps.length && (stamps[index + 1] - origin) * 1000 <= times[i] + 0.001)
+      index++
+    await runMedia(tools.ffmpeg, [
+      '-nostdin',
+      '-v',
+      'error',
+      '-protocol_whitelist',
+      'file,pipe',
+      '-i',
+      source,
+      '-map',
+      '0:v:0',
+      '-vf',
+      'select=eq(n\\,' + index + ')',
+      '-fps_mode',
+      'passthrough',
+      '-frames:v',
+      '1',
+      '-q:v',
+      '2',
+      '-n',
+      targets[i]
+    ])
+    const head = await fs.open(targets[i], 'r')
+    try {
+      const bytes = Buffer.alloc(3)
+      await head.read(bytes, 0, 3, 0)
+      if (!bytes.equals(Buffer.from([255, 216, 255]))) throw mediaError('截帧产物不是有效 JPEG')
+    } finally {
+      await head.close()
+    }
+    const image = await probeMedia(targets[i], tools)
+    entries.push({
+      time_ms: times[i],
+      frame_time_ms: Math.round((stamps[index] - origin) * 1000),
+      width: image.width,
+      height: image.height,
+      ...(await hashFile(targets[i]))
+    })
+  }
+  return entries
+}

package/src/model-options.js

@@ -0,0 +1,76 @@
+import { spaceContext } from './canvas.js'
+
+// Ordinary node controls only. Development evidence: ImageNode, VideoNode,
+// nodeFactories.js and shared/constants/modelOptions.js in the web application.
+// This projection is discovery data, never a generation request or approval.
+const values = (list) => Array.isArray(list)
+  ? [...new Set(list.map((v) => String(v || '').trim()).filter(Boolean))] : []
+const preferred = (list, value) => list.includes(value) ? value : list[0] || null
+export function imageQualityDefault(model) {
+  const options = values(model.quality_options)
+  return options.includes('medium') ? 'medium'
+    : preferred(options, String(model.quality || model.quality_default || '').trim()) || ''
+}
+export function projectModelOptions(model) {
+  const type = model.content_type
+  const controls = []
+  const problems = []
+  const draftName = String(model.label || '').trim().toLowerCase() === 'seedance 2.5 draft'
+  const draft = type === 'video' && draftName && model.is_sample_mode === true
+  if (type === 'video' && draftName !== (model.is_sample_mode === true))
+    problems.push('样片模型名称与目录 is_sample_mode 不一致，需核对当前部署兼容性')
+  const seedance25 = ['seedance-2.5', 'seedance2.5', 'seedance 2.5'].includes(String(model.label || '').trim().toLowerCase())
+  const add = (key, label, options, suggested) => {
+    if (options.length) controls.push({ key, label, kind: 'choice', options,
+      suggested, node_path: `data.${key}`, mirror_node_paths: [`data.extra.${key}`] })
+  }
+  if (['image', 'video'].includes(type)) {
+    const aspects = values(model.aspect_ratios)
+    const resolutions = draft
+      ? ['480p'] : values(model.resolutions)
+    add('aspect_ratio', '画面比例', aspects, preferred(aspects, '16:9'))
+    add('resolution', '分辨率', resolutions, preferred(resolutions, type === 'image' ? '1K' : '720p'))
+    if (draft) {
+      const resolution = controls.find(c => c.key === 'resolution')
+      Object.assign(resolution, { kind: 'fixed', value: '480p', reason: '前端样片模式锁定分辨率' })
+      if (!values(model.resolutions).includes('480p')) problems.push('样片目录缺少 480p，当前 CLI 无法准备此配置')
+    }
+    if (type === 'image') {
+      add('quality', '图片质量', values(model.quality_options), imageQualityDefault(model))
+      controls.push({ key: 'image_count', label: '图片数量', kind: 'fixed', value: 1,
+        node_path: 'data.image_count', mirror_node_paths: ['data.extra.image_count'], reason: '当前普通图片请求准备仅接入单张' })
+    } else {
+      const bound = (value, fallback) => value == null || String(value).trim() === '' ? fallback : Number(value)
+      const min = bound(model.durations?.min, 4)
+      const max = bound(model.durations?.max, 15)
+      if (!Number.isFinite(min) || !Number.isFinite(max) || min <= 0 || max < min)
+        problems.push('模型时长范围无效，不能提供可执行时长选项')
+      else controls.push({ key: 'duration', label: '视频时长（秒）', kind: 'range', min, max,
+        step: 1, suggested: Math.min(max, Math.max(min, 5)), node_path: 'data.duration' })
+      if (seedance25) for (const control of controls) control.not_applicable_modes = ['video_editing']
+    }
+  }
+  if (model.member_locked === true) problems.push('当前空间会员权限受限')
+  return {
+    label: model.label, content_type: type, selectable: problems.length === 0,
+    ...(problems.length ? { unavailable_reason: problems.join('；') } : {}),
+    workflow: 'ordinary_generation',
+    model_node_path: 'data.model_name', controls,
+    // Capability information is deliberately separate from editable controls.
+    generation_modes: Array.isArray(model.generation_modes) ? model.generation_modes : [],
+    requires_parameter_confirmation: true
+  }
+}
+export async function modelOptions(client, { space, teamUid, type }) {
+  if (!['text', 'image', 'video'].includes(type)) throw new Error('--type 必须是 text/image/video')
+  const context = spaceContext({ space, teamUid })
+  const query = new URLSearchParams({ ...context, content_type: type })
+  const catalog = await client.raw(`/canvas/models?${query}`)
+  if (!Array.isArray(catalog.items)) throw new Error('模型目录缺少 items，不能生成交互选项')
+  return {
+    space, team_uid: context.team_uid || null, content_type: type,
+    items: catalog.items.filter((m) => m.content_type === type).map(projectModelOptions),
+    submitted: false,
+    next: '通过交互卡片选择模型及适用参数，保存节点后运行 generation prepare；本输出不代表用户已确认'
+  }
+}