视频下载（抖音 / 小红书 / 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.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 bilibiliCookie 保存在 ~/.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 |