@tencentcloud/sdk-mcp 1.6.8 → 1.7.1

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# CHANGELOG
+
+## Version 1.7.1 @2026.08.11
+
+### 新增
+- 新增检索前置归一化：基于 prompt 真值对 `product` / `frameworks` 做归一化，解决 agent 推理错误导致的检索偏差。
+
+### 变更
+- 优化 `search_trtc_knowledge` 输出契约：移除 "1-2 sentence per subsection" 等压缩性措辞，改为输出完整合成答案。
+
+### 修复
+- 修复 "安卓 Web TRTC" 等 prompt 下 agent 误传双 product / 双 frameworks 时未按 prompt 真值校正的问题。
+
+## Version 1.7.0 @2026.08.02
+
+### 新增
+- 补充并同步 Chat / Call / Live / Room 等产品域最佳实践文档，增强知识覆盖范围。
+
+### 变更
+- 持续重构双语检索链路，优化 query 归一化、意图路由、候选过滤与精确命中策略。
+- 优化最佳实践与 URL 类文档的召回与排序，提升问答结果可用性与稳定性。
+- 优化 `search_trtc_knowledge` 相关定义与答复约束，提升回答可读性与可执行性。
+
+### 修复
+- 修复复杂问法下部分检索结果偏题的问题，降低高分误召回概率。
+
+## Version 1.6.6 @2026.07.18
+
+### 新增
+- 支持 `get_native_live_uikit_integration` 工具，支持 LiveKit(Android/iOS) 含 UI 集成。
+
+## Version 1.6.0 @2026.07.01
+
+### 新增
+- 重构 MCP 检索能力，收敛 MCP 工具数量。
+- 支持 `search_trtc_knowledge` 工具，支持实时音视频（TRTC/IM）相关文档检索。

package/README.md

@@ -1,42 +1,29 @@
-## Tencent SDK Model Context Protocol (MCP) Server for Cursor IDE
+## 腾讯云 SDK MCP Server 使用说明
 
-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.
+本仓库提供一个基于 CLI 的 Model Context Protocol（MCP）Server，向 LLM 工具暴露腾讯云 SDK 文档与 API 资料，帮助 AI Agent 更准确地理解并集成腾讯云实时音视频能力。
 
 
-## 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.
-- 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`.
+- **高效检索**：支持腾讯云实时音视频文档检索，快速定位官方资料与实践说明。
+- **覆盖全面**：支持 Chat（IM）、Call、Live、Room、RTCEngine（TRTC SDK）、TIMPush 等产品域。
+- **智能路由**：支持产品/平台语义识别与消歧，在必要时引导补齐平台与框架信息。
+- **集成友好**：除文档问答外，提供 Web / Android / iOS / Flutter 等含 UI 集成入口。
+- **官方可信**：基于官方资料，提升答案可靠性与可落地性。
+- **广泛兼容**：通过 STDIN/STDOUT 的 JSON-RPC 提供 MCP 能力，可接入 Cursor / Codex / Claude / CodeBuddy 等 MCP 客户端。
+- **开箱即用**：`npx` 即可运行，低接入门槛。
 
+## 环境要求
+- Node.js（>= 18）与 npm
+- 支持 MCP 的 IDE
 
-## Prerequisites
-- Node.js (>= 18) and npm
-- Cursor IDE with MCP support
 
+## 使用方式
+### 标准接入流程
 
-## How To Use
-To set up the @tencentcloud/sdk-mcp MCP Server, follow these steps:
+- Step1：在你的 Cursor 项目中，创建或编辑 `.cursor/mcp.json` 或 `~/.cursor/mcp.json`，添加如下配置。
 
-- Step1: Installation.
-
-```
-npx -y @tencentcloud/sdk-mcp
-```
-
-
-- Step2: In your Cursor project, create or open the `.cursor/mcp.json` or `~/.cursor/mcp.json` files and add your config.
-
-```javascript
+```json
 {
   "mcpServers": {
     "tencentcloud-sdk-mcp": {
@@ -50,16 +37,53 @@ npx -y @tencentcloud/sdk-mcp
   }
 }
 ```
