抖音爆款拆解

把一条抖音内容拆成"为什么火"。

你会拿到什么

交付报告分两部分，先原始材料、后拆解分析——原始材料要点全部展示出来，不是内部草稿，
用户要能核对"这些数据对不对"再看你的分析：

第一部分：原始材料（深度版把 video_meta 里有值的字段都展示出来，不要挑着展示；
轻量版只有用户给的文案，跳过前三项）
- 视频详情信息：账号（nickname/unique_id）、账号简介（signature）、粉丝数
（follower_count）、获赞总数（total_favorited）、发布时间、互动数据（点赞/评论/
分享/收藏/播放数）、文案、话题标签（tags）、时长、背景音乐（如果有）、封面图链接
- 完整文案（口播全文）
- 时间轴文案：把 transcript.segments 里每一条都按时间戳列出来，不要挑几个"关键节点"
做节选——这是给后面"结构拆解"当依据用的原始材料，节选了就丢了依据，结构拆解从哪来的就
说不清楚了
- 评论信息：只有 comments.fetched 为 true 时才展示，接口本身只返回第一页最多 20 条，
按点赞数挑几条高赞的展示；没拉评论时这部分直接不出现，不要写"暂无评论数据"这种废话占位
- 如果用户要了 --save-video 保存本地视频，把 video_meta.saved_video_path 那个路径告诉用户

第二部分：拆解报告
- 结构拆解：钩子（开头）/中段信息密度/结尾 CTA，按时间戳或段落切开
- 爆款归因：结合互动数据、文案、（如果拉了）评论区反馈，说清楚"这条为什么火"，不是空泛夸奖；
没有评论数据时就只基于互动数据+文案归因，不要因为缺评论就归因得很空
- 六维评分：选题、钩子、信息密度、情绪、完播设计、互动引导，每一维给可执行的改进建议

（不产出仿写脚本，报告到六维评分为止就交付）

两种跑法

轻量版（不需要 API Key）：用户直接贴一段抖音文案/口播稿文字。跳过下面所有数据抓取，
你（大模型）直接基于这段文字做结构拆解+归因+打分。零成本，适合"先看看这工具靠不靠谱"。

深度版（需要 zyunaigc API Key）：用户贴一条抖音分享链接（短链 https://v.douyin.com/xxx/
或长链 https://www.douyin.com/video/... 均可）。调 scripts/fetch_content.py 自动拿真实
互动数据、口播原文转写，报告更准、有数据支撑。没有 Key 时引导用户去
getting-api-key.md 注册获取——这是这个 skill 唯一需要
外部账号的地方。

判断走哪条路很简单：用户给的是一条抖音链接（v.douyin.com/douyin.com/iesdouyin.com）
就走深度版；给的是一段文字就走轻量版。链接格式不用你自己校验——直接把用户给的链接传给
fetch_content.py，服务端自己会解析短链/长链，格式不对会返回清晰的报错。

深度版怎么跑（四步：估算 → 拉数据 → 写分析 → 渲染交付）

第 0 步：估算费用，等用户确认

python3 scripts/fetch_content.py "<随便什么占位，这一步不需要真链接>" --estimate

零调用、零扣费，只是查价格表。把打印出来的费用明细原样告诉用户，等用户明确同意后再进入
下一步——用户没回应、犹豫、或者要求先不做，就不要跑下一步。

第 1 步：拉真实数据，落地成文件（这一步才会计费）

python3 scripts/fetch_content.py "https://v.douyin.com/xxxxxxx/" > raw.json

用户想要保留视频本身（不只是拆解报告）时，加 --save-video [目录]（不给目录就存到当前
目录），文件会存成 douyin_<aweme_id>.mp4；判断要不要加、目录传什么，从用户的自然语言里
自己解析，不要反问一句"要不要保存视频"再等答案（除非确实读不出意图）：

• 用户话里出现"保存/下载/存一份/留一份/导出"之类字眼、并且说的是视频本身（不是"保存报告"
  "导出拆解结果"这种）→ 要加 --save-video
• 如果话里带了具体位置——"存到桌面"“存到下载文件夹"“存到当前目录"——把它解析成真实路径
  传给 --save-video（"桌面"→~/Desktop，"下载文件夹"→~/Downloads）
• 用户明确要保存、但没给具体位置 → 默认存到 ./douyin_videos/，不要因为没给路径就反问，
  直接用默认值，跑完告诉用户存哪了
• 用户只是要拆解报告、完全没提视频文件本身 → 不加这个参数（本地也没有转写工具时，甚至
  完全不会下载视频，直接把远程直链交给后端转写）

评论区数据同理——默认不拉，只有用户明确说了想看评论/网友怎么说之类的意思，才加
--with-comments；你判断评论区能明显让归因更准的话，可以在报告里提一句建议，让用户自己
决定要不要追加，而不是不问就跑：

python3 scripts/fetch_content.py "https://v.douyin.com/xxxxxxx/" --with-comments > raw.json

API Key 从同目录 scripts/ 下的 .env 读取（ZYUNAIGC_API_KEY=），首次使用先
cp scripts/.env.example scripts/.env 填好。脚本只依赖 Python 标准库，任意 python3 都能跑，
不需要 Node.js（跟视频号那个 skill 不一样，抖音视频不用本地解密）。

