@tencent-rtc/mcp 1.7.0 → 1.7.2

package/knowledge/search/search-knowledge.js

@@ -7,9 +7,11 @@ 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 { 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) {
@@ -63,6 +65,97 @@ function buildCoverageReport(allChunks, fragments, preferredSource) {
         retry_suggested: primaryCompleteness < 0.6,
     };
 }
+/**
+ * 提取 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));
+        }
+    }
+    // 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',
+    ]);
+    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]}`);
+    }
+    return out;
+}
+/**
+ * 单主题截断：基于 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 走，不受影响）
+ */
+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);
+}
 /** 轻量覆盖度：仅算主文件完整度，用于非收敛场景的 allow_pending_confirm 判定，不产出逐文件明细 */
 function computePrimaryCompleteness(allChunks, fragments, preferredSource) {
     if (!fragments.length)
@@ -85,7 +178,7 @@ 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',
@@ -95,9 +188,7 @@ export function searchKnowledge(params) {
             documents: [],
             catalog: [],
             meta: {
-                pool_size: manifest.chunks.length,
-                filtered_size: 0,
-                exact_hits: [],
+                answer_contract: buildAnswerContract('needs_framework', 'none', retrievalMode, { fabricationRisk: false }),
             },
             fragments: [],
         };
@@ -115,9 +206,26 @@ export function searchKnowledge(params) {
     // 典型场景：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/'));
-    if (!hasLocalContent && norm.product?.length && !norm.types?.includes('faq')) {
+    // 当主 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))
@@ -138,13 +246,26 @@ export function searchKnowledge(params) {
             if ((bpRanked[0]?.score ?? 0) >= 6) {
                 const bpPass = runSearchPass({
                     allChunks,
-                    passNorm: { ...norm, types: undefined },
+                    passNorm: { ...norm, types: ['faq'] },
                     retrievalMode,
                     queryApiTokens,
                 });
                 if (bpPass.fragments.length > 0) {
-                    pass = bpPass;
-                    passRetryReasons.push('best_practice_supplement');
+                    // 合并：保留原 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');
+                    }
                 }
             }
         }
@@ -296,21 +417,30 @@ export function searchKnowledge(params) {
         };
     }
     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
-        : false;
+    // 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);
-    // point 模式不再返回 documents：fullDocumentMode 下 fragments 已按 char_start 顺序返回完整章节，
-    // 再回 documents 会造成同一篇内容重复外发。
+    // narrative 模式返回完整文档；point/discovery 通过 fragments 提供内容（已含正文）。
     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) {
@@ -323,18 +453,16 @@ export function searchKnowledge(params) {
             finalConfidence = 'low';
         }
     }
