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

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

首次使用：一键安装依赖

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

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

此脚本会自动：

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

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

下载流程

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

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

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

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

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

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

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

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

立即向用户展示确认按钮，使用 AskQuestion 工具：
- 提示：「已打开 B站登录页面，请在浏览器中完成登录，完成后点击下方确认按钮。」
- 选项 A：「已完成登录」
- 选项 B：「跳过登录（使用低画质）」
用户点击确认后：
- 选择 A：创建信号文件 touch /tmp/video_dl_login_done，等待登录脚本退出，然后继续下载
- 选择 B：终止登录脚本进程，直接下载（低画质）
兜底：如果用户直接关闭了浏览器窗口，登录脚本会自动检测到并保存 cookie，无需信号文件。

步骤 3：下载视频

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

登录管理

# 登录（打开可见浏览器）
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 ~/.cursor/skills/video-download/scripts/install_deps.sh

方式2：手动安装

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

# 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

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

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`