yuanflow-cli 0.1.39 → 0.1.41

package/skills/yuanflow-skill//350/247/206/350/247/211/347/220/206/350/247/243/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: 视觉理解
+description: 当用户提交图片、视频、本地媒体文件或媒体 URL，并要求识别画面、描述内容、对比画面差异、提取画面信息、检查视觉细节、总结视频画面时使用。本 Skill 是通用型画面理解能力，必须通过 yuanflow-cli 的 qwen3-vl-plus 调用，不用于自媒体对标拆解；对标视频和内容创作拆解请改用“视频拆解”。
+emoji: 👁️
+---
+
+# 视觉理解
+
+本 Skill 是通用型图片/视频画面理解技能。核心能力只使用 `yuanflow-cli ai qwen3-vl-plus`，通过 YuanFlow API 对外模型名 `qwen3-vl-plus` 完成图片、视频 URL 或本地图片、视频文件的理解。
+
+不要把它写成自媒体拆解、爆款分析或创作策略技能；这些需求交给 `视频拆解`。
+
+## 环境判断
+
+1. 在 YuanFlow 主程序内，优先调用受控工具 `yuanflow_cli_call`。
+2. 外部 Agent 且本机有 CLI 时，直接执行 `yuanflow-cli`。
+3. 外部 Agent 没有 CLI 时，再提示用户安装 `npm install -g yuanflow-cli`。
+
+不要让用户手动提供 YuanFlow token。YuanFlow 主程序会注入认证 token；外部 CLI 使用 `YUANCHUANG_API_TOKEN`。
+
+本地图片/视频上传依赖 CLI 的 YuanFlow 文件中转能力。外部 Agent 只需要配置 YuanFlow API token；不要要求用户提供第三方平台 Key，也不要在回复里展示完整 token。
+
+## 能处理什么
+
+- 图片 URL：`--image-url`
+- 视频 URL：`--video-url`
+- 本地图片：`--image-file`
+- 本地视频：`--video-file`
+
+快捷参数一次只传一个媒体。如果用户给多个图片或视频，逐个调用 qwen3-vl-plus，再把每次结果汇总、对比和整理。
+
+## 调用限制和注意事项
+
+- 视频 URL 需要能被 YuanFlow API 访问，响应头建议包含 `Content-Length` 和 `Content-Type`。
+- 视觉模型侧建议单个视频最大 2GB，时长 2 秒到 1 小时。
+- 本地文件会先通过 YuanFlow 文件中转 `POST /atomic/oss/temp-upload` 上传，CLI 取返回的 `signed_url` 后再调用 `/v1/chat/completions`。
+- 本地文件过大时，让用户压缩、裁剪、换文件，或改用可公网访问的视频 URL。
+- 不要上传密钥、cookie、身份证、合同、私密聊天记录等敏感文件，除非用户明确确认且任务确实需要。
+
+## 固定流程
+
+1. 明确用户要做什么：描述、提取文字、找细节、对比差异、判断场景、总结视频、检查异常等。
+2. 判断输入类型：图片 URL、视频 URL、本地图片、本地视频。
+3. 如果输入是多个媒体，按顺序逐个调用 CLI，给每个媒体编号。
+4. 把用户要求写进 `--prompt`，不要只写“描述一下”。
+5. 调用 qwen3-vl-plus。
+6. 整理输出：先给结论，再给画面证据，再给不确定项。
+
+## YuanFlow 内置工具调用示例
+
+图片 URL：
+
+```json
+{
+  "args": [
+    "ai",
+    "qwen3-vl-plus",
+    "--prompt",
+    "请描述图片里的主体、文字、环境和可能的用途。",
+    "--image-url",
+    "https://example.com/image.png",
+    "--format",
+    "agent-json"
+  ],
+  "timeout": 180
+}
+```
+
+视频 URL：
+
+```json
+{
+  "args": [
+    "ai",
+    "qwen3-vl-plus",
+    "--prompt",
+    "请总结视频的主要画面、人物动作、场景变化和可见文字。",
+    "--video-url",
+    "https://example.com/video.mp4",
+    "--format",
+    "agent-json"
+  ],
+  "timeout": 300
+}
+```
+
+本地图片：
+
+```json
+{
+  "args": [
+    "ai",
+    "qwen3-vl-plus",
+    "--prompt",
+    "请识别这张图片中的关键信息，并按主体、文字、细节、可能风险输出。",
+    "--image-file",
+    "D:\\素材\\cover.png",
+    "--format",
+    "agent-json"
+  ],
+  "timeout": 300
+}
+```
+
+本地视频：
+
+```json
+{
+  "args": [
+    "ai",
+    "qwen3-vl-plus",
+    "--prompt",
+    "请按时间顺序总结视频画面变化、人物动作、关键物品和屏幕文字。",
+    "--video-file",
+    "D:\\素材\\demo.mp4",
+    "--format",
+    "agent-json"
+  ],
+  "timeout": 600
+}
+```
+
+## 外部 CLI 示例
+
+```powershell
+yuanflow-cli ai qwen3-vl-plus --prompt "描述这张图的主体、文字和环境" --image-file "D:\素材\cover.png" --format agent-json
+```
+
+```powershell
+yuanflow-cli ai qwen3-vl-plus --prompt "总结视频画面变化和关键细节" --video-file "D:\素材\demo.mp4" --format agent-json
+```
+
+## 输出格式
+
+默认按这个结构输出：
+
+```text
+结论：
+- ...
+
+画面内容：
+- 主体：
+- 场景：
+- 动作/变化：
+- 可见文字：
+
+用户要求对应结果：
+- ...
+
+不确定项：
+- ...
+```
+
+如果是多个媒体对比，输出：
+
+```text
+整体结论：
+
+逐项理解：
+1. 媒体 A：
+2. 媒体 B：
+
+差异对比：
+- 相同点：
+- 不同点：
+- 需要人工确认：
+```
+
+## 失败处理
+
+- YuanFlow token 缺失：说明需要在受管环境或 CLI 配置 YuanFlow API token，不要让用户在聊天里粘贴敏感 Key。
+- 视频超限：提示视频最大 2GB、时长 2 秒到 1 小时，让用户裁剪或压缩。
+- URL 不可访问：提示用户换成公网可访问 URL，或改用本地文件上传。
+- 模型返回不确定：明确标注“不确定”，不要把猜测写成事实。

