@tencentcloud/sdk-mcp 1.7.8 → 1.7.9-beta.1

package/knowledge/chunker.js

@@ -130,6 +130,7 @@ function buildChunk(meta, source, title, body, id, char_start, char_end, extra)
         doc_kind: meta.doc_kind,
         capability_status: meta.capability_status,
         retrievable_scope: meta.retrievable_scope,
+        feature_domain: meta.feature_domain,
         meta_source: meta.meta_source,
         meta_override_fields: meta.meta_override_fields,
         title,

package/knowledge/frontmatter-meta.js

@@ -52,6 +52,24 @@ function normalizeRetrievableScope(value) {
         return 'always';
     return normalizeStringArray(value);
 }
+function normalizeFeatureDomain(value) {
+    const allowed = [
+        'app',
+        'app_demo',
+        'app_integration',
+        'device',
+        'device_demo',
+        'device_integration',
+        'security-camera',
+        'smart-vision',
+        'kids-watch',
+        'voice-recorder',
+        'client_api',
+    ];
+    return allowed.includes(value)
+        ? value
+        : undefined;
+}
 function parseFrontmatterObject(input) {
     if (!input || typeof input !== 'object' || Array.isArray(input)) {
         return {};
@@ -135,6 +153,11 @@ export function resolveFrontmatterMeta(rawMarkdown) {
         frontmatterMeta.retrievable_scope = retrievableScope;
         overrideFields.push('retrievable_scope');
     }
+    const featureDomain = normalizeFeatureDomain(fm.feature_domain);
+    if (featureDomain) {
+        frontmatterMeta.feature_domain = featureDomain;
+        overrideFields.push('feature_domain');
+    }
     return {
         content,
         contentOffset,

package/knowledge/path-meta.js

@@ -55,6 +55,23 @@ function inferShareScope(fileName) {
     }
     return 'always';
 }
+function inferIotFramework(normalizedPath) {
+    const pathLower = normalizedPath.toLowerCase();
+    if (pathLower.includes('miniprogram'))
+        return ['minprogram'];
+    if (pathLower.includes('react-native') || /\/(rn)\//.test(pathLower))
+        return ['rn'];
+    if (pathLower.includes('android'))
+        return ['android'];
+    if (pathLower.includes('ios'))
+        return ['ios'];
+    if (pathLower.includes('harmonyos'))
+        return ['harmonyos'];
+    if (pathLower.includes('linux-rtos') || pathLower.includes('/linux') || pathLower.includes('rtos')) {
+        return ['linux'];
+    }
+    return ['*'];
+}
 export function inferPathMeta(relativeSource) {
     const normalized = relativeSource.replace(/\\/g, '/');
     const parts = normalized.split('/');
@@ -69,6 +86,7 @@ export function inferPathMeta(relativeSource) {
     let doc_kind;
     let capability_status;
     let retrievable_scope;
+    let feature_domain;
     if (normalized.startsWith('knowledge/share/')) {
         // 通配语料（跨产品共享）显式建模，不再依赖默认兜底路径。
         product = '*';
@@ -76,6 +94,43 @@ export function inferPathMeta(relativeSource) {
         types.push('faq', 'product');
         retrievable_scope = inferShareScope(fileName);
     }
+    else if (normalized.startsWith('knowledge/iot/')) {
+        product = 'iot';
+        framework = inferIotFramework(normalized);
+        const top = parts[2] ?? '';
+        const topIsFeature = ['app', 'device', 'security-camera', 'smart-vision', 'kids-watch', 'voice-recorder'].includes(top);
+        const topIsApi = top === 'client-api';
+        if (topIsFeature) {
+            types.push('feature');
+        }
+        else if (topIsApi) {
+            types.push('api');
+        }
+        if (topIsFeature || topIsApi) {
+            if (top === 'app') {
+                if (parts[3] === 'demo')
+                    feature_domain = 'app_demo';
+                else if (parts[3] === 'integration')
+                    feature_domain = 'app_integration';
+                else
+                    feature_domain = 'app';
+            }
+            else if (top === 'device') {
+                if (parts[3] === 'demo')
+                    feature_domain = 'device_demo';
+                else if (parts[3] === 'integration')
+                    feature_domain = 'device_integration';
+                else
+                    feature_domain = 'device';
+            }
+            else if (top === 'client-api') {
+                feature_domain = 'client_api';
+            }
+            else {
+                feature_domain = top;
+            }
+        }
+    }
     else if (normalized.startsWith('knowledge/chat/') || normalized.startsWith('integration/chat/')) {
         product = 'chat';
         if (parts.includes('preset') && parts.length >= 4) {
@@ -386,6 +441,7 @@ export function inferPathMeta(relativeSource) {
         doc_kind,
         capability_status,
         retrievable_scope,
+        feature_domain,
         meta_source: 'path',
         meta_override_fields: [],
     };

package/knowledge/search/filter-pool.js

@@ -6,7 +6,12 @@ import { hasExplicitFrameworkMatch, hasFrameworkFallbackMatch } from './framewor
  * path-meta.ts 已通过 normalizeFrameworkDir 把目录名归一到标准 framework，
  * 所有产品的 framework 均已对齐枚举值，无需额外别名扩展。
  */
-const FRAMEWORK_SEARCH_ALIASES = {};
+const FRAMEWORK_SEARCH_ALIASES = {
+    miniprogram: ['miniprogram', 'minprogram'],
+    minprogram: ['minprogram', 'miniprogram'],
+    'react-native': ['react-native', 'rn'],
+    rn: ['rn', 'react-native'],
+};
 function expandFrameworks(frameworks, _products) {
     if (!frameworks?.length)
         return undefined;
@@ -166,6 +171,9 @@ export function isSoftAllowed(chunk, norm) {
     if (norm.scenario && chunk.scenario && chunk.scenario !== norm.scenario) {
         return false;
     }
+    // IoT 端别过滤改为“召回保留 + 排序分层”：
+    // Phase2 中 exact/common/conflict 的优先级由 applyRankMultipliers 处理，
+    // 这里不做硬过滤，避免因标注偏差误杀有效候选。
     // best-practice 文档对 types 过滤免疫：内容不依赖 types 分类，应始终进 pool 靠 BM25 自然排名。
     // 典型场景：Agent 传 types=['api'] 时，types=['faq'] 的 best-practice 不应被过滤掉。
     if (norm.types?.length && !norm.types.some((t) => chunk.types.includes(t))) {

package/knowledge/search/rank-profile.js

@@ -0,0 +1,25 @@
+const DEFAULT_PROFILE = {
+    name: 'default',
+    maxPerSource: 3,
+    rerankTopK: 20,
+    lowConfidenceRerankTopK: 0,
+    lowConfidenceTopScoreThreshold: 0,
+    lowConfidenceGapRatioThreshold: 0,
+    titleExactMultiplier: 1.03,
+    titleTokenBoost: 0.05,
+};
+const IOT_PROFILE = {
+    name: 'iot',
+    maxPerSource: 2,
+    rerankTopK: 24,
+    lowConfidenceRerankTopK: 10,
+    lowConfidenceTopScoreThreshold: 28,
+    lowConfidenceGapRatioThreshold: 1.08,
+    titleExactMultiplier: 1.15,
+    titleTokenBoost: 0.15,
+};
+export function resolveRankProfile(params) {
+    if (params.product?.includes('iot'))
+        return IOT_PROFILE;
+    return DEFAULT_PROFILE;
+}

package/knowledge/search/requires-framework.js

@@ -8,7 +8,7 @@ const PLATFORM_TYPES = new Set([
     'integration',
 ]);
 const CROSS_PLATFORM_TYPES = new Set(['server_api', 'webhook', 'product']);
-const CROSS_PLATFORM_PROMPT = /计费|套餐|价格|UserSig\s*原理|签发流程|控制台|服务端\s*REST|云\s*API|Webhook|回调|callback|server\s*callback/i;
+const CROSS_PLATFORM_PROMPT = /计费|套餐|价格|UserSig\s*原理|签发流程|控制台|服务端\s*REST|云\s*API|Webhook|回调|callback|server\s*callback|物联网开发平台|安防摄像头|智能视觉服务|儿童手表|录音卡/i;
 const PLATFORM_PROMPT = /API|组件|怎么用|怎么开|怎么设置|怎么配置|虚拟背景|屏幕分享|enterRoom|SDK|插件|集成步骤|客户端|Feature|主题定制|连麦|上麦/i;
 /**
  * push 必须问平台的强信号：仅当 prompt 明确提到具体「平台」（android/ios/flutter/...）时才拦询问。
@@ -60,6 +60,9 @@ export function requiresFramework(norm) {
             return false;
         return false;
     }
+    // iot：产品级/能力线/API 问法第一阶段允许跨平台检索，不做 framework 前置拦截
+    if (hasProduct(norm, 'iot'))
+        return false;
     // native_trtc_sdk：所有平台相关咨询都依赖具体客户端（android/ios/c++），必须先问
     if (hasProduct(norm, 'native_trtc_sdk'))
         return true;

package/knowledge/search/search-core.js

@@ -51,6 +51,7 @@ export function postProcess(ranked, chunksById, limit, opts) {
     }
     const sourceCount = {};
     const urlMappingSourceCount = {};
+    const maxPerSource = Math.max(1, opts?.maxPerSource ?? 3);
     /** 已入选的 push config/android/{vendor} 文件，用于抑制其他厂商噪声 */
     let selectedVendorFile = null;
     const fragments = [];
@@ -70,7 +71,7 @@ export function postProcess(ranked, chunksById, limit, opts) {
         }
         else {
             const count = sourceCount[chunk.source] ?? 0;
-            if (count >= 3)
+            if (count >= maxPerSource)
                 continue;
             sourceCount[chunk.source] = count + 1;
         }
@@ -384,7 +385,29 @@ export function hasNativeClientFramework(frameworks) {
         return false;
     return frameworks.some((fw) => ['android', 'ios', 'flutter', 'c++'].includes(fw));
 }
+function normalizeCompactText(input) {
+    return input.toLowerCase().replace(/[\s\-_]+/g, '');
+}
+function hasExactTitleMatch(prompt, title) {
+    if (!prompt || !title)
+        return false;
+    const p = normalizeCompactText(prompt);
+    const t = normalizeCompactText(title);
+    if (!p || !t)
+        return false;
+    return (t.length >= 3 && p.includes(t)) || (p.length >= 3 && t.includes(p));
+}
+function tokenizePromptForTitle(prompt) {
+    return [...new Set(prompt
+            .toLowerCase()
+            .split(/[^a-z0-9\u4e00-\u9fff]+/)
+            .map((s) => s.trim())
+            .filter((s) => s.length >= 2))];
+}
 export function applyRankMultipliers(ranked, chunksById, opts) {
+    const prompt = opts.prompt ?? '';
+    const promptTokens = tokenizePromptForTitle(prompt);
+    const isIotProfile = opts.rank_profile === 'iot';
     const adjusted = ranked.map((item) => {
         const chunk = chunksById.get(item.id);
         if (!chunk)
@@ -402,6 +425,38 @@ export function applyRankMultipliers(ranked, chunksById, opts) {
                 multiplier *= 0.2;
             }
         }
+        // Phase1: title/h2 与 query 精确短语命中增强
+        if (prompt && hasExactTitleMatch(prompt, chunk.title)) {
+            multiplier *= isIotProfile ? 1.15 : 1.03;
+        }
+        if (promptTokens.length > 0) {
+            const titleText = `${chunk.title} ${(chunk.key_phrases ?? []).join(' ')}`.toLowerCase();
+            const overlap = promptTokens.reduce((acc, token) => (titleText.includes(token) ? acc + 1 : acc), 0);
+            if (overlap > 0) {
+                multiplier *= 1 + Math.min(0.06, overlap * (isIotProfile ? 0.015 : 0.008));
+            }
+        }
+        // Phase2: IoT feature_domain 软回退（IoT 唯一排序信号）
+        if (chunk.product === 'iot') {
+            if (chunk.feature_domain && opts.preferred_iot_feature_domain) {
+                if (chunk.feature_domain === opts.preferred_iot_feature_domain)
+                    multiplier *= 1.15;
+                else
+                    multiplier *= 0.9;
+            }
+            // Phase2b: 强 feature 意图 → source 精准置顶
+            // 中文意图词（云台/语音对讲）与英文文件名（ptz-control/voice-intercom）无词面关系，
+            // 用 source 路径关键词精准命中 feature 文档，越过短文本泛文档的 BM25 优势。
+            if (opts.preferred_iot_feature_source && chunk.source.includes(opts.preferred_iot_feature_source)) {
+                multiplier *= 1.7;
+            }
+            // 非 demo 意图下，弱化 app_demo/device_demo 对功能问法的抢位
+            if (chunk.feature_domain && /demo$/i.test(chunk.feature_domain)) {
+                if (!/\bdemo\b|示例|sample|example|演示/i.test(prompt)) {
+                    multiplier *= 0.82;
+                }
+            }
+        }
         return { ...item, score: item.score * multiplier };
     });
     return adjusted.sort((a, b) => b.score - a.score);

package/knowledge/search/search-pass.js

@@ -8,6 +8,7 @@ import { computeGenericAnchorBoosts } from './generic-rerank.js';
 import { embedQuery, withQueryInstruction } from '../embedding/embed-model.js';
 import { queryVectors } from '../embedding/vector-index.js';
 import { applyRankMultipliers, computeApiNameCoverage, computeMissingApiTokens, isUrlMappingSource, postProcess, } from './search-core.js';
+import { resolveRankProfile } from './rank-profile.js';
 function isBestPracticeSource(source) {
     return /\/best-practice\//i.test(source);
 }
@@ -311,6 +312,74 @@ function stableSortRanked(items) {
         return a.id.localeCompare(b.id);
     });
 }
+function inferIotFeatureDomainFromPrompt(prompt) {
+    if (!prompt)
+        return undefined;
+    if (/安防摄像头|云台|\bPTZ\b|语音对讲|监控|回放|录像|录制|截图/i.test(prompt)) {
+        return 'security-camera';
+    }
+    if (/儿童手表/i.test(prompt))
+        return 'kids-watch';
+    if (/录音卡|语音卡/i.test(prompt))
+        return 'voice-recorder';
+    if (/智能视觉|视觉服务/i.test(prompt))
+        return 'smart-vision';
+    if (/设备端|linux|rtos|模组|芯片/i.test(prompt))
+        return 'device';
+    if (/客户端\s*api|client\s*api|\bTXIoT[A-Za-z0-9_]+\b/i.test(prompt))
+        return 'client_api';
+    if (/app\s*demo|示例工程|demo/i.test(prompt))
+        return 'app_demo';
+    if (/应用端接入|app接入|app\s*集成/i.test(prompt))
+        return 'app_integration';
+    return undefined;
+}
+/**
+ * IoT 强 feature 意图 → source 路径关键词映射。
+ * 中文意图词（云台/语音对讲）与英文文件名（ptz-control/voice-intercom）无直接词面关系，
+ * 需显式映射才能在排序层精准置顶对应 feature 文档，避免被短文本泛文档的 BM25 优势压制。
+ *
+ * 注意：仅收录「一 feature 一精准文件」的映射。像 monitor-playback 这类分布在
+ * 多端侧（app/device/security-camera）的 feature 不在此列，避免无差别 source boost
+ * 把 device 侧文档抬高、压制 app 侧（见 regression case 22）。
+ */
+const IOT_FEATURE_INTENT_MAP = [
+    { re: /云台|\bPTZ\b/i, keyword: 'ptz-control' },
+    { re: /语音对讲|对讲|intercom/i, keyword: 'voice-intercom' },
+];
+function inferIotFeatureSourceKeyword(prompt) {
+    if (!prompt)
+        return undefined;
+    for (const { re, keyword } of IOT_FEATURE_INTENT_MAP) {
+        if (re.test(prompt))
+            return keyword;
+    }
+    return undefined;
+}
+function inferPreferredIotFeatureDomain(ranked, chunksById, prompt) {
+    const byPrompt = inferIotFeatureDomainFromPrompt(prompt ?? '');
+    if (byPrompt)
+        return byPrompt;
+    const scoreByDomain = new Map();
+    const sampleWindow = Math.min(ranked.length, 80);
+    for (let i = 0; i < sampleWindow; i += 1) {
+        const item = ranked[i];
+        const chunk = chunksById.get(item.id);
+        if (!chunk || chunk.product !== 'iot' || !chunk.feature_domain)
+            continue;
+        const domain = chunk.feature_domain;
+        scoreByDomain.set(domain, (scoreByDomain.get(domain) ?? 0) + Math.max(item.score, 0));
+    }
+    let preferred;
+    let best = -1;
+    for (const [domain, score] of scoreByDomain.entries()) {
+        if (score > best) {
+            best = score;
+            preferred = domain;
+        }
+    }
+    return preferred;
+}
 function fuseByRRF(params) {
     const { bm25Ranked, vectorHits, rrfK, baseBeta, alpha, profile, } = params;
     const bmWeight = profile?.bmWeight ?? 1;
@@ -392,8 +461,35 @@ function resolveFusionProfile(prompt, queryApiTokens) {
     }
     return { name: 'default', bmWeight: 1.0, vecWeight: 1.0, alphaScale: 1.0 };
 }
+function normalizeCompactText(input) {
+    return input.toLowerCase().replace(/[\s\-_]+/g, '');
+}
+function hasTitleExactMatch(prompt, title) {
+    if (!prompt || !title)
+        return false;
+    const p = normalizeCompactText(prompt);
+    const t = normalizeCompactText(title);
+    if (!p || !t)
+        return false;
+    if (t.length >= 3 && p.includes(t))
+        return true;
+    if (p.length >= 3 && t.includes(p))
+        return true;
+    return false;
+}
+function shouldTriggerLowConfidenceRerank(params) {
+    const { ranked, rankProfile } = params;
+    if (rankProfile.lowConfidenceRerankTopK <= 0 || ranked.length < 2)
+        return false;
+    const top = ranked[0]?.score ?? 0;
+    const second = ranked[1]?.score ?? 0;
+    if (top <= 0)
+        return false;
+    const ratio = second > 0 ? top / second : Number.POSITIVE_INFINITY;
+    return top <= rankProfile.lowConfidenceTopScoreThreshold || ratio <= rankProfile.lowConfidenceGapRatioThreshold;
+}
 function rerankTopK(params) {
-    const { prompt, ranked, chunksById, topK } = params;
+    const { prompt, ranked, chunksById, topK, rankProfile, } = params;
     if (ranked.length < 2 || topK <= 0)
         return { ranked, applied: false };
     const head = ranked.slice(0, topK);
@@ -408,9 +504,13 @@ function rerankTopK(params) {
             return item;
         const text = [chunk.title, ...(chunk.key_phrases ?? [])].join(' ').toLowerCase();
         const overlap = promptTokens.reduce((acc, token) => (text.includes(token.toLowerCase()) ? acc + 1 : acc), 0);
-        if (overlap <= 0)
+        if (overlap <= 0 && !hasTitleExactMatch(prompt, chunk.title))
             return item;
-        const boost = topScore * 0.002 * overlap;
+        let boost = topScore * 0.002 * overlap;
+        if (hasTitleExactMatch(prompt, chunk.title)) {
+            boost += Math.max(topScore * 0.015, 1.5) * (rankProfile.titleExactMultiplier - 1);
+        }
+        boost += rankProfile.titleTokenBoost * overlap;
         return { ...item, score: item.score + boost };
     });
     const rerankedHead = stableSortRanked(bumped);
@@ -422,6 +522,7 @@ export async function runSearchPass(params) {
     const effectivePassNorm = retrievalMode === 'discovery'
         ? { ...passNorm, types: undefined }
         : passNorm;
+    const rankProfile = resolveRankProfile({ product: effectivePassNorm.product });
     let pool = filterPool(allChunks, effectivePassNorm);
     // types 误传自愈：首轮保留，二次扩检也同样保留该能力
     if (pool.length === 0 && effectivePassNorm.types?.length) {
@@ -468,7 +569,7 @@ export async function runSearchPass(params) {
     const baseBeta = readEnvNumber('VECTOR_AUGMENT_BASE_BETA', 0.3);
     const topK = Math.max(1, Math.floor(readEnvNumber('VECTOR_TOP_K', DEFAULT_VECTOR_TOP_K)));
     const rrfK = Math.max(1, Math.floor(readEnvNumber('VECTOR_RRF_K', DEFAULT_RRF_K)));
-    const rerankTopKLimit = Math.max(0, Math.floor(readEnvNumber('VECTOR_RERANK_TOP_K', DEFAULT_RERANK_TOP_K)));
+    const rerankTopKLimit = Math.max(0, Math.floor(readEnvNumber('VECTOR_RERANK_TOP_K', rankProfile.rerankTopK || DEFAULT_RERANK_TOP_K)));
     const fullDocumentMaxChars = Math.max(1000, Math.floor(readEnvNumber('SEARCH_FULL_DOCUMENT_MAX_CHARS', 7000)));
     let rankedFused = ranked;
     // 向量归因埋点采集（终态归因在函数末尾统一构造）：
@@ -536,6 +637,7 @@ export async function runSearchPass(params) {
                     ranked: fused.ranked,
                     chunksById,
                     topK: rerankTopKLimit,
+                    rankProfile,
                 });
                 rankedFused = reranked.ranked;
             }
@@ -545,12 +647,30 @@ export async function runSearchPass(params) {
             // 快照变量维持初始值即可。归因阶段 vector_top1_id 为 null 天然反映降级。
         }
     }
+    const preferredIotFeatureDomain = inferPreferredIotFeatureDomain(rankedFused, chunksById, passNorm.prompt);
+    const preferredIotFeatureSource = inferIotFeatureSourceKeyword(passNorm.prompt);
     const rankedWithMultipliers = applyRankMultipliers(rankedFused, chunksById, {
         product: passNorm.product,
         framework: passNorm.framework,
         frameworks: passNorm.frameworks,
+        preferred_iot_feature_domain: preferredIotFeatureDomain,
+        preferred_iot_feature_source: preferredIotFeatureSource,
+        prompt: passNorm.prompt,
+        rank_profile: rankProfile.name,
     });
-    const rankedAfterIntentGuard = applyDiagnosisIntentGuard(rankedWithMultipliers, chunksById, passNorm.prompt);
+    let rankedAfterIntentGuard = applyDiagnosisIntentGuard(rankedWithMultipliers, chunksById, passNorm.prompt);
+    if (shouldTriggerLowConfidenceRerank({ ranked: rankedAfterIntentGuard, rankProfile })) {
+        const secondPass = rerankTopK({
+            prompt: passNorm.prompt,
+            ranked: rankedAfterIntentGuard,
+            chunksById,
+            topK: rankProfile.lowConfidenceRerankTopK,
+            rankProfile,
+        });
+        if (secondPass.applied) {
+            rankedAfterIntentGuard = secondPass.ranked;
+        }
+    }
     const promptLockPolicy = decidePromptLockPolicy(passNorm.prompt);
     const allowContentPriority = promptLockPolicy.enableContentPriority;
     const allowFullDocumentLock = promptLockPolicy.enableFullDocumentLock;
@@ -593,6 +713,7 @@ export async function runSearchPass(params) {
         preferredSource: dominantBestPractice.preferredSource,
         fullDocumentMode: dominantBestPractice.fullDocumentMode,
         fullDocumentMaxChars,
+        maxPerSource: rankProfile.maxPerSource,
     });
     const urlMappingSources = [...new Set(fragments.map((f) => f.source).filter((source) => isUrlMappingSource(source)))];
     const references = buildReferences(fragments);

package/package.json

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