Item: 推送消息数据助手（友盟U-Push）
Rating: 4.2
Author: Implexa
友盟推送后台管理助手（只读查询）。帮助获取应用列表、查询推送数据等。**使用前需用户提供 Cookie**：请访问 https://upush.umeng.com 登录后，在浏览器开发者工具的 Network 标签中复制 Cookie 并提供给系统。Use when working with Umeng push...
SKILL.md

---
name: umeng-push-helper
description: 友盟推送后台管理助手（只读查询）。帮助获取应用列表、查询推送数据等。**使用前需用户提供 Cookie**：请访问 https://upush.umeng.com 登录后，在浏览器开发者工具的 Network 标签中复制 Cookie 并提供给系统。Use when working with Umeng push notifications or when user mentions 友盟推送.
---

# 友盟推送助手 (Umeng Push Helper)

## 功能概述

本技能提供以下核心功能：
1. **获取应用列表** - 获取账号下所有应用的列表
2. **查询应用数据** - 查询指定应用的消息概览、诊断摘要和诊断报告（三个接口）
3. **获取推送周报** - 获取指定应用的推送数据周报
4. **推送轨迹查询** - 根据 appkey、device_token 和 msg_id 分三步查询推送的完整轨迹
5. **开关统计查询** - 查询应用的开关趋势数据，包括新增关闭设备数、新增打开设备数、DAU、关闭设备数、日关闭率
6. **关闭归因分析** - 分析用户关闭推送的原因，包括用户偏好、推送频次、通知内容、设备维度四个维度的深度分析
7. **概况统计查询** - 查询应用的概况统计数据，包括应用概况、推送转换数据、厂商通道额度（仅安卓），支持 HTML 可视化报告
8. **获取消息列表** - 查询指定应用的消息列表，支持分页和日期范围筛选，显示推送的完整统计数据

## ⚠️ 安全限制 - 禁止调用的接口

**重要**：出于安全考虑，本技能**严格禁止**调用以下敏感接口：

| 序号 | 禁止调用的接口 | 用途 | 风险等级 |
|------|--------------|------|---------|
| 1 | `https://upush.umeng.com/hsf/push/sendMsg` | 发送推送消息 | 🔴 高危 |
| 2 | `https://upush.umeng.com/hsf/setting/updateApp` | 修改应用配置 | 🔴 高危 |
| 3 | `https://upush.umeng.com/hsf/setting/updateChannelInfo` | 修改渠道信息 | 🔴 高危 |
| 4 | `https://upush.umeng.com/hsf/setting/saveReceipt` | 保存回执配置 | 🟡 中危 |

**违反后果**：
- ❌ 如果用户请求调用上述接口，必须明确拒绝
- ❌ 不得提供任何绕过限制的方法或建议
- ✅ 应告知用户这些操作需要通过友盟官方后台手动执行

**允许调用的接口**（只读操作）：

**基础信息查询**：
- ✅ `https://upush.umeng.com/hsf/home/listAll` - 获取应用列表
- ✅ `https://upush.umeng.com/hsf/home/allAppAndGroup` - 获取所有应用和分组
- ✅ `https://upush.umeng.com/hsf/home/isFlowPackageUser` - 检查是否为流量包用户
- ✅ `https://upush.umeng.com/hsf/home/getUserProInfo` - 获取用户专业版信息
- ✅ `https://upush.umeng.com/hsf/setting/appInfo` - 获取应用详细信息
- ✅ `https://upush.umeng.com/hsf/setting/getChannelInfo` - 获取渠道配置信息
- ✅ `https://upush.umeng.com/hsf/setting/showLbs` - 检查 LBS 设置
- ✅ `https://upush.umeng.com/hsf/setting/getBenefits` - 获取权益信息

**概览页面查询**：
- ✅ `https://upush.umeng.com/hsf/overview/getAppCnt` - 获取应用数量统计
- ✅ `https://upush.umeng.com/hsf/overview/getTransformData` - 获取转化数据
- ✅ `https://upush.umeng.com/hsf/overview/queryThirdQuota` - 查询第三方指标
- ✅ `https://upush.umeng.com/hsf/overview/getAppTrend` - 获取应用趋势数据
- ✅ `https://upush.umeng.com/hsf/overview/getUserCnt` - 获取用户数量统计

**推送相关查询**：
- ✅ `https://upush.umeng.com/hsf/push/messageOverview` - 消息概览
- ✅ `https://upush.umeng.com/hsf/push/diagnosisSummery` - 诊断摘要
- ✅ `https://upush.umeng.com/hsf/push/diagnosisReport` - 诊断报告
- ✅ `https://upush.umeng.com/hsf/push/getToolLifeCycle` - 查询消息生命周期
- ✅ `https://upush.umeng.com/hsf/push/getToolRequestContent` - 查询推送请求内容
- ✅ `https://upush.umeng.com/hsf/push/getMsgList` - 获取推送消息列表（支持分页和筛选）
- ✅ `https://upush.umeng.com/hsf/push/getMsgInfo` - 查询单条消息基本信息
- ✅ `https://upush.umeng.com/hsf/push/getMsgData` - 查询单条消息统计数据
- ✅ `https://upush.umeng.com/hsf/push/getPushExpStatData` - 查询推送失败分析数据
- ✅ `https://upush.umeng.com/hsf/push/getMsgStatChannelData` - 查询分通道送达统计
- ✅ `https://upush.umeng.com/hsf/tool/canExportMsg` - 检查是否可以导出消息

**设备相关查询**：
- ✅ `https://upush.umeng.com/hsf/setting/getDeviceInfo` - 查询设备信息
- ✅ `https://upush.umeng.com/hsf/setting/deviceMessage` - 查询设备消息列表
- ✅ `https://upush.umeng.com/hsf/setting/getChannelInfo` - 查询厂商通道集成状态

**数据统计查询**：
- ✅ `https://upush.umeng.com/hsf/dataStatistic/getCloseTrend` - 获取开关趋势数据

**概况统计查询**：
- ✅ `https://upush.umeng.com/hsf/overview/getAppCnt` - 获取应用数量统计
- ✅ `https://upush.umeng.com/hsf/overview/getTransformData` - 获取转化数据
- ✅ `https://upush.umeng.com/hsf/overview/queryThirdQuota` - 查询第三方指标（厂商额度）

**关闭归因分析**：
- ✅ `https://upush.umeng.com/hsf/dataStatistic/userPreferenceAnalyzer` - 用户偏好分析
- ✅ `https://upush.umeng.com/hsf/dataStatistic/pushFrequencyAnalyzer` - 推送频次分析
- ✅ `https://upush.umeng.com/hsf/dataStatistic/pushMessageAnalyzer` - 通知内容分析
- ✅ `https://upush.umeng.com/hsf/dataStatistic/deviceDimensionAnalyzer` - 设备维度分析

## Cookie 管理

### ⚠️ 重要说明

**本技能不再支持自动从浏览器获取 Cookie，必须由用户手动提供 Cookie 值。**

### 方法一：直接通过对话提供 Cookie（推荐）

用户可以在对话中直接提供 Cookie，系统会自动验证并保存。

**示例格式：**
```
我的友盟 Cookie 是：ctoken=xxx; other_cookies...
```

**处理流程：**
1. 系统接收用户提供的 Cookie
2. 自动验证 Cookie 是否包含必需的 `ctoken` 字段
3. 验证通过则保存到 `~/.qoderwork/skills/umeng-push-helper/cookie.txt`
4. 显示验证结果和保存路径

### 方法二：使用命令行工具保存 Cookie

