@tencent-rtc/mcp 1.6.8 → 1.7.1

package/knowledge/search/filter-pool.js

@@ -1,5 +1,6 @@
 import { downgradeToProductType } from './product-scope-intent.js';
 import { normalizeQueryPrompt } from './query-normalizer.js';
+import { hasExplicitFrameworkMatch, hasFrameworkFallbackMatch } from './framework-fallback.js';
 /**
  * MCP framework enum → index 中对应的 framework 值列表。
  * path-meta.ts 已通过 normalizeFrameworkDir 把目录名归一到标准 framework，
@@ -42,14 +43,6 @@ function resolveTypes(products, types, prompt, frameworks) {
         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');
-    }
     return expanded;
 }
 /** 单平台产品的隐式 framework 推断：避免对显然唯一的平台再发起询问 */
@@ -133,33 +126,23 @@ export function filterPool(chunks, norm) {
             // 收紧：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));
-            // 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/'));
-            // Room special-case: Conference Web docs are under roomkit/core-sdk/vue.
-            const roomWebVueFallback = Boolean(norm.product?.includes('room')
-                && norm.framework === 'web'
-                && chunk.variant === 'core-sdk'
-                && chunk.framework.includes('vue')
-                && chunk.source.includes('knowledge/roomkit/core-sdk/vue/'));
-            if (!explicitMatch && !wildcardAllowed && !callCoreWebFallback && !liveWebVueFallback && !roomWebVueFallback)
+            const explicitMatch = hasExplicitFrameworkMatch(chunk.framework, norm.frameworks);
+            const fallbackMatch = hasFrameworkFallbackMatch(chunk, {
+                product: norm.product,
+                framework: norm.framework,
+                frameworks: norm.frameworks,
+            });
+            if (!explicitMatch && !wildcardAllowed && !fallbackMatch)
                 return false;
         }
         if (norm.scenario && chunk.scenario && chunk.scenario !== norm.scenario) {
             return false;
         }
+        // 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))) {
-            return false;
+            if (!chunk.source.includes('/best-practice/'))
+                return false;
         }
         return true;
     });

package/knowledge/search/framework-fallback.js

@@ -0,0 +1,22 @@
+export function hasExplicitFrameworkMatch(chunkFrameworks, requestFrameworks) {
+    if (!requestFrameworks?.length)
+        return false;
+    return requestFrameworks.some((fw) => chunkFrameworks.includes(fw));
+}
+export function hasFrameworkFallbackMatch(chunk, opts) {
+    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/'));
+    const roomWebVueFallback = Boolean(opts.product?.includes('room')
+        && opts.framework === 'web'
+        && chunk.variant === 'core-sdk'
+        && chunk.framework.includes('vue')
+        && chunk.source.includes('knowledge/roomkit/core-sdk/vue/'));
+    return callCoreWebFallback || liveWebVueFallback || roomWebVueFallback;
+}

package/knowledge/search/intent-router.js

