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

package/src/material-download.js

@@ -0,0 +1,55 @@
+import path from 'node:path'
+import fs from 'node:fs/promises'
+import crypto from 'node:crypto'
+import { materialGet } from './materials.js'
+import { requestFile } from './api.js'
+import { exclusiveOutput } from './local-output.js'
+import { downloadName } from './download-name.js'
+
+// Material download is a separate permission gate. A URL returned by list/get
+// never substitutes for a rejected download, even if that URL is still valid.
+export async function downloadMaterial(client, { space, teamUid, assetId, output, expectedHash }) {
+  if (typeof output !== 'string' || !output.trim()) throw new Error('素材下载必须提供--output FILE')
+  if (expectedHash !== undefined && (typeof expectedHash !== 'string' || !/^[a-fA-F0-9]{64}$/.test(expectedHash)))
+    throw new Error('--sha256 必须是64位十六进制')
+  // Resolve scope through the actual folder list and asset detail before asking
+  // the server for a new original-file link. No filename or format override.
+  const asset = await materialGet(client, { space, teamUid, assetId })
+  if (String(asset.id) !== String(assetId) || !/^(image|video|audio)\//.test(asset.mime_type || '') || !asset.file_ref)
+    throw new Error('素材身份、媒体类型或原文件引用不完整，停止下载')
+  const major = asset.mime_type.split('/')[0]
+  const link = await client.raw('/material-space/assets/' + encodeURIComponent(String(assetId)) + '/download',
+    {}, { retry: false })
+  if (!link?.file_ref || typeof link.url !== 'string' || !link.url.trim() ||
+      (link.format !== undefined && link.format !== 'original'))
+    throw new Error('素材原文件下载接口未返回有效原格式链接；不改用列表地址或转换格式')
+  const url = new URL(link.url, new URL(client.baseUrl).origin)
+  if (url.searchParams.has('format') && url.searchParams.get('format') !== 'original')
+    throw new Error('原文件下载链接包含转换参数；停止，不更改服务端URL或偷偷转换')
+  const saved = await exclusiveOutput(output, async temporary => {
+    const response = await requestFile(url, client.timeout)
+    const mime = (response.headers.get('content-type') || '').split(';')[0].trim().toLowerCase()
+    if (mime !== 'application/octet-stream' && !mime.startsWith(major + '/')) {
+      await response.body?.cancel()
+      throw new Error('素材下载内容类型与原素材不一致；未保存文件')
+    }
+    const handle = await fs.open(temporary, 'wx', 0o600)
+    const hash = crypto.createHash('sha256')
+    let bytes = 0
+    try {
+      for await (const chunk of response.body) {
+        await handle.writeFile(chunk)
+        hash.update(chunk)
+        bytes += chunk.length
+      }
+      const sha256 = hash.digest('hex'), length = response.headers.get('content-length')
+      if (!bytes || (length !== null && !response.headers.get('content-encoding') && bytes !== Number(length)) ||
+          (expectedHash && sha256 !== expectedHash.toLowerCase()))
+        throw new Error('素材下载文件完整性校验失败；未保存文件')
+      return { bytes, sha256, server_filename: downloadName(response.headers, link.filename) }
+    } finally { await handle.close() }
+  })
+  return { ...saved, output: path.resolve(output), asset_id: asset.id, format: 'original',
+    ...(typeof link.filename === 'string' ? { filename: link.filename } : {}),
+    canvas_written: false, generation_submitted: false, processing_submitted: false, library_saved: false }
+}

package/src/material-save.js

@@ -0,0 +1,254 @@
+import crypto from 'node:crypto'
+import path from 'node:path'
+import { atomic, json, root, safeName } from './store.js'
+import { materialFolders, materialGet, scopedCanvas } from './materials.js'
+import { readSource } from './generation-input.js'
+import { segment } from './workflows.js'
+
+const text = (value) => String(value ?? '').trim()
+const digest = (value) => crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex')
+const errorOf = (code, message, diagnostic) =>
+  Object.assign(new Error(message), { code, ...(diagnostic ? { diagnostic } : {}) })
+export const materialSavePath = (profile, operation) =>
+  path.join(root(), 'material-saves', safeName(profile), safeName(operation) + '.json')
+const positiveId = (value) => {
+  if (!/^[1-9]\d*$/.test(text(value)) || !Number.isSafeInteger(Number(value)))
+    throw new Error('任务和目录 ID 必须为正安全整数')
+  return Number(value)
+}
+function normalizeInput(value) {
+  if (
+    !value ||
+    Array.isArray(value) ||
+    typeof value !== 'object' ||
+    Object.keys(value).some(
+      (key) =>
+        !['doc_id', 'node_id', 'space', 'team_uid', 'folder_id', 'name', 'description'].includes(
+          key
+        )
+    )
+  )
+    throw new Error('保存素材输入无效或包含未接入字段')
+  if (!text(value.doc_id) || !text(value.node_id)) throw new Error('缺少来源 doc_id/node_id')
+  const input = { ...value, folder_id: positiveId(value.folder_id) }
+  if (
+    value.name !== undefined &&
+    (typeof value.name !== 'string' || !value.name.trim() || value.name.trim().length > 200)
+  )
+    throw new Error('素材名称须为 1–200 个字符')
+  if (value.description !== undefined && typeof value.description !== 'string')
+    throw new Error('素材说明必须为字符串')
+  if (value.name !== undefined) input.name = value.name.trim()
+  return input
+}
+async function identity(client) {
+  const me = await client.raw('/auth/me')
+  const owner = text(me.uid ?? me.id)
+  if (!owner) throw new Error('账号信息缺少 UID')
+  return owner
+}
+async function sourceContext(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 ||
+    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 (
+    !['image', 'video'].includes(source.mediaType) ||
+    !source.url ||
+    source.uploading ||
+    source.uploadError
+  )
+    throw new Error('来源没有已完成上传的图片/视频输出')
+  const taskId = positiveId(data.lastTaskId || data.last_task_id || data.runtime?.taskId || data.sourceTaskId || data.extra?.source_task_id)
+  const task = await client.raw('/canvas/generations/' + segment(taskId))
+  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 (new Set(refs).size !== 1 || !task.result?.file_ref || 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 !== source.mediaType ||
+    task.status !== 'completed'
+  )
+    throw new Error('素材来源与同画布已完成图片/视频任务不匹配')
+  const folders = await materialFolders(client, { space: input.space, teamUid: input.team_uid })
+  if (!folders.items?.some((folder) => String(folder.id) === String(input.folder_id)))
+    throw new Error('目标目录不属于确认的素材空间')
+  const name = input.name ?? text(data.title || data.name)
+  if (name.length > 200) throw new Error('素材名称超过 200 个字符，请明确名称')
+  const body = {
+    task_id: taskId,
+    folder_id: input.folder_id,
+    ...(name ? { name } : {}),
+    ...(input.description ? { description: input.description } : {})
+  }
+  return { body, mediaType: source.mediaType, sourceRef: refs[0] }
+}
+const summary = (record) => ({
+  operation: record.operation,
+  state: record.state,
+  task_id: record.body.task_id,
+  folder_id: record.body.folder_id,
+  asset_id: record.assetId || null,
+  ...(record.asset ? { asset: record.asset } : {}),
+  ...(record.lastFailure ? { last_failure: record.lastFailure } : {})
+})
+async function bound(client, profile, operation) {
+  const record = await json(materialSavePath(profile, operation), null)
+  if (!record) throw new Error('未找到素材保存 operation')
+  if (record.baseUrl !== client.baseUrl || record.owner !== (await identity(client)))
+    throw new Error('素材保存 operation 的服务或账号不匹配')
+  if (record.bodyHash !== digest(record.body)) throw new Error('素材保存请求摘要不匹配，停止恢复')
+  return record
+}
+function validateAsset(asset, record) {
+  positiveId(asset?.id)
+  if (
+    String(asset.folder_id) !== String(record.body.folder_id) ||
+    !text(asset.mime_type)
+      .toLowerCase()
+      .startsWith(record.mediaType + '/') ||
+    !asset.url ||
+    !asset.file_ref
+  )
+    throw errorOf(
+      'MATERIAL_SAVE_UNKNOWN',
+      '保存响应素材的目录/类型/引用不完整；查询原 operation，不新建保存'
+    )
+  return asset
+}
+async function verifySaved(client, profile, record) {
+  const asset = validateAsset(
+    await materialGet(client, {
+      space: record.input.space,
+      teamUid: record.input.team_uid,
+      assetId: record.assetId
+    }),
+    record
+  )
+  record.state = 'saved'
+  record.asset = asset
+  await atomic(materialSavePath(profile, record.operation), record)
+  return summary(record)
+}
+async function execute(client, profile, record) {
+  record.state = 'submitting'
+  await atomic(materialSavePath(profile, record.operation), record)
+  let response
+  try {
+    response = await client.raw(
+      '/material-space/assets/save-from-canvas',
+      { method: 'POST', body: record.body },
+      { retry: false }
+    )
+  } catch (error) {
+    const rejected =
+      [401, 403, 404, 422].includes(error.status) ||
+      [1000, 2000, 2001, 3001].includes(error.apiCode)
+    record.state = rejected ? 'rejected' : 'unknown'
+    record.lastFailure = {
+      code: rejected ? 'MATERIAL_SAVE_REJECTED' : 'MATERIAL_SAVE_UNKNOWN',
+      ...(Number.isInteger(error.status) ? { http_status: error.status } : {}),
+      ...(Number.isFinite(error.apiCode) ? { api_code: error.apiCode } : {}),
+      ...(error.requestId ? { request_id: error.requestId } : {})
+    }
+    await atomic(materialSavePath(profile, record.operation), record)
+    throw errorOf(
+      record.lastFailure.code,
+      rejected
+        ? '素材保存请求被拒绝；先核对原目录和接口错误，不自动另建保存'
+        : '素材保存结果未确认；先查目标目录与原 operation，仅明确恢复时沿用原幂等键',
+      record.lastFailure
+    )
+  }
+  try {
+    validateAsset(response, record)
+  } catch (error) {
+    record.state = 'unknown'
+    await atomic(materialSavePath(profile, record.operation), record)
+    throw error
+  }
+  record.assetId = response.id
+  record.state = 'verifying'
+  await atomic(materialSavePath(profile, record.operation), record)
+  // A failed read-back never causes another POST. The returned ID is already durable.
+  return verifySaved(client, profile, record)
+}
+export async function startMaterialSave(client, profile, value, operation, confirmed = false) {
+  const input = normalizeInput(value),
+    file = materialSavePath(profile, operation)
+  const existing = await json(file, null)
+  if (existing) {
+    const record = await bound(client, profile, operation)
+    if (digest(input) !== digest(record.input)) throw new Error('同一保存 operation 不可变更输入')
+    // Repeated start is a query, even with --yes. Recovery is explicit.
+    return getMaterialSave(client, profile, operation)
+  }
+  const owner = await identity(client),
+    context = await sourceContext(client, input)
+  if (!confirmed)
+    return {
+      operation,
+      submitted: false,
+      generation_submitted: false,
+      wallet: { space: input.space, team_uid: input.team_uid || null },
+      ...context.body,
+      media_type: context.mediaType,
+      next: '核对来源与目录后，加 --yes 直接保存原结果；不下载重传或提交生成'
+    }
+  const body = { ...context.body, idempotency_key: 'cli-material-' + crypto.randomUUID() }
+  const record = {
+    operation,
+    owner,
+    baseUrl: client.baseUrl,
+    input,
+    body,
+    bodyHash: digest(body),
+    mediaType: context.mediaType,
+    sourceRef: context.sourceRef,
+    state: 'prepared',
+    createdAt: new Date().toISOString()
+  }
+  await atomic(file, record)
+  return execute(client, profile, record)
+}
+export async function getMaterialSave(client, profile, operation) {
+  const record = await bound(client, profile, operation)
+  return record.assetId
+    ? verifySaved(client, profile, record)
+    : {
+        ...summary(record),
+        next: '先列目标目录核对；需要恢复未知提交时，save-recover 原 operation --yes 沿用原请求和幂等键'
+      }
+}
+export async function recoverMaterialSave(client, profile, operation, confirmed = false) {
+  const record = await bound(client, profile, operation)
+  if (record.assetId) return verifySaved(client, profile, record)
+  if (!confirmed || record.state === 'rejected') return getMaterialSave(client, profile, operation)
+  const current = await sourceContext(client, record.input)
+  const { idempotency_key, ...original } = record.body
+  if (
+    !idempotency_key ||
+    digest(current.body) !== digest(original) ||
+    current.sourceRef !== record.sourceRef ||
+    current.mediaType !== record.mediaType
+  )
+    throw new Error('保存期间源素材、任务、目录或参数已变化；不重发原请求')
+  return execute(client, profile, record)
+}

package/src/materials.js

@@ -0,0 +1,147 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { segment, uploadParts } from './workflows.js'
+import { spaceContext, writeNode } from './canvas.js'
+
+export function materialScope(space, teamUid) {
+  spaceContext({ space, teamUid })
+  return { scope: space, ...(space === 'team' ? { team_uid: teamUid } : {}) }
+}
+const query = (endpoint, params) =>
+  endpoint + '?' + new URLSearchParams(Object.entries(params).filter(([, v]) => v !== undefined))
+export async function scopedCanvas(client, docId, space, teamUid) {
+  materialScope(space, teamUid)
+  const doc = await client.raw(`/canvas/docs/${segment(docId)}`)
+  if (doc.id !== docId || String(doc.team_uid || '') !== String(space === 'team' ? teamUid : ''))
+    throw new Error('画布归属与确认空间不一致')
+  if (!['owner', 'editor'].includes(doc.role)) throw new Error('画布不可编辑')
+  return doc
+}
+export async function materialFolders(client, { space, teamUid }) {
+  return client.raw(query('/material-space/folders', materialScope(space, teamUid)))
+}
+export async function materialList(
+  client,
+  { space, teamUid, folderId, keyword, limit = 50, offset = 0 }
+) {
+  if (
+    !Number.isSafeInteger(limit) ||
+    limit < 1 ||
+    limit > 200 ||
+    !Number.isSafeInteger(offset) ||
+    offset < 0
+  )
+    throw new Error('素材分页参数无效')
+  return client.raw(
+    query('/material-space/assets', {
+      ...materialScope(space, teamUid),
+      folder_id: folderId,
+      keyword,
+      limit,
+      offset
+    })
+  )
+}
+export async function materialGet(client, { space, teamUid, assetId }) {
+  if (!/^[1-9][0-9]*$/.test(String(assetId))) throw new Error('asset ID 必须为正整数')
+  const folders = await materialFolders(client, { space, teamUid })
+  const asset = await client.raw(`/material-space/assets/${segment(assetId)}`)
+  if (!folders.items?.some((f) => String(f.id) === String(asset.folder_id)))
+    throw new Error('素材不属于确认的素材空间')
+  return asset
+}
+export async function materialUpload(client, { space, teamUid, folderId, file, mime, name }) {
+  const folders = await materialFolders(client, { space, teamUid })
+  if (!folders.items?.some((f) => String(f.id) === String(folderId)))
+    throw new Error('目标文件夹不属于确认空间')
+  const type = String(mime || '').split('/')[0]
+  if (!['image', 'audio', 'video'].includes(type))
+    throw new Error('素材 MIME 必须为 image/audio/video')
+  const limits = await client.raw('/material-space/upload-limits')
+  const handle = await fs.open(file, 'r')
+  try {
+    const stat = await handle.stat()
+    if (
+      !stat.isFile() ||
+      stat.size <= 0 ||
+      !Number.isFinite(limits.max_size_bytes) ||
+      stat.size > limits.max_size_bytes ||
+      !limits.allowed_mime_prefixes?.some((p) => mime.startsWith(p))
+    )
+      throw new Error('素材不符合实际上传限制')
+    const session = await client.raw(
+      '/uploads/sessions',
+      {
+        method: 'POST',
+        body: {
+          media_type: type,
+          filename: path.basename(file),
+          file_size: stat.size,
+          mime_type: mime,
+          purpose: 'material',
+          scope_id: String(folderId)
+        }
+      },
+      { retry: false }
+    )
+    const parts = await uploadParts(client, handle, stat, session, mime)
+    await client.raw(
+      `/uploads/sessions/${segment(session.upload_id)}/complete`,
+      {
+        method: 'POST',
+        body: { object_key: session.object_key, expected_parts: parts.length, parts }
+      },
+      { retry: false }
+    )
+    const body = new URLSearchParams({
+      folder_id: String(folderId),
+      upload_id: session.upload_id,
+      name: name || path.basename(file)
+    })
+    // No automatic replay: after an ambiguous response, inspect the same folder first.
+    return await client.raw(
+      '/material-space/assets/upload',
+      { method: 'POST', body },
+      { retry: false }
+    )
+  } finally {
+    await handle.close()
+  }
+}
+export async function materialUse(client, { space, teamUid, assetId, docId, nodeId, position }) {
+  if (
+    position !== undefined &&
+    (!position ||
+      typeof position !== 'object' ||
+      !Number.isFinite(position.x) ||
+      !Number.isFinite(position.y))
+  )
+    throw new Error('position.x/y 必须为有限数字')
+  const doc = await scopedCanvas(client, docId, space, teamUid)
+  const asset = await materialGet(client, { space, teamUid, assetId })
+  const type = String(asset.mime_type || '').split('/')[0]
+  if (!['image', 'video', 'audio'].includes(type) || !asset.url || !asset.file_ref)
+    throw new Error('素材缺少可用媒体引用')
+  if (doc.nodes.some((n) => n.id === nodeId))
+    throw new Error('目标节点已存在；先读回核对，不重复导入')
+  return writeNode(client, {
+    docId,
+    nodeId,
+    type: `${type}_upload`,
+    expectedSpace: space,
+    expectedTeamUid: teamUid,
+    patch: {
+      position: position || { x: 120, y: 130 },
+      data: {
+        title: asset.name,
+        url: asset.url,
+        file_ref: asset.file_ref,
+        mime_type: asset.mime_type,
+        file_name: asset.name,
+        width: asset.width,
+        height: asset.height,
+        extra: { file_ref: asset.file_ref, material_asset_id: asset.id }
+      }
+    }
+  })
+}

package/src/matting-background.js

@@ -0,0 +1,73 @@
+import path from 'node:path'
+import {fileURLToPath} from 'node:url'
+import crypto from 'node:crypto'
+import {spawn} from 'node:child_process'
+import {atomic,json,safeName} from './store.js'
+import {baseUrl} from './api.js'
+import {mattingPath,validateMattingBackground} from './matting.js'
+
+export const mattingWorkerPath=(profile,operation,id)=>path.join(path.dirname(mattingPath(profile,operation)),'background-'+safeName(id)+'.json')
+const alive=pid=>{
+ if(!Number.isSafeInteger(pid)||pid<1)return false
+ try{process.kill(pid,0);return true}catch(error){return error.code==='EPERM'?null:false}
+}
+const active=new Set(['launching','waiting_lock','running'])
+export async function mattingBackgroundStatus(store,operation){
+ const r=await json(mattingPath(store.name,operation),null)
+ if(!r||r.schema!==1||r.profile!==store.name||r.operation!==operation)throw Error('未找到原抠图operation')
+ const config=await store.config()
+ if(config.baseUrl&&baseUrl(config.baseUrl)!==r.baseUrl)throw Error('抠图operation服务与当前profile不匹配')
+ const worker=r.backgroundId?await json(mattingWorkerPath(store.name,operation,r.backgroundId),null):null
+ if(worker&&(worker.worker_id!==r.backgroundId||worker.profile!==store.name||worker.operation!==operation||worker.baseUrl!==r.baseUrl))throw Error('后台记录绑定不匹配')
+ const running=worker?.pid?alive(worker.pid):false
+ const interrupted=!!worker&&active.has(worker.status)&&worker.pid&&running===false
+ const launchUnconfirmed=!!worker&&active.has(worker.status)&&!worker.pid&&Date.now()-Date.parse(worker.updated_at)>=30000
+ const state=interrupted&&r.attempted&&!r.receipt&&r.state==='submitting'?'submission_unknown':r.state
+ const since=worker?.started_at||worker?.created_at
+ const elapsed=since?Math.max(0,(worker?.finished_at?Date.parse(worker.finished_at):Date.now())-Date.parse(since)):null
+ return {operation,profile:store.name,base_url:r.baseUrl,state,doc_id:r.input.doc_id,source_node_id:r.input.node_id,
+  ...(r.transport?{transport:r.transport,job_id:r.jobId||null,job_status:r.jobStatus||null}:{}),
+  ...(r.diagnostic?{diagnostic:r.diagnostic}:{}),
+  result_node_id:r.nodeId,credit_cost:r.cost??null,output:r.output||null,...(r.image?{image:r.image}:{}),
+  worker_status:interrupted?'interrupted':launchUnconfirmed?'launch_unconfirmed':worker?.status||'not_started',worker_alive:worker?.pid?running:false,
+  ...(worker?.pid?{worker_pid:worker.pid}:{}),worker_error:worker?.error||null,
+  phase:state==='submitting'?'waiting_response_including_queue':state,progress:null,elapsed_ms:elapsed,
+  updated_at:worker?.updated_at||null,poll_after_ms:worker&&active.has(worker.status)&&!interrupted&&!launchUnconfirmed?3000:null,
+  processing_request_attempted:!!r.attempted,known_result_reference:!!r.receipt?.['x-result-ref'],
+  background_auto_saves_canvas:false,read_only:true,local_only:true,account_verified_online:false,
+  canvas_written:false,processing_submitted:false,library_saved:false,
+  next:r.transport==='async-job'?(r.jobId?'此为本地快照；matting-get联网查询原job，成功后matting-recover --yes回填':'尚未取得job_id；保留原operation及诊断，请服务端核对原request_id，不重发'):state==='result_ready'?'原PNG已缓存；确认画布关闭后matting-recover --yes回填':interrupted?
+   '后台进程已退出；保留原operation，不自动重发。若profile锁残留，确认原进程退出后按现有锁规则处理':
+   worker&&active.has(worker.status)?'约3秒后查询同一operation；排队时间计入等待，不按3秒判失败':'保留原operation查询／恢复，不重做抠图'}
+}
+export async function launchMattingBackground(client,store,operation,confirmed=false,{requestTimeout=180000}={}){
+ const existing=await json(mattingPath(store.name,operation),null)
+ if(!existing)throw Error('后台抠图须先用image matting预览同一operation')
+ if(existing.baseUrl!==client.baseUrl)throw Error('后台抠图服务不匹配')
+ if(existing.attempted)return mattingBackgroundStatus(store,operation)
+ if(existing.backgroundId){
+  const old=await json(mattingWorkerPath(store.name,operation,existing.backgroundId),null)
+  if(old&&active.has(old.status)&&(old.pid?alive(old.pid)!==false:Date.now()-Date.parse(old.updated_at)<30000))return mattingBackgroundStatus(store,operation)
+ }
+ if(!confirmed)return {...await mattingBackgroundStatus(store,operation),next:'确认本次免费处理后matting-start 原operation --yes；后台仅缓存，不写画布'}
+ if(!Number.isSafeInteger(requestTimeout)||requestTimeout<1||requestTimeout>1800000)throw Error('后台request-timeout须为1–1800000毫秒')
+ const r=await validateMattingBackground(client,store.name,operation),id=crypto.randomUUID()
+ const record={schema:1,profile:store.name,operation,baseUrl:client.baseUrl,worker_id:id,status:'launching',
+  created_at:new Date().toISOString(),updated_at:new Date().toISOString(),request_timeout:requestTimeout}
+ r.backgroundId=id
+ await atomic(mattingPath(store.name,operation),r)
+ await atomic(mattingWorkerPath(store.name,operation,id),record)
+ try{
+  const child=spawn(process.execPath,[fileURLToPath(new URL('./matting-worker.js',import.meta.url)),store.name,operation,id,String(requestTimeout)],
+   {detached:true,windowsHide:true,stdio:'ignore',cwd:path.dirname(fileURLToPath(import.meta.url))})
+  await new Promise((resolve,reject)=>{child.once('spawn',resolve);child.once('error',reject)})
+  child.unref()
+  // Only the worker writes its status after spawn; a parent write could overwrite
+  // an already completed response when the service responds immediately.
+  return {...await mattingBackgroundStatus(store,operation),worker_pid:child.pid,worker_alive:alive(child.pid),background_started:true,read_only:false,local_only:false,next:'启动命令可以退出；约3秒后matting-status查询原operation。后台只缓存，回填另用原recover --yes'}
+ }catch(error){
+  record.status='launch_failed';record.error={code:'WORKER_LAUNCH_FAILED'};record.updated_at=new Date().toISOString()
+  await atomic(mattingWorkerPath(store.name,operation,id),record)
+  throw Object.assign(Error('抠图后台未能启动；查询原operation，不创建新操作',{cause:error}),{code:'MATTING_BACKGROUND_FAILED'})
+ }
+}

package/src/matting-jobs.js

@@ -0,0 +1,63 @@
+import {readBoundMatting,mattingSummary,persistMatting,validateMattingCache,saveMattingResult,cacheMattingReference} from './matting.js'
+import {multipartText} from './multipart.js'
+import {materialScope} from './materials.js'
+
+const states=new Set(['queued','processing','succeeded','failed','cancelled'])
+const jobId=value=>typeof value==='string'&&/^[A-Za-z0-9_-]{1,200}$/.test(value)?value:null
+const ref=value=>typeof value==='string'&&/^fr1_[A-Za-z0-9_-]+={0,2}$/.test(value)
+const pending=(message,diagnostic)=>Object.assign(Error(message),{code:'MATTING_SUBMISSION_PENDING',...(diagnostic?{diagnostic}:{})})
+
+export async function submitMattingJob(client,profile,operation,confirmed=false){
+ const {r,c}=await readBoundMatting(client,profile,operation)
+ if(r.attempted)return r.transport==='async-job'?recoverMattingJob(client,profile,operation,false):mattingSummary(r)
+ if(r.backgroundId)throw Error('原operation已交给本地后台，不改为异步任务提交')
+ if(r.transport&&r.transport!=='async-job')throw Error('原抠图传输类型不匹配')
+ if(r.state!=='prepared'||c.doc.version!==r.version)throw Error('异步提交须先预览并匹配当前画布版本')
+ if(!confirmed)return {...mattingSummary(r),next:'确认本次免费处理后matting-submit 原operation --yes；只入队，不自动写画布'}
+ r.transport='async-job';r.attempted=true;r.state='submitting';await persistMatting(r)
+ let response
+ try{
+  response=await client.raw('/matting/jobs',{method:'POST',...multipartText({file_ref:r.binding.file_ref,model:'general',...materialScope(r.input.space,r.input.team_uid)})},{retry:false,jsonMetadata: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 persistMatting(r);throw pending('异步抠图未取得已确认提交；查询原operation，不重POST',r.diagnostic)
+ }
+ // Keep any usable ID before interpreting status; an unexpected receipt must
+ // never cause the same operation to submit again.
+ r.jobId=jobId(response.data?.job_id)
+ r.state=r.jobId?'job_submitted':'submission_unknown'
+ await persistMatting(r)
+ if(response.status!==202||!r.jobId)throw pending('异步提交响应不是202或缺少有效job_id；保留原operation及已知ID，不重发')
+ return {...mattingSummary(r),poll_after_ms:3000,next:'任务已入队，可退出CLI；matting-get查询原job，完成后原matting-recover --yes回填'}
+}
+
+export async function recoverMattingJob(client,profile,operation,confirmed=false){
+ const {r,c}=await readBoundMatting(client,profile,operation)
+ if(r.transport!=='async-job')throw Error('原operation不是异步抠图任务')
+ if(r.saveAttempted)return saveMattingResult(client,r,c,false)
+ if(!r.jobId)return {...mattingSummary(r),next:'提交未取得job_id，无法按ID查回；不自动重提、不认领最新同源任务'}
+ const data=await client.raw('/matting/jobs/'+encodeURIComponent(r.jobId))
+ if(!data||!states.has(data.status)||(data.job_id!==undefined&&data.job_id!==r.jobId)){
+  r.state='job_response_unverified';await persistMatting(r);throw Error('抠图job响应身份／状态不匹配，保留原job_id')
+ }
+ r.jobStatus=data.status;r.jobCheckedAt=new Date().toISOString()
+ if(typeof data.credit_cost==='number'&&Number.isFinite(data.credit_cost))r.reportedCreditCost=data.credit_cost
+ r.state='job_'+data.status
+ await persistMatting(r)
+ if(data.status!=='succeeded')return {...mattingSummary(r),poll_after_ms:['queued','processing'].includes(data.status)?3000:null}
+ if(!ref(data.result_ref)||![0,'0'].includes(data.credit_cost)||(data.source_ref!==undefined&&data.source_ref!==r.binding.file_ref)){
+  r.state='job_result_unverified';await persistMatting(r);throw Error('抠图job结果引用／免费费用／来源不匹配，不下载落图或重做')
+ }
+ if(r.receipt&&r.receipt['x-result-ref']!==data.result_ref){r.state='job_result_unverified';await persistMatting(r);throw Error('原抠图job结果引用变化，保留缓存并停止落图')}
+ r.cost=0;r.receiptType='job-query'
+ r.receipt={'x-result-ref':data.result_ref,'x-source-ref':r.binding.file_ref,'x-credit-cost':'0'}
+ r.state='job_succeeded';await persistMatting(r)
+ // result_url may be an external delivery URL. Retrieve through the trusted
+ // service's original file-reference route, anonymously and without API tokens.
+ if(!confirmed)return {...mattingSummary(r),next:'原job已成功；确认画布关闭后matting-recover 原operation --yes取回PNG并保存'}
+ await cacheMattingReference(client,r,true)
+ try{await validateMattingCache(r)}catch(error){r.state='result_unverified';await persistMatting(r);throw error}
+ const current=await readBoundMatting(client,profile,operation)
+ return saveMattingResult(client,r,current.c,true)
+}

package/src/matting-worker.js

@@ -0,0 +1,49 @@
+import {setTimeout as sleep} from 'node:timers/promises'
+import {Store,json,atomic} from './store.js'
+import {ApiClient} from './api.js'
+import {startMatting,mattingPath} from './matting.js'
+import {mattingWorkerPath} from './matting-background.js'
+
+// Internal entry point. Arguments identify the already bound local operation;
+// credentials are loaded from its protected profile, never passed in argv/logs.
+async function run(){
+ const [profile,operation,id,timeoutText]=process.argv.slice(2)
+ const timeout=Number(timeoutText),store=new Store(profile),file=mattingWorkerPath(profile,operation,id)
+ if(!Number.isSafeInteger(timeout)||timeout<1||timeout>1800000)throw Error('Invalid worker timeout')
+ const worker=await json(file,null),first=await json(mattingPath(profile,operation),null)
+ if(!worker||worker.worker_id!==id||worker.profile!==profile||worker.operation!==operation||first?.backgroundId!==id)return
+ let updates=Promise.resolve(),timer,unlock
+ const write=patch=>{
+  Object.assign(worker,patch,{updated_at:new Date().toISOString()})
+  const snapshot=structuredClone(worker)
+  updates=updates.catch(()=>{}).then(()=>atomic(file,snapshot));return updates
+ }
+ try{
+  await write({pid:process.pid,status:'waiting_lock',started_at:new Date().toISOString()})
+  timer=setInterval(()=>{void write({heartbeat_at:new Date().toISOString()}).catch(()=>{})},1000)
+  const deadline=Date.now()+30000
+  while(!unlock){
+   try{unlock=await store.lock()}catch(error){
+    if(!error.message.startsWith('该 profile 正被使用')||Date.now()>=deadline)throw error
+    await sleep(100)
+   }
+  }
+  const record=await json(mattingPath(profile,operation),null)
+  if(record?.backgroundId!==id||record.attempted||record.state!=='prepared')throw Object.assign(Error('Worker reservation changed'),{code:'WORKER_RESERVATION_CHANGED'})
+  const client=new ApiClient(await store.load(),store,timeout)
+  if(client.baseUrl!==worker.baseUrl||record.baseUrl!==worker.baseUrl)throw Object.assign(Error('Worker service changed'),{code:'WORKER_BINDING_CHANGED'})
+  await write({status:'running'})
+  const result=await startMatting(client,profile,record.input,operation,true,{backgroundId:id,deferCanvas:true})
+  clearInterval(timer);timer=null;await updates
+  await write({status:'finished',finished_at:new Date().toISOString(),result_state:result.state})
+ }catch(error){
+  if(timer){clearInterval(timer);timer=null};await updates.catch(()=>{})
+  await write({status:'failed',finished_at:new Date().toISOString(),error:{code:typeof error.code==='string'?error.code:'WORKER_FAILED',
+   ...(Number.isInteger(error.status)?{http_status:error.status}:{}),...(Number.isInteger(error.apiCode)?{api_code:error.apiCode}:{})}})
+  process.exitCode=1
+ }finally{
+  if(timer)clearInterval(timer)
+  if(unlock)await unlock()
+ }
+}
+run().catch(()=>{process.exitCode=1})