yuanflow-cli 0.1.44 → 0.1.46

package/src/video-tools.js

@@ -1,969 +0,0 @@
-import { execFile } from 'node:child_process';
-import { createHash } from 'node:crypto';
-import fs from 'node:fs/promises';
-import path from 'node:path';
-
-const VIDEO_EXTS = new Set(['.mp4', '.mov', '.m4v', '.mkv', '.webm', '.avi']);
-const AUDIO_EXTS = new Set(['.mp3', '.wav', '.m4a', '.aac', '.flac', '.ogg']);
-const IMAGE_EXTS = new Set(['.jpg', '.jpeg', '.png', '.webp']);
-const PROJECT_FILE = 'project.json';
-const ASSETS_FILE = 'assets.json';
-const BEATS_FILE = 'beats.json';
-const AUDIO_ALIGNMENT_FILE = 'audio_alignment.json';
-const VISUAL_SEGMENTS_FILE = 'visual_segments.json';
-const VISUAL_UNDERSTANDING_FILE = 'visual_understanding.json';
-const EDL_FILE = 'edl.json';
-const STRATEGY_FILE = 'strategy_snapshot.json';
-const TIMELINE_PLAN_FILE = 'timeline_plan.json';
-
-export function listVideoCommands() {
-  return [
-    videoCommand('init', '初始化视频剪辑项目，创建独立工作目录和 project.json。', [
-      option('--input', 'input', true, '素材输入目录。'),
-      option('--output', 'output', false, '剪辑项目输出目录。'),
-      option('--primary-audio', 'primaryAudio', false, '主口播、旁白或主音频文件。'),
-      option('--broll', 'broll', false, 'B-roll 视频或图片素材路径，多个用英文逗号分隔。'),
-      option('--target-duration', 'targetDuration', false, '目标成片时长，单位秒。'),
-      option('--aspect', 'aspect', false, '目标画幅，例如 9:16。'),
-    ]),
-    videoCommand('strategy', '导入知识库规则查询结果，生成 strategy_snapshot.json。', [
-      option('--project', 'project', true, '剪辑项目目录。'),
-      option('--template-type', 'templateType', true, '模板类型：talking_head 或 short_video_sales。'),
-      option('--rules-file', 'rulesFile', true, '知识库 rules/rule-detail 查询结果 JSON，多个用英文逗号分隔。'),
-    ]),
-    videoCommand('inspect', '扫描素材并生成 assets.json。', [
-      option('--project', 'project', true, '剪辑项目目录。'),
-      option('--dry-run', 'dryRun', false, '不调用 ffprobe，用假探测数据验证流程。'),
-    ]),
-    videoCommand('transcribe', '导入文案或既有转写结果，生成 beats.json。', [
-      option('--project', 'project', true, '剪辑项目目录。'),
-      option('--script', 'script', false, '直接传入文案文本。'),
-      option('--script-file', 'scriptFile', false, '读取文案文件。'),
-      option('--transcript-file', 'transcriptFile', false, '读取转写 JSON 或文本文件。'),
-    ]),
-    videoCommand('align', '导入 ASR 或 forced alignment 时间戳结果，生成 audio_alignment.json 和带时间戳 beats.json。', [
-      option('--project', 'project', true, '剪辑项目目录。'),
-      option('--asr-file', 'asrFile', true, '音视频在线转文字或 forced alignment 输出的 JSON 文件。'),
-    ]),
-    videoCommand('timeline', '按 1 秒 1 帧抽帧并生成 visual_segments.json。', [
-      option('--project', 'project', true, '剪辑项目目录。'),
-      option('--fps', 'fps', false, '抽帧频率，基础版建议 1。'),
-      option('--dry-run', 'dryRun', false, '不调用 ffmpeg，只生成占位帧清单。'),
-    ]),
-    videoCommand('visual-review', '导入 Agent/人工对抽帧结果的视觉理解，回写 visual_segments.json。', [
-      option('--project', 'project', true, '剪辑项目目录。'),
-      option('--review-file', 'reviewFile', true, 'Agent 或人工生成的 visual_review.agent.json。'),
-    ]),
-    videoCommand('plan', '校验 Agent 生成的 timeline_plan 和 EDL，写入标准 timeline_plan.json / edl.json。', [
-      option('--project', 'project', true, '剪辑项目目录。'),
-      option('--timeline-plan', 'timelinePlan', false, 'Agent 生成的 timeline_plan.agent.json。'),
-      option('--edl', 'edl', false, 'Agent 生成的 edl.agent.json；如果 timeline_plan 内已包含 edl，可不传。'),
-    ]),
-    videoCommand('render-preview', '根据 edl.json 渲染预览视频。', [
-      option('--project', 'project', true, '剪辑项目目录。'),
-      option('--output', 'output', false, '预览视频输出路径。'),
-      option('--dry-run', 'dryRun', false, '只返回 ffmpeg 命令，不实际渲染。'),
-    ]),
-    videoCommand('evaluate', '检查预览或成片并生成 eval_report.json。', [
-      option('--project', 'project', true, '剪辑项目目录。'),
-      option('--file', 'file', false, '需要检查的视频文件。'),
-      option('--dry-run', 'dryRun', false, '只检查文件存在性，不调用 ffprobe。'),
-    ]),
-    videoCommand('render-final', '根据 edl.json 导出最终视频。', [
-      option('--project', 'project', true, '剪辑项目目录。'),
-      option('--output', 'output', false, '最终视频输出路径。'),
-      option('--dry-run', 'dryRun', false, '只返回 ffmpeg 命令，不实际渲染。'),
-    ]),
-  ];
-}
-
-export async function runVideoCommand({ action, options }) {
-  if (action === 'init') return initProject(options);
-  if (action === 'inspect') return inspectProject(options);
-  if (action === 'strategy') return saveStrategySnapshot(options);
-  if (action === 'transcribe') return importTranscript(options);
-  if (action === 'align') return importAudioAlignment(options);
-  if (action === 'timeline') return buildTimeline(options);
-  if (action === 'visual-review') return importVisualReview(options);
-  if (action === 'plan') return planFromAgentEdl(options);
-  if (action === 'render-preview') return renderVideo(options, { final: false });
-  if (action === 'render-final') return renderVideo(options, { final: true });
-  if (action === 'evaluate') return evaluateVideo(options);
-  throw new Error('未知 video 命令。用法：yuanflow-cli video init|inspect|strategy|transcribe|align|timeline|visual-review|plan|render-preview|render-final|evaluate');
-}
-
-function videoCommand(action, description, options) {
-  return {
-    key: `video.${action}`,
-    command: `video ${action}`,
-    kind: 'video-editing',
-    description,
-    method: 'LOCAL',
-    apiPath: '',
-    socialPath: '',
-    positionals: [],
-    options: [
-      ...options,
-      option('--format', 'format', false, 'Agent 调用时建议使用 agent-json。'),
-    ],
-    requestBody: null,
-    returns: '返回本地视频剪辑项目产物路径、校验结果或渲染命令。',
-  };
-}
-
-function option(flag, name, required, label) {
-  return { flag, name, required, label };
-}
-
-async function initProject(options) {
-  const input = requiredPath(options.named?.input, '缺少 --input。');
-  const output = path.resolve(options.output || options.named?.output || path.join(input, 'yuanflow-video-edit'));
-  await fs.mkdir(output, { recursive: true });
-  await fs.mkdir(path.join(output, 'frames'), { recursive: true });
-  await fs.mkdir(path.join(output, 'renders'), { recursive: true });
-
-  const project = {
-    project_id: `vf_${timestampId()}`,
-    input_dir: input,
-    work_dir: output,
-    created_at: new Date().toISOString(),
-    target: {
-      duration_s: numberOrNull(options.named?.['target-duration']),
-      aspect: stringOrDefault(options.named?.aspect, '9:16'),
-      platform: stringOrDefault(options.named?.platform, ''),
-      style: stringOrDefault(options.named?.style, ''),
-    },
-    asset_hints: {
-      primary_audio: normalizeOptionalPath(options.named?.['primary-audio']),
-      broll: parsePathList(options.named?.broll),
-      primary_video: normalizeOptionalPath(options.named?.['primary-video']),
-      background_music: normalizeOptionalPath(options.named?.['background-music']),
-    },
-    workflow: {
-      visual_sampling_fps: 1,
-      visual_understanding: 'agent_frame_review',
-      planning_owner: 'agent',
-      cli_responsibility: 'validate_edl_and_render',
-    },
-  };
-  await writeJson(path.join(output, PROJECT_FILE), project);
-  return { ok: true, action: 'video.init', project };
-}
-
-async function inspectProject(options) {
-  const project = await readProject(options);
-  const files = await collectInputFiles(project.input_dir);
-  const hintedPaths = new Set([
-    ...Object.values(project.asset_hints || {}).flat().filter(Boolean),
-  ].map((item) => path.resolve(item)));
-  const scanPaths = [...new Set([...files, ...hintedPaths])];
-  const assets = [];
-
-  for (const filePath of scanPaths) {
-    const stat = await safeStat(filePath);
-    if (!stat?.isFile()) continue;
-    const mediaType = detectMediaType(filePath);
-    if (!mediaType) continue;
-    const probe = options.dryRun ? dryProbe(filePath, mediaType) : await probeMedia(filePath, mediaType);
-    const asset = {
-      asset_id: `asset_${String(assets.length + 1).padStart(3, '0')}`,
-      path: path.resolve(filePath),
-      name: path.basename(filePath),
-      media_type: mediaType,
-      role: inferRole(filePath, mediaType, project, assets),
-      duration_s: probe.duration_s,
-      width: probe.width,
-      height: probe.height,
-      hash: await hashFileStat(filePath),
-      probe,
-    };
-    assets.push(asset);
-  }
-
-  await writeJson(path.join(project.work_dir, ASSETS_FILE), assets);
-  return {
-    ok: true,
-    action: 'video.inspect',
-    project: projectSummary(project),
-    assets,
-    dry_run: Boolean(options.dryRun),
-  };
-}
-
-async function importTranscript(options) {
-  const project = await readProject(options);
-  const script = await readScriptInput(options);
-  if (!script) {
-    return {
-      ok: true,
-      action: 'video.transcribe',
-      project: projectSummary(project),
-      requires_transcription: true,
-      next_action: '请先使用“音视频在线转文字”或“本地音视频转文字”获得文案，再用 --script-file 导入。',
-    };
-  }
-  const beats = splitScriptToBeats(script).map((text, index) => ({
-    beat_id: `beat_${String(index + 1).padStart(3, '0')}`,
-    text,
-    start_s: null,
-    end_s: null,
-    intent: '',
-    visual_need: '',
-    emotion: '',
-  }));
-  const payload = {
-    source: options.named?.['script-file'] ? path.resolve(options.named['script-file']) : 'inline',
-    imported_at: new Date().toISOString(),
-    beats,
-  };
-  await writeJson(path.join(project.work_dir, BEATS_FILE), payload);
-  return { ok: true, action: 'video.transcribe', project: projectSummary(project), beats };
-}
-
-async function importAudioAlignment(options) {
-  const project = await readProject(options);
-  const asrPath = requiredPath(options.named?.['asr-file'], '缺少 --asr-file。');
-  const parsed = JSON.parse(await fs.readFile(asrPath, 'utf8'));
-  const segments = extractAlignmentSegments(parsed);
-  if (segments.length === 0) {
-    return {
-      ok: false,
-      action: 'video.align',
-      project: projectSummary(project),
-      alignment_validation: {
-        ok: false,
-        errors: ['ASR/对齐结果里没有可用的 segments，无法生成带时间戳 beats。'],
-      },
-    };
-  }
-
-  const alignment = {
-    version: 1,
-    source: path.resolve(asrPath),
-    imported_at: new Date().toISOString(),
-    text: stringOrDefault(parsed.text || parsed.data?.text || parsed.result?.text, segments.map((item) => item.text).join('')),
-    segments,
-  };
-  const beats = segments.map((segment, index) => ({
-    beat_id: `beat_${String(index + 1).padStart(3, '0')}`,
-    text: segment.text,
-    start_s: segment.start_s,
-    end_s: segment.end_s,
-    intent: '',
-    visual_need: '',
-    emotion: '',
-    alignment_source: 'audio_alignment',
-  }));
-  await writeJson(path.join(project.work_dir, AUDIO_ALIGNMENT_FILE), alignment);
-  await writeJson(path.join(project.work_dir, BEATS_FILE), {
-    source: path.resolve(asrPath),
-    imported_at: new Date().toISOString(),
-    alignment_file: path.join(project.work_dir, AUDIO_ALIGNMENT_FILE),
-    beats,
-  });
-  return {
-    ok: true,
-    action: 'video.align',
-    project: projectSummary(project),
-    alignment,
-    beats,
-    alignment_path: path.join(project.work_dir, AUDIO_ALIGNMENT_FILE),
-    beats_path: path.join(project.work_dir, BEATS_FILE),
-  };
-}
-
-async function saveStrategySnapshot(options) {
-  const project = await readProject(options);
-  const templateType = stringOrDefault(options.named?.['template-type'], 'custom');
-  const ruleFiles = parsePathList(options.named?.['rules-file']);
-  if (ruleFiles.length === 0) {
-    return {
-      ok: true,
-      action: 'video.strategy',
-      project: projectSummary(project),
-      agent_action_required: true,
-      expected_output: path.join(project.work_dir, STRATEGY_FILE),
-      message: '请先通过 knowledge rules / rule-detail 查询视频剪辑策略规则，再用 --rules-file 导入查询结果。',
-    };
-  }
-
-  const ruleSources = [];
-  const rules = [];
-  for (const filePath of ruleFiles) {
-    const parsed = JSON.parse(await fs.readFile(filePath, 'utf8'));
-    const extracted = extractRulesFromKnowledgePayload(parsed);
-    ruleSources.push({
-      path: path.resolve(filePath),
-      count: extracted.length,
-    });
-    rules.push(...extracted);
-  }
-
-  const strategy = {
-    version: 1,
-    template_type: templateType,
-    created_at: new Date().toISOString(),
-    source: 'knowledge_rules_manual_import',
-    required_packs: requiredPacksForTemplate(templateType),
-    rule_sources: ruleSources,
-    rules: uniqueRules(rules),
-    execution_policy: {
-      planning_owner: 'agent',
-      rule_source: 'agent_rule_library',
-      cli_responsibility: 'validate_timeline_plan_edl_and_render',
-      manual_test_first: true,
-    },
-  };
-  await writeJson(path.join(project.work_dir, STRATEGY_FILE), strategy);
-  return {
-    ok: true,
-    action: 'video.strategy',
-    project: projectSummary(project),
-    strategy,
-    strategy_path: path.join(project.work_dir, STRATEGY_FILE),
-  };
-}
-
-async function buildTimeline(options) {
-  const project = await readProject(options);
-  const assets = await readAssets(project);
-  const fps = Number(options.named?.fps || 1);
-  if (!Number.isFinite(fps) || fps <= 0) {
-    throw new Error('--fps 必须是大于 0 的数字。基础版建议固定为 1。');
-  }
-
-  const frameRoot = path.join(project.work_dir, 'frames');
-  const frameManifests = [];
-  const visualSegments = [];
-  for (const asset of assets.filter((item) => ['video', 'image'].includes(item.media_type))) {
-    const assetFrameDir = path.join(frameRoot, asset.asset_id);
-    await fs.mkdir(assetFrameDir, { recursive: true });
-    let frames;
-    if (options.dryRun) {
-      frames = buildDryFrames(asset, assetFrameDir, fps);
-    } else {
-      frames = await extractFrames(asset, assetFrameDir, fps);
-    }
-    frameManifests.push({ asset_id: asset.asset_id, path: asset.path, fps, frames });
-    const segmentCount = Math.max(1, frames.length || Math.ceil((asset.duration_s || 1) * fps));
-    for (let index = 0; index < segmentCount; index += 1) {
-      visualSegments.push({
-        segment_id: `vis_${String(visualSegments.length + 1).padStart(4, '0')}`,
-        asset_id: asset.asset_id,
-        start_s: index / fps,
-        end_s: (index + 1) / fps,
-        frame_path: frames[index]?.path || path.join(assetFrameDir, `frame_${String(index + 1).padStart(6, '0')}.jpg`),
-        description: '',
-        subjects: [],
-        scene: '',
-        motion: '',
-        agent_review_required: true,
-      });
-    }
-  }
-  await writeJson(path.join(project.work_dir, 'frames_manifest.json'), frameManifests);
-  await writeJson(path.join(project.work_dir, VISUAL_SEGMENTS_FILE), visualSegments);
-  return {
-    ok: true,
-    action: 'video.timeline',
-    project: projectSummary(project),
-    fps,
-    visual_segments: visualSegments,
-    frame_manifests: frameManifests,
-    dry_run: Boolean(options.dryRun),
-  };
-}
-
-async function importVisualReview(options) {
-  const project = await readProject(options);
-  const reviewPath = requiredPath(options.named?.['review-file'], '缺少 --review-file。');
-  const review = JSON.parse(await fs.readFile(reviewPath, 'utf8'));
-  const visualSegments = await readOptionalJson(path.join(project.work_dir, VISUAL_SEGMENTS_FILE));
-  if (!Array.isArray(visualSegments) || visualSegments.length === 0) {
-    return {
-      ok: false,
-      action: 'video.visual-review',
-      project: projectSummary(project),
-      review_validation: { ok: false, errors: ['请先执行 video timeline 生成 visual_segments.json。'], warnings: [] },
-    };
-  }
-
-  const reviewValidation = validateVisualReview(review, visualSegments);
-  if (!reviewValidation.ok) {
-    return { ok: false, action: 'video.visual-review', project: projectSummary(project), review_validation: reviewValidation };
-  }
-
-  const byId = new Map((review.reviews || []).map((item) => [item.segment_id, item]));
-  const reviewedSegments = visualSegments.map((segment) => {
-    const item = byId.get(segment.segment_id);
-    if (!item) return segment;
-    return {
-      ...segment,
-      description: item.description,
-      subjects: Array.isArray(item.subjects) ? item.subjects : [],
-      scene: stringOrDefault(item.scene, ''),
-      motion: stringOrDefault(item.motion, ''),
-      semantic_tags: Array.isArray(item.semantic_tags) ? item.semantic_tags : [],
-      quality_score: isFiniteNumber(item.quality_score) ? Number(item.quality_score) : null,
-      visual_review_source: path.resolve(reviewPath),
-      agent_review_required: false,
-    };
-  });
-  const payload = {
-    version: 1,
-    source: path.resolve(reviewPath),
-    imported_at: new Date().toISOString(),
-    reviewed_count: review.reviews.length,
-    reviews: review.reviews,
-  };
-  await writeJson(path.join(project.work_dir, VISUAL_UNDERSTANDING_FILE), payload);
-  await writeJson(path.join(project.work_dir, VISUAL_SEGMENTS_FILE), reviewedSegments);
-  return {
-    ok: true,
-    action: 'video.visual-review',
-    project: projectSummary(project),
-    review_validation: reviewValidation,
-    visual_understanding_path: path.join(project.work_dir, VISUAL_UNDERSTANDING_FILE),
-    visual_segments_path: path.join(project.work_dir, VISUAL_SEGMENTS_FILE),
-    reviewed_segments: reviewedSegments.filter((segment) => byId.has(segment.segment_id)),
-  };
-}
-
-async function planFromAgentEdl(options) {
-  const project = await readProject(options);
-  const timelinePlanSource = normalizeOptionalPath(options.named?.['timeline-plan']);
-  const edlSource = normalizeOptionalPath(options.named?.edl);
-  let timelinePlan = null;
-  let timelinePlanValidation = null;
-
-  if (timelinePlanSource) {
-    timelinePlan = JSON.parse(await fs.readFile(timelinePlanSource, 'utf8'));
-    const beats = await readOptionalJson(path.join(project.work_dir, BEATS_FILE));
-    const visualSegments = await readOptionalJson(path.join(project.work_dir, VISUAL_SEGMENTS_FILE));
-    timelinePlanValidation = validateTimelinePlan(timelinePlan, beats, visualSegments);
-    if (!timelinePlanValidation.ok) {
-      return { ok: false, action: 'video.plan', project: projectSummary(project), timeline_plan_validation: timelinePlanValidation };
-    }
-    await writeJson(path.join(project.work_dir, TIMELINE_PLAN_FILE), timelinePlan);
-  }
-
-  if (!edlSource && !timelinePlan?.edl) {
-    return {
-      ok: true,
-      action: 'video.plan',
-      project: projectSummary(project),
-      agent_action_required: true,
-      required_inputs: ['strategy_snapshot.json', 'audio_alignment.json 或 beats.json', 'visual_segments.json', 'visual_understanding.json', '用户剪辑 brief'],
-      expected_outputs: [path.join(project.work_dir, TIMELINE_PLAN_FILE), path.join(project.work_dir, EDL_FILE)],
-      message: '由 Agent 读取规则库策略快照、音频对齐结果、beats、视觉理解结果和 1秒1帧抽帧结果后生成 timeline_plan；timeline_plan 内可包含 edl，或再用 --edl 单独传入。',
-    };
-  }
-  const edl = edlSource ? JSON.parse(await fs.readFile(edlSource, 'utf8')) : timelinePlan.edl;
-  const assets = await readAssets(project);
-  const validation = validateEdl(edl, assets);
-  if (!validation.ok) {
-    return { ok: false, action: 'video.plan', timeline_plan_validation: timelinePlanValidation, validation };
-  }
-  await writeJson(path.join(project.work_dir, EDL_FILE), edl);
-  return {
-    ok: true,
-    action: 'video.plan',
-    project: projectSummary(project),
-    timeline_plan_validation: timelinePlanValidation,
-    validation,
-    timeline_plan_path: timelinePlan ? path.join(project.work_dir, TIMELINE_PLAN_FILE) : '',
-    edl_path: path.join(project.work_dir, EDL_FILE),
-  };
-}
-
-async function renderVideo(options, { final }) {
-  const project = await readProject(options);
-  const edl = await readEdl(project);
-  const assets = await readAssets(project);
-  const validation = validateEdl(edl, assets);
-  if (!validation.ok) return { ok: false, action: final ? 'video.render-final' : 'video.render-preview', validation };
-
-  const output = path.resolve(options.output || options.named?.output || path.join(project.work_dir, final ? 'final.mp4' : 'preview.mp4'));
-  const commands = buildRenderCommands(project, edl, assets, output, { final });
-  if (!options.dryRun) {
-    await runRenderCommands(commands);
-  }
-  return {
-    ok: true,
-    action: final ? 'video.render-final' : 'video.render-preview',
-    project: projectSummary(project),
-    output,
-    validation,
-    commands: commands.map((item) => item.args),
-    dry_run: Boolean(options.dryRun),
-  };
-}
-
-async function evaluateVideo(options) {
-  const project = await readProject(options);
-  const target = path.resolve(options.named?.file || options.file || options.output || path.join(project.work_dir, 'preview.mp4'));
-  const exists = Boolean(await safeStat(target));
-  const checks = [{ type: 'file_exists', status: exists ? 'pass' : 'fail', message: exists ? '输出文件存在。' : '输出文件不存在。' }];
-  if (exists && !options.dryRun) {
-    const probe = await probeMedia(target, 'video');
-    checks.push({ type: 'duration', status: probe.duration_s > 0 ? 'pass' : 'warn', message: `检测到时长 ${probe.duration_s || 0} 秒。` });
-  }
-  const report = { ok: checks.every((item) => item.status !== 'fail'), file: target, checks, warnings: [] };
-  await writeJson(path.join(project.work_dir, 'eval_report.json'), report);
-  return { ok: true, action: 'video.evaluate', project: projectSummary(project), report, dry_run: Boolean(options.dryRun) };
-}
-
-function validateEdl(edl, assets) {
-  const errors = [];
-  const warnings = [];
-  const byId = new Map(assets.map((asset) => [asset.asset_id, asset]));
-  if (!edl || typeof edl !== 'object') errors.push('EDL 必须是 JSON 对象。');
-  if (!Array.isArray(edl?.ranges) || edl.ranges.length === 0) errors.push('EDL 必须包含非空 ranges。');
-  if (edl?.audio?.source && !byId.has(edl.audio.source)) errors.push(`audio.source 不存在: ${edl.audio.source}`);
-  if (edl?.audio?.source) {
-    const audio = byId.get(edl.audio.source);
-    if (audio && audio.media_type !== 'audio') errors.push(`audio.source 必须指向音频素材: ${edl.audio.source}`);
-  }
-  for (const [index, range] of (edl?.ranges || []).entries()) {
-    const label = `ranges[${index}]`;
-    const asset = byId.get(range.source);
-    if (!asset) {
-      errors.push(`${label}.source 不存在: ${range.source}`);
-      continue;
-    }
-    if (!['video', 'image'].includes(asset.media_type)) {
-      errors.push(`${label}.source 必须指向视频或图片素材。`);
-    }
-    if (!isFiniteNumber(range.start) || !isFiniteNumber(range.end) || range.end <= range.start) {
-      errors.push(`${label} start/end 必须是有效数字，且 end > start。`);
-    }
-    if (!range.reason) warnings.push(`${label} 缺少 reason，建议 Agent 写明保留理由。`);
-    if (asset.duration_s && range.end > asset.duration_s + 0.05) {
-      warnings.push(`${label} 结束时间超过素材探测时长，渲染时可能失败。`);
-    }
-  }
-  return { ok: errors.length === 0, errors, warnings };
-}
-
-function validateTimelinePlan(plan, beatsPayload, visualSegments) {
-  const errors = [];
-  const warnings = [];
-  if (!plan || typeof plan !== 'object' || Array.isArray(plan)) {
-    return { ok: false, errors: ['timeline_plan 必须是 JSON 对象。'], warnings };
-  }
-  if (!Array.isArray(plan.beats) || plan.beats.length === 0) {
-    errors.push('timeline_plan.beats 必须是非空数组。');
-  }
-  if (!Array.isArray(plan.matches) || plan.matches.length === 0) {
-    errors.push('timeline_plan.matches 必须是非空数组。');
-  }
-  if (!plan.template_type) {
-    warnings.push('timeline_plan 缺少 template_type，建议写明 talking_head 或 short_video_sales。');
-  }
-
-  const knownBeatIds = new Set((beatsPayload?.beats || []).map((beat) => beat.beat_id));
-  const planBeatIds = new Set((plan.beats || []).map((beat) => beat.beat_id).filter(Boolean));
-  const knownSegmentIds = new Set((visualSegments || []).map((segment) => segment.segment_id));
-  for (const [index, beat] of (plan.beats || []).entries()) {
-    const label = `beats[${index}]`;
-    if (!beat.beat_id) errors.push(`${label}.beat_id 不能为空。`);
-    if (!beat.text) warnings.push(`${label}.text 为空，后续复核会缺少文案依据。`);
-    if (knownBeatIds.size > 0 && beat.beat_id && !knownBeatIds.has(beat.beat_id)) {
-      warnings.push(`${label}.beat_id 未出现在 beats.json 中: ${beat.beat_id}`);
-    }
-  }
-  for (const [index, match] of (plan.matches || []).entries()) {
-    const label = `matches[${index}]`;
-    if (!match.beat_id) errors.push(`${label}.beat_id 不能为空。`);
-    if (match.beat_id && !planBeatIds.has(match.beat_id)) {
-      errors.push(`${label}.beat_id 未出现在 timeline_plan.beats 中: ${match.beat_id}`);
-    }
-    if (!match.segment_id) errors.push(`${label}.segment_id 不能为空。`);
-    if (knownSegmentIds.size > 0 && match.segment_id && !knownSegmentIds.has(match.segment_id)) {
-      errors.push(`${label}.segment_id 未出现在 visual_segments.json 中: ${match.segment_id}`);
-    }
-    if (!isFiniteNumber(match.score) || Number(match.score) < 0 || Number(match.score) > 1) {
-      errors.push(`${label}.score 必须是 0 到 1 之间的数字。`);
-    }
-    if (!match.reason) {
-      errors.push(`${label}.reason 不能为空，必须说明画面为什么匹配当前 beat。`);
-    }
-  }
-  const blockers = (plan.material_gaps || []).filter((gap) => ['blocker', 'fatal'].includes(String(gap.severity || '').toLowerCase()));
-  if (blockers.length > 0) {
-    errors.push(`timeline_plan 存在未处理的阻塞性缺素材: ${blockers.map((gap) => gap.description || gap.type || 'unknown').join('；')}`);
-  }
-  if (!plan.edl) {
-    warnings.push('timeline_plan 未内嵌 edl；需要另传 --edl。');
-  }
-  return { ok: errors.length === 0, errors, warnings };
-}
-
-function validateVisualReview(review, visualSegments) {
-  const errors = [];
-  const warnings = [];
-  if (!review || typeof review !== 'object' || Array.isArray(review)) {
-    return { ok: false, errors: ['visual_review 必须是 JSON 对象。'], warnings };
-  }
-  if (!Array.isArray(review.reviews) || review.reviews.length === 0) {
-    errors.push('visual_review.reviews 必须是非空数组。');
-  }
-  const knownSegmentIds = new Set((visualSegments || []).map((segment) => segment.segment_id));
-  const seen = new Set();
-  for (const [index, item] of (review.reviews || []).entries()) {
-    const label = `reviews[${index}]`;
-    if (!item.segment_id) errors.push(`${label}.segment_id 不能为空。`);
-    if (item.segment_id && !knownSegmentIds.has(item.segment_id)) {
-      errors.push(`${label}.segment_id 未出现在 visual_segments.json 中: ${item.segment_id}`);
-    }
-    if (item.segment_id && seen.has(item.segment_id)) {
-      errors.push(`${label}.segment_id 重复: ${item.segment_id}`);
-    }
-    if (item.segment_id) seen.add(item.segment_id);
-    if (!item.description) errors.push(`${label}.description 不能为空，必须说明画面内容。`);
-    if (!Array.isArray(item.subjects)) warnings.push(`${label}.subjects 建议使用数组。`);
-    if (item.quality_score !== undefined && (!isFiniteNumber(item.quality_score) || Number(item.quality_score) < 0 || Number(item.quality_score) > 1)) {
-      errors.push(`${label}.quality_score 必须是 0 到 1 之间的数字。`);
-    }
-  }
-  return { ok: errors.length === 0, errors, warnings };
-}
-
-function buildRenderCommands(project, edl, assets, output, { final }) {
-  const byId = new Map(assets.map((asset) => [asset.asset_id, asset]));
-  const renderDir = path.join(project.work_dir, 'renders');
-  const clipsDir = path.join(renderDir, final ? 'clips_final' : 'clips_preview');
-  const concatFile = path.join(renderDir, final ? 'concat_final.txt' : 'concat_preview.txt');
-  const baseVideo = path.join(renderDir, final ? 'base_final.mp4' : 'base_preview.mp4');
-  const commands = [
-    { tool: 'mkdir', args: ['mkdir', clipsDir] },
-  ];
-  const clipPaths = [];
-  const scale = final ? 'scale=-2:1920' : 'scale=-2:1280';
-
-  for (const [index, range] of edl.ranges.entries()) {
-    const asset = byId.get(range.source);
-    const clipPath = path.join(clipsDir, `seg_${String(index + 1).padStart(3, '0')}.mp4`);
-    clipPaths.push(clipPath);
-    const duration = Number(range.end) - Number(range.start);
-    if (asset.media_type === 'image') {
-      commands.push({
-        tool: 'ffmpeg',
-        args: ['ffmpeg', '-y', '-loop', '1', '-i', asset.path, '-t', String(duration), '-vf', scale, '-an', '-c:v', 'libx264', '-pix_fmt', 'yuv420p', clipPath],
-      });
-    } else {
-      commands.push({
-        tool: 'ffmpeg',
-        args: ['ffmpeg', '-y', '-ss', String(range.start), '-i', asset.path, '-t', String(duration), '-vf', scale, '-an', '-c:v', 'libx264', '-pix_fmt', 'yuv420p', clipPath],
-      });
-    }
-  }
-  commands.push({ tool: 'write-concat', args: ['write-concat', concatFile, ...clipPaths] });
-  commands.push({ tool: 'ffmpeg', args: ['ffmpeg', '-y', '-f', 'concat', '-safe', '0', '-i', concatFile, '-c', 'copy', baseVideo] });
-  const audioAsset = edl.audio?.source ? byId.get(edl.audio.source) : null;
-  if (audioAsset) {
-    commands.push({ tool: 'ffmpeg', args: ['ffmpeg', '-y', '-i', baseVideo, '-i', audioAsset.path, '-map', '0:v:0', '-map', '1:a:0', '-shortest', '-c:v', 'copy', '-c:a', 'aac', '-b:a', '192k', output] });
-  } else {
-    commands.push({ tool: 'ffmpeg', args: ['ffmpeg', '-y', '-i', baseVideo, '-c', 'copy', output] });
-  }
-  return commands;
-}
-
-async function runRenderCommands(commands) {
-  for (const command of commands) {
-    if (command.tool === 'mkdir') {
-      await fs.mkdir(command.args[1], { recursive: true });
-    } else if (command.tool === 'write-concat') {
-      const [, concatFile, ...clipPaths] = command.args;
-      await fs.mkdir(path.dirname(concatFile), { recursive: true });
-      await fs.writeFile(concatFile, clipPaths.map((item) => `file '${toFfmpegConcatPath(item)}'`).join('\n'), 'utf8');
-    } else if (command.tool === 'ffmpeg') {
-      await exec(command.args[0], command.args.slice(1));
-    }
-  }
-}
-
-async function extractFrames(asset, destDir, fps) {
-  const pattern = path.join(destDir, 'frame_%06d.jpg');
-  if (asset.media_type === 'image') {
-    const out = path.join(destDir, 'frame_000001.jpg');
-    await fs.copyFile(asset.path, out);
-    return [{ index: 1, time_s: 0, path: out }];
-  }
-  await exec('ffmpeg', ['-y', '-i', asset.path, '-vf', `fps=${fps}`, '-q:v', '3', pattern]);
-  const files = (await fs.readdir(destDir)).filter((item) => item.endsWith('.jpg')).sort();
-  return files.map((file, index) => ({ index: index + 1, time_s: index / fps, path: path.join(destDir, file) }));
-}
-
-function buildDryFrames(asset, assetFrameDir, fps) {
-  const count = asset.media_type === 'image' ? 1 : Math.max(1, Math.ceil((asset.duration_s || 6) * fps));
-  return Array.from({ length: count }, (_, index) => ({
-    index: index + 1,
-    time_s: index / fps,
-    path: path.join(assetFrameDir, `frame_${String(index + 1).padStart(6, '0')}.jpg`),
-  }));
-}
-
-async function readProject(options) {
-  const projectDir = normalizeOptionalPath(options.named?.project || options.output);
-  if (!projectDir) throw new Error('缺少 --project。');
-  return JSON.parse(await fs.readFile(path.join(projectDir, PROJECT_FILE), 'utf8'));
-}
-
-async function readAssets(project) {
-  return JSON.parse(await fs.readFile(path.join(project.work_dir, ASSETS_FILE), 'utf8'));
-}
-
-async function readEdl(project) {
-  return JSON.parse(await fs.readFile(path.join(project.work_dir, EDL_FILE), 'utf8'));
-}
-
-async function readOptionalJson(filePath) {
-  const stat = await safeStat(filePath);
-  if (!stat?.isFile()) return null;
-  return JSON.parse(await fs.readFile(filePath, 'utf8'));
-}
-
-async function readScriptInput(options) {
-  if (typeof options.named?.script === 'string') return options.named.script;
-  if (typeof options.named?.['script-file'] === 'string') {
-    return fs.readFile(path.resolve(options.named['script-file']), 'utf8');
-  }
-  if (typeof options.named?.['transcript-file'] === 'string') {
-    const raw = await fs.readFile(path.resolve(options.named['transcript-file']), 'utf8');
-    try {
-      const parsed = JSON.parse(raw);
-      if (Array.isArray(parsed.beats)) return parsed.beats.map((item) => item.text || '').join('\n');
-      if (Array.isArray(parsed.words)) return parsed.words.map((item) => item.text || '').join('');
-      if (typeof parsed.text === 'string') return parsed.text;
-    } catch {
-      return raw;
-    }
-  }
-  return '';
-}
-
-function extractAlignmentSegments(payload) {
-  const candidates = [
-    payload?.segments,
-    payload?.data?.segments,
-    payload?.result?.segments,
-    payload?.data?.result?.segments,
-    payload?.response?.segments,
-    payload?.words,
-    payload?.data?.words,
-    payload?.result?.words,
-  ];
-  const found = candidates.find((item) => Array.isArray(item));
-  return (found || [])
-    .map((item) => {
-      const text = stringOrDefault(item.text || item.word || item.sentence, '').trim();
-      const start = firstFiniteNumber(item.start_s, item.start, item.begin_s, item.begin, item.from);
-      const end = firstFiniteNumber(item.end_s, item.end, item.stop_s, item.stop, item.to);
-      return { text, start_s: start, end_s: end };
-    })
-    .filter((item) => item.text && isFiniteNumber(item.start_s) && isFiniteNumber(item.end_s) && Number(item.end_s) > Number(item.start_s))
-    .map((item) => ({ text: item.text, start_s: Number(item.start_s), end_s: Number(item.end_s) }));
-}
-
-function splitScriptToBeats(script) {
-  return String(script)
-    .replace(/\r/g, '\n')
-    .split(/(?<=[。！？!?；;])\s*|\n+/u)
-    .map((item) => item.trim())
-    .filter(Boolean);
-}
-
-async function collectInputFiles(inputDir) {
-  const out = [];
-  async function walk(dir) {
-    const entries = await fs.readdir(dir, { withFileTypes: true });
-    for (const entry of entries) {
-      const p = path.join(dir, entry.name);
-      if (entry.isDirectory()) await walk(p);
-      else out.push(path.resolve(p));
-    }
-  }
-  await walk(inputDir);
-  return out;
-}
-
-function inferRole(filePath, mediaType, project, existingAssets) {
-  const resolved = path.resolve(filePath);
-  const hints = project.asset_hints || {};
-  if (hints.primary_audio && path.resolve(hints.primary_audio) === resolved) return 'primary_audio';
-  if (hints.primary_video && path.resolve(hints.primary_video) === resolved) return 'primary_video';
-  if (hints.background_music && path.resolve(hints.background_music) === resolved) return 'background_music';
-  if ((hints.broll || []).map((item) => path.resolve(item)).includes(resolved)) {
-    return mediaType === 'image' ? 'broll_image' : 'broll_video';
-  }
-  if (mediaType === 'audio') {
-    return existingAssets.some((item) => item.role === 'primary_audio') ? 'background_music' : 'primary_audio';
-  }
-  if (mediaType === 'image') return 'broll_image';
-  return existingAssets.some((item) => item.role === 'primary_audio') ? 'broll_video' : 'primary_video';
-}
-
-async function probeMedia(filePath, mediaType) {
-  const output = await exec('ffprobe', ['-v', 'error', '-show_entries', 'format=duration:stream=width,height', '-of', 'json', filePath]);
-  const parsed = JSON.parse(output.stdout || '{}');
-  const videoStream = (parsed.streams || []).find((item) => item.width && item.height);
-  return {
-    duration_s: Number(parsed.format?.duration || 0),
-    width: mediaType === 'image' ? videoStream?.width || null : videoStream?.width || null,
-    height: mediaType === 'image' ? videoStream?.height || null : videoStream?.height || null,
-  };
-}
-
-function dryProbe(filePath, mediaType) {
-  return {
-    duration_s: mediaType === 'image' ? 1 : 6,
-    width: mediaType === 'audio' ? null : 1080,
-    height: mediaType === 'audio' ? null : 1920,
-    dry_run: true,
-    file: filePath,
-  };
-}
-
-function detectMediaType(filePath) {
-  const ext = path.extname(filePath).toLowerCase();
-  if (VIDEO_EXTS.has(ext)) return 'video';
-  if (AUDIO_EXTS.has(ext)) return 'audio';
-  if (IMAGE_EXTS.has(ext)) return 'image';
-  return '';
-}
-
-async function hashFileStat(filePath) {
-  const stat = await fs.stat(filePath);
-  const digest = createHash('sha256');
-  digest.update(path.resolve(filePath));
-  digest.update(String(stat.size));
-  digest.update(String(stat.mtimeMs));
-  return digest.digest('hex');
-}
-
-async function safeStat(filePath) {
-  try {
-    return await fs.stat(filePath);
-  } catch {
-    return null;
-  }
-}
-
-function requiredPath(value, message) {
-  const p = normalizeOptionalPath(value);
-  if (!p) throw new Error(message);
-  return p;
-}
-
-function normalizeOptionalPath(value) {
-  if (!value || value === true) return '';
-  return path.resolve(String(value));
-}
-
-function parsePathList(value) {
-  if (!value || value === true) return [];
-  return String(value)
-    .split(',')
-    .map((item) => item.trim())
-    .filter(Boolean)
-    .map((item) => path.resolve(item));
-}
-
-function extractRulesFromKnowledgePayload(payload) {
-  const candidates = [
-    payload?.data?.response?.data,
-    payload?.response?.data,
-    payload?.data?.data,
-    payload?.data,
-    payload,
-  ];
-  const found = candidates.find((item) => Array.isArray(item));
-  return (found || [])
-    .filter((item) => item && typeof item === 'object')
-    .map((item) => ({
-      rule_code: stringOrDefault(item.rule_code, ''),
-      rule_name: stringOrDefault(item.rule_name, ''),
-      rule_type: stringOrDefault(item.rule_type, ''),
-      summary: stringOrDefault(item.summary || item.public_summary, ''),
-      instruction: stringOrDefault(item.instruction || item.execution_instruction, ''),
-      avoid: Array.isArray(item.avoid) ? item.avoid : [],
-      example_pattern: Array.isArray(item.example_pattern) ? item.example_pattern : [],
-    }))
-    .filter((item) => item.rule_code || item.rule_name || item.instruction);
-}
-
-function uniqueRules(rules) {
-  const seen = new Set();
-  const out = [];
-  for (const rule of rules) {
-    const key = rule.rule_code || `${rule.rule_name}:${rule.instruction}`;
-    if (seen.has(key)) continue;
-    seen.add(key);
-    out.push(rule);
-  }
-  return out;
-}
-
-function requiredPacksForTemplate(templateType) {
-  const base = ['video_edit_logic_layer_pack', 'video_cli_validation_render_pack'];
-  if (templateType === 'talking_head') return [base[0], 'talking_head_edit_template_pack', base[1]];
-  if (templateType === 'short_video_sales') return [base[0], 'short_video_sales_edit_template_pack', base[1]];
-  return base;
-}
-
-function numberOrNull(value) {
-  if (value === undefined || value === null || value === true || value === '') return null;
-  const n = Number(value);
-  return Number.isFinite(n) ? n : null;
-}
-
-function stringOrDefault(value, fallback) {
-  if (value === undefined || value === null || value === true || value === '') return fallback;
-  return String(value);
-}
-
-function isFiniteNumber(value) {
-  return Number.isFinite(Number(value));
-}
-
-function firstFiniteNumber(...values) {
-  for (const value of values) {
-    if (isFiniteNumber(value)) return Number(value);
-  }
-  return null;
-}
-
-function projectSummary(project) {
-  return {
-    project_id: project.project_id,
-    work_dir: project.work_dir,
-    input_dir: project.input_dir,
-    target: project.target,
-  };
-}
-
-async function writeJson(filePath, payload) {
-  await fs.mkdir(path.dirname(filePath), { recursive: true });
-  await fs.writeFile(filePath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
-}
-
-function exec(file, args) {
-  return new Promise((resolve, reject) => {
-    execFile(file, args, { windowsHide: true }, (error, stdout, stderr) => {
-      if (error) {
-        reject(new Error(stderr || error.message));
-        return;
-      }
-      resolve({ stdout, stderr });
-    });
-  });
-}
-
-function toFfmpegConcatPath(filePath) {
-  return path.resolve(filePath).replace(/\\/g, '/').replace(/'/g, "'\\''");
-}
-
-function timestampId() {
-  return new Date().toISOString().replace(/[-:.TZ]/g, '').slice(0, 14);
-}