z-video-downloader，9个平台视频一句话存本地

刷到一条好视频，第一反应是点收藏。然后就没有然后了。

收藏夹越堆越厚，真正回看的没几条。更别提哪天作者把视频删了，或者平台换个规则、下架、限地区，链接直接变灰，你连个备份都翻不出来。

最近在 GitHub 上翻到一个东西，路子我觉得挺对：它不给你一个界面让你自己点，而是把下载这件事整个交给 AI Agent。你说一句话，视频就落到本地硬盘上了。

它叫 z-video-downloader，作者是 tjxj，也是那套 z-skills 仓库里的一个 Skill，MIT 协议，开源免费。

一、它不是软件，是给 Agent 用的技能包

先把形态说清楚，免得找错地方。

它没有 exe，没有界面，装完之后桌面上也不会多出图标。整个东西就是一个文件夹加一份说明文档，放进 Agent 的 skills 目录里。你用自然语言跟 Claude Code、Codex、WorkBuddy 这类工具说话，Agent 读到说明，自己去调脚本干活。

也就是说，操作入口从图形界面挪到了对话框。

支持的平台 README 里列得很清楚：YouTube、Bilibili、Vimeo、X/Twitter、TikTok、抖音、Instagram、Facebook，再加上微信视频号，一共 9 个。m3u8、mpd 这类流媒体地址也认，mp4、webm、mov、mkv、m4v、flv、ogv 这些常见直链同样能直接下。

底层站的是 yt-dlp，但不是简单包一层壳。作者在它上面补了不少东西，下面慢慢说。

二、装上之后怎么用

最省事的办法，是把仓库地址整段丢给你的 Agent：

帮我安装 https://github.com/tjxj/z-skills/tree/main/z-video-downloader 这个 Skill，装好后告诉我怎么用

装完之后日常就是一句话的事：

帮我下载这个视频：https://www.bilibili.com/video/BV…

输出目录是固定的 Video/Downloads/YYYY-MM-DD-主题名/，日期加主题，视频文件、元数据、报告全堆在里面，找起来不费劲。

想自己敲命令也行，核心就一个脚本：

python3 scripts/download_video.py --title "主题名" "视频链接"

批量下载的话，把链接按行写进一个 txt，用 –url-file 指过去就行，空行和井号开头的注释会自动跳过。如果链接是从它的兄弟项目 z-web-pack 采集来的媒体清单，直接 –inventory 传那个 md 文件，不用手工复制。

依赖只有四个：Python 3.10+、requests、yt-dlp、ffmpeg。前两个一般都有，yt-dlp 负责平台视频，ffmpeg 负责音视频合并。缺哪个让 Agent 自己装，或者你手动补上都行。

三、视频号这块，是真刚需

前面那些平台，yt-dlp 本来就吃得下。真正让我觉得值的，是视频号。

视频号一直是下载器里的硬骨头。常见路子要么抓包，要么装证书、改系统代理，折腾一圈还容易被风控。作者这里换了条思路：走在线解析。

手机上打开视频号，点转发，底下有个“复制链接”，拿到的就是 https://weixin.qq.com/sph/xxx 这种格式的分享链接。把它交给 Agent，脚本识别出来之后，去调一个公开的解析服务拿真实地址，再下载落盘。

按 README 的说法，不需要微信登录态，不用装证书，也不用动系统代理。默认还同时存两个版本：H.264 的高清兼容版，和 H.265 的省空间版。文件名会自动从视频描述或者作者昵称生成，省得一个个手动改。

解析服务来自 ltaoo 的 wx_channels_download 项目，作者在致谢里也写明了出处，这点挺规矩。

四、几个细节做得挺到位

用下来比较舒服的是这几处。

默认值很克制。默认只下单条视频、不碰播放列表，除非你显式加 –playlist；画质默认卡在 1080p，要最高画质得自己加 –quality best；单文件超过 2000 MB 直接失败并记进报告。这几条默认值防的是同一件事：一条命令下去，硬盘被塞满。
断点续传。直链走 .part 文件加 HTTP Range，平台视频走 yt-dlp 的分片续传。下到一半断了，用 –run-dir 指回原来的目录接着下，不用从头再来。
字幕、封面、元数据一起落盘。–subtitles –sub-langs “zh.,en.” –embed-thumbnail 这一串下去，字幕和封面都带上，另外还会留一份 .info.json 记录视频来源。后面想拿去喂 AI 做总结，这些现成信息能省不少事。
下载历史去重。长期批量任务加 –download-archive，下过的直接跳过，不重复占空间。
报告是必出的。download-report.md 和 download-report.json，成功几个、失败几个、失败原因是什么、建议怎么重试，一条条列得清清楚楚。

五、我在 Windows 上跑了一遍

胖猫这台主力机是 Windows，所以拿直链实测了一次，过程原样说一下，没验过的我不瞎讲。

脚本本身是跨平台的，Python 3.13 直接跑起来没报错。输出目录按 Video/Downloads/2026-09-04-主题名/ 建好了，Windows 的反斜杠路径也写得对。

第一次我挑了个谷歌的公开样例视频，失败了。报告里原因写得很清楚：代理隧道连不上，502。这不是工具的问题，是我这边网络环境的锅。

换了个直链再跑，成功。770.0 KB 的 mov_bbb.mp4 落到本地，报告里状态、类型、平台、文件名、大小、来源链接一行列全。

有一点得说明白：这次测的是直链，机器上没装 ffmpeg，所以平台视频那套音视频合并我没验。想一步到位的话，先把 ffmpeg 装上再说。

六、几个坑先说在前面

好话讲完，坑也得提。

SKILL.md 里的路径是作者机器的。文档里写死的 Python 和 ffmpeg 路径是 /Users/zz/miniconda3/bin/python3 和 /opt/homebrew/bin/ffmpeg，一看就是 macOS。Windows 用户装的时候，要么让 Agent 自己探测本机路径并替换掉，要么手动改，不然会直接报找不到解释器。

YouTube 的兜底只有 360p。没有 cookie 的情况下，如果 yt-dlp 被登录校验拦住，脚本会转去试 Invidious 代理，优先存 360p 的 progressive MP4。能下下来，但画质就那样了，聊胜于无。在意清晰度就老老实实用 –cookies-file 给一份 cookies.txt；介意链接被转给第三方代理，就加 –no-invidious-fallback 把这条路关掉。

yt-dlp 版本要够新。这两年 YouTube 一直在上 PO Token、SABR 这类限制，老版本 yt-dlp 动不动就报“请登录以确认你不是机器人”。遇到这种情况先把 yt-dlp 升到最新版，大部分问题当场解决。社区里也有人反馈过，从旧版本升到新版之后立刻正常。

视频号解析走的是第三方服务。这意味着你的链接会离开本机，发到别人的服务器上去解析。涉及隐私或者未公开内容的时候，自己掂量一下。

合规这条必须讲。项目 README 末尾写了免责声明：仅用于技术交流学习，请尊重内容创作者权益，只下载你有权访问和保存的内容。说白了，自己备份、离线回看、做学习素材都没问题，拿别人的视频去搬运、二创、商用，那就是另一回事了。按下下载键之前，先想清楚用途。