# Wechat Video Skill

> 微信视频号视频下载。用户提供 https://weixin.qq.com/sph/... 分享链接并要求下载/保存/解析视频或直播回放时触发。后端为 wx_channels_download（WechatVideoSniffer CLI 版），通过本地代理捕获微信 PC 端 feed 并下载、解密；需要微信 PC 端在线配合。

- **Type:** Skill
- **Install:** `agentstack add skill-chantillyan-wechat-video-skill-wechat-video-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ChantillyAn](https://agentstack.voostack.com/s/chantillyan)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ChantillyAn](https://github.com/ChantillyAn)
- **Source:** https://github.com/ChantillyAn/wechat-video-skill

## Install

```sh
agentstack add skill-chantillyan-wechat-video-skill-wechat-video-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# WeChat Channels 视频号下载

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

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

## 环境与位置（通用探测）

- 后端二进制：按序探测 `WX_CHANNELS_BACKEND` 环境变量 → `PATH` → `WX_CHANNELS_HOME/backend//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/`

## 首次安装（无后端时）

```bash
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 ''`
   校验格式并检查后端是否已在运行（`local_api_2022_listening`）。
2. 若 API 未监听：先快照系统代理再启动后端：
   ```bash
   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，浏览历史里有真实下载地址与解密密钥：
     ```bash
     python3 scripts/download.py --list
     ```
     列出捕获的视频（index、标题、作者、是否含 url/decode_key）。
4. **下载 + 解密**：
   ```bash
   python3 scripts/download.py --browse  [--download-dir ]
   ```
   或直接给媒体地址：
   ```bash
   python3 scripts/download.py --url '' --key  --title ''
   ```
   解密仅作用于前 131072 字节（ISAAC-64 流密码），其余为明文。
   **下载后自动发飞书**（需本机 lark-cli 已认证）：
   ```bash
   python3 scripts/download.py --browse  --send-lark
   ```
   **下载后自动发微信**（需 dsh-wechat-bridge 插件已安装、账号已绑定，且用户在微信里给 bot 发过消息激活会话）：
   ```bash
   python3 scripts/download.py --browse  --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 后端可用但代理管理需自行处理。

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ChantillyAn](https://github.com/ChantillyAn)
- **Source:** [ChantillyAn/wechat-video-skill](https://github.com/ChantillyAn/wechat-video-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-chantillyan-wechat-video-skill-wechat-video-skill
- Seller: https://agentstack.voostack.com/s/chantillyan
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.