@tencentcloud/sdk-mcp 1.7.7 → 1.7.9-beta.1

package/knowledge/search/search-pass.js

@@ -1,103 +1,41 @@
-import { attachPoolContent } from '../content-loader.js';
+import { attachChunkContent, attachPoolContent } from '../content-loader.js';
 import { buildReferences } from '../doc-url-resolver.js';
 import { rankSubsetWithIndex, tokenize } from '../bm25.js';
 import { getProductsBM25Index } from '../bm25-cache.js';
-import { filterPool } from './filter-pool.js';
+import { filterPool, filterPoolHard } from './filter-pool.js';
 import { runExactLookup } from './exact-lookup.js';
 import { computeGenericAnchorBoosts } from './generic-rerank.js';
+import { embedQuery, withQueryInstruction } from '../embedding/embed-model.js';
+import { queryVectors } from '../embedding/vector-index.js';
 import { applyRankMultipliers, computeApiNameCoverage, computeMissingApiTokens, isUrlMappingSource, postProcess, } from './search-core.js';
+import { resolveRankProfile } from './rank-profile.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 decidePromptLockPolicy(prompt) {
+    const integrationIntent = /集成|接入|指南|步骤|教程|快速开始|初始化|安装|跑通|demo|sample|example/i.test(prompt);
+    const productIntent = /配置|限制|上限|规则|权限|计费|套餐|价格|资费|多端登录|错误码|命名|长度|开通|购买/i.test(prompt);
+    if (integrationIntent && !productIntent) {
+        return {
+            enableContentPriority: true,
+            enableFullDocumentLock: true,
+        };
+    }
+    return {
+        enableContentPriority: false,
+        enableFullDocumentLock: false,
+    };
+}
 function buildChunkIntentText(chunk) {
     return [
         chunk.title,
@@ -131,16 +69,21 @@ function applyDiagnosisIntentGuard(ranked, chunksById, prompt) {
         adjusted = true;
         return { ...item, score: item.score - penalty };
     });
-    return adjusted ? next.sort((a, b) => b.score - a.score) : ranked;
+    return adjusted ? stableSortRanked(next) : ranked;
 }
 /**
- * A3: 同 prompt 下 best-practice 优先（仅在分数接近时触发，避免召回退化）
- * 触发条件：
+ * A3: best-practice 后处理轻校准（不再做“主通道抢首位”）
+ *
+ * 目标：
+ * - 保留 BP 的可见性优势（在接近相关时可轻微上浮）
+ * - 避免强行顶到 Top1 导致“策略叠策略”的排序失真
+ *
+ * 触发条件（更保守）：
  * - 当前 Top1 不是 best-practice
- * - 存在 best-practice 候选
- * - 该候选分数与 Top1 差距不超过 18%
+ * - Top20 内存在 BP 候选
+ * - 候选与 Top1 分差不大（gap <= 20%）且具备基础强度
  */
