yuanflow-cli 0.1.47 → 0.1.49

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.49",
   "description": "YuanFlow 自媒体 API CLI 与 Skill 安装器。",
   "type": "module",
   "license": "MIT",

package/skills/yuanflow-skill/README.md

@@ -8,7 +8,7 @@ YuanFlow Skill 是 `yuanflow-cli` 的 Agent Skill 仓库，用于把社媒平台
 - `yuanflow-cli/`：API CLI 子 Skill，说明 `yuanflow-cli` 的安装、配置、命令发现、schema 查询、dry-run 和 agent-json 调用方式。
 - `自媒体知识库/`：自媒体知识库渐进查询 Skill，走 `yuanflow-cli knowledge`。
 - `视觉理解/`：通用型图片、视频画面理解 Skill，走 `yuanflow-cli ai qwen3-vl-plus`，支持图片/视频 URL 和本地图片/视频上传。
-- `视频拆解/`：自媒体创作场景的对标视频拆解 Skill，先查自媒体知识库对标拆解规则，再用 `qwen3-vl-plus` 上传视频并按规则拆解。
+- `视频拆解/`：自媒体创作场景的对标视频拆解 Skill，先查自媒体知识库对标拆解规则；平台 URL 先获取作品详情和互动数据，需要画面分析时再下载/上传视频并按规则拆解。
 - `YuanFlow文件中转工具/`：YuanFlow 文件中转、签名链接、对象复制 Skill，内部兼容命令走 `yuanflow-cli oss`。
 - `生图技能/`：图片生成与编辑 Skill；外部环境使用 `yuanflow-cli`，YuanFlow-main 内置环境优先走 `yuanflow_image_request`。
 - `视觉卡片生成/`：小红书图文卡片、公众号封面、文章插图、海报、信息图和商业视觉方案卡生成 Skill，使用 HTML 模板、风格参考和质量检查脚本完成交付。
@@ -18,8 +18,9 @@ YuanFlow Skill 是 `yuanflow-cli` 的 Agent Skill 仓库，用于把社媒平台
 - `HTML报告生成/`：单页 HTML 报告生成 Skill，内置 9 种米色留白报告模板。
 - `本地音视频转文字/`：本地 SenseVoice 音视频转文字 Skill，首次明确使用时按需下载模型。
 - `音视频在线转文字/`：通过 YuanFlow 在线 ASR 接口把音频或视频转成干净文本，视频会先抽取音频并通过 YuanFlow 文件中转。
-- `声音克隆/`：通过 `yuanflow-cli voice clone/list/activate` 创建、查询和激活声音克隆音色，返回可复用的 `voice_xxx`。
-- `声音复刻/`：通过 `yuanflow-cli voice replicate` 使用已有 `voice_xxx` 或默认音色把文本合成为复刻音频文件。
+- `语音合成/`：通过 `yuanflow-cli ai doubao-tts` 查询预置音色、下载试听音频，并使用选定 `voice_type` 把文本合成为语音文件。
+- `声音克隆/`：通过 `yuanflow-cli voice clone/list/activate` 创建、查询和激活声音克隆音色；本地参考音频优先先用 YuanFlow 文件中转取得临时 URL，再用 `--audio-url` 创建音色。
+- `声音复刻/`：通过 `yuanflow-cli voice replicate` 使用已有 `voice_xxx` 或默认音色把文本合成为复刻音频文件；如果链路里出现本地参考音频，先转到声音克隆流程处理。
 - `自媒体浏览器自动化/`：自媒体平台专用浏览器自动化 Skill，用于登录态隔离、Cookie/profile 本地保存、页面采集和作品发布流程。
 - `帐号监控/`：帐号搜索、主页资料、主页作品、历史快照、变化对比和 HTML 可视化分流 Skill。
 - `个人创作库/`：长期保存、整理、复盘和复用用户认可的自媒体合格产出物。
@@ -39,7 +40,7 @@ YuanFlow Skill 是 `yuanflow-cli` 的 Agent Skill 仓库，用于把社媒平台
 - 让本地 Agent 稳定调用 `yuanflow-cli` 并解析 JSON 输出。
 - 查询自媒体知识库公开方向、方法包和规则摘要。
 - 对图片、视频、本地媒体文件或媒体 URL 做通用画面理解、内容描述、可见文字识别、画面对比和细节检查。
