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

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # CHANGELOG
 
+## Version 1.7.8 @2026.09.20
+
+### 新增
+- 新增基于 RRF 的 BM25 + Dense 混合检索能力，提升复杂自然语言查询下的召回与排序稳定性。
+- 新增向量索引构建流程：接入 `build:vectors`，在构建阶段生成/更新向量索引，支持检索链路的语义召回。
+
+### 变更
+- 优化框架前置门控规则：扩展跨平台问法识别，新增英文 `callback` / `server callback` 信号，降低服务端回调类问题被误判为必须先选框架的概率。
+- 增强 `preflight-route` 的 prompt 框架识别能力：补充 `vue/react` 显式信号采集，提升 product-only 入口下的框架补全准确性。
+
+### 修复
+- 修复部分 Chat 场景下因框架信号缺失或英文回调问法导致的 `needs_framework` 误触发问题，减少本应可直接召回的请求被前置拦截。
+
 ## Version 1.7.7 @2026.09.11
 
 ### 变更

package/README.md

@@ -88,17 +88,15 @@
 
 > 仅展示最近更新，完整历史请查看 `CHANGELOG.md`。
 
-## Version 1.7.7 @2026.09.11
+## Version 1.7.8 @2026.09.20
 
-### 变更
-- 优化 MCP 连接稳定性与可观测性，提升异常定位与运行诊断效率。
-
-## Version 1.7.6 @2026.09.09
+### 新增
+- 新增基于 RRF 的 BM25 + Dense 混合检索能力，提升复杂自然语言查询下的召回与排序稳定性。
+- 新增向量索引构建流程：接入 `build:vectors`，在构建阶段生成/更新向量索引，支持检索链路的语义召回。
 
 ### 变更
-- 清理知识库中引流入口信息，减少知识库检索噪声。
-- 重构工具定义：统一工具的调用边界、触发语义和模板结构。
-- 调整全局 Workflow 语义为“咨询流专用”，降低工具路由歧义。
+- 优化框架前置门控规则：扩展跨平台问法识别，新增英文 `callback` / `server callback` 信号，降低服务端回调类问题被误判为必须先选框架的概率。
+- 增强 `preflight-route` 的 prompt 框架识别能力：补充 `vue/react` 显式信号采集，提升 product-only 入口下的框架补全准确性。
 
 ### 修复
-- 修复部分集成工具定义中的边界冲突与参数文案不一致问题（如 `get_native_callkit_core_integration`），提升调用稳定性。
+- 修复部分 Chat 场景下因框架信号缺失或英文回调问法导致的 `needs_framework` 误触发问题，减少本应可直接召回的请求被前置拦截。

package/index.js

