Watch Skill：将视频变成 AI Agent 的眼睛

痛点：当 AI Agent 只会读文字

2025 年，Claude、GPT-4、DeepSeek 等大模型已经把代码生成和文本推理卷到了前所未有的高度。然而，当开发者试图让一个 AI Agent 去"看看"网页是否正常加载、视频里的人物说了什么、或者 UI 界面有没有 bug 时，一切都变得棘手起来——大多数 Agent 默认只有文字输入，无法感知视觉世界。

举一个真实场景：某团队用 AI Coding Agent（Cursor/Windsurf/Claude Code）开发 Web 应用，开发完成后想让 Agent 自动"看"一眼页面，确认按钮是否对齐、弹窗是否正常。现有方案要么依赖截图 API 的昂贵调用，要么干脆放弃视觉验证。watch-skill 正是在这个痛点上生长出来的开源工具——给任何 AI Agent 一双眼睛，让它能够"观看"视频、屏幕录制、直播流，并将视觉内容转化为可检索、可分析、可验证的证据。

核心功能：一个四阶段视觉处理管道

watch-skill 的本质是一个模块化的视频理解管道，由四个核心阶段组成，每一阶段都高度解耦，可独立使用：

1. Acquire（获取） — 支持 YouTube、直播流（HLS/DASH）、本地视频文件、网页截图等多种来源。工具内置自愈链路：优先用 yt-dlp 下载，遇到 extractor 失效时自动更新 yt-dlp 重试，还可以配置自托管 Cobalt API 绕过限制。所有下载内容进入内容寻址 LRU 缓存，重复请求直接命中缓存。

2. Perceive（感知） — 将视频切分为场景（PySceneDetect），按视频时长动态分配帧预算（最长 100 帧，512px），通过感知哈希（pHash）去重，保证每帧都是独特内容。然后对每帧运行 OCR（RapidOCR + ONNX），自动识别阿拉伯语、中文、西里尔文等多语言脚本，无需手动配置语言模型。

3. Transcribe（转录） — 采用阶梯式策略：优先提取平台自带字幕（原语言优先于机翻译文）→ 降级到本地 faster-whisper（支持离线，完全免费）→ 最后才是云端 STT（用户主动授权）。每一级的失败都会记录并自动尝试下一级。

4. Index（索引） — 所有内容存入 SQLite 数据库，用 FastEmbed 生成向量嵌入，支持语义搜索和跨视频检索。你可以问"这个视频里提到的部署命令是什么"，工具会直接返回时间戳和对应帧。

图：The Loop 工作流——Agent 执行 → Watch 捕获证据 → 批评者分析 → 修复 → 再次验证

交互方式：MCP、CLI、REST API 三种入口

watch-skill 不强制绑定任何特定 Agent，而是提供了三种薄薄的"入口"：

• MCP Server（fastmcp，stdio + 流式 HTTP）— 直接接入 Claude Desktop、Cursor Agents、Windsurf、OpenHands 等主流 AI Coding Agent，实现无缝集成。安装后告诉 Agent"我支持视频观察"，Agent 即可调用 watch 工具。
• CLI（typer 框架）— 本地开发者直接敲命令：watch-skill watch <url>、watch-skill ask "视频里演示了什么功能"、watch-skill loop（启动 UI 循环监控）。
• REST API（FastAPI + Uvicorn）— 适合在服务器端批量处理视频，或集成到现有 DevOps 流水线。

有意思的是，这三层入口永远不包含业务逻辑，核心逻辑全部在 src/watch_skill 下，入口只负责渲染结果——这保证了三种方式的输出完全一致，不会出现 CLI 和 MCP 行为不一致的坑。

类比理解：视频版的生活记忆系统

如果把 watch-skill 比作人类的记忆系统：Acquire 就像眼睛看到的画面，Perceive 是大脑识别出"这是会议室、这是代码编辑器"，Transcribe 是听清每个人说的话，Index 就是把这一切整理成一本可检索的日记。区别在于，这套系统 24 小时在线、永不遗忘，而且可以并行处理上百个视频。

技术亮点：本地优先 + 隐私硬编码

watch-skill 在设计上把隐私作为第一原则：视频文件永不离开本机，不登录、不使用 Cookie、不调用第三方追踪 API。OCR 模型和 Whisper 模型都可以完全本地运行（ONNX + faster-whisper），不依赖任何云端视觉 API。所有敏感数据路径都有测试覆盖（tests/transcribe/test_privacy.py）。

代码质量也值得称道：70+ 个测试模块覆盖感知、OCR、循环、API 等所有子系统，使用 ruff 进行代码风格检查，要求 Python 3.11+，类型提示完备。

框架生态集成

watch-skill 不只是单打独斗，还预置了与主流 AI 框架的集成适配器：

• LangChain（langchain-core 集成）
• CrewAI（多 Agent 协作场景）
• LlamaIndex（RAG 知识库场景）
• AutoGen（微软多 Agent 框架）
• OpenAI Agents SDK

开发者可以根据自己的技术栈选择最合适的方式接入，官方提供了 16 个完整可运行的 examples，从基础的"观看并提问"到高阶的"浏览器自动化验证"、"跨视频语义搜索"都有覆盖。

局限与争议

工具也有明显的局限性：本地 Whisper 模型对内存要求较高（至少 8GB RAM），GPU 加速能显著提升体验但非必须；OpenCV + PySceneDetect 的场景检测在低对比度视频（如昏暗室内录制）中效果一般；本地 OCR 模型库目前对部分少数民族语言支持有限。另外，由于这是一个相对垂直的工具（非通用多模态模型），用户需要理解"视频理解管道"的概念才能用好它。

行业意义：填补 Agent 视觉验证空白

watch-skill 的出现代表了一个趋势：AI Agent 正在从纯文本推理向多模态感知演进。它不追求做一个"通用视频理解大模型"，而是专注于"给 Agent 提供可信赖的视觉证据"这个细分场景。通过 MCP 协议，它天然适配了当前最活跃的 AI Coding Agent 生态（Claude Code、Cursor、Windsurf 等），有望成为 AI 辅助开发流程中视觉验证环节的事实标准。