# Viral Chaser

> 用户转发/分享抖音、B站、小红书视频链接(v.douyin.com / b23.tv / xhslink.com / xhslink.cn),要求拆解分析时使用（俗称「追爆」）：下载视频、ASR 转写、结构化拆解，产出拆解分析报告。仅产出报告，视频生产需另外委托 content-producer。

- Skill: `teamwiseflow/viral-chaser` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add teamwiseflow/viral-chaser`
- Raw SKILL.md: https://api.skillmd.com/api/skills/teamwiseflow/viral-chaser/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: teamwiseflow (https://skillmd.com/u/teamwiseflow)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/teamwiseflow/viral-chaser

---


## 🔑 前置：开通火山语音模型（仅首次）

本技能的语音转写（ASR）使用**火山引擎豆包语音 · 录音文件极速版**（资源 ID `volc.bigasr.auc_turbo`）。即便账号已订购火山 Code Plan，语音模型仍需**单独开通**，否则调用会返回鉴权/权限错误。

**判断是否已开通**：直接跑 Step 3 分析器，若 ASR 报错含 `status=45xxxxx` 或权限相关码，说明未开通，按下面流程开通一次即可。

**开通流程**（未开通时，根据下面提示并引导用户在火山引擎控制台操作一次）：

1. 登录火山引擎控制台，左侧控制面板进入 **「开通管理」**
2. 选择 **「语音模型」** 选项卡
3. 找到 **「Doubao-录音文件识别2.0」** 这一项，点击它的 **「立即使用」**
4. 在跳转页面的「服务详情」里，选择 **「极速版」** 标签卡（对应实例名称 `Speech_Recognition_Seed_AUC2000000854311547266`，资源 ID `volc.bigasr.auc_turbo`），点击 **「试用」**（赠送 20 小时，可先用，后续再点开通付费）
5. 在该极速版页面可同时获得三项凭据：**APP ID**（数字）、**Access Token**、**Secret Key**。把 **APP ID + Access Token** 提供给小贝（旧控制台双头鉴权，对应 `VOLC_ASR_APP_ID` + `VOLC_ASR_ACCESS_KEY`）；**Secret Key 不需要给**（旧控制台账号用不上，填进 `X-Api-App-Key` 反而会报 `45000010 appid mismatch`）。由小贝写入实例环境变量。

**环境变量**（开通后由小贝配置，用户无需手动设置）：

| 变量 | 说明 |
|------|------|
| `VOLC_ASR_APP_ID` | 旧控制台**数字 APP ID**（如 `1216386473`），用于 `X-Api-App-Key`。旧控制台双头鉴权必需 |
| `VOLC_ASR_ACCESS_KEY` | 旧控制台 Access Token，用于 `X-Api-Access-Key`。与 `VOLC_ASR_APP_ID` 成对使用 |
| `VOLC_ASR_APP_KEY` | 新控制台 APP Key，用于 `X-Api-Key` 单头鉴权。仅新控制台账号需要；旧控制台账号不要把 Secret Key 填到这里（会报 `45000010 appid mismatch`） |
| `VOLC_ASR_RESOURCE_ID` | 资源 ID，默认 `volc.bigasr.auc_turbo`，一般无需改 |

> 鉴权二选一（脚本优先旧控制台双头）：同时给出 `VOLC_ASR_APP_ID`+`VOLC_ASR_ACCESS_KEY` → 旧控制台双头；否则用 `VOLC_ASR_APP_KEY` → 新控制台单头。**旧控制台 `X-Api-App-Key` 要的是数字 APP ID，不是 Secret Key。**

> **写入流程**：用户把 `VOLC_ASR_APP_ID` / `VOLC_ASR_ACCESS_KEY`（或新控制台的 `VOLC_ASR_APP_KEY`）交给小贝后，**小贝应 spawn 一个 `IT engineer` 作为 subagent** 去把这两个变量添加到实例环境变量中——IT engineer 掌握如何在本机环境变量 / 服务配置里安全添加此类密钥的规范。小贝本人不要直接写环境变量文件。

> **关于接口选型**：火山 ASR 分录音文件标准版 2.0（`volc.seedasr.auc`，单价最低，但只接受音频公网 URL，需自备 TOS 对象存储）、极速版（本技能采用，支持本地文件 base64 直传、一次返回）、闲时版（24h 内返回，不适合交互流程）、流式（实时上屏用）。viral-chaser 输入是本地 audio.wav，极速版免托管、原生返回时间戳，综合最合适。若后续为降本要切标准版 2.0，需额外引入 TOS 上传环节。

# Viral Chaser（追爆分析 — 报告产出）

Use this skill when:
- 用户提供抖音 / B 站 / 小红书视频链接，希望分析并制作同类视频
- 需要分析爆款视频的结构和公式

**本技能仅产出追爆报告**，不生成脚本，不制作视频。如需据此生成视频，需另行委托 `content-producer` （spawn subagent）执行。

**Supported platforms:** 抖音（Douyin）、B 站（Bilibili）、小红书（XHS — 仅视频笔记, 如果是图文的话则转向执行 `xhs-content-ops` 技能。）

**Not supported:** 微信视频号、TikTok

---

## ⚙️ 执行方式（强制）

本技能涉及多步骤生产流程，你应该 self-spawn 一个 subagent 来执行，原因：subagent 独立上下文，不会因对话历史积累而降低输出质量。

你只负责跟进subagent的执行，避免它们长时间卡在某个步骤，必要时可以提供提示或调整执行策略。

---

## Workflow

### Step 1 — Create workspace

Before anything else, create the working directory for this video under the source platform's 平台运营文件夹 `<platform>/ref/`（`<platform>` 取视频来源平台代号：douyin / bilibili / xhs）:

```bash
PLATFORM="douyin"  # 视频来源平台代号：douyin / bilibili / xhs
VIDEO_SLUG="<platform>-<contentId>"  # e.g. douyin-7389abc or bilibili-BV1xx
mkdir -p "${PLATFORM}/ref/${VIDEO_SLUG}/references"
```

若调用方 workflow 指定了产出落点（如把参考素材收进在制作品目录 `<platform>/outputs/<work>/references/`），则按指定位置建工作目录，内部结构不变。

All downloaded files, analysis results, and generated reports will be saved under this directory. The `references/` subdirectory holds the raw assets (video, audio, key frames) downloaded by the analyzer script.

### Step 2 — Run the analyzer（内置探活 + 下载 + 转写 + 关键帧）

一条命令闭环：先探活、再下载、再 ASR、再抽帧。**探活已合并进脚本**，无需单独跑 check-login。

```bash
viral-chaser <url> [--no-frames]
```

- `<url>`: Full or short-link URL of the video（支持短链，如 `xhslink.com/o/xxx`、`v.douyin.com/xxx`、`b23.tv/xxx`，脚本内部跟随重定向解析）
- `--no-frames`: Skip key frame extraction (faster, audio-only analysis)
- `OUTPUT_DIR`（环境变量）：落盘目录，必须指向 Step 1 建的 `references/` 子目录

> **⚠️ exec allowlist 注意**：`OUTPUT_DIR=... viral-chaser ...` 内联 env 前缀会触发 allowlist miss。通过 exec 工具调用时，把 `OUTPUT_DIR` 放到 exec 的 **`env` 字段**里传，不要写成内联前缀；同理避免 `mkdir ... ; echo` 这类分号复合命令。脚本本身已正确读取 `OUTPUT_DIR` 落盘，问题只在调用规范。

**内置探活**（`_shared/check-session.ts`）：douyin 抓取前先做两层探活（Tier1 cookie 关键字段 + Tier2 平台 pong，pong 带 TTL 缓存）；bilibili 公开视频免登录，跳过探活。**xhs 走无 cookie HTML 路线（见下），不依赖签名/cookie，跳过探活**——探活 user/me 通过也不代表 feed 签名路径被接受，HTML 路线根本不走签名，无需探活。

The script outputs a **JSON object to stdout**. Read it and proceed with analysis.

**Output JSON structure:**
```json
{
  "ok": true,
  "platform": "douyin",
  "metadata": {
    "contentId": "...",
    "title": "...",
    "desc": "...",
    "author": "...",
    "durationSeconds": 89,
    "coverUrl": "...",
    "stats": { "playCount": 0, "likeCount": 0, "commentCount": 0 }
  },
  "transcript": {
    "text": "全文转录...",
    "segments": [{ "start": 0.0, "end": 5.2, "text": "开场文案" }],
    "estimated": false
  },
  "frames": ["<platform>/ref/<slug>/references/frames/frame_00_0s.jpg", "..."],
  "localPaths": {
    "video": "<platform>/ref/<slug>/references/video.mp4",
    "audio": "<platform>/ref/<slug>/references/audio.wav",
    "tmpDir": "<platform>/ref/<slug>/references"
  }
}
```

- `transcript.estimated`: `false` 表示 `segments` 是火山 ASR 返回的**真实时间戳**（utterance 级，毫秒精度转秒）；`true` 仅在接口异常未返回 utterances 时出现，此时按句切分全文并按字数比例在音频时长上估算分段，时间区间为近似值。正常情况下始终为 `false`。

**Exit codes:**
- `0` = Success
- `1` = Error（URL invalid / download failed），或 `SIGN_UNAVAILABLE`（签名缺 OFB_KEY，重登救不了，交 IT engineer 配凭证）
- `2` = `SESSION_EXPIRED`（cookie 失效）— 走 login-manager 重登（`login-manager --platform <p>` 导出+验证），重试一次

### Step 3 — Read key frames (if available)

For each path in `frames`, use the `Read` tool to load the image and analyze it visually.

```
Read: <platform>/ref/<slug>/references/frames/frame_00_0s.jpg
Read: <platform>/ref/<slug>/references/frames/frame_01_3s.jpg
...
```

---

## Analysis Framework

After receiving the JSON output and reading the frames, generate a **追爆报告** in Markdown and save it to `<platform>/ref/<slug>/raw_article.md`.

### 1. 内容摘要
1–2 sentences: what core value does this video deliver to viewers?

### 2. 开头钩子分析（前 0–10 秒）
Based on `transcript.segments` where `start < 10`:
- **钩子类型**: 提问型 / 冲突型 / 反转型 / 数字型 / 悬念型 / 痛点型 / 利益型
- **具体文案**: quote the exact opening line(s)
- **效果评估**: why this hook works (or doesn't)

### 3. 内容结构拆解
Based on transcript segments, divide into logical sections:

| 段落 | 时间区间 | 功能 | 核心内容 |
|------|---------|------|---------|
| 开场 | 0–Xs | 钩子/引入 | ... |
| 主体一 | X–Ys | 价值/信息传递 | ... |
| 主体二 | Y–Zs | 深化/转折 | ... |
| 收尾 | Z–结束 | CTA/情绪收尾 | ... |

### 4. 爆款元素评估
Rate each element as **强 / 中 / 弱** with a one-line explanation:

| 元素 | 评级 | 说明 |
|------|:----:|------|
| 前 3 秒吸引力 | | |
| 痛点共鸣度 | | |
| 悬念设置 | | |
| 情绪触发 | | |
| 价值清晰度 | | |
| CTA 效果 | | |
| 视觉冲击（基于关键帧） | | |
| 节奏把控 | | |

### 5. 视觉风格分析（基于关键帧图片）
After reading the frame images:
- **色调风格**: 暖色系/冷色系/高饱和/低饱和/黑白
- **构图类型**: 人脸近景 / 产品展示 / 场景空镜 / 文字卡片 / 混合
- **字幕/文字覆盖**: 字体粗细、位置、是否有背景框、动画感
- **整体视觉标签**: 3–5 个关键词（如：「真实感」「强对比」「高信息密度」）

If `--no-frames` was used or frames is empty, note: "（跳过视觉分析，请重新运行不带 --no-frames 参数）"

### 6. 可借鉴点
3–5 concise, directly actionable techniques. One sentence each.

### 7. 目标受众
One sentence describing the primary audience persona.

---

## Notes

- **Workspace files** are stored in `<platform>/ref/<slug>/` — all downloaded assets and analysis reports are kept together. The `references/` subdirectory contains raw assets from the analyzer.
- **Bilibili DASH format**: if `mediaFormat` is `DASH`, the video and audio streams are separate. The downloaded `video.mp4` contains the video stream only; audio is in `audio.wav` after extraction. This is transparent to the analysis workflow.
- **XHS video notes only**: 小红书图文笔记（image-only）不含视频，viral-chaser 会报错并提示。只有视频笔记（type=video）才能下载和分析。
- **XHS 取数走 SSR HTML 路线（无 cookie 优先）**：`platforms/xhs.ts` 直接 GET `www.xiaohongshu.com/explore/{note_id}?xsec_token=...` 笔记详情页 HTML，解析 og:meta + `window.__INITIAL_STATE__` 拿标题/封面/视频地址/时长/互动计数（`_shared/xhs-html-note.ts`）。**不走 feed API**（`/api/sns/web/v1/feed` 需 xRap relay 签名，极易 406/500/滑块，且探活 user/me 通过不代表 feed 签名路径被接受，会出现「探活绿、feed 红」假绿）。输入必须是带 `xsec_token` 的分享链接（`xhslink.com/...` 或 `www.xiaohongshu.com/explore/...?xsec_token=...`），脚本从短链展开后的 URL 抽 token。无 cookie 抓不到（滑块/空页）时，若本机有 `xhs-browse` cookie 则用同指纹 UA + cookie 回退重试一次。
- **ASR segments**: 语音转写使用火山引擎豆包语音·录音文件极速版（`volc.bigasr.auc_turbo`），原生返回 utterance 级真实时间戳（`start_time`/`end_time`，毫秒），脚本转成秒后填入 `transcript.segments`，`estimated=false`。仅在接口异常未返回 utterances 时，才按句切分全文并按字数比例在音频时长上估算分段（`estimated=true`）作为兜底。开通/鉴权见文首「前置：开通火山语音模型」。
- **Exit code 2 — cookie expired:** Execute the login flow described in the login-manager skill（原则 3：douyin / xhs-browse 有头手动登录；bilibili 有头登录），导出 cookie + UA 后重试一次。Do not retry more than once.