@tencent-rtc/mcp 1.7.0 → 1.7.2

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # CHANGELOG
 
+## Version 1.7.2 @2026.08.13
+
+### Changed
+- Improved observability into retrieval routing accuracy.
+
+## Version 1.7.1 @2026.08.11
+
+### Added
+- Added pre-search normalization: normalizes `product` / `frameworks` based on prompt truth, fixing retrieval bias caused by wrong agent inference.
+
+### Changed
+- Optimized the `search_trtc_knowledge` output contract: removed brevity wording such as "1-2 sentence per subsection", replaced with complete synthesized answers.
+
+### Fixed
+- Fixed the case where mis-passed dual product / dual frameworks (e.g., "安卓 Web TRTC") were not corrected according to the prompt truth.
+
 ## Version 1.7.0 @2026.08.02
 
 ### Added

package/README.md

@@ -57,6 +57,17 @@ npx -y @tencent-rtc/mcp
 
 > Only recent updates are listed here. For full history, see `CHANGELOG.md`.
 
+## Version 1.7.1 @2026.08.11
+
+### Added
+- Added pre-search normalization: normalizes `product` / `frameworks` based on prompt truth, fixing retrieval bias caused by wrong agent inference.
+
+### Changed
+- Optimized the `search_trtc_knowledge` output contract: removed brevity wording such as "1-2 sentence per subsection", replaced with complete synthesized answers.
+
+### Fixed
+- Fixed the case where mis-passed dual product / dual frameworks (e.g., "安卓 Web TRTC") were not corrected according to the prompt truth.
+
 ### Version 1.7.0 @2026.08.02
 
 #### Added
@@ -74,9 +85,3 @@ npx -y @tencent-rtc/mcp
 
 #### Added
 - Added support for `get_native_live_uikit_integration`, enabling LiveKit(Android/iOS) UI integration guidance.
-
-### Version 1.6.0 @2026.07.01
-
-#### Added
-- Refactored MCP retrieval capabilities and consolidated the MCP toolset.
-- Added support for `search_trtc_knowledge` to retrieve real-time audio/video (TRTC/IM) documentation.

package/knowledge/doc-url-resolver.js

