yuanflow-cli 0.1.47 → 0.1.48

package/README.md

@@ -50,15 +50,15 @@ yuanflow-cli browser profile-path --platform douyin --account main --format agen
 yuanflow-cli browser task-plan --platform xiaohongshu --task publish --account main --format agent-json
 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 ai qwen3-vl-plus --prompt "描述本地视频" --video-file "<本地视频路径>" --format agent-json
+yuanflow-cli voice clone --file-transfer "<本地音频路径>" --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 voice replicate --text "你好，这是声音复刻测试。" --voice voice_xxx --output "<输出音频路径>" --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
-yuanflow-cli ai doubao-tts --text "你好" --voice zh_female_xiaohe_uranus_bigtts --output "D:\voice\doubao.mp3" --format agent-json
+yuanflow-cli ai doubao-tts voice-download --voice zh_female_xiaohe_uranus_bigtts --output "<输出音频路径>" --format agent-json
+yuanflow-cli ai doubao-tts --text "你好" --voice zh_female_xiaohe_uranus_bigtts --output "<输出音频路径>" --format agent-json
 yuanflow-cli ai fun-asr --audio-url "https://example.com/audio.wav" --response-format verbose_json --format agent-json
 yuanflow-cli list douyin
 ```
@@ -77,7 +77,10 @@ token 优先级：`--token` > `YUANCHUANG_API_TOKEN` > 本地 `config.token`。
 
 ```bash
 # 创建声音克隆：本地音频先走 YuanFlow 文件中转
-yuanflow-cli voice clone --file-transfer "D:\voice\sample.wav" --name "我的声音" --activate --format agent-json
+yuanflow-cli voice clone --file-transfer "<本地音频路径>" --name "我的声音" --activate --format agent-json
+
+# 创建声音克隆：本地音频 multipart 直接提交给 YuanFlow API
+yuanflow-cli voice clone --file "<本地音频路径>" --name "我的声音" --activate --format agent-json
 
 # 查询已有声音克隆 ID
 yuanflow-cli voice list --format agent-json
@@ -86,17 +89,17 @@ 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 voice replicate --text "你好，这是声音复刻测试。" --voice voice_xxx --output "<输出音频路径>" --format agent-json
 ```
 
 命令清单：
 
-- `voice clone`：`POST /v1/audio/voices`，创建声音克隆，常用参数 `--file`、`--file-transfer`、`--audio-url`、`--name`、`--activate`。
+- `voice clone`：`POST /v1/audio/voices`，创建声音克隆，默认使用 `voice-enrollment` 并绑定后续合成模型 `cosyvoice-v3-flash`，常用参数 `--file`、`--file-transfer`、`--audio-url`、`--name`、`--language-hints`、`--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` 只能选择一个。
+`--file-transfer` 会先通过 YuanFlow 文件中转上传本地音频，再把临时访问链接作为 `audio_url` 提交给 YuanFlow API。`--file` 会通过 multipart 直接提交本地音频，由 YuanFlow API 处理临时访问链接。`--file`、`--file-transfer` 和 `--audio-url` 只能选择一个。
 
 ### AI 模型命令
 
@@ -106,13 +109,15 @@ yuanflow-cli voice replicate --text "你好，这是声音复刻测试。" --voi
 yuanflow-cli ai help
 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 "描述本地图片" --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 qwen3-vl-plus --prompt "描述本地图片" --image-file "<本地图片路径>" --format agent-json
+yuanflow-cli ai qwen3-vl-plus --prompt "描述本地视频" --video-file "<本地视频路径>" --format agent-json
+yuanflow-cli ai voice-enrollment --file "<本地音频路径>" --name "我的声音" --activate --format agent-json
+yuanflow-cli ai cosyvoice-v3-flash --text "你好，这是声音复刻测试。" --voice voice_xxx --output "<输出音频路径>" --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
-yuanflow-cli ai doubao-tts voice-download --voice zh_female_xiaohe_uranus_bigtts --output "D:\voice\preview.mp3" --format agent-json
-yuanflow-cli ai doubao-tts --text "你好" --voice zh_female_xiaohe_uranus_bigtts --output "D:\voice\doubao.mp3" --format agent-json
+yuanflow-cli ai doubao-tts voice-download --voice zh_female_xiaohe_uranus_bigtts --output "<输出音频路径>" --format agent-json
+yuanflow-cli ai doubao-tts --text "你好" --voice zh_female_xiaohe_uranus_bigtts --output "<输出音频路径>" --format agent-json
 ```
 
 #### qwen3-vl-plus 视觉理解
@@ -127,10 +132,10 @@ 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 文件中转，再把临时访问链接传给 YuanFlow API
-yuanflow-cli ai qwen3-vl-plus --prompt "描述本地图片" --image-file "D:\素材\cover.png" --format agent-json
+yuanflow-cli ai qwen3-vl-plus --prompt "描述本地图片" --image-file "<本地图片路径>" --format agent-json
 
 # 本地视频：先上传到 YuanFlow 文件中转，再把临时访问链接传给 YuanFlow API
-yuanflow-cli ai qwen3-vl-plus --prompt "描述本地视频" --video-file "D:\素材\demo.mp4" --format agent-json
+yuanflow-cli ai qwen3-vl-plus --prompt "描述本地视频" --video-file "<本地视频路径>" --format agent-json
 ```
 
 本地文件上传要求：
@@ -149,6 +154,8 @@ 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 voice-enrollment`：`POST /v1/audio/voices`，创建声音克隆音色，返回 `voice_xxx`。
+- `ai cosyvoice-v3-flash`：`POST /v1/audio/speech`，使用 `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 可用音色列表。
@@ -171,10 +178,10 @@ yuanflow-cli ai doubao-tts voices --format agent-json
 yuanflow-cli ai doubao-tts voice --voice zh_female_xiaohe_uranus_bigtts --format agent-json
 
 # 3. 下载该音色的试听音频
-yuanflow-cli ai doubao-tts voice-download --voice zh_female_xiaohe_uranus_bigtts --output "D:\voice\preview-xiaohe.mp3" --format agent-json
+yuanflow-cli ai doubao-tts voice-download --voice zh_female_xiaohe_uranus_bigtts --output "<输出音频路径>" --format agent-json
 
 # 4. 使用同一个 voice_type 进行真实语音合成
-yuanflow-cli ai doubao-tts --text "你好，这是豆包语音合成测试。" --voice zh_female_xiaohe_uranus_bigtts --output "D:\voice\doubao-xiaohe.mp3" --format agent-json
+yuanflow-cli ai doubao-tts --text "你好，这是豆包语音合成测试。" --voice zh_female_xiaohe_uranus_bigtts --output "<输出音频路径>" --format agent-json
 ```
 
 音色列表返回的关键字段：
