@tencent-rtc/mcp 1.7.2 → 1.7.4

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # CHANGELOG
 
+## Version 1.7.4 @2026.08.31
+
+### Added
+- Added 4 CallKit Flutter best-practice docs: Android background call keep-alive, iOS background audio keep-alive, iOS startup crash troubleshooting, background incoming call notification troubleshooting.
+- Added CallKit Android video chat dating scenario (VideoChat Demo) best-practice doc, covering Demo setup and component quick integration.
+- Added CallKit HarmonyOS platform support: UIKit integration guide and API reference.
+- Added CallKit Mini Program & uni-app docs: UIKit integration guide, API reference, uni-app packaging guide.
+- Added CallKit uni-app (Android/iOS) standalone integration docs and API reference.
+- Added Chat Vue3/React H5 mobile integration docs.
+
+### Changed
+- Optimized Chat UIKit search tags: vue/react framework changed from single tag to dual tags (`['vue','web']` / `['react','web']`), allowing `frameworks=['web']` to match Chat Web docs.
+
+## Version 1.7.3 @2026.08.17
+
+### Added
+- Added knowledge base resources for RoomKit multi-platform integration, recording, whiteboard, network proxy, AI noise reduction, and subtitle translation, expanding coverage of the Room product domain.
+- Added best-practice docs covering error codes, log levels, automatic screen-share stop, and WeChat Mini Program error troubleshooting.
+- Added a generic additive rerank module with anchor selection and phrase extraction, integrated into the search reranking logic to improve recall ranking accuracy.
+
+### Changed
+- Optimized the BM25 index to use prototype-less objects, improving the isolation and stability of the index structure.
+
+### Fixed
+- Fixed BM25 scoring anomalies caused by prototype-key pollution by adding prototype-key guards, preventing score pollution and NaN issues.
+
 ## Version 1.7.2 @2026.08.13
 
 ### Changed

package/README.md

@@ -57,31 +57,39 @@ npx -y @tencent-rtc/mcp
 
 > Only recent updates are listed here. For full history, see `CHANGELOG.md`.
 
-## Version 1.7.1 @2026.08.11
+## Version 1.7.4 @2026.08.31
 
 ### Added
-- Added pre-search normalization: normalizes `product` / `frameworks` based on prompt truth, fixing retrieval bias caused by wrong agent inference.
+- Added 4 CallKit Flutter best-practice docs: Android background call keep-alive, iOS background audio keep-alive, iOS startup crash troubleshooting, background incoming call notification troubleshooting.
+- Added CallKit Android video chat dating scenario (VideoChat Demo) best-practice doc, covering Demo setup and component quick integration.
+- Added CallKit HarmonyOS platform support: UIKit integration guide and API reference.
+- Added CallKit Mini Program & uni-app docs: UIKit integration guide, API reference, uni-app packaging guide.
+- Added CallKit uni-app (Android/iOS) standalone integration docs and API reference.
+- Added Chat Vue3/React H5 mobile integration docs.
 
 ### Changed
-- Optimized the `search_trtc_knowledge` output contract: removed brevity wording such as "1-2 sentence per subsection", replaced with complete synthesized answers.
+- Optimized Chat UIKit search tags: vue/react framework changed from single tag to dual tags (`['vue','web']` / `['react','web']`), allowing `frameworks=['web']` to match Chat Web docs.
 
-### Fixed
-- Fixed the case where mis-passed dual product / dual frameworks (e.g., "安卓 Web TRTC") were not corrected according to the prompt truth.
+## Version 1.7.3 @2026.08.17
+
+### Added
+- Added knowledge base resources for RoomKit multi-platform integration, recording, whiteboard, network proxy, AI noise reduction, and subtitle translation, expanding coverage of the Room product domain.
+- Added best-practice docs covering error codes, log levels, automatic screen-share stop, and WeChat Mini Program error troubleshooting.
+- Added a generic additive rerank module with anchor selection and phrase extraction, integrated into the search reranking logic to improve recall ranking accuracy.
 
