yuanflow-cli 0.1.44 → 0.1.45

package/README.md

@@ -6,6 +6,7 @@ YuanFlow 的 npm 包，包含两个命令入口：
 - `yuanflow-skill`：把 `YuanFlow-skill` 注入到本机支持的 AI Agent skills 目录。
 - `飞书官方技能`：YuanFlow-main 内置环境通过受控工具托管安装并调用飞书官方 `@larksuite/cli`，npm 包只提供 Skill 说明，不复制官方 CLI 源码。
 - `视觉卡片生成`：作为 Skill、HTML 模板、参考文档和检查脚本随包分发，不新增独立 `yuanflow-cli visual-card` 命令。
+- `声音克隆 / 声音复刻`：通过 `yuanflow-cli voice` 命令创建、查询、激活 `voice_xxx`，并把文本复刻生成音频文件。
 
 ## 安装
 
@@ -53,6 +54,10 @@ yuanflow-cli video plan --project "D:\素材\yuanflow-video-edit" --timeline-pla
 yuanflow-cli ai qwen3-vl-plus --prompt "描述这张图" --image-url "https://example.com/image.png" --format agent-json
 yuanflow-cli ai qwen3-vl-plus --prompt "总结这个视频画面" --video-url "https://example.com/video.mp4" --format agent-json
 yuanflow-cli ai qwen3-vl-plus --prompt "描述本地视频" --video-file "D:\素材\demo.mp4" --format agent-json
+yuanflow-cli voice clone --file-transfer "D:\voice\sample.wav" --name "我的声音" --activate --format agent-json
+yuanflow-cli voice list --format agent-json
+yuanflow-cli voice activate --voice voice_xxx --format agent-json
+yuanflow-cli voice replicate --text "你好，这是声音复刻测试。" --voice voice_xxx --output "D:\voice\replicate.mp3" --format agent-json
 yuanflow-cli ai doubao-tts voices --format agent-json
 yuanflow-cli ai doubao-tts voice --voice zh_female_xiaohe_uranus_bigtts --format agent-json
 yuanflow-cli ai doubao-tts voice-download --voice zh_female_xiaohe_uranus_bigtts --output "D:\voice\preview.mp3" --format agent-json
@@ -69,6 +74,33 @@ YUANCHUANG_API_TOKEN=<你的令牌>
 
 token 优先级：`--token` > `YUANCHUANG_API_TOKEN` > 本地 `config.token`。独立 CLI 用户可以使用环境变量或 `config set-token`；在 YuanFlow-main 内置环境使用时，token 由 YuanFlow-main 内置环境注入，不需要手动配置。本地图片/视频上传统一使用 YuanFlow 文件中转，不需要用户配置第三方平台 Key。
 
+### 声音克隆与声音复刻
+
+`voice` 命令组用于创建声音克隆、查询已有克隆音色 ID、激活默认音色，并使用 `voice_xxx` 把文本复刻为音频文件。声音复刻前必须先有 `voice_xxx`，或已激活默认音色。
+
+```bash
+# 创建声音克隆：本地音频先走 YuanFlow 文件中转
+yuanflow-cli voice clone --file-transfer "D:\voice\sample.wav" --name "我的声音" --activate --format agent-json
+
+# 查询已有声音克隆 ID
+yuanflow-cli voice list --format agent-json
+
+# 激活某个克隆音色为默认音色
+yuanflow-cli voice activate --voice voice_xxx --format agent-json
+
+# 使用克隆音色生成复刻音频
+yuanflow-cli voice replicate --text "你好，这是声音复刻测试。" --voice voice_xxx --output "D:\voice\replicate.mp3" --format agent-json
+```
+
+命令清单：
+
+- `voice clone`：`POST /v1/audio/voices`，创建声音克隆，常用参数 `--file`、`--file-transfer`、`--audio-url`、`--name`、`--activate`。
+- `voice list`：`GET /v1/audio/voices`，查询当前用户已有声音克隆音色 ID。
+- `voice activate`：`POST /v1/audio/voices/{voice_xxx}/activate`，把已有声音克隆设为默认音色。
+- `voice replicate`：`POST /v1/audio/speech`，使用 `voice_xxx` 或 `default` 生成复刻音频，真实调用时必须传 `--output`。
+
+`--file-transfer` 会先通过 YuanFlow 文件中转上传本地音频，再把临时访问链接提交给 YuanFlow API。`--file` 保留为直接提交本地音频的兼容方式。`--file`、`--file-transfer` 和 `--audio-url` 只能选择一个。
+
 ### AI 模型命令
 
 `ai` 命令用于调用 YuanFlow API 的 OpenAI 兼容端点。CLI 对外只使用 YuanFlow API 模型参数，不暴露底层供应商内部模型名。