-- 对自媒体对标视频、爆款视频、竞品视频做内容结构、开头钩子、脚本节奏、镜头节奏和可复用创作方法拆解；开始前先查自媒体知识库规则，视频 URL 先解析并保存本地。
+- 对自媒体对标视频、爆款视频、竞品视频做内容结构、开头钩子、标题文案、封面、互动数据、脚本节奏、镜头节奏、视频风格和可复用创作方法拆解；开始前先查自媒体知识库规则，平台视频 URL 先获取作品详情，需要画面分析时再解析并保存本地。
 - 上传文件到 YuanFlow 文件中转、生成签名链接或复制文件对象。
 - 生成图片、编辑图片，并缓存返回 URL 或 base64 图片。生成图片必填 `prompt`，可选 `size / quality / style / n / response_format`；编辑图片必须通过 multipart 上传本地图片。
 - 生成小红书图文卡片、公众号封面、文章插图、社交媒体配图、海报、信息图和商业视觉方案卡；视觉卡片生成不新增独立 CLI 命令，按 Skill 模板、参考文档和检查脚本完成。
@@ -49,7 +50,8 @@ YuanFlow Skill 是 `yuanflow-cli` 的 Agent Skill 仓库，用于把社媒平台
 - 在用户要求智能剪辑、自动剪辑、主音频匹配 B-roll、重排视频画面或生成剪辑预览时，使用视频智能剪辑 Skill；第一版先查规则库，导入策略快照，用“音视频在线转文字”或 forced alignment 建立音频对齐，抽帧频率固定 1 秒 1 帧，再回写视觉理解结果，最后生成 `timeline_plan` 和 EDL。
 - 在用户明确要求本地转写时，把本地音频或视频转成文字；视频会先抽取音频，模型和缓存由当前运行环境管理，不要求固定安装目录。
 - 在用户要求在线转写、云端转写或 doubao-asr 时，把本地音频或视频经 YuanFlow 文件中转后提交在线 ASR，默认只返回干净文本。
-- 在用户要求创建声音克隆、查询已有克隆音色 ID、激活默认克隆音色或生成声音复刻音频时，使用声音克隆或声音复刻 Skill；声音复刻前必须先拿到 `voice_xxx` 或使用已激活默认音色。
+- 在用户要求文本转语音、生成口播/旁白/TTS 音频，或不确定使用哪个预置音色时，使用语音合成 Skill；先查询音色列表，必要时下载试听音频，再用选定的 `voice_type` 合成。
+- 在用户要求创建声音克隆、查询已有克隆音色 ID、激活默认克隆音色或生成声音复刻音频时，使用声音克隆或声音复刻 Skill；本地参考音频优先先走 YuanFlow 文件中转获取临时 URL，声音复刻前必须先拿到 `voice_xxx` 或使用已激活默认音色。
 - 在用户要求自媒体平台浏览器自动化、账号登录态隔离、Cookie/profile 保存、平台页面采集或作品发布时，使用专用自媒体浏览器自动化 Skill；普通网页浏览和搜索仍使用通用浏览器能力。
 - 监控抖音、小红书、微博、知乎、Bilibili、TikTok、YouTube、Twitter/X 帐号主页，保存快照并对比历史变化；抖音链路优先使用 `get-sec-user-id -> user-profile -> user-posts -> works detail`。
 - 在用户要求保存、归档、复盘或复用已完成创作成果时，把选题、标题、文案、脚本、封面、剪辑思路、发布计划和数据复盘沉淀进个人创作库。
@@ -149,6 +151,8 @@ yuanflow-skill list-skills
 │  └─ scripts/
 ├─ 音视频在线转文字
 │  └─ SKILL.md
+├─ 语音合成
+│  └─ SKILL.md
 ├─ 自媒体浏览器自动化
 │  └─ SKILL.md
 ├─ 个人创作库

package/skills/yuanflow-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: YuanFlow技能总入口
-description: 当用户需要处理自媒体平台接口工作流、平台数据查询、命令发现、生图、视觉卡片生成、YuanFlow 文件中转、知识库查询、HTML 报告生成，或需要在 YuanFlow 子技能之间选择合适能力时使用。
+description: 当用户需要处理自媒体平台接口工作流、平台数据查询、命令发现、生图、语音合成、视觉卡片生成、YuanFlow 文件中转、知识库查询、HTML 报告生成，或需要在 YuanFlow 子技能之间选择合适能力时使用。
 ---
 
 # YuanFlow Skill