如果用户已经复制了 Cookie 值，可以使用以下命令保存：

```bash
python scripts/manage_cookie.py save "用户提供的 cookie 值"
```

该命令会：
- 自动验证 Cookie 是否包含必需的 `ctoken` 字段
- 提取并验证 `ctoken` 长度（必须 >= 10）
- 验证通过则保存到本地文件
- 显示详细的验证结果

### 指导用户如何获取 Cookie

如果用户不知道如何获取 Cookie，请提供以下详细步骤：

#### 步骤 1：登录友盟后台
1. 打开浏览器访问：https://upush.umeng.com/apps/list
2. 输入账号密码完成登录

#### 步骤 2：打开开发者工具
1. 按 **F12** 键（或右键点击页面 -> 检查）
2. 切换到 **Network**（网络）标签

#### 步骤 3：触发接口请求
1. 刷新页面（F5）
2. 或在左侧菜单点击任意功能（如"推送记录"）
3. 在 Network 标签的左侧列表中找到 XHR 请求（如 `listAll`、`appInfo`、`getMsgList` 等）

#### 步骤 4：复制 Cookie
1. 点击任意 XHR 请求
2. 在右侧面板中找到 **Request Headers**（请求头）部分
3. 找到 **Cookie** 字段
4. 复制完整的 Cookie 值（是一整行很长的字符串，包含多个以分号分隔的键值对）

#### 步骤 5：提供 Cookie
将复制的 Cookie 值通过以下方式之一提供给系统：
- **方式 A**：在对话中直接发送："我的 Cookie 是：[粘贴的值]"
- **方式 B**：使用命令行保存：`python scripts/manage_cookie.py save "[粘贴的值]"`

### Cookie 验证要求

系统会验证 Cookie 是否包含以下必需字段：
- ✅ `ctoken` - CSRF 令牌（长度必须 >= 10）

**注意**：不再强制要求 `umplus_uc_loginid` 字段。

### 使用 Cookie

**首次保存后，后续使用无需重复提供！**

系统会自动从 `~/.qoderwork/skills/umeng-push-helper/cookie.txt` 读取 Cookie 并携带在请求头中。

**Cookie 有效期**：
- Cookie 通常在数小时到数天内有效
- 如果 API 返回认证错误，说明 Cookie 已过期
- 需要重新登录并获取新的 Cookie

### 查看和管理 Cookie

```bash
# 检查是否已保存 Cookie
python scripts/manage_cookie.py check

# 加载已保存的 Cookie（查看完整值）
python scripts/manage_cookie.py load

# 验证 Cookie 是否仍然有效
python scripts/manage_cookie.py validate "<cookie_value>"

# 提取 ctoken（用于调试）
python scripts/manage_cookie.py extract-ctoken "<cookie_value>"
```

## 功能一：获取应用列表

### API 信息

- **URL**: `https://upush.umeng.com/hsf/home/listAll`
- **Method**: POST
- **Content-Type**: `application/json`

### 请求参数

```json
{
  "appkey": "",
  "platform": "all",
  "page": 1,        // 页码，默认为 1，用户可查看下一页时 +1
  "perPage": 15,    // 每页固定 15 条记录
  "hasPush": 0,
  "appName": "",
  "yearQuotaSts": 0
}
```

### 请求头

```
Content-Type: application/json;charset=UTF-8
Cookie: <从 cookie.txt 读取>
x-csrf-token: <从 Cookie 中提取的 ctoken 值>
```

**重要说明**：系统会自动从 Cookie 中提取 `ctoken` 的值并添加到 `x-csrf-token` 请求头中，无需手动操作。

### 响应解析与数据解读

从响应数据中提取 `data.appList` 数组，该数组包含应用信息。对每个应用提取以下字段：

- `appkey` - 应用的唯一标识
- `appName` - 应用名称
- `platform` - 平台类型（android/iOS/harmony）
- `dau` - 日活跃用户数

**数据解读示例**：
```
================================================================================
账号下共有 739 个应用，共分 50 页，当前处于第 1 页
================================================================================

序号     appkey                       应用名称                                     平台                DAU
--------------------------------------------------------------------------------
1      EXAMPLE_APPKEY_001     嗣曼 PUSH 测试应用                               android             2
2      EXAMPLE_APPKEY_002     ROLA 内测版                                  harmony             0
3      EXAMPLE_APPKEY_003     雨桐 -0529                                  harmony             0
...

================================================================================
本页显示 15 个应用（第 1-15 个）
下一页：python scripts/get_app_list.py --page 2
上一页：python scripts/get_app_list.py --page 1
================================================================================
```

### 分页使用说明

**默认行为**：
- 首次调用时 `page` 默认为 1
- 每页固定显示 15 条记录
- 当用户希望查看下一页时，将 `page` 参数 +1

**命令行使用示例**：
```bash
# 显示第 1 页（默认）
python scripts/get_app_list.py

# 显示第 2 页
python scripts/get_app_list.py 2

# 显示第 3 页
python scripts/get_app_list.py --page 3

# 查看最后一页
python scripts/get_app_list.py --page 50
```

**输出信息包含**：
- ✅ 账号下应用总数（从返回结果的 `data.total` 字段解析）
- ✅ 总页数（从返回结果的 `data.totalPage` 字段解析）
- ✅ 当前页码（从返回结果的 `data.currPage` 字段解析）
- ✅ 本页显示的应用数量和范围
- ✅ 上一页/下一页导航提示

**列表字段说明**：
- **序号**：当前应用在所有应用中的排序位置
- **appkey**：应用的唯一标识符
- **应用名称**：应用的展示名称
- **平台**：应用所属平台（android/iOS/harmony）
- **DAU**：日活跃用户数

## 功能二：查询应用数据（三个接口）

### 前置条件

用户需要指定一个 `appkey` 参数

### 使用流程

1. 确认用户已提供 `appkey`
2. 如果未提供，先调用"获取应用列表"功能让用户选择
3. 使用选定的 `appkey` 依次调用以下三个接口

### 接口 1：消息概览 (messageOverview)

**API 信息**:
- **URL**: `https://upush.umeng.com/hsf/push/messageOverview`
- **Method**: POST
- **参数**: `{"appkey": "<用户输入的 appkey>", "dateType": "7d"}`

**响应解析**:
从 `data.list` 数组中提取每个项目的 `name` 和 `value` 字段，以列表形式展示。

### 接口 2：诊断摘要 (diagnosisSummery)

**API 信息**:
- **URL**: `https://upush.umeng.com/hsf/push/diagnosisSummery`
- **Method**: POST
- **参数**: `{"appkey": "<用户输入的 appkey>", "dateType": "7d"}`

**响应解析**:
直接展示 `data` 字段的内容。

### 接口 3：诊断报告 (diagnosisReport)

**API 信息**:
- **URL**: `https://upush.umeng.com/hsf/push/diagnosisReport`
- **Method**: POST
- **参数**: `{"appkey": "<用户输入的 appkey>", "dateType": "7d"}`

**响应解析**:
提取 `data` 值，并进行简单分析：
- 如果包含 `score` 字段，显示健康得分
- 如果包含 `issues` 或 `problems` 字段，列出发现的问题
- 如果包含 `suggestions` 或 `recommendations` 字段，列出建议

### 请求头（三个接口通用）

```
Content-Type: application/json;charset=UTF-8
Cookie: <从 cookie.txt 读取>
x-csrf-token: <从 Cookie 中提取的 ctoken 值>
```

