yuanflow-cli 0.1.39 → 0.1.41

package/src/cli.js

@@ -27,6 +27,8 @@ import {
   searchContent,
   searchUsers,
 } from './work-tools.js';
+import { fetchVideoHotList } from './trending-tools.js';
+import { formatAiHelp, runAiCommand } from './ai-tools.js';
 
 export async function main(argv) {
   const args = argv.slice(2);
@@ -72,6 +74,11 @@ export async function main(argv) {
     return;
   }
 
+  if (command === 'trending') {
+    await handleTrending(rest);
+    return;
+  }
+
   if (command === 'knowledge') {
     await handleKnowledge(rest);
     return;
@@ -92,6 +99,11 @@ export async function main(argv) {
     return;
   }
 
+  if (command === 'ai') {
+    await handleAi(rest);
+    return;
+  }
+
   if (command === 'schema') {
     await handleSchema(rest);
     return;
@@ -351,6 +363,19 @@ async function handleSearch(args) {
   });
 }
 
+async function handleTrending(args) {
+  const { positionals, options } = parseOptions(args);
+  const [action = 'video-hot-list'] = positionals;
+  if (action !== 'video-hot-list') {
+    throw new Error('未知 trending 命令。用法：yuanflow-cli trending video-hot-list');
+  }
+  const result = await fetchVideoHotList({ options });
+  await outputResult(result, options, {
+    command: 'trending video-hot-list',
+    meta: { endpoint: result.endpoint.path, kind: result.endpoint.kind },
+  });
+}
+
 async function handleKnowledge(args) {
   const { positionals, options } = parseOptions(args);
   const [action = 'docs'] = positionals;
@@ -412,6 +437,20 @@ async function handleVideo(args) {
   });
 }
 
