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

package/knowledge/search/exact-lookup.js

@@ -6,11 +6,17 @@ import { computeCommonSectionTokens, isUrlMappingSource, normalizeUrlRowQuery, q
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const SCHEMA_ROOT = path.resolve(__dirname, '../../resource/_schema');
 /**
- * 分组语义命中的基础分：当 scoreUrlRow=0 但该 url 行「分组被 query 命中 + types 匹配」时给予。
- * 取值需满足 E7 strongCandidates 门槛（typeMatch ×1.2 后 ≥500 → base ≥417）。
- * 只在「分组命中」时给（区别于旧的「所有 types 匹配行给 500」），避免无关行涌入。
+ * 分组语义命中兜底相关常量。
+ * 结构性约束：兜底分永远 < 同批次真实命中的最低分，避免「未命中兜底反超弱命中真分」倒挂。
+ *
+ * - FALLBACK_SAFETY_MARGIN：兜底分与最低真实命中分之间的安全间距。
+ * - FALLBACK_MIN_SCORE：兜底分硬下限（无真实命中时的默认底），仍能进入候选池；
+ *   后续 filter 门槛会决定它是否上榜。
+ * - FALLBACK_DEFAULT_BASELINE：无任何真实命中时用于估算兜底的默认真分基线。
  */
-const SECTION_MATCH_BASE_SCORE = 450;
+const FALLBACK_SAFETY_MARGIN = 50;
+const FALLBACK_MIN_SCORE = 100;
+const FALLBACK_DEFAULT_BASELINE = 500;
 export const DOC_PATH_MAP = {
     android: {
         core_api: 'TRTCCloud',
@@ -316,8 +322,14 @@ export function runExactLookup(prompt, pool, norm) {
         // 支持 types 领域限定：上游推断出 types 时，优先 types 匹配的子文件行，
         // 不匹配的行降权（避免跨域误命中，如 SDK 问题命中 restapi）。
         if (normalizeUrlRowQuery(prompt).replace(/\s+/g, '').length >= 2) {
-            const candidates = [];
-            const hasTypeFilter = Boolean(norm.searchIntent?.length);
+            // 结构性修复：分两遍收集，避免「未命中兜底分」反超「弱命中真实分」的倒挂 bug。
+            // 第一遍收集 realHits（scoreUrlRow>0）和 fallbackChunks（分组语义命中兜底）；
+            // 第二遍以 realHits 的最低分为基准，动态计算兜底分（min - MARGIN），保证：
+            //   任意 fallback score < 任意 realHit score
+            // 这样无论 query 怎么变化，命中的真分永远优先于未命中的兜底分。
+            const realHits = [];
+            const fallbackChunks = [];
+            const hasTypeFilter = Boolean((norm.types ?? []).length);
             // 预收集 urls 行的分组结构：按 source 读整个 md 源文件，解析 `##` 分组与每行归属。
             // 分组粗筛对所有 urls 资源生效（产品无关），不针对 webhook.md 打补丁。
             const urlChunks = pool.filter((c) => isUrlMappingSource(c.source) && c.title.trim());
@@ -359,11 +371,12 @@ export function runExactLookup(prompt, pool, norm) {
             for (const [source, sections] of sectionsBySource) {
                 commonTokensBySource.set(source, computeCommonSectionTokens([...sections]));
             }
+            // 第一遍：分流真实命中与兜底候选
             for (const chunk of urlChunks) {
                 const scoreResult = scoreUrlRow(prompt, chunk.title);
                 // types 领域限定：query types 与 chunk types 是否有交集
                 const typeMatch = hasTypeFilter
-                    ? (norm.searchIntent ?? []).some((t) => chunk.types.includes(t))
+                    ? (norm.types ?? []).some((t) => chunk.types.includes(t))
                     : true;
                 // 分组粗筛：query 是否命中该 chunk 所在的分组。
                 // 命中分组 → 正常；未命中分组 → 降权（不排除，避免 query 与分组名匹配不准时误杀）。
@@ -377,27 +390,40 @@ export function runExactLookup(prompt, pool, norm) {
                 // 跟 section 标题「群组系统回调」共享字符少（仅「群」），sectionMatch 失败，
                 // 但 row title 本身完美匹配 user 意图，强行降权会让单聊 row 顶上。
                 const highConfidence = scoreResult.score >= 700;
-                // 分组语义命中基础分：scoreUrlRow 可能因「同义词/长句」对精确行打 0 分
-                // （如「群消息发送前回调」vs「群内发言之前回调」），但分组已语义命中，
-                // 给予基础分进入候选，避免该领域行被 score<=0 排除。
+                // scoreUrlRow<=0 且分组语义命中 → 归入 fallbackChunks（第二遍统一定分）
                 // 区别于旧的「所有 types 匹配行给 500」——只在分组命中时才给，避免无关行涌入。
                 if (scoreResult.score <= 0) {
                     if (sectionMatch && typeMatch) {
-                        candidates.push({ chunk, score: SECTION_MATCH_BASE_SCORE, typeMatch, sectionMatch });
+                        fallbackChunks.push({ chunk, typeMatch, sectionMatch });
                     }
                     continue;
                 }
                 // finalScore 排序用：sectionMatch 失败且非高置信时，×0.7 软降权。
                 // 高置信（scoreUrlRow ≥ 700）跳过降权，避免短 query + 长 section 标题时的误杀。
                 const finalScore = (sectionMatch || highConfidence) ? scoreResult.score : scoreResult.score * 0.7;
-                candidates.push({ chunk, score: finalScore, typeMatch, sectionMatch });
+                realHits.push({ chunk, score: finalScore, typeMatch, sectionMatch });
             }
-            candidates.sort((a, b) => b.score - a.score);
+            // 第二遍：以最低真分为基准动态计算兜底分，保证兜底 < 所有真命中
+            const minRealScore = realHits.length > 0
+                ? Math.min(...realHits.map((h) => h.score))
+                : FALLBACK_DEFAULT_BASELINE;
+            const fallbackScore = Math.max(FALLBACK_MIN_SCORE, minRealScore - FALLBACK_SAFETY_MARGIN);
+            const candidates = [
+                ...realHits,
+                ...fallbackChunks.map((f) => ({ ...f, score: fallbackScore })),
+            ];
+            candidates.sort((a, b) => {
+                if (b.score !== a.score)
+                    return b.score - a.score;
+                return a.chunk.id.localeCompare(b.chunk.id);
+            });
             // types 匹配的行加分（更优先）；不匹配的行轻度降权但仍可兜底召回。
             // 避免上游 types 推断不准确时误杀正确文档（如「多端登录配置」被推断为 feature 而非 product）。
+            // 门槛从 >=500 降至 >=400：配套动态兜底逻辑——真实弱命中（如 scoreUrlRow=400 × 0.7 = 280
+            // → 280×1.2=336 仍会被 >=500 淘汰），需要将 filter 门槛与新的兜底基线保持在同一整数域。
             const typeScored = candidates
                 .map((c) => (c.typeMatch ? { ...c, score: c.score * 1.2 } : { ...c, score: c.score * 0.6 }))
-                .filter(({ score }) => score >= 500);
+                .filter(({ score }) => score >= 400);
             // 同分 row（典型：query「群消息撤回回调」时「撤回群消息」跟「单聊消息撤回」都 scoreUrlRow=660），
             // 按「query 字符集被 row title 覆盖比例」再排，覆盖更高的 row 排前。
             // 修 E7 boost idx=0 多 40 分的副作用：让字符集更精准的 row 拿 idx=0 → 300 分而不是 260 分。
@@ -417,7 +443,10 @@ export function runExactLookup(prompt, pool, norm) {
                 // 优先按 typeScored score 降序；同分时按字符集覆盖率降序
                 if (b.score !== a.score)
                     return b.score - a.score;
-                return charCoverage(b.chunk.title) - charCoverage(a.chunk.title);
+                const coverageDiff = charCoverage(b.chunk.title) - charCoverage(a.chunk.title);
+                if (coverageDiff !== 0)
+                    return coverageDiff;
+                return a.chunk.id.localeCompare(b.chunk.id);
             })
                 .slice(0, 12);
             strongCandidates.forEach(({ chunk, score }, idx) => {
@@ -433,7 +462,7 @@ export function runExactLookup(prompt, pool, norm) {
         }
     }
     // E9: chat faq——types=faq 时优先 knowledge 语料，避免 integration 文档内 FAQ 章节抢首位
-    if (norm.searchIntent?.includes('faq') && norm.product?.includes('chat')) {
+    if ((norm.types ?? []).includes('faq') && norm.product?.includes('chat')) {
         const authPrompt = /auth|login|signature|usersig|鉴权|登录/i.test(prompt);
         for (const chunk of pool) {
             if (chunk.source.startsWith('knowledge/chat/')) {
@@ -487,6 +516,106 @@ export function runExactLookup(prompt, pool, norm) {
                     }
                 }
             }
+            // E10.5: room best-practice 召回补偿
+            // 背景：E10 只对 `scope === coreScope` 的 chunk 广谱 +40，
+            // 而 `knowledge/roomkit/best-practice/` 下的跨平台 FAQ（scope=platform_common）
+            // 一分未拿，同 query 下会被同一份 core-sdk 文件的多 chunk +40 累加压掉。
+            // 三层加分（可叠加）：
+            //   1) 广谱 +80：所有 room best-practice chunk 统一 +80，跟 core-sdk 广谱 +40 拉开档次；
+            //   2) 平台匹配 +40：chunk.framework 与当前 platform 有交集（含 web/common 兼容项）；
+            //   3) §8 同义问法命中 +200：读源文件解析 §8「同义问法覆盖」条目，query 命中任一问法 → +200。
+            // 参考 callkit E13A/E13B 的 +260~+300 精准 boost，room 这里用略低的 +200 尊重现有排序。
+            const bpChunks = pool.filter((c) => c.product === 'room' && c.source.includes('/best-practice/'));
+            // Source → §8 问法条目缓存（同一 source 下多 chunk 共用文件级 §8）
+            const bpSynonymsBySource = new Map();
+            const extractSynonyms = (source) => {
+                if (bpSynonymsBySource.has(source))
+                    return bpSynonymsBySource.get(source);
+                let full = '';
+                try {
+                    full = getSourceFileContent(source);
+                }
+                catch {
+                    full = '';
+                }
+                const lines = full.split('\n');
+                const list = [];
+                let inSection = false;
+                for (const line of lines) {
+                    // §8 允许 "## 8. xxx" 或 "## 同义问法..." 两种标题格式
+                    if (/^##\s+(8\.\s*)?同义问法/.test(line)) {
+                        inSection = true;
+                        continue;
+                    }
+                    if (inSection && /^##\s+/.test(line))
+                        break;
+                    if (inSection) {
+                        const item = line.match(/^-\s+(.+?)[?？]?$/);
+                        if (item)
+                            list.push(item[1].trim());
+                    }
+                }
+                bpSynonymsBySource.set(source, list);
+                return list;
+            };
+            // 平台兼容集：query platform 命中 chunk.framework 里的这些标签均视为匹配
+            // vue → [vue, web, common, react]（跨平台 web 类问法通常写作 react/vue/web）
+            // react → [react, web, common, vue]
+            // android/ios/flutter → [self, common]
+            const platformCompat = {
+                vue: ['vue', 'web', 'common', 'react'],
+                react: ['react', 'web', 'common', 'vue'],
+                android: ['android', 'common'],
+                ios: ['ios', 'common'],
+                flutter: ['flutter', 'common'],
+            };
+            const compatSet = new Set(platformCompat[platform] ?? [platform, 'common']);
+            // query 归一化：小写 + 去空格，用于宽松包含匹配（问法通常是短句）
+            const promptForMatch = prompt.toLowerCase().replace(/\s+/g, '');
+            for (const chunk of bpChunks) {
+                // 1) 广谱 +80
+                addBoost(chunk, 80, 'E10.5:room-bp');
+                // 2) 平台匹配 +40
+                const frameworkMatch = (chunk.framework ?? []).some((fw) => compatSet.has(fw));
+                if (frameworkMatch) {
+                    addBoost(chunk, 40, `E10.5:room-bp-platform:${platform}`);
+                }
+                // 3) §8 同义问法命中 +200（同 source 只算一次，避免同文件多 chunk 重复加）
+                const synonyms = extractSynonyms(chunk.source);
+                if (synonyms.length === 0)
+                    continue;
+                const hit = synonyms.some((q) => {
+                    const normQ = q.toLowerCase().replace(/\s+/g, '');
+                    if (normQ.length < 4)
+                        return false;
+                    // 双向宽松匹配：query 包含问法（短问法命中长 query），或问法包含 query（罕见，防守）
+                    return promptForMatch.includes(normQ) || normQ.includes(promptForMatch);
+                });
+                if (hit) {
+                    addBoost(chunk, 200, `E10.5:room-bp-synonym`);
+                }
+                else {
+                    // 退化匹配：若整句问法未匹配，用问法内 4+ 长中文/英文子串扫描
+                    // 覆盖 "整屏共享怎么避免无限镜像" vs "分享屏幕出现无限套娃" 这类只共享部分词汇的情况
+                    const keywords = new Set();
+                    for (const q of synonyms) {
+                        const zhTokens = q.match(/[\u4e00-\u9fff]{2,}/g) ?? [];
+                        for (const t of zhTokens)
+                            if (t.length >= 2)
+                                keywords.add(t);
+                    }
+                    let matchedKeywordCount = 0;
+                    for (const kw of keywords) {
+                        if (promptForMatch.includes(kw.toLowerCase()))
+                            matchedKeywordCount += 1;
+                        if (matchedKeywordCount >= 2)
+                            break;
+                    }
+                    if (matchedKeywordCount >= 2) {
+                        addBoost(chunk, 120, `E10.5:room-bp-keywords`);
+                    }
+                }
+            }
         }
     }
     // E12: CallKit Vue 混合类型问题消歧（状态机 STATUS 与 Core Store 类型分层召回）

package/knowledge/search/filter-pool.js

@@ -6,7 +6,12 @@ import { hasExplicitFrameworkMatch, hasFrameworkFallbackMatch } from './framewor
  * path-meta.ts 已通过 normalizeFrameworkDir 把目录名归一到标准 framework，
  * 所有产品的 framework 均已对齐枚举值，无需额外别名扩展。
  */
-const FRAMEWORK_SEARCH_ALIASES = {};
+const FRAMEWORK_SEARCH_ALIASES = {
+    miniprogram: ['miniprogram', 'minprogram'],
+    minprogram: ['minprogram', 'miniprogram'],
+    'react-native': ['react-native', 'rn'],
+    rn: ['rn', 'react-native'],
+};
 function expandFrameworks(frameworks, _products) {
     if (!frameworks?.length)
         return undefined;
@@ -112,38 +117,77 @@ function promptMatchesRetrievableScope(prompt, scope) {
     const normalizedPrompt = normalizeScopeToken(prompt);
     return scope.some((token) => normalizedPrompt.includes(normalizeScopeToken(token)));
 }
-export function filterPool(chunks, norm) {
-    return chunks.filter((chunk) => {
-        if (norm.product && !norm.product.includes(chunk.product) && chunk.product !== '*') {
-            return false;
-        }
-        // A1: 通配语料(share 等)必须命中 retrievable_scope 才能进入检索池
-        if (chunk.product === '*' && !promptMatchesRetrievableScope(norm.prompt, chunk.retrievable_scope)) {
+/**
+ * 硬过滤层（Hard filter）：语义无关的强约束，任何检索通道都必须遵守。
+ *
+ * 语义：
+ *   - product：产品维度物理隔离（不同产品的语料本就不应互相召回）。
+ *   - A1 retrievable_scope：通配语料（share 等）必须命中作用域，防止 share 语义误召到具体产品下。
+ *
+ * 使用者：
+ *   - BM25 通道：入池前调用
+ *   - 向量通道：召回后二次校验，作为索引层 product 分片的兜底
+ */
+export function filterPoolHard(chunks, norm) {
+    return chunks.filter((chunk) => isHardAllowed(chunk, norm));
+}
+export function isHardAllowed(chunk, norm) {
+    if (norm.product && !norm.product.includes(chunk.product) && chunk.product !== '*') {
+        return false;
+    }
+    // A1: 通配语料(share 等)必须命中 retrievable_scope 才能进入检索池
+    if (chunk.product === '*' && !promptMatchesRetrievableScope(norm.prompt, chunk.retrievable_scope)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * 软过滤层（Soft filter）：语义相关的偏好约束，向量语义召回不应被此层直接砍掉。
+ *
+ * 语义：
+ *   - framework：平台维度偏好（向量语义可跨平台复用，应转为软降权）
+ *   - scenario：场景维度偏好（live/voice）
+ *   - types：文档类型偏好（Agent 可能传错，向量语义能自愈到正确类型）
+ *
+ * 使用者：
+ *   - BM25 通道：与 Hard 合用（保持现网行为）
+ *   - 向量通道：不使用；由 applyRankMultipliers 在融合后做软降权
+ */
+export function isSoftAllowed(chunk, norm) {
+    if (norm.frameworks?.length) {
+        const isWildcardChunk = chunk.framework.includes('*');
+        // 收紧：framework=['*'] 仅在该 chunk 明确是跨平台 type（product/server_api/webhook）时放行；
+        // 否则要求 chunk.framework 与请求 framework 有交集。
+        const wildcardAllowed = isWildcardChunk && chunkIsCrossPlatform(chunk.types);
+        const explicitMatch = hasExplicitFrameworkMatch(chunk.framework, norm.frameworks);
+        const fallbackMatch = hasFrameworkFallbackMatch(chunk, {
+            product: norm.product,
+            framework: norm.framework,
+            frameworks: norm.frameworks,
+        });
+        if (!explicitMatch && !wildcardAllowed && !fallbackMatch)
             return false;
-        }
-        if (norm.frameworks?.length) {
-            const isWildcardChunk = chunk.framework.includes('*');
-            // 收紧：framework=['*'] 仅在该 chunk 明确是跨平台 type（product/server_api/webhook）时放行；
-            // 否则要求 chunk.framework 与请求 framework 有交集。
-            const wildcardAllowed = isWildcardChunk && chunkIsCrossPlatform(chunk.types);
-            const explicitMatch = hasExplicitFrameworkMatch(chunk.framework, norm.frameworks);
-            const fallbackMatch = hasFrameworkFallbackMatch(chunk, {
-                product: norm.product,
-                framework: norm.framework,
-                frameworks: norm.frameworks,
-            });
-            if (!explicitMatch && !wildcardAllowed && !fallbackMatch)
-                return false;
-        }
-        if (norm.scenario && chunk.scenario && chunk.scenario !== norm.scenario) {
+    }
+    if (norm.scenario && chunk.scenario && chunk.scenario !== norm.scenario) {
+        return false;
+    }
+    // IoT 端别过滤改为“召回保留 + 排序分层”：
+    // Phase2 中 exact/common/conflict 的优先级由 applyRankMultipliers 处理，
+    // 这里不做硬过滤，避免因标注偏差误杀有效候选。
+    // best-practice 文档对 types 过滤免疫：内容不依赖 types 分类，应始终进 pool 靠 BM25 自然排名。
+    // 典型场景：Agent 传 types=['api'] 时，types=['faq'] 的 best-practice 不应被过滤掉。
+    if (norm.types?.length && !norm.types.some((t) => chunk.types.includes(t))) {
+        if (!chunk.source.includes('/best-practice/'))
             return false;
-        }
-        // best-practice 文档对 types 过滤免疫：内容不依赖 types 分类，应始终进 pool 靠 BM25 自然排名。
-        // 典型场景：Agent 传 types=['api'] 时，types=['faq'] 的 best-practice 不应被过滤掉。
-        if (norm.types?.length && !norm.types.some((t) => chunk.types.includes(t))) {
-            if (!chunk.source.includes('/best-practice/'))
-                return false;
-        }
-        return true;
-    });
+    }
+    return true;
+}
+/**
+ * 完整过滤（Hard + Soft）：BM25 主通道使用，保持现网行为不变。
+ *
+ * 向量通道**不应**使用此函数——它会把 framework/types/scenario 硬砍掉，
+ * 抵消向量语义的跨平台/类型自愈能力。向量通道请使用 filterPoolHard。
+ */
+export function filterPool(chunks, norm) {
+    return chunks.filter((chunk) => isHardAllowed(chunk, norm) && isSoftAllowed(chunk, norm));
 }

package/knowledge/search/rank-profile.js

@@ -0,0 +1,25 @@
+const DEFAULT_PROFILE = {
+    name: 'default',
+    maxPerSource: 3,
+    rerankTopK: 20,
+    lowConfidenceRerankTopK: 0,
+    lowConfidenceTopScoreThreshold: 0,
+    lowConfidenceGapRatioThreshold: 0,
+    titleExactMultiplier: 1.03,
+    titleTokenBoost: 0.05,
+};
+const IOT_PROFILE = {
+    name: 'iot',
+    maxPerSource: 2,
+    rerankTopK: 24,
+    lowConfidenceRerankTopK: 10,
+    lowConfidenceTopScoreThreshold: 28,
+    lowConfidenceGapRatioThreshold: 1.08,
+    titleExactMultiplier: 1.15,
+    titleTokenBoost: 0.15,
+};
+export function resolveRankProfile(params) {
+    if (params.product?.includes('iot'))
+        return IOT_PROFILE;
+    return DEFAULT_PROFILE;
+}

package/knowledge/search/requires-framework.js

@@ -8,7 +8,7 @@ const PLATFORM_TYPES = new Set([
     'integration',
 ]);
 const CROSS_PLATFORM_TYPES = new Set(['server_api', 'webhook', 'product']);
-const CROSS_PLATFORM_PROMPT = /计费|套餐|价格|UserSig\s*原理|签发流程|控制台|服务端\s*REST|云\s*API|Webhook|回调/i;
+const CROSS_PLATFORM_PROMPT = /计费|套餐|价格|UserSig\s*原理|签发流程|控制台|服务端\s*REST|云\s*API|Webhook|回调|callback|server\s*callback|物联网开发平台|安防摄像头|智能视觉服务|儿童手表|录音卡/i;
 const PLATFORM_PROMPT = /API|组件|怎么用|怎么开|怎么设置|怎么配置|虚拟背景|屏幕分享|enterRoom|SDK|插件|集成步骤|客户端|Feature|主题定制|连麦|上麦/i;
 /**
  * push 必须问平台的强信号：仅当 prompt 明确提到具体「平台」（android/ios/flutter/...）时才拦询问。
@@ -60,6 +60,9 @@ export function requiresFramework(norm) {
             return false;
         return false;
     }
+    // iot：产品级/能力线/API 问法第一阶段允许跨平台检索，不做 framework 前置拦截
+    if (hasProduct(norm, 'iot'))
+        return false;
     // native_trtc_sdk：所有平台相关咨询都依赖具体客户端（android/ios/c++），必须先问
     if (hasProduct(norm, 'native_trtc_sdk'))
         return true;

package/knowledge/search/search-core.js

@@ -36,11 +36,22 @@ export function postProcess(ranked, chunksById, limit, opts) {
             .filter((chunk) => chunk.source === opts.preferredSource)
             .sort((a, b) => a.char_start - b.char_start);
         if (sections.length > 0) {
-            return sections.map((section, idx) => buildFragment(section, scoreMap.get(section.id) ?? 0, idx + 1));
+            const fullDocumentMaxChars = Math.max(1000, opts.fullDocumentMaxChars ?? 7000);
+            const selectedSections = [];
+            let usedChars = 0;
+            for (const section of sections) {
+                const sectionChars = section.content.length;
+                if (selectedSections.length > 0 && usedChars + sectionChars > fullDocumentMaxChars)
+                    break;
+                selectedSections.push(section);
+                usedChars += sectionChars;
+            }
+            return selectedSections.map((section, idx) => buildFragment(section, scoreMap.get(section.id) ?? 0, idx + 1));
         }
     }
     const sourceCount = {};
     const urlMappingSourceCount = {};
+    const maxPerSource = Math.max(1, opts?.maxPerSource ?? 3);
     /** 已入选的 push config/android/{vendor} 文件，用于抑制其他厂商噪声 */
     let selectedVendorFile = null;
     const fragments = [];
@@ -60,7 +71,7 @@ export function postProcess(ranked, chunksById, limit, opts) {
         }
         else {
             const count = sourceCount[chunk.source] ?? 0;
-            if (count >= 3)
+            if (count >= maxPerSource)
                 continue;
             sourceCount[chunk.source] = count + 1;
         }
@@ -88,22 +99,18 @@ export function postProcess(ranked, chunksById, limit, opts) {
         }
         else if (!isPinnedUrlRow) {
             const topScore = fragments[0].score;
-            // 方案A：分数断崖截断。
-            // 当已有 E7 精确命中行（pinned url-row）时，后续非 pinned 行若跌破 Top1 的 20%，
-            // 视为「Top1 已精确命中、后续多为泛匹配噪声」，提前截断，避免凑满 limit 返回冗余。
-            // 无 E7 命中时不触发（此时答案依赖 best-practice/本地文档，需完整保留）。
+            // 方案A：分数断崖截断（拆分为两个独立信号）：
+            //   1) 通用分数衰减截断（不依赖 pin/exact-url 状态）
+            //   2) 精确 URL 命中断崖：由 caller 通过 strictCutoffOnExactUrlHit 显式启用，
+            //      避免"fragments 里恰好含 pinned row"这类间接信号驱动策略。
             if (topScore > 0) {
-                const pinnedChunkIds = opts?.pinnedUrlRowChunkIds;
-                const hasPinnedRow = pinnedChunkIds
-                    ? fragments.some((f) => pinnedChunkIds.has(f.chunk_id))
-                    : false;
                 // 原有：分数衰减到 top 的 5% 以下时停止
                 if (item.score < topScore * 0.05)
                     break;
-                // 新增：已有 E7 精确命中 + 后续跌破 35% → 断崖截断
+                // 新增：精确 URL 命中场景 → 后续跌破 35% → 断崖截断
                 // 阈值取 35%（非 20%）：best-practice 泛匹配分数常在 Top1 的 20%~35% 区间，
-                // 用 35% 才能拦住「Top1 精确命中后仍返回一堆无关 best-practice」的冗余。
-                if (hasPinnedRow && item.score < topScore * 0.35)
+                // 用 35% 才能拦住"Top1 精确命中后仍返回一堆无关 best-practice"的冗余。
+                if (opts?.strictCutoffOnExactUrlHit && item.score < topScore * 0.35)
                     break;
             }
         }
@@ -378,7 +385,29 @@ export function hasNativeClientFramework(frameworks) {
         return false;
     return frameworks.some((fw) => ['android', 'ios', 'flutter', 'c++'].includes(fw));
 }
+function normalizeCompactText(input) {
+    return input.toLowerCase().replace(/[\s\-_]+/g, '');
+}
+function hasExactTitleMatch(prompt, title) {
+    if (!prompt || !title)
+        return false;
+    const p = normalizeCompactText(prompt);
+    const t = normalizeCompactText(title);
+    if (!p || !t)
+        return false;
+    return (t.length >= 3 && p.includes(t)) || (p.length >= 3 && t.includes(p));
+}
+function tokenizePromptForTitle(prompt) {
+    return [...new Set(prompt
+            .toLowerCase()
+            .split(/[^a-z0-9\u4e00-\u9fff]+/)
+            .map((s) => s.trim())
+            .filter((s) => s.length >= 2))];
+}
 export function applyRankMultipliers(ranked, chunksById, opts) {
+    const prompt = opts.prompt ?? '';
+    const promptTokens = tokenizePromptForTitle(prompt);
+    const isIotProfile = opts.rank_profile === 'iot';
     const adjusted = ranked.map((item) => {
         const chunk = chunksById.get(item.id);
         if (!chunk)
@@ -396,6 +425,38 @@ export function applyRankMultipliers(ranked, chunksById, opts) {
                 multiplier *= 0.2;
             }
         }
+        // Phase1: title/h2 与 query 精确短语命中增强
+        if (prompt && hasExactTitleMatch(prompt, chunk.title)) {
+            multiplier *= isIotProfile ? 1.15 : 1.03;
+        }
+        if (promptTokens.length > 0) {
+            const titleText = `${chunk.title} ${(chunk.key_phrases ?? []).join(' ')}`.toLowerCase();
+            const overlap = promptTokens.reduce((acc, token) => (titleText.includes(token) ? acc + 1 : acc), 0);
+            if (overlap > 0) {
+                multiplier *= 1 + Math.min(0.06, overlap * (isIotProfile ? 0.015 : 0.008));
+            }
+        }
+        // Phase2: IoT feature_domain 软回退（IoT 唯一排序信号）
+        if (chunk.product === 'iot') {
+            if (chunk.feature_domain && opts.preferred_iot_feature_domain) {
+                if (chunk.feature_domain === opts.preferred_iot_feature_domain)
+                    multiplier *= 1.15;
+                else
+                    multiplier *= 0.9;
+            }
+            // Phase2b: 强 feature 意图 → source 精准置顶
+            // 中文意图词（云台/语音对讲）与英文文件名（ptz-control/voice-intercom）无词面关系，
+            // 用 source 路径关键词精准命中 feature 文档，越过短文本泛文档的 BM25 优势。
+            if (opts.preferred_iot_feature_source && chunk.source.includes(opts.preferred_iot_feature_source)) {
+                multiplier *= 1.7;
+            }
+            // 非 demo 意图下，弱化 app_demo/device_demo 对功能问法的抢位
+            if (chunk.feature_domain && /demo$/i.test(chunk.feature_domain)) {
+                if (!/\bdemo\b|示例|sample|example|演示/i.test(prompt)) {
+                    multiplier *= 0.82;
+                }
+            }
+        }
         return { ...item, score: item.score * multiplier };
     });
     return adjusted.sort((a, b) => b.score - a.score);