byted-kickart-video-analyzer

视频解析SKILL

📋 工具说明

核心功能

提供视频解析、视频分析、视频反解、视频分镜提取、视频元数据提取等功能，解析本地或网络视频文件，提取视频元数据（时长、分辨率）、视频分镜信息和内容分析。

可用命令

📥 视频获取方式

支持以下两种方式获取视频：

1. 本地文件：直接提供本地视频文件的绝对路径
2. 网络视频：先使用下载工具（如curl、wget或浏览器）将视频保存到本地，再提供本地路径进行反解

---

🚨 强制前置校验流程（必须按顺序执行，任意不通过直接终止流程）

所有用户请求必须先完成以下3步校验，不得跳过：

1. 火山鉴权校验

• 执行环境变量检查命令：

  echo "ARK_SKILL_API_BASE: $ARK_SKILL_API_BASE" && echo "ARK_SKILL_API_KEY: $ARK_SKILL_API_KEY" && echo "ACCESS_KEY_ID: $ACCESS_KEY_ID" && echo "SECRET_ACCESS_KEY: $SECRET_ACCESS_KEY"
  

• 判断鉴权结果（按优先级）：
  • 第一优先级（Bearer Token）：ARK_SKILL_API_BASE 和 ARK_SKILL_API_KEY 均为非空值 → 鉴权通过
  • 第二优先级（AK/SK签名）：ACCESS_KEY_ID 和 SECRET_ACCESS_KEY 均为非空值 → 鉴权通过
  • 鉴权不通过：执行以下引导方案

❌ 鉴权未配置时的引导方案

1. 引导用户直接在聊天中发送ACCESS_KEY_ID/SECRET_ACCESS_KEY内容：

   请你提供火山账号AK&SK，用于检查火山创作Agent是否已开通套餐和有可用的创点！

2. 收到用户发送的ACCESS_KEY_ID/SECRET_ACCESS_KEY后，执行配置命令：

   export ACCESS_KEY_ID=用户提供的ACCESS_KEY_ID值
   export SECRET_ACCESS_KEY=用户提供的SECRET_ACCESS_KEY值
   

3. 配置完成后告知用户：

   已完成AK&SK临时配置，当前配置仅在本次会话生效，不会持久化存储，请放心使用。

4. 后续所有相关脚本执行时，均会自动通过export指定这两个环境变量，确保鉴权正常，无需用户重复配置

2. 套餐有效性校验

• 步骤1：Python版本校验

  python3.12 --version || (echo "❌ Python 3.12+ 未安装，请先安装Python 3.12" && exit 1)
  

• 步骤2：依赖包安装校验

  python3.12 -m pip install -r ./scripts/requirements.txt
  

• 步骤3：执行套餐查询命令

  python3.12 -m ./scripts/plan.py
  

• 步骤4：结果处理逻辑
  • ✅ 套餐有效：返回结果中的 message 字段为有效截止时间（北京时间），校验通过
  • ❌ 套餐已过期：message 小于等于当前时间，引导用户开通套餐，终止流程
  • ❌ 接口调用错误：参考「错误处理规范」匹配错误码，向用户明确告知错误原因和解决方案，并且终止流程

3. 技能版本校验

• 步骤1：执行版本检查命令

  python3.12 -m ./scripts/upgrade.py
  

• 步骤2：解析返回结果 返回格式示例：

  {"code":"0","message":"success","data":"{\"install_command\":\"\",\"latest_version\":\"1.0.0\",\"latest_version_number\":100000000,\"update_message\":\"\"}"}
  

  • latest_version：最新版本号（如 "1.0.0"）
  • install_command：新版本安装指令
• 步骤3：版本对比逻辑
  • ✅ 当前版本 >= 最新版本：版本校验通过，继续后续流程
  • ⚠️ 当前版本 < 最新版本：执行以下更新询问流程
    1. 询问用户是否更新到最新版本：

       检测到技能有新版本 {latest_version}，是否更新？（是/否）

    2. 用户确认更新（是）：执行 install_command 安装新版本
    3. 用户不更新（否）：跳过更新，继续后续流程

---

🛠️ 视频解析执行流程

完整流程概览

