yuanflow-cli 0.1.39 → 0.1.41

package/src/ai-tools.js

@@ -0,0 +1,835 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { readConfig } from './config.js';
+import { callAtomic } from './atomic-request.js';
+
+const CHAT_COMPLETIONS_PATH = '/v1/chat/completions';
+const AUDIO_SPEECH_PATH = '/v1/audio/speech';
+const AUDIO_TRANSCRIPTIONS_PATH = '/v1/audio/transcriptions';
+const AUDIO_VOICES_PATH = '/v1/audio/voices';
+const DOUBAO_TTS_VOICE_ASSETS_PATH = '/api/voice-assets/doubao/voices';
+const YUANFLOW_FILE_TRANSFER_PATH = '/atomic/oss/temp-upload';
+
+const MODEL_QWEN_VL = 'qwen3-vl-plus';
+const MODEL_QWEN_VOICE = 'qwen-voice-enrollment';
+const MODEL_QWEN_TTS_VC = 'qwen3-tts-vc-realtime-2026-01-15';
+const MODEL_FUN_ASR = 'fun-asr';
+const MODEL_DOUBAO_TTS = 'doubao-tts';
+
+export function listAiCommands() {
+  return [
+    aiCommand({
+      key: 'ai.qwen3-vl-plus',
+      command: 'ai qwen3-vl-plus',
+      description: '调用 YuanFlow API 对外模型 qwen3-vl-plus，支持图片/视频 URL 与本地图片/视频经 YuanFlow 文件中转后的视觉理解。',
+      apiPath: CHAT_COMPLETIONS_PATH,
+      options: [
+        option('--prompt', 'prompt', true, '用户文本提示词。'),
+        option('--image-url', 'imageUrl', false, '图片 URL，支持 http(s) 可访问地址。'),
+        option('--video-url', 'videoUrl', false, '视频 URL，支持 http(s) 可访问地址；YuanFlow 视觉理解建议单个视频最大 2GB，时长 2 秒至 1 小时。'),
+        option('--image-file', 'imageFile', false, '本地图片文件；CLI 会先上传到 YuanFlow 文件中转，再调用 qwen3-vl-plus。'),
+        option('--video-file', 'videoFile', false, '本地视频文件；CLI 会先上传到 YuanFlow 文件中转，再调用 qwen3-vl-plus。'),
+        option('--system', 'system', false, '可选系统提示词。'),
+        option('--temperature', 'temperature', false, '采样温度。'),
+        option('--max-tokens', 'maxTokens', false, '最大输出 token 数。'),
+        ...commonOptions(),
+      ],
+      requestBody: {
+        model: MODEL_QWEN_VL,
+        messages: '<由 --prompt 和 --image-url/--video-url/--image-file/--video-file 组装>',
+      },
+      returns: '返回 OpenAI chat.completion 兼容 JSON。',
+    }),
+    aiCommand({
+      key: 'ai.qwen-voice-enrollment',
+      command: 'ai qwen-voice-enrollment',
+      description: '调用 YuanFlow API 对外模型 qwen-voice-enrollment，创建音色复刻记录。',
+      apiPath: AUDIO_VOICES_PATH,
+      options: [
+        option('--file', 'file', false, '本地音频文件；与 --audio-url 二选一。'),
+        option('--audio-url', 'audioUrl', false, '公网可访问音频 URL；与 --file 二选一。'),
+        option('--name', 'name', false, '音色展示名。'),
+        option('--preferred-name', 'preferredName', false, '偏好音色名，默认跟随 --name。'),
+        option('--text', 'text', false, '参考音频对应文本，可选。'),
+        option('--language', 'language', false, '语言代码，可选。'),
+        option('--activate', 'activate', false, '创建后设为当前默认音色。'),
+        ...commonOptions(),
+      ],
+      requestBody: {
+        model: MODEL_QWEN_VOICE,
+        audio: '<本地文件 data URI 或 audio_url>',
+      },
+      returns: '返回 voice_xxx 音色对象；后续 qwen3-tts-vc-realtime-2026-01-15 可用 --voice voice_xxx 调用。',
+    }),
+    aiCommand({
+      key: 'ai.qwen3-tts-vc-realtime-2026-01-15',
+      command: 'ai qwen3-tts-vc-realtime-2026-01-15',
+      description: '调用 YuanFlow API 对外模型 qwen3-tts-vc-realtime-2026-01-15，使用 voice_xxx 或 default 合成音频。',
+      apiPath: AUDIO_SPEECH_PATH,
+      options: speechOptions('音色 ID：voice_xxx 或 default。', false),
+      requestBody: {
+        model: MODEL_QWEN_TTS_VC,
+        input: '<text>',
+        voice: '<voice_xxx|default>',
+      },
+      returns: '返回音频二进制；CLI 通过 --output 保存到本地文件。',
+    }),
+    aiCommand({
+      key: 'ai.fun-asr',
+      command: 'ai fun-asr',
+      description: '调用 YuanFlow API 对外模型 fun-asr，提交音频转写。',
+      apiPath: AUDIO_TRANSCRIPTIONS_PATH,
+      options: [
+        option('--audio-url', 'audioUrl', false, '公网可访问音频 URL；适合异步 ASR。'),
+        option('--file', 'file', false, '本地音频文件；适合直传 ASR。'),
+        option('--response-format', 'responseFormat', false, 'json 或 verbose_json，默认 json。'),
+        option('--language', 'language', false, '语言提示，例如 zh、en。'),
+        option('--language-hints', 'languageHints', false, '逗号分隔语言提示。'),
+        option('--timestamps', 'timestamps', false, '返回时间戳。'),
+        option('--diarization-enabled', 'diarizationEnabled', false, '开启说话人分离。'),
+        option('--speaker-count', 'speakerCount', false, '说话人数。'),
+        ...commonOptions(),
+      ],
+      requestBody: {
+        model: MODEL_FUN_ASR,
+        response_format: 'json',
+        metadata: '<audio_url/language/timestamps 等>',
+      },
+      returns: '返回 OpenAI audio transcription 兼容 JSON。',
+    }),
+    aiCommand({
+      key: 'ai.doubao-tts',
+      command: 'ai doubao-tts',
+      description: '调用 YuanFlow API 对外模型 doubao-tts，voice 直接传豆包音色参数。',
+      apiPath: AUDIO_SPEECH_PATH,
+      options: speechOptions('豆包音色 ID，例如 zh_female_xiaohe_uranus_bigtts。', true),
+      requestBody: {
+        model: MODEL_DOUBAO_TTS,
+        input: '<text>',
+        voice: '<豆包音色 ID>',
+      },
+      returns: '返回音频二进制；CLI 通过 --output 保存到本地文件。',
+    }),
+    aiCommand({
+      key: 'ai.doubao-tts.voices',
+      command: 'ai doubao-tts voices',
+      description: '查询 doubao-tts 可用于合成的全部豆包官方音色清单。',
+      method: 'GET',
+      apiPath: DOUBAO_TTS_VOICE_ASSETS_PATH,
+      options: commonOptions(),
+      requestBody: null,
+      returns: '返回音色列表；合成时使用每条记录的 voice_type 作为 --voice。',
+    }),
+    aiCommand({
+      key: 'ai.doubao-tts.voice',
+      command: 'ai doubao-tts voice',
+      description: '查询单个 doubao-tts 音色详情。',
+      method: 'GET',
+      apiPath: `${DOUBAO_TTS_VOICE_ASSETS_PATH}/{voice_type}`,
+      options: [
+        option('--voice', 'voice', true, '豆包音色 ID，也就是 voice_type。'),
+        ...commonOptions(),
+      ],
+      requestBody: null,
+      returns: '返回单个音色的展示名、分类、语言、能力标签和试听资源 key。',
+    }),
+    aiCommand({
+      key: 'ai.doubao-tts.voice-download',
+      command: 'ai doubao-tts voice-download',
+      description: '获取 doubao-tts 单个音色试听音频下载地址，并可保存到本地。',
+      method: 'GET',
+      apiPath: `${DOUBAO_TTS_VOICE_ASSETS_PATH}/{voice_type}/download`,
+      options: [
+        option('--voice', 'voice', true, '豆包音色 ID，也就是 voice_type。'),
+        option('--output', 'output', false, '可选本地保存路径；不传时只返回签名下载 URL。'),
+        ...commonOptions(),
+      ],
+      requestBody: null,
+      returns: '返回签名下载 URL；传 --output 时 CLI 会下载试听 mp3 到本地。',
+    }),
+  ];
+}
+
+export function formatAiHelp() {
+  return listAiCommands()
+    .map((command) => {
+      const options = command.options.map((item) => `    ${item.flag} ${item.label}`).join('\n');
+      return `${command.command}\n  ${command.description}\n  接口：${command.method} ${command.apiPath}\n  参数：\n${options}\n  返回：${command.returns}`;
+    })
+    .join('\n\n');
+}
+
+export async function runAiCommand({ action = 'help', rest = [], options }) {
+  switch (action) {
+    case 'help':
+    case 'list':
+      return { ok: true, commands: listAiCommands() };
+    case MODEL_QWEN_VL:
+      return callJson(CHAT_COMPLETIONS_PATH, options, await buildQwenVLBody(options));
+    case MODEL_QWEN_VOICE:
+      return callJson(AUDIO_VOICES_PATH, options, await buildVoiceEnrollmentBody(options));
+    case MODEL_QWEN_TTS_VC:
+      return callSpeech(MODEL_QWEN_TTS_VC, options, false);
+    case MODEL_FUN_ASR:
+      return callFunASR(options);
+    case MODEL_DOUBAO_TTS:
+      return runDoubaoTTSCommand(rest, options);
+    default:
+      throw new Error(`未知 ai 命令：${action}。可执行 yuanflow-cli ai help 查看用法。`);
+  }
+}
+
+async function runDoubaoTTSCommand(rest, options) {
+  const [subCommand] = rest;
+  if (!subCommand) {
+    return callSpeech(MODEL_DOUBAO_TTS, options, true);
+  }
+  switch (subCommand) {
+    case 'voices':
+    case 'list':
+      return listDoubaoTTSVoices(options);
+    case 'voice':
+    case 'detail':
+      return getDoubaoTTSVoice(options);
+    case 'voice-download':
+    case 'download':
+      return downloadDoubaoTTSVoice(options);
+    default:
+      throw new Error(`未知 doubao-tts 子命令：${subCommand}。可用：voices、voice、voice-download。`);
+  }
+}
+
+async function buildQwenVLBody(options) {
+  if (options.json) {
+    return JSON.parse(options.json);
+  }
+  const prompt = cleanOptional(options.named?.prompt);
+  if (!prompt) {
+    throw new Error('缺少 --prompt。');
+  }
+  const messages = [];
+  const system = cleanOptional(options.named?.system);
+  if (system) {
+    messages.push({ role: 'system', content: system });
+  }
+  const media = await resolveQwenVLMedia(options);
+  const content = media
+    ? [
+        { type: 'text', text: prompt },
+        mediaPart(media),
+      ]
+    : prompt;
+  const body = {
+    model: MODEL_QWEN_VL,
+    messages: [...messages, { role: 'user', content }],
+  };
+  addNumber(body, 'temperature', options.named?.temperature);
+  addNumber(body, 'max_tokens', options.named?.['max-tokens']);
+  return body;
+}
+
+async function resolveQwenVLMedia(options) {
+  const inputs = [
+    { source: 'image-url', kind: 'image', value: cleanOptional(options.named?.['image-url']) },
+    { source: 'video-url', kind: 'video', value: cleanOptional(options.named?.['video-url']) },
+    { source: 'image-file', kind: 'image', value: cleanOptional(options.named?.['image-file']) },
+    { source: 'video-file', kind: 'video', value: cleanOptional(options.named?.['video-file']) },
+  ].filter((item) => item.value !== undefined);
+
+  if (inputs.length === 0) {
+    return null;
+  }
+  if (inputs.length > 1) {
+    throw new Error('qwen3-vl-plus 快捷参数一次只支持一个媒体输入，请在 --image-url、--video-url、--image-file、--video-file 中选择一个。');
+  }
+
+  const [input] = inputs;
+  if (input.source.endsWith('-url')) {
+    return { kind: input.kind, url: input.value };
+  }
+  const url = await resolveQwenVLLocalFile(input.value, input.kind, options);
+  return { kind: input.kind, url };
+}
+
+async function resolveQwenVLLocalFile(filePath, mediaKind, options) {
+  const filename = path.basename(filePath);
+  if (options.dryRun) {
+    return `<YuanFlow 文件中转 signed_url:${filename}>`;
+  }
+  const response = await uploadYuanFlowVisionFile({
+    filePath,
+    filename,
+    mediaKind,
+    options,
+  });
+  return extractYuanFlowFileURL(response);
+}
+
+async function uploadYuanFlowVisionFile({ filePath, filename, mediaKind, options }) {
+  const body = {
+    filename,
+    content_base64: (await readFile(filePath)).toString('base64'),
+    content_type: inferMediaMimeType(filePath, mediaKind),
+  };
+  return callAtomic(YUANFLOW_FILE_TRANSFER_PATH, {
+    ...options,
+    json: undefined,
+    method: 'POST',
+    body,
+  });
+}
+
+function extractYuanFlowFileURL(response) {
+  const data = response?.data && typeof response.data === 'object' ? response.data : response;
+  const url = cleanOptional(data?.signed_url) || cleanOptional(data?.url);
+  if (!url) {
+    throw new Error('YuanFlow 文件中转未返回 signed_url 或 url。');
+  }
+  return url;
+}
+
+function mediaPart(media) {
+  if (media.kind === 'video') {
+    return { type: 'video_url', video_url: { url: media.url } };
+  }
+  return { type: 'image_url', image_url: { url: media.url } };
+}
+
+async function buildVoiceEnrollmentBody(options) {
+  if (options.json) {
+    return JSON.parse(options.json);
+  }
+  const filePath = cleanOptional(options.file);
+  const audioUrl = cleanOptional(options.named?.['audio-url']);
+  if (!filePath && !audioUrl) {
+    throw new Error('缺少 --file 或 --audio-url。');
+  }
+  if (filePath && audioUrl) {
+    throw new Error('--file 和 --audio-url 不能同时使用。');
+  }
+  const body = {
+    model: MODEL_QWEN_VOICE,
+    ...optionalField('name', options.named?.name),
+    ...optionalField('preferred_name', options.named?.['preferred-name']),
+    ...optionalField('text', options.named?.text),
+    ...optionalField('language', options.named?.language),
+    ...optionalBooleanField('activate', options.named?.activate),
+  };
+  if (audioUrl) {
+    body.audio_url = audioUrl;
+  } else {
+    body.audio = options.dryRun ? '<data URI omitted in dry-run>' : await fileToDataUri(filePath);
+  }
+  return body;
+}
+
+async function callSpeech(model, options, requiresVoice) {
+  const body = buildSpeechBody(model, options, requiresVoice);
+  const response = await callBinary(AUDIO_SPEECH_PATH, options, body);
+  return result(model, AUDIO_SPEECH_PATH, body, response);
+}
+
+function buildSpeechBody(model, options, requiresVoice) {
+  if (options.json) {
+    return JSON.parse(options.json);
+  }
+  const text = cleanOptional(options.named?.text || options.named?.input);
+  if (!text) {
+    throw new Error('缺少 --text。');
+  }
+  const voice = cleanOptional(options.named?.voice) || (requiresVoice ? undefined : 'default');
+  if (!voice) {
+    throw new Error('缺少 --voice。');
+  }
+  const body = {
+    model,
+    input: text,
+    voice,
+    response_format: cleanOptional(options.named?.['response-format']) || 'mp3',
+    ...optionalField('instructions', options.named?.instructions),
+  };
+  addNumber(body, 'speed', options.named?.speed);
+  const metadata = parseJsonObject(options.named?.metadata);
+  addNumber(metadata, 'sample_rate', options.named?.['sample-rate']);
+  addNumber(metadata, 'volume', options.named?.volume);
+  addNumber(metadata, 'pitch_rate', options.named?.['pitch-rate']);
+  addNumber(metadata, 'bit_rate', options.named?.['bit-rate']);
+  addString(metadata, 'mode', options.named?.mode);
+  addString(metadata, 'language', options.named?.language);
+  if (Object.keys(metadata).length > 0) {
+    body.metadata = metadata;
+  }
+  return body;
+}
+
+async function callFunASR(options) {
+  if (options.json) {
+    return callJson(AUDIO_TRANSCRIPTIONS_PATH, options, JSON.parse(options.json));
+  }
+  const metadata = buildASRMetadata(options);
+  const responseFormat = cleanOptional(options.named?.['response-format']) || 'json';
+  const filePath = cleanOptional(options.file);
+  if (filePath) {
+    const response = await callMultipartJson(AUDIO_TRANSCRIPTIONS_PATH, options, {
+      model: MODEL_FUN_ASR,
+      response_format: responseFormat,
+      metadata,
+      filePath,
+    });
+    return result(MODEL_FUN_ASR, AUDIO_TRANSCRIPTIONS_PATH, { model: MODEL_FUN_ASR, response_format: responseFormat, metadata, file: filePath }, response);
+  }
+  if (!metadata.audio_url) {
+    throw new Error('缺少 --audio-url 或 --file。');
+  }
+  const body = {
+    model: MODEL_FUN_ASR,
+    response_format: responseFormat,
+    metadata,
+  };
+  const response = await callJson(AUDIO_TRANSCRIPTIONS_PATH, options, body);
+  return result(MODEL_FUN_ASR, AUDIO_TRANSCRIPTIONS_PATH, body, response);
+}
+
+async function listDoubaoTTSVoices(options) {
+  const response = await callGetJson(DOUBAO_TTS_VOICE_ASSETS_PATH, options);
+  return result('doubao-tts voices', DOUBAO_TTS_VOICE_ASSETS_PATH, undefined, response, {
+    method: 'GET',
+    kind: 'ai-voice-assets',
+  });
+}
+
+async function getDoubaoTTSVoice(options) {
+  const voiceType = requiredVoiceType(options);
+  const endpointPath = `${DOUBAO_TTS_VOICE_ASSETS_PATH}/${encodeURIComponent(voiceType)}`;
+  const response = await callGetJson(endpointPath, options);
+  return result('doubao-tts voice', endpointPath, undefined, response, {
+    method: 'GET',
+    kind: 'ai-voice-assets',
+  });
+}
+
+async function downloadDoubaoTTSVoice(options) {
+  const voiceType = requiredVoiceType(options);
+  const endpointPath = `${DOUBAO_TTS_VOICE_ASSETS_PATH}/${encodeURIComponent(voiceType)}/download`;
+  const signed = await callGetJson(endpointPath, options);
+  if (options.dryRun || !options.output) {
+    return result('doubao-tts voice-download', endpointPath, undefined, signed, {
+      method: 'GET',
+      kind: 'ai-voice-assets',
+    });
+  }
+  const downloadUrl = signed?.data?.url || signed?.url;
+  if (!downloadUrl) {
+    throw new Error('下载接口未返回 data.url。');
+  }
+  const response = await fetch(downloadUrl);
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`试听音频下载失败：HTTP ${response.status} ${text}`);
+  }
+  const bytes = Buffer.from(await response.arrayBuffer());
+  await writeFile(options.output, bytes);
+  return result('doubao-tts voice-download', endpointPath, undefined, {
+    ok: true,
+    output: options.output,
+    bytes: bytes.length,
+    voice_type: voiceType,
+    content_type: response.headers.get('content-type') || signed?.data?.preview_audio_content_type || '',
+    signed_url_expires_at: signed?.data?.expires_at,
+  }, {
+    method: 'GET',
+    kind: 'ai-voice-assets',
+  });
+}
+
+function buildASRMetadata(options) {
+  const metadata = parseJsonObject(options.named?.metadata);
+  addString(metadata, 'audio_url', options.named?.['audio-url']);
+  addString(metadata, 'language', options.named?.language);
+  const hints = splitList(options.named?.['language-hints']);
+  if (hints.length > 0) {
+    metadata.language_hints = hints;
+  }
+  addBoolean(metadata, 'timestamps', options.named?.timestamps);
+  addBoolean(metadata, 'diarization_enabled', options.named?.['diarization-enabled']);
+  addNumber(metadata, 'speaker_count', options.named?.['speaker-count']);
+  return metadata;
+}
+
+async function callJson(apiPath, options, body) {
+  const request = await buildRequest(apiPath, options, 'POST', body);
+  if (request.dryRun) {
+    return request;
+  }
+  const response = await fetch(request.url, {
+    method: 'POST',
+    headers: {
+      ...request.headers,
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(body || {}),
+  });
+  return readJsonResponse(response);
+}
+
+async function callGetJson(apiPath, options) {
+  const request = await buildRequest(apiPath, options, 'GET');
+  if (request.dryRun) {
+    return request;
+  }
+  const response = await fetch(request.url, {
+    method: 'GET',
+    headers: {
+      ...request.headers,
+      Accept: 'application/json',
+    },
+  });
+  return readJsonResponse(response);
+}
+
+async function callMultipartJson(apiPath, options, payload) {
+  const request = await buildRequest(apiPath, options, 'POST', {
+    model: payload.model,
+    response_format: payload.response_format,
+    metadata: payload.metadata,
+    file: '<file omitted>',
+  });
+  if (request.dryRun) {
+    return request;
+  }
+  const form = new FormData();
+  form.set('model', payload.model);
+  form.set('response_format', payload.response_format);
+  form.set('metadata', JSON.stringify(payload.metadata || {}));
+  const file = new Blob([await readFile(payload.filePath)], { type: inferAudioMimeType(payload.filePath) });
+  form.set('file', file, path.basename(payload.filePath));
+  const response = await fetch(request.url, {
+    method: 'POST',
+    headers: request.headers,
+    body: form,
+  });
+  return readJsonResponse(response);
+}
+
+async function callBinary(apiPath, options, body) {
+  const request = await buildRequest(apiPath, options, 'POST', body);
+  if (request.dryRun) {
+    return request;
+  }
+  if (!options.output) {
+    throw new Error('音频生成需要 --output 指定保存路径。');
+  }
+  const response = await fetch(request.url, {
+    method: 'POST',
+    headers: {
+      ...request.headers,
+      Accept: '*/*',
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(body || {}),
+  });
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`请求失败：HTTP ${response.status} ${text}`);
+  }
+  const bytes = Buffer.from(await response.arrayBuffer());
+  await writeFile(options.output, bytes);
+  return {
+    ok: true,
+    output: options.output,
+    bytes: bytes.length,
+    content_type: response.headers.get('content-type') || '',
+  };
+}
+
+async function buildRequest(apiPath, options, method, body) {
+  const config = await readConfig();
+  const baseUrl = cleanBaseUrl(options.baseUrl || config.baseUrl);
+  const token = options.token || process.env.YUANCHUANG_API_TOKEN || config.token || '';
+  const url = new URL(apiPath, baseUrl);
+  if (options.dryRun) {
+    return {
+      dryRun: true,
+      method,
+      url: url.toString(),
+      headers: token ? { Authorization: `Bearer ${maskToken(token)}` } : {},
+      body: redactBody(body),
+    };
+  }
+  if (!token) {
+    throw new Error('缺少 token。请设置 YUANCHUANG_API_TOKEN，或执行 yuanflow-cli config set-token <你的令牌>');
+  }
+  return {
+    method,
+    url: url.toString(),
+    headers: { Authorization: `Bearer ${token}` },
+    body,
+  };
+}
+
+async function readJsonResponse(response) {
+  const text = await response.text();
+  const payload = parseMaybeJson(text);
+  if (!response.ok) {
+    const message = typeof payload === 'object' ? JSON.stringify(payload) : text;
+    throw new Error(`请求失败：HTTP ${response.status} ${message}`);
+  }
+  return payload;
+}
+
+function result(action, endpointPath, body, response, endpoint = {}) {
+  return {
+    ok: true,
+    action,
+    endpoint: { method: endpoint.method || 'POST', path: endpointPath, kind: endpoint.kind || 'ai-model' },
+    request: { body: redactBody(body) },
+    response,
+  };
+}
+
+function aiCommand({ key, command, description, method = 'POST', apiPath, options, requestBody, returns }) {
+  return {
+    key,
+    command,
+    kind: 'ai-model',
+    description,
+    method,
+    apiPath,
+    positionals: [],
+    options,
+    requestBody,
+    returns,
+  };
+}
+
+function requiredVoiceType(options) {
+  const voiceType = cleanOptional(options.named?.voice || options.named?.['voice-type']);
+  if (!voiceType) {
+    throw new Error('缺少 --voice。');
+  }
+  return voiceType;
+}
+
+function speechOptions(voiceLabel, voiceRequired) {
+  return [
+    option('--text', 'text', true, '待合成文本。'),
+    option('--voice', 'voice', voiceRequired, voiceLabel),
+    option('--output', 'output', true, '音频保存路径；dry-run 时可不传。'),
+    option('--response-format', 'responseFormat', false, 'mp3、wav、pcm 等，默认 mp3。'),
+    option('--speed', 'speed', false, '语速控制。'),
+    option('--sample-rate', 'sampleRate', false, '采样率。'),
+    option('--metadata', 'metadata', false, '透传给 YuanFlow API 的 metadata JSON。'),
+    ...commonOptions(),
+  ];
+}
+
+function commonOptions() {
+  return [
+    option('--json', 'json', false, '直接传完整 YuanFlow API 请求 JSON。'),
+    option('--token', 'token', false, '临时 token。'),
+    option('--base-url', 'baseUrl', false, 'YuanFlow API 地址。'),
+    option('--format', 'format', false, 'Agent 调用时建议使用 agent-json。'),
+    option('--dry-run', 'dryRun', false, '仅预览请求映射，不发起真实请求，也不要求 token。'),
+  ];
+}
+
+function option(flag, name, required, label) {
+  return { flag, name, required, label };
+}
+
+async function fileToDataUri(filePath) {
+  const data = await readFile(filePath);
+  return `data:${inferAudioMimeType(filePath)};base64,${data.toString('base64')}`;
+}
+
+function inferAudioMimeType(filePath) {
+  switch (path.extname(filePath).toLowerCase()) {
+    case '.mp3':
+      return 'audio/mpeg';
+    case '.wav':
+      return 'audio/wav';
+    case '.m4a':
+      return 'audio/mp4';
+    case '.ogg':
+      return 'audio/ogg';
+    case '.flac':
+      return 'audio/flac';
+    case '.pcm':
+      return 'audio/pcm';
+    default:
+      return 'application/octet-stream';
+  }
+}
+
+function inferMediaMimeType(filePath, mediaKind) {
+  if (mediaKind === 'image') {
+    return inferImageMimeType(filePath);
+  }
+  return inferVideoMimeType(filePath);
+}
+
+function inferImageMimeType(filePath) {
+  switch (path.extname(filePath).toLowerCase()) {
+    case '.jpg':
+    case '.jpeg':
+      return 'image/jpeg';
+    case '.png':
+      return 'image/png';
+    case '.webp':
+      return 'image/webp';
+    case '.gif':
+      return 'image/gif';
+    case '.bmp':
+      return 'image/bmp';
+    case '.tif':
+    case '.tiff':
+      return 'image/tiff';
+    case '.heic':
+      return 'image/heic';
+    default:
+      return 'application/octet-stream';
+  }
+}
+
+function inferVideoMimeType(filePath) {
+  switch (path.extname(filePath).toLowerCase()) {
+    case '.mp4':
+      return 'video/mp4';
+    case '.mov':
+      return 'video/quicktime';
+    case '.avi':
+      return 'video/x-msvideo';
+    case '.mkv':
+      return 'video/x-matroska';
+    case '.flv':
+      return 'video/x-flv';
+    case '.wmv':
+      return 'video/x-ms-wmv';
+    case '.webm':
+      return 'video/webm';
+    default:
+      return 'application/octet-stream';
+  }
+}
+
+function parseJsonObject(value) {
+  const cleaned = cleanOptional(value);
+  if (!cleaned) {
+    return {};
+  }
+  const parsed = JSON.parse(cleaned);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('--metadata 必须是 JSON 对象。');
+  }
+  return parsed;
+}
+
+function optionalField(name, value) {
+  const cleaned = cleanOptional(value);
+  return cleaned === undefined ? {} : { [name]: cleaned };
+}
+
+function optionalBooleanField(name, value) {
+  const parsed = parseBoolean(value);
+  return parsed === undefined ? {} : { [name]: parsed };
+}
+
+function addString(target, name, value) {
+  const cleaned = cleanOptional(value);
+  if (cleaned !== undefined) {
+    target[name] = cleaned;
+  }
+}
+
+function addNumber(target, name, value) {
+  const cleaned = cleanOptional(value);
+  if (cleaned !== undefined) {
+    const number = Number(cleaned);
+    target[name] = Number.isFinite(number) ? number : cleaned;
+  }
+}
+
+function addBoolean(target, name, value) {
+  const parsed = parseBoolean(value);
+  if (parsed !== undefined) {
+    target[name] = parsed;
+  }
+}
+
+function parseBoolean(value) {
+  const cleaned = cleanOptional(value);
+  if (cleaned === undefined) {
+    return undefined;
+  }
+  if (typeof cleaned === 'boolean') {
+    return cleaned;
+  }
+  return ['1', 'true', 'yes', 'on'].includes(String(cleaned).toLowerCase());
+}
+
+function splitList(value) {
+  const cleaned = cleanOptional(value);
+  if (!cleaned) {
+    return [];
+  }
+  return String(cleaned)
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function cleanOptional(value) {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+  }
+  return value;
+}
+
+function redactBody(body) {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) {
+    return body;
+  }
+  const redacted = { ...body };
+  if ('audio' in redacted) {
+    redacted.audio = '<data URI omitted>';
+  }
+  if ('file' in redacted) {
+    redacted.file = '<file omitted>';
+  }
+  return redacted;
+}
+
+function cleanBaseUrl(value) {
+  return (value || 'https://open.yuanchuangai.com').replace(/\/+$/, '');
+}
+
+function parseMaybeJson(text) {
+  if (!text) {
+    return null;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+function maskToken(token) {
+  if (!token) {
+    return '';
+  }
+  if (token.length <= 10) {
+    return '***';
+  }
+  return `${token.slice(0, 6)}...${token.slice(-4)}`;
+}
+
+function formatBytes(bytes) {
+  if (bytes < 1024 * 1024) {
+    return `${Math.ceil(bytes / 1024)}KB`;
+  }
+  return `${(bytes / 1024 / 1024).toFixed(2)}MB`;
+}