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
- 最近更新
- 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 的设计原则:
- 每个场景化消息 Skill 都需要先检查开发者是否已正确获取 Push Token
- 如果没有 Token 或不确定,需要引导开发者先完成
hmos-push-kit-token场景 - 这确保了开发者的推送集成工作从一开始就建立在正确的基础上
场景化消息流程
┌─────────────────────────────────────────────────────────────────────┐
│ Master Skill (路由索引) │
├─────────────────────────────────────────────────────────────────────┤
│ 开发者问询 │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ 1. 解析开发者需求 → 确定需要哪些场景化消息 Skill │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ 2. 按需加载一个或多个子 Skill │ │
│ │ (每个子Skill自行处理Token检查和具体代码生成) │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ 3. 子Skill依次执行,完成对应场景的开发 │ │
│ └──────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
快速导航
根据您的需求,选择相应的场景:
我想获取 Push Token
- 触发条件:开发者首次集成推送、Token 获取失败、询问 Token 相关问题
- 跳转到:
hmos-push-kit-tokenSkill
我想发送通知消息
- 触发条件:开发者要实现消息推送、通知功能、消息提醒
- 跳转到:
hmos-push-kit-notificationSkill
我想发送应用内通话/voip消息
- 触发条件:开发者要实现 voip、来电提醒、视频通话功能
- 跳转到:
hmos-push-kit-voipSkill
我想发送后台消息
- 触发条件:开发者要实现数据静默更新、离线缓存功能
- 跳转到:
hmos-push-kit-backgroundSkill
我需要接入多个场景
- 触发条件:开发者说"帮接入推送"、"接入华为推送服务"等未明确场景
- 处理方式:主动询问具体场景 → 根据回答路由到对应子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 进行测试 |
参考文档
详细配置说明请参考华为官方文档:
官方文档链接
本地参考文档
references/push-error-codes.md- Push Kit 错误码速查(快速定位问题)references/push-guide.md- 推送服务配置完整指南references/push-api.md- Push Kit API 参考references/push-templates.md- 完整源代码模板
代码生成规则
生成代码时必须遵循:
- 使用正确的导入路径:
@kit.PushKit、@kit.BasicServicesKit等 - 所有 ArkTS 类型注解必须正确
- 使用 Promise 处理异步操作
- 添加适当的错误处理
- 使用
hilog模块记录日志 - 生成的代码必须能够直接编译通过
- 遵守 HarmonyOS 应用开发规范
04 同仓库更多 Skills
writing-for-agents
为 agent 撰写文档。当创建或编辑 skill、修改 AGENTS.md 或 CLAUDE.md 时使用。
wait-what
停。上一条消息没讲明白:换个说法再讲一遍。
to-questionnaire
把你无法独自回答的决策转化成一份问卷,交给别人填写。
teach
在当前工作区内,教会用户一项新 skill 或概念。
handoff
把当前对话压缩成一份交接(handoff)文档,供另一个代理接手。
grilling
就一个计划、决策或想法对用户进行无情的访谈。当用户想压力测试自己的思路,或使用任何 'grill' 触发短语时使用。