@tencent-rtc/mcp 1.6.8 → 1.7.1

package/knowledge/search/search-message.js

@@ -0,0 +1,88 @@
+import { hasBestPracticeFragment, partitionFragments, } from './search-core.js';
+export function buildAnswerContract(status, confidence, retrievalMode, opts) {
+    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 a footnote to avoid confusion with directly matched fragments.'
+        : '';
+    const modeRule = retrievalMode === 'narrative'
+        ? (opts?.fullDocumentRequired
+            ? '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: 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 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 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 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,
+        aggregatedRule,
+    ].filter(Boolean).join(' ');
+}
+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 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.';
+    }
+    if (status === 'success' && retrievalMode === 'narrative' && opts?.hasDocuments) {
+        if (opts?.fullDocumentRequired) {
+            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 `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' && 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}`;
+    }
+    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 `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 `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 `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 `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 `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 `Prioritize actionable conclusions from best-practice and local fragments. ${tail}`;
+            }
+            return `First extract target URL(s) from URL mapping and fetch official docs for key details, then answer. ${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 `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/search-pass.js

@@ -0,0 +1,428 @@
+import { attachPoolContent } from '../content-loader.js';
+import { buildReferences } from '../doc-url-resolver.js';
+import { rankSubsetWithIndex } from '../bm25.js';
+import { getProductsBM25Index } from '../bm25-cache.js';
+import { filterPool } from './filter-pool.js';
+import { runExactLookup } from './exact-lookup.js';
+import { applyRankMultipliers, computeApiNameCoverage, computeMissingApiTokens, isUrlMappingSource, postProcess, } from './search-core.js';
+function isBestPracticeSource(source) {
+    return /\/best-practice\//i.test(source);
+}
+function normalizeTopicText(text) {
+    return text
+        .toLowerCase()
+        .replace(/[（()）【】\[\]{}《》"""'`]/g, '')
+        .replace(/[\s/\\,，。:：;；|·\-—_]+/g, '');
+}
+const TOPIC_EN_NOISE_WORDS = new Set([
+    'a', 'an', 'the', 'and', 'or', 'to', 'of', 'in', 'on', 'for', 'with',
+    'is', 'are', 'was', 'were', 'be', 'how', 'what', 'why', 'when', 'where',
+    'chat', 'message', 'messages', 'api', 'sdk', 'doc', 'docs',
+]);
+function extractTopicTokens(text) {
+    const tokens = new Set();
+    for (const match of text.matchAll(/\b\d{2,}\b/g)) {
+        tokens.add(match[0]);
+    }
+    for (const match of text.matchAll(/\b[a-z][a-z0-9_]{1,}\b/gi)) {
+        const token = match[0].toLowerCase();
+        if (TOPIC_EN_NOISE_WORDS.has(token))
+            continue;
+        tokens.add(token);
+    }
+    const cjkSegments = text.match(/[\u4e00-\u9fff]+/g) ?? [];
+    for (const seg of cjkSegments) {
+        if (seg.length >= 2)
+            tokens.add(seg);
+        for (let i = 0; i < seg.length - 1; i += 1) {
+            tokens.add(seg.slice(i, i + 2));
+        }
+    }
+    return [...tokens].filter((token) => token.length >= 2);
+}
+function countTopicTokenHits(tokens, normalizedTarget) {
+    if (!tokens.length || !normalizedTarget)
+        return 0;
+    let hits = 0;
+    for (const token of tokens) {
+        const normalizedToken = normalizeTopicText(token);
+        if (normalizedToken.length < 2)
+            continue;
+        if (normalizedTarget.includes(normalizedToken))
+            hits += 1;
+    }
+    return hits;
+}
+const TOPIC_GENERIC_GUARD_WORDS = new Set([
+    ...TOPIC_EN_NOISE_WORDS,
+    'web', 'ios', 'android', 'flutter', 'react', 'vue',
+    '直播', '消息', '文档', '教程', '指南', '重要', '保证', '丢失', '聊天',
+]);
+/**
+ * 提取更强区分度的话题锚点（通用策略，不针对任何单 case）：
+ * - 英文：长度 >= 4 或包含数字（如 AVChatRoom / trtc123）
+ * - 中文：连续 3 字以上片段（避免 2-gram 过宽）
+ */
+function extractStrongTopicAnchors(text) {
+    const anchors = new Set();
+    for (const match of text.matchAll(/\b[a-z][a-z0-9_]{3,}\b/gi)) {
+        const token = match[0].toLowerCase();
+        if (TOPIC_GENERIC_GUARD_WORDS.has(token))
+            continue;
+        anchors.add(token);
+    }
+    for (const segment of text.match(/[\u4e00-\u9fff]{3,}/g) ?? []) {
+        if (TOPIC_GENERIC_GUARD_WORDS.has(segment))
+            continue;
+        anchors.add(segment);
+    }
+    return [...anchors];
+}
+function extractPrimaryHeading(content) {
+    const heading = content.split('\n').find((line) => /^#\s+/.test(line.trim()));
+    return heading ? heading.replace(/^#\s+/, '').trim() : '';
+}
+function buildBestPracticeTopicText(chunk) {
+    if (!chunk)
+        return '';
+    return normalizeTopicText([
+        chunk.title,
+        ...(chunk.key_phrases ?? []),
+        extractPrimaryHeading(chunk.content),
+    ].filter(Boolean).join(' '));
+}
+const DIAGNOSIS_INTENT_RE = /丢消息|消息丢失|message\s*loss|消息可靠性|message\s*reliability|超时|timeout|失败|fail(?:ed|ure)?|排查|诊断|troubleshoot(?:ing)?/i;
+const DIAGNOSIS_DOC_RE = /diagnosis|troubleshoot|排查|诊断|丢失|message\s*loss|reliability|可靠性|timeout|fail(?:ed|ure)?/i;
+const TUTORIAL_DOC_RE = /audio[\s-]*message|voice[\s-]*message|语音消息|录音|recorder|create[a-z]+message|sendmessage|standard\s*(approach|usage)|标准用法|如何发送|how\s*to\s*send/i;
+function isDiagnosisIntent(prompt) {
+    return DIAGNOSIS_INTENT_RE.test(prompt);
+}
+function buildChunkIntentText(chunk) {
+    return [
+        chunk.title,
+        ...(chunk.key_phrases ?? []),
+        extractPrimaryHeading(chunk.content),
+    ].filter(Boolean).join(' ');
+}
+function isDiagnosisStyleChunk(chunk) {
+    return DIAGNOSIS_DOC_RE.test(buildChunkIntentText(chunk));
+}
+function isTutorialStyleChunk(chunk) {
+    return TUTORIAL_DOC_RE.test(buildChunkIntentText(chunk));
+}
+/**
+ * 通用门控：诊断/排查类问法下，抑制教程型文档误抢首位。
+ * 仅对“教程型且非诊断型”文档施加轻度降权，不做任何单文档特化。
+ */
+function applyDiagnosisIntentGuard(ranked, chunksById, prompt) {
+    if (!isDiagnosisIntent(prompt) || ranked.length < 2)
+        return ranked;
+    const topChunk = chunksById.get(ranked[0].id);
+    const topIsTutorial = topChunk ? isTutorialStyleChunk(topChunk) && !isDiagnosisStyleChunk(topChunk) : false;
+    const penalty = topIsTutorial ? 90 : 60;
+    let adjusted = false;
+    const next = ranked.map((item) => {
+        const chunk = chunksById.get(item.id);
+        if (!chunk)
+            return item;
+        if (!isTutorialStyleChunk(chunk) || isDiagnosisStyleChunk(chunk))
+            return item;
+        adjusted = true;
+        return { ...item, score: item.score - penalty };
+    });
+    return adjusted ? next.sort((a, b) => b.score - a.score) : ranked;
+}
+/**
+ * A3: 同 prompt 下 best-practice 优先（仅在分数接近时触发，避免召回退化）
+ * 触发条件：
+ * - 当前 Top1 不是 best-practice
+ * - 存在 best-practice 候选
+ * - 该候选分数与 Top1 差距不超过 18%
+ */
+function prioritizeBestPracticeWhenCompetitive(ranked, chunksById, prompt) {
+    if (ranked.length < 2)
+        return ranked;
+    const top = ranked[0];
+    const topChunk = chunksById.get(top.id);
+    if (!topChunk || isBestPracticeSource(topChunk.source) || top.score <= 0) {
+        return ranked;
+    }
+    // 收集所有 best-practice 候选，取分数最高者，避免"首个 best-practice 不一定最相关"的偏置。
+    let bestPracticeIdx = -1;
+    let bestPracticeScore = -Infinity;
+    for (let i = 1; i < ranked.length; i += 1) {
+        const chunk = chunksById.get(ranked[i].id);
+        if (!chunk)
+            continue;
+        if (!isBestPracticeSource(chunk.source))
+            continue;
+        if (ranked[i].score > bestPracticeScore) {
+            bestPracticeScore = ranked[i].score;
+            bestPracticeIdx = i;
+        }
+    }
+    if (bestPracticeIdx < 0)
+        return ranked;
+    const candidate = ranked[bestPracticeIdx];
+    const gapRatio = (top.score - candidate.score) / top.score;
+    // 常规场景：仅在分数接近时提升（避免召回退化）
+    const normalCompetitive = gapRatio <= 0.35;
+    // URL 映射/FAQ 抢首位场景：只要 best-practice 达到基础相关阈值，也应优先返回可执行内容
+    // 这样可避免"只有 URL 映射行或 FAQ 简答，没有本地内容"的体验退化。
+    // chat/urls 的 URL 行：需额外校验 BP 和 URL 行是否同一话题，
+    // 避免"问地理位置消息，URL 行是地理位置，但 BP 是语音消息"的跨话题 shadow。
+    const topIsUrlMapping = Boolean(isUrlMappingSource(topChunk.source));
+    const topIsChatUrlRow = topIsUrlMapping && topChunk.source.includes('knowledge/chat/urls/');
+    const topIsFaq = topChunk.source.includes('/faq/');
+    // chat/urls 话题一致性：收紧为“高精度 + 多信号”
+    // 1) prompt 中数字/错误码（高区分信号）
+    // 2) prompt 切词与 BP 主题 token 命中
+    // 3) URL 行标题切词与 BP 主题 token 命中（跨语言兜底）
+    // 4) 通用强锚点（长 token / CJK>=3）需与 BP 主题有交集（若 prompt 存在强锚点）
+    let chatUrlRowTopicMatch = true;
+    let chatUrlTopicSignalCount = 0;
+    if (topIsChatUrlRow) {
+        const bpChunk = chunksById.get(candidate.id);
+        const bpTopicText = buildBestPracticeTopicText(bpChunk);
+        const promptDigits = prompt.match(/\b\d{2,}\b/g) ?? [];
+        const digitMatch = promptDigits.some((d) => bpTopicText.includes(d));
+        const promptTokens = extractTopicTokens(prompt);
+        const promptTokenHitCount = countTopicTokenHits(promptTokens, bpTopicText);
+        const promptTokenMatch = promptTokenHitCount >= 1;
+        const urlTopicRaw = (topChunk.title ?? '').replace(/[（(].*$/, '').trim();
+        const urlTopicTokens = extractTopicTokens(urlTopicRaw);
+        const urlTitleHitCount = countTopicTokenHits(urlTopicTokens, bpTopicText);
+        const urlTitleMatch = urlTitleHitCount >= 1;
+        const strongAnchors = extractStrongTopicAnchors(prompt);
+        const strongAnchorHitCount = countTopicTokenHits(strongAnchors, bpTopicText);
+        const strongAnchorMatch = strongAnchors.length === 0 || strongAnchorHitCount >= 1;
+        chatUrlTopicSignalCount = Number(digitMatch) + Number(promptTokenMatch) + Number(urlTitleMatch);
+        const hasHighPrecisionSignal = digitMatch || urlTitleMatch;
+        chatUrlRowTopicMatch = hasHighPrecisionSignal
+            && chatUrlTopicSignalCount >= 2
+            && strongAnchorMatch;
+    }
+    const bestPracticeStrongEnough = candidate.score >= Math.max(12, top.score * 0.05);
+    const urlRatioThreshold = topIsChatUrlRow ? 0.045 : 0.05;
+    const urlAbsoluteThreshold = topIsChatUrlRow ? 20 : 16;
+    const urlStrongEnough = candidate.score >= Math.max(urlAbsoluteThreshold, top.score * urlRatioThreshold);
+    const urlMappingShadowing = topIsUrlMapping
+        && urlStrongEnough
+        && chatUrlRowTopicMatch;
+    const faqShadowing = topIsFaq && bestPracticeStrongEnough;
+    // Feature/API 文档抢首位场景：top1 是功能文档（非 integration、非 BP），
+    // BP 的精准实践应优先于功能文档的泛匹配。
+    // 条件更严格：BP 分数需达到 top 的 40%（避免完全不相关的 BP 被误提）。
+    const topIsFeatureDoc = !topIsUrlMapping && !topIsFaq
+        && !isBestPracticeSource(topChunk.source)
+        && !isIntegrationSource(topChunk.source);
+    const featureDocShadowing = topIsFeatureDoc && candidate.score >= top.score * 0.4;
+    if (!normalCompetitive && !urlMappingShadowing && !faqShadowing && !featureDocShadowing)
+        return ranked;
+    const next = [...ranked];
+    next[bestPracticeIdx] = { ...candidate, score: top.score + 2 };
+    return next.sort((a, b) => b.score - a.score);
+}
+/**
+ * P0-R1/P0-R2：best-practice 单 chunk 直通。
+ * 在高置信且无强竞争时，直接锁定 preferredSource + fullDocumentMode。
+ * 当 promote 已发生（faqShadowing 触发后 best-practice 排到首位），
+ * 即使分数未达 80 也信任 promote 结果执行收敛。
+ */
+function pickDominantBestPracticeSource(ranked, chunksById) {
+    const top = ranked[0];
+    if (!top || top.score <= 0)
+        return { fullDocumentMode: false };
+    const topChunk = chunksById.get(top.id);
+    if (!topChunk || !isBestPracticeSource(topChunk.source)) {
+        return { fullDocumentMode: false };
+    }
+    const source = topChunk.source;
+    const topWindow = ranked.slice(0, 12);
+    // URL 映射行和 FAQ 语料是导航指针/概览而非内容竞争者：
+    // 若计入两者竞争，1.2 倍 dominance 门槛在 best-practice 被命中时永远无法达成。
+    const isCrossCompetitor = (item) => {
+        const chunk = chunksById.get(item.id);
+        if (!chunk || chunk.source === source)
+            return false;
+        if (isUrlMappingSource(chunk.source))
+            return false;
+        if (chunk.source.includes('/faq/'))
+            return false;
+        return true;
+    };
+    const secondCrossSource = ranked.find((item) => isCrossCompetitor(item));
+    const secondCrossScore = secondCrossSource?.score ?? 0;
+    const strongCrossSourceCount = topWindow
+        .filter((item) => isCrossCompetitor(item) && item.score >= top.score * 0.92)
+        .length;
+    const sourceSections = [...chunksById.values()].filter((chunk) => chunk.source === source);
+    const sourceTotalChars = sourceSections.reduce((sum, chunk) => sum + chunk.content.length, 0);
+    const isPromotedResult = top.score >= 20 && ranked.length >= 2 && (top.score - ranked[1].score) >= 0.05;
+    const scoreStrongEnough = top.score >= 80 || isPromotedResult;
+    const dominanceStrongEnough = secondCrossScore === 0 || (top.score / secondCrossScore) >= 1.2 || isPromotedResult;
+    const crossSourceNotCompeting = strongCrossSourceCount === 0 || isPromotedResult;
+    const withinLengthBudget = sourceTotalChars <= 7000;
+    if (scoreStrongEnough && dominanceStrongEnough && crossSourceNotCompeting && withinLengthBudget) {
+        return {
+            preferredSource: source,
+            fullDocumentMode: true,
+        };
+    }
+    return { fullDocumentMode: false };
+}
+function isIntegrationSource(source) {
+    return /\/integration\.md$/i.test(source)
+        || /\/preset\/.+integration/i.test(source);
+}
+/**
+ * 覆盖度竞争：在 A3 之前执行。
+ * 当 integration 的多个 section 被查询广泛命中时，选择 integration 完整文档；
+ * 否则返回 null，交由 A3 + BP 收敛处理。
+ *
+ * 规则：
+ * - 按 source 聚合 integration 的 section 命中数，选命中数最多的 source
+ * - ≥3 个 section 命中 + integration top 分数 ≥ BP top × 0.6 → 选 integration
+ * - BP 分数远高于 integration（>1.2×）→ 直接返回 null
+ * - 否则 → 返回 null
+ */
+function resolveContentPriority(ranked, chunksById) {
+    if (ranked.length < 2)
+        return null;
+    // 找 BP 最高分（在 top-30 范围内）
+    let bpTopScore = -1;
+    for (let i = 0; i < Math.min(ranked.length, 30); i++) {
+        const chunk = chunksById.get(ranked[i].id);
+        if (!chunk || !isBestPracticeSource(chunk.source))
+            continue;
+        if (ranked[i].score > bpTopScore) {
+            bpTopScore = ranked[i].score;
+        }
+    }
+    // 按 source 聚合 integration 的 section 命中（在全部 ranked 范围内，但有 minScore 门槛）
+    const minScore = bpTopScore > 0 ? Math.max(bpTopScore * 0.3, 5) : 5;
+    const intSourceStats = new Map();
+    for (const item of ranked) {
+        const chunk = chunksById.get(item.id);
+        if (!chunk || !isIntegrationSource(chunk.source))
+            continue;
+        if (item.score < minScore)
+            continue;
+        const prev = intSourceStats.get(chunk.source);
+        if (!prev) {
+            intSourceStats.set(chunk.source, { hitCount: 1, topScore: item.score });
+        }
+        else {
+            intSourceStats.set(chunk.source, {
+                hitCount: prev.hitCount + 1,
+                topScore: Math.max(prev.topScore, item.score),
+            });
+        }
+    }
+    if (intSourceStats.size === 0)
+        return null;
+    // 选命中数最多的 integration source（同命中数则选分数最高的）
+    let bestIntSource = '';
+    let bestHitCount = 0;
+    let bestIntTopScore = 0;
+    for (const [source, stats] of intSourceStats) {
+        if (stats.hitCount > bestHitCount
+            || (stats.hitCount === bestHitCount && stats.topScore > bestIntTopScore)) {
+            bestIntSource = source;
+            bestHitCount = stats.hitCount;
+            bestIntTopScore = stats.topScore;
+        }
+    }
+    // 无 BP 候选 → 选 integration（如果有足够 section 命中）
+    if (bpTopScore < 0) {
+        return bestHitCount >= 2
+            ? { preferredSource: bestIntSource, fullDocumentMode: true }
+            : null;
+    }
+    // BP 分数远高于 integration → 不走 integration 路径
+    if (bpTopScore > bestIntTopScore * 1.2)
+        return null;
+    // 覆盖度判定
+    const BREADTH_THRESHOLD = 3;
+    if (bestHitCount >= BREADTH_THRESHOLD && bestIntTopScore >= bpTopScore * 0.6) {
+        return { preferredSource: bestIntSource, fullDocumentMode: true };
+    }
+    return null;
+}
+export function runSearchPass(params) {
+    const { allChunks, passNorm, retrievalMode, queryApiTokens, opts, } = params;
+    const effectivePassNorm = retrievalMode === 'discovery'
+        ? { ...passNorm, types: undefined }
+        : passNorm;
+    let pool = filterPool(allChunks, effectivePassNorm);
+    // types 误传自愈：首轮保留，二次扩检也同样保留该能力
+    if (pool.length === 0 && effectivePassNorm.types?.length) {
+        pool = filterPool(allChunks, { ...effectivePassNorm, types: undefined });
+    }
+    const { boosts, exactHits, urlRowHitChunkIds } = runExactLookup(effectivePassNorm.prompt, pool, effectivePassNorm);
+    // 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;
+            }
+        }
+    }
+    // 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;
+            }
+        }
+    }
+    const productIndex = getProductsBM25Index(allChunks, passNorm.product);
+    const poolWithContent = attachPoolContent(pool);
+    const chunksById = new Map(poolWithContent.map((chunk) => [chunk.id, chunk]));
+    const ranked = rankSubsetWithIndex(effectivePassNorm.prompt, pool.map((chunk) => chunk.id), productIndex, boosts);
+    const rankedWithMultipliers = applyRankMultipliers(ranked, chunksById, {
+        product: passNorm.product,
+        framework: passNorm.framework,
+        frameworks: passNorm.frameworks,
+    });
+    const rankedAfterIntentGuard = applyDiagnosisIntentGuard(rankedWithMultipliers, chunksById, passNorm.prompt);
+    // 覆盖度竞争先于 A3 执行
+    const integrationPriority = resolveContentPriority(rankedAfterIntentGuard, chunksById);
+    let dominantBestPractice;
+    let rankedAfterBestPractice;
+    if (integrationPriority) {
+        // integration 胜出 → 跳过 A3，直接走完整文档路径
+        rankedAfterBestPractice = rankedAfterIntentGuard;
+        dominantBestPractice = integrationPriority;
+    }
+    else {
+        // integration 未胜出 → A3 提升 BP → BP 收敛判定
+        rankedAfterBestPractice = prioritizeBestPracticeWhenCompetitive(rankedAfterIntentGuard, chunksById, passNorm.prompt);
+        dominantBestPractice = pickDominantBestPracticeSource(rankedAfterBestPractice, chunksById);
+    }
+    const pinnedUrlRowChunkIds = new Set(urlRowHitChunkIds);
+    const fragments = postProcess(rankedAfterBestPractice, chunksById, passNorm.limit, {
+        pinnedUrlRowChunkIds,
+        preferredSource: dominantBestPractice.preferredSource,
+        fullDocumentMode: dominantBestPractice.fullDocumentMode,
+    });
+    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,
+        poolWithContent,
+        rankedWithMultipliers: rankedAfterBestPractice,
+        fragments,
+        exactHits,
+        urlMappingSources,
+        references,
+        apiNameCoverage,
+        missingApiTokens,
+        urlMapRelaxed: pinnedUrlRowChunkIds.size > 0,
+        urlMapExactHitCount: pinnedUrlRowChunkIds.size,
+        preferredSource: dominantBestPractice.preferredSource,
+        fullDocumentMode: dominantBestPractice.fullDocumentMode,
+    };
+}

package/knowledge/search/search-types.js

@@ -0,0 +1 @@
+export {};

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;
+}