微信视频号直播复盘报告生成

概述

通过微信视频号助手 API 拉取直播大屏全量数据，自动解析并同时生成两种格式的复盘报告：

1. MD 报告：结构化 Markdown，适合 IMA 知识库沉淀、飞书文档导入
2. HTML 可视化报告：含 Chart.js 交互图表，适合浏览器预览、团队分享

MD 与 HTML 模块顺序完全一致（先数据、后结论）：
- 核心数据概览（观看、在线、内容力对比）
- 流量来源分析（公域/私域/加热/广告）
- 电商成交数据（GMV、转化漏斗、客户结构）
- 商品销售 TOP 20
- 选品复盘（动销率、品类结构、价格带、零成交诊断）
- 排品复盘（引流款/利润款/福利款/滞销款分类）
- 投流分析（加热/广告流量效率对比）
- 总结与洞察（亮点/风险/优化建议，收束全场结论）

使用流程

1. 获取用户凭证

向用户确认以下信息：

• AppID — 视频号助手 API 的 AppID（从视频号助手后台获取）
• AppSecret — 对应的 AppSecret（可从视频号助手后台获取）
• 账号名称（可选）— 用于报告标题，如未提供则使用 API 返回的昵称
• 目标直播 — 默认为"最近一场"电商直播；用户可指定特定 export_id 或日期

> 凭证也可通过环境变量 WX_APPID / WX_APPSECRET 注入（推荐，避免明文出现在对话中）。
> 本技能包不内置任何账号凭证，详见 references/credentials.md。

安全提醒：如果用户在对话中明文发送了 AppSecret，必须提醒用户去后台重置密钥。

2. 获取 access_token

GET https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET

Token 有效期 7200 秒，建议在每次拉取数据前刷新。

3. 确认 API 权限

先调用账号信息接口确认 AppID 有效：

POST https://api.weixin.qq.com/channels/finderlive/get_finder_attr_by_appid?access_token=TOKEN

如果返回 nickname 和 fans_count，说明凭证有效。将 nickname 和 fans_count 用于报告头部信息。

4. 获取直播列表

使用 getlivelist 接口（注意：必须传 ds 参数，格式为 YYYYMMDD 整数）：

POST https://api.weixin.qq.com/channels/livedashboard/getlivelist?access_token=TOKEN
Body: {"ds": 20260722}

• 从当天开始查询，如无数据则向前逐天尝试（最多回溯 7-30 天）
• 只返回电商直播间，非电商直播不在列表中
• getfinderliverecordlist 接口只返回"当前在播"记录，不适用于历史数据查询
• 从返回的 live_items 中取 create_time 最大的作为"最近一场"

常见问题排查：
- 返回 errcode: 48001：API 权限未启用，需在视频号助手后台打开
- 返回 errcode: 0 + 空列表：该日期无电商直播，换日期
- 返回 errcode: 1：可能是 ds 参数格式不对（需传入整数无引号）

5. 获取直播大屏数据

POST https://api.weixin.qq.com/channels/livedashboard/getlivedata?access_token=TOKEN
Body: {"export_id": "export/XXXXXX..."}

返回的顶层 JSON 中，live_dashboard_data、live_comparison_index、live_ec_data_summary、live_ec_conversion_metric、single_live_ec_spu_data_page_v2 等字段是嵌套 JSON 字符串，需各自解析：

import json
raw = json.loads(api_response)
dashboard = json.loads(raw["live_dashboard_data"])
ec_summary = json.loads(raw["live_ec_data_summary"])
comparison = json.loads(raw["live_comparison_index"])
spu_data = json.loads(raw["single_live_ec_spu_data_page_v2"])

6. 拉取数据脚本（推荐）

直接用捆绑脚本拉取并落盘原始 JSON，无需手工拼接口：

# 拉目标日期(默认昨天)最新一场；无数据自动向前回溯
python scripts/fetch_live_data.py raw_live_data.json [YYYYMMDD]

# 拉最近 N 场，每场独立 JSON（同日多场按 _2/_3 后缀区分）
python scripts/fetch_live_data_multi.py 3 ./

注意事项：
- 同日可能有多场：getlivelist 返回当天全部电商场次，脚本已按 create_time 排序取最新（勿直接取首条，会漏掉同日较早场次）
- 异常场识别：观看人数 ≤1 且上架商品数 =0 的场次疑似测试/无效场，脚本会标记 _abnormal: true 并打印警告；此类场生成的报告为空壳（GMV 0），需向用户确认是否保留（项目惯例命名为"*_异常场"）
- 输出 JSON 含元数据字段 _live_date / _export_id / _abnormal，生成报告时可直接读取

7. 生成 MD 报告

调用捆绑脚本 scripts/generate_report.py 生成 MD 报告：

python scripts/generate_report.py raw_live_data.json ./ "" "YYYY年MM月DD日" "export/XXXXXX..." "账号名称" "粉丝数" "品类"

默认输出文件名格式为 直播复盘报告_{日期}.md。

8. 生成 HTML 可视化报告

必须执行，调用捆绑脚本 scripts/html_report.py 生成 HTML 报告：

# 用法同 generate_report.py，参数完全一致
python scripts/html_report.py raw_live_data.json ./ "" "YYYY年MM月DD日" "export/XXXXXX..." "账号名称" "粉丝数" "品类"

默认输出文件名格式为 直播复盘报告_{日期}.html。

HTML 报告包含 12 张 Chart.js 交互图表 + 完整数据表格，模块顺序与 MD 报告完全一致。
MD 和 HTML 各自独立从 raw_live_data.json 读取数据，无需中间产物。

> 输出文件参数说明：第 3 个参数（output_file）可留空（自动按生成日命名）或传文件名；相对文件名会自动拼接到 output_dir，也可直接传绝对路径。

9. IMA 知识库上传

python scripts/upload_to_ima.py <report_path> <knowledge_base_id>

将 MD 报告上传到指定的 IMA 知识库（knowledge_base_id 由用户提供）。

11. 数据处理注意事项

10. 报告模块（共8个模块，MD/HTML 顺序一致）

报告包含以下完整模块：

报告会自动：
- 选品复盘：自动提取品类关键词（支持内置服装/食品/美妆/家居/母婴/数码 + 自动检测 + 自定义JSON），分析动销率和GMV集中度，诊断零成交商品原因
- 排品复盘：基于相对价格分位 + GMV占比 + 点击率中位数自动划分引流款/利润款/滞销款/福利款，阈值随数据自适应
- 投流分析：评估加热和广告渠道效率，对比公域渠道，给出投放建议
- 价格带分析：基于商品实际价格分布的 P25/P50/P75 自动分档，适配任意价格区间

捆绑资源

• references/api_reference.md：完整的 API 参数与返回结构文档，包含枚举值对照表。
• references/credentials.md：默认 API 凭证（AppID/AppSecret），生成报告时优先使用。
• scripts/fetch_live_data.py：拉取指定日（默认昨天）最新一场数据，输出含 _abnormal 异常场标记。
• scripts/fetch_live_data_multi.py：回溯 30 天拉取最近 N 场数据，每场独立 JSON。
• scripts/generate_report.py：从 raw_live_data.json 解析并生成 MD 报告的核心脚本。
• scripts/html_report.py：从 raw_live_data.json 解析并生成 HTML 可视化报告（含 Chart.js 图表）。
• scripts/upload_to_ima.py：将 MD 报告上传到 IMA 知识库。