视频号爆款短视频拆解

技能文档

---
name: lingyi-wx-video-decomposer-plus
title: 视频号爆款短视频拆解
category: 内容创作
description: 一键拆解微信视频号爆款视频：结构分段、爆款归因、六维评分和可借鉴策略，输出 Markdown 报告，支持视频号分享链接和本地视频（100MB 以内）。当用户需要拆解视频号视频、分析爆款视频结构或学习对标视频文案时触发。触发词：视频号拆解、爆款拆解、视频分析、对标视频。
---

# 视频号爆款短视频拆解

使用远端服务拆解微信视频号视频。支持两种输入：微信视频号分享链接，或本地视频文件路径。本地视频会先上传到服务端，再发起拆解任务。脚本 [scripts/analyze_wx_video.py](scripts/analyze_wx_video.py) 负责全部 HTTP 调用，接口说明见 [references/api.md](references/api.md)。

## 技能工作流

### 步骤1：取 API Key

读技能目录下 `config.json` 的 `LY_API_KEY`（回退环境变量）。缺失或不合法时，按「鉴权」流程引导用户获取并写入，再继续。
### 步骤2：识别输入

判断用户提供的是视频号分享链接还是本地视频文件路径。无效或缺失时，按「引导话术」对应场景引导用户更正。
### 步骤3：扣点确认

首次执行（非 `--task-id` 恢复）时，运行脚本前向用户说明「本次拆解预计扣点约 128 点，实际扣点视任务复杂程度而定」，请用户确认后再继续；用户未确认不要运行脚本。恢复超时任务不重复扣点，跳过本步。详见「扣点与确认」。
### 步骤4：上传本地视频（仅本地视频）

本地文件走 预签名 → 直传 → 确认 三步换 `video_id`。上限 100MB，超限以退出码 2 退出。
### 步骤5：发起拆解

`share_url` 或 `video_id` 二选一调发起接口，取得 `analysis_task_id`。
### 步骤6：轮询等待

按 `--interval` 轮询状态，进度变了简短转述给用户；通常 1–5 分钟。
### 步骤7：交付报告

终态完成后，把分隔符之间的 Markdown 渲染给用户，告知本次实际扣点与报告查看方式。

> 若是恢复已超时的任务，直接用 `--task-id <id>` 从第 5 步恢复轮询。

任一步异常按「退出码处理」表对号入座，**不要自行判定失败**。

## 鉴权

Token 取「技能目录」（SKILL.md 所在目录）下 `config.json` 里的 `LY_API_KEY` 字段，回退到环境变量 `LY_API_KEY`。脚本请求头使用 `Authorization: <api_key>`，裸 key，不带 `Bearer`。`config.json` 形如：

```json
{ "LY_API_KEY": "你的密钥" }
```

运行脚本前，先按下面的流程确认 key 就绪。**任何时候都不要编造或猜测 key。**

1. **检查是否已有 key。** 读技能目录下的 `config.json`，看 `LY_API_KEY` 是否为非空字符串；若没有，再看环境变量 `LY_API_KEY`。两者任一有值即视为就绪，直接进入后续流程。
2. **缺失则引导用户获取。** 若都没有，停下来提示用户前往 <https://claw.lingyishuke.com/webapps/01claw-auth/index.html> 获取 API Key，并让用户把拿到的 Key 直接发给你。在拿到 key 之前不要运行脚本。
3. **记录用户发来的 key。** 收到 key 后，把它写入技能目录下的 `config.json` 的 `LY_API_KEY` 字段（保留文件其它内容），然后再运行脚本。该文件已被 `.gitignore` 忽略，不会入库。
4. **鉴权失败（退出码 3）时。** 多半是 key 失效或过期。提示用户重新前往上述地址获取新 key，按第 3 步覆盖写入 `config.json` 后重试；不要反复用同一个失效 key 重跑。

> 若运行报 SSL 证书错误（`CERTIFICATE_VERIFY_FAILED` 等，常见于 macOS 缺证书或企业代理环境），可设环境变量 `LY_SKIP_SSL_VERIFY=1` 后重试。注意：跳过证书校验有中间人风险，仅在受控环境临时使用。

## 输入识别

单次只处理一条输入：

- **微信视频号分享链接**：host 为 `weixin.qq.com`，典型链接如 `https://weixin.qq.com/sph/...`。直接把链接传给脚本。
- **本地视频文件路径**：文件存在，扩展名为 `.mp4` `.mov` `.m4v` `.avi` `.mkv` `.webm` `.flv` `.wmv`，且大小不超过 100MB。脚本会自动上传并换取 `video_id`。

不要处理其它平台链接。若用户给出非微信视频号链接，按「引导话术 > 非微信平台链接」引导。若未提供输入、本地文件不存在、格式不支持、文件超过 100MB，按「引导话术」对应场景引导。若一次给出多条或同时给出链接和本地文件，先让用户指定一条。

## 引导话术

