视频爆款文案拆解分析器

把任意一条本地视频完整拆解为一份可直接复用的「爆款文案分析报告」。报告固定包含五大模块：结构分段、脚本类型判断、爆款归因、六维评分、可借鉴策略。

何时使用

• 用户把视频文件拖入对话，或发来一个视频文件的本地路径（绝对/相对均可）。
• 用户明确或隐含希望分析视频的文案结构、脚本类型、爆款原因、可借鉴方法。
• 支持的扩展名：mp4、mov、m4v、mkv、avi、webm、flv、wmv（大小写均可）。

只要传入的是上述格式的合法视频路径，就应走完整个流程并产出完整报告，不因缺少字幕、缺少网络、时长长短而中途放弃——缺失环节要显式说明并降级处理（见「鲁棒性要点」）。

前置依赖

• ffmpeg / ffprobe：必须在 PATH 中（脚本会先自动定位；缺失时给出安装提示：winget install ffmpeg 或 apt install ffmpeg）。
• Python：用于运行 scripts/extract.py 与 scripts/transcribe.py。优先用托管 Python；没有则用系统 python3。
• 转写引擎：默认本地离线 faster-whisper（首次自动在 ~/.workbuddy/binaries/python/envs/default310 建 venv 并安装，需联网下载一次模型）。若本机无法安装/无网络，自动回退到云端 STT（见「转写回退」）。

执行流程

按顺序执行，每一步都检查产物是否存在，失败则按「鲁棒性要点」降级，不要直接中断。

第 1 步：定位视频与脚本

解析用户输入中的视频路径（拖入文件取其实路径；发路径则直接使用）。确定脚本目录：<skill>/scripts/（scripts 与本 SKILL.md 同级）。

第 2 步：提取（确定性，必做）

