/watch

为智能体提供视频证据：URL 或本地文件会转换为带时间戳的帧和转录稿。你可以将它安装在 Claude Code（桌面应用、VS Code 或终端）中，也可以搭配 Codex 及其他 Agent Skills 宿主应用使用。原生字幕优先；对于没有字幕的视频，可选择本地 WhisperX 或 Groq/OpenAI 转录。

选择你的应用

正在使用 Claude？请在 Claude Code 中运行 Watch。 通过 Claude Desktop 安装并使用 Code 会话，或在 VS Code 或终端中使用插件命令添加。Watch 无法在 Claude Chat 或 Cowork 中使用；了解原因。

为你的智能体选择一种安装方式。如果已经安装 Watch，可直接前往你的第一个视频。

Claude Desktop — Code

1. 打开 Claude Desktop，并在侧边栏中点击 Customize。
2. 选择 Plugins，打开 Add，然后选择 Add marketplace。

3. 选择 Add from a repository。

4. 在 URL 中粘贴下方地址。如果打开选择器，请将其搜索框中粘贴该地址，并针对该 URL 选择 Use。点击 Sync。

https://github.com/bradautomates/claude-video

5. 在已添加的插件市场中找到 Watch 并安装它。仅添加插件市场并不会安装 Watch。
6. 启动一个 Code 会话，并让它使用 watch 技能。Watch 无法在 Cowork 任务中使用（原因）。继续你的第一个视频。

如果你看不到这些控件，请更新 Claude Desktop。在受管账户中，管理员可能会控制你可以添加哪些插件。请参阅官方插件指南。

截图仅显示安装控件。标签可能因应用版本不同而略有差异。

Codex

在桌面应用、CLI 或 IDE 扩展中，将以下内容粘贴到 Codex 的消息框：

Use $skill-installer to install the watch skill from:
https://github.com/bradautomates/claude-video/tree/main/skills/watch

请让 Codex 完成安装，然后开启新的对话轮次或会话，并让它使用 watch。如果该技能没有显示，请重启 Codex。采用这种方式不需要 Node/npm。请参阅 OpenAI 的技能安装指南。

codex plugin marketplace add bradautomates/claude-video
codex plugin add watch@claude-video

codex plugin list --marketplace claude-video

继续前往你的第一个视频。

在 VS Code 中使用 Claude Code

1. 在 VS Code 中打开 Claude Code 面板。
2. 在 Claude Code 消息框中输入 /plugins，打开 管理插件。
3. 选择 插件市场，并添加 bradautomates/claude-video。
4. 返回 插件，找到 watch，选择 为你安装，即可在所有项目中使用。
5. 按提示完成激活或重启。然后输入 /watch，选择推荐技能——通常为 /watch:watch——或让 Claude 按名称使用 watch。

该扩展自带图形化安装程序；你无需切换到终端。其插件配置与本地 Claude Code CLI 共享。官方 VS Code 说明

继续前往你的第一个视频。

在终端中使用 Claude Code

打开终端，使用 claude 启动 Claude Code。请在 Claude Code 会话内 逐条输入以下内容：

/plugin marketplace add bradautomates/claude-video
/plugin install watch@claude-video

请按照激活提示操作。如果 Watch 功能尚未可用，请新建一个 Claude Code 会话。输入 /watch，并从自动补全中选中 /watch:watch。官方安装指南

claude plugin marketplace add bradautomates/claude-video
claude plugin install watch@claude-video

继续体验你的第一个视频。

其他本地智能体

对于其他 Agent Skills 宿主，如有需要，请先安装 Node.js，然后在你的电脑终端中运行：

npx skills add bradautomates/claude-video -g --skill watch

按提示选择你的智能体，按照安装器提示的目标位置操作，然后重启智能体。此安装器需要 Node/npm，Watch 的 Python 运行时则不需要。

你可以显式指定目标智能体，例如 -a codex，但 Codex 用户也可以使用更简单的消息框安装。参见Skills CLI 文档。

体验你的第一个视频

最快的路径——让 Gemini 来观看。 获取一个免费的Google AI Studio 密钥。当设置向导提示输入时，将密钥粘贴到聊天中；或者让智能体在你的文本编辑器中打开 ~/.config/watch/.env，以便你将密钥粘贴到 GEMINI_API_KEY= 之后并自行保存。随后，Watch 会将完整视频——画面和声音——交给 Google 的智能体式视频模型，并转达其带时间戳的回答。YouTube 链接无需额外安装任何内容。本地文件会被上传到 Google，并在回答后删除。