**重要说明**：系统会自动从 Cookie 中提取 `ctoken` 的值并添加到 `x-csrf-token` 请求头中，无需手动操作。

### 示例命令

```bash
python scripts/query_app_data.py EXAMPLE_APPKEY_004
```

## 功能四：推送轨迹查询（消息排查工具）

### 🎯 功能概述

**主要用途**：当用户反馈收不到推送消息时，通过提供 `appkey`、`device_token` 和 `msg_id`，自动分三步排查问题原因。

**适用场景**：
- 📱 用户反馈收不到推送消息
- ✅ 推送后台显示成功但用户未收到
- 🔍 需要排查推送失败的具体原因
- 📊 分析消息的发送、到达、点击状态

### 前置条件

用户需要提供以下三个参数：

| 参数 | 说明 | 如何获取 |
|------|------|----------|
| **appkey** | 应用的唯一标识 | 运行 `python scripts/get_app_list.py` 查看应用列表 |
| **device_token** | 设备的推送 token | 从客户端日志、数据库或友盟后台的设备管理中获取 |
| **msg_id** | 消息 ID（22 位） | 从友盟后台的推送记录中点击具体某条推送查看详情 |

### 使用流程

系统会依次执行以下四个步骤，并提供**智能诊断建议**：

#### 步骤 1：查询消息生命周期

**API 信息**:
- **URL**: `https://upush.umeng.com/hsf/push/getToolLifeCycle`
- **Method**: POST
- **参数**: 
```json
{
  "appkey": "<应用 key>",
  "deviceToken": "<设备 token>",
  "msgId": "<消息 ID>"
}
```

**返回信息**:
- ✅ 消息发送时间 - 判断推送是否已发出
- ✅ 消息到达时间 - 判断设备是否收到
- ✅ 消息点击时间 - 判断用户是否点击
- ⚠️ 如果缺少某个时间点，会提示可能的问题

**诊断逻辑**:
```
❌ 无发送时间 → 推送任务未执行或被取消
✅ 有发送时间，❌ 无到达时间 → 网络问题、通道延迟、设备异常
✅ 有到达时间，❌ 无点击时间 → 正常现象（用户未点击）
```

#### 步骤 2：查询设备信息（含厂商 Token 检查）⭐

**API 信息**:
- **URL**: `https://upush.umeng.com/hsf/setting/getDeviceInfo`
- **Method**: POST
- **参数**: 
```json
{
  "appkey": "<应用 key>",
  "deviceToken": "<设备 token>"
}
```

**返回信息**:
- 设备型号 - 确认设备类型
- 操作系统版本 - 判断系统兼容性问题
- 应用版本 - 检查 SDK 版本
- 推送通道 - 验证通道配置是否正确
- **thirdTokens** - 厂商推送 Token 字典（仅安卓设备，新增重点检查项⭐）

**诊断逻辑**:
```
❌ 无法获取设备信息 → device_token 不正确或设备从未注册
⚠️ 推送通道为 unknown → 设备推送配置异常
✅ 信息完整 → 设备状态正常
```

**🔍 thirdTokens 字段检查（新增功能）**：

当检测到设备为安卓设备时，会自动检查 `thirdTokens` 字段：

1. **thirdTokens 为空** ❌
   ```
   ❌❌❌ 严重问题：未获取到任何厂商 Token ❌❌❌
   
   【问题分析】
   - thirdTokens 字段为空，说明设备未成功注册任何厂商推送通道
   - 当设备离线时，推送将无法通过厂商通道下发
   - 这是导致消息无法送达的重要原因！
   
   【可能原因】
   1. 客户端未集成对应厂商的推送 SDK
   2. 厂商推送配置不正确（如 AppKey、AppSecret 配置错误）
   3. 客户端初始化时未正确调用厂商通道注册方法
   4. 设备不支持该厂商推送（如模拟器、定制 ROM）
   
   【解决方案】
   1. 检查客户端代码，确认已集成对应厂商的推送 SDK
   2. 在友盟后台配置正确的厂商推送凭证
      路径：友盟后台 → 应用配置 → 推送渠道 → 配置对应厂商
   3. 引导用户重启应用，重新注册推送
   4. 检查客户端日志，查看厂商通道初始化是否成功
   ```

2. **thirdTokens 包含有效值** ✅
   ```
   ✅ thirdTokens 字段包含内容:
   
      ✅ 华为：abc123def456... (有效)
      ✅ 小米：xyz789ghi012... (有效)
      ⚠️  OPPO: 空值或无效
   
   ✅ 设备已成功注册厂商推送通道
   💡 如果仍无法收到消息，请检查：
      1. 厂商后台配置的证书/凭证是否正确
      2. 推送内容是否符合厂商规范
      3. 设备通知权限是否开启
   ```

3. **thirdTokens 全为无效值** ⚠️
   ```
   ⚠️  警告：虽然有 thirdTokens 字段，但所有厂商 token 均为空或无效
   💡 这可能导致离线推送失败
   ```

#### 步骤 3：查询推送请求内容

**API 信息**:
- **URL**: `https://upush.umeng.com/hsf/push/getToolRequestContent`
- **Method**: POST
- **参数**: 
```json
{
  "appkey": "<应用 key>",
  "msgId": "<消息 ID>"
}
```

**返回信息**:
- 推送标题和内容
- 推送类型（单播/广播/组播等）
- 推送发送时间
- 目标受众信息

**诊断逻辑**:
```
❌ 无法获取推送内容 → msg_id 不正确或记录已删除
✅ 内容完整 → 推送配置正常
```

#### 步骤 4：查询当天消息列表（分页获取所有记录）

**API 信息**:
- **URL**: `https://upush.umeng.com/hsf/setting/deviceMessage`
- **Method**: POST
- **参数**: 
```json
{
  "appkey": "<应用 key>",
  "deviceToken": "<设备 token>",
  "startDate": "<从 msg_id 中提取的日期>",
  "endDate": "<从 msg_id 中提取的日期>",
  "page": 1,
  "pageSize": 50
}
```

**返回信息**:
- 当天该设备收到的所有推送消息列表
- 包含字段：msgId、digest（标题）、startTime、status、channel 等

**分页逻辑**:
```
1. 先查询第 1 页（pageSize=50），获取总记录数 total
2. 如果 total > 50，计算总页数 = (total + 49) / 50
3. 依次查询第 2 页、第 3 页...直到所有页面获取完成
4. 合并所有页面的消息记录
5. 找到目标 msg_id 在列表中的位置
6. 显示目标消息及之后的所有消息（按发送时间降序）
```

**输出格式**:
```
序号     消息 ID                     标题                   发送时间                 状态           通道        
----------------------------------------------------------------------------------------------------
🎯1     uaop149177503491390601    点赞                   2026-04-01 17:15:13  送达失败         oppo      
  2     uaqeph2177503481348101    评论                   2026-04-01 17:13:33  已忽略          友盟        
  3     uafzrt6177502881316001    评论                   2026-04-01 15:33:33  送达成功         友盟        
```

**说明**:
- 🎯 标记为目标消息
- 显示目标消息及之前发送的消息（因为列表按时间降序排列）
- 帮助分析推送频率、限流策略等问题

### 📋 命令行使用示例

```bash
# 基本用法
python scripts/query_push_trace.py <appkey> <device_token> <msg_id>

# 示例 1：排查用户反馈的推送问题
python scripts/query_push_trace.py EXAMPLE_APPKEY_001 abc123xyz 1234567890abcdef

# 示例 2：使用真实的参数
python scripts/query_push_trace.py EXAMPLE_APPKEY_002 V1_abc123def456 1a2b3c4d5e6f7g8h9i0j1k
```

