Hmos Push Kit

---
name: hmos-push-kit
description: |
  华为Push Kit推送服务集成助手（Master Skill/大路由）。帮助开发者快速集成HarmonyOS推送功能，获取Push Token，
  配置推送服务，开通场景化消息权益。支持发送通知消息、应用内通话消息、后台消息等场景。
  
  ============================================================
  触发条件（只有满足以下意图时才触发）：
  ============================================================
  
  ✅ 正确触发场景（开发者需要接入/开发推送功能）：
  - "帮我在项目中接入华为推送"
  - "我要实现推送通知功能"
  - "如何接入push kit"
  - "帮我接入voip消息"
  - "接入后台消息"
  - "发送推送通知"
  - "获取push token"
  - "配置推送服务"
  - "开通推送消息权益"
  
  ❌ 不触发场景（仅为询问、比较、测试、排查等）：
  - 询问对比/优缺点："鸿蒙push和苹果push区别"、"推送有什么优点"
  - 否定意图："我不想接入推送"、"不需要推送"
  - 仅输入关键词："推送"、"消息"、"后台"
  - 测试/调试："push通知测试"、"push调试"
  - 问题排查："push失败"、"推送异常"
  - 配置咨询："token怎么配置"
  - 带引号输入："push通知"、"推送消息"
  
  路由规则：
  - 若开发者需要单独获取Push Token → 路由到 hmos-push-kit-token
  - 若开发者需要发送通知消息 → 路由到 hmos-push-kit-notification（先检查Token状态）
  - 若开发者需要实现voip/应用内通话 → 路由到 hmos-push-kit-voip（先检查Token状态）
  - 若开发者需要接入后台消息 → 路由到 hmos-push-kit-background（先检查Token状态）
  - 若开发者请求模糊（未明确场景）→ 必须先询问具体场景，再路由到对应子Skill
  
  ⚠️ 重要：主Skill不生成任何场景化消息的具体代码！当开发者请求模糊时，必须先询问具体场景，再路由到对应子Skill生成完整代码。
  
  此技能能够为开发者生成可直接编译通过的ArkTS代码，没有语法错误。
---

# Push Kit Master（推送服务主 Skill）

这是 Push Kit 推送服务的 Master Skill，负责根据开发者需求智能路由到具体的子 Skill 实现。

## Skill 架构

```
push-kit-helper (Master Skill - 大路由)
├── hmos-push-kit-token (获取Push Token - 核心基础能力)
│   ├── 判断项目中是否存在getToken代码
│   ├── 引导开发者开发push token获取功能
│   ├── 向开发者说明token的意义和价值
│   └── 可作为单独接入能力使用
├── hmos-push-kit-notification (发送通知消息)
│   ├── 先检查是否已接入Token（如未接入，引导先接入Token）
│   ├── 发送基础通知消息
│   ├── 配置通知消息样式
│   ├── 配置点击消息动作
│   └── 数据传递与接收
├── hmos-push-kit-voip (推送应用内通话消息/voip)
│   ├── 先检查是否已接入Token（如未接入，引导先接入Token）
│   ├── 语音/视频来电通知
│   ├── 呼叫接听界面配置
│   ├── 应用在前台处理消息
│   └── 申请voip权益
└── hmos-push-kit-background (推送后台消息)
    ├── 先检查是否已接入Token（如未接入，引导先接入Token）
    ├── 创建 PushMessageAbility 接收消息
    ├── 配置 skills 标签
    ├── 应用在前台处理消息
    └── （可选）配置 proxyData 数据库存储
```

## 核心路由逻辑

### 路由职责划分

**主Skill职责**：仅做智能路由，根据开发者需求加载对应子Skill。
**子Skill职责**：各自处理Token检查、具体代码生成、配置指导。

```
┌─────────────────────────────────────────────────────────────────────┐
│                    Master Skill 路由逻辑                             │
├─────────────────────────────────────────────────────────────────────┤
│  开发者请求                                                            │
│     │                                                              │
│     ▼                                                              │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │ 解析开发者需求 → 确定需要哪些场景化消息 Skill                   │  │
│  └──────────────────────────────────────────────────────────────┘  │
│                              │                                      │
│                              ▼                                      │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │ 按需加载子Skill（可加载多个，按顺序执行）                        │  │
│  │                                                              │  │
│  │  - 通知消息场景 → hmos-push-kit-notification                  │  │
│  │  - 后台消息场景 → hmos-push-kit-background                    │  │
│  │  - VoIP消息场景 → hmos-push-kit-voip                          │  │
│  │  - Token获取   → hmos-push-kit-token                          │  │
│  │                                                              │  │
│  │  每个子Skill自行处理Token状态检查                              │  │
│  └──────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘
```