没有密钥，或视频是私有的？ 选择 local。Watch 会在你的机器上提取视频帧和字幕（ffmpeg + yt-dlp），与之前完全相同。随时可使用 --engine local 强制启用。下面的操作指南使用这种无需密钥的路径。

1. 让智能体访问一个包含短视频的文件夹，例如 example.mp4。将该文件夹作为智能体的项目打开。将下文中的文件名替换为你自己的文件名。
2. 将以下内容粘贴到智能体的消息框中：

Use the watch skill on example.mp4 in the folder I shared.
For setup, choose balanced detail and captions only (none).
Summarize what is visible, with timestamps.

3. 让智能体检查它的工具。如果它报告缺少某个程序，请按照下面的缺少工具？ 处理，然后重试。

成功的表现应是一份带时间戳的视觉摘要。 首次运行无需转写 API 密钥或本地语音模型。禁用了语音回退的本地文件不会生成语音转写文本。智能体会自行找到其内置脚本；你无需定位 plugin-cache 文件夹。

接下来，尝试一个公开视频 URL，并请求转写详情。无需下载视频即可读取原生字幕。URL 可访问性取决于来源以及当前会话的网络权限。

之后，你可以添加语音转写。本地 WhisperX 需要 Watch v0.3.0 或更高版本；如果你安装的版本是 v0.2.0，请在新版本发布后再更新。

缺少工具？

Watch 使用 Python 3.10+、FFmpeg/ffprobe 和当前版本的 yt-dlp。YouTube 还需要受支持的 JavaScript 运行时/EJS 配置。安装该 skill 会向智能体提供说明和脚本；它不会捆绑这些程序。

首先，询问你的智能体：

Use the watch skill's bundled setup.py to check dependencies in this session.
Tell me which tools are missing and help me install them here.

云会话（如 Web 版 Claude Code）：让智能体在其执行环境内部进行检查。通过 Homebrew 在 Mac 上安装 FFmpeg，并不会把它安装到云沙箱内部。包权限和网络权限可能需要管理员协助。新的云任务可能也需要重新完成设置。

直接运行在你电脑上的智能体： Watch 可以通过 macOS 上的 Homebrew 安装缺失的媒体工具。在其他系统上，它会提供相应命令。如果需要手动安装，请在终端中运行相应命令：

安装完成后，请重新打开终端和智能体，以便它们能找到新工具。在 Windows 上，可使用 python --version 或 py -3 --version 验证 Python。Watch 仅支持 最新版本的 yt-dlp，因为网站经常导致旧版失效；它使用当前活动环境中可用的可执行文件。

Chat、Cowork 和浏览器应用

Watch 适用于 Claude Code： Claude Desktop 中的 Code 会话，或使用插件命令在 VS Code 或 终端 中安装的 Claude Code。Codex 以及其他 本地智能体 也可用。

请参阅 Web 版 Claude Code 和 OpenAI 插件界面 的官方指南。

选择引擎

在 Gemini 运行中，YouTube 链接会直接发送给 Google；其他链接会通过 yt-dlp 下载，并且与本地文件一样上传到 Google 的 Files API，回答完成后删除（无法删除的上传会在 48 小时内过期）。--start/--end 会将 Gemini 限制在该范围内。帧和转写选项（--detail、--fps、--whisper……）仅适用于 local 引擎，并会显示为已忽略。Watch 不会自行切换引擎：Gemini 失败会连同其类别一起报告，是否使用 --engine local 重新运行由你决定。本 README 其余部分介绍 local 引擎。

选择转写回退方案

首次运行的向导会询问你的详细程度偏好和回退后端。可以先从 none 开始，以快速获得视觉结果；需要时再选择语音后端。在任何选择下，字幕都保持优先。设置会保存在执行环境中，因此临时云会话可能需要重新配置。

现有 0.2.0 用户保留 auto：优先使用 Groq 密钥，其次使用 OpenAI。不会自动迁移到本地推理。显式指定 --whisper groq|openai|whisperx 会覆盖本次运行的回退方案，而 --no-whisper 会禁用所有回退方案，但仍允许使用原生字幕。这两个 flag 相互冲突。

设置保存在 ~/.config/watch/.env 中。请私密地在此处或进程环境中输入密钥；不要提交它们，也不要粘贴到公开 issue 中。云密钥查找首先遵循 provider 偏好，然后针对每个 provider 按 environment → user file → cwd .env 的顺序查找。显式指定的 provider 绝不会借用其他 provider 的密钥。配置文件支持 UTF-8、UTF-8 BOM 和带 BOM 的 UTF-16；引号、注释以及字面 Windows 路径可正常使用，无需 shell 展开。最后一个赋值生效。

