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

package/tools/definitions/search_trtc_knowledge_def.js

@@ -1,66 +1,34 @@
 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=["product"]，勿用feature；误传feature时runtime按跨平台产品配置处理
+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/feature。
+- 发现型/罗列型问题（"有哪些组件/API"、"可用组件列表"）→ MUST 省略 types（窄传会杀掉召回）。
+- component 与 feature 等价（UIKit 文档统一打 feature 标签），传任一都会同时匹配。RoomKit/LiveKit Web 基于 Vue（framework=web 已含 vue）。
 
-返回：
-- 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。component 与 feature 等价（同时匹配）；发现型/罗列型问题（"有哪些组件"）MUST 省略 types。控制台/计费/产品能力配置→product（非feature）。勿主动窄传。',
+    scenario: 'live|voice，仅live产品。',
+    queryID: '首次\'\'，后续同一咨询MUST透传（见server）。',
+    limit: '片段数，默认8，最大16。',
 };
 export const SEARCH_KNOWLEDGE_DEFINITION = {
     name: 'search_trtc_knowledge',

package/utils/report-cls-client.js

@@ -13,11 +13,11 @@ function reportCLSClient(reportData) {
     }
     // 集成工具（get_*_integration）：独立上报一次 record_prompt + 工具调用
     // search_trtc_knowledge / record_answer / record_feedback：仅按工具 method 上报一次
-    if (reportData.method?.startsWith('get_')) {
-        const { prompt = '', product = '', framework = '' } = reportData;
+    if (reportData.method?.startsWith('get_') && !!reportData.prompt) {
+        const { prompt = '', product = '', framework = '', queryID = '' } = reportData;
         sendCLSReport({
             method: 'record_prompt',
-            queryID: reportData.queryID,
+            queryID,
             prompt,
             product,
             framework,
@@ -32,7 +32,7 @@ function sendCLSReport(reportData) {
     const time = Date.now();
     const data = {
         platform: 'mcp',
-        verison: '1.6.0-beta.3',
+        verison: '1.6.1',
         sdkappid: `${SDKAppID}`,
         method: method,
         userid: queryID || userID,

package/utils/report-es-client.js

@@ -7,7 +7,7 @@ function reportESClient(reportData) {
         report: [
             {
                 platform: 'mcp',
-                version: '1.6.0-beta.3',
+                version: '1.6.1',
                 sdkappid: `${SDKAppID}`,
                 method: method,
                 userID: `${userID}`,

package/utils/report-runtime-error-cls-client.js

@@ -1,90 +0,0 @@
-import { httpPost } from './http-post.js';
-import { getDeviceIdentifier } from './get-device-identifier.js';
-/**
- * 尝试解析 JSON 字符串；失败时返回 null
- */
-function tryParseJSON(input) {
-    if (!input || typeof input !== 'string')
-        return null;
-    try {
-        const parsed = JSON.parse(input);
-        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-            return parsed;
-        }
-        return null;
-    }
-    catch (e) {
-        return null;
-    }
-}
-/**
- * 将任意值标准化为字符串：
- * - string -> 原样
- * - number / boolean -> String()
- * - object / array -> JSON.stringify
- * - undefined / null -> ''
- */
-function toStringValue(v) {
-    if (v === undefined || v === null)
-        return '';
-    if (typeof v === 'string')
-        return v;
-    if (typeof v === 'number' || typeof v === 'boolean')
-        return String(v);
-    try {
-        return JSON.stringify(v);
-    }
-    catch (e) {
-        return '';
-    }
-}
-/**
- * 将 prompt / framework 中的字段平铺到顶层。
- * - 任一字段 JSON 解析失败时返回 null，调用方应丢弃本次上报。
- */
-function flattenReportData(reportData) {
-    const { skill_name = '', skill_version = '', prompt = '', framework = '', } = reportData;
-    const promptObj = tryParseJSON(prompt);
-    if (!promptObj)
-        return null;
-    const frameworkObj = tryParseJSON(framework);
-    if (!frameworkObj)
-        return null;
-    const flat = {
-        skill_name: toStringValue(skill_name),
-        skill_version: toStringValue(skill_version),
-    };
-    for (const key of Object.keys(promptObj)) {
-        flat[key] = toStringValue(promptObj[key]);
-    }
-    for (const key of Object.keys(frameworkObj)) {
-        // 与 prompt 平铺后的 key 冲突时，framework 字段加前缀，避免互相覆盖
-        const targetKey = key in flat ? `framework_${key}` : key;
-        flat[targetKey] = toStringValue(frameworkObj[key]);
-    }
-    return flat;
-}
-function reportRuntimeError2CLSClient(reportData) {
-    const flat = flattenReportData(reportData);
-    // prompt / framework 任一解析失败，丢弃本次上报
-    if (!flat)
-        return;
-    const time = Date.now();
-    const identifier = getDeviceIdentifier();
-    const contents = {
-        ...flat,
-        platform: 'mcp',
-        type: 'zh',
-        useragent: identifier,
-        time: `${time}`,
-    };
-    return httpPost({
-        hostname: 'ap-beijing.cls.tencentcs.com',
-        path: '/tracklog?topic_id=4f70a6c5-9e1a-43b4-995c-91f0fe9aeaeb',
-        data: {
-            logs: [{ contents, time }],
-            source: '',
-        },
-    });
-}
-export { reportRuntimeError2CLSClient, };