watch

/watch（Watch 技能）

你没有视频输入；这项技能会为你提供视频输入。它是 watch-skill CLI 的轻量封装——所有逻辑都在引擎中，因此这项技能在每种运行环境（Claude Code、Codex、Cursor 等）中的表现都相同。

这是经典 claude-video /watch 技能的即插即用升级版：调用方式相同，此外还提供持久化索引（ask 可在无需重新处理的情况下回答后续问题）、帧 OCR、基于场景的采样和感知去重、本地 Whisper（默认离线，无需 API 密钥），以及用于迭代改进自身输出的 THE LOOP（捕获 -> 评估 -> 修复 -> 重新捕获）。

步骤 0 — 预检（每个会话首次调用时）

watch-skill doctor --json

• 退出码为 0 → 静默继续。不要宣布设置正常。
• 非零 → JSON 会列出每项未通过的检查及其 fix。在 Windows/macOS/Linux 上，doctor 会自动将 ffmpeg 和 yt-dlp 引导安装到受管理的 bin 目录中；报告修复结果后，再运行一次。只有在修复后检查仍未通过时，才联系用户。
• 如果 watch-skill 本身不在 PATH 中：运行 pip install watch-skill（或 uv tool install watch-skill），然后重新运行 doctor。

采集、转录、OCR、索引或搜索均不需要 API 密钥：转录会回退到本地 faster-whisper。视觉合成和验证可以使用用户现有的 Anthropic、OpenAI、Gemini 或 OpenRouter 密钥，也可以使用可选的本地 Ollama 模型。Agent 和提供方彼此独立；请参阅 configuring-vision 技能。云端 STT 为可选功能（--cloud-stt），且只会上传提取出的单声道音频——视频文件绝不会离开本机。

步骤 1 — 观看

将用户输入解析为来源 + 可选问题，然后：

watch-skill watch "<source>" [--start T --end T] [--max-frames N] [--transcript-only]

• 支持 yt-dlp 支持的任何网站（1800 多个）、直接媒体 URL、HLS/DASH 清单（--duration 60 可限制直播流时长）和本地文件。
• --start / --end（SS、MM:SS、HH:MM:SS）会切换为对该时间段进行密集的重点采样——可用于“2:30 时发生了什么？”这类问题，也适用于超过约 10 分钟且用户关注某一片段的视频。
• --timestamps T1,T2,... 会固定提取转录中标记的时刻（“看这里”“如你所见”），避免这些时刻被视觉筛选漏掉。
• --transcript-only 会完全跳过帧（速度最快；存在字幕时无需下载视频）。
• --max-frames N 会收紧 token 预算（默认值按时长分档，硬上限为 100，最高 2 fps）。

报告会输出一行 Indexed: video_id ...、带有 t=MM:SS 时间戳的帧、OCR 文本和转录内容。

步骤 2 — 阅读帧

在同一条消息中阅读报告列出的所有帧路径（并行调用 Read），这样你就能按时间顺序一起查看它们。

步骤 3 — 回答

根据帧 + OCR + 转录内容作答，并引用时间戳。没有问题时 → 总结视频结构、关键时刻、值得注意的画面和语音内容。

后续问题 — 使用索引，而非重新处理

视频已建立索引。在本次或之后的会话中遇到任何后续问题时：

watch-skill ask <video_id> "<question>"      # self-healing answer + evidence
watch-skill search "<phrase>"                 # across every video ever watched

ask（v0.6）会优先以文本作答，并提供带时间戳的证据、置信度分数和一行 ~N tokens saved。如果不确定，它会自行升级处理（密集重新采样、放大裁剪后重新进行 OCR），并明确说明视频是否未清晰展示答案——请相信它拒绝作答的判断，不要在此基础上编造答案。只有当引擎希望你自行查看（或传入 --frames）时，才会列出帧路径；届时再阅读这些帧。对于已经建立索引的视频，后续问题绝不要重新运行 watch。

如果用户纠正了你对视频内容的回答，请报告该纠正，以便系统在本地学习：

watch-skill lessons add <video_id> "<question>" "<your wrong answer>" "<the correction>"

THE LOOP — 迭代改进自身输出

当用户要求你修复 UI/视觉输出并验证修复效果时：

watch-skill loop start "<url-or-screen:-or-file>" "<pass criteria>" [--script '<json steps>']
# ... you apply the suggested fixes ...
watch-skill loop iterate <loop_id>

评估结果会返回包含时间戳和建议修复方法的结构化问题。由你修改代码；循环只负责观察。通过后，它会生成修复前后对比的 MP4+GIF 证明。watch-skill capture "<target>" 会进行录制，但不做评估。

安全态势

• 视频文件本身绝不会离开本机。只有提取的单声道 16 kHz 音频可能会发送到云端 STT API，且仅在显式指定 --cloud-stt 时才会发送。
• 不使用 Cookie，不登录——只请求公开数据。
• API 密钥存储在环境变量 / .env 中，绝不会写入日志或回显。
• 下载内容会缓存在 ~/.watch-skill/cache 下（采用 LRU，限制缓存大小）。