VideoDB 视频感知技能
让 AI 编码代理一站式完成视频与音频的摄取、理解、检索、剪辑和实时推流，无需在本地拼装 ffmpeg。
亮点：明确要求用户自行设置VIDEO_DB_API_KEY且禁止技能代管密钥；权限声明为allowed-tools: Read Grep Glob Bash(python:*)，范围较克制。扣分：Bash(python:*)实质允许任意Python执行（含网络访问、文件读写），桌面/麦克风/系统音频捕获涉及高度敏感数据收集，文档未要求显式用户确认步骤，数据流向第三方云端(Videodb.io)的处理与留存虽有说明但缺数据保留/删除政策，无回滚机制说明。
文档高度自洽：包含轮询partial状态的边界处理、常见错误对照表、版本破坏性变更说明(SearchResponse vs SearchResult)、macOS-only等约束。但为静态评审，无已提交测试套件或CI运行证据覆盖关键路径，按校准规则封顶10分。
场景、输入输出、触发示例明确（canonical prompts），声明了边界（桌面捕获仅macOS、reframe耗时、计划限制功能）。扣分：核心功能完全依赖VideoDB海外云服务与console.videodb.io，对中国大陆网络可达性未做说明，也未提及中文语言支持；非适用范围仅部分覆盖。
文档分层良好（SKILL.md + reference/ + 具有渐进披露结构），仓库标注MIT。扣分：技能本身无版本号/changelog，维护责任与更新路径未在技能内声明，安装依赖说明存在但故障排查部分依赖外部SDK行为。
提供了从摄取到编辑的完整可操作代码路径，规避常见陷阱的指导附加价值明显（如.length字符串、Clip duration校验、force=True用法）。但静态评审无法验证输出可直接使用，且与直接调用SDK相比的边际价值部分来自文档整合，证据有限，按封顶规则不超过7。
引用了大量具体API行为与错误信息，具有可审计的主材料性质。但无第三方执行证据、无测试复现、无跨源佐证，多数声明只能视为作者陈述，封顶5分内给4分。
- 技能通过Bash(python:*)可执行任意Python代码，且支持屏幕/麦克风/系统音频捕获，使用前应确认用户知情并授权录制范围。
- 所有媒体与索引数据均上传至VideoDB海外云，敏感内容慎用；中国大陆网络可达性未经验证。
- 桌面捕获仅支持macOS；reframe等操作可能长时间阻塞，应使用片段限制或异步回调。
- 技能无版本号和变更记录，升级SDK时行为可能变化，建议固定videodb>=0.5.0版本并自行验证。
- 本评审为静态源码审阅，未执行任何代码，实际可用性需自行复现验证。
这个 Skill 能做什么，适合哪些场景？
VideoDB 官方提供的 Agent Skill，把服务端视频工作流接入 Claude Code 等编码代理。它覆盖完整的"看—懂—做"链路：摄取本地文件、URL、YouTube 或 RTSP 直播流，运行语音、场景、物体、OCR、品牌等分析器并建立可检索索引，再通过时间线编辑、字幕、配音和媒体生成产出结果，所有产出都附带可播放的 HLS 流链接。技能本体是一份详细的 SKILL.md 加参考文档和脚本，实际处理全部由 VideoDB 云端完成。需要 VideoDB API Key（含免费额度）和 Python 3.9+。
通过 videodb Python SDK 调用 VideoDB 服务端 API：上传本地文件、URL 或 RTSP 流并返回可播放链接；运行分析器（spoken_words、vlm、object_detection、ocr、brand_detection、activity_recognition 等）生成工件并逐一建立索引；用 search/semantic_search/query/aggregate/ask 检索带时间戳的片段和证据；在 Editor Timeline 上做剪辑、字幕烧录、文字/图片/音频叠加；调用 transcode/reframe 转码和调整画幅；生成图像、音频、配音等媒体资产；对桌面录屏（仅 macOS）和 RTSP 直播流做实时理解并触发事件告警。
- 开发者想让代理把一段 YouTube 或本地视频变成可分享的流媒体链接，而不自己搭转码管线
- 内容团队需要在长视频中按语义查找特定时刻（如"所有出现产品的场景"）并拿到带时间戳的片段
- 运营人员要为 TikTok/Instagram 等平台批量改写视频画幅（竖屏/方图）和分辨率
- 创作者需要自动生成字幕、翻译配音、叠加品牌水印并直接导出成片
- 安防场景用 RTSP 摄像头接入，代理实时监控画面并在检测到人进入时记录告警
- 桌面录屏用户希望录制会话并生成带证据链接的可行动总结
这个 Skill 有哪些优点和局限？
- 覆盖摄取、理解、检索、编辑、生成、推流的完整视频链路，接口统一
- 所有重计算在服务端完成，客户端无需安装 ffmpeg 等本地编码工具
- SKILL.md 写得非常细致：包含常见报错表、版本陷阱（如 SearchResponse 上的 .compile()）、v1/v2 索引迁移指引
- 附带丰富的 reference/ 文档和可运行代码示例，降低试错成本
- 支持沙箱运行开源权重模型（Gemma、Qwen、Whisper、FLUX 等）
- 提供免费额度和免费 API Key，无需信用卡
- 强依赖 VideoDB 云服务和 API Key，属于付费 SaaS（超出免费额度后产生费用），不适合完全离线场景
- 桌面录屏捕获仅支持 macOS
- reframe 对长视频是慢速服务端操作，可能超时，需限定片段或走异步回调
- 部分功能（如 generate_video、create_collection）受套餐限制
- 源材料未提供测试套件或独立基准数据，实际效果需自行验证
如何安装这个 Skill？
在 AI 编码代理中执行 npx skills add video-db/skills，或使用 Claude Code 插件：/plugin marketplace add video-db/skills 然后 /plugin install videodb@videodb-skills。随后对代理说"setup videodb"，它会引导安装 SDK（pip install "videodb[capture]" >=0.5.0 python-dotenv）并验证连接。API Key 需用户自行在 https://console.videodb.io 注册获取（免费额度），通过 export VIDEO_DB_API_KEY=sk-xxx 或项目 .env 文件设置；技能明确要求代理不得代为处理密钥。
如何使用这个 Skill？
直接用自然语言向代理下达任务，技能会自动加载。示例指令："Ingest this file and return a playable stream link"；"Index this folder and find every scene with people, return timestamps"；"Generate subtitles, burn them in, and add light background music"；"Start desktop capture and alert when a password field appears"。技能会生成内联 Python 代码调用 videodb SDK（要求先 cd 到项目目录以加载 .env），参考文档位于技能目录的 reference/ 下。
这个 Skill 与同类方案有什么区别？
SKILL.md 明确对比了本地工具链：要求在 VideoDB 支持的操作上不要使用 ffmpeg、moviepy 或本地编码工具，仅速度调整、裁剪/缩放、调色、关键帧动画等少数场景回退本地工具。也就是说它是"云端视频处理 API"与"本地 ffmpeg 拼装"之间的替代方案。