@tencent-rtc/mcp 1.6.7 → 1.7.0

package/knowledge/path-meta.js

@@ -110,7 +110,9 @@ export function inferPathMeta(relativeSource) {
         // 两者都统一标记为 types=['faq']，便于通过 types=faq 命中“经验类问答”。
         if (parts[1] === 'chat' && parts[2] === 'best-practice' && parts.length >= 5) {
             const fwSlug = normalizeFrameworkDir(parts[3]);
-            framework = [fwSlug];
+            // chat best-practice 的 common 目录表示平台通用（Web + 小程序），
+            // 不能按 framework=common 打标，否则会被 framework 硬过滤误排除。
+            framework = fwSlug === 'common' ? ['web', 'miniprogram'] : [fwSlug];
             types.push('faq');
         }
         if (parts[1] === 'chat' && parts[2] === 'faq' && parts.length >= 4) {
@@ -137,13 +139,13 @@ export function inferPathMeta(relativeSource) {
         }
         // callkit 最佳实践目录：knowledge/callkit/best-practice/{platform}/{topic}.md
         // 统一按 FAQ/经验类知识处理，支持 types=faq + frameworks={platform} 的精确检索。
+        // 与 chat best-practice 对齐：common 目录表示多平台通用，按最全集覆盖。
         if (parts[1] === 'callkit' && parts[2] === 'best-practice' && parts.length >= 5) {
-            framework = [normalizeFrameworkDir(parts[3])];
+            const fwSlug = normalizeFrameworkDir(parts[3]);
+            framework = fwSlug === 'common'
+                ? ['react', 'vue', 'miniprogram', 'web', 'android', 'ios', 'flutter', 'uni-app']
+                : [fwSlug];
             types.push('faq');
-            // calls 相关最佳实践既是 FAQ 也是 API 语义，避免 types=api 时被误过滤。
-            if (/(callengine-invitation|callkit-call-vs-calls)\.md$/i.test(fileName)) {
-                types.push('api');
-            }
         }
         if (parts.includes('faq'))
             types.push('faq', 'error_code');
@@ -226,6 +228,15 @@ export function inferPathMeta(relativeSource) {
             types.push('component');
         if (fileName === 'faq.md')
             types.push('faq');
+        // livekit 最佳实践目录：knowledge/livekit/best-practice/{platform}/{topic}.md
+        // 与 chat/callkit 对齐：common 目录表示多平台通用，按最全集覆盖。
+        if (parts[1] === 'livekit' && parts[2] === 'best-practice' && parts.length >= 5) {
+            const fwSlug = normalizeFrameworkDir(parts[3]);
+            framework = fwSlug === 'common'
+                ? ['react', 'vue', 'web', 'android', 'ios', 'flutter']
+                : [fwSlug];
+            types.push('faq');
+        }
         // 与 roomkit 对齐：core-sdk 下 capability-matrix.md / unsupported-features.md
         //   视为能力边界文档（doc_kind + capability_status），方便检索层按 doc_kind 过滤
         const docMeta = inferDocMeta(fileName);
@@ -255,6 +266,15 @@ export function inferPathMeta(relativeSource) {
             types.push('feature');
         if (parts.includes('faq'))
             types.push('faq', 'error_code');
+        // roomkit 最佳实践目录：knowledge/roomkit/best-practice/{platform}/{topic}.md
+        // 与 chat/callkit 对齐：common 目录表示多平台通用，按最全集覆盖。
+        if (parts[1] === 'roomkit' && parts[2] === 'best-practice' && parts.length >= 5) {
+            const fwSlug = normalizeFrameworkDir(parts[3]);
+            framework = fwSlug === 'common'
+                ? ['react', 'vue', 'web', 'android', 'ios', 'flutter']
+                : [fwSlug];
+            types.push('faq');
+        }
         const docMeta = inferDocMeta(fileName);
         doc_kind = docMeta.doc_kind;
         capability_status = docMeta.capability_status ?? capability_status;
@@ -333,5 +353,7 @@ export function inferPathMeta(relativeSource) {
         doc_kind,
         capability_status,
         retrievable_scope,
+        meta_source: 'path',
+        meta_override_fields: [],
     };
 }

package/knowledge/search/exact-lookup.js

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { normalizeUrlRowQuery, scoreUrlRow } from './url-row-scorer.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const SCHEMA_ROOT = path.resolve(__dirname, '../../resource/_schema');
 export const DOC_PATH_MAP = {
@@ -69,184 +70,6 @@ function loadJson(fileName, fallback) {
         return fallback;
     return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
 }
-const E7_EN_STOPWORDS = new Set([
-    'the', 'and', 'for', 'with', 'from', 'into', 'about', 'using', 'via',
-    'how', 'what', 'where', 'when', 'which', 'please', 'docs', 'documentation',
-    'tencent', 'im', 'rest', 'server', 'webhook', 'webhooks',
-]);
-/** Generic terms — excluded from API-token hits to avoid false positives */
-const E7_GENERIC_TERMS = new Set([
-    'message', 'messages', 'group', 'groups', 'user', 'users', 'account', 'accounts',
-    'send', 'get', 'set', 'delete', 'create', 'update', 'query', 'before', 'after',
-    'webhook', 'friend', 'single', 'multiple', 'history', 'chat', 'sdk', 'api',
-    'profile', 'conversation', 'import', 'recall', 'modify', 'pull', 'mark', 'data',
-    'list', 'online', 'status', 'custom', 'attributes', 'counter', 'member', 'members',
-    'management', 'overview', 'integration', 'initialization', 'billing', 'topic',
-    'topics', 'community', 'robot', 'chatbot', 'streaming', 'broadcast', 'official',
-    'extension', 'receipt', 'receipts', 'global', 'mute', 'ban', 'unban', 'forbid',
-    'ordinary', 'specified', 'historical', 'unread', 'read', 'configure', 'configuration', 'invalidate',
-    'invalidating', 'disband', 'change', 'search', 'cloud', 'local', 'robot', 'bots',
-]);
-const E7_QUERY_NOISE = /\b(rest\s*ful?\s*api|rest\s*api|server\s*api|webhook|webhooks|how\s+to|how\s+do\s+i|what\s+is|where\s+is|please|documentation|docs?)\b/gi;
-const E7_QUERY_NOISE_CN = /怎么|如何|什么|用哪个|查询|服务端/g;
-const E7_PHRASES = [
-    'before send one-to-one message',
-    'after send one-to-one message',
-    'one-to-one message',
-    'group message',
-    'recall group message',
-    'recall one-to-one message',
-    'send one-to-one message',
-    'send single chat message',
-    'getmessagelist',
-    'message history',
-    'add friend',
-    'import single account',
-    'import a single account',
-    'multi-device login',
-    'multi device login',
-    'login policy',
-    'login strategy',
-    'message storage duration',
-    'roaming message storage',
-];
-function extractRestEndpoints(text) {
-    return [...text.matchAll(/v4\/[\w/]+/gi)].map((m) => m[0].toLowerCase());
-}
-function extractE7ApiTokens(text) {
-    const tokens = new Set();
-    for (const match of text.matchAll(/\b([a-z][a-z0-9_]{2,})\b/gi)) {
-        const token = match[1].toLowerCase();
-        if (!E7_GENERIC_TERMS.has(token) && !E7_EN_STOPWORDS.has(token))
-            tokens.add(token);
-    }
-    for (const match of text.matchAll(/\b([A-Z][A-Za-z0-9]*(?:\.[A-Za-z]\w*)?)\b/g)) {
-        const token = match[1].toLowerCase();
-        if (!E7_GENERIC_TERMS.has(token))
-            tokens.add(token);
-    }
-    for (const match of text.matchAll(/([a-z]+[A-Z][A-Za-z0-9]*)/g)) {
-        tokens.add(match[1].toLowerCase());
-    }
-    return [...tokens];
-}
-function normalizeE7Text(text) {
-    return text
-        .toLowerCase()
-        .replace(E7_QUERY_NOISE, ' ')
-        .replace(E7_QUERY_NOISE_CN, '')
-        .replace(/[^\w\u4e00-\u9fff/]+/g, ' ')
-        .replace(/\s+/g, ' ')
-        .trim();
-}
-function phraseBonus(query, title) {
-    const q = query.toLowerCase().replace(/\s+/g, ' ');
-    const t = title.toLowerCase();
-    let bonus = 0;
-    for (const phrase of E7_PHRASES) {
-        if (q.includes(phrase) && t.includes(phrase))
-            bonus += 180;
-    }
-    if (/send single chat message/.test(q) && /send one-to-one message/.test(t))
-        bonus += 200;
-    if (/recall group message/.test(q) && /recall group message/.test(t))
-        bonus += 200;
-    if (/before send one-to-one message/.test(q) && /before send one-to-one message/.test(t))
-        bonus += 220;
-    if (/\bbefore\b/.test(q) && t.startsWith('before '))
-        bonus += 120;
-    if (/\bafter\b/.test(q) && t.startsWith('after '))
-        bonus += 120;
-    if (/多端登录/.test(query) && /多端登录|multi[\s-]?device/i.test(title))
-        bonus += 220;
-    if (/登录策略|login\s*(policy|strategy)/i.test(query) && /登录策略|login\s*(policy|strategy)/i.test(title))
-        bonus += 200;
-    return bonus;
-}
-function scoreE7UrlRow(query, title) {
-    const queryEndpoints = extractRestEndpoints(query);
-    const titleEndpoints = extractRestEndpoints(title);
-    for (const qe of queryEndpoints) {
-        if (titleEndpoints.some((te) => te === qe || te.endsWith(qe) || qe.endsWith(te))) {
-            return 1000;
-        }
-    }
-    let score = phraseBonus(query, title);
-    const titleLower = title.toLowerCase();
-    const queryApis = extractE7ApiTokens(query);
-    let apiHits = 0;
-    let longApiHit = false;
-    for (const api of queryApis) {
-        if (!titleLower.includes(api))
-            continue;
-        apiHits += 1;
-        if (api.length >= 8)
-            longApiHit = true;
-    }
-    if (longApiHit)
-        score = Math.max(score, 940);
-    else if (apiHits >= 2)
-        score = Math.max(score, 900);
-    else if (apiHits === 1)
-        score = Math.max(score, 860);
-    const qNorm = normalizeE7Text(query);
-    const tNorm = normalizeE7Text(title);
-    const qTokens = qNorm.split(' ').filter((t) => t.length >= 3 && !E7_GENERIC_TERMS.has(t));
-    const tTokens = tNorm.split(' ').filter((t) => t.length >= 3 && !E7_GENERIC_TERMS.has(t));
-    let overlap = 0;
-    for (const qt of qTokens) {
-        if (tTokens.some((tt) => tt.includes(qt) || qt.includes(tt)))
-            overlap += 1;
-    }
-    if (overlap >= 3)
-        score = Math.max(score, 720 + overlap * 15);
-    else if (overlap >= 2)
-        score = Math.max(score, 650);
-    else if (overlap >= 1)
-        score = Math.max(score, 520);
-    const qCompact = qNorm.replace(/\s+/g, '');
-    const tCompact = tNorm.replace(/\s+/g, '');
-    if (qCompact.length >= 5 && tCompact.includes(qCompact)) {
-        score = Math.max(score, 560 - Math.min(tCompact.length - qCompact.length, 80));
-    }
-    else if (tCompact.length >= 5 && qCompact.includes(tCompact)) {
-        score = Math.max(score, 500 + Math.min(tCompact.length, 30));
-    }
-    const qCjk = query.replace(/[^\u4e00-\u9fff]/g, '');
-    const tCjk = title.replace(/[^\u4e00-\u9fff]/g, '');
-    if (qCjk.length >= 2 && tCjk.includes(qCjk)) {
-        let cjkScore = 500;
-        if (/批量|群组|群流|广播|导入|公众号|已读|回执/.test(tCjk) && !/批量|群组|群|已读|回执/.test(qCjk)) {
-            cjkScore -= 250;
-        }
-        if (/^单发/.test(tCjk) && /发送|单聊/.test(qCjk))
-            cjkScore += 120;
-        score = Math.max(score, cjkScore);
-    }
-    if (score <= 0)
-        return 0;
-    const queryL = query.toLowerCase();
-    const titleL = title.toLowerCase();
-    if (/group/.test(queryL) && /one-to-one|c2c/.test(titleL) && !/group/.test(titleL))
-        score -= 400;
-    if (/one-to-one|c2c|single chat/.test(queryL) && /import.*account|add friend/.test(titleL))
-        score -= 400;
-    if (/send.*message|one-to-one message/.test(queryL) && /add friend|import.*account/.test(titleL))
-        score -= 400;
-    if (/getmessagelist|message history/.test(qCompact) && /integration|initialization/.test(titleL) && !/getmessagelist|history/.test(tCompact))
-        score -= 400;
-    if (/extension/.test(titleL) && !/extension/.test(queryL))
-        score -= 350;
-    if (/\bbefore\b/.test(queryL) && !/^before\b/.test(titleL.trim()))
-        score -= 250;
-    if (/\bafter\b/.test(queryL) && !/^after\b/.test(titleL.trim()))
-        score -= 250;
-    if (/batch|multiple/.test(titleL) && !/batch|multiple/.test(queryL))
-        score -= 200;
-    if (/group/.test(titleL) && !/group|channel/.test(queryL) && /one-to-one|c2c|single chat/.test(queryL))
-        score -= 200;
-    return Math.max(score, 0);
-}
 function loadFeatureAliases() {
     const filePath = path.join(SCHEMA_ROOT, 'feature-aliases.yaml');
     if (!fs.existsSync(filePath))
@@ -314,8 +137,6 @@ const ROOM_FEATURE_SPECS = [
 function detectRoomFeatureHits(prompt) {
     return ROOM_FEATURE_SPECS.filter((spec) => spec.promptPattern.test(prompt));
 }
-const LIVE_LIFECYCLE_PROMPT = /create\s*live|end\s*live|join\s*live|leave\s*live|start\s*live|stop\s*live|watch\s*live|host_streaming|audience_streaming|开播|创建直播|结束直播|停播|观看直播|退出直播|进房|离房|createLive|endLive|joinLive|leaveLive/i;
-const LIVE_LIFECYCLE_APIS = ['createLive', 'endLive', 'joinLive', 'leaveLive'];
 export function runExactLookup(prompt, pool, norm) {
     const boosts = {};
     const exactHits = [];
@@ -486,52 +307,35 @@ export function runExactLookup(prompt, pool, norm) {
             }
         }
         // E7: URL map row match (chunk.title = Query column); boost multiple strong hits with pinned relaxation
-        if (normalizeE7Text(prompt).replace(/\s+/g, '').length >= 2) {
+        if (normalizeUrlRowQuery(prompt).replace(/\s+/g, '').length >= 2) {
             const candidates = [];
             for (const chunk of pool) {
                 if (!chunk.source.includes('knowledge/chat/urls/'))
                     continue;
                 if (!chunk.title.trim())
                     continue;
-                const score = scoreE7UrlRow(prompt, chunk.title);
-                if (score > 0) {
-                    candidates.push({ chunk, score });
+                const scoreResult = scoreUrlRow(prompt, chunk.title);
+                if (scoreResult.score > 0) {
+                    candidates.push({ chunk, score: scoreResult.score });
                 }
             }
             candidates.sort((a, b) => b.score - a.score);
             const strongCandidates = candidates
-                .filter(({ score }) => score >= 150)
+                .filter(({ score }) => score >= 500)
                 .slice(0, 12);
             strongCandidates.forEach(({ chunk, score }, idx) => {
+                // 递减 boost：前两条更高，其余保持可召回但不过度压制 BM25
+                // token 匹配（600 分）至少给 150，确保子句拆分的行不被 BM25 原始分压掉
                 const amount = idx === 0
                     ? 200 + Math.min(score, 100)
                     : idx === 1
                         ? 170 + Math.min(score, 90)
-                        : Math.max(score >= 300 ? 100 : 70, 100 - idx * 5);
+                        : Math.max(score >= 600 ? 150 : 90, 140 - idx * 8);
                 addBoost(chunk, amount, `E7:url-row:${chunk.title}`);
                 urlRowHitChunkIds.add(chunk.id);
             });
         }
     }
-    // E8: 集成查阅意图 boost——prompt 含集成/接入/快速开始/接入文档等意图词时，
-    // 把 {integration|knowledge}/{product}/preset/{fw}/integration.md 系列文件顶到前列。
-    // 解决问题：集成文档内容长、词密度低，BM25 原始分常被短小的 features/ 文档压过。
-    // 注：android-view / ios-uikit 已迁到 knowledge corpus，但同样是集成指引，需要一并 boost。
-    const isIntegrationIntent = /集成|接入|快速开始|快速接入|集成文档|接入文档|集成指南|接入指南|接入流程|集成步骤|如何接入|如何集成|怎么接入|怎么集成/i.test(prompt)
-        || /\b(integrat(e|ion|ing)|getting\s+started|quick\s+start|setup\s+guide|how\s+to\s+(integrate|set\s+up)|install(?:ation)?\s+guide)\b/i.test(prompt);
-    if (isIntegrationIntent && norm.product?.length && norm.frameworks?.length) {
-        for (const chunk of pool) {
-            if (!norm.product.includes(chunk.product))
-                continue;
-            const fwMatch = norm.frameworks.some((fw) => chunk.framework.includes(fw));
-            if (!fwMatch)
-                continue;
-            // 命中 preset/{fw}/integration.md 系列（含 integration/ 和 knowledge/ 两种 corpus）
-            if (!chunk.source.includes('/preset/') || (!chunk.source.endsWith('integration.md') && !chunk.source.endsWith('-integration.md')))
-                continue;
-            addBoost(chunk, 120, `E8:integration-doc:${chunk.source}`);
-        }
-    }
     // E9: chat faq — types=faq 时优先 knowledge/ 语料，避免 integration 文档内 FAQ 章节抢首位
     if (norm.searchIntent?.includes('faq') && norm.product?.includes('chat')) {
         const authPrompt = /auth|login|signature|usersig|鉴权|登录/i.test(prompt);
@@ -545,28 +349,6 @@ export function runExactLookup(prompt, pool, norm) {
             }
         }
     }
-    // E11: LiveKit lifecycle strong recall
-    if (norm.product?.includes('live') && LIVE_LIFECYCLE_PROMPT.test(prompt)) {
-        const queryApiHits = LIVE_LIFECYCLE_APIS.filter((api) => new RegExp(api, 'i').test(prompt));
-        for (const chunk of pool) {
-            const isLiveCoreIntegration = chunk.source.startsWith('knowledge/livekit/core-sdk/live/')
-                && chunk.source.endsWith('/integration.md');
-            const isVoiceCoreIntegration = chunk.source.startsWith('knowledge/livekit/core-sdk/voice/')
-                && chunk.source.endsWith('/integration.md');
-            if (!isLiveCoreIntegration && !isVoiceCoreIntegration)
-                continue;
-            if (norm.scenario === 'live' && !isLiveCoreIntegration)
-                continue;
-            if (norm.scenario === 'voice' && !isVoiceCoreIntegration)
-                continue;
-            addBoost(chunk, 140, 'E11:live-lifecycle-core-integration');
-            for (const api of queryApiHits) {
-                if (chunk.api_names?.some((name) => name.toLowerCase() === api.toLowerCase())) {
-                    addBoost(chunk, 160, `E11:live-lifecycle-api:${api}`);
-                }
-            }
-        }
-    }
     // E10: RoomKit Core/Preset disambiguation + unsupported feature routing
     if (norm.product?.includes('room') && norm.frameworks?.length) {
         const platform = norm.frameworks.find((fw) => ['android', 'ios', 'flutter', 'vue'].includes(fw));

package/knowledge/search/filter-pool.js

@@ -1,4 +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，
@@ -41,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 推断：避免对显然唯一的平台再发起询问 */
@@ -70,15 +64,16 @@ function inferImplicitFramework(products, frameworks, prompt) {
     return undefined;
 }
 export function normalizeParams(params) {
+    const normalizedPrompt = normalizeQueryPrompt(params.prompt);
     const limit = Math.min(Math.max(params.limit ?? 8, 1), 16);
-    const effectiveFramework = inferImplicitFramework(params.product, params.frameworks, params.prompt);
+    const effectiveFramework = inferImplicitFramework(params.product, params.frameworks, normalizedPrompt);
     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);
+    const types = resolveTypes(params.product, params.types, normalizedPrompt, requestedFrameworks);
     return {
-        prompt: params.prompt,
+        prompt: normalizedPrompt,
         product: params.product,
         framework: effectiveFramework,
         frameworks,
@@ -131,27 +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/'));
-            if (!explicitMatch && !wildcardAllowed && !callCoreWebFallback && !liveWebVueFallback)
+            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,13 @@
+/** 枚举/目录浏览意图 */
+const DISCOVERY_INTENT_RE = /有哪些|支持哪些|列一下|清单|目录|可用|全部|全量|对比|怎么选|选哪个|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/错误码/参数 → 即使同时命中 narrative 关键词也优先走 point */
+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|\b参数\b|\b事件\b|\b回调\b|\berror\s*code\b|错误码|怎么用|如何用|参数是什么/i;
+export function classifyRetrievalMode(prompt) {
+    if (NARRATIVE_INTENT_RE.test(prompt) && !POINT_STRONG_SIGNAL_RE.test(prompt))
+        return 'narrative';
+    if (DISCOVERY_INTENT_RE.test(prompt))
+        return 'discovery';
+    return 'point';
+}

package/knowledge/search/query-normalizer.js

@@ -0,0 +1,129 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+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'],
+        webhook: ['回调', 'webhook', 'callbacks'],
+        avchatroom: ['直播群'],
+        priority: ['重要消息', '优先级'],
+        reliability: ['消息可靠性'],
+        'message loss': ['丢消息', '消息丢失'],
+        'rate limit': ['限频', '刷屏'],
+    },
+};
+let cachedConfig = null;
+function unquote(input) {
+    return input.trim().replace(/^['"]|['"]$/g, '');
+}
+function loadQueryNormalizationConfig() {
+    if (cachedConfig)
+        return cachedConfig;
+    const config = {
+        literal: { ...BASE_QUERY_NORMALIZATION.literal },
+        word: { ...BASE_QUERY_NORMALIZATION.word },
+    };
+    if (!fs.existsSync(QUERY_NORMALIZATION_FILE)) {
+        cachedConfig = config;
+        return config;
+    }
+    const text = fs.readFileSync(QUERY_NORMALIZATION_FILE, 'utf-8');
+    let currentSection = '';
+    for (const rawLine of text.split('\n')) {
+        const line = rawLine.trimEnd();
+        if (!line.trim() || line.trimStart().startsWith('#'))
+            continue;
+        const sectionMatch = line.match(/^(literal|word):\s*$/);
+        if (sectionMatch) {
+            currentSection = sectionMatch[1];
+            continue;
+        }
+        const entryMatch = line.match(/^\s{2}([^:#]+):\s*\[(.*)\]\s*$/);
+        if (!entryMatch || !currentSection)
+            continue;
+        const key = unquote(entryMatch[1]);
+        const values = entryMatch[2]
+            .split(',')
+            .map((token) => unquote(token))
+            .filter(Boolean);
+        if (!key || !values.length)
+            continue;
+        config[currentSection][key] = values;
+    }
+    cachedConfig = config;
+    return config;
+}
+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();
+    let appendedCount = 0;
+    const tryAppend = (tokens) => {
+        for (const token of tokens) {
+            if (appendedCount >= MAX_APPEND_TOKENS)
+                return;
+            if (!terms.has(token)) {
+                terms.add(token);
+                appendedCount += 1;
+            }
+        }
+    };
+    for (const [needle, expansion] of Object.entries(config.literal)) {
+        if (!prompt.includes(needle))
+            continue;
+        tryAppend(expansion);
+    }
+    for (const [needle, expansion] of Object.entries(config.word)) {
+        if (!hasWordMatch(prompt, promptLower, needle))
+            continue;
+        tryAppend(expansion);
+    }
+    return [...terms].join(' ');
+}