Communitygithub.com

The-AIOS/aios

真正觀看或收聽影片/音訊來源,將其保留在上下文(context)中,以便能回答相關問題、總結、擷取引文,或根據內容採取行動——這是一個「快速理解」動作,而非歸檔流程。包含 Claude 無法自行發現的本機媒體鉤子(hooks):hooks/transcribe.py(長音頻→文字,設備端執行)和 hooks/video-watch.py(視覺通道——投影片、程式碼、圖表、終端機、螢幕上的文字,這些是逐字稿會丟失的資訊)。

aios 是什麼?

此技能專為開發者與 AI 代理(如 Claude Code、Cursor)設計,解決 AI 無法直接存取本地媒體檔案的痛點。當使用者分享影片、錄音、簡報、螢幕錄製、講座或 YouTube 連結時,技能會自動調用兩個核心鉤子:transcribe.py 處理長音頻(使用設備上的 mlx-whisper 模型進行語音辨識),video-watch.py 則利用 OCR 或 VLM 分析視覺畫面(如投影片、程式碼、圖表)。其核心原則是「理解而非歸檔」——所有產出僅保留於當前對話工作階段,不寫入永久庫。支援 macOS/Apple Silicon 平台,在其他系統上會優雅降級使用 MarkItDown。技能還包含清晰的決策樹:文件類走 MarkItDown,純音訊用轉寫,YouTube 優先抓取字幕,螢幕有資訊時疊加視覺分析。執行前會估算時間並確認,並提供失敗模式(如逐字稿遺漏視覺內容)與交接機制(需歸檔時引導至 /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 的新對話。

說明文件

觀看影片——理解,而非攝取

有人分享一個影片並請你處理。兩個鉤子(hooks)讓這成為可能,但它們本身都無法被直接發現——鉤子沒有語義匹配,因此當工作階段被要求「看這個」時,它會找不到任何東西而只能臨時應變。這個缺口正是此技能存在的全部理由。

邊界——請先閱讀此部分

此技能是「觀看」。它不是「歸檔」。 它的輸出是在工作階段中持有的理解,而非庫藏工件。沒有筆記、沒有 frontmatter、沒有交叉連結、沒有 _index 更新、沒有行動項目路由。工作檔案會放到暫存路徑(/tmp),絕不放入 vault/。

/aios:ingest 是歸檔流程——它的存在正是為了將來源轉換為永久且帶有連結的庫藏筆記,這是一個需要遵循慣例的刻意動作。如果使用者想要這樣做,請交接(「要我把它 /aios:ingest 歸檔,放到 reflections/ingests/ 並附上交叉連結嗎?」)——不要在這裡半套實作。兩條路徑,一條邊界,沒有重疊。

所以一次執行的流程是:放入上下文 → 執行要求 → 提供選項,不要預設。 如果要求是開放的(只是「看這個」而沒有提問),那就觀看,然後用兩三行說明內容,再問對方想要什麼。不要製造沒人要求的交付物。

選哪個工具——實際決策

來源選用工具原因
文件(PDF、docx、簡報、試算表)MarkItDown 或 document-skills非此技能職責;那些已有語義匹配
長音頻/影片,音訊已足夠hooks/transcribe.pyMarkItDown 對音訊使用 Google Web Speech API 單次呼叫——對一句話還行,但對 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 選擇是唯一真正需要決定的參數:

  • --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/,使用 {來源}-{slug} 命名、frontmatter、交叉連結,行動項目路由到專案待辦事項)。
  • 它改變了專案狀態 → 告知並提議更新該專案筆記。
  • 它產生了持久的洞見 → 這應透過正常的關閉工作階段路徑放入庫藏,而不是作為觀看某事物的副作用。

觀看是便宜且可重複的。歸檔則是一個決定。保持兩者分離。

相關技能