package/skills/yuanflow-skill//350/247/206/351/242/221/346/212/225/346/265/201/347/255/226/347/225/245/SKILL.md

@@ -46,6 +46,7 @@ emoji: 📈
    - 如果没有命中，说明“未发现可用历史参考记录”，继续下一步。
 5. 调用 `自媒体知识库`。
    - 先查 `knowledge docs` 或 `knowledge entry`，根据平台、投放目标、预算、人群和素材类型构造 `domain` 和 `content_goal`。
+   - 查询时，必须先明确用户具体需求，然后从知识库的一级能力开始，依次使用渐进式查询。不能跳级、跨越式查询。
    - 按返回的 `next_actions` 分层查看 `packs`、`rules` 或 `rule-detail`，直到拿到足够的方法摘要。
    - 不要自己拼 SQL，不要跳过知识库直接凭空输出。
 6. 结合用户要求、账号最近 5 条视频数据、历史参考记录和知识库结果，输出视频投流策略。

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

@@ -0,0 +1,245 @@
+---
+name: 视频拆解
+description: 当用户提交对标视频、本地视频、视频 URL，要求做自媒体创作方向的视频拆解、爆款结构分析、内容复盘、脚本拆解、镜头节奏拆解、账号/竞品内容学习时使用。开始前必须先使用“自媒体知识库”查询与对标拆解相关的规则，再通过 yuanflow-cli 的 qwen3-vl-plus 上传/理解视频，并把知识库规则放入提示词中指导拆解。
+emoji: 🎬
+---
+
+# 视频拆解
+
+本 Skill 是自媒体创作场景下的对标视频拆解技能。它不是通用画面描述工具；通用图片/视频理解请使用 `视觉理解`。
+
+核心链路：
+
+1. 先查 `自媒体知识库`，获取与“对标拆解、视频拆解、内容创作、脚本结构、镜头节奏、爆款复盘”相关的规则摘要。
+2. 如果用户给的是视频 URL，先用相关工具解析并保存到本地。
+3. 使用 `yuanflow-cli ai qwen3-vl-plus --video-file` 提交本地视频。
+4. 把知识库拆解规则写进 prompt，让模型按规则拆解视频。
+5. 整理成适合自媒体创作复用的详细拆解报告。
+
+## 环境判断
+
+1. 在 YuanFlow 主程序内，优先调用受控工具 `yuanflow_cli_call`。
+2. 外部 Agent 且本机有 CLI 时，直接执行 `yuanflow-cli`。
+3. 外部 Agent 没有 CLI 时，再提示用户安装 `npm install -g yuanflow-cli`。
+
+不要让用户手动提供 YuanFlow token。YuanFlow 主程序会注入认证 token；外部 CLI 使用 `YUANCHUANG_API_TOKEN`。
+
+本地视频上传依赖 qwen3-vl-plus 的 YuanFlow 文件中转能力。外部 Agent 只需要配置 YuanFlow API token；不要要求用户提供第三方平台 Key。
+
+## 适用场景
+
+- 对标视频拆解。
+- 爆款视频拆解。
+- 内容结构、开头钩子、脚本节奏、镜头节奏分析。
+- 短视频带货、口播、剧情、测评、知识分享类内容复盘。
+- 用户希望从竞品视频里提炼可复用创作方法。
+
+不适合：
+
+- 只想描述视频画面：改用 `视觉理解`。
+- 只想转文字：改用 `音视频在线转文字` 或 `本地音视频转文字`。
+- 只想下载视频：改用 `作品下载综合工具`。
+
+## 固定流程
+
+### 1. 明确拆解目标
+
+先问清或从用户话里提取：
+
+- 平台或内容类型：抖音、小红书、B站、视频号、YouTube 等。
+- 拆解目的：选题学习、脚本复用、镜头节奏、带货结构、账号定位、投放素材、爆款复盘。
+- 用户是否给了本地视频，还是视频 URL。
+
+### 2. 先查自媒体知识库
+
+必须先调用知识库，不要直接上传视频拆解。
+
+YuanFlow 内置工具示例：
+
+```json
+{
+  "args": [
+    "knowledge",
+    "entry",
+    "--output-format",
+    "video_breakdown",
+    "--domain",
+    "自媒体运营",
+    "--content-goal",
+    "对标视频拆解，提炼内容结构、脚本节奏、镜头设计和可复用创作方法",
+    "--target-audience",
+    "自媒体创作者",
+    "--format",
+    "agent-json"
+  ],
+  "timeout": 180
+}
+```
+
+如果返回 `next_actions`，继续按推荐调用 `packs`、`rules` 或 `rule-detail`。优先查询与以下方向相关的规则：
+
+- 对标拆解
+- 视频拆解
+- 内容复盘
+- 脚本结构
+- 开头钩子
+- 镜头节奏
+- 账号定位
+- 带货/转化结构
+
+外部 CLI 示例：
+
+```powershell
+yuanflow-cli knowledge entry --output-format video_breakdown --domain 自媒体运营 --content-goal "对标视频拆解，提炼内容结构、脚本节奏、镜头设计和可复用创作方法" --target-audience 自媒体创作者 --format agent-json
+```
+
+### 3. 视频 URL 先解析并保存本地
+
+如果用户提交的是平台视频 URL，先用 `作品下载综合工具` 或 `yuanflow-cli works download` 解析可播放/下载地址候选。
+
+先按链接判断平台：
+
+- `douyin.com`、`v.douyin.com`：`--platform douyin`，国内环境通常加 `--region CN`。
+- `bilibili.com`、`b23.tv`、`BV`：`--platform bilibili`。
+- `youtube.com`、`youtu.be`：`--platform youtube`。
+- `ixigua.com`：`--platform xigua`。
+
+YuanFlow 内置工具示例：
+
+```json
+{
+  "args": [
+    "works",
+    "download",
+    "--platform",
+    "douyin",
+    "--target",
+    "https://v.douyin.com/xxx/",
+    "--region",
+    "CN",
+    "--format",
+    "agent-json"
+  ],
+  "timeout": 180
+}
+```
+
+外部 CLI 示例：
+
+```powershell
+yuanflow-cli works download --platform douyin --target "https://v.douyin.com/xxx/" --region CN --format agent-json
+```
+
+解析到可访问视频 URL 后，经用户授权保存到本地临时文件，再提交 qwen3-vl-plus。保存文件时使用清晰路径，例如：
+
+```text
+D:\素材\yuanflow-video-breakdown\input.mp4
+```
+
+保存方式：
+
+- 如果返回的是普通 mp4/http 下载地址，用系统下载能力保存到本地。
+- 如果返回的是 m3u8 或分片流，优先用 ffmpeg 保存成 mp4。
+- 如果返回多个清晰度，默认选清晰度高且文件体积可控的一项；不要为了拆解盲目选超大文件。
+- 保存前确认这是用户授权分析的视频，不要下载私密、付费、未授权或明显受版权限制的内容。
+
+外部 Agent 可用的保存示例：
+
+```powershell
+New-Item -ItemType Directory -Force "D:\素材\yuanflow-video-breakdown"
+Invoke-WebRequest -Uri "<解析得到的视频直链>" -OutFile "D:\素材\yuanflow-video-breakdown\input.mp4"
+```
+
+如果是 m3u8：
+
+```powershell
+ffmpeg -y -i "<解析得到的 m3u8 地址>" -c copy "D:\素材\yuanflow-video-breakdown\input.mp4"
+```
+
+如果平台解析只返回播放候选而没有稳定下载 URL，说明当前链接需要用户提供可下载文件，或先让用户使用其它授权方式保存视频。
+
+### 4. 调用 qwen3-vl-plus 做规则化拆解
+
+把知识库查询到的规则摘要压缩进 prompt。不要只让模型“分析视频”，必须告诉它按规则拆解。
+
+YuanFlow 内置工具示例：
+
+```json
+{
+  "args": [
+    "ai",
+    "qwen3-vl-plus",
+    "--prompt",
+    "你是自媒体视频拆解助手。请严格按以下知识库规则拆解这个对标视频：\\n【知识库规则摘要】...\\n【用户目标】学习该视频的选题、开头、脚本结构、镜头节奏和可复用创作方法。\\n请输出：1. 一句话总结；2. 视频定位；3. 开头钩子；4. 内容结构；5. 镜头/画面节奏；6. 情绪和转化设计；7. 可复用模板；8. 不建议照搬的风险。",
+    "--video-file",
+    "D:\\素材\\yuanflow-video-breakdown\\input.mp4",
+    "--format",
+    "agent-json"
+  ],
+  "timeout": 600
+}
+```
+
+外部 CLI 示例：
+
+```powershell
+yuanflow-cli ai qwen3-vl-plus --prompt "你是自媒体视频拆解助手。请按知识库规则拆解这个视频：..." --video-file "D:\素材\yuanflow-video-breakdown\input.mp4" --format agent-json
+```
+
+## 调用限制和注意事项
+
+- qwen3-vl-plus 视频建议单个视频最大 2GB，时长 2 秒到 1 小时。
+- 本地视频上传时，CLI 会先调用 YuanFlow 文件中转 `POST /atomic/oss/temp-upload`，再把返回的 `signed_url` 提交给 YuanFlow API。
+- 本地文件过大时，让用户压缩、裁剪、提供短版本，或改用可公网访问的视频 URL。
+- 对标视频拆解只能用于学习结构、表达和创作方法，不要鼓励搬运、洗稿、规避版权或冒充原创。
+
+## 输出格式
+
+默认输出详细拆解报告：
+
+```text
+# 视频拆解报告
+
+## 1. 一句话结论
+
+## 2. 视频基础判断
+- 内容类型：
+- 目标受众：
+- 核心卖点/观点：
+- 适用平台：
+
+## 3. 开头钩子拆解
+- 前 3 秒：
+- 冲突/利益点：
+- 留人方式：
+
+## 4. 内容结构拆解
+- 段落 1：
+- 段落 2：
+- 段落 3：
+- 结尾：
+
+## 5. 画面与镜头节奏
+- 场景变化：
+- 人物/产品/字幕：
+- 节奏特点：
+
+## 6. 情绪、信任和转化设计
+
+## 7. 可复用创作模板
+
+## 8. 可借鉴点与风险
+- 可借鉴：
+- 不建议照搬：
+- 需要二次原创：
+
+## 9. 给用户的下一步建议
+```
+
+## 失败处理
+
+- 知识库查询失败：说明无法取得拆解规则，不要跳过规则直接当普通视觉理解；可询问用户是否改为通用视觉理解。
+- 视频 URL 解析失败：说明需要用户提供本地视频或可直接访问的下载链接。
+- YuanFlow token 缺失：说明需要在受管环境或 CLI 配置 YuanFlow API token，不要让用户在聊天里粘贴敏感 Key。
+- 视频超限：提示最大 2GB、2 秒到 1 小时，让用户裁剪或压缩。
+- 模型无法识别细节：按“可确认/不确定/建议人工复查”分开写，不要编造。

