---
name: wechat
description: "微信视频号视频下载与 metadata 查询。使用场景：下载视频号/微信视频/weixin.qq.com/sph/ 链接，或查看视频号信息/作者/话题/点赞。使用 scout wechat 命令。"
---

# 微信 - 视频号视频下载与 metadata

所有命令使用 `scout wechat` 前缀。当前覆盖**视频号(Channels)**,未来可扩展到公众号、小程序等其他微信 surface。

> **依赖**:`@optima-chat/scout-cli >= 0.14.0`(`scout wechat` 命令在 0.14.0 引入)。如果 CLI 报 `unknown command 'wechat'`,说明环境里 scout-cli 版本太低,**不要重试**,直接告诉用户"请升级 scout-cli 到 0.14.0 或以上"。

---

## 快速选择

| 你的目标 | 命令 |
|---------|------|
| **下载视频号视频**(拿可播放 mp4) | `scout wechat fetch <url或exportId>` |
| **只看 metadata**(作者/话题/点赞,不下载) | `scout wechat metadata <url或exportId>` |

---

## 典型场景

当用户说:
- "下载这个视频号" + 链接 → `scout wechat fetch <url>`
- "下载微信视频" + 链接 → `scout wechat fetch <url>`
- "看看这个视频号的信息" / "这个视频号谁发的" → `scout wechat metadata <url>`
- 用户直接贴 `weixin.qq.com/sph/xxx` 或 `channels.weixin.qq.com/.../sph?id=xxx`，无其他说明 → 默认走 `metadata`（避免误烧 TikHub 额度；用户明确说"下载"/"保存"才走 `fetch`）

---

## URL 解析 - 视频号链接处理

视频号视频有三种形态,**都直接传给命令即可,不需要自己解析**(命令内置正则):

| URL 形态 | 示例 |
|---------|------|
| 短链 | `https://weixin.qq.com/sph/Azn5HYOeb0` |
| 完整链 | `https://channels.weixin.qq.com/finder-preview/pages/sph?id=Azn5HYOeb0` |
| 裸 exportId(10 位短码) | `Azn5HYOeb0` |

```bash
# 三种都行（以下示例用 fetch 演示 URL 形态；实际用哪个命令看场景，默认 metadata）
scout wechat fetch https://weixin.qq.com/sph/Azn5HYOeb0
scout wechat fetch "https://channels.weixin.qq.com/finder-preview/pages/sph?id=Azn5HYOeb0"
scout wechat fetch Azn5HYOeb0
```

**不要用 WebFetch** 去抓视频号页面 — 视频是加密的,WebFetch 拿不到。

---

## 核心命令

### 1. fetch - 下载视频 + metadata

完整 pipeline:解析 URL → TikHub 拿 metadata + 加密 CDN → 下载 + 解密 → 上传 S3 → 返回可播放 mp4 URL。

```bash
scout wechat fetch https://weixin.qq.com/sph/Azn5HYOeb0
```

**返回数据**(JSON):
- `data.videoUrl` — 可直接播放/下载的 mp4 URL(S3,公开读)
- `data.videoSize` — 文件字节数
- `data.metadata.title` — 标题
- `data.metadata.author.nickname` — 作者昵称
- `data.metadata.author.auth` — 认证身份(若有)
- `data.metadata.topics` — 话题列表(从 `#xxx` 解析)
- `data.metadata.video.durationSec` — 视频时长(秒)
- `data.metadata.video.width / height` — 分辨率
- `data.metadata.stats` — `like / comment / forward / fav`
- `data.metadata.coverUrl` — 封面图

**下载视频文件**:拿到 `videoUrl` 后用任意 HTTP 工具:
```bash
# Linux/macOS 通常有 wget
wget -O video.mp4 "<videoUrl>"

# Windows / 没有 wget — 用 curl (curl 在 macOS / Win10+ 都自带)
curl -L -o video.mp4 "<videoUrl>"
```

### 2. metadata - 只看信息

不下载视频文件,只拿 metadata 字段(省 S3 流量,但仍消耗 1 次 TikHub 额度)。

```bash
scout wechat metadata https://weixin.qq.com/sph/Azn5HYOeb0
```

返回字段跟 `fetch` 的 `data.metadata` 一致,但没有 `videoUrl / videoSize`。

**何时用 metadata 而不是 fetch**:
- 用户问"这视频谁发的""讲什么的""多少赞" → 用 metadata
- 用户要"下载""视频文件""保存下来" → 用 fetch
- 用户只贴链接、没说要做什么 → 默认 metadata（见典型场景第 4 条）

---

## 限制与注意事项

1. **画质**:目前只能拿低清版本(约 576×1024,1-3 MB),TikHub 公开 API 不返回高清 30 MB 版
2. **每次消费 TikHub 额度**:`fetch_video_detail` 大约 \$0.01/次,频繁调用会烧钱,先 `metadata` 看看有没有必要再 `fetch`
3. **依赖 decrypt server**:`fetch` 的解密步骤依赖外部部署的 decrypt 服务,如果返回 **503 Service Unavailable**,说明 backend 配置缺失(`WECHAT_DECRYPT_API_URL` 没设),应该告知用户"视频号下载服务暂未配置,请联系 SRE"
4. **错误码语义**:
   - `400` — URL 解析不出 exportId(用户给的链接不对)
   - `502` — TikHub / CDN / decrypt server 上游失败(短期重试可能恢复)
   - `503` — backend 没配解密服务(SRE 还没部署)
   - `500` — 其它内部异常
5. **videoUrl 是一次性签名链接**:`fetch` pipeline 必须一气呵成拿到后立刻返回,不要中间缓存;只直接返回给当前用户,不要存储或转发给第三方系统(链接很快失效)
6. **scope 限定**:这个 skill 只管视频号(Channels),不要用它处理公众号文章 / 小程序 / 朋友圈

---

## 工作流示例

### 用户给链接要下载

```
用户:帮我下载这个视频号 https://weixin.qq.com/sph/Azn5HYOeb0
```

```bash
scout wechat fetch https://weixin.qq.com/sph/Azn5HYOeb0
```

返回 JSON 后,以 Markdown 链接格式展示 `videoUrl`（如 `[点击播放/下载](<实际 videoUrl>)`），并列出标题、作者昵称、时长。

### 用户问"这视频啥情况"

```
用户:这条视频号链接讲啥的 https://weixin.qq.com/sph/Azn5HYOeb0
```

```bash
scout wechat metadata https://weixin.qq.com/sph/Azn5HYOeb0
```

列出标题、作者昵称、时长、话题、点赞数给用户，不消耗 S3 / 解密资源。

### 用户给的是 exportId 且只想看信息

```
用户:看下 Azn5HYOeb0 这个视频号
```

```bash
scout wechat metadata Azn5HYOeb0
```

直接传短码，命令内部识别。

### 用户给的是 exportId 且要下载

```
用户:下载 Azn5HYOeb0
```

```bash
scout wechat fetch Azn5HYOeb0
```

直接传短码，命令内部识别。

### 出错怎么办

| 状态 | 处理 |
|------|------|
| 400 (URL 解析失败) | 跟用户说"这个链接不是视频号链接,请贴 `weixin.qq.com/sph/...` 或 `channels.weixin.qq.com/...` 的链接" |
| 502 (上游失败) | 重试 1 次;仍失败告诉用户"上游服务波动,稍后再试" |
| 503 (服务未配置) | 告诉用户"视频号下载服务暂未上线,请联系运维"(不要重试) |
| 500 (内部异常) | 让用户提供链接给运维排查 |
