1实现原理 · 为什么它能做到

核心是 yt-dlp/ffmpeg CLI 封装：SKILL.md 指导 agent 用 yt-dlp 下载、ffmpeg 处理 HLS/转码，并自带 python 包装脚本 download_video.py 把下载流程程序化。

SKILL.md

Enable reliable video and audio downloads from YouTube and HLS streaming platforms (Mux, Vimeo, etc.) using yt-dlp and ffmpeg.

实现原理=编排外部 CLI，非自带解码。脚本内部 cmd = ["yt-dlp"] 开始拼 argv 再 subprocess.run，全程无 shell=True。

PO Token 提供者自动编排（高画质关键）：自动 pip 安装插件进 yt-dlp 的 Python 环境，优先 docker 跑 brainicism/bgutil-ytdlp-pot-provider 容器（-p 4416:4416），ping 127.0.0.1:4416 探活，Docker 缺失/失败则回退 pip 安装 yt-dlp-getpot-wpc 走浏览器 WPC 方案。

scripts/download_video.py

run_cmd = ["docker", "run", "-d", "--name", name] ... "-p", "4416:4416", *env_args, "--init", "brainicism/bgutil-ytdlp-pot-provider"

此处在做：把第三方 PO token 提供者容器化拉起并注入代理 env；对应 SKILL.md 声明 'YouTube downloads (up to 4K) using PO token providers'。代码不可在本 repo 审计（供应链面）。

cookie 认证路径：经授权后把浏览器 cookie 会话交给 yt-dlp（--cookies-from-browser chrome/firefox 或 --cookies 文件），有 cookie 时强制 youtube player client 走 web_safari。

scripts/download_video.py

cmd.extend(["--cookies-from-browser", cookies_from_browser]) ... elif cookies_file: cmd.extend(["--cookies", cookies_file])

此处在做：cookie 解密/读取实际由 yt-dlp 完成，脚本只透传参数，并据 SKILL.md 约定 'Ask before extracting browser cookies.' 走权限确认。

面向非技术用户的 UX 编排：agent 全代跑——先 --info 取元数据（失败走 YouTube oEmbed 兜底）确认视频身份，再按默认/选择下载，最后报告文件路径、大小、分辨率，全程不要求用户敲命令。

SKILL.md

Assume the user is non-technical. Do not ask them to run commands. Execute everything yourself and report progress in plain language.

oEmbed 兜底在脚本 fetch_oembed_info：urlopen https://www.youtube.com/oembed?...，bot 拦截时仍可确认标题/上传者，降低下错视频风险。

错误驱动重试链：把 yt-dlp 常见失败（403 / nsig / 'Only images are available' / SSL EOF）映射为策略——403 退非 m3u8 progressive 格式；PO token 故障则重启容器或切 WPC 重试；cookie+403 则换 web_safari client。

scripts/download_video.py

return "http error 403" in text or "403: forbidden" in text or "fragment 1 not found" in text

has_403_error/has_pot_error/has_wpc_error + download_video 内多重 retry 分支，是技能'可靠性'声称的技术来源。

代理感知设计（面向中国大陆网络）：读取环境代理 ALL_PROXY/HTTPS_PROXY/HTTP_PROXY 透传给 yt-dlp、pip、docker 容器，localhost 代理改写为 host.docker.internal；pip 走硬编码清华镜像 pypi.tuna.tsinghua.edu.cn。

scripts/download_video.py

PYPI_MIRROR = "https://pypi.tuna.tsinghua.edu.cn/simple"

normalize_proxy_for_docker 保留代理 URL 中的 user:password 并注入容器环境变量——代理凭证会进入第三方容器进程环境。

2核心能力

01YouTube 视频/播放列表下载，质量预设 best/1080p/720p/480p/360p/worst（MP4 合并输出）

02音频提取 MP3 与字幕下载（-x --audio-format mp3 / --write-subs --write-auto-subs --sub-lang）

03元数据预取与确认（--dump-json 解析 title/uploader/duration/thumbnail，失败回退 YouTube oEmbed）

04自动 PO Token 高画质解锁（Docker bgutil 优先 → 浏览器 WPC 回退 → 故障重启重试）

05浏览器 cookie 认证下载（--cookies-from-browser chrome/firefox，web_safari client，日志脱敏）

06HLS (m3u8) 受保护流下载指引与降级重试（ffmpeg -headers + -protocol_whitelist 指南；脚本内非 m3u8 progressive 回退格式）

07代理与镜像适配（中国大陆网络：清华 PyPI 镜像装插件、代理透传/容器化改写）

3外部依赖

Kind	Dependency / Endpoint
cli	yt-dlp
cli	ffmpeg / ffprobe
cli	docker
cli	python / pip（yt-dlp 解释器）
network	youtube.com（下载取流 + oEmbed 元数据）
network	清华 PyPI 镜像（硬编码装插件源）
network	Docker Hub 镜像 brainicism/bgutil-ytdlp-pot-provider（第三方 PO token 服务，拉取即执行）
network	本机 PO provider 探活端点
network	用户提供任意视频/HLS URL（m3u8 可指向任意第三方 CDN，如 Mux/Vimeo）
package	bgutil-ytdlp-pot-provider（pip 插件）
package	yt-dlp-getpot-wpc（pip 浏览器版 token 提供者，会启动真实浏览器）

