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

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

## 概述

通过微信视频号助手 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 字符串**，需各自解析：

```python
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，无需手工拼接口：

```bash
# 拉目标日期(默认昨天)最新一场；无数据自动向前回溯
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 报告：

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

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

### 8. 生成 HTML 可视化报告

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

```bash
# 用法同 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 知识库上传

```bash
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 知识库。