-When you save the file, a notification is displayed. In the prompt, click **Enable**.
+保存后会弹出提示，在提示中点击 **Enable**。
 
 ![mcp-server-prompt](https://web.sdk.qcloud.com/im/assets/images/mcp-server-prompt.png)
 
-- Step3: Navigate to **Cursor Settings** (the gear icon in top right corner) -> **MCP**, and check if tencentcloud-sdk-mcp server is enabled.
+- Step2：进入 **Cursor Settings**（右上角齿轮）-> **MCP**，确认 `tencentcloud-sdk-mcp` 已启用。
 
 ![cursor-setting](https://web.sdk.qcloud.com/im/assets/images/cursor-setting.png)
 
+- Step3：在 IDE 中直接描述你的需求，让 AI 基于腾讯云 SDK 文档完成实现或答疑。
+
+### 可选：全局安装
+
+如需在本地全局快速调用，可先执行：
+
+```bash
+npx -y @tencentcloud/sdk-mcp
+```
+
+## 更新记录
+
+> 仅展示最近更新，完整历史请查看 `CHANGELOG.md`。
+
+## Version 1.7.1 @2026.08.11
+
+### 新增
+- 新增检索前置归一化：基于 prompt 真值对 `product` / `frameworks` 做归一化，解决 agent 推理错误导致的检索偏差。
+
+### 变更
+- 优化 `search_trtc_knowledge` 输出契约：移除 "1-2 sentence per subsection" 等压缩性措辞，改为输出完整合成答案。
+
+### 修复
+- 修复 "安卓 Web TRTC" 等 prompt 下 agent 误传双 product / 双 frameworks 时未按 prompt 真值校正的问题。
+
+### Version 1.7.0 @2026.08.02
+
+#### 新增
+- 补充并同步 Chat / Call / Live / Room 等产品域最佳实践文档，增强知识覆盖范围。
+
+#### 变更
+- 持续重构双语检索链路，优化 query 归一化、意图路由、候选过滤与精确命中策略。
+- 优化最佳实践与 URL 类文档的召回与排序，提升问答结果可用性与稳定性。
+- 优化 `search_trtc_knowledge` 相关定义与答复约束，提升回答可读性与可执行性。
+
+#### 修复
+- 修复复杂问法下部分检索结果偏题的问题，降低高分误召回概率。
 
-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.
+#### 新增
+- 支持 `get_native_live_uikit_integration` 工具，支持 LiveKit(Android/iOS) 含 UI 集成。

package/knowledge/build-index.js

@@ -3,7 +3,9 @@ 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));
 // 构建期写入索引到 dist/resource/index/：
 //   dist/knowledge/ → ../resource/ → dist/resource/
@@ -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/doc-url-resolver.js

@@ -5,6 +5,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 /** 控制台/购买页等不适合作为「参考文档」的链接 */
 const NOISE_URL_RE = /console\.cloud\.tencent|buy\.cloud\.tencent|account\.renewal|edu\/learning/i;
 const PREFERRED_DOC_HOST_RE = /cloud\.tencent\.com|web\.sdk\.qcloud\.com|github\.com\/Tencent(?:Cloud|RTC)/i;
+const LOCALHOST_URL_RE = /^https?:\/\/(?:localhost|127\.0\.0\.1)(?::|\b)/i;
 let cachedSourceUrlMap = null;
 function loadSourceUrlMap() {
     if (cachedSourceUrlMap)
@@ -25,6 +26,8 @@ function isUsefulDocUrl(url) {
         return false;
     if (NOISE_URL_RE.test(url))
         return false;
+    if (LOCALHOST_URL_RE.test(url))
+        return false;
     return true;
 }
 /** 从 markdown 正文中提取可参考的官网链接（优先 cloud.tencent / web.sdk.qcloud） */
@@ -51,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/zh-cn/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)
@@ -84,35 +112,58 @@ 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;
 }
+function coerceHttpUrl(value) {
+    if (typeof value !== 'string')
+        return null;
+    const normalized = value.replace(/\\/g, '/').trim();
+    if (!normalized.startsWith('http'))
+        return null;
+    return normalized;
+}
+function resolveManifestDocUrl(entry) {
+    return coerceHttpUrl(entry.ref) ?? coerceHttpUrl(entry.nodeId);
+}
 /** build 时从 sync-manifest 生成 localPath → 官网 URL 映射 */
 export function buildDocSourceUrlMap(syncManifestPath) {
     if (!fs.existsSync(syncManifestPath))
         return {};
     const manifest = JSON.parse(fs.readFileSync(syncManifestPath, 'utf-8'));
     const map = {};
-    for (const entry of Object.values(manifest.entries ?? {})) {
-        if (entry.nodeId?.startsWith('http') && entry.localPath) {
-            map[entry.localPath.replace(/\\/g, '/')] = entry.nodeId;
+    const entries = manifest.entries ?? {};
+    for (const entry of Object.values(entries)) {
+        const url = resolveManifestDocUrl(entry);
+        if (url && entry.localPath) {
+            map[entry.localPath.replace(/\\/g, '/')] = url;
         }
     }
+    for (const [localPath, nodeId] of Object.entries(manifest.byLocalPath ?? {})) {
+        const normalized = localPath.replace(/\\/g, '/');
+        if (map[normalized])
+            continue;
+        const url = resolveManifestDocUrl(entries[nodeId] ?? { nodeId });
+        if (url)
+            map[normalized] = url;
+    }
     return map;
 }