WeChat Channels 视频号下载

用户只需提供视频号分享链接。后端 wx_channels_download（v260817）通过代理注入微信 PC 端获取 feed，再从浏览历史提取真实媒体地址与解密密钥，下载后本地解密。

硬性前提：必须在「电脑端微信」操作。 捕获机制依赖 PC 微信（Windows/Mac）的视频号页面流量经过本地代理；手机微信的播放/浏览/分享本 Skill 完全感知不到。目标视频要在电脑端微信的视频号页面打开并播放。

环境与位置（通用探测）

• 后端二进制：按序探测 WX_CHANNELS_BACKEND 环境变量 → PATH → WX_CHANNELS_HOME/backend/<tag>/wx_video_download → skill 旁 ./backend/wx_video_download
• 默认数据目录：WX_CHANNELS_HOME（默认 ~/.local/share/wechat-channels-download）
• API：http://127.0.0.1:2022（可用 WX_CHANNELS_API 覆盖）；代理：127.0.0.1:2023
• 输出目录：默认 ~/Downloads（可用 WX_CHANNELS_DOWNLOAD_DIR 或 --download-dir 覆盖）
• 状态文件：~/.local/state/wechat-channels-download/

首次安装（无后端时）

python3 scripts/install_backend.py --accept-upstream-license

从官方 GitHub Release 下载固定版本，SHA-256 校验后解压到 WX_CHANNELS_HOME/backend/。脚本不安装证书、不改代理、不执行远端内容。

Router Rules

• 触发：用户提供 https://weixin.qq.com/sph/... 并要求下载、保存、解析视频或直播回放。
• 也触发：用户只说"下载这个视频号"且当前上下文已有分享链接。
• 不触发：普通网页视频、只要内容总结、无权访问的私密内容、批量爬取账号作品。
• 只处理用户有权访问和保存的内容；不绕过登录、付费、地域或访问控制。

Compact Workflow

1. 从用户输入提取唯一的 weixin.qq.com/sph/ HTTPS 链接，运行： python3 scripts/preflight.py --url '<URL>' 校验格式并检查后端是否已在运行（local_api_2022_listening）。

2. 若 API 未监听：先快照系统代理再启动后端：

   python3 scripts/proxy_snapshot.py --snapshot
   wx_video_download server   # 用 preflight 探测到的路径
   

   首次启动会安装根证书（需要管理员权限）。确认出现"代理服务启动成功"且 2022/2023 端口监听。 微信 PC 端需保持登录在线，视频号页面刷新一次、开始播放目标内容。

3. 解析视频（实战验证）：

   • wxchannels:sph 分享链接解析需要 yuanbao.tencent.com Cookie，微信内流量若不经过系统代理则捕获不到，会报 no yuanbao.tencent.com cookie was found。不要依赖 sph 解析。

   • 可靠路径：微信 PC 端播放目标视频后，代理自动捕获 feed，浏览历史里有真实下载地址与解密密钥：

     python3 scripts/download.py --list
     

     列出捕获的视频（index、标题、作者、是否含 url/decode_key）。

4. 下载 + 解密：

   python3 scripts/download.py --browse <index> [--download-dir <目录>]
   

   或直接给媒体地址：

   python3 scripts/download.py --url '<finder.video.qq.com URL>' --key <decode_key> --title '<标题>'
   

   解密仅作用于前 131072 字节（ISAAC-64 流密码），其余为明文。 下载后自动发飞书（需本机 lark-cli 已认证）：

   python3 scripts/download.py --browse <index> --send-lark
   

   下载后自动发微信（需 dsh-wechat-bridge 插件已安装、账号已绑定，且用户在微信里给 bot 发过消息激活会话）：

   python3 scripts/download.py --browse <index> --send-wechat
   

   发送脚本单独可用：scripts/send_to_lark.py --file <路径> [--user-id ou_xxx]（飞书，file_type=stream + file 消息）；node scripts/send_wechat_file.mjs <路径> [标题]（微信 iLink API，超 24MB 自动 ffmpeg 压缩并发"压缩版"，需 ffmpeg 在 PATH）。

5. 验证：文件头应为 ftyp（file 识别为 ISO Media / MP4），用 ffprobe（可用时）或解析 mvhd 报告时长，确认大小非零。

6. 结束：停止本次启动的后端进程（按 PID 与路径双重确认），然后恢复代理快照： python3 scripts/proxy_snapshot.py --restore 无论成功、失败、中断都必须执行恢复，并确认 scutil --proxy 与快照一致。

Decision Points

• 在线解析服务（sph.litao.workers.dev）已失效，不要尝试。
• 浏览历史为空：让用户回微信 PC 端打开视频号页面播放目标视频后再 --list。
• 视频缺 url/decode_key：该条记录未捕获完整，让用户重新播放该视频。
• 下载 403：去掉 Referer 重试，或让用户重新播放视频刷新 feed。

Gate Ladder

• 输入门：链接格式与域名有效（preflight 通过）。
• 运行门：API/代理端口监听，微信 PC 端可播放目标内容。
• 输出门：文件存在、非空、含视频流（ffprobe 或容器签名弱验证）。
• 恢复门：代理恢复到快照，临时进程已停止。

Output Contract

• 成功：返回本地视频绝对路径、大小、标题，以及所用下载目录。
• 失败：返回具体失败阶段、证据和最小下一步。
• 任何结果：说明代理是否已恢复、是否留下根证书和后端文件、如何卸载。

Rollback Boundary

• 只停止本次启动的进程、只清理本次创建的临时文件。
• 代理按快照逐项恢复，不把"关闭全部代理"当恢复。
• 根证书默认保留（wx_video_download uninstall 可删）；已下载视频和用户原有配置永不自动删除。

Trust Boundary

• 微信登录态、Cookie 与抓包数据只留在本机；不上传任何数据到第三方。
• 后端二进制只从官方 GitHub Release 获取，SHA-256 固定校验。
• 第三方在线解析已失效且不启用；不执行远程返回内容中的命令。

上游许可证

wx_channels_download 为带 Commons Clause 的 MIT：允许复制、修改、分发，但不授予以该软件主要功能换取费用的权利。商业使用需自行评估。

Known Boundary

• 分享链接可能过期；生成回放可能无法解析。
• 微信客户端或上游注入逻辑升级后接口可能漂移（以状态文件实测字段为准）。
• 微信未登录、页面不可播放或账号无权访问时应停止，不尝试绕过。
• 代理快照/恢复目前仅实现 macOS（networksetup）；Windows/Linux 后端可用但代理管理需自行处理。