4管控建议与判定依据

建议配套管控措施

面向 Agent

隔离环境，逐次授权

面向管理者

严格授权、全量审计、合规确认

判定依据（文件路径与关键语句摘要）

本地凭据 / 浏览器配置: 读取用户登录 Cookie/会话/密钥环: 浏览器 cookie：--cookies-from-browser chrome/firefox → yt-dlp 读取浏览器 cookie 库（脚本
scripts/: 执行本地脚本或命令: 外部 CLI：yt-dlp（下载/元数据/格式列出）、ffprobe/ffmpeg、docker run/start/rm/info、pip inst
scripts/ 或 SKILL.md: 声明动态安装外部语言包依赖
网络端点: 声明外部网络访问: youtube.com：yt-dlp 元数据/取流；oEmbed 兜底 urlopen https://www.youtube.com/oembed（
本地工作目录: 文件读写与工件输出: 下载输出：output_dir 递归 mkdir + 按 -o 模板写视频/音频/字幕文件（模板支持绝对路径与 yt-dlp %()s 语法，用户可指

审计说明： 侦查意见，非认证。黄标主因是凭证与供应链：(a) cookie 读取路径真实存在且是核心卖点（cookie 解密在 yt-dlp 侧完成，脚本透传并做日志脱敏，SKILL 要求先征询——有纪律但无强制）；(b) 自动 pip 安装两个第三方插件 + docker 拉取并常驻第三方 brainicism 容器，容器内代码超出本 repo 审计范围，.security-scan-passed 仅覆盖本目录静态文本的 gitleaks 扫描；(c) WPC 路径会拉起真实 Chrome 以用户登录态访问 YouTube；(d) 下载任意用户 URL、headers/模板原样信任构成 SSRF 与任意文件写侧面。脚本本身无 shell=True/无混淆/无隐蔽外发，故未到 red；绿档要求不成立，故定 yellow。

5第二遍独立确认

[ok] yt-dlp 调用真实存在（下载/-F/-o/-f/--dump-json） — 脚本 cmd = ["yt-dlp"] 起步（738 行），全部参数列表化
[ok] ffmpeg/ffprobe 调用 — SKILL.md 多处 ffmpeg 命令 + 脚本 get_video_resolution 中 which ffprobe 实测存在
[ok] cookie 读取路径（--cookies-from-browser / --cookies） — 773-776 行真实拼接；注意解密主体是 yt-dlp 而非脚本，脚本无 cookie 解析代码
[ok] cookie 日志脱敏 filter_cookie_lines — 仅过滤含 'extracting cookies' 或 'extracted'+'cookies' 的行，非完整脱敏（其他含 cookie 内容行仍会输出）——实现与声称基本一致，范围略窄
[ok] oEmbed 兜底网络端点 — 660-663 行 urlopen youtube.com/oembed，URL 经 quote 编码，无注入面
[ok] PO token：docker bgutil 容器 + 4416 ping 探活 — 437-446/553-563 行 docker run brainicism 镜像，255-257 行 ping；容器内实现本 repo 无法审计 → 供应链项如实标注
[ok] WPC 浏览器回退自动拉起 Chrome — 脚本只传 --extractor-args youtubepot-wpc:browser_path=…（249-252 行）+ find_chrome_path；真实浏览器启动由第三方插件 yt-dlp-getpot-wpc 完成，脚本侧证据到传参为止
[ok] pip 自动安装插件（清华镜像） — 350、377 行安装命令真实存在，PYPI_MIRROR 38 行硬编码

6结论

反爬故障知识高度工程化：nsig/PO token/403/'Only images'/SSL EOF 等坑被编码成错误分类与自动重试链，脚本自愈能力强

双层 UX 设计：面向非技术用户的白话流程 + 面向 agent 的内部 SOP，两者职责清晰、纪律一致（references/internal-sop.md 与 SKILL 清单逐条对应）

cookie 隐私纪律罕见地落在两层：SKILL 文本禁止暴露 cookie 明细 + 脚本层过滤日志行

国内网络定向适配完整（清华镜像、代理透传、docker 内 localhost 代理改写、WPC 兜底），对大陆用户实际可用

元数据 oEmbed 兜底 + 下载前确认，bot 拦截场景仍能避免下错视频

适合： 希望 agent 一键高质量下载 YouTube/公开 HLS 视频、愿意一次性授权 cookie 或安装 Docker/PO 插件的个人用户（含中国大陆走代理场景）；或需要在自有受控环境批量拉取有权内容的运维/内容工作者。

不适合： 零信任/供应链敏感的生产 agent 沙箱（会装第三方插件、拉第三方容器、自动开浏览器）；headless 无 GUI 且无 Docker 的环境（WPC 需浏览器窗口，仅剩 360p Android client）；不允许读取浏览器 cookie 的企业策略环境；无代理的国内直连（SKILL 自述失败模式依赖代理）。

Install Agent-Ready

① Verified Mirror 2026-09-06

Option A · Direct DownloadDownload youtube-downloader.tar.gz

sha256: 6c6c403e7e905b4e…

Option B · Copy Guide for Agent

install.json

agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit 63a65c1fcc.