yuanflow-cli 0.1.40 → 0.1.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yuanflow-cli",
-  "version": "0.1.40",
+  "version": "0.1.41",
   "description": "YuanFlow 自媒体 API CLI 与 Skill 安装器。",
   "type": "module",
   "license": "MIT",

package/scripts/generate-registry.js

@@ -66,7 +66,7 @@ async function main() {
         command,
         aliases: [],
         method: method.toUpperCase(),
-        upstreamPath: rawPath,
+        sourcePath: rawPath,
         socialPath,
         summary: cleanText(operation.summary || ''),
         bodyExample: extractBodyExample(operation),

package/skills/yuanflow-skill/README.md

@@ -7,16 +7,16 @@ YuanFlow Skill 是 `yuanflow-cli` 的 Agent Skill 仓库，用于把社媒平台
 - `SKILL.md`：总入口，负责分流和索引。
 - `yuanflow-cli/`：API CLI 子 Skill，说明 `yuanflow-cli` 的安装、配置、命令发现、schema 查询、dry-run 和 agent-json 调用方式。
 - `自媒体知识库/`：自媒体知识库渐进查询 Skill，走 `yuanflow-cli knowledge`。
-- `OSS文件中转工具/`：OSS 临时上传、签名链接、对象复制 Skill，走 `yuanflow-cli oss`。
+- `视觉理解/`：通用型图片、视频画面理解 Skill，走 `yuanflow-cli ai qwen3-vl-plus`，支持图片/视频 URL 和本地图片/视频上传。
+- `视频拆解/`：自媒体创作场景的对标视频拆解 Skill，先查自媒体知识库对标拆解规则，再用 `qwen3-vl-plus` 上传视频并按规则拆解。
+- `YuanFlow文件中转工具/`：YuanFlow 文件中转、签名链接、对象复制 Skill，内部兼容命令走 `yuanflow-cli oss`。
 - `生图技能/`：图片生成与编辑 Skill，优先走 YuanFlow 内置 `yuanflow_image_request`。
 - `公众号生成与发布/`：公众号文章创作、主题预览、微信内联 HTML 排版、正文图片上传和草稿箱推送 Skill。
 - `小红书运营/`：小红书选题调研、笔记搜索、账号分析、评论采集、文案创作、发布前检查和互动操作 Skill；不建议浏览器自动发布作品，除非用户明确无视平台识别和限流风险并强制要求。
-- `热门内容整理/`：一次性查询视频总榜、低粉爆款、高完播率、高涨粉率、高点赞率，并结合用户创作方向输出建议。
-- `创作总监/`：负责内容方向把控、创新判断、复查验收和跨技能创作统筹。
 - `视频智能剪辑/`：主音频 + B-roll 素材智能剪辑 Skill，先查自媒体知识库的视频剪辑策略，保存 `strategy_snapshot.json`，再通过 ASR/forced alignment 导入 `audio_alignment.json`，按 1 秒 1 帧抽帧并回写视觉理解，由 Agent 生成 `timeline_plan` 和 EDL，交给 `yuanflow-cli video` 校验和渲染。
 - `HTML报告生成/`：单页 HTML 报告生成 Skill，内置 9 种米色留白报告模板。
 - `本地音视频转文字/`：本地 SenseVoice 音视频转文字 Skill，首次明确使用时按需下载模型。
-- `音视频在线转文字/`：通过 YuanFlow 在线 ASR 接口把音频或视频转成干净文本，视频会先抽取音频并通过 OSS 中转。
+- `音视频在线转文字/`：通过 YuanFlow 在线 ASR 接口把音频或视频转成干净文本，视频会先抽取音频并通过 YuanFlow 文件中转。
 - `自媒体浏览器自动化/`：自媒体平台专用浏览器自动化 Skill，用于登录态隔离、Cookie/profile 本地保存、页面采集和作品发布流程。
 - `帐号监控/`：帐号搜索、主页资料、主页作品、历史快照、变化对比和 HTML 可视化分流 Skill。
 - `个人创作库/`：长期保存、整理、复盘和复用用户认可的自媒体合格产出物。
@@ -35,14 +35,16 @@ YuanFlow Skill 是 `yuanflow-cli` 的 Agent Skill 仓库，用于把社媒平台
 - 查看可用 API 命令、快捷命令和 schema。
 - 让本地 Agent 稳定调用 `yuanflow-cli` 并解析 JSON 输出。
 - 查询自媒体知识库公开方向、方法包和规则摘要。
-- 上传文件到临时 OSS、生成签名链接或复制 OSS 对象。
+- 对图片、视频、本地媒体文件或媒体 URL 做通用画面理解、内容描述、可见文字识别、画面对比和细节检查。
+- 对自媒体对标视频、爆款视频、竞品视频做内容结构、开头钩子、脚本节奏、镜头节奏和可复用创作方法拆解；开始前先查自媒体知识库规则，视频 URL 先解析并保存本地。
+- 上传文件到 YuanFlow 文件中转、生成签名链接或复制文件对象。
 - 生成图片、编辑图片，并缓存返回 URL 或 base64 图片。生成图片必填 `prompt`，可选 `size / quality / style / n / response_format`；编辑图片必须通过 multipart 上传本地图片。
 - 把自媒体分析、数据复盘、文案方案、账号监控、知识梳理和执行计划生成可直接打开的单页 HTML 报告。
 - 生成或改写公众号文章，进入主题选择预览后导出微信公众号编辑器可粘贴 HTML，或推送到公众号草稿箱。
-- 处理小红书单段或全流程任务，例如只写文案、只采集笔记、只分析账号、只采集评论、只做点赞收藏评论回复，或完整执行图文/视频发布流程；每轮开始前必须明确任务边界。
+- 处理小红书单段或全流程任务，例如只写文案、只采集笔记、只分析账号、只采集评论、只做点赞收藏评论回复，或完整执行图文/视频发布流程；每轮开始前必须明确任务边界。写小红书文案前先查自媒体知识库方法论，遇到封面或正文插图生成时先确认 4:3 或 3:4 比例并调用生图技能。
 - 在用户要求智能剪辑、自动剪辑、主音频匹配 B-roll、重排视频画面或生成剪辑预览时，使用视频智能剪辑 Skill；第一版先查规则库，导入策略快照，用“音视频在线转文字”或 forced alignment 建立音频对齐，抽帧频率固定 1 秒 1 帧，再回写视觉理解结果，最后生成 `timeline_plan` 和 EDL。
 - 在用户明确要求本地转写时，把本地音频或视频转成文字；视频会先抽取音频，模型和缓存都保存在 Skill 自己目录下。
-- 在用户要求在线转写、云端转写或 doubao-asr 时，把本地音频或视频经 OSS 中转后提交在线 ASR，默认只返回干净文本。
+- 在用户要求在线转写、云端转写或 doubao-asr 时，把本地音频或视频经 YuanFlow 文件中转后提交在线 ASR，默认只返回干净文本。
 - 在用户要求自媒体平台浏览器自动化、账号登录态隔离、Cookie/profile 保存、平台页面采集或作品发布时，使用专用自媒体浏览器自动化 Skill；普通网页浏览和搜索仍使用通用浏览器能力。
 - 监控抖音、小红书、微博、知乎、Bilibili、TikTok、YouTube、Twitter/X 帐号主页，保存快照并对比历史变化；抖音链路优先使用 `get-sec-user-id -> user-profile -> user-posts -> works detail`。
 - 在用户要求保存、归档、复盘或复用已完成创作成果时，把选题、标题、文案、脚本、封面、剪辑思路、发布计划和数据复盘沉淀进个人创作库。
@@ -107,6 +109,10 @@ yuanflow-skill list-skills
 │  └─ SKILL.md
 ├─ 自媒体知识库
 │  └─ SKILL.md
+├─ 视觉理解
+│  └─ SKILL.md
+├─ 视频拆解
+│  └─ SKILL.md
 ├─ 生图技能
 │  └─ SKILL.md
 ├─ 公众号生成与发布
@@ -116,8 +122,6 @@ yuanflow-skill list-skills
 │  ├─ references/
 │  └─ tests/
 ├─ 小红书运营
-├─ 热门内容整理
-├─ 创作总监
 │  ├─ SKILL.md
 │  └─ references/
 ├─ 视频智能剪辑
@@ -154,7 +158,7 @@ yuanflow-skill list-skills
 │  └─ SKILL.md
 ├─ 直播投流策略
 │  └─ SKILL.md
-└─ OSS文件中转工具
+└─ YuanFlow文件中转工具
    └─ SKILL.md
 ```
 

package/skills/yuanflow-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: YuanFlow技能总入口
-description: 当用户需要处理自媒体平台接口工作流、平台数据查询、命令发现、生图、OSS 文件中转、知识库查询、HTML 报告生成，或需要在 YuanFlow 子技能之间选择合适能力时使用。
+description: 当用户需要处理自媒体平台接口工作流、平台数据查询、命令发现、生图、YuanFlow 文件中转、知识库查询、HTML 报告生成，或需要在 YuanFlow 子技能之间选择合适能力时使用。
 ---
 
 # YuanFlow Skill
@@ -19,7 +19,9 @@ description: 当用户需要处理自媒体平台接口工作流、平台数据
 - `综合搜索工具/`
 - `综合用户搜索工具/`
 - `自媒体知识库/`
-- `OSS文件中转工具/`
+- `视觉理解/`
+- `视频拆解/`
+- `YuanFlow文件中转工具/`
 - `生图技能/`
 - `公众号生成与发布/`
 - `小红书运营/`
@@ -179,17 +181,17 @@ description: 当用户需要处理自媒体平台接口工作流、平台数据
 
 - `帐号监控`
 
-### 10. 走 `OSS文件中转工具`
+### 10. 走 `YuanFlow文件中转工具`
 
 遇到下面这些需求，优先进入这个子 Skill：
 
-- 上传图片、音频、视频、文档到临时 OSS。
-- 为已有 OSS 对象生成签名访问链接。
-- 复制 OSS 对象，或为其它自媒体流程准备文件中转链接。
+- 上传图片、音频、视频、文档到 YuanFlow 文件中转。
+- 为已有文件对象生成签名访问链接。
+- 复制文件对象，或为其它自媒体流程准备文件中转链接。
 
 子 Skill 名称：
 
-- `OSS文件中转工具`
+- `YuanFlow文件中转工具`
 
 ### 11. 走 `自媒体浏览器自动化`
 
@@ -293,6 +295,34 @@ description: 当用户需要处理自媒体平台接口工作流、平台数据
 
 - `音视频在线转文字`
 
+### 19. 走 `视觉理解`
+
+遇到下面这些需求，优先进入这个子 Skill：
+
+- 用户提交图片、视频、本地媒体文件或媒体 URL，要求识别画面、描述内容、提取画面信息、检查视觉细节。
+- 用户要求对图片或视频做通用理解、画面总结、可见文字识别、场景判断或多媒体对比。
+- 用户明确要使用 `qwen3-vl-plus` 做图片/视频理解。
+
+这是通用型画面理解 Skill，只使用 `yuanflow-cli ai qwen3-vl-plus`。如果用户目标是自媒体对标、爆款复盘、脚本结构、镜头节奏或内容创作拆解，改用 `视频拆解`。
+
+子 Skill 名称：
+
+- `视觉理解`
+
+### 20. 走 `视频拆解`
+
+遇到下面这些需求，优先进入这个子 Skill：
+
+- 用户提交对标视频、本地视频或视频 URL，要求做自媒体创作方向的视频拆解。
+- 用户要求分析爆款结构、开头钩子、脚本节奏、镜头节奏、转化设计、可复用创作模板。
+- 用户希望从竞品视频、对标账号视频里提炼内容创作方法。
+
+这个 Skill 开始前必须先使用 `自媒体知识库` 查询与对标拆解相关的规则。如果用户提交的是视频 URL，先用作品解析/下载相关工具保存到本地，再通过 `yuanflow-cli ai qwen3-vl-plus --video-file` 上传拆解。
+
+子 Skill 名称：
+
+- `视频拆解`
+
 ## 多需求时怎么处理
 
 如果用户一次提了多段流程，不要强行塞进一个子 Skill，按阶段拆开：

package/skills/yuanflow-skill/{OSS → YuanFlow}/346/226/207/344/273/266/344/270/255/350/275/254/345/267/245/345/205/267/SKILL.md

@@ -1,12 +1,12 @@
 ---
-name: OSS文件中转工具
-description: 当用户需要把本地文件上传到 YuanFlow 临时 OSS、生成对象签名访问链接、复制 OSS 对象，或为自媒体工作流准备图片、音频、视频、文档中转链接时使用。
+name: YuanFlow文件中转工具
+description: 当用户需要把本地文件上传到 YuanFlow 文件中转、生成对象签名访问链接、复制文件对象，或为自媒体工作流准备图片、音频、视频、文档中转链接时使用。
 emoji: 🔗
 ---
 
-# OSS 文件中转工具
+# YuanFlow 文件中转工具
 
-这个 Skill 负责使用 YuanFlow 的 OSS 原子能力。它只处理文件中转、签名链接和对象复制，不负责社媒数据采集。
+这个 Skill 负责使用 YuanFlow 文件中转能力。CLI 内部兼容命令仍叫 `oss`，但对用户说明时统一称为 YuanFlow 文件中转。它只处理文件中转、签名链接和对象复制，不负责社媒数据采集。
 
 ## 环境判断
 
@@ -18,9 +18,9 @@ emoji: 🔗
 
 ## 能做什么
 
-- 上传本地图片、音频、视频、文档到临时 OSS。
-- 为已有 OSS 对象生成临时签名 URL。
-- 把一个 OSS 对象复制到另一个 key。
+- 上传本地图片、音频、视频、文档到 YuanFlow 文件中转。
+- 为已有文件对象生成临时签名 URL。
+- 把一个文件对象复制到另一个 key。
 - 为后续自媒体创作、发布、转写、封面处理等流程提供临时文件链接。
 
 ## 命令
@@ -37,7 +37,7 @@ yuanflow-cli oss temp-upload \
 可选参数：
 
 - `--filename`：指定上传文件名。
-- `--key`：指定 OSS 对象 key。
+- `--key`：指定文件对象 key。
 - `--content-type`：MIME 类型，默认 `application/octet-stream`。
 
 ### 生成签名链接

package/skills/yuanflow-skill/yuanflow-cli/SKILL.md

@@ -65,7 +65,7 @@ yuanflow-cli --help
 $env:YUANCHUANG_API_TOKEN="<你的令牌>"
 ```
 
-保存 Yuan API 令牌和服务地址：
+保存 YuanFlow API 令牌和服务地址：
 
 ```powershell
 yuanflow-cli config set-token <你的令牌>
@@ -113,10 +113,10 @@ yuanflow-cli schema douyin.video-detail
 
 | 错误码 | 含义 |
 | --- | --- |
-| `TOKEN_MISSING` | 没有配置 Yuan API token |
+| `TOKEN_MISSING` | 没有配置 YuanFlow API token |
 | `BAD_ARGUMENT` | 参数或命令写错 |
 | `AUTH_INVALID` | token 无效或权限不足 |
-| `UPSTREAM_ERROR` | 上游平台或服务报错 |
+| `PLATFORM_SERVICE_ERROR` | 平台服务或 YuanFlow API 报错 |
 | `NETWORK_ERROR` | 网络或超时错误 |
 | `INTERNAL_ERROR` | 未分类错误 |
 

package/skills/yuanflow-skill//344/275/234/345/223/201/344/270/213/350/275/275/347/273/274/345/220/210/345/267/245/345/205/267/SKILL.md

@@ -25,7 +25,7 @@ emoji: ⬇️
 - 用户给出抖音、B站、YouTube、西瓜视频链接或作品 ID。
 - 用户只想先确认作品是否有可用播放/下载地址。
 
-不要用于批量抓取、绕过平台限制、破解权限、去除平台风控、下载私密或未授权内容。该工具只返回上游接口提供的播放/下载地址候选或视频流信息；真正保存到本地文件如需后续执行，必须先确认用户授权和保存路径。
+不要用于批量抓取、绕过平台限制、破解权限、去除平台风控、下载私密或未授权内容。该工具只返回 YuanFlow API 提供的播放/下载地址候选或视频流信息；真正保存到本地文件如需后续执行，必须先确认用户授权和保存路径。
 
 ## 调用优先级
 

package/skills/yuanflow-skill//344/275/234/345/223/201/350/257/204/350/256/272/351/207/207/351/233/206/SKILL.md

@@ -164,6 +164,6 @@ Agent 不需要直接拼接口地址，只需要选对 `platform`、`action` 和
 - `TOKEN_MISSING`：提示先完成 YuanFlow KEY 认证或外部 CLI 环境变量配置。
 - `BAD_ARGUMENT`：检查平台、action、target、comment-id、cursor。
 - `AUTH_INVALID`：认证无效或权限不足。
-- `UPSTREAM_ERROR`、`NETWORK_ERROR`：说明上游或网络失败，可稍后重试，或在有备用能力的平台加 `--prefer fallback`。
+- `PLATFORM_SERVICE_ERROR`、`NETWORK_ERROR`：说明平台服务或网络失败，可稍后重试，或在有备用能力的平台加 `--prefer fallback`。
 
 不要展示完整 Authorization 请求头、token、cookie 或敏感账号信息。

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/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 小时，让用户裁剪或压缩。
+- 模型无法识别细节：按“可确认/不确定/建议人工复查”分开写，不要编造。