视频号拆解诊断助手

视频号拆解诊断助手

版本：v0.6.0

基于曼格云 API 拆解微信视频号视频。支持两种输入：视频号分享链接，或本地视频文件。脚本 scripts/analyze_wx_video.py 负责全部 HTTP 调用、ISAAC64 本机解密、报告渲染与多格式导出（Markdown / Excel / HTML 看板），接口说明见 references/api.md，分析层契约见 references/analysis-schema.md。纯 Python 标准库实现，无第三方依赖。

核心原则：报告 = 数据层 + 分析层。 数据层（脚本）回答"视频里有什么"； 分析层（你，assistant）回答"为什么有效、怎么借鉴"。只交数据不交分析 = 交付不完整。

执行流程（两阶段）

按以下顺序执行，每一步都对应后续章节的细节：

阶段 0：确认配置与选项（不产生费用）

1. 取 API Key：读技能目录下 config.json 的 WM_API_KEY（回退环境变量）。缺失或不合法时，按「鉴权」流程引导用户到 创建 Key 并写入，拿到 Key 之前不要运行脚本。
2. 识别输入：判断用户提供的是视频号分享链接还是本地视频文件路径。无效或缺失时，按「引导话术」对应场景引导用户更正。
3. 让用户选视觉理解：每次拆解前用 AskUserQuestion 或直接询问，让用户确认两件事——
   • 是否启用视觉理解（画面拆解：镜头/运镜/转场/情绪/屏幕文字/时间线）。关闭则只出作品资料维度（文案/发布时间/时长/互动）。
   • 若启用，选档位：summary(¥0.12) / timeline(¥0.18) / decompose(¥0.24，默认推荐)。 用户没有明确表态时，默认 decompose，但必须让用户有机会改。
4. 预估费用并确认：运行 python3 scripts/analyze_wx_video.py "<输入>" --estimate [--no-visual] [--mode <档位>]（零 API 调用、零扣费），把输出的费用明细原样告知用户，并请用户确认。用户未确认不要进入阶段 1。

阶段 1：数据采集（脚本，产生扣费）

1. 运行脚本：python3 scripts/analyze_wx_video.py "<输入>" [--no-visual] [--mode <档位>]。脚本运行前会再次打印费用预估；完成后落地 wm_video_raw.json。
2. 告知用户数据采集完成与实际消费，然后立即进入阶段 2（不需要用户再确认，分析不产生费用）。

阶段 0 与阶段 2 都不产生任何扣费。同一输入 24 小时内重跑会命中本地缓存，命中步骤不再扣费。

默认不部署公开链接：拆解完成后只在本机生成 Markdown / Excel / HTML 看板并交付文件。除非用户明确要求"分享 / 部署 / 生成公开链接"，否则不要调用 cloudstudio 部署，也不要主动给出 app.workbuddy.link 分享链接。

阶段 2：深度分析 + 渲染（assistant + 脚本，零扣费）

1. 读取原始数据：读 wm_video_raw.json，通读标题/文案、互动 metrics、时间线 segments、画面事实、不确定项。

   若用户选择了 --no-visual，raw 中没有 segments / visualFacts，分析层只产出受众画像、互动数据反推、运营建议与总体评估，不得虚构画面细节；此时受影响的评分维度（信息密度、节奏控制、情绪曲线）应说明"数据不足，不予评分"并在理由中写明原因。

2. 产出分析：按 references/analysis-schema.md 的 schema 与红线，把深度分析写入输出目录的 wm_analysis.json。分析必须逐条锚定 raw 数据的真实时间点和数字。
3. 校验分析：python3 scripts/analyze_wx_video.py --check-analysis wm_analysis.json --render wm_video_raw.json。退出码 8 表示结构不合契约，按 stderr 错误清单逐条修正后重新校验，校验通过才进入渲染。这一步保证任何一次产出的报告结构完全一致（相同板块、相同表格列、固定六个评分维度）。
4. 重渲染：python3 scripts/analyze_wx_video.py --render wm_video_raw.json --analysis wm_analysis.json --out <目录>（零 API 调用、零扣费），生成含分析层的 Markdown / Excel / HTML。渲染前会再次自动校验分析文件。
5. 交付：按「输出交付」渲染 Markdown 报告、用 present_files 打开 HTML 看板、告知实际消费与文件路径。

