video-understand

视频理解技能

使用 Gemini 模型理解视频内容。

工作流程

用户发送视频文件或视频 URL
→ 如果是本地文件：先检查上传缓存，再上传到文件 API
→ 如果本来就是 URL：直接复用 URL
→ 调用视频理解 API
→ 返回分析结果

当前主入口

• 主脚本：video_analyzer.py
• 推荐入口：run.sh（自动使用技能目录下的 .venv）

推荐通过 run.sh 调用：

# 基础用法
./run.sh <视频文件路径或URL>

# 自定义问题
./run.sh ./video.mp4 -q "这个视频的教学步骤是什么？"

配置文件

主配置文件：config.json

{
  "api_key": "${VIDEO_UNDERSTAND_API_KEY}",
  "api_url": "https://api.whatai.cc/v1/chat/completions",
  "model": "gemini-3-flash-preview-nothinking",
  "default_question": "请分析这个视频镜头，并按以下结构输出：\n\n1. 镜头内容：这一镜头拍到了什么\n2. 景别与机位：远景/中景/近景，平视/俯拍/仰拍等\n3. 运镜方式：固定、推、拉、摇、移、跟拍等；如无法判断请说明\n4. 人物与动作：人物状态、动作、互动\n5. 场景与道具：环境、物件、视觉元素\n6. 字幕与声音：字幕文案、旁白、音乐、环境声\n7. 氛围与作用：这个镜头传达的情绪，以及在整体内容中的作用\n\n要求：\n- 用中文输出\n- 不要编造细节\n- 看不清就明确说明\n- 保持简洁、客观、可用于后续汇总成分镜脚本",
  "stream": false
}

配置说明

• api_key：API 密钥，建议通过环境变量 VIDEO_UNDERSTAND_API_KEY 注入
• api_url：API 端点 URL
• model：模型名称，默认 gemini-3-flash-preview-nothinking
• default_question：默认提问
• stream：是否按配置透传到视频理解 API

目录边界

• 主链路源码：SKILL.md、config.json、run.sh、video_analyzer.py
• 本地私有配置：.env
• 本地运行环境：.venv/
• 运行缓存：runtime/upload_cache.json

可用模型

• gemini-3-flash-preview-nothinking（当前默认，速度快）
• 其他兼容视觉/视频理解的 Gemini 模型（按你的 API 服务支持情况调整）

触发场景

• 用户发送视频链接并问“视频讲了什么”
• 用户说“分析这个视频”
• 用户发送视频 URL 并询问内容
• 用户自定义问题（如“这个视频里的人在做什么？”）

注意事项

• 本地文件分析需要有效的 VIDEO_UNDERSTAND_API_KEY
• 建议始终通过 ./run.sh 调用，以确保使用技能目录内的 .venv
• 本地文件会先走上传缓存；URL 输入不会触发本地上传
• 当前脚本对本地上传文件设置了 20MB 限制；超过该大小会直接返回上传失败
• 上传缓存统一位于 runtime/upload_cache.json；旧根目录缓存会在读取时自动迁移
• .env 属于本地私有配置，不应提交
• 建议通过 run.sh 而不是直接切换解释器运行，减少环境漂移

返回处理

API 返回 JSON，默认提取 choices[0].message.content 作为回答。 如果上游接口报错，脚本会直接返回错误文本，便于在命令行快速定位问题。

子代理执行策略

• 默认执行模式：优先使用子代理独立执行；主会话负责接单、补齐必要上下文、控制范围，并在最后整合结果回报给用户。
• 适合交给子代理的任务：预计超过 30 秒的处理、多步骤流水线、多文件/多产物生成、批处理、审计、转写、总结、离线分析。
• 主会话保留职责：只在必要时追问关键缺口、确认边界、挑选最终结果，并把输出改写成面向用户的完成答复。
• 不建议默认交给子代理的情况：一次性极短任务、需要高频来回确认的对话、强依赖当前聊天即时上下文的动作。
• 回报节点：默认只保留“已受理 / 已开始 / 已完成 / 已失败”四类关键节点，避免刷屏。