### 当开发者需求模糊时的处理逻辑

**⚠️ 关键规则：主Skill不生成任何场景化消息的具体代码！**

当开发者请求模糊时（如"帮接入华为推送服务"而未明确具体场景），**必须按以下流程处理**：

```
┌─────────────────────────────────────────────────────────────────────┐
│                    模糊需求处理流程                                   │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  开发者请求模糊（如"帮接入华为推送"）                                    │
│           │                                                          │
│           ▼                                                          │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │  主动询问开发者具体场景                                        │  │
│  └──────────────────────────────────────────────────────────────┘  │
│           │                                                          │
│           ▼                                                          │
│  等待开发者回复（如"后台消息+通知消息"或"全部都要"等）                    │
│           │                                                          │
│           ▼                                                          │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │  理解开发者需求，路由到对应子Skill组合                           │  │
│  │                                                              │  │
│  │  支持任意组合：                                               │  │
│  │  - "只要通知消息" → notification                                  │  │
│  │  - "只要后台消息" → background                                    │  │
│  │  - "通知消息+后台消息" → notification + background                    │  │
│  │  - "全部" → token + notification + background + voip          │  │
│  │  - "通知消息和应用内通话" → notification + voip                         │  │
│  │  - ...任意合理组合                                             │  │
│  └──────────────────────────────────────────────────────────────┘  │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘
```

**询问示例**：

当开发者说"帮我在项目中接入华为推送服务"或类似模糊请求时，AI应该这样回应：

> "好的，我来帮您接入华为Push Kit推送服务。在开始之前，请告诉我您需要接入哪些推送场景？
> 
> Push Kit 支持三种场景化消息：
> - **通知消息**：发送消息提醒、弹窗通知，用户点击可打开应用
> - **后台消息**：数据静默更新，应用在后台接收消息后处理
> - **VoIP消息**：语音/视频来电提醒，需要申请VoIP权益
> 
> 请告诉我您需要哪些场景？例如：
> - "只要通知消息"
> - "通知+后台"
> - "全部都要"
> - 或者直接描述您的业务需求，我来帮您判断"

**路由规则**：

| 开发者需求 | 路由目标（按顺序加载） |
|-----------|----------------------|
| 通知 | notification |
| 后台 | background |
| VoIP/通话/来电 | voip |
| 通知+后台 | notification → background |
| 通知+VoIP | notification → voip |
| 后台+VoIP | background → voip |
| 全部/都要 | token → notification → background → voip |

**禁止行为**：
- ❌ 主Skill直接生成通知/后台/VoIP的具体实现代码
- ❌ 不询问开发者场景就直接生成部分代码
- ❌ 用主Skill中已有的描述片段代替子Skill的完整代码

## 核心设计理念

### Push Token 的核心地位

**所有推送服务的基础都是获取 Push Token**。无论选择哪种场景化消息（通知、通话、语音），都需要首先完成 Push Token 的获取。

**本 Skill 的设计原则**：
1. 每个场景化消息 Skill 都需要先检查开发者是否已正确获取 Push Token
2. 如果没有 Token 或不确定，需要引导开发者先完成 `hmos-push-kit-token` 场景
3. 这确保了开发者的推送集成工作从一开始就建立在正确的基础上


### 场景化消息流程

```
┌─────────────────────────────────────────────────────────────────────┐
│                         Master Skill (路由索引)                     │
├─────────────────────────────────────────────────────────────────────┤
│  开发者问询                                                         │
│     │                                                              │
│     ▼                                                              │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │ 1. 解析开发者需求 → 确定需要哪些场景化消息 Skill               │  │
│  └──────────────────────────────────────────────────────────────┘  │
│                              │                                      │
│                              ▼                                      │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │ 2. 按需加载一个或多个子 Skill                                 │  │
│  │    （每个子Skill自行处理Token检查和具体代码生成）              │  │
│  └──────────────────────────────────────────────────────────────┘  │
│                              │                                      │
│                              ▼                                      │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │ 3. 子Skill依次执行，完成对应场景的开发                         │  │
│  └──────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘
```

## 快速导航

根据您的需求，选择相应的场景：

### 我想获取 Push Token
- **触发条件**：开发者首次集成推送、Token 获取失败、询问 Token 相关问题
- **跳转到**：`hmos-push-kit-token` Skill

### 我想发送通知消息
- **触发条件**：开发者要实现消息推送、通知功能、消息提醒
- **跳转到**：`hmos-push-kit-notification` Skill

