---
name: z-video-downloader
description: 当用户给出视频链接并要求“下载视频”“视频下载”“帮我把这个视频下下来”“下载 YouTube 视频”“下载 B站/哔哩哔哩视频”“下载 m3u8/mp4 直链”“把视频保存到本地”“后续我给你链接你来下载视频”时必须使用。本 skill 面向单个或多个视频链接，支持 YouTube、Bilibili/哔哩哔哩、Vimeo、X/Twitter、TikTok、抖音、Instagram、Facebook 等 yt-dlp 支持的主流平台，也支持 mp4/webm/mov/mkv 等直链视频；会保存到本地 Video/Downloads，并生成下载报告。
---

# 视频下载器

把用户给的视频链接下载成本地视频文件。核心实现来自 `1-web-pack` 中已经完成的视频下载部分：直链视频走流式下载，平台视频和 m3u8 走 `yt-dlp`，遇到平台风控时优先使用导出的 `cookies.txt` 文件重试。

## 依赖

- Python：优先使用 `/Users/zz/miniconda3/bin/python3`
- 平台下载：`/Users/zz/miniconda3/bin/yt-dlp`
- 合并音视频：`ffmpeg`，当前通常在 `/opt/homebrew/bin/ffmpeg`

## 默认输出

所有文件保存到：

```text
Video/Downloads/YYYY-MM-DD-主题/
├── 下载的视频文件.mp4
├── 下载的视频文件.info.json
├── download-report.md
└── download-report.json
```

## 常用命令

单个链接：

```bash
/Users/zz/miniconda3/bin/python3 .agent/skills/z-video-downloader/scripts/download_video.py \
  --title "主题名" \
  "https://www.bilibili.com/video/BV..."
```

多个链接：

```bash
/Users/zz/miniconda3/bin/python3 .agent/skills/z-video-downloader/scripts/download_video.py \
  --title "主题名" \
  "https://www.youtube.com/watch?v=..." \
  "https://www.bilibili.com/video/BV..."
```

遇到 YouTube bot 验证、B 站 412、登录可见内容：

```bash
/Users/zz/miniconda3/bin/python3 .agent/skills/z-video-downloader/scripts/download_video.py \
  --cookies-file "cookies/cookies.txt" \
  --title "主题名" \
  "视频链接"
```

命令行临时调试仍支持 `--browser-cookies chrome`，但网页服务应使用 `--cookies-file`，避免服务进程反复唤起 Chrome/Safari。

YouTube 无 cookie 时若 `yt-dlp` 被登录校验拦截，脚本默认会再尝试 Invidious `local=true` 代理 fallback，优先保存 360p progressive MP4。若明确只允许官方 `yt-dlp` 路线，可加：

```bash
--no-invidious-fallback
```

下载播放列表、合集、频道列表时，用户必须明确要整组下载，再加：

```bash
--playlist
```

下载更高清时：

```bash
--quality best
```

默认限制为 1080p，避免无意下载超大文件。用户明确要最高画质时才使用 `--quality best`。

## 执行流程

1. 先确认用户给的是视频链接或视频直链；如果是网页素材采集、正文和图片也要保存，改用 `1-web-pack`。
2. 运行 `scripts/download_video.py`。没有特殊要求时使用默认 1080p、单视频模式。
3. 如果 YouTube 失败原因包含登录、bot 验证、cookies、captcha，脚本会自动尝试 Invidious 代理 fallback；若用户需要更高清或官方登录态，再使用 `--cookies-file cookies/cookies.txt` 重试。
4. 如果 B 站或其他平台失败原因包含 HTTP 412、403、登录或 cookies，使用 `--cookies-file cookies/cookies.txt` 重试一次。
5. 如果用户给的是合集、播放列表、UP 主空间、频道页，先确认用户确实要批量下载，再使用 `--playlist`。
6. 完成后读取 `download-report.md`，最终回复给用户：
   - skill 路径
   - 输出目录
   - 成功/失败数量
   - 成功文件名和大小
   - 失败链接的原因与 cookie 重试提示

## 平台策略

- mp4/webm/mov/m4v/mkv/flv/ogv 直链：脚本直接流式下载，保留 Referer 和 User-Agent。
- m3u8、YouTube、Bilibili、Vimeo、X/Twitter、TikTok、抖音等：交给 `yt-dlp`。
- YouTube 直连被登录校验拦截时：尝试 Invidious `local=true` 代理端点，使用 Range 小块续传保存 360p MP4。
- 默认 `--no-playlist`，避免一个链接意外下载整套列表。
- 默认 `--max-video-mb 2000`，超出时失败并记录到报告。
- 默认 `--write-info-json`，保留视频元数据，方便后续追溯来源。

## 收尾检查

下载后至少运行：

```bash
find "Video/Downloads/本次目录" -maxdepth 1 -type f | sort
sed -n '1,160p' "Video/Downloads/本次目录/download-report.md"
```

如果本任务只下载视频，报告 Markdown 不含外链图片，无需调用图床 skill。若后续改成产出包含外链图片的 `.md` 文件，按项目规则调用 `1-upload-images-to-picgo`。