-### Version 1.7.0 @2026.08.02
+### Changed
+- Optimized the BM25 index to use prototype-less objects, improving the isolation and stability of the index structure.
 
-#### Added
-- Added and synchronized best-practice docs across product domains including Chat / Call / Live / Room to improve knowledge coverage.
+### Fixed
+- Fixed BM25 scoring anomalies caused by prototype-key pollution by adding prototype-key guards, preventing score pollution and NaN issues.
 
-#### Changed
-- Continued refactoring of the bilingual retrieval pipeline, including query normalization, intent routing, candidate filtering, and exact-match strategies.
-- Improved recall and ranking for best-practice and URL-based documents to increase answer usability and stability.
-- Improved `search_trtc_knowledge` definitions and answer constraints for better readability and executability.
+## Version 1.7.1 @2026.08.11
 
-#### Fixed
-- Fixed off-topic retrieval in some complex queries, reducing high-score false-positive hits.
+### Added
+- Added pre-search normalization: normalizes `product` / `frameworks` based on prompt truth, fixing retrieval bias caused by wrong agent inference.
 
-### Version 1.6.6 @2026.07.18
+### Changed
+- Optimized the `search_trtc_knowledge` output contract: removed brevity wording such as "1-2 sentence per subsection", replaced with complete synthesized answers.
 
-#### Added
-- Added support for `get_native_live_uikit_integration`, enabling LiveKit(Android/iOS) UI integration guidance.
+### Fixed
+- Fixed the case where mis-passed dual product / dual frameworks (e.g., "安卓 Web TRTC") were not corrected according to the prompt truth.

package/knowledge/bm25.js

