视频号视频下载
从 https://weixin.qq.com/sph/xxxx 分享链接下载视频号原片到本地。
触发条件
- 用户消息含
https://weixin.qq.com/sph/xxxx链接，并说"提取/下载/保存这个视频" - 或用户要求批量下载多个视频号链接
环境要求
- Python 3.9+（本机已有
~/.workbuddy/binaries/python/versions/3.13.12/bin/python3） - 工具目录（首次自动安装，约 20MB）：
- 优先
$SPH_WXDL_DIR - 其次
~/Desktop/WorkBuddy/视频号下载/wxdl（已存在则复用） - 否则
~/.workbuddy/tools/wx-channels-download - 可选：
agent-browser（仅在凭证失效、需要重新登录元宝时用到）
标准流程
1. 下载
python3 "<SKILL目录>/scripts/sph_download.py" "<sph_url>" "<输出目录>"
脚本自动完成：装依赖（含 sha256 校验）→ 起本地服务 → 校验凭证 → 解析 → 下载 → MP4 文件头校验。
输出 JSON：
| 输出 | 含义 | 下一步 |
|---|---|---|
{"ok": true, "file": ...} |
成功 | 交付文件 |
{"ok": false, "error": "credential_expired"} |
元宝凭证失效 | 走第 2 步刷新后重跑 |
其他 error |
按返回的 hint 处理 |
— |
多个链接就按顺序多次调用；脚本会自动复用已在运行的服务。
2. 刷新凭证（仅 credential_expired 时，需要用户在场）
agent-browser open "https://yuanbao.tencent.com/"
agent-browser snapshot -i # 找到「登录」→「微信快捷登录」并 click
- 多数情况本机会识别微信头像，点「微信快捷登录」一键完成；若出现二维码，
agent-browser screenshot出图给用户扫码 - 登录成功后写回凭证（自动提取 hy_source / hy_user / hy_token）：
cd "$(python3 -c "
import os
p = os.path.expanduser('~/Desktop/WorkBuddy/视频号下载/wxdl')
print(p if os.path.isdir(p) else os.path.expanduser('~/.workbuddy/tools/wx-channels-download'))
")" && agent-browser cookies get 2>&1 | python3 -c "
import sys, re, json
jar = {}
for line in sys.stdin.read().splitlines():
if '=' in line:
k, v = line.split('=', 1); jar[k.strip()] = v.strip()
cookie = 'hy_source=%s; hy_user=%s; hy_token=%s' % (jar['hy_source'], jar['hy_user'], jar['hy_token'])
cfg = open('config.yaml', encoding='utf-8').read()
cfg, n = re.subn(r'sphCookie: \".*?\"', lambda m: 'sphCookie: ' + json.dumps(cookie, ensure_ascii=False), cfg)
assert n == 1
open('config.yaml', 'w', encoding='utf-8').write(cfg)
print('sphCookie updated')
"
然后 pkill -f "wx_video_download server" 并重跑第 1 步（脚本会自动拉起新服务）。
3. 交付
- 可选校验：
ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1 <file> - 用
present_files把 mp4 交付给用户 - 收尾：
pkill -f "wx_video_download server"；若开过浏览器必须agent-browser close
已知坑
- 不要改
proxy.system：必须保持false，否则会改写系统代理并与第三方代理软件（如 Surge）冲突；skipInstallRootCert保持true，避免装根证书。 - 后台服务会被回收：普通 shell
&起的进程随会话结束被清理。脚本用start_new_session=True拉起，且每次调用会先探测服务是否已在运行。 - 两种 stodownload 链接：
picformat=200/wxampicformat结尾的是封面 JPEG，带X-snsvideoflag的才是视频流。脚本用ftyp文件头校验，误下封面会报错并删除。 - 视频号网页版不暴露视频流：sph 预览页只给封面和"扫码观看"，
channels.weixin.qq.com/web/pages/feed会跳"微信版本过低"更新页。不要尝试纯浏览器抓包方案。 - 凭证有效期：元宝 cookie 通常可用数天到数周，失效表现为
credential_expired，按第 2 步刷新即可（凭证仅存本地config.yaml，权限 600）。
依赖说明（第三方）
- wx_channels_download（开源），脚本从官方 GitHub Releases 下载
v260907，并对已核对过的平台做 sha256 校验，校验失败即中止。 - 解析视频号分享链接需要腾讯元宝（yuanbao.tencent.com）账号凭证，由使用者自行登录获取，脚本不会上传任何凭证。
合规提示
仅限个人学习、素材留存用途。请勿用于二次分发、商业使用或侵犯他人著作权；请遵守微信/视频号平台规则与当地法律法规。
