@tencentcloud/sdk-mcp 1.7.0 → 1.7.1

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,32 +1,33 @@
 import { hasBestPracticeFragment, partitionFragments, } from './search-core.js';
 export function buildAnswerContract(status, confidence, retrievalMode, opts) {
-    const uncertaintyRule = '不得出现"可能/大概/应该/推测"等猜测措辞。';
-    const riskRule = opts?.fabricationRisk ? 'fabrication_risk=true：禁止补全未命中 API 细节。' : '';
+    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
-        ? '若字段来自 aggregated fragment，引用处需显式标注"[补全]"或脚注，避免与直接命中片段混淆。'
+        ? '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 模式（全文优先）：必须按 documents[0].sections 顺序输出完整正文，保留示例代码块/命令与关键说明，不得压缩成目录或摘要。'
-            : 'narrative 模式：优先按 documents.sections 的顺序组织答案，不要跳节。')
+            ? '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 模式：先给目录/清单，再给简短选择建议；不要伪造不存在的条目。'
-            : 'point 模式：优先给直接结论，再引用命中片段补充关键细节。';
+            ? '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
-        ? '当用户明确要求"完整指南/完整 md/全文/含示例代码"时，正文必须以文档章节顺序完整展开；除必要的章节标题整理外，不得省略步骤与代码。'
-        : '使用"问题导向"标题组织答案，优先复用用户提问原句：一、<问题1> 二、<问题2> 三、<问题3> …';
+        ? '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 when the answer benefits from sections; otherwise write a continuous synthesized answer (no per-section length constraint).';
     const sectionRule = opts?.fullDocumentRequired
-        ? '每个章节可包含完整步骤、命令与代码，不受"1-2句"限制。'
-        : '每个小节先给直接结论，再补 1-2 句必要说明；避免模板化术语（如"依据/操作"字样）。';
+        ? 'Each section may contain complete steps/commands/code; no "1-2 sentence" limit applies.'
+        : '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,
-        '信息不足的延展细节可直接省略，不要为凑完整度强行补全。',
-        '末尾保留"参考文档"小节，仅列文档标题或 URL；正文不展示检索过程、证据链、打分细节。',
-        '用户可见正文禁止出现系统检索话术（如"命中片段/检索结果/置信度/分数/召回/重排"）。',
-        '用户可见正文禁止出现工具与链路决策话术（如"应调用/先调用/让我先搜索/属于咨询类问题/而非 codegen/search_trtc_knowledge/finalize_answer/submit_feedback"）。',
-        '硬约束：不得引入 fragments 未出现的 API 名、字段值、枚举项、事件名。',
+        '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").',
+        'Hard constraint: do not introduce API names/field values/enums/events that are absent from fragments.',
         modeRule,
         uncertaintyRule,
         riskRule,
@@ -34,23 +35,23 @@ export function buildAnswerContract(status, confidence, retrievalMode, opts) {
     ].filter(Boolean).join(' ');
 }
 export function buildAgentMessage(status, retrievalMode, fragments, confidence, _references, opts) {
-    const riskRule = opts?.fabricationRisk ? '当前检索存在幻觉风险（fabrication_risk=true）：禁止补全未命中 API 细节。' : '';
-    // 输出契约只在 meta.answer_contract 保留一份，避免 message 内嵌造成双份指令。
-    const tail = `${riskRule} 输出模板契约见 meta.answer_contract，必须严格遵守。用户可见输出必须直接回答问题，禁止先叙述工具选择或检索计划。 Final answer drafted -> MUST call \`finalize_answer\` before replying，prompt、answer、queryID 都是必填参数，必须传入（queryID 即本工具返回的 queryID）。Explicit follow-up feedback -> call \`submit_feedback\`.`;
+    const riskRule = opts?.fabricationRisk ? 'Current retrieval has hallucination risk (fabrication_risk=true): do not fill unmatched API details.' : '';
+    // 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 '【硬规则】问题依赖具体平台实现，但未指定 frameworks，全平台混检信息密度低且被禁止。MUST 先调用 `present_framework_choice`（传入 product），等用户选定 web/miniprogram/android/ios/flutter/react/vue/uni-app 等后再调用本工具，并 MUST 带上 **product + frameworks**。禁止传空 frameworks 硬搜。';
+        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.';
     }
     if (status === 'success' && retrievalMode === 'narrative' && opts?.hasDocuments) {
         if (opts?.fullDocumentRequired) {
-            return `当前请求属于 narrative（完整指南）模式，且用户明确要求完整正文：必须按 documents[0].sections 顺序输出完整内容，保留示例代码与命令，不要摘要化；fragments 仅用于交叉校验。${tail}`;
+            return `This request is narrative (full guide) mode and user explicitly asks for full text: output complete content in documents[0].sections order, preserving sample code and commands; do not summarize. Fragments are for cross-checking only. ${tail}`;
         }
-        return `当前请求属于 narrative（完整指南）模式：优先按 documents.sections 顺序组织答案，不要跳节；fragments 仅用于交叉校验。${tail}`;
+        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 `当前请求属于 discovery（目录清单）模式：先输出候选项清单，再给简短选择建议；不要把单个片段当完整流程。${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 `当前命中已收敛到单一 best-practice 标准文档：fragments 已按原文章节顺序完整返回，请按章节顺序组织答案，保留示例代码与关键说明，不要压缩成摘要或跳节。${tail}`;
+        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}`;
     }
     const { urlMapping, localDoc, urlMappingKinds } = partitionFragments(fragments);
     const hasUrlMapping = urlMapping.length > 0;
