@tencent-rtc/mcp 1.6.3 → 1.6.5

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

@@ -12,7 +12,7 @@ const CROSS_PLATFORM_PROMPT = /计费|套餐|价格|UserSig\s*原理|签发流
 const PLATFORM_PROMPT = /API|组件|怎么用|怎么开|怎么设置|怎么配置|虚拟背景|屏幕分享|enterRoom|SDK|插件|集成步骤|客户端|Feature|主题定制|连麦|上麦/i;
 /**
  * push 必须问平台的强信号：仅当 prompt 明确提到具体「平台」（android/ios/flutter/...）时才拦询问。
- * 厂商（小米/OPPO/华为/FCM 等）不算平台——它们会命中写写对齐后的平台级配置页（如 knowledge/push/config/android.md），
+ * 厂商（小米/OPPO/华为/FCM 等）不算平台——它们全部归属 android 厂商配置子分类（knowledge/push/config/android/{vendor}.md），
  * 问厂商问题不需要再让用户选平台。
  */
 const PUSH_PLATFORM_SPECIFIC_PROMPT = /\b(android|ios|flutter|harmonyos|react[\s-]?native|unity|unreal|donut|uni[\s-]?app)\b/i;
@@ -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))

package/knowledge/search/search-knowledge.js

@@ -74,16 +74,26 @@ function postProcess(ranked, chunksById, limit) {
             if (topScore > 0 && item.score < topScore * 0.05)
                 break;
         }
+        const contentWithHint = chunk.contains_code
+            ? `【代码示例，须与目标端一致】\n${chunk.content}`
+            : chunk.content;
         fragments.push({
             rank: fragments.length + 1,
             score: item.score,
             title: chunk.title,
-            content: chunk.content,
+            content: contentWithHint,
             source: chunk.source,
             doc_urls: resolveFragmentDocUrls(chunk.source, chunk.content, getSourceFileContent(chunk.source)),
             product: chunk.product,
             framework: chunk.framework,
             types: chunk.types,
+            variant: chunk.variant,
+            scope: chunk.scope,
+            doc_kind: chunk.doc_kind,
+            capability_status: chunk.capability_status,
+            api_names: chunk.api_names,
+            contains_code: chunk.contains_code,
+            citation: `[来源: ${chunk.id}]`,
             chunk_id: chunk.id,
         });
         if (fragments.length >= limit)
@@ -112,62 +122,168 @@ function partitionFragments(fragments) {
     const urlMappingKinds = [...new Set(urlMapping.map((f) => isUrlMappingSource(f.source)).filter(Boolean))];
     return { urlMapping, localDoc, urlMappingKinds };
 }