-function prioritizeBestPracticeWhenCompetitive(ranked, chunksById, prompt) {
+function prioritizeBestPracticeWhenCompetitive(ranked, chunksById, _prompt) {
     if (ranked.length < 2)
         return ranked;
     const top = ranked[0];
@@ -148,14 +91,12 @@ function prioritizeBestPracticeWhenCompetitive(ranked, chunksById, prompt) {
     if (!topChunk || isBestPracticeSource(topChunk.source) || top.score <= 0) {
         return ranked;
     }
-    // 收集所有 best-practice 候选，取分数最高者，避免"首个 best-practice 不一定最相关"的偏置。
+    const searchWindow = Math.min(ranked.length, 20);
     let bestPracticeIdx = -1;
     let bestPracticeScore = -Infinity;
-    for (let i = 1; i < ranked.length; i += 1) {
+    for (let i = 1; i < searchWindow; i += 1) {
         const chunk = chunksById.get(ranked[i].id);
-        if (!chunk)
-            continue;
-        if (!isBestPracticeSource(chunk.source))
+        if (!chunk || !isBestPracticeSource(chunk.source))
             continue;
         if (ranked[i].score > bestPracticeScore) {
             bestPracticeScore = ranked[i].score;
@@ -166,71 +107,25 @@ function prioritizeBestPracticeWhenCompetitive(ranked, chunksById, prompt) {
         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)
+    const competitiveEnough = gapRatio <= 0.2;
+    const strengthEnough = candidate.score >= Math.max(14, top.score * 0.3);
+    if (!competitiveEnough || !strengthEnough)
+        return ranked;
+    // 轻量校准：最多只允许轻微越过 top，避免“强提权抢首位”。
+    const lift = Math.max(top.score * 0.03, 1.2);
+    const boostedScore = Math.min(top.score * 1.01, candidate.score + lift);
+    if (boostedScore <= candidate.score)
         return ranked;
     const next = [...ranked];
-    next[bestPracticeIdx] = { ...candidate, score: top.score + 2 };
-    return next.sort((a, b) => b.score - a.score);
+    next[bestPracticeIdx] = { ...candidate, score: boostedScore };
+    return stableSortRanked(next);
 }
 /**
- * P0-R1/P0-R2：best-practice 单 chunk 直通。
- * 在高置信且无强竞争时，直接锁定 preferredSource + fullDocumentMode。
- * 当 promote 已发生（faqShadowing 触发后 best-practice 排到首位），
- * 即使分数未达 80 也信任 promote 结果执行收敛。
+ * P0-R1/P0-R2：best-practice 单 chunk 收敛（高置信门控版）。
+ * 仅当 BP 在跨来源竞争中具备明显优势时，才锁定 preferredSource + fullDocumentMode。
+ * 不再因为轻量校准后的微小领先而触发整文锁定。
  */
-function pickDominantBestPracticeSource(ranked, chunksById) {
+function pickDominantBestPracticeSource(ranked, chunksById, fullDocumentMaxChars) {
     const top = ranked[0];
     if (!top || top.score <= 0)
         return { fullDocumentMode: false };
@@ -259,11 +154,12 @@ function pickDominantBestPracticeSource(ranked, chunksById) {
         .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;
+    const scoreStrongEnough = top.score >= 85;
+    const dominanceStrongEnough = secondCrossScore === 0
+        ? top.score >= 65
+        : (top.score / secondCrossScore) >= 1.25;
+    const crossSourceNotCompeting = strongCrossSourceCount === 0;
+    const withinLengthBudget = sourceTotalChars <= fullDocumentMaxChars;
     if (scoreStrongEnough && dominanceStrongEnough && crossSourceNotCompeting && withinLengthBudget) {
         return {
             preferredSource: source,
@@ -276,6 +172,51 @@ function isIntegrationSource(source) {
     return /\/integration\.md$/i.test(source)
         || /\/preset\/.+integration/i.test(source);
 }
+function isNavigationIntent(prompt) {
+    return /文档|链接|地址|url|网址|入口|在哪看|在哪里看|官网|文档地址|sdk文档/i.test(prompt);
+}
+/**
+ * 通用语义仲裁（非 integration 特化）：
+ * 当 top1 落在 urls 映射行（导航型来源），且向量 top1 指向内容型文档时，
+ * 对“非导航意图”的 query 优先选择内容文档来源。
+ *
+ * 目的：避免 BM25 在 urls 索引行上的词面优势压制真实内容页。
+ */
+function resolveSemanticSourcePriorityByVector(params) {
+    const { ranked, chunksById, vectorTopId, prompt, fullDocumentMaxChars, } = params;
+    if (!vectorTopId || ranked.length === 0)
+        return null;
+    if (isNavigationIntent(prompt))
+        return null;
+    const top = ranked[0];
+    const topChunk = chunksById.get(top.id);
+    const vectorTopChunk = chunksById.get(vectorTopId);
+    if (!topChunk || !vectorTopChunk)
+        return null;
+    // 仅在“导航来源(top1) vs 内容来源(vectorTop)”冲突时触发
+    if (!isUrlMappingSource(topChunk.source))
+        return null;
+    if (isUrlMappingSource(vectorTopChunk.source))
+        return null;
+    if (topChunk.source === vectorTopChunk.source)
+        return null;
+    const vectorTopRanked = ranked.find((item) => item.id === vectorTopId);
+    if (!vectorTopRanked)
+        return null;
+    // 置信门槛：vector top 不能离 top1 太远，避免误切
+    const scoreGapOk = vectorTopRanked.score >= top.score * 0.45;
+    if (!scoreGapOk)
+        return null;
+    const sourceTotalChars = [...chunksById.values()]
+        .filter((chunk) => chunk.source === vectorTopChunk.source)
+        .reduce((sum, chunk) => sum + chunk.content.length, 0);
+    if (sourceTotalChars > fullDocumentMaxChars)
+        return null;
+    return {
+        preferredSource: vectorTopChunk.source,
+        fullDocumentMode: true,
+    };
+}
 /**
  * 覆盖度竞争：在 A3 之前执行。
  * 当 integration 的多个 section 被查询广泛命中时，选择 integration 完整文档；
@@ -287,16 +228,16 @@ function isIntegrationSource(source) {
  * - BP 分数远高于 integration（>1.2×）→ 直接返回 null
  * - 否则 → 返回 null
  */
-function resolveContentPriority(ranked, chunksById) {
+function resolveContentPriority(ranked, chunksById, fullDocumentMaxChars) {
     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))
+        if (!chunk)
             continue;
-        if (ranked[i].score > bpTopScore) {
+        if (isBestPracticeSource(chunk.source) && ranked[i].score > bpTopScore) {
             bpTopScore = ranked[i].score;
         }
     }
@@ -334,9 +275,13 @@ function resolveContentPriority(ranked, chunksById) {
             bestIntTopScore = stats.topScore;
         }
     }
+    const integrationSourceTotalChars = [...chunksById.values()]
+        .filter((chunk) => chunk.source === bestIntSource)
+        .reduce((sum, chunk) => sum + chunk.content.length, 0);
+    const withinLengthBudget = integrationSourceTotalChars <= fullDocumentMaxChars;
     // 无 BP 候选 → 选 integration（如果有足够 section 命中）
     if (bpTopScore < 0) {
-        return bestHitCount >= 2
+        return bestHitCount >= 2 && withinLengthBudget
             ? { preferredSource: bestIntSource, fullDocumentMode: true }
             : null;
     }
@@ -345,21 +290,248 @@ function resolveContentPriority(ranked, chunksById) {
         return null;
     // 覆盖度判定
     const BREADTH_THRESHOLD = 3;
-    if (bestHitCount >= BREADTH_THRESHOLD && bestIntTopScore >= bpTopScore * 0.6) {
+    if (bestHitCount >= BREADTH_THRESHOLD && bestIntTopScore >= bpTopScore * 0.6 && withinLengthBudget) {
         return { preferredSource: bestIntSource, fullDocumentMode: true };
     }
     return null;
 }
-export function runSearchPass(params) {
+const DEFAULT_VECTOR_TOP_K = 30;
+const DEFAULT_RRF_K = 60;
+const DEFAULT_RERANK_TOP_K = 20;
+function readEnvNumber(name, fallback) {
+    const raw = process.env[name];
+    if (raw === undefined || raw === '')
+        return fallback;
+    const val = Number(raw);
+    return Number.isFinite(val) ? val : fallback;
+}
+function stableSortRanked(items) {
+    return [...items].sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        return a.id.localeCompare(b.id);
+    });
+}
+function inferIotFeatureDomainFromPrompt(prompt) {
+    if (!prompt)
+        return undefined;
+    if (/安防摄像头|云台|\bPTZ\b|语音对讲|监控|回放|录像|录制|截图/i.test(prompt)) {
+        return 'security-camera';
+    }
+    if (/儿童手表/i.test(prompt))
+        return 'kids-watch';
+    if (/录音卡|语音卡/i.test(prompt))
+        return 'voice-recorder';
+    if (/智能视觉|视觉服务/i.test(prompt))
+        return 'smart-vision';
+    if (/设备端|linux|rtos|模组|芯片/i.test(prompt))
+        return 'device';
+    if (/客户端\s*api|client\s*api|\bTXIoT[A-Za-z0-9_]+\b/i.test(prompt))
+        return 'client_api';
+    if (/app\s*demo|示例工程|demo/i.test(prompt))
+        return 'app_demo';
+    if (/应用端接入|app接入|app\s*集成/i.test(prompt))
+        return 'app_integration';
+    return undefined;
+}
+/**
+ * IoT 强 feature 意图 → source 路径关键词映射。
+ * 中文意图词（云台/语音对讲）与英文文件名（ptz-control/voice-intercom）无直接词面关系，
+ * 需显式映射才能在排序层精准置顶对应 feature 文档，避免被短文本泛文档的 BM25 优势压制。
+ *
+ * 注意：仅收录「一 feature 一精准文件」的映射。像 monitor-playback 这类分布在
+ * 多端侧（app/device/security-camera）的 feature 不在此列，避免无差别 source boost
+ * 把 device 侧文档抬高、压制 app 侧（见 regression case 22）。
+ */
+const IOT_FEATURE_INTENT_MAP = [
+    { re: /云台|\bPTZ\b/i, keyword: 'ptz-control' },
+    { re: /语音对讲|对讲|intercom/i, keyword: 'voice-intercom' },
+];
+function inferIotFeatureSourceKeyword(prompt) {
+    if (!prompt)
+        return undefined;
+    for (const { re, keyword } of IOT_FEATURE_INTENT_MAP) {
+        if (re.test(prompt))
+            return keyword;
+    }
+    return undefined;
+}
+function inferPreferredIotFeatureDomain(ranked, chunksById, prompt) {
+    const byPrompt = inferIotFeatureDomainFromPrompt(prompt ?? '');
+    if (byPrompt)
+        return byPrompt;
+    const scoreByDomain = new Map();
+    const sampleWindow = Math.min(ranked.length, 80);
+    for (let i = 0; i < sampleWindow; i += 1) {
+        const item = ranked[i];
+        const chunk = chunksById.get(item.id);
+        if (!chunk || chunk.product !== 'iot' || !chunk.feature_domain)
+            continue;
+        const domain = chunk.feature_domain;
+        scoreByDomain.set(domain, (scoreByDomain.get(domain) ?? 0) + Math.max(item.score, 0));
+    }
+    let preferred;
+    let best = -1;
+    for (const [domain, score] of scoreByDomain.entries()) {
+        if (score > best) {
+            best = score;
+            preferred = domain;
+        }
+    }
+    return preferred;
+}
+function fuseByRRF(params) {
+    const { bm25Ranked, vectorHits, rrfK, baseBeta, alpha, profile, } = params;
+    const bmWeight = profile?.bmWeight ?? 1;
+    const vecWeight = profile?.vecWeight ?? 1;
+    const alphaScale = profile?.alphaScale ?? 1;
+    if (!bm25Ranked.length && !vectorHits.length) {
+        return { ranked: [], bm25AdjustedCount: 0, vectorOnlyAddedCount: 0 };
+    }
+    const topBM25 = bm25Ranked[0]?.score ?? baseBeta;
+    const bm25ById = new Map(bm25Ranked.map((item) => [item.id, item]));
+    const bm25Rank = new Map();
+    bm25Ranked.forEach((item, idx) => bm25Rank.set(item.id, idx + 1));
+    const vecRank = new Map();
+    vectorHits.forEach((hit, idx) => vecRank.set(hit.id, idx + 1));
+    const vecMin = vectorHits.length ? Math.min(...vectorHits.map((h) => h.score)) : 0;
+    const vecMax = vectorHits.length ? Math.max(...vectorHits.map((h) => h.score)) : 1;
+    const vecRange = vecMax - vecMin || 1;
+    const vecNorm = new Map();
+    for (const hit of vectorHits) {
+        vecNorm.set(hit.id, (hit.score - vecMin) / vecRange);
+    }
+    const unionIds = new Set([
+        ...bm25Ranked.map((item) => item.id),
+        ...vectorHits.map((item) => item.id),
+    ]);
+    const rrfRaw = new Map();
+    let maxRRF = 0;
+    for (const id of unionIds) {
+        const bRank = bm25Rank.get(id);
+        const vRank = vecRank.get(id);
+        const score = (bRank ? bmWeight / (rrfK + bRank) : 0)
+            + (vRank ? vecWeight / (rrfK + vRank) : 0);
+        rrfRaw.set(id, score);
+        if (score > maxRRF)
+            maxRRF = score;
+    }
+    let bm25AdjustedCount = 0;
+    let vectorOnlyAddedCount = 0;
+    // 类别权重也影响 hybrid 融合权重，避免 rrf 权重与 sim 权重口径分裂。
+    const totalWeight = bmWeight + vecWeight || 1;
+    const simWeight = vecWeight / totalWeight; // 0..1
+    const rrfWeight = 1 - simWeight;
+    const fused = [...unionIds].map((id) => {
+        const original = bm25ById.get(id);
+        const rrfNorm = maxRRF > 0 ? (rrfRaw.get(id) ?? 0) / maxRRF : 0;
+        const simNorm = vecNorm.get(id) ?? 0;
+        const hybridNorm = rrfWeight * rrfNorm + simWeight * simNorm;
+        const effectiveAlpha = alpha * alphaScale;
+        if (original) {
+            const hasVectorSignal = vecRank.has(id);
+            if (hasVectorSignal)
+                bm25AdjustedCount += 1;
+            const boost = hasVectorSignal ? original.score * effectiveAlpha * 0.25 * hybridNorm : 0;
+            return { id, score: original.score + boost };
+        }
+        vectorOnlyAddedCount += 1;
+        return { id, score: topBM25 * baseBeta * (1 + effectiveAlpha * 0.9 * hybridNorm) };
+    });
+    return {
+        ranked: stableSortRanked(fused),
+        bm25AdjustedCount,
+        vectorOnlyAddedCount,
+    };
+}
+function resolveFusionProfile(prompt, queryApiTokens) {
+    const trimmed = prompt.trim();
+    if (queryApiTokens.length > 0) {
+        return { name: 'api_token', bmWeight: 1.3, vecWeight: 0.8, alphaScale: 0.7 };
+    }
+    // 长自然语言：字符数或分词粒度足够
+    const tokenCount = tokenize(trimmed).filter((t) => t.length >= 2).length;
+    const isLongNatural = trimmed.length >= 14 || tokenCount >= 6;
+    if (isLongNatural) {
+        return { name: 'natural_language', bmWeight: 0.85, vecWeight: 1.2, alphaScale: 1.15 };
+    }
+    const isShortKeyword = trimmed.length <= 6 && tokenCount <= 2;
+    if (isShortKeyword) {
+        return { name: 'short_keyword', bmWeight: 1.0, vecWeight: 1.0, alphaScale: 0.9 };
+    }
+    return { name: 'default', bmWeight: 1.0, vecWeight: 1.0, alphaScale: 1.0 };
+}
+function normalizeCompactText(input) {
+    return input.toLowerCase().replace(/[\s\-_]+/g, '');
+}
+function hasTitleExactMatch(prompt, title) {
+    if (!prompt || !title)
+        return false;
+    const p = normalizeCompactText(prompt);
+    const t = normalizeCompactText(title);
+    if (!p || !t)
+        return false;
+    if (t.length >= 3 && p.includes(t))
+        return true;
+    if (p.length >= 3 && t.includes(p))
+        return true;
+    return false;
+}
+function shouldTriggerLowConfidenceRerank(params) {
+    const { ranked, rankProfile } = params;
+    if (rankProfile.lowConfidenceRerankTopK <= 0 || ranked.length < 2)
+        return false;
+    const top = ranked[0]?.score ?? 0;
+    const second = ranked[1]?.score ?? 0;
+    if (top <= 0)
+        return false;
+    const ratio = second > 0 ? top / second : Number.POSITIVE_INFINITY;
+    return top <= rankProfile.lowConfidenceTopScoreThreshold || ratio <= rankProfile.lowConfidenceGapRatioThreshold;
+}
+function rerankTopK(params) {
+    const { prompt, ranked, chunksById, topK, rankProfile, } = params;
+    if (ranked.length < 2 || topK <= 0)
+        return { ranked, applied: false };
+    const head = ranked.slice(0, topK);
+    const tail = ranked.slice(topK);
+    const promptTokens = [...new Set(tokenize(prompt).filter((t) => t.length >= 2))];
+    if (!promptTokens.length)
+        return { ranked, applied: false };
+    const topScore = head[0]?.score ?? 0;
+    const bumped = head.map((item) => {
+        const chunk = chunksById.get(item.id);
+        if (!chunk)
+            return item;
+        const text = [chunk.title, ...(chunk.key_phrases ?? [])].join(' ').toLowerCase();
+        const overlap = promptTokens.reduce((acc, token) => (text.includes(token.toLowerCase()) ? acc + 1 : acc), 0);
+        if (overlap <= 0 && !hasTitleExactMatch(prompt, chunk.title))
+            return item;
+        let boost = topScore * 0.002 * overlap;
+        if (hasTitleExactMatch(prompt, chunk.title)) {
+            boost += Math.max(topScore * 0.015, 1.5) * (rankProfile.titleExactMultiplier - 1);
+        }
+        boost += rankProfile.titleTokenBoost * overlap;
+        return { ...item, score: item.score + boost };
+    });
+    const rerankedHead = stableSortRanked(bumped);
+    const applied = rerankedHead.some((item, idx) => item.id !== head[idx]?.id);
+    return { ranked: [...rerankedHead, ...tail], applied };
+}
+export async function runSearchPass(params) {
     const { allChunks, passNorm, retrievalMode, queryApiTokens, opts, } = params;
     const effectivePassNorm = retrievalMode === 'discovery'
         ? { ...passNorm, types: undefined }
         : passNorm;
+    const rankProfile = resolveRankProfile({ product: effectivePassNorm.product });
     let pool = filterPool(allChunks, effectivePassNorm);
     // types 误传自愈：首轮保留，二次扩检也同样保留该能力
     if (pool.length === 0 && effectivePassNorm.types?.length) {
         pool = filterPool(allChunks, { ...effectivePassNorm, types: undefined });
     }
+    // 分层过滤：向量语义召回仅受 Hard 层（product + retrievable_scope）约束，
+    // framework/types/scenario 转到 applyRankMultipliers 做软降权，保留向量的跨平台/类型自愈能力。
+    const hardPool = filterPoolHard(allChunks, effectivePassNorm);
+    const hardChunksById = new Map(hardPool.map((chunk) => [chunk.id, chunk]));
     const { boosts, exactHits, urlRowHitChunkIds } = runExactLookup(effectivePassNorm.prompt, pool, effectivePassNorm);
     // A2 补充正向路由：UserSig 问法下允许 share 命中且优先于无关 urls 噪声
     if (/usersig|sdkappid|secretkey|鉴权|签名|gentestusersig/i.test(passNorm.prompt)) {
@@ -387,36 +559,189 @@ export function runSearchPass(params) {
         boosts[id] = (boosts[id] ?? 0) + amount;
     }
     const ranked = rankSubsetWithIndex(effectivePassNorm.prompt, pool.map((chunk) => chunk.id), productIndex, boosts);
-    const rankedWithMultipliers = applyRankMultipliers(ranked, chunksById, {
+    // 固定链路：Hybrid（BM25 + Vector）→ RRF 融合 → 轻量重排。
+    // 兼容开关：DISABLE_VECTOR_AUGMENT=1 时只关闭向量相关步骤，BM25 主链路保持不变。
+    const vectorAugmentDisabled = process.env.DISABLE_VECTOR_AUGMENT === '1';
+    const alphaOverride = process.env.VECTOR_AUGMENT_ALPHA
+        ? Number(process.env.VECTOR_AUGMENT_ALPHA)
+        : undefined;
+    const alpha = alphaOverride !== undefined && !Number.isNaN(alphaOverride) ? alphaOverride : 0.15;
+    const baseBeta = readEnvNumber('VECTOR_AUGMENT_BASE_BETA', 0.3);
+    const topK = Math.max(1, Math.floor(readEnvNumber('VECTOR_TOP_K', DEFAULT_VECTOR_TOP_K)));
+    const rrfK = Math.max(1, Math.floor(readEnvNumber('VECTOR_RRF_K', DEFAULT_RRF_K)));
+    const rerankTopKLimit = Math.max(0, Math.floor(readEnvNumber('VECTOR_RERANK_TOP_K', rankProfile.rerankTopK || DEFAULT_RERANK_TOP_K)));
+    const fullDocumentMaxChars = Math.max(1000, Math.floor(readEnvNumber('SEARCH_FULL_DOCUMENT_MAX_CHARS', 7000)));
+    let rankedFused = ranked;
+    // 向量归因埋点采集（终态归因在函数末尾统一构造）：
+    // - bm25TopIdSnapshot：向量介入前的 BM25 单路头名（即 ranked[0]，融合前的原始头名）
+    // - vectorTopIdSnapshot：向量单路头名（vecHits[0]，经 hardChunksById 过滤后）
+    // - vecScoreById：向量单路每个候选的 sim 分，供 final_top1_id 查表得 vector_score_of_final_top1
+    // - bm25RankById：向量介入前 BM25 单路的 1-based 名次索引，供 rank_shift 与 promoted_by_vector_count 计算
+    const bm25TopIdSnapshot = ranked[0]?.id ?? null;
+    const bm25RankById = new Map();
+    ranked.forEach((item, idx) => bm25RankById.set(item.id, idx + 1));
+    let vectorTopIdSnapshot = null;
+    let vecScoreById = new Map();
+    if (!vectorAugmentDisabled) {
+        try {
+            const [qvecInst, qvecRaw] = await Promise.all([
+                embedQuery(withQueryInstruction(effectivePassNorm.prompt)),
+                embedQuery(effectivePassNorm.prompt),
+            ]);
+            const [hitsInst, hitsRaw] = await Promise.all([
+                queryVectors(passNorm.product, qvecInst, topK),
+                queryVectors(passNorm.product, qvecRaw, topK),
+            ]);
+            const merged = new Map();
+            for (const h of hitsInst) {
+                merged.set(h.id, Math.max(merged.get(h.id) ?? Number.NEGATIVE_INFINITY, h.score));
+            }
+            for (const h of hitsRaw) {
+                const weighted = h.score * 0.97;
+                merged.set(h.id, Math.max(merged.get(h.id) ?? Number.NEGATIVE_INFINITY, weighted));
+            }
+            const hits = [...merged.entries()]
+                .map(([id, score]) => ({ id, score }))
+                .sort((a, b) => {
+                if (b.score !== a.score)
+                    return b.score - a.score;
+                return a.id.localeCompare(b.id);
+            })
+                .slice(0, topK);
+            // 分层过滤：向量仅受 Hard 层（product + retrievable_scope）约束，
+            // framework/types/scenario 交给 applyRankMultipliers 做软降权。
+            // 向量补召回但不在 BM25 pool 内的 chunk 需要挂到 chunksById，供下游 rerank / multiplier / postProcess 读取。
+            const vecHits = hits.filter((h) => hardChunksById.has(h.id));
+            for (const hit of vecHits) {
+                if (chunksById.has(hit.id))
+                    continue;
+                const chunk = hardChunksById.get(hit.id);
+                if (!chunk)
+                    continue;
+                chunksById.set(hit.id, attachChunkContent(chunk));
+            }
+            vectorTopIdSnapshot = vecHits[0]?.id ?? null;
+            vecScoreById = new Map(vecHits.map((h) => [h.id, h.score]));
+            if (vecHits.length > 0) {
+                const fusionProfile = resolveFusionProfile(effectivePassNorm.prompt, queryApiTokens);
+                const fused = fuseByRRF({
+                    bm25Ranked: ranked,
+                    vectorHits: vecHits,
+                    rrfK,
+                    baseBeta,
+                    alpha,
+                    profile: fusionProfile,
+                });
+                const reranked = rerankTopK({
+                    prompt: effectivePassNorm.prompt,
+                    ranked: fused.ranked,
+                    chunksById,
+                    topK: rerankTopKLimit,
+                    rankProfile,
+                });
+                rankedFused = reranked.ranked;
+            }
+        }
+        catch {
+            // 向量链路失败（embed/query 异常）：保持 rankedFused = ranked，
+            // 快照变量维持初始值即可。归因阶段 vector_top1_id 为 null 天然反映降级。
+        }
+    }
+    const preferredIotFeatureDomain = inferPreferredIotFeatureDomain(rankedFused, chunksById, passNorm.prompt);
+    const preferredIotFeatureSource = inferIotFeatureSourceKeyword(passNorm.prompt);
+    const rankedWithMultipliers = applyRankMultipliers(rankedFused, chunksById, {
         product: passNorm.product,
         framework: passNorm.framework,
         frameworks: passNorm.frameworks,
+        preferred_iot_feature_domain: preferredIotFeatureDomain,
+        preferred_iot_feature_source: preferredIotFeatureSource,
+        prompt: passNorm.prompt,
+        rank_profile: rankProfile.name,
     });
-    const rankedAfterIntentGuard = applyDiagnosisIntentGuard(rankedWithMultipliers, chunksById, passNorm.prompt);
-    // 覆盖度竞争先于 A3 执行
-    const integrationPriority = resolveContentPriority(rankedAfterIntentGuard, chunksById);
+    let rankedAfterIntentGuard = applyDiagnosisIntentGuard(rankedWithMultipliers, chunksById, passNorm.prompt);
+    if (shouldTriggerLowConfidenceRerank({ ranked: rankedAfterIntentGuard, rankProfile })) {
+        const secondPass = rerankTopK({
+            prompt: passNorm.prompt,
+            ranked: rankedAfterIntentGuard,
+            chunksById,
+            topK: rankProfile.lowConfidenceRerankTopK,
+            rankProfile,
+        });
+        if (secondPass.applied) {
+            rankedAfterIntentGuard = secondPass.ranked;
+        }
+    }
+    const promptLockPolicy = decidePromptLockPolicy(passNorm.prompt);
+    const allowContentPriority = promptLockPolicy.enableContentPriority;
+    const allowFullDocumentLock = promptLockPolicy.enableFullDocumentLock;
+    // 覆盖度竞争先于 A3 执行（仅在前置策略允许时开启）
+    // 若覆盖度竞争未触发，再尝试“导航来源 vs 内容来源”的通用语义仲裁。
+    const integrationPriority = allowContentPriority
+        ? (resolveContentPriority(rankedAfterIntentGuard, chunksById, fullDocumentMaxChars)
+            ?? resolveSemanticSourcePriorityByVector({
+                ranked: rankedAfterIntentGuard,
+                chunksById,
+                vectorTopId: vectorTopIdSnapshot,
+                prompt: passNorm.prompt,
+                fullDocumentMaxChars,
+            }))
+        : null;
     let dominantBestPractice;
     let rankedAfterBestPractice;
     if (integrationPriority) {
         // integration 胜出 → 跳过 A3，直接走完整文档路径
         rankedAfterBestPractice = rankedAfterIntentGuard;
-        dominantBestPractice = integrationPriority;
+        dominantBestPractice = allowFullDocumentLock
+            ? integrationPriority
+            : { fullDocumentMode: false };
     }
     else {
         // integration 未胜出 → A3 提升 BP → BP 收敛判定
         rankedAfterBestPractice = prioritizeBestPracticeWhenCompetitive(rankedAfterIntentGuard, chunksById, passNorm.prompt);
-        dominantBestPractice = pickDominantBestPracticeSource(rankedAfterBestPractice, chunksById);
+        dominantBestPractice = allowFullDocumentLock
+            ? pickDominantBestPracticeSource(rankedAfterBestPractice, chunksById, fullDocumentMaxChars)
+            : { fullDocumentMode: false };
     }
     const pinnedUrlRowChunkIds = new Set(urlRowHitChunkIds);
+    // 独立信号：存在精确 URL 命中 → 启用 35% 断崖截断。
+    // 与 pin 语义解耦：即便 pin 集合发生变化或 BP 校准影响 fragments 组成，
+    // 截断策略仍由“是否存在精确 URL 命中”这一确定性信号决定。
+    const strictCutoffOnExactUrlHit = pinnedUrlRowChunkIds.size > 0;
     const fragments = postProcess(rankedAfterBestPractice, chunksById, passNorm.limit, {
         pinnedUrlRowChunkIds,
+        strictCutoffOnExactUrlHit,
         preferredSource: dominantBestPractice.preferredSource,
         fullDocumentMode: dominantBestPractice.fullDocumentMode,
+        fullDocumentMaxChars,
+        maxPerSource: rankProfile.maxPerSource,
     });
     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);
+    // === 向量归因（终态构造）===
+    // final_top1_id：postProcess 之后 fragments[0] 的 chunk_id（enrichL1Fragments 后续 in-place enrich
+    // content 但不改动 chunk_id / 顺序，所以此处快照即最终外部感知的 top1）。
+    const finalTop1Id = fragments[0]?.chunk_id ?? null;
+    const finalTop1BmRank = finalTop1Id ? (bm25RankById.get(finalTop1Id) ?? null) : null;
+    const finalTop1VecScore = finalTop1Id ? (vecScoreById.get(finalTop1Id) ?? null) : null;
+    // promoted_by_vector_count：BM25 原始名次 > 3 且经融合/后处理进入 final top3 的 chunk 数量。
+    // 只需交集 |{chunk : bm25Rank(chunk) > 3 AND chunk ∈ finalTop3}|；ranked 为空自然记 0。
+    const finalTop3Ids = fragments.slice(0, 3).map((f) => f.chunk_id);
+    let promotedByVectorCount = 0;
+    for (const id of finalTop3Ids) {
+        const bmRank = bm25RankById.get(id);
+        if (bmRank !== undefined && bmRank > 3)
+            promotedByVectorCount += 1;
+    }
+    const vectorDiagnostics = {
+        bm25_top1_id: bm25TopIdSnapshot,
+        vector_top1_id: vectorTopIdSnapshot,
+        final_top1_id: finalTop1Id,
+        rank_shift_from_bm25: finalTop1BmRank,
+        vector_score_of_final_top1: finalTop1VecScore,
+        promoted_by_vector_count: promotedByVectorCount,
+    };
     return {
         pool,
         poolWithContent,
@@ -429,6 +754,7 @@ export function runSearchPass(params) {
         missingApiTokens,
         urlMapRelaxed: pinnedUrlRowChunkIds.size > 0,
         urlMapExactHitCount: pinnedUrlRowChunkIds.size,
+        vectorDiagnostics,
         preferredSource: dominantBestPractice.preferredSource,
         fullDocumentMode: dominantBestPractice.fullDocumentMode,
     };