[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M75ZFAY754THAXD4P5SNJSY2":3,"skill-same:01M75ZFAY754THAXD4P5SNJSY2":46},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":30,"updatedAt":31,"install":32,"resources":45},"01M75ZFAY754THAXD4P5SNJSY2","hmos-push-kit-notification",null,"发送通知消息助手。当开发者需要实现推送通知功能、发送消息提醒、配置通知样式或点击动作时触发。\n\n============================================================\n触发条件（只有满足以下意图时才触发）：\n============================================================\n\n✅ 正确触发场景：\n- \"帮我在项目中接入推送通知\"\n- \"实现推送消息功能\"\n- \"添加推送消息功能\"\n- \"接入通知消息\"\n- \"发送通知消息\"\n- \"配置推送前台接收\"\n\n❌ 不触发场景：\n- 询问\u002F概念：\"通知消息是什么\"、\"推送有啥优点\"\n- 否定意图：\"不需要通知消息\"\n- 仅输入关键词：\"通知\"、\"推送消息\"\n- 测试\u002F调试：\"测试推送通知\"\n- 问题排查：\"推送失败\"、\"通知异常\"\n- 带引号输入：\"推送通知\"\n- 配置咨询：\"通知怎么配置\"\n\n此 Skill 专注于帮助开发者实现通知消息的发送和配置。\n\n前置检查：\n- 在继续之前，会自动检查开发者是否已接入Push Token\n- 如果未接入Token，会引导开发者先使用 hmos-push-kit-token Skill","IsKenKenYa\u002Fskills","IsKenKenYa","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F92219680?v=4","01M75Z8AFJBVH1Y9JJWRT35P0Z","是小啃啃呀","01M75Z8AG6RVC5RF6KTJQ7PQKQ",3,"GPL-3.0","https:\u002F\u002Fgithub.com\u002FIsKenKenYa\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fharmonyos\u002Fdevelopment\u002Fpush-kit\u002Fhmos-push-kit\u002Fhmos-push-kit-notification\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: hmos-push-kit-notification\ndescription: |\n  发送通知消息助手。当开发者需要实现推送通知功能、发送消息提醒、配置通知样式或点击动作时触发。\n  \n  ============================================================\n  触发条件（只有满足以下意图时才触发）：\n  ============================================================\n  \n  ✅ 正确触发场景：\n  - \"帮我在项目中接入推送通知\"\n  - \"实现推送消息功能\"\n  - \"添加推送消息功能\"\n  - \"接入通知消息\"\n  - \"发送通知消息\"\n  - \"配置推送前台接收\"\n  \n  ❌ 不触发场景：\n  - 询问\u002F概念：\"通知消息是什么\"、\"推送有啥优点\"\n  - 否定意图：\"不需要通知消息\"\n  - 仅输入关键词：\"通知\"、\"推送消息\"\n  - 测试\u002F调试：\"测试推送通知\"\n  - 问题排查：\"推送失败\"、\"通知异常\"\n  - 带引号输入：\"推送通知\"\n  - 配置咨询：\"通知怎么配置\"\n\n  此 Skill 专注于帮助开发者实现通知消息的发送和配置。\n  \n  前置检查：\n  - 在继续之前，会自动检查开发者是否已接入Push Token\n  - 如果未接入Token，会引导开发者先使用 hmos-push-kit-token Skill\n---\n\n# 发送通知消息助手\n\n本 Skill 帮助开发者实现华为推送通知功能。在开始发送通知消息开发之前，需要先确认 Push Token 的状态。\n\n---\n\n## ⚠️ AI 必做检查清单（强制检查）\n\n> **AI 必须在开始开发前逐一确认以下所有项目，确保不遗漏任何关键步骤！**\n\n### 接入通知消息必须完成的文件清单：\n\n| 序号 | 必做项 | 文件路径 | 用途 |\n|-----|-------|---------|-----|\n| ☐ 1 | 请求通知授权 | EntryAbility.ets 中调用 `requestEnableNotification()` | **用户点击\"允许\"后才能收到通知** ⭐ |\n| ☐ 2 | 配置 skills（点击首页） | `src\u002Fmain\u002Fmodule.json5` | 配置 entity.system.home + ohos.want.action.home |\n| ☐ 3 | 配置 action.ohos.push.listener | `src\u002Fmain\u002Fmodule.json5` | **用于接收前台通知消息** ⭐ |\n| ☐ 4 | 创建 PushMessageAbility | `src\u002Fmain\u002Fets\u002Fabilities\u002FPushMessageAbility.ets` | **调用 receiveMessage('DEFAULT', ...) 接收前台消息** ⭐ |\n| ☐ 5 | 确认已开通推送服务 | AppGallery Connect | ⭐必须已开通 |\n| ☐ 6 | 申请消息自分类权益（如需） | AppGallery Connect | 申请 IM\u002FVOIP\u002FTRAVEL\u002FHEALTH\u002FWORK 分类 |\n\n> **⚠️ 默认配置说明**：接入通知消息时，前台消息接收是**默认必须**配置的。原因是：\n> - 应用在前台时，如果设置 `foregroundShow: true`，通知会在通知栏显示，可能影响用户体验\n> - 通过配置 `action.ohos.push.listener` 并设置 `foregroundShow: false`，可以在前台静默接收消息\n> - **因此，接入通知消息时，前台接收功能是默认必须配置的**\n>\n> **特别注意**：\n> - `requestEnableNotification()` **必须**放在 `onWindowStageCreate()` 的 `loadContent` 回调中调用，不能放在 `onCreate()` 中！\n\n---\n\n## Token 接入检测与处理流程\n\n### 第一步：AI 自动检测（默认执行）\n\nAI 首先自动检查项目中是否已经接入了 Push Token：\n\n**检测内容**：\n1. 搜索项目中是否引入了 `@kit.PushKit`\n2. 搜索是否调用了 `pushService.getToken()`\n3. 检查是否在 `onCreate()` 生命周期中获取 Token\n4. 检查是否有将 Token 上报到服务器的逻辑\n\n### 第二步：根据检测结果处理\n\n| 检测结果 | 处理方式 |\n|---------|---------|\n| ✅ **已接入 Token** | 直接进入通知消息开发流程 |\n| ❌ **未接入 Token** | **参考 token skill 代码，直接帮开发者接入** |\n\n### 第三步：未接入 Token 时直接接入（参考 hmos-push-kit-token Skill 的代码）\n\n**当 AI 确定项目未接入 Token 时，参考 token skill 的标准代码帮开发者接入**：\n\n**参考以下代码模板，将相关 import 和方法添加到 EntryAbility.ets 中**：\n\n```typescript\nimport { pushService } from '@kit.PushKit';\nimport { hilog } from '@kit.PerformanceAnalysisKit';\nimport { BusinessError } from '@kit.BasicServicesKit';\n\u002F\u002F 其他 import 如果已有则不需要重复添加\n\nexport default class EntryAbility extends UIAbility {\n  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {\n    \u002F\u002F 将 getToken 调用添加到现有 onCreate 逻辑中\n    pushService.getToken().then((token: string) => {\n      hilog.info(0x0000, 'testTag', 'Succeeded in getting push token');\n      this.reportTokenToServer(token);\n    }).catch((err: BusinessError) => {\n      hilog.error(0x0000, 'testTag', 'Failed to get push token: %{public}d %{public}s', err.code, err.message);\n    });\n  }\n\n  \u002F\u002F 如果已有此方法，需要合并 Token 上报逻辑\n  reportTokenToServer(token: string): void {\n    hilog.info(0x0000, 'testTag', 'Reporting token to server');\n    \u002F\u002F TODO: 将 Token 上报到您的服务器（必需步骤）\n  }\n}\n```\n\n**⚠️ 重要**：\n- 保持原有代码不变，只添加 Token 相关逻辑\n- 合并到现有 onCreate 和 reportTokenToServer 中\n\n**说明提醒事项**：\n- 告知开发者必须将 Token 上报到服务器\n- 服务器需要保存 Token 才能向设备发送推送\n\n**完成 Token 接入后**：继续执行通知消息开发流程\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│            未接入 Token 时的处理流程                                  │\n├─────────────────────────────────────────────────────────────────────┤\n│                                                                     │\n│  1. AI 自动检测到项目未接入 Token                                    │\n│                                                                     │\n│  2. ⭐ 参考 hmos-push-kit-token Skill 的代码                        │\n│     - 添加缺失的 import                                            │\n│     - 将 getToken 调用合并到现有 onCreate 中                        │\n│     - 合并或添加 reportTokenToServer() 方法                         │\n│                                                                     │\n│  3. 接入完成后，自动继续通知消息开发                                  │\n│     - 配置 requestEnableNotification                                │\n│     - 创建 PushMessageAbility                                       │\n│     - 配置 skills 等                                                │\n│                                                                     │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n> **说明**：AI 不再需要切换到 hmos-push-kit-token Skill，而是直接在本 Skill 中完成 Token 接入，然后再继续通知消息的开发。\n\n---\n\n## 通知消息开发步骤\n\n当确认有有效 Token 后，按照以下步骤开发通知消息：\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                    通知消息开发流程                                   │\n├─────────────────────────────────────────────────────────────────────┤\n│                                                                     │\n│  Step 1: 请求用户通知授权 ⭐必做                                      │\n│     └── 在 EntryAbility 的 onWindowStageCreate() 中调用             │\n│     └── requestEnableNotification() 在 loadContent 回调中          │\n│                                                                     │\n│  Step 2: 配置 skills 点击首页 ⭐必做                                 │\n│     └── 配置 entity.system.home + ohos.want.action.home            │\n│                                                                     │\n│  Step 3: 配置 action.ohos.push.listener ⭐必做                      │\n│     └── 在 module.json5 中添加该 action                             │\n│     └── 用于前台静默接收通知消息                                      │\n│                                                                     │\n│  Step 4: 创建 PushMessageAbility ⭐必做                             │\n│     └── 调用 pushService.receiveMessage('DEFAULT', ...)            │\n│     └── 在 onCreate() 中同步调用接收消息                             │\n│                                                                     │\n│  Step 5: 开通推送服务和申请权益                                       │\n│     └── 在 AppGallery Connect 完成                                  │\n│                                                                     │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Step 1: 请求用户通知授权 ⭐必做\n\n### 为什么要请求通知授权？\n\n根据 HarmonyOS 规范，应用在发送通知前需要获得用户的明确同意。这是系统级别的安全要求。\n\n```\n⚠️ 重要提示：\n- 应用在发送任何通知之前必须先获取用户授权\n- 如果未获取授权，通知消息将无法正常显示\n- 建议在应用首次启动时请求授权，并保存授权状态\n```\n\n### 生成请求通知授权代码\n\n> **⚠️ 重要：`requestEnableNotification()` 必须放在 `onWindowStageCreate()` 中调用！**\n\n**原因**：\n- 必须等页面加载完成后再弹出权限授权对话框\n- 如果在 `onCreate()` 中调用，页面还未加载，用户体验不好\n- 系统要求在页面渲染完成后再请求通知权限\n\n**代码位置**：`src\u002Fmain\u002Fets\u002Fentryability\u002FEntryAbility.ets`\n\n```typescript\nimport { BusinessError } from '@kit.BasicServicesKit';\nimport { UIAbility } from '@kit.AbilityKit';\nimport { window } from '@kit.ArkUI';\nimport { hilog } from '@kit.PerformanceAnalysisKit';\nimport { notificationManager } from '@kit.NotificationKit';\n\nexport default class EntryAbility extends UIAbility {\n  onWindowStageCreate(windowStage: window.WindowStage): void {\n    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');\n    windowStage.loadContent('pages\u002FIndex', (err, data) => {\n      if (err.code) {\n        hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');\n        return;\n      }\n      hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');\n      \n      \u002F\u002F ✅ 重要：必须在页面加载完成后再请求通知权限\n      \u002F\u002F 放在 loadContent 的回调中，确保页面渲染完成后再弹出授权对话框\n      notificationManager.requestEnableNotification(this.context).then(() => {\n        hilog.info(0x0000, 'testTag', `[ANS] requestEnableNotification success`);\n      }).catch((err: BusinessError) => {\n        hilog.error(0x0000, 'testTag',\n          `[ANS] requestEnableNotification failed, code is ${err.code}, message is ${err.message}`);\n      });\n    });\n  }\n}\n```\n\n> **参考**：华为官方文档 - [发送通知消息](https:\u002F\u002Fdeveloper.huawei.com\u002Fconsumer\u002Fcn\u002Fdoc\u002Fharmonyos-guides\u002Fpush-send-alert)\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                        ⚠️ 放置位置注意                               │\n├─────────────────────────────────────────────────────────────────────┤\n│                                                                     │\n│  ❌ 不要放在 onCreate() 中                                         │\n│  ✅ 必须放在 onWindowStageCreate() 中，且在 loadContent 回调中调用 │\n│                                                                     │\n│  原因：                                                              │\n│  1. onCreate() 时页面尚未加载完成                                    │\n│  2. 用户看到空白页面突然弹出授权对话框，体验极差                      │\n│  3. 系统要求页面渲染完成后再请求权限                                  │\n│                                                                     │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Step 2: 配置 Skills - 点击通知进入应用首页 ⭐必做\n\n### 为什么要配置 Skills？\n\nSkills 标签定义了应用能够处理的消息类型和跳转路径。当用户点击通知消息时，系统需要知道：\n1. 点击后应该打开哪个页面\n2. 页面应该显示什么内容\n\n根据华为官方文档，点击通知消息有两种跳转场景，需要配置不同的 skills：\n\n---\n\n### 场景一：点击通知进入应用首页\n\n**服务端设置**：`actionType: 0`\n\n**module.json5 配置**：\n```json5\n{\n  \"module\": {\n    \u002F\u002F ...\n    \"abilities\": [\n      {\n        \"name\": \"TestAbility\",\n        \"srcEntry\": \".\u002Fets\u002Fabilities\u002FTestAbility.ets\",\n        \"exported\": false,\n        \"startWindowIcon\": \"$media:startIcon\",\n        \"startWindowBackground\": \"$color:start_window_background\",\n        \"skills\": [\n          \u002F\u002F 该skill标识应用首页，不要配置uris\n          {\n            \"entities\": [\n              \"entity.system.home\"\n            ],\n            \"actions\": [\n              \u002F\u002F \"action.system.home\"为API19以下版本配置，已废弃\n              \"ohos.want.action.home\"\n            ]\n          },\n          \u002F\u002F 其他skill配置\n          {}\n        ]\n      }\n    ]\n  }\n}\n```\n\n**关键点**：\n- `entities` 设置为 `entity.system.home`\n- `actions` 设置为 `ohos.want.action.home`\n- **不要配置 uris**，否则消息会接收不到\n\n---\n\n## Step 3: 配置 Skills - 点击通知进入应用内页（可选）\n\n### 场景二：点击通知进入应用内页\n\n**服务端设置**：`actionType: 1`\n\n有两种配置方式：\n\n**方式一：配置 actions 参数（推荐）**\n\n```json5\n{\n  \"name\": \"TestAbility\",\n  \"srcEntry\": \".\u002Fets\u002Fabilities\u002FTestAbility.ets\",\n  \"exported\": false,\n  \"startWindowIcon\": \"$media:startIcon\",\n  \"startWindowBackground\": \"$color:start_window_background\",\n  \"skills\": [\n    \u002F\u002F 保持现有skill对象不变\n    {\n      \"actions\": [\n        \"com.app.action\"\n      ]\n    },\n    \u002F\u002F 新增一个独立的skill对象，配置actions参数\n    {\n      \"actions\": [\n        \"com.test.action\"\n      ]\n    }\n  ]\n}\n```\n\n**方式二：配置 uris 参数**\n\n```json5\n{\n  \"name\": \"TestAbility\",\n  \"srcEntry\": \".\u002Fets\u002Fabilities\u002FTestAbility.ets\",\n  \"exported\": false,\n  \"startWindowIcon\": \"$media:startIcon\",\n  \"startWindowBackground\": \"$color:start_window_background\",\n  \"skills\": [\n    \u002F\u002F 保持现有skill对象不变\n    {\n      \"actions\": [\n        \"com.app.action\"\n      ]\n    },\n    \u002F\u002F 新增一个独立的skill对象，配置uris参数，且必须同时配置actions参数，actions参数为空字符串\n    {\n      \"actions\": [\"\"],\n      \"uris\": [\n        {\n          \"scheme\": \"https\",\n          \"host\": \"www.xxx.com\",\n          \"port\": \"8080\",\n          \"path\": \"push\u002Ftest\"\n        }\n      ]\n    }\n  ]\n}\n```\n\n> **参考**：华为官方文档 - [点击消息动作](https:\u002F\u002Fdeveloper.huawei.com\u002Fconsumer\u002Fcn\u002Fdoc\u002Fharmonyos-guides\u002Fpush-send-alert#点击消息动作)\n\n---\n\n## Step 4: 配置 action.ohos.push.listener ⭐必做\n\n### 前台消息处理说明\n\n> **⚠️ 默认配置**：本 Skill 默认配置前台消息接收。需要在服务端设置 `foregroundShow` 为 `false`，这样应用在前台时可以静默接收消息而不展示通知栏。\n\n**服务端设置**：\n\n```json\n{\n  \"payload\": {\n    \"notification\": {\n      \"category\": \"IM\",\n      \"title\": \"您有新消息\",\n      \"body\": \"来自朋友的消息\",\n      \"foregroundShow\": false\n    }\n  },\n  \"target\": {\n    \"token\": [\"MAMzLg**********lPW\"]\n  }\n}\n```\n\n**参数说明**：\n- `foregroundShow: true`（默认）：前后台都展示通知\n- `foregroundShow: false`：仅在后台展示通知，前台不展示但可接收消息\n\n---\n\n## Step 5: 创建 PushMessageAbility 接收前台消息 ⭐必做\n\n### 配置 module.json5\n\n需要在 abilities 中配置 skills，用于接收前台通知消息：\n\n```json5\n{\n  \"name\": \"PushMessageAbility\",\n  \"srcEntry\": \".\u002Fets\u002Fabilities\u002FPushMessageAbility.ets\",\n  \"launchType\": \"singleton\",\n  \"startWindowIcon\": \"$media:startIcon\",\n  \"startWindowBackground\": \"$color:start_window_background\",\n  \"exported\": false,\n  \"skills\": [\n    \u002F\u002F 保持现有skill对象不变\n    {\n      \"actions\": [\n        \"com.app.action\"\n      ]\n    },\n    \u002F\u002F 新增一个独立的skill对象，配置actions参数\n    {\n      \"actions\": [\n        \"action.ohos.push.listener\"\n      ]\n    }\n  ]\n}\n```\n\n> **⚠️ 配置警告**：\n> - **label 字段**：默认**不要添加**！如果需要添加，必须使用 `$string:xxx` 格式，并在 `string.json` 中添加资源名\n> - **description 字段**：可以使用普通字符串，也可以不添加\n> - **⭐ startWindowIcon 和 startWindowBackground 字段**：**必须填写**，不能遗漏！\n>   - `startWindowIcon`：应用启动图标，如 `$media:startIcon`\n>   - `startWindowBackground`：启动背景色，如 `$color:start_window_background`\n>   - 如果遗漏会导致应用无法正常启动\n>\n> 错误示例（会编译报错）：\n> ```json5\n> {\n>   \"label\": \"PushMessageAbility\"  \u002F\u002F ❌ 错误！必须用 $string:xxx 格式\n> }\n> ```\n\n**关键点**：\n- `actions` 设置为 `action.ohos.push.listener`\n- `launchType` 设置为 `singleton`\n- **项目中只能有一个 ability 定义该 action**\n- **label 字段**：默认不添加，如果添加必须用 `$string:xxx` 格式\n- **description 字段**：可以使用普通字符串，也可以不添加\n\n### 创建消息接收 Ability\n\n**文件位置**：`src\u002Fmain\u002Fets\u002Fabilities\u002FPushMessageAbility.ets`\n\n```typescript\nimport { UIAbility } from '@kit.AbilityKit';\nimport { pushService } from '@kit.PushKit';\nimport { BusinessError } from '@kit.BasicServicesKit';\nimport { hilog } from '@kit.PerformanceAnalysisKit';\n\n\u002F**\n * 此处以PushMessageAbility为例，用于应用在前台时接收通知消息\n *\u002F\nexport default class PushMessageAbility extends UIAbility {\n  onCreate(): void {\n    try {\n      \u002F\u002F receiveMessage中的参数固定为DEFAULT\n      pushService.receiveMessage('DEFAULT', this, (payload) => {\n        try {\n          \u002F\u002F 获取服务端传递的数据\n          const data: string = payload.data;\n          \u002F\u002F TODO：业务自行处理\n          hilog.info(0x0000, 'testTag', 'Succeeded in getting notification,data=%{public}s',\n            JSON.stringify(JSON.parse(data)?.notification));\n        } catch (e) {\n          let errRes: BusinessError = e as BusinessError;\n          hilog.error(0x0000, 'testTag', 'Failed to process data: %{public}d %{public}s',\n            errRes.code, errRes.message);\n        }\n      });\n    } catch (err) {\n      let e: BusinessError = err as BusinessError;\n      hilog.error(0x0000, 'testTag', 'Failed to get message: %{public}d %{public}s', e.code,\n        e.message);\n    }\n  }\n}\n```\n\n**代码说明**：\n\n| 代码段 | 作用 |\n|-------|------|\n| `pushService.receiveMessage('DEFAULT', ...)` | 注册接收通知消息 |\n| `'DEFAULT'` | 固定值，表示通知消息类型 |\n| `payload.data` | 包含通知消息内容的 JSON 字符串 |\n\n> **⚠️ 重要**：\n> - UIAbility.onCreate 是同步接口，不支持异步回调\n> - `pushService.receiveMessage()` 必须在 onCreate 入口同步调用\n> - 不能在注册前等待异步方法执行\n\n> **参考**：华为官方文档 - [应用在前台时处理通知消息](https:\u002F\u002Fdeveloper.huawei.com\u002Fconsumer\u002Fcn\u002Fdoc\u002Fharmonyos-guides\u002Fpush-send-alert#应用在前台时处理通知消息)\n\n---\n\n## 服务端推送示例\n\n### 请求示例\n\n```json\n\u002F\u002F Request URL\nPOST \"https:\u002F\u002Fpush-api.cloud.huawei.com\u002Fv3\u002F[projectId]\u002Fmessages:send\"\n\n\u002F\u002F Request Header\n\"Content-Type\": application\u002Fjson\"\n\"Authorization: Bearer eyJr*****OiIx---****.eyJh*****iJodHR--***.QRod*****4Gp---****\"\n\"push-type: 0\"\n\n\u002F\u002F Request Body\n{\n  \"payload\": {\n    \"notification\": {\n      \"category\": \"IM\",\n      \"title\": \"通知标题\",\n      \"body\": \"通知内容\",\n      \"clickAction\": {\n        \"actionType\": 0\n      },\n      \"foregroundShow\": true,\n      \"notifyId\": 12345\n    }\n  },\n  \"target\": {\n    \"token\": [\"MAMzLg**********lPW\"]\n  },\n  \"pushOptions\": {\n    \"testMessage\": true,\n    \"ttl\": 86400\n  }\n}\n```\n\n### 参数说明\n\n| 参数 | 说明 |\n|-----|------|\n| push-type | 0 表示通知消息 |\n| category | 消息分类：IM\u002FVOIP\u002FTRAVEL\u002FHEALTH\u002FWORK\u002FMARKETING |\n| foregroundShow | 应用在前台时是否展示通知 |\n| notifyId | 消息ID，用于消息撤回 |\n| testMessage | 测试消息标识，绕过频控 |\n\n---\n\n## ⚠️ 重要：多个场景化消息的配置\n\n**如果您需要同时接入通知消息、voip、后台消息，必须注意以下事项**：\n\n根据华为官方文档，一个项目中**有且只能有一个 ability** 配置 `action.ohos.push.listener`。\n\n**这意味着**：\n- 不要为每种消息类型创建单独的 Ability\n- 所有的 `receiveMessage` 注册应该放在**同一个 Ability** 中\n- module.json5 中只配置一个 ability 包含 `action.ohos.push.listener`\n\n**⚠️ 特别提醒：接入 voip 或后台消息时，请加载对应的专门 Skill**\n\n虽然同一个 Ability 中可以注册多种消息类型，但 **每种消息类型都有各自完整的开发流程和注意事项**，不能互相替代：\n\n- **通知消息**：调用 `receiveMessage('DEFAULT', ...)`，配合 `requestEnableNotification()` 授权\n- **voip 消息**：调用 `receiveMessage('VoIP', ...)`，还需要创建 VoipCallService、CalleePage 页面、注册 voipCallUiEvent 事件、上报来电状态等完整流程\n- **后台消息**：调用 `receiveMessage('BACKGROUND', ...)`，还需要实现数据静默更新和缓存策略\n\n因此：\n- 接入 **voip 消息** → 请加载 **hmos-push-kit-voip** Skill\n- 接入**后台消息** → 请加载 **hmos-push-kit-background** Skill\n- **不要**仅凭本 skill 中关于\"同一 ability 接收多种消息类型\"的说明就自行编写 voip 或后台消息代码\n\n**⚠️ 示例：不能这样做**\n\n以下示例展示的是**错误做法**——仅凭 notification skill 的说明就自行添加 voip 代码：\n\n```typescript\n\u002F\u002F ❌ 错误示例：仅凭 notification skill 的说明就自行添加 voip 代码\npushService.receiveMessage('VoIP', this, (payload) => {\n  \u002F\u002F 没有创建 VoipCallService\n  \u002F\u002F 没有创建 CalleePage 页面\n  \u002F\u002F 没有注册 voipCallUiEvent 事件监听\n  \u002F\u002F 没有上报来电状态\n  \u002F\u002F voip 有完整独立的开发流程，必须参考专门的 voip skill\n});\n```\n\n**正确做法**：请明确告诉我\"需要接入 voip 消息\"，我会加载 voip skill，在本项目的同一个 PushMessageAbility 中添加 voip 接收逻辑。\n\n---\n\n## 代码生成规则\n\n生成代码时必须遵循：\n1. 使用正确的导入路径：`@kit.NotificationKit`、`@kit.BasicServicesKit`\n2. 所有 ArkTS 类型注解必须正确\n3. 添加适当的错误处理和日志记录\n4. 生成的代码必须能够直接编译通过\n5. 遵守 HarmonyOS 应用开发规范\n\n---\n\n## 常见问题排查\n\n| 问题 | 可能原因 | 解决方案 |\n|-----|---------|---------|\n| 通知不显示 | 未调用 requestEnableNotification() | 在 onWindowStageCreate() 的 loadContent 回调中调用 |\n| 前台收不到消息 | foregroundShow 未设置为 false | 服务端设置 `foregroundShow: false` |\n| 前台收不到消息 | skills 未配置正确 | 检查 module.json5 中 skills 是否包含 `action.ohos.push.listener` |\n| 收到多条消息 | 多个 ability 都配置了相同 action | 确保只有一个 ability 配置该 action |\n| 消息数据为空 | 未正确解析 JSON | 检查 payload.data 的解析方式 |\n| 每天只能发2-5条 | 未申请消息自分类权益 | 在 AppGallery Connect 申请 IM\u002FVOIP\u002FTRAVEL\u002FHEALTH\u002FWORK 分类 |\n\n---\n\n## 常见错误码\n\n接入通知消息后，如遇到以下错误码，请参考：\n\n| 错误码 | 可能原因 | 解决方法 |\n|-------|---------|---------|\n| 1000900010 | 推送服务未开通 | 在 AppGallery Connect 开通推送服务 |\n| 1000900011 | 应用签名不匹配 | 检查签名配置是否正确 |\n| 1000900012 | 网络问题 | 检查网络连接 |\n| 1000900013 | 请求超时 | 增加超时时间或检查网络 |\n| 1000900014 | 权限不足 | 检查 module.json5 权限配置 |\n| 1000900001 | 推送服务内部错误 | 重试或联系华为支持 |\n| 1000900002 | 参数错误 | 检查请求参数是否正确 |\n| 1000900003 | Token 无效 | 检查 Token 是否正确 |\n\n> 完整错误码列表请参考 `references\u002Fpush-error-codes.md`\n\n---\n\n## ✅ AI 开发完成后的自检清单\n\n> **AI 必须在完成通知消息接入开发后，逐项确认以下所有内容：**\n\n### 通知授权检查：\n- [ ] EntryAbility.ets 中已调用 `requestEnableNotification()` ⭐重点\n- [ ] 调用位置在 `onWindowStageCreate()` 的 `loadContent` 回调中 ⭐重点\n- [ ] **不是**在 `onCreate()` 中调用\n\n### Skills 配置检查：\n- [ ] 点击首页：skills 配置包含 `entity.system.home` + `ohos.want.action.home` ⭐重点\n- [ ] 前台接收：skills 配置包含 `action.ohos.push.listener` ⭐重点\n\n### PushMessageAbility 检查：\n- [ ] `src\u002Fmain\u002Fets\u002Fabilities\u002FPushMessageAbility.ets` 已创建 ⭐重点\n- [ ] `pushService.receiveMessage('DEFAULT', ...)` 已在 onCreate() 中同步调用 ⭐重点\n- [ ] ability 的 launchType 设置为 `singleton`\n\n### 权益检查：\n- [ ] 已在 AppGallery Connect 开通推送服务 ⭐\n- [ ] 已申请通知消息自分类权益（如需要发送 IM\u002FVOIP\u002FTRAVEL\u002FHEALTH\u002FWORK 类）\n\n### 服务端参数检查：\n- [ ] category 参数正确设置\n- [ ] foregroundShow 参数设置为 false（前台静默接收）⭐重点\n- [ ] actionType 参数正确设置（0=首页，1=内页）\n\n### module.json5 配置检查：\n- [ ] skills 配置正确（首页\u002F内页\u002F前台接收）\n- [ ] **label 字段**：默认不添加，如果添加必须用 `$string:xxx` 格式\n- [ ] description 字段：可以使用普通字符串，也可以不添加\n- [ ] 如果添加了 label，确认已在 `string.json` 中添加对应资源名\n\n---\n\n> **⚠️ 如果 AI 遗漏了上述任何一项（特别是 ⭐重点 标记的项目），请立即补充！**\n\n---\n\n## ⚠️ 重要提醒汇总\n\n> **⭐ 接入通知消息完成后，请务必逐项完成以下所有提醒事项！**\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│       ⭐ 重要：接入通知消息后必须完成的权益申请和Token上报            │\n├─────────────────────────────────────────────────────────────────────┤\n│                                                                     │\n│  【权益申请 - 必须完成】⭐                                            │\n│                                                                     │\n│  1. 开通推送服务（必须）⭐                                            │\n│     您必须前往 AppGallery Connect 开通推送服务，否则无法获取有效 Token │\n│     参考文档：                                                       │\n│     https:\u002F\u002Fdeveloper.huawei.com\u002Fconsumer\u002Fcn\u002Fdoc\u002Fharmonyos-guides\u002Fpush-config-setting  │\n│                                                                     │\n│  2. 申请消息自分类权益（如需发送 IM\u002FVOIP\u002FTRAVEL\u002FHEALTH\u002FWORK）⭐       │\n│     未申请时默认为「资讯营销类」消息，会受到「每日每设备 2-5 条」限制  │\n│     参考文档：                                                       │\n│     https:\u002F\u002Fdeveloper.huawei.com\u002Fconsumer\u002Fcn\u002Fdoc\u002Fharmonyos-guides\u002Fpush-apply-right  │\n│                                                                     │\n│  ───────────────────────────────────────────────────────────────    │\n│                                                                     │\n│  【Token 上报 - 必须完成】⭐                                          │\n│                                                                     │\n│  ⚠️ 如果本次接入过程中，因项目未接入Token而自动帮您接入了Token，       │\n│     您必须完成以下工作：                                              │\n│                                                                     │\n│  在本次接入过程中，AI 已自动将 `getToken()` 调用添加到您的项目中。    │\n│  但是 `reportTokenToServer()` 方法中的上报逻辑尚未完成！              │\n│                                                                     │\n│  您必须实现 Token 上报到服务器的逻辑：                                │\n│                                                                     │\n│  ```typescript                                                      │\n│  reportTokenToServer(token: string): void {                         │\n│    hilog.info(0x0000, 'testTag', 'Reporting token to server: %{public}s', token);    │\n│    \u002F\u002F TODO: 将 Token 上报到您的服务器（必需步骤）                      │\n│  }                                                                   │\n│  ```                                                                 │\n│                                                                     │\n│  ⚠️ 重要提示：完成 Token 上报后，您的推送功能才能真正工作！            │\n│                                                                     │\n│  ───────────────────────────────────────────────────────────────    │\n│                                                                     │\n│  【频控规则】                                                        │\n│  • 调测阶段：每个项目每日全网最多可推送1000条测试消息，                 │\n│    发送测试消息需设置testMessage为true                                │\n│  • 正式发布阶段：单设备单应用下每日推送消息总条数受设备消息频控限制     │\n│                                                                     │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n> **⚠️ 请务必完成上述所有提醒事项，遗漏任何一项都可能导致推送功能无法正常工作！**\n","# 发送通知消息助手\n\n本 Skill 帮助开发者实现华为推送通知功能。在开始发送通知消息开发之前，需要先确认 Push Token 的状态。\n\n---\n\n## ⚠️ AI 必做检查清单（强制检查）\n\n> **AI 必须在开始开发前逐一确认以下所有项目，确保不遗漏任何关键步骤！**\n\n### 接入通知消息必须完成的文件清单：\n\n| 序号 | 必做项 | 文件路径 | 用途 |\n|-----|-------|---------|-----|\n| ☐ 1 | 请求通知授权 | EntryAbility.ets 中调用 `requestEnableNotification()` | **用户点击\"允许\"后才能收到通知** ⭐ |\n| ☐ 2 | 配置 skills（点击首页） | `src\u002Fmain\u002Fmodule.json5` | 配置 entity.system.home + ohos.want.action.home |\n| ☐ 3 | 配置 action.ohos.push.listener | `src\u002Fmain\u002Fmodule.json5` | **用于接收前台通知消息** ⭐ |\n| ☐ 4 | 创建 PushMessageAbility | `src\u002Fmain\u002Fets\u002Fabilities\u002FPushMessageAbility.ets` | **调用 receiveMessage('DEFAULT', ...) 接收前台消息** ⭐ |\n| ☐ 5 | 确认已开通推送服务 | AppGallery Connect | ⭐必须已开通 |\n| ☐ 6 | 申请消息自分类权益（如需） | AppGallery Connect | 申请 IM\u002FVOIP\u002FTRAVEL\u002FHEALTH\u002FWORK 分类 |\n\n> **⚠️ 默认配置说明**：接入通知消息时，前台消息接收是**默认必须**配置的。原因是：\n> - 应用在前台时，如果设置 `foregroundShow: true`，通知会在通知栏显示，可能影响用户体验\n> - 通过配置 `action.ohos.push.listener` 并设置 `foregroundShow: false`，可以在前台静默接收消息\n> - **因此，接入通知消息时，前台接收功能是默认必须配置的**\n>\n> **特别注意**：\n> - `requestEnableNotification()` **必须**放在 `onWindowStageCreate()` 的 `loadContent` 回调中调用，不能放在 `onCreate()` 中！\n\n---\n\n## Token 接入检测与处理流程\n\n### 第一步：AI 自动检测（默认执行）\n\nAI 首先自动检查项目中是否已经接入了 Push Token：\n\n**检测内容**：\n1. 搜索项目中是否引入了 `@kit.PushKit`\n2. 搜索是否调用了 `pushService.getToken()`\n3. 检查是否在 `onCreate()` 生命周期中获取 Token\n4. 检查是否有将 Token 上报到服务器的逻辑\n\n### 第二步：根据检测结果处理\n\n| 检测结果 | 处理方式 |\n|---------|---------|\n| ✅ **已接入 Token** | 直接进入通知消息开发流程 |\n| ❌ **未接入 Token** | **参考 token skill 代码，直接帮开发者接入** |\n\n### 第三步：未接入 Token 时直接接入（参考 hmos-push-kit-token Skill 的代码）\n\n**当 AI 确定项目未接入 Token 时，参考 token skill 的标准代码帮开发者接入**：\n\n**参考以下代码模板，将相关 import 和方法添加到 EntryAbility.ets 中**：\n\n```typescript\nimport { pushService } from '@kit.PushKit';\nimport { hilog } from '@kit.PerformanceAnalysisKit';\nimport { BusinessError } from '@kit.BasicServicesKit';\n\u002F\u002F 其他 import 如果已有则不需要重复添加\n\nexport default class EntryAbility extends UIAbility {\n  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {\n    \u002F\u002F 将 getToken 调用添加到现有 onCreate 逻辑中\n    pushService.getToken().then((token: string) => {\n      hilog.info(0x0000, 'testTag', 'Succeeded in getting push token');\n      this.reportTokenToServer(token);\n    }).catch((err: BusinessError) => {\n      hilog.error(0x0000, 'testTag', 'Failed to get push token: %{public}d %{public}s', err.code, err.message);\n    });\n  }\n\n  \u002F\u002F 如果已有此方法，需要合并 Token 上报逻辑\n  reportTokenToServer(token: string): void {\n    hilog.info(0x0000, 'testTag', 'Reporting token to server');\n    \u002F\u002F TODO: 将 Token 上报到您的服务器（必需步骤）\n  }\n}\n```\n\n**⚠️ 重要**：\n- 保持原有代码不变，只添加 Token 相关逻辑\n- 合并到现有 onCreate 和 reportTokenToServer 中\n\n**说明提醒事项**：\n- 告知开发者必须将 Token 上报到服务器\n- 服务器需要保存 Token 才能向设备发送推送\n\n**完成 Token 接入后**：继续执行通知消息开发流程\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│            未接入 Token 时的处理流程                                  │\n├─────────────────────────────────────────────────────────────────────┤\n│                                                                     │\n│  1. AI 自动检测到项目未接入 Token                                    │\n│                                                                     │\n│  2. ⭐ 参考 hmos-push-kit-token Skill 的代码                        │\n│     - 添加缺失的 import                                            │\n│     - 将 getToken 调用合并到现有 onCreate 中                        │\n│     - 合并或添加 reportTokenToServer() 方法                         │\n│                                                                     │\n│  3. 接入完成后，自动继续通知消息开发                                  │\n│     - 配置 requestEnableNotification                                │\n│     - 创建 PushMessageAbility                                       │\n│     - 配置 skills 等                                                │\n│                                                                     │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n> **说明**：AI 不再需要切换到 hmos-push-kit-token Skill，而是直接在本 Skill 中完成 Token 接入，然后再继续通知消息的开发。\n\n---\n\n## 通知消息开发步骤\n\n当确认有有效 Token 后，按照以下步骤开发通知消息：\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                    通知消息开发流程                                   │\n├─────────────────────────────────────────────────────────────────────┤\n│                                                                     │\n│  Step 1: 请求用户通知授权 ⭐必做                                      │\n│     └── 在 EntryAbility 的 onWindowStageCreate() 中调用             │\n│     └── requestEnableNotification() 在 loadContent 回调中          │\n│                                                                     │\n│  Step 2: 配置 skills 点击首页 ⭐必做                                 │\n│     └── 配置 entity.system.home + ohos.want.action.home            │\n│                                                                     │\n│  Step 3: 配置 action.ohos.push.listener ⭐必做                      │\n│     └── 在 module.json5 中添加该 action                             │\n│     └── 用于前台静默接收通知消息                                      │\n│                                                                     │\n│  Step 4: 创建 PushMessageAbility ⭐必做                             │\n│     └── 调用 pushService.receiveMessage('DEFAULT', ...)            │\n│     └── 在 onCreate() 中同步调用接收消息                             │\n│                                                                     │\n│  Step 5: 开通推送服务和申请权益                                       │\n│     └── 在 AppGallery Connect 完成                                  │\n│                                                                     │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Step 1: 请求用户通知授权 ⭐必做\n\n### 为什么要请求通知授权？\n\n根据 HarmonyOS 规范，应用在发送通知前需要获得用户的明确同意。这是系统级别的安全要求。\n\n```\n⚠️ 重要提示：\n- 应用在发送任何通知之前必须先获取用户授权\n- 如果未获取授权，通知消息将无法正常显示\n- 建议在应用首次启动时请求授权，并保存授权状态\n```\n\n### 生成请求通知授权代码\n\n> **⚠️ 重要：`requestEnableNotification()` 必须放在 `onWindowStageCreate()` 中调用！**\n\n**原因**：\n- 必须等页面加载完成后再弹出权限授权对话框\n- 如果在 `onCreate()` 中调用，页面还未加载，用户体验不好\n- 系统要求在页面渲染完成后再请求通知权限\n\n**代码位置**：`src\u002Fmain\u002Fets\u002Fentryability\u002FEntryAbility.ets`\n\n```typescript\nimport { BusinessError } from '@kit.BasicServicesKit';\nimport { UIAbility } from '@kit.AbilityKit';\nimport { window } from '@kit.ArkUI';\nimport { hilog } from '@kit.PerformanceAnalysisKit';\nimport { notificationManager } from '@kit.NotificationKit';\n\nexport default class EntryAbility extends UIAbility {\n  onWindowStageCreate(windowStage: window.WindowStage): void {\n    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');\n    windowStage.loadContent('pages\u002FIndex', (err, data) => {\n      if (err.code) {\n        hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');\n        return;\n      }\n      hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');\n      \n      \u002F\u002F ✅ 重要：必须在页面加载完成后再请求通知权限\n      \u002F\u002F 放在 loadContent 的回调中，确保页面渲染完成后再弹出授权对话框\n      notificationManager.requestEnableNotification(this.context).then(() => {\n        hilog.info(0x0000, 'testTag', `[ANS] requestEnableNotification success`);\n      }).catch((err: BusinessError) => {\n        hilog.error(0x0000, 'testTag',\n          `[ANS] requestEnableNotification failed, code is ${err.code}, message is ${err.message}`);\n      });\n    });\n  }\n}\n```\n\n> **参考**：华为官方文档 - [发送通知消息](https:\u002F\u002Fdeveloper.huawei.com\u002Fconsumer\u002Fcn\u002Fdoc\u002Fharmonyos-guides\u002Fpush-send-alert)\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                        ⚠️ 放置位置注意                               │\n├─────────────────────────────────────────────────────────────────────┤\n│                                                                     │\n│  ❌ 不要放在 onCreate() 中                                         │\n│  ✅ 必须放在 onWindowStageCreate() 中，且在 loadContent 回调中调用 │\n│                                                                     │\n│  原因：                                                              │\n│  1. onCreate() 时页面尚未加载完成                                    │\n│  2. 用户看到空白页面突然弹出授权对话框，体验极差                      │\n│  3. 系统要求页面渲染完成后再请求权限                                  │\n│                                                                     │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Step 2: 配置 Skills - 点击通知进入应用首页 ⭐必做\n\n### 为什么要配置 Skills？\n\nSkills 标签定义了应用能够处理的消息类型和跳转路径。当用户点击通知消息时，系统需要知道：\n1. 点击后应该打开哪个页面\n2. 页面应该显示什么内容\n\n根据华为官方文档，点击通知消息有两种跳转场景，需要配置不同的 skills：\n\n---\n\n### 场景一：点击通知进入应用首页\n\n**服务端设置**：`actionType: 0`\n\n**module.json5 配置**：\n```json5\n{\n  \"module\": {\n    \u002F\u002F ...\n    \"abilities\": [\n      {\n        \"name\": \"TestAbility\",\n        \"srcEntry\": \".\u002Fets\u002Fabilities\u002FTestAbility.ets\",\n        \"exported\": false,\n        \"startWindowIcon\": \"$media:startIcon\",\n        \"startWindowBackground\": \"$color:start_window_background\",\n        \"skills\": [\n          \u002F\u002F 该skill标识应用首页，不要配置uris\n          {\n            \"entities\": [\n              \"entity.system.home\"\n            ],\n            \"actions\": [\n              \u002F\u002F \"action.system.home\"为API19以下版本配置，已废弃\n              \"ohos.want.action.home\"\n            ]\n          },\n          \u002F\u002F 其他skill配置\n          {}\n        ]\n      }\n    ]\n  }\n}\n```\n\n**关键点**：\n- `entities` 设置为 `entity.system.home`\n- `actions` 设置为 `ohos.want.action.home`\n- **不要配置 uris**，否则消息会接收不到\n\n---\n\n## Step 3: 配置 Skills - 点击通知进入应用内页（可选）\n\n### 场景二：点击通知进入应用内页\n\n**服务端设置**：`actionType: 1`\n\n有两种配置方式：\n\n**方式一：配置 actions 参数（推荐）**\n\n```json5\n{\n  \"name\": \"TestAbility\",\n  \"srcEntry\": \".\u002Fets\u002Fabilities\u002FTestAbility.ets\",\n  \"exported\": false,\n  \"startWindowIcon\": \"$media:startIcon\",\n  \"startWindowBackground\": \"$color:start_window_background\",\n  \"skills\": [\n    \u002F\u002F 保持现有skill对象不变\n    {\n      \"actions\": [\n        \"com.app.action\"\n      ]\n    },\n    \u002F\u002F 新增一个独立的skill对象，配置actions参数\n    {\n      \"actions\": [\n        \"com.test.action\"\n      ]\n    }\n  ]\n}\n```\n\n**方式二：配置 uris 参数**\n\n```json5\n{\n  \"name\": \"TestAbility\",\n  \"srcEntry\": \".\u002Fets\u002Fabilities\u002FTestAbility.ets\",\n  \"exported\": false,\n  \"startWindowIcon\": \"$media:startIcon\",\n  \"startWindowBackground\": \"$color:start_window_background\",\n  \"skills\": [\n    \u002F\u002F 保持现有skill对象不变\n    {\n      \"actions\": [\n        \"com.app.action\"\n      ]\n    },\n    \u002F\u002F 新增一个独立的skill对象，配置uris参数，且必须同时配置actions参数，actions参数为空字符串\n    {\n      \"actions\": [\"\"],\n      \"uris\": [\n        {\n          \"scheme\": \"https\",\n          \"host\": \"www.xxx.com\",\n          \"port\": \"8080\",\n          \"path\": \"push\u002Ftest\"\n        }\n      ]\n    }\n  ]\n}\n```\n\n> **参考**：华为官方文档 - [点击消息动作](https:\u002F\u002Fdeveloper.huawei.com\u002Fconsumer\u002Fcn\u002Fdoc\u002Fharmonyos-guides\u002Fpush-send-alert#点击消息动作)\n\n---\n\n## Step 4: 配置 action.ohos.push.listener ⭐必做\n\n### 前台消息处理说明\n\n> **⚠️ 默认配置**：本 Skill 默认配置前台消息接收。需要在服务端设置 `foregroundShow` 为 `false`，这样应用在前台时可以静默接收消息而不展示通知栏。\n\n**服务端设置**：\n\n```json\n{\n  \"payload\": {\n    \"notification\": {\n      \"category\": \"IM\",\n      \"title\": \"您有新消息\",\n      \"body\": \"来自朋友的消息\",\n      \"foregroundShow\": false\n    }\n  },\n  \"target\": {\n    \"token\": [\"MAMzLg**********lPW\"]\n  }\n}\n```\n\n**参数说明**：\n- `foregroundShow: true`（默认）：前后台都展示通知\n- `foregroundShow: false`：仅在后台展示通知，前台不展示但可接收消息\n\n---\n\n## Step 5: 创建 PushMessageAbility 接收前台消息 ⭐必做\n\n### 配置 module.json5\n\n需要在 abilities 中配置 skills，用于接收前台通知消息：\n\n```json5\n{\n  \"name\": \"PushMessageAbility\",\n  \"srcEntry\": \".\u002Fets\u002Fabilities\u002FPushMessageAbility.ets\",\n  \"launchType\": \"singleton\",\n  \"startWindowIcon\": \"$media:startIcon\",\n  \"startWindowBackground\": \"$color:start_window_background\",\n  \"exported\": false,\n  \"skills\": [\n    \u002F\u002F 保持现有skill对象不变\n    {\n      \"actions\": [\n        \"com.app.action\"\n      ]\n    },\n    \u002F\u002F 新增一个独立的skill对象，配置actions参数\n    {\n      \"actions\": [\n        \"action.ohos.push.listener\"\n      ]\n    }\n  ]\n}\n```\n\n> **⚠️ 配置警告**：\n> - **label 字段**：默认**不要添加**！如果需要添加，必须使用 `$string:xxx` 格式，并在 `string.json` 中添加资源名\n> - **description 字段**：可以使用普通字符串，也可以不添加\n> - **⭐ startWindowIcon 和 startWindowBackground 字段**：**必须填写**，不能遗漏！\n>   - `startWindowIcon`：应用启动图标，如 `$media:startIcon`\n>   - `startWindowBackground`：启动背景色，如 `$color:start_window_background`\n>   - 如果遗漏会导致应用无法正常启动\n>\n> 错误示例（会编译报错）：\n> ```json5\n> {\n>   \"label\": \"PushMessageAbility\"  \u002F\u002F ❌ 错误！必须用 $string:xxx 格式\n> }\n> ```\n\n**关键点**：\n- `actions` 设置为 `action.ohos.push.listener`\n- `launchType` 设置为 `singleton`\n- **项目中只能有一个 ability 定义该 action**\n- **label 字段**：默认不添加，如果添加必须用 `$string:xxx` 格式\n- **description 字段**：可以使用普通字符串，也可以不添加\n\n### 创建消息接收 Ability\n\n**文件位置**：`src\u002Fmain\u002Fets\u002Fabilities\u002FPushMessageAbility.ets`\n\n```typescript\nimport { UIAbility } from '@kit.AbilityKit';\nimport { pushService } from '@kit.PushKit';\nimport { BusinessError } from '@kit.BasicServicesKit';\nimport { hilog } from '@kit.PerformanceAnalysisKit';\n\n\u002F**\n * 此处以PushMessageAbility为例，用于应用在前台时接收通知消息\n *\u002F\nexport default class PushMessageAbility extends UIAbility {\n  onCreate(): void {\n    try {\n      \u002F\u002F receiveMessage中的参数固定为DEFAULT\n      pushService.receiveMessage('DEFAULT', this, (payload) => {\n        try {\n          \u002F\u002F 获取服务端传递的数据\n          const data: string = payload.data;\n          \u002F\u002F TODO：业务自行处理\n          hilog.info(0x0000, 'testTag', 'Succeeded in getting notification,data=%{public}s',\n            JSON.stringify(JSON.parse(data)?.notification));\n        } catch (e) {\n          let errRes: BusinessError = e as BusinessError;\n          hilog.error(0x0000, 'testTag', 'Failed to process data: %{public}d %{public}s',\n            errRes.code, errRes.message);\n        }\n      });\n    } catch (err) {\n      let e: BusinessError = err as BusinessError;\n      hilog.error(0x0000, 'testTag', 'Failed to get message: %{public}d %{public}s', e.code,\n        e.message);\n    }\n  }\n}\n```\n\n**代码说明**：\n\n| 代码段 | 作用 |\n|-------|------|\n| `pushService.receiveMessage('DEFAULT', ...)` | 注册接收通知消息 |\n| `'DEFAULT'` | 固定值，表示通知消息类型 |\n| `payload.data` | 包含通知消息内容的 JSON 字符串 |\n\n> **⚠️ 重要**：\n> - UIAbility.onCreate 是同步接口，不支持异步回调\n> - `pushService.receiveMessage()` 必须在 onCreate 入口同步调用\n> - 不能在注册前等待异步方法执行\n\n> **参考**：华为官方文档 - [应用在前台时处理通知消息](https:\u002F\u002Fdeveloper.huawei.com\u002Fconsumer\u002Fcn\u002Fdoc\u002Fharmonyos-guides\u002Fpush-send-alert#应用在前台时处理通知消息)\n\n---\n\n## 服务端推送示例\n\n### 请求示例\n\n```json\n\u002F\u002F Request URL\nPOST \"https:\u002F\u002Fpush-api.cloud.huawei.com\u002Fv3\u002F[projectId]\u002Fmessages:send\"\n\n\u002F\u002F Request Header\n\"Content-Type\": application\u002Fjson\"\n\"Authorization: Bearer eyJr*****OiIx---****.eyJh*****iJodHR--***.QRod*****4Gp---****\"\n\"push-type: 0\"\n\n\u002F\u002F Request Body\n{\n  \"payload\": {\n    \"notification\": {\n      \"category\": \"IM\",\n      \"title\": \"通知标题\",\n      \"body\": \"通知内容\",\n      \"clickAction\": {\n        \"actionType\": 0\n      },\n      \"foregroundShow\": true,\n      \"notifyId\": 12345\n    }\n  },\n  \"target\": {\n    \"token\": [\"MAMzLg**********lPW\"]\n  },\n  \"pushOptions\": {\n    \"testMessage\": true,\n    \"ttl\": 86400\n  }\n}\n```\n\n### 参数说明\n\n| 参数 | 说明 |\n|-----|------|\n| push-type | 0 表示通知消息 |\n| category | 消息分类：IM\u002FVOIP\u002FTRAVEL\u002FHEALTH\u002FWORK\u002FMARKETING |\n| foregroundShow | 应用在前台时是否展示通知 |\n| notifyId | 消息ID，用于消息撤回 |\n| testMessage | 测试消息标识，绕过频控 |\n\n---\n\n## ⚠️ 重要：多个场景化消息的配置\n\n**如果您需要同时接入通知消息、voip、后台消息，必须注意以下事项**：\n\n根据华为官方文档，一个项目中**有且只能有一个 ability** 配置 `action.ohos.push.listener`。\n\n**这意味着**：\n- 不要为每种消息类型创建单独的 Ability\n- 所有的 `receiveMessage` 注册应该放在**同一个 Ability** 中\n- module.json5 中只配置一个 ability 包含 `action.ohos.push.listener`\n\n**⚠️ 特别提醒：接入 voip 或后台消息时，请加载对应的专门 Skill**\n\n虽然同一个 Ability 中可以注册多种消息类型，但 **每种消息类型都有各自完整的开发流程和注意事项**，不能互相替代：\n\n- **通知消息**：调用 `receiveMessage('DEFAULT', ...)`，配合 `requestEnableNotification()` 授权\n- **voip 消息**：调用 `receiveMessage('VoIP', ...)`，还需要创建 VoipCallService、CalleePage 页面、注册 voipCallUiEvent 事件、上报来电状态等完整流程\n- **后台消息**：调用 `receiveMessage('BACKGROUND', ...)`，还需要实现数据静默更新和缓存策略\n\n因此：\n- 接入 **voip 消息** → 请加载 **hmos-push-kit-voip** Skill\n- 接入**后台消息** → 请加载 **hmos-push-kit-background** Skill\n- **不要**仅凭本 skill 中关于\"同一 ability 接收多种消息类型\"的说明就自行编写 voip 或后台消息代码\n\n**⚠️ 示例：不能这样做**\n\n以下示例展示的是**错误做法**——仅凭 notification skill 的说明就自行添加 voip 代码：\n\n```typescript\n\u002F\u002F ❌ 错误示例：仅凭 notification skill 的说明就自行添加 voip 代码\npushService.receiveMessage('VoIP', this, (payload) => {\n  \u002F\u002F 没有创建 VoipCallService\n  \u002F\u002F 没有创建 CalleePage 页面\n  \u002F\u002F 没有注册 voipCallUiEvent 事件监听\n  \u002F\u002F 没有上报来电状态\n  \u002F\u002F voip 有完整独立的开发流程，必须参考专门的 voip skill\n});\n```\n\n**正确做法**：请明确告诉我\"需要接入 voip 消息\"，我会加载 voip skill，在本项目的同一个 PushMessageAbility 中添加 voip 接收逻辑。\n\n---\n\n## 代码生成规则\n\n生成代码时必须遵循：\n1. 使用正确的导入路径：`@kit.NotificationKit`、`@kit.BasicServicesKit`\n2. 所有 ArkTS 类型注解必须正确\n3. 添加适当的错误处理和日志记录\n4. 生成的代码必须能够直接编译通过\n5. 遵守 HarmonyOS 应用开发规范\n\n---\n\n## 常见问题排查\n\n| 问题 | 可能原因 | 解决方案 |\n|-----|---------|---------|\n| 通知不显示 | 未调用 requestEnableNotification() | 在 onWindowStageCreate() 的 loadContent 回调中调用 |\n| 前台收不到消息 | foregroundShow 未设置为 false | 服务端设置 `foregroundShow: false` |\n| 前台收不到消息 | skills 未配置正确 | 检查 module.json5 中 skills 是否包含 `action.ohos.push.listener` |\n| 收到多条消息 | 多个 ability 都配置了相同 action | 确保只有一个 ability 配置该 action |\n| 消息数据为空 | 未正确解析 JSON | 检查 payload.data 的解析方式 |\n| 每天只能发2-5条 | 未申请消息自分类权益 | 在 AppGallery Connect 申请 IM\u002FVOIP\u002FTRAVEL\u002FHEALTH\u002FWORK 分类 |\n\n---\n\n## 常见错误码\n\n接入通知消息后，如遇到以下错误码，请参考：\n\n| 错误码 | 可能原因 | 解决方法 |\n|-------|---------|---------|\n| 1000900010 | 推送服务未开通 | 在 AppGallery Connect 开通推送服务 |\n| 1000900011 | 应用签名不匹配 | 检查签名配置是否正确 |\n| 1000900012 | 网络问题 | 检查网络连接 |\n| 1000900013 | 请求超时 | 增加超时时间或检查网络 |\n| 1000900014 | 权限不足 | 检查 module.json5 权限配置 |\n| 1000900001 | 推送服务内部错误 | 重试或联系华为支持 |\n| 1000900002 | 参数错误 | 检查请求参数是否正确 |\n| 1000900003 | Token 无效 | 检查 Token 是否正确 |\n\n> 完整错误码列表请参考 `references\u002Fpush-error-codes.md`\n\n---\n\n## ✅ AI 开发完成后的自检清单\n\n> **AI 必须在完成通知消息接入开发后，逐项确认以下所有内容：**\n\n### 通知授权检查：\n- [ ] EntryAbility.ets 中已调用 `requestEnableNotification()` ⭐重点\n- [ ] 调用位置在 `onWindowStageCreate()` 的 `loadContent` 回调中 ⭐重点\n- [ ] **不是**在 `onCreate()` 中调用\n\n### Skills 配置检查：\n- [ ] 点击首页：skills 配置包含 `entity.system.home` + `ohos.want.action.home` ⭐重点\n- [ ] 前台接收：skills 配置包含 `action.ohos.push.listener` ⭐重点\n\n### PushMessageAbility 检查：\n- [ ] `src\u002Fmain\u002Fets\u002Fabilities\u002FPushMessageAbility.ets` 已创建 ⭐重点\n- [ ] `pushService.receiveMessage('DEFAULT', ...)` 已在 onCreate() 中同步调用 ⭐重点\n- [ ] ability 的 launchType 设置为 `singleton`\n\n### 权益检查：\n- [ ] 已在 AppGallery Connect 开通推送服务 ⭐\n- [ ] 已申请通知消息自分类权益（如需要发送 IM\u002FVOIP\u002FTRAVEL\u002FHEALTH\u002FWORK 类）\n\n### 服务端参数检查：\n- [ ] category 参数正确设置\n- [ ] foregroundShow 参数设置为 false（前台静默接收）⭐重点\n- [ ] actionType 参数正确设置（0=首页，1=内页）\n\n### module.json5 配置检查：\n- [ ] skills 配置正确（首页\u002F内页\u002F前台接收）\n- [ ] **label 字段**：默认不添加，如果添加必须用 `$string:xxx` 格式\n- [ ] description 字段：可以使用普通字符串，也可以不添加\n- [ ] 如果添加了 label，确认已在 `string.json` 中添加对应资源名\n\n---\n\n> **⚠️ 如果 AI 遗漏了上述任何一项（特别是 ⭐重点 标记的项目），请立即补充！**\n\n---\n\n## ⚠️ 重要提醒汇总\n\n> **⭐ 接入通知消息完成后，请务必逐项完成以下所有提醒事项！**\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│       ⭐ 重要：接入通知消息后必须完成的权益申请和Token上报            │\n├─────────────────────────────────────────────────────────────────────┤\n│                                                                     │\n│  【权益申请 - 必须完成】⭐                                            │\n│                                                                     │\n│  1. 开通推送服务（必须）⭐                                            │\n│     您必须前往 AppGallery Connect 开通推送服务，否则无法获取有效 Token │\n│     参考文档：                                                       │\n│     https:\u002F\u002Fdeveloper.huawei.com\u002Fconsumer\u002Fcn\u002Fdoc\u002Fharmonyos-guides\u002Fpush-config-setting  │\n│                                                                     │\n│  2. 申请消息自分类权益（如需发送 IM\u002FVOIP\u002FTRAVEL\u002FHEALTH\u002FWORK）⭐       │\n│     未申请时默认为「资讯营销类」消息，会受到「每日每设备 2-5 条」限制  │\n│     参考文档：                                                       │\n│     https:\u002F\u002Fdeveloper.huawei.com\u002Fconsumer\u002Fcn\u002Fdoc\u002Fharmonyos-guides\u002Fpush-apply-right  │\n│                                                                     │\n│  ───────────────────────────────────────────────────────────────    │\n│                                                                     │\n│  【Token 上报 - 必须完成】⭐                                          │\n│                                                                     │\n│  ⚠️ 如果本次接入过程中，因项目未接入Token而自动帮您接入了Token，       │\n│     您必须完成以下工作：                                              │\n│                                                                     │\n│  在本次接入过程中，AI 已自动将 `getToken()` 调用添加到您的项目中。    │\n│  但是 `reportTokenToServer()` 方法中的上报逻辑尚未完成！              │\n│                                                                     │\n│  您必须实现 Token 上报到服务器的逻辑：                                │\n│                                                                     │\n│  ```typescript                                                      │\n│  reportTokenToServer(token: string): void {                         │\n│    hilog.info(0x0000, 'testTag', 'Reporting token to server: %{public}s', token);    │\n│    \u002F\u002F TODO: 将 Token 上报到您的服务器（必需步骤）                      │\n│  }                                                                   │\n│  ```                                                                 │\n│                                                                     │\n│  ⚠️ 重要提示：完成 Token 上报后，您的推送功能才能真正工作！            │\n│                                                                     │\n│  ───────────────────────────────────────────────────────────────    │\n│                                                                     │\n│  【频控规则】                                                        │\n│  • 调测阶段：每个项目每日全网最多可推送1000条测试消息，                 │\n│    发送测试消息需设置testMessage为true                                │\n│  • 正式发布阶段：单设备单应用下每日推送消息总条数受设备消息频控限制     │\n│                                                                     │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n> **⚠️ 请务必完成上述所有提醒事项，遗漏任何一项都可能导致推送功能无法正常工作！**\n",{"name":5,"description":7},"main","581098187aec1258c6d9e65e1b9866c2e7381167","skills\u002Fharmonyos\u002Fdevelopment\u002Fpush-kit\u002Fhmos-push-kit\u002Fhmos-push-kit-notification",0,"https:\u002F\u002Fgithub.com\u002FIsKenKenYa\u002Fskills","https:\u002F\u002Fgithub.com\u002FIsKenKenYa","是小啃啃呀-一个初学者，中国开源共享推动者之一。\r\n未来，会涉及OpenHarmony、HarmonyOS（部分应用开源）、Android Open Sources Project等。\r\n\r\n目前正在学习中，欢迎友善的讨论。","2026-10-08 01:02:25",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add IsKenKenYa\u002Fskills --skill hmos-push-kit-notification",{"tool":38,"command":39},"bunx","bunx skills add IsKenKenYa\u002Fskills --skill hmos-push-kit-notification",{"tool":41,"command":42},"pnpm","pnpm dlx skills add IsKenKenYa\u002Fskills --skill hmos-push-kit-notification","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FIsKenKenYa\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fharmonyos\u002Fdevelopment\u002Fpush-kit\u002Fhmos-push-kit\u002Fhmos-push-kit-notification\u002FSKILL.md",true,[],[47,54,61,68,75,82],{"skillNo":48,"name":49,"nameZh":6,"description":50,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":51,"categories":52,"keywords":53,"publishedAt":19},"01M75ZN00W20TC7TJ40TDM7E4X","writing-for-agents","为 agent 撰写文档。当创建或编辑 skill、修改 AGENTS.md 或 CLAUDE.md 时使用。","https:\u002F\u002Fgithub.com\u002FIsKenKenYa\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fwriting-for-agents\u002FSKILL.md",[],[],{"skillNo":55,"name":56,"nameZh":6,"description":57,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":58,"categories":59,"keywords":60,"publishedAt":19},"01M75ZMZ63RYMNRTPEXW5T82S6","wait-what","停。上一条消息没讲明白：换个说法再讲一遍。","https:\u002F\u002Fgithub.com\u002FIsKenKenYa\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fwait-what\u002FSKILL.md",[],[],{"skillNo":62,"name":63,"nameZh":6,"description":64,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":65,"categories":66,"keywords":67,"publishedAt":19},"01M75ZMXZT6MGCGFMKRTM6V6GW","to-questionnaire","把你无法独自回答的决策转化成一份问卷，交给别人填写。","https:\u002F\u002Fgithub.com\u002FIsKenKenYa\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fto-questionnaire\u002FSKILL.md",[],[],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":19},"01M75ZMWQGNJW3E592V94ZYJMX","teach","在当前工作区内，教会用户一项新 skill 或概念。","https:\u002F\u002Fgithub.com\u002FIsKenKenYa\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fteach\u002FSKILL.md",[],[],{"skillNo":76,"name":77,"nameZh":6,"description":78,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":19},"01M75ZMVQREJR3YDK0XED9AJHB","handoff","把当前对话压缩成一份交接（handoff）文档，供另一个代理接手。","https:\u002F\u002Fgithub.com\u002FIsKenKenYa\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fhandoff\u002FSKILL.md",[],[],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":19},"01M75ZMTQAAFGA7QH26WK9Z936","grilling","就一个计划、决策或想法对用户进行无情的访谈。当用户想压力测试自己的思路，或使用任何 'grill' 触发短语时使用。","https:\u002F\u002Fgithub.com\u002FIsKenKenYa\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fgrilling\u002FSKILL.md",[],[]]