用 Python 运行提取脚本，得到 metadata.json、audio.wav、frames/*.jpg：

python <skill>/scripts/extract.py "<视频路径>" --out "<工作目录>" --frames 10

• <工作目录> 默认在视频同目录生成 <视频名>_analysis，也可显式指定（建议放到当前 workspace 下，便于 present_files 预览）。
• 脚本会自动校验格式白名单、抽取元数据、提取 16kHz 单声道音频、均匀抽 10 帧。
• 若视频无音轨：脚本会跳过音频与转写，仅做视觉/结构分析，并在 metadata 中标记 audio_extracted=false。

第 3 步：转写（获取脚本文本）

若 audio_extracted=true，转写音频：

python <skill>/scripts/transcribe.py "<工作目录>/audio.wav" --out "<工作目录>/transcript.json" --model small --lang zh

• --model：默认 small（中文够用、速度快）；追求精度用 medium；超短视频可用 base。
• --lang：已知语言可固定（如 zh / en）以提升准确率与速度；留空自动识别。
• 产出 transcript.json：{language, duration_seconds, segments:[{id,start,end,text}], text}。

转写回退：若本地转写失败（脚本退出码 4 并打印 FALLBACK_TO_CLOUD_STT），改用云端 STT 技能对同一个 audio.wav 转写——加载 speech-to-text（ElevenLabs，需 ELEVENLABS_API_KEY）或 azure-speech-to-text（需 AZURE_SPEECH_KEY+AZURE_SPEECH_REGION），拿到文本后手动整理为上面的 transcript.json schema（分段可按停顿/标点切，带起止秒）。若两者都不可用且无本地转写，则跳过文本分析，在报告顶部显式标注「未获取语音文本，以下结构/类型/归因基于画面与元数据推断」，仍尽力产出报告。

第 4 步：辅助视觉阅读（可选但推荐）

用 Read 工具查看 <工作目录>/frames/ 下的若干抽帧，辅助判断脚本类型（口播/剧情/Vlog/测评）与画面包装。不要一次性读全部，挑 4–6 张代表性帧即可。无音轨视频必须做这一步。

第 5 步：分析 + 生成报告

基于 transcript.json（文本+时间戳）、metadata.json（时长/分辨率等）、以及抽帧画面，按下方「分析方法论」完成五大模块推理，套用「报告输出格式」生成一份 Markdown 报告，保存为 <工作目录>/爆款文案分析报告.md。

第 6 步：交付

用 present_files 同时呈现：报告 Markdown 文件，以及（可选）frames/ 关键帧，方便用户对照。在正文中用中文给出报告摘要与最关键的 3 条结论。

分析方法论（五大模块怎么得出）

模块一 · 结构分段

以 transcript.segments 的时间戳为锚，通读内容后把整条视频按时序切成若干段落，至少覆盖四类角色：开头钩子 / 内容展开 / 高潮转折 / 结尾引导（中间可按需要加子类，如「铺垫」「案例」「复盘」）。每段给出：起止时间 [mm:ss-mm:ss]、时长、一句话作用（它在这条视频里承担什么功能）。钩子段要指出「用什么钩子手法」（疑问/反差/利益点/冲突）；结尾段要指出「引导动作」（关注/转发/评论/下单/进主页）。

模块二 · 脚本类型判断

在 {口播, 剧情, Vlog, 测评, 教程, 混剪, 访谈, 其他} 中选最贴切的一个（可并列次要类型）。判断依据必须落到可观测信号：是否单人面对镜头讲述（口播）、是否有角色与剧情线（剧情）、是否第一人称手持+生活画面（Vlog）、是否展示产品并对比/打分（测评）、是否步骤化教学（教程）、是否多素材快剪（混剪）。结合 transcript 的语气与 frames 的画面。

模块三 · 爆款归因

提炼 3–6 条该视频「为什么能火」的关键因素，每条配视频中的具体例证（引用某段台词/某个画面/某个节奏点）。常见维度：选题角度（稀缺/争议/刚需）、情绪共鸣（愤怒/治愈/爽感/焦虑）、节奏设计（前 3 秒留存、信息密度曲线）、文案钩子（开头与转折处的钩子句）、人设/信任背书、视觉包装（字幕/BGM/转场）、互动引导（评论区运营）。只写真正成立的，不硬凑。

模块四 · 六维评分

按下列六个维度逐项打 0–10 分，给出评分理由，再算总分（满分 60）与百分制换算，最后写一段简评（优点+最该补的短板）。评分要基于本视频证据，避免空泛。

> 完整评分细则与示例见 references/report-format.md（需要更严标准时再读取）。

模块五 · 可借鉴策略

给出 4–8 条可直接复用的创作方法与实操建议，必须落到动作层面（例如：「开头 3 秒用『反常识结论+留悬念』替代平铺直叙」「每 20–30 秒插入一个钩子句维持留存」「结尾用『评论区扣 1 领模板』提升互动」）。尽量结合本视频被验证有效的点，说明「为什么有效 + 怎么抄」。

报告输出格式

严格按以下 Markdown 骨架输出（中文），标题层级与表格不可省略：

# 视频爆款文案拆解报告

> 文件名：<file_name> ｜ 时长：<mm:ss> ｜ 分辨率：<WxH> ｜ 类型初判：<脚本类型>
> 分析依据：语音转写 + 元数据 + 抽帧画面（若未转写，此处注明）

## 一、结构分段
| 段落 | 时间段 | 时长 | 作用 |
|---|---|---|---|
| 开头钩子 | 00:00–00:08 | 8s | 用 XXX 手法留住观众 |
| 内容展开 | 00:08–01:20 | 72s | … |
| 高潮转折 | 01:20–02:10 | 50s | … |
| 结尾引导 | 02:10–02:35 | 25s | 引导关注/互动 |

## 二、脚本类型判断
- **判定：<类型>**（次要：<次要类型>）
- **判断依据：** <落到可观测信号，2–4 条>

## 三、爆款归因
1. **<因素名>**：<结合视频的具体例证与说明>
2. …
（3–6 条）

## 四、六维评分
| 维度 | 分数(0–10) | 说明 |
|---|---|---|
| 选题价值 | 8 | … |
| 开头钩子力 | 7 | … |
| 节奏把控 | 8 | … |
| 情绪共鸣 | 9 | … |
| 价值/信息密度 | 7 | … |
| 结尾转化力 | 6 | … |

- **总分：<X>/60（百分制 <Y>/100）**
- **简评：** <一段，点出最强项与最该补的短板>

## 五、可借鉴策略
1. **<策略名>**：<为什么有效 + 具体怎么抄>
2. …
（4–8 条）

鲁棒性要点

• 路径含空格/中文：所有命令用引号包裹路径；脚本内部用 subprocess 列表传参，不拼 shell 字符串。
• 格式不支持：extract.py 会校验白名单并明确报错；此时不要强行分析，先告知用户支持的格式。
• 无音轨 / 转写失败：按第 3 步的回退链路降级，报告顶部显式标注缺失项，其余模块仍尽力完成。
• 超长视频：transcribe 的 --model 可调小（base）以提速；抽帧数保持 10 张足够覆盖。
• ffmpeg 缺失：extract.py 会打印安装指引并退出；先帮用户装好 ffmpeg 再重跑。
• 不要臆造转写文本：没有可靠文本时，宁可在报告标注「基于画面推断」，也不要编造台词。

展示界面（界碑）

技能自带一个自包含单文件 UI「界碑」（showcase.html），用于清晰呈现技能信息（触发方式 / 支持格式 / 流程 / 产出）与边界范围（格式白名单 / 依赖 / 降级规则），并内置导入视频一键分析与报告导出功能（复制 / Markdown / HTML / PDF）。

• 路径：<skill>/showcase.html（与 SKILL.md 同级）。
• 离线打开（仅展示 + 导出）：浏览器直接打开即可，内置一份示例报告，也可用「载入你的报告」按钮载入任意生成的 爆款文案分析报告.md 后导出。
• 导入视频一键分析（本地服务）：先运行 scripts/serve_showcase.py，它会启动本地服务并给出地址；在该地址打开界碑页，把视频拖入「导入视频」区即可自动执行 提取 → 转写 → 成稿，并实时渲染报告与抽帧。页面会自动探测服务是否在线，未连接时降级为「复制提示语去对话分析」。
• 启动：python <skill>/scripts/serve_showcase.py [--port 8771] [--html 界碑路径]，浏览器打开终端打印的 http://127.0.0.1:<port>/。
• 重新生成页面：在技能根目录运行 python build_showcase.py（默认读取 assets/sample-report.md 重建 showcase.html；可用 --report <路径> 换示例报告、--out <路径> 指定输出位置）。
• 图标与资产：assets/icon.png（技能图标）、assets/sample-report.md（页面内置示例报告）。
• 完整使用手册：技能根目录的 使用手册.md（或 使用手册.html），覆盖三种使用方式、依赖、降级规则与命令。

自动成稿脚本（analyze.py）

除对话里的 LLM 深度分析外，技能还提供一个规则化自动成稿脚本，供本地服务在无 LLM 在场时产出可用的五模块报告初稿：

• 路径：<skill>/scripts/analyze.py
• 输入：extract + transcribe 的输出目录（metadata.json、transcript.json、frames/）。
• 输出：<目录>/爆款文案分析报告.md（五模块标准格式；无音轨/无转写时自动降级，报告顶部显式标注「基于画面与元数据推断」）。
• 用法：python analyze.py <analysis_dir> [--out report.md] [--model-note TEXT]
• 说明：这是启发式初稿（结构骨架 + 可复用清单），质量弱于对话中的 AI 深度版；若需更深文案洞察，把视频发到对话触发本技能即可。