+async function handleAi(args) {
+  const { positionals, options } = parseOptions(args);
+  const [action = 'help', ...rest] = positionals;
+  if (action === 'help' && !isAgentJsonFormat(options)) {
+    console.log(formatAiHelp());
+    return;
+  }
+  const result = await runAiCommand({ action, rest, options });
+  await outputResult(result, { ...options, output: undefined }, {
+    command: `ai ${[action, ...rest].filter(Boolean).join(' ')}`,
+    meta: { endpoint: result.endpoint?.path, kind: result.endpoint?.kind || 'ai-model' },
+  });
+}
+
 async function handleGeneratedCommand(platform, args) {
   if (!getPlatforms().includes(platform)) {
     throw new Error(`未知平台：${platform}。可用平台：${getPlatforms().join(', ')}`);
@@ -578,6 +617,7 @@ function printHelp() {
   yuanflow-cli works download --platform youtube --target "dQw4w9WgXcQ" --dry-run
   yuanflow-cli search content --platform xiaohongshu --keyword "美妆" --dry-run
   yuanflow-cli search users --platform instagram --keyword "nasa" --dry-run
+  yuanflow-cli trending video-hot-list --dry-run --format agent-json
   yuanflow-cli knowledge docs --dry-run
   yuanflow-cli knowledge entry --output-format short_video_script --domain 自媒体运营 --content-goal "写一个创业者短视频选题" --target-audience 创业者 --format agent-json
   yuanflow-cli oss signed-url --key path/to/file.png --ttl-seconds 1800 --format agent-json
@@ -585,14 +625,30 @@ function printHelp() {
   yuanflow-cli browser task-plan --platform xiaohongshu --task publish --account main --format agent-json
   yuanflow-cli video init --input "D:\\素材" --primary-audio "D:\\素材\\口播.mp3" --broll "D:\\素材\\画面.mp4" --format agent-json
   yuanflow-cli video strategy --project "D:\\素材\\yuanflow-video-edit" --template-type talking_head --rules-file "D:\\规则\\logic.json,D:\\规则\\template.json,D:\\规则\\cli.json" --format agent-json
+  yuanflow-cli video align --project "D:\\素材\\yuanflow-video-edit" --asr-file "D:\\素材\\asr.json" --format agent-json
   yuanflow-cli video timeline --project "D:\\素材\\yuanflow-video-edit" --fps 1 --format agent-json
+  yuanflow-cli video visual-review --project "D:\\素材\\yuanflow-video-edit" --review-file "D:\\素材\\yuanflow-video-edit\\visual_review.agent.json" --format agent-json
   yuanflow-cli video plan --project "D:\\素材\\yuanflow-video-edit" --timeline-plan "D:\\素材\\yuanflow-video-edit\\timeline_plan.agent.json" --format agent-json
+  yuanflow-cli ai qwen3-vl-plus --prompt "描述这张图" --image-url "https://example.com/image.png" --dry-run
+  yuanflow-cli ai qwen3-vl-plus --prompt "总结这个视频画面" --video-url "https://example.com/video.mp4" --dry-run
+  yuanflow-cli ai qwen3-vl-plus --prompt "描述本地图片" --image-file "D:\\素材\\cover.png" --dry-run
+  yuanflow-cli ai qwen3-vl-plus --prompt "描述本地视频" --video-file "D:\\素材\\demo.mp4" --dry-run
+  yuanflow-cli ai qwen-voice-enrollment --file "D:\\voice\\sample.wav" --name demo --activate --dry-run
+  yuanflow-cli ai qwen3-tts-vc-realtime-2026-01-15 --text "你好" --voice voice_xxx --output "D:\\voice\\qwen.mp3" --dry-run
+  yuanflow-cli ai fun-asr --audio-url "https://example.com/audio.wav" --response-format verbose_json --dry-run
+  yuanflow-cli ai doubao-tts voices --dry-run
+  yuanflow-cli ai doubao-tts voice --voice zh_female_xiaohe_uranus_bigtts --dry-run
+  yuanflow-cli ai doubao-tts voice-download --voice zh_female_xiaohe_uranus_bigtts --output "D:\\voice\\preview.mp3" --dry-run
+  yuanflow-cli ai doubao-tts --text "你好" --voice zh_female_xiaohe_uranus_bigtts --output "D:\\voice\\doubao.mp3" --dry-run
   yuanflow-cli list douyin
 
 说明：
-  社媒请求调用 Yuan API 的 /social/*path；知识库和 OSS 原子能力调用 /api/* 或 /atomic/*。
+  社媒请求调用 YuanFlow API 的 /social/*path；知识库和 YuanFlow 文件中转调用 /api/* 或 /atomic/*。
+  ai 命令调用 YuanFlow API OpenAI 兼容端点，模型名使用 YuanFlow API 对外模型参数，不暴露底层供应商内部模型名。
+  qwen3-vl-plus 支持 --image-url、--video-url、--image-file、--video-file 四选一；视频建议最大 2GB、时长 2 秒到 1 小时。
+  qwen3-vl-plus 本地图片/视频会先走 YuanFlow 文件中转，内部调用 /atomic/oss/temp-upload 后把 signed_url 提交给模型。
   browser 命令是自媒体平台专用浏览器自动化协议，只返回受控 profile/cookie/任务路径与执行计划，不用于普通网页搜索。
-  video 命令是视频智能剪辑基础链路：规则库策略快照、主音频+B-roll、1秒1帧抽帧、Agent 生成 timeline_plan/EDL、CLI 校验和渲染。
+  video 命令是视频智能剪辑基础链路：规则库策略快照、主音频+B-roll、ASR 时间戳对齐、1秒1帧抽帧、视觉理解回写、Agent 生成 timeline_plan/EDL、CLI 校验和渲染。
   需要鉴权的请求都会使用 Authorization: Bearer <token>。
   token 优先级：--token > YUANCHUANG_API_TOKEN > 本地 config.token。
   YuanFlow 主程序内使用时，token 由主程序认证系统注入，不需要手动配置。

package/src/comment-collector.js

@@ -454,7 +454,7 @@ export function listCommentCommands() {
     options: buildCommentCommandOptions(endpoint),
     queryParams: buildCommentCommandQueryParams(endpoint),
     requestBody: endpoint.bodyMode ? buildCommentCommandRequestBody(endpoint) : null,
-    returns: '返回评论列表、翻页游标和平台原始响应字段，字段以上游接口实际响应为准。',
+    returns: '返回评论列表、翻页游标和平台原始响应字段，字段以 YuanFlow API 实际响应为准。',
   }));
 }
 

package/src/oss-tools.js

@@ -12,14 +12,14 @@ export function listOssCommands() {
       key: 'oss.temp-upload',
       command: 'oss temp-upload',
       kind: 'oss-atomic',
-      description: '上传本地文件到 Yuan API 临时 OSS bucket，并返回对象 key 和临时访问信息。',
+      description: '上传本地文件到 YuanFlow 文件中转，并返回对象 key 和临时访问信息。',
       method: 'POST',
       apiPath: OSS_TEMP_UPLOAD_PATH,
       positionals: [],
       options: [
         { flag: '--file', name: 'file', required: true, label: '本地文件路径。' },
         { flag: '--filename', name: 'filename', required: false, label: '上传时使用的文件名，默认取本地文件名。' },
-        { flag: '--key', name: 'key', required: false, label: '可选 OSS 对象 key。' },
+        { flag: '--key', name: 'key', required: false, label: '可选文件对象 key。' },
         { flag: '--content-type', name: 'contentType', required: false, label: '文件 MIME 类型，默认 application/octet-stream。' },
         ...commonOptions(),
       ],
@@ -29,19 +29,19 @@ export function listOssCommands() {
         content_base64: '<base64>',
         content_type: '<content-type>',
       },
-      returns: '返回 bucket、key、url、signed_url、expires_at 等字段，字段以后端实际响应为准。',
+      returns: '返回 bucket、key、url、signed_url、expires_at 等字段，字段以 YuanFlow API 实际响应为准。',
     },
     {
       key: 'oss.signed-url',
       command: 'oss signed-url',
       kind: 'oss-atomic',
-      description: '为已有 OSS 对象生成临时签名访问链接。',
+      description: '为已有文件中转对象生成临时签名访问链接。',
       method: 'POST',
       apiPath: OSS_SIGNED_URL_PATH,
       positionals: [],
       options: [
-        { flag: '--key', name: 'key', required: true, label: 'OSS 对象 key。' },
-        { flag: '--bucket', name: 'bucket', required: false, label: '可选 bucket，不传则使用后端默认配置。' },
+        { flag: '--key', name: 'key', required: true, label: '文件对象 key。' },
+        { flag: '--bucket', name: 'bucket', required: false, label: '可选 bucket，不传则使用 YuanFlow 默认配置。' },
         { flag: '--ttl-seconds', name: 'ttlSeconds', required: false, label: '签名有效期，最大 86400 秒。' },
         { flag: '--method', name: 'method', required: false, label: '签名方法：GET、PUT、HEAD。' },
         ...commonOptions(),
@@ -52,19 +52,19 @@ export function listOssCommands() {
         ttl_seconds: 1800,
         method: 'GET',
       },
-      returns: '返回签名 URL、过期时间和对象信息，字段以后端实际响应为准。',
+      returns: '返回签名 URL、过期时间和对象信息，字段以 YuanFlow API 实际响应为准。',
     },
     {
       key: 'oss.copy',
       command: 'oss copy',
       kind: 'oss-atomic',
-      description: '复制 OSS 对象到目标 key。',
+      description: '复制文件中转对象到目标 key。',
       method: 'POST',
       apiPath: OSS_COPY_PATH,
       positionals: [],
       options: [
-        { flag: '--source-key', name: 'sourceKey', required: true, label: '源 OSS 对象 key。' },
-        { flag: '--target-key', name: 'targetKey', required: true, label: '目标 OSS 对象 key。' },
+        { flag: '--source-key', name: 'sourceKey', required: true, label: '源文件对象 key。' },
+        { flag: '--target-key', name: 'targetKey', required: true, label: '目标文件对象 key。' },
         { flag: '--source-bucket', name: 'sourceBucket', required: false, label: '可选源 bucket。' },
         { flag: '--target-bucket', name: 'targetBucket', required: false, label: '可选目标 bucket。' },
         ...commonOptions(),
@@ -75,7 +75,7 @@ export function listOssCommands() {
         source_bucket: '<optional source bucket>',
         target_bucket: '<optional target bucket>',
       },
-      returns: '返回复制后的对象信息，字段以后端实际响应为准。',
+      returns: '返回复制后的对象信息，字段以 YuanFlow API 实际响应为准。',
     },
   ];
 }

package/src/shortcuts.js

@@ -7,7 +7,7 @@ export const shortcuts = [
     socialPath: '/douyin/app/v3/fetch_multi_video_v2',
     positionals: [{ name: 'url', label: '作品链接' }],
     options: [],
-    returns: '返回作品基础信息、作者信息、互动统计、媒体信息等字段，字段结构以上游实际响应为准。',
+    returns: '返回作品基础信息、作者信息、互动统计、媒体信息等字段，字段结构以 YuanFlow API 实际响应为准。',
     alternatives: [
       'GET /social/douyin/app/v3/fetch_one_video_by_share_url?share_url=...',
       'GET /social/douyin/web/fetch_one_video?aweme_id=...',
@@ -21,7 +21,7 @@ export const shortcuts = [
     socialPath: '/douyin/app/v3/fetch_video_high_quality_play_url',
     positionals: [{ name: 'share_url', label: '作品链接或分享链接' }],
     options: [{ flag: 'region', name: 'region', label: '地区，可选，如 CN' }],
-    returns: '返回视频播放地址、清晰度信息、媒体地址等；是否可直接下载取决于上游返回和目标平台限制。',
+    returns: '返回视频播放地址、清晰度信息、媒体地址等；是否可直接下载取决于 YuanFlow API 返回和目标平台限制。',
     alternatives: [
       'POST /social/douyin/app/v3/fetch_multi_video_high_quality_play_url',
       'GET /social/douyin/web/fetch_video_high_quality_play_url',
@@ -280,7 +280,7 @@ export const shortcuts = [
   {
     platform: 'wechat',
     command: 'channels-home',
-    description: '微信视频号主页采集，参数结构通常需要用 --json 传入上游要求的完整请求体。',
+    description: '微信视频号主页采集，参数结构通常需要用 --json 传入接口要求的完整请求体。',
     method: 'POST',
     socialPath: '/wechat_channels/fetch_home_page',
     positionals: [],

package/src/trending-tools.js

@@ -0,0 +1,117 @@
+import { callEndpoint } from './request.js';
+
+const VIDEO_HOT_LIST_PATH = '/douyin/billboard/fetch_hot_total_video_list';
+
+const VIDEO_HOT_BOARD_TYPES = [
+  { subType: 1001, label: '视频总榜' },
+  { subType: 1002, label: '低粉爆款' },
+  { subType: 1003, label: '高完播率' },
+  { subType: 1004, label: '高涨粉率' },
+  { subType: 1005, label: '高点赞率' },
+];
+
+export function listTrendingCommands() {
+  return [
+    {
+      key: 'trending.video-hot-list',
+      command: 'trending video-hot-list',
+      kind: 'trending',
+      description: '一次性查询抖音视频热榜五类榜单：视频总榜、低粉爆款、高完播率、高涨粉率、高点赞率。',
+      method: 'POST',
+      socialPath: VIDEO_HOT_LIST_PATH,
+      positionals: [],
+      options: [
+        { flag: '--page', name: 'page', required: false, label: '页码，默认 1' },
+        { flag: '--page-size', name: 'page_size', required: false, label: '每页数量，默认 10' },
+        { flag: '--date-window', name: 'date_window', required: false, label: '时间窗口，默认 2 按天' },
+        { flag: '--tags-json', name: 'tags', required: false, label: '垂类标签 JSON 数组，空则全部垂类' },
+      ],
+      returns: '返回五类视频热榜的统一 JSON，字段结构以 YuanFlow API 实际响应为准。',
+    },
+  ];
+}
+
+export async function fetchVideoHotList({ options }) {
+  const query = buildVideoHotListQuery(options);
+  const boards = [];
+
+  for (const board of VIDEO_HOT_BOARD_TYPES) {
+    const requestBody = {
+      page: query.page,
+      page_size: query.page_size,
+      date_window: query.date_window,
+      sub_type: board.subType,
+      ...(query.tags !== undefined ? { tags: query.tags } : {}),
+    };
+    const response = await callEndpoint(VIDEO_HOT_LIST_PATH, {
+      ...options,
+      method: 'POST',
+      body: requestBody,
+    });
+    boards.push({
+      sub_type: board.subType,
+      label: board.label,
+      request: requestBody,
+      response,
+    });
+  }
+
+  return {
+    platform: 'douyin',
+    endpoint: {
+      method: 'POST',
+      path: VIDEO_HOT_LIST_PATH,
+      kind: 'video-hot-list',
+    },
+    query,
+    boards,
+    guidance: [
+      '结合用户个人创作信息、个人创作库历史记录、历史任务或对话记录输出建议。',
+      '不要只罗列榜单，必须区分五类榜单来源并提炼可执行选题和内容结构。',
+      '重点比较总榜、低粉爆款、高完播率、高涨粉率、高点赞率之间的差异。',
+    ],
+  };
+}
+
+function buildVideoHotListQuery(options = {}) {
+  return {
+    page: parsePositiveInteger(options.named?.page, 1, 'page'),
+    page_size: parsePositiveInteger(options.named?.['page-size'] ?? options.named?.page_size, 10, 'page_size'),
+    date_window: parsePositiveInteger(options.named?.['date-window'] ?? options.named?.date_window, 2, 'date_window'),
+    ...(parseTags(options.named?.['tags-json'] ?? options.named?.tags) !== undefined
+      ? { tags: parseTags(options.named?.['tags-json'] ?? options.named?.tags) }
+      : {}),
+  };
+}
+
+function parsePositiveInteger(value, fallback, name) {
+  if (value === undefined || value === null || value === '') {
+    return fallback;
+  }
+  const number = Number(value);
+  if (!Number.isInteger(number) || number <= 0) {
+    throw new Error(`${name} 必须是正整数。`);
+  }
+  return number;
+}
+
+function parseTags(value) {
+  if (value === undefined || value === null || value === '') {
+    return undefined;
+  }
+  if (Array.isArray(value)) {
+    return value;
+  }
+  try {
+    const parsed = JSON.parse(String(value));
+    if (!Array.isArray(parsed)) {
+      throw new Error('tags-json 必须是数组。');
+    }
+    return parsed;
+  } catch (error) {
+    if (error?.message === 'tags-json 必须是数组。') {
+      throw error;
+    }
+    throw new Error('tags-json 必须是合法 JSON 数组。');
+  }
+}

package/src/video-tools.js

@@ -9,7 +9,9 @@ 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';
@@ -39,11 +41,19 @@ export function listVideoCommands() {
       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。'),
@@ -72,12 +82,14 @@ export async function runVideoCommand({ action, 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|timeline|plan|render-preview|render-final|evaluate');
+  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) {
@@ -208,6 +220,58 @@ async function importTranscript(options) {
   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');
@@ -310,6 +374,61 @@ async function buildTimeline(options) {
   };
 }
 
+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']);
@@ -334,9 +453,9 @@ async function planFromAgentEdl(options) {
       action: 'video.plan',
       project: projectSummary(project),
       agent_action_required: true,
-      required_inputs: ['strategy_snapshot.json', 'beats.json', 'visual_segments.json', '用户剪辑 brief'],
+      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 单独传入。',
+      message: '由 Agent 读取规则库策略快照、音频对齐结果、beats、视觉理解结果和 1秒1帧抽帧结果后生成 timeline_plan；timeline_plan 内可包含 edl，或再用 --edl 单独传入。',
     };
   }
   const edl = edlSource ? JSON.parse(await fs.readFile(edlSource, 'utf8')) : timelinePlan.edl;
@@ -480,6 +599,36 @@ function validateTimelinePlan(plan, beatsPayload, visualSegments) {
   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');
@@ -594,6 +743,29 @@ async function readScriptInput(options) {
   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')
@@ -755,6 +927,13 @@ 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,

package/src/work-tools.js

@@ -148,8 +148,8 @@ function workCommand(platform, action, endpoint, kind) {
     requestBody: endpoint.bodyMode ? requestBodyExample(endpoint, 'target') : null,
     returns:
       action === 'download'
-        ? '返回作品可播放媒体信息、下载地址候选或视频流信息，字段以上游实际响应为准。'
-        : '返回作品详情、作者信息、正文/标题、互动统计和媒体信息，字段以上游实际响应为准。',
+        ? '返回作品可播放媒体信息、下载地址候选或视频流信息，字段以 YuanFlow API 实际响应为准。'
+        : '返回作品详情、作者信息、正文/标题、互动统计和媒体信息，字段以 YuanFlow API 实际响应为准。',
   };
 }
 
@@ -167,8 +167,8 @@ function searchCommand(platform, action, endpoint, kind) {
     requestBody: endpoint.bodyMode ? requestBodyExample(endpoint, 'keyword') : null,
     returns:
       action === 'users'
-        ? '返回用户/频道搜索结果、分页字段和平台原始摘要字段，字段以上游实际响应为准。'
-        : '返回内容搜索结果、分页字段和平台原始摘要字段，字段以上游实际响应为准。',
+        ? '返回用户/频道搜索结果、分页字段和平台原始摘要字段，字段以 YuanFlow API 实际响应为准。'
+        : '返回内容搜索结果、分页字段和平台原始摘要字段，字段以 YuanFlow API 实际响应为准。',
   };
 }