yuanflow-cli 0.1.40 → 0.1.42

package/README.md

@@ -4,7 +4,7 @@ YuanFlow 的 npm 包，包含两个命令入口：
 
 - `yuanflow-cli`：社媒 API 转 CLI，覆盖完整 registry、快捷命令、schema、dry-run 和 agent-json 输出。
 - `yuanflow-skill`：把 `YuanFlow-skill` 注入到本机支持的 AI Agent skills 目录。
-- `飞书官方技能`：YuanFlow 主程序内通过受控工具托管安装并调用飞书官方 `@larksuite/cli`，npm 包只提供 Skill 说明，不复制官方 CLI 源码。
+- `飞书官方技能`：YuanFlow-main 内置环境通过受控工具托管安装并调用飞书官方 `@larksuite/cli`，npm 包只提供 Skill 说明，不复制官方 CLI 源码。
 
 ## 安装
 
@@ -48,6 +48,14 @@ yuanflow-cli browser task-plan --platform xiaohongshu --task publish --account m
 yuanflow-cli video init --input "D:\素材" --primary-audio "D:\素材\口播.mp3" --broll "D:\素材\画面.mp4" --format agent-json
 yuanflow-cli video strategy --project "D:\素材\yuanflow-video-edit" --template-type talking_head --rules-file "D:\规则\logic.json,D:\规则\template.json,D:\规则\cli.json" --format agent-json
 yuanflow-cli video plan --project "D:\素材\yuanflow-video-edit" --timeline-plan "D:\素材\yuanflow-video-edit\timeline_plan.agent.json" --format agent-json
+yuanflow-cli ai qwen3-vl-plus --prompt "描述这张图" --image-url "https://example.com/image.png" --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 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 fun-asr --audio-url "https://example.com/audio.wav" --response-format verbose_json --format agent-json
 yuanflow-cli list douyin
 ```
 
@@ -57,7 +65,110 @@ yuanflow-cli list douyin
 YUANCHUANG_API_TOKEN=<你的令牌>
 ```
 