@@ -79,8 +111,6 @@ yuanflow-cli ai qwen3-vl-plus --prompt "描述这张图" --image-url "https://ex
 yuanflow-cli ai qwen3-vl-plus --prompt "总结这个视频画面" --video-url "https://example.com/video.mp4" --format agent-json
 yuanflow-cli ai qwen3-vl-plus --prompt "描述本地图片" --image-file "D:\素材\cover.png" --format agent-json
 yuanflow-cli ai qwen3-vl-plus --prompt "描述本地视频" --video-file "D:\素材\demo.mp4" --format agent-json
-yuanflow-cli ai qwen-voice-enrollment --file "D:\voice\sample.wav" --name demo --activate --format agent-json
-yuanflow-cli ai qwen3-tts-vc-realtime-2026-01-15 --text "你好" --voice voice_xxx --output "D:\voice\qwen.mp3" --format agent-json
 yuanflow-cli ai fun-asr --audio-url "https://example.com/audio.wav" --response-format verbose_json --format agent-json
 yuanflow-cli ai doubao-tts voices --format agent-json
 yuanflow-cli ai doubao-tts voice --voice zh_female_xiaohe_uranus_bigtts --format agent-json
@@ -122,8 +152,6 @@ yuanflow-cli ai qwen3-vl-plus --prompt "描述本地视频" --video-file "D:\素
 命令清单：
 
 - `ai qwen3-vl-plus`：`POST /v1/chat/completions`，文本/图片/视频理解，常用参数 `--prompt`、`--image-url`、`--video-url`、`--image-file`、`--video-file`。
-- `ai qwen-voice-enrollment`：`POST /v1/audio/voices`，音色复刻，常用参数 `--file` 或 `--audio-url`、`--name`、`--activate`。
-- `ai qwen3-tts-vc-realtime-2026-01-15`：`POST /v1/audio/speech`，复刻音色合成，`--voice` 使用 `voice_xxx` 或 `default`。
 - `ai fun-asr`：`POST /v1/audio/transcriptions`，语音识别，`--audio-url` 适合远程音频，`--file` 适合本地音频直传。
 - `ai doubao-tts`：`POST /v1/audio/speech`，豆包语音合成，`--voice` 直接传豆包官方音色 ID。
 - `ai doubao-tts voices`：`GET /api/voice-assets/doubao/voices`，查询 doubao-tts 可用音色列表。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yuanflow-cli",
-  "version": "0.1.44",
+  "version": "0.1.45",
   "description": "YuanFlow 自媒体 API CLI 与 Skill 安装器。",
   "type": "module",
   "license": "MIT",