阶段 2 失败（如分析文件写错、渲染报错）不会产生任何扣费，修正后直接重新 --render 即可。

任一步异常按「退出码处理」表对号入座，不要自行判定失败。

鉴权

API Key 取「技能目录」（SKILL.md 所在目录）下 config.json 里的 WM_API_KEY 字段，回退到环境变量 WM_API_KEY。脚本请求头使用 X-API-Key: 。config.json 形如：

{ "WM_API_KEY": "你的密钥" }

运行脚本前，先按下面的流程确认 key 就绪。任何时候都不要编造或猜测 key。

1. 检查是否已有 key。 读技能目录下的 config.json，看 WM_API_KEY 是否为非空字符串；若没有，再看环境变量 WM_API_KEY。两者任一有值即视为就绪，直接进入后续流程。

2. 缺失则引导用户获取。 若都没有，停下来告诉用户这个技能需要曼格云 API Key 才能调用，并给出官方地址与操作步骤，让用户把创建的 Key 发给你。在拿到 key 之前不要运行脚本（预估费用 --estimate 不需要 key，可以照常先跑）。

   引导话术：

   这个技能需要曼格云 API Key 才能调用数据接口，你还没有配置。

   获取步骤（约 1 分钟）：

   1. 打开 ，注册并登录
   2. 在控制台创建 API Key（形如 ach_live_...）
   3. 把 Key 发给我，我写入配置后就可以开始

   没有 Key 之前不会产生任何费用。你也可以先把要拆的视频链接发我，我先用 --estimate 帮你看这次大概花多少。

3. 记录用户发来的 key。 收到 key 后，把它写入技能目录下的 config.json 的 WM_API_KEY 字段（保留文件其它内容），然后再运行脚本。

4. 鉴权失败（退出码 3）时。 多半是 key 失效或余额为 0。提示用户重新前往 获取新 key 或充值，按第 3 步覆盖写入 config.json 后重试；不要反复用同一个失效 key 重跑。

计费与选项

单价（以接口响应 consumption 为准）：

• 视觉理解可以关闭（--no-visual）：只出作品资料维度，不下载视频、不做画面拆解，费用降到 ¥0.21。
• 本地视频没有作品元信息，关闭视觉理解将无内容可分析，脚本会直接拒绝。
• 24 小时内同一输入重跑会命中本地缓存，命中步骤不再扣费。

档位差异：

运行前用 --estimate 输出预估明细给用户确认，用户确认后才执行。

输入识别

单次只处理一条输入：

• 微信视频号分享链接：host 为 weixin.qq.com 或 channels.weixin.qq.com，路径以 /sph/ 开头。直接把链接传给脚本。
• 本地视频文件路径：文件存在，扩展名为 .mp4 .mov .m4v .avi .mkv .webm .flv .wmv，且大小不超过 128MB。

不要处理其它平台链接。若用户给出非微信视频号链接，按「引导话术 > 非微信平台链接」引导。若未提供输入、本地文件不存在、格式不支持、文件超过 128MB，按「引导话术」对应场景引导。若一次给出多条或同时给出链接和本地文件，先让用户指定一条。

引导话术

当用户触发本技能但未提供有效输入、或输入有误时，按以下场景引导。语气亲和自然，不要罗列技术参数。

未提供输入

技能已就绪 ✅ 这个技能能帮你把一条视频号视频拆成一份完整的拆解报告——包含作品文案、发布时间、时长分辨率、互动数据（点赞/转发/评论/收藏）及其结构反推、视觉深度拆解（镜头/运镜/转场/情绪/时间线/屏幕文字），以及为什么有效、怎么借鉴的分析结论。

说明：视频号接口不提供播放量，所以报告不含播放数据；视觉理解可选可关，开始前会先给你报一次费用。

随时可以开拆，把下面任意一种发给我即可：