-token 优先级：`--token` > `YUANCHUANG_API_TOKEN` > 本地 `config.token`。独立 CLI 用户可以使用环境变量或 `config set-token`；在 YuanFlow 主程序内使用时，token 由主程序认证系统注入，不需要手动配置。
+token 优先级：`--token` > `YUANCHUANG_API_TOKEN` > 本地 `config.token`。独立 CLI 用户可以使用环境变量或 `config set-token`；在 YuanFlow-main 内置环境使用时，token 由 YuanFlow-main 内置环境注入，不需要手动配置。本地图片/视频上传统一使用 YuanFlow 文件中转，不需要用户配置第三方平台 Key。
+
+### AI 模型命令
+
+`ai` 命令用于调用 YuanFlow API 的 OpenAI 兼容端点。CLI 对外只使用 YuanFlow API 模型参数，不暴露底层供应商内部模型名。
+
+```bash
+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 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
+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
+```
+
+#### qwen3-vl-plus 视觉理解
+
+`qwen3-vl-plus` 走 YuanFlow API 对外模型名，不在 CLI 里暴露或改写成底层供应商内部名称。它支持 4 种媒体输入方式，一次快捷调用只选一种：
+
+```bash
+# 图片 URL
+yuanflow-cli ai qwen3-vl-plus --prompt "描述这张图" --image-url "https://example.com/image.png" --format agent-json
+
+# 视频 URL
+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 文件中转，再把临时访问链接传给 YuanFlow API
+yuanflow-cli ai qwen3-vl-plus --prompt "描述本地视频" --video-file "D:\素材\demo.mp4" --format agent-json
+```
+
+本地文件上传要求：
+
+- 只需要 YuanFlow API token；CLI 会调用 `POST /atomic/oss/temp-upload` 完成 YuanFlow 文件中转。
+- 文件上传请求体包含 `filename`、`content_base64`、`content_type` 和可选 `key`，返回里的 `signed_url` 会继续传给 `qwen3-vl-plus`。
+- 该临时访问链接仅用于本次或短期处理，不建议长期保存；后续 skill 应在每次处理本地文件时重新上传。
+- `--dry-run` 不读取、不上传本地文件，只预览最终请求结构。
+
+视频调用注意：
+
+- 视频 URL 需要能被 YuanFlow API 访问，响应头建议包含 `Content-Length` 和 `Content-Type`。
+- 视觉模型侧建议单个视频最大 2GB，时长 2 秒到 1 小时；本地上传会经过 YuanFlow 文件中转，超大视频建议优先使用可公网访问的视频 URL。
+- 图片/视频不要同时传；`--image-url`、`--video-url`、`--image-file`、`--video-file` 四选一。
+
+命令清单：
+
+- `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 可用音色列表。
+- `ai doubao-tts voice`：`GET /api/voice-assets/doubao/voices/{voice_type}`，查询单个音色详情。
+- `ai doubao-tts voice-download`：`GET /api/voice-assets/doubao/voices/{voice_type}/download`，获取试听音频签名地址，传 `--output` 时下载试听音频到本地。
+
+所有 AI 命令都支持 `--dry-run` 预览请求映射，支持 `--format agent-json` 输出稳定 Agent JSON 外壳。音频合成命令真实调用时必须传 `--output` 保存音频文件。
+
+#### doubao-tts 音色查询、试听和合成
+
+`doubao-tts` 的音色资源接口和合成接口要配套使用。音色接口只负责查询和下载试听音频，不参与模型调用计费；真正合成时仍调用 `ai doubao-tts`，并把音色记录里的 `voice_type` 传给 `--voice`。
+
+完整流程：
+
+```bash
+# 1. 查询全部可用音色
+yuanflow-cli ai doubao-tts voices --format agent-json
+
+# 2. 查看某个音色详情
+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
+
+# 4. 使用同一个 voice_type 进行真实语音合成
+yuanflow-cli ai doubao-tts --text "你好，这是豆包语音合成测试。" --voice zh_female_xiaohe_uranus_bigtts --output "D:\voice\doubao-xiaohe.mp3" --format agent-json
+```
+
+音色列表返回的关键字段：
+
+- `display_name`：给用户看的名称，例如“小何”。
+- `name`：更完整的展示名称，例如“小何 2.0”。
+- `voice_type`：真正合成时传给 `--voice` 的 YuanFlow 音色参数，建议外部系统用它做缓存 key。
+- `category`：音色分类，例如通用场景。
+- `language`：语言。
+- `capabilities`：能力说明，例如情感变化、指令遵循、ASMR。
+- `preview_audio_key`：试听音频在资源 bucket 里的对象 key。
+- `preview_audio_content_type`：试听音频 MIME 类型，通常是 `audio/mpeg`。
+
+`voice-download` 默认返回签名下载地址；传 `--output` 时 CLI 会继续下载试听音频到本地。签名 URL 会过期，不建议长期保存；外部应用应缓存 `voice_type` 和本地试听文件，过期后重新调用 `voice-download` 获取新 URL。
+
+外部系统推荐展示逻辑：
+
+- 下拉框展示 `display_name` 或 `name`。
+- 实际合成提交 `voice_type`。
+- 用户点击试听时先查本地缓存；没有缓存再调用 `voice-download`。
+- 合成接口固定使用 YuanFlow API 对外模型名 `doubao-tts`，不要把底层供应商内部资源名写到外部参数里。
 
 ### 作品评论采集
 
@@ -143,7 +254,7 @@ yuanflow-cli works detail --platform douyin --target "<aweme_id 或 share_url>"
 
 ### 自媒体知识库
 
-知识库能力独立于社媒 `/social` 接口，走 Yuan API 的 `/api/knowledge-base/docs` 和 `/atomic/agent-rules/navigate`：
+知识库能力独立于社媒 `/social` 接口，走 YuanFlow API 的 `/api/knowledge-base/docs` 和 `/atomic/agent-rules/navigate`：
 
 ```bash
 yuanflow-cli knowledge docs --format agent-json