### 💡 输出格式示例

```
================================================================================
🔍 友盟推送消息排查
================================================================================
应用 Key     : EXAMPLE_APPKEY_001
设备 Token   : abc123xyz
消息 ID      : 1234567890abcdef
================================================================================

开始排查消息未收到的原因...
================================================================================

================================================================================
步骤 1：查询消息生命周期
================================================================================
接口：https://upush.umeng.com/hsf/push/getToolLifeCycle
请求参数:
{
  "appkey": "EXAMPLE_APPKEY_001",
  "deviceToken": "abc123xyz",
  "msgId": "1234567890abcdef"
}

返回结果:
{
  "sendTime": "2024-01-01 10:00:00",
  "arriveTime": null,
  "clickTime": null
}

【消息状态分析】
✅ 消息已发送：2024-01-01 10:00:00
⚠️  消息已发送但未到达 - 可能原因：
   - 设备网络问题
   - 推送通道延迟
   - 设备已关机或卸载应用

... (步骤 2 和步骤 3) ...

================================================================================
📊 排查结果汇总与诊断建议
================================================================================

发现以下问题：

   ⚠️  4. 消息已发送但未到达 - 检查设备网络状态、推送通道配置

建议按以上顺序逐一排查

================================================================================
排查完成
================================================================================
```

### 🔧 请求头（三个接口通用）

```
Content-Type: application/json;charset=UTF-8
Cookie: <从 cookie.txt 读取>
x-csrf-token: <从 Cookie 中提取的 ctoken 值>
```

**重要说明**：系统会自动从 Cookie 中提取 `ctoken` 的值并添加到 `x-csrf-token` 请求头中，无需手动操作。

### 🛠️ 常见排查场景与建议

#### 场景 1：消息未发送
```
症状：无 sendTime
可能原因:
- 推送任务被取消
- 定时推送时间未到
- 推送配额已用完
建议：检查推送任务状态和配额使用情况
```

#### 场景 2：消息已发送但未到达
```
症状：有 sendTime，无 arriveTime
可能原因:
- 设备网络异常（离线/弱网）
- 推送通道侧延迟或失败
- 设备已关机或卸载应用
- 设备通知权限被关闭
建议：
1. 确认设备在线状态
2. 检查推送通道配置
3. 引导用户检查通知权限
```

#### 场景 3：消息已到达但用户未点击
```
症状：有 sendTime 和 arriveTime，无 clickTime
说明：这是正常现象，不属于技术问题
建议：优化推送内容和时机，提升点击率
```

#### 场景 4：设备信息查询失败
```
症状：getDeviceInfo 返回错误
可能原因:
- device_token 不正确或已失效
- 设备从未注册过推送
- 设备已被删除
建议：重新获取正确的 device_token
```

### ⚠️ 错误处理

- **Cookie 无效或过期**：提示用户重新登录并获取新的 Cookie
- **参数格式错误**：显示正确的用法和参数获取方法
- **API 返回错误**：显示具体的错误信息和可能的原因
- **网络错误**：提示检查网络连接

### 📝 最佳实践

1. **优先检查 msg_id**：确保从推送记录中获取的是正确的消息 ID
2. **验证 device_token**：确保 token 是该设备当前有效的标识
3. **结合日志分析**：如有条件，同时查看客户端日志和服务端日志
4. **多次测试**：对同一设备发送多条推送，排除偶发因素

### 前置条件

用户需要指定一个 `appkey` 参数

### 使用流程

1. 确认用户已提供 `appkey`
2. 如果未提供，先调用"获取应用列表"功能让用户选择
3. 使用选定的 `appkey` 调用周报 API（具体 API 端点待用户提供或补充）

## 错误处理

### Cookie 无效或过期

**症状**：API 返回 401、403 或其他认证错误

**处理步骤**：
1. **告知用户**：Cookie 可能已过期或无效
2. **指导用户重新获取**：
   - 访问 https://upush.umeng.com 重新登录
   - 按 F12 打开开发者工具 -> Network 标签
   - 刷新页面，点击任意 XHR 请求
   - 复制 Request Headers 中的 Cookie 值
3. **更新 Cookie**：
   - 在对话中提供新的 Cookie："我的新 Cookie 是：[新值]"
   - 或使用命令行：`python scripts/manage_cookie.py save "[新值]"`
4. **重试请求**：使用新 Cookie 重新执行操作

### API 调用失败

**排查步骤**：
1. 检查网络连接是否正常
2. 验证 Cookie 是否正确（包含必需的 ctoken）
3. 检查请求参数格式是否符合要求
4. 查看具体的错误响应信息
5. 向用户展示详细的错误原因和解决建议

### ⚠️ 禁止接口调用请求

**当用户请求调用禁止的接口时**：

必须明确拒绝并回复：
```
抱歉，出于安全考虑，本技能禁止调用以下类型的接口：

❌ 发送推送消息 (sendMsg)
❌ 修改应用配置 (updateApp)
❌ 修改渠道信息 (updateChannelInfo)
❌ 保存回执配置 (saveReceipt)

这些操作涉及账号安全和数据修改，需要您登录友盟官方后台 (https://upush.umeng.com) 手动执行。

本技能仅支持查询类操作（只读），如：
✅ 获取应用列表
✅ 查询推送数据
✅ 查看诊断报告
```

**处理原则**：
- 态度坚定但礼貌
- 不提供任何绕过方法
- 引导用户使用官方后台
- 说明安全原因

## 安全注意事项

- Cookie 包含敏感认证信息，仅保存在本地
- 不要将 Cookie 分享到聊天或日志中
- 建议用户定期更新 Cookie

## 相关文件

### 核心文件
- `cookie.txt` - 存储用户登录 Cookie
- `SKILL.md` - 技能定义文档

### 脚本工具
- `scripts/manage_cookie.py` - Cookie 管理工具（保存、加载、验证、提取 ctoken）
- `scripts/get_app_list.py` - 获取应用列表
- `scripts/query_app_data.py` - 查询应用数据（三个接口）
- `scripts/query_push_trace.py` - 推送轨迹查询（消息排查工具）
- `scripts/query_switch_statistics.py` - 开关统计查询
- `scripts/query_close_attribution.py` - 关闭归因分析（新增功能）⭐
- `scripts/query_overview_stats.py` - 概况统计查询（新增功能）⭐
- `scripts/query_msg_list.py` - 获取消息列表（新增功能）⭐
- `scripts/query_msg_detail.py` - 单条消息详情查询（新增功能）⭐
- `scripts/switch_chart_template.html` - 开关统计 HTML 图表模板
- `scripts/close_attribution_template.html` - 关闭归因 HTML 图表模板
- `scripts/overview_stats_template.html` - 概况统计 HTML 图表模板
- `scripts/api_request.py` - API 请求封装

## 功能六：关闭归因分析（新增）

### 🎯 功能概述

**主要用途**：深度分析用户关闭推送功能的原因，从四个维度提供详细的归因数据，帮助优化推送策略。

**适用场景**：
- 🔍 分析用户为什么关闭推送
- 📊 了解不同推送频次的效果
- 📝 优化通知内容和类型
- 📲 针对不同设备制定策略

### 四个分析维度

#### 1️⃣ 用户偏好分析

**接口**: `POST https://upush.umeng.com/hsf/dataStatistic/userPreferenceAnalyzer`

**功能**: 分析用户关闭推送的偏好原因分布