@@ -54,17 +54,42 @@ export function extractUrlMappingPrimaryUrl(content) {
     const row = content.match(/\|\s*[^|]+\s*\|\s*`?(https?:\/\/[^|`\s]+)`?\s*\|/);
     return row?.[1] ? normalizeUrl(row[1]) : null;
 }
+/** 产品无关的 URL 映射行判定：knowledge/<product>/urls/... */
 function isUrlMappingSource(source) {
-    return /knowledge\/chat\/urls\/.+\.md$/i.test(source.replace(/\\/g, '/'));
+    return /knowledge\/[a-z0-9_-]+\/urls\/.+\.md$/i.test(source.replace(/\\/g, '/'));
+}
+const RTCENGINE_WEB_API_SOURCE = 'knowledge/rtcengine/web/api.md';
+const RTCENGINE_WEB_API_BASE_URL = 'https://web.sdk.qcloud.com/trtc/webrtc/doc/en/TRTC.html';
+/** api.md 中的非方法标题（示例/成员枚举/类型定义等），不作为锚点生成 */
+const RTCENGINE_WEB_API_NON_METHOD_RE = /^(?:Example|Members|Type|Definitions)$/i;
+/**
+ * rtcengine/web/api.md 的 API 章节 chunk（如 `### TRTC.setCurrentSpeaker` / `### setCurrentSpeaker`）
+ * 生成稳定参考链接：`.../TRTC.html#.setCurrentSpeaker`
+ * 兼容两种标题格式：静态方法带 `TRTC.` 前缀，实例方法不带前缀。
+ */
+function resolveRtcengineWebApiUrl(source, content) {
+    if (source !== RTCENGINE_WEB_API_SOURCE)
+        return null;
+    const methodMatch = content.match(/^###\s+(?:TRTC\.)?([A-Za-z0-9_]+)/m);
+    if (methodMatch?.[1] && !RTCENGINE_WEB_API_NON_METHOD_RE.test(methodMatch[1])) {
+        return `${RTCENGINE_WEB_API_BASE_URL}#.${methodMatch[1]}`;
+    }
+    // 未解析到具体方法时回退到类文档首页，避免误用整篇正文里无关 URL。
+    return RTCENGINE_WEB_API_BASE_URL;
 }
 /**
  * 为检索 fragment 解析可参考的官网 URL（去重、按优先级）。
- * 1. sync-manifest 落盘的 localPath → 官网 URL（rtcengine 等）
- * 2. L1 URL 映射行内目标 URL
- * 3. 本地文档正文中的官网链接
+ * 1. rtcengine/web/api.md：优先按 API 标题生成锚点 URL（例如 #.setCurrentSpeaker）
+ * 2. sync-manifest 落盘的 localPath → 官网 URL（rtcengine 等）
+ * 3. L1 URL 映射行内目标 URL
+ * 4. 本地文档正文中的官网链接
  */
 export function resolveFragmentDocUrls(source, content, fullSourceContent) {
     const normalized = source.replace(/\\/g, '/');
+    const rtcengineWebApiUrl = resolveRtcengineWebApiUrl(normalized, content);
+    if (rtcengineWebApiUrl) {
+        return [rtcengineWebApiUrl];
+    }
     const urls = [];
     const canonical = loadSourceUrlMap()[normalized];
     if (canonical)
@@ -87,22 +112,24 @@ export function resolveFragmentDocUrls(source, content, fullSourceContent) {
     }
     return urls.slice(0, 3);
 }
-/** 从 fragments 汇总去重后的参考链接列表（按 fragment 相关度排序） */
+/** 从 fragments 汇总去重后的参考链接列表（按 fragment 相关度排序）。
+ * 规则：每个 fragment 仅取一个参考链接（优先 doc_urls[0]），避免 1 个片段膨胀出多个 references。 */
 export function buildReferences(fragments) {
     const refs = [];
     const seen = new Set();
     for (const fragment of fragments) {
-        for (const url of fragment.doc_urls) {
-            if (seen.has(url))
-                continue;
-            seen.add(url);
-            refs.push({
-                rank: refs.length + 1,
-                title: fragment.title,
-                url,
-                source: fragment.source,
-            });
-        }
+        const primaryUrl = fragment.doc_urls.find((u) => isUsefulDocUrl(u));
+        if (!primaryUrl)
+            continue;
+        if (seen.has(primaryUrl))
+            continue;
+        seen.add(primaryUrl);
+        refs.push({
+            rank: refs.length + 1,
+            title: fragment.title,
+            url: primaryUrl,
+            source: fragment.source,
+        });
     }
     return refs;
 }

package/knowledge/search/exact-lookup.js

@@ -1,9 +1,16 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { normalizeUrlRowQuery, scoreUrlRow } from './url-row-scorer.js';
+import { getSourceFileContent } from '../content-loader.js';
+import { computeCommonSectionTokens, isUrlMappingSource, normalizeUrlRowQuery, queryMatchesSection, scoreUrlRow } from './url-row-scorer.js';
 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」），避免无关行涌入。
+ */
+const SECTION_MATCH_BASE_SCORE = 450;
 export const DOC_PATH_MAP = {
     android: {
         core_api: 'TRTCCloud',
@@ -289,43 +296,135 @@ export function runExactLookup(prompt, pool, norm) {
             }
         }
     }
-    // E6: chat urls boost（L1 URL 映射；错误码单独指向 urls/error-code.md）
-    if (!norm.product?.length || norm.product.includes('chat')) {
+    // E6: URL 映射文件 boost（L1；产品无关：任意 product 的 urls 均适用）
+    const hasUrlChunks = pool.some((c) => isUrlMappingSource(c.source));
+    if (hasUrlChunks) {
         if (/payload|usersig|authentication|auth|login|signature|登录|鉴权/i.test(prompt)) {
             for (const chunk of pool) {
-                if (chunk.source.includes('knowledge/chat/urls/')) {
-                    addBoost(chunk, 100, 'E6:chat-urls');
+                if (isUrlMappingSource(chunk.source)) {
+                    addBoost(chunk, 100, 'E6:urls');
                 }
             }
         }
         const errorCodeIntent = /错误码|\berror\s*code\b/i.test(prompt) || errorMatches.length > 0 || norm.searchIntent?.includes('error_code');
         if (errorCodeIntent) {
             for (const chunk of pool) {
-                if (chunk.source.includes('knowledge/chat/urls/error-code.md')) {
-                    addBoost(chunk, 180, 'E6:chat-error-code-url');
+                if (/\/error-code\.md$/i.test(chunk.source)) {
+                    addBoost(chunk, 180, 'E6:error-code-url');
                 }
             }
         }
-        // E7: URL map row match (chunk.title = Query column); boost multiple strong hits with pinned relaxation
+        // E7: URL 映射表行级匹配（chunk.title = 子问题列）
+        // 共享 scorer 按「REST 端点 > API token > 语义词对齐(IDF 加权)」打分。
+        // 支持 types 领域限定：上游推断出 types 时，优先 types 匹配的子文件行，
+        // 不匹配的行降权（避免跨域误命中，如 SDK 问题命中 restapi）。
         if (normalizeUrlRowQuery(prompt).replace(/\s+/g, '').length >= 2) {
             const candidates = [];
-            for (const chunk of pool) {
-                if (!chunk.source.includes('knowledge/chat/urls/'))
-                    continue;
-                if (!chunk.title.trim())
-                    continue;
+            const hasTypeFilter = Boolean(norm.searchIntent?.length);
+            // 预收集 urls 行的分组结构：按 source 读整个 md 源文件，解析 `##` 分组与每行归属。
+            // 分组粗筛对所有 urls 资源生效（产品无关），不针对 webhook.md 打补丁。
+            const urlChunks = pool.filter((c) => isUrlMappingSource(c.source) && c.title.trim());
+            const sectionByChunk = new Map(); // chunk.id -> 分组标题
+            const sectionsBySource = new Map(); // source -> 分组标题集合
+            const mdRowsBySource = new Map(); // source -> {行title -> 分组标题}
+            for (const source of new Set(urlChunks.map((c) => c.source))) {
+                let full = '';
+                try {
+                    full = getSourceFileContent(source);
+                }
+                catch {
+                    full = '';
+                }
+                let cur = '';
+                const rows = new Map();
+                const sections = new Set();
+                for (const line of full.split('\n')) {
+                    const h = line.match(/^#{2,3}\s+(.+)$/);
+                    if (h) {
+                        cur = h[1].trim();
+                        sections.add(cur);
+                        continue;
+                    }
+                    const row = line.match(/^\|\s*([^|]+?)\s*\|\s*`(https?:[^`]+)`/);
+                    if (row)
+                        rows.set(row[1].trim(), cur);
+                }
+                mdRowsBySource.set(source, rows);
+                sectionsBySource.set(source, sections);
+            }
+            for (const chunk of urlChunks) {
+                const section = mdRowsBySource.get(chunk.source)?.get(chunk.title);
+                if (section)
+                    sectionByChunk.set(chunk.id, section);
+            }
+            // 计算每个 source 的共有词（该文件所有分组都出现的词）
+            const commonTokensBySource = new Map();
+            for (const [source, sections] of sectionsBySource) {
+                commonTokensBySource.set(source, computeCommonSectionTokens([...sections]));
+            }
+            for (const chunk of urlChunks) {
                 const scoreResult = scoreUrlRow(prompt, chunk.title);
-                if (scoreResult.score > 0) {
-                    candidates.push({ chunk, score: scoreResult.score });
+                // types 领域限定：query types 与 chunk types 是否有交集
+                const typeMatch = hasTypeFilter
+                    ? (norm.searchIntent ?? []).some((t) => chunk.types.includes(t))
+                    : true;
+                // 分组粗筛：query 是否命中该 chunk 所在的分组。
+                // 命中分组 → 正常；未命中分组 → 降权（不排除，避免 query 与分组名匹配不准时误杀）。
+                const section = sectionByChunk.get(chunk.id);
+                const commonTokens = commonTokensBySource.get(chunk.source);
+                const sectionMatch = section && commonTokens
+                    ? queryMatchesSection(prompt, section, commonTokens)
+                    : true; // 无分组信息时不做粗筛（保持原行为）
+                // 高 scoreUrlRow 兜底：scoreUrlRow ≥ 700 是极强语义信号（query 2-gram 全覆盖），
+                // 此时不应被 sectionMatch 软降权压制。常见场景：短 query 如「群消息发送异常」
+                // 跟 section 标题「群组系统回调」共享字符少（仅「群」），sectionMatch 失败，
+                // 但 row title 本身完美匹配 user 意图，强行降权会让单聊 row 顶上。
+                const highConfidence = scoreResult.score >= 700;
+                // 分组语义命中基础分：scoreUrlRow 可能因「同义词/长句」对精确行打 0 分
+                // （如「群消息发送前回调」vs「群内发言之前回调」），但分组已语义命中，
+                // 给予基础分进入候选，避免该领域行被 score<=0 排除。
+                // 区别于旧的「所有 types 匹配行给 500」——只在分组命中时才给，避免无关行涌入。
+                if (scoreResult.score <= 0) {
+                    if (sectionMatch && typeMatch) {
+                        candidates.push({ chunk, score: SECTION_MATCH_BASE_SCORE, 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 });
             }
             candidates.sort((a, b) => b.score - a.score);
-            const strongCandidates = candidates
-                .filter(({ score }) => score >= 500)
+            // types 匹配的行加分（更优先）；不匹配的行轻度降权但仍可兜底召回。
+            // 避免上游 types 推断不准确时误杀正确文档（如「多端登录配置」被推断为 feature 而非 product）。
+            const typeScored = candidates
+                .map((c) => (c.typeMatch ? { ...c, score: c.score * 1.2 } : { ...c, score: c.score * 0.6 }))
+                .filter(({ score }) => score >= 500);
+            // 同分 row（典型：query「群消息撤回回调」时「撤回群消息」跟「单聊消息撤回」都 scoreUrlRow=660），
+            // 按「query 字符集被 row title 覆盖比例」再排，覆盖更高的 row 排前。
+            // 修 E7 boost idx=0 多 40 分的副作用：让字符集更精准的 row 拿 idx=0 → 300 分而不是 260 分。
+            const queryChars = new Set(prompt.match(/[\u4e00-\u9fff]/g) ?? []);
+            const charCoverage = (title) => {
+                if (queryChars.size === 0)
+                    return 0;
+                const titleChars = new Set(title.match(/[\u4e00-\u9fff]/g) ?? []);
+                let hit = 0;
+                for (const ch of queryChars)
+                    if (titleChars.has(ch))
+                        hit += 1;
+                return hit / queryChars.size;
+            };
+            const strongCandidates = typeScored
+                .sort((a, b) => {
+                // 优先按 typeScored score 降序；同分时按字符集覆盖率降序
+                if (b.score !== a.score)
+                    return b.score - a.score;
+                return charCoverage(b.chunk.title) - charCoverage(a.chunk.title);
+            })
                 .slice(0, 12);
             strongCandidates.forEach(({ chunk, score }, idx) => {
                 // 递减 boost：前两条更高，其余保持可召回但不过度压制 BM25
-                // token 匹配（600 分）至少给 150，确保子句拆分的行不被 BM25 原始分压掉
                 const amount = idx === 0
                     ? 200 + Math.min(score, 100)
                     : idx === 1

package/knowledge/search/intent-router.js

@@ -1,13 +1,29 @@
 /** 枚举/目录浏览意图 */
-const DISCOVERY_INTENT_RE = /有哪些|支持哪些|列一下|清单|目录|可用|全部|全量|对比|怎么选|选哪个|which\s+one|compare|comparison|what\s+(is|are)\s+available|what\s+.*\b(components?|features?|apis?)\b|available\s+(components?|features?|apis?)|supported\s+(components?|features?|apis?)|list\s+(all|available)|catalog/i;
+const DISCOVERY_INTENT_RE = /有哪些|支持哪些|列一下|列出来|清单|目录|可用|全部|全量|对比|怎么选|选哪个|哪些\s+(组件|功能|接口|能力)|which\s+one|compare|comparison|what\s+(is|are)\s+available|what\s+.*\b(components?|features?|apis?)\b|available\s+(components?|features?|apis?)|supported\s+(components?|features?|apis?)|list\s+(all|available)|catalog/i;
 /** 显式完整文档意图（用户明确说"完整/从零/step by step"） */
 const NARRATIVE_INTENT_RE = /从头到尾|一步一步|完整指南|完整教程|完整流程|完整接入|完整集成|完整的\s*(接入|集成|教程|指南|流程)|从零|全流程|接入指南|集成指南|step\s*by(?:\s*step)?|end[-\s]?to[-\s]?end|full\s+(guide|tutorial|flow|integration)|complete\s+(guide|tutorial|integration)|quick\s*start|getting\s*started/i;
-/** 强 point 信号：提到具体 API/错误码/参数 → 即使同时命中 narrative 关键词也优先走 point */
-const POINT_STRONG_SIGNAL_RE = /\b\d{5,7}\b|\bERR_[A-Z0-9_]+\b|\buse[A-Z]\w*\b|\b[A-Z][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*\b|\b(TRTC|TX)[A-Za-z0-9_]+\b|\bprops?\b|\b参数\b|\b事件\b|\b回调\b|\berror\s*code\b|错误码|怎么用|如何用|参数是什么/i;
+/** 强 point 信号：API token / 错误码 / 具体操作词 → 优先走 point。
+ *  注意 camelCase 检测必须区分大小写（不加 /i），否则 React/RoomKit 这类普通专有名词会被误判为 API。 */
+const POINT_STRONG_SIGNAL_RE = /\b\d{5,7}\b|\bERR_[A-Z0-9_]+\b|\buse[A-Z]\w*\b|\b[A-Z][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*\b|\b(TRTC|TX)[A-Za-z0-9_]+\b|\bprops?\b|参数|事件|回调|error\s*code|错误码|怎么用|如何用|怎么实现|如何实现|怎么做|怎么发送|怎么获取|怎么监听|怎么接收|怎么调用|如何发送|如何获取|如何监听|如何调用|参数是什么/i;
+/** 判断是否含 API token（驼峰/点号/错误码/数字），这是最强的 point 结构信号。
+ *  camelCase 检测区分大小写，避免把 React/RoomKit 等专有名词误判为 API。 */
+function hasApiToken(prompt) {
+    return /\b[a-z]+[A-Z][A-Za-z0-9_]*\b|\b[A-Z][A-Za-z0-9_]*\.[A-Za-z_]\w*\b|\b(TRTC|TX)[A-Za-z0-9_]+\b|\b\d{5,7}\b|\bERR_[A-Z0-9_]+\b/.test(prompt);
+}
 export function classifyRetrievalMode(prompt) {
-    if (NARRATIVE_INTENT_RE.test(prompt) && !POINT_STRONG_SIGNAL_RE.test(prompt))
+    // 优先级分层（结构化信号，不依赖句末问号）：
+    // 1) narrative 优先（保守）：用户明确要完整指南/从零/step by step，
+    //    即使带操作词（如"完整指南怎么做"）也走 narrative，因为意图是完整文档。
+    if (NARRATIVE_INTENT_RE.test(prompt) && !hasApiToken(prompt)) {
         return 'narrative';
-    if (DISCOVERY_INTENT_RE.test(prompt))
+    }
+    // 2) API token 是最强 point 信号：query 出现具体 API/错误码/数字 → point
+    if (hasApiToken(prompt)) {
+        return 'point';
+    }
+    // 3) discovery：枚举词 + 无具体操作词（"有哪些接口 怎么实现"这类混合问法 → 走 point）
+    if (DISCOVERY_INTENT_RE.test(prompt) && !POINT_STRONG_SIGNAL_RE.test(prompt)) {
         return 'discovery';
+    }
     return 'point';
 }

package/knowledge/search/l1-enrich.js

@@ -0,0 +1,159 @@
+/**
+ * l1-enrich.ts
+ *
+ * 当检索结果命中 chat/urls 的 L1 URL 映射行（内容只是官网链接，无本地正文）时，
+ * server 内部 fetch 目标文档并回填 markdown 正文，避免把"只有一行 URL"的结果交给 AI。
+ *
+ * 设计：
+ * - 复用 fetch-doc-content 的清洗能力（白名单 + gzip 解压 + md 转换 + 截断）。
+ * - 仅对"纯 URL 映射行"的 fragment 回填；已有本地正文的 fragment 不动。
+ * - 逐条 fetch，但并发受限 + 超时 + 缓存兜底，失败静默（保留原 URL 行）。
+ */
+import { fetchDocContent } from '../../utils/fetch-doc-content.js';
+import { buildReferences } from '../doc-url-resolver.js';
+import { partitionFragments } from './search-core.js';
+import { isUrlMappingSource } from './url-row-scorer.js';
+/** 从 fragment 中取第一个可 fetch 的官方 URL */
+function primaryDocUrl(fragment) {
+    const urls = fragment.doc_urls ?? [];
+    return urls[0];
+}
+/**
+ * 单条 fragment 回填：
+ * 拉取到正文后，content 替换为官网 markdown，source 改写为官网 URL。
+ * 这样已回填片段不再命中 `chat/urls/` 的 L1 判定，AI 会把它当本地正文（L0）直接作答，无需再 fetch。
+ */
+async function enrichFragment(fragment, maxChars) {
+    const url = primaryDocUrl(fragment);
+    if (!url)
+        return null;
+    const result = await fetchDocContent(url, { maxChars });
+    if (!result)
+        return null;
+    return {
+        ...fragment,
+        content: result.markdown,
+        source: url,
+    };
+}
+/** 服务端 L1 领域类型：query 为客户端 SDK 意图时跳过，避免给 SDK 问题回填 REST/回调正文。
+ * 注意：'product' 不在集合中——产品概念/全局方案（如「内网代理实现方案」）跨平台适用，
+ * 客户端 query 命中 product 文档应正常 enrich（如 web SDK 用户搜「内网代理」应拿到正文）。
+ */
+const SERVER_SIDE_TYPES = new Set(['server_api', 'webhook']);
+/**
+ * 判定 L1 行是否属于「query 主领域」，用于限领域回填（避免 token 浪费在无关领域）。
+ * - query 有 frameworks（客户端 SDK 意图）：只回填 sdk/api 等客户端行，跳过 server_api/webhook/product。
+ * - query 无 frameworks（服务端/跨域意图）：只回填服务端行，跳过 sdk/api 客户端行。
+ * 语言无关、产品无关。
+ */
+function isInQueryDomain(fragment, queryFrameworks) {
+    if (queryFrameworks?.length) {
+        // 客户端意图：跳过服务端领域行
+        if (fragment.types.some((t) => SERVER_SIDE_TYPES.has(t)))
+            return false;
+        return true;
+    }
+    // 无 frameworks：跨域/服务端意图，跳过纯客户端 sdk/api 行
+    if (fragment.types.includes('sdk') || fragment.types.includes('api'))
+        return false;
+    return true;
+}
+/**
+ * 全部主领域 L1 行回填成功后，重写 message：
+ * 原始 message 是在回填前由 searchKnowledge 生成的（可能提示"需抓官网文档"），
+ * 回填后 source 已指向官网正文，应改为"直接基于正文作答"，避免 AI 被旧话术误导再去抓官网。
+ * 保留原 message 中 finalize_answer / submit_feedback 等必要工作流指令。
+ */
+function buildEnrichedMessage(response) {
+    const original = response.message ?? '';
+    const tail = original.includes('Final answer drafted')
+        ? original.slice(original.indexOf('Final answer drafted'))
+        : '';
+    return `Official content has been fetched and provided below; answer directly. ${tail}`;
+}
+/**
+ * 对 searchKnowledge 的结果做 L1 内容回填（异步，不影响同步检索主流程）。
+ * 返回回填后的新 response 副本。
+ *
+ * 修复（与 V3 `applySingleTopicTrim` 同步改造）：
+ * - 跨领域 L1 行 filter 提到早 return 之前，覆盖「无主领域 L1 行可 enrich」分支（A: 无 L1 / B: L1 全跨领域 / C: L1 全已回填）。
+ *   修复前 B case 早 return，跨领域 L1 行残留 + message 假 "fetch 提示"，LLM 拿到 URL 表行 content 无法作答。
+ * - targets 用 origIndex 跟踪原数组位置，确保回填后 fragments/references 仍按原顺序、保持一致。
+ */
+export async function enrichL1Fragments(response, opts) {
+    const maxChars = opts?.maxChars ?? 50000;
+    const concurrency = opts?.concurrency ?? 3;
+    const queryFrameworks = response.query?.frameworks;
+    const originalFragments = response.fragments ?? [];
+    // 公共 filter：跨领域 L1 行一律过滤（无论是否走 enrich 路径）
+    const afterFilter = originalFragments.filter((f) => {
+        if (!isUrlMappingSource(f.source))
+            return true;
+        // L1 行：已回填（source 已是官网 URL）或属于主领域 → 保留；否则过滤
+        return /^https?:\/\//i.test(f.source) || isInQueryDomain(f, queryFrameworks);
+    });
+    // 收集需要回填的 L1 fragment（仅纯 URL 映射行 + 属于 query 主领域 + 未回填）
+    // 关键：用 origIndex 跟踪原数组位置，enrich 后能正确回填，避免与公共 filter 后的 fragments 错位
+    const targets = [];
+    for (let i = 0; i < originalFragments.length; i += 1) {
+        const f = originalFragments[i];
+        if (isUrlMappingSource(f.source)
+            && !/^https?:\/\//i.test(f.source) // 未回填
+            && isInQueryDomain(f, queryFrameworks) // 属于主领域
+        ) {
+            targets.push({ f, origIndex: i });
+        }
+    }
+    // 无主领域 L1 行可 enrich（A: 无 L1 / B: L1 全跨领域 / C: L1 全已回填）
+    // 仍按公共 filter 后的 fragments 返回，并重建 references 保持 fragments/references 一致
+    if (targets.length === 0) {
+        const refs = afterFilter.length > 0 ? buildReferences(afterFilter) : [];
+        return {
+            ...response,
+            fragments: afterFilter,
+            meta: { ...response.meta, references: refs },
+        };
+    }
+    // 并发受限地逐条回填：仅成功拉取到正文的 fragment 才写入 Map
+    const enriched = new Map();
+    let cursor = 0;
+    const worker = async () => {
+        while (cursor < targets.length) {
+            const { f, origIndex } = targets[cursor];
+            cursor += 1;
+            const enrichedFragment = await enrichFragment(f, maxChars);
+            if (enrichedFragment)
+                enriched.set(origIndex, enrichedFragment);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, targets.length) }, () => worker()));
+    // 组装新 fragments：
+    // - 基于 originalFragments 替换已回填的 L1 行
+    // - 跨领域 L1 行再次过滤（保险，理论上已被 afterFilter 过滤）
+    const newFragments = originalFragments
+        .map((f, i) => enriched.get(i) ?? f)
+        .filter((f) => {
+        if (!isUrlMappingSource(f.source))
+            return true;
+        return /^https?:\/\//i.test(f.source) || isInQueryDomain(f, queryFrameworks);
+    });
+    // 基于回填后的新 fragments 重建 references，
+    // 使 meta.references 与 fragments 的 source 保持一致（回填后 source=官网 URL，不再指向 chat/urls 本地路径）。
+    const references = newFragments.length > 0 ? buildReferences(newFragments) : [];
+    // 仅当回填前「有 L1 行且无本地正文」（对应 buildAgentMessage 的"需抓官网"分支）且本次全部回填成功时，
+    // 重写 message 为「已提供官网正文」。用结构判断（而非正则匹配 message 文案），更稳、不随文案变化失效。
+    const { urlMapping, localDoc } = partitionFragments(originalFragments);
+    const originalNeedsFetch = urlMapping.length > 0 && localDoc.length === 0;
+    const allEnriched = originalNeedsFetch && enriched.size > 0 && enriched.size === targets.length;
+    const message = allEnriched ? buildEnrichedMessage(response) : response.message;
+    return {
+        ...response,
+        fragments: newFragments,
+        message,
+        meta: {
+            ...response.meta,
+            references,
+        },
+    };
+}

package/knowledge/search/query-normalizer.js

@@ -37,7 +37,6 @@ const BASE_QUERY_NORMALIZATION = {
         messages: ['消息', 'chat', 'conversation'],
         group: ['群组', '群聊', 'group chat'],
         c2c: ['单聊', 'one-to-one', 'single chat'],
-        webhook: ['回调', 'webhook', 'callbacks'],
         avchatroom: ['直播群'],
         priority: ['重要消息', '优先级'],
         reliability: ['消息可靠性'],
@@ -104,12 +103,20 @@ export function normalizeQueryPrompt(prompt) {
     const config = loadQueryNormalizationConfig();
     const terms = new Set(prompt.split(/\s+/).filter(Boolean));
     const promptLower = prompt.toLowerCase();
+    // 纯 EN 提问时跳过 CJK 注入：query expansion 的 CJK 翻译（群组/群聊/回调 等）
+    // 会进入 qCjk 触发「混合 query 只走 CJK 路径」分支，导致纯 EN title 行（CJK 路径
+    // 返回 0）失去 E7 boost，BM25 排名错误。典型回归：webhook 行「X webhook」全部
+    // 被「Before create group webhook」抢首位（+7 row top1 退化）。
+    // zh 端几乎都是 CJK 提问 → isPureEn=false → 行为完全不变。
+    const isPureEn = !hasCjk(prompt);
     let appendedCount = 0;
     const tryAppend = (tokens) => {
         for (const token of tokens) {
             if (appendedCount >= MAX_APPEND_TOKENS)
                 return;
             if (!terms.has(token)) {
+                if (isPureEn && hasCjk(token))
+                    continue;
                 terms.add(token);
                 appendedCount += 1;
             }

package/knowledge/search/search-core.js

@@ -87,11 +87,25 @@ export function postProcess(ranked, chunksById, limit, opts) {
             // 首条不设分数截止，至少保证 1 条返回
         }
         else if (!isPinnedUrlRow) {
-            // 分数衰减到 top 的 5% 以下时停止，不硬填到 limit
-            // chat/urls 的行级精确命中（E7）不受该规则截断，保证多子主题可并行返回
             const topScore = fragments[0].score;
-            if (topScore > 0 && item.score < topScore * 0.05)
-                break;
+            // 方案A：分数断崖截断。
+            // 当已有 E7 精确命中行（pinned url-row）时，后续非 pinned 行若跌破 Top1 的 20%，
+            // 视为「Top1 已精确命中、后续多为泛匹配噪声」，提前截断，避免凑满 limit 返回冗余。
+            // 无 E7 命中时不触发（此时答案依赖 best-practice/本地文档，需完整保留）。
+            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% → 断崖截断
+                // 阈值取 35%（非 20%）：best-practice 泛匹配分数常在 Top1 的 20%~35% 区间，
+                // 用 35% 才能拦住「Top1 精确命中后仍返回一堆无关 best-practice」的冗余。
+                if (hasPinnedRow && item.score < topScore * 0.35)
+                    break;
+            }
         }
         const aggregated = Boolean(chunk.aggregable) && fragments.length > 0 && fragments[0].source === chunk.source;
         fragments.push(buildFragment(chunk, item.score, fragments.length + 1, aggregated));
@@ -100,9 +114,14 @@ export function postProcess(ranked, chunksById, limit, opts) {
     }
     return fragments;
 }
+/** 产品无关的 URL 映射行判定：knowledge/<product>/urls/.../xxx.md */
 export function isUrlMappingSource(source) {
+    return /knowledge\/[a-z0-9_-]+\/urls\/.+\.md$/i.test(source.replace(/\\/g, '/'));
+}
+/** 产品无关地提取 URL 映射行的「子文件 kind」（如 sdk/web、error-code）；非映射行返回 null */
+export function extractUrlMappingKind(source) {
     const normalized = source.replace(/\\/g, '/');
-    const match = normalized.match(/knowledge\/chat\/urls\/(.+\.md)$/);
+    const match = normalized.match(/knowledge\/[a-z0-9_-]+\/urls\/(.+\.md)$/);
     if (!match)
         return null;
     return match[1].replace(/\.md$/, '').replace(/\/index$/, '');
@@ -118,7 +137,7 @@ export function partitionFragments(fragments) {
             localDoc.push(fragment);
         }
     }
-    const urlMappingKinds = [...new Set(urlMapping.map((f) => isUrlMappingSource(f.source)).filter(Boolean))];
+    const urlMappingKinds = [...new Set(urlMapping.map((f) => extractUrlMappingKind(f.source)).filter(Boolean))];
     return { urlMapping, localDoc, urlMappingKinds };
 }
 export function isNarrativeSource(source) {