package/skills/yuanflow-skill//345/243/260/351/237/263/345/205/213/351/232/206/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: 声音克隆
+description: 当用户需要创建声音克隆、查询已有声音克隆音色 ID、激活默认克隆音色，或为后续声音复刻准备 voice_xxx 时使用。本 Skill 通过 YuanFlow API 和 yuanflow-cli voice 命令完成。
+emoji: 🎙️
+---
+
+# 声音克隆
+
+本 Skill 用于把参考音频注册成可复用的声音克隆音色，并返回 `voice_xxx` 音色 ID。后续要生成复刻音频时，交给 `声音复刻` Skill。
+
+## 外部 CLI 主流程
+
+外部 Agent 或用户直接使用时，优先使用 `yuanflow-cli voice ...` 命令。
+
+1. 先确认本机可执行 `yuanflow-cli --help`。
+2. 外部 CLI 使用 `YUANCHUANG_API_TOKEN` 或 `yuanflow-cli config set-token <你的令牌>` 完成鉴权。
+3. 选择音频输入方式：
+   - 本地音频直接提交：`--file`
+   - 本地音频先走 YuanFlow 文件中转：`--file-transfer`
+   - 已有公网音频链接：`--audio-url`
+4. 创建成功后，保存返回的 `voice_xxx`。这是后续声音复刻必须使用的音色 ID。
+
+不要在回复、日志或文件中暴露 token。用户主流程统一称为 YuanFlow API 和 YuanFlow 文件中转，不要求用户配置第三方平台 Key。
+
+## 创建声音克隆
+
+推荐本地文件使用 YuanFlow 文件中转：
+
+```powershell
+yuanflow-cli voice clone --file-transfer "D:\voice\sample.wav" --name "我的声音" --activate --format agent-json
+```
+
+如果用户明确希望直接提交本地音频：
+
+```powershell
+yuanflow-cli voice clone --file "D:\voice\sample.wav" --name "我的声音" --activate --format agent-json
+```
+
+如果已经有可访问音频 URL：
+
+```powershell
+yuanflow-cli voice clone --audio-url "https://example.com/sample.wav" --name "我的声音" --activate --format agent-json
+```
+
+返回里重点读取：
+
+```text
+data.response.id
+```
+
+如果响应结构被 Agent JSON 包裹，优先找 `voice_xxx` 格式的 `id` 字段。不要把内部原始音色参数展示给用户。
+
+## 查询已有声音克隆 ID
+
+当用户已经做过声音克隆但忘记 ID，先查询：
+
+```powershell
+yuanflow-cli voice list --format agent-json
+```
+
+输出时只需要整理这些字段：
+
+```text
+声音名称：
+音色 ID：voice_xxx
+状态：
+是否默认：
+创建时间：
+```
+
+如果没有可用音色，提示用户先提供参考音频创建声音克隆。
+
+## 激活默认音色
+
+如果用户希望后续用 `default` 复刻，或指定某个克隆音色为默认：
+
+```powershell
+yuanflow-cli voice activate --voice voice_xxx --format agent-json
+```
+
+## 音频要求
+
+- 优先使用清晰、无背景音乐、无明显混响的人声音频。
+- 建议使用 wav、mp3、m4a、flac 等常见格式。
+- 文件过大、噪音明显或多人混说时，先让用户换音频或裁剪。
+- 不要上传身份证、合同、私密通话、未授权人物声音等敏感内容，除非用户明确确认且任务确实需要。
+
+## YuanFlow-main 内置环境
+
+只有在 YuanFlow-main 内置环境中，才使用受控工具 `yuanflow_cli_call`。token、受管包路径和输出目录由 YuanFlow-main 管理，不写成外部用户必备步骤。
+
+创建声音克隆：
+
+```json
+{
+  "args": [
+    "voice",
+    "clone",
+    "--file-transfer",
+    "D:\\voice\\sample.wav",
+    "--name",
+    "我的声音",
+    "--activate",
+    "--format",
+    "agent-json"
+  ],
+  "timeout": 300
+}
+```
+
+查询已有声音克隆：
+
+```json
+{
+  "args": [
+    "voice",
+    "list",
+    "--format",
+    "agent-json"
+  ],
+  "timeout": 120
+}
+```
+
+激活默认音色：
+
+```json
+{
+  "args": [
+    "voice",
+    "activate",
+    "--voice",
+    "voice_xxx",
+    "--format",
+    "agent-json"
+  ],
+  "timeout": 120
+}
+```
+
+## 失败处理
+
+- token 缺失：说明需要配置 YuanFlow API token，或在 YuanFlow-main 受控环境中运行。
+- 没有返回 `voice_xxx`：说明声音克隆未完成，不要继续声音复刻。
+- 已存在克隆限制：先用 `voice list` 查询已有音色，必要时让用户选择已有 `voice_xxx` 继续。
+- 音频不可访问：如果使用 URL，让用户换成可访问链接；如果是本地文件，改用 `--file-transfer`。

