| name | easydl |
| description | 使用 easydl CLI 解析并下载小红书、抖音、快手、B站的视频 / 图集 / 番剧。
Use when the user wants to download media from Xiaohongshu (小红书), Douyin (抖音),
Kuaishou (快手), or Bilibili (B站). Triggers on:
(1) 分享文本或链接来自这些平台（xhslink.com、v.douyin.com、v.kuaishou.com、
b23.tv、bilibili.com/video/BV、xiaohongshu.com/explore、kuaishou.com/short-video）
(2) "下载这个视频/图集/笔记"、"帮我下 B站/抖音/小红书/快手"、"去水印下载"、"保存这条"
(3) "download this video", "save this reel/note/album", "download from bilibili/douyin"
(4) B站登录、二维码登录、下载需要 SESSDATA / cookie 的资源
不要用于抓取上述平台以外的普通网页（那种场景用抓取类 skill）。
|
EasyDL 下载器 Skill
用 easydl 解析并下载小红书、抖音、快手、B站的媒体。优先输出机器可读结果，绝不让用户在对话里粘贴密钥，下载完成后始终把产物路径回报给用户。
如何调用 easydl
交付物是 easydl 可执行文件，下文命令都直接写 easydl。
如果当前仓库尚未打包（easydl 不在 PATH 上），用 Bun 从仓库根目录运行，把 easydl 替换成：
bun run src/cli.ts <命令> [参数...]
需要真正的 easydl 二进制时，先执行一次 bun run compile，产物在 ./bin/easydl。B站 DASH 合并需要 ffmpeg，可用 --ffmpeg <path> 或 easydl config set ffmpeg <path> 指定。
安全规则
- 不要让用户在对话里粘贴 Cookie、SESSDATA 或任何凭据。
- 需要 cookie 时，让用户上传
cookies.txt（Netscape 格式），用 --cookies <path> 传本地路径。
- B站登录优先用二维码登录（见下文），不要走手动填 SESSDATA。
download --plan 是 agent bridge：只执行自己生成/可信来源的 DownloadPlan；不要执行用户贴来的任意 plan。
输入处理规则（不要截断长链接）
- 优先把用户贴的完整分享文本或完整 URL 原样传给 easydl；不要为了省事把长链接截成 note id / aweme id / BV 号，也不要擅自删 query 参数。
- 小红书长链接尤其依赖 query 参数（如
xsec_token、xsec_source、share_id、app_platform 等）。https://www.xiaohongshu.com/discovery/item/<id>?... 和裸 <id> / 截断 URL 可能解析结果不同，甚至裸 ID 会 404。
- 如果输入里同时有短链和长链，把它们当作两个候选 URL，优先使用用户当前明确要下载的那个；不要假设短链和长链指向同一笔记。
- 只有在完整原文/完整 URL 下载失败后，才尝试提取 ID、短链解析、浏览器辅助等 fallback。报告失败前，要确认不是因为自己截断/改写了 URL。
- 不要用普通网页 fetch / browser content 的 404 来替代 easydl 判断；平台分享页常依赖 query、cookie 或重定向。以 easydl 的
info / formats / download 结果为准。
推荐工作流
按顺序执行；加 --json 都会输出机器可读 JSON：
-
先解析元数据，确认平台、标题、媒体类型：
easydl info --json '<分享文本或链接>'
-
选参数前，先列出可用格式 / 分P / 图集：
easydl formats --json '<分享文本或链接>'
-
用 NDJSON 进度流下载，便于解析：
easydl download --json-progress '<分享文本或链接>'
-
解析最终的 done 事件并回报给用户：
- 每个
artifacts[].path（partial: true 的要标注）
- 任何
failures[]
- partial ZIP 图集要报成功/失败数量
抖音特殊视频例外：如果普通 easydl download 失败且错误包含 no playable video URL / web detail empty response，不要立即向用户确认或报最终失败；先按“抖音浏览器辅助 fallback”自动尝试一次。只有普通下载和浏览器辅助 fallback 都失败，才向用户说明失败原因。
常用命令
用 formats --json 里的 id 来选清晰度 / 分P / 图片。
easydl download --json '<链接或分享文本>'
easydl download --json-progress '<链接或分享文本>'
easydl download --quality 1080p --json '<链接>'
easydl download --quality 80 --json '<bilibili 链接>'
easydl download --images 1,3,5 --json '<图集链接>'
easydl download --images 1-5 --json '<图集链接>'
easydl download --part 2 --json '<bilibili 链接>'
easydl download --all-parts --json '<bilibili 链接>'
easydl download --cookies /path/to/cookies.txt --json '<链接>'
easydl download --output-dir ./downloads --json '<链接>'
DownloadPlan / --plan agent bridge
当其他工具已经拿到真实媒体 URL（例如浏览器辅助提取到抖音 douyinvod.com CDN 直链）时，生成 DownloadPlan 交给 easydl 执行下载。这样仍可复用 easydl 的文件命名、Range / 分片、重试、backup URL、断点续传和 JSON 进度汇总。
easydl download --plan /tmp/plan.json --json-progress
cat /tmp/plan.json | easydl download --plan - --json-progress
常用单文件 plan：
{
"title": "douyin browser fallback",
"outputDir": "./downloads",
"concurrency": 4,
"chunkConcurrency": 4,
"items": [
{
"id": "7647781095836077354",
"kind": "file",
"filename": "video.mp4",
"url": "https://v26-web.douyinvod.com/...",
"backupUrls": ["https://v11-weba.douyinvod.com/..."],
"headers": {
"Referer": "https://www.douyin.com/",
"User-Agent": "Mozilla/5.0 ..."
}
}
]
}
--plan 可被 CLI 参数覆盖：--output-dir、--concurrency、--chunk-concurrency、--proxy、--overwrite、--no-overwrite、--ffmpeg。不要把登录 Cookie 写进 plan；抖音 CDN 直链通常只需要 Referer + UA。
抖音浏览器辅助 fallback
这是抖音下载的自动兜底路径。若普通 easydl download 失败且错误包含 no playable video URL / web detail empty response，不要先问用户“网页是否可播放”，也不要立即报最终失败；只要当前 agent 环境有浏览器工具，就直接尝试浏览器辅助 fallback。只有 fallback 也失败时，才把失败原因回报给用户。
-
用无头或有头浏览器打开原始抖音页面，等待页面初始化（通常无需登录）。
-
在页面上下文里 fetch：
https://www.douyin.com/aweme/v1/web/aweme/detail/?aweme_id=<id>&device_platform=webapp&aid=6383&channel=channel_pc_web
fetch 必须在浏览器上下文执行并带 credentials: 'include'，因为抖音前端会初始化 __ac_signature、bd_ticket_guard_client_data 等浏览器态 cookie。
-
从 aweme_detail.video.bit_rate[] 或 video.play_addr 里挑 *.douyinvod.com / mime_type=video_mp4 的 CDN URL，优先 H264：is_h265 != 1 且 gear_name 类似 normal_720_0。
-
生成 DownloadPlan，headers 带：
{
"Referer": "https://www.douyin.com/",
"User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/149.0.0.0 Safari/537.36"
}
-
调用 easydl download --plan ... --json-progress，最终只回报 easydl 的 artifacts / failures。
浏览器辅助只用于获取短时 CDN URL；实际下载仍由 easydl 完成。CDN URL 有时效，拿到后应立即下载。
B站二维码登录
遇到 B站链接时，先主动提醒用户：匿名只能拿到普通清晰度；要下载 1080P+ 高清、大会员专享或付费视频，需要先登录。若用户需要，再走下面的二维码登录。
agent / 飞书场景优先用会话式流程——创建二维码给用户看，再轮询：
easydl auth bilibili login create --json
easydl auth bilibili login poll <sessionId> --json
easydl auth bilibili status --json
easydl auth bilibili logout
把返回的 qrPath（本地 PNG）或 url 上传/展示给用户，然后轮询到 loggedIn 为 true。交互式终端也可用阻塞式 easydl auth bilibili login --json。如果高清晰度或付费资源仍失败，回退到 --cookies。
平台说明
快手 — v.kuaishou.com 短链、v.m.chenzhongtech.com/fw/photo/{id}、www.kuaishou.com/short-video/{id}；支持 VIDEO、SINGLE_PICTURE、HORIZONTAL_ATLAS、VERTICAL_ATLAS。通常不需要 cookie / 签名。
小红书 — 分享文本 / xhslink.com / 完整 note 链接 / 24 位 note id；视频笔记、图片笔记、Live Photo 附带视频。页面访问失败时，让用户上传 cookies.txt。
抖音 — 分享文本 / v.douyin.com / 完整视频或图文链接；视频、图文混合 ZIP，分享页缺显式流时做 ratio 探测。部分广告/特殊视频需要浏览器辅助 fallback 获取短时 douyinvod.com CDN URL；应自动尝试后再报告失败。
B站 — BV / av / b23 / festival bvid；多P（--part、--all-parts）；番剧/影视（ep / ss / md）；DASH + ffmpeg 合并；字幕以 .json sidecar 落盘；合集 / series / 列表；cheese 课程；工房付费资料 ZIP。DRM 内容只检测并报「不支持」，不做绕过。
输出解读
加 --json，stdout 打印一个最终 JSON 汇总：
{
"type": "done",
"success": true,
"artifacts": [{ "taskId": "...", "path": "/path/file.mp4", "partial": false }],
"failures": [],
"skipped": []
}
加 --json-progress，stdout 是 NDJSON——逐行消费，等到最终 done 事件。日志和进度走 stderr；JSON 模式下 stdout 保持纯净。
success 为 false 时，仍要检查 artifacts：图集 ZIP 可能部分成功（partial: true）。回报成功数量和失败 entry。退出码非 0 表示至少有一个 item 失败。