@@ -61,28 +61,29 @@ export function tokenize(text) {
     return tokens;
 }
 export function buildBM25Index(documents) {
-    const postings = {};
-    const docLengths = {};
-    const docFreq = {};
+    // 用无原型对象，杜绝 term/id 为 'constructor'/'__proto__' 等原型键时的污染。
+    const postings = Object.create(null);
+    const docLengths = Object.create(null);
+    const docFreq = Object.create(null);
     let totalLength = 0;
     for (const doc of documents) {
         const tokens = tokenize(doc.text);
         docLengths[doc.id] = tokens.length;
         totalLength += tokens.length;
-        const termFreq = {};
+        const termFreq = Object.create(null);
         for (const token of tokens) {
             termFreq[token] = (termFreq[token] ?? 0) + 1;
         }
         for (const [term, freq] of Object.entries(termFreq)) {
             if (!postings[term])
-                postings[term] = {};
+                postings[term] = Object.create(null);
             postings[term][doc.id] = freq;
             docFreq[term] = (docFreq[term] ?? 0) + 1;
         }
     }
     const n = documents.length;
     const avgDocLength = n > 0 ? totalLength / n : 0;
-    const idf = {};
+    const idf = Object.create(null);
     for (const [term, df] of Object.entries(docFreq)) {
         idf[term] = Math.log(1 + (n - df + 0.5) / (df + 0.5));
     }
@@ -96,15 +97,23 @@ export function buildBM25Index(documents) {
 }
 export function scoreBM25(query, chunkId, index) {
     const tokens = tokenize(query);
-    const docLength = index.docLengths[chunkId] ?? 0;
-    if (docLength === 0)
+    // Object.prototype 污染防护：postings/idf/docLengths 来自 JSON.parse 的普通对象，
+    // term 可能是 'constructor'/'toString'/'__proto__' 等原型键，直接 [] 取值会命中
+    // 原型链上的函数（如 Object.prototype.constructor），污染打分为 NaN。用 hasOwn 守卫。
+    const docLength = Object.hasOwn(index.docLengths, chunkId) ? index.docLengths[chunkId] : 0;
+    if (!docLength || Number.isNaN(docLength))
         return 0;
     let score = 0;
     for (const term of tokens) {
-        const tf = index.postings[term]?.[chunkId] ?? 0;
-        if (tf === 0)
+        if (!Object.hasOwn(index.postings, term) || !Object.hasOwn(index.idf, term))
+            continue;
+        const posting = index.postings[term];
+        const tf = Object.hasOwn(posting, chunkId) ? posting[chunkId] : 0;
+        if (!tf || Number.isNaN(tf))
+            continue;
+        const idf = index.idf[term];
+        if (Number.isNaN(idf))
             continue;
-        const idf = index.idf[term] ?? 0;
         const numerator = tf * (K1 + 1);
         const denominator = tf + K1 * (1 - B + B * (docLength / (index.avgDocLength || 1)));
         score += idf * (numerator / denominator);

package/knowledge/path-meta.js

@@ -8,6 +8,9 @@ function inferTypesFromFilename(fileName, baseTypes) {
         types.push('error_code');
     if (lower === 'client-api.md' || lower === 'api.md' || lower === 'index.md')
         types.push('api');
+    // api-<变体>.md（如 api-uniapp.md：微信小程序 uni-app 打包 API）同样是 API 文档
+    if (/^api-[\w-]+\.mdx?$/.test(lower))
+        types.push('api');
     if (lower === 'faq.md')
         types.push('faq');
     // 文件名 = integration.md 不再默认 push integration（由上游 framework 分支显式声明 type）
@@ -75,7 +78,14 @@ export function inferPathMeta(relativeSource) {
     else if (normalized.startsWith('knowledge/chat/') || normalized.startsWith('integration/chat/')) {
         product = 'chat';
         if (parts.includes('preset') && parts.length >= 4) {
-            framework = [normalizeFrameworkDir(parts[parts.indexOf('preset') + 1])];
+            const fw = normalizeFrameworkDir(parts[parts.indexOf('preset') + 1]);
+            // vue/react 运行在 Web/H5 端，追加 web 标签，使 frameworks=['web'] 也能命中
+            framework = (fw === 'vue' || fw === 'react') ? [fw, 'web'] : [fw];
+            variant = 'preset';
+            // preset 下的 integration.md 显式标记 integration type
+            if (fileName.toLowerCase() === 'integration.md') {
+                types.push('integration');
+            }
         }
         if (parts.includes('features')) {
             types.push('feature');
@@ -137,6 +147,13 @@ export function inferPathMeta(relativeSource) {
             framework = [normalizeFrameworkDir(parts[coreIdx + 1])];
             variant = 'core-sdk';
         }
+        // 微信小程序 uni-app 打包版：目录归入 miniprogram（运行平台=微信小程序），
+        // 但技术栈是 uni-app，通过文件名 *-uniapp.md / uniapp-*.md 触发双标签，
+        // 使「微信小程序」与「uni-app」两种 framework 检索都能召回同一篇文档。
+        // 原生小程序（api.md/integration.md 等无 uniapp 标记）保持单 miniprogram 标签。
+        if (framework[0] === 'miniprogram' && /(^uniapp[-.]|-uniapp\.mdx?$)/.test(fileName.toLowerCase())) {
+            framework = ['miniprogram', 'uni-app'];
+        }
         // callkit 最佳实践目录：knowledge/callkit/best-practice/{platform}/{topic}.md
         // 统一按 FAQ/经验类知识处理，支持 types=faq + frameworks={platform} 的精确检索。
         // 与 chat best-practice 对齐：common 目录表示多平台通用，按最全集覆盖。
@@ -147,6 +164,11 @@ export function inferPathMeta(relativeSource) {
                 : [fwSlug];
             types.push('faq');
         }
+        // preset 下的 integration.md（纯文件名，无连字符前缀）需显式标记 integration type，
+        // 否则 inferTypesFromFilename 只匹配 *-integration.md，导致兜底为 faq。
+        if (variant === 'preset' && fileName.toLowerCase() === 'integration.md') {
+            types.push('integration');
+        }
         if (parts.includes('faq'))
             types.push('faq', 'error_code');
         if (fileName === 'api.md')

package/knowledge/search/generic-rerank.js

@@ -0,0 +1,123 @@
+/**
+ * 通用加性 rerank：数据驱动的高 IDF 锚点命中 + 连续短语命中。
+ *
+ * 设计约束（零衰减 + 通用）：
+ * - 纯加性：只往 boosts 加正数，无 penalty；无信号（无锚点且无短语命中）时返回空 map，
+ *   排序数学上完全等于现状 → 已有功能零衰减。
+ * - 量纲受控：单 chunk 上限 = W_ANCHOR + W_PHRASE，远低于 exact-lookup 的 +200~+300，
+ *   只在 BM25 平局区间起微调，不翻转既有精确命中。
+ * - 零硬编码：锚点门槛来自运行时 index.idf 分位、短语来自 query 结构，
+ *   不含任何具体词 / product / 文件名 → 对任意产品成立。
+ *
+ * 治两个诊断确认的真病根：
+ * - A（锚点命中）：对抗「CJK unigram 被拆多份 × 高 tf 堆分」——稀有锚点命中给加权，
+ *   把靠通用词堆分的长文档区分开。
+ * - B（连续短语）：用原始字符串连续匹配抓「组合稀有」（如 WebSocket is not a constructor），
+ *   同时天然排除 tokenize 产生的跨词垃圾 bigram（如「错怎」——它在原 query 里虽连续，
+ *   但作为连续串在无关文档正文中不命中，不会被误加分）。
+ */
+// ── 超参（唯一可调项，均可回归验证）──────────────────────────────
+/** 锚点门槛：取当前检索子库 IDF 分布的分位阈值，IDF ≥ 此值的 query term 视为锚点 */
+const IDF_PERCENTILE = 0.75;
+/** 锚点数上限，防止长 query 稀释权重 */
+const MAX_ANCHORS = 6;
+/** 锚点命中权重（与 BM25 top 分 20~50 同量级，低于 exact-lookup boost 量级） */
+const W_ANCHOR = 40;
+/** 连续短语命中权重 */
+const W_PHRASE = 30;
+/**
+ * 从 query term 中选出锚点：IDF ≥ 子库分位阈值的 term，按 IDF 降序取 top-K。
+ * 门槛完全由 index.idf 的运行时分布决定（数据驱动），不写死任何词。
+ */
+function selectAnchors(queryTerms, index) {
+    const allIdf = Object.values(index.idf);
+    if (allIdf.length === 0)
+        return [];
+    const sorted = [...allIdf].sort((a, b) => a - b);
+    const threshold = sorted[Math.floor(sorted.length * IDF_PERCENTILE)] ?? 0;
+    const seen = new Set();
+    const anchors = [];
+    for (const term of queryTerms) {
+        if (seen.has(term))
+            continue;
+        seen.add(term);
+        // Object.prototype 污染防护：term 可能是 'constructor' 等原型键。
+        if (!Object.hasOwn(index.idf, term))
+            continue;
+        const idf = index.idf[term];
+        if (typeof idf !== 'number' || Number.isNaN(idf) || idf < threshold)
+            continue;
+        anchors.push({ term, idf });
+    }
+    anchors.sort((a, b) => b.idf - a.idf);
+    return anchors.slice(0, MAX_ANCHORS);
+}
+/**
+ * 从原始 query 抽取连续短语（不经 tokenize，避免分词假象）：
+ * - 英文：相邻词对（连续两个 ≥2 长度的英文/数字 token）
+ * - 中文：连续 ≥2 字的中文片段（整段，不切分）
+ */
+function extractPhrases(prompt) {
+    const phrases = [];
+    const enWords = prompt.toLowerCase().match(/[a-z0-9_]{2,}/g) ?? [];
+    for (let i = 0; i < enWords.length - 1; i += 1) {
+        phrases.push(`${enWords[i]} ${enWords[i + 1]}`);
+    }
+    for (const seg of prompt.match(/[\u4e00-\u9fff]{2,}/g) ?? []) {
+        phrases.push(seg);
+    }
+    return [...new Set(phrases)].filter((p) => p.replace(/\s/g, '').length >= 2);
+}
+/**
+ * 计算通用加性 boost。返回 chunkId -> 正分。
+ * 无锚点且无短语时返回空 map（排序退化为原始，零衰减）。
+ */
+export function computeGenericAnchorBoosts(prompt, pool, index, tokenizeFn) {
+    const result = {};
+    const anchors = selectAnchors(tokenizeFn(prompt), index);
+    const phrases = extractPhrases(prompt);
+    // 门槛：既无锚点也无短语 → 直接返回空，排序完全等于原来。
+    if (anchors.length === 0 && phrases.length === 0)
+        return result;
+    const maxIdf = Math.max(1, ...anchors.map((a) => a.idf));
+    for (const chunk of pool) {
+        // ── 信号 A：命中锚点，按 IDF 归一化累加命中强度 ──
+        let anchorStrength = 0;
+        let anchorHits = 0;
+        for (const { term, idf } of anchors) {
+            // Object.prototype 污染防护：term 可能是 'constructor' 等原型键。
+            if (!Object.hasOwn(index.postings, term))
+                continue;
+            const posting = index.postings[term];
+            if ((Object.hasOwn(posting, chunk.id) ? posting[chunk.id] : 0) > 0) {
+                anchorStrength += idf / maxIdf;
+                anchorHits += 1;
+            }
+        }
+        // ── 信号 B：连续短语在 title / key_phrases / 正文原始串命中 ──
+        const haystack = [
+            chunk.title,
+            ...(chunk.key_phrases ?? []),
+            chunk.content,
+        ].filter(Boolean).join(' ').toLowerCase();
+        let phraseHits = 0;
+        for (const phrase of phrases) {
+            if (haystack.includes(phrase.toLowerCase())) {
+                phraseHits += 1;
+            }
+        }
+        // 该 chunk 无任何信号 → 不加分（保持原分）。
+        if (anchorHits === 0 && phraseHits === 0)
+            continue;
+        const boostA = anchors.length > 0
+            ? W_ANCHOR * (anchorStrength / anchors.length) // 归一化到 [0, W_ANCHOR]
+            : 0;
+        const boostB = phrases.length > 0
+            ? W_PHRASE * Math.min(1, phraseHits / phrases.length) // [0, W_PHRASE]
+            : 0;
+        const total = boostA + boostB;
+        if (total > 0)
+            result[chunk.id] = total;
+    }
+    return result;
+}

package/knowledge/search/search-pass.js

@@ -1,9 +1,10 @@
 import { attachPoolContent } from '../content-loader.js';
 import { buildReferences } from '../doc-url-resolver.js';
-import { rankSubsetWithIndex } from '../bm25.js';
+import { rankSubsetWithIndex, tokenize } from '../bm25.js';
 import { getProductsBM25Index } from '../bm25-cache.js';
 import { filterPool } from './filter-pool.js';
 import { runExactLookup } from './exact-lookup.js';
+import { computeGenericAnchorBoosts } from './generic-rerank.js';
 import { applyRankMultipliers, computeApiNameCoverage, computeMissingApiTokens, isUrlMappingSource, postProcess, } from './search-core.js';
 function isBestPracticeSource(source) {
     return /\/best-practice\//i.test(source);
@@ -379,6 +380,12 @@ export function runSearchPass(params) {
     const productIndex = getProductsBM25Index(allChunks, passNorm.product);
     const poolWithContent = attachPoolContent(pool);
     const chunksById = new Map(poolWithContent.map((chunk) => [chunk.id, chunk]));
+    // 通用加性 rerank：数据驱动的高 IDF 锚点命中 + 连续短语命中。
+    // 纯加性、只加不减、无信号时返回空 map → 排序退化为原始，已有功能零衰减。
+    const genericBoosts = computeGenericAnchorBoosts(effectivePassNorm.prompt, poolWithContent, productIndex, tokenize);
+    for (const [id, amount] of Object.entries(genericBoosts)) {
+        boosts[id] = (boosts[id] ?? 0) + amount;
+    }
     const ranked = rankSubsetWithIndex(effectivePassNorm.prompt, pool.map((chunk) => chunk.id), productIndex, boosts);
     const rankedWithMultipliers = applyRankMultipliers(ranked, chunksById, {
         product: passNorm.product,

package/package.json

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