@tencentcloud/sdk-mcp 1.7.7 → 1.7.8

package/knowledge/search/exact-lookup.js

@@ -6,11 +6,17 @@ import { computeCommonSectionTokens, isUrlMappingSource, normalizeUrlRowQuery, q
 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」），避免无关行涌入。
+ * 分组语义命中兜底相关常量。
+ * 结构性约束：兜底分永远 < 同批次真实命中的最低分，避免「未命中兜底反超弱命中真分」倒挂。
+ *
+ * - FALLBACK_SAFETY_MARGIN：兜底分与最低真实命中分之间的安全间距。
+ * - FALLBACK_MIN_SCORE：兜底分硬下限（无真实命中时的默认底），仍能进入候选池；
+ *   后续 filter 门槛会决定它是否上榜。
+ * - FALLBACK_DEFAULT_BASELINE：无任何真实命中时用于估算兜底的默认真分基线。
  */
-const SECTION_MATCH_BASE_SCORE = 450;
+const FALLBACK_SAFETY_MARGIN = 50;
+const FALLBACK_MIN_SCORE = 100;
+const FALLBACK_DEFAULT_BASELINE = 500;
 export const DOC_PATH_MAP = {
     android: {
         core_api: 'TRTCCloud',
@@ -316,8 +322,14 @@ export function runExactLookup(prompt, pool, norm) {
         // 支持 types 领域限定：上游推断出 types 时，优先 types 匹配的子文件行，
         // 不匹配的行降权（避免跨域误命中，如 SDK 问题命中 restapi）。
         if (normalizeUrlRowQuery(prompt).replace(/\s+/g, '').length >= 2) {
-            const candidates = [];
-            const hasTypeFilter = Boolean(norm.searchIntent?.length);
+            // 结构性修复：分两遍收集，避免「未命中兜底分」反超「弱命中真实分」的倒挂 bug。
+            // 第一遍收集 realHits（scoreUrlRow>0）和 fallbackChunks（分组语义命中兜底）；
+            // 第二遍以 realHits 的最低分为基准，动态计算兜底分（min - MARGIN），保证：
+            //   任意 fallback score < 任意 realHit score
+            // 这样无论 query 怎么变化，命中的真分永远优先于未命中的兜底分。
+            const realHits = [];
+            const fallbackChunks = [];
+            const hasTypeFilter = Boolean((norm.types ?? []).length);
             // 预收集 urls 行的分组结构：按 source 读整个 md 源文件，解析 `##` 分组与每行归属。
             // 分组粗筛对所有 urls 资源生效（产品无关），不针对 webhook.md 打补丁。
             const urlChunks = pool.filter((c) => isUrlMappingSource(c.source) && c.title.trim());
@@ -359,11 +371,12 @@ export function runExactLookup(prompt, pool, norm) {
             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))
+                    ? (norm.types ?? []).some((t) => chunk.types.includes(t))
                     : true;
                 // 分组粗筛：query 是否命中该 chunk 所在的分组。
                 // 命中分组 → 正常；未命中分组 → 降权（不排除，避免 query 与分组名匹配不准时误杀）。
@@ -377,27 +390,40 @@ export function runExactLookup(prompt, pool, norm) {
                 // 跟 section 标题「群组系统回调」共享字符少（仅「群」），sectionMatch 失败，
                 // 但 row title 本身完美匹配 user 意图，强行降权会让单聊 row 顶上。
                 const highConfidence = scoreResult.score >= 700;
-                // 分组语义命中基础分：scoreUrlRow 可能因「同义词/长句」对精确行打 0 分
-                // （如「群消息发送前回调」vs「群内发言之前回调」），但分组已语义命中，
-                // 给予基础分进入候选，避免该领域行被 score<=0 排除。
+                // scoreUrlRow<=0 且分组语义命中 → 归入 fallbackChunks（第二遍统一定分）
                 // 区别于旧的「所有 types 匹配行给 500」——只在分组命中时才给，避免无关行涌入。
                 if (scoreResult.score <= 0) {
                     if (sectionMatch && typeMatch) {
-                        candidates.push({ chunk, score: SECTION_MATCH_BASE_SCORE, typeMatch, sectionMatch });
+                        fallbackChunks.push({ chunk, 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 });
+                realHits.push({ chunk, score: finalScore, typeMatch, sectionMatch });
             }
-            candidates.sort((a, b) => b.score - a.score);
+            // 第二遍：以最低真分为基准动态计算兜底分，保证兜底 < 所有真命中
+            const minRealScore = realHits.length > 0
+                ? Math.min(...realHits.map((h) => h.score))
+                : FALLBACK_DEFAULT_BASELINE;
+            const fallbackScore = Math.max(FALLBACK_MIN_SCORE, minRealScore - FALLBACK_SAFETY_MARGIN);
+            const candidates = [
+                ...realHits,
+                ...fallbackChunks.map((f) => ({ ...f, score: fallbackScore })),
+            ];
+            candidates.sort((a, b) => {
+                if (b.score !== a.score)
+                    return b.score - a.score;
+                return a.chunk.id.localeCompare(b.chunk.id);
+            });
             // types 匹配的行加分（更优先）；不匹配的行轻度降权但仍可兜底召回。
             // 避免上游 types 推断不准确时误杀正确文档（如「多端登录配置」被推断为 feature 而非 product）。
+            // 门槛从 >=500 降至 >=400：配套动态兜底逻辑——真实弱命中（如 scoreUrlRow=400 × 0.7 = 280
+            // → 280×1.2=336 仍会被 >=500 淘汰），需要将 filter 门槛与新的兜底基线保持在同一整数域。
             const typeScored = candidates
                 .map((c) => (c.typeMatch ? { ...c, score: c.score * 1.2 } : { ...c, score: c.score * 0.6 }))
-                .filter(({ score }) => score >= 500);
+                .filter(({ score }) => score >= 400);
             // 同分 row（典型：query「群消息撤回回调」时「撤回群消息」跟「单聊消息撤回」都 scoreUrlRow=660），
             // 按「query 字符集被 row title 覆盖比例」再排，覆盖更高的 row 排前。
             // 修 E7 boost idx=0 多 40 分的副作用：让字符集更精准的 row 拿 idx=0 → 300 分而不是 260 分。
@@ -417,7 +443,10 @@ export function runExactLookup(prompt, pool, norm) {
                 // 优先按 typeScored score 降序；同分时按字符集覆盖率降序
                 if (b.score !== a.score)
                     return b.score - a.score;
-                return charCoverage(b.chunk.title) - charCoverage(a.chunk.title);
+                const coverageDiff = charCoverage(b.chunk.title) - charCoverage(a.chunk.title);
+                if (coverageDiff !== 0)
+                    return coverageDiff;
+                return a.chunk.id.localeCompare(b.chunk.id);
             })
                 .slice(0, 12);
             strongCandidates.forEach(({ chunk, score }, idx) => {
@@ -433,7 +462,7 @@ export function runExactLookup(prompt, pool, norm) {
         }
     }
     // E9: chat faq——types=faq 时优先 knowledge 语料，避免 integration 文档内 FAQ 章节抢首位
-    if (norm.searchIntent?.includes('faq') && norm.product?.includes('chat')) {
+    if ((norm.types ?? []).includes('faq') && norm.product?.includes('chat')) {
         const authPrompt = /auth|login|signature|usersig|鉴权|登录/i.test(prompt);
         for (const chunk of pool) {
             if (chunk.source.startsWith('knowledge/chat/')) {
@@ -487,6 +516,106 @@ export function runExactLookup(prompt, pool, norm) {
                     }
                 }
             }
+            // E10.5: room best-practice 召回补偿
+            // 背景：E10 只对 `scope === coreScope` 的 chunk 广谱 +40，
+            // 而 `knowledge/roomkit/best-practice/` 下的跨平台 FAQ（scope=platform_common）
+            // 一分未拿，同 query 下会被同一份 core-sdk 文件的多 chunk +40 累加压掉。
+            // 三层加分（可叠加）：
+            //   1) 广谱 +80：所有 room best-practice chunk 统一 +80，跟 core-sdk 广谱 +40 拉开档次；
+            //   2) 平台匹配 +40：chunk.framework 与当前 platform 有交集（含 web/common 兼容项）；
+            //   3) §8 同义问法命中 +200：读源文件解析 §8「同义问法覆盖」条目，query 命中任一问法 → +200。
+            // 参考 callkit E13A/E13B 的 +260~+300 精准 boost，room 这里用略低的 +200 尊重现有排序。
+            const bpChunks = pool.filter((c) => c.product === 'room' && c.source.includes('/best-practice/'));
+            // Source → §8 问法条目缓存（同一 source 下多 chunk 共用文件级 §8）
+            const bpSynonymsBySource = new Map();
+            const extractSynonyms = (source) => {
+                if (bpSynonymsBySource.has(source))
+                    return bpSynonymsBySource.get(source);
+                let full = '';
+                try {
+                    full = getSourceFileContent(source);
+                }
+                catch {
+                    full = '';
+                }
+                const lines = full.split('\n');
+                const list = [];
+                let inSection = false;
+                for (const line of lines) {
+                    // §8 允许 "## 8. xxx" 或 "## 同义问法..." 两种标题格式
+                    if (/^##\s+(8\.\s*)?同义问法/.test(line)) {
+                        inSection = true;
+                        continue;
+                    }
+                    if (inSection && /^##\s+/.test(line))
+                        break;
+                    if (inSection) {
+                        const item = line.match(/^-\s+(.+?)[?？]?$/);
+                        if (item)
+                            list.push(item[1].trim());
+                    }
+                }
+                bpSynonymsBySource.set(source, list);
+                return list;
+            };
+            // 平台兼容集：query platform 命中 chunk.framework 里的这些标签均视为匹配
+            // vue → [vue, web, common, react]（跨平台 web 类问法通常写作 react/vue/web）
+            // react → [react, web, common, vue]
+            // android/ios/flutter → [self, common]
+            const platformCompat = {
+                vue: ['vue', 'web', 'common', 'react'],
+                react: ['react', 'web', 'common', 'vue'],
+                android: ['android', 'common'],
+                ios: ['ios', 'common'],
+                flutter: ['flutter', 'common'],
+            };
+            const compatSet = new Set(platformCompat[platform] ?? [platform, 'common']);
+            // query 归一化：小写 + 去空格，用于宽松包含匹配（问法通常是短句）
+            const promptForMatch = prompt.toLowerCase().replace(/\s+/g, '');
+            for (const chunk of bpChunks) {
+                // 1) 广谱 +80
+                addBoost(chunk, 80, 'E10.5:room-bp');
+                // 2) 平台匹配 +40
+                const frameworkMatch = (chunk.framework ?? []).some((fw) => compatSet.has(fw));
+                if (frameworkMatch) {
+                    addBoost(chunk, 40, `E10.5:room-bp-platform:${platform}`);
+                }
+                // 3) §8 同义问法命中 +200（同 source 只算一次，避免同文件多 chunk 重复加）
+                const synonyms = extractSynonyms(chunk.source);
+                if (synonyms.length === 0)
+                    continue;
+                const hit = synonyms.some((q) => {
+                    const normQ = q.toLowerCase().replace(/\s+/g, '');
+                    if (normQ.length < 4)
+                        return false;
+                    // 双向宽松匹配：query 包含问法（短问法命中长 query），或问法包含 query（罕见，防守）
+                    return promptForMatch.includes(normQ) || normQ.includes(promptForMatch);
+                });
+                if (hit) {
+                    addBoost(chunk, 200, `E10.5:room-bp-synonym`);
+                }
+                else {
+                    // 退化匹配：若整句问法未匹配，用问法内 4+ 长中文/英文子串扫描
+                    // 覆盖 "整屏共享怎么避免无限镜像" vs "分享屏幕出现无限套娃" 这类只共享部分词汇的情况
+                    const keywords = new Set();
+                    for (const q of synonyms) {
+                        const zhTokens = q.match(/[\u4e00-\u9fff]{2,}/g) ?? [];
+                        for (const t of zhTokens)
+                            if (t.length >= 2)
+                                keywords.add(t);
+                    }
+                    let matchedKeywordCount = 0;
+                    for (const kw of keywords) {
+                        if (promptForMatch.includes(kw.toLowerCase()))
+                            matchedKeywordCount += 1;
+                        if (matchedKeywordCount >= 2)
+                            break;
+                    }
+                    if (matchedKeywordCount >= 2) {
+                        addBoost(chunk, 120, `E10.5:room-bp-keywords`);
+                    }
+                }
+            }
         }
     }
     // E12: CallKit Vue 混合类型问题消歧（状态机 STATUS 与 Core Store 类型分层召回）

package/knowledge/search/filter-pool.js

@@ -112,38 +112,74 @@ function promptMatchesRetrievableScope(prompt, scope) {
     const normalizedPrompt = normalizeScopeToken(prompt);
     return scope.some((token) => normalizedPrompt.includes(normalizeScopeToken(token)));
 }
-export function filterPool(chunks, norm) {
-    return chunks.filter((chunk) => {
-        if (norm.product && !norm.product.includes(chunk.product) && chunk.product !== '*') {
-            return false;
-        }
-        // A1: 通配语料(share 等)必须命中 retrievable_scope 才能进入检索池
-        if (chunk.product === '*' && !promptMatchesRetrievableScope(norm.prompt, chunk.retrievable_scope)) {
+/**
+ * 硬过滤层（Hard filter）：语义无关的强约束，任何检索通道都必须遵守。
+ *
+ * 语义：
+ *   - product：产品维度物理隔离（不同产品的语料本就不应互相召回）。
+ *   - A1 retrievable_scope：通配语料（share 等）必须命中作用域，防止 share 语义误召到具体产品下。
+ *
+ * 使用者：
+ *   - BM25 通道：入池前调用
+ *   - 向量通道：召回后二次校验，作为索引层 product 分片的兜底
+ */
+export function filterPoolHard(chunks, norm) {
+    return chunks.filter((chunk) => isHardAllowed(chunk, norm));
+}
+export function isHardAllowed(chunk, norm) {
+    if (norm.product && !norm.product.includes(chunk.product) && chunk.product !== '*') {
+        return false;
+    }
+    // A1: 通配语料(share 等)必须命中 retrievable_scope 才能进入检索池
+    if (chunk.product === '*' && !promptMatchesRetrievableScope(norm.prompt, chunk.retrievable_scope)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * 软过滤层（Soft filter）：语义相关的偏好约束，向量语义召回不应被此层直接砍掉。
+ *
+ * 语义：
+ *   - framework：平台维度偏好（向量语义可跨平台复用，应转为软降权）
+ *   - scenario：场景维度偏好（live/voice）
+ *   - types：文档类型偏好（Agent 可能传错，向量语义能自愈到正确类型）
+ *
+ * 使用者：
+ *   - BM25 通道：与 Hard 合用（保持现网行为）
+ *   - 向量通道：不使用；由 applyRankMultipliers 在融合后做软降权
+ */
+export function isSoftAllowed(chunk, norm) {
+    if (norm.frameworks?.length) {
+        const isWildcardChunk = chunk.framework.includes('*');
+        // 收紧：framework=['*'] 仅在该 chunk 明确是跨平台 type（product/server_api/webhook）时放行；
+        // 否则要求 chunk.framework 与请求 framework 有交集。
+        const wildcardAllowed = isWildcardChunk && chunkIsCrossPlatform(chunk.types);
+        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.frameworks?.length) {
-            const isWildcardChunk = chunk.framework.includes('*');
-            // 收紧：framework=['*'] 仅在该 chunk 明确是跨平台 type（product/server_api/webhook）时放行；
-            // 否则要求 chunk.framework 与请求 framework 有交集。
-            const wildcardAllowed = isWildcardChunk && chunkIsCrossPlatform(chunk.types);
-            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) {
+    }
+    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))) {
+        if (!chunk.source.includes('/best-practice/'))
             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))) {
-            if (!chunk.source.includes('/best-practice/'))
-                return false;
-        }
-        return true;
-    });
+    }
+    return true;
+}
+/**
+ * 完整过滤（Hard + Soft）：BM25 主通道使用，保持现网行为不变。
+ *
+ * 向量通道**不应**使用此函数——它会把 framework/types/scenario 硬砍掉，
+ * 抵消向量语义的跨平台/类型自愈能力。向量通道请使用 filterPoolHard。
+ */
+export function filterPool(chunks, norm) {
+    return chunks.filter((chunk) => isHardAllowed(chunk, norm) && isSoftAllowed(chunk, norm));
 }

package/knowledge/search/requires-framework.js

@@ -8,7 +8,7 @@ const PLATFORM_TYPES = new Set([
     'integration',
 ]);
 const CROSS_PLATFORM_TYPES = new Set(['server_api', 'webhook', 'product']);
-const CROSS_PLATFORM_PROMPT = /计费|套餐|价格|UserSig\s*原理|签发流程|控制台|服务端\s*REST|云\s*API|Webhook|回调/i;
+const CROSS_PLATFORM_PROMPT = /计费|套餐|价格|UserSig\s*原理|签发流程|控制台|服务端\s*REST|云\s*API|Webhook|回调|callback|server\s*callback/i;
 const PLATFORM_PROMPT = /API|组件|怎么用|怎么开|怎么设置|怎么配置|虚拟背景|屏幕分享|enterRoom|SDK|插件|集成步骤|客户端|Feature|主题定制|连麦|上麦/i;
 /**
  * push 必须问平台的强信号：仅当 prompt 明确提到具体「平台」（android/ios/flutter/...）时才拦询问。

package/knowledge/search/search-core.js

@@ -36,7 +36,17 @@ export function postProcess(ranked, chunksById, limit, opts) {
             .filter((chunk) => chunk.source === opts.preferredSource)
             .sort((a, b) => a.char_start - b.char_start);
         if (sections.length > 0) {
-            return sections.map((section, idx) => buildFragment(section, scoreMap.get(section.id) ?? 0, idx + 1));
+            const fullDocumentMaxChars = Math.max(1000, opts.fullDocumentMaxChars ?? 7000);
+            const selectedSections = [];
+            let usedChars = 0;
+            for (const section of sections) {
+                const sectionChars = section.content.length;
+                if (selectedSections.length > 0 && usedChars + sectionChars > fullDocumentMaxChars)
+                    break;
+                selectedSections.push(section);
+                usedChars += sectionChars;
+            }
+            return selectedSections.map((section, idx) => buildFragment(section, scoreMap.get(section.id) ?? 0, idx + 1));
         }
     }
     const sourceCount = {};
@@ -88,22 +98,18 @@ export function postProcess(ranked, chunksById, limit, opts) {
         }
         else if (!isPinnedUrlRow) {
             const topScore = fragments[0].score;
-            // 方案A：分数断崖截断。
-            // 当已有 E7 精确命中行（pinned url-row）时，后续非 pinned 行若跌破 Top1 的 20%，
-            // 视为「Top1 已精确命中、后续多为泛匹配噪声」，提前截断，避免凑满 limit 返回冗余。
-            // 无 E7 命中时不触发（此时答案依赖 best-practice/本地文档，需完整保留）。
+            // 方案A：分数断崖截断（拆分为两个独立信号）：
+            //   1) 通用分数衰减截断（不依赖 pin/exact-url 状态）
+            //   2) 精确 URL 命中断崖：由 caller 通过 strictCutoffOnExactUrlHit 显式启用，
+            //      避免"fragments 里恰好含 pinned row"这类间接信号驱动策略。
             if (topScore > 0) {
-                const pinnedChunkIds = opts?.pinnedUrlRowChunkIds;
-                const hasPinnedRow = pinnedChunkIds
-                    ? fragments.some((f) => pinnedChunkIds.has(f.chunk_id))
-                    : false;
                 // 原有：分数衰减到 top 的 5% 以下时停止
                 if (item.score < topScore * 0.05)
                     break;
-                // 新增：已有 E7 精确命中 + 后续跌破 35% → 断崖截断
+                // 新增：精确 URL 命中场景 → 后续跌破 35% → 断崖截断
                 // 阈值取 35%（非 20%）：best-practice 泛匹配分数常在 Top1 的 20%~35% 区间，
-                // 用 35% 才能拦住「Top1 精确命中后仍返回一堆无关 best-practice」的冗余。
-                if (hasPinnedRow && item.score < topScore * 0.35)
+                // 用 35% 才能拦住"Top1 精确命中后仍返回一堆无关 best-practice"的冗余。
+                if (opts?.strictCutoffOnExactUrlHit && item.score < topScore * 0.35)
                     break;
             }
         }

package/knowledge/search/search-knowledge.js

@@ -7,7 +7,7 @@ import { classifyRetrievalMode } from './intent-router.js';
 import { rankSubsetWithIndex } from '../bm25.js';
 import { getProductsBM25Index } from '../bm25-cache.js';
 import { hasExplicitFrameworkMatch } from './framework-fallback.js';
-import { assessConfidence, assessNarrativeCompleteness, buildNarrativeDocument, hasNativeClientFramework, hasNativeTrtcApiSignal, hasProductScopeIntent, inferQueryApiTokens, pickNarrativeSource, } from './search-core.js';
+import { assessConfidence, assessNarrativeCompleteness, buildDiscoveryCatalog, buildNarrativeDocument, hasNativeClientFramework, hasNativeTrtcApiSignal, hasProductScopeIntent, inferQueryApiTokens, pickNarrativeSource, } from './search-core.js';
 import { scoreUrlRow } from './url-row-scorer.js';
 import { buildAnswerContract, buildAgentMessage } from './search-message.js';
 import { runSearchPass } from './search-pass.js';
@@ -174,7 +174,7 @@ function computePrimaryCompleteness(allChunks, fragments, preferredSource) {
         primary_completeness: fileToken > 0 ? Number((hitToken / fileToken).toFixed(2)) : 0,
     };
 }
-export function searchKnowledge(params) {
+export async function searchKnowledge(params) {
     const norm = normalizeParams(params);
     const retrievalMode = classifyRetrievalMode(norm.prompt);
     if (requiresFramework(norm)) {
@@ -196,36 +196,21 @@ export function searchKnowledge(params) {
     const manifest = loadManifest();
     const allChunks = manifest.chunks;
     const queryApiTokens = inferQueryApiTokens(norm.prompt);
-    let pass = runSearchPass({
+    let pass = await runSearchPass({
         allChunks,
         passNorm: norm,
         retrievalMode,
         queryApiTokens,
     });
-    // best-practice 懒补充：仅在主 pass 无本地片段（仅 URL 映射行或完全为空）时触发。
-    // 典型场景：Agent 传 types=['sdk']，filterPool 把 best-practice（type=faq）硬过滤掉，
-    // 只剩 URL 映射行（有 E7 boost 但内容只是一个 URL 链接）。
-    // 不侵入 runSearchPass 层，避免每次调用都执行重复检索。
-    // 修复 B1 副作用：之前 `types: undefined` 会同时把 chat/preset/{flutter,android,...}/integration.md
-    // （types=['integration']）也放进 pool，integration 文档多 section 命中 generic 词会把 URL row 顶掉。
-    // 改为 `types: ['faq']` 后：
-    //   - best-practice（types=['faq']）走 filterPool 的 bp-bypass 保留
-    //   - chat/preset/.../integration.md（types=['integration']）被硬过滤
-    //   - URL row（types 与原请求一致）继续保留
-    // 合并策略：append BP fragments 到原 pass（不去重 URL row），保留 URL row 在 top。
+    // best-practice 懒补充（收敛版）：仅在主 pass 完全无结果时触发。
+    //
+    // 设计意图：
+    // - BP 从“主通道召回增强”退到“兜底校准器”
+    // - 对“仅 URL 行”的场景不再补 BP，避免策略叠加导致的 BP 过召回
+    // - 保留 hard-fail 场景的可恢复性（空结果时补一次 faq）
     const passRetryReasons = [];
-    const hasLocalContent = pass.fragments.some((f) => !f.source.includes('/urls/'));
-    // 当主 pass 命中一个明确的 URL row（scoreUrlRow ≥ 300 强信号）时，**跳过 B1 补充**，
-    // 避免 BP 兜底把无关 BP 文档（message-unread-count、avchatroom-message-loss-diagnosis 等）塞满 fragments。
-    // 典型反例：query「im 内网代理」types=['product']，pass 命中「内网代理实现方案」(scoreUrlRow=460)，
-    // 旧 B1 会触发 → 拉 8 个无关 BP → fragments 膨胀到 9 个。
-    // 进一步保护：当 top1 finalScore < 20（零命中场景，如「im 怎么发火箭」finalScore=16.8），
-    // 也不触发 B1——无意义 query 不该被 BP 兜底撑满。
-    const top1UrlScore = !hasLocalContent && pass.fragments[0]?.title
-        ? scoreUrlRow(norm.prompt, pass.fragments[0].title).score
-        : 0;
-    const top1FinalScore = pass.fragments[0]?.score ?? 0;
-    if (!hasLocalContent && top1UrlScore < 300 && top1FinalScore >= 20 && norm.product?.length && !norm.types?.includes('faq')) {
+    const noFragments = pass.fragments.length === 0;
+    if (noFragments && norm.product?.length && !norm.types?.includes('faq')) {
         const primaryProduct = norm.product[0];
         const bpCandidates = allChunks.filter((chunk) => {
             if (!/\/best-practice\//i.test(chunk.source))
@@ -244,7 +229,7 @@ export function searchKnowledge(params) {
             const bpIndex = getProductsBM25Index(allChunks, [norm.product[0]]);
             const bpRanked = rankSubsetWithIndex(norm.prompt, bpCandidates.map((c) => c.id), bpIndex, {});
             if ((bpRanked[0]?.score ?? 0) >= 6) {
-                const bpPass = runSearchPass({
+                const bpPass = await runSearchPass({
                     allChunks,
                     passNorm: { ...norm, types: ['faq'] },
                     retrievalMode,
@@ -276,7 +261,7 @@ export function searchKnowledge(params) {
         ? Number((pass.missingApiTokens.length / queryApiTokens.length).toFixed(2))
         : 0;
     if (queryApiTokens.length > 0 && (pass.apiNameCoverage === 0 || missingRatio >= 0.3)) {
-        const retryPass = runSearchPass({
+        const retryPass = await runSearchPass({
             allChunks,
             passNorm: { ...norm, types: undefined },
             retrievalMode,
@@ -296,7 +281,7 @@ export function searchKnowledge(params) {
     // B3: 混合“集成 + 产品开通/计费/控制台”问法时，补充 product type，避免仅搜 integration/feature。
     if (norm.types?.length && !norm.types.includes('product') && hasProductScopeIntent(norm.prompt)) {
         const widenedTypes = [...new Set([...norm.types, 'product'])];
-        const retryPass = runSearchPass({
+        const retryPass = await runSearchPass({
             allChunks,
             passNorm: { ...norm, types: widenedTypes },
             retrievalMode,
@@ -320,7 +305,7 @@ export function searchKnowledge(params) {
         && pass.apiNameCoverage < 0.5;
     if (shouldRetryNativeProduct) {
         const expandedProducts = [...new Set([...(norm.product ?? []), 'native_trtc_sdk'])];
-        const retryPass = runSearchPass({
+        const retryPass = await runSearchPass({
             allChunks,
             passNorm: { ...norm, product: expandedProducts, types: undefined },
             retrievalMode,
@@ -356,7 +341,7 @@ export function searchKnowledge(params) {
             types: undefined,
             limit: Math.max(norm.limit ?? 8, 12),
         };
-        const retryPass = runSearchPass({
+        const retryPass = await runSearchPass({
             allChunks,
             passNorm: narrativeRetryNorm,
             retrievalMode,
@@ -379,7 +364,7 @@ export function searchKnowledge(params) {
     if (shouldDeepCoverageCheck) {
         coverageReport = buildCoverageReport(allChunks, pass.fragments, pass.preferredSource);
         if (coverageReport.retry_suggested) {
-            const coverageRetryPass = runSearchPass({
+            const coverageRetryPass = await runSearchPass({
                 allChunks,
                 passNorm: { ...norm, types: undefined, limit: Math.max(norm.limit ?? 8, 12) },
                 retrievalMode,
@@ -441,6 +426,9 @@ export function searchKnowledge(params) {
     const documents = retrievalMode === 'narrative'
         ? (narrativeState.document ? [narrativeState.document] : [])
         : [];
+    const catalog = retrievalMode === 'discovery'
+        ? buildDiscoveryCatalog(pass.rankedWithMultipliers, pass.poolWithContent, Math.max(norm.limit ?? 8, 6))
+        : [];
     let finalStatus = status;
     let finalConfidence = confidence;
     if (retrievalMode === 'narrative' && documents.length > 0) {
@@ -453,7 +441,7 @@ export function searchKnowledge(params) {
             finalConfidence = 'low';
         }
     }
-    if (retrievalMode === 'discovery' && pass.fragments.length > 0) {
+    if (retrievalMode === 'discovery' && catalog.length > 0) {
         finalStatus = 'success';
         finalConfidence = finalConfidence === 'none' ? 'medium' : finalConfidence;
     }
@@ -486,7 +474,7 @@ export function searchKnowledge(params) {
     const narrativeConverged = retrievalMode !== 'narrative'
         || (documents.length > 0 && narrativeState.quality.isComplete);
     const convergenceReached = (retrievalMode === 'narrative' && narrativeConverged)
-        || (retrievalMode === 'discovery' && pass.fragments.length > 0)
+        || (retrievalMode === 'discovery' && catalog.length > 0)
         || (finalStatus === 'success'
             && (finalConfidence === 'high' || finalConfidence === 'medium')
             && (!hasApiQueryTokens || pass.apiNameCoverage >= 0.5)
@@ -529,6 +517,7 @@ export function searchKnowledge(params) {
         query: params,
         retrieval_mode: retrievalMode,
         documents,
+        catalog,
         meta: {
             // 参考文档（AI 输出「参考文档」小节依据）：
             ...(pass.references.length ? { references: pass.references } : {}),
@@ -549,6 +538,7 @@ export function searchKnowledge(params) {
                     },
                 }
                 : {}),
+            vector_retrieval: pass.vectorDiagnostics,
         },
         fragments: pass.fragments,
     };