当用户触发本技能但未提供有效输入、或输入有误时，按以下场景引导。语气亲和自然，不要罗列技术参数。

### 未提供输入

> 技能已就绪 ✅ 这个技能能帮你把一条视频号视频拆成一份爆款文案分析报告——包含结构分段、脚本类型判断、爆款归因、六维评分和可借鉴策略，直接照着学/抄 📊
>
> 随时可以开拆，把下面任意一种发给我即可：
>
> 1. **视频号分享链接** — 微信里打开要拆的视频，点右上角「···」→「复制链接」，把链接贴过来
> 2. **本地视频文件** — 已下载到电脑的视频，直接把文件拖进来或把路径发给我（支持 mp4 / mov / m4v / mkv / avi / webm / flv / wmv，100MB 以内）
>
> 拿到后我立刻提交拆解，通常 1–5 分钟出报告 📊

### 非微信平台链接

> 目前这个技能只支持**微信视频号**的视频哦，暂时没法直接处理 [抖音/B站/YouTube 等] 的链接。
>
> 不过你可以先把视频下载到电脑上，然后把本地文件路径发给我，我一样可以帮你拆解分析 😊

### 文件问题（不存在 / 格式不对 / 太大）

- **文件不存在**：找不到这个文件，麻烦检查一下路径是否正确？可以直接把文件拖到对话框里试试。
- **格式不支持**：这个文件格式暂时处理不了，支持的视频格式有：mp4、mov、m4v、avi、mkv、webm、flv、wmv。
- **文件过大**：这个视频有点大（超过 100MB 了），可以先用剪辑工具压缩一下再发给我。

### 缺少 API Key

> 拆解视频需要调用远端的付费拆解服务，首次使用得配置一下 API Key 🔑
>
> 👉 打开这个链接登录/注册 服务账号并获取 Key：https://claw.lingyishuke.com/webapps/01claw-auth/index.html
>
> 拿到 Key 后直接粘贴发给我（一串字符即可），我会帮你存好，之后拆解视频就不用再管它了。这个服务按次计费，余额不足时我会提醒你充值。

## 扣点与确认

本技能每次「新发起」拆解任务会消耗点数，整条链路对用户的扣点感知由你（assistant）来贯穿：

- **执行前确认（仅新任务，非 `--task_id` 恢复）**：识别成有效输入、API Key 就绪后，运行脚本前向用户说明并请其确认：

  > 本次拆解预计扣点约 128 点，实际扣点视任务复杂程度而定。是否继续？

  等用户明确确认后再运行脚本；用户未确认、未回应或要求改主意时，不要运行脚本。

- **执行成功后回告实际扣点**：见「输出交付」，把脚本透出的 `WX_VIDEO_POINTS_USED` 作为实际扣点告诉用户，并给出查看报告的方式。

- **执行失败后告知点数返还**：见「退出码处理」，任务已发起但未成功产出报告时，告知用户「因网络原因本次任务执行失败，相应点数已返还」并询问是否重试。

> 恢复已有任务（`--task_id`）时点数已在发起时扣除，本次仅继续轮询，不重复扣点、不需再次确认。

## 运行方式

在 skill 目录下运行：

```bash
python3 scripts/analyze_wx_video.py "<share_url 或 本地视频路径>"
```

恢复超时的任务（跳过输入/上传/创建，直接轮询）：

```bash
python3 scripts/analyze_wx_video.py --task-id "<task_id>"
```

可选参数：

- `--task-id ID`：已有的任务 ID，跳过输入识别/上传/创建，直接进入轮询。用于超时后恢复。
- `--out PATH`：报告输出路径，目录或文件均可。
- `--max-wait`：等待上限秒，默认 600。
- `--interval`：轮询间隔秒，默认 4。

## 本地视频上传

本地视频分支由脚本自动完成：

1. `POST /api/v1/content-ops/videos/public-upload-url` 获取预签名上传地址；
2. 直传文件字节到预签名地址；
3. `POST /api/v1/content-ops/videos/public-upload-confirm` 确认上传并取得 `video_id`；
4. 使用 `video_id` 发起拆解任务。

上传上限为 100MB。脚本会在上传前校验大小，超限以退出码 2 退出，不发任何请求。上传进度写到 stderr，必要时转述给用户。

## 发起拆解与轮询

脚本向 `POST /api/v1/social-analytics/collector/wx-video-analyses` 发起任务，`share_url` 与 `video_id` 二选一必填。成功后取得 `analysis_task_id`，再轮询：

```text
GET /api/v1/social-analytics/collector/wx-video-analyses/{analysis_task_id}
```

进度写到 stderr，报告写到 stdout。每当 `status`、`current_stage` 或 `progress_message` 变化时，可以简短转述给用户，让用户知道任务仍在推进。状态枚举见 [references/api.md](references/api.md)。

远端拆解通常需要 1-5 分钟。运行脚本后，**立即告诉用户**"已提交拆解任务，服务端正在处理，预计需要几分钟"，避免长时间沉默让用户误以为卡住。脚本运行期间不需要做其他操作，等待脚本返回即可。