+function hasBestPracticeFragment(fragments) {
+    return fragments.some((f) => /\/best-practice\//i.test(f.source));
+}
+function inferQueryApiTokens(prompt) {
+    const tokens = new Set();
+    const upperNoise = new Set(['SDK', 'API', 'HTTP', 'HTTPS', 'JSON', 'CALL', 'NAME', 'STATUS']);
+    for (const match of prompt.matchAll(/\b([a-z]+[A-Z][A-Za-z0-9_]*)\b/g)) {
+        tokens.add(match[1]);
+    }
+    for (const match of prompt.matchAll(/\b([A-Z][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*)\b/g)) {
+        tokens.add(match[1]);
+    }
+    for (const match of prompt.matchAll(/\b(use[A-Z]\w*)\b/g)) {
+        tokens.add(match[1]);
+    }
+    for (const match of prompt.matchAll(/\b(I[A-Z][A-Za-z0-9_]*)\b/g)) {
+        tokens.add(match[1]);
+    }
+    for (const match of prompt.matchAll(/\b([A-Z][A-Za-z0-9_]*\.[A-Z_][A-Z0-9_]*)\b/g)) {
+        tokens.add(match[1]);
+    }
+    for (const match of prompt.matchAll(/\b([A-Z_]{3,})\b/g)) {
+        const token = match[1];
+        if (!upperNoise.has(token))
+            tokens.add(token);
+    }
+    return [...tokens];
+}
+function tokenInChunk(token, chunk) {
+    if (chunk.api_names?.some((name) => name.toLowerCase() === token.toLowerCase()))
+        return true;
+    if (chunk.symbols?.some((name) => name.toLowerCase() === token.toLowerCase()))
+        return true;
+    const low = token.toLowerCase();
+    return chunk.title.toLowerCase().includes(low) || chunk.source.toLowerCase().includes(low);
+}
+function computeApiNameCoverage(tokens, candidates) {
+    if (!tokens.length)
+        return 1;
+    const hit = tokens.filter((token) => candidates.some((chunk) => tokenInChunk(token, chunk))).length;
+    return Number((hit / tokens.length).toFixed(2));
+}
+function computeMissingApiTokens(tokens, candidates) {
+    if (!tokens.length)
+        return [];
+    return tokens.filter((token) => !candidates.some((chunk) => tokenInChunk(token, chunk)));
+}
+function applyRankMultipliers(ranked, chunksById, opts) {
+    const adjusted = ranked.map((item) => {
+        const chunk = chunksById.get(item.id);
+        if (!chunk)
+            return item;
+        let multiplier = 1;
+        // A2: 传了 product 时，命中 scope 的通配语料允许召回但降权
+        if (opts.product?.length && chunk.product === '*') {
+            multiplier *= 0.2;
+        }
+        // F2: framework 软降权（保留硬过滤，处理 fallback/边界残留）
+        if (opts.framework && opts.frameworks?.length && !chunk.framework.includes('*')) {
+            const explicitMatch = opts.frameworks.some((fw) => chunk.framework.includes(fw));
+            const callCoreWebFallback = Boolean(opts.product?.includes('call')
+                && (opts.framework === 'react' || opts.framework === 'vue')
+                && chunk.variant === 'core-sdk'
+                && chunk.framework.includes('web'));
+            const liveWebVueFallback = Boolean(opts.product?.includes('live')
+                && opts.framework === 'web'
+                && chunk.variant === 'core-sdk'
+                && chunk.framework.includes('vue')
+                && chunk.source.includes('/api-reference/'));
+            if (!explicitMatch && !callCoreWebFallback && !liveWebVueFallback) {
+                multiplier *= 0.2;
+            }
+        }
+        return { ...item, score: item.score * multiplier };
+    });
+    return adjusted.sort((a, b) => b.score - a.score);
+}
 /**
- * P0-3：相对阈值的置信度评估。
- * - high：top ≥ 50 或有精确命中（exactHits 非空）
- * - medium：top ≥ 10 且 top / second ≥ 1.3（区分度足够）
- * - low：top 较低或与 second 接近（同水位竞争，agent 应谨慎）
- * - none：fragments 为空
+ * 多因子置信度评估：exact 命中 + 分数梯度 + API 覆盖度。
  */
-function assessConfidence(fragments, exactHits) {
+function assessConfidence(fragments, exactHits, apiNameCoverage, queryApiTokens) {
     if (fragments.length === 0) {
         return { confidence: 'none', status: 'empty' };
     }
     const top = fragments[0].score;
     const second = fragments[1]?.score ?? 0;
-    if (exactHits.length > 0 || top >= 50) {
-        return { confidence: 'high', status: 'success' };
-    }
     const ratio = second > 0 ? top / second : Infinity;
-    if (top >= 10 && ratio >= 1.3) {
-        return { confidence: 'medium', status: 'success' };
-    }
-    if (top >= 5 && ratio >= 1.15) {
-        return { confidence: 'medium', status: 'success' };
+    let confidence;
+    if (exactHits.length > 0 || top >= 50)
+        confidence = 'high';
+    else if (top >= 12 && ratio >= 1.25)
+        confidence = 'medium';
+    else if (top >= 6 && ratio >= 1.12)
+        confidence = 'medium';
+    else
+        confidence = 'low';
+    // D2: API 覆盖过低时，confidence 上限降为 low
+    if (queryApiTokens.length > 0 && apiNameCoverage < 0.3) {
+        confidence = 'low';
     }
-    return { confidence: 'low', status: 'low_confidence' };
+    const status = confidence === 'low' ? 'low_confidence' : 'success';
+    return { confidence, status };
+}
+function buildAnswerContract(status, confidence, opts) {
+    const uncertaintyRule = status === 'low_confidence' || confidence === 'low'
+        ? '当信息不足时必须显式写“待确认：”，只允许陈述缺口，不允许猜测补全。'
+        : '除“待确认：”段落外，不得出现“可能/大概/应该/推测”等猜测措辞。';
+    const riskRule = opts?.fabricationRisk
+        ? 'fabrication_risk=true 时，若片段未覆盖该细节，必须输出“待确认：知识片段未覆盖此项”。'
+        : '';
+    return [
+        '【输出模板（必须遵守）】',
+        '使用“问题导向”标题组织答案，优先复用用户提问原句：一、<问题1> 二、<问题2> 三、<问题3> …',
+        '每个小节先给直接结论，再补 1-2 句必要说明；避免模板化术语（如“依据/操作”字样）。',
+        '信息缺口统一放在对应小节末尾，使用“待确认：xxx”；若全都确认则可省略“待确认”小节。',
+        '末尾保留“参考文档”小节，仅列文档标题或 URL；正文不展示检索过程、证据链、打分细节。',
+        '用户可见正文禁止出现系统检索话术（如“命中片段/检索结果/置信度/分数/召回/重排”）。',
+        '硬约束：不得引入 fragments 未出现的 API 名、字段值、枚举项、事件名。',
+        uncertaintyRule,
+        riskRule,
+    ].filter(Boolean).join(' ');
 }
-function buildAgentMessage(status, fragments, confidence, references) {
-    const citeTail = references?.length
-        ? 'When answering, MUST append a **References** section listing only **https** URLs from `meta.references` (or each fragment\'s `doc_urls`). Do not invent links. Do **not** list local repo paths such as `knowledge/...` or `integration/...` — users cannot open those.'
-        : 'If fragments include `doc_urls`, append a **References** section with those **https** URLs only. Do **not** cite `fragment.source` local paths. If no online URLs are available, omit the References section rather than listing local file paths.';
-    const tail = `${citeTail} Final answer drafted -> MUST call \`finalize_answer\` before replying. Explicit follow-up feedback -> call \`submit_feedback\`.`;
+function buildAgentMessage(status, fragments, confidence, _references, opts) {
+    const platformRule = '端别硬规则：字段/API 描述前先标注【端别: framework】；禁止“部分版本也称 xxx”这类跨端混写；字段大小写必须与目标端文档一致；多端片段同时命中时主答案仅讲目标端，其他端差异放末尾简述；无片段覆盖的细节禁止补全。';
+    const riskRule = opts?.fabricationRisk ? '当前检索存在幻觉风险（fabrication_risk=true）：禁止补全未命中 API 细节。' : '';
+    const answerContract = buildAnswerContract(status, confidence, opts);
+    const tail = `${platformRule} ${riskRule} ${answerContract} Final answer drafted -> MUST call \`finalize_answer\` before replying. Explicit follow-up feedback -> call \`submit_feedback\`.`;
     if (status === 'needs_framework') {
-        return '[Hard rule] This question depends on a specific platform but no framework was provided; cross-platform search is low-signal and disallowed. MUST call `present_framework_choice` (with product), wait for the user to pick android/ios/flutter/react/vue/uni-app, then call this tool again with **product + framework**. Do not search with an empty framework.';
+        return '【硬规则】问题依赖具体平台实现，但未指定 frameworks，全平台混检信息密度低且被禁止。MUST 先调用 `present_framework_choice`（传入 product），等用户选定 web/miniprogram/android/ios/flutter/react/vue/uni-app 等后再调用本工具，并 MUST 带上 **product + frameworks**。禁止传空 frameworks 硬搜。';
     }
     const { urlMapping, localDoc, urlMappingKinds } = partitionFragments(fragments);
     const hasUrlMapping = urlMapping.length > 0;
     const hasLocalDoc = localDoc.length > 0;
+    const hasBestPractice = hasBestPracticeFragment(fragments);
     const urlKindLabel = urlMappingKinds.join(' / ') || 'urls';
     if (status === 'success' && fragments.length > 0) {
-        const confidenceHint = confidence === 'high' ? '(confidence=high)'
-            : confidence === 'medium' ? '(confidence=medium; top vs runner-up separation is moderate—confirm with the user if unsure)'
-                : '';
+        const topFragment = fragments[0];
+        if (topFragment?.capability_status === 'unsupported') {
+            const scopeLabel = topFragment.scope ? `（${topFragment.scope}）` : '';
+            return `当前问题在该平台 / 形态下 **不支持**${scopeLabel}。回答 MUST：① 第一段先明确写“**不支持**”；② 说明这是当前平台 Core 的能力边界，而不是缺少示例代码；③ 仅提供当前平台已支持的替代方案（如对应平台 preset 预制 UI）；若当前知识库未给出明确替代形态，应直接说明暂无可执行替代路径；④ **禁止**输出当前平台 Core 的 API 调用步骤或集成步骤。${tail}`;
+        }
         if (hasUrlMapping && !hasLocalDoc) {
-            return `Knowledge base hit **L1 URL map**${confidenceHint} (${urlKindLabel}, ${urlMapping.length} fragment(s)). These fragments are **documentation entry URLs only** (cloud.tencent.com / web.sdk.qcloud.com, etc.), not full REST API / error-code / webhook text. MUST: ① match the user's question to the **target URL** in fragments; ② **fetch** that official doc before answering; ③ do not restate the map table or invent API/error details.${tail}`;
+            return `当前可用信息主要是文档入口链接（${urlKindLabel}）。请先匹配用户问题对应的目标 URL，抓取官网文档后再合成答案；禁止仅复述映射表或臆造 API/错误码细节。${tail}`;
         }
         if (hasUrlMapping && hasLocalDoc) {
-            return `Knowledge base returned ${fragments.length} fragment(s)${confidenceHint}: ${localDoc.length} local doc + ${urlMapping.length} URL map (${urlKindLabel}). Answer directly from **local doc** fragments (preset/integration, etc.); for **URL map** fragments MUST extract the target URL and **fetch** the official doc—do not restate the map table.${tail}`;
+            if (hasBestPractice) {
+                return `优先基于已命中的 best-practice 与本地片段直接作答；URL 映射仅作补充参考，不要再抓官网做二次求证。${tail}`;
+            }
+            return `本地文档片段可直接用于作答；若本地片段未覆盖关键细节，再从 URL 映射中提取目标 URL 抓取官网文档补齐。${tail}`;
         }
-        return `Knowledge base returned ${fragments.length} valid fragment(s)${confidenceHint}. Synthesize the answer **only from fragments**; do **not** run web_search or fetch docs separately.${tail}`;
+        return `请仅基于已返回 fragments 合成答案；不要并行 web_search 或额外抓取官网文档。${tail}`;
     }
     if (status === 'low_confidence') {
         if (hasUrlMapping) {
-            return `Low confidence (confidence=low: top score weak or too close to runner-up) but URL map hit (${urlKindLabel}). Extract target URLs from fragments and **fetch** official docs; tell the user if the map does not cover their question.${tail}`;
+            if (hasBestPractice) {
+                return `优先基于 best-practice 与本地片段给出可执行结论；未覆盖的内容统一写入“待确认”，不要默认抓官网二次求证。${tail}`;
+            }
+            return `请先从 URL 映射里提取目标 URL 并抓取官网文档补齐关键信息，再给出答案；仍无法确认的内容明确写“待确认”。${tail}`;
         }
-        return `Low confidence (confidence=low: top score weak or too close to runner-up; may not match the question). Answer from available fragments and **state uncertainty**; ask for a more specific query (component / API / error code) and retry. Do **not** default to web_search.${tail}`;
+        return `请基于已有 fragments 给出最可执行答案，并将未覆盖细节明确写为“待确认”；可引导用户补充组件名/API 名/错误码后重新检索。不要默认并行 web_search。${tail}`;
     }
-    return `No valid fragments matched. Tell the user and verify product/framework; if the question needs a client platform, call \`present_framework_choice\` first.${tail}`;
+    return `知识库未命中有效片段。请向用户说明并确认 product/framework 是否准确；若仍无 platform 信息且问题依赖具体客户端，应先 \`present_framework_choice\`。${tail}`;
 }
 export function searchKnowledge(params) {
     const norm = normalizeParams(params);
@@ -188,42 +304,103 @@ export function searchKnowledge(params) {
     }
     const manifest = loadManifest();
     const allChunks = manifest.chunks;
-    let pool = filterPool(allChunks, norm);
-    // 自愈：types 过滤导致 0 命中时，丢掉 types 再过滤一次，避免误传类型标签直接返回 empty
-    if (pool.length === 0 && norm.types?.length) {
-        pool = filterPool(allChunks, { ...norm, types: undefined });
-    }
-    const { boosts, exactHits } = runExactLookup(norm.prompt, pool, norm);
-    // P0-4：用 product 级缓存的 BM25 索引对子集打分（首次构建，后续命中缓存）
-    // 索引基于该 product 全量 chunks（含 integration corpus）；
-    // 子集 ranking 只对 filteredPool.map(id) 打分，IDF 用更稳的产品级全量统计。
-    // 支持多 product 同时检索（products 数组），跨域问题如 Chat + Push 能同时命中各方知识。
-    const productIndex = getProductsBM25Index(allChunks, norm.product);
-    const poolWithContent = attachPoolContent(pool);
-    const chunksById = new Map(poolWithContent.map((chunk) => [chunk.id, chunk]));
-    const ranked = rankSubsetWithIndex(norm.prompt, pool.map((chunk) => chunk.id), productIndex, boosts);
-    const fragments = postProcess(ranked, chunksById, norm.limit);
-    const urlMappingSources = [...new Set(fragments.map((f) => f.source).filter((source) => isUrlMappingSource(source)))];
-    const references = buildReferences(fragments);
-    // P0-3：相对阈值评估置信度（替代原硬编码 0.5 死阈值）
-    const { confidence, status } = assessConfidence(fragments, exactHits);
-    const topScore = fragments[0]?.score;
-    const secondScore = fragments[1]?.score;
+    const queryApiTokens = inferQueryApiTokens(norm.prompt);
+    const runSearchPass = (passNorm, opts) => {
+        let pool = filterPool(allChunks, passNorm);
+        // types 误传自愈：首轮保留，二次扩检也同样保留该能力
+        if (pool.length === 0 && passNorm.types?.length) {
+            pool = filterPool(allChunks, { ...passNorm, types: undefined });
+        }
+        const { boosts, exactHits } = runExactLookup(passNorm.prompt, pool, passNorm);
+        // A2 补充正向路由：UserSig 问法下允许 share 命中且优先于无关 urls 噪声
+        if (/usersig|sdkappid|secretkey|鉴权|签名|gentestusersig/i.test(passNorm.prompt)) {
+            for (const chunk of pool) {
+                if (chunk.product === '*' && chunk.source.includes('knowledge/share/userSig.md')) {
+                    boosts[chunk.id] = (boosts[chunk.id] ?? 0) + 220;
+                }
+            }
+        }
+        // B2: API 覆盖不足扩检时，对 api/integration 语料做轻量重排提权
+        if (opts?.apiRetry) {
+            for (const chunk of pool) {
+                if (chunk.types.includes('api') || chunk.types.includes('integration')) {
+                    boosts[chunk.id] = (boosts[chunk.id] ?? 0) + 40;
+                }
+            }
+        }
+        const productIndex = getProductsBM25Index(allChunks, passNorm.product);
+        const poolWithContent = attachPoolContent(pool);
+        const chunksById = new Map(poolWithContent.map((chunk) => [chunk.id, chunk]));
+        const ranked = rankSubsetWithIndex(passNorm.prompt, pool.map((chunk) => chunk.id), productIndex, boosts);
+        const rankedWithMultipliers = applyRankMultipliers(ranked, chunksById, {
+            product: passNorm.product,
+            framework: passNorm.framework,
+            frameworks: passNorm.frameworks,
+        });
+        const fragments = postProcess(rankedWithMultipliers, chunksById, passNorm.limit);
+        const urlMappingSources = [...new Set(fragments.map((f) => f.source).filter((source) => isUrlMappingSource(source)))];
+        const references = buildReferences(fragments);
+        const apiNameCoverage = computeApiNameCoverage(queryApiTokens, poolWithContent);
+        const missingApiTokens = computeMissingApiTokens(queryApiTokens, poolWithContent);
+        return {
+            pool,
+            fragments,
+            exactHits,
+            urlMappingSources,
+            references,
+            apiNameCoverage,
+            missingApiTokens,
+        };
+    };
+    let pass = runSearchPass(norm);
+    let retryReason;
+    // B2: API token 覆盖不足时触发一次扩检（去掉 types 约束 + api/integration 轻提权）
+    const missingRatio = queryApiTokens.length > 0
+        ? Number((pass.missingApiTokens.length / queryApiTokens.length).toFixed(2))
+        : 0;
+    if (queryApiTokens.length > 0 && (pass.apiNameCoverage === 0 || missingRatio >= 0.3)) {
+        const retryPass = runSearchPass({ ...norm, types: undefined }, { apiRetry: true });
+        const retryMissingRatio = queryApiTokens.length > 0
+            ? Number((retryPass.missingApiTokens.length / queryApiTokens.length).toFixed(2))
+            : 0;
+        if (retryPass.apiNameCoverage > pass.apiNameCoverage
+            || retryMissingRatio < missingRatio
+            || (pass.fragments.length === 0 && retryPass.fragments.length > 0)) {
+            pass = retryPass;
+            retryReason = `api_gap_retry:coverage=${pass.apiNameCoverage},missing_ratio=${retryMissingRatio}`;
+        }
+    }
+    const routeInconsistencyWarning = pass.fragments.length > 0
+        ? pass.fragments.filter((f) => f.product === '*').length / pass.fragments.length > 0.3
+        : false;
+    const { confidence, status } = assessConfidence(pass.fragments, pass.exactHits, pass.apiNameCoverage, queryApiTokens);
+    const fabricationRisk = (queryApiTokens.length > 0 && pass.apiNameCoverage < 0.3)
+        || (confidence === 'low' && pass.fragments.length < 2);
+    const topScore = pass.fragments[0]?.score;
+    const secondScore = pass.fragments[1]?.score;
+    const answerContract = buildAnswerContract(status, confidence, { fabricationRisk });
     return {
         status,
         confidence,
-        message: buildAgentMessage(status, fragments, confidence, references),
+        message: buildAgentMessage(status, pass.fragments, confidence, pass.references, { fabricationRisk }),
         query: params,
         meta: {
             pool_size: allChunks.length,
-            filtered_size: pool.length,
-            exact_hits: exactHits,
-            ...(urlMappingSources.length ? { url_mapping_sources: urlMappingSources } : {}),
-            ...(references.length ? { references } : {}),
+            filtered_size: pass.pool.length,
+            exact_hits: pass.exactHits,
+            ...(pass.urlMappingSources.length ? { url_mapping_sources: pass.urlMappingSources } : {}),
+            ...(pass.references.length ? { references: pass.references } : {}),
             ...(topScore !== undefined ? { top_score: Number(topScore.toFixed(2)) } : {}),
             ...(secondScore !== undefined ? { second_score: Number(secondScore.toFixed(2)) } : {}),
+            ...(queryApiTokens.length ? { query_api_tokens: queryApiTokens } : {}),
+            ...(pass.missingApiTokens.length ? { missing_api_tokens: pass.missingApiTokens } : {}),
+            ...(retryReason ? { retry_reason: retryReason } : {}),
+            answer_contract: answerContract,
+            api_name_coverage: pass.apiNameCoverage,
+            fabrication_risk: fabricationRisk,
+            route_inconsistency_warning: routeInconsistencyWarning,
         },
-        fragments,
+        fragments: pass.fragments,
     };
 }
 export { normalizeParams, filterPool };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencent-rtc/mcp",
-  "version": "1.6.3",
+  "version": "1.6.5",
   "description": "Tencent Cloud MCP Server for SDK",
   "type": "module",
   "main": "index.js",