**参数**:
```json
{
  "appkey": "<应用 key>",
  "datetype": "7d"  // 支持：1d(昨日), 7d(近 7 日)
}
```

**展示形式**: 
- 文本条形图：显示各原因的关闭数量和占比

#### 2️⃣ 推送频次分析

**接口**: `POST https://upush.umeng.com/hsf/dataStatistic/pushFrequencyAnalyzer`

**功能**: 分析推送频次与用户关闭的关系

**参数**: 同用户偏好分析

**展示形式**:
- 文本条形图：显示不同频次区间的关闭情况

#### 3️⃣ 通知内容分析

**接口**: `POST https://upush.umeng.com/hsf/dataStatistic/pushMessageAnalyzer`

**功能**: 分析每条推送消息的关闭情况，提供详细的消息内容和效果数据

**参数**: 同用户偏好分析

**展示字段**:
- 任务描述 (description) - 推送的消息描述
- 目标人群 (target) - 推送的目标用户群体
- 发送时间 (pushTime) - 消息发送的具体时间
- 通知标题 (title) - 推送通知的标题
- 通知内容 (text) - 推送通知的正文内容
- 消息点击数 (clickNum) - 该消息被点击的次数
- 关闭通知数 (closeNum) - 用户收到后关闭通知的次数
- 正负效果比 (effectRatio) - 点击与关闭的效果比率
- 消息 ID (msgId) - 消息的唯一标识

**展示形式**:
- 文本表格：详细列出每条消息的完整信息和效果数据

#### 4️⃣ 设备维度分析

**接口**: `POST https://upush.umeng.com/hsf/dataStatistic/deviceDimensionAnalyzer`

**功能**: 分析不同设备类型的关闭分布

**参数**: 同用户偏好分析

**展示形式**:
- 文本条形图：显示各设备类型的关闭情况

### 📋 使用方法

#### 命令行方式

```bash
# 查询近 7 日数据（默认）
python scripts/query_close_attribution.py EXAMPLE_APPKEY_005

# 查询昨日数据
python scripts/query_close_attribution.py EXAMPLE_APPKEY_005 1d

# 查询近 7 日数据
python scripts/query_close_attribution.py EXAMPLE_APPKEY_005 7d
```

#### 对话方式

告诉助手：
- "分析 EXAMPLE_APPKEY_005 的关闭归因"
- "查看应用的关闭归因分析"
- "查询昨日关闭归因数据"

### 💡 输出示例

```
================================================================================
🔍 友盟推送 - 关闭归因分析
================================================================================
应用 Key   : EXAMPLE_APPKEY_005
时间范围   : 近 7 日
================================================================================

👤 正在查询 用户偏好分析...
✅ 用户偏好分析 查询成功

================================================================================
👤 用户偏好分析 (近 7 日)
================================================================================

【用户关闭原因偏好分布】
--------------------------------------------------------------------------------
1. 推送太频繁              12,345     45.67% |████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░|
2. 内容不相关               8,234     30.45% |███████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░|
3. 打扰休息                 4,567     16.89% |████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░|
...

📱 推送频次分析...
📝 通知内容分析...
📲 设备维度分析...

🎨 正在生成可视化图表报告...
✅ 图表报告已生成：/path/to/report.html
```

### 📊 数据解读

**用户偏好分析**：
- 识别主要的关闭原因
- 针对性优化推送策略
- 减少用户流失

**推送频次分析**：
- 找到最佳推送频次区间
- 避免过度推送引起反感
- 平衡触达率和用户体验

**通知内容分析**：
- 了解哪些类型的内容更受欢迎
- 优化推送内容质量
- 提高点击率和点击效果

**设备维度分析**：
- 了解不同设备用户的行为差异
- 针对特定设备优化推送策略
- 提升特定平台的推送效果

### ⚠️ 注意事项

1. **日期限制**：仅支持 `1d`（昨日）和`7d`（近 7 日），不可随意传其他日期
2. **Cookie 要求**：必须携带有效的 Cookie 才能访问接口
3. **数据解读**：结合多个维度综合分析，不要单一维度下结论
4. **隐私保护**：所有数据均为聚合统计，不包含个人隐私信息

### 📈 优化建议

根据分析结果，可以：
1. 调整推送频次，避免用户反感
2. 优化推送内容，提高相关性
3. 分时段推送，避开休息时间
4. 针对不同设备制定差异化策略
5. A/B 测试不同推送策略的效果

## 功能七：概况统计查询（新增）

### 🎯 功能概述

**主要用途**：一站式查询应用的核心运营数据，包括应用概况、推送转换漏斗、厂商通道额度（仅安卓），支持生成美观的 HTML 可视化报告。

**适用场景**：
- 📊 快速了解应用整体运营状况
- 🔄 分析推送消息的转化漏斗
- 🏭 监控厂商通道额度使用情况
- 📈 生成可视化数据报告

### 三个查询接口

#### 1️⃣ 应用概况

**接口**: `POST https://upush.umeng.com/hsf/overview/getAppCnt`

**功能**: 获取应用的总体运营数据

**参数**:
```json
{
  "appkey": "<应用 key>"
}
```

**返回指标**:
- `totalDevices` - 总设备数
- `todayActive` - 今日活跃设备数
- `todayPush` - 今日推送数量
- `todayArrive` - 今日送达数量
- `todayShow` - 今日展示数量
- `todayClick` - 今日点击数量

**各阶段比率计算**:
- 送达率 = todayArrive / todayPush × 100%
- 展示率 = todayShow / todayArrive × 100%
- 点击率 = todayClick / todayShow × 100%

#### 2️⃣ 推送转换数据

**接口**: `POST https://upush.umeng.com/hsf/overview/getTransformData`

**功能**: 获取推送消息的转换漏斗数据

**参数**:
```json
{
  "appkey": "<应用 key>",
  "msgType": "notification",  // 或 "message"
  "dateType": "1d"            // 支持："1d", "3d", "7d"
}
```

**参数说明**:
- `msgType`: 
  - `notification` - 通知栏消息（默认）
  - `message` - 消息
- `dateType`:
  - `1d` - 昨日（默认）
  - `3d` - 近 3 日
  - `7d` - 近 7 日

**返回指标**:
- `pushCnt` - 推送数量
- `arriveCnt` - 到达数量
- `showCnt` - 展示数量
- `clickCnt` - 点击数量

#### 3️⃣ 厂商通道额度（仅安卓）

**接口**: `POST https://upush.umeng.com/hsf/overview/queryThirdQuota`

**功能**: 查询各大手机厂商的推送通道额度使用情况

**参数**:
```json
{
  "appkey": "<应用 key>"
}
```

**支持的厂商**:
- 华为 (huawei)
- 小米 (xiaomi)
- OPPO (oppo)
- VIVO (vivo)
- 荣耀 (honor)
- 魅族 (meizu)

**返回指标**（每个厂商）:
- `total` - 总额度
- `remaining` - 剩余额度
- `used` = total - remaining（已使用额度）
- `usage_rate` = used / total × 100%（使用率）

### 📋 使用方法

#### 命令行方式

```bash
# 查询昨日数据（默认）
python scripts/query_overview_stats.py EXAMPLE_APPKEY_005

# 查询并生成 HTML 可视化报告
python scripts/query_overview_stats.py EXAMPLE_APPKEY_005 --html

# 查询近 3 日数据
python scripts/query_overview_stats.py EXAMPLE_APPKEY_005 3d

# 查询近 7 日数据并生成报告
python scripts/query_overview_stats.py EXAMPLE_APPKEY_005 7d --html

# 查询消息类型的近 3 日数据
python scripts/query_overview_stats.py EXAMPLE_APPKEY_005 3d message

# 查询并生成报告（完整参数）
python scripts/query_overview_stats.py EXAMPLE_APPKEY_005 7d notification --html
```