@@ -298,11 +305,7 @@ Agent 应先查看 `knowledge docs`，再把用户需求整理成 `task_frame`
 
 ### 视频制作能力迁移
 
-视频智能剪辑、主音频+B-roll、EDL 校验和基础渲染链路已迁移到独立项目维护，不再作为 `yuanflow-cli video` 命令提供。独立开发目录：
-
-```text
-D:\AI_project\视频制作
-```
+视频智能剪辑、主音频+B-roll、EDL 校验和基础渲染链路已迁移到独立项目维护，不再作为 `yuanflow-cli video` 命令提供。
 
 `YuanFlow-cli` 仍保留通用视频理解、视频拆解、音视频在线转文字、作品下载和知识库查询等通用能力；视频制作项目后续按需调用这些通用能力。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yuanflow-cli",
-  "version": "0.1.47",
+  "version": "0.1.48",
   "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

@@ -15,33 +15,54 @@ emoji: 🎙️
 1. 先确认本机可执行 `yuanflow-cli --help`。
 2. 外部 CLI 使用 `YUANCHUANG_API_TOKEN` 或 `yuanflow-cli config set-token <你的令牌>` 完成鉴权。
 3. 选择音频输入方式：
-   - 本地音频直接提交：`--file`
-   - 本地音频先走 YuanFlow 文件中转：`--file-transfer`
-   - 已有公网音频链接：`--audio-url`
+   - 本地音频优先先调用 `YuanFlow文件中转工具`，用 `oss temp-upload` 上传并取得临时访问 URL，再通过 `--audio-url` 提交。
+   - 已有公网音频链接或上一步取得的临时访问 URL：`--audio-url`
+   - 兼容快捷方式：`--file-transfer` 会在声音克隆命令内部先走 YuanFlow 文件中转，再把临时访问链接作为 `audio_url` 提交。
+   - 只有用户明确要求直接传本地文件时，才使用 multipart：`--file`
 4. 创建成功后，保存返回的 `voice_xxx`。这是后续声音复刻必须使用的音色 ID。
 
 不要在回复、日志或文件中暴露 token。用户主流程统一称为 YuanFlow API 和 YuanFlow 文件中转，不要求用户配置第三方平台 Key。
 
 ## 创建声音克隆
 
-推荐本地文件使用 YuanFlow 文件中转：
+本地文件优先先使用 `YuanFlow文件中转工具` 获取临时 URL，再创建声音克隆：
 
 ```powershell
-yuanflow-cli voice clone --file-transfer "<本地声音样本路径>" --name "我的声音" --activate --format agent-json
+yuanflow-cli oss temp-upload --file "<本地声音样本路径>" --content-type audio/wav --format agent-json
 ```
 
-如果用户明确希望直接提交本地音频：
+从返回结果中读取临时访问链接：
+
+```text
+data.response.data.signed_url
+```
+
+再把临时访问链接作为 `audio_url` 提交：
 
 ```powershell
-yuanflow-cli voice clone --file "<本地声音样本路径>" --name "我的声音" --activate --format agent-json
+yuanflow-cli voice clone --audio-url "<临时访问URL>" --name "我的声音" --language-hints zh --activate --format agent-json
+```
+
+如果当前执行环境需要一步完成，也可以使用兼容快捷方式：
+
+```powershell
+yuanflow-cli voice clone --file-transfer "<本地声音样本路径>" --name "我的声音" --language-hints zh --activate --format agent-json
+```
+
+如果用户明确希望直接提交本地音频，使用 multipart：
+
+```powershell
+yuanflow-cli voice clone --file "<本地声音样本路径>" --name "我的声音" --language-hints zh --activate --format agent-json
 ```
 
 如果已经有可访问音频 URL：
 
 ```powershell
-yuanflow-cli voice clone --audio-url "https://example.com/sample.wav" --name "我的声音" --activate --format agent-json
+yuanflow-cli voice clone --audio-url "https://example.com/sample.wav" --name "我的声音" --language-hints zh --activate --format agent-json
 ```
 