@@ -0,0 +1,29 @@
+/** 枚举/目录浏览意图 */
+const DISCOVERY_INTENT_RE = /有哪些|支持哪些|列一下|列出来|清单|目录|可用|全部|全量|对比|怎么选|选哪个|哪些\s+(组件|功能|接口|能力)|which\s+one|compare|comparison|what\s+(is|are)\s+available|what\s+.*\b(components?|features?|apis?)\b|available\s+(components?|features?|apis?)|supported\s+(components?|features?|apis?)|list\s+(all|available)|catalog/i;
+/** 显式完整文档意图（用户明确说"完整/从零/step by step"） */
+const NARRATIVE_INTENT_RE = /从头到尾|一步一步|完整指南|完整教程|完整流程|完整接入|完整集成|完整的\s*(接入|集成|教程|指南|流程)|从零|全流程|接入指南|集成指南|step\s*by(?:\s*step)?|end[-\s]?to[-\s]?end|full\s+(guide|tutorial|flow|integration)|complete\s+(guide|tutorial|integration)|quick\s*start|getting\s*started/i;
+/** 强 point 信号：API token / 错误码 / 具体操作词 → 优先走 point。
+ *  注意 camelCase 检测必须区分大小写（不加 /i），否则 React/RoomKit 这类普通专有名词会被误判为 API。 */
+const POINT_STRONG_SIGNAL_RE = /\b\d{5,7}\b|\bERR_[A-Z0-9_]+\b|\buse[A-Z]\w*\b|\b[A-Z][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*\b|\b(TRTC|TX)[A-Za-z0-9_]+\b|\bprops?\b|参数|事件|回调|error\s*code|错误码|怎么用|如何用|怎么实现|如何实现|怎么做|怎么发送|怎么获取|怎么监听|怎么接收|怎么调用|如何发送|如何获取|如何监听|如何调用|参数是什么/i;
+/** 判断是否含 API token（驼峰/点号/错误码/数字），这是最强的 point 结构信号。
+ *  camelCase 检测区分大小写，避免把 React/RoomKit 等专有名词误判为 API。 */
+function hasApiToken(prompt) {
+    return /\b[a-z]+[A-Z][A-Za-z0-9_]*\b|\b[A-Z][A-Za-z0-9_]*\.[A-Za-z_]\w*\b|\b(TRTC|TX)[A-Za-z0-9_]+\b|\b\d{5,7}\b|\bERR_[A-Z0-9_]+\b/.test(prompt);
+}
+export function classifyRetrievalMode(prompt) {
+    // 优先级分层（结构化信号，不依赖句末问号）：
+    // 1) narrative 优先（保守）：用户明确要完整指南/从零/step by step，
+    //    即使带操作词（如"完整指南怎么做"）也走 narrative，因为意图是完整文档。
+    if (NARRATIVE_INTENT_RE.test(prompt) && !hasApiToken(prompt)) {
+        return 'narrative';
+    }
+    // 2) API token 是最强 point 信号：query 出现具体 API/错误码/数字 → point
+    if (hasApiToken(prompt)) {
+        return 'point';
+    }
+    // 3) discovery：枚举词 + 无具体操作词（"有哪些接口 怎么实现"这类混合问法 → 走 point）
+    if (DISCOVERY_INTENT_RE.test(prompt) && !POINT_STRONG_SIGNAL_RE.test(prompt)) {
+        return 'discovery';
+    }
+    return 'point';
+}

package/knowledge/search/l1-enrich.js

@@ -0,0 +1,159 @@
+/**
+ * l1-enrich.ts
+ *
+ * 当检索结果命中 chat/urls 的 L1 URL 映射行（内容只是官网链接，无本地正文）时，
+ * server 内部 fetch 目标文档并回填 markdown 正文，避免把"只有一行 URL"的结果交给 AI。
+ *
+ * 设计：
+ * - 复用 fetch-doc-content 的清洗能力（白名单 + gzip 解压 + md 转换 + 截断）。
+ * - 仅对"纯 URL 映射行"的 fragment 回填；已有本地正文的 fragment 不动。
+ * - 逐条 fetch，但并发受限 + 超时 + 缓存兜底，失败静默（保留原 URL 行）。
+ */
+import { fetchDocContent } from '../../utils/fetch-doc-content.js';
+import { buildReferences } from '../doc-url-resolver.js';
+import { partitionFragments } from './search-core.js';
+import { isUrlMappingSource } from './url-row-scorer.js';
+/** 从 fragment 中取第一个可 fetch 的官方 URL */
+function primaryDocUrl(fragment) {
+    const urls = fragment.doc_urls ?? [];
+    return urls[0];
+}
+/**
+ * 单条 fragment 回填：
+ * 拉取到正文后，content 替换为官网 markdown，source 改写为官网 URL。
+ * 这样已回填片段不再命中 `chat/urls/` 的 L1 判定，AI 会把它当本地正文（L0）直接作答，无需再 fetch。
+ */
+async function enrichFragment(fragment, maxChars) {
+    const url = primaryDocUrl(fragment);
+    if (!url)
+        return null;
+    const result = await fetchDocContent(url, { maxChars });
+    if (!result)
+        return null;
+    return {
+        ...fragment,
+        content: result.markdown,
+        source: url,
+    };
+}
+/** 服务端 L1 领域类型：query 为客户端 SDK 意图时跳过，避免给 SDK 问题回填 REST/回调正文。
+ * 注意：'product' 不在集合中——产品概念/全局方案（如「内网代理实现方案」）跨平台适用，
+ * 客户端 query 命中 product 文档应正常 enrich（如 web SDK 用户搜「内网代理」应拿到正文）。
+ */
+const SERVER_SIDE_TYPES = new Set(['server_api', 'webhook']);
+/**
+ * 判定 L1 行是否属于「query 主领域」，用于限领域回填（避免 token 浪费在无关领域）。
+ * - query 有 frameworks（客户端 SDK 意图）：只回填 sdk/api 等客户端行，跳过 server_api/webhook/product。
+ * - query 无 frameworks（服务端/跨域意图）：只回填服务端行，跳过 sdk/api 客户端行。
+ * 语言无关、产品无关。
+ */
+function isInQueryDomain(fragment, queryFrameworks) {
+    if (queryFrameworks?.length) {
+        // 客户端意图：跳过服务端领域行
+        if (fragment.types.some((t) => SERVER_SIDE_TYPES.has(t)))
+            return false;
+        return true;
+    }
+    // 无 frameworks：跨域/服务端意图，跳过纯客户端 sdk/api 行
+    if (fragment.types.includes('sdk') || fragment.types.includes('api'))
+        return false;
+    return true;
+}
+/**
+ * 全部主领域 L1 行回填成功后，重写 message：
+ * 原始 message 是在回填前由 searchKnowledge 生成的（可能提示"需抓官网文档"），
+ * 回填后 source 已指向官网正文，应改为"直接基于正文作答"，避免 AI 被旧话术误导再去抓官网。
+ * 保留原 message 中 finalize_answer / submit_feedback 等必要工作流指令。
+ */
+function buildEnrichedMessage(response) {
+    const original = response.message ?? '';
+    const tail = original.includes('Final answer drafted')
+        ? original.slice(original.indexOf('Final answer drafted'))
+        : '';
+    return `Official content has been fetched and provided below; answer directly. ${tail}`;
+}
+/**
+ * 对 searchKnowledge 的结果做 L1 内容回填（异步，不影响同步检索主流程）。
+ * 返回回填后的新 response 副本。
+ *
+ * 修复（与 V3 `applySingleTopicTrim` 同步改造）：
+ * - 跨领域 L1 行 filter 提到早 return 之前，覆盖「无主领域 L1 行可 enrich」分支（A: 无 L1 / B: L1 全跨领域 / C: L1 全已回填）。
+ *   修复前 B case 早 return，跨领域 L1 行残留 + message 假 "fetch 提示"，LLM 拿到 URL 表行 content 无法作答。
+ * - targets 用 origIndex 跟踪原数组位置，确保回填后 fragments/references 仍按原顺序、保持一致。
+ */
+export async function enrichL1Fragments(response, opts) {
+    const maxChars = opts?.maxChars ?? 50000;
+    const concurrency = opts?.concurrency ?? 3;
+    const queryFrameworks = response.query?.frameworks;
+    const originalFragments = response.fragments ?? [];
+    // 公共 filter：跨领域 L1 行一律过滤（无论是否走 enrich 路径）
+    const afterFilter = originalFragments.filter((f) => {
+        if (!isUrlMappingSource(f.source))
+            return true;
+        // L1 行：已回填（source 已是官网 URL）或属于主领域 → 保留；否则过滤
+        return /^https?:\/\//i.test(f.source) || isInQueryDomain(f, queryFrameworks);
+    });
+    // 收集需要回填的 L1 fragment（仅纯 URL 映射行 + 属于 query 主领域 + 未回填）
+    // 关键：用 origIndex 跟踪原数组位置，enrich 后能正确回填，避免与公共 filter 后的 fragments 错位
+    const targets = [];
+    for (let i = 0; i < originalFragments.length; i += 1) {
+        const f = originalFragments[i];
+        if (isUrlMappingSource(f.source)
+            && !/^https?:\/\//i.test(f.source) // 未回填
+            && isInQueryDomain(f, queryFrameworks) // 属于主领域
+        ) {
+            targets.push({ f, origIndex: i });
+        }
+    }
+    // 无主领域 L1 行可 enrich（A: 无 L1 / B: L1 全跨领域 / C: L1 全已回填）
+    // 仍按公共 filter 后的 fragments 返回，并重建 references 保持 fragments/references 一致
+    if (targets.length === 0) {
+        const refs = afterFilter.length > 0 ? buildReferences(afterFilter) : [];
+        return {
+            ...response,
+            fragments: afterFilter,
+            meta: { ...response.meta, references: refs },
+        };
+    }
+    // 并发受限地逐条回填：仅成功拉取到正文的 fragment 才写入 Map
+    const enriched = new Map();
+    let cursor = 0;
+    const worker = async () => {
+        while (cursor < targets.length) {
+            const { f, origIndex } = targets[cursor];
+            cursor += 1;
+            const enrichedFragment = await enrichFragment(f, maxChars);
+            if (enrichedFragment)
+                enriched.set(origIndex, enrichedFragment);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, targets.length) }, () => worker()));
+    // 组装新 fragments：
+    // - 基于 originalFragments 替换已回填的 L1 行
+    // - 跨领域 L1 行再次过滤（保险，理论上已被 afterFilter 过滤）
+    const newFragments = originalFragments
+        .map((f, i) => enriched.get(i) ?? f)
+        .filter((f) => {
+        if (!isUrlMappingSource(f.source))
+            return true;
+        return /^https?:\/\//i.test(f.source) || isInQueryDomain(f, queryFrameworks);
+    });
+    // 基于回填后的新 fragments 重建 references，
+    // 使 meta.references 与 fragments 的 source 保持一致（回填后 source=官网 URL，不再指向 chat/urls 本地路径）。
+    const references = newFragments.length > 0 ? buildReferences(newFragments) : [];
+    // 仅当回填前「有 L1 行且无本地正文」（对应 buildAgentMessage 的"需抓官网"分支）且本次全部回填成功时，
+    // 重写 message 为「已提供官网正文」。用结构判断（而非正则匹配 message 文案），更稳、不随文案变化失效。
+    const { urlMapping, localDoc } = partitionFragments(originalFragments);
+    const originalNeedsFetch = urlMapping.length > 0 && localDoc.length === 0;
+    const allEnriched = originalNeedsFetch && enriched.size > 0 && enriched.size === targets.length;
+    const message = allEnriched ? buildEnrichedMessage(response) : response.message;
+    return {
+        ...response,
+        fragments: newFragments,
+        message,
+        meta: {
+            ...response.meta,
+            references,
+        },
+    };
+}