若发起任务时余额不足，脚本以退出码 4 退出。引导用户前往 <https://claw.lingyishuke.com/webapps/01claw-auth/index.html> 充值；充值前不要继续轮询。

## 输出交付

成功时 stdout 形如：

```text
WX_VIDEO_POINTS_USED=<本次实际扣点，可能为空>
WX_VIDEO_REPORT_FILE=<报告文件绝对路径>
=== WX_VIDEO_REPORT_START ===
<完整 Markdown 报告>
=== WX_VIDEO_REPORT_END ===
```

交付时按顺序做三件事：

1. **渲染报告**：截取两个分隔符之间的 Markdown 渲染给用户。
2. **告知实际扣点**：若 `WX_VIDEO_POINTS_USED` 非空，告诉用户「本次任务实际扣除 {点数} 点」；为空时说「本次任务约扣 128 点（实际以服务端扣点为准，可在 01Claw 账户查看）」。
3. **告知报告查看方式**：报告已渲染在上方对话中；同时已保存为 Markdown 文件，路径见 `WX_VIDEO_REPORT_FILE`，可直接打开该文件查看或归档。

若文件写入失败但 stdout 有报告正文，仍按上面方式在对话中交付报告并说明扣点。

## 退出码处理

| 码 | 含义 | 处理 |
| --- | --- | --- |
| 0 | 成功 | 按「输出交付」处理。 |
| 2 | 输入错误 | 让用户更正链接、路径、格式或文件大小；超限时提示压缩或裁剪后重试。任务未发起，**不扣点**。 |
| 3 | 缺 key 或鉴权失败 | 按「鉴权」流程处理：引导用户前往 `https://claw.lingyishuke.com/webapps/01claw-auth/index.html` 获取 key，收到后写入 `config.json` 再重试。任务未发起，**不扣点**。 |
| 4 | 发起拆解失败，含余额不足 | 展示服务端 message；余额不足时引导用户前往 `https://claw.lingyishuke.com/webapps/01claw-auth/index.html` 充值，有服务端充值链接则优先用它。任务未成功发起，**不扣点**。 |
| 5 | 任务失败 | 告知用户「因网络原因本次任务执行失败，相应点数已返还」；转述 stderr 中的失败原因，并询问是否重试一次。 |
| 6 | 发起拆解或轮询阶段的网络 / 限流 / 任务失效 | 停止并告知用户「因网络原因本次任务执行失败，相应点数已返还」；说明网络、限流、服务端不可用或任务失效等实际原因；附 stderr 中具体信息，询问是否重试。 |
| 7 | 完成但报告为空 | 多为报告落库的短暂延迟（脚本已内置宽限等待，多数能自动补齐），少数是服务端解析未提取到正文。仍为空时：转述 stderr 中的 `current_stage`/`progress_message`/`error_message`（若有）；建议稍候用 `--task-id <id>` 重新轮询一次，仍为空则改用本地文件方式重新发起。任务已发起，按实际扣点处理。 |
| 9 | 本地视频上传失败 | 告知失败步骤，可让用户稍后重试。任务未发起，**不扣点**。 |
| 124 | 超时 | 说明任务可能仍在进行，附 task_id，用 `--task-id <id>` 重新轮询恢复。若用户放弃恢复，告知「因网络原因任务执行失败，相应点数已返还」并询问是否重试。 |

> 一句话：任务已发起但未成功产出报告（退出码 5、6，以及放弃恢复后的 124），统一告知用户「因网络原因本次任务执行失败，相应点数已返还」并询问是否重试；任务未发起到位的（2、3、4、9）不涉及扣点。

未知状态不要自行判定失败；脚本会原样透出 `progress_message`，继续按轮询结果处理。

使用说明

# 视频号爆款短视频拆解

把一条微信视频号视频拆成结构分段、爆款归因、六维评分和可借鉴策略，输出 Markdown 报告，支持分享链接与本地视频。

## 使用

对助手说：

```text
帮我拆解这条视频号视频：<分享链接>
```

首次使用需在 `config.json` 填入 `LY_API_KEY`（获取入口见 SKILL.md，按次计费）。本地视频直接发文件路径即可（100MB 以内），1–5 分钟出报告。

## 工作原理

脚本把视频（分享链接直传，本地文件经预签名上传换取 video_id）提交给远端拆解服务，服务端完成语音转写、结构分段、脚本类型判断、爆款归因与六维评分；客户端负责轮询任务状态并在终态后交付 Markdown 报告。超时任务可用 `--task-id` 恢复轮询，不重复扣点。

## 目录结构

- `SKILL.md`：工作流、引导话术、扣点确认与退出码处理
- `scripts/analyze_wx_video.py`：全部接口调用脚本
- `references/api.md`：接口参考
- `config.json`：密钥配置

## 依赖

- `python3`，需联网访问拆解服务（按次计费，需密钥）

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。