-    if (retrievalMode === 'discovery' && catalog.length > 0) {
+    if (retrievalMode === 'discovery' && pass.fragments.length > 0) {
         finalStatus = 'success';
         finalConfidence = finalConfidence === 'none' ? 'medium' : finalConfidence;
     }
-    const topScore = pass.fragments[0]?.score;
-    const secondScore = pass.fragments[1]?.score;
     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]`,
+        citation: fragment.citation ?? `[Source: ${fragment.chunk_id}][aggregated]`,
     }));
     const fullDocumentRequired = retrievalMode === 'narrative'
         && /完整的?\s*(接入|集成|教程|指南|流程)|完整\s*md|全文|原文|不要总结|含\s*(示例)?代码|全部步骤|完整步骤/i.test(norm.prompt);
@@ -358,7 +486,7 @@ export function searchKnowledge(params) {
     const narrativeConverged = retrievalMode !== 'narrative'
         || (documents.length > 0 && narrativeState.quality.isComplete);
     const convergenceReached = (retrievalMode === 'narrative' && narrativeConverged)
-        || (retrievalMode === 'discovery' && catalog.length > 0)
+        || (retrievalMode === 'discovery' && pass.fragments.length > 0)
         || (finalStatus === 'success'
             && (finalConfidence === 'high' || finalConfidence === 'medium')
             && (!hasApiQueryTokens || pass.apiNameCoverage >= 0.5)
@@ -393,33 +521,23 @@ export function searchKnowledge(params) {
         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 保留：l1-enrich 依赖 response.query.frameworks 做限领域回填（内部消费）
         query: params,
         retrieval_mode: retrievalMode,
         documents,
-        catalog,
         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 } : {}),
-            ...(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 } : {}),
+            answer_contract: answerContract,
+            // 防幻觉信号（search-message 依赖）：
+            fabrication_risk: fabricationRisk,
+            // 内部重试决策（供上游判断是否需重搜）：
+            retry_advice: retryAdvice,
+            // narrative 模式的完整度报告（仅 narrative 模式返回，用于验收/判断完整指南是否完整）
             ...(retrievalMode === 'narrative'
                 ? {
                     narrative_completeness: {
@@ -431,11 +549,6 @@ export function searchKnowledge(params) {
                     },
                 }
                 : {}),
-            answer_contract: answerContract,
-            api_name_coverage: pass.apiNameCoverage,
-            fabrication_risk: fabricationRisk,
-            route_inconsistency_warning: routeInconsistencyWarning,
-            retry_advice: retryAdvice,
         },
         fragments: pass.fragments,
     };

package/knowledge/search/search-message.js

@@ -1,28 +1,29 @@
 import { hasBestPracticeFragment, partitionFragments, } from './search-core.js';
 export function buildAnswerContract(status, confidence, retrievalMode, opts) {
-    const uncertaintyRule = 'Avoid speculative wording such as "maybe/probably/should/it seems".';
-    const riskRule = opts?.fabricationRisk ? 'When fabrication_risk=true, do not fill unmatched API details.' : '';
+    const uncertaintyRule = 'Do not use speculative wording (e.g., "maybe/probably/should/it seems"). When the user asks for a specific detail (API/method/enum/event/error code) that is not present in the returned fragments, do not invent it; instead, explicitly mark it as "[not found in docs]" or "[to be confirmed]" in the answer so the gap is visible to the user.';
+    const riskRule = opts?.fabricationRisk ? 'fabrication_risk=true: do not fill unmatched API details. For every detail that cannot be grounded in the returned fragments, explicitly mark it as "[not found in docs]" or "[to be confirmed]"; the user-facing answer must surface every gap, not omit silently.' : '';
     const aggregatedRule = opts?.hasAggregatedFragments
-        ? 'If a field comes from an aggregated fragment, explicitly mark it as "[supplement]" or footnote to avoid confusion with directly matched fragments.'
+        ? 'If a field comes from an aggregated fragment, explicitly mark it as "[supplement]" or a footnote to avoid confusion with directly matched fragments.'
         : '';
     const modeRule = retrievalMode === 'narrative'
         ? (opts?.fullDocumentRequired
-            ? 'Narrative mode (full-document priority): output complete body content in documents[0].sections order, preserving sample code blocks/commands/key notes; do not compress into a summary.'
+            ? 'Narrative mode (full-document priority): output the complete body in documents[0].sections order, preserving sample code blocks/commands/key notes; do not compress into a summary.'
             : 'Narrative mode: organize the answer in documents.sections order; do not skip sections.')
         : retrievalMode === 'discovery'
-            ? 'Discovery mode: provide catalog/list first, then brief selection advice; do not fabricate nonexistent items.'
-            : 'Point mode: provide direct conclusion first, then key details from matched fragments.';
+            ? 'Discovery mode: list every candidate from the returned fragments with full identifying detail (name, purpose, platform scope); then give complete selection guidance with trade-offs; do not fabricate nonexistent items.'
+            : 'Point mode: synthesize a complete answer derived from the matched fragments, preserving relevant depth and source-faithful detail; do not artificially shorten, the reporting layer enforces any necessary truncation.';
     const structureRule = opts?.fullDocumentRequired
         ? 'If the user explicitly asks for a "full guide/full markdown/full text/include sample code", expand the body in full section order; do not omit steps or code except minimal heading cleanup.'
-        : 'Use problem-oriented headings and reuse the user question wording when possible.';
+        : 'Use problem-oriented headings when the answer benefits from sections; otherwise write a continuous synthesized answer (no per-section length constraint).';
     const sectionRule = opts?.fullDocumentRequired
         ? 'Each section may contain complete steps/commands/code; no "1-2 sentence" limit applies.'
-        : 'For each subsection, give the direct answer first, then 1-2 essential explanatory sentences; avoid template wording.';
+        : 'For each section (or in continuous prose): synthesize a complete answer from the matched fragments, including problem analysis, code samples, citations, and examples as relevant. Preserve the source depth. Avoid template wording. The reporting layer enforces truncation, so do not artificially summarize.';
     return [
         '[Output contract — MUST follow]',
+        'User-visible answer MUST be complete; never artificially shorten or summarize for brevity.',
         structureRule,
         sectionRule,
-        'If details are not covered, omit them directly instead of filling for completeness.',
+        'If details are not covered by fragments, mark them as "[not found in docs]" or "[to be confirmed]" instead of inventing or silently omitting.',
         'Keep a final "References" section with only document titles or URLs; do not show retrieval process/evidence chain/scoring details in the body.',
         'User-visible content MUST NOT include retrieval-system wording (e.g., "matched fragments / retrieval result / confidence / score / recall / rerank").',
         'User-visible content MUST NOT include tool/routing decision wording (e.g., "should call / call first / let me search / consultation task / not codegen / search_trtc_knowledge / finalize_answer / submit_feedback").',
@@ -35,7 +36,7 @@ export function buildAnswerContract(status, confidence, retrievalMode, opts) {
 }
 export function buildAgentMessage(status, retrievalMode, fragments, confidence, _references, opts) {
     const riskRule = opts?.fabricationRisk ? 'Current retrieval has hallucination risk (fabrication_risk=true): do not fill unmatched API details.' : '';
-    // Keep output contract in meta.answer_contract only, to avoid duplicated instruction blocks in message.
+    // Keep the output contract in meta.answer_contract only, to avoid duplicated instruction blocks in message.
     const tail = `${riskRule} Output contract is in meta.answer_contract and MUST be followed. User-visible output must answer the question directly; do not start with tool-selection or retrieval-plan narrative. Final answer drafted -> MUST call \`finalize_answer\` before replying, and \`prompt\`, \`answer\`, \`queryID\` are all required (queryID is from this tool output). Explicit follow-up feedback -> call \`submit_feedback\`.`;
     if (status === 'needs_framework') {
         return '[Hard rule] The question depends on a concrete platform implementation, but frameworks are missing. Cross-platform mixed retrieval is disallowed due to low precision. MUST call `present_framework_choice` first (with product), then call this tool again after user selects web/miniprogram/android/ios/flutter/react/vue/uni-app etc, and MUST include both **product + frameworks**. Do not hard-search with empty frameworks.';
@@ -46,8 +47,8 @@ export function buildAgentMessage(status, retrievalMode, fragments, confidence,
         }
         return `This request is narrative (full guide) mode: prioritize documents.sections order and do not skip sections. Fragments are for cross-checking only. ${tail}`;
     }
