视频号爆款短视频拆解

技能文档

---
name: omni-viral-video-deconstruction
title: 视频号爆款短视频拆解
category: 内容创作
description: "对本地视频文件本地提取素材（元数据/关键帧/字幕），按视频号带货与流量逻辑拆成结构分段、脚本类型、爆款归因和六维评分报告，原视频/帧/音频均不上传。当用户需要拆解短视频、分析爆款视频结构、给视频打分归因、学习爆款套路时触发。触发词：短视频拆解、爆款分析、视频号拆解、视频结构分析。需配置服务 API Key，每次开单扣 5 点；仅支持本地视频上传，暂不支持视频号链接。"
---


# 视频号爆款短视频拆解

对本地视频文件本地提取素材（元数据 / 关键帧 / 字幕），向网关分 3 包领取写作说明书，由 agent 当前配置的模型完成结构化拆解。**原视频 / 帧 / 音频 / 本地路径均不上传**。写作方法不在本技能包内：必须联网领取当前包 prompt，禁止凭记忆或旧模板写报告。

## ⚠️ 完成判定硬性规则（最高优先级，先读再做）

长上下文下不要凭记忆判定报告是否写完——一切以**磁盘上的 `report.md` + 本地结构门禁 `scripts/verify_report_structure.py` 的退出码**为准：

- 未通过本地门禁（`ok=false` / 退出码 12）之前，禁止回复任何含「全部完成 / 任务完成 / 报告已交付 / 校验通过」语义的收尾语。
- 宣布完成前必须重新 `Read` 一次磁盘上的 `report.md`，并确认门禁 `ok=true`。
- 完成只认本地门禁。报告回传另起一句提及即可；回传失败不影响「报告已写完」。
- 门禁不达标：按其 `missing_*` / `issues` 仅补写缺漏，再跑门禁；满 3 轮仍不通过则如实说明，不得谎称完成。

## 联网与扣点（启动一次性告知）

写报告前向拆解服务网关领取 3 包写作说明书；**每次成功开单（prepare）扣 5 点**。必须提供用户 API Key（账号里 `sk-` 开头的钥匙），环境变量 `QN_API_KEY`。报告通过本地门禁后回传报告文本。不上传原视频、帧、音频、路径。