package/skills/yuanflow-skill//350/247/206/351/242/221/346/231/272/350/203/275/345/211/252/350/276/221/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: 视频智能剪辑
-description: "用于把主音频、文案、B-roll 视频或图片素材组合成可解释的智能剪辑项目。执行前先查询自媒体知识库中的视频剪辑策略规则，再按 1秒1帧抽帧，由 Agent 判断画面语义并生成 EDL，交给 yuanflow-cli video 校验和渲染。"
+description: "用于把主音频、文案、B-roll 视频或图片素材组合成可解释的智能剪辑项目。执行前先查询自媒体知识库中的视频剪辑策略规则，再用音视频在线转文字取得 ASR/时间戳，导入音频对齐，按 1秒1帧抽帧并回写视觉理解，由 Agent 生成 EDL，交给 yuanflow-cli video 校验和渲染。"
 metadata:
   builtin_skill_version: "1.0.1"
   yuanflow:
@@ -25,6 +25,7 @@ tags:
 推荐查询顺序：
 
 1. 先用 `knowledge entry` 建立任务入口，`domain` 填 `视频剪辑`，`content_goal` 写清本次剪辑目标。
+   - 查询时，必须先明确用户具体需求，然后从知识库的一级能力开始，依次使用渐进式查询。不能跳级、跨越式查询。
 2. 再用 `knowledge packs --capability-code video_editing_strategy` 查看视频剪辑策略下的方法包。
 3. 必查 `video_edit_logic_layer_pack`，获得通用剪辑逻辑层规则。
 4. 如果任务是口播、旁白、主音频驱动，查询 `talking_head_edit_template_pack`。
