@tencentcloud/sdk-mcp 1.6.3 → 1.6.5

package/knowledge/search/exact-lookup.js

@@ -94,6 +94,50 @@ function loadFeatureAliases() {
     }
     return result;
 }
+const ROOM_CORE_SIGNAL = /atomicx\s*core|atomicxcore|atomicx|core\s*sdk|无\s*ui|自定义\s*ui|自实现|roomstore|store|useRoomState|useDeviceState|useLoginState/i;
+const ROOM_PRESET_SIGNAL = /预制|preset|roommainview|roommainwidget|默认\s*ui|主页面|房间主页面/i;
+const ROOM_FEATURE_SPECS = [
+    {
+        fileName: 'room-chat.md',
+        titlePattern: /room\s*chat|in-room\s*im\s*chat|会中聊天|聊天能力|IM\s*聊天/i,
+        promptPattern: /room\s*chat|会中聊天|in[- ]room\s*(im\s*)?chat|im\s*聊天|messagelist|messageinput|messagestore|聊天面板|房间聊天/i,
+    },
+    {
+        fileName: 'screen-share.md',
+        titlePattern: /screen\s*share|屏幕分享/i,
+        promptPattern: /screen\s*share|屏幕分享|共享屏幕|startScreenShare/i,
+    },
+    {
+        fileName: 'virtual-background.md',
+        titlePattern: /virtual\s*background|虚拟背景/i,
+        promptPattern: /virtual\s*background|虚拟背景|背景虚化|背景替换|initVirtualBackground/i,
+    },
+    {
+        fileName: 'room-view.md',
+        titlePattern: /roomview|room\s*view|房间主视图|视频布局/i,
+        promptPattern: /roomview|room\s*view|房间主视图|视频布局|画面布局|layoutTemplate/i,
+    },
+    {
+        fileName: 'device-detection.md',
+        titlePattern: /device\s*detection|设备检测|设备预览/i,
+        promptPattern: /device\s*detection|设备检测|设备预览|startCameraTest|startMicrophoneTest|startSpeakerTest/i,
+    },
+    {
+        fileName: 'device-state.md',
+        titlePattern: /device\s*state|设备状态|设备管理/i,
+        promptPattern: /device\s*state|设备状态|设备管理|摄像头|麦克风|扬声器|switchMirror|setCurrentCamera|networkInfo/i,
+    },
+    {
+        fileName: 'free-beauty-panel.md',
+        titlePattern: /free\s*beauty|美颜面板|基础美颜/i,
+        promptPattern: /free\s*beauty|美颜面板|基础美颜|beauty/i,
+    },
+];
+function detectRoomFeatureHits(prompt) {
+    return ROOM_FEATURE_SPECS.filter((spec) => spec.promptPattern.test(prompt));
+}
+const LIVE_LIFECYCLE_PROMPT = /开播|创建直播|结束直播|停播|观看直播|退出直播|进房|离房|createLive|endLive|joinLive|leaveLive|host_streaming|audience_streaming/i;
+const LIVE_LIFECYCLE_APIS = ['createLive', 'endLive', 'joinLive', 'leaveLive'];
 export function runExactLookup(prompt, pool, norm) {
     const boosts = {};
     const exactHits = [];
@@ -103,6 +147,9 @@ export function runExactLookup(prompt, pool, norm) {
         if (!exactHits.includes(label))
             exactHits.push(label);
     };
+    const addPenalty = (chunk, amount) => {
+        boosts[chunk.id] = (boosts[chunk.id] ?? 0) - Math.abs(amount);
+    };
     // E1: error codes
     const errorMatches = [
         ...prompt.matchAll(/\b(\d{5,7})\b/g),
@@ -326,5 +373,124 @@ export function runExactLookup(prompt, pool, norm) {
             addBoost(chunk, 120, `E8:integration-doc:${chunk.source}`);
         }
     }
+    // E9: chat faq——types=faq 时优先 knowledge 语料，避免 integration 文档内 FAQ 章节抢首位
+    if (norm.searchIntent?.includes('faq') && norm.product?.includes('chat')) {
+        const authPrompt = /auth|login|signature|usersig|鉴权|登录/i.test(prompt);
+        for (const chunk of pool) {
+            if (chunk.source.startsWith('knowledge/chat/')) {
+                const urlBoost = authPrompt && chunk.source.includes('/urls/') ? 180 : 100;
+                addBoost(chunk, urlBoost, 'E9:chat-faq:knowledge');
+            }
+            if (chunk.source.startsWith('integration/chat/')) {
+                addBoost(chunk, -120, 'E9:chat-faq:penalize-integration');
+            }
+        }
+    }
+    // E11: LiveKit 生命周期意图强召回（开播/停播/观看/退出）
+    if (norm.product?.includes('live') && LIVE_LIFECYCLE_PROMPT.test(prompt)) {
+        const queryApiHits = LIVE_LIFECYCLE_APIS.filter((api) => new RegExp(api, 'i').test(prompt));
+        for (const chunk of pool) {
+            const isLiveCoreIntegration = chunk.source.startsWith('knowledge/livekit/core-sdk/live/')
+                && chunk.source.endsWith('/integration.md');
+            const isVoiceCoreIntegration = chunk.source.startsWith('knowledge/livekit/core-sdk/voice/')
+                && chunk.source.endsWith('/integration.md');
+            if (!isLiveCoreIntegration && !isVoiceCoreIntegration)
+                continue;
+            if (norm.scenario === 'live' && !isLiveCoreIntegration)
+                continue;
+            if (norm.scenario === 'voice' && !isVoiceCoreIntegration)
+                continue;
+            addBoost(chunk, 140, 'E11:live-lifecycle-core-integration');
+            for (const api of queryApiHits) {
+                if (chunk.api_names?.some((name) => name.toLowerCase() === api.toLowerCase())) {
+                    addBoost(chunk, 160, `E11:live-lifecycle-api:${api}`);
+                }
+            }
+        }
+    }
+    // E10: roomkit Core/Preset 消歧 + unsupported feature 强召回
+    if (norm.product?.includes('room') && norm.frameworks?.length) {
+        const platform = norm.frameworks.find((fw) => ['android', 'ios', 'flutter', 'vue'].includes(fw));
+        const featureHits = detectRoomFeatureHits(prompt);
+        const coreIntent = ROOM_CORE_SIGNAL.test(prompt) || !ROOM_PRESET_SIGNAL.test(prompt);
+        const presetIntent = ROOM_PRESET_SIGNAL.test(prompt) && !ROOM_CORE_SIGNAL.test(prompt);
+        if (platform) {
+            const coreScope = `room:core-sdk:${platform}`;
+            const presetScope = `room:preset:${platform}`;
+            for (const chunk of pool) {
+                if (chunk.product !== 'room')
+                    continue;
+                if (chunk.scope === coreScope) {
+                    addBoost(chunk, 40, `E10:room-core-scope:${platform}`);
+                    if (platform !== 'vue' && chunk.doc_kind === 'capability_matrix') {
+                        addBoost(chunk, 120, `E10:room-matrix:${platform}`);
+                    }
+                }
+                if (coreIntent && chunk.scope === presetScope) {
+                    addPenalty(chunk, 120);
+                }
+                if (presetIntent && chunk.scope === coreScope && chunk.capability_status === 'unsupported') {
+                    addPenalty(chunk, 180);
+                }
+            }
+            for (const feature of featureHits) {
+                for (const chunk of pool) {
+                    if (chunk.product !== 'room')
+                        continue;
+                    if (platform === 'vue' && chunk.scope === coreScope && chunk.source.endsWith(feature.fileName)) {
+                        addBoost(chunk, 220, `E10:room-vue-feature:${feature.fileName}`);
+                    }
+                    if (platform !== 'vue' && chunk.scope === coreScope) {
+                        if (chunk.source.endsWith('unsupported-features.md') && feature.titlePattern.test(chunk.title)) {
+                            addBoost(chunk, 280, `E10:room-unsupported:${platform}:${feature.fileName}`);
+                        }
+                        if (chunk.doc_kind === 'capability_matrix') {
+                            addBoost(chunk, 120, `E10:room-matrix:${platform}:${feature.fileName}`);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // E12: CallKit Vue 混合类型问题消歧（状态机 STATUS 与 Core Store 类型分层召回）
+    if (norm.product?.includes('call')) {
+        const isStatusIntent = /statuschanged|\bstatus\b|callmediatype|媒体类型|通话状态|状态回调/i.test(prompt);
+        const isStoreIntent = /callstatus|callrole|iuserinfo|storename\.?call|store|name\s*常量|枚举值|字段定义/i.test(prompt);
+        const isEngineInvitationIntent = /tuicallengine|on_call_received|call\s*invitation|incoming\s*call|accept\(|reject\(|inviteid|userData|邀请|来电|接听|拒接|信令/i.test(prompt);
+        const isCallkitDiffIntent = /\bcall\s*vs\s*calls\b|\bcalls?\b|groupcall|tuicallkitapi\.calls|tuicallkitserver\.call|tuicallkitserver\.groupcall|\bv4(\.x)?\b|useridlist|chatgroupid|发起(单人|多人)?通话|呼叫|拨打/i.test(prompt);
+        const isLogIntent = /setloglevel|log\s*level|disable\s*log|console\s*log|日志级别|关闭\s*log/i.test(prompt);
+        for (const chunk of pool) {
+            if (chunk.product !== 'call')
+                continue;
+            const source = chunk.source.toLowerCase();
+            if (isStatusIntent && source.includes('knowledge/callkit/preset/vue/uikit-api-reference.md')) {
+                addBoost(chunk, 180, 'E12:callkit-vue-status');
+            }
+            if (isStoreIntent && source.includes('knowledge/callkit/core-sdk/web/')) {
+                addBoost(chunk, 220, 'E12:callkit-core-store');
+            }
+            if (isStoreIntent && source.includes('knowledge/callkit/preset/vue/')) {
+                addPenalty(chunk, 80);
+            }
+            if (isEngineInvitationIntent && source.includes('knowledge/callkit/best-practice/web/callengine-invitation.md')) {
+                addBoost(chunk, 300, 'E13A:callengine-invitation');
+            }
+            if (isEngineInvitationIntent && source.includes('knowledge/callkit/best-practice/web/callkit-call-vs-calls.md')) {
+                addPenalty(chunk, 80);
+            }
+            if (isCallkitDiffIntent && source.includes('knowledge/callkit/best-practice/web/callkit-call-vs-calls.md')) {
+                addBoost(chunk, 300, 'E13B:callkit-call-vs-calls');
+            }
+            if (isCallkitDiffIntent && source.includes('knowledge/callkit/best-practice/web/callengine-invitation.md')) {
+                addPenalty(chunk, 80);
+            }
+            if (isCallkitDiffIntent && source.includes('knowledge/callkit/preset/vue/uikit-api-reference.md')) {
+                addPenalty(chunk, 40);
+            }
+            if (isLogIntent && source.includes('knowledge/callkit/best-practice/web/callengine-log-control.md')) {
+                addBoost(chunk, 260, 'E13:callengine-log-control');
+            }
+        }
+    }
     return { boosts, exactHits };
 }

package/knowledge/search/filter-pool.js

@@ -3,15 +3,18 @@ import { downgradeToProductType } from './product-scope-intent.js';
  * MCP framework enum → index 中对应的 framework 值列表。
  * path-meta.ts 已通过 normalizeFrameworkDir 把目录名归一到标准 framework，
  * 所有产品的 framework 均已对齐枚举值，无需额外别名扩展。
- * web 匹配 react/vue/web（Chat/Call/Live Web 端覆盖）。
  */
 const FRAMEWORK_SEARCH_ALIASES = {};
-function expandFrameworks(framework) {
-    if (!framework)
+function expandFrameworks(frameworks, _products) {
+    if (!frameworks?.length)
         return undefined;
-    if (framework === 'web')
-        return ['react', 'vue', 'web'];
-    return FRAMEWORK_SEARCH_ALIASES[framework] ?? [framework];
+    const expanded = new Set();
+    for (const framework of frameworks) {
+        for (const alias of FRAMEWORK_SEARCH_ALIASES[framework] ?? [framework]) {
+            expanded.add(alias);
+        }
+    }
+    return [...expanded];
 }
 /**
  * 类型别名：UIKit「组件(component)」与「feature」是同一批文档的两种叫法
@@ -21,6 +24,7 @@ const TYPE_ALIASES = {
     component: ['component', 'feature'],
     feature: ['feature', 'component'],
 };
+const LIVE_LIFECYCLE_PROMPT = /开播|创建直播|结束直播|停播|观看直播|退出直播|进房|离房|createLive|endLive|joinLive|leaveLive|host_streaming|audience_streaming/i;
 function expandTypeAliases(types) {
     const expanded = new Set();
     for (const t of types) {
@@ -29,29 +33,50 @@ function expandTypeAliases(types) {
     }
     return [...expanded];
 }
-/** Chat 无独立 faq.md；types 含 faq 时退化到全语料检索（feature/component/urls 等均命中） */
-function resolveTypes(products, types, prompt, framework) {
+/**
+ * Chat FAQ 现已迁移到 best-practice 语料，types=faq 时应保留 faq 过滤，避免退化到全语料噪声。
+ */
+function resolveTypes(products, types, prompt, frameworks) {
     if (!types?.length)
         return undefined;
-    if (products?.includes('chat') && types.includes('faq')) {
-        return undefined;
+    const downgraded = downgradeToProductType(products, types, prompt, frameworks);
+    const expanded = expandTypeAliases(downgraded);
+    // Live 生命周期兼容：用户常传 types=['api']，但核心生命周期方法来自 core-sdk/live|voice/*/integration.md。
+    // 这里补充 core/integration，避免被类型硬过滤提前排除。
+    if (products?.includes('live') && expanded.includes('api') && LIVE_LIFECYCLE_PROMPT.test(prompt)) {
+        if (!expanded.includes('core'))
+            expanded.push('core');
+        if (!expanded.includes('integration'))
+            expanded.push('integration');
     }
-    const downgraded = downgradeToProductType(products, types, prompt, framework);
-    return expandTypeAliases(downgraded);
+    return expanded;
 }
 /** 单平台产品的隐式 framework 推断：避免对显然唯一的平台再发起询问 */
-function inferImplicitFramework(products, framework) {
-    if (framework)
-        return framework;
+function inferImplicitFramework(products, frameworks, prompt) {
+    if (frameworks?.length)
+        return frameworks[0];
     if (products?.length === 1 && products[0] === 'rtcengine')
         return 'web';
+    if (products?.includes('call')) {
+        if (/小程序|miniprogram/i.test(prompt))
+            return 'miniprogram';
+        if (/\breact\b/i.test(prompt))
+            return 'react';
+        if (/\bvue\b/i.test(prompt))
+            return 'vue';
+        if (/\b(web|h5|pc)\b|Web&H5/i.test(prompt))
+            return 'web';
+    }
     return undefined;
 }
 export function normalizeParams(params) {
     const limit = Math.min(Math.max(params.limit ?? 8, 1), 16);
-    const effectiveFramework = inferImplicitFramework(params.product, params.framework);
-    const frameworks = expandFrameworks(effectiveFramework);
-    const types = resolveTypes(params.product, params.types, params.prompt, effectiveFramework);
+    const effectiveFramework = inferImplicitFramework(params.product, params.frameworks, params.prompt);
+    const requestedFrameworks = params.frameworks?.length
+        ? params.frameworks
+        : effectiveFramework ? [effectiveFramework] : undefined;
+    const frameworks = expandFrameworks(requestedFrameworks, params.product);
+    const types = resolveTypes(params.product, params.types, params.prompt, requestedFrameworks);
     return {
         prompt: params.prompt,
         product: params.product,
@@ -79,18 +104,47 @@ const CROSS_PLATFORM_CHUNK_TYPES = new Set([
 function chunkIsCrossPlatform(chunkTypes) {
     return chunkTypes.some((t) => CROSS_PLATFORM_CHUNK_TYPES.has(t));
 }
+function normalizeScopeToken(input) {
+    return input.toLowerCase().replace(/[\s_\-]+/g, '');
+}
+function promptMatchesRetrievableScope(prompt, scope) {
+    if (!scope)
+        return true;
+    if (scope === 'always')
+        return true;
+    if (!scope.length)
+        return true;
+    const normalizedPrompt = normalizeScopeToken(prompt);
+    return scope.some((token) => normalizedPrompt.includes(normalizeScopeToken(token)));
+}
 export function filterPool(chunks, norm) {
     return chunks.filter((chunk) => {
         if (norm.product && !norm.product.includes(chunk.product) && chunk.product !== '*') {
             return false;
         }
+        // A1: 通配语料(share 等)必须命中 retrievable_scope 才能进入检索池
+        if (chunk.product === '*' && !promptMatchesRetrievableScope(norm.prompt, chunk.retrievable_scope)) {
+            return false;
+        }
         if (norm.frameworks?.length) {
             const isWildcardChunk = chunk.framework.includes('*');
             // 收紧：framework=['*'] 仅在该 chunk 明确是跨平台 type（product/server_api/webhook）时放行；
             // 否则要求 chunk.framework 与请求 framework 有交集。
             const wildcardAllowed = isWildcardChunk && chunkIsCrossPlatform(chunk.types);
             const explicitMatch = norm.frameworks.some((fw) => chunk.framework.includes(fw));
-            if (!explicitMatch && !wildcardAllowed)
+            // CallKit 特例：core-sdk 仍维持 web 单套（纯 JS），允许 react/vue 查询命中 core-sdk/web。
+            const callCoreWebFallback = Boolean(norm.product?.includes('call')
+                && (norm.framework === 'react' || norm.framework === 'vue')
+                && chunk.variant === 'core-sdk'
+                && chunk.framework.includes('web'));
+            // Live 特例：写写侧把 'Web' 平台归到 livekit/core-sdk/api-reference/{vue,web} 目录（写写节点名是 'Web'），
+            // 本地目录重命名为 'vue' 后 framework 标签变为 'vue'。'web' 查询仍应能命中这些 chunk。
+            const liveWebVueFallback = Boolean(norm.product?.includes('live')
+                && norm.framework === 'web'
+                && chunk.variant === 'core-sdk'
+                && chunk.framework.includes('vue')
+                && chunk.source.includes('/api-reference/'));
+            if (!explicitMatch && !wildcardAllowed && !callCoreWebFallback && !liveWebVueFallback)
                 return false;
         }
         if (norm.scenario && chunk.scenario && chunk.scenario !== norm.scenario) {

package/knowledge/search/product-scope-intent.js

@@ -24,8 +24,8 @@ export function isProductScopePrompt(prompt) {
  * rewrite the type to `product` so filterPool can hit chat/urls/product.md.
  * If a framework is present, the Agent genuinely wants a client feature — do not downgrade.
  */
-export function downgradeToProductType(products, types, prompt, framework) {
-    if (framework)
+export function downgradeToProductType(products, types, prompt, frameworks) {
+    if (frameworks?.length)
         return types;
     if (!types.includes('feature'))
         return types;

package/knowledge/search/requires-framework.js

@@ -44,7 +44,7 @@ function isChatErrorCodeAmbiguous(norm) {
 }
 /** 未传 framework 时，是否应先 present_framework_choice 再检索 */
 export function requiresFramework(norm) {
-    if (norm.framework)
+    if (norm.frameworks?.length)
         return false;
     // 硬规则：chat 错误码场景必须问平台（服务端 / Web / Native 三个 URL）
     if (isChatErrorCodeAmbiguous(norm))