@@ -32,6 +32,7 @@ description: 当用户需要处理自媒体平台接口工作流、平台数据
 - `HTML报告生成/`
 - `本地音视频转文字/`
 - `音视频在线转文字/`
+- `语音合成/`
 - `自媒体浏览器自动化/`
 - `帐号监控/`
 - `个人创作库/`
@@ -319,7 +320,21 @@ description: 当用户需要处理自媒体平台接口工作流、平台数据
 
 - `音视频在线转文字`
 
-### 20. 走 `视觉理解`
+### 20. 走 `语音合成`
+
+遇到下面这些需求，优先进入这个子 Skill：
+
+- 用户要求把文本合成为语音、口播音频、旁白音频或 TTS 音频文件。
+- 用户要求查询、筛选或试听预置音色列表里的音色。
+- 用户提供或需要选择 `voice_type`，并要求用该音色合成音频。
+
+这个 Skill 只使用预置音色 ID，不支持自行设计音色或克隆声音。如果用户要克隆本人或指定人物声音，改用 `声音克隆` / `声音复刻`。
+
+子 Skill 名称：
+
+- `语音合成`
+
+### 21. 走 `视觉理解`
 
 遇到下面这些需求，优先进入这个子 Skill：
 
@@ -333,15 +348,16 @@ description: 当用户需要处理自媒体平台接口工作流、平台数据
 
 - `视觉理解`
 
-### 21. 走 `视频拆解`
+### 22. 走 `视频拆解`
 
 遇到下面这些需求，优先进入这个子 Skill：
 
 - 用户提交对标视频、本地视频或视频 URL，要求做自媒体创作方向的视频拆解。
 - 用户要求分析爆款结构、开头钩子、脚本节奏、镜头节奏、转化设计、可复用创作模板。
+- 用户要求补齐视频标题、文案、封面、点赞评论转发收藏等作品详情，或要求视频风格解析拆解。
 - 用户希望从竞品视频、对标账号视频里提炼内容创作方法。
 
-这个 Skill 开始前必须先使用 `自媒体知识库` 查询与对标拆解相关的规则。如果用户提交的是视频 URL，先用作品解析/下载相关工具保存到本地，再通过 `yuanflow-cli ai qwen3-vl-plus --video-file` 上传拆解。
+这个 Skill 开始前必须先使用 `自媒体知识库` 查询与对标拆解相关的规则。如果用户提交的是平台视频 URL，先用 `作品详情获取工具` 补齐平台元数据；需要画面分析时，再用作品解析/下载相关工具保存到本地，并通过 `yuanflow-cli ai qwen3-vl-plus --video-file` 上传拆解。
 
 子 Skill 名称：
 

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//346/234/254/345/234/260/351/237/263/350/247/206/351/242/221/350/275/254/346/226/207/345/255/227/SKILL.md

@@ -60,6 +60,30 @@ emoji: 🎙️
 cd "<当前 Skill 安装目录>\scripts"
 ```
 
+## 使用前配置要求
+
+本 Skill 是本地模型转写，不是云端接口。首次使用会下载 SenseVoiceSmall 和 VAD 模型到本机，后续可离线复用。
+
+最低可用：
+
+- Python 3.10 优先，3.11/3.12 可尝试；不建议 3.13/3.14。
+- 能安装 `torch`、`torchaudio`、`funasr`、`modelscope`。
+- CPU 可运行，但长音频会比较慢。
+- 本地磁盘需预留模型、依赖和缓存空间，建议至少预留数 GB。
+- 如果输入是视频，系统必须可用 `ffmpeg`。
+
+推荐配置：
+
+- NVIDIA GPU + CUDA 环境，显存 8GB 以上更合适。
+- 16GB 以上内存、SSD、稳定网络。
+- 长音频或低配设备建议把 `--batch-size-s` 调小到 `20` 或 `10`。
+
+不适合的情况：
+
+- 设备内存很小、磁盘空间不足、不能安装 Python 依赖。
+- 不能下载模型，又本地没有提前缓存模型。
+- 视频转写但系统没有 `ffmpeg`。
+
 ## 首次使用模型下载规则
 
 开始转写前先检查模型目录是否已经存在：