yuanflow-cli 0.1.39 → 0.1.41

package/README.md

@@ -36,6 +36,7 @@ yuanflow-cli works detail --platform douyin --target "https://v.douyin.com/xxx/"
 yuanflow-cli works download --platform douyin --target "https://v.douyin.com/xxx/" --region CN --format agent-json
 yuanflow-cli search content --platform xiaohongshu --keyword "美妆" --format agent-json
 yuanflow-cli search users --platform instagram --keyword "nasa" --format agent-json
+yuanflow-cli trending video-hot-list --format agent-json
 yuanflow-cli douyin web get-sec-user-id --url "https://v.douyin.com/xxx/" --format agent-json
 yuanflow-cli douyin user-profile <sec_user_id> --format agent-json
 yuanflow-cli douyin user-posts <sec_user_id> --count 20 --cursor 0 --format agent-json
@@ -47,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
 ```
 
@@ -56,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 主程序内使用时，token 由主程序认证系统注入，不需要手动配置。本地图片/视频上传统一使用 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`，不要把底层供应商内部资源名写到外部参数里。
 
 ### 作品评论采集
 
@@ -99,6 +211,26 @@ yuanflow-cli search users --platform instagram --keyword "nasa" --format agent-j
 
 Agent 不确定参数时先执行 `commands list`，再用 `schema works.douyin.detail` 或 `schema search.xiaohongshu.content` 查看参数。`--dry-run` 可预览请求映射，不发起真实接口请求，也不要求 token。
 
+### 热门内容整理
+
+热门内容整理统一走 `trending video-hot-list`，一次性查询抖音视频热榜五类榜单，并输出统一 JSON：
+
+```bash
+yuanflow-cli trending video-hot-list --format agent-json
+yuanflow-cli trending video-hot-list --page 1 --page-size 10 --date-window 2 --format agent-json
+yuanflow-cli trending video-hot-list --tags-json "[{\"value\":\"顶级垂类标签id\",\"children\":[{\"value\":\"子级垂类标签id\"}]}]" --format agent-json
+```
+
+默认查询：
+
+- `1001` 视频总榜
+- `1002` 低粉爆款
+- `1003` 高完播率
+- `1004` 高涨粉率
+- `1005` 高点赞率
+
+Agent 使用该命令后，应结合用户个人创作信息、个人创作库历史记录、历史任务或对话记录，输出可执行的选题、内容结构和发布建议，而不是只罗列榜单。
+
 ### 帐号监控
 
 `帐号监控` 随 npm 包安装到 Skill bundle，用于把帐号搜索、主页资料、主页作品、历史快照和变化对比串成稳定流程。
@@ -122,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
@@ -133,26 +265,29 @@ yuanflow-cli knowledge rule-detail --rule-code some_rule_code --output-format sh
 
 Agent 应先查看 `knowledge docs`，再把用户需求整理成 `task_frame`，按接口返回的 `next_actions` 渐进查询。v2 接口不要求 `task_intent`；旧字段仅保留兼容。`packs`、`rules` 的 `data` 可能直接是数组，Agent 不应假设固定对象结构，应优先读取 `next_actions` 继续下钻。
 
+查询前必须先明确用户具体需求，再从知识库的一级能力开始，依次使用渐进式查询。不能跳级、跨越式查询。
+
 `knowledge entry`、`knowledge packs`、`knowledge evaluate` 会按规则库实际校验要求本地检查 `task_frame.domain` 和 `task_frame.content_goal`，CLI 调用时必须传 `--domain` 和 `--content-goal`，或通过 `--task-frame-file` 提供同名字段。`rules` 和 `rule-detail` 用于按已选包/规则继续下钻，仍必须分别传 `--pack-code` 或 `--rule-code`。
 
 ### 视频智能剪辑
 
-视频剪辑链路先查自媒体知识库中的 `video_editing_strategy`，再进入 `video` 命令执行。第一版人工测试流程是：查询规则包、保存策略快照、扫描素材、导入文案、1 秒 1 帧抽帧、Agent 生成 `timeline_plan.agent.json`、CLI 校验并渲染。
+视频剪辑链路先查自媒体知识库中的 `video_editing_strategy`，再进入 `video` 命令执行。第一版人工测试流程是：查询规则包、保存策略快照、扫描素材、通过“音视频在线转文字”取得 ASR/时间戳结果、导入音频对齐、1 秒 1 帧抽帧、导入视觉理解结果、Agent 生成 `timeline_plan.agent.json`、CLI 校验并渲染。
 
 ```bash
 yuanflow-cli knowledge rules --pack-code video_edit_logic_layer_pack --domain 视频剪辑 --content-goal "口播视频剪辑，需要主音频匹配 B-roll 并生成 EDL" --output-format video_edit_plan --format agent-json --output "D:\规则\logic.json"
 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:\规则\talking_head.json,D:\规则\cli.json" --format agent-json
 yuanflow-cli video inspect --project "D:\素材\yuanflow-video-edit" --format agent-json
-yuanflow-cli video transcribe --project "D:\素材\yuanflow-video-edit" --script-file "D:\素材\口播文案.txt" --format agent-json
+yuanflow-cli video align --project "D:\素材\yuanflow-video-edit" --asr-file "D:\素材\asr.json" --format agent-json
 yuanflow-cli video timeline --project "D:\素材\yuanflow-video-edit" --fps 1 --format agent-json
+yuanflow-cli video visual-review --project "D:\素材\yuanflow-video-edit" --review-file "D:\素材\yuanflow-video-edit\visual_review.agent.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 video render-preview --project "D:\素材\yuanflow-video-edit" --format agent-json
 yuanflow-cli video evaluate --project "D:\素材\yuanflow-video-edit" --file "D:\素材\yuanflow-video-edit\preview.mp4" --format agent-json
 yuanflow-cli video render-final --project "D:\素材\yuanflow-video-edit" --format agent-json
 ```
 
-`--template-type` 当前支持 `talking_head` 和 `short_video_sales`。知识库查询由 `knowledge` 命令负责，`video` 命令只导入规则结果并保存 `strategy_snapshot.json`，不直接远程查规则库。
+`video align` 只导入已有 ASR 或 forced alignment 结果，不直接调用在线 ASR；在线 ASR 由“音视频在线转文字”Skill 执行。`video visual-review` 只导入 Agent/人工对抽帧图片的视觉理解，不替 Agent 做语义判断。`--template-type` 当前支持 `talking_head` 和 `short_video_sales`。知识库查询由 `knowledge` 命令负责，`video` 命令只导入规则结果并保存 `strategy_snapshot.json`，不直接远程查规则库。
 
 ### 业务创作类 Skill
 
@@ -163,12 +298,14 @@ 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
@@ -207,16 +344,16 @@ 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` 干净文本；用户要求时间戳时再检查响应结构，不编造时间戳。
+6. 默认只返回响应里的 `text` 干净文本；视频剪辑任务需要音频对齐时，要优先保留 ASR 响应中的 `segments` / `words` 时间戳结构，后续交给 `yuanflow-cli video align --asr-file` 导入。接口没有返回时间戳时，不编造时间戳，改用 forced alignment 或人工按文案切分时间。
 
 请求体示例：
 
@@ -225,7 +362,7 @@ 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>"
   }
 }
 ```