受管 WhisperX

WhisperX 会在 agent 执行脚本的任意位置运行。在本地会话中，推理在你的电脑上运行；在云端会话中，推理会在云端主机上运行。它可以避免使用单独的转录 API，但云端执行不会将音频保留在你的设备上。

请让 agent 运行内置的 setup.py --install-whisperx（或 --backend whisperx --detail balanced）。它会在需要时准备 uv，安装 Python 3.12 和 WhisperX 3.8.6，并转录两秒静默音频以预热 Whisper 和 Silero 缓存。安装器不会使用 sudo。基础 watch 流程保持仅依赖标准库，并可独立使用更新的 Python。

用户会基于这些要求自行选择；向导不会检查硬件、内存、磁盘或浏览器会话。

默认值为 small、cpu、int8，批处理大小为 8，不启用对齐或说话人分离。片段时间戳会被保留。在参考测量中，small 在 Apple M5 Pro 上处理 69 秒英文音频耗时 9.6 秒；更慢的 CPU 和更长的录音会需要更长时间。

WATCH_WHISPER_BACKEND=whisperx
WATCH_WHISPERX_MODEL=small
WATCH_WHISPERX_DEVICE=cpu
WATCH_WHISPERX_COMPUTE_TYPE=int8
WATCH_WHISPERX_BATCH_SIZE=8
# WATCH_WHISPERX_LANGUAGE=es
# WATCH_WHISPERX_TIMEOUT=1800

安装程序会写入绝对的 WATCH_WHISPERX_BIN 路径。虚拟环境位于 ~/.cache/watch/whisperx-venv，并在 watch-install.json 中记录 .deps-ok 哨兵文件和已解析的包列表。如果安装中断且没有哨兵文件，将安全地重建。模型缓存通常位于 ~/.cache/huggingface 和 ~/.cache/torch/hub 下；uv 也会缓存 wheel 包和 Python。它们都在插件之外，因此更新技能不会删除它们。

对于非英语音频，请设置口语语言提示（例如 WATCH_WHISPERX_LANGUAGE=es），或尝试 WATCH_WHISPERX_MODEL=large-v3 并重新运行安装程序。Large-v3 的下载量约为 2.9 GB，参考测量中峰值进程内存约为 6 GB。Small 在没有提示时可能误判非英语语音。字幕翻译请求（--sub-lang）永远不会被用作口语语言提示。当 alignment 被禁用时，WhisperX 3.8.6 的 JSON language 字段并不可靠，因此自动检测会报告为 unverified。

本地推理没有默认超时；WATCH_WHISPERX_TIMEOUT 接受正数秒。失败或取消时，绝不会切换到云端转录。CUDA 可配置，但未经测试；不承诺支持 MPS。对于该 CLI 解码路径，会抑制新版 FFmpeg 中的 TorchCodec 导入警告；请勿仅因该警告而降级 FFmpeg。

细节与重点

使用 WATCH_DETAIL 作为已保存的偏好设置，或使用 --detail 仅对单次运行生效。下文的 /watch 示例是简写：在 Claude Code 插件中，选择 /watch:watch；在其他宿主中，请让 watch 技能应用相同选项。通常，视频时长在 10 分钟以内或聚焦于某个时间段时，准确性最佳：

/watch video.mp4 --start 2:15 --end 2:45
/watch video.mp4 --detail efficient --max-frames 30
/watch video.mp4 --detail transcript --timestamps 1:05,2:30

均匀采样会在区间内选取实际源帧，并降低采样速率以适配剩余额度（最高 2 fps）。场景/关键帧选择会先在区间内检测候选帧，然后按上限采样。最后选中的候选帧不一定就是视频的最后一帧；场景切换无法捕捉所有事件。帧时间戳以源视频为基准，包含聚焦 seek 和分数 seek。

16×16 RGB 缩略图处理会基于通道平均差值移除近似重复帧。对于细微的视觉变化，可使用 --no-dedup；极小的缩略图无法保留每一次代码编辑。默认图像宽度最大 512px，高度最大 1998px；--resolution 1024 对屏幕文字更有帮助。图像成本取决于 host/model 和帧尺寸。

在阅读转录文本后，代理可以使用 --timestamps 固定“请查看这里”的时刻。这些时刻会优先占用帧预算。仅字幕处理可能不会下载视频；在这种情况下，cue 处理会再次使用该 URL。仅音频下载无法提供 cue 帧。

