@tencent-rtc/mcp 1.6.8 → 1.7.1

package/knowledge/search/search-knowledge.js

@@ -1,13 +1,17 @@
 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, 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';
+import { buildReferences } from '../doc-url-resolver.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 let cachedManifest = null;
 function resolveResourcePath(...segments) {
@@ -18,317 +22,173 @@ 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;
+function buildCoverageReport(allChunks, fragments, preferredSource) {
+    if (!fragments.length) {
+        return {
+            files: [],
+            allow_pending_confirm: true,
+            retry_suggested: false,
+        };
     }
-    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$/, '');
+    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,
+        };
+    });
+    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 partitionFragments(fragments) {
-    const urlMapping = [];
-    const localDoc = [];
-    for (const fragment of fragments) {
-        if (isUrlMappingSource(fragment.source)) {
-            urlMapping.push(fragment);
-        }
-        else {
-            localDoc.push(fragment);
+/**
+ * 提取 title 的主题特征 token 集合（跨语言统一）。
+ * - CJK 路径: 字符 2-gram 滑动（与 V2 版本 bit-identical，zh 端 0 退化）。
+ * - EN 路径: 原子 token + word 2-gram。
+ *   - 原子 token: 单词 [a-z0-9]+ 或带连字符的复合词 [a-z0-9]+(?:-[a-z0-9]+)+
+ *     关键: `one-to-one` 整体作为一个 token，不拆成 ['one', 'to', 'one']（域语义：C2C 类别标签，
+ *     跟 CJK「单聊」等价；拆开会产生 'one one' 这种无意义 2-gram 噪声）。
+ *   - word 2-gram: 原子 token 之间的 2-gram 滑动（不跨复合词内部），跟 CJK 2-gram 同构。
+ *   - stopword 过滤: the/and/for/with/from/how/use/api/sdk/app/set/get/add/to/of/in/on/by 等功能词。
+ *
+ * 产品无关: 纯字面特征，不依赖 IDF / 分词词表。
+ */
+function extractTitleTokens(text) {
+    const out = new Set();
+    // CJK 路径: 字符 2-gram（与原 extractTitleBigrams bit-identical）
+    for (const seg of text.match(/[\u4e00-\u9fff]{2,}/g) ?? []) {
+        for (let i = 0; i < seg.length - 1; i += 1) {
+            out.add(seg.slice(i, i + 2));
         }
     }
-    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();
-    // Keep API-shaped tokens only; exclude product/platform brand words to avoid false low-confidence downgrades.
-    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',
+    // EN 路径: 原子 token（含连字符复合词整体保留）+ 原子间的 2-gram
+    // 正则说明: [a-z][a-z0-9]*(?:-[a-z][a-z0-9]*)* — 匹配单词或带连字符的复合词，
+    // 一次匹配即可拿到完整 token，不会在复合词内部产生 2-gram。
+    const EN_STOPS = new Set([
+        'the', 'and', 'for', 'with', 'from', 'how', 'what', 'why', 'when', 'where',
+        'use', 'api', 'sdk', 'app', 'set', 'get', 'add', 'to', 'of', 'in', 'on', 'by',
     ]);
-    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]);
+    const atomic = (text.toLowerCase().match(/[a-z][a-z0-9]*(?:-[a-z][a-z0-9]*)*/g) ?? [])
+        .filter((w) => w.length >= 3 && !EN_STOPS.has(w));
+    for (const w of atomic)
+        out.add(w);
+    for (let i = 0; i < atomic.length - 1; i += 1) {
+        out.add(`${atomic[i]} ${atomic[i + 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;
-    }
-    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 };
-    });
-    return adjusted.sort((a, b) => b.score - a.score);
+    return out;
 }
 /**
- * 多因子置信度评估：exact 命中 + 分数梯度 + API 覆盖度。
+ * 单主题截断：基于 scoreUrlRow + 字面 token Jaccard 判定 query 是否有「精确单主题」命中。
+ *
+ * 设计（V3 跨语言对称版，V2 基础上扩展 EN 路径）：
+ * - scoreUrlRow 是「URL row 跟 query 的纯净相关度」（不被 E7 boost 稀释），
+ *   500+ 代表覆盖率 + 有效信号占比都达标的语义对齐强信号。
+ * - **但 scoreUrlRow 数值相近（615-700）时无法区分「同主题相关 row」和「泛命中 row」**。
+ *   例：query「单聊消息发送前回调」+ types=['webhook']：
+ *     - top1=单聊消息发送之前回调 (scoreUrlRow=700) ← 真正答案
+ *     - top2=单聊消息发送之后回调 (scoreUrlRow=672) ← 时态近义，保留
+ *     - top3-6=单聊消息撤回/扩展/编辑/已读 (scoreUrlRow=615) ← 不同动作，应砍
+ *     - top7-8=群消息发送之前/之后 (scoreUrlRow=643/615) ← 动作相同时态差异，保留"前"砍"后"
+ *   同样例 EN 端: query "One-to-one message send before webhook" 返回 5 个 webhook 切片
+ *   （before/after C2C、before/after group、group exception），其中 group 类 3 个应砍。
+ * - 解决: 加 **token Jaccard** 作为「是否跟 top1 同主题」的二次过滤——
+ *   只保留跟 top1 字面 Jaccard ≥ 0.5 的 row（共享核心动作词/时态词）。
+ *   - CJK: 2-gram 字符滑动（与 V2 bit-identical，zh 端 0 退化）
+ *   - EN:  原子 token（含连字符复合词 one-to-one 整体保留）+ 原子间 word 2-gram，
+ *          跟 CJK 2-gram 同构
+ * - 多主题（保留 ≥ 2 个 row）/ 弱信号（top1 < 500）/ 不足 2 个候选 → 保持原 limit。
+ *
+ * 关键不变量:
+ * - 不动 top1（避免误判导致用户拿不到正确答案）
+ * - 不减少「真的有第二个相关 row」的场景（如「群消息发送前/之后」同主题）
+ * - 截断发生在 narrative 模式之外（narrative 模式本身按 full document 走，不受影响）
  */
-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 SINGLE_TOPIC_URL_SCORE_THRESHOLD = 500;
+const SINGLE_TOPIC_JACCARD_THRESHOLD = 0.5;
+function applySingleTopicTrim(fragments, prompt, limit) {
+    if (fragments.length < 2)
+        return fragments;
+    // top1 必须有强 scoreUrlRow 信号（避免弱信号 top1 误判导致砍掉正确答案）
+    const top1UrlScore = scoreUrlRow(prompt, fragments[0].title).score;
+    if (top1UrlScore < SINGLE_TOPIC_URL_SCORE_THRESHOLD)
+        return fragments;
+    // 用 top1 标题的 token 集合作为「主题特征」，过滤出字面同主题的 row。
+    // CJK 标题走 2-gram 字符路径（与 V2 等价，zh 端 0 退化），
+    // EN 标题走原子 token + word 2-gram 路径（与 CJK 2-gram 同构，en 端获得对等的单主题判定）。
+    const top1Tokens = extractTitleTokens(fragments[0].title);
+    if (top1Tokens.size < 2)
+        return fragments; // 标题太短或纯 stopword，不做主题判定
+    const related = fragments.filter((f) => {
+        const fTokens = extractTitleTokens(f.title);
+        if (fTokens.size === 0)
+            return false;
+        const intersection = [...fTokens].filter((t) => top1Tokens.has(t)).length;
+        const union = new Set([...fTokens, ...top1Tokens]).size;
+        return intersection / union >= SINGLE_TOPIC_JACCARD_THRESHOLD;
+    });
+    // 过滤后只剩 1 个 → 单主题精确返回 [top1]
+    if (related.length === 1)
+        return [related[0]];
+    // 多个同主题 row（topN）→ 保留全部（受 limit 约束）
+    return related.slice(0, limit);
 }
-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();
+        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,
-                exact_hits: [],
+                answer_contract: buildAnswerContract('needs_framework', 'none', retrievalMode, { fabricationRisk: false }),
             },
             fragments: [],
         };
@@ -336,66 +196,93 @@ 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 层，避免每次调用都执行重复检索。
+    // 修复 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。
+    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 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: ['faq'] },
+                    retrievalMode,
+                    queryApiTokens,
+                });
+                if (bpPass.fragments.length > 0) {
+                    // 合并：保留原 URL row 在前，追加 BP fragments 去重
+                    const existingIds = new Set(pass.fragments.map((f) => f.chunk_id));
+                    const newBpFragments = bpPass.fragments.filter((f) => !existingIds.has(f.chunk_id));
+                    if (newBpFragments.length > 0) {
+                        // 重新编号 rank：原 URL row 保持 1..N，BP 从 N+1 开始
+                        const merged = [
+                            ...pass.fragments,
+                            ...newBpFragments.map((f, i) => ({ ...f, rank: pass.fragments.length + i + 1 })),
+                        ];
+                        pass = {
+                            ...pass,
+                            fragments: merged,
+                        };
+                        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;
@@ -406,10 +293,15 @@ export function searchKnowledge(params) {
             retryReasons.push(`api_gap_retry:coverage=${pass.apiNameCoverage},missing_ratio=${retryMissingRatio}`);
         }
     }
-    // B3: Mixed “integration + product-scope” questions should include product docs, not just feature/integration.
+    // 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)
@@ -419,7 +311,7 @@ export function searchKnowledge(params) {
             retryReasons.push('product_scope_retry:types+=product');
         }
     }
-    // B4: If query looks like Native TRTC APIs but routed to live/room/call, auto-append native_trtc_sdk and retry.
+    // B4: 若疑似 Native TRTC API 问法却路由到 live/room/call，自动补扩 native_trtc_sdk 产品重检。
     const shouldRetryNativeProduct = hasNativeClientFramework(norm.frameworks)
         && hasNativeTrtcApiSignal(norm.prompt, queryApiTokens)
         && norm.product?.some((p) => ['live', 'room', 'call'].includes(p))
@@ -428,7 +320,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,33 +338,166 @@ export function searchKnowledge(params) {
             retryReasons.push(`native_product_retry:products=${expandedProducts.join('+')},coverage=${retryPass.apiNameCoverage}`);
         }
     }
-    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
-        : false;
+    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);
+    // P0 单主题截断：基于 scoreUrlRow（URL row 跟 query 的纯净相关度，不被 E7 boost 污染）
+    // + 2-gram 字面 Jaccard 判定 query 是否有「精确单主题」命中。
+    // 详见 applySingleTopicTrim 函数注释。
+    let passFragments = applySingleTopicTrim(pass.fragments, norm.prompt, norm.limit ?? 8);
+    // P1 低置信裁剪：0 命中 query（top1 finalScore < 20）的 fragments 是 BM25 凑出来的
+    // 无关内容（如「im 怎么发火箭」top1=audio-message-send finalScore=16.8），
+    // 直接裁剪到 1 个 top fragment，避免 BP 凑数撑爆。
+    // 适用：first pass 已经拉了 BP 文档但 top1 仍很弱的情况。
+    if (passFragments.length > 1 && (passFragments[0]?.score ?? 0) < 20) {
+        passFragments = [passFragments[0]];
+    }
+    if (passFragments !== pass.fragments) {
+        // 同步重建 references：V3 applySingleTopicTrim 砍 fragment 时不砍 references 会导致
+        // fragments/references 数量错位（实测：5→3 fragment 砍后 references 仍 5 个，LLM 困惑）。
+        // 用 trim 后的 fragments 重建 references，保持一致。
+        pass = { ...pass, fragments: passFragments, references: buildReferences(passFragments) };
+    }
     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);
-    const topScore = pass.fragments[0]?.score;
-    const secondScore = pass.fragments[1]?.score;
-    const answerContract = buildAnswerContract(status, confidence, { fabricationRisk });
+    // narrative 模式返回完整文档；point/discovery 通过 fragments 提供内容（已含正文）。
+    const documents = retrievalMode === 'narrative'
+        ? (narrativeState.document ? [narrativeState.document] : [])
+        : [];
+    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' && pass.fragments.length > 0) {
+        finalStatus = 'success';
+        finalConfidence = finalConfidence === 'none' ? 'medium' : finalConfidence;
+    }
+    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 ?? `[Source: ${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' && pass.fragments.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,34 +510,45 @@ 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,
+            fullDocumentRequired,
+            preferDocuments: pass.fullDocumentMode,
+            hasAggregatedFragments: aggregatedFragments.length > 0,
+        }),
+        // query 保留：l1-enrich 依赖 response.query.frameworks 做限领域回填（内部消费）
         query: params,
+        retrieval_mode: retrievalMode,
+        documents,
         meta: {
-            pool_size: allChunks.length,
-            filtered_size: pass.pool.length,
-            exact_hits: pass.exactHits,
-            ...(pass.urlMappingSources.length ? { url_mapping_sources: pass.urlMappingSources } : {}),
-            ...(pass.urlMapRelaxed ? { url_map_relaxed: pass.urlMapRelaxed } : {}),
-            ...(pass.urlMapExactHitCount > 0 ? { url_map_exact_hit_count: pass.urlMapExactHitCount } : {}),
+            // 参考文档（AI 输出「参考文档」小节依据）：
             ...(pass.references.length ? { references: pass.references } : {}),
-            ...(topScore !== undefined ? { top_score: Number(topScore.toFixed(2)) } : {}),
-            ...(secondScore !== undefined ? { second_score: Number(secondScore.toFixed(2)) } : {}),
-            ...(queryApiTokens.length ? { query_api_tokens: queryApiTokens } : {}),
-            ...(pass.missingApiTokens.length ? { missing_api_tokens: pass.missingApiTokens } : {}),
-            ...(retryReason ? { retry_reason: retryReason } : {}),
             answer_contract: answerContract,
-            api_name_coverage: pass.apiNameCoverage,
+            // 防幻觉信号（search-message 依赖）：
             fabrication_risk: fabricationRisk,
-            route_inconsistency_warning: routeInconsistencyWarning,
+            // 内部重试决策（供上游判断是否需重搜）：
             retry_advice: retryAdvice,
+            // narrative 模式的完整度报告（仅 narrative 模式返回，用于验收/判断完整指南是否完整）
+            ...(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,
+                    },
+                }
+                : {}),
         },
         fragments: pass.fragments,
     };