@tencentcloud/sdk-mcp 1.6.7 → 1.6.8

package/knowledge/build-index.js

@@ -5,7 +5,10 @@ import { chunkMarkdown, toManifestChunk } from './chunker.js';
 import { buildDocSourceUrlMap } from './doc-url-resolver.js';
 import { inferPathMeta } from './path-meta.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const RESOURCE_ROOT = path.resolve(__dirname, '../../resource');
+// 构建期写入索引到 dist/resource/index/：
+//   dist/knowledge/ → ../resource/ → dist/resource/
+// 必须在 scripts/copy-resource.js 之后执行，否则目标目录不存在。
+const RESOURCE_ROOT = path.resolve(__dirname, '../resource');
 function walkMarkdownFiles(dir, baseRel) {
     if (!fs.existsSync(dir))
         return [];

package/knowledge/content-loader.js

@@ -4,7 +4,9 @@ import { fileURLToPath } from 'url';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const fileCache = new Map();
 function resolveResourceRoot() {
-    // npm: knowledge/ → ../resource/ 到包根；dev: dist/knowledge/ → ../resource/ 到 dist/resource/
+    // 运行时读 md 源目录（与 knowledge/ 同级的 resource/）：
+    //   npm 包：<pkg>/knowledge/  →  <pkg>/resource/
+    //   本地：  dist/knowledge/   →  dist/resource/（依赖 build 时 copy-resource.js）
     return path.resolve(__dirname, '../resource');
 }
 function readSourceFile(source) {

package/knowledge/search/filter-pool.js

@@ -1,4 +1,5 @@
 import { downgradeToProductType } from './product-scope-intent.js';
+import { normalizeQueryPrompt } from './query-normalizer.js';
 /**
  * MCP framework enum → index 中对应的 framework 值列表。
  * path-meta.ts 已通过 normalizeFrameworkDir 把目录名归一到标准 framework，
@@ -70,15 +71,16 @@ function inferImplicitFramework(products, frameworks, prompt) {
     return undefined;
 }
 export function normalizeParams(params) {
+    const normalizedPrompt = normalizeQueryPrompt(params.prompt);
     const limit = Math.min(Math.max(params.limit ?? 8, 1), 16);
-    const effectiveFramework = inferImplicitFramework(params.product, params.frameworks, params.prompt);
+    const effectiveFramework = inferImplicitFramework(params.product, params.frameworks, normalizedPrompt);
     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);
+    const types = resolveTypes(params.product, params.types, normalizedPrompt, requestedFrameworks);
     return {
-        prompt: params.prompt,
+        prompt: normalizedPrompt,
         product: params.product,
         framework: effectiveFramework,
         frameworks,
@@ -144,7 +146,13 @@ export function filterPool(chunks, norm) {
                 && chunk.variant === 'core-sdk'
                 && chunk.framework.includes('vue')
                 && chunk.source.includes('/api-reference/'));
-            if (!explicitMatch && !wildcardAllowed && !callCoreWebFallback && !liveWebVueFallback)
+            // Room 特例：Conference Web 实际语料在 roomkit/core-sdk/vue，web 查询应可命中。
+            const roomWebVueFallback = Boolean(norm.product?.includes('room')
+                && norm.framework === 'web'
+                && chunk.variant === 'core-sdk'
+                && chunk.framework.includes('vue')
+                && chunk.source.includes('knowledge/roomkit/core-sdk/vue/'));
+            if (!explicitMatch && !wildcardAllowed && !callCoreWebFallback && !liveWebVueFallback && !roomWebVueFallback)
                 return false;
         }
         if (norm.scenario && chunk.scenario && chunk.scenario !== norm.scenario) {

package/knowledge/search/query-normalizer.js

@@ -0,0 +1,76 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMA_ROOT = path.resolve(__dirname, '../../resource/_schema');
+const QUERY_NORMALIZATION_FILE = path.join(SCHEMA_ROOT, 'query-normalization.yaml');
+const MAX_APPEND_TOKENS = 6;
+let cachedConfig = null;
+function unquote(input) {
+    return input.trim().replace(/^['"]|['"]$/g, '');
+}
+function loadQueryNormalizationConfig() {
+    if (cachedConfig)
+        return cachedConfig;
+    const config = { literal: {}, word: {} };
+    if (!fs.existsSync(QUERY_NORMALIZATION_FILE)) {
+        cachedConfig = config;
+        return config;
+    }
+    const text = fs.readFileSync(QUERY_NORMALIZATION_FILE, 'utf-8');
+    let currentSection = '';
+    for (const rawLine of text.split('\n')) {
+        const line = rawLine.trimEnd();
+        if (!line.trim() || line.trimStart().startsWith('#'))
+            continue;
+        const sectionMatch = line.match(/^(literal|word):\s*$/);
+        if (sectionMatch) {
+            currentSection = sectionMatch[1];
+            continue;
+        }
+        const entryMatch = line.match(/^\s{2}([^:#]+):\s*\[(.*)\]\s*$/);
+        if (!entryMatch || !currentSection)
+            continue;
+        const key = unquote(entryMatch[1]);
+        const values = entryMatch[2]
+            .split(',')
+            .map((token) => unquote(token))
+            .filter(Boolean);
+        if (!key || !values.length)
+            continue;
+        config[currentSection][key] = values;
+    }
+    cachedConfig = config;
+    return config;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+export function normalizeQueryPrompt(prompt) {
+    const config = loadQueryNormalizationConfig();
+    const terms = new Set(prompt.split(/\s+/).filter(Boolean));
+    const promptLower = prompt.toLowerCase();
+    let appendedCount = 0;
+    const tryAppend = (tokens) => {
+        for (const token of tokens) {
+            if (appendedCount >= MAX_APPEND_TOKENS)
+                return;
+            if (!terms.has(token)) {
+                terms.add(token);
+                appendedCount += 1;
+            }
+        }
+    };
+    for (const [needle, expansion] of Object.entries(config.literal)) {
+        if (!prompt.includes(needle))
+            continue;
+        tryAppend(expansion);
+    }
+    for (const [needle, expansion] of Object.entries(config.word)) {
+        const pattern = new RegExp(`\\b${escapeRegExp(needle.toLowerCase())}\\b`, 'i');
+        if (!pattern.test(promptLower))
+            continue;
+        tryAppend(expansion);
+    }
+    return [...terms].join(' ');
+}

package/knowledge/search/search-knowledge.js

@@ -129,7 +129,16 @@ function hasBestPracticeFragment(fragments) {
 }
 function inferQueryApiTokens(prompt) {
     const tokens = new Set();
-    const upperNoise = new Set(['SDK', 'API', 'HTTP', 'HTTPS', 'JSON', 'CALL', 'NAME', 'STATUS']);
+    // 仅保留 API 形态 token，剔除产品/平台品牌词，避免把“TRTC Conference Web ...”误判为 API 缺口。
+    const upperNoise = new Set([
+        'SDK', 'API', 'HTTP', 'HTTPS', 'JSON', 'CALL', 'NAME', 'STATUS',
+        'TRTC', 'TENCENT', 'WEB', 'VUE', 'REACT', 'ROOMKIT', 'LIVEKIT', 'CALLKIT',
+    ]);
+    const platformNoise = new Set([
+        'ios', 'android', 'flutter', 'web', 'react', 'vue', 'miniprogram',
+        'harmonyos', 'react-native', 'unity', 'unreal', 'unreal-engine', 'donut', 'uni-app',
+        'pc', 'h5',
+    ]);
     for (const match of prompt.matchAll(/\b([a-z]+[A-Z][A-Za-z0-9_]*)\b/g)) {
         tokens.add(match[1]);
     }
@@ -150,7 +159,7 @@ function inferQueryApiTokens(prompt) {
         if (!upperNoise.has(token))
             tokens.add(token);
     }
-    return [...tokens];
+    return [...tokens].filter((token) => !platformNoise.has(token.toLowerCase()));
 }
 function tokenInChunk(token, chunk) {
     if (chunk.api_names?.some((name) => name.toLowerCase() === token.toLowerCase()))
@@ -171,6 +180,21 @@ function computeMissingApiTokens(tokens, candidates) {
         return [];
     return tokens.filter((token) => !candidates.some((chunk) => tokenInChunk(token, chunk)));
 }
+function hasProductScopeIntent(prompt) {
+    return /控制台|开通|开通服务|计费|套餐|价格|pricing|billing|plan|console|activate|activation|service/i.test(prompt);
+}
+function hasNativeTrtcApiSignal(prompt, queryApiTokens) {
+    if (/\bTRTCCloud\b|\bTRTCRenderParams\b|\bTXDeviceManager\b|setLocalRenderParams|startLocalPreview|stopLocalPreview/i.test(prompt)) {
+        return true;
+    }
+    return queryApiTokens.some((token) => /^(TRTC|TX)[A-Za-z0-9_]+$/.test(token)
+        || /^(set|get|start|stop|enable|disable)[A-Z][A-Za-z0-9_]+$/.test(token));
+}
+function hasNativeClientFramework(frameworks) {
+    if (!frameworks?.length)
+        return false;
+    return frameworks.some((fw) => ['android', 'ios', 'flutter', 'c++'].includes(fw));
+}
 function applyRankMultipliers(ranked, chunksById, opts) {
     const adjusted = ranked.map((item) => {
         const chunk = chunksById.get(item.id);
@@ -193,7 +217,12 @@ function applyRankMultipliers(ranked, chunksById, opts) {
                 && chunk.variant === 'core-sdk'
                 && chunk.framework.includes('vue')
                 && chunk.source.includes('/api-reference/'));
-            if (!explicitMatch && !callCoreWebFallback && !liveWebVueFallback) {
+            const roomWebVueFallback = Boolean(opts.product?.includes('room')
+                && opts.framework === 'web'
+                && chunk.variant === 'core-sdk'
+                && chunk.framework.includes('vue')
+                && chunk.source.includes('knowledge/roomkit/core-sdk/vue/'));
+            if (!explicitMatch && !callCoreWebFallback && !liveWebVueFallback && !roomWebVueFallback) {
                 multiplier *= 0.2;
             }
         }
@@ -360,7 +389,7 @@ export function searchKnowledge(params) {
         };
     };
     let pass = runSearchPass(norm);
-    let retryReason;
+    const retryReasons = [];
     // B2: API token 覆盖不足时触发一次扩检（去掉 types 约束 + api/integration 轻提权）
     const missingRatio = queryApiTokens.length > 0
         ? Number((pass.missingApiTokens.length / queryApiTokens.length).toFixed(2))
@@ -374,9 +403,44 @@ export function searchKnowledge(params) {
             || retryMissingRatio < missingRatio
             || (pass.fragments.length === 0 && retryPass.fragments.length > 0)) {
             pass = retryPass;
-            retryReason = `api_gap_retry:coverage=${pass.apiNameCoverage},missing_ratio=${retryMissingRatio}`;
+            retryReasons.push(`api_gap_retry:coverage=${pass.apiNameCoverage},missing_ratio=${retryMissingRatio}`);
+        }
+    }
+    // B3: 混合“集成 + 产品开通/计费/控制台”问法时，补充 product type，避免仅搜 integration/feature。
+    if (norm.types?.length && !norm.types.includes('product') && hasProductScopeIntent(norm.prompt)) {
+        const widenedTypes = [...new Set([...norm.types, 'product'])];
+        const retryPass = runSearchPass({ ...norm, types: widenedTypes });
+        const baseHasProduct = pass.fragments.some((f) => f.types.includes('product'));
+        const retryHasProduct = retryPass.fragments.some((f) => f.types.includes('product'));
+        if ((retryHasProduct && !baseHasProduct)
+            || (pass.fragments.length === 0 && retryPass.fragments.length > 0)
+            || (retryPass.fragments[0]?.score ?? 0) > (pass.fragments[0]?.score ?? 0) * 1.08) {
+            pass = retryPass;
+            retryReasons.push('product_scope_retry:types+=product');
+        }
+    }
+    // B4: 若疑似 Native TRTC API 问法却路由到 live/room/call，自动补扩 native_trtc_sdk 产品重检。
+    const shouldRetryNativeProduct = hasNativeClientFramework(norm.frameworks)
+        && hasNativeTrtcApiSignal(norm.prompt, queryApiTokens)
+        && norm.product?.some((p) => ['live', 'room', 'call'].includes(p))
+        && !norm.product?.includes('native_trtc_sdk')
+        && queryApiTokens.length > 0
+        && pass.apiNameCoverage < 0.5;
+    if (shouldRetryNativeProduct) {
+        const expandedProducts = [...new Set([...(norm.product ?? []), 'native_trtc_sdk'])];
+        const retryPass = runSearchPass({ ...norm, product: expandedProducts, types: undefined }, { apiRetry: true });
+        const retryMissingRatio = queryApiTokens.length > 0
+            ? Number((retryPass.missingApiTokens.length / queryApiTokens.length).toFixed(2))
+            : 0;
+        if (retryPass.apiNameCoverage > pass.apiNameCoverage
+            || retryPass.exactHits.length > pass.exactHits.length
+            || retryMissingRatio < missingRatio
+            || (pass.fragments.length === 0 && retryPass.fragments.length > 0)) {
+            pass = retryPass;
+            retryReasons.push(`native_product_retry:products=${expandedProducts.join('+')},coverage=${retryPass.apiNameCoverage}`);
         }
     }
+    const retryReason = retryReasons.length ? retryReasons.join(';') : undefined;
     const routeInconsistencyWarning = pass.fragments.length > 0
         ? pass.fragments.filter((f) => f.product === '*').length / pass.fragments.length > 0.3
         : false;
@@ -386,6 +450,40 @@ export function searchKnowledge(params) {
     const topScore = pass.fragments[0]?.score;
     const secondScore = pass.fragments[1]?.score;
     const answerContract = buildAnswerContract(status, confidence, { fabricationRisk });
+    const hasProductScope = hasProductScopeIntent(norm.prompt);
+    const hasNativeSignal = hasNativeTrtcApiSignal(norm.prompt, queryApiTokens);
+    const hasProductContent = pass.fragments.some((f) => f.types.includes('product') || /\/product\.md$/i.test(f.source));
+    const hasIntegrationContent = pass.fragments.some((f) => f.types.includes('integration') || /\/integration\.md$/i.test(f.source) || /\/preset\//i.test(f.source));
+    const hasApiQueryTokens = queryApiTokens.length > 0;
+    const apiGapDetected = hasApiQueryTokens && (pass.apiNameCoverage === 0 || missingRatio >= 0.3);
+    const retryApiGapApplied = retryReasons.some((r) => r.startsWith('api_gap_retry:'));
+    const retryProductScopeApplied = retryReasons.includes('product_scope_retry:types+=product');
+    const retryNativeProductApplied = retryReasons.some((r) => r.startsWith('native_product_retry:'));
+    const convergenceReached = status === 'success'
+        && (confidence === 'high' || confidence === 'medium')
+        && (!hasApiQueryTokens || pass.apiNameCoverage >= 0.5)
+        && (!hasProductScope || hasProductContent || hasIntegrationContent);
+    const retryAdvice = (() => {
+        if (status === 'needs_framework') {
+            return { stop_retry: true, next_action: 'ask_framework', reason: 'missing_framework' };
+        }
+        if (convergenceReached) {
+            return { stop_retry: true, next_action: 'answer', reason: 'converged' };
+        }
+        if (hasApiQueryTokens && apiGapDetected && !retryApiGapApplied) {
+            return { stop_retry: false, next_action: 'retry_widen_types', reason: 'api_coverage_gap' };
+        }
+        if (hasProductScope && !hasProductContent && !retryProductScopeApplied) {
+            return { stop_retry: false, next_action: 'retry_add_product_scope', reason: 'missing_product_scope_content' };
+        }
+        if (hasNativeSignal && hasNativeClientFramework(norm.frameworks) && !retryNativeProductApplied) {
+            return { stop_retry: false, next_action: 'retry_add_native_trtc_sdk', reason: 'possible_native_product_misroute' };
+        }
+        if (status === 'empty' || confidence === 'low') {
+            return { stop_retry: false, next_action: 'retry_or_clarify', reason: 'insufficient_retrieval_signal' };
+        }
+        return { stop_retry: true, next_action: 'answer', reason: 'default_stop' };
+    })();
     return {
         status,
         confidence,
@@ -408,6 +506,7 @@ export function searchKnowledge(params) {
             api_name_coverage: pass.apiNameCoverage,
             fabrication_risk: fabricationRisk,
             route_inconsistency_warning: routeInconsistencyWarning,
+            retry_advice: retryAdvice,
         },
         fragments: pass.fragments,
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencentcloud/sdk-mcp",
-  "version": "1.6.7",
+  "version": "1.6.8",
   "description": "Tencent Cloud MCP Server for SDK",
   "type": "module",
   "main": "index.js",

package/resource/_schema/feature-aliases.yaml

@@ -9,3 +9,4 @@ live:
 room:
   screen-share.md: ["屏幕分享", "screen share", "startScreenShare"]
   virtual-background.md: ["虚拟背景", "virtual background"]
+  device-state.md: ["conference", "会议", "开摄像头", "camera", "后端支持", "服务端支持"]

package/resource/_schema/query-normalization.yaml

@@ -0,0 +1,9 @@
+literal:
+  摄影头: ["摄像头"]
+  会议: ["roomkit", "conference"]
+  会议室: ["roomkit", "conference"]
+word:
+  conference: ["会议", "roomkit", "conference"]
+  meeting: ["会议", "roomkit", "conference"]
+  room: ["会议", "roomkit", "conference"]
+  roomkit: ["会议", "roomkit", "conference"]