用户请求 → 强制前置校验 → 用户输入收集 → 视频上传 → 视频解析 → 结果返回

前置准备

1. 确保输出目录存在：mkdir -p /tmp/openclaw/byted-kickart-video-analyzer/output
2. 生成唯一输出文件名：video_analysis_result_<timestamp>_<random>.json

执行步骤

1. 步骤0：强制前置校验（必须按顺序执行，任意不通过直接终止流程）

   • 执行「🚨 强制前置校验流程」中的所有校验步骤
   • ✅ 火山鉴权校验通过
   • ✅ 套餐有效性校验通过
   • ✅ 技能版本校验通过
   • 只有全部校验通过后，才能进入下一步

2. 步骤1：视频上传引导

   • 询问用户：「请先提供要解析的视频：可以发我视频tos链接，或上传 MP4/MOV 文件（≤60s、≤50MB、≥480p）」
   • 支持两种上传方式：
     • 本地文件：直接提供本地视频文件的绝对路径（如 /Users/user/video.mp4）
     • 公网URL：提供可直接访问的视频链接（如 https://example.com/video.mp4）

3. 步骤2：视频预处理

   • 若用户提供的是公网URL，先下载到本地：

     mkdir -p /tmp/openclaw/byted-kickart-video-analyzer/input
     curl -L -o /tmp/openclaw/byted-kickart-video-analyzer/input/downloaded_video.mp4 "<视频URL>"
     

   • 检查文件是否存在：ls -la /tmp/openclaw/byted-kickart-video-analyzer/input/downloaded_video.mp4
   • 检查文件类型是否为有效视频（仅支持MP4/MOV格式）：

     file /tmp/openclaw/byted-kickart-video-analyzer/input/downloaded_video.mp4 | grep -qE "ISO Media|MPEG v4|QuickTime" && echo "valid" || echo "invalid"
     

   • 若文件不存在或类型无效，终止流程并提示用户：

     文件不可用，请检查路径是否正确，或确认文件为有效视频格式（仅支持 MP4/MOV）

4. 步骤3：上传视频获取媒资信息

   • 执行 python3.12 ./scripts/upload.py --file <视频路径> 命令
   • 返回字段说明：

     字段	类型	说明
     id	string	媒资ID（唯一标识）
     url	string	视频访问URL
     duration	number	视频时长（秒）

5. 步骤4：解析媒资信息

   • 从上传输出中提取 id 作为媒资ID
   • 提取 duration 用于视频分析

6. 步骤5：执行视频解析

   • 执行以下命令：

     python3.12 ./scripts/analyze.py \
       --media-id <媒资ID> \
       --output /tmp/openclaw/byted-kickart-video-analyzer/output/video_analysis_result_<timestamp>_<random>.json
     

   • 重要：
     • --media-id 参数值为媒资ID（通过上传脚本获取）
     • --output 参数值为结果JSON文件的绝对路径；脚本会同时输出两个文件：
       • 格式化后的JSON文件：<output>.json（原始格式，用于SKILL消息模板渲染）
       • seedance格式JSON文件：<output>_seedance.json（符合seedance格式，用于视频生成）

7. 步骤6：解析结果

   • 读取结果文件：脚本会同时生成两个文件，均需读取并持久化
   • 持久化存储：将解析结果和两个输出文件路径（原始格式 + Seedance格式）持久化到会话上下文，供后续流程使用

8. 步骤7：询问输出格式

   • 询问用户：「解析完成！请选择输出格式：

     • 原始格式：适合查看详细解析结果
     • Seedance格式：适合用于视频生成

     请回复「原始格式」或「Seedance格式」」

   • 等待用户回复：根据用户选择决定后续输出方式

9. 步骤8：结果输出

   • 原始格式：读取 <output>.json 文件内容，使用「原始格式消息模板」输出
   • Seedance格式：读取 <output>_seedance.json 文件内容，使用「Seedance格式消息模板」输出

7.1 输出文件说明

脚本执行后会同时生成两个JSON文件：

7.2 原始格式文件结构（用于消息模板渲染）

字段提取路径（供Agent使用）：

分镜数据提取规则：

遍历 $.video_info.shot_breakdown 数组，每行分镜数据提取：

