@tencentcloud/sdk-mcp 1.7.1 → 1.7.3

package/resource/knowledge/push/integration/donut.md

@@ -7,27 +7,23 @@
 
 ## 操作步骤
 
-### 步骤1: 推送插件配置
+### 步骤1：配置微信消息推送插件
 
 > **说明：**
 > 在 [微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/nightly.html) 中开启推送服务，默认支持在线推送。
 >
 
 【Android】
-
-#### 插件配置
 1. 在可视化界面配置填写插件版本号，勾选开启腾讯云消息推送功能，请查看 [更新日志](https://cloud.tencent.com/document/product/269/114293) 获取插件最新版本号**。**
 
 2. 设置 Android SDK 版本。推送服务所需的微信小程序多端框架 Android SDK 最低版本为 1.4.7，推荐使用 [最新版本](https://developers.weixin.qq.com/miniprogram/dev/platform-capabilities/miniapp/changelog/android/changelog.html)。
 
 【iOS】
-
-#### 插件配置
 1. 在可视化界面配置填写插件版本号，勾选开启腾讯云消息推送功能，请查看 [更新日志](https://cloud.tencent.com/document/product/269/114293) 获取插件最新版本号。
 
 2. 设置 iOS SDK 版本。推送服务所需的微信小程序多端框架 iOS SDK 版本号为 `1.4.15` , 推荐使用 [最新的 SDK](https://developers.weixin.qq.com/miniprogram/dev/platform-capabilities/miniapp/changelog/ios/changelog.html)。
 
-### 步骤2: 离线推送配置
+### 步骤2：配置离线推送厂商
 
 > **说明：**
 > 如果只使用在线推送，则无需进行厂商离线推送配置。
@@ -35,8 +31,6 @@
 
 【Android】
 
-#### 离线推送配置
-
 可参见微信小程序多端框架官方文档 [Android 配置原生资源](https://developers.weixin.qq.com/miniprogram/dev/platform-capabilities/miniapp/handbook/devtools/android-native-resource.html)。
 1. 配置 timpush-configs.json。
 
@@ -63,8 +57,6 @@
 厂商推送都有消息分类机制，不同类型也会有不同的推送策略。需正确 [配置推送消息分类](https://cloud.tencent.com/document/product/269/100649) 才能正常收到离线推送。
 
 【iOS】
-
-#### 离线推送配置
 1. 配置证书和描述文件。
 
 请参见 [微信小程序多端框架配置文档](https://developers.weixin.qq.com/miniprogram/dev/platform-capabilities/miniapp/handbook/certificate/ios.html) 或 [腾讯云推送厂商配置文档](https://cloud.tencent.com/document/product/269/100624) 以生成 iOS 应用运行时所需的证书和 Provisioning Profile，这些文件将在后续配置中使用。您需要准备以下文件：
@@ -132,9 +124,7 @@
 > - TIMPushAppGroupID，当您需要使用 TIMPush 组件统计推送抵达率时，推荐您按照配置文档配置。
 > - 请您按照情况填写。
 
-## 推送服务使用
-
-### 集成 JS API
+### 步骤3：集成 Push SDK
 
 > **说明：**
 > 如何使用 npm 请查阅[官方文档](https://developers.weixin.qq.com/miniprogram/dev/devtools/npm.html)，此处不再赘述。
@@ -147,62 +137,44 @@
    ```
 2. 在微信开发者工具中构建 npm（**微信开发者工具** > **工具** > **构建 npm**）
 
-### 使用方法
-
-``` javascript
-import Push from "@tencentcloud/donut-push"
-const sdkAppID = 0; // 您的 SDKAppID
-const appKey = ''; // 客户端密钥
-const registrationID = ""; //用户的 registrationID
-const listener = (param) => {
-  console.log('onEvent', JSON.stringify(param));
-}
-App({
-  onLaunch: function () {
-    // 请确保在调用 registerPush 方法之前设置好registrationID。
-    // 如果您卸载并重新安装应用，registrationID 会发生改变。
-    Push.setRegistrationID(registrationID)
-      .then((res) => {
-          console.info("setRegistrationID", JSON.stringify(res));
-          return Push.registerPush(sdkAppID, appKey);
-      }).then((res) => {
-          console.info("registerPush", JSON.stringify(res));
-          return Push.getRegistrationID();
-      }).then((res) => {
-          console.info("getRegistrationID", JSON.stringify(res));
-      })
-      .catch((res) => {
-          console.error("registerPush failed", JSON.stringify(res));
-    });
-    // 监听在线推送
-    Push.addPushListener(Push.EventName.NOTIFICATION_CLICKED, listener);
-  }
-})
-```
-
-## 体验您的第一次推送
-
-在测试推送前，请务必打开通知和状态栏。进入 [推送服务 Push > 接入测试](https://console.cloud.tencent.com/im/push-plugin-push-check) 发送您的第一条推送。
-
-## 推送结果回调
-
-开启推送服务后，推送结果可以通过配置基础回调的方式，将结果转发给 App 后台，详细可参见：
-- [普通推送结果回调](https://cloud.tencent.com/document/product/269/102567)
-
-- [全员推送结果回调](https://cloud.tencent.com/document/product/269/102568)
-
-## 设备通知栏设置
-
-推送的直观表现就是通知栏提示，所以同其他通知一样受设备通知相关设置的影响，以华为为例：
-- “**手机设置** > **通知** > **锁屏通知** > **隐藏或者不显示通知**”，会影响锁屏状态下推送通知显示。
-
-- “**手机设置** > **通知** > **更多通知设置** > **状态栏显示通知图标**”，会影响状态栏下推送通知的图标显示。
+   示例代码如下：
+
+   ``` javascript
+   import Push from "@tencentcloud/donut-push"
+   const sdkAppID = 0; // 您的 SDKAppID
+   const appKey = ''; // 客户端密钥
+   const registrationID = ""; //用户的 registrationID
+   const listener = (param) => {
+     console.log('onEvent', JSON.stringify(param));
+   }
+   App({
+     onLaunch: function () {
+       // 请确保在调用 registerPush 方法之前设置好registrationID。
+       // 如果您卸载并重新安装应用，registrationID 会发生改变。
+       Push.setRegistrationID(registrationID)
+         .then((res) => {
+             console.info("setRegistrationID", JSON.stringify(res));
+             return Push.registerPush(sdkAppID, appKey);
+         }).then((res) => {
+             console.info("registerPush", JSON.stringify(res));
+             return Push.getRegistrationID();
+         }).then((res) => {
+             console.info("getRegistrationID", JSON.stringify(res));
+         })
+         .catch((res) => {
+             console.error("registerPush failed", JSON.stringify(res));
+       });
+       // 监听在线推送
+       Push.addPushListener(Push.EventName.NOTIFICATION_CLICKED, listener);
+     }
+   })
+   ```
 
-- “**手机设置** > **通知** > **应用的通知管理** > **允许通知**”，打开关闭会直接影响推送通知显示。
+### 步骤4：测试推送链路
 
-- “**手机设置** > **通知** > **应用的通知管理** > **通知铃声**” 和 “**手机设置** > **通知** > **应用的通知管理** > **静默通知**”，会影响推送通知铃音的效果。
+在测试推送前，请务必打开通知和状态栏。进入 [推送服务 Push > 接入测试](https://console.cloud.tencent.com/im/push-plugin-push-check) 发送您的第一条推送。
 
-## 厂商推送限制
+### 步骤5：检查厂商推送限制
 1. 国内厂商都有消息分类机制，不同类型也会有不同的推送策略。如果想要推送及时可靠，需要按照厂商规则设置自己应用的推送类型为高优先级的系统消息类型或者重要消息类型。反之，推送消息会受厂商推送消息分类影响，与预期会有差异。
 
 2. 另外，一些厂商对于应用每天的推送数量也是有限制的，可以在厂商控制台查看应用每日限制的推送数量。 如果推送消息出现推送不及时或者偶尔收不到情况，需要考虑下这里：
@@ -234,12 +206,23 @@ App({
 
 推送上行消息频率有限制。 具体请参见[厂商描述](https://firebase.google.com/docs/cloud-messaging/throttling-and-quotas)。
 
-## 常见问题
+## 推送结果回调
+
+开启推送服务后，推送结果可以通过配置基础回调的方式，将结果转发给 App 后台，详细可参见：
+- [普通推送结果回调](https://cloud.tencent.com/document/product/269/102567)
+
+- [全员推送结果回调](https://cloud.tencent.com/document/product/269/102568)
+
+## 设备通知栏设置
+
+推送的直观表现就是通知栏提示，所以同其他通知一样受设备通知相关设置的影响，以华为为例：
+- “**手机设置** > **通知** > **锁屏通知** > **隐藏或者不显示通知**”，会影响锁屏状态下推送通知显示。
 
-### **为什么在开发者工具上清了缓存但是构建时还是用的原来的基座 App**
+- “**手机设置** > **通知** > **更多通知设置** > **状态栏显示通知图标**”，会影响状态栏下推送通知的图标显示。
 
-需要修改 project.miniapp.json 文件才能重新构建远程基座 App，改一下应用的 version code 再进行构建即可。
+- “**手机设置** > **通知** > **应用的通知管理** > **允许通知**”，打开关闭会直接影响推送通知显示。
+
+- “**手机设置** > **通知** > **应用的通知管理** > **通知铃声**” 和 “**手机设置** > **通知** > **应用的通知管理** > **静默通知**”，会影响推送通知铃音的效果。
 
-### **iOS 在控制台上测试工具显示“上传 token 无效，请检查”，怎么办？**
+## 接入排查
 
-需要您检查下上传的 p12证书是否为推送证书、且 Bundle ID 应该是与主 App 一致。

package/resource/knowledge/push/integration/flutter.md

@@ -1,58 +1,154 @@
+本文将介绍如何在 Flutter 工程中集成 TIMPush。
+
 ## 前提条件
 
-开始接入前，请先完成对应原生平台的推送前提配置：请参见 [iOS 前提条件](https://cloud.tencent.com/document/product/269/100627#.E5.89.8D.E6.8F.90.E6.9D.A1.E4.BB.B6) 和 [Android 前提条件](https://cloud.tencent.com/document/product/269/100626#.E5.89.8D.E6.8F.90.E6.9D.A1.E4.BB.B6)。
+开始接入前，请先完成目标平台的推送前提配置，并准备好注册所需参数。按平台查看：
+
+【Android】
+
+请确认已 开通 Push 服务，并按需完成 Android 厂商配置（小米 / 华为 / OPPO / vivo / 荣耀 / 魅族 / Google FCM）。Flutter Android 侧至少需要准备：
+
+|资源|用途|
+|---------|---------|
+|`SDKAppID`、客户端密钥（Push Key）|调用 `registerPush`|
+|`timpush-configs.json`|放入 Android 应用模块 `assets`|
+|目标厂商配置文件（如有）|华为、荣耀、Google FCM 等按厂商要求放入工程|
+|工程 `applicationId`|与厂商平台应用包名一致|
+|TIMPush 版本号 `VERSION`|厂商通道包依赖版本，见 更新日志|
+
+完整资源清单与获取路径见 Android 前提条件。
+
+【iOS】
+
+请确认已 开通 Push 服务 并完成 iOS 厂商配置。Flutter iOS 侧至少需要准备：
+
+|资源|用途|
+|---------|---------|
+|`SDKAppID`、Push Key|调用 `registerPush`|
+|证书 ID（`businessID` / `apnsCertificateID`）|腾讯云控制台上传 APNs 证书后生成，经 `registerPush` 传入|
+|App Group ID（可选）|仅触达统计需要，经 `registerPush` 的 `applicationGroupID` 传入|
+
+完整资源清单见 iOS 前提条件。
+
+本文示例中的 `VERSION`、`SDKAppID`、`AppKey`、证书 ID、App Group ID 均为占位符，请勿在代码仓库中提交真实密钥。
 
 ## AI 集成
 
-通过 npx 安装 [@tencent-rtc/trtc-push-skill](https://www.npmjs.com/package/@tencent-rtc/trtc-push-skill/v/1.0.1#%E7%AE%80%E4%BD%93%E4%B8%AD%E6%96%87) 到本地 AI IDE 中，辅助完成 TIMPush 离线推送集成。安装后，你可以直接向 AI 输入“集成 Flutter 离线推送”“帮我集成 Flutter TIMPush”等需求，AI 将根据项目类型引导你完成环境检测、厂商通道配置、凭据填写、代码接入和验证等步骤。
+通过 npx 安装 [@tencent-rtc/trtc-push-skill](https://www.npmjs.com/package/@tencent-rtc/trtc-push-skill/v/1.0.1#%E7%AE%80%E4%BD%93%E4%B8%AD%E6%96%87) 到本地 AI IDE 中，辅助完成 TIMPush 离线推送集成。安装后，你可以直接向 AI 输入“集成 Flutter 离线推送”“帮我集成 Flutter TIMPush”等需求，AI 将根据项目类型引导你完成环境检测、厂商通道配置、凭据填写、代码接入和验证等步骤。详情可参考 AI Coding。
 
-> **注意：**
-> 使用 Push Skill AI 集成不是全自动流程，依然需要开发者在厂商配置控制台、腾讯云控制台等配置 Push 相关信息。具体的配置方法请参考下文相关章节。
->
+## 手动集成
 
-## 集成 TIMPush
+### 步骤1：集成 TIMPush SDK
 
-如果你想手动集成，请按顺序完成下文配置。
+如果你想手动集成，请按顺序完成下述步骤。
 
-Flutter 工程需要先引入推送插件，您可以在 `pubspec.yaml` 中添加依赖，也可以执行以下命令自动安装：
+#### 集成 Flutter 插件
+
+Flutter 工程需要先引入推送插件。您可以在 `pubspec.yaml` 中添加依赖，也可以执行以下命令自动安装：
 ``` bash
 flutter pub add tencent_cloud_chat_push
 ```
 
-完成 Flutter 插件集成后，还需要继续完成对应原生平台侧配置。
+#### 配置原生工程
+
+完成 Flutter 插件集成后，继续完成对应原生平台配置。
+
+【Android】
 
-Android 端请参考 [Android 集成 TIMPush](https://cloud.tencent.com/document/product/269/100626#.E9.9B.86.E6.88.90-timpush) 章节，完成各项配置；其中“集成 TIMPush 依赖”步骤与原生 Android 工程不同，请按下方 Flutter 方式处理。
+请先按 Android TIMPush 公共集成 和 Android 厂商通道集成 完成原生工程配置。
 
-在 `android/app/build.gradle` 或  `android/app/build.gradle.kts` 按需引入目标厂商的 TIMPush 通道包。只有引入对应厂商包，才能启用该厂商的原生推送能力。`VERSION` 请前往 [更新日志](https://cloud.tencent.com/document/product/269/1606) 获取并替换为实际版本号。
+与原生 Android 的差异如下，请按下方完成：
+1. **厂商通道包**：Flutter 插件已处理 TIMPush 基础依赖，**不要**再添加 `com.tencent.timpush:timpush` / `tuicore`。只需按需引入目标厂商通道包。
+
+2. **自定义 Application**：必须继承 `TencentCloudChatPushApplication`。
+
+在 `android/app/build.gradle` 或 `android/app/build.gradle.kts` 按需引入目标厂商的 TIMPush 通道包。只有引入对应厂商包，才能启用该厂商的原生推送能力。`VERSION` 请前往 更新日志 获取并替换为实际版本号。
+
+【小米】
 
 【Groovy DSL】
 ``` bash
-dependencies {
-    implementation 'com.tencent.timpush:huawei:VERSION'
-    implementation 'com.tencent.timpush:xiaomi:VERSION'
-    implementation 'com.tencent.timpush:oppo:VERSION'
-    implementation 'com.tencent.timpush:vivo:VERSION'
-    implementation 'com.tencent.timpush:honor:VERSION'
-    implementation 'com.tencent.timpush:meizu:VERSION'
-    implementation 'com.tencent.timpush:fcm:VERSION'
-}
+implementation 'com.tencent.timpush:xiaomi:VERSION'
 ```
 
 【Kotlin DSL】
 ``` bash
-dependencies {
-    implementation("com.tencent.timpush:huawei:VERSION")
-    implementation("com.tencent.timpush:xiaomi:VERSION")
-    implementation("com.tencent.timpush:oppo:VERSION")
-    implementation("com.tencent.timpush:vivo:VERSION")
-    implementation("com.tencent.timpush:honor:VERSION")
-    implementation("com.tencent.timpush:meizu:VERSION")
-    implementation("com.tencent.timpush:fcm:VERSION")
-}
+implementation("com.tencent.timpush:xiaomi:VERSION")
+```
+
+【华为】
 
+【Groovy DSL】
+``` bash
+implementation 'com.tencent.timpush:huawei:VERSION'
+```
+
+【Kotlin DSL】
+``` bash
+implementation("com.tencent.timpush:huawei:VERSION")
 ```
 
-Android 端还需要创建或复用自定义 `Application` 类，并继承 `TencentCloudChatPushApplication`。如果工程中已存在自定义 `Application`，直接改为继承该类，并确保 `onCreate`() 中调用 `super.onCreate()`。
+【OPPO】
+
+【Groovy DSL】
+``` bash
+implementation 'com.tencent.timpush:oppo:VERSION'
+```
+
+【Kotlin DSL】
+``` bash
+implementation("com.tencent.timpush:oppo:VERSION")
+```
+
+【vivo】
+
+【Groovy DSL】
+``` bash
+implementation 'com.tencent.timpush:vivo:VERSION'
+```
+
+【Kotlin DSL】
+``` bash
+implementation("com.tencent.timpush:vivo:VERSION")
+```
+
+【荣耀】
+
+【Groovy DSL】
+``` bash
+implementation 'com.tencent.timpush:honor:VERSION'
+```
+
+【Kotlin DSL】
+``` bash
+implementation("com.tencent.timpush:honor:VERSION")
+```
+
+【魅族】
+
+【Groovy DSL】
+``` bash
+implementation 'com.tencent.timpush:meizu:VERSION'
+```
+
+【Kotlin DSL】
+``` bash
+implementation("com.tencent.timpush:meizu:VERSION")
+```
+
+【Google FCM】
+
+【Groovy DSL】
+``` bash
+implementation 'com.tencent.timpush:fcm:VERSION'
+```
+
+【Kotlin DSL】
+``` bash
+implementation("com.tencent.timpush:fcm:VERSION")
+```
+
+Android 端还需要创建或复用自定义 `Application` 类，并继承 `TencentCloudChatPushApplication`。如果工程中已存在自定义 `Application`，直接改为继承该类，并确保 `onCreate()` 中调用 `super.onCreate()`。
 ``` java
 package com.example.pushdemo
 
@@ -73,7 +169,9 @@ class MyApplication : TencentCloudChatPushApplication() {
 </application>
 ```
 
-iOS 端不需要执行原生 iOS 文档中“主 App target 集成”步骤，Flutter 插件会处理相关依赖。您只需要在 `ios/Runner/AppDelegate.swift` 中补充 TIMPush 相关配置，用于返回推送证书 ID、App Group ID，以及转发离线推送点击事件。
+【iOS】
+
+Flutter 插件会处理 TIMPush 相关依赖，**不需要**执行原生 iOS 文档中“主 App target 集成”步骤。您只需要在 `ios/Runner/AppDelegate.swift` 中补充 TIMPush 相关配置，用于返回推送证书 ID、App Group ID，以及转发离线推送点击事件。证书 ID 与 App Group ID 由 `registerPush` 传入，再经下列桥接方法返回给 TIMPush。
 ``` swift
 import UIKit
 import Flutter
@@ -111,11 +209,23 @@ import tencent_cloud_chat_push
 }
 ```
 
-## 注册推送
+### 步骤2：注册推送服务
 
-[registerPush](https://cloud.tencent.com/document/product/269/101962#3aab298e-7d51-4b17-ac24-8dd6b2d30e01) 用于注册当前设备的推送 token。注册时机、参数含义和不同接入场景的说明，请参考 [Android 注册推送](https://cloud.tencent.com/document/product/269/100626#.E6.B3.A8.E5.86.8C.E6.8E.A8.E9.80.81) 和 [iOS 注册推送](https://cloud.tencent.com/document/product/269/100627#50e75789-9e42-43b1-b9d1-7cf0dd15b930) 章节。
+registerPush 用于向 TIMPush 注册当前设备的推送 token。注册成功后，TIMPush 会为当前设备建立一个推送目标标识 `registrationID`；服务端、控制台接入测试和排查工具可以使用该标识向这台设备下发离线推送。若 App 同时接入 IM 并完成登录，也可以使用 `userID` 向该用户已建立推送关系的设备下发离线推送。
 
-**请注意，不要在 Flutter 程序入口的** `main` **方法中调用。**建议在用户同意隐私政策后，并在业务侧合适时机调用。
+`appKey` 的取值会影响注册方式和可用的推送标识：
+- `appKey = Push Key`：注册 TIMPush 独立推送能力。Push Key 客户端密钥。
+
+- `appKey = null`：复用 IM 登录态注册推送，必须在 IM `login` 成功后调用。
+
+   请先根据业务场景确认调用顺序。注册时机、参数含义和不同接入场景的说明，也可参考 Android 注册推送 和 iOS 注册推送。
+
+   > **注意：**
+   >
+   > - 如果用户退出 IM SDK，同时集成了 IM SDK + TIMPush 的场景下已建立的 `userID` 与 `registrationID` 推送关系都会失效，需要重新完成对应注册。
+   > - Chat 应用的密钥仅用于 IM 登录，不能作为 `registerPush` 的 `appKey`。
+
+   **请注意，不要在 Flutter 程序入口的** `main` **方法中调用。**建议在用户同意隐私政策后，并在业务侧合适时机调用。
 
 【App 冷启动注册 TIMPush（appKey 传 Push Key）】
 ``` javascript
@@ -206,17 +316,52 @@ Future<void> loginIMAndRegisterPush() async {
 }
 ```
 
-## 配置消息触达统计（可选）
+   > **警告：**
+   >
+   > 如果您的业务仅使用即时通信 IM 聊天能力，请勿在 IM 登录前先调用 `registerPush`。否则 SDK 可能会按独立推送场景注册 Push 类型账号，并产生对应的 Push DAU。Push DAU 超出套餐额度后，可能会产生额外费用。
+   >
+
+### 步骤3：配置消息触达统计（可选）
+
+触达统计主要涉及厂商控制台、回执地址、APNs Notification Service Extension、App Group 等平台专属配置。按平台完成：
 
-触达统计主要涉及厂商控制台、回执地址、APNs Notification Service Extension、App Group 等平台专属配置，请参考 [Android 配置消息触达统计](https://cloud.tencent.com/document/product/269/100626#.E9.85.8D.E7.BD.AE.E6.B6.88.E6.81.AF.E8.A7.A6.E8.BE.BE.E7.BB.9F.E8.AE.A1.EF.BC.88.E5.8F.AF.E9.80.89.EF.BC.89) 和 [iOS 配置消息触达统计](https://cloud.tencent.com/document/product/269/100627#.E9.85.8D.E7.BD.AE.E6.B6.88.E6.81.AF.E8.A7.A6.E8.BE.BE.E7.BB.9F.E8.AE.A1.EF.BC.88.E5.8F.AF.E9.80.89.EF.BC.89) 文档。
+【Android】
 
-iOS 如需统计推送触达数据，请在 `registerPush` 时传入 `applicationGroupID`，并确认 `ios/Runner/AppDelegate.swift` 中已实现 `applicationGroupID()`。
+请按 Android 厂商通道集成 中对应厂商 Tab 的触达统计说明完成配置。Flutter 侧无额外 Dart 代码。
 
-## 测试推送
+【iOS】
+
+请按 iOS 配置消息触达统计 完成 Notification Service Extension、`mutable-content` 与 App Group 等配置。
+
+Flutter 额外确认两点：
+1. 调用 `registerPush` 时传入 `applicationGroupID`。
+
+2. `ios/Runner/AppDelegate.swift` 中已实现 `applicationGroupID()`。
+
+### 步骤4：测试推送链路
+
+完成上述集成步骤后，需要通过发送测试消息验证链路是否打通。
 
 运行 App 后，过滤 `TIMPush` 关键字查看注册日志。注册成功后，调用 `getRegistrationID()` 获取当前设备推送标识。控制台或服务端发送测试消息时，可使用该值定位设备。
 
-测试流程请参考 [Android 测试推送](https://cloud.tencent.com/document/product/269/100626#.E6.B5.8B.E8.AF.95.E6.8E.A8.E9.80.81) 和 [iOS 测试推送](https://cloud.tencent.com/document/product/269/100627#.E6.B5.8B.E8.AF.95.E6.8E.A8.E9.80.81) 文档。仅集成 TIMPush 的用户，建议优先使用腾讯云控制台接入测试能力验证离线推送。
+发送消息前请确认：
+1. App 已获得系统通知权限（含横幅、锁屏、声音等开关）。
+
+2. App 已置于后台或杀掉进程（前台时离线推送可能不触发）。
+
+   发送测试消息可以采用下面几种方法：
+
+【控制台发送】
+
+仅集成 TIMPush 的用户，建议优先使用腾讯云控制台接入测试能力验证离线推送。
+
+操作路径：腾讯云控制台 > **推送服务 Push** > **接入测试**。在接入测试页面，可以指定 `registrationID` 或 `userID` 发送离线推送测试。
+
+【REST API 发送】
+
+如果需要通过服务端发送推送，可参考 全员/标签推送。
+
+【SDK API 发送】
 
 如果您的项目已接入 IM SDK，可通过 SDK API 发送一条带离线推送参数的消息进行验证。Flutter 侧示例如下：
 ``` java
@@ -255,9 +400,13 @@ Future<void> sendTestPushMessage({
 }
 ```
 
-## 处理通知点击跳转
+   **验证**：App 置于后台后发送测试消息，设备能收到离线推送通知。如果手机通知栏开启权限，通知栏会弹出离线推送消息弹框。
 
-通知点击跳转完整流程请参考 [Android 处理通知点击跳转](https://cloud.tencent.com/document/product/269/100626#.E5.A4.84.E7.90.86.E9.80.9A.E7.9F.A5.E7.82.B9.E5.87.BB.E8.B7.B3.E8.BD.AC) 和 [iOS 处理通知点击跳转](https://cloud.tencent.com/document/product/269/100627#.E5.A4.84.E7.90.86.E9.80.9A.E7.9F.A5.E7.82.B9.E5.87.BB.E8.B7.B3.E8.BD.AC) 文档。Flutter 侧主要关注两处差异：通过 IM SDK API 发送消息时写入 `ext`，以及在客户端注册监听并解析 `ext`。
+### 步骤5：处理通知点击跳转
+
+通知点击跳转完整流程。Flutter 侧的配置控制台点击动作跟原生平台一致，但要关注另外两个步骤差异。
+
+#### **发送推送时携带** `ext`
 
 如果您的项目已接入 IM SDK，可在发送消息时通过 `OfflinePushInfo.ext` 携带跳转参数。示例代码如下：
 ``` java
@@ -296,9 +445,10 @@ Future<void> sendMessageWithPushExt({
 }
 ```
 
+#### **客户端注册监听并解析** `ext`
+
 Flutter 客户端推荐使用 `TencentCloudChatPush().addPushListener` 监听通知点击事件，并在 `onNotificationClicked` 中解析 `ext`。示例代码如下：
 ``` java
-
 final TIMPushListener timPushListener = TIMPushListener(
   onRecvPushMessage: (TimPushMessage msg) {
     debugPrint(
@@ -348,26 +498,7 @@ Future<void> removeTIMPushListener() async {
 > - `ext` 是发送方写入的业务透传字段，建议使用 JSON 字符串，例如 `{"conversationID":"user_A","conversationType":1}`。
 > - 若 App 冷启动后需要立即处理点击事件，建议尽早注册 `listener`，例如在登录流程完成后、业务首页初始化前完成注册。
 
-## 配置消息分类（可选）
-
-消息分类属于 Android 厂商通道策略，Flutter 侧没有额外的接入操作，请参考 [Android 配置消息分类](https://cloud.tencent.com/document/product/269/100626#config_category) 文档，API 请参考 [Flutter 消息分类 API](https://pub.dev/documentation/tencent_cloud_chat_sdk/latest/enum_offlinePushInfo/OfflinePushInfo-class.html) 文档。
-
-## 收不到推送排障流程
-
-### 步骤1：原生侧排查
-
-如果发送测试消息后设备没有收到推送，请先按平台文档 [Android 收不到推送排障流程](https://cloud.tencent.com/document/product/269/100626#.E6.94.B6.E4.B8.8D.E5.88.B0.E6.8E.A8.E9.80.81.E6.8E.92.E9.9A.9C.E6.B5.81.E7.A8.8B) 和 [iOS 收不到推送排障流程](https://cloud.tencent.com/document/product/269/100627#.E6.94.B6.E4.B8.8D.E5.88.B0.E6.8E.A8.E9.80.81.E6.8E.92.E9.9A.9C.E6.B5.81.E7.A8.8B) 完成原生侧排查。
-
-### 步骤2：Flutter 侧可按以下顺序补充检查
-1. 确认 `registerPush` 返回 `code = 0`。如果返回非 0，请先根据错误码和 `errorMessage` 排查，不要只看 App 是否启动成功。
-
-2. 注册成功后调用 `getRegistrationID()`，确认返回值非空。控制台或服务端发送测试消息时，使用的 `RegistrationID / userID` 应与这里返回的值一致。
-
-3. 确认 `registerPush` 的调用时机正确。仅使用 Push 能力时，可在 App 完成必要初始化、用户同意隐私政策并获得通知权限后调用；Chat / TUIKit 离线推送场景下，应在 IM 登录成功后调用。
-
-4. 确认通知点击逻辑已通过 `TencentCloudChatPush().addPushListener` 注册。`registerPush` 中的 `onNotificationClicked` 参数当前仅作为必填空实现保留，不建议继续在其中处理跳转。
-
-5. 如果通过 Chat SDK 发送测试消息，确认 `OfflinePushInfo` 中已设置 `title`、`desc`，并按业务需要设置 `ext`。如需点击跳转，`ext` 中应包含客户端可解析的页面或会话参数。
+发送离线推送时如需设置 Android 厂商消息分类或通知渠道 ID，可通过 Flutter Chat SDK 的 [OfflinePushInfo](https://pub.dev/documentation/tencent_cloud_chat_sdk/latest/enum_offlinePushInfo/OfflinePushInfo-class.html) 设置；具体字段含义与厂商规则见 Android 厂商通道集成。
 
-### 仍无法解决
+## 接入排查
 

package/resource/knowledge/push/integration/harmonyos.md

@@ -12,7 +12,11 @@
 
 本文示例中的 `VERSION`、`SDKAppID`、`appKey`均为占位符，请勿在代码仓库中提交真实密钥。
 
-## 操作步骤
+## AI 集成
+
+通过 npx 安装 [@tencent-rtc/trtc-push-skill](https://www.npmjs.com/package/@tencent-rtc/trtc-push-skill/v/1.0.1#%E7%AE%80%E4%BD%93%E4%B8%AD%E6%96%87) 到本地 AI IDE 中，辅助完成 TIMPush 离线推送集成。安装后，您可以直接向 AI 输入“集成 Harmonyos 离线推送”等需求，AI 将根据项目类型引导您完成环境检测、厂商通道配置、凭据填写、代码接入和验证等步骤。详情可参考 AI Coding。
+
+## 手动集成
 
 ### 步骤1：集成 TIMPush
 
@@ -71,4 +75,5 @@ let pushListener: TIMPushListener = {
 TIMPushManager.getInstance().addPushListener(pushListener);
 ```
 
-恭喜您已经完成了推送插件的接入。如果接入完成收不到推送，请使用 [排查工具](https://cloud.tencent.com/document/product/269/100629) 查看具体原因。
+## 接入排查
+