@tencent-rtc/mcp 1.6.8 → 1.7.1

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# CHANGELOG
+
+## 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
+- Added and synchronized best-practice docs across product domains including Chat / Call / Live / Room to improve knowledge coverage.
+
+### Changed
+- Continued refactoring of the bilingual retrieval pipeline, including query normalization, intent routing, candidate filtering, and exact-match strategies.
+- Improved recall and ranking for best-practice and URL-based documents to increase answer usability and stability.
+- Improved `search_trtc_knowledge` definitions and answer constraints for better readability and executability.
+
+### Fixed
+- Fixed off-topic retrieval in some complex queries, reducing high-score false-positive hits.
+
+## Version 1.6.6 @2026.07.18
+
+### 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/README.md

@@ -1,45 +1,27 @@
-## Tencent SDK Model Context Protocol (MCP) Server for Cursor IDE
-
-This repository provides a CLI-based Model Context Protocol (MCP) server that exposes Tencent SDK documentation and Tencent API resources to LLM-powered tools.
-This improves the LLM AI Agent's ability to understand and interact with Tencent's SDKs and APIs.
+## Tencent RTC SDK MCP Server Guide
 
+This repository provides a CLI-based Model Context Protocol (MCP) Server that exposes Tencent RTC SDK documentation and API resources to LLM tools, helping AI agents deliver more accurate implementation guidance and integration support.
 
 ## Features
 
-- MCP server exposing tools for interacting with Tencent via JSON-RPC over STDIN/STDOUT.
-- MCP server supports SSE Mode by supplying `HTTP_PORT` environment variable.
-- Retrieve official Tencent SDK documentation (HTML → Markdown) for:
-  - Languages: JavaScript, Java, Swift, Objective-C, Kotlin.
-  - API reference sections: configuration, calls function.
-- Retrieve official Tencent TUICallKit SDK documentation (HTML → Markdown) for:
-  - TUICallKit SDK languages: JavaScript, Kotlin, Swift.
-  - TUICallKit SDK topics: configuration, calls function.
-- Retrieve official Tencent ChatUIKit documentation (HTML → Markdown) for:
-  - ChatUIKit SDK languages: JavaScript, Kotlin, Swift.
-  - ChatUIKit SDK topics: configuration, chat function.
-- Converts remote HTML articles to Markdown using `jsdom` and `turndown` for consistent documentation formatting.
-- Input validation via Zod schemas for all tool parameters, ensuring robust error handling.
-- Extensible tool definitions leveraging the Model Context Protocol SDK (`@modelcontextprotocol/sdk`) with `McpServer` and `StdioServerTransport`.
-
-
-## Prerequisites
-- Node.js (>= 18) and npm
-- Cursor IDE with MCP support
-
+- **Efficient retrieval**: Supports Tencent RTC documentation retrieval for fast access to official references and best practices.
+- **Broad coverage**: Covers Chat (IM), Call, Live, Room, RTCEngine (TRTC SDK), and TIMPush domains.
+- **Intelligent routing**: Supports product/platform intent disambiguation and prompts for missing platform/framework information when needed.
+- **Integration-friendly**: In addition to documentation Q&A, provides integration entry points for Web / Android / iOS / Flutter, including UI-based integration directions.
+- **Reliable source**: Grounded in official Tencent Cloud materials to improve answer reliability and implementation readiness.
+- **Wide compatibility**: Exposes MCP capabilities over STDIN/STDOUT JSON-RPC, compatible with MCP clients such as Cursor / Codex / Claude / CodeBuddy.
+- **Quick start**: Run with `npx` and get started with minimal setup.
 
-## How To Use
-To set up the @tencent-rtc/mcp MCP Server, follow these steps:
-
-- Step1: Installation.
-
-```
-npx -y @tencent-rtc/mcp
-```
+## Requirements
+- Node.js (>= 18) and npm
+- An MCP-capable IDE
 
+## Usage
+### Standard setup flow
 
-- Step2: In your Cursor project, create or open the `.cursor/mcp.json` or `~/.cursor/mcp.json` files and add your config.
+- Step1: In your Cursor project, create or edit `.cursor/mcp.json` or `~/.cursor/mcp.json` and add the following configuration.
 