@@ -192,9 +303,9 @@ yuanflow-cli video render-final --project "D:\素材\yuanflow-video-edit" --form
 - `视频投流策略`：短视频、图文视频或内容素材的投流目标、人群、预算、素材分层和测试节奏。
 - `直播投流策略`：直播预热、直播引流、直播成交和直播间投放的人群、预算、素材、节奏和复盘策略。
 
-### OSS 原子能力
+### YuanFlow 文件中转
 
-OSS 能力独立封装为 `oss` 命令，用于临时上传、签名链接和对象复制：
+YuanFlow 文件中转能力独立封装为兼容命令 `oss`，用于临时上传、签名链接和对象复制：
 
 ```bash
 yuanflow-cli oss temp-upload --file ./cover.png --content-type image/png --format agent-json
@@ -233,14 +344,14 @@ yuanflow-cli browser dry-run --platform xiaohongshu --task publish --account mai
 
 ### 音视频在线转文字
 
-`音视频在线转文字` 随 npm 包安装到 Skill bundle，用于通过 YuanFlow 在线 ASR 接口把音频或视频转成干净文本。视频输入需要先用 ffmpeg 分离音频，再上传 OSS。
+`音视频在线转文字` 随 npm 包安装到 Skill bundle，用于通过 YuanFlow 在线 ASR 接口把音频或视频转成干净文本。视频输入需要先用 ffmpeg 分离音频，再上传到 YuanFlow 文件中转。
 
 固定链路：
 
 1. 判断用户提交的是音频还是视频。
 2. 视频先抽取为音频，音频上传前改成英文文件名。
-3. 使用 `yuanflow-cli oss temp-upload` 上传音频。
-4. ASR 请求必须优先使用 OSS 返回的 `data.signed_url` 作为 `metadata.audio_url`，不要优先使用裸域名 `data.url`。
+3. 使用 `yuanflow-cli oss temp-upload` 上传音频到 YuanFlow 文件中转。
+4. ASR 请求必须优先使用文件中转返回的 `data.signed_url` 作为 `metadata.audio_url`，不要优先使用裸域名 `data.url`。
 5. 调用 `POST https://open.yuanchuangai.com/v1/audio/transcriptions`，模型 `doubao-asr`，`response_format=json`。
 6. 默认只返回响应里的 `text` 干净文本；视频剪辑任务需要音频对齐时，要优先保留 ASR 响应中的 `segments` / `words` 时间戳结构，后续交给 `yuanflow-cli video align --asr-file` 导入。接口没有返回时间戳时，不编造时间戳，改用 forced alignment 或人工按文案切分时间。
 
@@ -251,14 +362,14 @@ yuanflow-cli browser dry-run --platform xiaohongshu --task publish --account mai
   "model": "doubao-asr",
   "response_format": "json",
   "metadata": {
-    "audio_url": "<OSS signed_url>"
+    "audio_url": "<YuanFlow 文件中转 signed_url>"
   }
 }
 ```
 
 ### 生图技能
 
-`生图技能` 随 npm 包安装到 Skill bundle。YuanFlow 主程序内优先使用受控工具 `yuanflow_image_request`，自动注入当前用户 token 并缓存返回图片。
+`生图技能` 随 npm 包安装到 Skill bundle。YuanFlow-main 内置环境优先使用受控工具 `yuanflow_image_request`，自动注入当前用户 token 并缓存返回图片。
 
 - 生成图片：`/v1/images/generations`，主模型 `gpt-image-2-c`，备用模型 `gpt-image-2`，请求体使用 `prompt`。
 - 编辑图片：`/v1/images/edits`，必须使用 multipart/form-data 上传本地图片文件。