7.3 Seedance格式文件结构（用于视频生成）

Seedance格式文件用于视频生成，仅保留指定字段：

7.3.1 字段映射规则

7.3.2 完整格式示例

{
  "video_duration": 44.5,
  "product_title": "商品名称",
  "product_description": "商品描述",
  "shots": [
    {
      "shot_number": 1,
      "start_time": 0,
      "end_time": 2.2,
      "camera_language": "近景平视",
      "main_subject": "BB霜",
      "marketing_intent": "产品展示",
      "on_camera_speech": "口播内容",
      "voiceover_text": "旁白内容",
      "bgm": "背景音乐",
      "stickers": "花字字幕",
      "vocal_attributes": ["音色参数1", "音色参数2"]
    }
  ],
  "subject_definition": {
    "characters": "角色1,角色2",
    "props": "道具1,道具2",
    "voice": "key1:value1;key2:value2"
  }
}

Agent执行特殊要求

1. 超时设置：调用exec工具启动脚本时，设置≥180000ms（3分钟）的yieldMs
2. 友好提示：若脚本未立即返回结果，先回复用户："正在为您进行视频解析，任务执行时间可能较长，请您稍候~"
3. 异常处理：若脚本因超时/异常退出，立即使用持久化的Task ID调用任务查询接口确认后端状态，禁止直接判定任务失败

回复用户消息模板

【原始格式回复模板】

严格要求：视频信息、商品信息、分镜脚本、完整数据四个模块标题使用加粗格式，其余内容为普通正文，必须严格保留每一行的换行符！

解析完成后，使用以下模板回复用户：

🎬 链接解析成功，解析结果如下

---
**🔍 视频信息**
| 项 | 内容 |
| --- | --- |
| 视频时长 | {video_duration}s |
---
**🛍️ 商品信息**
✅ 商品名称： {product_title}
✅ 商品描述： {product_description}
---
**📸 分镜脚本**
| 分镜编号 | 时间 | 镜头语言 | 镜头主体 | 营销意图 | 口播 | 旁白 | BGM | 屏幕贴纸&字幕文案 | 字幕样式 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
{shot_table_rows}

---
**📋 完整数据：**
{raw_json}

新模板变量说明：

• {video_duration}：视频时长
• {product_title}：商品名称
• {product_description}：商品描述
• {shot_table_rows}：分镜表格行，每行格式为：| {shot_number} | {start_time}-{end_time}s | {camera_language} | {main_subject} | {marketing_intent} | {on_camera_speech} | {voiceover_text} | {bgm} | {stickers} | {text_style} |
• {raw_json}：完整解析结果（json格式）

---

【Seedance格式消息模板】

【全局开场】
视频时长：{video_duration}秒。

【主体定义】
角色:{role_id_list}
道具:{product_description}
音色:{role_list[*].vocal_attributes}

【时间轴分镜】
{start_time}-{end_time}:{main_subject}。镜头:{camera_language}。
角色台词:{on_camera_speech}
画外音:{voiceover_text}
音效:{bgm}
音乐:{bgm}
字幕:{stickers}

(下一段时间轴依次拼接...)

【约束】
{marketing_intent}

Seedance格式模板变量说明：

• {video_duration}：视频时长
• {product_title}：商品名称
• {product_description}：商品描述
• {start_time}：分镜开始时间
• {end_time}：分镜结束时间
• {main_subject}：镜头主体
• {camera_language}：镜头语言
• {on_camera_speech}：口播
• {voiceover_text}：旁白
• {bgm}：背景音乐
• {stickers}：花字&字幕
• {marketing_intent}：营销意图
• {role_list[*].vocal_attributes}：音色参数列表，逐条展示（每条格式为 音色{i}:{音色描述}，多条用换行分隔）
• {subject_definition.characters}：主体定义中的角色（来自 scene_info.subject_anchors 中的 character 类型）
• {subject_definition.props}：主体定义中的道具（来自 scene_info.subject_anchors 中的非 character 类型）
• {subject_definition.voice}：音色字典（来自 scene_info.voice，格式为 key1:value1;key2:value2）

---

⚠️ 错误处理规范

所有错误必须明确告知原因和可执行解决方案，禁止模糊提示！！！

---