/watch
你原本没有视频输入能力,这个技能为你提供了。一个 Python 脚本首先获取字幕,可选地下载视频,将帧提取为 JPEG 格式(场景感知模式,或 efficient 模式下的快速关键帧),获取带时间戳的文字记录(优先原生字幕,回退到 Whisper API),并打印帧路径。然后你 Read 每个帧路径以查看图像,并将它们与文字记录结合以回答用户的问题。
解析 SKILL_DIR(在任何命令之前执行)
下面的每个 python3 ... 命令都运行 SKILL_DIR/scripts/ 下的捆绑脚本。将 SKILL_DIR 设置为 包含此 SKILL.md 文件的目录的绝对路径——你的运行环境在 Read 结果中已告知你该路径。脚本始终与这个文件直接同级(SKILL_DIR/scripts/watch.py),在所有安装布局中都是如此:
Read ~/.claude/plugins/cache/claude-video/watch/<ver>/skills/watch/SKILL.md → SKILL_DIR=…/skills/watch
Read ~/.codex/skills/watch/SKILL.md → SKILL_DIR=~/.codex/skills/watch
Read ~/.agents/skills/watch/SKILL.md → SKILL_DIR=~/.agents/skills/watch
在每条命令中将 ${SKILL_DIR} 替换为该文字路径。这种方式适用于所有运行环境(Claude Code、Codex、Cursor、Gemini CLI 等),而无需依赖任何特定于运行环境的环境变量。在运行开始时进行一次验证:
SKILL_DIR="<你所 Read 的 SKILL.md 所在目录的绝对路径>"
if [ ! -f "$SKILL_DIR/scripts/watch.py" ]; then
echo "错误:在 SKILL_DIR=$SKILL_DIR 下未找到 scripts/watch.py" >&2
echo "请重新检查你所 Read 的 SKILL.md 所在目录,并将 SKILL_DIR 替换为该路径。" >&2
exit 1
fi
步骤 0 — 设置预检(每次调用 /watch 时运行,成功时静默)
Python 解释器: 此技能中所有 python3 ... 命令均适用于 macOS/Linux。在 Windows 上,请替换为 python——Windows 上的 python3 命令是 Microsoft Store 存根,无法运行脚本。
在会话中首次调用 /watch 时,使用结构化预检以便检测首次运行设置:
python3 "${SKILL_DIR}/scripts/setup.py" --json
根据两个字段进行分支处理:
can_proceed: true且first_run: false→ 设置已完成(用户可能有意跳过了 Whisper 密钥——这是允许的)。直接进入步骤 1,无需评论。first_run: true→ 真正的首次设置。按以下顺序执行:- 如果
missing_binaries非空,则首先运行安装程序(它在 macOS 上自动安装/在其他系统上打印命令——见下文)并确认二进制文件已就位。不要跳过此步骤直接进入偏好设置。 - 如有必要,再运行一次安装程序,以便创建
~/.config/watch/.env文件(它仅在文件不存在时写入模板,因此请先让它创建文件之后你再向其中写入任何值)。 - 鼓励用户提供 Whisper API 密钥并询问下面的观看偏好问题,然后将所选值写入
~/.config/watch/.env并设置SETUP_COMPLETE=true。
- 如果
can_proceed: false且first_run: false→ 之前已完成设置,但环境退化了(例如操作系统更改后出现missing_binaries)。运行安装程序进行修复,然后继续。不要重新询问偏好。
缺少 Whisper 密钥是鼓励修复,但非必须:在真正的首次运行时,即使二进制文件存在,status 也会显示为 needs_key——这是你鼓励提供密钥的提示,而不是障碍。
在同一会话的后续 /watch 调用中,使用静默检查:
python3 "${SKILL_DIR}/scripts/setup.py" --check
这是一个小于 100ms 的查找操作。退出码 0 表示可以运行 /watch——这包括已完成设置但没有 Whisper 密钥的用户(无密钥是允许的)。退出码 0 时脚本不输出任何内容——直接进入步骤 1 而不评论。不要向用户宣布“设置已完成”——他们不需要在每次交互时都看到状态消息。步骤 0 唯一可接受的对用户可见的输出是当需要修复时。
在非零退出时,按照下表处理:
| 退出码 | 含义 | 操作 |
|---|---|---|
2 | 缺少二进制文件(ffmpeg / ffprobe / yt-dlp) | 运行安装程序 |
3 | 真正的首次运行且没有 Whisper API 密钥 | 运行安装程序以创建 .env 文件,然后鼓励提供密钥(用户可能拒绝——使用 --no-whisper 继续) |
4 | 两者都缺失 | 运行安装程序,然后鼓励提供密钥 |
退出码 3 仅在用户尚未完成设置时触发。一旦写入 SETUP_COMPLETE=true,无密钥的安装返回退出码 0 并且永远不会再次提示。
安装程序是幂等的——可以安全地重新运行:
python3 "${SKILL_DIR}/scripts/setup.py"
在 macOS(带有 Homebrew)上,它会自动安装 ffmpeg 和 yt-dlp。在 Linux/Windows 上,它会打印出确切的安装命令供用户运行。它以 0600 权限创建带有注释占位符和默认观看设置的 ~/.config/watch/.env 文件。
如果安装后 API 密钥仍然缺失: 使用 AskUserQuestion 询问用户是否有 Groq API 密钥(首选——更便宜、更快)或 OpenAI 密钥。然后将其写入 ~/.config/watch/.env——设置匹配的 GROQ_API_KEY=... 或 OPENAI_API_KEY=... 行。如果他们不想设置 Whisper,则使用 --no-whisper 继续,并告诉他们没有原生字幕的视频将以仅帧的形式返回。
首次运行的观看偏好: 在安装程序创建 ~/.config/watch/.env 后,使用 AskUserQuestion 询问一个问题:
- 默认细节(单次选择)。以以下确切顺序将选项呈现为
AskUserQuestion选项——从最轻到最重——并保留balanced上的(recommended)标记,即使它不是第一个选项(不要重新排序将推荐选项放在首位):transcript— 无帧,仅文字记录(存在字幕时跳过视频下载)。efficient— 快速关键帧传递(上限 50)。balanced(推荐)— 场景感知帧(上限 100,默认)。token-burner— 场景感知,无上限(最高保真度;高令牌成本)。
直接将答案写入 ~/.config/watch/.env,设置裸键在其单独的行上——没有尾随内联注释(值后的 # 注释 可能会破坏解析):
WATCH_DETAIL=balanced
使用用户选择的值。如果他们跳过问题,则保留推荐的默认值。一旦处理完依赖项、API 密钥选择和此偏好,在同一个文件中写入或更新 SETUP_COMPLETE=true。当 SETUP_COMPLETE=true 时,不要再问此偏好的问题。
结构化模式(可选): python3 "${SKILL_DIR}/scripts/setup.py" --json 输出 {status, can_proceed, first_run, setup_complete, missing_binaries, whisper_backend, has_api_key, config_file, watch_detail, platform},其中 status 为 ready | needs_install | needs_key | needs_install_and_key 之一。status 描述理想状态(鼓励使用密钥,因此无密钥的首次运行显示为 needs_key);can_proceed 是操作门控(二进制文件存在 AND 密钥已设置 OR 设置已完成)。根据 can_proceed/first_run 决定是否运行;使用 status 决定鼓励什么。
在同一个会话中,你可以在后续的 /watch 调用中跳过步骤 0——一旦 --check 返回 0,环境在两次交互之间不会发生变化。
何时使用
- 用户粘贴视频 URL(YouTube、Vimeo、X、TikTok、Twitch 片段、大多数 yt-dlp 支持的站点)并询问相关内容。
- 用户指向本地视频文件(
.mp4、.mov、.mkv、.webm等)并询问相关内容。 - 用户输入
/watch <url-or-path> [question]。
推荐限制
- 最佳准确度:10 分钟以下的视频。 帧覆盖范围与时长成反比。
- 通用速率限制:2 fps。 即使预算或
--fps暗示更多,脚本采样速度也永远不会超过 2 fps。 - 帧上限由细节模式决定(
~/.config/watch/.env中的WATCH_DETAIL,或--detail),而不是单个全局上限:transcript→ 无帧efficient→ 最多 50(关键帧)balanced(默认)→ 最多 100(场景感知)token-burner→ 无上限(场景感知;超过 250 帧时会打印一个软警告)--max-frames N覆盖模式原本使用的任何上限。
- 按时长划分的全视频帧预算。 令牌成本随帧数增长,因此脚本按时长设定预算。此预算设置 fps 和均匀采样回退方案;场景感知选择可以填充到上述细节上限,以较低者为准:
- ≤30秒 → 约12-30帧
- 30秒-1分钟 → 约40帧
- 1-3分钟 → 约60帧
- 3-10分钟 → 约80帧
-
10分钟 → 最高到细节上限,稀疏分布(会打印警告)
- 如果用户给你一个长视频,考虑询问他们是否想要特定分段,然后再在稀疏扫描上消耗令牌。
如何调用
步骤 1 — 解析用户输入。 将视频源(URL 或路径)与用户提出的任何问题分开。示例:/watch https://youtu.be/abc 这个视频是什么语言的? → 源 = https://youtu.be/abc,问题 = 这个视频是什么语言的?。
步骤 2 — 运行观看脚本。 直接传递源字符串。除了正常引用外,不要自己进行 shell 转义:
python3 "${SKILL_DIR}/scripts/watch.py" "<source>"
可选标志:
--detail transcript|efficient|balanced|token-burner— 保真度/速度调节。transcript= 无帧(仅文字记录,存在字幕时跳过视频下载);efficient= 快速关键帧(上限 50);balanced= 场景感知帧(上限 100);token-burner= 场景感知,无上限。--start T/--end T— 聚焦于某个片段。接受SS、MM:SS或HH:MM:SS格式。当设置了其中任一时,fps 会自动缩放得更密集(见下文“聚焦于某个片段”)。--timestamps T1,T2,…— 在这些绝对时间戳(SS、MM:SS或HH:MM:SS)处各抓取一帧。在阅读文字记录后使用此功能,以捕获演示者强调的指示性时刻(“看这里”、“正如你所见”、“注意这个”),这些时刻单靠视觉选择可能错过。见下面的“文字记录提示帧”。--max-frames N— 覆盖预设上限以获得更紧凑的令牌预算(例如--max-frames 40)--resolution W— 更改帧宽度(像素,默认为 512;仅当用户需要阅读屏幕上的文本时才增加到 1024)--fps F— 覆盖自动 fps(上限为 2 fps)--out-dir DIR— 将工作文件保留在特定位置(默认:自动生成的临时目录)--whisper groq|openai— 强制使用特定的 Whisper 后端(默认:如果两个密钥都存在,则优先使用 Groq)--no-whisper— 完全禁用 Whisper 回退(如果没有字幕,则仅返回帧)--no-dedup— 保留近乎重复的帧。默认情况下,帧差异传递会删除与前一个保留帧视觉上近乎相同的帧(如静态幻灯片、屏幕录制、暂停的视频),以便帧预算用于不同的内容;报告的 Frames 行会注明丢弃了多少帧。仅在用户需要每个采样帧时才传递此标志(例如,判断细微的帧间运动)。
聚焦于某个片段(更高的帧率)
当用户询问特定时刻时——“2 分钟处发生了什么?”、“集中看 0:45 到 1:00”、“前 10 秒”——传递 --start 和/或 --end。脚本切换到聚焦模式预算,这比全视频预算更密集(仍然上限为 2 fps,并且仍受细节模式上限的约束——以下计数假设默认的 balanced 上限为 100;efficient 上限为 50):
- ≤5秒 → 2 fps(最多 10 帧)
- 5-15秒 → 2 fps(最多 30 帧)
- 15-30秒 → 约2 fps(最多 60 帧)
- 30-60秒 → 约1.3 fps(最多 80 帧)
- 60-180秒 → 约0.6 fps(100 帧,上限)
聚焦模式适用于以下情况:
- 用户明确命名的任何时刻/范围(“大约 2:30”、“开头”、“最后 30 秒”)。
- 任何时长超过约 10 分钟且用户的问题针对特定部分的视频——对相关片段运行聚焦模式比对整个视频进行稀疏扫描有用得多。
- 在全扫描后发现某个区域细节不足时重新运行。
文字记录会自动过滤到相同范围。帧时间戳是绝对的(视频的真实时间线,不是从开始算起的偏移量)。
示例:
# 1 分钟视频的最后 10 秒
python3 "${SKILL_DIR}/scripts/watch.py" video.mp4 --start 50 --end 60
# 聚焦 2:15 → 2:45,2 fps(60 帧)
python3 "${SKILL_DIR}/scripts/watch.py" "$URL" --start 2:15 --end 2:45 --fps 2
# 从 1h12m 到视频结束
python3 "${SKILL_DIR}/scripts/watch.py" "$URL" --start 1:12:00
步骤 3 — Read 脚本列出的每个帧路径。 Read 工具将 JPEG 直接渲染为图像供你查看。在单条消息中(并行工具调用)Read 所有帧,以便你一起看到它们。帧按时间顺序排列,带有 t=MM:SS 时间戳,方便你将其与文字记录对齐。
步骤 4 — 回答用户。 你现在有两方面的证据:
- 帧 — 每个时间戳屏幕上的内容
- 文字记录 — 每个时间戳所说的内容。报告的头部显示来源(
captions= yt-dlp 拉取的原生字幕;whisper (groq)或whisper (openai)= 由 API 转录)。
如果用户问了具体问题,直接回答并引用时间戳。如果他们什么都没问,则总结视频中发生的事情——结构、关键时刻、显著的视觉内容、口语内容。
这也适用于 transcript 细节模式:即使没有帧,也要像其他模式一样生成一个摘要——不要将完整文字记录粘贴到聊天中。综合结构、关键时刻和口语内容并附上时间戳;只引用关键语句。仅当用户明确要求时才提供原始文字记录。
步骤 5 — 清理。 脚本会在末尾打印工作目录。如果用户不会就此视频提出后续问题,请使用 rm -rf <dir> 删除它。如果他们可能会问,则将其保留在原处。
细节和帧
默认行为来自 ~/.config/watch/.env:
WATCH_DETAIL=transcript|efficient|balanced|token-burner(默认:balanced)
在
…
[翻译截断]