yt-dlp

yt-dlp

yt-dlp 的命令行工具技能：只读 URL 探测、字幕／转录文本提取，以及可选的媒体下载。任何下载前都必须遵循 转录优先协议。

范围： 通过 yt-dlp 支持的视频／音频托管平台、用户拥有的 Cookie 文件、播放列表元数据，以及保存到明确指定目录的本地输出。不适用于： 静态页面抓取（使用 Fetch MCP 或 curl）、广泛的多来源研究（research）、ffmpeg 转换方案（ffmpeg），或绕过平台服务条款。

---

规范术语

术语	含义	不包括
探测	通过 --dump-json 只读获取元数据；不写入媒体	下载
转录文本	将字幕／隐藏字幕提取为文本文件；优先于完整下载	默认提取音频
下载	探测并获得用户批准后保存媒体数据	未经确认的批量抓取
播放列表	多条目 URL；选择性下载前先列出条目	不加筛选地下载整个播放列表
Cookie	通过 --cookies 传入的用户拥有的 Netscape Cookie 文件	提交到仓库或随技能打包的机密
诊断	针对二进制文件、版本和 ffmpeg 的预检 JSON 报告	在线 URL 烟雾测试
格式 ID	探测得到的 yt-dlp format_id（例如 251、137+140）	猜测的扩展名
手动字幕	创作者上传的字幕	仅自动生成的字幕
自动字幕	平台生成的字幕	保证准确

---

调度

$ARGUMENTS	模式	操作
probe <url> / metadata <url> / info <url>	探测	运行内置的 probe_url.py；汇总标题、ID、时长和字幕
transcript <url> / subs <url> / captions <url>	转录文本	先探测；提取可用的最佳字幕，不下载视频
download <url> / fetch <url> / save <url>	下载	先探测；确认权利和格式；下载到明确指定的输出目录
playlist <url>	播放列表	允许播放列表进行探测；列出条目；仅在获得批准后选择性下载
cookies <path> / cookies check <path>	Cookie	验证用户拥有的 Cookie 文件路径；绝不复制到仓库
doctor / preflight	诊断	运行 scripts/doctor.py --format json
自然语言：“这是什么视频”“获取字幕”“下载这个”	自动	根据下方协议映射到探测 → 转录文本 → 下载
(空)	帮助	显示模式、协议、伦理说明和示例

自动检测规则

1. URL 加上 subtitle、caption、transcript、CC 等词 → 转录文本（仍须先探测）。
2. URL 加上 download、save、mp4、audio、rip 等词 → 下载（仍须先探测并获得批准）。
3. URL 加上 playlist、channel list、all videos → 播放列表。
4. 单独的 URL 或“这个链接是什么” → 探测。
5. 以 cookies.txt 结尾的路径，或提及登录／身份验证 → 提供 Cookie 指引，然后使用 --cookies 重新探测。
6. 意图不明确 → 询问：仅获取元数据、提取转录文本，还是下载？

---

转录优先协议

按顺序执行以下阶段。不得跳过探测。 在确认不需要转录文本之前，或用户明确要求媒体文件之前，不得下载。

阶段 1 — 诊断（每个会话运行一次，或出错后运行）

uv run python scripts/doctor.py --format json

如果出现 ok: false，或任何检查的 status: fail（缺少 yt-dlp 二进制文件），则停止。

阶段 2 — 探测（提取转录文本或下载前必须执行）

uv run python scripts/probe_url.py --url 'https://…' --format json

使用用户拥有的 Cookie：

uv run python scripts/probe_url.py --url 'https://…' --cookies "$HOME/.config/yt-dlp/cookies.txt" --format json

播放列表 URL（列出条目；探测时传入 --allow-playlist）：

uv run python scripts/probe_url.py --url 'https://www.youtube.com/playlist?list=PL…' --allow-playlist --format json

根据探测 JSON，报告：id、title、duration、uploader、availability、subtitles / automatic_captions 语言，以及推荐的 format_id 候选项。选择格式时，请加载 references/formats-and-quality.md。

阶段 3 — 字幕稿（优先于下载）

如果有字幕，则提取文本，无需下载视频：

yt-dlp --skip-download --write-subs --write-auto-subs --sub-langs 'en.*,en' \
  --convert-subs srt --sub-format srt \
  -o '%(title).200B.%(ext)s' \
  --paths home:"$HOME/Downloads/yt-dlp/transcripts" \
  'URL'

如果手动字幕和自动字幕都存在，优先使用手动字幕。说明生成 .srt / .vtt 的路径，并询问是否要去掉时间轴行以获取纯文本。如果没有字幕，则说明情况，并在下载以进行转录之前征求许可（成本更高，且涉及版权）。

阶段 4 — 下载（必须获得明确批准）

运行前：

1. 确认用户有权保存内容（请参考 references/ethics-and-tos.md 中关于个人使用、存档和合理使用的说明）。
2. 确认输出目录（默认：$HOME/Downloads/yt-dlp/media/）。
3. 根据探测结果确认格式（-f FORMAT，或使用合理的默认值：bv*+ba/b）。

mkdir -p "$HOME/Downloads/yt-dlp/media"
yt-dlp -f 'bv*+ba/b' \
  --paths home:"$HOME/Downloads/yt-dlp/media" \
  -o '%(playlist_index)s-%(title).200B.%(ext)s' \
  'URL'

