观看视频 —— 理解而非归档
有人分享了一个视频并向你提问。两个钩子使这成为可能,但每个钩子本身都无法被直接发现——钩子没有语义匹配,所以当会话要求“观看这个”时,它会找不到任何东西并只能即兴发挥。这个缺口正是本技能存在的全部原因。
边界 —— 请先阅读此内容
此技能是“观看”而非“归档”。 其输出是会话中持有的理解,而非保险库产物。没有笔记、没有前置元数据、没有交叉链接、没有
_index更新、没有行动项路由。工作文件会存入临时路径 (/tmp),绝不会进入vault/。
/aios:ingest是归档管道——它存在的意义正是让将源文件转化为永久、结构化的保险库笔记成为一种带有约定的深思熟虑行为。如果操作者想要这个,请移交 (“希望我使用/aios:ingest将其归档,这样它会带着交叉链接进入reflections/ingests/吗?”) —— 不要在此处半途实现它。两条路径,一个边界,没有重叠。
因此,一次运行的流程是:将其放入上下文 → 执行请求的操作 → 提供选项,不要假定。 如果请求是开放性的(只是“观看这个”而没有具体问题),那么观看后,用两三句话说明内容,然后询问他们想要什么。不要制造一个无人要求的交付物。
使用哪个工具 —— 真正的决策
| 源类型 | 使用工具 | 原因 |
|---|---|---|
| 文档(PDF、docx、幻灯片、表格) | MarkItDown 或 document-skills | 不是此技能的工作;那些已有语义匹配 |
| 长音频/视频,音频足够 | hooks/transcribe.py | MarkItDown 一次性将音频发送给 Google Web Speech——对一句话还行,但对 49 分钟的访谈毫无用处 |
| YouTube,音频足够 | 优先使用 MarkItDown 字幕 | 比转录快得多;当字幕缺失或质量差时,回退到 transcribe.py |
| 屏幕携带信号 | 在转录文本之上使用 hooks/video-watch.py | 转录文本会丢弃每一帧:幻灯片、代码、图表、终端、屏幕上的文字 |
屏幕携带信号的情况包括:带幻灯片的演讲、截屏视频、代码演示、工具教程、带图表的教学,或任何*“如你所见”*会让你失明的内容。如有疑问,请询问——视觉扫描会占用实际时间。
命令
# 转录主干(设备端:ffmpeg → mlx-whisper large-v3-turbo,任意长度)
python3 ~/aios/hooks/transcribe.py <文件或URL> /tmp/watch-transcript.txt
# 视觉通道,叠加在转录文本之上——绝不能替代它
python3 ~/aios/hooks/video-watch.py <文件或URL> \
--transcript /tmp/watch-transcript.txt --reader ocr --code
读取器选择是唯一真正需要决定的标志:
--reader ocr— 通过 Apple Vision 逐字提取屏幕上文本。幻灯片、代码、终端以及任何需要精确引用内容的默认选项。 当帧中包含代码时,请添加--code。--reader vlm— Claude 视觉描述每一帧。适用于图表、流程图、架构图、UI——关注结构而非字面文本。--reader both— 当需要精确的文字和图像的含义时。每帧成本大约翻倍。
其余所有参数(--scene-threshold、--max-frames、--sample-every、--max-width、--phash-threshold)都有合理的默认值。仅当首次扫描明显稀疏或过于嘈杂时才调整它们;使用 --help 查看完整列表。
平台现实 —— 说明,不要硬碰
这两个钩子都要求 macOS / Apple Silicon(mlx-whisper,通过 hooks/ocr-image.swift 使用 Apple Vision)。在 Linux 或 Windows 上,请说明情况并回退到 MarkItDown,它在跨平台下处理 YouTube 字幕和短音频。不要让操作者眼睁睁看着命令失败才知道这个限制。
在执行耗时操作前设定预期
转录长录音并读取其帧需要数分钟而非数秒——一次 45 分钟的演讲加上视觉扫描是本技能中最繁重的操作。请提前说明预估时间并确认,尤其是视觉扫描。通常比蛮力更好的两个廉价策略:
- 始终优先获取转录文本。 它是语义主干,速度更快,而且通常能直接回答问题——此时视觉扫描就不必要了。
- 如果请求很具体(“她提到定价了吗?”),搜索转录文本而不是完整回读。
值得了解的故障模式
- 转录文本不等于视频内容。 如果操作者询问显示的内容,一个干净的但从未提及该内容的转录文本并非不存在的证据——它是使用了错误的工具。请运行视觉扫描或说明你还无法回答。
- YouTube 字幕可能是自动生成的并且是错误的(特别是名称、专业术语、数字)。如果引用内容很重要,在归因前请使用
transcribe.py进行验证。 - 不要引用你没读过的东西。 帧是根据场景变化采样并去重的,因此视觉扫描是样本而非完整记录。如果某个断言仅基于一帧,请说明该帧来自哪个时间戳。
- 临时文件就是临时的。 完成后清理
/tmp/watch-*,或说明你将其留在了哪里。切勿将其写入vault/。
移交
当材料证明值得保存时:
- 正确归档 → 使用
/aios:ingest(放入reflections/ingests/,使用{源}-{片段}命名,包含前置元数据、交叉链接,行动项路由到项目待办事项)。 - 它改变了项目状态 → 说明情况并提供更新该项目笔记。
- 它产生了可持久的洞见 → 应通过正常的会话结束路径放入保险库,而不是作为看视频的副作用。
观看是廉价且可重复的。归档是一个决定。请保持两者分离。