@tencentcloud/sdk-mcp 1.6.8 → 1.7.0

package/knowledge/search/search-knowledge.js

@@ -1,13 +1,15 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { attachPoolContent, getSourceFileContent } from '../content-loader.js';
-import { buildReferences, resolveFragmentDocUrls } from '../doc-url-resolver.js';
-import { rankSubsetWithIndex } from '../bm25.js';
-import { getProductsBM25Index } from '../bm25-cache.js';
 import { filterPool, normalizeParams } from './filter-pool.js';
-import { runExactLookup } from './exact-lookup.js';
 import { requiresFramework } from './requires-framework.js';
+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, buildDiscoveryCatalog, buildNarrativeDocument, hasNativeClientFramework, hasNativeTrtcApiSignal, hasProductScopeIntent, inferQueryApiTokens, pickNarrativeSource, } from './search-core.js';
+import { buildAnswerContract, buildAgentMessage } from './search-message.js';
+import { runSearchPass } from './search-pass.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 let cachedManifest = null;
 function resolveResourcePath(...segments) {
@@ -18,313 +20,80 @@ function loadManifest() {
         return cachedManifest;
     const manifestPath = resolveResourcePath('index', 'manifest.json');
     if (!fs.existsSync(manifestPath)) {
-        throw new Error('manifest.json not found. Run `npm run build` in zh/ first.');
+        throw new Error('manifest.json not found. Run `npm run build` first.');
     }
     cachedManifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
     return cachedManifest;
 }
-function postProcess(ranked, chunksById, limit, opts) {
-    const sourceCount = {};
-    const urlMappingSourceCount = {};
-    /** 已入选的 push config/android/{vendor} 文件，用于抑制其他厂商噪声 */
-    let selectedVendorFile = null;
-    const fragments = [];
-    for (const item of ranked) {
-        const chunk = chunksById.get(item.id);
-        if (!chunk)
-            continue;
-        const isUrlMapping = Boolean(isUrlMappingSource(chunk.source));
-        const isPinnedUrlRow = isUrlMapping && (opts?.pinnedUrlRowChunkIds?.has(chunk.id) ?? false);
-        if (isUrlMapping) {
-            const urlCount = urlMappingSourceCount[chunk.source] ?? 0;
-            if (!isPinnedUrlRow && urlCount >= 1)
-                continue;
-            urlMappingSourceCount[chunk.source] = urlCount + 1;
-        }
-        else {
-            const count = sourceCount[chunk.source] ?? 0;
-            if (count >= 3)
-                continue;
-            sourceCount[chunk.source] = count + 1;
-        }
-        // 当用户明确问某厂商时，抑制同目录下其他厂商文档的噪声
-        // 规则：如果已有 config/android/{vendor}.md 入选，
-        // 后续其他 config/android/{other}.md 跳过
-        const isVendorDoc = chunk.source.match(/^knowledge\/push\/config\/android\/[a-z]+\.md$/);
-        if (isVendorDoc) {
-            if (!selectedVendorFile) {
-                selectedVendorFile = chunk.source;
-            }
-            else if (chunk.source !== selectedVendorFile) {
-                continue; // 跳过其他厂商
-            }
-        }
-        // 当已明确命中了厂商配置页后，后续的 push 通用文件（integration/、其他 config/）不再有意义
-        // 只保留同厂商文件（已由 vendor dedup 处理）和 overview 综述，其他 push 通用文档视为噪声
-        if (selectedVendorFile && chunk.source.startsWith('knowledge/push/') && !chunk.source.includes('/overview/')) {
-            if (chunk.source !== selectedVendorFile)
-                continue;
-        }
-        const firstPush = fragments.length === 0;
-        if (firstPush) {
-            // 首条不设分数截止，至少保证 1 条返回
-        }
-        else if (!isPinnedUrlRow) {
-            // 分数衰减到 top 的 5% 以下时停止，不硬填到 limit
-            // chat/urls 的行级精确命中（E7）不受该规则截断，保证多子主题可并行返回
-            const topScore = fragments[0].score;
-            if (topScore > 0 && item.score < topScore * 0.05)
-                break;
-        }
-        const contentWithHint = chunk.contains_code
-            ? `【代码示例，须与目标端一致】\n${chunk.content}`
-            : chunk.content;
-        fragments.push({
-            rank: fragments.length + 1,
-            score: item.score,
-            title: chunk.title,
-            content: contentWithHint,
-            source: chunk.source,
-            doc_urls: resolveFragmentDocUrls(chunk.source, chunk.content, getSourceFileContent(chunk.source)),
-            product: chunk.product,
-            framework: chunk.framework,
-            types: chunk.types,
-            variant: chunk.variant,
-            scope: chunk.scope,
-            doc_kind: chunk.doc_kind,
-            capability_status: chunk.capability_status,
-            api_names: chunk.api_names,
-            contains_code: chunk.contains_code,
-            citation: `[来源: ${chunk.id}]`,
-            chunk_id: chunk.id,
-        });
-        if (fragments.length >= limit)
-            break;
-    }
-    return fragments;
-}
-function isUrlMappingSource(source) {
-    const normalized = source.replace(/\\/g, '/');
-    const match = normalized.match(/knowledge\/chat\/urls\/(.+\.md)$/);
-    if (!match)
-        return null;
-    return match[1].replace(/\.md$/, '').replace(/\/index$/, '');
-}
-function partitionFragments(fragments) {
-    const urlMapping = [];
-    const localDoc = [];
-    for (const fragment of fragments) {
-        if (isUrlMappingSource(fragment.source)) {
-            urlMapping.push(fragment);
-        }
-        else {
-            localDoc.push(fragment);
-        }
-    }
-    const urlMappingKinds = [...new Set(urlMapping.map((f) => isUrlMappingSource(f.source)).filter(Boolean))];
-    return { urlMapping, localDoc, urlMappingKinds };
-}
-function hasBestPracticeFragment(fragments) {
-    return fragments.some((f) => /\/best-practice\//i.test(f.source));
-}
-function inferQueryApiTokens(prompt) {
-    const tokens = new Set();
-    // 仅保留 API 形态 token，剔除产品/平台品牌词，避免把“TRTC Conference Web ...”误判为 API 缺口。
-    const upperNoise = new Set([
-        'SDK', 'API', 'HTTP', 'HTTPS', 'JSON', 'CALL', 'NAME', 'STATUS',
-        'TRTC', 'TENCENT', 'WEB', 'VUE', 'REACT', 'ROOMKIT', 'LIVEKIT', 'CALLKIT',
-    ]);
-    const platformNoise = new Set([
-        'ios', 'android', 'flutter', 'web', 'react', 'vue', 'miniprogram',
-        'harmonyos', 'react-native', 'unity', 'unreal', 'unreal-engine', 'donut', 'uni-app',
-        'pc', 'h5',
-    ]);
-    for (const match of prompt.matchAll(/\b([a-z]+[A-Z][A-Za-z0-9_]*)\b/g)) {
-        tokens.add(match[1]);
-    }
-    for (const match of prompt.matchAll(/\b([A-Z][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*)\b/g)) {
-        tokens.add(match[1]);
-    }
-    for (const match of prompt.matchAll(/\b(use[A-Z]\w*)\b/g)) {
-        tokens.add(match[1]);
-    }
-    for (const match of prompt.matchAll(/\b(I[A-Z][A-Za-z0-9_]*)\b/g)) {
-        tokens.add(match[1]);
-    }
-    for (const match of prompt.matchAll(/\b([A-Z][A-Za-z0-9_]*\.[A-Z_][A-Z0-9_]*)\b/g)) {
-        tokens.add(match[1]);
-    }
-    for (const match of prompt.matchAll(/\b([A-Z_]{3,})\b/g)) {
-        const token = match[1];
-        if (!upperNoise.has(token))
-            tokens.add(token);
-    }
-    return [...tokens].filter((token) => !platformNoise.has(token.toLowerCase()));
-}
-function tokenInChunk(token, chunk) {
-    if (chunk.api_names?.some((name) => name.toLowerCase() === token.toLowerCase()))
-        return true;
-    if (chunk.symbols?.some((name) => name.toLowerCase() === token.toLowerCase()))
-        return true;
-    const low = token.toLowerCase();
-    return chunk.title.toLowerCase().includes(low) || chunk.source.toLowerCase().includes(low);
-}
-function computeApiNameCoverage(tokens, candidates) {
-    if (!tokens.length)
-        return 1;
-    const hit = tokens.filter((token) => candidates.some((chunk) => tokenInChunk(token, chunk))).length;
-    return Number((hit / tokens.length).toFixed(2));
-}
-function computeMissingApiTokens(tokens, candidates) {
-    if (!tokens.length)
-        return [];
-    return tokens.filter((token) => !candidates.some((chunk) => tokenInChunk(token, chunk)));
-}
-function hasProductScopeIntent(prompt) {
-    return /控制台|开通|开通服务|计费|套餐|价格|pricing|billing|plan|console|activate|activation|service/i.test(prompt);
-}
-function hasNativeTrtcApiSignal(prompt, queryApiTokens) {
-    if (/\bTRTCCloud\b|\bTRTCRenderParams\b|\bTXDeviceManager\b|setLocalRenderParams|startLocalPreview|stopLocalPreview/i.test(prompt)) {
-        return true;
+function buildCoverageReport(allChunks, fragments, preferredSource) {
+    if (!fragments.length) {
+        return {
+            files: [],
+            allow_pending_confirm: true,
+            retry_suggested: false,
+        };
     }
-    return queryApiTokens.some((token) => /^(TRTC|TX)[A-Za-z0-9_]+$/.test(token)
-        || /^(set|get|start|stop|enable|disable)[A-Z][A-Za-z0-9_]+$/.test(token));
-}
-function hasNativeClientFramework(frameworks) {
-    if (!frameworks?.length)
-        return false;
-    return frameworks.some((fw) => ['android', 'ios', 'flutter', 'c++'].includes(fw));
-}
-function applyRankMultipliers(ranked, chunksById, opts) {
-    const adjusted = ranked.map((item) => {
-        const chunk = chunksById.get(item.id);
-        if (!chunk)
-            return item;
-        let multiplier = 1;
-        // A2: 传了 product 时，命中 scope 的通配语料允许召回但降权
-        if (opts.product?.length && chunk.product === '*') {
-            multiplier *= 0.2;
-        }
-        // F2: framework 软降权（保留硬过滤，处理 fallback/边界残留）
-        if (opts.framework && opts.frameworks?.length && !chunk.framework.includes('*')) {
-            const explicitMatch = opts.frameworks.some((fw) => chunk.framework.includes(fw));
-            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/'));
-            if (!explicitMatch && !callCoreWebFallback && !liveWebVueFallback && !roomWebVueFallback) {
-                multiplier *= 0.2;
-            }
-        }
-        return { ...item, score: item.score * multiplier };
+    const hitChunkIds = new Set(fragments.map((f) => f.chunk_id));
+    const sources = [...new Set(fragments.map((f) => f.source))];
+    const files = sources.map((source) => {
+        const sourceChunks = allChunks.filter((chunk) => chunk.source === source);
+        const fileToken = sourceChunks.reduce((sum, chunk) => sum + Math.max(0, chunk.char_end - chunk.char_start), 0);
+        const hitToken = sourceChunks
+            .filter((chunk) => hitChunkIds.has(chunk.id))
+            .reduce((sum, chunk) => sum + Math.max(0, chunk.char_end - chunk.char_start), 0);
+        const completeness = fileToken > 0 ? Number((hitToken / fileToken).toFixed(2)) : 0;
+        const missingChunkIds = sourceChunks.filter((chunk) => !hitChunkIds.has(chunk.id)).map((chunk) => chunk.id).slice(0, 12);
+        return {
+            source,
+            hit_token: hitToken,
+            file_token: fileToken,
+            completeness,
+            missing_chunk_ids: missingChunkIds,
+        };
     });
-    return adjusted.sort((a, b) => b.score - a.score);
-}
-/**
- * 多因子置信度评估：exact 命中 + 分数梯度 + API 覆盖度。
- */
-function assessConfidence(fragments, exactHits, apiNameCoverage, queryApiTokens) {
-    if (fragments.length === 0) {
-        return { confidence: 'none', status: 'empty' };
-    }
-    const top = fragments[0].score;
-    const second = fragments[1]?.score ?? 0;
-    const ratio = second > 0 ? top / second : Infinity;
-    let confidence;
-    if (exactHits.length > 0 || top >= 50)
-        confidence = 'high';
-    else if (top >= 12 && ratio >= 1.25)
-        confidence = 'medium';
-    else if (top >= 6 && ratio >= 1.12)
-        confidence = 'medium';
-    else
-        confidence = 'low';
-    // D2: API 覆盖过低时，confidence 上限降为 low
-    if (queryApiTokens.length > 0 && apiNameCoverage < 0.3) {
-        confidence = 'low';
-    }
-    const status = confidence === 'low' ? 'low_confidence' : 'success';
-    return { confidence, status };
-}
-function buildAnswerContract(status, confidence, opts) {
-    const uncertaintyRule = status === 'low_confidence' || confidence === 'low'
-        ? '当信息不足时必须显式写“待确认：”，只允许陈述缺口，不允许猜测补全。'
-        : '除“待确认：”段落外，不得出现“可能/大概/应该/推测”等猜测措辞。';
-    const riskRule = opts?.fabricationRisk
-        ? 'fabrication_risk=true 时，若片段未覆盖该细节，必须输出“待确认：知识片段未覆盖此项”。'
-        : '';
-    return [
-        '【输出模板（必须遵守）】',
-        '使用“问题导向”标题组织答案，优先复用用户提问原句：一、<问题1> 二、<问题2> 三、<问题3> …',
-        '每个小节先给直接结论，再补 1-2 句必要说明；避免模板化术语（如“依据/操作”字样）。',
-        '信息缺口统一放在对应小节末尾，使用“待确认：xxx”；若全都确认则可省略“待确认”小节。',
-        '末尾保留“参考文档”小节，仅列文档标题或 URL；正文不展示检索过程、证据链、打分细节。',
-        '用户可见正文禁止出现系统检索话术（如“命中片段/检索结果/置信度/分数/召回/重排”）。',
-        '硬约束：不得引入 fragments 未出现的 API 名、字段值、枚举项、事件名。',
-        uncertaintyRule,
-        riskRule,
-    ].filter(Boolean).join(' ');
+    const primarySource = preferredSource ?? fragments[0]?.source;
+    const primaryCompleteness = primarySource
+        ? files.find((file) => file.source === primarySource)?.completeness ?? 0
+        : 0;
+    return {
+        files,
+        allow_pending_confirm: primaryCompleteness < 0.9,
+        primary_source: primarySource,
+        primary_completeness: primaryCompleteness,
+        retry_suggested: primaryCompleteness < 0.6,
+    };
 }
-function buildAgentMessage(status, fragments, confidence, _references, opts) {
-    const platformRule = '端别硬规则：字段/API 描述前先标注【端别: framework】；禁止“部分版本也称 xxx”这类跨端混写；字段大小写必须与目标端文档一致；多端片段同时命中时主答案仅讲目标端，其他端差异放末尾简述；无片段覆盖的细节禁止补全。';
-    const riskRule = opts?.fabricationRisk ? '当前检索存在幻觉风险（fabrication_risk=true）：禁止补全未命中 API 细节。' : '';
-    const answerContract = buildAnswerContract(status, confidence, opts);
-    const tail = `${platformRule} ${riskRule} ${answerContract} Final answer drafted -> MUST call \`finalize_answer\` before replying. Explicit follow-up feedback -> call \`submit_feedback\`.`;
-    if (status === 'needs_framework') {
-        return '【硬规则】问题依赖具体平台实现，但未指定 frameworks，全平台混检信息密度低且被禁止。MUST 先调用 `present_framework_choice`（传入 product），等用户选定 web/miniprogram/android/ios/flutter/react/vue/uni-app 等后再调用本工具，并 MUST 带上 **product + frameworks**。禁止传空 frameworks 硬搜。';
-    }
-    const { urlMapping, localDoc, urlMappingKinds } = partitionFragments(fragments);
-    const hasUrlMapping = urlMapping.length > 0;
-    const hasLocalDoc = localDoc.length > 0;
-    const hasBestPractice = hasBestPracticeFragment(fragments);
-    const urlKindLabel = urlMappingKinds.join(' / ') || 'urls';
-    if (status === 'success' && fragments.length > 0) {
-        const topFragment = fragments[0];
-        if (topFragment?.capability_status === 'unsupported') {
-            const scopeLabel = topFragment.scope ? `（${topFragment.scope}）` : '';
-            return `当前问题在该平台 / 形态下 **不支持**${scopeLabel}。回答 MUST：① 第一段先明确写“**不支持**”；② 说明这是当前平台 Core 的能力边界，而不是缺少示例代码；③ 仅提供当前平台已支持的替代方案（如对应平台 preset 预制 UI）；若当前知识库未给出明确替代形态，应直接说明暂无可执行替代路径；④ **禁止**输出当前平台 Core 的 API 调用步骤或集成步骤。${tail}`;
-        }
-        if (hasUrlMapping && !hasLocalDoc) {
-            return `当前可用信息主要是文档入口链接（${urlKindLabel}）。请先匹配用户问题对应的目标 URL，抓取官网文档后再合成答案；禁止仅复述映射表或臆造 API/错误码细节。${tail}`;
-        }
-        if (hasUrlMapping && hasLocalDoc) {
-            if (hasBestPractice) {
-                return `优先基于已命中的 best-practice 与本地片段直接作答；URL 映射仅作补充参考，不要再抓官网做二次求证。${tail}`;
-            }
-            return `本地文档片段可直接用于作答；若本地片段未覆盖关键细节，再从 URL 映射中提取目标 URL 抓取官网文档补齐。${tail}`;
-        }
-        return `请仅基于已返回 fragments 合成答案；不要并行 web_search 或额外抓取官网文档。${tail}`;
-    }
-    if (status === 'low_confidence') {
-        if (hasUrlMapping) {
-            if (hasBestPractice) {
-                return `优先基于 best-practice 与本地片段给出可执行结论；未覆盖的内容统一写入“待确认”，不要默认抓官网二次求证。${tail}`;
-            }
-            return `请先从 URL 映射里提取目标 URL 并抓取官网文档补齐关键信息，再给出答案；仍无法确认的内容明确写“待确认”。${tail}`;
-        }
-        return `请基于已有 fragments 给出最可执行答案，并将未覆盖细节明确写为“待确认”；可引导用户补充组件名/API 名/错误码后重新检索。不要默认并行 web_search。${tail}`;
-    }
-    return `知识库未命中有效片段。请向用户说明并确认 product/framework 是否准确；若仍无 platform 信息且问题依赖具体客户端，应先 \`present_framework_choice\`。${tail}`;
+/** 轻量覆盖度：仅算主文件完整度，用于非收敛场景的 allow_pending_confirm 判定，不产出逐文件明细 */
+function computePrimaryCompleteness(allChunks, fragments, preferredSource) {
+    if (!fragments.length)
+        return { primary_completeness: 0 };
+    const primarySource = preferredSource ?? fragments[0]?.source;
+    if (!primarySource)
+        return { primary_completeness: 0 };
+    const hitChunkIds = new Set(fragments.map((f) => f.chunk_id));
+    const sourceChunks = allChunks.filter((chunk) => chunk.source === primarySource);
+    const fileToken = sourceChunks.reduce((sum, chunk) => sum + Math.max(0, chunk.char_end - chunk.char_start), 0);
+    const hitToken = sourceChunks
+        .filter((chunk) => hitChunkIds.has(chunk.id))
+        .reduce((sum, chunk) => sum + Math.max(0, chunk.char_end - chunk.char_start), 0);
+    return {
+        primary_source: primarySource,
+        primary_completeness: fileToken > 0 ? Number((hitToken / fileToken).toFixed(2)) : 0,
+    };
 }
 export function searchKnowledge(params) {
     const norm = normalizeParams(params);
+    const retrievalMode = classifyRetrievalMode(norm.prompt);
     if (requiresFramework(norm)) {
         const manifest = loadManifest();
         return {
             status: 'needs_framework',
             confidence: 'none',
-            message: buildAgentMessage('needs_framework', [], 'none', undefined),
+            message: buildAgentMessage('needs_framework', retrievalMode, [], 'none', undefined),
             query: params,
+            retrieval_mode: retrievalMode,
+            documents: [],
+            catalog: [],
             meta: {
                 pool_size: manifest.chunks.length,
                 filtered_size: 0,
@@ -336,66 +105,63 @@ export function searchKnowledge(params) {
     const manifest = loadManifest();
     const allChunks = manifest.chunks;
     const queryApiTokens = inferQueryApiTokens(norm.prompt);
-    const runSearchPass = (passNorm, opts) => {
-        let pool = filterPool(allChunks, passNorm);
-        // types 误传自愈：首轮保留，二次扩检也同样保留该能力
-        if (pool.length === 0 && passNorm.types?.length) {
-            pool = filterPool(allChunks, { ...passNorm, types: undefined });
-        }
-        const { boosts, exactHits, urlRowHitChunkIds } = runExactLookup(passNorm.prompt, pool, passNorm);
-        // A2 补充正向路由：UserSig 问法下允许 share 命中且优先于无关 urls 噪声
-        if (/usersig|sdkappid|secretkey|鉴权|签名|gentestusersig/i.test(passNorm.prompt)) {
-            for (const chunk of pool) {
-                if (chunk.product === '*' && chunk.source.includes('knowledge/share/userSig.md')) {
-                    boosts[chunk.id] = (boosts[chunk.id] ?? 0) + 220;
-                }
+    let pass = runSearchPass({
+        allChunks,
+        passNorm: norm,
+        retrievalMode,
+        queryApiTokens,
+    });
+    // best-practice 懒补充：仅在主 pass 无本地片段（仅 URL 映射行或完全为空）时触发。
+    // 典型场景：Agent 传 types=['sdk']，filterPool 把 best-practice（type=faq）硬过滤掉，
+    // 只剩 URL 映射行（有 E7 boost 但内容只是一个 URL 链接）。
+    // 不侵入 runSearchPass 层，避免每次调用都执行重复检索。
+    const passRetryReasons = [];
+    const hasLocalContent = pass.fragments.some((f) => !f.source.includes('/urls/'));
+    if (!hasLocalContent && norm.product?.length && !norm.types?.includes('faq')) {
+        const primaryProduct = norm.product[0];
+        const bpCandidates = allChunks.filter((chunk) => {
+            if (!/\/best-practice\//i.test(chunk.source))
+                return false;
+            if (chunk.product !== primaryProduct && chunk.product !== '*')
+                return false;
+            if (norm.frameworks?.length) {
+                const explicitMatch = hasExplicitFrameworkMatch(chunk.framework, norm.frameworks);
+                const wildcardAllowed = chunk.framework.includes('*');
+                if (!explicitMatch && !wildcardAllowed)
+                    return false;
             }
-        }
-        // B2: API 覆盖不足扩检时，对 api/integration 语料做轻量重排提权
-        if (opts?.apiRetry) {
-            for (const chunk of pool) {
-                if (chunk.types.includes('api') || chunk.types.includes('integration')) {
-                    boosts[chunk.id] = (boosts[chunk.id] ?? 0) + 40;
+            return true;
+        });
+        if (bpCandidates.length > 0) {
+            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({
+                    allChunks,
+                    passNorm: { ...norm, types: undefined },
+                    retrievalMode,
+                    queryApiTokens,
+                });
+                if (bpPass.fragments.length > 0) {
+                    pass = bpPass;
+                    passRetryReasons.push('best_practice_supplement');
                 }
             }
         }
-        const productIndex = getProductsBM25Index(allChunks, passNorm.product);
-        const poolWithContent = attachPoolContent(pool);
-        const chunksById = new Map(poolWithContent.map((chunk) => [chunk.id, chunk]));
-        const ranked = rankSubsetWithIndex(passNorm.prompt, pool.map((chunk) => chunk.id), productIndex, boosts);
-        const rankedWithMultipliers = applyRankMultipliers(ranked, chunksById, {
-            product: passNorm.product,
-            framework: passNorm.framework,
-            frameworks: passNorm.frameworks,
-        });
-        const pinnedUrlRowChunkIds = new Set(urlRowHitChunkIds);
-        const fragments = postProcess(rankedWithMultipliers, chunksById, passNorm.limit, {
-            pinnedUrlRowChunkIds,
-        });
-        const urlMappingSources = [...new Set(fragments.map((f) => f.source).filter((source) => isUrlMappingSource(source)))];
-        const references = buildReferences(fragments);
-        const apiNameCoverage = computeApiNameCoverage(queryApiTokens, poolWithContent);
-        const missingApiTokens = computeMissingApiTokens(queryApiTokens, poolWithContent);
-        return {
-            pool,
-            fragments,
-            exactHits,
-            urlMappingSources,
-            references,
-            apiNameCoverage,
-            missingApiTokens,
-            urlMapRelaxed: pinnedUrlRowChunkIds.size > 0,
-            urlMapExactHitCount: pinnedUrlRowChunkIds.size,
-        };
-    };
-    let pass = runSearchPass(norm);
-    const retryReasons = [];
+    }
+    const retryReasons = [...passRetryReasons];
     // B2: API token 覆盖不足时触发一次扩检（去掉 types 约束 + api/integration 轻提权）
     const missingRatio = queryApiTokens.length > 0
         ? Number((pass.missingApiTokens.length / queryApiTokens.length).toFixed(2))
         : 0;
     if (queryApiTokens.length > 0 && (pass.apiNameCoverage === 0 || missingRatio >= 0.3)) {
-        const retryPass = runSearchPass({ ...norm, types: undefined }, { apiRetry: true });
+        const retryPass = runSearchPass({
+            allChunks,
+            passNorm: { ...norm, types: undefined },
+            retrievalMode,
+            queryApiTokens,
+            opts: { apiRetry: true },
+        });
         const retryMissingRatio = queryApiTokens.length > 0
             ? Number((retryPass.missingApiTokens.length / queryApiTokens.length).toFixed(2))
             : 0;
@@ -409,7 +175,12 @@ 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({ ...norm, types: widenedTypes });
+        const retryPass = runSearchPass({
+            allChunks,
+            passNorm: { ...norm, types: widenedTypes },
+            retrievalMode,
+            queryApiTokens,
+        });
         const baseHasProduct = pass.fragments.some((f) => f.types.includes('product'));
         const retryHasProduct = retryPass.fragments.some((f) => f.types.includes('product'));
         if ((retryHasProduct && !baseHasProduct)
@@ -428,7 +199,13 @@ export function searchKnowledge(params) {
         && pass.apiNameCoverage < 0.5;
     if (shouldRetryNativeProduct) {
         const expandedProducts = [...new Set([...(norm.product ?? []), 'native_trtc_sdk'])];
-        const retryPass = runSearchPass({ ...norm, product: expandedProducts, types: undefined }, { apiRetry: true });
+        const retryPass = runSearchPass({
+            allChunks,
+            passNorm: { ...norm, product: expandedProducts, types: undefined },
+            retrievalMode,
+            queryApiTokens,
+            opts: { apiRetry: true },
+        });
         const retryMissingRatio = queryApiTokens.length > 0
             ? Number((retryPass.missingApiTokens.length / queryApiTokens.length).toFixed(2))
             : 0;
@@ -440,6 +217,85 @@ export function searchKnowledge(params) {
             retryReasons.push(`native_product_retry:products=${expandedProducts.join('+')},coverage=${retryPass.apiNameCoverage}`);
         }
     }
+    const resolveNarrativeState = (passSnapshot) => {
+        const source = retrievalMode === 'narrative'
+            ? pickNarrativeSource(passSnapshot.exactHits, passSnapshot.rankedWithMultipliers, passSnapshot.poolWithContent)
+            : null;
+        const document = source ? buildNarrativeDocument(source, allChunks) : null;
+        const quality = assessNarrativeCompleteness(document, norm.prompt);
+        return { source, document, quality };
+    };
+    let narrativeState = resolveNarrativeState(pass);
+    // P0: narrative 自动扩检（一次）——当“完整流程”候选文档缺失或完整度不足时，放宽 types 并提高 limit。
+    const shouldRetryNarrative = retrievalMode === 'narrative'
+        && (narrativeState.document === null || !narrativeState.quality.isComplete);
+    if (shouldRetryNarrative) {
+        const narrativeRetryNorm = {
+            ...norm,
+            types: undefined,
+            limit: Math.max(norm.limit ?? 8, 12),
+        };
+        const retryPass = runSearchPass({
+            allChunks,
+            passNorm: narrativeRetryNorm,
+            retrievalMode,
+            queryApiTokens,
+            opts: { apiRetry: true },
+        });
+        const retryNarrativeState = resolveNarrativeState(retryPass);
+        if (retryNarrativeState.quality.score > narrativeState.quality.score
+            || (narrativeState.document === null && retryNarrativeState.document !== null)
+            || (retryPass.exactHits.length > pass.exactHits.length && retryNarrativeState.document !== null)) {
+            pass = retryPass;
+            narrativeState = retryNarrativeState;
+            retryReasons.push(`narrative_retry:score=${retryNarrativeState.quality.score}`);
+        }
+    }
+    // 覆盖度深检（全量 files 明细 + 自动扩检）仅在收敛到单一 best-practice 时启用，
+    // 避免对普通点查场景做无差别二次检索与全量 coverage_report 外发。
+    const shouldDeepCoverageCheck = Boolean(pass.preferredSource || pass.fullDocumentMode) && pass.fragments.length > 0;
+    let coverageReport;
+    if (shouldDeepCoverageCheck) {
+        coverageReport = buildCoverageReport(allChunks, pass.fragments, pass.preferredSource);
+        if (coverageReport.retry_suggested) {
+            const coverageRetryPass = runSearchPass({
+                allChunks,
+                passNorm: { ...norm, types: undefined, limit: Math.max(norm.limit ?? 8, 12) },
+                retrievalMode,
+                queryApiTokens,
+                opts: { apiRetry: true },
+            });
+            const retriedCoverageReport = buildCoverageReport(allChunks, coverageRetryPass.fragments, coverageRetryPass.preferredSource);
+            const currentCoverage = coverageReport.primary_completeness ?? 0;
+            const retriedCoverage = retriedCoverageReport.primary_completeness ?? 0;
+            if (retriedCoverage > currentCoverage || coverageRetryPass.fragments.length > pass.fragments.length) {
+                pass = coverageRetryPass;
+                coverageReport = retriedCoverageReport;
+                retryReasons.push(`coverage_check_retry:primary=${retriedCoverage}`);
+            }
+        }
+        // 单 chunk 文档 completeness 恒为 1，不代表问题被完整覆盖；
+        // 仅在 fullDocumentMode 聚合多 chunk（>1）且覆盖度足够时才禁止“待确认”。
+        const primaryChunkCount = coverageReport.primary_source
+            ? allChunks.filter((chunk) => chunk.source === coverageReport.primary_source).length
+            : 0;
+        coverageReport = {
+            ...coverageReport,
+            allow_pending_confirm: !(pass.fullDocumentMode
+                && primaryChunkCount > 1
+                && (coverageReport.primary_completeness ?? 0) >= 0.9),
+        };
+    }
+    else {
+        const primary = computePrimaryCompleteness(allChunks, pass.fragments, pass.preferredSource);
+        coverageReport = {
+            allow_pending_confirm: true,
+            ...(primary.primary_source ? { primary_source: primary.primary_source } : {}),
+            primary_completeness: primary.primary_completeness,
+            retry_suggested: false,
+        };
+    }
+    narrativeState = resolveNarrativeState(pass);
     const retryReason = retryReasons.length ? retryReasons.join(';') : undefined;
     const routeInconsistencyWarning = pass.fragments.length > 0
         ? pass.fragments.filter((f) => f.product === '*').length / pass.fragments.length > 0.3
@@ -447,26 +303,73 @@ export function searchKnowledge(params) {
     const { confidence, status } = assessConfidence(pass.fragments, pass.exactHits, pass.apiNameCoverage, queryApiTokens);
     const fabricationRisk = (queryApiTokens.length > 0 && pass.apiNameCoverage < 0.3)
         || (confidence === 'low' && pass.fragments.length < 2);
+    // point 模式不再返回 documents：fullDocumentMode 下 fragments 已按 char_start 顺序返回完整章节，
+    // 再回 documents 会造成同一篇内容重复外发。
+    const documents = retrievalMode === 'narrative'
+        ? (narrativeState.document ? [narrativeState.document] : [])
+        : [];
+    const catalog = retrievalMode === 'discovery'
+        ? buildDiscoveryCatalog(pass.rankedWithMultipliers, pass.poolWithContent, norm.limit)
+        : [];
+    let finalStatus = status;
+    let finalConfidence = confidence;
+    if (retrievalMode === 'narrative' && documents.length > 0) {
+        if (narrativeState.quality.isComplete) {
+            finalStatus = 'success';
+            finalConfidence = 'high';
+        }
+        else {
+            finalStatus = 'low_confidence';
+            finalConfidence = 'low';
+        }
+    }
+    if (retrievalMode === 'discovery' && catalog.length > 0) {
+        finalStatus = 'success';
+        finalConfidence = finalConfidence === 'none' ? 'medium' : finalConfidence;
+    }
     const topScore = pass.fragments[0]?.score;
     const secondScore = pass.fragments[1]?.score;
-    const answerContract = buildAnswerContract(status, confidence, { fabricationRisk });
+    const aggregatedFragments = pass.fragments
+        .filter((fragment) => fragment.aggregated || fragment.citation?.includes('[aggregated]'))
+        .map((fragment) => ({
+        chunk_id: fragment.chunk_id,
+        source: fragment.source,
+        citation: fragment.citation ?? `[来源: ${fragment.chunk_id}][aggregated]`,
+    }));
+    const fullDocumentRequired = retrievalMode === 'narrative'
+        && /完整的?\s*(接入|集成|教程|指南|流程)|完整\s*md|全文|原文|不要总结|含\s*(示例)?代码|全部步骤|完整步骤/i.test(norm.prompt);
+    const answerContract = buildAnswerContract(finalStatus, finalConfidence, retrievalMode, {
+        fabricationRisk,
+        fullDocumentRequired,
+        hasAggregatedFragments: aggregatedFragments.length > 0,
+    });
     const hasProductScope = hasProductScopeIntent(norm.prompt);
     const hasNativeSignal = hasNativeTrtcApiSignal(norm.prompt, queryApiTokens);
-    const hasProductContent = pass.fragments.some((f) => f.types.includes('product') || /\/product\.md$/i.test(f.source));
+    const hasProductContent = pass.fragments.some((f) => f.types.includes('product') || /\/product\.md$/i.test(f.source) || /\/best-practice\//i.test(f.source));
     const hasIntegrationContent = pass.fragments.some((f) => f.types.includes('integration') || /\/integration\.md$/i.test(f.source) || /\/preset\//i.test(f.source));
     const hasApiQueryTokens = queryApiTokens.length > 0;
-    const apiGapDetected = hasApiQueryTokens && (pass.apiNameCoverage === 0 || missingRatio >= 0.3);
+    const finalMissingRatio = hasApiQueryTokens
+        ? Number((pass.missingApiTokens.length / queryApiTokens.length).toFixed(2))
+        : 0;
+    const apiGapDetected = hasApiQueryTokens && (pass.apiNameCoverage === 0 || finalMissingRatio >= 0.3);
     const retryApiGapApplied = retryReasons.some((r) => r.startsWith('api_gap_retry:'));
     const retryProductScopeApplied = retryReasons.includes('product_scope_retry:types+=product');
     const retryNativeProductApplied = retryReasons.some((r) => r.startsWith('native_product_retry:'));
-    const convergenceReached = status === 'success'
-        && (confidence === 'high' || confidence === 'medium')
-        && (!hasApiQueryTokens || pass.apiNameCoverage >= 0.5)
-        && (!hasProductScope || hasProductContent || hasIntegrationContent);
+    const narrativeConverged = retrievalMode !== 'narrative'
+        || (documents.length > 0 && narrativeState.quality.isComplete);
+    const convergenceReached = (retrievalMode === 'narrative' && narrativeConverged)
+        || (retrievalMode === 'discovery' && catalog.length > 0)
+        || (finalStatus === 'success'
+            && (finalConfidence === 'high' || finalConfidence === 'medium')
+            && (!hasApiQueryTokens || pass.apiNameCoverage >= 0.5)
+            && (!hasProductScope || hasProductContent || hasIntegrationContent));
     const retryAdvice = (() => {
-        if (status === 'needs_framework') {
+        if (finalStatus === 'needs_framework') {
             return { stop_retry: true, next_action: 'ask_framework', reason: 'missing_framework' };
         }
+        if (retrievalMode === 'narrative' && !narrativeConverged) {
+            return { stop_retry: false, next_action: 'retry_or_clarify', reason: 'narrative_incomplete' };
+        }
         if (convergenceReached) {
             return { stop_retry: true, next_action: 'answer', reason: 'converged' };
         }
@@ -479,16 +382,26 @@ export function searchKnowledge(params) {
         if (hasNativeSignal && hasNativeClientFramework(norm.frameworks) && !retryNativeProductApplied) {
             return { stop_retry: false, next_action: 'retry_add_native_trtc_sdk', reason: 'possible_native_product_misroute' };
         }
-        if (status === 'empty' || confidence === 'low') {
+        if (finalStatus === 'empty' || finalConfidence === 'low') {
             return { stop_retry: false, next_action: 'retry_or_clarify', reason: 'insufficient_retrieval_signal' };
         }
         return { stop_retry: true, next_action: 'answer', reason: 'default_stop' };
     })();
     return {
-        status,
-        confidence,
-        message: buildAgentMessage(status, pass.fragments, confidence, pass.references, { fabricationRisk }),
+        status: finalStatus,
+        confidence: finalConfidence,
+        message: buildAgentMessage(finalStatus, retrievalMode, pass.fragments, finalConfidence, pass.references, {
+            fabricationRisk,
+            hasDocuments: documents.length > 0,
+            hasCatalog: catalog.length > 0,
+            fullDocumentRequired,
+            preferDocuments: pass.fullDocumentMode,
+            hasAggregatedFragments: aggregatedFragments.length > 0,
+        }),
         query: params,
+        retrieval_mode: retrievalMode,
+        documents,
+        catalog,
         meta: {
             pool_size: allChunks.length,
             filtered_size: pass.pool.length,
@@ -502,6 +415,22 @@ export function searchKnowledge(params) {
             ...(queryApiTokens.length ? { query_api_tokens: queryApiTokens } : {}),
             ...(pass.missingApiTokens.length ? { missing_api_tokens: pass.missingApiTokens } : {}),
             ...(retryReason ? { retry_reason: retryReason } : {}),
+            ...(retrievalMode === 'narrative' && narrativeState.source ? { narrative_source: narrativeState.source } : {}),
+            ...(pass.preferredSource ? { preferred_source: pass.preferredSource } : {}),
+            ...(pass.fullDocumentMode ? { full_document_mode: pass.fullDocumentMode } : {}),
+            coverage_report: coverageReport,
+            ...(aggregatedFragments.length ? { aggregated_fragments: aggregatedFragments } : {}),
+            ...(retrievalMode === 'narrative'
+                ? {
+                    narrative_completeness: {
+                        is_complete: narrativeState.quality.isComplete,
+                        score: narrativeState.quality.score,
+                        section_count: narrativeState.quality.sectionCount,
+                        total_chars: narrativeState.quality.totalChars,
+                        reason: narrativeState.quality.reason,
+                    },
+                }
+                : {}),
             answer_contract: answerContract,
             api_name_coverage: pass.apiNameCoverage,
             fabrication_risk: fabricationRisk,