1. 视频号分享链接 — 微信里打开要拆的视频，点右上角「···」→「复制链接」，把链接贴过来
2. 本地视频文件 — 已下载到电脑的视频，直接把文件拖进来或把路径发给我（支持 mp4 / mov / m4v / mkv / avi / webm / flv / wmv，128MB 以内）

拿到后我会先报一次预估费用，你确认并选好拆解深度后开始，通常 2–5 分钟出报告。

非微信平台链接

目前这个技能只支持微信视频号的视频哦，暂时没法直接处理 [抖音/B站/YouTube 等] 的链接。

不过你可以先把视频下载到电脑上，然后把本地文件路径发给我，我一样可以帮你拆解分析 😊

文件问题（不存在 / 格式不对 / 太大）

• 文件不存在：找不到这个文件，麻烦检查一下路径是否正确？可以直接把文件拖到对话框里试试。
• 格式不支持：这个文件格式暂时处理不了，支持的视频格式有：mp4、mov、m4v、avi、mkv、webm、flv、wmv。
• 文件过大：这个视频有点大（超过 128MB 了），可以先用剪辑工具压缩一下再发给我。

缺少 API Key

拆解视频需要调用曼格云付费 API，首次使用得配置一下 API Key 🔑

👉 打开这个链接注册/登录并创建 API Key：https://api.we-media.cn

拿到 Key 后直接粘贴发给我（一串字符即可），我会帮你存好，之后拆解视频就不用再管它了。这个服务按次计费，余额不足时我会提醒你充值。

扣费与确认

本技能每次拆解会消耗费用，整条链路对用户的扣费感知由你（assistant）来贯穿：

• 执行前确认：识别成有效输入、API Key 就绪后，运行脚本前向用户说明并请其确认：

  本次拆解预计消费约 ¥0.45（作品资料 ¥0.21 + 视觉理解 ¥0.24），实际以接口响应 consumption 为准。是否继续？

  等用户明确确认后再运行脚本；用户未确认、未回应或要求改主意时，不要运行脚本。

• 执行成功后回告实际消费：见「输出交付」，把脚本透出的各步骤 consumption 和总消费告诉用户，并给出查看报告的方式。

• 执行失败后告知费用情况：见「退出码处理」，按退出码区分是否已扣费。

余额不足时，引导用户前往 充值。

运行方式

在 skill 目录下运行：

# 先看这次要花多少（零扣费，无需 key）——拆解前必做
python3 scripts/analyze_wx_video.py "<分享链接>" --estimate
python3 scripts/analyze_wx_video.py "<分享链接>" --estimate --no-visual        # 关闭视觉理解的价格
python3 scripts/analyze_wx_video.py "<分享链接>" --estimate --mode timeline     # 换档位的价格

# 分享链接拆解（默认 decompose 档，同时生成 Markdown + Excel + HTML 看板）
python3 scripts/analyze_wx_video.py "<分享链接>"

# 只要作品资料维度（文案/发布时间/时长/互动），不做画面拆解
python3 scripts/analyze_wx_video.py "<分享链接>" --no-visual

# 指定视觉理解档位
python3 scripts/analyze_wx_video.py "<分享链接>" --mode summary
python3 scripts/analyze_wx_video.py "<分享链接>" --mode timeline

# 本地视频拆解
python3 scripts/analyze_wx_video.py "<本地视频路径>"

# 仅查询余额（免费，不拆解）
python3 scripts/analyze_wx_video.py --balance

# 阶段2：注入 AI 分析层后零扣费重渲染（核心用法）
python3 scripts/analyze_wx_video.py --render wm_video_raw.json --analysis wm_analysis.json --out <目录>

# 指定输出格式
python3 scripts/analyze_wx_video.py "<分享链接>" --format markdown   # 仅 Markdown
python3 scripts/analyze_wx_video.py "<分享链接>" --format excel       # 仅 Excel
python3 scripts/analyze_wx_video.py "<分享链接>" --format html         # 仅 HTML 看板
python3 scripts/analyze_wx_video.py "<分享链接>" --format all          # 三种全出（默认）

可选参数：

