video-download

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

统一入口原则（重要）

• 本 skill 是社媒视频下载的唯一入口。
• 当任务来自飞书多维表格（Base）/表格批处理时，下载动作也必须调用本 skill 的 scripts/download.py，不要在业务脚本里另写直连下载器。
• 需要正文/点赞/收藏时，可以在业务脚本里各自抓取；但“视频文件获取”必须复用本 skill 的下载链路与校验能力。

从分享链接下载视频到本地。视频号使用用户配置的自托管解析器取得临时直链；B站优先使用 yt-dlp，失败后回退 Playwright；抖音/小红书优先使用 Playwright，抓流失败后回退 yt-dlp；TikTok 优先使用真实浏览器 CDP 抓流。

下载流程

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

先进入 skill 根目录后再执行以下命令（命令均使用相对路径）：

cd <your-skill-root>/video-download

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

python3 ./scripts/download.py check-login bilibili

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

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

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

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

python3 ./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：下载视频

python3 ./scripts/download.py "<分享文本或链接>" [输出文件名.mp4]

平台支持

脚本自动识别平台，并按平台使用不同的主引擎与兜底引擎：

平台	支持的链接格式	引擎	需要登录	备注
微信视频号	weixin.qq.com/sph/xxx、channels.weixin.qq.com/finder-preview/pages/sph?id=xxx	自托管解析器 + 直链下载	解析器端需要	优先 H.264，下载后用 ffprobe 校验
抖音	v.douyin.com/xxx 短链、www.douyin.com/video/xxx、modal_id=xxx	Playwright→yt-dlp	视风控	优先抓网络请求；失败后使用已保存 Cookie 回退
小红书	xiaohongshu.com/discovery/item/xxx、explore/xxx、xhslink.com/xxx	Playwright→yt-dlp	视内容	优先抓网络请求；失败后使用已保存 Cookie 回退
B站	bilibili.com/video/BVxxx、b23.tv/xxx 短链	yt-dlp→Playwright	推荐	yt-dlp 处理清晰度与音视频合并；需要 ffmpeg
TikTok	tiktok.com/@user/video/xxx、vm.tiktok.com/xxx	CDP→tikwm→yt-dlp	推荐	优先真实浏览器 CDP；app-only/shop 场景自动尝试 tikwm 兜底
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+ 站点

• 回退条件包括「主引擎崩溃」，不只是「没抓到地址」：Playwright 抛的异常会被包成 RuntimeError，由调用方接住转兜底引擎；到顶层也只打一行错误，不会甩 traceback
• 输出文件名可选，默认从视频标题生成
• 文件保存到 ~/Downloads/
• 依赖：playwright、yt-dlp、ffmpeg（B站及分离音视频格式合并）

B站、抖音与小红书回退策略

按以下顺序下载：

1. B站：yt-dlp → Playwright。
2. 抖音、小红书：Playwright → yt-dlp。
3. yt-dlp 需要 Cookie 时，只使用 ~/.config/video-download/<平台>_cookies.json 中对应平台的 Cookie。
4. 脚本把该平台 Cookie 临时转换为 Netscape 格式，权限设为 0600，yt-dlp 结束后立即删除；不要默认读取整个浏览器 Cookie 数据库。
5. Cookie 缺失或失效时，先执行 python3 ./scripts/download.py login <平台>，再重试下载。

微信视频号专项说明

视频号分享页通常只公开封面和基础元数据，不直接暴露可下载的视频地址。本 Skill 借鉴 ltaoo/wx_channels_download 的分享链接解析接口形状，但不会安装根证书、修改系统代理，也不会直接保存或发送元宝 Cookie。

优先配置 Video-Picture-OSS-Auth 自托管解析器；脚本也兼容 wx_channels_download 的嵌套响应结构：

export WECHAT_CHANNELS_RESOLVER_URL="http://api-ai.modianinc.com:8080/wechat/channels/resolve"
export WECHAT_CHANNELS_RESOLVER_API_KEY="<WECHAT_API_KEY>"

• WECHAT_CHANNELS_RESOLVER_API_KEY 可选；配置后通过 X-API-Key 请求头发送。
• 元宝登录 Cookie 只应保存在解析器服务端的 WECHAT_CHANNELS_YUANBAO_COOKIE 环境变量或 GitHub Secret 中，不能放进 Skill、命令参数、Git 或元数据文件。
• 公网 HTTP 会明文传输 API Key 和解析结果；当前无 HTTPS 时仅建议在可信网络临时使用，并尽快迁移到 HTTPS 或内网。
• 解析器应返回可直接下载的 URL；若返回解密密钥，Skill 会拒绝下载并要求解析器提供已解密代理地址。

仅解析并查看元数据、临时直链：

python3 ./scripts/download.py resolve "https://weixin.qq.com/sph/ARebDCbPGy"

解析并下载：

python3 ./scripts/download.py "https://weixin.qq.com/sph/ARebDCbPGy" "video.mp4"

成功后生成：

• 视频文件（默认 ~/Downloads/，可用 VIDEO_DOWNLOAD_OUTPUT_DIR 修改）
• <视频文件>.meta.json，包含作者、描述、封面、时间和互动数据，不包含临时视频 URL、API Key 或 Cookie

