| name | video-downloader |
| description | Downloads videos from YouTube, Bilibili, Douyin, Xiaohongshu, Kuaishou, Twitter/X, Weibo, Vimeo, TikTok, and 1700+ other sites to local disk. Handles per-platform quirks (Bilibili login for 720P+, Xiaohongshu xsec_token, custom parsers for Douyin/Kuaishou). Use when the user asks to download, save, grab, rip, or archive a video, or provides a video URL with intent to save it locally. |
Video Downloader
支持从多个视频平台下载视频到本地，基于 yt-dlp + 自研脚本实现。下载前先解析所有可下载档位让用户挑选，自动应用平台特定优化。
📘 新用户必读：完整安装 / 权限 / 路径配置见 SETUP.md。
📘 平台细节 / 错误处理速查：见 references/platform-notes.md。
Step 0：环境自检（首次使用必做）
MISSING=()
for tool in yt-dlp ffmpeg; do
command -v "$tool" >/dev/null 2>&1 || MISSING+=("$tool")
done
command -v aria2c >/dev/null 2>&1 || echo "ℹ️ aria2c 未装（可选，装了会快 10x）：brew install aria2"
if [[ ${#MISSING[@]} -gt 0 ]]; then
echo "❌ 缺少必需工具: ${MISSING[*]}"
echo " 请跑：brew install ${MISSING[*]}"
exit 1
fi
echo "✅ 必需工具齐全；默认下载目录：$HOME/Downloads"
依赖缺失时引导用户去 SETUP.md。
核心流程
Step 1：识别下载请求并提取 URL
从用户消息中抽取第一个视频平台 URL。如果有多个 URL，逐个询问或批量处理。
Step 2：识别平台 + 检查依赖
which yt-dlp ffmpeg aria2c 2>&1
平台特定的登录态 / cookies / 特殊脚本逻辑见 references/platform-notes.md。下面只列出影响交互的关键提示：
- B 站 → 必须提示用户"720P+ 需要登录态"
- 小红书 → 必须确认 URL 含
xsec_token；quality 模式必须提示"4K 需要 Chrome 匿名 session cookie"
- 抖音 / 快手 →
download.sh 会自动委派到对应专用脚本，无需 Agent 操心
- 微博 →
quality 模式可能下到 300+ MB 大文件，提前告知
Step 3：先探测，把档位给用户挑（必须做）
⚠️ 不要直接下载。必须先调 probe 拿到档位表，让用户自己选。
B 站 / 小红书 probe 前必须先问一句（默认 guest 只能看 480p / 720p）：
想要 1080p+ 高清吗？需要读 Chrome 登录态 cookies（首次会弹一次 macOS 钥匙串，点「始终允许」即永久免弹）。(1) 要高清 / (2) 不用，guest 就行
用户选 (1) → 命令前缀加 VDL_USE_CHROME=1；选 (2) 或其他平台 → 直接跑：
bash "<skill_directory>/scripts/probe.sh" --human "<URL>"
VDL_USE_CHROME=1 bash "<skill_directory>/scripts/probe.sh" --human "<URL>"
把 probe 输出的档位表直接展示给用户，加一句推荐（兼容优先 = H.264 / 画质优先 = HEVC 或 AV1 / 速度优先 = 最低分辨率），然后问：
你想下载哪一档？(回复行号，或输入 quality / compat / speed 用预设规则)。保存位置默认 ~/Downloads，如需修改请告诉我目录。
Step 4：执行下载（按用户选择）
三种下载语法（任选一种）：
bash "<skill_directory>/scripts/download.sh" --format <#> "<URL>" [output_dir]
bash "<skill_directory>/scripts/download.sh" <MODE> "<URL>" [output_dir]
bash "<skill_directory>/scripts/download.sh" --format-arg "<expr>" "<URL>" [output_dir]
参数：
<#>：probe --human 输出里的行号MODE：quality | speed | compat（预设规则，可跳过 probe）URL：视频链接output_dir：可选，默认 ~/Downloads
download.sh 已内嵌平台委派逻辑——抖音 / 快手会自动走对应的专用脚本。
三档预设语义（不调 probe 的快捷路径）
| 维度 | quality | speed | compat |
|---|
格式选择 -f | bv*+ba/b | bv*[height<=480]+ba/b[height<=480] | bv*[vcodec^=avc1][height<=1080]+ba/b[ext=mp4][height<=1080] |
| 容器 | mkv | mp4 | mp4 |
| 并发分片 | 16 | 16 | 16 |
| Cookies | 默认游客；遇到小红书/B 站才读 Chrome | 同左 | 同左 |
| 外部下载器 | aria2c（如已安装） | 同左 | 同左 |
macOS 钥匙串弹窗
ℹ️ B 站 / 小红书 quality 模式首次会触发 macOS 钥匙串弹窗（点「始终允许」即可），完整说明见 SETUP.md。
Step 5：监控 + 汇报
后台执行 + 每 30s 轮询：
ls -lh "<output_dir>"/*.part 2>/dev/null
ps -p <PID> >/dev/null && echo RUNNING || echo DONE
下载完成用 ffprobe 抓出分辨率 / 编码 / 大小，汇报给用户。
Step 6：兼容性自检（quality 模式）
如果 ffprobe 输出的视频编码是 vp9 / av01 / hevc，必须额外提醒：
这个文件是 <编码> 编码，部分播放器 / 移动端 / 网页可能无法直接播放（例如 macOS QuickTime / Windows 资源管理器缩略图 / Office 插入视频）。建议用现代播放器：macOS = IINA / VLC，Windows = PotPlayer / VLC / MPV，跨平台 = VLC / mpv / IINA。
如果需要任意环境都能直接播放的文件，重选「兼容优先」模式下一遍（1080p H.264 + MP4）。
注意事项
- 必须先问用户偏好，不要默认替用户选 quality / speed / compat
- B 站链接必须额外提示登录态
- 大文件下载用后台执行 + 轮询，不要阻塞对话
- 下载到
~/Downloads（除非用户指定）
- 版权声明：仅协助下载用户有权访问的内容；不绕过付费墙、不下载受 DRM 保护的内容、不破解会员专享内容
- 进度反馈：每 30–60 秒向用户汇报一次进度，避免长时间静默
支持文件
references/platform-notes.md —— 各平台要点 + 错误处理速查references/format-reference.md —— 各平台编码 / format id / 容器选择速查scripts/probe.sh —— 链接解析（不下载），输出元数据 + 档位表scripts/download.sh —— 统一下载入口（自动平台识别 + 多线程 + 自动委派抖音 / 快手）scripts/_probe_format_ytdlp.py —— yt-dlp -J → 统一 probe JSONscripts/_probe_render_human.py —— probe JSON → 人类表格scripts/download-douyin.sh —— 抖音专用（绕开 yt-dlp 失效 extractor，走分享页 SSR）scripts/download-kuaishou.sh —— 快手专用（yt-dlp 无内置 extractor，走分享页 SSR）