+默认创建模型为 `voice-enrollment`，默认绑定后续合成模型 `cosyvoice-v3-flash`。除非用户明确要求其它 YuanFlow API 对外模型参数，一般不要改 `--target-model`。
+
 返回里重点读取：
 
 ```text
@@ -83,6 +104,7 @@ yuanflow-cli voice activate --voice voice_xxx --format agent-json
 - 优先使用清晰、无背景音乐、无明显混响的人声音频。
 - 建议使用 wav、mp3、m4a、flac 等常见格式。
 - 文件过大、噪音明显或多人混说时，先让用户换音频或裁剪。
+- 样本语言建议用 `--language-hints zh` 这类提示传入；多语种用逗号分隔。
 - 不要上传身份证、合同、私密通话、未授权人物声音等敏感内容，除非用户明确确认且任务确实需要。
 
 ## YuanFlow-main 内置环境
@@ -91,15 +113,35 @@ yuanflow-cli voice activate --voice voice_xxx --format agent-json
 
 创建声音克隆：
 
+```json
+{
+  "args": [
+    "oss",
+    "temp-upload",
+    "--file",
+    "<本地声音样本路径>",
+    "--content-type",
+    "audio/wav",
+    "--format",
+    "agent-json"
+  ],
+  "timeout": 300
+}
+```
+
+拿到 `data.response.data.signed_url` 后，再提交声音克隆：
+
 ```json
 {
   "args": [
     "voice",
     "clone",
-    "--file-transfer",
-    "<本地声音样本路径>",
+    "--audio-url",
+    "<临时访问URL>",
     "--name",
     "我的声音",
+    "--language-hints",
+    "zh",
     "--activate",
     "--format",
     "agent-json"
@@ -143,4 +185,4 @@ yuanflow-cli voice activate --voice voice_xxx --format agent-json
 - token 缺失：说明需要配置 YuanFlow API token，或在 YuanFlow-main 受控环境中运行。
 - 没有返回 `voice_xxx`：说明声音克隆未完成，不要继续声音复刻。
 - 已存在克隆限制：先用 `voice list` 查询已有音色，必要时让用户选择已有 `voice_xxx` 继续。
-- 音频不可访问：如果使用 URL，让用户换成可访问链接；如果是本地文件，改用 `--file-transfer`。
+- 音频不可访问：如果使用 URL，让用户换成可访问链接；如果是本地文件，优先调用 `YuanFlow文件中转工具` 获取新的临时 URL，再用 `--audio-url` 重试。

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

@@ -14,6 +14,8 @@ emoji: 🔊
 
 如果没有声音克隆 ID，先调用 `声音克隆`，不要直接复刻。
 
+当前声音复刻使用 YuanFlow API 对外模型参数 `cosyvoice-v3-flash`。Agent 日常优先使用聚合命令 `yuanflow-cli voice replicate`，不要在公共流程里要求用户理解底层接口细节。
+
 ## 外部 CLI 主流程
 
 外部 Agent 或用户直接使用时，优先使用 `yuanflow-cli voice replicate`。
@@ -22,6 +24,7 @@ emoji: 🔊
 2. 外部 CLI 使用 `YUANCHUANG_API_TOKEN` 或 `yuanflow-cli config set-token <你的令牌>` 完成鉴权。
 3. 确认 `--voice` 是 `voice_xxx` 或 `default`。
 4. 用 `--output` 指定音频保存路径。
+5. 如果链路里需要上传本地参考音频，不要直接交给复刻命令；先调用 `YuanFlow文件中转工具` 的 `oss temp-upload` 获取临时 URL，再转到 `声音克隆` 使用 `--audio-url` 创建或确认 `voice_xxx`。
 
 不要在回复、日志或文件中暴露 token。用户主流程统一称为 YuanFlow API，不要求用户配置第三方平台 Key。
 
@@ -35,6 +38,28 @@ yuanflow-cli voice list --format agent-json
 
 如果列表中没有可用音色，转到 `声音克隆` Skill，先创建声音克隆。
 
+## 本地文件处理
+
+`voice replicate` 只接收文本和已有音色 ID，不接收本地参考音频。遇到本地音频文件时，优先按下面链路处理：
+
+```powershell
+yuanflow-cli oss temp-upload --file "<本地声音样本路径>" --content-type audio/wav --format agent-json
+```
+
+从返回结果读取临时访问链接：
+
+```text
+data.response.data.signed_url
+```
+
+再调用 `声音克隆` 创建或确认音色：
+
+```powershell
+yuanflow-cli voice clone --audio-url "<临时访问URL>" --name "我的声音" --language-hints zh --activate --format agent-json
+```
+
+拿到 `voice_xxx` 后，再执行下面的声音复刻。
+
 ## 生成复刻音频
 
 ```powershell
@@ -53,6 +78,18 @@ yuanflow-cli voice replicate --text "你好，这是声音复刻测试。" --voi
 yuanflow-cli voice replicate --text "测试内容" --voice voice_xxx --response-format wav --output "<输出音频路径>" --format agent-json
 ```
 
+常用控制参数：
+
+- `--instructions`：语气、情绪、角色等朗读要求。
+- `--sample-rate`：采样率，默认按 YuanFlow API 处理，常用 `24000`。
+- `--rate`：语速。
+- `--volume`：音量。
+- `--pitch`：音调。
+- `--language`：目标合成语言，例如 `zh`。
+- `--language-hints`：目标合成语言提示，例如 `zh`。
+- `--enable-ssml`：需要 SSML 时开启。
+- `--word-timestamp-enabled`：需要字级时间戳时开启。
+
 ## 输出要求
 
 最终回复给用户时说明：
@@ -84,6 +121,8 @@ data.response.content_type
     "你好，这是声音复刻测试。",
     "--voice",
     "voice_xxx",
+    "--language",
+    "zh",
     "--output",
     "replicate.mp3",
     "--format",

package/skills/yuanflow-skill//350/247/206/351/242/221/346/213/206/350/247/243/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: 视频拆解
-description: 当用户提交对标视频、本地视频、视频 URL，要求做自媒体创作方向的视频拆解、爆款结构分析、内容复盘、脚本拆解、镜头节奏拆解、账号/竞品内容学习时使用。开始前必须先使用“自媒体知识库”查询与对标拆解相关的规则，再通过 yuanflow-cli 的 qwen3-vl-plus 上传/理解视频，并把知识库规则放入提示词中指导拆解。
+description: 当用户提交对标视频、本地视频、视频 URL，要求做自媒体创作方向的视频拆解、爆款结构分析、内容复盘、脚本拆解、镜头节奏拆解、视频风格解析、账号/竞品内容学习时使用。开始前必须先查自媒体知识库；平台 URL 还要尽量获取作品详情和视频文件，再用 qwen3-vl-plus 规则化拆解。
 emoji: 🎬
 ---
 
@@ -11,19 +11,20 @@ emoji: 🎬
 核心链路：
 
 1. 先查 `自媒体知识库`，获取与“对标拆解、视频拆解、内容创作、脚本结构、镜头节奏、爆款复盘”相关的规则摘要。
-2. 如果用户给的是视频 URL，先用相关工具解析并保存到本地。
-3. 使用 `yuanflow-cli ai qwen3-vl-plus --video-file` 提交本地视频。
-4. 把知识库拆解规则写进 prompt，让模型按规则拆解视频。
-5. 整理成适合自媒体创作复用的详细拆解报告。
+2. 如果用户给的是平台视频 URL，先获取作品详情，尽量拿到标题、文案、封面、作者、发布时间、点赞/评论/转发/收藏等互动数据。
+3. 如果需要分析视频画面，再用下载/播放相关工具解析并保存到本地。
+4. 使用 `yuanflow-cli ai qwen3-vl-plus --video-file` 提交本地视频。
+5. 把知识库规则、作品详情摘要和用户目标写进 prompt，让模型按规则拆解视频。
+6. 合并“平台元数据 + 视觉理解结果 + 知识库规则”，整理成适合自媒体创作复用的详细拆解报告。
 
 ## 外部 CLI 主流程
 
-外部 Agent 或用户直接使用时，先用 `yuanflow-cli knowledge ...` 查询拆解规则，再用 `yuanflow-cli ai qwen3-vl-plus` 处理视频。
+外部 Agent 或用户直接使用时，先用 `yuanflow-cli knowledge ...` 查询拆解规则；如果输入是平台作品 URL，再用 `yuanflow-cli works detail` 获取作品详情，用 `yuanflow-cli works download` 获取可播放/下载地址；最后用 `yuanflow-cli ai qwen3-vl-plus` 处理本地视频。
 
 1. 先确认本机可执行 `yuanflow-cli --help`。
 2. 外部 CLI 使用 `YUANCHUANG_API_TOKEN` 或 `yuanflow-cli config set-token <你的令牌>` 完成鉴权。
 3. 本地视频会先经过 YuanFlow 文件中转，再提交给 YuanFlow API。
-4. 如果是平台视频 URL，先解析并在用户授权后保存到本地文件。
+4. 如果是平台视频 URL，先获取作品详情；需要画面拆解时，再解析并在用户授权后保存到本地文件。
 
 本地视频上传依赖 qwen3-vl-plus 的 YuanFlow 文件中转能力。外部 Agent 只需要配置 YuanFlow API token；不要要求用户提供第三方平台 Key。
 
@@ -74,7 +75,42 @@ YuanFlow-main 内置环境调用见后文专属小节。
 - 账号定位
 - 带货/转化结构
 
-### 3. 视频 URL 先解析并保存本地
+### 3. 平台视频 URL 先获取作品详情
+
+如果用户提交的是平台视频 URL，先用 `作品详情获取工具` 或 `yuanflow-cli works detail` 获取平台元数据。它负责标题、文案/描述、封面、作者、发布时间、互动统计和媒体信息；这些内容不要让视觉模型凭画面猜。
+
+先按链接判断平台：
+
+- `douyin.com`、`v.douyin.com`：`--platform douyin`。
+- `xiaohongshu.com`、`xhslink.com`：`--platform xiaohongshu`，如详情接口要求 `xsec_token`，按返回或用户提供信息补充 `--xsec-token`。
+- `bilibili.com`、`b23.tv`、`BV`：`--platform bilibili`。
+- `youtube.com`、`youtu.be`：`--platform youtube`。
+- `tiktok.com`、`vm.tiktok.com`：`--platform tiktok`。
+- `kuaishou.com`：`--platform kuaishou`。
+- `xigua.com`：`--platform xigua`。
+
+外部 CLI 示例：
+
+```powershell
+yuanflow-cli works detail --platform douyin --target "https://v.douyin.com/xxx/" --format agent-json
+```
+
+拿到详情后，先提炼成“作品详情摘要”，供后续 prompt 使用：
+
+```text
+【作品详情摘要】
+- 标题：
+- 文案/描述：
+- 作者：
+- 发布时间：
+- 封面：
+- 点赞/评论/转发/收藏/播放：
+- 其它可确认媒体信息：
+```
+
+如果详情接口没有返回某些字段，最终报告里写“未返回/未确认”，不要编造。
+
+### 4. 视频 URL 再解析并保存本地
 
 如果用户提交的是平台视频 URL，先用 `作品下载综合工具` 或 `yuanflow-cli works download` 解析可播放/下载地址候选。
 
@@ -85,6 +121,8 @@ YuanFlow-main 内置环境调用见后文专属小节。
 - `youtube.com`、`youtu.be`：`--platform youtube`。
 - `ixigua.com`：`--platform xigua`。
 
+注意：`works detail` 支持的平台更多，`works download` 当前只覆盖可播放/下载地址已接入的平台。详情能拿到不代表一定能直接下载视频；下载失败时，让用户提供本地视频或可直接访问的视频文件。
+
 外部 CLI 示例：
 
 ```powershell
@@ -121,21 +159,66 @@ ffmpeg -y -i "<解析得到的 m3u8 地址>" -c copy "<视频拆解工作目录>
 
 如果平台解析只返回播放候选而没有稳定下载 URL，说明当前链接需要用户提供可下载文件，或先让用户使用其它授权方式保存视频。
 
-### 4. 调用 qwen3-vl-plus 做规则化拆解
+### 5. 调用 qwen3-vl-plus 做规则化拆解
 
-把知识库查询到的规则摘要压缩进 prompt。不要只让模型“分析视频”，必须告诉它按规则拆解。
+把知识库查询到的规则摘要、作品详情摘要和用户目标压缩进 prompt。不要只让模型“分析视频”，必须告诉它按规则拆解，也要明确哪些字段来自平台详情、哪些内容来自视频画面理解。
 
 外部 CLI 示例：
 
 ```powershell
-yuanflow-cli ai qwen3-vl-plus --prompt "你是自媒体视频拆解助手。请按知识库规则拆解这个视频：..." --video-file "<本地视频路径>" --format agent-json
+yuanflow-cli ai qwen3-vl-plus --prompt "你是自媒体视频拆解助手。请按知识库规则和作品详情摘要拆解这个视频：..." --video-file "<本地视频路径>" --format agent-json
 ```
 
 ## YuanFlow-main 内置环境
 
 在 YuanFlow-main 内置环境，优先调用受控工具 `yuanflow_cli_call`。token、受管包路径和输出目录由 YuanFlow-main 管理，不要要求用户手动提供 YuanFlow token。
 
-YuanFlow-main 内置工具示例：
+内置环境应按阶段调用：
+
+1. `knowledge entry/packs/rules`：查询拆解规则。
+2. `works detail`：平台 URL 获取标题、文案、封面和互动数据。
+3. `works download`：需要画面拆解时获取可播放/下载地址并保存本地。
+4. `ai qwen3-vl-plus`：提交本地视频做视觉与风格拆解。
+
+YuanFlow-main 作品详情调用示例：
+
+```json
+{
+  "args": [
+    "works",
+    "detail",
+    "--platform",
+    "douyin",
+    "--target",
+    "https://v.douyin.com/xxx/",
+    "--format",
+    "agent-json"
+  ],
+  "timeout": 180
+}
+```
+
+YuanFlow-main 下载/播放地址调用示例：
+
+```json
+{
+  "args": [
+    "works",
+    "download",
+    "--platform",
+    "douyin",
+    "--target",
+    "https://v.douyin.com/xxx/",
+    "--region",
+    "CN",
+    "--format",
+    "agent-json"
+  ],
+  "timeout": 300
+}
+```
+
+YuanFlow-main 视频拆解调用示例：
 
 ```json
 {
@@ -143,7 +226,7 @@ YuanFlow-main 内置工具示例：
     "ai",
     "qwen3-vl-plus",
     "--prompt",
-    "你是自媒体视频拆解助手。请严格按以下知识库规则拆解这个对标视频：\\n【知识库规则摘要】...\\n【用户目标】学习该视频的选题、开头、脚本结构、镜头节奏和可复用创作方法。\\n请输出：1. 一句话总结；2. 视频定位；3. 开头钩子；4. 内容结构；5. 镜头/画面节奏；6. 情绪和转化设计；7. 可复用模板；8. 不建议照搬的风险。",
+    "你是自媒体视频拆解助手。请严格按以下知识库规则和作品详情摘要拆解这个对标视频：\\n【知识库规则摘要】...\\n【作品详情摘要】标题、文案、封面、作者、发布时间、互动数据...\\n【用户目标】学习该视频的选题、开头、脚本结构、镜头节奏、视频风格和可复用创作方法。\\n请区分平台详情可确认字段和视频画面分析结论，不要编造未返回的数据。",
     "--video-file",
     "<本地视频路径>",
     "--format",
@@ -169,43 +252,71 @@ YuanFlow-main 内置工具示例：
 
 ## 1. 一句话结论
 
-## 2. 视频基础判断
+## 2. 视频基础信息与数据表现
+- 标题：
+- 文案/描述：
+- 作者/账号：
+- 发布时间：
+- 封面：
+- 点赞/评论/转发/收藏/播放：
+- 数据初步判断：
+- 未返回或不确定字段：
+
+## 3. 视频基础判断
 - 内容类型：
 - 目标受众：
 - 核心卖点/观点：
 - 适用平台：
 
-## 3. 开头钩子拆解
+## 4. 封面、标题与文案拆解
+- 封面吸引点：
+- 标题钩子：
+- 文案结构：
+- 标题/文案/封面的匹配度：
+
+## 5. 开头钩子拆解
 - 前 3 秒：
 - 冲突/利益点：
 - 留人方式：
 
-## 4. 内容结构拆解
+## 6. 内容结构拆解
 - 段落 1：
 - 段落 2：
 - 段落 3：
 - 结尾：
 
-## 5. 画面与镜头节奏
+## 7. 画面与镜头节奏
 - 场景变化：
 - 人物/产品/字幕：
 - 节奏特点：
 
-## 6. 情绪、信任和转化设计
+## 8. 视频风格解析拆解
+- 整体风格标签：
+- 镜头语言：
+- 剪辑节奏：
+- 字幕与包装：
+- 音乐/音效：
+- 叙事语气：
+- 人设或账号气质：
+- 平台适配特点：
+- 可复用风格公式：
+
+## 9. 情绪、信任和转化设计
 
-## 7. 可复用创作模板
+## 10. 可复用创作模板
 
-## 8. 可借鉴点与风险
+## 11. 可借鉴点与风险
 - 可借鉴：
 - 不建议照搬：
 - 需要二次原创：
 
-## 9. 给用户的下一步建议
+## 12. 给用户的下一步建议
 ```
 
 ## 失败处理
 
 - 知识库查询失败：说明无法取得拆解规则，不要跳过规则直接当普通视觉理解；可询问用户是否改为通用视觉理解。
+- 作品详情获取失败：说明无法补齐标题、文案、封面和互动数据；可继续做视频画面拆解，但最终报告必须标注平台元数据缺失。
 - 视频 URL 解析失败：说明需要用户提供本地视频或可直接访问的下载链接。
 - YuanFlow token 缺失：说明需要在受管环境或 CLI 配置 YuanFlow API token，不要让用户在聊天里粘贴敏感 Key。
 - 视频超限：提示最大 2GB、2 秒到 1 小时，让用户裁剪或压缩。

package/src/agent-protocol.js

@@ -25,7 +25,8 @@ const ERROR_MAP = [
         message.includes('未知平台') ||
         message.includes('未找到命令') ||
         message.includes('未知命令') ||
-        message.includes('不支持'),
+        message.includes('不支持') ||
+        message.includes('已有未归档音色'),
   },
   {
     code: 'AUTH_INVALID',
@@ -78,7 +79,7 @@ export function createAgentSuccess(command, data, meta = {}) {
 }
 
 export function createAgentError(command, error) {
-  const message = error?.message || String(error);
+  const message = sanitizeErrorMessage(error?.message || String(error));
   const mapped = mapError(message);
   return {
     payload: {
@@ -97,6 +98,18 @@ export function createAgentError(command, error) {
   };
 }
 
+function sanitizeErrorMessage(message) {
+  const text = String(message || '');
+  if (text.includes('one username can only have one voice id')) {
+    return '请求失败：HTTP 409 当前用户已有未归档音色。请先使用 voice list 查询已有 voice_xxx，或使用已有音色复刻。';
+  }
+  const internalErrorType = ['new', 'api', 'error'].join('_');
+  const internalProductName = ['New', 'Api'].join('');
+  return text
+    .replace(new RegExp(internalErrorType, 'gi'), 'platform_service_error')
+    .replace(new RegExp(internalProductName, 'g'), 'YuanFlow API');
+}
+
 export function getCommandName(platform, command) {
   return [platform, command].filter(Boolean).join(' ') || 'unknown';
 }

package/src/ai-tools.js

@@ -11,8 +11,8 @@ 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_VOICE_ENROLLMENT = 'voice-enrollment';
+const MODEL_COSYVOICE_FLASH = 'cosyvoice-v3-flash';
 const MODEL_FUN_ASR = 'fun-asr';
 const MODEL_DOUBAO_TTS = 'doubao-tts';
 
@@ -41,34 +41,36 @@ export function listAiCommands() {
       returns: '返回 OpenAI chat.completion 兼容 JSON。',
     }),
     aiCommand({
-      key: 'ai.qwen-voice-enrollment',
-      command: 'ai qwen-voice-enrollment',
-      description: '调用 YuanFlow API 对外模型 qwen-voice-enrollment，创建音色复刻记录。',
+      key: 'ai.voice-enrollment',
+      command: 'ai voice-enrollment',
+      description: '调用 YuanFlow API 对外模型 voice-enrollment，创建音色复刻记录。',
       apiPath: AUDIO_VOICES_PATH,
       options: [
-        option('--file', 'file', false, '本地音频文件；与 --audio-url 二选一。'),
+        option('--file', 'file', false, '本地音频文件；通过 multipart 直接提交给 YuanFlow API，与 --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('--target-model', 'targetModel', false, `后续合成模型，默认 ${MODEL_COSYVOICE_FLASH}。`),
+        option('--language-hints', 'languageHints', false, '逗号分隔的样本音频语种提示，例如 zh。'),
+        option('--language', 'language', false, '兼容别名；会映射为 language_hints。'),
         option('--activate', 'activate', false, '创建后设为当前默认音色。'),
         ...commonOptions(),
       ],
       requestBody: {
-        model: MODEL_QWEN_VOICE,
-        audio: '<本地文件 data URI 或 audio_url>',
+        model: MODEL_VOICE_ENROLLMENT,
+        target_model: MODEL_COSYVOICE_FLASH,
+        file: '<multipart 本地音频，或通过 audio_url 传入公网音频 URL>',
       },
-      returns: '返回 voice_xxx 音色对象；后续 qwen3-tts-vc-realtime-2026-01-15 可用 --voice voice_xxx 调用。',
+      returns: '返回 voice_xxx 音色对象；后续 cosyvoice-v3-flash 可用 --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 合成音频。',
+      key: 'ai.cosyvoice-v3-flash',
+      command: 'ai cosyvoice-v3-flash',
+      description: '调用 YuanFlow API 对外模型 cosyvoice-v3-flash，使用 voice_xxx 或 default 合成音频。',
       apiPath: AUDIO_SPEECH_PATH,
       options: speechOptions('音色 ID：voice_xxx 或 default。', false),
       requestBody: {
-        model: MODEL_QWEN_TTS_VC,
+        model: MODEL_COSYVOICE_FLASH,
         input: '<text>',
         voice: '<voice_xxx|default>',
       },
@@ -166,10 +168,10 @@ export async function runAiCommand({ action = 'help', rest = [], options }) {
       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_VOICE_ENROLLMENT:
+      return callVoiceEnrollment(options);
+    case MODEL_COSYVOICE_FLASH:
+      return callSpeech(MODEL_COSYVOICE_FLASH, options, false);
     case MODEL_FUN_ASR:
       return callFunASR(options);
     case MODEL_DOUBAO_TTS:
@@ -308,21 +310,38 @@ async function buildVoiceEnrollmentBody(options) {
     throw new Error('--file 和 --audio-url 不能同时使用。');
   }
   const body = {
-    model: MODEL_QWEN_VOICE,
+    model: MODEL_VOICE_ENROLLMENT,
+    target_model: cleanOptional(options.named?.['target-model']) || MODEL_COSYVOICE_FLASH,
     ...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),
   };
+  const languageHints = splitList(options.named?.['language-hints'] || options.named?.language);
+  if (languageHints.length > 0) {
+    body.language_hints = languageHints;
+  }
   if (audioUrl) {
     body.audio_url = audioUrl;
   } else {
-    body.audio = options.dryRun ? '<data URI omitted in dry-run>' : await fileToDataUri(filePath);
+    body.file = '<file omitted>';
   }
   return body;
 }
 
+async function callVoiceEnrollment(options) {
+  const body = await buildVoiceEnrollmentBody(options);
+  const filePath = cleanOptional(options.file);
+  const audioUrl = cleanOptional(options.named?.['audio-url']);
+  if (filePath && !audioUrl && !options.json) {
+    const response = await callMultipartJson(AUDIO_VOICES_PATH, options, {
+      ...body,
+      filePath,
+    });
+    return result(MODEL_VOICE_ENROLLMENT, AUDIO_VOICES_PATH, body, response);
+  }
+  return callJson(AUDIO_VOICES_PATH, options, body);
+}
+
 async function callSpeech(model, options, requiresVoice) {
   const body = buildSpeechBody(model, options, requiresVoice);
   const response = await callBinary(AUDIO_SPEECH_PATH, options, body);
@@ -352,10 +371,18 @@ function buildSpeechBody(model, options, requiresVoice) {
   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, 'rate', options.named?.rate || options.named?.speed);
+  addNumber(metadata, 'pitch', options.named?.pitch || options.named?.['pitch-rate']);
   addNumber(metadata, 'bit_rate', options.named?.['bit-rate']);
   addString(metadata, 'mode', options.named?.mode);
   addString(metadata, 'language', options.named?.language);
+  addNumber(metadata, 'seed', options.named?.seed);
+  addBoolean(metadata, 'enable_ssml', options.named?.['enable-ssml']);
+  addBoolean(metadata, 'word_timestamp_enabled', options.named?.['word-timestamp-enabled']);
+  const hints = splitList(options.named?.['language-hints']);
+  if (hints.length > 0) {
+    metadata.language_hints = hints;
+  }
   if (Object.keys(metadata).length > 0) {
     body.metadata = metadata;
   }
@@ -489,19 +516,25 @@ async function callGetJson(apiPath, options) {
 }
 
 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>',
-  });
+  const requestBody = { ...payload, file: '<file omitted>' };
+  delete requestBody.filePath;
+  const request = await buildRequest(apiPath, options, 'POST', requestBody);
   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 || {}));
+  for (const [key, value] of Object.entries(payload || {})) {
+    if (key === 'filePath' || key === 'file' || value === undefined || value === null) {
+      continue;
+    }
+    if (Array.isArray(value)) {
+      form.set(key, value.join(','));
+    } else if (typeof value === 'object') {
+      form.set(key, JSON.stringify(value));
+    } else {
+      form.set(key, String(value));
+    }
+  }
   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, {
@@ -617,8 +650,16 @@ function speechOptions(voiceLabel, voiceRequired) {
     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('--rate', 'rate', false, '语速控制，会写入 metadata.rate。'),
+    option('--speed', 'speed', false, '兼容别名；会写入 metadata.rate。'),
+    option('--volume', 'volume', false, '音量控制，会写入 metadata.volume。'),
+    option('--pitch', 'pitch', false, '音调控制，会写入 metadata.pitch。'),
     option('--sample-rate', 'sampleRate', false, '采样率。'),
+    option('--language', 'language', false, '目标合成语言，例如 zh。'),
+    option('--language-hints', 'languageHints', false, '逗号分隔的目标合成语种提示，例如 zh。'),
+    option('--enable-ssml', 'enableSsml', false, '是否开启 SSML。'),
+    option('--word-timestamp-enabled', 'wordTimestampEnabled', false, '是否开启字级时间戳。'),
+    option('--seed', 'seed', false, '随机种子。'),
     option('--metadata', 'metadata', false, '透传给 YuanFlow API 的 metadata JSON。'),
     ...commonOptions(),
   ];
@@ -638,11 +679,6 @@ 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':

package/src/cli.js

@@ -629,19 +629,19 @@ function printHelp() {
   yuanflow-cli browser task-plan --platform xiaohongshu --task publish --account main --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 voice clone --file-transfer "D:\\voice\\sample.wav" --name demo --activate --dry-run
+  yuanflow-cli ai qwen3-vl-plus --prompt "描述本地图片" --image-file "<本地图片路径>" --dry-run
+  yuanflow-cli ai qwen3-vl-plus --prompt "描述本地视频" --video-file "<本地视频路径>" --dry-run
+  yuanflow-cli voice clone --file-transfer "<本地音频路径>" --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 voice replicate --text "你好" --voice voice_xxx --output "<输出音频路径>" --dry-run
+  yuanflow-cli ai voice-enrollment --file "<本地音频路径>" --name demo --activate --dry-run
+  yuanflow-cli ai cosyvoice-v3-flash --text "你好" --voice voice_xxx --output "<输出音频路径>" --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 ai doubao-tts voice-download --voice zh_female_xiaohe_uranus_bigtts --output "<输出音频路径>" --dry-run
+  yuanflow-cli ai doubao-tts --text "你好" --voice zh_female_xiaohe_uranus_bigtts --output "<输出音频路径>" --dry-run
   yuanflow-cli list douyin
 
 说明：
@@ -650,7 +650,7 @@ function printHelp() {
   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/任务路径与执行计划，不用于普通网页搜索。
-  视频智能剪辑和视频制作执行链已迁移到独立项目 D:\\AI_project\\视频制作，不再由 yuanflow-cli video 命令提供；视频拆解仍由 yuanflow-skill 的“视频拆解”提供。
+  视频智能剪辑和视频制作执行链已迁移到独立项目，不再由 yuanflow-cli video 命令提供；视频拆解仍由 yuanflow-skill 的“视频拆解”提供。
   需要鉴权的请求都会使用 Authorization: Bearer <token>。
   token 优先级：--token > YUANCHUANG_API_TOKEN > 本地 config.token。
   YuanFlow-main 内置环境使用时，token 由 YuanFlow-main 内置环境注入，不需要手动配置。

package/src/voice-tools.js

@@ -7,8 +7,8 @@ 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';
+const MODEL_VOICE_CLONE = 'voice-enrollment';
+const MODEL_VOICE_REPLICATE = 'cosyvoice-v3-flash';
 
 export function listVoiceCommands() {
   return [
@@ -19,19 +19,21 @@ export function listVoiceCommands() {
       method: 'POST',
       apiPath: AUDIO_VOICES_PATH,
       options: [
-        option('--file', 'file', false, '本地音频文件；与 --file-transfer、--audio-url 三选一。'),
+        option('--file', 'file', false, '本地音频文件；通过 multipart 直接提交给 YuanFlow API，与 --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('--target-model', 'targetModel', false, `后续合成模型，默认 ${MODEL_VOICE_REPLICATE}。`),
+        option('--language-hints', 'languageHints', false, '逗号分隔的样本音频语种提示，例如 zh。'),
+        option('--language', 'language', false, '兼容别名；会映射为 language_hints。'),
         option('--activate', 'activate', false, '创建后设为当前默认音色。'),
         ...commonOptions(),
       ],
       requestBody: {
         model: MODEL_VOICE_CLONE,
-        audio: '<本地音频 data URI，或通过 audio_url 传入 YuanFlow 文件中转 URL>',
+        target_model: MODEL_VOICE_REPLICATE,
+        file: '<multipart 本地音频，或通过 audio_url 传入公网音频 URL>',
       },
       returns: '返回 voice_xxx 音色对象；后续 voice replicate 可通过 --voice voice_xxx 复刻声音。',
     }),
@@ -69,8 +71,16 @@ export function listVoiceCommands() {
         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('--rate', 'rate', false, '语速控制，会写入 metadata.rate。'),
+        option('--speed', 'speed', false, '兼容别名；会写入 metadata.rate。'),
+        option('--volume', 'volume', false, '音量控制，会写入 metadata.volume。'),
+        option('--pitch', 'pitch', false, '音调控制，会写入 metadata.pitch。'),
         option('--sample-rate', 'sampleRate', false, '采样率。'),
+        option('--language', 'language', false, '目标合成语言，例如 zh。'),
+        option('--language-hints', 'languageHints', false, '逗号分隔的目标合成语种提示，例如 zh。'),
+        option('--enable-ssml', 'enableSsml', false, '是否开启 SSML。'),
+        option('--word-timestamp-enabled', 'wordTimestampEnabled', false, '是否开启字级时间戳。'),
+        option('--seed', 'seed', false, '随机种子。'),
         option('--metadata', 'metadata', false, '透传给 YuanFlow API 的 metadata JSON。'),
         ...commonOptions(),
       ],
@@ -112,8 +122,10 @@ export async function runVoiceCommand({ action = 'help', options }) {
 }
 
 async function cloneVoice(options) {
-  const body = await buildVoiceCloneBody(options);
-  const response = await callJson(AUDIO_VOICES_PATH, options, body);
+  const { body, filePath } = await buildVoiceClonePayload(options);
+  const response = filePath
+    ? await callMultipartJson(AUDIO_VOICES_PATH, options, body, filePath)
+    : await callJson(AUDIO_VOICES_PATH, options, body);
   return result('voice clone', AUDIO_VOICES_PATH, body, response, { kind: 'voice-clone' });
 }
 
@@ -138,9 +150,9 @@ async function replicateVoice(options) {
   return result('voice replicate', AUDIO_SPEECH_PATH, body, response, { kind: 'voice-replicate' });
 }
 
-async function buildVoiceCloneBody(options) {
+async function buildVoiceClonePayload(options) {
   if (options.json) {
-    return JSON.parse(options.json);
+    return { body: JSON.parse(options.json) };
   }
   const filePath = cleanOptional(options.file);
   const fileTransferPath = cleanOptional(options.named?.['file-transfer']);
@@ -155,20 +167,24 @@ async function buildVoiceCloneBody(options) {
 
   const body = {
     model: MODEL_VOICE_CLONE,
+    target_model: cleanOptional(options.named?.['target-model']) || MODEL_VOICE_REPLICATE,
     ...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),
   };
+  const languageHints = splitList(options.named?.['language-hints'] || options.named?.language);
+  if (languageHints.length > 0) {
+    body.language_hints = languageHints;
+  }
   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);
+    body.file = '<file omitted>';
+    return { body, filePath };
   }
-  return body;
+  return { body };
 }
 
 function buildVoiceReplicateBody(options) {
@@ -187,9 +203,19 @@ function buildVoiceReplicateBody(options) {
     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, 'rate', options.named?.rate || options.named?.speed);
+  addNumber(metadata, 'pitch', options.named?.pitch);
+  addString(metadata, 'language', options.named?.language);
+  addNumber(metadata, 'seed', options.named?.seed);
+  addBoolean(metadata, 'enable_ssml', options.named?.['enable-ssml']);
+  addBoolean(metadata, 'word_timestamp_enabled', options.named?.['word-timestamp-enabled']);
+  const hints = splitList(options.named?.['language-hints']);
+  if (hints.length > 0) {
+    metadata.language_hints = hints;
+  }
   if (Object.keys(metadata).length > 0) {
     body.metadata = metadata;
   }
@@ -236,6 +262,28 @@ async function callJson(apiPath, options, body) {
   return readJsonResponse(response);
 }
 
+async function callMultipartJson(apiPath, options, body, filePath) {
+  const request = await buildRequest(apiPath, options, 'POST', body);
+  if (request.dryRun) {
+    return request;
+  }
+  const form = new FormData();
+  for (const [key, value] of Object.entries(body || {})) {
+    if (key === 'file') {
+      continue;
+    }
+    form.set(key, Array.isArray(value) ? value.join(',') : String(value));
+  }
+  const file = new Blob([await readFile(filePath)], { type: inferAudioMimeType(filePath) });
+  form.set('file', file, path.basename(filePath));
+  const response = await fetch(request.url, {
+    method: 'POST',
+    headers: request.headers,
+    body: form,
+  });
+  return readJsonResponse(response);
+}
+
 async function callGetJson(apiPath, options) {
   const request = await buildRequest(apiPath, options, 'GET');
   if (request.dryRun) {
@@ -364,11 +412,6 @@ 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':
@@ -418,6 +461,20 @@ function addNumber(target, name, value) {
   }
 }
 
+function addString(target, name, value) {
+  const cleaned = cleanOptional(value);
+  if (cleaned !== undefined) {
+    target[name] = 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) {
@@ -429,6 +486,20 @@ function parseBoolean(value) {
   return ['1', 'true', 'yes', 'on'].includes(String(cleaned).toLowerCase());
 }
 
+function splitList(value) {
+  const cleaned = cleanOptional(value);
+  if (!cleaned) {
+    return [];
+  }
+  if (Array.isArray(cleaned)) {
+    return cleaned.map((item) => String(item).trim()).filter(Boolean);
+  }
+  return String(cleaned)
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
 function cleanOptional(value) {
   if (value === undefined || value === null) return undefined;
   if (typeof value === 'string') {