@@ -101,8 +102,9 @@ CLI 会生成 `strategy_snapshot.json`，后续 Agent 必须基于这个快照
 
 - 主音频可以是口播、旁白或已经录好的音频。
 - B-roll 可以是视频或图片素材。
-- 第一版视觉理解不调用视觉模型，使用 `yuanflow-cli video timeline --fps 1` 按 1秒1帧抽帧。
-- Agent 需要查看抽帧结果，自己判断每段画面的语义、主体、动作和适合承接的文案。
+- 第一版音频对齐优先使用“音视频在线转文字”Skill 的 ASR 时间戳结果；如果 ASR 没有时间戳，使用 forced alignment 或人工按文案切分，不编造时间戳。
+- 第一版视觉理解不调用固定视觉模型，使用 `yuanflow-cli video timeline --fps 1` 按 1秒1帧抽帧。
+- Agent 或人工需要查看抽帧结果，判断每段画面的语义、主体、动作和适合承接的文案，再用 `video visual-review` 回写结构化视觉描述。
 - 第一版 `video plan` 不自动生成 EDL，由 Agent 生成 EDL 后交给 CLI 校验和渲染。
 
 ## 执行原则
@@ -161,18 +163,27 @@ yuanflow-cli video inspect --project "D:\素材\yuanflow-video-edit" --format ag
 
 如果只是验证命令结构，可以加 `--dry-run`。
 
