核心用法
video-understand 是一款命令行视频理解工具，通过集成 Google Gemini 和 Moonshot Kimi 的多模态大模型，赋予 AI Agent 深度解析视频内容的能力。核心工作流围绕 analyze → ask 展开：用户通过 analyze 命令上传本地视频（MP4/MOV/WebM 等）或提供 URL（YouTube/HTTP直链），并附带自然语言提示词获取结构化分析；系统会自动缓存文件内容哈希，避免重复上传。对于 YouTube 链接，Gemini 原生支持免下载解析，而 Kimi 需依赖 yt-dlp 先下载后上传。
工具提供丰富的输出格式控制：--timestamps 生成带时间戳的关键时刻定位，--json 输出结构化数据便于二次开发，-o 可将结果持久化到工作目录。ask 命令支持基于已上传文件的会话式追问，无需重新传输视频，upload/list/delete 则构成完整的文件生命周期管理。
显著优点
1. 双模型冗余设计：Gemini 与 Kimi 双后端可选，前者在 URL 场景下响应更快（免下载），后者在中文语境理解上表现优异
2. 零重复传输机制：基于内容哈希的缓存策略，大幅降低 API 调用成本与等待时间
3. URL 原生支持：Gemini 可直接消费 YouTube/HTTP 链接，省去本地存储与带宽消耗
4. 开发者友好：完整的 JSON 输出、环境变量优先的密钥管理、适合 CI/CD 的非交互模式
潜在局限
- Kimi 依赖外部工具：YouTube 分析需额外安装
yt-dlp，增加环境复杂度 - 文件时效差异：Gemini 文件约48小时过期，Kimi 虽持久但存在单账户存储总量限制
- 平台绑定风险：双模型均为商业 API，存在服务稳定性与区域可用性依赖
- 无本地推理选项：必须联网调用云端多模态模型，无法离线使用
适合人群
- 内容创作者：快速提取视频摘要、生成带时间戳的脚本大纲
- 学术研究者：批量分析访谈录像、实验视频，提取结构化观察数据
- 开发者/自动化工程师：构建视频内容审核、元数据标注等 Pipeline
- 语言学习者：通过
ask追问特定片段细节，辅助理解外语视频
常规风险
1. API 密钥泄露：配置存储于 ~/.video-understand/config.json，共享环境需权限隔离
2. 版权与隐私：上传 YouTube/第三方视频可能涉及版权争议，敏感内容分析需确认合规
3. 模型幻觉：多模态模型可能对复杂场景产生错误描述，关键场景建议人工复核
4. yt-dlp 供应链：Kimi 分析 YouTube 时依赖社区工具，需警惕非官方渠道下载的二进制风险