shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 数据与分析需要 API Key

oneone-直播复盘

从微信视频号助手 API 拉取直播大屏数据，自动生成结构化 MD 复盘报告 + 交互式 HTML 可视化报告（双输出，模块顺序一致，先数据后结论）。支持全品类商家（服装/食品/美妆/家居/母婴/数码等），品类关键词和价格带自动适配。适用场景：用户提供视频号 AppID 和 AppSecret，需要某场或最近一场直播的全面数据复盘（观看、成交、商品、流量）。触发词：视频号直播复盘、直播数据报告、拉取视频号直播数据、直播间复盘。

person作者: user_48324e52hubcommunity
download下载资源包

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

概述

通过微信视频号助手 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. 数据处理注意事项

| 数据 | 原始单位 | 报告单位 | |------|----------|----------| | GMV、退款金额、客单价 | 分 | 元（÷100） | | 内容力指标（CTR、评论率等） | 万分比 | 报告显示原始万分比值 | | 转化率 | 小数（0.0486） | 百分比（4.86%，×100） | | 观看时长 | 秒 | 分秒（÷60） |

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

报告包含以下完整模块：

| # | 模块 | 内容 | |---|------|------| | 一 | 核心数据概览 | 观看/在线/曝光、内容力指标、互动数据 | | 二 | 流量来源分析 | 公域/私域/加热渠道明细、占比分布 | | 三 | 电商成交数据 | GMV/客单价/转化漏斗/客户结构/转化力 | | 四 | 商品销售 TOP 20 | 每个商品 GMV/销量/点击率/退款率 | | 五 | 选品复盘 | 动销率、品类结构、价格带分布、零成交诊断 | | 六 | 排品复盘 | 引流款/利润款/福利款/滞销款分类、排品策略评估 | | 七 | 投流分析 | 加热/广告流量效率对比、渠道ROI评估、投流建议 | | 八 | 总结与洞察 | 亮点/风险点/优化建议（选品/排品/投流/流量） |

报告会自动：

  • 选品复盘：自动提取品类关键词（支持内置服装/食品/美妆/家居/母婴/数码 + 自动检测 + 自定义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 知识库。