字幕、认证和部分结果

自动字幕选择会在可用时使用原始语言证据，优先选择同语言人工字幕，其次才是原始 ASR。它最多请求一个轨道。来源未知时会标记为 unknown。--sub-lang CODE / WATCH_SUB_LANG 用于显式选择语言，该语言可能是译文。

认证需主动启用：

/watch https://example.com/video --cookies /path/to/cookies.txt
/watch https://example.com/video --cookies-from-browser firefox

每次只使用一种 Cookie 机制，或保存 WATCH_COOKIES_FILE / WATCH_COOKIES_FROM_BROWSER。Cookie 文件是一个可读写 jar；yt-dlp 可能会更新它。浏览器访问可能因锁定或加密的存储而失败，尤其是在 Windows 上的 Chromium；Firefox 可能是替代方案，但不保证成功。Watch 不会自动搜索浏览器会话。现有 yt-dlp 代理、CA、运行时和身份验证配置，在未明确覆盖时保持有效。

新建的下载目录可防止来自失败源的过期文件被重复使用。媒体必须成功完成并报告其最终路径；部分文件和合并组件文件会被拒绝。成功获取的字幕即使在下载、解码或探测失败时也会保留。报告会区分证据不可用、无语音，以及带有缺失时间间隔的失败云分块。仅仅因为某个请求静默区间的字幕位于范围之外，不会触发回退。

云上传使用 24,000,000 字节的文件预算，并执行 multipart 和实际分块检查。本地 WhisperX 会使用整个提取出的音频文件。不会自动执行 provider/client/cookie 轮换。

更新与故障排查

使用安装 Watch 时相同的方法更新它，然后开始新会话：

市场自动更新行为取决于宿主和你的设置。更新 Watch 与更新其媒体工具是相互独立的。

保持 yt-dlp 处于最新发行版。使用其所属安装器更新，然后使用 yt-dlp --version 验证同一个可执行文件：

• Homebrew: brew upgrade yt-dlp
• pipx: pipx upgrade yt-dlp
• 专用 Python 环境: python -m pip install -U "yt-dlp[default,curl-cffi]"
• winget: winget upgrade --id yt-dlp.yt-dlp --exact

yt-dlp -U 并不是通用的包管理器更新命令。参见上游安装和EJS 指南。

让 agent 运行随附的 setup.py --json，以查看已解析的路径/版本、JS 运行时是否存在、模拟目标以及本地后端就绪情况。诊断不会联系视频服务。EJS 是否存在可能仍未知；它属于实际的 yt-dlp 发行版，而不是 watch 的 Python。setup.py --check 速度很快，成功时保持静默，并且从不导入 Torch。

开发与打包

python3 -m venv .venv
.venv/bin/python -m pip install pytest
.venv/bin/pytest -q

测试使用隔离的配置目录和 FFmpeg 合成的媒体文件；不会使用服务商密钥或调用线上服务。离线 yt-dlp 集成测试需要其 CLI。CI 在 Linux、macOS 和 Windows 上运行，使用真实的 FFmpeg/ffprobe，并作为由标签触发的发布任务的门禁。

如需手动安装，请创建宿主环境的技能目录，并将 整个 skills/watch/ 文件夹 符号链接或复制到其中。Windows 用户可以复制该文件夹，或使用目录联接。请勿将 SKILL.md 与其同级的 scripts/ 拆分，也不要添加重复的命令封装。

bash skills/watch/scripts/build-skill.sh 会基于已提交的 HEAD 构建 dist/watch.skill，并拒绝在存在已跟踪文件未提交更改时继续。可以从临时暂存目录预览未提交的代码。打包产物不包含规划文档、环境或模型权重。有关仓库结构和发布规则，请参阅 AGENTS.md。

数据与清理

WhisperX 会在代理的执行环境中处理音频：本地执行时在您的计算机上，云端执行时则在服务商的基础设施上。设置过程会从包和模型托管源下载包/模型，并禁用遥测。预热缓存的推理可以离线运行，但上游缓存检查仍可能尝试访问网络。云后端只会将提取的音频发送到所选服务商。视频内容仅作为证据，绝不作为可执行指令。

Watch 会创建一个可丢弃的运行目录，即便位于用户指定的任意 --out-dir 之下也是如此。清理操作只删除该子目录，保留用户目录和原始媒体文件。模型环境/缓存和私有配置会单独保留。API 密钥不会被记录，也不会包含在报告中。

采用 MIT 许可。请参阅 LICENSE。