-    if (status === 'success' && retrievalMode === 'discovery' && opts?.hasCatalog) {
-        return `This request is discovery (catalog/list) mode: output candidate list first, then brief selection advice; do not treat a single fragment as a full workflow. ${tail}`;
+    if (status === 'success' && retrievalMode === 'discovery' && fragments.length > 0) {
+        return `This request is discovery (catalog/list) mode: list every candidate from the returned fragments with full identifying detail, then give complete selection guidance; do not treat a single fragment as a full workflow, and do not fabricate nonexistent items. ${tail}`;
     }
     if (status === 'success' && retrievalMode === 'point' && opts?.preferDocuments) {
         return `Current results have converged to a single best-practice document: fragments already contain the full document in original section order. Answer in that order, preserve code samples and key notes, and do not compress into a short summary. ${tail}`;

package/knowledge/search/url-row-idf.js

@@ -0,0 +1,120 @@
+/**
+ * url-row-idf.ts
+ *
+ * 为 url-row 匹配提供 **IDF（逆文档频率）加权**，用于自动降权高频泛词
+ * （`消息`/`message`/`group` 等），而不依赖任何枚举词表。
+ *
+ * 语言无关：同时支持中文（CJK 切词）与英文（空格切词）。
+ * 产品无关：词频统计对当前语料中所有 `urls/` 行的标题构建，未来新增产品自动纳入。
+ *
+ * 懒加载 + 内存缓存：首次调用时从 manifest 索引统计，之后复用。
+ */
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+let cachedIdf = null;
+let cachedManifestPath = '';
+/** 判断 source 是否 url 映射行（产品无关：knowledge/<product>/urls/） */
+function isUrlMappingSource(source) {
+    return /knowledge\/[a-z0-9_-]+\/urls\/.+\.md$/i.test(source.replace(/\\/g, '/'));
+}
+/**
+ * 中文连续段切为 2-gram 词片；英文按空白切词。
+ * 返回小写 token 列表（未去重，用于统计文档频率）。
+ */
+function tokenizeTitle(title) {
+    const tokens = [];
+    const lower = title.toLowerCase();
+    // 英文词（>=2 字母）
+    for (const match of lower.matchAll(/[a-z][a-z0-9]{1,}/g)) {
+        tokens.push(match[0]);
+    }
+    // 中文连续段 → 2-gram（避免单字「消息」过于泛，同时保留「消息回应」这类相邻组合的贡献）
+    for (const seg of lower.match(/[\u4e00-\u9fff]{2,}/g) ?? []) {
+        for (let i = 0; i < seg.length - 1; i += 1) {
+            tokens.push(seg.slice(i, i + 2));
+        }
+        // 整段作为复合词也计入（比 2-gram 更有区分度）
+        tokens.push(seg);
+    }
+    return tokens;
+}
+function resolveManifestPath() {
+    return path.resolve(__dirname, '../../resource/index/manifest.json');
+}
+/** 构建 IDF 索引：统计所有 urls 行标题的文档频率 */
+function buildIdfIndex() {
+    const manifestPath = resolveManifestPath();
+    const df = new Map();
+    const seenTitles = new Set();
+    let totalDocs = 0;
+    if (fs.existsSync(manifestPath)) {
+        try {
+            const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+            for (const chunk of manifest.chunks ?? []) {
+                if (!chunk.title)
+                    continue;
+                if (!isUrlMappingSource(chunk.source))
+                    continue;
+                if (seenTitles.has(chunk.title))
+                    continue;
+                seenTitles.add(chunk.title);
+                totalDocs += 1;
+                const seen = new Set();
+                for (const token of tokenizeTitle(chunk.title)) {
+                    if (seen.has(token))
+                        continue;
+                    seen.add(token);
+                    df.set(token, (df.get(token) ?? 0) + 1);
+                }
+            }
+        }
+        catch {
+            // manifest 读取失败时退化为空索引（IDF 全视为高区分度）
+        }
+    }
+    return { df, totalDocs };
+}
+/**
+ * 计算单个 token 的 IDF 权重。
+ * - 未出现在统计中（稀有/新词）→ 高权重（IDF 高）
+ * - 高频泛词 → 低权重
+ * - totalDocs 为 0 时退化为 1（不降权）
+ */
+export function idfWeight(token) {
+    if (!cachedIdf)
+        loadIdf();
+    const { df, totalDocs } = cachedIdf;
+    if (!totalDocs)
+        return 1;
+    const docFreq = df.get(token.toLowerCase()) ?? 0;
+    if (docFreq <= 0)
+        return 1;
+    // IDF = ln((N - df + 0.5) / (df + 0.5)) + 1，平滑处理避免极端
+    const idf = Math.log((totalDocs - docFreq + 0.5) / (docFreq + 0.5)) + 1;
+    return Math.max(idf, 0.2);
+}
+/** 加载（或复用）IDF 索引 */
+export function loadIdf() {
+    const manifestPath = resolveManifestPath();
+    if (cachedIdf && cachedManifestPath === manifestPath)
+        return;
+    cachedIdf = buildIdfIndex();
+    cachedManifestPath = manifestPath;
+}
+/**
+ * 判断 2-gram 是否为「有效词」（在 urls 标题语料中出现过，df>0）。
+ * 跨词边界的 2-gram（如「送前」「前回」「端群」）在标题语料中 df=0（从未作为词出现），
+ * 属于 N-gram 滑窗产生的噪声，不应参与覆盖率分母。df>0 的才是真实语义词。
+ * 产品无关：对所有产品的 urls 标题统计，不依赖枚举词表。
+ */
+export function isValidBigram(token) {
+    if (!cachedIdf)
+        loadIdf();
+    return (cachedIdf.df.get(token.toLowerCase()) ?? 0) > 0;
+}
+/** 供测试/热更使用 */
+export function resetIdfCache() {
+    cachedIdf = null;
+}