• --mode summary|timeline|decompose：视觉理解档位，默认 decompose（最详细）。单价 ¥0.12 / ¥0.18 / ¥0.24。
• --no-visual：关闭视觉理解，只出作品资料维度（不下载视频、不做画面拆解）。
• --estimate：只输出费用预估，不调用接口、不扣费，无需 API Key。
• --format markdown|excel|html|all：输出格式，默认 all（同时生成 Markdown 报告、Excel 表格、HTML 看板）。
• --out PATH：报告输出路径，目录或文件均可。
• --render RAW_JSON：零扣费重渲染模式，读取 wm_video_raw.json 重新生成报告，不调用任何 API。
• --analysis ANALYSIS_JSON：配合 --render 注入 AI 分析层，schema 见 references/analysis-schema.md。注入前会自动做 schema 强校验，不合契约直接退出码 8 拒绝渲染。
• --check-analysis ANALYSIS_JSON：仅校验分析文件是否符合 schema 契约（可配 --render RAW_JSON 做交叉校验，如片段序号不越界），不生成报告、零扣费。
• --balance：仅查询账户余额，不执行拆解。

环境变量：WM_VIDEO_CACHE=0 可关闭本地响应缓存（默认开启）。

省钱与稳定性机制

脚本内置两个保护机制，避免重试时白烧钱：

1. 付费接口响应缓存（默认开启，24 小时有效）：作品资料（¥0.21）和 视频视觉理解（¥0.24）的成功响应会写入技能目录 .cache/。作品资料按 path + 请求体 哈希索引；视觉理解因请求体里的 fileUrl 每次上传都重新生成，额外以视频内容 sha256 作为缓存 key 的一部分——同一视频（内容不变）重跑即可命中。命中后不再调用接口、不再扣费，日志打印 [缓存命中] xxx（本次不再扣费），费用明细中该步骤显示为 （缓存） 且消费为 0。

   失败响应不写入缓存，保证修正问题后能真正重跑而不是一直读到旧结果。

2. 上游瞬时故障自动重试：视觉理解上游（阶跃）偶发返回 UPSTREAM_UNAVAILABLE / INVALID_UPSTREAM_RESPONSE 等错误。这类错误平台会退回费用，因此脚本自动退避重试（最多 4 次尝试，等待 8/20/45 秒），日志明确提示「费用已退回，不会重复扣费」。鉴权失败、参数错误等业务性错误不重试。

   因此：报告渲染出错、或上游抖动导致失败后，直接重跑同一条命令即可，已完成的付费步骤会命中缓存，通常只补最后失败的那一步。

接口字段的实际命名（重要）

接口文档描述的字段名与线上实际返回不一致，脚本已同时兼容两套命名。若后续改动渲染逻辑，务必用 _pick() 按别名取值，不要只认文档名：

时长单位坑：media[0].videoPlayLen 单位是秒；media[0].spec[0].durationMs 单位是毫秒。统一用 _media_duration_seconds() 归一化，不要直接把 videoPlayLen 当毫秒除 1000。

播放量：视频号 API 不返回 viewCount，报告（HTML/Markdown/Excel）均不展示「播放」卡片或互动率——前者强行展示「0 / 未获取」会误导用户，后者无分母无法计算。互动维度只保留点赞/转发/评论/收藏 + 互动总量。

本机解密

视频号分享链接的 playbackUrl 是 Finder 加密地址，前 128 KiB 需用 decodeKey 做 ISAAC64 流按字节 XOR 解密。脚本内置纯 Python 标准库 ISAAC64 实现（不依赖原生扩展），在本机完成解密后校验 MP4 ftyp 标识，再上传。解密仅处理前 128 KiB，后续字节保持原样。视觉调用结束后删除本机临时目录。

回归向量：decodeKey=1233185028、全零输入时密钥流前 64 字节为 59cd728cbf3e0f6c525f36b3079a51cd606cd7f9af2b30dccf6decbccc7563fa14ffc4254d415520fc6bf0c68bb14b086b34d0cab535aa463c05a027ba8e7770。

输出交付

成功时 stdout 形如：

