进阶 约 25 分钟 2026-10-17 02:23:48 · 27 阅读

watch-skill MCP 接入实操:给 AI 助手装上带时间戳的视频记忆

让 AI 助手「看」一段视频,常见的做法是把几帧截图丢给它,或者人工誊一份字幕——都费人力,而且追问一句就要重来一遍。watch-skill 这个开源工具(GitHub 仓库 oxbshw/watch-skill,PyPI 包名同名)的思路是给 agent 装一个视频输入通道:把任意视频源下载、抽帧、OCR、转写、建索引,之后所有追问都从持久索引里拿答案,并附带可以点开的时间戳。它还有一个更较真的分支——验证:用冻结的契约(文件摘要、JSON 值、SQL 结果、HTTP 响应、DOM 状态)由独立进程判定结果,判定词只有 VERIFIED、FAILED、UNVERIFIED、INCONCLUSIVE 四个,明确「不来自语言模型」。这篇教程覆盖两件事:把 watch-skill 装对,以及把它的 MCP 服务器接进你正在用的编程助手。工具生态总览见 总纲。

先看官方 README 的一句自我定位,原话是「Give AI agents eyes, ears, and verifiable results」——眼睛耳朵指感知(视频、音频、屏幕活动变成带绝对时间戳的帧、转写、OCR 文本),可验证的结果指上面那套契约判定。两个能力可以分开用,这个拆分是刻意的(原文 the split is deliberate)。同一个引擎有四条接入通道:MCP、CLI、REST API,外加一个叫 DeepWatch 的成品工作区(基于官方 DeepSeek Harness、预装 watch-skill 的浏览器工作台)。本篇聚焦 MCP 这条最通用的路。

安装:extras 决定你拿到多少

watch-skill extras 安装决策表

不同安装量对应的能力与缺口,以及官方 Start here 的免安装试用命令

README 在安装节写了一段很坦白的话,值得原样引在这里:

Take the extra seriously. A bare pip install watch-skill gives you the CLI, the verifier and the Bridge, and it cannot extract a frame: watch stops at perceive.missing_dependency on the first video.

翻译过来:裸装只有 CLI、验证器和 Bridge 协议,抽不了帧,第一个视频就会停在 perceive.missing_dependency。extras 体系是叠加式的:[standard] 补上帧提取、检索和 MCP 服务器;[ocr] 读屏上文字;[whisper] 给没有字幕的源加本地转写;[loop] 是浏览器回路;全都要就 [all]。哪个没装,watch-skill doctor 会点名并给出确切命令——这个自检命令后面还会反复出现。

版本口径以 PyPI 实查为准:当前最新 1.4.3,requires-python >=3.11,依赖只有 typer、pydantic、rich、httpx、pydantic-settings 五个轻量包。官方 Start here 给的免安装试用三连是 uvx --from "watch-skill[standard]" watch-skill doctor,然后 watch 一个视频、ask 一个问题。想装进 25 个以上 agent 的技能库,还有一条 npx skills add oxbshw/watch-skill -g(skills CLI 来自 vercel-labs/skills 开源项目)。

本机实测:裸装会缺什么

watch-skill 两轮安装实测终端记录

干净 venv 里的两轮真实安装:裸包 serve 报缺 fastmcp,补装后 MCP 握手成功

以下是在一台 x86_64 Linux 上用干净的 Python 3.12 venv 实际跑一遍的结果,结论比 README 还多一条:裸包不仅抽不了帧,连 MCP 服务器都起不来——执行 watch-skill serve 直接 ModuleNotFoundError: No module named 'fastmcp',因为 fastmcp 声明在 [standard](等同 [mcp])extras 里。补装 fastmcp<4,>=3.4 之后握手即通,serverInfo 返回 {"name": "watch-skill", "version": "1.4.3"},与 PyPI 版本一致。

握手成功的同时 stderr 打出一行警告:fastembed not installed — keyword-only search (install with "watch-skill[index]", ...)。这不是故障,是检索降级——缺语义索引组件时搜索自动退回关键词匹配,功能不中断。另外提示一句喂stdin的节奏:慢速管道发 JSON-RPC 时,initialize 与 tools/list 之间给足 9 秒以上间隔,响应就稳定。

39 个工具:实测清单长这样

watch-skill 39 工具分组实测清单

stdio 握手后 tools/list 的真实返回,按用途分组呈现;工具名逐字未改

