AGENT SKILL

hmos-push-kit

华为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代码,没有语法错误。

License 许可
GPL-3.0
所属仓库
IsKenKenYa/skills
最近更新
2026-10-08
Stars
★ 3
Forks
0

01 前言 Front Matter

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代码,没有语法错误。

03 SKILL.md 正文

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 应用开发规范

04 同仓库更多 Skills