package/skills/yuanflow-skill//345/243/260/351/237/263/345/244/215/345/210/273/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: 声音复刻
+description: 当用户需要使用已有声音克隆 ID 生成复刻语音、把文字合成为用户克隆声音，或要求根据 voice_xxx 输出音频文件时使用。使用前必须先完成声音克隆或查询到已有 voice_xxx。
+emoji: 🔊
+---
+
+# 声音复刻
+
+本 Skill 用于把文本合成为已有克隆音色的音频。使用前必须满足其中一个条件：
+
+- 已通过 `声音克隆` Skill 创建过声音克隆，并拿到 `voice_xxx`。
+- 已通过 `yuanflow-cli voice list` 查询到可用 `voice_xxx`。
+- 用户明确指定使用已激活默认音色 `default`。
+
+如果没有声音克隆 ID，先调用 `声音克隆`，不要直接复刻。
+
+## 外部 CLI 主流程
+
+外部 Agent 或用户直接使用时，优先使用 `yuanflow-cli voice replicate`。
+
+1. 先确认本机可执行 `yuanflow-cli --help`。
+2. 外部 CLI 使用 `YUANCHUANG_API_TOKEN` 或 `yuanflow-cli config set-token <你的令牌>` 完成鉴权。
+3. 确认 `--voice` 是 `voice_xxx` 或 `default`。
+4. 用 `--output` 指定音频保存路径。
+
+不要在回复、日志或文件中暴露 token。用户主流程统一称为 YuanFlow API，不要求用户配置第三方平台 Key。
+
+## 查询或确认音色 ID
+
+如果用户没有提供 `voice_xxx`，先查询：
+
+```powershell
+yuanflow-cli voice list --format agent-json
+```
+
+如果列表中没有可用音色，转到 `声音克隆` Skill，先创建声音克隆。
+
+## 生成复刻音频
+
+```powershell
+yuanflow-cli voice replicate --text "你好，这是声音复刻测试。" --voice voice_xxx --output "D:\voice\replicate.mp3" --format agent-json
+```
+
+如果用户要求使用默认音色：
+
+```powershell
+yuanflow-cli voice replicate --text "你好，这是声音复刻测试。" --voice default --output "D:\voice\replicate.mp3" --format agent-json
+```
+
+默认输出 `mp3`。用户要求 wav 或 pcm 时，增加 `--response-format`：
+
+```powershell
+yuanflow-cli voice replicate --text "测试内容" --voice voice_xxx --response-format wav --output "D:\voice\replicate.wav" --format agent-json
+```
+
+## 输出要求
+
+最终回复给用户时说明：
+
+```text
+复刻音频已生成：
+文件路径：D:\voice\replicate.mp3
+使用音色：voice_xxx
+```
+
+如果命令返回 agent-json，优先读取：
+
+```text
+data.response.output
+data.response.bytes
+data.response.content_type
+```
+
+## YuanFlow-main 内置环境
+
+只有在 YuanFlow-main 内置环境中，才使用受控工具 `yuanflow_cli_call`。token、受管包路径和输出目录由 YuanFlow-main 管理，不写成外部用户必备步骤。
+
+```json
+{
+  "args": [
+    "voice",
+    "replicate",
+    "--text",
+    "你好，这是声音复刻测试。",
+    "--voice",
+    "voice_xxx",
+    "--output",
+    "replicate.mp3",
+    "--format",
+    "agent-json"
+  ],
+  "timeout": 300
+}
+```
+
+在 YuanFlow-main 内置环境里，`--output` 会被限制到受控输出目录。不要要求用户手动传程序数据目录，也不要绕过 `yuanflow_cli_call` 直接写本地文件。
+
+## 失败处理
+
+- 缺少 `voice_xxx`：先调用 `声音克隆` 的查询流程或创建流程。
+- 音色不存在或无权限：提示用户重新查询 `voice list`，不要猜测 ID。
+- 输出路径被拒绝：在 YuanFlow-main 内置环境中改用相对文件名，让受控工具自动放入输出目录。
+- 生成失败：报告 YuanFlow API 返回的简短错误，不暴露 token、Authorization header 或完整敏感链接。

