微信视频号下载器
把 https://weixin.qq.com/sph/XXXX 形式的视频号分享链接下载为本地 MP4。
视频号没有「保存到本地」按钮，且 CDN 直链必须有登录态才能换取。本技能通过
腾讯元宝的解析接口拿到播放地址，再用 channels feed 接口换取 H.264/H.265 直链，
最后以单线程流式请求落盘并校验文件头。
何时使用
- 用户给出
weixin.qq.com/sph/...链接，要求下载 / 保存 / 转存 / 归档 - 用户要求把一堆视频号链接批量下到本地
- 用户要求只查询视频号的标题、作者、可用清晰度（用
resolve）
不适用于：抖音、小红书、B 站、YouTube 等其它平台（本技能只处理视频号）。
前置条件
- Python 3.9+
pip install requests playwright- 一次微信扫码登录腾讯元宝（
login子命令会拉起本机 Chrome/Edge，不需要
playwright install下载额外浏览器内核） - Cookie 有效期约 2 个月，过期后重跑
login即可
使用流程
1. 先确认登录态
python scripts/sph_dl.py resolve "<分享链接>"
resolve 会同时验证 Cookie。如果输出 Cookie 已过期，执行登录：
python scripts/sph_dl.py login
浏览器弹出后用微信扫码，检测到 hy_user / hy_token 即自动保存并退出。
Cookie 落在 ~/.wechat-sph/cookie.txt，浏览器配置留在 ~/.wechat-sph/profile。
2. 下载
# 单条
python scripts/sph_dl.py download "https://weixin.qq.com/sph/XXXX"
# 批量
python scripts/sph_dl.py download "https://weixin.qq.com/sph/AAA" "https://weixin.qq.com/sph/BBB"
# 从文件批量（每行一个链接，# 开头为注释）
python scripts/sph_dl.py download --url-file urls.txt
# 指定输出目录与编码
python scripts/sph_dl.py download --url-file urls.txt --out "D:/Media/视频号下载" --codec h265
# Cookie 失效时不要弹浏览器（自动化场景）
python scripts/sph_dl.py download "<链接>" --no-login
执行结束会在输出目录写 download-report.json，记录每条的成功/失败、字节数、
作者、描述与实际使用的清晰度。有失败条目时进程退出码为 1。
3. 交付给用户时
- 报告真实结果：成功几条、失败几条、各自大小
- 失败条目把
error原文一并说明，不要含糊成「部分成功」 - 需要确认视频是否真的可播时，用 PyAV 校验时长与分辨率，不要只看文件大小
关键实现约束（改动代码前必读）
- CDN 直链必须原样使用，保留
hy/idx/uzid/sign/bizid/dotrans/
basedata/X-snsvideoflag全部查询参数。只留encfilekey+token会
HTTP 400 Bad Request。 - 必须校验响应：无效 token 时 CDN 会返回 HTTP 200 + HTML 预览页。只校验
状态码会把 2–3KB 的 HTML 存成 .mp4 并误报成功。脚本已校验 Content-Type 与
MP4ftyp头。 - 不要用多线程 Range 下载：
finder.video.qq.com不支持并发 Range，会返回
「服务器不支持并发下载」。单线程requests流式即可。 - 在线解析站点不可依赖：
sph.litao.workers.dev等第三方在线解析已固定返回
401，元宝登录态是目前唯一稳定路径。 - 下载请求带
Referer: https://channels.weixin.qq.com/即可，CDN 不需要 Cookie。
详细接口链路、字段含义与历史坑位见 references/api-chain.md；
报错对照表见 references/troubleshooting.md。
边界
- 仅下载用户有权访问的公开视频，不绕过私密、已删除、付费或权限受限内容
- 不内置任何账号凭据；Cookie 属于用户本人，不要写进日志、报告或提交到仓库
- 下载内容的版权归原作者，二次使用请遵守平台规则与当地法律