-### 3. 导入文案或转写
+### 3. 音频对齐
 
-如果用户已有文案：
+主音频驱动的剪辑必须先建立音频时间轴。优先使用“音视频在线转文字”Skill 调用在线 ASR；如果 ASR 返回 `segments` / `words` 时间戳，保存为 JSON 后导入：
 
 ```bash
-yuanflow-cli video transcribe \
+yuanflow-cli video align \
   --project "D:\素材\yuanflow-video-edit" \
-  --script-file "D:\素材\口播文案.txt" \
+  --asr-file "D:\素材\asr.json" \
   --format agent-json
 ```
 
-如果用户只有音频，先使用“音视频在线转文字”或“本地音视频转文字”得到文本，再用 `--script-file` 导入。
+如果 ASR 只返回纯文本，没有时间戳：
+
+- 先明确说明缺少时间戳。
+- 可用 forced alignment 或人工按文案切分生成 `segments`。
+- 只有在用户允许“粗对齐”时，才能按文本段落和音频总时长均分兜底。
+
+`video align` 会生成：
+
+- `audio_alignment.json`
+- 带 `start_s / end_s` 的 `beats.json`
 
 ### 4. 生成 1秒1帧时间线
 
@@ -191,14 +202,51 @@ CLI 会生成：
 
 Agent 必须基于这些抽帧图片判断画面，不要凭文件名猜。
 