-```javascript
+```json
 {
   "mcpServers": {
     "tencent-rtc": {
@@ -53,16 +35,53 @@ npx -y @tencent-rtc/mcp
   }
 }
 ```
-When you save the file, a notification is displayed. In the prompt, click **Enable**.
+After saving, a prompt appears. Click **Enable** in the prompt.
 
 ![mcp-server-prompt](https://web.sdk.qcloud.com/im/assets/images/mcp-server-prompt-en.png)
 
-- Step3: Navigate to **Cursor Settings** (the gear icon in top right corner) -> **MCP**, and check if tencentcloud-sdk-mcp server is enabled.
+- Step2: Go to **Cursor Settings** (top-right gear icon) -> **MCP**, and make sure `tencent-rtc` is enabled.
 
 ![cursor-setting](https://web.sdk.qcloud.com/im/assets/images/cursor-setting-en.png)
 
+- Step3: Describe your requirements directly in the IDE, and let the AI complete implementation or troubleshooting based on Tencent Cloud SDK documentation.
+
+### Optional: global install
+
+If you want quick global invocation locally, run:
+
+```bash
+npx -y @tencent-rtc/mcp
+```
+
+## Changelog
+
+> 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
+- Added and synchronized best-practice docs across product domains including Chat / Call / Live / Room to improve knowledge coverage.
+
+#### Changed
+- Continued refactoring of the bilingual retrieval pipeline, including query normalization, intent routing, candidate filtering, and exact-match strategies.
+- Improved recall and ranking for best-practice and URL-based documents to increase answer usability and stability.
+- Improved `search_trtc_knowledge` definitions and answer constraints for better readability and executability.
+
+#### Fixed
+- Fixed off-topic retrieval in some complex queries, reducing high-score false-positive hits.
 
-Step4: Ask the AI agent to build your Tencentcloud sdk app for you by describing the functionality yourself or by using a sample prompt.
+### Version 1.6.6 @2026.07.18
 
-> [!WARNING]
-Make sure to use the Agent mode. Depending on your Cursor rules, you may also need to explicitly ask the AI agent to use the Tencentcloud sdk-mcp server.
+#### Added
+- Added support for `get_native_live_uikit_integration`, enabling LiveKit(Android/iOS) UI integration guidance.

package/knowledge/build-index.js

@@ -3,11 +3,13 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import { chunkMarkdown, toManifestChunk } from './chunker.js';
 import { buildDocSourceUrlMap } from './doc-url-resolver.js';
+import { mergePathMetaWithFrontmatter, resolveFrontmatterMeta } from './frontmatter-meta.js';
 import { inferPathMeta } from './path-meta.js';
+import { loadChunkingPolicy, resolveChunkingRule, resolvePolicyFilePath } from './chunking-policy.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-// Build-time: writes index into dist/resource/index/.
+// 构建期写入索引到 dist/resource/index/：
 //   dist/knowledge/ → ../resource/ → dist/resource/
-// Must run AFTER scripts/copy-resource.js, otherwise the target dir does not exist.
+// 必须在 scripts/copy-resource.js 之后执行，否则目标目录不存在。
 const RESOURCE_ROOT = path.resolve(__dirname, '../resource');
 function walkMarkdownFiles(dir, baseRel) {
     if (!fs.existsSync(dir))
@@ -45,11 +47,32 @@ export function buildKnowledgeIndex() {
         ...walkMarkdownFiles(path.join(RESOURCE_ROOT, 'integration'), 'integration'),
     ];
     const chunks = [];
+    let frontmatterFileCount = 0;
+    let frontmatterMergedCount = 0;
+    let frontmatterParseErrorCount = 0;
+    const chunkingPolicyPath = resolvePolicyFilePath(__dirname);
+    const chunkingPolicy = loadChunkingPolicy(chunkingPolicyPath);
     for (const source of sources) {
         const abs = path.join(RESOURCE_ROOT, source);
-        const content = fs.readFileSync(abs, 'utf-8');
-        const meta = inferPathMeta(source);
-        chunks.push(...chunkMarkdown(source, content, meta).map(toManifestChunk));
+        const rawContent = fs.readFileSync(abs, 'utf-8');
+        // Phase A（兼容期）：frontmatter 优先，未声明字段继续走路径推断 fallback。
+        const pathMeta = inferPathMeta(source);
+        const fm = resolveFrontmatterMeta(rawContent);
+        const meta = mergePathMetaWithFrontmatter(pathMeta, fm.frontmatterMeta, fm.overrideFields);
+        if (fm.hasFrontmatter)
+            frontmatterFileCount += 1;
+        if (meta.meta_source === 'merged')
+            frontmatterMergedCount += 1;
+        if (fm.parseError) {
+            frontmatterParseErrorCount += 1;
+            console.warn(`[build-knowledge-index] frontmatter parse failed: ${source} - ${fm.parseError}`);
+        }
+        const policyRule = resolveChunkingRule(source, chunkingPolicy);
+        chunks.push(...chunkMarkdown(source, fm.content, meta, {
+            baseOffset: fm.contentOffset,
+            policyRule,
+            defaultSplitTokenThreshold: chunkingPolicy.default.split_token_threshold,
+        }).map(toManifestChunk));
     }
     const indexDir = path.join(RESOURCE_ROOT, 'index');
     fs.mkdirSync(indexDir, { recursive: true });
@@ -68,5 +91,6 @@ export function buildKnowledgeIndex() {
     if (fs.existsSync(staleSearchIndex)) {
         fs.unlinkSync(staleSearchIndex);
     }
-    console.warn(`build-knowledge-index: ${chunks.length} chunks (manifest-lite) from ${sources.length} files`);
+    console.warn(`build-knowledge-index: ${chunks.length} chunks (manifest-lite) from ${sources.length} files; `
+        + `frontmatter files=${frontmatterFileCount}, merged=${frontmatterMergedCount}, parse_errors=${frontmatterParseErrorCount}`);
 }

package/knowledge/chunker.js

@@ -42,6 +42,34 @@ function isFaqLike(source, content) {
 function shouldForceSectionSplit(source, meta) {
     return source.endsWith('unsupported-features.md') || meta.doc_kind === 'unsupported_summary';
 }
+function isBestPracticeSource(source) {
+    return /\/best-practice\//i.test(source.replace(/\\/g, '/'));
+}
+const BEST_PRACTICE_SINGLE_CHUNK_MAX_TOKENS = 4096;
+const LEGACY_SINGLE_CHUNK_CHAR_THRESHOLD = 2048;
+function estimateTextTokens(text) {
+    let tokens = 0;
+    for (const ch of text) {
+        tokens += /[A-Za-z]/.test(ch) ? 0.5 : 1;
+    }
+    return tokens;
+}
+function estimateMarkdownTokens(content) {
+    let tokens = 0;
+    let cursor = 0;
+    const codeBlockRE = /```[\s\S]*?```/g;
+    for (const match of content.matchAll(codeBlockRE)) {
+        const start = match.index ?? cursor;
+        const end = start + match[0].length;
+        tokens += estimateTextTokens(content.slice(cursor, start));
+        tokens += match[0].length * 1.3;
+        cursor = end;
+    }
+    if (cursor < content.length) {
+        tokens += estimateTextTokens(content.slice(cursor));
+    }
+    return tokens;
+}
 function isChatUrlMapping(source) {
     return /knowledge\/chat\/urls\/.+\.md$/i.test(source.replace(/\\/g, '/'));
 }
@@ -86,7 +114,7 @@ function extractKeyPhrases(title, body) {
         .slice(0, 8);
     return [...new Set(phrases)];
 }
-function buildChunk(meta, source, title, body, id, char_start, char_end) {
+function buildChunk(meta, source, title, body, id, char_start, char_end, extra) {
     const api_names = extractApiNames(body);
     const key_phrases = extractKeyPhrases(title, body);
     return {
@@ -101,6 +129,8 @@ function buildChunk(meta, source, title, body, id, char_start, char_end) {
         doc_kind: meta.doc_kind,
         capability_status: meta.capability_status,
         retrievable_scope: meta.retrievable_scope,
+        meta_source: meta.meta_source,
+        meta_override_fields: meta.meta_override_fields,
         title,
         source,
         content: body,
@@ -109,14 +139,15 @@ function buildChunk(meta, source, title, body, id, char_start, char_end) {
         ...(api_names.length ? { api_names } : {}),
         ...(containsCodeBlock(body) ? { contains_code: true } : {}),
         ...(key_phrases.length ? { key_phrases } : {}),
+        ...(extra ?? {}),
         char_start,
         char_end,
     };
 }
-function parseUrlMappingRows(content) {
+function parseUrlMappingRows(content, baseOffset) {
     const lines = content.split('\n');
     let sectionTitle = '';
-    let offset = 0;
+    let offset = baseOffset;
     const rows = [];
     for (const line of lines) {
         const lineStart = offset;
@@ -144,8 +175,8 @@ function parseUrlMappingRows(content) {
     }
     return rows;
 }
-function chunkUrlMapping(source, content, meta) {
-    const rows = parseUrlMappingRows(content);
+function chunkUrlMapping(source, content, meta, baseOffset) {
+    const rows = parseUrlMappingRows(content, baseOffset);
     if (rows.length === 0) {
         return [];
     }
@@ -157,33 +188,70 @@ function chunkUrlMapping(source, content, meta) {
         return buildChunk(meta, source, row.label, body, `${baseSlug}#${headingSlug}`, row.lineStart, row.lineEnd);
     });
 }
