> 版权声明：本技能 (视频号视频一键下载) 由「书童哥」原创，核心解析脚本为自研实现（非任何第三方打包工具）。
> 允许个人学习与非商业使用；禁止未经授权的二次分发、售卖、或改头换面重新发布（含被 AI 蒸馏整合后改发）；如需转载或商用，须先获作者授权并保留署名。
> ⚠️ 合规与使用边界（务必阅读）：本工具不限制下载对象，但仅可用于你有权处理的视频号内容——本人发布过的作品、已获原作者授权的内容、或本地自有文件。下载他人视频号视频、提取用于剪辑 / 二创 / 搬运，须先取得版权方许可，否则构成著作权侵权，全部法律责任由使用者自行承担，与作者无关。本工具不支持解析付费、会员专享、私密作品。
视频号视频一键下载
Overview
一个专注微信视频号视频下载的工具型 skill。给你一个 https://weixin.qq.com/sph/... 分享链接，自动解析出真实直链并下载 mp4 到本地；如果你手头已有手机里的视频号视频文件，也能零登录直接整理到电脑。
原理（自研实现，不依赖任何第三方打包工具）：
视频号官方不提供公开下载接口，但分享链接 sph/... 可以通过腾讯元宝(Yuanbao) 的解析接口换成真实直链。本 skill 内置 scripts/wx_channels.py 实现这条链路：
- 用 Playwright 打开一个专用隔离的 Edge/Chrome 配置目录（不影响你日常浏览器），让你登录元宝。
- 拦截登录后的鉴权请求头，调用元宝
get_parse_result把 sph 链接换成可播放地址。 - 取出
generalToken+exportId，再调微信视频号finder-previewfeed 接口拿到真实videoUrl。 - 用标准库 urllib 把 mp4 流式下载到本地，并校验 ftyp 头。
安全约定：不安装系统根证书、不改系统代理（与"本地抓包"方案有本质区别）；不向外打印任何 cookie / token / 直链；只输出结构化 JSON。
触发逻辑 (When to Use)
当用户出现以下任一时触发本 skill：
- 发送 https://weixin.qq.com/sph/... 链接，想下载该视频号视频
- 说"下载视频号视频""视频号怎么保存""视频号视频怎么下载""保存视频号到本地""视频号解析""视频号直链"
- 手头有手机里的视频号视频文件（本地路径），想整理/转存到电脑
不触发：B站/抖音/YouTube 等其它平台（交给 media2text 等通用工具）。
> 关于"转录文字"：v1.1.0 起，下载后可加 --transcribe 联动 media2text（本 skill 就是从 media2text 分出来的，复用其转录/二创能力）自动产出逐字稿 + 多平台二创稿，形成「下载 → 转录 → 二创」闭环。若只需纯下载，不加该参数即可。
核心脚本
scripts/wx_channels.py（自研，单文件、可独立运行）。子命令：
| 命令 | 作用 |
|---|---|
doctor |
检查环境（浏览器是否安装、是否已登录元宝），不打印任何密钥 |
login |
打开隔离浏览器让用户登录元宝（一次性，长期有效） |
resolve <sph-url> |
只解析出直链与元信息，不保存 |
download <sph-url> |
解析并下载 mp4 到本地（默认 ~/Downloads，可用 --output-dir 指定）；支持 --transcribe 联动转录、--srt 导出字幕、--no-rewrite 仅转录 |
batch [urls...] [--file urls.txt] |
v1.1.0 新增 批量下载，整批只登录一次；支持与 download 相同的 --transcribe / --srt / --no-rewrite，输出汇总 JSON |
> v1.1.0 起，download / batch 下载 mp4 的同时会落盘一份同名 .json 元数据（作者/标题/封面 url/技术字段），并尽力抓取同名 .jpg 封面图。
Quick Start
方式一：本地文件（零登录·最快，推荐急着要视频时用）
手机微信点开视频 → 右下角「…」→「保存到相册」，或转发给「文件传输助手」后再另存到电脑，然后把本地文件路径告诉 AI 即可。无需安装任何东西、无需登录。
方式二：分享链接（贴链接·需登录元宝一次）
cd <本 skill>/scripts
# 第 1 步：登录元宝一次（会话存在专用隔离配置目录，之后长期有效）
python wx_channels.py login --browser edge # 或 --browser chrome
# 在弹出的浏览器里用微信/QQ 扫码登录元宝，登录成功关窗即可
# 第 2 步：把 sph 链接丢进来，自动下载 mp4 到本地
python wx_channels.py download "https://weixin.qq.com/sph/xxxxxx"
# 指定保存目录：
python wx_channels.py download "https://weixin.qq.com/sph/xxxxxx" --output-dir "D:/视频号下载"
# v1.1.0：下载后联动 media2text 做转录 + 多平台二创（需已安装 media2text 技能）
python wx_channels.py download "https://weixin.qq.com/sph/xxxxxx" --transcribe
# 仅转录 + 字幕，不要二创稿：
python wx_channels.py download "https://weixin.qq.com/sph/xxxxxx" --transcribe --no-rewrite --srt
# v1.1.0：批量下载（整批只登录一次，效率关键）
python wx_channels.py batch "https://weixin.qq.com/sph/aaa" "https://weixin.qq.com/sph/bbb" --output-dir "D:/视频号合集"
# 或从链接清单文件批量（每行一个，# 开头为注释）：
python wx_channels.py batch --file "D:/sph_urls.txt" --transcribe
> 首次使用（仅方式二）：依赖 Playwright 浏览器。安装：pip install "playwright>=1.52,<2" && playwright install chromium（或复用本机已装的 Edge/Chrome，见 dependencies）。方式一无需任何安装。
常见问题 (FAQ)
Q：视频号必须安装/登录什么？
A：只有"贴链接下载"需要 Playwright 浏览器 + 一次元宝登录（见 Quick Start 方式二）。"本地文件"方式什么都不用装。
Q：元宝登录麻烦吗？
A：只烦一次。登录态保存在本机专用隔离浏览器配置目录（%LOCALAPPDATA%/sphdownload/...），关掉窗口后依然有效，之后所有 sph 链接秒下，无需重复登录。不想登录？走"本地文件"方式零登录。
Q：为什么不用装根证书 / 改代理的方案？
A：市面上一些"抓包"类下载器要装系统根证书 + 改系统代理做中间人拦截，有安全和隐私隐患。本 skill 走元宝解析接口，不装根证书、不改系统代理，更安全干净。
Q：下载的 mp4 有水印吗？
A：按平台返回的原画质下载保存，不做额外加水印处理。
Q：元宝接口失效了怎么办？
A：腾讯内部接口可能随版本调整失效。失效时退回"手机下载到本地 → 传文件路径"的本地文件方式即可，不影响其它功能。
Q：会把我本地视频传到外面吗？
A：不会。下载过程仅联网腾讯服务器拿直链；视频文件存到你本机指定目录，不出电脑。本地文件方式更是完全不联网。
Q：v1.1.0 的 --transcribe 是什么？我没有 media2text 会怎样？
A：--transcribe 会在下载完成后调用 media2text（本 skill 就是从 media2text 分出来的，转录/二创能力由它提供）对本地 mp4 做转录，并产出逐字稿 + 多平台二创稿。找不到 media2text 时不会报错、也不会影响下载，只是跳过转录那一步（返回 transcribe.invoked=false 提示）。本机已配 key 时 media2text 走 LLM 三平台改写；无 key 退化为本地轻量清洗。
Q：v1.1.0 下载后会多出来 .json 和 .jpg 文件，是什么？
A：.json 是这条视频的元数据侧车（作者昵称、标题、封面地址、文件大小、sha256 等），.jpg 是尽力抓取的视频封面图。两者都不影响 mp4 本身；不需要可忽略，后续版本会加开关。
Q：批量下载 batch 和多次 download 有什么区别？
A：核心区别在登录次数。batch 整批只登录元宝一次就循环下载所有链接；多次 download 每次都要重新打开浏览器登录，慢且易被风控。batch 还支持 --file 从链接清单批量读入，并输出一份汇总 JSON 便于脚本化消费。
Q：视频号网页里那种"可扫码前往微信观看"的链接能用吗？
A：能用。https://channels.weixin.qq.com/finder-preview/pages/sph?id=XXX 这类网页预览链接会被自动归一化为 https://weixin.qq.com/sph/XXX 再解析（v1.1.6 起），无需手动转换。注意：预览页面上那个二维码只是网页端的观看门槛，本 skill 不走该页面，而是走元宝解析接口 + 视频号 feed 接口，所以网页端"限制升级"不影响本工具。仍推荐直接喂官方分享链接 weixin.qq.com/sph/...（微信里点「分享 → 复制链接」）。
Q：doctor 显示 logged_in: true，但 resolve/download 却报 401 YUANBAO_AUTH_FAILED？
A：doctor 的 logged_in 只表示专用配置目录里存在元宝登录 cookie，不代表会话仍然有效——元宝会话过期后 cookie 会残留，造成假阳性。只要解析报 401，直接重登一次即可：python wx_channels.py login --force --browser edge（会清掉旧会话，扫码后恢复，登录态长期有效）。
安全与隐私
- 登录态只存在专用配置目录，绝不读取你的日常浏览器 profile。
- 脚本不向外打印 cookie / token / 媒体直链 / 请求头，只输出结构化 JSON。
- 不安装系统根证书、不改系统代理。
报错与排错（v1.0.1 新增，v1.1.0 增强）
所有失败都会以结构化 JSON 返回 error.code 与 error.hint（一句能直接照做的处置），例如：
{ "ok": false, "error": { "code": "YUANBAO_AUTH_FAILED", "message": "元宝会话已失效，请重新登录", "hint": "元宝会话已失效，运行 login --force 清空专用配置目录后重新登录。" } }
完整错误码对照表见 references/troubleshooting.md。
拿不准时，先跑环境自检（不打印任何密钥）：
python wx_channels.py doctor --browser edge
依赖
详见 references/dependencies.md（仅"贴链接"方式需要 Playwright；"本地文件"方式零依赖）。