-### 5. Agent 生成 timeline_plan 和 EDL
+### 5. 视觉理解回写
+
+Agent 或人工查看抽帧图片后，先写出 `visual_review.agent.json`，不要直接跳到 EDL。基础格式：
+
+```json
+{
+  "version": 1,
+  "reviews": [
+    {
+      "segment_id": "vis_0001",
+      "description": "产品近景，手持展示刷头。",
+      "subjects": ["产品", "手"],
+      "scene": "厨房水槽",
+      "motion": "展示",
+      "semantic_tags": ["product_closeup", "kitchen"],
+      "quality_score": 0.88
+    }
+  ]
+}
+```
+
+导入视觉理解：
+
+```bash
+yuanflow-cli video visual-review \
+  --project "D:\素材\yuanflow-video-edit" \
+  --review-file "D:\素材\yuanflow-video-edit\visual_review.agent.json" \
+  --format agent-json
+```
+
+CLI 会生成或更新：
+
+- `visual_understanding.json`
+- 带结构化描述的 `visual_segments.json`
+
+### 6. Agent 生成 timeline_plan 和 EDL
 
 Agent 读取：
 
 - `project.json`
 - `assets.json`
+- `audio_alignment.json`
 - `beats.json`
 - `visual_segments.json`
+- `visual_understanding.json`
 - `strategy_snapshot.json`
 - 抽帧图片
 
@@ -268,7 +316,7 @@ Agent 读取：
 }
 ```
 
-### 6. 校验 EDL
+### 7. 校验 EDL
 
 ```bash
 yuanflow-cli video plan \
@@ -289,14 +337,14 @@ yuanflow-cli video plan \
 
 只有校验通过后，才允许渲染。
 
-### 7. 渲染预览和自检
+### 8. 渲染预览和自检
 
 ```bash
 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
 ```
 