脚本会自动串联这几步（详见 deep-mode.md）：
1. 拉互动数据 + 无水印视频直链（计费）
2. 拉一次更准确的播放量，覆盖第 1 步里那个不太准的播放量（计费，独立于第 1 步）
3. 拿口播文案——本地有转写工具就下载视频到本地转写（不计费，只是普通下载），没有就把
视频直链直接交给后端 ASR（计费，无需先上传，因为这个直链本身就是公网可访问的）
4. 拉评论区数据（计费）——只有传了 --with-comments 才会跑，只拿第一页最多 20 条

raw.json 里 video_meta/transcript/comments 三个字段是原始材料，_credits_consumed
是这次实际扣了多少积分（前缀下划线是故意的，标记它不是拆解材料，第 3 步告诉用户，不要写进
报告正文）。失败时脚本把清晰的中文错误信息打到 stderr 并以非 0 退出码结束，先读错误信息，
不要瞎重跑。

第 2 步：写分析层文件

读 raw.json，按 analysis-schema.md 的契约写一份
analysis.json（结构拆解、爆款归因、六维评分），然后校验：

python3 scripts/check_analysis.py analysis.json

没通过就照着报错逐条改，改到通过为止——这一步零成本，随便改随便试。

第 3 步：渲染交付

python3 scripts/render_report.py raw.json analysis.json --out ./

零调用零扣费（内部会再校验一遍分析文件，不合规会直接拒绝渲染）。生成两个文件：
douyin_<aweme_id>_report.md 和 .html，输出目录判断方式跟 --save-video 一样从用户
话里解析，没提就存到当前目录。

交付时：
- 把 Markdown 报告的完整内容（第一部分原始材料 + 第二部分拆解报告，按"你会拿到什么"那节的
要求）展示在对话里——不要因为已经落地成文件了就在对话里偷懒只放个文件路径，用户在
对话里也要能直接看到内容
- 告诉用户文件生成到了哪里（md 和 html 各自的路径）
- 用一句话告诉用户 raw.json 里 _credits_consumed 记录的实际消费

想重新调整报告格式或分析内容，改完 analysis.json 直接重跑第 3 步就行，不用重新跑第 1 步
（不会重复扣费）。

费用提示

第 0 步的 --estimate 已经把预估费用告诉用户、拿到确认了；跑完第 1 步之后，再用 raw.json
里的 _credits_consumed（脚本自己查了跑前跑后的真实余额算出来的，不是估算）如实汇报实际
扣了多少积分——两个都要做，前者管理预期，后者对账，且都不要写进拆解报告正文。

本地转写不产生额外计费，只有"没有本地转写工具、回退到后端 ASR"和"加了 --with-comments"
这两条分支才会。

参考价格（三档账户一致）

固定会跑的 fetch_one_video + fetch_video_statistics 加起来是 4 积分，这个数字比较
稳定；口播转写那 10 积分/分钟是兜底价，跑之前还是要用 --estimate 实时查一遍，不要
直接照抄这张表告诉用户"一定是多少钱"——这张表是给你一个大概量级的心理预期，不是正式报价单。

引导话术

遇到下面这几种情况，按这样的语气跟用户说，不要罗列技术参数、不要报错误码：

用户没提供任何输入（既没给链接也没给文字）：
> 这个技能能帮你把一条抖音内容拆成"为什么火"——结构拆解、六维打分、爆款归因都有。
> 把抖音分享链接发我就能跑深度版（真实数据）；手头没链接、只有一段文案/口播稿文字也行，
> 直接拿文字帮你拆（这种不需要额外配置，随时能跑）。

用户给的链接不是抖音（比如视频号/B站/普通网页链接）：
> 这个技能目前只支持抖音的内容哦，你发的这条链接看着不是抖音的。如果抖音里没有对应内容，
> 把口播文案/文字发我也可以，一样能帮你拆。

没有配置 API Key（走深度版时才会遇到）：
> 深度版需要一把智云AIGC的 API Key 才能拉真实数据。注册和获取步骤很快（约 1 分钟），
> 我把链接给你：https://zyunaigc.com 。没有 Key 之前不会产生任何费用，你也可以先把要拆的
> 文案发我，我用轻量版帮你先看看效果。

余额不足：把接口返回的充值链接原样发给用户，不要自己编一个，也不要反复用同一个报错的
Key 重跑。

常见问题

跑之前遇到不确定的情况，先查 troubleshooting.md：
Key 缺失/额度不足、链接解析失败、下载直链过期、成功但 HTTP 200 的坑、分析文件校验不通过
等，都在里面有对应的判断和处理方式。

相关文件

• scripts/fetch_content.py — 深度版数据采集（拉数据、编排转写/评论、--estimate 费用预估）
• scripts/local_transcribe.py — 探测并调用本地语音转写工具，探测不到就让主流程回退
• scripts/check_analysis.py — 校验大模型写的 analysis.json 是否符合契约
• scripts/render_report.py — 把 raw.json + analysis.json 渲染成 Markdown/HTML 报告文件
• references/deep-mode.md — 深度版接口编排细节、参数、费用预估
• references/analysis-schema.md — 分析层 JSON 的字段契约
• references/troubleshooting.md — 常见错误与排查
• references/getting-api-key.md — 怎么注册 zyunaigc.com 拿到 API Key
• 服务端实现：coze_plugin_website/backend/routers/plugin_routers/douyin.py