-export function chunkMarkdown(source, content, meta) {
+export function chunkMarkdown(source, content, meta, options) {
     const chunks = [];
     const baseSlug = sourceSlug(source);
-    if (isChatUrlMapping(source)) {
-        const urlChunks = chunkUrlMapping(source, content, meta);
+    const baseOffset = options?.baseOffset ?? 0;
+    const policyRule = options?.policyRule;
+    if (isChatUrlMapping(source) || policyRule?.strategy === 'by_row') {
+        const urlChunks = chunkUrlMapping(source, content, meta, baseOffset);
         if (urlChunks.length > 0) {
             return urlChunks;
         }
     }
     const forceSectionSplit = shouldForceSectionSplit(source, meta);
-    if (content.length < 2048 && !forceSectionSplit) {
-        const { body, char_start, char_end } = trimSliceOffsets(content, 0);
+    const isBestPractice = isBestPracticeSource(source);
+    const estimatedTokenCount = estimateMarkdownTokens(content);
+    const defaultSplitThreshold = options?.defaultSplitTokenThreshold ?? LEGACY_SINGLE_CHUNK_CHAR_THRESHOLD;
+    const singleChunkMaxTokens = policyRule?.max_tokens
+        ?? (isBestPractice ? BEST_PRACTICE_SINGLE_CHUNK_MAX_TOKENS : undefined);
+    const shouldSingleChunk = policyRule?.strategy === 'single_chunk_per_file'
+        || (isBestPractice && !policyRule?.strategy);
+    if (shouldSingleChunk && singleChunkMaxTokens !== undefined && estimatedTokenCount <= singleChunkMaxTokens) {
+        const { body, char_start, char_end } = trimSliceOffsets(content, baseOffset);
         if (!body)
             return chunks;
         chunks.push(buildChunk(meta, source, pathBasename(source), body, `${baseSlug}#full`, char_start, char_end));
         return chunks;
     }
-    const level = forceSectionSplit ? 3 : (isFaqLike(source, content) ? 3 : 2);
+    if (!shouldSingleChunk
+        && !forceSectionSplit
+        && content.length < (policyRule?.split_token_threshold ?? defaultSplitThreshold)) {
+        const { body, char_start, char_end } = trimSliceOffsets(content, baseOffset);
+        if (!body)
+            return chunks;
+        chunks.push(buildChunk(meta, source, pathBasename(source), body, `${baseSlug}#full`, char_start, char_end));
+        return chunks;
+    }
+    const fallbackStrategy = policyRule?.split_fallback ?? policyRule?.strategy ?? 'by_h2';
+    const level = forceSectionSplit
+        ? 3
+        : fallbackStrategy === 'by_h3'
+            ? 3
+            : (isFaqLike(source, content) ? 3 : 2);
     const sections = splitByHeading(content, level);
     for (const section of sections) {
-        const { body, char_start, char_end } = trimSliceOffsets(section.raw, section.start);
+        const { body, char_start, char_end } = trimSliceOffsets(section.raw, section.start + baseOffset);
         if (!body)
             continue;
         const headingSlug = slugify(section.title);
-        chunks.push(buildChunk(meta, source, section.title, body, `${baseSlug}#${headingSlug}`, char_start, char_end));
+        const fallbackMeta = shouldSingleChunk && singleChunkMaxTokens !== undefined && estimatedTokenCount > singleChunkMaxTokens
+            ? {
+                split_reason: 'exceed_token_threshold',
+                original_file_token_count: Math.ceil(estimatedTokenCount),
+                aggregable: policyRule?.split_aggregable ?? isBestPractice,
+                parent_h2: section.title,
+            }
+            : undefined;
+        chunks.push(buildChunk(meta, source, section.title, body, `${baseSlug}#${headingSlug}`, char_start, char_end, fallbackMeta));
     }
-    return chunks.length > 0 ? chunks : chunkMarkdown(source, content.slice(0, 2048), meta);
+    return chunks.length > 0
+        ? chunks
+        : chunkMarkdown(source, content.slice(0, defaultSplitThreshold), meta, {
+            baseOffset,
+            policyRule,
+            defaultSplitTokenThreshold: defaultSplitThreshold,
+        });
 }
 export function toManifestChunk(chunk) {
     const { content: _content, ...manifestChunk } = chunk;

package/knowledge/chunking-policy.js

@@ -0,0 +1,100 @@
+import fs from 'fs';
+import path from 'path';
+import * as yaml from 'js-yaml';
+const DEFAULT_POLICY = {
+    default: {
+        strategy: 'by_h2',
+        split_token_threshold: 2048,
+    },
+    rules: [
+        {
+            path_prefix: 'knowledge/chat/best-practice/',
+            strategy: 'single_chunk_per_file',
+            max_tokens: 4096,
+            hard_max_tokens: 8192,
+            split_fallback: 'by_h2',
+            split_aggregable: true,
+        },
+        {
+            path_prefix: 'knowledge/chat/urls/',
+            strategy: 'by_row',
+        },
+    ],
+};
+function toPolicy(raw) {
+    if (!raw || typeof raw !== 'object')
+        return DEFAULT_POLICY;
+    const root = raw;
+    const policyObj = (root.chunking_policy && typeof root.chunking_policy === 'object')
+        ? root.chunking_policy
+        : null;
+    if (!policyObj)
+        return DEFAULT_POLICY;
+    const rawDefault = (policyObj.default && typeof policyObj.default === 'object')
+        ? policyObj.default
+        : {};
+    const strategy = rawDefault.strategy === 'by_h3' ? 'by_h3' : 'by_h2';
+    const splitThreshold = typeof rawDefault.split_token_threshold === 'number'
+        ? rawDefault.split_token_threshold
+        : 2048;
+    const rules = Array.isArray(policyObj.rules)
+        ? policyObj.rules
+            .map((item) => {
+            if (!item || typeof item !== 'object')
+                return null;
+            const rule = item;
+            const pathPrefix = typeof rule.path_prefix === 'string' ? rule.path_prefix.trim() : '';
+            const strategyValue = typeof rule.strategy === 'string' ? rule.strategy : '';
+            if (!pathPrefix || !['single_chunk_per_file', 'by_h2', 'by_h3', 'by_row'].includes(strategyValue)) {
+                return null;
+            }
+            return {
+                path_prefix: pathPrefix,
+                strategy: strategyValue,
+                max_tokens: typeof rule.max_tokens === 'number' ? rule.max_tokens : undefined,
+                hard_max_tokens: typeof rule.hard_max_tokens === 'number' ? rule.hard_max_tokens : undefined,
+                split_fallback: rule.split_fallback === 'by_h3' ? 'by_h3' : (rule.split_fallback === 'by_h2' ? 'by_h2' : undefined),
+                split_aggregable: typeof rule.split_aggregable === 'boolean' ? rule.split_aggregable : undefined,
+                split_token_threshold: typeof rule.split_token_threshold === 'number' ? rule.split_token_threshold : undefined,
+            };
+        })
+            .filter((rule) => Boolean(rule))
+        : [];
+    return {
+        default: {
+            strategy,
+            split_token_threshold: splitThreshold,
+        },
+        rules,
+    };
+}
+function extractYamlBlock(markdown) {
+    const match = markdown.match(/```ya?ml\n([\s\S]*?)\n```/i);
+    return match?.[1] ?? null;
+}
+export function loadChunkingPolicy(policyFilePath) {
+    if (!fs.existsSync(policyFilePath)) {
+        return DEFAULT_POLICY;
+    }
+    try {
+        const markdown = fs.readFileSync(policyFilePath, 'utf-8');
+        const yamlBlock = extractYamlBlock(markdown);
+        if (!yamlBlock)
+            return DEFAULT_POLICY;
+        const parsed = yaml.load(yamlBlock);
+        return toPolicy(parsed);
+    }
+    catch {
+        return DEFAULT_POLICY;
+    }
+}
+export function resolveChunkingRule(source, policy) {
+    const normalized = source.replace(/\\/g, '/');
+    const matched = policy.rules
+        .filter((rule) => normalized.startsWith(rule.path_prefix.replace(/\\/g, '/')))
+        .sort((a, b) => b.path_prefix.length - a.path_prefix.length);
+    return matched[0];
+}
+export function resolvePolicyFilePath(knowledgeDirname) {
+    return path.resolve(knowledgeDirname, '../../../chunking-policy.md');
+}

package/knowledge/content-loader.js

@@ -4,9 +4,9 @@ import { fileURLToPath } from 'url';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const fileCache = new Map();
 function resolveResourceRoot() {
-    // Runtime md source dir (sibling of knowledge/):
-    //   npm package: <pkg>/knowledge/  →  <pkg>/resource/
-    //   local:       dist/knowledge/   →  dist/resource/ (populated by copy-resource.js at build time)
+    // 运行时读 md 源目录（与 knowledge/ 同级的 resource/）：
+    //   npm 包：<pkg>/knowledge/  →  <pkg>/resource/
+    //   本地：  dist/knowledge/   →  dist/resource/（依赖 build 时 copy-resource.js）
     return path.resolve(__dirname, '../resource');
 }
 function readSourceFile(source) {

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