TikTok 专项说明（CDP 优先）

脚本会优先尝试连接以下 CDP 端口抓取 video/mp4 响应体：

1. VIDEO_DOWNLOAD_TIKTOK_CDP_ENDPOINT（如果设置）
2. http://127.0.0.1:9225

端口约定（团队规则）：

• 在 TikTok 批处理任务中，如果显式设置了 VIDEO_DOWNLOAD_TIKTOK_CDP_ENDPOINT，应把它视为唯一目标端口（例如 9225），不应在任务层再切换到其他端口进行重试。
• 当前团队默认 TikTok 端口为 http://127.0.0.1:9225。
• TikTok 任务不回退到 9222，避免串到其他平台的浏览器。
• 账号主页批处理可设置 VIDEO_DOWNLOAD_TIKTOK_LIST_RECORD 和 VIDEO_DOWNLOAD_TIKTOK_AUTHOR_HANDLE，通过 9225 浏览器上下文携带 Cookie 请求已核验列表记录里的 playAddr，但不导航到作品详情页。设置 VIDEO_DOWNLOAD_TIKTOK_LIST_ONLY=1 后，直链失败会留待重试，不进入作品详情页。

若 CDP 抓取失败，会自动尝试 tikwm 解析；若仍失败，再按环境变量决定是否回退 yt-dlp。

失败重试策略（已内置）：

• 第一轮：CDP -> tikwm
• 第二轮（换路径重试一次）：tikwm -> CDP
• 仍失败时：按 VIDEO_DOWNLOAD_TIKTOK_ALLOW_YTDLP_FALLBACK=1 决定是否回退 yt-dlp

可通过环境变量指定端口：

VIDEO_DOWNLOAD_TIKTOK_CDP_ENDPOINT=http://127.0.0.1:9225 \
python3 ./scripts/download.py "<tiktok链接>" "output.mp4"

可选环境变量：

• VIDEO_DOWNLOAD_TIKTOK_DISABLE_TIKWM=1：禁用 tikwm 兜底
• VIDEO_DOWNLOAD_TIKTOK_ALLOW_YTDLP_FALLBACK=1：允许最终回退 yt-dlp

TikTok 抓取元数据输出

每次 TikTok 成功下载后，会在视频旁边生成一个元文件：

• <视频文件路径>.meta.json

关键字段：

• source: cdp / tikwm / ytdlp
• target_video_id
• resolved_video_id
• expected_duration
• actual_duration
• validation.id_ok
• validation.duration_ok
• validation.video_track_ok

终端也会打印一行摘要，便于批处理写表：

[TikTok/META] source=... id_ok=... duration_ok=... video_track_ok=...

登录管理

# 登录（打开可见浏览器）
python3 ./scripts/download.py login bilibili

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

# 检查登录状态
python3 ./scripts/download.py check-login bilibili

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

支持的平台: bilibili / douyin / xiaohongshu

抖音既有 CDP 环境

已有抖音浏览器环境时，显式设置 VIDEO_DOWNLOAD_DOUYIN_CDP_ENDPOINT=http://127.0.0.1:9222，仍使用 scripts/download.py 下载入口。已知作者时设置 VIDEO_DOWNLOAD_DOUYIN_AUTHOR_ID 为账号的 sec_uid。端点应以 MD-Browser 原有配置为准。

此模式仅连接现有环境、打开并关闭本次任务页，不导入 Cookie，不启动无头浏览器；连接或作品校验失败直接报错，不回退其他下载路径。从与目标 aweme_id 对应的详情取得媒体地址，校验作者、视频轨及时长，成功后生成 .mp4.meta.json，不保存视频临时 CDN 地址或 Cookie；详情封面地址供调用方及时归档。

依赖安装

pip3 install playwright && python3 -m playwright install chromium
brew install ffmpeg   # B站视频合并需要
brew install yt-dlp   # B站、抖音/小红书兜底及通用站点需要

故障排除

问题	解决方案
SSL 证书错误	脚本已内置 ssl._create_unverified_context
未捕获到视频地址	增加等待时间，或内容需要登录/是图文非视频
抖音/小红书回退 yt-dlp 后提示 fresh cookies	执行对应平台的 login 命令，保存新 Cookie 后重试
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
视频号提示未配置解析器	设置 WECHAT_CHANNELS_RESOLVER_URL
视频号解析失败/登录过期	在解析器服务端更新元宝登录 Cookie，不要把 Cookie 传给 Skill
视频号返回加密流	让解析器返回已解密代理 URL；Skill 不复制受限项目的解密代码

抖音素材工厂列表优先下载

调用方可设置 VIDEO_DOWNLOAD_DOUYIN_LIST_RECORD 为已核验的主页记录JSON，配合管理器返回的既有CDP endpoint和预期作者ID。优先下载列表中720p候选，失败再访问详情；实际选择及全部候选摘要写入meta。详情返回的新字段通过detail_updates交给调用方覆盖当前值。无参数时保留作品链接入口。清晰度选择与归档规则见douyin-scraper的素材工厂完整流程。