推送消息数据助手（友盟U-Push）

友盟推送后台管理助手（只读查询）。帮助获取应用列表、查询推送数据等。**使用前需用户提供 Cookie**：请访问 https://upush.umeng.com 登录后，在浏览器开发者工具的 Network 标签中复制 Cookie 并提供给系统。Use when working with Umeng push...
view source
installs
stars
karma
SkillRank score ↗
4.2/ 10
evaluated by implexa, claude-haiku-4-5 · 2026-05-26
umeng-push-helper provides read-only querying of umeng push backend data including app lists, message statistics, push traces, and close attribution analysis. requires manual cookie provisioning from umeng dashboard.
structure
5.0
trigger phrases
3.0
procedure
5.0
edge cases
3.0
documentation
4.0
strengths
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. 优化推送内容，提升点击率
related skills

semantically similar in the cross-vendor index
clawhub
68% match
Founder-HongYun Editor Automation
方正鸿云学术出版平台自动化技能。使用 browser 工具处理登录和页面交互，API 调用使用 browser.evaluate() 执行。触发关键词：登录方正鸿云、切换刊物、自动催修、自动催审、催审第 X 条、鸿云任务提醒、自动填写送审单、自动注册 DOI、获取登录 Cookie、调用获取刊物信息接口、调用获取...
don't have the plugin yet? install it then click "run inline in claude" again.