package/knowledge/search/query-normalizer.js

@@ -5,6 +5,45 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const SCHEMA_ROOT = path.resolve(__dirname, '../../resource/_schema');
 const QUERY_NORMALIZATION_FILE = path.join(SCHEMA_ROOT, 'query-normalization.yaml');
 const MAX_APPEND_TOKENS = 6;
+const BASE_QUERY_NORMALIZATION = {
+    literal: {
+        登录: ['login', 'signin', 'authentication', 'auth'],
+        鉴权: ['authentication', 'auth', 'usersig'],
+        错误码: ['error', 'error code', 'code'],
+        重复登录: ['repeat login', 'multi-device login', 'login policy'],
+        单聊: ['one-to-one', 'c2c', 'single chat'],
+        群聊: ['group chat', 'group message'],
+        直播群: ['avchatroom'],
+        直播间: ['avchatroom', 'live room'],
+        丢消息: ['message loss', 'reliability', 'priority'],
+        消息丢失: ['message loss', 'reliability', 'priority'],
+        重要消息: ['priority', 'high priority', 'critical message'],
+        用户: ['user', 'account'],
+        消息: ['message', 'messages'],
+        userSig: ['usersig', 'auth', 'authentication'],
+        AVChatRoom: ['直播群'],
+        'error code': ['错误码', '错误', 'code'],
+        'repeat login': ['重复登录', '多端登录', 'login policy'],
+        'one-to-one': ['单聊', 'c2c', 'single chat'],
+    },
+    word: {
+        login: ['登录', '鉴权', 'authentication', 'auth'],
+        auth: ['鉴权', '登录', 'authentication'],
+        authentication: ['鉴权', '登录', 'auth'],
+        usersig: ['userSig', '鉴权', '登录'],
+        error: ['错误', '错误码', 'error code'],
+        code: ['错误码', 'error code'],
+        message: ['消息', 'chat', 'conversation'],
+        messages: ['消息', 'chat', 'conversation'],
+        group: ['群组', '群聊', 'group chat'],
+        c2c: ['单聊', 'one-to-one', 'single chat'],
+        avchatroom: ['直播群'],
+        priority: ['重要消息', '优先级'],
+        reliability: ['消息可靠性'],
+        'message loss': ['丢消息', '消息丢失'],
+        'rate limit': ['限频', '刷屏'],
+    },
+};
 let cachedConfig = null;
 function unquote(input) {
     return input.trim().replace(/^['"]|['"]$/g, '');
@@ -12,7 +51,10 @@ function unquote(input) {
 function loadQueryNormalizationConfig() {
     if (cachedConfig)
         return cachedConfig;
-    const config = { literal: {}, word: {} };
+    const config = {
+        literal: { ...BASE_QUERY_NORMALIZATION.literal },
+        word: { ...BASE_QUERY_NORMALIZATION.word },
+    };
     if (!fs.existsSync(QUERY_NORMALIZATION_FILE)) {
         cachedConfig = config;
         return config;
@@ -46,16 +88,35 @@ function loadQueryNormalizationConfig() {
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+function hasCjk(text) {
+    return /[\u4e00-\u9fff]/.test(text);
+}
+function hasWordMatch(prompt, promptLower, needle) {
+    const normalizedNeedle = needle.toLowerCase();
+    if (hasCjk(normalizedNeedle)) {
+        return prompt.includes(needle);
+    }
+    const pattern = new RegExp(`\\b${escapeRegExp(normalizedNeedle)}\\b`, 'i');
+    return pattern.test(promptLower);
+}
 export function normalizeQueryPrompt(prompt) {
     const config = loadQueryNormalizationConfig();
     const terms = new Set(prompt.split(/\s+/).filter(Boolean));
     const promptLower = prompt.toLowerCase();
+    // 纯 EN 提问时跳过 CJK 注入：query expansion 的 CJK 翻译（群组/群聊/回调 等）
+    // 会进入 qCjk 触发「混合 query 只走 CJK 路径」分支，导致纯 EN title 行（CJK 路径
+    // 返回 0）失去 E7 boost，BM25 排名错误。典型回归：webhook 行「X webhook」全部
+    // 被「Before create group webhook」抢首位（+7 row top1 退化）。
+    // zh 端几乎都是 CJK 提问 → isPureEn=false → 行为完全不变。
+    const isPureEn = !hasCjk(prompt);
     let appendedCount = 0;
     const tryAppend = (tokens) => {
         for (const token of tokens) {
             if (appendedCount >= MAX_APPEND_TOKENS)
                 return;
             if (!terms.has(token)) {
+                if (isPureEn && hasCjk(token))
+                    continue;
                 terms.add(token);
                 appendedCount += 1;
             }
@@ -67,8 +128,7 @@ export function normalizeQueryPrompt(prompt) {
         tryAppend(expansion);
     }
     for (const [needle, expansion] of Object.entries(config.word)) {
-        const pattern = new RegExp(`\\b${escapeRegExp(needle.toLowerCase())}\\b`, 'i');
-        if (!pattern.test(promptLower))
+        if (!hasWordMatch(prompt, promptLower, needle))
             continue;
         tryAppend(expansion);
     }