@tencentcloud/sdk-mcp 1.6.8 → 1.7.1

package/tools/definitions/search_trtc_knowledge_def.js

@@ -1,6 +1,8 @@
 const TOOL_DESCRIPTION = `
 凡 Tencent RTC 文档咨询（Chat/Call/Live/Room/Push/Web TRTC/Native TRTC）：FAQ、错误码、API、组件、feature、插件、集成查阅、排障 → MUST 先本工具。禁止 web_search。写接入代码 → get_*_integration。
 
+**prompt 必须原样保留用户问题**：禁止扩写、发散、改写、补充 API 用法/场景描述。用户问什么就传什么原文。若需补充语义（如 API/事件/具体实现），用 types/frameworks/product 结构化参数表达，或另行搜索。
+
 **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"]
@@ -19,12 +21,12 @@ types含api/component/feature/plugin/sdk/integration→MUST | API/组件/enterRo
 
 **L0/L1**：本地fragments仅基于片段答；chat/urls/须fetch官网URL，禁止臆造。
 
-**返回**：status、confidence、fragments(doc_urls)、meta.references/exact_hits、top_score/second_score、queryID、message、meta.answer_contract。答案须严格遵守 answer_contract（结论先行、用户可执行、未确认显式化）；正文不展开证据链，且禁止输出“命中片段/检索结果/置信度”等系统话术，但末尾需保留“参考文档”并列出 references/doc_urls。最终回复前 MUST 调用 finalize_answer；明确 follow-up 反馈后调用 submit_feedback。
+**返回**：status、confidence、fragments(doc_urls)、meta.references、queryID、message、meta.answer_contract。答案遵守 answer_contract(完整输出、用户可执行、未确认显式化),禁止精简,禁止输出"命中片段/检索结果/置信度/分数"等系统话术,但末尾需保留"参考文档"并列出 references/doc_urls。最终回复前 MUST 调用 finalize_answer;明确 follow-up 反馈后调用 submit_feedback。
 `;
 const PARAMETER_DESCRIPTIONS = {
-    prompt: '用户原始问题全文，保留完整上下文，不要压缩成关键词摘要。',
+    prompt: '用户原始问题原文，MUST 原样透传，禁止扩写/发散/补充（如补 API 用法、场景、追问）。用户没说的不写进去；需补充语义用 types/frameworks 等结构化参数表达。',
     product: '产品数组：chat|call|live|room|push|rtcengine|native_trtc_sdk。能推断 MUST 传；push优先(TIMPush/推送→push，禁止误归chat)。live 常见关键词：LiveKit/直播/语聊房/TUILiveKit/AtomicXCore/开播/观看。不能确定先问用户。',
-    frameworks: '平台数组：react|vue|web|miniprogram|android|ios|flutter|c++|uni-app|harmonyos|react-native|unity|unreal-engine|donut。支持传多个平台用于跨端检索；CallKit 中 TUICallKit 建议按 react/vue 区分检索，TUICallEngine/TUICallEvent 仍归 web；小程序用 miniprogram；harmonyos/react-native/unity/unreal/donut仅push适用。',
+    frameworks: '平台数组：react|vue|web|miniprogram|android|ios|flutter|c++|uni-app|harmonyos|react-native|unity|unreal-engine|donut。支持传多个平台用于跨端检索；CallKit 中 TUICallKit 建议按 react/vue 区分检索，TUICallEngine/TUICallEvent 仍归 web；小程序用 miniprogram；harmonyos/react-native/unity/unreal/donut仅push适用。若未传且问题依赖具体客户端平台，必须先调用 present_framework_choice 询问后重搜。',
     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）。',

package/utils/fetch-doc-content.js

@@ -0,0 +1,198 @@
+/**
+ * fetch-doc-content.ts
+ *
+ * 在命中 chat/urls L1 URL 映射行时，由 server 内部 fetch 官网目标文档并清洗成
+ * markdown 返回给 AI，避免 AI 自行联网抓取（不可靠、拿到的还是整页 HTML）。
+ *
+ * 设计要点：
+ * - 白名单域名：仅允许 fetch 我们自己的 urls 映射里出现的官方域名，防 SSRF。
+ * - Node 22 原生 fetch 会自动解 gzip（解决 cloud.tencent.com 返回 gzip 导致乱码的问题）。
+ * - 内部分流函数 fetch 按 hostname 选策略：
+ *     - trtc.io（en 端 urls 主域名）：`url + '.md'` 直拿 text/markdown，跳过 cheerio 清洗
+ *     - 其他：cheerio + turndown 清洗 HTML（cloud.tencent.com / web.sdk.qcloud.com）
+ * - 内存缓存 + 超时 + 失败兜底（返回 null，不阻断原有检索）。
+ * - 对外函数 fetchDocContent 签名不变（l1-enrich 调用方无感知）。
+ * - 缓存 key 始终用原 URL（不带 .md 后缀），避免缓存 key 污染。
+ */
+import * as cheerio from 'cheerio';
+import TurndownService from 'turndown';
+/**
+ * 白名单域名：只允许这些域名的文档页被 fetch。
+ * 与 zh/resource/knowledge/chat/urls/ 和 en/resource/knowledge/chat/urls/ 下的映射保持一致。
+ */
+const ALLOWED_HOSTS = new Set([
+    'cloud.tencent.com',
+    'web.sdk.qcloud.com',
+    'trtc.io',
+]);
+/**
+ * 走"url + '.md' 直拿 markdown"策略的域名。
+ * 这类域名提供原生 markdown 视图（content-type=text/markdown），
+ * 比 cheerio+turndown 清洗 HTML 更干净、token 更省。
+ */
+const DIRECT_MD_HOSTS = new Set([
+    'trtc.io',
+]);
+const REQUEST_TIMEOUT_MS = 15000;
+/** 默认截断长度（字符），超过则按段落截断 */
+const DEFAULT_MAX_CHARS = 50000;
+/** 内存缓存：url -> markdown，避免同一咨询/相近请求重复打官网 */
+const cache = new Map();
+/** 判断 URL 是否命中白名单域名 */
+function isAllowedUrl(url) {
+    try {
+        const { hostname } = new URL(url);
+        return ALLOWED_HOSTS.has(hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 从 HTML 中提取正文容器（cheerio 按域名选择稳定容器）。
+ * 找不到时回退到更宽泛的选择器；仍找不到返回 null，交由调用方退化为整页清洗。
+ */
+function extractArticleSelector(hostname) {
+    if (hostname === 'cloud.tencent.com') {
+        // 腾讯云文档：正文在 #docArticleContent 内（SSR 直出），依次回退
+        return ['#docArticleContent', '#doc-slate-root', '.J-markdown-box'];
+    }
+    if (hostname === 'web.sdk.qcloud.com') {
+        // JSDoc 静态文档：正文在 #main 的 article 内
+        return ['#main article', '#main', 'article'];
+    }
+    return [];
+}
+/** 使用 turndown 将选中的 HTML 节点转成 markdown */
+function convertToMarkdown(html) {
+    const turndown = new TurndownService({
+        headingStyle: 'atx', // ## 风格标题
+        codeBlockStyle: 'fenced', // ``` 围栏代码块
+        bulletListMarker: '-',
+    });
+    turndown.remove(['script', 'style', 'nav', 'noscript', 'iframe']);
+    let md = turndown.turndown(html);
+    md = md
+        .replace(/[ \t]+\n/g, '\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+    return md;
+}
+/** 按段落截断到 maxChars */
+function truncateMarkdown(md, maxChars) {
+    if (md.length <= maxChars)
+        return md;
+    const head = md.slice(0, maxChars);
+    const lastBreak = head.lastIndexOf('\n\n');
+    return `${head.slice(0, lastBreak > 0 ? lastBreak : maxChars)}\n…[已截断]`;
+}
+/**
+ * 公共 fetch helper：带 timeout + 错误吞咽，把 Response 交给 handle 解析。
+ * 用 globalThis.fetch 避免与下方内部分流函数 fetch 同名冲突。
+ */
+async function fetchWithTimeout(url, handle) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    try {
+        const res = await globalThis.fetch(url, {
+            signal: controller.signal,
+            headers: {
+                'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36',
+                // 加 text/markdown 偏好，让 trtc.io 等支持 .md 后缀的站点优先返回 markdown
+                'Accept': 'text/markdown,text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+                'Accept-Language': 'zh-CN,zh;q=0.9,en;q=0.8',
+            },
+            // Node fetch 自动处理 gzip/deflate/br
+            redirect: 'follow',
+        });
+        if (!res.ok)
+            return null;
+        return await handle(res);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** cheerio+turndown 路径：处理 cloud.tencent.com / web.sdk.qcloud.com 等 HTML 文档 */
+async function fetchAndConvert(url, maxChars) {
+    return fetchWithTimeout(url, async (res) => {
+        const html = await res.text();
+        const { hostname } = new URL(url);
+        // cheerio 定位正文容器
+        const $ = cheerio.load(html);
+        const selectors = extractArticleSelector(hostname);
+        let article = selectors.map((sel) => $(sel)).find((node) => node.length > 0);
+        if (!article || article.length === 0) {
+            // 找不到容器时退化为 body 清洗（会偏大，但不丢正文）
+            article = $('body');
+        }
+        const markdown = convertToMarkdown(article.html() ?? '');
+        if (!markdown)
+            return null;
+        const truncated = markdown.length > maxChars;
+        const final = truncated ? truncateMarkdown(markdown, maxChars) : markdown;
+        return {
+            markdown: final,
+            truncated,
+            htmlBytes: Buffer.byteLength(html, 'utf-8'),
+        };
+    });
+}
+/**
+ * direct-md 路径：trtc.io 提供 `url + '.md'` 视图，
+ * content-type=text/markdown，可直接消费，跳过 cheerio 清洗。
+ * 失败时（content-type 不对 / 404）返回 null，让调用方走 fallback 路径。
+ */
+async function fetchDirectMarkdown(url, maxChars) {
+    const mdUrl = `${url}.md`;
+    return fetchWithTimeout(mdUrl, async (res) => {
+        const ct = res.headers.get('content-type') ?? '';
+        if (!/text\/markdown/i.test(ct))
+            return null;
+        const md = await res.text();
+        const truncated = md.length > maxChars;
+        return {
+            markdown: truncated ? truncateMarkdown(md, maxChars) : md,
+            truncated,
+            htmlBytes: 0,
+        };
+    });
+}
+/**
+ * 内部分流 fetch：按 hostname 选择策略。
+ * - DIRECT_MD_HOSTS 内的域名走 fetchDirectMarkdown；失败 fallback 到 fetchAndConvert。
+ * - 其他域名走 fetchAndConvert（cheerio+turndown）。
+ */
+async function fetch(url, hostname, maxChars) {
+    if (DIRECT_MD_HOSTS.has(hostname)) {
+        const direct = await fetchDirectMarkdown(url, maxChars);
+        // 防御：.md 视图失败时（如 content-type 不对、404）fallback 到 cheerio 路径
+        return direct ?? fetchAndConvert(url, maxChars);
+    }
+    return fetchAndConvert(url, maxChars);
+}
+/**
+ * fetch 官网文档并清洗为 markdown。
+ * 命中白名单才请求；失败/超时/非白名单一律返回 null，不抛错。
+ */
+export async function fetchDocContent(url, opts) {
+    if (!isAllowedUrl(url))
+        return null;
+    // 缓存 key 用原 URL（不带 .md），让 fetchDocContent 调用方透明
+    const cached = cache.get(url);
+    if (cached)
+        return { markdown: cached, truncated: false, htmlBytes: 0 };
+    const { hostname } = new URL(url);
+    const maxChars = opts?.maxChars ?? DEFAULT_MAX_CHARS;
+    const result = await fetch(url, hostname, maxChars);
+    if (result)
+        cache.set(url, result.markdown);
+    return result;
+}
+/** 清空内存缓存（测试/热更时用） */
+export function clearFetchDocCache() {
+    cache.clear();
+}

package/utils/preflight-route.js

@@ -0,0 +1,197 @@
+// ========== 信号分层（方案 §3，中英双语） ==========
+// 产品词：产品线路标识
+const PRODUCT_SIGNALS = {
+    call: /CallKit|TUICallKit|TUICallEngine|语音通话|视频通话|来电|去电|拨打|\b(?:voice|video)\s+calls?\b|incoming\s+calls?|outgoing\s+calls?|make\s+a\s+call|\bdial(?:ing)?\b/i,
+    live: /LiveKit|TUILiveKit|直播|语聊房|连麦|开播|观看直播|\blive\s+stream(?:ing)?\b|\bvoice\s+room\b|co-?host(?:ing)?|go\s+live|start\s+stream(?:ing)?|watch(?:ing)?\s+live|\bbroadcast(?:ing)?\b/i,
+    room: /RoomKit|会议|会中|会议室|屏幕分享|白板|\bconference\b|\bmeetings?\b|in-?meeting|meeting\s+room|screen\s+shar(?:e|ing)|white\s*board/i,
+    chat: /\bchat\b|\bim\b|会话|消息|TUIKit|ChatKit|\bconversation\b|\bmessaging\b|\binstant\s+messaging\b/i,
+    push: /TIMPush|推送|离线推送|FCM|APNs|华为|小米|OPPO|vivo|\bpush(?:\s+notification)?s?\b|offline\s+push|vendor\s+channel|\bHuawei\b|\bXiaomi\b|\bHonor\b/i,
+};
+// 平台词（纯运行形态，不含任何产品词）
+const PLATFORM_NATIVE_SIGNAL = /\b(android|ios|flutter|c\+\+|native)\b|安卓\s*(sdk|端|原生)|iOS\s*(SDK|端|原生)|原生\s*(sdk|端)?|native\s+(?:sdk|client|app)|mobile\s+(?:sdk|native)/i;
+const PLATFORM_WEB_SIGNAL = /\b(web|h5|html5|browser|webview)\b|浏览器|网页|Web端|H5端|网页端|web\s+(?:app|client|page)|in-?browser|mobile\s+browser|安卓\s*(浏览器|网页|H5|Web|webview)|iOS\s*(浏览器|网页|H5|Web|webview)|Android\s*(?:浏览器|网页|H5|Web|webview|browser|web)|iPad\s*(?:浏览器|网页|H5|Web|browser|web)|\b(Safari|Chrome|Edge|UC|QQ浏览器|QQ\s+Browser)\b/i;
+// 平台+产品复合词（运行形态 + 产品线路标识）
+const WEB_PRODUCT_PAIR_SIGNAL = /\bweb\s+(trtc|sdk|im|chat|roomkit)\b|\b(trtc|sdk|im|chat|roomkit)\s+web\b|trtc[-\s]?sdk|trtc\.js/i;
+// API 词（客户端调用形态）
+const NATIVE_TRTC_CLASS_SIGNAL = /\b(TRTCCloud|TRTCCloudListener|TRTCCloudDelegate|ITRTCCloud|TRTCTypeDef|TRTCCloudCallback|TXAudioEffectManager|TXBeautyManager|TXDeviceManager|TXLiteAVCode|TXLiveSDKTypeDef)\b/i;
+const NATIVE_TRTC_METHOD_SIGNAL = /\b(?:TRTCCloud|ITRTCCloud|TX[A-Za-z0-9_]+)\s*(?:\.|::|->)\s*(?:set|get|start|stop|enable|disable)[A-Z][A-Za-z0-9_]+\b/i;
+const WEB_TRTC_API_RE = /TRTC\.(setCurrentSpeaker|getMicrophoneList|getSpeakerList|getCameraList|isSupported|create)|trtc\.(startLocalAudio|startLocalVideo|updateLocalAudio|updateLocalVideo)/i;
+const WEB_TRTC_TOKEN_RE = /^TRTC\.(setCurrentSpeaker|getMicrophoneList|getSpeakerList|getCameraList|isSupported|create)$/i;
+// 协议级 TRTC 信号
+const TRTC_SIGNAL = /\bTRTC\b|\bWebRTC\b|rtcengine|TRTCCloud|腾讯实时音视频/i;
+// ========== 工具函数 ==========
+function uniq(list) {
+    return [...new Set(list)];
+}
+function extractQueryApiTokens(prompt) {
+    const matches = prompt.match(/\b(?:TRTC|trtc)\.[A-Za-z_][A-Za-z0-9_]*\b/g) ?? [];
+    return uniq(matches.map((m) => m.replace(/^trtc\./i, 'TRTC.')));
+}
+function collectPromptSignals(prompt) {
+    const products = new Set();
+    if (PRODUCT_SIGNALS.call.test(prompt))
+        products.add('call');
+    if (PRODUCT_SIGNALS.live.test(prompt))
+        products.add('live');
+    if (PRODUCT_SIGNALS.room.test(prompt))
+        products.add('room');
+    if (PRODUCT_SIGNALS.chat.test(prompt))
+        products.add('chat');
+    if (PRODUCT_SIGNALS.push.test(prompt))
+        products.add('push');
+    if (TRTC_SIGNAL.test(prompt))
+        products.add('trtc');
+    // 平台 tokens：web signal 锁定 → 压制 native 单字(安卓/iOS 仅归 hostEnv);
+    // 真复合词(unreal/unity/harmonyos/react-native/flutter/c++)不受影响。
+    const platforms = [];
+    const webLocked = PLATFORM_WEB_SIGNAL.test(prompt) || WEB_PRODUCT_PAIR_SIGNAL.test(prompt);
+    if (webLocked) {
+        platforms.push('web');
+    }
+    const nativeSpecificHits = [];
+    if (/\b(?:unreal|UE[45]?|unreal-engine)\b/i.test(prompt))
+        nativeSpecificHits.push('unreal-engine');
+    if (/\b(?:unity)\b/i.test(prompt))
+        nativeSpecificHits.push('unity');
+    if (/\b(?:harmonyos|鸿蒙|HarmonyOS)\b/i.test(prompt))
+        nativeSpecificHits.push('harmonyos');
+    if (/\b(?:react-native)\b/i.test(prompt))
+        nativeSpecificHits.push('react-native');
+    if (/\b(?:flutter)\b/i.test(prompt))
+        nativeSpecificHits.push('flutter');
+    if (/\b(?:c\+\+)\b/i.test(prompt))
+        nativeSpecificHits.push('c++');
+    // 安卓/iOS 单字只在非 web-locked 时进 platforms(web-locked 时仅归 hostEnv)
+    if (!webLocked && /\b(?:ios|iphone|ipad|苹果)\b/i.test(prompt))
+        nativeSpecificHits.push('ios');
+    if (!webLocked && /\b(?:android|安卓)\b/i.test(prompt))
+        nativeSpecificHits.push('android');
+    // 真复合词(如 unity/unreal/flutter/harmonyos/react-native/c++)无条件 push;单字在 webLocked 时被压制
+    if (nativeSpecificHits.length > 0) {
+        platforms.push(...nativeSpecificHits);
+    }
+    else if (!webLocked && PLATFORM_NATIVE_SIGNAL.test(prompt)) {
+        // 仅 "native" 词,未指定细分 → 默认 android(webLocked 时不触发 fallback,避免被 \b(android|ios|...) 反向命中把 web 路径覆盖成 native)
+        platforms.push('android');
+    }
+    // Host env：仅用于标记，不进 platforms 归一化
+    let hostEnv = null;
+    if (/\bios\b|iphone|ipad|苹果/i.test(prompt))
+        hostEnv = 'ios';
+    else if (/\bandroid\b|安卓/i.test(prompt))
+        hostEnv = 'android';
+    const queryApiTokens = extractQueryApiTokens(prompt);
+    const hasWebTrtcApi = PLATFORM_WEB_SIGNAL.test(prompt)
+        || WEB_TRTC_API_RE.test(prompt)
+        || queryApiTokens.some((t) => WEB_TRTC_TOKEN_RE.test(t));
+    const hasNativeTrtcApi = NATIVE_TRTC_CLASS_SIGNAL.test(prompt) || NATIVE_TRTC_METHOD_SIGNAL.test(prompt);
+    return { products, platforms, hostEnv, hasWebTrtcApi, hasNativeTrtcApi, queryApiTokens };
+}
+function reconcileWithPrompt(promptValues, explicit) {
+    // 核心规则：prompt 是真值源，explicit 只在 prompt 为空时启用。
+    // 这条规则必须严格遵守——
+    //   「prompt 是用户问题表达出来的真实意图」，explicit 只在外部上下文（IDE/文件/历史）有补充价值，
+    //   但 prompt 既然明示了「Web」，就要按 Web 来，不要因为 explicit 多了 'android' 就把它"补"进来当成双路。
+    // 情形 1：prompt 真值存在 → 信任 prompt 真值
+    //   - 即便 explicit 扩张（prompt 外多列了平台）→ 也只输出 prompt 真值（prompt_override=true 表示 agent 推理被忽略）
+    //   - 即便 explicit 收缩（prompt 真值的子集）→ 也只输出 prompt 真值（避免丢失用户意图）
+    if (promptValues.length > 0) {
+        const promptSet = new Set(promptValues);
+        const sameAsExplicit = !!explicit?.length
+            && explicit.length === promptValues.length
+            && explicit.every((v) => promptSet.has(v));
+        return { values: uniq(promptValues), corrected: !sameAsExplicit };
+    }
+    // 情形 2：prompt 真值无平台信息 → 信任上游 agent 基于上下文（IDE/文件/历史）的推理
+    if (!promptValues.length) {
+        return { values: uniq(explicit ?? []), corrected: false };
+    }
+    return { values: [], corrected: false };
+}
+// ========== Phase 3: 单 SearchParams 构造 ==========
+//
+// 关键约束：**永远只返回单 primary**，consumer 只跑一次 searchKnowledge。
+// multi-platform / multi-product 通过把 frameworks / product 设成数组交给 search core 处理。
+// search core 的 filterPool.applyRankMultipliers 已原生支持多值归并。
+function passthroughPlan(params, reason, env) {
+    return { primary: params, meta: { route_reason: reason, environment_downgraded: env } };
+}
+/** 单产品路径：product 是单值；frameworks 是数组（可能多平台共享一个 product） */
+function singleProductPlan(params, product, frameworks, hostEnv, reason) {
+    const envDiff = hostEnv != null && !frameworks.includes(hostEnv);
+    return {
+        primary: { ...params, product: [product], frameworks },
+        meta: { route_reason: reason, environment_downgraded: envDiff },
+    };
+}
+/** TRC 路径：product 是数组（rtcengine/native_trtc_sdk 两个产品码，按 platforms 各命中其一）；frameworks 也是数组 */
+function trcMultiProductPlan(params, products, frameworks, reason, env) {
+    return {
+        primary: { ...params, product: products, frameworks },
+        meta: { route_reason: reason, environment_downgraded: env },
+    };
+}
+// ========== 主入口（基于 prompt 真值归一化） ==========
+export function preflightRoute(params) {
+    const prompt = params.prompt ?? '';
+    const explicitFrameworks = params.frameworks?.length ? uniq(params.frameworks) : undefined;
+    const explicitProducts = params.product?.length ? uniq(params.product) : undefined;
+    // Phase 1
+    const signals = collectPromptSignals(prompt);
+    // —— 真跨主题（多产品信号）直接 passthrough
+    const nonTrtcProducts = [...signals.products].filter((p) => p !== 'trtc');
+    if (nonTrtcProducts.length > 1) {
+        return passthroughPlan(params, 'cross_product_passthrough', false);
+    }
+    // Phase 2: frameworks 调和
+    const fwRecon = reconcileWithPrompt(signals.platforms, explicitFrameworks);
+    const frameworks = fwRecon.values;
+    const envDowngraded = signals.hostEnv != null && !frameworks.includes(signals.hostEnv);
+    // Phase 2.5: products 调和（仅当 prompt 有非 TRTC 单产品时取此产品；TRTC 由 platform 推断 rtcengine/native_trtc_sdk）
+    const explicitTrtcBoth = explicitProducts?.includes('rtcengine') && explicitProducts?.includes('native_trtc_sdk');
+    const explicitTrtcAny = explicitProducts?.some((p) => p === 'rtcengine' || p === 'native_trtc_sdk') ?? false;
+    const isTrtcFamily = signals.products.has('trtc') || explicitTrtcBoth || (explicitTrtcAny && !nonTrtcProducts[0]);
+    // —— TRTC 家族：产物随平台分流
+    if (isTrtcFamily) {
+        const hasWeb = frameworks.includes('web');
+        const natives = frameworks.filter((f) => f !== 'web');
+        // TRTC + 多平台（web + native）→ product 数组，search core filterPool 原生接受多 product 交集
+        if (hasWeb && natives.length > 0) {
+            const reason = fwRecon.corrected ? 'trtc_multi_platform_prompt_override' : 'trtc_multi_platform';
+            return trcMultiProductPlan(params, ['rtcengine', 'native_trtc_sdk'], frameworks, reason, envDowngraded);
+        }
+        // TRTC + 仅 web
+        if (hasWeb) {
+            const reason = fwRecon.corrected ? 'trtc_web_prompt_override' : 'trtc_web';
+            return singleProductPlan(params, 'rtcengine', ['web'], signals.hostEnv, reason);
+        }
+        // TRTC + 仅 native
+        if (natives.length > 0) {
+            const reason = fwRecon.corrected ? 'trtc_native_prompt_override' : 'trtc_native';
+            return singleProductPlan(params, 'native_trtc_sdk', natives, signals.hostEnv, reason);
+        }
+        // TRTC 但 prompt / explicit 都没有可用平台 → 透传
+        return passthroughPlan(params, 'trtc_no_platform_resolved', false);
+    }
+    // —— 单非 TRTC 产品
+    if (nonTrtcProducts.length === 1) {
+        const product = nonTrtcProducts[0];
+        // 多平台 → product 单值，frameworks 多值（search core filterPool 原生按 framework 交集过滤）
+        if (frameworks.length >= 2) {
+            const reason = fwRecon.corrected ? 'multi_platform_prompt_override' : 'multi_platform';
+            return singleProductPlan(params, product, frameworks, signals.hostEnv, reason);
+        }
+        // 单平台
+        if (frameworks.length === 1) {
+            const reason = fwRecon.corrected ? 'single_platform_prompt_override' : 'single_platform';
+            return singleProductPlan(params, product, frameworks, signals.hostEnv, reason);
+        }
+        // 无平台信号：透传（保留 explicit frameworks）
+        if (explicitFrameworks?.length) {
+            return singleProductPlan(params, product, uniq(explicitFrameworks), signals.hostEnv, 'product_no_platform_explicit');
+        }
+        return passthroughPlan(params, 'product_no_platform_signal', false);
+    }
+    // —— 无产品信号：纯透传
+    return passthroughPlan(params, 'no_product_signal', false);
+}

package/utils/report-cls-client.js

@@ -32,7 +32,7 @@ function sendCLSReport(reportData) {
     const time = Date.now();
     const data = {
         platform: 'mcp',
-        verison: '1.6.8',
+        verison: '1.7.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.8',
+                version: '1.7.1',
                 sdkappid: `${SDKAppID}`,
                 method: method,
                 userID: `${userID}`,

package/resource/knowledge/callkit/best-practice/web/callengine-invitation.md

@@ -1,80 +0,0 @@
----
-product: 'Call'
-tech_stack: 'callengine'
-framework: 'web'
-doc_kind: 'best_practice'
-title: 'TUICallengine 通话处理'
-keywords: ['ON_CALL_RECEIVED', '通话邀请', '@trtc/call-engine-lite-js', 'calls', 'businessID', 'userData', 'callMediaType', 'calls', 'accept', 'onReceiveNewInvitation', 'onRecvNewMessage 自定义消息']
----
-
-# TUICallEngine Web 通话邀请接收与信令说明
-
-适用包：**@trtc/call-engine-lite-js**（TUICallEngine Web SDK）。
-
-## 一、如何接收通话邀请？
-
-**应用层应监听 `TUICallEvent.ON_CALL_RECEIVED`，而不是 TRTC Signaling 或 IM 自定义消息。**
-
-```javascript
-import { TUICallEngine, TUICallEvent } from '@trtc/call-engine-lite-js';
-
-const tuiCallEngine = TUICallEngine.createInstance({ SDKAppID: xxx, tim: timInstance });
-await tuiCallEngine.login({ userID, userSig });
-
-tuiCallEngine.on(TUICallEvent.ON_CALL_RECEIVED, (event) => {
-  console.log('来电', event);
-  // 展示接听 UI，随后 accept() 或 reject()
-});
-```
-
-### ON_CALL_RECEIVED 事件字段
-
-|参数|类型|含义|
-|---------|---------|---------|
-|callerId|String|邀请者。|
-|calleeIdList|Array<String>|同时还被邀请的人。|
-|isFromGroup|Boolean|是否是群组通话。|
-|inviteData|Object|呼叫数据。|
-|inviteID|String|邀请 ID，标识一次邀请。|
-|userData|String|扩展字段：用于在邀请信令中增加扩展信息。|
-|callId|String|本次通话的唯一 ID。|
-|roomID|Number|此次通话的音视频房间 ID。|
-|callMediaType|Number|通话的媒体类型，视频通话、语音通话。|
-|callRole|String|角色，枚举类型：主叫、被叫。|
-
-## 二、calls API 发送邀请时的参数有哪些？
-
-主叫通过 **`TUICallEngine.calls()`** 发起邀请：
-
-```javascript
-await tuiCallEngine.calls({
-  userIDList: ['user_bob'],
-  type: 2,                    // 1=语音 2=视频（CallMediaType）
-  userData: '{"ext":"info"}', // 可选，字符串
-  timeout: 30,                // 秒，默认 30
-  roomID: 123456,             // 数字房间号, 范围 [1, 2147483647]
-  strRoomID: '',              // 字符串房间号
-  chatGroupID: '',            // 在 Chat 群聊中多人通话时填写
-  offlinePushInfo: { /* … */ },
-});
-```
-
-## 三、在 Chat 中集成音视频通话时，如果需要处理通话消息上屏，自定义消息中的字段含义？
-
-|**问题**|**说明**|
-|---------|---------|
-|如何判断 “发起通话”|actionType = 1 且 cmd = 'videoCall' 或 'audioCall'|
-|如何判断 “已接听”|actionType = 3 |
-|如何判断 “通话已结束”，“通话时长是多少”|actionType = 1 且 cmd = 'hangup'，通话时长取 call_end 字段，单位：秒|
-|如何判断 “取消通话”|actionType = 2|
-|如何判断 “拒绝通话”|actionType = 4|
-|如何判断对端忙线产生的 “拒绝通话”|actionType = 4 且 cmd = "line_busy"|
-|如何被叫判断 “超时未接听”|actionType = 5|
-
-## 四、最佳实践摘要
-
-1. **只监听** `TUICallEvent.ON_CALL_RECEIVED`，用 `accept()` / `reject()` 响应。
-2. **不要**监听 `TIM.EVENT.MESSAGE_RECEIVED` 自行解析通话邀请。
-3. 扩展信息用 **`userData` 字符串**，主叫传入、被叫从事件读取。
-4. **`businessID` / 底层 payload 格式**属 SDK 内部实现；无官方公开文档前不要编造。
-5. **`@trtc/call-engine-lite-js` 4.x 起发起通话时需要传递自定义内容可以通过 `userData` 传递给被叫，不存在 `customData` 字段。

package/resource/knowledge/callkit/best-practice/web/callengine-log-control.md

@@ -1,20 +0,0 @@
----
-product: 'Call'
-tech_stack: 'callengine'
-framework: 'web'
-doc_kind: 'best_practice'
-title: 'TUICallengine 设置日志输出级别'
-keywords: ['控制台日志', '关闭 log', 'log level']
----
-
-# TUICallEngine 设置日志输出级别
-
-Web TUICallEngine 提供浏览器控制台日志输出控制接口 setLogLevel。
-日志级别分为以下几种：
-0 普通级别，日志量较多，接入时建议使用
-1 主要级别，SDK 输出关键信息，默认日志等级
-2 告警级别，SDK 只输出告警和错误级别的日志
-3 错误级别，SDK 只输出错误级别的日志
-4 无日志级别，SDK 将不打印任何日志
-
-文档：[setLogLevel](https://web.sdk.qcloud.com/component/trtccalling/doc/TUICallEngine/web/zh-cn/TUICallEngine.html#setLogLevel)