@@ -60,28 +61,28 @@ export function buildAgentMessage(status, retrievalMode, fragments, confidence,
     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}`;
+            const scopeLabel = topFragment.scope ? ` (${topFragment.scope})` : '';
+            return `This capability is **NOT supported** on the current platform/form${scopeLabel}. Answer MUST: (1) clearly state "**not supported**" in the first paragraph; (2) explain this is a current platform Core capability boundary, not a missing sample-code issue; (3) provide only supported alternatives on this platform (e.g., corresponding preset UI); if no explicit alternative exists in knowledge, clearly state no executable alternative path is available; (4) DO NOT output Core API invocation steps or integration steps for this unsupported capability. ${tail}`;
         }
         if (hasUrlMapping && !hasLocalDoc) {
-            return `当前可用信息主要是文档入口链接（${urlKindLabel}）。请先匹配用户问题对应的目标 URL，抓取官网文档后再合成答案；禁止仅复述映射表或臆造 API/错误码细节。${tail}`;
+            return `Available information is mainly documentation-entry links (${urlKindLabel}). First map user question to target URL(s), fetch official docs, then synthesize the answer. Do not merely repeat URL mappings or invent API/error-code details. ${tail}`;
         }
         if (hasUrlMapping && hasLocalDoc) {
             if (hasBestPractice) {
-                return `优先基于已命中的 best-practice 与本地片段直接作答；URL 映射仅作补充参考，不要再抓官网做二次求证。${tail}`;
+                return `Prioritize direct answering from matched best-practice and local fragments; use URL mapping only as supplemental reference. Do not fetch official docs again for secondary verification by default. ${tail}`;
             }
-            return `本地文档片段可直接用于作答；若本地片段未覆盖关键细节，再从 URL 映射中提取目标 URL 抓取官网文档补齐。${tail}`;
+            return `Local documentation fragments are sufficient for direct answering. Only if key details are still missing, extract target URL from URL mapping and fetch official docs to fill gaps. ${tail}`;
         }
-        return `请仅基于已返回 fragments 合成答案；不要并行 web_search 或额外抓取官网文档。${tail}`;
+        return `Synthesize the answer strictly from returned fragments; do not run parallel web_search or extra official-doc fetching. ${tail}`;
     }
     if (status === 'low_confidence') {
         if (hasUrlMapping) {
             if (hasBestPractice) {
-                return `优先基于 best-practice 与本地片段给出可执行结论。${tail}`;
+                return `Prioritize actionable conclusions from best-practice and local fragments. ${tail}`;
             }
-            return `请先从 URL 映射里提取目标 URL 并抓取官网文档补齐关键信息，再给出答案。${tail}`;
+            return `First extract target URL(s) from URL mapping and fetch official docs for key details, then answer. ${tail}`;
         }
-        return `请基于已有 fragments 给出最可执行答案；可引导用户补充组件名/API 名/错误码后重新检索。不要默认并行 web_search。${tail}`;
+        return `Provide the most actionable answer from existing fragments; you may guide user to provide component/API/error-code specifics for another retrieval round. Do not run parallel web_search by default. ${tail}`;
     }
-    return `知识库未命中有效片段。请向用户说明并确认 product/framework 是否准确；若仍无 platform 信息且问题依赖具体客户端，应先 \`present_framework_choice\`。${tail}`;
+    return `No effective fragment was retrieved from the knowledge base. Ask user to verify product/framework; if platform is still missing and the question depends on client-specific implementation, call \`present_framework_choice\` first. ${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;
+}