#### 对话方式

告诉助手：
- "查询 EXAMPLE_APPKEY_005 的概况统计"
- "查看应用的概况统计数据"
- "生成昨日的数据报告"
- "查询近 7 日的推送转换数据"
- "帮我生成概况统计的可视化报告"

### 💡 输出示例

#### 终端输出

```
================================================================================
📊 友盟推送 - 概况统计
================================================================================
应用 Key   : EXAMPLE_APPKEY_005
时间范围   : 昨日
消息类型   : 通知栏消息
================================================================================

📊 正在查询 应用概况...
✅ 应用概况 查询成功

================================================================================
📊 应用概况统计
================================================================================

应用 Key: EXAMPLE_APPKEY_005
--------------------------------------------------------------------------------
指标                                          数值             占上一阶段比率
--------------------------------------------------------------------------------
总设备数                                         1,408,306
今日活跃设备                                       125,432
今日推送                                           50,000
今日送达                                           48,500          97.00%
今日展示                                           35,000          72.16%
今日点击                                           12,000          34.29%
--------------------------------------------------------------------------------

📱 正在查询 推送转换数据...
✅ 推送转换数据 查询成功

================================================================================
📱 推送转换数据 (通知栏消息 - 昨日)
================================================================================

阶段                                数量             占上一阶段比率
------------------------------------------------------------
推送                                 50,000
送达                                 48,500          97.00%
展示                                 35,000          72.16%
点击                                 12,000          34.29%
------------------------------------------------------------

📊 转化漏斗:
推送   ██████████████████████████████████████████████████ 50,000
送达   ███████████████████████████████████████████████░░ 48,500 (97.00%)
展示   ██████████████████████████████████████░░░░░░░░░░░ 35,000 (72.16%)
点击   ███████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 12,000 (34.29%)

🏭 正在查询 厂商通道额度...
💡 提示：仅安卓应用需要查询此项
✅ 厂商通道额度 查询成功

================================================================================
🏭 厂商通道额度统计
================================================================================

应用 Key: EXAMPLE_APPKEY_005
--------------------------------------------------------------------------------
厂商                         剩余额度             总额度             使用率
--------------------------------------------------------------------------------
华为                           850,000         1,000,000       15.00% |███████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░|
小米                           420,000           500,000       16.00% |████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░|
OPPO                           180,000           200,000       10.00% |█████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░|
VIVO                           270,000           300,000       10.00% |█████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░|
--------------------------------------------------------------------------------

================================================================================
✅ 概况统计查询完成
================================================================================

📊 正在生成 HTML 可视化报告...
✅ 图表报告已生成：/path/to/outputs/overview_stats_EXAMPLE_APPKEY_005_20260403_152736.html
🌐 已在浏览器中打开报告
```

### 📊 数据解读

**应用概况**：
- **总设备数**：反映应用的用户规模
- **今日活跃**：反映应用的日常活跃度
- **推送 - 送达 - 展示 - 点击**：完整的推送转化链路
- **各阶段比率分析**：
  - 送达率低 → 检查设备在线状态、推送通道配置
  - 展示率低 → 检查通知栏折叠、系统限制
  - 点击率低 → 优化推送内容和时机

**推送转换**：
- **推送数量**：当天的推送任务总量
- **各阶段比率趋势**：对比不同日期类型的变化情况
- **消息类型对比**：通知栏消息 vs 消息的转化差异

**厂商额度**：
- **使用率监控**：防止额度用尽影响推送
- **额度分配优化**：根据各厂商用户占比合理分配
- **预警机制**：当使用率超过 80% 时应引起注意

### 🎨 HTML 可视化报告

**报告特点**：
- 📊 **应用概况柱状图**：直观展示各项指标的对比
- 🔄 **推送转换漏斗图**：横向条形图展示转化流程
- 🏭 **厂商额度堆叠柱状图**：显示已使用和剩余额度
- 🎨 **渐变配色**：紫色系主题，美观专业
- 📱 **响应式设计**：适配各种屏幕尺寸

**报告内容**：
1. **应用概况部分**
   - 6 个指标卡片（总设备数、今日活跃、今日推送、今日送达、今日展示、今日点击）
   - 柱状图对比各指标
2. **推送转换部分**
   - 漏斗条形图（推送→送达→展示→点击）
   - 转换率标注
   - 横向柱状图展示转化流程
3. **厂商额度部分**
   - 各厂商额度卡片
   - 堆叠柱状图显示总额度和剩余额度
   - 使用率进度条

### ⚠️ 注意事项

1. **日期限制**：`dateType` 仅支持 `1d`、`3d`、`7d`，不可随意传其他值
2. **消息类型**：`msgType` 仅支持 `notification` 和 `message`
3. **厂商额度**：仅安卓应用有此项数据，iOS 应用查询会返回空
4. **Cookie 要求**：必须携带有效的 Cookie 才能访问接口
5. **HTML 报告**：使用 `--html` 参数会自动在浏览器中打开报告

### 📈 优化建议

根据概况统计数据，可以：

1. **提升送达率**：
   - 优化推送通道配置
   - 引导用户保持网络畅通
   - 使用厂商通道提高到达率

2. **提升展示率**：
   - 优化推送标题和内容
   - 选择合适的推送时段
   - 避免被系统折叠

3. **提升点击率**：
   - A/B 测试不同推送文案
   - 个性化推送内容
   - 增加推送的吸引力和相关性

4. **厂商额度管理**：
   - 定期监控各厂商额度使用率
   - 根据用户分布调整额度分配
   - 提前申请增加高使用率的厂商额度

5. **数据趋势分析**：
   - 对比不同日期类型（1d/3d/7d）的数据
   - 发现数据异常波动及时排查
   - 建立数据基线，设定合理目标

## 功能八：获取消息列表（包含任务粒度和 API 单播统计）

### 🎯 功能概述

**主要用途**：查询指定应用的消息列表，包含两部分数据：
1. **任务粒度的消息列表** - 显示每条推送任务的完整统计数据
2. **API 单播统计记录** - 显示每日 API 单播推送的统计数据

**适用场景**：
- 📨 查看应用的历史推送记录
- 📊 分析每条消息的推送效果
- 📡 监控 API 单播推送的每日数据
- 🔍 排查特定消息的发送情况

### 第一部分：任务粒度的消息列表

#### API 信息

- **URL**: `https://upush.umeng.com/hsf/push/getMsgList`
- **Method**: POST
- **Content-Type**: `application/json`

#### 请求参数

```json
{
  "appkey": "<应用的唯一标识>",
  "productionMode": true,           // 是否生产模式
  "displayType": 0,                 // 展示类型
  "description": "",                // 任务描述筛选
  "timeSelectorType": 1,            // 时间选择器类型
  "startTime": "yyyy-MM-dd",        // 开始时间
  "endTime": "yyyy-MM-dd",          // 结束时间
  "appGroup": false,                // 是否应用组
  "pageIndex": 1,                   // 页码
  "pageSize": 15                    // 每页条数（固定 15）
}
```

#### 显示字段（安卓）

以下字段适用于**安卓应用**的任务粒度消息列表和 API 单播统计列表：

