@tencentcloud/sdk-mcp 1.6.0-beta.3 → 1.6.0

package/resource/knowledge/push/config/unity.md

@@ -0,0 +1,199 @@
+目前消息推送插件，在 Unity 中仅支持推送至 Android（含各厂商通道）和 iOS 设备。
+
+> **注意：**
+>
+
+> 每个厂商仅支持配置 1 个证书。
+>
+
+【iOS】
+
+集成消息推送插件之前，需要先向 Apple 申请 APNs 推送证书，然后上传推送证书到 IM 控制台 。之后按照快速接入步骤接入即可。
+
+## 操作步骤
+
+【p8 证书（推荐）】
+
+p8 证书：p8 证书没有到期日期，因此您无需担心证书过期。此外，使用 p8 证书可以简化证书管理，因为您可以使用一个 p8 证书为多个应用程序提供推送通知服务。另外，p8 证书支持灵动岛推送。
+
+### 步骤1：申请 APNs 证书
+
+要创建 p8 证书文件，首先需要登录 [苹果开发者中心](https://developer.apple.com/)。
+
+1.  进入 Certificates, Identifiers & Profiles：在页面右上角单击 **Account**，然后在下拉菜单中选择 **Certificates, Identifiers & Profiles** 。
+
+2. 创建一个新的 App ID：在左侧菜单中单击 **Identifiers** ，然后单击右侧的 **+** 创建一个新的 App ID。填写相应的信息并单击 **Continue **。
+
+3. 创建一个新的密钥：在左侧菜单中单击 **Keys**，然后单击右侧的 **+** 创建一个新的密钥。输入密钥的名称，然后勾选 **Apple Push Notifications service (APNs)**，单击 **Continue** 。
+
+确认并生成密钥：在确认页面核对您的密钥信息，然后单击 **Register** 。接下来，您将看到一个页面提示您下载密钥。单击 **Download**，将生成的 .p8 文件保存到您的计算机上。
+
+> **说明：**
+>
+> - p8 证书只可以下载一次，请妥善保存。
+> - 请妥善保管下载的 p8 文件，因为您将无法再次下载该文件。您可以使用此 p8 证书配置您的 iOS 应用程序以接收推送通知。
+
+### 步骤2：上传 p8 证书到 IM 控制台
+1. 登录 [即时通信 IM 控制台](https://console.cloud.tencent.com/im)。
+
+2. 单击目标应用卡片，进入应用的基础配置页面。
+
+3. 单击 **iOS 原生离线推送设置**右侧的**添加证书**。
+
+4. 选择 **p8 证书**。
+
+> **说明：**
+>
+> - **Key ID**：这是您的 APNs Auth Key 的唯一标识符。当您在 Apple Developer Center 创建一个新的 APNs Auth Key 时，系统会为您生成一个 Key ID。您可以在 "Certificates, Identifiers & Profiles" 部分的 "Keys" 中找到它。
+> - **Team ID**：这是您的开发者账户的唯一标识符。您可以在 Apple Developer Center 的账户详情页面找到它。点击右上角的 "Membership"，在 "Membership Details" 部分可以找到您的 Team ID。
+> - **Bundle ID**：这是您的应用程序的唯一标识符，也称为应用程序 ID。您可以在 Apple Developer Center 的 "Certificates, Identifiers & Profiles" 部分找到它。选择 "Identifiers"，然后在您的应用程序列表中找到对应的 Bundle ID。
+
+【p12 证书】
+
+### 步骤1：申请 APNs 证书
+
+#### 开启 App 远程推送
+1. 登录 [苹果开发者中心](https://developer.apple.com/account/) 网站，单击 **Certificates, Identifiers & Profiles** 或者侧栏的 **Certificates, IDs & Profiles**，进入 **Certificates, IDs & Profiles** 页面。
+
+2. 单击 Identifiers 右侧的 **+**。
+
+3. 您可以参见如下步骤新建一个 AppID，或者在您原有的 AppID 上增加 `Push Notification` 的 `Service`。
+
+> **说明：**
+>
+
+>  您 App 的 `Bundle ID` 不能使用通配符 `*`，否则将无法使用远程推送服务。
+>
+
+4. 勾选 **App IDs**，单击 **Continue** 进行下一步。
+
+5. 选择 **App**，单击 **Continue** 进行下一步。
+
+6. 配置 `Bundle ID` 等其他信息，单击 **Continue** 进行下一步。
+
+7. 勾选 **Push Notifications**，开启远程推送服务。
+
+#### 生成证书
+1. 选中您的 AppID，选择 **Configure**。
+
+2. 可以看到在 **Apple Push Notification service SSL Certificates** 窗口中有两个 `SSL Certificate`，分别用于开发环境（Development）和生产环境（Production）的远程推送证书，如下图所示：
+
+3.
+
+我们先选择开发环境（Development）的 **Create Certificate**，系统将提示我们需要一个 Certificate Signing Request（CSR）。
+
+4. 在 Mac 上打开**钥匙串访问工具（Keychain Access）**，在菜单中选择**钥匙串访问 **> **证书助理 **> **从证书颁发机构请求证书**（`Keychain Access - Certificate Assistant - Request a Certificate From a Certificate Authority`）。
+
+5. 输入用户电子邮件地址（您的邮箱）、常用名称（您的名称或公司名），选择**存储到磁盘**，单击**继续**，系统将生成一个 `*.certSigningRequest` 文件。
+
+6. 返回上述 步骤3 中 Apple Developer 网站刚才的页面，单击 **Choose File** 上传生成的 `*.certSigningRequest` 文件。
+
+7. 单击 **Continue**，即可生成推送证书。
+
+8. 单击 **Download** 下载开发环境的 `Development SSL Certificate` 到本地。
+
+9. 再次按照上述步骤1 - 8，将生产环境的 `Production SSL Certificate` 下载到本地。
+
+> **说明：**
+>
+
+> 生产环境的证书实际是开发（Sandbox）+生产（Production）的合并证书，可以同时作为开发环境和生产环境的证书使用。
+>
+
+10. 双击打开下载的开发环境和生产环境的 `SSL Certificate`，系统会将其导入钥匙串中。
+
+11. 打开钥匙串应用，在**登录 **> **我的证书**，右键分别导出刚创建的开发环境（`Apple Development IOS Push Service`）和生产环境（`Apple Push Services`）的 `p12` 文件。
+
+> **注意**
+>
+
+> 保存`.p12`文件时，请务必为其设置密码。
+>
+
+### 步骤2：上传证书到控制台
+1. 登录 [即时通信 IM 控制台](https://console.cloud.tencent.com/im)。
+
+2. 单击目标应用卡片，进入应用的基础配置页面。
+
+3. 单击 **iOS 原生离线推送设置**右侧的**添加证书**。
+
+4. 选择证书类型，上传 iOS 证书（.p12），设置证书密码，单击**确认**。
+
+> **说明：**
+>
+> - 上传证书名最好使用全英文（尤其不能使用括号等特殊字符）。
+> - 上传证书需要设置密码，无密码收不到推送。
+> - 发布 App Store 的证书需要设置为生产环境，否则无法收到推送。
+> - 上传的 p12 证书必须是自己申请的真实有效的证书。
+
+5. 待推送证书信息生成后，记录证书的 ID。
+
+【Android】
+
+## 操作步骤
+
+### 步骤1：注册应用到厂商推送平台
+
+离线推送需要将您自己的应用注册到各个厂商的推送平台，得到 AppID 和 AppKey 等参数，来实现离线推送功能。目前国内支持的手机厂商有：[小米](https://dev.mi.com/xiaomihyperos/documentation/detail)、[华为](https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/service-introduction-0000001050040060)、[荣耀](https://developer.hihonor.com/cn/kitdoc)、[OPPO](https://open.oppomobile.com/wiki/doc#id=10195)、[vivo](https://dev.vivo.com.cn/documentCenter/doc/281)、[魅族](https://open.flyme.cn/service/3)，境外支持 [Google FCM](https://console.firebase.google.com/u/0/)，是否需要上架商店详情如下：
+
+|厂商|小米|华为|OPPO|vivo|魅族|荣耀|Google FCM|
+|---------|---------|---------|---------|---------|---------|---------|---------|
+|是否需要上架|是|否|是|是|否|否|否|
+
+### 步骤2：IM 控制台配置
+
+登录腾讯云 [即时通信 IM 控制台](https://console.qcloud.com/avc) ，在**推送服务 Push > 推送设置 > 厂商配置**功能栏添加各个厂商推送证书，并将您在步骤一中获取的各厂商的 AppId、AppKey、AppSecret 等参数配置给添加的推送证书。
+
+> **注意：**
+>
+
+> 关于**点击后续动作**选项，如需使用本插件提供的点击跳转能力，请保持默认值不变， 即通常是`打开应用内指定页面`并带有默认配置。
+>
+
+> 如需使用上报统计功能，也请保持此项默认值不变。
+>
+
+【小米】
+
+|厂商推送平台|IM 控制台配置|
+|---------|---------|
+|||
+
+【华为】
+| 厂商推送平台 | IM 控制台配置 |
+| --- | --- |
+|  | <strong>说明：</strong><br>Client ID 对应 AppID，Client Secret 对应 AppSecret。 |
+
+【OPPO】
+
+|厂商推送平台|IM 控制台配置|
+|---------|---------|
+|||
+
+【vivo】
+
+|厂商推送平台|IM 控制台配置|
+|---------|---------|
+|||
+
+回执配置请参考：[消息触达统计配置-vivo](https://cloud.tencent.com/document/product/269/100626#daa658b0-1ac0-44a8-8a47-7ec8822ebe82)
+
+【魅族】
+
+|厂商推送平台|IM 控制台配置|
+|---------|---------|
+|||
+
+回执配置请参考：[消息触达统计配置 > 魅族](https://cloud.tencent.com/document/product/269/100626#daa658b0-1ac0-44a8-8a47-7ec8822ebe82)
+
+【荣耀】
+
+|厂商推送平台|IM 控制台配置|
+|---------|---------|
+|||
+
+【Google FCM】
+
+|厂商推送平台|IM 控制台配置|
+|---------|---------|
+|||

package/resource/knowledge/push/config/unreal-engine.md

@@ -0,0 +1,199 @@
+推送服务目前推送支持小米、华为、荣耀、OPPO、vivo、魅族、一加、realme、iQOO 、FCM 和 Apple 等厂商通道。
+
+> **注意：**
+>
+
+> 每个厂商仅支持配置 1 个证书。
+>
+
+【iOS】
+
+集成 消息推送插件之前，需要先向 Apple 申请 APNs 推送证书，然后上传推送证书到 IM 控制台 。之后按照快速接入步骤接入即可。
+
+## 操作步骤
+
+【p8 证书（推荐）】
+
+p8 证书：p8 证书没有到期日期，因此您无需担心证书过期。此外，使用 p8 证书可以简化证书管理，因为您可以使用一个 p8 证书为多个应用程序提供推送通知服务。另外，p8 证书支持灵动岛推送。
+
+### 步骤1：申请 APNs 证书
+
+要创建 p8 证书文件，首先需要登录 [苹果开发者中心](https://developer.apple.com/)。
+
+1.  进入 Certificates,Identifiers & Profiles：在页面右上角单击 **Account**，然后在下拉菜单中选择 **Certificates, Identifiers & Profiles** 。
+
+2. 创建一个新的 App ID：在左侧菜单中单击 **Identifiers** ，然后单击右侧的 **+** 创建一个新的 App ID。填写相应的信息并单击 **Continue **。
+
+3. 创建一个新的密钥：在左侧菜单中单击 **Keys**，然后单击右侧的 **+** 创建一个新的密钥。输入密钥的名称，然后勾选 **Apple Push Notifications service (APNs)**，单击 **Continue** 。
+
+确认并生成密钥：在确认页面核对您的密钥信息，然后单击 **Register** 。接下来，您将看到一个页面提示您下载密钥。单击 **Download**，将生成的 .p8 文件保存到您的计算机上。
+
+> **说明：**
+>
+> - p8 证书只可以下载一次，请妥善保存。
+> - 请妥善保管下载的 p8 文件，因为您将无法再次下载该文件。您可以使用此 p8 证书配置您的 iOS 应用程序以接收推送通知。
+
+### 步骤2：上传 p8 证书到 IM 控制台
+1. 登录 [即时通信 IM 控制台](https://console.cloud.tencent.com/im)。
+
+2. 单击目标应用卡片，进入应用的基础配置页面。
+
+3. 单击 **iOS 原生离线推送设置**右侧的**添加证书**。
+
+4. 选择 .p8 证书
+
+> **说明：**
+>
+> - **Key ID**：这是您的 APNs Auth Key 的唯一标识符。当您在 Apple Developer Center 创建一个新的 APNs Auth Key 时，系统会为您生成一个 Key ID。您可以在 "Certificates, Identifiers & Profiles" 部分的 "Keys" 中找到它。
+> - **Team ID**：这是您的开发者账户的唯一标识符。您可以在 Apple Developer Center 的账户详情页面找到它。点击右上角的 "Membership"，在 "Membership Details" 部分可以找到您的 Team ID。
+> - **Bundle ID**：这是您的应用程序的唯一标识符，也称为应用程序 ID。您可以在 Apple Developer Center 的 "Certificates, Identifiers & Profiles" 部分找到它。选择 "Identifiers"，然后在您的应用程序列表中找到对应的 Bundle ID。
+
+【p12 证书】
+
+### 步骤1：申请 APNs 证书
+
+#### 开启 App 远程推送
+1. 登录 [苹果开发者中心](https://developer.apple.com/account/) 网站，单击 **Certificates, Identifiers & Profiles** 或者侧栏的 **Certificates, IDs & Profiles**，进入 **Certificates, IDs & Profiles** 页面。
+
+2. 单击 Identifiers 右侧的 **+**。
+
+3. 您可以参见如下步骤新建一个 AppID，或者在您原有的 AppID 上增加 `Push Notification` 的 `Service`。
+
+> **说明：**
+>
+
+>  您 App 的 `Bundle ID` 不能使用通配符 `*`，否则将无法使用远程推送服务。
+>
+
+4. 勾选 **App IDs**，单击 **Continue** 进行下一步。
+
+5. 选择 **App**，单击 **Continue** 进行下一步。
+
+6. 配置 `Bundle ID` 等其他信息，单击 **Continue** 进行下一步。
+
+7. 勾选 **Push Notifications**，开启远程推送服务。
+
+#### 生成证书
+1. 选中您的 AppID，选择 **Configure**。
+
+2. 可以看到在 **Apple Push Notification service SSL Certificates** 窗口中有两个 `SSL Certificate`，分别用于开发环境（Development）和生产环境（Production）的远程推送证书，如下图所示：
+
+3.
+
+我们先选择开发环境（Development）的 **Create Certificate**，系统将提示我们需要一个 Certificate Signing Request（CSR）。
+
+4. 在 Mac 上打开**钥匙串访问工具（Keychain Access）**，在菜单中选择**钥匙串访问 **> **证书助理 **> **从证书颁发机构请求证书**（`Keychain Access - Certificate Assistant - Request a Certificate From a Certificate Authority`）。
+
+5. 输入用户电子邮件地址（您的邮箱）、常用名称（您的名称或公司名），选择**存储到磁盘**，单击**继续**，系统将生成一个 `*.certSigningRequest` 文件。
+
+6. 返回上述 步骤3 中 Apple Developer 网站刚才的页面，单击 **Choose File** 上传生成的 `*.certSigningRequest` 文件。
+
+7. 单击 **Continue**，即可生成推送证书。
+
+8. 单击 **Download** 下载开发环境的 `Development SSL Certificate` 到本地。
+
+9. 再次按照上述步骤1 - 8，将生产环境的 `Production SSL Certificate` 下载到本地。
+
+> **说明：**
+>
+
+> 生产环境的证书实际是开发（Sandbox）+生产（Production）的合并证书，可以同时作为开发环境和生产环境的证书使用。
+>
+
+10. 双击打开下载的开发环境和生产环境的 `SSL Certificate`，系统会将其导入钥匙串中。
+
+11. 打开钥匙串应用，在**登录 **> **我的证书**，右键分别导出刚创建的开发环境（`Apple Development IOS Push Service`）和生产环境（`Apple Push Services`）的 `p12` 文件。
+
+> **注意**
+>
+
+> 保存`.p12`文件时，请务必为其设置密码。
+>
+
+### 步骤2：上传证书到控制台
+1. 登录 [即时通信 IM 控制台](https://console.cloud.tencent.com/im)。
+
+2. 单击目标应用卡片，进入应用的基础配置页面。
+
+3. 单击 **iOS 原生离线推送设置**右侧的**添加证书**。
+
+4. 选择证书类型，上传 iOS 证书（.p12），设置证书密码，单击**确认**。
+
+> **说明：**
+>
+> - 上传证书名最好使用全英文（尤其不能使用括号等特殊字符）。
+> - 上传证书需要设置密码，无密码收不到推送。
+> - 发布 App Store 的证书需要设置为生产环境，否则无法收到推送。
+> - 上传的 p12 证书必须是自己申请的真实有效的证书。
+
+5. 待推送证书信息生成后，记录证书的 ID。
+
+【Android】
+
+## 操作步骤
+
+### 步骤1：注册应用到厂商推送平台
+
+离线推送需要将您自己的应用注册到各个厂商的推送平台，得到 AppID 和 AppKey 等参数，来实现离线推送功能。目前国内支持的手机厂商有：[小米](https://dev.mi.com/xiaomihyperos/documentation/detail)、[华为](https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/service-introduction-0000001050040060)、[荣耀](https://developer.hihonor.com/cn/kitdoc)、[OPPO](https://open.oppomobile.com/wiki/doc#id=10195)、[vivo](https://dev.vivo.com.cn/documentCenter/doc/281)、[魅族](https://open.flyme.cn/service/3)，境外支持 [Google FCM](https://console.firebase.google.com/u/0/)，是否需要上架商店详情如下：
+
+|厂商|小米|华为|OPPO|vivo|魅族|荣耀|Google FCM|
+|---------|---------|---------|---------|---------|---------|---------|---------|
+|是否需要上架|是|否|是|是|否|否|否|
+
+### 步骤2：IM 控制台配置
+
+登录腾讯云 [即时通信 IM 控制台](https://console.qcloud.com/avc) ，在**推送服务 Push > 推送设置 > 厂商配置**功能栏添加各个厂商推送证书，并将您在步骤一中获取的各厂商的 AppId、AppKey、AppSecret 等参数配置给添加的推送证书。
+
+> **注意：**
+>
+
+> 关于**点击后续动作**选项, 如需使用本插件提供的点击跳转能力, 请保持默认值不变, 即通常是 `打开应用内指定页面` 并带有默认配置.
+>
+
+> 如需使用上报统计功能, 也请保持此项默认值不变,
+>
+
+【小米】
+
+|厂商推送平台|IM 控制台配置|
+|---------|---------|
+|||
+
+【华为】
+| 厂商推送平台 | IM 控制台配置 |
+| --- | --- |
+|  | <strong>说明：</strong><br>Client ID 对应 AppID，Client Secret 对应 AppSecret。 |
+
+【OPPO】
+
+|厂商推送平台|IM 控制台配置|
+|---------|---------|
+|||
+
+【vivo】
+
+|厂商推送平台|IM 控制台配置|
+|---------|---------|
+|||
+
+回执配置请参考：[消息触达统计配置-vivo](https://cloud.tencent.com/document/product/269/100626#daa658b0-1ac0-44a8-8a47-7ec8822ebe82)
+
+【魅族】
+
+|厂商推送平台|IM 控制台配置|
+|---------|---------|
+|||
+
+回执配置请参考：[消息触达统计配置 > 魅族](https://cloud.tencent.com/document/product/269/100626#daa658b0-1ac0-44a8-8a47-7ec8822ebe82)
+
+【荣耀】
+
+|厂商推送平台|IM 控制台配置|
+|---------|---------|
+|||
+
+【Google FCM】
+
+|厂商推送平台|IM 控制台配置|
+|---------|---------|
+|||

package/server.js

@@ -8,6 +8,18 @@ You are using Tencent RTC MCP Server for SDK documentation retrieval.
   Use this tool FIRST for all technical documentation / FAQ / error code / integration guide lookups.
   Do NOT use web_search for questions that can be answered via this knowledge base.
 
+**Product routing（调用 search_trtc_knowledge 前 MUST 推断 product 数组）**：
+- TIMPush / 推送 / 厂商通道 / FCM / APNs / 华为 / 小米 / OPPO / vivo → product=["push"]（独立产品，禁止误归 chat）
+- 会话 / TUIKit / ChatKit / IM 组件 / 主题定制 → ["chat"]
+- CallKit / 通话 → ["call"]；直播 / 语聊房 / LiveKit → ["live"]；RoomKit / 会议 → ["room"]
+- TRTC Web SDK / rtcengine / WebRTC 插件 → ["rtcengine"]
+- TRTCCloud / Native SDK（客户端）→ ["native_trtc_sdk"]
+- 推送 + IM 同时涉及 → 可传 ["push","chat"]
+- 无法从 prompt 唯一判断 product → 先向用户确认，不要无 product 硬搜，也不要 web_search
+
+**Framework**：返回 needs_framework 时 MUST 先 present_framework_choice；详见 search_trtc_knowledge 工具 description 决策表。
+**When in doubt**：仍优先调用 search_trtc_knowledge（带最佳猜测 product）；status=empty 或 low_confidence 时再澄清或重搜。
+
 **queryID 传递规则（硬规则，违反会导致 CLS 数据断裂）**：
 - 首次调用 search_trtc_knowledge：无需传 queryID（默认空串），响应 JSON 中会有 server 生成的 queryID 字段
 - 后续每一次 search_trtc_knowledge / record_answer / record_feedback 调用：**MUST** 携带首次响应中的 queryID
@@ -18,6 +30,7 @@ Workflow:
 1. Call search_trtc_knowledge → synthesize answer from returned fragments (answer body only, no follow-up).
    - First call: no queryID (or empty string); extract queryID from response.
    - Subsequent calls: **MUST** pass the same queryID.
+   - If response includes meta.references or fragment doc_urls, append a「参考文档」section with those URLs at the end of your answer.
 2. MUST call record_answer (same prompt + same queryID) before outputting to the user.
    Pass the full answer text; record_answer returns the follow-up question text.
 3. Output a single message: your answer + the follow-up question text.
@@ -29,7 +42,7 @@ Workflow:
 export function createServer() {
     const server = new McpServer({
         name: "Tencent RTC MCP Server",
-        version: "1.6.0-beta.2",
+        version: "1.6.0",
     }, {
         instructions: SERVER_INSTRUCTIONS,
     });

package/tools/common/record_answer.js

@@ -10,7 +10,7 @@ const registryRecordAnswerTool = (mcpServer) => {
             answer: z.string().describe(parameter_descriptions.answer),
             product: z.enum(['chat', 'call', 'live', 'room', 'push', 'rtcengine', 'native_trtc_sdk']).optional().describe(parameter_descriptions.product),
             framework: z.enum(['react', 'vue', 'web', 'android', 'ios', 'flutter', 'c++', 'uni-app', 'harmonyos', 'react-native', 'unity', 'unreal-engine', 'donut']).optional().describe(parameter_descriptions.framework),
-            queryID: z.string().default("").describe(parameter_descriptions.queryID),
+            queryID: z.string().describe(parameter_descriptions.queryID),
         },
     }, (params) => {
         reportCLSClient({

package/tools/common/record_feedback.js

@@ -8,7 +8,7 @@ const registryRecordFeedbackTool = (mcpServer) => {
         inputSchema: {
             prompt: z.string().describe(parameter_descriptions.prompt),
             framework: z.enum(['react', 'vue', 'web', 'android', 'ios', 'flutter', 'c++', 'uni-app', 'harmonyos', 'react-native', 'unity', 'unreal-engine', 'donut']).optional().describe(parameter_descriptions.framework),
-            queryID: z.string().default("").describe(parameter_descriptions.queryID),
+            queryID: z.string().describe(parameter_descriptions.queryID),
             resolved: z.enum(['0', '1']).describe(parameter_descriptions.resolved),
         },
     }, (params) => {

package/tools/common/search_trtc_knowledge.js

@@ -11,7 +11,7 @@ const registrySearchTRTCKnowledgeTool = (mcpServer) => {
             prompt: z.string().describe(parameter_descriptions.prompt),
             product: z.array(z.enum(['chat', 'call', 'live', 'room', 'push', 'rtcengine', 'native_trtc_sdk'])).min(1).max(4).optional().describe(parameter_descriptions.product),
             framework: z.enum(['react', 'vue', 'web', 'android', 'ios', 'flutter', 'c++', 'uni-app', 'harmonyos', 'react-native', 'unity', 'unreal-engine', 'donut']).optional().describe(parameter_descriptions.framework),
-            queryID: z.string().default("").describe(parameter_descriptions.queryID),
+            queryID: z.string().describe(parameter_descriptions.queryID),
             types: z.array(z.enum([
                 'integration', 'component', 'feature', 'api', 'plugin',
                 'sdk', 'faq', 'error_code', 'product', 'server_api', 'webhook',

package/tools/definitions/record_answer_def.js

@@ -9,10 +9,11 @@ When to call:
 
 Input:
 - prompt: User's original question in full (required; must match the prompt used in get_faq / doc tools).
-- answer: Your complete final answer text (the full answer as delivered to the user; must NOT be a summary or truncated version).
+- answer: Your complete final answer text (the full answer as delivered to the user).
+  **Must NOT be a summary or truncated version** — except: if the answer exceeds 3000 characters and contains two or more of (pipe / backtick / quote / newline), simplify it first (remove redundant delimiters, collapse repeated lines), then pass the simplified version.
 - product: chat | call | live | room | push | rtcengine | native_trtc_sdk
 - framework: react | vue | web | android | ios | flutter | c++ | uni-app | harmonyos | react-native | unity | unreal-engine | donut
-- queryID: Query trace ID (optional). Must match the queryID returned by the first search_trtc_knowledge call.
+- queryID: Query ID. **REQUIRED**. Must match the queryID returned by search_trtc_knowledge (i.e. pass the queryID initially returned — first call's empty string is NOT acceptable here).
 
 Returns:
 - The follow-up question text as a plain string.
@@ -23,14 +24,14 @@ Boundaries:
 - This tool call is NOT silent — its return value is part of your answer.
 - The return value must be used as-is, without rephrasing.
 - Do NOT call this tool before the final answer is written to the user.
-- prompt is required and is stored in CLS text field for correlation with record_feedback.
+- Required params: prompt、answer、queryID（queryID is **REQUIRED** — must carry the non-empty queryID returned by search_trtc_knowledge; empty string is NOT acceptable）.
 `;
 const PARAMETER_DESCRIPTIONS = {
     prompt: "User's original question in full. Required. Must match the prompt from the documentation tool call.",
-    answer: "Agent's complete final answer text (full answer as delivered to the user; must NOT be a summary or truncated version).",
+    answer: 'Agent complete final answer. Keep as-is unless > 3000 chars with 2+ special chars (pipe backtick quote newline). In that case simplify (remove redundant delimiters, collapse lines) before passing.',
     product: 'Target product. One of: chat | call | live | room | push | rtcengine | native_trtc_sdk.',
     framework: 'Target platform. One of: react | vue | web | android | ios | flutter | c++ | uni-app | harmonyos | react-native | unity | unreal-engine | donut.',
-    queryID: 'Query trace ID. Optional. Must match the queryID returned by search_trtc_knowledge.',
+    queryID: 'Query ID. **REQUIRED**. Must match the non-empty queryID returned by search_trtc_knowledge on the same conversation chain. Empty string is NOT acceptable.',
 };
 export const RECORD_ANSWER_DEFINITION = {
     name: 'record_answer',

package/tools/definitions/record_feedback_def.js

@@ -12,7 +12,7 @@ When to call:
 Input:
 - prompt: User's original question in full (required; must match record_answer prompt).
 - framework: Target platform (optional; must match the framework from the original doc tool call). One of: react | vue | web | android | ios | flutter | c++ | uni-app | harmonyos | react-native | unity | unreal-engine | donut.
-- queryID: Query trace ID (optional). Must match the queryID from the search_trtc_knowledge call.
+- queryID: Query ID. **REQUIRED**. Must match the queryID returned by search_trtc_knowledge / record_answer (i.e. pass the non-empty queryID — empty string is NOT acceptable here).
 - resolved: 1 if the user confirms solved; 0 if not solved or needs more help.
 
 Returns:
@@ -27,7 +27,7 @@ Boundaries:
 const PARAMETER_DESCRIPTIONS = {
     prompt: "User's original question in full. Required. Must match the prompt used in record_answer.",
     framework: 'Target platform. Optional. Must match the framework from the original doc tool call. One of: react | vue | web | android | ios | flutter | c++ | uni-app | harmonyos | react-native | unity | unreal-engine | donut.',
-    queryID: 'Query trace ID. Optional. Must match the queryID from search_trtc_knowledge.',
+    queryID: 'Query ID. **REQUIRED**. Must match the non-empty queryID returned by search_trtc_knowledge on the same conversation chain. Empty string is NOT acceptable.',
     resolved: '1 if user confirms solved; 0 if user says not solved or needs more help.',
 };
 export const RECORD_FEEDBACK_DEFINITION = {

package/tools/definitions/search_trtc_knowledge_def.js

@@ -1,66 +1,31 @@
 const TOOL_DESCRIPTION = `
-用途：
-统一检索 Tencent RTC 咨询内容，返回与问题最相关的文档片段，供 Agent 合成答案。覆盖 FAQ、错误码、组件/API、feature 扩展、集成文档查阅等一切**非 codegen** 场景。
+凡 Tencent RTC 文档咨询（Chat/Call/Live/Room/Push/Web TRTC/Native TRTC）：FAQ、错误码、API、组件、feature、插件、集成查阅、排障 → MUST 先本工具。禁止 web_search。写接入代码 → get_*_integration。
 
-典型适用问题：
-- FAQ/排障/配置：FAQ, 常见问题, 排障, 鉴权失败, 控制台配置, 计费, 套餐, call faq, live faq, room faq, rtcengine faq, native trtc sdk faq, react faq, vue faq, web faq, android faq, ios faq, flutter faq, c++ faq, uni-app faq（**Chat 无独立 faq.md**；传 product=chat + framework 即可，types 含 faq 时会自动检索 knowledge/chat 下 preset 单功能与 urls 全文）
-- 错误码/鉴权：错误码, error code, ERR_, TXLiteAVCode, -4009, -13xx, 某个错误码含义, 某个错误码怎么处理, userSig 怎么生成, userSig 原理, userSig 签发流程, 服务端鉴权, Payload, IM 消息结构
-- 通用咨询句式：怎么用, 是什么, 有哪些步骤, 某个能力用哪个 API, 方法名是什么, 最新接口是什么, 参数怎么传, 回调怎么监听, 某个功能怎么设置, 某个功能怎么配置, 方法用法, 事件回调, 组件说明, API 说明, 组件属性, 组件示例, 组件事件, 查集成文档, 集成步骤查阅, 单功能查询, 单模块接入
-- **Push 推送服务**：TIMPush, 推送, 离线推送, 在线推送, 厂商推送, 通知, FCM, APNs, 华为, 小米, OPPO, vivo, 荣耀, 魅族, 厂商配置, 推送证书, 推送回调, 接入推送, TIMPush 集成, 角标, 铃声, 小图标, 跳转, 推送触达统计, donut（微信小程序多端框架）, harmonyos 推送, react-native 推送, unity 推送, unreal-engine 推送 → **MUST product=push**，**禁止**误归 chat（TIMPush 虽与 IM 同生态但已拆分为独立产品，自有 SDKAppID、自有控制台、自有文档）
-- Chat 聊天/IM（**仅限消息会话与 UIKit 组件，不含离线推送**）：Web Chat UIKit, Native Chat UIKit, ChatKit, TUIKit, IM SDK 消息收发, 会话, 聊天窗口, 组件详情, chat-header, conversation-list, conversation-preview, conversation-search, conversation-actions, message-list, message-input, contact-list, search, theme, 主题定制, 深色模式, UI 定制, TUITheme, Android Compose, UIKit, SwiftUI
-- Call：CallKit API, TUICallKit API, 含 UI API, 自定义 UI, calls, join, setSelfInfo, 来电铃声
-- Live：TUILiveKit, LiveKit State API, Store, State, 响应式数据, 字段, 方法签名, live-state, updateVideoQuality, 分辨率, 清晰度, PK 配置, 连麦状态, 主播端状态, 观众端状态, LiveView, LiveAudienceList, Barrage, CoGuestPanel, LiveScenePanel, StreamMixer, AtomicXCore, Core SDK, co_guest, co_host, 连麦, PK, 观众管理, 上麦, 麦位管理, 成员列表, 语聊房, 视频直播, 美颜, 音效, 弹幕, 礼物, BaseBeautyStore, AudioEffectStore, BarrageStore, GiftStore
-- Room：Atomicx API, 自定义模块, 组合式状态, useRoomState, useDeviceState, useRoomParticipantState, useRoomView, room-state, room-view, room-chat, screen-share, schedule-room, call-user-to-room, free-beauty-panel, virtual-background, 屏幕分享, 虚拟背景
-- TRTC Native：TRTC SDK, TRTCCloud, ITRTCCloud, 实时音视频, 互动直播, 多人音视频, 进房, 退房, enterRoom, exitRoom, 本地预览, 远端渲染, 回调, 事件监听, 参数结构, 类型定义, 编码参数, 统计信息, 音效, 美颜, 设备管理, 录制
-- Web TRTC/rtcengine：TRTC Web SDK, RTC Engine Web SDK, WebRTC, enterRoom, publish, subscribe, startLocalVideo, startLocalAudio, screen share, device, exception, TRTC Web SDK 插件, plugin, Beauty, BasicBeauty, VirtualBackground, Watermark, VideoMixer, FaceDetection, AudioMixer, AIDenoiser, VoiceChanger, RealtimeTranscriber, Chorus, CDNStreaming, CrossRoom, DeviceDetector, 水印, 合流, 降噪, 语音转写, 推流, 拉流
+**product**（能推断 MUST 传；不能确定先问用户）：
+push:TIMPush/推送/厂商/FCM/华为/小米/OPPO（≠chat）| chat:会话/TUIKit/IM/主题 | call:CallKit | live:LiveKit | room:RoomKit/会议
+rtcengine:Web TRTC | native_trtc_sdk:TRTCCloud | 跨域:["push","chat"]
 
-输入：
-- prompt: 用户的原始问题全文，保留完整上下文，不要压缩成关键词摘要
-- product: 目标产品数组。可选值：chat | call | live | room | push | rtcengine | native_trtc_sdk。**必须从 prompt 推断并填写**（见边界映射）。单产品传 ["chat"]，跨域问题（如离线推送+聊天）传 ["chat", "push"]。仅 prompt 完全无法判断产品时才省略
-- framework: react | vue | web | android | ios | flutter | c++ | uni-app | harmonyos | react-native | unity | unreal-engine | donut（平台相关咨询时，用户未说明则**先询问**，见边界；**harmonyos / react-native / unity / unreal-engine / donut 仅 push 产品适用**）
-- queryID: 查询追踪 ID（可选）。首次调用不传，服务器生成并返回。后续同一咨询链路的 search_trtc_knowledge / record_answer / record_feedback 应携带该 ID
-- types: integration | component | feature | api | plugin | sdk | faq | error_code | product | server_api | webhook（可选）
-- scenario: live | voice（可选，仅 live 产品）
-- limit: 返回片段数量，默认 8，最大 16
+**framework**（requires-framework.ts 顺序）：
+已传→检索 | needs_framework→present_framework_choice后重搜
+chat+错误码/ERR_→先问platform | native→MUST android/ios/c++ | rtcengine→隐式web
+push:厂商名≠平台(可不传);开通/接入/控制台/厂商配置可不传;含android/ios/flutter等→MUST
+计费/REST/Webhook/UserSig→可不传 | types仅server_api/webhook/product→可不传
+types含api/component/feature/plugin/sdk/integration→MUST | API/组件/enterRoom/SDK/插件/排障→MUST或先问
 
-必须流程（硬规则，平台相关咨询如「虚拟背景 API 怎么用」）：
-1. MUST 从 prompt 推断 **product**（如 push / rtcengine / live …）
-2. 用户未说明平台 → MUST **先**调用 \`present_framework_choice\`（传入 product），展示 android / ios / flutter / react / vue / uni-app 等选项；**禁止**跳过此步
-3. 用户选定后 → MUST 调用本工具并**同时传入 product + framework**；**禁止**传空 framework 硬搜；再基于 fragments 作答
+**types**：默认不传；开放["faq"]；明确REST/错误码/Webhook时再传。勿窄传component/api。
 
-返回：
-- JSON：status（success | low_confidence | empty | **needs_framework**）、fragments、meta、**queryID**（查询追踪 ID，**MUST 提取并透传给后续 search_trtc_knowledge / record_answer / record_feedback**）、message
-- \`needs_framework\`：**硬规则拦截**——未传 framework 且问题依赖具体平台；MUST 先 \`present_framework_choice\`，**禁止**空 framework 硬搜
+**L0/L1**：本地fragments仅基于片段答；chat/urls/须fetch官网URL，禁止臆造。
 
-**queryID 工作流**：
-- 首次调用无需传 queryID；响应中会带 server 生成的 queryID
-- 后续同一咨询链路的所有 search_trtc_knowledge / record_answer / record_feedback MUST 携带该 queryID
-- 不传 queryID = 视为新会话（CLS 数据无法串联）
-
-边界：
-- **product 必须从 prompt 提取**：调用前 MUST 根据用户原话推断 product 并传入，**不要**省略或留空（除非确实无法判断）。常见映射（**push 优先识别**）：**TIMPush/推送/通知/离线推送/在线推送/厂商推送/APNs/FCM/华为/小米/OPPO/vivo/荣耀/魅族 → \`push\`（独立产品，禁止误归 chat）**；ChatKit/TUIKit/IM 消息收发/会话/聊天窗口 → \`chat\`；CallKit/TUICallKit/通话/呼叫 → \`call\`；LiveKit/TUILiveKit/直播/语聊房 → \`live\`；RoomKit/TUIRoomKit/会议/房间 → \`room\`；Web TRTC/WebRTC/TRTC Web SDK → \`rtcengine\`；TRTC 原生 SDK/TRTCCloud/enterRoom（Native）→ \`native_trtc_sdk\`。无法唯一确定时先向用户确认，**不要**无 product 硬搜
-- **咨询与查阅专用**：FAQ、错误码、组件/API、feature 扩展、集成文档查阅（types 含 integration）
-- 用户明确要求 **写代码集成 / codegen** → 调用对应 \`get_*_integration\`，**不要**用本工具替代
-- **平台/框架未明确时 MUST 先询问（硬规则）**：问题涉及具体客户端/框架实现（组件怎么用、SDK API、feature 配置、客户端排障、集成步骤查阅等），但用户**未说明** react/vue/web/android/ios/flutter/c++ 等 → MUST **先**调用 \`present_framework_choice\`，等用户选定后再调用本工具并传入 framework；**禁止**猜测 framework、**禁止**省略询问直接检索
-- **跨平台可省略 framework**：产品简介、计费/套餐、服务端 REST、UserSig 签发原理、控制台配置等明显与单一客户端无关的问题，可直接调用本工具（**product 仍须从 prompt 提取**）
-- **rtcengine 仅支持 web**：传 product=rtcengine 时**无需再传 framework**（系统自动按 web 检索）
-- **native_trtc_sdk 强制平台**：product=native_trtc_sdk 时 **MUST** 传 framework（android / ios / c++），未传一律 \`needs_framework\` 拦截，禁止跨平台混检
-- **chat 错误码必须先问平台**：错误码映射页同时含「服务端 / Web SDK / Native SDK」三类 URL，product=chat + 错误码相关 prompt（或 types 含 error_code）时 **MUST** 先 \`present_framework_choice\`
-- **push 接入前综述可省略 framework**：prompt 含「接入前 / 准备 / 前置 / 注意事项 / 开通 / 流程总览 / 计费」等综述语义时，会自动放过；其他 push 咨询（android/ios/flutter/donut/...）**MUST** 传 framework
-- **禁止与外部搜索并行（仅适用于本地文档片段）**：fragments 来自 preset/integration/feature 等**本地全文**时 → **仅基于 fragments** 作答，**不要** web_search
-- **L1 URL 映射命中时必须自行抓取官网**：fragments 来自 \`knowledge/chat/urls/\`（restapi、webhook、error-code、product、sdk 等）时，这些片段**仅为 cloud.tencent.com / web.sdk.qcloud.com 入口表**，MCP 不本地维护 API/错误码全文 → MUST 从 fragments 匹配目标 URL 并**自行抓取**该官网文档后再作答；**禁止**仅复述映射表或臆造细节
-- **混合命中**：同时含本地文档与 URL 映射时，本地片段直接作答；映射片段须抓取 URL 后再答
-- **仅当知识库明显不足时补充**：\`status=empty\` 或无 URL 映射可 follow 时，向用户说明缺口；**仅在用户明确要求**时再考虑其他外部搜索
-- 作答后 MUST 调用 \`record_answer\`；用户反馈 → \`record_feedback\`
+**返回**：status(success|low_confidence|empty|needs_framework)、confidence(high|medium|low|none)、fragments（含doc_urls）、meta.references（参考链接列表）、meta.exact_hits(非空优先)、top_score/second_score、queryID(server)、message。作答末尾须附「参考文档」列出references/doc_urls。record_answer→record_feedback。
 `;
 const PARAMETER_DESCRIPTIONS = {
-    prompt: '用户的原始问题全文，保留完整上下文，不要压缩成关键词摘要。',
-    product: '目标产品数组。可选值：chat | call | live | room | rtcengine | native_trtc_sdk | push。**必须从 prompt 推断并填写**。映射（**push 优先识别**）：**TIMPush/推送/通知/离线推送/在线推送/厂商推送/APNs/FCM/华为/小米/OPPO/vivo/荣耀/魅族 → push**（独立产品，与 chat 解耦，禁止误归）。单产品传 ["chat"]；跨域问题（如离线推送+聊天）传 ["chat", "push"]。仅 prompt 完全无法判断产品时才省略或先向用户确认。',
-    framework: '目标平台或框架。参数名固定为 framework。可选值：react | vue | web | android | ios | flutter | c++ | uni-app | harmonyos | react-native | unity | unreal-engine | donut。**平台相关咨询时 MUST 填写**。**harmonyos / react-native / unity / unreal-engine / donut 仅 push 产品适用**（donut 对应微信小程序多端框架）。',
-    types: '语料类型过滤。可选值：integration | component | feature | api | plugin | sdk | faq | error_code | product | server_api | webhook。**Chat 无 faq.md**：product=chat 时 types 含 faq 会被忽略，等效检索 knowledge/chat 全量；Call/Live/Room 等仍有 faq.md 时可传 faq。',
-    scenario: '直播场景细分。可选值：live（视频直播）| voice（语聊房）。',
-    queryID: '查询追踪 ID（可选）。首次调用不传，服务器生成并返回 queryID；后续同一咨询链路的 search_trtc_knowledge / record_answer / record_feedback 应携带该 ID。',
-    limit: '返回片段数量，默认 8，最大 16。',
+    prompt: '用户原始问题全文，保留完整上下文，不要压缩成关键词摘要。',
+    product: '产品数组：chat|call|live|room|push|rtcengine|native_trtc_sdk。能推断 MUST 传；push优先(TIMPush/推送→push，禁止误归chat)。不能确定先问用户。',
+    framework: '平台：react|vue|web|android|ios|flutter|c++|uni-app|harmonyos|react-native|unity|unreal-engine|donut。按description决策表；harmonyos/react-native/unity/unreal/donut仅push适用。',
+    types: '默认不传；开放["faq"]。限定：integration|component|feature|api|plugin|sdk|error_code|product|server_api|webhook。勿主动窄传。',
+    scenario: 'live|voice，仅live产品。',
+    queryID: '首次\'\'，后续同一咨询MUST透传（见server）。',
+    limit: '片段数，默认8，最大16。',
 };
 export const SEARCH_KNOWLEDGE_DEFINITION = {
     name: 'search_trtc_knowledge',