WM_VIDEO_TOTAL_CONSUMPTION=<本次总消费，元>
WM_VIDEO_FILE_RAW=<原始数据 JSON 绝对路径>
WM_VIDEO_FILE_MARKDOWN=
WM_VIDEO_FILE_XLSX=
WM_VIDEO_FILE_HTML=
=== WM_VIDEO_REPORT_START ===
<完整 Markdown 报告>
=== WM_VIDEO_REPORT_END ===

WM_VIDEO_FILE_* 行仅在对应格式实际生成时出现。--format markdown 只输出 Markdown 行，--format excel 只输出 XLSX 行，依此类推。WM_VIDEO_FILE_RAW 始终输出（除非渲染失败）——它是阶段 2 分析的唯一输入。

Markdown 报告

报告包含数据层 + 分析层两大板块群：

数据层（脚本自动生成）：

1. 基本信息：标题/文案、发布账号、发布时间、封面、时长、分辨率、文件大小。
2. 互动数据：点赞、转发、评论、收藏（视频号 API 不返回播放量）。
3. 内容摘要：基于视频画面证据的摘要。
4. 结构拆解：时间线 + 每片段的镜头/运镜/转场/情绪线索/置信度，及分析层注解。
5. 画面事实与证据：可核验的画面事实，带时间范围和置信度。
6. 不确定项：无法从视频确认的内容，防止猜测包装成事实。
7. 费用明细：各步骤消费与余额。

分析层（--render --analysis 注入，schema 见 references/analysis-schema.md）：

1. 受众画像：年龄段/性别比例/兴趣标签/消费能力（推断）。
2. 结构解读：脚本类型、判断依据（引用时间点）、每片段"为什么有效"、结构总结。
3. 爆款归因：2-4 条归因表（层/因素/详细描述/贡献度百分比/数据佐证）。
4. 爆款公式 + 可复刻性：一句话公式、可复刻性评分/策略/不适用场景。
5. 六维评分：Hook强度/信息密度/节奏控制/产品展示/情绪曲线/转化引导，各带节奏证据/评分理由/改进建议。
6. 运营建议：可执行动作列表。
7. 总体评估：总分/可复制性/亮点问题/首要改进。
8. 标签：内容标签。

未注入分析层时，报告自动降级为纯数据版（含"可借鉴策略要点（基础版）"浅层要点），不报错。

Excel 报告（.xlsx）

纯标准库 zipfile+XML 生成，数据层 6 个 sheet + 分析层 5 个 sheet（注入时）：

HTML 结果看板

自包含单文件（样式内联自 scripts/report_style.css，不依赖外部 CDN，可直接打印为 PDF）。 采用专业报告版式：单一强调色、章节自动编号、无 emoji 与装饰性图标。

• 封面区：报告标题、发布账号、发布时间、时长/分辨率/文件大小、封面图。
• 执行摘要：关键指标（点赞/转发/评论/收藏/时长/综合评分）+ 结论前置的三条判断。
• 数据性质图例：明确区分 实测 / 模型输出 / 推断 三类信息。
• 正文章节（自动编号，标题带来源标签）：受众画像、互动数据、互动数据反推、内容摘要、结构拆解、爆款归因、爆款公式、六维评分、运营建议、标签、画面事实、不确定项、费用明细。
• 方法论与数据说明：数据来源、数据性质分级、反推口径与阈值、口径限制、使用声明。
• 响应式 + 打印样式：移动端自适应，打印时隐藏装饰、按章节分页。

交付时按顺序做三件事：

1. 渲染报告：截取两个分隔符之间的 Markdown 渲染给用户。
2. 展示 HTML 看板：用 present_files 打开 HTML 看板文件，让用户直接看到可视化结果。
3. 告知实际消费与文件：把 WM_VIDEO_TOTAL_CONSUMPTION 和各步骤明细告诉用户，同时告知 Markdown / Excel / HTML 文件的保存路径。

退出码处理

一句话：任务已发起但未成功产出报告（退出码 5、6、7、9、124），作品资料等已调用步骤的费用不退回，告知用户实际已扣费金额并询问是否重试；任务未发起到位的（2、3）不涉及扣费。