@lingjingai/lj-awb-cli-pre 0.3.15

package/packages/awb-core/src/artifact.js

@@ -0,0 +1,936 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { apiFetch } from './api.js';
+import { LingjingAwbCliError, parseJsonArg, toBool, trimToNull } from './common.js';
+
+const WORKBENCH_PREFIX = '/api/anime/workbench';
+
+function argumentError(message, hint = '') {
+  return new LingjingAwbCliError(message, {
+    type: 'argument_error',
+    exitCode: 2,
+    hint,
+  });
+}
+
+function ensureConfirmed(kwargs, message, details = {}) {
+  if (toBool(kwargs?.dryRun)) return;
+  if (toBool(kwargs?.yes)) return;
+  throw new LingjingAwbCliError(message, {
+    type: 'confirmation_required',
+    exitCode: 10,
+    hint: '确认后追加 --yes 重试；如果只是预览，请追加 --dry-run。',
+    details,
+  });
+}
+
+function compactRecord(record = {}) {
+  return Object.fromEntries(Object.entries(record)
+    .filter(([, value]) => value !== undefined && value !== null && value !== ''));
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function requireValue(kwargs, key, label = key) {
+  const value = trimToNull(kwargs?.[key]);
+  if (!value) {
+    throw argumentError(`缺少参数：--${label.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`)}`);
+  }
+  return value;
+}
+
+function requireProjectId(kwargs) {
+  const projectId = requireValue(kwargs, 'projectId', 'project-id');
+  if (!/^\d+$/.test(String(projectId))) throw argumentError('--project-id 必须是数字');
+  return projectId;
+}
+
+function requireNumericValue(kwargs, key, label = key) {
+  const value = requireValue(kwargs, key, label);
+  if (!/^\d+$/.test(String(value))) throw argumentError(`--${label.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`)} 必须是数字`);
+  return value;
+}
+
+function artifactPath(kind, projectId, suffix = '') {
+  return `${WORKBENCH_PREFIX}/${kind}-output/projects/${encodeURIComponent(projectId)}${suffix}`;
+}
+
+async function readJsonFile(filePath) {
+  const absolutePath = path.resolve(String(filePath || ''));
+  try {
+    return JSON.parse(await fs.readFile(absolutePath, 'utf8'));
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      throw argumentError(`JSON 文件不存在：${absolutePath}`);
+    }
+    if (error instanceof SyntaxError) {
+      throw argumentError(`JSON 文件解析失败：${absolutePath}`, error.message);
+    }
+    throw error;
+  }
+}
+
+async function pathExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readBodyPayload(kwargs = {}) {
+  const bodyJson = trimToNull(kwargs.bodyJson);
+  const inputFile = trimToNull(kwargs.inputFile);
+  if (bodyJson) {
+    try {
+      return parseJsonArg(bodyJson);
+    } catch (error) {
+      throw argumentError('--body-json 不是有效 JSON', error.message);
+    }
+  }
+  if (inputFile) return await readJsonFile(inputFile);
+  throw argumentError('缺少请求体：传 --body-json <json> 或 --input-file <path>');
+}
+
+function firstValue(source, ...keys) {
+  if (!isPlainObject(source)) return undefined;
+  for (const key of keys) {
+    if (source[key] !== undefined && source[key] !== null) return source[key];
+  }
+  return undefined;
+}
+
+function textValue(source, ...keys) {
+  const value = firstValue(source, ...keys);
+  return value === undefined || value === null ? undefined : String(value);
+}
+
+function numberFromId(value, fallback = 0) {
+  const match = String(value || '').match(/(\d+)/);
+  return match ? Number.parseInt(match[1], 10) : fallback;
+}
+
+function byKind(rows) {
+  return rows.reduce((acc, row) => {
+    const key = row.rowKind || 'unknown';
+    acc[key] = (acc[key] || 0) + 1;
+    return acc;
+  }, {});
+}
+
+function scriptDocumentRow(script) {
+  return compactRecord({
+    rowKind: 'document',
+    entityKey: 'document',
+    parentKey: null,
+    schemaVersion: firstValue(script, 'schemaVersion', 'schema_version'),
+    revisionNo: firstValue(script, 'revisionNo', 'revision_no') ?? 1,
+    sortOrder: 0,
+    title: script.title,
+    worldview: script.worldview,
+    worldviewRaw: firstValue(script, 'worldviewRaw', 'worldview_raw'),
+    style: script.style,
+    mode: script.mode,
+    compat: compactRecord({
+      source: 'script.json',
+      schemaVersion: firstValue(script, 'schemaVersion', 'schema_version'),
+    }),
+  });
+}
+
+function scriptAssetRows(script) {
+  const rows = [];
+  const actors = Array.isArray(script.actors) ? script.actors : [];
+  const locations = Array.isArray(script.locations) ? script.locations : [];
+  const props = Array.isArray(script.props) ? script.props : [];
+
+  for (const [index, actor] of actors.entries()) {
+    const assetKey = textValue(actor, 'actorKey', 'actor_key', 'actorId', 'actor_id');
+    if (!assetKey) continue;
+    rows.push(compactRecord({
+      rowKind: 'asset',
+      entityKey: assetKey,
+      sortOrder: index + 1,
+      assetKind: 'actor',
+      assetKey,
+      assetName: textValue(actor, 'actorName', 'actor_name', 'name'),
+      assetDescription: textValue(actor, 'description'),
+      roleType: textValue(actor, 'roleType', 'role_type'),
+      compat: actor,
+    }));
+    const states = Array.isArray(actor.states) ? actor.states : [];
+    for (const [stateIndex, state] of states.entries()) {
+      const stateKey = textValue(state, 'stateKey', 'state_key', 'stateId', 'state_id');
+      if (!stateKey) continue;
+      rows.push(compactRecord({
+        rowKind: 'state',
+        entityKey: `${assetKey}/${stateKey}`,
+        parentKey: assetKey,
+        sortOrder: stateIndex + 1,
+        assetKind: 'actor',
+        assetKey,
+        stateKey,
+        stateName: textValue(state, 'stateName', 'state_name'),
+        stateDescription: textValue(state, 'description'),
+        roleType: textValue(state, 'roleType', 'role_type') ?? textValue(actor, 'roleType', 'role_type'),
+        compat: state,
+      }));
+    }
+  }
+
+  for (const [index, location] of locations.entries()) {
+    const assetKey = textValue(location, 'locationKey', 'location_key', 'locationId', 'location_id');
+    if (!assetKey) continue;
+    rows.push(compactRecord({
+      rowKind: 'asset',
+      entityKey: assetKey,
+      sortOrder: actors.length + index + 1,
+      assetKind: 'location',
+      assetKey,
+      assetName: textValue(location, 'locationName', 'location_name', 'name'),
+      assetDescription: textValue(location, 'description'),
+      groupName: textValue(location, 'groupName', 'group_name', 'group'),
+      compat: location,
+    }));
+  }
+
+  for (const [index, prop] of props.entries()) {
+    const assetKey = textValue(prop, 'propKey', 'prop_key', 'propId', 'prop_id');
+    if (!assetKey) continue;
+    rows.push(compactRecord({
+      rowKind: 'asset',
+      entityKey: assetKey,
+      sortOrder: actors.length + locations.length + index + 1,
+      assetKind: 'prop',
+      assetKey,
+      assetName: textValue(prop, 'propName', 'prop_name', 'name'),
+      assetDescription: textValue(prop, 'description'),
+      compat: prop,
+    }));
+  }
+
+  return rows;
+}
+
+function scriptSpeakerRows(script) {
+  const speakers = Array.isArray(script.speakers) ? script.speakers : [];
+  return speakers
+    .map((speaker, index) => {
+      const speakerKey = textValue(speaker, 'speakerKey', 'speaker_key', 'speakerId', 'speaker_id', 'id', 'key');
+      if (!speakerKey) return null;
+      return compactRecord({
+        rowKind: 'speaker',
+        entityKey: speakerKey,
+        sortOrder: index + 1,
+        speakerKey,
+        speakerDisplayName: textValue(speaker, 'speakerDisplayName', 'speaker_display_name', 'displayName', 'display_name', 'name'),
+        speakerSourceKind: textValue(speaker, 'speakerSourceKind', 'speaker_source_kind', 'sourceKind', 'source_kind'),
+        speakerSourceKey: textValue(speaker, 'speakerSourceKey', 'speaker_source_key', 'sourceKey', 'source_key', 'sourceId', 'source_id'),
+        voiceDesc: textValue(speaker, 'voiceDesc', 'voice_desc'),
+        compat: speaker,
+      });
+    })
+    .filter(Boolean);
+}
+
+function scriptEpisodeRows(script) {
+  const rows = [];
+  const episodes = Array.isArray(script.episodes) ? script.episodes : [];
+  for (const [episodeIndex, episode] of episodes.entries()) {
+    const episodeKey = textValue(episode, 'episodeKey', 'episode_key', 'episodeId', 'episode_id');
+    if (!episodeKey) continue;
+    rows.push(compactRecord({
+      rowKind: 'episode',
+      entityKey: episodeKey,
+      sortOrder: episodeIndex + 1,
+      episodeKey,
+      episodeNo: numberFromId(episodeKey, episodeIndex + 1),
+      episodeTitle: textValue(episode, 'episodeTitle', 'episode_title', 'title'),
+      compat: { ...episode, scenes: undefined },
+    }));
+    const scenes = Array.isArray(episode.scenes) ? episode.scenes : [];
+    for (const [sceneIndex, scene] of scenes.entries()) {
+      const sceneKey = textValue(scene, 'sceneKey', 'scene_key', 'sceneId', 'scene_id');
+      if (!sceneKey) continue;
+      rows.push(compactRecord({
+        rowKind: 'scene',
+        entityKey: sceneKey,
+        parentKey: episodeKey,
+        sortOrder: sceneIndex + 1,
+        episodeKey,
+        episodeNo: numberFromId(episodeKey, episodeIndex + 1),
+        sceneKey,
+        sceneNo: numberFromId(sceneKey, sceneIndex + 1),
+        environmentSpace: firstValue(scene.environment, 'space'),
+        environmentTime: firstValue(scene.environment, 'time'),
+        sceneLocations: scene.locations,
+        sceneActors: scene.actors,
+        sceneProps: scene.props,
+        compat: { ...scene, actions: undefined },
+      }));
+      const actions = Array.isArray(scene.actions) ? scene.actions : [];
+      for (const [actionIndex, action] of actions.entries()) {
+        rows.push(compactRecord({
+          rowKind: 'action',
+          entityKey: `${episodeKey}/${sceneKey}#${actionIndex}`,
+          parentKey: sceneKey,
+          sortOrder: actionIndex,
+          episodeKey,
+          sceneKey,
+          actionIndex,
+          actionType: textValue(action, 'actionType', 'action_type', 'type'),
+          content: textValue(action, 'content'),
+          actorKey: textValue(action, 'actorKey', 'actor_key', 'actorId', 'actor_id'),
+          actionSpeakerKey: textValue(action, 'actionSpeakerKey', 'action_speaker_key', 'speakerKey', 'speaker_key'),
+          delivery: textValue(action, 'delivery'),
+          emotion: textValue(action, 'emotion'),
+          speakers: firstValue(action, 'speakers'),
+          lines: firstValue(action, 'lines'),
+          stateChanges: firstValue(action, 'stateChanges', 'state_changes'),
+          transitionPrompt: firstValue(action, 'transitionPrompt', 'transition_prompt'),
+          compat: action,
+        }));
+      }
+    }
+  }
+  return rows;
+}
+
+export function buildScriptRows(script) {
+  if (!isPlainObject(script)) throw argumentError('script.json 顶层必须是 object');
+  return [
+    scriptDocumentRow(script),
+    ...scriptAssetRows(script),
+    ...scriptSpeakerRows(script),
+    ...scriptEpisodeRows(script),
+  ];
+}
+
+function stateEntries(entry) {
+  if (!isPlainObject(entry)) return [];
+  const reserved = new Set([
+    'id',
+    'project_id',
+    'projectId',
+    'name',
+    'actor_name',
+    'actorName',
+    'voice_text',
+    'voiceText',
+    'voice_desc',
+    'voiceDesc',
+    'voice',
+    'voice_url',
+    'voiceUrl',
+    'voice_status',
+    'voiceStatus',
+    'voice_candidates',
+    'voiceCandidates',
+    'selected_voice_candidate_id',
+    'selectedVoiceCandidateId',
+    'voice_backend',
+    'voiceBackend',
+    'voice_reference_image_url',
+    'voiceReferenceImageUrl',
+    'subject_id',
+    'subjectId',
+    'group',
+    'group_name',
+    'groupName',
+    'group_default',
+    'groupDefault',
+    'group_sheet',
+    'groupSheet',
+    'group_sheet_url',
+    'groupSheetUrl',
+    'group_id',
+    'groupId',
+    'image_prompts',
+    'imagePrompts',
+    'episodes',
+    'lab',
+    'is_deleted',
+    'isDeleted',
+    'created_at',
+    'createdAt',
+    'updated_at',
+    'updatedAt',
+  ]);
+  return Object.entries(entry)
+    .filter(([key, value]) => !reserved.has(key) && isPlainObject(value))
+    .filter(([key, value]) => key === 'default' || /^st[_-]/i.test(key) || value.state_name != null || value.stateName != null);
+}
+
+function normalizeActorState(stateKey, state, actor = {}) {
+  return compactRecord({
+    stateKey,
+    stateName: textValue(state, 'stateName', 'state_name') ?? stateKey,
+    roleType: textValue(state, 'roleType', 'role_type') ?? textValue(actor, 'roleType', 'role_type'),
+    gender: textValue(state, 'gender'),
+    age: textValue(state, 'age'),
+    assetsWorldviewType: textValue(state, 'assetsWorldviewType', 'assets_worldview_type'),
+    subjectId: textValue(state, 'subjectId', 'subject_id'),
+    threeViewId: textValue(state, 'threeViewId', 'three_view_id'),
+    faceView: textValue(state, 'faceView', 'face_view'),
+    faceViewUrl: textValue(state, 'faceViewUrl', 'face_view_url'),
+    sideView: textValue(state, 'sideView', 'side_view'),
+    sideViewUrl: textValue(state, 'sideViewUrl', 'side_view_url'),
+    backView: textValue(state, 'backView', 'back_view'),
+    backViewUrl: textValue(state, 'backViewUrl', 'back_view_url'),
+    threeView: textValue(state, 'threeView', 'three_view'),
+    threeViewUrl: textValue(state, 'threeViewUrl', 'three_view_url'),
+    matchedHeadAsset: firstValue(state, 'matchedHeadAsset', 'matched_head_asset'),
+    matchedBodyAsset: firstValue(state, 'matchedBodyAsset', 'matched_body_asset'),
+    imagePrompts: firstValue(state, 'imagePrompts', 'image_prompts'),
+    description: textValue(state, 'description'),
+    episodes: firstValue(state, 'episodes'),
+    status: textValue(state, 'status'),
+    genPrompt: textValue(state, 'genPrompt', 'gen_prompt'),
+    frontFullBodyPrompt: textValue(state, 'frontFullBodyPrompt', 'front_full_body_prompt'),
+    threeViewPrompt: textValue(state, 'threeViewPrompt', 'three_view_prompt'),
+    promptHead: textValue(state, 'promptHead', 'prompt_head'),
+    promptBody: textValue(state, 'promptBody', 'prompt_body'),
+    frontUseAssetMatch: firstValue(state, 'frontUseAssetMatch', 'front_use_asset_match'),
+    frontAssetMatchMode: textValue(state, 'frontAssetMatchMode', 'front_asset_match_mode'),
+    frontSavedMatchedAssets: firstValue(state, 'frontSavedMatchedAssets', 'front_saved_matched_assets'),
+    frontManualRefs: firstValue(state, 'frontManualRefs', 'front_manual_refs'),
+    headCloseup: textValue(state, 'headCloseup', 'head_closeup'),
+    headCloseupUrl: textValue(state, 'headCloseupUrl', 'head_closeup_url'),
+    lab: firstValue(state, 'lab'),
+  });
+}
+
+function normalizeNamedState(stateKey, state) {
+  return compactRecord({
+    stateKey,
+    stateName: textValue(state, 'stateName', 'state_name') ?? stateKey,
+    description: textValue(state, 'description'),
+    genPrompt: textValue(state, 'genPrompt', 'gen_prompt'),
+    status: textValue(state, 'status'),
+    main: textValue(state, 'main'),
+    mainUrl: textValue(state, 'mainUrl', 'main_url'),
+    auxiliary: textValue(state, 'auxiliary'),
+    auxiliaryUrl: textValue(state, 'auxiliaryUrl', 'auxiliary_url'),
+    lab: firstValue(state, 'lab'),
+  });
+}
+
+function rowsFromAssetObject(payload, keyName, normalizer) {
+  if (Array.isArray(payload)) return payload;
+  if (!isPlainObject(payload)) throw argumentError(`${keyName}.json 顶层必须是 object 或 array`);
+  return Object.entries(payload).map(([assetKey, entry]) => normalizer(assetKey, entry));
+}
+
+export function buildActorRequests(payload) {
+  return rowsFromAssetObject(payload, 'actors', (actorKey, actor = {}) => compactRecord({
+    actorKey,
+    name: textValue(actor, 'name', 'actorName', 'actor_name') ?? actorKey,
+    actorName: textValue(actor, 'actorName', 'actor_name', 'name') ?? actorKey,
+    voiceText: textValue(actor, 'voiceText', 'voice_text'),
+    voiceDesc: textValue(actor, 'voiceDesc', 'voice_desc'),
+    voice: textValue(actor, 'voice'),
+    voiceUrl: textValue(actor, 'voiceUrl', 'voice_url'),
+    voiceStatus: textValue(actor, 'voiceStatus', 'voice_status'),
+    voiceCandidates: firstValue(actor, 'voiceCandidates', 'voice_candidates'),
+    selectedVoiceCandidateId: textValue(actor, 'selectedVoiceCandidateId', 'selected_voice_candidate_id'),
+    voiceBackend: textValue(actor, 'voiceBackend', 'voice_backend'),
+    voiceReferenceImageUrl: textValue(actor, 'voiceReferenceImageUrl', 'voice_reference_image_url'),
+    lab: firstValue(actor, 'lab'),
+    states: stateEntries(actor).map(([stateKey, state]) => normalizeActorState(stateKey, state, actor)),
+  }));
+}
+
+export function buildPropRequests(payload) {
+  return rowsFromAssetObject(payload, 'props', (propKey, prop = {}) => compactRecord({
+    propKey,
+    name: textValue(prop, 'name', 'propName', 'prop_name') ?? propKey,
+    subjectId: textValue(prop, 'subjectId', 'subject_id'),
+    groupName: textValue(prop, 'groupName', 'group_name', 'group'),
+    groupDefault: firstValue(prop, 'groupDefault', 'group_default'),
+    imagePrompts: firstValue(prop, 'imagePrompts', 'image_prompts'),
+    episodes: firstValue(prop, 'episodes'),
+    lab: firstValue(prop, 'lab'),
+    states: stateEntries(prop).map(([stateKey, state]) => normalizeNamedState(stateKey, state)),
+  }));
+}
+
+export function buildLocationRequests(payload) {
+  return rowsFromAssetObject(payload, 'locations', (locationKey, location = {}) => compactRecord({
+    locationKey,
+    name: textValue(location, 'name', 'locationName', 'location_name') ?? locationKey,
+    subjectId: textValue(location, 'subjectId', 'subject_id'),
+    groupSheet: textValue(location, 'groupSheet', 'group_sheet'),
+    groupSheetUrl: textValue(location, 'groupSheetUrl', 'group_sheet_url'),
+    groupName: textValue(location, 'groupName', 'group_name', 'group'),
+    groupId: firstValue(location, 'groupId', 'group_id'),
+    imagePrompts: firstValue(location, 'imagePrompts', 'image_prompts'),
+    episodes: firstValue(location, 'episodes'),
+    lab: firstValue(location, 'lab'),
+    states: stateEntries(location).map(([stateKey, state]) => normalizeNamedState(stateKey, state)),
+  }));
+}
+
+function episodeIdFromStoryboard(storyboard, inputFile = '') {
+  const explicit = textValue(storyboard, 'episodeId', 'episode_id');
+  if (explicit) return explicit;
+  const basename = path.basename(inputFile);
+  const match = basename.match(/ep[_-]?(\d+)/i);
+  if (match) return `ep_${match[1].padStart(3, '0')}`;
+  throw argumentError('storyboard 缺少 episode_id，且无法从文件名推断');
+}
+
+export function buildVideoImportRequests(storyboard, inputFile = '') {
+  if (!isPlainObject(storyboard)) throw argumentError('storyboard 顶层必须是 object');
+  const episodeId = episodeIdFromStoryboard(storyboard, inputFile);
+  const scenes = Array.isArray(storyboard.scenes) ? storyboard.scenes : [];
+  const sceneRequests = [];
+  const clipsByScene = new Map();
+  for (const [sceneIndex, scene] of scenes.entries()) {
+    const sceneId = textValue(scene, 'sceneId', 'scene_id') ?? `scn_${String(sceneIndex + 1).padStart(3, '0')}`;
+    sceneRequests.push(compactRecord({
+      sceneId,
+      payload: scene,
+      lab: compactRecord({ sourceFile: inputFile }),
+    }));
+    const clips = Array.isArray(scene.clips) ? scene.clips : [];
+    clipsByScene.set(sceneId, clips.map((clip, clipIndex) => compactRecord({
+      clipId: textValue(clip, 'clipId', 'clip_id') ?? `clip_${String(clipIndex + 1).padStart(3, '0')}`,
+      expectedDuration: textValue(clip, 'expectedDuration', 'expected_duration'),
+      completePrompt: textValue(clip, 'completePrompt', 'complete_prompt'),
+      videoUrls: firstValue(clip, 'videoUrls', 'video_urls') ?? [],
+      payload: clip,
+      lab: compactRecord({ sourceFile: inputFile }),
+    })));
+  }
+  return {
+    episodeId,
+    episode: {
+      episodeId,
+      payload: storyboard,
+      lab: compactRecord({ sourceFile: inputFile }),
+    },
+    scenes: sceneRequests,
+    clipsByScene,
+    clipCount: [...clipsByScene.values()].reduce((sum, clips) => sum + clips.length, 0),
+  };
+}
+
+export async function artifactScriptGet(kwargs = {}) {
+  return await apiFetch(artifactPath('script', requireProjectId(kwargs)), { method: 'GET' });
+}
+
+export async function artifactScriptDocument(kwargs = {}) {
+  return await apiFetch(artifactPath('script', requireProjectId(kwargs), '/document'), { method: 'GET' });
+}
+
+export async function artifactScriptRows(kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  return await apiFetch(artifactPath('script', projectId, '/rows'), {
+    method: 'GET',
+    query: {
+      rowKind: kwargs.rowKind,
+      parentKey: kwargs.parentKey,
+      revisionAfter: kwargs.revisionAfter,
+      includeDeleted: kwargs.includeDeleted,
+    },
+  });
+}
+
+export async function artifactScriptRow(kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  return await apiFetch(artifactPath('script', projectId, '/rows/detail'), {
+    method: 'GET',
+    query: {
+      rowKind: requireValue(kwargs, 'rowKind', 'row-kind'),
+      entityKey: requireValue(kwargs, 'entityKey', 'entity-key'),
+    },
+  });
+}
+
+export async function artifactScriptChildren(kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  return await apiFetch(artifactPath('script', projectId, '/children'), {
+    method: 'GET',
+    query: {
+      parentKey: requireValue(kwargs, 'parentKey', 'parent-key'),
+      rowKind: kwargs.rowKind,
+    },
+  });
+}
+
+export async function artifactScriptUpsertRow(kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  const body = await readBodyPayload(kwargs);
+  if (toBool(kwargs.dryRun)) return { dryRun: true, action: 'artifact script upsert-row', projectId, request: body };
+  ensureConfirmed(kwargs, '写入剧本产物行需要确认', { action: 'artifact script upsert-row', projectId });
+  return await apiFetch(artifactPath('script', projectId, '/rows'), { body });
+}
+
+export async function artifactScriptDeleteRow(kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  const rowKind = requireValue(kwargs, 'rowKind', 'row-kind');
+  const entityKey = requireValue(kwargs, 'entityKey', 'entity-key');
+  if (toBool(kwargs.dryRun)) return { dryRun: true, action: 'artifact script delete-row', projectId, rowKind, entityKey };
+  ensureConfirmed(kwargs, '删除剧本产物行需要确认', { action: 'artifact script delete-row', projectId, rowKind, entityKey });
+  return await apiFetch(artifactPath('script', projectId, '/rows'), {
+    method: 'DELETE',
+    query: { rowKind, entityKey },
+  });
+}
+
+export async function artifactScriptImport(kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  const inputFile = trimToNull(kwargs.inputFile) || 'output/script.json';
+  const script = await readJsonFile(inputFile);
+  const rows = buildScriptRows(script);
+  const summary = {
+    projectId,
+    sourceFile: path.resolve(inputFile),
+    rowCount: rows.length,
+    rowsByKind: byKind(rows),
+  };
+  if (toBool(kwargs.dryRun)) {
+    return { dryRun: true, action: 'artifact script import', ...summary, rows };
+  }
+  ensureConfirmed(kwargs, '导入剧本最终产物需要确认', { action: 'artifact script import', projectId, rowCount: rows.length });
+  const result = await apiFetch(artifactPath('script', projectId, '/rows/batch'), { body: rows });
+  return { imported: true, ...summary, result };
+}
+
+export async function artifactAssetGet(kwargs = {}) {
+  return await apiFetch(artifactPath('asset', requireProjectId(kwargs)), { method: 'GET' });
+}
+
+async function assetList(kind, kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  return await apiFetch(artifactPath('asset', projectId, `/${kind}`), {
+    method: 'GET',
+    query: { includeStates: kwargs.includeStates ?? true },
+  });
+}
+
+async function assetGetOne(kind, keyName, kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  const key = requireValue(kwargs, keyName, keyName.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`));
+  return await apiFetch(artifactPath('asset', projectId, `/${kind}/${encodeURIComponent(key)}`), {
+    method: 'GET',
+    query: { includeStates: kwargs.includeStates ?? true },
+  });
+}
+
+async function assetUpsert(kind, kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  const body = await readBodyPayload(kwargs);
+  if (toBool(kwargs.dryRun)) return { dryRun: true, action: `artifact asset upsert-${kind.slice(0, -1)}`, projectId, request: body };
+  ensureConfirmed(kwargs, '写入资产最终产物需要确认', { action: `artifact asset upsert-${kind.slice(0, -1)}`, projectId });
+  return await apiFetch(artifactPath('asset', projectId, `/${kind}`), { body });
+}
+
+async function assetUpsertState(kind, keyName, kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  const key = requireValue(kwargs, keyName, keyName.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`));
+  const body = await readBodyPayload(kwargs);
+  if (toBool(kwargs.dryRun)) return { dryRun: true, action: `artifact asset upsert-${kind.slice(0, -1)}-state`, projectId, key, request: body };
+  ensureConfirmed(kwargs, '写入资产状态最终产物需要确认', { action: `artifact asset upsert-${kind.slice(0, -1)}-state`, projectId, key });
+  return await apiFetch(artifactPath('asset', projectId, `/${kind}/${encodeURIComponent(key)}/states`), { body });
+}
+
+async function assetDelete(kind, keyName, kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  const key = requireValue(kwargs, keyName, keyName.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`));
+  if (toBool(kwargs.dryRun)) return { dryRun: true, action: `artifact asset delete-${kind.slice(0, -1)}`, projectId, key };
+  ensureConfirmed(kwargs, '删除资产最终产物需要确认', { action: `artifact asset delete-${kind.slice(0, -1)}`, projectId, key });
+  return await apiFetch(artifactPath('asset', projectId, `/${kind}/${encodeURIComponent(key)}`), { method: 'DELETE' });
+}
+
+async function assetDeleteState(kind, keyName, kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  const key = requireValue(kwargs, keyName, keyName.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`));
+  const stateKey = requireValue(kwargs, 'stateKey', 'state-key');
+  if (toBool(kwargs.dryRun)) return { dryRun: true, action: `artifact asset delete-${kind.slice(0, -1)}-state`, projectId, key, stateKey };
+  ensureConfirmed(kwargs, '删除资产状态最终产物需要确认', { action: `artifact asset delete-${kind.slice(0, -1)}-state`, projectId, key, stateKey });
+  return await apiFetch(artifactPath('asset', projectId, `/${kind}/${encodeURIComponent(key)}/states/${encodeURIComponent(stateKey)}`), { method: 'DELETE' });
+}
+
+export async function artifactAssetActors(kwargs = {}) { return await assetList('actors', kwargs); }
+export async function artifactAssetActor(kwargs = {}) { return await assetGetOne('actors', 'actorKey', kwargs); }
+export async function artifactAssetProps(kwargs = {}) { return await assetList('props', kwargs); }
+export async function artifactAssetProp(kwargs = {}) { return await assetGetOne('props', 'propKey', kwargs); }
+export async function artifactAssetLocations(kwargs = {}) { return await assetList('locations', kwargs); }
+export async function artifactAssetLocation(kwargs = {}) { return await assetGetOne('locations', 'locationKey', kwargs); }
+export async function artifactAssetUpsertActor(kwargs = {}) { return await assetUpsert('actors', kwargs); }
+export async function artifactAssetUpsertProp(kwargs = {}) { return await assetUpsert('props', kwargs); }
+export async function artifactAssetUpsertLocation(kwargs = {}) { return await assetUpsert('locations', kwargs); }
+export async function artifactAssetUpsertActorState(kwargs = {}) { return await assetUpsertState('actors', 'actorKey', kwargs); }
+export async function artifactAssetUpsertPropState(kwargs = {}) { return await assetUpsertState('props', 'propKey', kwargs); }
+export async function artifactAssetUpsertLocationState(kwargs = {}) { return await assetUpsertState('locations', 'locationKey', kwargs); }
+export async function artifactAssetDeleteActor(kwargs = {}) { return await assetDelete('actors', 'actorKey', kwargs); }
+export async function artifactAssetDeleteProp(kwargs = {}) { return await assetDelete('props', 'propKey', kwargs); }
+export async function artifactAssetDeleteLocation(kwargs = {}) { return await assetDelete('locations', 'locationKey', kwargs); }
+export async function artifactAssetDeleteActorState(kwargs = {}) { return await assetDeleteState('actors', 'actorKey', kwargs); }
+export async function artifactAssetDeletePropState(kwargs = {}) { return await assetDeleteState('props', 'propKey', kwargs); }
+export async function artifactAssetDeleteLocationState(kwargs = {}) { return await assetDeleteState('locations', 'locationKey', kwargs); }
+
+async function resolveAssetImportFile(inputDir, explicitFile, type) {
+  if (trimToNull(explicitFile)) {
+    const absolute = path.resolve(explicitFile);
+    if (await pathExists(absolute)) return absolute;
+    throw argumentError(`${type}.json 文件不存在：${absolute}`);
+  }
+  const dir = path.resolve(inputDir || 'output');
+  const candidates = [
+    path.join(dir, type, `${type}.json`),
+    path.join(dir, `${type}.json`),
+    path.join(dir, 'output', type, `${type}.json`),
+    path.join(dir, 'output', `${type}.json`),
+  ];
+  for (const candidate of candidates) {
+    if (await pathExists(candidate)) return candidate;
+  }
+  return null;
+}
+
+export async function artifactAssetImport(kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  const inputDir = trimToNull(kwargs.inputDir) || 'output';
+  const actorsFile = await resolveAssetImportFile(inputDir, kwargs.actorsFile, 'actors');
+  const propsFile = await resolveAssetImportFile(inputDir, kwargs.propsFile, 'props');
+  const locationsFile = await resolveAssetImportFile(inputDir, kwargs.locationsFile, 'locations');
+  if (!actorsFile && !propsFile && !locationsFile) {
+    throw argumentError('未找到可导入的资产 JSON', '传 --input-dir <2_asset/output>，或显式传 --actors-file / --props-file / --locations-file。');
+  }
+
+  const actors = actorsFile ? buildActorRequests(await readJsonFile(actorsFile)) : [];
+  const props = propsFile ? buildPropRequests(await readJsonFile(propsFile)) : [];
+  const locations = locationsFile ? buildLocationRequests(await readJsonFile(locationsFile)) : [];
+  const summary = {
+    projectId,
+    inputDir: path.resolve(inputDir),
+    actorCount: actors.length,
+    propCount: props.length,
+    locationCount: locations.length,
+    files: compactRecord({ actorsFile, propsFile, locationsFile }),
+  };
+  if (toBool(kwargs.dryRun)) {
+    return { dryRun: true, action: 'artifact asset import', ...summary, actors, props, locations };
+  }
+  ensureConfirmed(kwargs, '导入资产最终产物需要确认', {
+    action: 'artifact asset import',
+    projectId,
+    actorCount: actors.length,
+    propCount: props.length,
+    locationCount: locations.length,
+  });
+  const result = {};
+  if (actors.length) result.actors = await apiFetch(artifactPath('asset', projectId, '/actors/batch'), { body: actors });
+  if (props.length) result.props = await apiFetch(artifactPath('asset', projectId, '/props/batch'), { body: props });
+  if (locations.length) result.locations = await apiFetch(artifactPath('asset', projectId, '/locations/batch'), { body: locations });
+  return { imported: true, ...summary, result };
+}
+
+export async function artifactVideoGet(kwargs = {}) {
+  return await apiFetch(artifactPath('video', requireProjectId(kwargs)), { method: 'GET' });
+}
+
+export async function artifactVideoEpisodes(kwargs = {}) {
+  return await apiFetch(artifactPath('video', requireProjectId(kwargs), '/episodes'), { method: 'GET' });
+}
+
+export async function artifactVideoEpisode(kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  const episodeId = requireValue(kwargs, 'episodeId', 'episode-id');
+  return await apiFetch(artifactPath('video', projectId, `/episodes/${encodeURIComponent(episodeId)}`), { method: 'GET' });
+}
+
+export async function artifactVideoScenes(kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  const episodeId = requireValue(kwargs, 'episodeId', 'episode-id');
+  return await apiFetch(artifactPath('video', projectId, `/episodes/${encodeURIComponent(episodeId)}/scenes`), { method: 'GET' });
+}
+
+export async function artifactVideoScene(kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  const episodeId = requireValue(kwargs, 'episodeId', 'episode-id');
+  const sceneId = requireValue(kwargs, 'sceneId', 'scene-id');
+  return await apiFetch(artifactPath('video', projectId, `/episodes/${encodeURIComponent(episodeId)}/scenes/${encodeURIComponent(sceneId)}`), { method: 'GET' });
+}
+
+export async function artifactVideoClips(kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  const episodeId = requireValue(kwargs, 'episodeId', 'episode-id');
+  const sceneId = requireValue(kwargs, 'sceneId', 'scene-id');
+  return await apiFetch(artifactPath('video', projectId, `/episodes/${encodeURIComponent(episodeId)}/scenes/${encodeURIComponent(sceneId)}/clips`), { method: 'GET' });
+}
+
+export async function artifactVideoClip(kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  const episodeId = requireValue(kwargs, 'episodeId', 'episode-id');
+  const sceneId = requireValue(kwargs, 'sceneId', 'scene-id');
+  const clipId = requireValue(kwargs, 'clipId', 'clip-id');
+  return await apiFetch(artifactPath('video', projectId, `/episodes/${encodeURIComponent(episodeId)}/scenes/${encodeURIComponent(sceneId)}/clips/${encodeURIComponent(clipId)}`), { method: 'GET' });
+}
+
+async function videoUpsert(level, kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  const body = await readBodyPayload(kwargs);
+  let suffix = '/episodes';
+  if (level === 'scene') {
+    const episodeId = requireValue(kwargs, 'episodeId', 'episode-id');
+    suffix = `/episodes/${encodeURIComponent(episodeId)}/scenes`;
+  }
+  if (level === 'clip') {
+    const episodeId = requireValue(kwargs, 'episodeId', 'episode-id');
+    const sceneId = requireValue(kwargs, 'sceneId', 'scene-id');
+    suffix = `/episodes/${encodeURIComponent(episodeId)}/scenes/${encodeURIComponent(sceneId)}/clips`;
+  }
+  if (toBool(kwargs.dryRun)) return { dryRun: true, action: `artifact video upsert-${level}`, projectId, request: body };
+  ensureConfirmed(kwargs, '写入视频最终产物需要确认', { action: `artifact video upsert-${level}`, projectId });
+  return await apiFetch(artifactPath('video', projectId, suffix), { body });
+}
+
+async function videoDelete(level, kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  const episodeId = requireValue(kwargs, 'episodeId', 'episode-id');
+  let suffix = `/episodes/${encodeURIComponent(episodeId)}`;
+  const details = { action: `artifact video delete-${level}`, projectId, episodeId };
+  if (level === 'scene' || level === 'clip') {
+    const sceneId = requireValue(kwargs, 'sceneId', 'scene-id');
+    suffix += `/scenes/${encodeURIComponent(sceneId)}`;
+    details.sceneId = sceneId;
+  }
+  if (level === 'clip') {
+    const clipId = requireValue(kwargs, 'clipId', 'clip-id');
+    suffix += `/clips/${encodeURIComponent(clipId)}`;
+    details.clipId = clipId;
+  }
+  if (toBool(kwargs.dryRun)) return { dryRun: true, ...details };
+  ensureConfirmed(kwargs, '删除视频最终产物需要确认', details);
+  return await apiFetch(artifactPath('video', projectId, suffix), { method: 'DELETE' });
+}
+
+export async function artifactVideoUpsertEpisode(kwargs = {}) { return await videoUpsert('episode', kwargs); }
+export async function artifactVideoUpsertScene(kwargs = {}) { return await videoUpsert('scene', kwargs); }
+export async function artifactVideoUpsertClip(kwargs = {}) { return await videoUpsert('clip', kwargs); }
+export async function artifactVideoDeleteEpisode(kwargs = {}) { return await videoDelete('episode', kwargs); }
+export async function artifactVideoDeleteScene(kwargs = {}) { return await videoDelete('scene', kwargs); }
+export async function artifactVideoDeleteClip(kwargs = {}) { return await videoDelete('clip', kwargs); }
+
+export async function artifactVideoUpdateClipVideoUrls(kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  const episodeId = requireValue(kwargs, 'episodeId', 'episode-id');
+  const sceneId = requireValue(kwargs, 'sceneId', 'scene-id');
+  const clipId = requireValue(kwargs, 'clipId', 'clip-id');
+  let videoUrls;
+  try {
+    videoUrls = parseJsonArg(requireValue(kwargs, 'videoUrlsJson', 'video-urls-json'));
+  } catch (error) {
+    throw argumentError('--video-urls-json 不是有效 JSON', error.message);
+  }
+  if (!Array.isArray(videoUrls)) throw argumentError('--video-urls-json 必须是 JSON 数组');
+  const body = { videoUrls };
+  if (toBool(kwargs.dryRun)) return { dryRun: true, action: 'artifact video update-clip-urls', projectId, episodeId, sceneId, clipId, request: body };
+  ensureConfirmed(kwargs, '回写 clip 视频链接需要确认', { action: 'artifact video update-clip-urls', projectId, episodeId, sceneId, clipId });
+  return await apiFetch(artifactPath('video', projectId, `/episodes/${encodeURIComponent(episodeId)}/scenes/${encodeURIComponent(sceneId)}/clips/${encodeURIComponent(clipId)}/video-urls`), { body });
+}
+
+export async function artifactVideoImportStoryboard(kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  const inputFile = requireValue(kwargs, 'inputFile', 'input-file');
+  const storyboard = await readJsonFile(inputFile);
+  const requests = buildVideoImportRequests(storyboard, path.resolve(inputFile));
+  const summary = {
+    projectId,
+    sourceFile: path.resolve(inputFile),
+    episodeId: requests.episodeId,
+    sceneCount: requests.scenes.length,
+    clipCount: requests.clipCount,
+  };
+  if (toBool(kwargs.dryRun)) {
+    return {
+      dryRun: true,
+      action: 'artifact video import-storyboard',
+      ...summary,
+      episode: requests.episode,
+      scenes: requests.scenes,
+      clipsByScene: Object.fromEntries(requests.clipsByScene.entries()),
+    };
+  }
+  ensureConfirmed(kwargs, '导入视频 storyboard 最终产物需要确认', { action: 'artifact video import-storyboard', ...summary });
+  const result = {};
+  result.episode = await apiFetch(artifactPath('video', projectId, '/episodes'), { body: requests.episode });
+  if (requests.scenes.length) {
+    result.scenes = await apiFetch(artifactPath('video', projectId, `/episodes/${encodeURIComponent(requests.episodeId)}/scenes/batch`), { body: requests.scenes });
+  }
+  result.clips = {};
+  for (const [sceneId, clips] of requests.clipsByScene.entries()) {
+    if (!clips.length) continue;
+    result.clips[sceneId] = await apiFetch(artifactPath('video', projectId, `/episodes/${encodeURIComponent(requests.episodeId)}/scenes/${encodeURIComponent(sceneId)}/clips/batch`), { body: clips });
+  }
+  return { imported: true, ...summary, result };
+}
+
+export async function artifactClipGet(kwargs = {}) {
+  return await apiFetch(artifactPath('clip', requireProjectId(kwargs)), { method: 'GET' });
+}
+
+export async function artifactClipEpisodes(kwargs = {}) {
+  return await apiFetch(artifactPath('clip', requireProjectId(kwargs), '/episodes'), { method: 'GET' });
+}
+
+export async function artifactClipEpisode(kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  const videoEpisodeId = requireNumericValue(kwargs, 'videoEpisodeId', 'video-episode-id');
+  return await apiFetch(artifactPath('clip', projectId, `/episodes/${encodeURIComponent(videoEpisodeId)}`), { method: 'GET' });
+}
+
+export async function artifactClipEpisodeById(kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  const episodeId = requireValue(kwargs, 'episodeId', 'episode-id');
+  return await apiFetch(artifactPath('clip', projectId, `/episode-id/${encodeURIComponent(episodeId)}`), { method: 'GET' });
+}
+
+export async function artifactClipUpsertEpisode(kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  const body = await readBodyPayload(kwargs);
+  if (toBool(kwargs.dryRun)) return { dryRun: true, action: 'artifact clip upsert-episode', projectId, request: body };
+  ensureConfirmed(kwargs, '写入剪辑最终产物需要确认', { action: 'artifact clip upsert-episode', projectId, videoEpisodeId: body?.videoEpisodeId });
+  return await apiFetch(artifactPath('clip', projectId, '/episodes'), { body });
+}
+
+export async function artifactClipUpsertBatch(kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  const body = await readBodyPayload(kwargs);
+  if (!Array.isArray(body)) throw argumentError('剪辑批量写入请求体必须是 JSON 数组');
+  if (toBool(kwargs.dryRun)) return { dryRun: true, action: 'artifact clip upsert-batch', projectId, episodeCount: body.length, request: body };
+  ensureConfirmed(kwargs, '批量写入剪辑最终产物需要确认', { action: 'artifact clip upsert-batch', projectId, episodeCount: body.length });
+  return await apiFetch(artifactPath('clip', projectId, '/episodes/batch'), { body });
+}
+
+export async function artifactClipUpdateStatus(kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  const videoEpisodeId = requireNumericValue(kwargs, 'videoEpisodeId', 'video-episode-id');
+  const status = requireValue(kwargs, 'status');
+  let messages;
+  if (trimToNull(kwargs.messagesJson)) {
+    try {
+      messages = parseJsonArg(kwargs.messagesJson);
+    } catch (error) {
+      throw argumentError('--messages-json 不是有效 JSON', error.message);
+    }
+  }
+  const body = compactRecord({ status, messages });
+  if (toBool(kwargs.dryRun)) return { dryRun: true, action: 'artifact clip update-status', projectId, videoEpisodeId, request: body };
+  ensureConfirmed(kwargs, '更新剪辑最终产物状态需要确认', { action: 'artifact clip update-status', projectId, videoEpisodeId, status });
+  return await apiFetch(artifactPath('clip', projectId, `/episodes/${encodeURIComponent(videoEpisodeId)}/status`), { body });
+}
+
+export async function artifactClipDeleteEpisode(kwargs = {}) {
+  const projectId = requireProjectId(kwargs);
+  const videoEpisodeId = requireNumericValue(kwargs, 'videoEpisodeId', 'video-episode-id');
+  if (toBool(kwargs.dryRun)) return { dryRun: true, action: 'artifact clip delete-episode', projectId, videoEpisodeId };
+  ensureConfirmed(kwargs, '删除剪辑最终产物需要确认', { action: 'artifact clip delete-episode', projectId, videoEpisodeId });
+  return await apiFetch(artifactPath('clip', projectId, `/episodes/${encodeURIComponent(videoEpisodeId)}`), { method: 'DELETE' });
+}