从任意视频按需提取文字、关键画面或多模态摘要时用：解决视频转…

给定 YouTube/Loom/Vimeo/Riverside/Zoom/本地 MP4/X/IG 等视频源，按 transcript/visual/multimodal 三档深度转写、分析并生成可路由摘要。

适用场景

解决思路

1. 解析输入视频源：接受 YouTube 完整 URL、`youtu.be/<id>`、`youtube.com/shorts/<id>`、裸 11 位 ID；Loom `loom.com/share/<id>` 或 `loom.com/embed/<id>`；Vimeo `vimeo.com/<id>`；Riverside 下载 URL 或本地文件；Zoom 下载录制得到的本地 `.mp4`；X/IG/TikTok 视频 URL（元数据交给 `social-fetch`，文件用 yt-dlp）；本地任意 `.mp4`/`.mov`/`.webm`/`.mkv` 路径。根据 URL 模式或文件扩展名检测来源；模糊时询问用户。
2. 解析深度模式：`/watch-video <url>` 默认 transcript；`/watch-video <url> transcript` 同默认；`visual` = transcript + 按间隔抽帧 + Claude vision pass 识别关键时刻；`multimodal` = 若设置 `$GEMINI_API_KEY` 则原生视频给 Gemini，否则密集 Claude vision 逐帧。未指定深度且视频 >10 分钟时先询问再默认（visual/multimodal 在长视频上会花真钱）。
3. 拉取元数据：URL 源用 `yt-dlp --print "%(title)s|%(uploader)s|%(duration_string)s|%(upload_date>%Y-%m-%d)s|%(description)s" --print "%(chapters)j" --skip-download "<url>"`，捕获 title、uploader/channel、duration、upload date、description 第一段、chapters（JSON 或 null）。本地文件用 `ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "<file>"`。
4. 构建工作目录：`~/Documents/videos/<source>-<slug>-<date>/`；`source` 为 `youtube`/`loom`/`vimeo`/`riverside`/`zoom`/`local`；`slug` 为标题 kebab-case 的前 4–6 个词，最多 50 字符；`date` 为 `YYYY-MM-DD`。
5. 获取转写文本，按顺序选择后端：1) 平台自带 transcript 若存在且看起来完整：YouTube 用 `yt-dlp --write-sub --write-auto-sub --skip-download --sub-lang en --sub-format vtt`；Loom 从 `https://www.loom.com/share/<id>` 页面元数据或设置 `$LOOM_API_KEY` 时用 Loom API 获取；Riverside 从录制分享页获取内置 transcript；若平台 transcript 存在且带时间戳，则使用它并跳过 Whisper。2) MLX-Whisper 本地（默认回退，Mac M 系列快）：安装一次 `pip install mlx-whisper`；运行 `python3 -c "import mlx_whisper; mlx_whisper.transcribe('<file>', path_or_hf_repo='mlx-community/whisper-large-v3-turbo')" > "<workdir>/transcript-raw.json"`；或用 CLI `mlx_whisper <file> --model mlx-community/whisper-large-v3-turbo --output-dir <workdir>`。3) 若 MLX 不可用，进一步回退 `whisper.cpp`。
6. 若源是 URL 且需要本地文件，先下载视频：`yt-dlp -f "bv*[height<=720]+ba/b[height<=720]" -o "<workdir>/video.%(ext)s" "<url>"`；720p 足够转写和帧分析（下载更小、处理更快）。
7. 清理转写文本：仅 YouTube 自动字幕需要（Whisper 输出已干净）。用 awk 去重滚动字幕、剥离标签、在 cue 间隔 >2s 时分段：`awk '/^WEBVTT/ || /^Kind:/ || /^Language:/ || /^NOTE/ { next } /-->/ { in_cue = 1; last = ""; next } /^$/ { if (last) print last; in_cue = 0; last = ""; next } in_cue { gsub(/<[^>]+>/, "", $0); last = $0 } END { if (last) print last }' "<workdir>/transcript.en.vtt" | awk '!seen[$0]++' > "<workdir>/transcript.txt"`。最终保存到 `<workdir>/transcript.txt`。
8. 若为 `transcript` 模式：到此停止。输出 `transcript.txt`、`metadata.json`、聊天中一行摘要（title、source、duration、word count）、workdir 路径；可选执行第 9 步，询问是否捕获到 second-brain。
9. 若为 `visual` 模式：按来源启发式抽帧：屏幕共享/Loom/demo 每 5s 1 帧（UI 变化快）；说话头/播客每 30s 1 帧（变化慢）；幻灯片每 10s 1 帧 + 在每个检测到的场景变化强制抽帧；不确定默认每 15s 1 帧。命令：`mkdir -p "<workdir>/frames"` 和 `ffmpeg -i "<workdir>/video.mp4" -vf "fps=1/15" "<workdir>/frames/frame-%04d.png" -y`；幻灯片场景变化用 `ffmpeg -i "<workdir>/video.mp4" -vf "select='gt(scene,0.3)',showinfo" -vsync vfr "<workdir>/frames/scene-%04d.png" 2> "<workdir>/scene-detection.log"`。
10. 在 `visual` 模式做 vision pass：将每帧与同一时间戳窗口的 transcript chunk 配对；批量发送给 Claude vision 综合，每次最多约 10 帧；提示词为：这里有 N 帧来自视频时间戳 T1..TN。对每一帧用 1–2 句话描述屏幕上是什么。标记：(a) 相对上一帧的 UI 变化，(b) 屏幕可见文字，(c) 任何看起来像决策、动作或显著事件的时刻。同时记录此窗口内说出的 transcript 文本。保存输出为 `<workdir>/moments.md`，模板含 `# Key moments — <title>`，每个条目包含时间戳/帧文件名、`On screen` 屏幕内容、`Transcript` 对应转写、`Note` 备注。
11. 在 `visual` 模式生成摘要：moments 识别后，将整个视频综合成 `<workdir>/summary.md`，模板含 `Source`、`Duration`、`Watched at`、`Mode`、`TL;DR`、`Key moments`、`Action items flagged`、`Decisions flagged`、`Quotes worth keeping`、`Open questions`；每个关键时刻一行，action/decision 带时间戳，decision 提示可路由到 `/decide`。
12. 若为 `multimodal` 模式且设置 `$GEMINI_API_KEY`，优先 Gemini 原生（比逐帧更便宜更快）：默认模型 `gemini-3.5-flash`（2026 年 5 月发布，约 $1.50 输入 / $9 输出每 1M tokens；约 $0.15/秒视频；在 coding/agentic benchmark 上以 4× 速度击败 3.1 Pro）；品牌审计/高风险分析可覆盖为 `gemini-3.1-pro`；批量便宜处理用 `gemini-2.5-flash-lite`。上传视频：`FILE_URI=$(curl -s -X POST "https://generativelanguage.googleapis.com/upload/v1beta/files?key=$GEMINI_API_KEY" -H "X-Goog-Upload-Command: start, upload, finalize" -H "Content-Type: video/mp4" --data-binary "@<workdir>/video.mp4" | jq -r '.file.uri')`；轮询直到 `STATE=ACTIVE`：`while true; do STATE=$(curl -s "$FILE_URI?key=$GEMINI_API_KEY" | jq -r '.state'); [ "$STATE" = "ACTIVE" ] && break; sleep 3; done`；生成内容：`curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent?key=$GEMINI_API_KEY" -H "Content-Type: application/json" -d "{\"contents\":[{\"parts\":[{\"file_data\":{\"mime_type\":\"video/mp4\",\"file_uri\":\"$FILE_URI\"}},{\"text\":\"<multimodal analysis prompt — see Step 7 summary template + use-case extensions>\"}]}]}"`。Gemini Files API 中文件保留约 48 小时，便于用不同提示重复查询同一视频。
13. 若为 `multimodal` 模式但没有 `$GEMINI_API_KEY`，回退密集 Claude vision：帧节奏为每 3s 1 帧（比 visual 模式密得多）；用 multimodal-analysis prompt 批量走 Claude vision；对长视频比 Gemini 更慢更贵——在 >10 分钟内容上运行前警告用户。
14. `multimodal` 模式输出：使用与 Step 7 相同的 `summary.md` 模板 + 扩展节 `## Multimodal observations`，含 `Body language / delivery`、`Pacing`、`Visual style`、`Audio quality / atmosphere`；额外节取决于用例（品牌审计、广告评审、演讲表达评审、客户电话解读），用例从来源 + 用户调用时口头描述推断。
15. 可选捕获到 second-brain：任何模式完成后询问：是否要捕获到 second-brain？会写入 `call-<slug>.md`（或 `meeting-`/`note-`/`resource-`）到 `${SECOND_BRAIN_VAULT:-$HOME/Documents/SecondBrain}/raw/`，含 summary、source URL、transcript 链接。按来源选前缀：Loom/Zoom/Riverside/Otter/call recording -> `call-`；会议（自己的笔记，不是 transcript）-> `meeting-`；Talk/keynote/conference -> `note-`；Ad/landing-page video/marketing reference/competitor video -> `resource-`。文件正文：1 行来源、summary、完整 workdir 链接。
16. 在聊天中报告：一行标题 `<source> · <title> · <duration> · <mode> · <word count> words`；workdir 路径；对 `visual`/`multimodal` 列出 top 3 关键时刻；所有模式列出任何 action items/decisions 供 triage；若捕获到 second-brain，也给该路径。
17. 按来源参考表处理下载与内置字幕：YouTube 用 `yt-dlp` 下载，自动字幕用 `--write-auto-sub`；Loom 用 `yt-dlp` 下载，内置 transcript 从 embed metadata 或 Loom API 获取；Vimeo 用 `yt-dlp` 下载，有时有内置字幕；Riverside 用导出直链或本地文件，Riverside 会生成内置 transcript；Zoom 用本地 `.mp4`（下载的录制），有时有 Zoom audio transcript 文件；X/IG/TikTok 交给 `social-fetch` 取元数据，用 yt-dlp 下文件，无内置字幕；本地文件无需下载。
18. 与其它技能组合：`social-fetch` 处理 X/IG/TikTok URL 元数据（engagement、author、replies）后再处理视频；`second-brain` 捕获 summary 为 `raw/call-<slug>.md`、`meeting-`、`note-` 或 `resource-`；`decide` 当视频含 flagged decision 时路由到 `/decide` 做结构化捕获；`pm` 将 summary 中 action items 分诊到项目看板；`slide-deck` 将 talk recordings 提取大纲并生成 deck 草稿（循环）；`jab-hook` 将 podcast/talk 视频中的 quotes + clip-worthy moments 用于 BIP/promo 帖子；`skillify from-video` 是 `visual` 模式处理流程录制的主要用例：用户录制自己做工作流（Loom/屏幕共享），本技能提取 transcript + 关键视觉时刻，然后 `skillify` 将工作流合成为 SKILL.md（“Record once, AI converts to skill”）。
19. 错误处理：视频不可用/私有/区域锁 -> 报告并停止；无字幕且未安装 Whisper -> 告诉用户 `pip install mlx-whisper` (Mac)；缺少 ffmpeg（visual/multimodal）-> 告诉用户 `brew install ffmpeg`；vision pass 返回空/不清 -> 降低帧数、重试，或回退 transcript-only 并注明；请求 multimodal 但无 `$GEMINI_API_KEY` 且视频 >30min -> 警告成本，提供回退 visual 模式；缺少 `yt-dlp` 二进制 -> `brew install yt-dlp`。
20. 质量注意事项 1：用户选择深度，不是技能。Transcript/visual/multimodal 是 3 种不同成本 + 延迟配置。长视频（>10 min）在 visual/multimodal 花钱前总是确认。
21. 质量注意事项 2：平台 transcript 优先，Whisper 第二。YouTube auto-subs、Loom transcripts、Riverside built-in transcripts 在存在时免费 + 即时。只有平台提供的都不可用时才回退 MLX-Whisper 本地。
22. 质量注意事项 3：MLX-Whisper 本地是 Mac 快路径。M 系列机器转写快于实时。云 Whisper 是远次选——花钱、依赖网络、典型时长下延迟更差。
23. 质量注意事项 4：帧节奏按来源类型。屏幕共享/演示需每 5s 1 帧（UI 变化快）；说话头播客需每 30s 1 帧（变化慢）。不确定默认 15s。错误节奏 = 错过关键时刻 OR 浪费 vision-pass 成本。
24. 质量注意事项 5：720p 足够。下载 1080p/4K 用于转写 + 帧分析浪费带宽 + 存储。`yt-dlp -f "bv*[height<=720]+ba/b[height<=720]"` 是默认。
25. 质量注意事项 6：场景变化检测捕捉幻灯片切换。视频是幻灯片时，加 `ffmpeg -vf "select='gt(scene,0.3)'"` 强制在每次检测到的幻灯片变化抽帧——比纯时间采样更可靠。
26. 质量注意事项 7：Multimodal 成本警告不可省略。Gemini multimodal 在 60 分钟视频上有明显成本。运行前警告；用户不确定时提供 transcript-only 回退。
27. 质量注意事项 8：摘要格式包含路由提示。`## Decisions flagged` + `## Action items flagged` 节信号 `/decide` 和 `/pm` 后续。下游可组合性存在于摘要结构中。

适用边界 · 注意事项

• 视频不可用、私有或区域锁定：无法拉取，应报告并停止。
• 未安装 yt-dlp/ffmpeg/MLX-Whisper 且不愿安装：转写、抽帧或视觉分析流程无法运行。
• 长视频（>10 分钟）且不希望为 visual/multimodal 承担成本或等待：应只用 transcript，或先确认再运行。