Communitygithub.com

The-AIOS/aios — 视频/音频理解

实际观看或收听视频/音频源并将其保留在上下文中,以便你能就其内容提问、总结、引用或执行操作——这是一种快速理解行为,而非文件归档管道。涵盖 Claude 无法自行发现的本地媒体钩子。

aios — 视频/音频理解 是什么?

此技能让 AI 助手能够实时观看或收听视频/音频内容(包括本地文件或 YouTube 链接),并将其理解放在对话上下文而非文件归档中。它提供两个关键钩子:`hooks/transcribe.py` 用于设备端长音频转录(使用 mlx-whisper),`hooks/video-watch.py` 用于视觉通道——可识别幻灯片、代码、图表、终端文本等转录文本无法捕获的信息。用户只需分享视频或链接并提问,助手即可快速理解、总结或提取信息。该技能专门为 macOS/Apple Silicon 设计,在 Linux/Windows 上会回退到 MarkItDown。它强调效率:先获取转录文本,若问题较窄则搜索而非完整阅读,并在执行耗时操作前设定预期。重要的是,此技能仅用于理解,不创建笔记或更新索引;若用户需要永久保存,应使用 `/aios:ingest` 管道进行正式归档。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/The-AIOS/aios/tree/HEAD/skills/aios/watch-video

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

观看视频 —— 理解而非归档

有人分享了一个视频并向你提问。两个钩子使这成为可能,但每个钩子本身都无法被直接发现——钩子没有语义匹配,所以当会话要求“观看这个”时,它会找不到任何东西并只能即兴发挥。这个缺口正是本技能存在的全部原因。

边界 —— 请先阅读此内容

此技能是“观看”而非“归档”。 其输出是会话中持有的理解,而非保险库产物。没有笔记、没有前置元数据、没有交叉链接、没有 _index 更新、没有行动项路由。工作文件会存入临时路径 (/tmp),绝不会进入 vault/。

/aios:ingest 是归档管道——它存在的意义正是让将源文件转化为永久、结构化的保险库笔记成为一种带有约定的深思熟虑行为。如果操作者想要这个,请移交 (“希望我使用 /aios:ingest 将其归档,这样它会带着交叉链接进入 reflections/ingests/ 吗?”) —— 不要在此处半途实现它。两条路径,一个边界,没有重叠。

因此,一次运行的流程是:将其放入上下文 → 执行请求的操作 → 提供选项,不要假定。 如果请求是开放性的(只是“观看这个”而没有具体问题),那么观看后,用两三句话说明内容,然后询问他们想要什么。不要制造一个无人要求的交付物。

使用哪个工具 —— 真正的决策

源类型使用工具原因
文档(PDF、docx、幻灯片、表格)MarkItDown 或 document-skills不是此技能的工作;那些已有语义匹配
长音频/视频,音频足够hooks/transcribe.pyMarkItDown 一次性将音频发送给 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/,使用 {源}-{片段} 命名,包含前置元数据、交叉链接,行动项路由到项目待办事项)。
  • 它改变了项目状态 → 说明情况并提供更新该项目笔记。
  • 它产生了可持久的洞见 → 应通过正常的会话结束路径放入保险库,而不是作为看视频的副作用。

观看是廉价且可重复的。归档是一个决定。请保持两者分离。

相关技能