@optima-chat/optima-agent 0.9.7 → 0.9.8

package/.claude/skills/wechat/SKILL.md

@@ -1,174 +1,174 @@
----
-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 (内部异常) | 让用户提供链接给运维排查 |
+---
+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 (内部异常) | 让用户提供链接给运维排查 |