viral-chaser

name	viral-chaser
description	下载分析抖音/B站/小红书爆款视频，生成追爆报告。仅产出报告，脚本另外使用 video-product 技能根据 追爆报告.md 生成。
metadata	{"openclaw":{"emoji":"🎯","requires":{"bins":["node","ffmpeg"],"env":["VOLC_ASR_APP_ID"]}}}

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

本技能的语音转写（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 站 / 小红书视频链接，希望分析并制作同类视频
• 需要分析爆款视频的结构和公式

本技能仅产出追爆报告，不生成脚本，不制作视频。报告产出后，直接进入 video-product 技能，按追爆报告生成脚本并完成后续生产。

Supported platforms: 抖音（Douyin）、B 站（Bilibili）、小红书（XHS — 仅视频笔记）

Not supported: 微信视频号、TikTok

---

⚙️ 执行方式（强制）

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

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

---

Workflow

Step 1 — Create workspace

Before anything else, create the working directory for this video under output_videos/:

VIDEO_SLUG="<platform>-<contentId>"  # e.g. douyin-7389abc or bilibili-BV1xx
mkdir -p "output_videos/${VIDEO_SLUG}/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。

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:

{
  "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": ["output_videos/<slug>/references/frames/frame_00_0s.jpg", "..."],
  "localPaths": {
    "video": "output_videos/<slug>/references/video.mp4",
    "audio": "output_videos/<slug>/references/audio.wav",
    "tmpDir": "output_videos/<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: output_videos/<slug>/references/frames/frame_00_0s.jpg
Read: output_videos/<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 output_videos/<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.

---

衔接 video-product

追爆报告产出后，直接进入 video-product 技能流程，并应该明确提示后续工作流程：工作目录为 output_videos/<slug>/，直接按raw_article.md制作脚本.

---

Notes

• Workspace files are stored in output_videos/<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.