-### 8. 最终导出
+### 9. 最终导出
 
 ```bash
 yuanflow-cli video render-final --project "D:\素材\yuanflow-video-edit" --format agent-json

package/skills/yuanflow-skill//351/200/211/351/242/230/347/255/226/345/210/222/SKILL.md

@@ -16,6 +16,7 @@ emoji: 💡
    - 如果没有命中，说明“未发现可用历史参考记录”，继续下一步。
 2. 调用 `自媒体知识库`。
    - 先查 `knowledge docs` 或 `knowledge entry`，根据平台、受众、内容目标和选题方向构造 `domain` 和 `content_goal`。
+   - 查询时，必须先明确用户具体需求，然后从知识库的一级能力开始，依次使用渐进式查询。不能跳级、跨越式查询。
    - 按返回的 `next_actions` 分层查看 `packs`、`rules` 或 `rule-detail`，直到拿到足够的方法摘要。
    - 不要自己拼 SQL，不要跳过知识库直接凭空输出。
 3. 结合用户要求、历史参考记录和知识库结果，输出选题策划结果。

package/skills/yuanflow-skill//351/237/263/350/247/206/351/242/221/345/234/250/347/272/277/350/275/254/346/226/207/345/255/227/SKILL.md

@@ -21,11 +21,11 @@ emoji: ☁️
    - 视频：先用 ffmpeg 分离音频，再进入上传流程。
 2. 上传前把待上传音频整理为英文文件名。
    - 官方参数只要求 `metadata.audio_url` 是可公网访问的音频 URL，没有说明必须英文文件名。
-   - 但为避免 OSS URL 编码、上游下载和中文文件名兼容问题，上传前必须使用 ASCII 英文文件名，例如 `transcription-input.mp3`。
-3. 使用 `OSS文件中转工具` 上传音频。
-4. 从 OSS 返回中优先取 `data.signed_url` 作为 ASR 的 `metadata.audio_url`。
-   - 不要优先使用裸域名 `data.url`；实测裸域名可能导致上游报 `Invalid audio URI` 或音频下载失败。
-   - 如果只有 `data.url`，必须补齐 `https://` 后再尝试；失败时说明 OSS URL 不可被 ASR 上游下载。
+   - 但为避免文件中转 URL 编码、服务下载和中文文件名兼容问题，上传前必须使用 ASCII 英文文件名，例如 `transcription-input.mp3`。
+3. 使用 `YuanFlow 文件中转工具` 上传音频。
+4. 从文件中转返回中优先取 `data.signed_url` 作为 ASR 的 `metadata.audio_url`。
+   - 不要优先使用裸域名 `data.url`；实测裸域名可能导致 `Invalid audio URI` 或音频下载失败。
+   - 如果只有 `data.url`，必须补齐 `https://` 后再尝试；失败时说明该文件中转 URL 不可被 ASR 服务下载。
 5. 调用在线 ASR 接口。
 6. 默认只把干净文本返回给用户，不展示原始 JSON。
 7. 只有用户明确要求时间戳、分句、原始结构或调试信息时，才返回 JSON 摘要或原始字段。
@@ -40,9 +40,9 @@ ffmpeg -y -i "C:\path\to\input.mp4" -vn -acodec libmp3lame -ar 44100 -ac 2 "tran
 
 如果 ffmpeg 不可用，必须明确告诉用户缺少 ffmpeg，不能伪造转写结果。
 
-## OSS 上传
+## YuanFlow 文件中转
 
-YuanFlow 主程序内优先调用 `yuanflow_cli_call`，使用 OSS 子命令上传英文命名后的音频：
+YuanFlow 主程序内优先调用 `yuanflow_cli_call`，使用兼容子命令 `oss` 上传英文命名后的音频：
 
 ```json
 {
@@ -95,7 +95,7 @@ Content-Type: application/json
   "model": "doubao-asr",
   "response_format": "json",
   "metadata": {
-    "audio_url": "<OSS signed_url>"
+    "audio_url": "<YuanFlow 文件中转 signed_url>"
   }
 }
 ```
@@ -110,7 +110,7 @@ Content-Type: application/json
     "model": "doubao-asr",
     "response_format": "json",
     "metadata": {
-      "audio_url": "<OSS signed_url>"
+      "audio_url": "<YuanFlow 文件中转 signed_url>"
     }
   },
   "timeout": 180
@@ -138,6 +138,6 @@ Content-Type: application/json
 ## 失败处理
 
 - `Invalid audio URI` / `audio download failed`：优先检查是否误用了 `data.url` 裸域名；改用 `data.signed_url` 重试。
-- OSS 上传成功但 ASR 失败：说明 OSS key 已生成，但上游无法下载或识别该 URL。
+- YuanFlow 文件中转上传成功但 ASR 失败：说明文件对象已生成，但 ASR 服务无法下载或识别该 URL。
 - 视频抽音频失败：报告 ffmpeg 错误，不继续调用 ASR。
 - 不要暴露 token、Authorization header、签名 URL 的完整敏感查询参数，除非用户明确需要调试链接。