**账号中心（复制 API Key）必须用可点击 Markdown 链接，禁止只写加粗/纯文本：**
[账号中心](http://159.75.168.183/webapps/quanneng-auth/index.html)

首次领取第 1 包之前告知用户，例如：

> 写报告需联网领取写作说明；每次开单扣 5 点。请先到 [账号中心](http://159.75.168.183/webapps/quanneng-auth/index.html) 复制 API Key（QN_API_KEY）。

若没有 `QN_API_KEY`：**不要跑 fetch_prompt**，停下让用户去 [账号中心](http://159.75.168.183/webapps/quanneng-auth/index.html) 复制 API Key。对用户说话时必须原样输出上面这条 Markdown 链接（`[账号中心](http://159.75.168.183/webapps/quanneng-auth/index.html)`），不要改成无链接的纯文本。缺视频或缺 Key 时可原样用：

> 下一步（两件事，缺一不可）：
> 1. 把视频文件发我（或给绝对路径）
> 2. 从 [账号中心](http://159.75.168.183/webapps/quanneng-auth/index.html) 复制 API Key 给我，我帮你配置后开单（会先确认再扣点）
>
> 准备好后随时发视频 + Key。

领取失败或余额不足（HTTP 402）必须停下，不得凭记忆写报告。回传失败不阻塞把报告交给用户。

## 匹配条件

满足任一即触发：上传视频附件（`.mp4` `.mov` `.mkv` `.webm` `.m4v` `.avi` 等）；消息含本地视频绝对路径；明确说拆解本地视频并提供了文件。

## 输入

- 必需：本地视频文件的**绝对路径**。
- 可选 CLI（传给 `scripts/analyze_local_video.py`）：`--out`、`--max-frames`（默认 20）、`--max-frame-edge`（默认 1280）、`--no-scene-aware`、`--scene-threshold`（默认 0.3）、`--max-size-mb`（默认 100）、`--max-duration-sec`（默认 900）、`--lang`、`--install-ffmpeg`、`--install-whisper`、`--no-transcribe`。
- 网关：`QN_SKILL_GATEWAY_URL`（默认 `http://159.75.168.183`）。
- **必需：用户 API Key** `QN_API_KEY`（从 [账号中心](http://159.75.168.183/webapps/quanneng-auth/index.html) 复制的 `sk-...`）。每次 `fetch_prompt.py prepare` 扣 5 点。

## 依赖

- 必需：当前模型须支持视觉，详见 [references/model-requirements.md](references/model-requirements.md)。
- 必需：`ffmpeg` + `ffprobe`（缺则退出码 8，询问是否 `--install-ffmpeg`，见 [references/deps.md](references/deps.md)）。
- 可选：本地 Whisper（未装则台词按画面推断，不中断）。

## 技能工作流

### 步骤1：确定输入并校验

确定本地视频绝对路径并校验存在。缺输入、文件不存在、或给的是视频号链接/URL 时：**不要跑脚本**，展示 [references/usage-notes.md](references/usage-notes.md) 后停下。

### 步骤2：本地素材提取

运行：
   ```
   python3 scripts/analyze_local_video.py <video_path> [--out PATH] [--max-frames 20]
                  [--lang zh] [--install-ffmpeg] [--install-whisper]
                  [--no-scene-aware] [--scene-threshold 0.3] [--max-frame-edge 1280]
   ```
脚本纯本地：探测 ffmpeg；抽元数据/封面/帧（默认场景感知，长边 ≤1280）；尝试 Whisper。stdout 输出 manifest。

解析 `=== WX_VIDEO_LOCAL_MANIFEST_START ===` 与 `=== WX_VIDEO_LOCAL_MANIFEST_END ===` 之间的 JSON。`frame_index` 是时间线地图（`idx/path/ts/source`）。记住 `WX_VIDEO_REPORT_FILE`，后续报告写到该路径。`transcript_available=false` 不阻塞。
### 步骤3：视觉预检

读取第一张帧。能描述画面 → 继续；`does not support images` / `Content filtered` / 无画面描述 → **立即停止、不要领 prompt、不要写报告**，原样传达：
   > 当前模型为纯文本模型，无法读取视频画面，无法完成拆解。请切换到**任何支持视觉的多模态模型**后重新运行。认能力不认名单：模型名带 vision/-V/-VL/4o/Gemini 通常可用；或直接发图问「这张图里有什么」。常见如 Kimi 视觉版、Qwen-VL、GLM-4V、豆包视觉版、Claude 4.x、GPT-4o、Gemini 2.x。素材已提取，切换后从视觉分析接着走。
   预检通过后**批量并读** `frame_index` 里需要细看的帧（同一条消息并行读取多张帧，帧多则分两三批），不要逐张串行。

### 步骤4：领取写作说明书并分节写报告

**领取第 1 包并只写前两节。** 先把素材摘要写成 JSON 文件（**去掉所有本地路径**），字段只用：`metadata`（时长/分辨率/编码等）、`cover_source`、`frames_mode`、`frames_count`、`frames_interval_sec`、`frame_index` 每项仅 `idx/ts/source`、`transcript`、`transcript_available`、`whisper_impl`。不要带 `path`/`cover`/`frames`/`report_file`/`report_dir`/`video_path`。
   ```
   python3 scripts/fetch_prompt.py prepare --payload <payload.json>
   ```
   脚本会带上 `QN_API_KEY`。缺 key 或 HTTP 401/402 → 停下，说明要到 [账号中心](http://159.75.168.183/webapps/quanneng-auth/index.html) 复制 API Key / 余额不足（对用户必须带这条可点击链接）。
   解析 `=== QN_PROMPT_PACK_START ===` … `=== QN_PROMPT_PACK_END ===`。`ok=false` 或非 0 退出 → 停下并说明需联网领取写作说明。`ok=true` 后**严格按返回的 `prompt` 写** `WX_VIDEO_REPORT_FILE`：本包只写「基本信息 + 结构拆解」，分节写入（先标题+基本信息，再追加结构拆解），禁止一次 Write 全文，禁止用本技能包内记忆补写作方法。记下 `invocation_id`、`next_url`、`result_callback_url`。
**领取第 2 包并追加中间两节。**
   ```
   python3 scripts/fetch_prompt.py next --invocation-id <id> --content <WX_VIDEO_REPORT_FILE>
   ```
   HTTP 400（缺标题）→ 按返回原因补写第 1 包章节后再 next。按新 `prompt` 只追加「内容归因分析 + 六维评分」，不要重写已写好的前两节。
**领取第 3 包并追加末两节。** 再次 `fetch_prompt.py next`（`--content` 为当前报告）。`next_url` 为空表示没有下一包。按 `prompt` 只追加「总体评估 + 标签」。
### 步骤5：本地结构硬门禁

运行：
   ```
   python3 scripts/verify_report_structure.py <WX_VIDEO_REPORT_FILE>
   ```
   退出码 0 / `ok=true` 才可说「本地结构校验通过（六节齐全）」。退出码 12 则补写后重跑。退出码 2 则核对 `WX_VIDEO_REPORT_FILE` 路径。满 3 轮仍失败不得跳到回传、不得谎称完成。
### 步骤6：回传报告（旁路）

门禁通过后运行：
    ```
    python3 scripts/submit_result.py <WX_VIDEO_REPORT_FILE> --invocation-id <id>
    ```
    失败退出码仍为 0，报告照常交给用户；至多一句「本次登记未完成，可稍后重试」。

## Whisper 转写（选装）

未装自动降级为画面推断，不影响出报告。默认不强引导安装；用户主动要台词分析时带 `--install-whisper`。耗时与选型见 [references/deps.md](references/deps.md)。

## 输出格式

脚本 stdout 形如：

```
WX_VIDEO_REPORT_FILE=/abs/path/to/wx-video-local-{ts}/report.md
=== WX_VIDEO_LOCAL_MANIFEST_START ===
{ "metadata": {...}, "cover": "...", "frame_index": [...], "transcript": "...", ... }
=== WX_VIDEO_LOCAL_MANIFEST_END ===
```

最终报告六节顺序固定：基本信息 → 结构拆解 → 内容归因分析 → 六维评分 → 总体评估 → 标签。章节名、表头以各包 prompt 与本地门禁为准，不要自行改名。

## 限制

- 只接受本地视频，不支持视频号分享链接。
- 单个文件 ≤ 100MB、≤ 15 分钟；超限退出码 11，把 stderr 原样转达。
- 写报告必须能连上网关；抽帧本身仍纯本地。
- 长视频抽帧稀疏（`--max-frames` 可调）；画面小字不清时用 `--max-frame-edge 1600` 或 `0`。

## 脚本位置

- `scripts/analyze_local_video.py` — 本地素材提取。
- `scripts/fetch_prompt.py` — 领取当前包写作说明书（失败则停）。
- `scripts/verify_report_structure.py` — 本地结构硬门禁。
- `scripts/submit_result.py` — 回传报告（旁路）。

使用说明

# 视频号爆款短视频拆解

把本地短视频按视频号带货/流量逻辑拆成结构分段、脚本类型、爆款归因和六维评分报告。素材全程本地提取，不传视频不传帧。

## 使用

```text
帮我拆解这个视频：/Users/me/Downloads/demo.mp4
```

## 工作原理

本地用 ffmpeg/Whisper 提取元数据、关键帧与字幕后，由多模态模型按服务端下发的写作说明
分三节完成结构化拆解报告（基本信息→结构拆解→归因分析→六维评分→总体评估→标签），
并通过本地结构门禁校验后交付。需配置 API Key，每次开单扣 5 点；单文件 ≤100MB、≤15 分钟。

如何安装此技能？

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