**任务粒度消息列表**:
- `description` - 任务描述
- `target` - 目标人群
- `createTime` - 创建时间
- `pushTime` - 发送时间
- `totalCount` - 计划发送
- `acceptCount` - 有效设备
- `sentCount` - 实际发送
- `arriveCount` - 消息送达
- `arriveRate` - 送达率
- `showCount` - 消息展示
- `showRate` - 展示率
- `clickCount` - 消息点击
- `clickRate` - 送达点击率（点击数/送达数）
- `clickRateOnShow` - 展示点击率（点击数/展示数）
- `ignoreCount` - 消息忽略
- `ignoreRate` - 忽略率

**API 单播统计记录**:
- `date` - 日期
- `acceptCount` - 有效设备
- `sentCount` - 实际发送
- `arriveCount` - 消息送达
- `arriveRate` - 送达率
- `showCount` - 消息展示
- `showRate` - 展示率
- `clickCount` - 消息点击
- `clickRate` - 送达点击率（点击数/送达数）
- `clickRateOnShow` - 展示点击率（点击数/展示数）
- `ignoreCount` - 消息忽略
- `ignoreRate` - 忽略率

**注意**：上述字段为安卓应用的展示指标，iOS 应用的展示字段将在后续补充。

### 第二部分：API 单播统计记录

#### API 信息

- **URL**: `https://upush.umeng.com/hsf/dataStatistic/getApi`
- **Method**: POST
- **Content-Type**: `application/json`

#### 请求参数

```json
{
  "appkey": "<应用的唯一标识>",
  "pageIndex": 1,                   // 页码
  "pageSize": 15                    // 每页条数（固定 15）
}
```

#### 显示字段（安卓）

以下字段适用于**安卓应用**的 API 单播统计列表：

- `date` - 日期
- `acceptCount` - 有效设备
- `sentCount` - 实际发送
- `arriveCount` - 消息送达
- `arriveRate` - 送达率
- `showCount` - 消息展示
- `showRate` - 展示率
- `clickCount` - 消息点击
- `clickRate` - 送达点击率（点击数/送达数）
- `clickRateOnShow` - 展示点击率（点击数/展示数）
- `ignoreCount` - 消息忽略
- `ignoreRate` - 忽略率

**注意**：上述字段为安卓应用的展示指标，iOS 应用的展示字段将在后续补充。

### 使用方法

```bash
# 查询默认时间范围（近 15 天）的消息列表（包含两部分数据）
python scripts/query_msg_list.py EXAMPLE_APPKEY_006

# 查询指定时间范围的消息列表
python scripts/query_msg_list.py EXAMPLE_APPKEY_006 --start 2026-03-20 --end 2026-04-03

# 查询任务列表第 2 页
python scripts/query_msg_list.py EXAMPLE_APPKEY_006 --page 2

# 查询 API 单播统计第 2 页
python scripts/query_msg_list.py EXAMPLE_APPKEY_006 --api-page 2

# 同时查询任务列表和 API 单播统计的不同页
python scripts/query_msg_list.py EXAMPLE_APPKEY_006 --page 2 --api-page 3

# 按任务描述筛选
python scripts/query_msg_list.py EXAMPLE_APPKEY_006 --desc '测试'
```

### 输出示例

```
================================================================================================================================================================
📨 友盟推送 - 消息列表（任务粒度）
================================================================================================================================================================
应用 Key   : EXAMPLE_APPKEY_006
时间范围   : 2026-01-01 ~ 2026-04-07
================================================================================================================================================================

📊 共有 1 条数据，共 1 页，当前第 1 页
----------------------------------------------------------------------------------------------------------------------------------------------------------------

  序号 | 任务描述                 | 目标人群         | 创建时间               | 发送时间               | 计划发送         | 有效设备         | 实际发送         | 消息送达         | 送达率       | 消息展示         | 展示率       | 消息点击         | 送达点击率       | 展示点击率       | 消息忽略         | 忽略率      
----------------------------------------------------------------------------------------------------------------------------------------------------------------
     1 | N/A                       | 全部用户         | 2026-01-15 10:30:00    | 2026-01-15 10:30:00    |   18,300,244     |   10,275,738     |   10,275,738     |    7,523,500     | 73.22%       |    5,222,299     | 69.41%       |        6,614     |      0.13%       |      0.06%       |        4,649     | 0.06%     
----------------------------------------------------------------------------------------------------------------------------------------------------------------

📄 分页信息：
   当前页：1 / 1
   上一页：已是第一页
   下一页：已是最后一页
================================================================================================================================================================

============================================================================================================================================
📡 API 单播统计记录
============================================================================================================================================
应用 Key   : EXAMPLE_APPKEY_006
============================================================================================================================================

📊 共有 30 条数据，共 2 页，当前第 1 页
--------------------------------------------------------------------------------------------------------------------------------------------

  序号 | 日期           | 有效设备         | 实际发送         | 消息送达         | 送达率       | 消息展示         | 展示率       | 消息点击         | 送达点击率       | 展示点击率       | 消息忽略         | 忽略率      
--------------------------------------------------------------------------------------------------------------------------------------------
     1 | 2026-04-07     |   15,418,704     |   12,699,523     |   10,462,983     | 82.39%       |   10,204,965     | 97.53%       |       16,223     |      0.16%       |      0.16%       |              0     | 0.00%       
     2 | 2026-04-06     |   22,340,705     |   16,526,564     |   11,354,701     | 68.71%       |   10,968,029     | 96.59%       |       20,238     |      0.18%       |      0.18%       |              0     | 0.00%       
--------------------------------------------------------------------------------------------------------------------------------------------
```

## 功能九：单条消息详情查询（新增）

### 🎯 功能概述

**主要用途**：根据 `appkey` 和 `msg_id` 查询单条推送消息的完整详情，包括消息基本信息、推送统计漏斗、失败原因分析、厂商通道集成状态（仅 Android）和分通道送达统计（仅 Android）。

**适用场景**：
- 🔍 排查某条具体推送的发送效果
- 📊 查看单条消息的完整统计漏斗
- 🏭 分析消息在各厂商通道的送达分布
- ⚠️ 诊断消息推送失败的原因

### ⚠️ API 单播检测

**自动识别**：当 `msg_id` 以 `uu`、`ul` 或 `ua` 开头，且倒数第二位是 `0` 时，系统自动判定为 API 单播消息，将提示用户 API 单播不支持查询单条消息明细。

### 查询流程（5 个接口）

#### 接口 1：消息基本信息 (getMsgInfo)

**API 信息**:
- **URL**: `https://upush.umeng.com/hsf/push/getMsgInfo`
- **Method**: POST
- **参数**: 
```json
{
  "appkey": "<应用 key>",
  "taskId": "<msg_id>"
}
```

**返回信息**:
- 任务描述 (description/title)
- 推送类型 (type/pushType)
- 目标人群 (target)
- 生产模式 (productionMode)
- 发送时间 (pushTime/sendTime)
- 创建时间 (createTime)
- 状态 (status)
- **channelActivity** - Android 厂商通道活动配置（⚠️ 如果未配置，无法通过厂商通道下发，只能依赖应用活跃时通过在线通道下发）

**诊断逻辑**:
```
✅ channelActivity 有值 → 厂商通道可正常下发
⚠️  channelActivity 为空 → 无法通过厂商通道下发，只能在线通道
   结合 getChannelInfo 检查哪些厂商通道未集成，逐一提示用户
```

#### 接口 2：推送统计数据 (getMsgData)

**API 信息**:
- **URL**: `https://upush.umeng.com/hsf/push/getMsgData`
- **Method**: POST
- **参数**: 同上