### 我想发送应用内通话/voip消息
- **触发条件**：开发者要实现 voip、来电提醒、视频通话功能
- **跳转到**：`hmos-push-kit-voip` Skill

### 我想发送后台消息
- **触发条件**：开发者要实现数据静默更新、离线缓存功能
- **跳转到**：`hmos-push-kit-background` Skill

### 我需要接入多个场景
- **触发条件**：开发者说"帮接入推送"、"接入华为推送服务"等未明确场景
- **处理方式**：主动询问具体场景 → 根据回答路由到对应子Skill组合
- **重要**：主Skill不生成具体代码，必须路由到子Skill



## 场景化消息权益说明

Push Kit 支持多种场景化消息权益，部分需要申请才能使用：

| 权益名称 | 说明 | 每日推送限制 | 提醒方式 |
|---------|------|------------|---------|
| 即时聊天（IM） | 社交通讯类消息 | 无限制 | 锁屏+铃声+振动 |
| 音视频通话（voip） | 来电通知 | 无限制 | 锁屏+铃声+振动 |
| 出行提醒（TRAVEL） | 出行相关通知 | 无限制 | 锁屏+铃声+振动 |
| 健康数据（HEALTH） | 健康运动通知 | 无限制 | 锁屏+铃声+振动 |
| 工作事项（WORK） | 工作任务提醒 | 无限制 | 锁屏+铃声+振动 |
| 资讯营销（默认） | 活动和内容推荐 | 2-5条/设备/日 | 静默通知 |

> **重要提示**：未申请自分类权益的应用，默认推送的都是资讯营销类消息，会受到"每日每设备 2-5 条"的严格限制！

## 开发流程总览

### Step 1: 开通推送服务（必须）

推送服务需要在 AppGallery Connect 中开通才能使用。这是获取有效 Push Token 的前提。

**操作路径**：AppGallery Connect → 项目 → 应用 → 增长 → 推送服务 → 立即开通

### Step 2: 配置应用签名（必须）

签名配置决定应用能否正常获取 Push Token：
- **调试阶段**：使用调试证书 + 调试 Profile
- **发布阶段**：使用发布证书 + 发布 Profile
- **自动签名**：DevEco Studio 6.0.0+ 支持自动配置

### Step 3: 获取 Push Token（必须）

所有推送的起点，在应用启动时调用 `getToken()`。

### Step 4: 申请场景化消息权益（推荐）

申请对应类型的自分类权益，可以突破每日推送数量限制。

### Step 5: 开发具体功能

根据业务需求，选择对应的场景化消息类型进行开发。

## 常见问题快速排查

| 问题现象 | 可能原因 | 解决方案 |
|---------|---------|---------|
| `getToken()` 返回错误码 1000900010 | 推送服务未开通或签名问题 | 检查推送服务是否开通，重新申请 Profile |
| 收不到推送消息 | Token 过期或签名问题 | 重新获取 Token，检查签名配置 |
| Token 一直获取失败 | 调试设备未注册 | 注册调试设备 |
| 每日推送数量受限 | 未申请自分类权益 | 申请通知消息自分类权益 |
| 推送数量被频控 | 测试阶段未使用 testMessage 参数 | 设置 testMessage 为 true 进行测试 |

## 参考文档

详细配置说明请参考华为官方文档：

### 官方文档链接

| 文档 | 链接 |
|------|------|
| Push Kit 简介 | https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/push-kit-introduction |
| 使用入门 | https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/push-gettingstart |
| 开发准备 | https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/push-preparations |
| 获取Push Token | https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/push-get-token |
| 推送场景化消息 | https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/push-scenes |
| 发送通知消息 | https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/push-send-alert |
| 推送应用内通话消息(voip) | https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hmos-push-kit-voip |
| 端云调试 | https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/push-server |
| 申请推送场景化消息权益 | https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/push-apply-right |

### 本地参考文档

- `references/push-error-codes.md` - Push Kit 错误码速查（快速定位问题）
- `references/push-guide.md` - 推送服务配置完整指南
- `references/push-api.md` - Push Kit API 参考
- `references/push-templates.md` - 完整源代码模板

## 代码生成规则

生成代码时必须遵循：
1. 使用正确的导入路径：`@kit.PushKit`、`@kit.BasicServicesKit` 等
2. 所有 ArkTS 类型注解必须正确
3. 使用 Promise 处理异步操作
4. 添加适当的错误处理
5. 使用 `hilog` 模块记录日志
6. 生成的代码必须能够直接编译通过
7. 遵守 HarmonyOS 应用开发规范