@tencentcloud/sdk-mcp 1.7.2 → 1.7.4

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # CHANGELOG
 
+## Version 1.7.4 @2026.08.31
+
+### 新增
+- 新增 CallKit Flutter 最佳实践文档 4 篇：Android 后台通话保活、iOS 后台音频保活、iOS 启动崩溃排查、后台来电无通知排查。
+- 新增 CallKit Android 视频交友场景（VideoChat Demo）最佳实践文档，覆盖 Demo 跑通与组件快速集成。
+- 新增 CallKit HarmonyOS 平台支持：含 UI 集成指南与 API 参考文档。
+- 新增 CallKit 小程序 & uni-app 集成文档：含 UI 集成指南、API 参考、uni-app 打包指南。
+- 新增 CallKit uni-app（Android/iOS）独立集成文档与 API 参考。
+- 新增 Chat Vue3/React H5 移动端集成文档。
+
+### 变更
+- 优化 Chat 含 UI 检索标签：vue/react 的 framework 从单标签改为双标签（`['vue','web']` / `['react','web']`），使 `frameworks=['web']` 也能命中 Chat Web 端文档。
+
+## Version 1.7.3 @2026.08.17
+
+### 新增
+- 新增 RoomKit 多端集成、录制、白板、网络代理、AI 降噪与字幕翻译等知识库资源，扩充 Room 产品域知识覆盖。
+- 新增错误码、日志级别、屏幕分享自动停止及微信小程序报错排查等最佳实践文档。
+- 新增通用加性 rerank 模块，实现锚点选择与短语提取，并集成到搜索重排逻辑，提升召回排序准确率。
+
+### 变更
+- 优化 BM25 索引为无原型对象，提升索引结构的隔离性与稳定性。
+
+### 修复
+- 修复 BM25 打分受原型键污染导致的异常，增加原型键守卫，避免打分污染与 NaN 问题。
+
 ## Version 1.7.2 @2026.08.13
 
 ### 变更

package/README.md

@@ -59,31 +59,39 @@ npx -y @tencentcloud/sdk-mcp
 
 > 仅展示最近更新，完整历史请查看 `CHANGELOG.md`。
 
-## Version 1.7.1 @2026.08.11
+## Version 1.7.4 @2026.08.31
 
 ### 新增
-- 新增检索前置归一化：基于 prompt 真值对 `product` / `frameworks` 做归一化，解决 agent 推理错误导致的检索偏差。
+- 新增 CallKit Flutter 最佳实践文档 4 篇：Android 后台通话保活、iOS 后台音频保活、iOS 启动崩溃排查、后台来电无通知排查。
+- 新增 CallKit Android 视频交友场景（VideoChat Demo）最佳实践文档，覆盖 Demo 跑通与组件快速集成。
+- 新增 CallKit HarmonyOS 平台支持：含 UI 集成指南与 API 参考文档。
+- 新增 CallKit 小程序 & uni-app 集成文档：含 UI 集成指南、API 参考、uni-app 打包指南。
+- 新增 CallKit uni-app（Android/iOS）独立集成文档与 API 参考。
+- 新增 Chat Vue3/React H5 移动端集成文档。
 
 ### 变更
-- 优化 `search_trtc_knowledge` 输出契约：移除 "1-2 sentence per subsection" 等压缩性措辞，改为输出完整合成答案。
+- 优化 Chat 含 UI 检索标签：vue/react 的 framework 从单标签改为双标签（`['vue','web']` / `['react','web']`），使 `frameworks=['web']` 也能命中 Chat Web 端文档。
 
-### 修复
-- 修复 "安卓 Web TRTC" 等 prompt 下 agent 误传双 product / 双 frameworks 时未按 prompt 真值校正的问题。
+## Version 1.7.3 @2026.08.17
+
+### 新增
+- 新增 RoomKit 多端集成、录制、白板、网络代理、AI 降噪与字幕翻译等知识库资源，扩充 Room 产品域知识覆盖。
+- 新增错误码、日志级别、屏幕分享自动停止及微信小程序报错排查等最佳实践文档。
+- 新增通用加性 rerank 模块，实现锚点选择与短语提取，并集成到搜索重排逻辑，提升召回排序准确率。
 
-### Version 1.7.0 @2026.08.02
+### 变更
+- 优化 BM25 索引为无原型对象，提升索引结构的隔离性与稳定性。
 
-#### 新增
-- 补充并同步 Chat / Call / Live / Room 等产品域最佳实践文档，增强知识覆盖范围。
+### 修复
+- 修复 BM25 打分受原型键污染导致的异常，增加原型键守卫，避免打分污染与 NaN 问题。
 
-#### 变更
-- 持续重构双语检索链路，优化 query 归一化、意图路由、候选过滤与精确命中策略。
-- 优化最佳实践与 URL 类文档的召回与排序，提升问答结果可用性与稳定性。
-- 优化 `search_trtc_knowledge` 相关定义与答复约束，提升回答可读性与可执行性。
+## Version 1.7.1 @2026.08.11
 
-#### 修复
-- 修复复杂问法下部分检索结果偏题的问题，降低高分误召回概率。
+### 新增
+- 新增检索前置归一化：基于 prompt 真值对 `product` / `frameworks` 做归一化，解决 agent 推理错误导致的检索偏差。
 
-### Version 1.6.6 @2026.07.18
+### 变更
+- 优化 `search_trtc_knowledge` 输出契约：移除 "1-2 sentence per subsection" 等压缩性措辞，改为输出完整合成答案。
 
-#### 新增
-- 支持 `get_native_live_uikit_integration` 工具，支持 LiveKit(Android/iOS) 含 UI 集成。
+### 修复
+- 修复 "安卓 Web TRTC" 等 prompt 下 agent 误传双 product / 双 frameworks 时未按 prompt 真值校正的问题。

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": "@tencentcloud/sdk-mcp",
-  "version": "1.7.2",
+  "version": "1.7.4",
   "description": "Tencent Cloud MCP Server for SDK",
   "type": "module",
   "main": "index.js",

package/resource/_schema/query-normalization.yaml

@@ -7,3 +7,9 @@ word:
   meeting: ["会议", "roomkit", "conference"]
   room: ["会议", "roomkit", "conference"]
   roomkit: ["会议", "roomkit", "conference"]
+  # 症状词 → 规范词：桌面版微信小程序运行 IM SDK 报 WebSocket is not a constructor / tencent_cloud_im_csig_flutter_for_web_25F_cy undefined。
+  # 用户常贴"AppService 逻辑层没有原生 WebSocket 构造函数"这类现象描述，与目标文档
+  # "桌面版微信 + 包名版本升级"词汇体系字面不重合，靠此映射补齐规范词，拉高召回重合度。
+  "WebSocket is not a constructor": ["桌面版微信", "小程序", "SDK 版本", "升级"]
+  AppService: ["桌面版微信", "小程序"]
+  "Cannot read properties of undefined (reading 'tencent_cloud_im_csig_flutter_for_web_25F_cy')": ["桌面版微信", "小程序", "SDK 版本"]