**返回信息**（按漏斗展示）:
- 计划发送 (totalCount)
- 实际发送 (sentCount)
- 消息送达 (arriveCount) + 送达率
- 消息展示 (showCount) + 展示率
- 消息点击 (clickCount) + 送达点击率 + 展示点击率
- 消息忽略 (ignoreCount) + 忽略率

#### 接口 3：失败分析 (getPushExpStatData)

**API 信息**:
- **URL**: `https://upush.umeng.com/hsf/push/getPushExpStatData`
- **Method**: POST
- **参数**:
```json
{
  "appkey": "<应用 key>",
  "isTask": true,
  "msgId": "<msg_id>",
  "isFree": false,
  "stage": "all",
  "channel": "all"
}
```

**返回信息**:
- 各阶段失败分布（stage、channel、reason、count）
- 按数量排序，计算占比

#### 接口 4：厂商通道集成状态 (getChannelInfo) - 仅 Android

**API 信息**:
- **URL**: `https://upush.umeng.com/hsf/setting/getChannelInfo`
- **Method**: POST
- **参数**: `{"appkey": "<应用 key>"}`

**返回信息**:
- 各厂商通道集成状态（华为、小米、OPPO、VIVO、荣耀、魅族）
- 未集成的通道会发出警告

#### 接口 5：分通道送达统计 (getMsgStatChannelData) - 仅 Android

**API 信息**:
- **URL**: `https://upush.umeng.com/hsf/push/getMsgStatChannelData`
- **Method**: POST
- **参数**: `{"appkey": "<应用 key>", "taskId": "<msg_id>"}`

**返回信息**:
- 各通道（友盟通道/华为/小米/OPPO/VIVO/荣耀/魅族）的发送、送达、展示、点击数据
- `accs` 通道显示为"友盟通道"

### 📋 使用方法

#### 命令行方式

```bash
# 查询消息详情（终端文本输出）
python scripts/query_msg_detail.py EXAMPLE_APPKEY_005 <msg_id>

# 查询并生成 HTML 可视化报告
python scripts/query_msg_detail.py EXAMPLE_APPKEY_005 <msg_id> --html

# API 单播自动拦截
python scripts/query_msg_detail.py EXAMPLE_APPKEY_005 uuabc123def45678901230
# → ⚠️  该消息为 API 单播消息，不支持查询单条消息明细
```

#### 对话方式

告诉助手：
- "查询 EXAMPLE_APPKEY_005 的消息详情，msg_id 是 xxx"
- "查看某条推送的完整数据"
- "分析这条消息的失败原因"

### 💡 输出示例

```
================================================================================================================================================================
📨 友盟推送 - 单条消息详情
================================================================================================================================================================
应用 Key   : EXAMPLE_APPKEY_005
消息 ID    : abcdefg12345678901234
================================================================================================================================================================

【消息基本信息】
----------------------------------------------------------------------------------------------------
  任务描述     : xxx
  推送类型     : 广播
  目标人群     : 全部用户
  生产模式     : 是
  发送时间     : 2026-04-08 10:30:00
  创建时间     : 2026-04-08 10:29:00
  状态         : 发送完成
  厂商通道配置 : 已配置
  通道详情     :
               华为: {...}
               小米: {...}
----------------------------------------------------------------------------------------------------

【推送统计漏斗】
----------------------------------------------------------------------------------------------------
阶段               数量          比率 可视化
----------------------------------------------------------------------------------------------------
计划发送      7,847,893      100.00% ██████████████████████████████████████████████████
实际发送      5,188,950       66.12% ██████████████████████████████████████░░░░░░░░░░
消息送达      4,338,336       83.61% ████████████████████████████████░░░░░░░░░░░░░░░░
消息展示      3,171,839       73.11% █████████████████████████░░░░░░░░░░░░░░░░░░░░░░░
消息点击          6,863        0.16% ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
消息忽略         28,945        0.67% ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
----------------------------------------------------------------------------------------------------

  送达点击率（点击/送达）: 0.16%
  展示点击率（点击/展示）: 0.22%
----------------------------------------------------------------------------------------------------

【失败原因分析】
----------------------------------------------------------------------------------------------------
  序号 | 阶段              | 通道            | 原因                             |         数量 |       占比
----------------------------------------------------------------------------------------------------
     1 | send              | huawei          | 设备离线                            |    123,456 |    45.67%
     2 | arrive            | xiaomi          | 推送限流                            |     89,012 |    32.89%
...
----------------------------------------------------------------------------------------------------

【厂商通道集成状态】
----------------------------------------------------------------------------------------------------
  序号 | 通道名称           | 集成状态         | 配置状态         | 说明
----------------------------------------------------------------------------------------------------
     1 | 华为               | 已集成           | 已配置           |
     2 | 小米               | 已集成           | 已配置           |
     3 | OPPO              | 未集成           | 未配置           |
----------------------------------------------------------------------------------------------------

  ⚠️  以下厂商通道未集成，将无法通过对应通道下发推送：
     - OPPO

【分通道送达统计】
----------------------------------------------------------------------------------------------------
  序号 | 通道           |         发送 |         送达 |      送达率 |         展示 |      展示率 |       点击 |      送达点击率
----------------------------------------------------------------------------------------------------
     1 | 友盟通道          |  1,000,000 |    800,000 |   80.00% |    600,000 |   75.00% |      1,000 |      0.13%
     2 | 华为             |  2,000,000 |  1,800,000 |   90.00% |  1,500,000 |   83.33% |      3,000 |      0.17%
     3 | 小米             |  1,500,000 |  1,200,000 |   80.00% |    900,000 |   75.00% |      2,000 |      0.17%
----------------------------------------------------------------------------------------------------
```

### 📊 数据解读

**消息基本信息**：
- 确认消息配置是否正确
- 检查 channelActivity 是否配置了厂商通道

**推送统计漏斗**：
- 计划发送 → 实际发送：过滤率过高说明设备 token 有效性低
- 实际发送 → 消息送达：送达率低说明通道下发有问题
- 消息送达 → 消息展示：展示率低说明通知栏被折叠或用户未查看
- 消息展示 → 消息点击：点击率低说明推送内容吸引力不足

**失败原因分析**：
- 识别主要失败阶段和原因
- 针对性优化推送策略

**厂商通道集成状态**：
- 确认哪些通道已集成
- 未集成的通道无法下发离线推送

**分通道送达统计**：
- 对比各通道的送达率和点击率
- 优化各通道的推送策略

### 🎨 HTML 可视化报告

使用 `--html` 参数可生成包含以下图表的报告：
- 📋 消息基本信息卡片
- 📊 推送统计漏斗（横向条形图 + 进度条）
- 🔍 失败原因分析（饼图 + 表格）
- 🔧 厂商通道集成状态（状态卡片，仅 Android）
- 📡 分通道送达统计（堆叠柱状图 + 表格，仅 Android）

### ⚠️ 注意事项

1. **API 单播限制**：API 单播消息不支持单条消息详情查询
2. **平台限制**：接口 4 和 5 仅对 Android 应用有效
3. **Cookie 要求**：必须携带有效的 Cookie 才能访问接口
4. **channelActivity 配置**：Android 应用必须正确配置 channelActivity，否则厂商通道无法使用

### 📈 优化建议

根据查询结果，可以：
1. 优化 channelActivity 配置，确保厂商通道可正常下发
2. 集成未开通的厂商通道，提升离线推送到达率
3. 针对高失败率的阶段进行针对性优化
4. 对比各通道的送达率，调整推送策略
5. 优化推送内容，提升点击率
推送消息数据助手（友盟U-Push）

SKILL.md

related skills