@@ -15,14 +15,14 @@ async function main() {
     console.error('RTC Official MCP Server running on stdio');
 }
 main().then(() => {
-    reportCLSClient({
-        method: 'mcp_connect_success',
-        from: 'stdio',
-        info: JSON.stringify({
-            status: 'success',
-            latency_ms: Date.now() - startTime,
-        }),
-    });
+    // reportCLSClient({
+    //   method: 'mcp_connect_success',
+    //   from: 'stdio',
+    //   info: JSON.stringify({
+    //     status: 'success',
+    //     latency_ms: Date.now() - startTime,
+    //   }),
+    // });
 }).catch((error) => {
     reportCLSClient({
         method: 'mcp_connect_fail',

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/doc-url-resolver.js

@@ -112,22 +112,29 @@ export function resolveFragmentDocUrls(source, content, fullSourceContent) {
     }
     return urls.slice(0, 3);
 }
-/** 从 fragments 汇总去重后的参考链接列表（按 fragment 相关度排序）。
- * 规则：每个 fragment 仅取一个参考链接（优先 doc_urls[0]），避免 1 个片段膨胀出多个 references。 */
+/** 从 fragments 汇总去重后的参考链接列表（rank 与 fragment.rank 对齐）。
+ *
+ * 规则：
+ * 1. 每个 fragment 仅生成一个 reference（优先 doc_urls[0]），避免单片段膨胀出多个 references。
+ * 2. rank 直接沿用 fragment.rank，保证 references 与 fragments 位置一一对应；
+ *    历史实现用 refs.length+1 自增序号，导致 fragments[0] 无 URL 时 references[0]
+ *    的 rank/source 都会与 fragments[0] 错位（LLM/观测层难对齐）。
+ * 3. 当 fragment.doc_urls 全为空或全为噪音 URL 时，仍生成占位 reference（url=''），
+ *    保持 references.length == fragments.length；下游若判空可用 url==='' 兜底展示 title/source。
+ * 4. URL 去重：同一 URL 只在首次出现的 fragment 上保留，后续同 URL fragment 降级为占位。 */
 export function buildReferences(fragments) {
     const refs = [];
     const seen = new Set();
     for (const fragment of fragments) {
         const primaryUrl = fragment.doc_urls.find((u) => isUsefulDocUrl(u));
-        if (!primaryUrl)
-            continue;
-        if (seen.has(primaryUrl))
-            continue;
-        seen.add(primaryUrl);
+        // 占位规则：无可用 URL 或 URL 已被更靠前的 fragment 占用 → url=''，rank/source 仍保留
+        const url = primaryUrl && !seen.has(primaryUrl) ? primaryUrl : '';
+        if (url)
+            seen.add(url);
         refs.push({
-            rank: refs.length + 1,
+            rank: fragment.rank,
             title: fragment.title,
-            url: primaryUrl,
+            url,
             source: fragment.source,
         });
     }

package/knowledge/embedding/build-vectors.js

@@ -0,0 +1,92 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { LocalIndex } from 'vectra';
+import { attachPoolContent } from '../content-loader.js';
+import { chunkSearchText } from '../bm25.js';
+import { embedTexts } from './embed-model.js';
+import { allIndexPath } from './vector-index.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const RESOURCE_ROOT = path.resolve(__dirname, '../../resource');
+const BATCH = 32;
+function loadManifest() {
+    const p = path.join(RESOURCE_ROOT, 'index', 'manifest.json');
+    const m = JSON.parse(fs.readFileSync(p, 'utf-8'));
+    return m.chunks;
+}
+/** chunk 内容指纹：offset / title 变化即视为内容变化，触发重算 */
+function fingerprint(chunk) {
+    return `${chunk.source}:${chunk.char_start}:${chunk.char_end}:${chunk.title}`;
+}
+/**
+ * vectra 主键（唯一）。manifest 存在 27 个重复 id（同文件同名 section），
+ * 直接用 chunk.id 做主键会互相覆盖导致丢向量；用 id + char_start 复合键保证唯一。
+ * metadata.chunk_id 仍存原始 id，供运行期召回映射回 pool。
+ */
+function vectorKey(chunk) {
+    return `${chunk.id}@${chunk.char_start}`;
+}
+/** product 小写归一：容忍数据源大小写不一致（如 livekit faq 的 'Live' vs 'live'），
+ * 与 vector-index.queryVectors 的归一保持一致，避免向量召回因大小写漏检。*/
+function normalizedProduct(chunk) {
+    return (chunk.product || '*').toLowerCase();
+}
+/**
+ * 增量构建单一全局向量库（不再按 product 物理分片，product 作为 metadata 字段存入每条 item）：
+ * - 已存在且指纹一致 → 跳过
+ * - 新增 / 指纹变化 → 重新编码 upsert
+ * - manifest 已删除的 id → 从索引 delete
+ */
+export async function buildVectors() {
+    const chunks = loadManifest();
+    console.warn(`[build-vectors] ${chunks.length} chunks (single global index)`);
+    const idx = new LocalIndex(allIndexPath());
+    if (!(await idx.isIndexCreated())) {
+        await idx.createIndex({ version: 1, deleteIfExists: false });
+    }
+    // 现有条目：vectorKey → fingerprint
+    const existing = new Map();
+    for (const item of await idx.listItems()) {
+        const key = String(item.metadata.vkey ?? item.metadata.chunk_id);
+        existing.set(key, String(item.metadata.fp ?? ''));
+    }
+    const wantKeys = new Set(chunks.map((c) => vectorKey(c)));
+    const toEncode = chunks.filter((c) => existing.get(vectorKey(c)) !== fingerprint(c));
+    const toDelete = [...existing.keys()].filter((key) => !wantKeys.has(key));
+    if (toDelete.length > 0) {
+        await idx.deleteItems(toDelete);
+    }
+    if (toEncode.length === 0) {
+        console.warn(`[build-vectors] up-to-date (${chunks.length} chunks, +0/-${toDelete.length})`);
+        return;
+    }
+    const withContent = attachPoolContent(toEncode);
+    const texts = withContent.map((c) => chunkSearchText(c));
+    await idx.beginUpdate();
+    try {
+        for (let i = 0; i < texts.length; i += BATCH) {
+            const batchChunks = withContent.slice(i, i + BATCH);
+            const vectors = await embedTexts(texts.slice(i, i + BATCH));
+            for (let j = 0; j < batchChunks.length; j += 1) {
+                const c = batchChunks[j];
+                await idx.upsertItem({
+                    id: vectorKey(c),
+                    vector: Array.from(vectors[j]),
+                    metadata: {
+                        chunk_id: c.id,
+                        vkey: vectorKey(c),
+                        fp: fingerprint(c),
+                        product: normalizedProduct(c),
+                    },
+                });
+            }
+        }
+        await idx.endUpdate();
+    }
+    catch (e) {
+        idx.cancelUpdate();
+        throw e;
+    }
+    console.warn(`[build-vectors] +${toEncode.length}/-${toDelete.length} (total ${chunks.length})`);
+    console.warn('[build-vectors] done');
+}

package/knowledge/embedding/embed-model.js

@@ -0,0 +1,41 @@
+import { pipeline } from '@huggingface/transformers';
+/**
+ * 本地 ONNX 文本编码器。
+ *
+ * 模型：BGE-small-zh-v1.5（512 维，中文检索优化，体积轻）。
+ * 后端：device='cpu'（@huggingface/transformers 4.x 的 Node 端支持 coreml/webgpu/cpu；
+ *       'wasm' 仅浏览器可用）。cpu 后端底层走 onnxruntime-node。
+ */
+const MODEL_ID = 'Xenova/bge-small-zh-v1.5';
+export const EMBED_DIM = 512;
+let extractorPromise = null;
+function getExtractor() {
+    if (!extractorPromise) {
+        extractorPromise = pipeline('feature-extraction', MODEL_ID, {
+            device: 'cpu',
+            dtype: 'q8',
+        });
+    }
+    return extractorPromise;
+}
+/**
+ * 编码一批文本 → 归一化向量（余弦相似度可直接点积）。
+ * mean pooling + L2 normalize（BGE 官方推荐）。
+ */
+export async function embedTexts(texts) {
+    if (texts.length === 0)
+        return [];
+    const extractor = await getExtractor();
+    const output = await extractor(texts, { pooling: 'mean', normalize: true });
+    const rows = output.tolist();
+    return rows.map((row) => Float32Array.from(row));
+}
+/** 单条查询编码（运行期热路径，texts=1） */
+export async function embedQuery(text) {
+    const [vec] = await embedTexts([text]);
+    return vec;
+}
+/** BGE 建议给查询加指令前缀以提升检索质量 */
+export function withQueryInstruction(query) {
+    return `为这个句子生成表示以用于检索相关文章：${query}`;
+}

package/knowledge/embedding/vector-augment.js

@@ -0,0 +1,126 @@
+import { embedQuery, withQueryInstruction } from './embed-model.js';
+import { queryVectors } from './vector-index.js';
+export const DEFAULT_VECTOR_OPTS = {
+    alpha: 0.15,
+    baseBeta: 0.3,
+    topK: 30,
+};
+/**
+ * 软融合：在既有 BM25 ranked 上叠加向量语义信号，**输出仍是 BM25 量纲**。
+ *
+ * 融合公式：
+ *   BM25 已命中：      finalScore = bm25 * (1 + alpha * simNorm)
+ *   仅向量命中(补召回): finalScore = topBM25 * baseBeta * (1 + alpha * simNorm)
+ *
+ * simNorm：对本轮向量候选做 min-max 归一化到 [0,1]。
+ *
+ * 关键不变量：
+ * - 下游 assessConfidence / postProcess / best-practice 竞争 / 低置信裁剪的阈值全部继续有效（量纲不变）
+ * - 补召回 base 分 < topBM25 * 0.35，不越过断崖截断保护线
+ * - 容错：向量库缺失 / 编码失败 → 返回原 bm25Ranked（降级纯 BM25），绝不阻断主链路
+ */
+export async function vectorAugment(query, 
+/** hard 层过滤后的 chunk id 集合（product + retrievable_scope），不应包含 framework/types/scenario 过滤 */
+poolIds, bm25Ranked, products, opts = DEFAULT_VECTOR_OPTS) {
+    if (bm25Ranked.length === 0) {
+        return {
+            ranked: bm25Ranked,
+            stats: {
+                attempted: false,
+                applied: false,
+                reason: 'bm25_empty',
+                raw_hit_count: 0,
+                pool_hit_count: 0,
+                bm25_adjusted_count: 0,
+                vector_only_added_count: 0,
+                alpha: opts.alpha,
+                base_beta: opts.baseBeta,
+                top_k: opts.topK,
+            },
+        };
+    }
+    let hits;
+    try {
+        const qvec = await embedQuery(withQueryInstruction(query));
+        hits = await queryVectors(products, qvec, opts.topK);
+    }
+    catch {
+        return {
+            ranked: bm25Ranked,
+            stats: {
+                attempted: true,
+                applied: false,
+                reason: 'embed_or_query_failed',
+                raw_hit_count: 0,
+                pool_hit_count: 0,
+                bm25_adjusted_count: 0,
+                vector_only_added_count: 0,
+                alpha: opts.alpha,
+                base_beta: opts.baseBeta,
+                top_k: opts.topK,
+            },
+        };
+    }
+    // 只保留在 hard 层（product + retrievable_scope）过滤后的向量候选。
+    // framework/types/scenario 属于软过滤层，不应在此二次砍杀向量语义召回。
+    const vecHits = hits.filter((h) => poolIds.has(h.id));
+    if (vecHits.length === 0) {
+        return {
+            ranked: bm25Ranked,
+            stats: {
+                attempted: true,
+                applied: false,
+                reason: 'no_vector_hit_in_pool',
+                raw_hit_count: hits.length,
+                pool_hit_count: 0,
+                bm25_adjusted_count: 0,
+                vector_only_added_count: 0,
+                alpha: opts.alpha,
+                base_beta: opts.baseBeta,
+                top_k: opts.topK,
+            },
+        };
+    }
+    // simNorm：min-max 归一化
+    const sims = vecHits.map((h) => h.score);
+    const minS = Math.min(...sims);
+    const maxS = Math.max(...sims);
+    const range = maxS - minS || 1;
+    const simMap = new Map(vecHits.map((h) => [h.id, (h.score - minS) / range]));
+    const topBM25 = bm25Ranked[0].score;
+    const bm25Ids = new Set(bm25Ranked.map((item) => item.id));
+    let bm25AdjustedCount = 0;
+    let vectorOnlyAddedCount = 0;
+    // 1) BM25 已命中的 chunk 做加权
+    const fused = bm25Ranked.map((item) => {
+        const sim = simMap.get(item.id);
+        if (sim === undefined)
+            return item;
+        bm25AdjustedCount += 1;
+        return { id: item.id, score: item.score * (1 + opts.alpha * sim) };
+    });
+    // 2) 向量补召回（BM25 未命中但语义相近）
+    const baseScore = topBM25 * opts.baseBeta;
+    for (const h of vecHits) {
+        if (bm25Ids.has(h.id))
+            continue;
+        const sim = simMap.get(h.id) ?? 0;
+        fused.push({ id: h.id, score: baseScore * (1 + opts.alpha * sim) });
+        vectorOnlyAddedCount += 1;
+    }
+    return {
+        ranked: fused.sort((a, b) => b.score - a.score),
+        stats: {
+            attempted: true,
+            applied: bm25AdjustedCount > 0 || vectorOnlyAddedCount > 0,
+            reason: 'fused',
+            raw_hit_count: hits.length,
+            pool_hit_count: vecHits.length,
+            bm25_adjusted_count: bm25AdjustedCount,
+            vector_only_added_count: vectorOnlyAddedCount,
+            alpha: opts.alpha,
+            base_beta: opts.baseBeta,
+            top_k: opts.topK,
+        },
+    };
+}

package/knowledge/embedding/vector-index.js

@@ -0,0 +1,70 @@
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { LocalIndex } from 'vectra';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * 运行期向量库根目录。
+ * 编译后本文件位于 dist/knowledge/embedding/，向量产物在 dist/resource/index/vectors/。
+ */
+function vectorsRoot() {
+    return path.resolve(__dirname, '../../resource/index/vectors');
+}
+/**
+ * 单一全局向量索引目录（不再按 product 物理分片）。
+ *
+ * 背景：vectra LocalIndex.queryItems 本身就是全量线性扫描 + 堆排序取 topK
+ * （非 ANN 索引结构），按 product 物理拆分索引文件不会带来性能收益
+ * （全库 4173 条 chunk 的线性扫描耗时在毫秒级，远小于 embedQuery 的 ONNX 推理耗时）。
+ * 反而在 products 未指定时（恰恰是最需要语义补召回的模糊查询场景），
+ * 只能退回体量极小的 '*' 分片，导致向量召回几乎失效——这是不合理的设计。
+ *
+ * 现改为单一索引 + metadata.product 字段 + queryItems 的 MetadataFilter 过滤：
+ * - products 有值 → filter: { product: { $in: products } }
+ * - products 为空 → 不传 filter，全库扫描（行为对齐 BM25 的全量兜底语义）
+ *
+ * 索引直接落在 vectors/ 目录下（index.json 等文件），不再套一层多余的 'all' 子目录。
+ */
+export function allIndexPath() {
+    return vectorsRoot();
+}
+// 进程内缓存已加载的 LocalIndex，避免每次查询重开
+let cachedIndex;
+async function loadIndex() {
+    if (cachedIndex !== undefined)
+        return cachedIndex;
+    const idx = new LocalIndex(allIndexPath());
+    const exists = await idx.isIndexCreated();
+    cachedIndex = exists ? idx : null;
+    return cachedIndex;
+}
+/**
+ * 在全局向量库里查 topK 相似 chunk，按 products 做 metadata 过滤。
+ * products 为空/未指定 → 不加过滤条件，全库扫描（不再退化为几乎空的 '*' 分片）。
+ * 索引不存在 → 返回空数组（容错，降级为纯 BM25）。
+ */
+export async function queryVectors(products, queryVec, topK) {
+    const idx = await loadIndex();
+    if (!idx)
+        return [];
+    // product 小写归一，与 build-vectors.groupByProduct 一致（容忍数据源大小写不一致）
+    const normalized = products && products.length
+        ? [...new Set(products.map((p) => p.toLowerCase()))]
+        : [];
+    const vec = Array.from(queryVec);
+    const filter = normalized.length ? { product: { $in: normalized } } : undefined;
+    const results = await idx.queryItems(vec, '', topK, filter);
+    const best = new Map();
+    for (const r of results) {
+        const id = String(r.item.metadata.chunk_id);
+        const prev = best.get(id);
+        if (prev === undefined || prev < r.score)
+            best.set(id, r.score);
+    }
+    return [...best.entries()]
+        .map(([id, score]) => ({ id, score }))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, topK);
+}
+export function clearVectorCache() {
+    cachedIndex = undefined;
+}

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: [],
     };