---
name: video-download
description: Download videos from Douyin (抖音), Xiaohongshu (小红书), Bilibili (B站), YouTube, Twitter/X, Instagram, and 1700+ sites to local disk. Use when the user shares a video link, asks to download a video, or mentions v.douyin.com / xiaohongshu.com / xhslink.com / bilibili.com / b23.tv / youtube.com / youtu.be / x.com / twitter.com / instagram.com or any other video URL.
---

# 视频下载（抖音 / 小红书 / B站 + YouTube / Twitter 等）

从分享链接下载视频到本地。抖音/小红书/B站使用 Playwright 无头浏览器，其他站点使用 yt-dlp。

## 首次使用：一键安装依赖

**推荐：自动安装脚本（已优化国内网络）**

```bash
bash ~/.cursor/skills/video-download/scripts/install_deps.sh
```

此脚本会自动：

- ✅ 使用清华镜像源加速 pip 安装
- ✅ 使用 npmmirror 加速 Playwright 浏览器下载
- ✅ 检测已安装的依赖，避免重复下载
- ✅ 自动安装 ffmpeg（B站需要）

**或手动安装**（参考本文档末尾的"依赖安装"部分）

---

## 下载流程

**重要：下载 B站视频前，必须先检查登录状态（未登录只能获取 480p）。**

### 步骤 1：检查登录状态（B站必须）

```bash
python3 ~/.cursor/skills/video-download/scripts/download.py check-login bilibili
```

- 退出码 `0`（输出 `LOGIN_OK`）→ 直接跳到步骤 3 下载
- 退出码 `2`（输出 `LOGIN_REQUIRED`）→ 需要执行步骤 2 登录

### 步骤 2：交互式登录（需要时）

当 check-login 返回退出码 2 时，按以下流程操作：

1. **后台启动登录浏览器**（设置 block_until_ms: 0）：

```bash
python3 ~/.cursor/skills/video-download/scripts/download.py login bilibili --signal-file /tmp/video_dl_login_done
```

2. **立即向用户展示确认按钮**，使用 AskQuestion 工具：
   - 提示：「已打开 B站 登录页面，请在浏览器中完成登录，完成后点击下方确认按钮。」
   - 选项 A：「已完成登录」
   - 选项 B：「跳过登录（使用低画质）」

3. **用户点击确认后**：
   - 选择 A：创建信号文件 `touch /tmp/video_dl_login_done`，等待登录脚本退出，然后继续下载
   - 选择 B：终止登录脚本进程，直接下载（低画质）

4. **兜底**：如果用户直接关闭了浏览器窗口，登录脚本会自动检测到并保存 cookie，无需信号文件。

### 步骤 3：下载视频

```bash
python3 ~/.cursor/skills/video-download/scripts/download.py "<分享文本或链接>" [输出文件名.mp4]
```

## 平台支持

脚本自动识别平台，优先使用 Playwright，其余 fallback 到 yt-dlp：

| 平台      | 支持的链接格式                                                         | 引擎       | 需要登录 | 备注                             |
| --------- | ---------------------------------------------------------------------- | ---------- | -------- | -------------------------------- |
| 抖音      | `v.douyin.com/xxx` 短链、`www.douyin.com/video/xxx`、`modal_id=xxx`    | Playwright | 否       | 抓网络请求                       |
| 小红书    | `xiaohongshu.com/discovery/item/xxx`、`explore/xxx`、`xhslink.com/xxx` | Playwright | 否       | 抓网络请求                       |
| B站       | `bilibili.com/video/BVxxx`、`b23.tv/xxx` 短链                          | Playwright | 推荐     | 解析 `__playinfo__`，需要 ffmpeg |
| YouTube   | `youtube.com/watch?v=xxx`、`youtu.be/xxx`                              | yt-dlp     | 否       |                                  |
| Twitter/X | `x.com/xxx/status/xxx`、`twitter.com/...`                              | yt-dlp     | 否       |                                  |
| Instagram | `instagram.com/reel/xxx`、`instagram.com/p/xxx`                        | yt-dlp     | 否       | 私密内容需登录                   |
| 其他      | 任意视频链接                                                           | yt-dlp     | 视站点   | 支持 1700+ 站点                  |

- 输出文件名可选，默认从视频标题生成
- 文件保存到 `~/Downloads/`
- 依赖：`playwright`（抖音/小红书/B站）、`yt-dlp`（其他站点）、`ffmpeg`

## 登录管理

```bash
# 登录（打开可见浏览器）
python3 ~/.cursor/skills/video-download/scripts/download.py login bilibili

# 带信号文件的登录（Agent 交互模式用）
python3 ~/.cursor/skills/video-download/scripts/download.py login bilibili --signal-file /tmp/video_dl_login_done

# 检查登录状态
python3 ~/.cursor/skills/video-download/scripts/download.py check-login bilibili
```

Cookie 保存在 `~/.config/video-download/<平台>_cookies.json`，自动检测过期。

支持的平台: `bilibili` / `douyin` / `xiaohongshu`

## 依赖安装

### 方式1：一键自动安装（推荐）

```bash
bash ~/.cursor/skills/video-download/scripts/install_deps.sh
```

### 方式2：手动安装

**国内用户推荐配置（避免卡住）：**

```bash
# 1. 配置 pip 国内镜像源（永久生效）
pip3 config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 2. 安装 Python 包
pip3 install playwright

# 3. 使用国内镜像下载浏览器
export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright/
python3 -m playwright install chromium

# 4. 安装 ffmpeg（B站视频合并需要）
brew install ffmpeg

# 5. 安装 yt-dlp（YouTube/Twitter 等站点需要）
brew install yt-dlp
```

**临时使用镜像（不改配置）：**

```bash
pip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple playwright
export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright/
python3 -m playwright install chromium
```

## 故障排除

| 问题              | 解决方案                                               |
| ----------------- | ------------------------------------------------------ |
| SSL 证书错误      | 脚本已内置 `ssl._create_unverified_context`            |
| 未捕获到视频地址  | 增加等待时间，或内容需要登录/是图文非视频              |
| curl/下载 403     | 检查 Referer 头是否匹配平台域名                        |
| B站 ffmpeg 不存在 | `brew install ffmpeg`                                  |
| B站画质低         | 执行 `login bilibili` 登录后重新下载                   |
| CDN 地址过期      | 重新运行，URL 有几小时时效                             |
| cookie 过期       | 重新执行 login 命令                                    |
| yt-dlp 未安装     | `brew install yt-dlp` 或 `pip3 install yt-dlp`         |
| yt-dlp 下载失败   | 先 `yt-dlp -U` 更新到最新版，站点可能更新了反爬        |
| YouTube 地区限制  | 使用代理：`yt-dlp --proxy socks5://127.0.0.1:1080 URL` |