@tencentcloud/sdk-mcp 1.6.8 → 1.7.1

package/knowledge/frontmatter-meta.js

@@ -0,0 +1,167 @@
+import * as yaml from 'js-yaml';
+const FRONTMATTER_RE = /^\uFEFF?---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+function uniq(arr) {
+    return [...new Set(arr)];
+}
+function normalizeString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value.trim();
+    return normalized ? normalized : undefined;
+}
+function normalizeStringArray(value) {
+    if (Array.isArray(value)) {
+        const normalized = value
+            .map((item) => (typeof item === 'string' ? item.trim() : ''))
+            .filter(Boolean);
+        return normalized.length ? uniq(normalized) : undefined;
+    }
+    if (typeof value === 'string') {
+        const normalized = value
+            .split(',')
+            .map((item) => item.trim())
+            .filter(Boolean);
+        return normalized.length ? uniq(normalized) : undefined;
+    }
+    return undefined;
+}
+function normalizeScenario(value) {
+    if (value === 'live' || value === 'voice')
+        return value;
+    return undefined;
+}
+function normalizeVariant(value) {
+    if (value === 'core-sdk' || value === 'preset')
+        return value;
+    return undefined;
+}
+function normalizeDocKind(value) {
+    if (value === 'capability_matrix' || value === 'unsupported_summary' || value === 'negative_faq') {
+        return value;
+    }
+    return undefined;
+}
+function normalizeCapabilityStatus(value) {
+    if (value === 'supported' || value === 'unsupported' || value === 'partial' || value === 'version_gated') {
+        return value;
+    }
+    return undefined;
+}
+function normalizeRetrievableScope(value) {
+    if (value === 'always')
+        return 'always';
+    return normalizeStringArray(value);
+}
+function parseFrontmatterObject(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) {
+        return {};
+    }
+    return input;
+}
+export function resolveFrontmatterMeta(rawMarkdown) {
+    const match = rawMarkdown.match(FRONTMATTER_RE);
+    if (!match) {
+        return {
+            content: rawMarkdown,
+            contentOffset: 0,
+            hasFrontmatter: false,
+            frontmatterMeta: {},
+            overrideFields: [],
+        };
+    }
+    const rawBlock = match[1] ?? '';
+    const contentOffset = match[0].length;
+    const content = rawMarkdown.slice(contentOffset);
+    let parsed;
+    try {
+        parsed = yaml.load(rawBlock);
+    }
+    catch (error) {
+        const parseError = error instanceof Error ? error.message : String(error);
+        return {
+            content,
+            contentOffset,
+            hasFrontmatter: true,
+            parseError,
+            frontmatterMeta: {},
+            overrideFields: [],
+        };
+    }
+    const fm = parseFrontmatterObject(parsed);
+    const frontmatterMeta = {};
+    const overrideFields = [];
+    const product = normalizeString(fm.product);
+    if (product) {
+        frontmatterMeta.product = product;
+        overrideFields.push('product');
+    }
+    const framework = normalizeStringArray(fm.frameworks) ?? normalizeStringArray(fm.framework);
+    if (framework?.length) {
+        frontmatterMeta.framework = framework;
+        overrideFields.push('framework');
+    }
+    const types = normalizeStringArray(fm.types);
+    if (types?.length) {
+        frontmatterMeta.types = types;
+        overrideFields.push('types');
+    }
+    const scenario = normalizeScenario(fm.scenario);
+    if (scenario !== undefined) {
+        frontmatterMeta.scenario = scenario;
+        overrideFields.push('scenario');
+    }
+    const variant = normalizeVariant(fm.variant);
+    if (variant) {
+        frontmatterMeta.variant = variant;
+        overrideFields.push('variant');
+    }
+    const scope = normalizeString(fm.scope);
+    if (scope) {
+        frontmatterMeta.scope = scope;
+        overrideFields.push('scope');
+    }
+    const docKind = normalizeDocKind(fm.doc_kind);
+    if (docKind) {
+        frontmatterMeta.doc_kind = docKind;
+        overrideFields.push('doc_kind');
+    }
+    const capabilityStatus = normalizeCapabilityStatus(fm.capability_status);
+    if (capabilityStatus) {
+        frontmatterMeta.capability_status = capabilityStatus;
+        overrideFields.push('capability_status');
+    }
+    const retrievableScope = normalizeRetrievableScope(fm.retrievable_scope);
+    if (retrievableScope) {
+        frontmatterMeta.retrievable_scope = retrievableScope;
+        overrideFields.push('retrievable_scope');
+    }
+    return {
+        content,
+        contentOffset,
+        hasFrontmatter: true,
+        frontmatterMeta,
+        overrideFields: uniq(overrideFields),
+    };
+}
+export function mergePathMetaWithFrontmatter(pathMeta, frontmatterMeta, overrideFields) {
+    if (!overrideFields.length) {
+        return {
+            ...pathMeta,
+            meta_source: 'path',
+            meta_override_fields: [],
+        };
+    }
+    const merged = {
+        ...pathMeta,
+        meta_source: 'merged',
+        meta_override_fields: uniq(overrideFields),
+    };
+    for (const field of overrideFields) {
+        const value = frontmatterMeta[field];
+        if (value === undefined)
+            continue;
+        // PathMeta 字段由 frontmatter 显式声明时优先；未声明字段保留路径推断兜底。
+        merged[field] = value;
+    }
+    return merged;
+}

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,8 +1,16 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { getSourceFileContent } from '../content-loader.js';
+import { computeCommonSectionTokens, isUrlMappingSource, normalizeUrlRowQuery, queryMatchesSection, scoreUrlRow } from './url-row-scorer.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const SCHEMA_ROOT = path.resolve(__dirname, '../../resource/_schema');
+/**
+ * 分组语义命中的基础分：当 scoreUrlRow=0 但该 url 行「分组被 query 命中 + types 匹配」时给予。
+ * 取值需满足 E7 strongCandidates 门槛（typeMatch ×1.2 后 ≥500 → base ≥417）。
+ * 只在「分组命中」时给（区别于旧的「所有 types 匹配行给 500」），避免无关行涌入。
+ */
+const SECTION_MATCH_BASE_SCORE = 450;
 export const DOC_PATH_MAP = {
     android: {
         core_api: 'TRTCCloud',
@@ -94,19 +102,6 @@ function loadFeatureAliases() {
     }
     return result;
 }
-/**
- * 将 prompt 按分隔符拆成子句列表，用于 url 行匹配。
- * 分隔符：、 ， , ； ; 空格
- * 保留每个子句的原文（去首尾空白），不引入新词。
- */
-function splitPromptIntoClauses(prompt) {
-    const raw = prompt
-        .replace(/rest\s*api|服务端|server\s*api|api|怎么|如何|什么|用哪个|查询/g, '')
-        .replace(/\s+/g, ' ')
-        .trim();
-    const parts = raw.split(/[、，,；;、\s]+/).filter((p) => p.length >= 2);
-    return parts.length > 0 ? parts : [raw];
-}
 const ROOM_CORE_SIGNAL = /atomicx\s*core|atomicxcore|atomicx|core\s*sdk|无\s*ui|自定义\s*ui|自实现|roomstore|store|useRoomState|useDeviceState|useLoginState/i;
 const ROOM_PRESET_SIGNAL = /预制|preset|roommainview|roommainwidget|默认\s*ui|主页面|房间主页面/i;
 const ROOM_FEATURE_SPECS = [
@@ -149,8 +144,6 @@ const ROOM_FEATURE_SPECS = [
 function detectRoomFeatureHits(prompt) {
     return ROOM_FEATURE_SPECS.filter((spec) => spec.promptPattern.test(prompt));
 }
-const LIVE_LIFECYCLE_PROMPT = /开播|创建直播|结束直播|停播|观看直播|退出直播|进房|离房|createLive|endLive|joinLive|leaveLive|host_streaming|audience_streaming/i;
-const LIVE_LIFECYCLE_APIS = ['createLive', 'endLive', 'joinLive', 'leaveLive'];
 export function runExactLookup(prompt, pool, norm) {
     const boosts = {};
     const exactHits = [];
@@ -300,113 +293,143 @@ export function runExactLookup(prompt, pool, norm) {
             }
         }
     }
-    // E6: chat urls boost（L1 URL 映射；错误码单独指向 urls/error-code.md）
-    if (!norm.product?.length || norm.product.includes('chat')) {
+    // E6: URL 映射文件 boost（L1；产品无关：任意 product 的 urls 均适用）
+    const hasUrlChunks = pool.some((c) => isUrlMappingSource(c.source));
+    if (hasUrlChunks) {
         if (/payload|登录|usersig|鉴权/i.test(prompt)) {
             for (const chunk of pool) {
-                if (chunk.source.includes('knowledge/chat/urls/')) {
-                    addBoost(chunk, 100, 'E6:chat-urls');
+                if (isUrlMappingSource(chunk.source)) {
+                    addBoost(chunk, 100, 'E6:urls');
                 }
             }
         }
         const errorCodeIntent = /错误码/i.test(prompt) || errorMatches.length > 0 || norm.searchIntent?.includes('error_code');
         if (errorCodeIntent) {
             for (const chunk of pool) {
-                if (chunk.source.includes('knowledge/chat/urls/error-code.md')) {
-                    addBoost(chunk, 180, 'E6:chat-error-code-url');
+                if (/\/error-code\.md$/i.test(chunk.source)) {
+                    addBoost(chunk, 180, 'E6:error-code-url');
                 }
             }
         }
         // E7: URL 映射表行级匹配（chunk.title = 子问题列）
-        // 策略：保留整句匹配，同时补充子句拆分 + 逐行匹配，同一 chunk 取最高分。
-        // 子句拆分使 "创建群组、加入群组、发送群组自定义消息" 能命中多行。
-        const clauses = splitPromptIntoClauses(prompt.toLowerCase());
-        const candidates = [];
-        for (const chunk of pool) {
-            if (!chunk.source.includes('knowledge/chat/urls/'))
-                continue;
-            const titleNorm = chunk.title.toLowerCase().replace(/\s+/g, '');
-            if (!titleNorm)
-                continue;
-            // 对每个子句和整句分别打分，取最高分
-            let bestScore = 0;
-            const allParts = [...clauses, prompt.toLowerCase().replace(/\s+/g, '')];
-            // 也按常见分隔符拆分 title 得到 tokens，用于不连续匹配
-            const titleTokens = titleNorm.split(/[\/（(（、,，\s]+/).filter(Boolean);
-            const seen = new Set();
-            for (const part of allParts) {
-                const pn = part.replace(/\s+/g, '');
-                if (pn.length < 2 || seen.has(pn))
-                    continue;
-                seen.add(pn);
-                let s = 0;
-                if (pn === titleNorm) {
-                    s = 1000;
-                }
-                else if (titleNorm.includes(pn)) {
-                    const trailing = titleNorm.slice(titleNorm.indexOf(pn) + pn.length);
-                    s = 800 - trailing.length * 80;
+        // 共享 scorer 按「REST 端点 > API token > 语义词对齐(IDF 加权)」打分。
+        // 支持 types 领域限定：上游推断出 types 时，优先 types 匹配的子文件行，
+        // 不匹配的行降权（避免跨域误命中，如 SDK 问题命中 restapi）。
+        if (normalizeUrlRowQuery(prompt).replace(/\s+/g, '').length >= 2) {
+            const candidates = [];
+            const hasTypeFilter = Boolean(norm.searchIntent?.length);
+            // 预收集 urls 行的分组结构：按 source 读整个 md 源文件，解析 `##` 分组与每行归属。
+            // 分组粗筛对所有 urls 资源生效（产品无关），不针对 webhook.md 打补丁。
+            const urlChunks = pool.filter((c) => isUrlMappingSource(c.source) && c.title.trim());
+            const sectionByChunk = new Map(); // chunk.id -> 分组标题
+            const sectionsBySource = new Map(); // source -> 分组标题集合
+            const mdRowsBySource = new Map(); // source -> {行title -> 分组标题}
+            for (const source of new Set(urlChunks.map((c) => c.source))) {
+                let full = '';
+                try {
+                    full = getSourceFileContent(source);
                 }
-                else if (pn.includes(titleNorm)) {
-                    s = 700 + titleNorm.length;
+                catch {
+                    full = '';
                 }
-                else if (titleTokens.some((token) => pn.includes(token) || token.includes(pn))) {
-                    // 子句匹配 title 的 token（如 "创建群组" 匹配 "创建/解散群组（普通群管理）" 中的 "创建" token）
-                    s = 600;
+                let cur = '';
+                const rows = new Map();
+                const sections = new Set();
+                for (const line of full.split('\n')) {
+                    const h = line.match(/^#{2,3}\s+(.+)$/);
+                    if (h) {
+                        cur = h[1].trim();
+                        sections.add(cur);
+                        continue;
+                    }
+                    const row = line.match(/^\|\s*([^|]+?)\s*\|\s*`(https?:[^`]+)`/);
+                    if (row)
+                        rows.set(row[1].trim(), cur);
                 }
-                if (s > bestScore)
-                    bestScore = s;
+                mdRowsBySource.set(source, rows);
+                sectionsBySource.set(source, sections);
             }
-            if (bestScore <= 0) {
-                // 退化：子句无匹配时，试 loose（去噪声字 + 单字容错）
-                const qn = clauses[0].replace(/发送/g, '发');
-                if (qn.length >= 3 && titleNorm.includes(qn)) {
-                    bestScore = 500;
-                    if (/批量|群组|群流|广播|导入|公众号|已读|回执/.test(titleNorm)
-                        && !/批量|群组|群|已读|回执/.test(clauses[0])) {
-                        bestScore -= 250;
-                    }
-                    if (/^单发/.test(titleNorm) && /发送|单聊/.test(clauses[0])) {
-                        bestScore += 120;
+            for (const chunk of urlChunks) {
+                const section = mdRowsBySource.get(chunk.source)?.get(chunk.title);
+                if (section)
+                    sectionByChunk.set(chunk.id, section);
+            }
+            // 计算每个 source 的共有词（该文件所有分组都出现的词）
+            const commonTokensBySource = new Map();
+            for (const [source, sections] of sectionsBySource) {
+                commonTokensBySource.set(source, computeCommonSectionTokens([...sections]));
+            }
+            for (const chunk of urlChunks) {
+                const scoreResult = scoreUrlRow(prompt, chunk.title);
+                // types 领域限定：query types 与 chunk types 是否有交集
+                const typeMatch = hasTypeFilter
+                    ? (norm.searchIntent ?? []).some((t) => chunk.types.includes(t))
+                    : true;
+                // 分组粗筛：query 是否命中该 chunk 所在的分组。
+                // 命中分组 → 正常；未命中分组 → 降权（不排除，避免 query 与分组名匹配不准时误杀）。
+                const section = sectionByChunk.get(chunk.id);
+                const commonTokens = commonTokensBySource.get(chunk.source);
+                const sectionMatch = section && commonTokens
+                    ? queryMatchesSection(prompt, section, commonTokens)
+                    : true; // 无分组信息时不做粗筛（保持原行为）
+                // 高 scoreUrlRow 兜底：scoreUrlRow ≥ 700 是极强语义信号（query 2-gram 全覆盖），
+                // 此时不应被 sectionMatch 软降权压制。常见场景：短 query 如「群消息发送异常」
+                // 跟 section 标题「群组系统回调」共享字符少（仅「群」），sectionMatch 失败，
+                // 但 row title 本身完美匹配 user 意图，强行降权会让单聊 row 顶上。
+                const highConfidence = scoreResult.score >= 700;
+                // 分组语义命中基础分：scoreUrlRow 可能因「同义词/长句」对精确行打 0 分
+                // （如「群消息发送前回调」vs「群内发言之前回调」），但分组已语义命中，
+                // 给予基础分进入候选，避免该领域行被 score<=0 排除。
+                // 区别于旧的「所有 types 匹配行给 500」——只在分组命中时才给，避免无关行涌入。
+                if (scoreResult.score <= 0) {
+                    if (sectionMatch && typeMatch) {
+                        candidates.push({ chunk, score: SECTION_MATCH_BASE_SCORE, typeMatch, sectionMatch });
                     }
+                    continue;
                 }
+                // finalScore 排序用：sectionMatch 失败且非高置信时，×0.7 软降权。
+                // 高置信（scoreUrlRow ≥ 700）跳过降权，避免短 query + 长 section 标题时的误杀。
+                const finalScore = (sectionMatch || highConfidence) ? scoreResult.score : scoreResult.score * 0.7;
+                candidates.push({ chunk, score: finalScore, typeMatch, sectionMatch });
             }
-            if (bestScore > 0) {
-                candidates.push({ chunk, score: bestScore });
-            }
-        }
-        candidates.sort((a, b) => b.score - a.score);
-        const strongCandidates = candidates
-            .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 >= 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);
-    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}`);
+            candidates.sort((a, b) => b.score - a.score);
+            // types 匹配的行加分（更优先）；不匹配的行轻度降权但仍可兜底召回。
+            // 避免上游 types 推断不准确时误杀正确文档（如「多端登录配置」被推断为 feature 而非 product）。
+            const typeScored = candidates
+                .map((c) => (c.typeMatch ? { ...c, score: c.score * 1.2 } : { ...c, score: c.score * 0.6 }))
+                .filter(({ score }) => score >= 500);
+            // 同分 row（典型：query「群消息撤回回调」时「撤回群消息」跟「单聊消息撤回」都 scoreUrlRow=660），
+            // 按「query 字符集被 row title 覆盖比例」再排，覆盖更高的 row 排前。
+            // 修 E7 boost idx=0 多 40 分的副作用：让字符集更精准的 row 拿 idx=0 → 300 分而不是 260 分。
+            const queryChars = new Set(prompt.match(/[\u4e00-\u9fff]/g) ?? []);
+            const charCoverage = (title) => {
+                if (queryChars.size === 0)
+                    return 0;
+                const titleChars = new Set(title.match(/[\u4e00-\u9fff]/g) ?? []);
+                let hit = 0;
+                for (const ch of queryChars)
+                    if (titleChars.has(ch))
+                        hit += 1;
+                return hit / queryChars.size;
+            };
+            const strongCandidates = typeScored
+                .sort((a, b) => {
+                // 优先按 typeScored score 降序；同分时按字符集覆盖率降序
+                if (b.score !== a.score)
+                    return b.score - a.score;
+                return charCoverage(b.chunk.title) - charCoverage(a.chunk.title);
+            })
+                .slice(0, 12);
+            strongCandidates.forEach(({ chunk, score }, idx) => {
+                // 递减 boost：前两条更高，其余保持可召回但不过度压制 BM25
+                const amount = idx === 0
+                    ? 200 + Math.min(score, 100)
+                    : idx === 1
+                        ? 170 + Math.min(score, 90)
+                        : Math.max(score >= 600 ? 150 : 90, 140 - idx * 8);
+                addBoost(chunk, amount, `E7:url-row:${chunk.title}`);
+                urlRowHitChunkIds.add(chunk.id);
+            });
         }
     }
     // E9: chat faq——types=faq 时优先 knowledge 语料，避免 integration 文档内 FAQ 章节抢首位
@@ -422,28 +445,6 @@ export function runExactLookup(prompt, pool, norm) {
             }
         }
     }
-    // E11: LiveKit 生命周期意图强召回（开播/停播/观看/退出）
-    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 消歧 + unsupported feature 强召回
     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,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 特例：Conference Web 实际语料在 roomkit/core-sdk/vue，web 查询应可命中。
-            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;
+}