package/src/agent-protocol.js

@@ -8,6 +8,7 @@ import { listSearchCommands, listWorkCommands } from './work-tools.js';
 import { listVideoCommands } from './video-tools.js';
 import { listTrendingCommands } from './trending-tools.js';
 import { listAiCommands } from './ai-tools.js';
+import { listVoiceCommands } from './voice-tools.js';
 
 const ERROR_MAP = [
   {
@@ -113,6 +114,7 @@ export function buildCommandRegistry() {
   const videoCommands = listVideoCommands();
   const trendingCommands = listTrendingCommands();
   const aiCommands = listAiCommands();
+  const voiceCommands = listVoiceCommands();
   return [
     ...shortcuts,
     ...endpoints,
@@ -125,6 +127,7 @@ export function buildCommandRegistry() {
     ...videoCommands,
     ...trendingCommands,
     ...aiCommands,
+    ...voiceCommands,
   ].sort((left, right) => left.key.localeCompare(right.key));
 }
 

package/src/cli.js

@@ -29,6 +29,7 @@ import {
 } from './work-tools.js';
 import { fetchVideoHotList } from './trending-tools.js';
 import { formatAiHelp, runAiCommand } from './ai-tools.js';
+import { formatVoiceHelp, runVoiceCommand } from './voice-tools.js';
 
 export async function main(argv) {
   const args = argv.slice(2);
@@ -104,6 +105,11 @@ export async function main(argv) {
     return;
   }
 
+  if (command === 'voice') {
+    await handleVoice(rest);
+    return;
+  }
+
   if (command === 'schema') {
     await handleSchema(rest);
     return;
@@ -451,6 +457,20 @@ async function handleAi(args) {
   });
 }
 
+async function handleVoice(args) {
+  const { positionals, options } = parseOptions(args);
+  const [action = 'help'] = positionals;
+  if (action === 'help' && !isAgentJsonFormat(options)) {
+    console.log(formatVoiceHelp());
+    return;
+  }
+  const result = await runVoiceCommand({ action, options });
+  await outputResult(result, { ...options, output: undefined }, {
+    command: `voice ${action}`,
+    meta: { endpoint: result.endpoint?.path, kind: result.endpoint?.kind || 'voice' },
+  });
+}
+
 async function handleGeneratedCommand(platform, args) {
   if (!getPlatforms().includes(platform)) {
     throw new Error(`未知平台：${platform}。可用平台：${getPlatforms().join(', ')}`);
@@ -633,6 +653,10 @@ function printHelp() {
   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 voice clone --file-transfer "D:\\voice\\sample.wav" --name demo --activate --dry-run
+  yuanflow-cli voice list --dry-run
+  yuanflow-cli voice activate --voice voice_xxx --dry-run
+  yuanflow-cli voice replicate --text "你好" --voice voice_xxx --output "D:\\voice\\replicate.mp3" --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

package/src/voice-tools.js

@@ -0,0 +1,471 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { readConfig } from './config.js';
+import { callAtomic, cleanBaseUrl } from './atomic-request.js';
+
+const AUDIO_SPEECH_PATH = '/v1/audio/speech';
+const AUDIO_VOICES_PATH = '/v1/audio/voices';
+const YUANFLOW_FILE_TRANSFER_PATH = '/atomic/oss/temp-upload';
+
+const MODEL_VOICE_CLONE = 'qwen-voice-enrollment';
+const MODEL_VOICE_REPLICATE = 'qwen3-tts-vc-realtime-2026-01-15';
+
+export function listVoiceCommands() {
+  return [
+    voiceCommand({
+      key: 'voice.clone',
+      command: 'voice clone',
+      description: '通过 YuanFlow API 创建声音克隆，返回可复用的 voice_xxx 音色 ID。',
+      method: 'POST',
+      apiPath: AUDIO_VOICES_PATH,
+      options: [
+        option('--file', 'file', false, '本地音频文件；与 --file-transfer、--audio-url 三选一。'),
+        option('--file-transfer', 'fileTransfer', false, '本地音频文件；先通过 YuanFlow 文件中转生成临时 URL，再创建声音克隆。'),
+        option('--audio-url', 'audioUrl', false, '公网可访问音频 URL；与 --file、--file-transfer 三选一。'),
+        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_VOICE_CLONE,
+        audio: '<本地音频 data URI，或通过 audio_url 传入 YuanFlow 文件中转 URL>',
+      },
+      returns: '返回 voice_xxx 音色对象；后续 voice replicate 可通过 --voice voice_xxx 复刻声音。',
+    }),
+    voiceCommand({
+      key: 'voice.list',
+      command: 'voice list',
+      description: '查询当前 YuanFlow API 令牌下已有的声音克隆音色 ID。',
+      method: 'GET',
+      apiPath: AUDIO_VOICES_PATH,
+      options: commonOptions(),
+      requestBody: null,
+      returns: '返回当前用户可用的 voice_xxx 音色列表、名称、状态和是否默认激活。',
+    }),
+    voiceCommand({
+      key: 'voice.activate',
+      command: 'voice activate',
+      description: '把已有声音克隆音色设为默认音色，方便 voice replicate 使用 default 复刻。',
+      method: 'POST',
+      apiPath: `${AUDIO_VOICES_PATH}/{voice_xxx}/activate`,
+      options: [
+        option('--voice', 'voice', true, '声音克隆 ID，例如 voice_xxx。'),
+        ...commonOptions(),
+      ],
+      requestBody: null,
+      returns: '返回已激活的 voice_xxx 音色对象。',
+    }),
+    voiceCommand({
+      key: 'voice.replicate',
+      command: 'voice replicate',
+      description: '使用已有声音克隆音色 ID 复刻生成音频文件。',
+      method: 'POST',
+      apiPath: AUDIO_SPEECH_PATH,
+      options: [
+        option('--text', 'text', true, '待复刻合成文本。'),
+        option('--voice', 'voice', true, '声音克隆 ID：voice_xxx；也可传 default 使用已激活默认音色。'),
+        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(),
+      ],
+      requestBody: {
+        model: MODEL_VOICE_REPLICATE,
+        input: '<text>',
+        voice: '<voice_xxx|default>',
+      },
+      returns: '返回音频二进制；CLI 通过 --output 保存到本地文件。',
+    }),
+  ];
+}
+
+export function formatVoiceHelp() {
+  return listVoiceCommands()
+    .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 runVoiceCommand({ action = 'help', options }) {
+  switch (action) {
+    case 'help':
+    case 'list-commands':
+      return { ok: true, commands: listVoiceCommands() };
+    case 'clone':
+      return cloneVoice(options);
+    case 'list':
+      return listVoices(options);
+    case 'activate':
+      return activateVoice(options);
+    case 'replicate':
+      return replicateVoice(options);
+    default:
+      throw new Error(`未知 voice 命令：${action}。可执行 yuanflow-cli voice help 查看用法。`);
+  }
+}
+
+async function cloneVoice(options) {
+  const body = await buildVoiceCloneBody(options);
+  const response = await callJson(AUDIO_VOICES_PATH, options, body);
+  return result('voice clone', AUDIO_VOICES_PATH, body, response, { kind: 'voice-clone' });
+}
+
+async function listVoices(options) {
+  const response = await callGetJson(AUDIO_VOICES_PATH, options);
+  return result('voice list', AUDIO_VOICES_PATH, undefined, response, {
+    method: 'GET',
+    kind: 'voice-clone',
+  });
+}
+
+async function activateVoice(options) {
+  const voice = requiredVoice(options);
+  const endpointPath = `${AUDIO_VOICES_PATH}/${encodeURIComponent(voice)}/activate`;
+  const response = await callJson(endpointPath, options, {});
+  return result('voice activate', endpointPath, undefined, response, { kind: 'voice-clone' });
+}
+
+async function replicateVoice(options) {
+  const body = buildVoiceReplicateBody(options);
+  const response = await callBinary(AUDIO_SPEECH_PATH, options, body);
+  return result('voice replicate', AUDIO_SPEECH_PATH, body, response, { kind: 'voice-replicate' });
+}
+
+async function buildVoiceCloneBody(options) {
+  if (options.json) {
+    return JSON.parse(options.json);
+  }
+  const filePath = cleanOptional(options.file);
+  const fileTransferPath = cleanOptional(options.named?.['file-transfer']);
+  const audioUrl = cleanOptional(options.named?.['audio-url']);
+  const sources = [filePath, fileTransferPath, audioUrl].filter(Boolean);
+  if (sources.length === 0) {
+    throw new Error('缺少 --file、--file-transfer 或 --audio-url。');
+  }
+  if (sources.length > 1) {
+    throw new Error('--file、--file-transfer 和 --audio-url 只能选择一个。');
+  }
+
+  const body = {
+    model: MODEL_VOICE_CLONE,
+    ...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 if (fileTransferPath) {
+    body.audio_url = await resolveYuanFlowAudioFile(fileTransferPath, options);
+  } else {
+    body.audio = options.dryRun ? '<data URI omitted in dry-run>' : await fileToDataUri(filePath);
+  }
+  return body;
+}
+
+function buildVoiceReplicateBody(options) {
+  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 = requiredVoice(options);
+  const body = {
+    model: MODEL_VOICE_REPLICATE,
+    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']);
+  if (Object.keys(metadata).length > 0) {
+    body.metadata = metadata;
+  }
+  return body;
+}
+
+async function resolveYuanFlowAudioFile(filePath, options) {
+  const filename = path.basename(filePath);
+  if (options.dryRun) {
+    return `<YuanFlow 文件中转 signed_url:${filename}>`;
+  }
+  const response = await callAtomic(YUANFLOW_FILE_TRANSFER_PATH, {
+    ...options,
+    json: undefined,
+    method: 'POST',
+    body: {
+      filename,
+      content_base64: (await readFile(filePath)).toString('base64'),
+      content_type: inferAudioMimeType(filePath),
+    },
+  });
+  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;
+}
+
+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 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 || 'voice' },
+    request: { body: redactBody(body) },
+    response,
+  };
+}
+
+function voiceCommand({ key, command, description, method, apiPath, options, requestBody, returns }) {
+  return {
+    key,
+    command,
+    kind: 'voice',
+    description,
+    method,
+    apiPath,
+    positionals: [],
+    options,
+    requestBody,
+    returns,
+  };
+}
+
+function requiredVoice(options) {
+  const voice = cleanOptional(options.named?.voice || options.named?.['voice-id']);
+  if (!voice) {
+    throw new Error('缺少 --voice。');
+  }
+  return voice;
+}
+
+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 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 addNumber(target, name, value) {
+  const cleaned = cleanOptional(value);
+  if (cleaned !== undefined) {
+    const number = Number(cleaned);
+    target[name] = Number.isFinite(number) ? number : cleaned;
+  }
+}
+
+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 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>';
+  }
+  return redacted;
+}
+
+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)}`;
+}