报告输出路径、格式 ID、文件大小，以及是否运行了 ffmpeg 合并。

---

模式详情

探测模式

• 使用随附的 probe_url.py（封装 yt-dlp --dump-json --no-download）。
• 只读：不会在 cwd 或仓库下写入文件。
• 对于有年龄限制或仅限登录的内容，停止操作并转到Cookies，不要猜测凭据。

字幕稿

• 不要默认为了获取文本而下载视频/音频。
• 始终使用 --skip-download。
• 如果有多种语言，选择用户指定的语言；否则使用 en，并按探测结果中的备用语言列表回退。

下载

• 单个 URL 的默认设置：除非用户要求下载播放列表，否则使用 --no-playlist。
• 未经明确确认范围，不要批量下载频道内容或进行归档。
• 不要在聊天日志中的命令里嵌入 cookies；仅引用 $COOKIES 环境变量或用户提供的路径。

播放列表

1. 启用播放列表进行探测：

uv run python scripts/probe_url.py --url 'PLAYLIST_URL' --allow-playlist --format json

2. 按编号列出条目（索引、标题、时长）。
3. 获得批准后，仅下载选中的索引（--playlist-items 1,3,5）——绝不要不经确认就下载整个播放列表。

Cookies

• 仅使用用户自己的 cookie 文件——路径必须位于用户主目录下，或由用户明确提供。
• 绝不要提交 cookie 文件、将其存储在仓库中，也不要将其打包进技能包。
• 导出说明（浏览器扩展 → Netscape cookies.txt）位于 references/ethics-and-tos.md。
• 验证文件是否可读：

test -r "$HOME/.config/yt-dlp/cookies.txt" && echo readable

只有在用户提供路径后，才在探测/下载时传递 --cookies PATH。

Doctor

uv run python scripts/doctor.py --format json

解析 JSON 中的 ok、summary 和各项检查的 status。遇到 fail 时停止工作流。将 warn（例如缺少 ffmpeg）视为提示。

帮助

显示分发模式表、字幕稿优先的操作流程、默认路径和伦理参考链接。

展示（参数为空）

当 $ARGUMENTS 为空时，展示常用调用方式：

#	任务	示例
1	预检	/yt-dlp doctor
2	探测元数据	/yt-dlp probe https://www.youtube.com/watch?v=…
3	获取字幕	/yt-dlp transcript https://www.youtube.com/watch?v=…
4	下载（获批后）	/yt-dlp download https://www.youtube.com/watch?v=…
5	列出播放列表	/yt-dlp playlist https://www.youtube.com/playlist?list=…
6	用户自己的 cookies	/yt-dlp cookies ~/.config/yt-dlp/cookies.txt

选择一个编号、分发模式表中的模式，或粘贴 URL 并说明你需要元数据、字幕还是下载。

---

关键规则

1. 先探测，再获取字幕或下载——始终使用 probe_url.py 或等效的 --dump-json --no-download。
2. 先获取字幕，再下载——有字幕时，优先使用 --skip-download 提取字幕。
3. 下载前须获得明确批准——确认权利、范围、输出目录和格式。
4. 仅使用用户自己的 Cookie——绝不提交 Cookie、将其复制到仓库中，或自行编造 Cookie 路径。
5. 不得指导规避服务条款——参见 references/ethics-and-tos.md；拒绝 DRM 绕过或规避付费墙的请求。
6. 这不是 Fetch MCP——静态 HTML、文档页面和非 yt-dlp 主机应使用 Fetch MCP 或 curl，而不是此技能。
7. 这不是 ffmpeg 技能——如有需要，下载后再使用 /ffmpeg 进行重新封装、转码、剪辑或生成波形。
8. 输出遵循最小权限原则——仅写入用户批准的目录，绝不写入 Agents 仓库目录树。
9. 报告来源信息——在最终摘要中列出标题、URL、提取器、格式 ID 和输出路径。

---

故障排除

有关提取器错误、地理限制、签名失败和 ffmpeg 合并问题，请参见 references/troubleshooting.md。

---

参考资料

文件	适用场景
ethics-and-tos.md	权利、Cookie、拒绝边界
formats-and-quality.md	选择 -f 格式字符串
troubleshooting.md	doctor 检查通过后出现错误

---

脚本

脚本	用途
scripts/doctor.py	JSON 预检：yt-dlp、版本、ffmpeg
scripts/probe_url.py	只读 --dump-json 封装器
scripts/check.py	验证技能清单和评估

---

示例

# Preflight
uv run python scripts/doctor.py --format json

# Probe
uv run python scripts/probe_url.py --url 'https://www.youtube.com/watch?v=dQw4w9WgXcQ' --format json

# Transcript (after probe shows subs)
yt-dlp --skip-download --write-subs --write-auto-subs --sub-langs en -o '%(id)s' \
  --paths home:"$HOME/Downloads/yt-dlp/transcripts" 'URL'

# Download (after user approval)
yt-dlp -f 'bv*+ba/b' --paths home:"$HOME/Downloads/yt-dlp/media" -o '%(title).200B.%(ext)s' 'URL'