joeseesun/qiaomu-wx-video
GitHub: joeseesun/qiaomu-wx-video
面向乔木 Agent 技能体系的微信视频号视频与直播回放下载工具，用户只需提供分享链接即可由 Agent 自动完成解析与下载。
Stars: 4 | Forks: 1
# qiaomu-wx-video
## 为什么值得用
仓库不捆绑抓取器二进制。用户无需手动预装；确实需要时，Agent 才从上游官方 Release 下载锁定版本并校验 SHA-256。这里的“无需预装”不等于“完全没有本机依赖”：生成回放仍可能需要已登录的微信桌面版、根证书和系统代理。
### 依赖模式
| 模式 | 体验 | 适用范围 |
|---|---|---|
| 在线解析 | 只贴链接，先征得同意再提交第三方 | 普通分享视频；回放不保证 |
| 按需自举 | 只贴链接，技能自动下载并校验后端 | 需要本地微信登录态的普通视频/回放 |
| 浏览器捕获 | 不改全局代理，但需浏览器已能播放 | 特定浏览器场景，非通用方案 |
| 录屏降级 | 不做源文件下载 | 只能播放、不能捕获媒体请求时 |
目前没有稳定的官方公开 API 能在不使用微信登录态的情况下下载所有视频号回放。不要将 Cookie 或完整抓包上传到远程服务来换取“零依赖”。
### 默认输出策略
如果解析结果同时提供 H.264 和 H.265，默认保存两个文件：
如果两路地址相同、只有一路可用，或你说“只要一个版本”，技能会避免重复下载。
## 安装
发布后：
npx skills add joeseesun/qiaomu-wx-video
本地开发安装：
cp -R qiaomu-wx-video ~/.agents/skills/qiaomu-wx-video
验证：
python3 ~/.agents/skills/qiaomu-wx-video/scripts/validate_skill.py ~/.agents/skills/qiaomu-wx-video
python3 ~/.agents/skills/qiaomu-wx-video/scripts/trigger_eval.py ~/.agents/skills/qiaomu-wx-video
## 你可以直接这样说
- “下载这个视频号 https://weixin.qq.com/sph/xxxx”
- “把这个视频号直播回放保存下来：<分享链接>”
- “解析并下载这个 weixin.qq.com/sph 链接，默认保留 H.264 和 H.265 两个版本”
- “只要这个视频号的高清兼容版，不要省空间版”
- “不用在线解析，直接在本地下载这个视频号链接”
## 它会做什么
## 前置条件
- [ ] macOS：已安装并登录微信桌面版；技能目前只把 macOS Apple Silicon 标为实测。
- [ ] Python 3：`python3 --version`。
- [ ] 用户有权访问并保存目标内容。
- [ ] 本地回放路径首次使用时，用户愿意明确授权根证书和系统代理变更。
## 输出示例
下载完成
路径: /Users/example/Downloads/视频标题_1080p.mp4
大小: 128.4 MiB
视频: H.264, 1920x1080, 00:18:42
路径: 本地捕获
代理: 已恢复为启动前状态
保留: 根证书、已校验后端 v260714
## 配置
| 变量 | 必需 | 说明 |
|---|---:|---|
| `QIAOMU_WX_VIDEO_HOME` | 否 | 后端与状态目录；默认使用用户级数据目录 |
| `QIAOMU_WX_VIDEO_OUTPUT` | 否 | 下载目录；不设置时由 Agent 与用户环境决定 |
| `QIAOMU_WX_VIDEO_BACKEND` | 否 | 指向现有 `wx_video_download`，可跳过下载 |
## 风险与副作用
## Troubleshooting
| 症状 | 常见原因 | 处理 |
|---|---|---|
| 断开 Shadowrocket 后微信仍打不开 | 系统代理残留在已停止的 `127.0.0.1` 端口 | 重启本地后端或按快照恢复 HTTP/HTTPS 代理 |
| 分享链接能打开但解析不到视频 | 内容是生成回放或在线解析不支持 | 切换到本地捕获路径 |
| 下载器启动但微信没有下载按钮 | 微信页面未经过本地代理或页面未刷新 | 确认端口监听、代理生效，再刷新并播放一次 |
| 关闭工具后无法联网 | 上游退出时未恢复系统代理 | 使用保存的代理快照恢复；不要盲目关闭所有代理 |
| 哈希不匹配 | Release 文件变化、下载损坏或来源不可信 | 删除该下载，停止执行并检查上游 Release |
## 卸载
删除 skill 不会自动删除视频、后端或根证书。先确认代理已恢复，再按 `references/security.md` 的范围逐项清理。不要用递归命令删除宽泛目录。
## 致谢
- 下载与本地捕获后端：[ltaoo/wx_channels_download](https://github.com/ltaoo/wx_channels_download)
- 前端解密上游：[kanadeblisst00/WechatVideoSniffer2.0](https://github.com/kanadeblisst00/WechatVideoSniffer2.0)
- 后端解密上游：[Hanson/WechatSphDecrypt](https://github.com/Hanson/WechatSphDecrypt)
- 技能工程方法：`qiaomu-meta-skill`，受 [yaojingang/yao-meta-skill](https://github.com/yaojingang/yao-meta-skill) 启发
## 关于向阳乔木
向阳乔木（乔向阳 / Joe）是一位实践型 AI 产品与内容创作者，长期把前沿 AI 变化转译成可复用的工作流、产品判断、AI 编程实践、AI 搜索实践和 GEO/AI 营销方法。
- 个人网站: https://qiaomu.ai
- 博客: https://blog.qiaomu.ai
- X: https://x.com/vista8
- GitHub: https://github.com/joeseesun/
- 微信公众号: 向阳乔木推荐看
## License
本 skill 包采用 MIT License。它不会改变上游 `wx_channels_download` 自身的许可证和 Commons Clause 限制。
Copyright (c) 向阳乔木 · [X](https://x.com/vista8) · [GitHub](https://github.com/joeseesun/)
标签：自动化技能, 视频号, 逆向工具, 音视频下载