很多聚合资料把 watch-skill 描述成「两个工具」——watch_video 和 watch_remember。实测 1.4.3 的 tools/list 返回 39 个工具,里面并没有 watch_remember;纠错与记忆相关的职责现在由 report_mistake 工具和 CLI 的 lessons 命令承担。README 里那句「stdio MCP server, 39 tools」与实测吻合。核心四件:

  • watch_video——首次看片:支持 yt-dlp 认识的 1800+ 站点、直链、HLS/DASH、本地文件,下载、场景感知抽帧(感知去重)、OCR、转写(先字幕后本地 Whisper)、建索引,返回报告与关键帧图片;追问同一视频时永远走 ask_video,不要重看;
  • ask_video——从持久索引回答追问,自带时间戳证据,答案不确定时会自行升级采样密度、缩放重 OCR,视频里没有答案时它会直说,别替它编;
  • get_moment——缩放到某个时间戳细看;
  • search_videos——跨所有已看过的视频搜短语。

外围工具按用途分几簇:THE LOOP 一族(loop_start/loop_iterate/loop_status 等)做「捕获-批评-修复-再捕获」的自迭代;直播一族(start_live_watch/observe_live/ask_live)处理直播流;取证一族(get_evidence、aligned_evidence、verify_contract)对应验证契约。空库状态下实测调用 stats,真实返回是两行:answers served: 0 和 tokens saved: ~0 vs raw-frame injection——后者也在提示这个工具的核心卖点:答案走索引而不是整包塞帧,token 是省着花的。

接入客户端:配置块与状态标签

watch-skill 客户端接入配置与验证状态

官方 agents 文档的三级验证状态与主流客户端配置原文

官方给 26 个客户端各写了一页接入文档,并按证据强度标三级:Machine-tested(真实会话端到端跑通)、Machine-configured(配置已写入且服务器完成 initialize 握手,会话内未跑)、Documentation-verified(配置与客户端官方文档一致并通过仓库校验器,未执行)。官方特意说明这些标签描述的是集成证据、不是产品质量。Claude Code 是目前唯一的 Machine-tested 档,官方记录里最后一次实跑是 2026-07-06:/watch 技能在会话内处理了一段 7 分钟的真实 YouTube 视频,doctor 绿灯、25 张场景帧、24 帧 OCR、字幕转写、索引全通,无人工干预。

接 Claude Code 一条命令:

claude mcp add watch-skill -- uvx --from "watch-skill[standard]" watch-skill serve

Cursor、Claude Desktop、Codex CLI 是 Machine-configured 档,配置是同款 JSON(全局写在 ~/.cursor/mcp.json 或 Claude Desktop 的 claude_desktop_config.json,项目级写 .mcp.json):

{
  "mcpServers": {
    "watch-skill": {
      "command": "uvx",
      "args": ["--from", "watch-skill[standard]", "watch-skill", "serve"]
    }
  }
}

pip 永久安装过的,把 command 换成 watch-skill、args 换成 ["serve"]。Zed 有个专档提醒:配置键是 context_servers 不是 mcpServers。官方的冒烟测试三步可以直接抄:重启客户端确认工具列表出现 watch-skill;让它看一个视频并问 0:10 处发生了什么;再追问一句看它是否走索引而不是重新下载。

冒烟测试用什么视频

官方文档所有示例用一个固定视频:YouTube 上的 Big Buck Bunny(aqz-KE-bpKQ)。选它有道理——公共素材、无版权顾虑、长度适中、画面里有一只鸟可以拿来追问(官方原例就是「what color is the bird?」)。照抄这个 ID 做第一次冒烟,排除了「视频本身看不了」这个变量,出问题就是配置问题。

隐私与边界

安全姿态在 SKILL.md 里写成四条硬规则,原文要点:视频文件本身永远不离开本机,只有显式加 --cloud-stt 时才可能把抽出的单声道 16kHz 音频送去云端转写;不碰 cookie 不碰登录态,只请求公开数据;API key 只活在环境变量和 .env 里,不进日志;下载缓存在 ~/.watch-skill/cache,LRU 淘汰、有容量上限。默认全链路离线——转写回退到本地 faster-whisper,不需要任何 API key。

几个如实的局限。默认安装没有语音分离(diarize 是独立 extra);检索降级为关键词匹配时不做语义召回(上一节 stderr 那行);DeepWatch 工作区那条线的 npm 端(@deepwatch/cli,当前 0.1.4)要求 Node ^22.19.0 或 >=24.0.0,比很多机器的默认 Node 新;浏览器回路([loop])需要 playwright,首次会拉浏览器二进制。工具数 39 个,客户端侧每次会话的工具清单加载成本自己掂量。

本文步骤与图片依据 oxbshw/watch-skill 官方 README 与 docs/agents 文档(2026-10-14 最近提交)整理,实测部分为本机 Python 3.12 venv 安装 watch-skill==1.4.3 + fastmcp 3.x 的真实输出,版权归原作者所有。

评论 (0)