@tencentcloud/sdk-mcp 1.6.0-beta.2 → 1.6.0

package/README.md

@@ -41,7 +41,7 @@ npx -y @tencentcloud/sdk-mcp
   "mcpServers": {
     "tencentcloud-sdk-mcp": {
       "command": "npx",
-      "args": ["-y", "@tencentcloud/sdk-mcp"],
+      "args": ["-y", "@tencentcloud/sdk-mcp@latest"],
       "env": {
         "SDKAPPID": "YOUR_SDKAPPID",
         "SECRETKEY": "YOUR_SECRET_KEY"

package/knowledge/build-index.js

@@ -2,9 +2,10 @@ import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { chunkMarkdown, toManifestChunk } from './chunker.js';
+import { buildDocSourceUrlMap } from './doc-url-resolver.js';
 import { inferPathMeta } from './path-meta.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const RESOURCE_ROOT = path.resolve(__dirname, '../../resource');
+const RESOURCE_ROOT = path.resolve(__dirname, '../resource');
 function walkMarkdownFiles(dir, baseRel) {
     if (!fs.existsSync(dir))
         return [];
@@ -57,6 +58,9 @@ export function buildKnowledgeIndex() {
     const componentSlugs = collectComponentSlugs(chunks);
     fs.writeFileSync(path.join(indexDir, 'manifest.json'), JSON.stringify(manifest));
     fs.writeFileSync(path.join(indexDir, 'component-slugs.json'), JSON.stringify(componentSlugs));
+    const syncManifestPath = path.resolve(__dirname, '../../sync/sync-manifest.json');
+    const docSourceUrls = buildDocSourceUrlMap(syncManifestPath);
+    fs.writeFileSync(path.join(indexDir, 'doc-source-urls.json'), JSON.stringify(docSourceUrls));
     const staleSearchIndex = path.join(indexDir, 'search-index.json');
     if (fs.existsSync(staleSearchIndex)) {
         fs.unlinkSync(staleSearchIndex);

package/knowledge/content-loader.js

@@ -4,8 +4,8 @@ import { fileURLToPath } from 'url';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const fileCache = new Map();
 function resolveResourceRoot() {
-    // dist/knowledge/ → 上溯两级到包根，resource/ 与 package.json 平级
-    return path.resolve(__dirname, '../../resource');
+    // npm: knowledge/ → ../resource/ 到包根；dev: dist/knowledge/ → ../resource/ 到 dist/resource/
+    return path.resolve(__dirname, '../resource');
 }
 function readSourceFile(source) {
     const cached = fileCache.get(source);
@@ -16,6 +16,9 @@ function readSourceFile(source) {
     fileCache.set(source, text);
     return text;
 }
+export function getSourceFileContent(source) {
+    return readSourceFile(source);
+}
 /** 按 build 时写入的 char 偏移从 md 源文件切片（方案 B：manifest 不存 content） */
 export function getChunkContent(chunk) {
     const full = readSourceFile(chunk.source);

package/knowledge/doc-url-resolver.js

@@ -0,0 +1,118 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+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;
+let cachedSourceUrlMap = null;
+function loadSourceUrlMap() {
+    if (cachedSourceUrlMap)
+        return cachedSourceUrlMap;
+    const mapPath = path.resolve(__dirname, '../resource/index/doc-source-urls.json');
+    if (!fs.existsSync(mapPath)) {
+        cachedSourceUrlMap = {};
+        return cachedSourceUrlMap;
+    }
+    cachedSourceUrlMap = JSON.parse(fs.readFileSync(mapPath, 'utf-8'));
+    return cachedSourceUrlMap;
+}
+function normalizeUrl(raw) {
+    return raw.replace(/[.,;)\]]+$/, '').trim();
+}
+function isUsefulDocUrl(url) {
+    if (!/^https?:\/\//i.test(url))
+        return false;
+    if (NOISE_URL_RE.test(url))
+        return false;
+    return true;
+}
+/** 从 markdown 正文中提取可参考的官网链接（优先 cloud.tencent / web.sdk.qcloud） */
+export function extractUrlsFromContent(content, max = 3) {
+    const found = [];
+    const preferred = [];
+    for (const match of content.matchAll(/https?:\/\/[^\s`|)\]"'>]+/g)) {
+        const url = normalizeUrl(match[0]);
+        if (!isUsefulDocUrl(url))
+            continue;
+        if (PREFERRED_DOC_HOST_RE.test(url)) {
+            if (!preferred.includes(url))
+                preferred.push(url);
+        }
+        else if (!found.includes(url)) {
+            found.push(url);
+        }
+    }
+    const merged = [...preferred, ...found];
+    return merged.slice(0, max);
+}
+/** L1 URL 映射 chunk：表格行中的目标文档 URL */
+export function extractUrlMappingPrimaryUrl(content) {
+    const row = content.match(/\|\s*[^|]+\s*\|\s*`?(https?:\/\/[^|`\s]+)`?\s*\|/);
+    return row?.[1] ? normalizeUrl(row[1]) : null;
+}
+function isUrlMappingSource(source) {
+    return /knowledge\/chat\/urls\/.+\.md$/i.test(source.replace(/\\/g, '/'));
+}
+/**
+ * 为检索 fragment 解析可参考的官网 URL（去重、按优先级）。
+ * 1. sync-manifest 落盘的 localPath → 官网 URL（rtcengine 等）
+ * 2. L1 URL 映射行内目标 URL
+ * 3. 本地文档正文中的官网链接
+ */
+export function resolveFragmentDocUrls(source, content, fullSourceContent) {
+    const normalized = source.replace(/\\/g, '/');
+    const urls = [];
+    const canonical = loadSourceUrlMap()[normalized];
+    if (canonical)
+        urls.push(canonical);
+    if (isUrlMappingSource(normalized)) {
+        const primary = extractUrlMappingPrimaryUrl(content);
+        if (primary && !urls.includes(primary))
+            urls.push(primary);
+        return urls;
+    }
+    const collect = (text) => {
+        for (const url of extractUrlsFromContent(text)) {
+            if (!urls.includes(url))
+                urls.push(url);
+        }
+    };
+    collect(content);
+    if (urls.length === 0 && fullSourceContent && fullSourceContent !== content) {
+        collect(fullSourceContent);
+    }
+    return urls.slice(0, 3);
+}
+/** 从 fragments 汇总去重后的参考链接列表（按 fragment 相关度排序） */
+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,
+            });
+        }
+    }
+    return refs;
+}
+/** 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;
+        }
+    }
+    return map;
+}

package/knowledge/path-meta.js

@@ -148,8 +148,10 @@ export function inferPathMeta(relativeSource) {
             types.push('integration');
         }
         else if (category === 'config' && parts[3]) {
-            // config/{platform}/{vendor}.md：platform 决定 framework，vendor 靠关键词
-            framework = [parts[3]];
+            // config/{platform}/{vendor}.md（Android 厂商）或 config/{platform}.md（非 Android 平台配置）
+            // platform 决定 framework，vendor 靠 BM25 命中
+            const platform = parts[3].replace(/\.mdx?$/, '');
+            framework = [platform];
             types.push('integration');
         }
         else {

package/knowledge/search/exact-lookup.js

@@ -2,7 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const SCHEMA_ROOT = path.resolve(__dirname, '../../../resource/_schema');
+const SCHEMA_ROOT = path.resolve(__dirname, '../../resource/_schema');
 export const DOC_PATH_MAP = {
     android: {
         core_api: 'TRTCCloud',
@@ -146,7 +146,7 @@ export function runExactLookup(prompt, pool, norm) {
     }
     // E3: component slugs
     const componentSlugs = loadJson('../index/component-slugs.json', {});
-    const indexPath = path.resolve(__dirname, '../../../resource/index/component-slugs.json');
+    const indexPath = path.resolve(__dirname, '../../resource/index/component-slugs.json');
     const slugs = fs.existsSync(indexPath)
         ? JSON.parse(fs.readFileSync(indexPath, 'utf-8'))
         : componentSlugs;
@@ -248,7 +248,7 @@ export function runExactLookup(prompt, pool, norm) {
                 }
             }
         }
-        const errorCodeIntent = /错误码/i.test(prompt) || errorMatches.length > 0 || norm.types?.includes('error_code');
+        const errorCodeIntent = /错误码/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')) {

package/knowledge/search/filter-pool.js

@@ -12,15 +12,14 @@ function expandFrameworks(framework) {
         return ['react', 'vue', 'web'];
     return FRAMEWORK_SEARCH_ALIASES[framework] ?? [framework];
 }
-/** Chat 无独立 faq.md；types 含 faq 时改为检索 knowledge/chat 全语料（feature/component/urls 等） */
+/** Chat 无独立 faq.md；types 含 faq 时退化到全语料检索（feature/component/urls 等均命中） */
 function resolveTypes(products, types) {
     if (!types?.length)
         return undefined;
-    let resolved = [...types];
-    if (products?.includes('chat') && resolved.includes('faq')) {
-        resolved = resolved.filter((t) => t !== 'faq');
+    if (products?.includes('chat') && types.includes('faq')) {
+        return undefined;
     }
-    return resolved.length ? resolved : undefined;
+    return types;
 }
 /** 单平台产品的隐式 framework 推断：避免对显然唯一的平台再发起询问 */
 function inferImplicitFramework(products, framework) {
@@ -40,6 +39,7 @@ export function normalizeParams(params) {
         product: params.product,
         framework: effectiveFramework,
         frameworks,
+        searchIntent: params.types,
         types,
         scenario: params.scenario,
         limit,

package/knowledge/search/requires-framework.js

@@ -31,7 +31,7 @@ function isChatErrorCodeAmbiguous(norm) {
         return false;
     if (norm.framework)
         return false;
-    if (norm.types?.includes('error_code'))
+    if (norm.searchIntent?.includes('error_code'))
         return true;
     return /错误码|error\s*code|ERR_/i.test(norm.prompt);
 }
@@ -44,7 +44,7 @@ export function requiresFramework(norm) {
         return true;
     // push：判定逻辑（自上而下）
     if (hasProduct(norm, 'push')) {
-        if (norm.types?.length && norm.types.every((t) => CROSS_PLATFORM_TYPES.has(t))) {
+        if (norm.searchIntent?.length && norm.searchIntent.every((t) => CROSS_PLATFORM_TYPES.has(t))) {
             return false;
         }
         if (PUSH_PLATFORM_SPECIFIC_PROMPT.test(norm.prompt))
@@ -58,13 +58,13 @@ export function requiresFramework(norm) {
         return true;
     if (CROSS_PLATFORM_PROMPT.test(norm.prompt))
         return false;
-    if (norm.types?.length) {
-        if (norm.types.some((t) => PLATFORM_TYPES.has(t)))
+    if (norm.searchIntent?.length) {
+        if (norm.searchIntent.some((t) => PLATFORM_TYPES.has(t)))
             return true;
-        if (norm.types.every((t) => CROSS_PLATFORM_TYPES.has(t)))
+        if (norm.searchIntent.every((t) => CROSS_PLATFORM_TYPES.has(t)))
             return false;
         // faq / error_code 等默认可跨平台检索
-        if (norm.types.every((t) => t === 'faq' || t === 'error_code' || CROSS_PLATFORM_TYPES.has(t))) {
+        if (norm.searchIntent.every((t) => t === 'faq' || t === 'error_code' || CROSS_PLATFORM_TYPES.has(t))) {
             return false;
         }
     }

package/knowledge/search/search-knowledge.js

@@ -1,7 +1,8 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { attachPoolContent } from '../content-loader.js';
+import { attachPoolContent, getSourceFileContent } from '../content-loader.js';
+import { buildReferences, resolveFragmentDocUrls } from '../doc-url-resolver.js';
 import { rankSubsetWithIndex } from '../bm25.js';
 import { getProductsBM25Index } from '../bm25-cache.js';
 import { filterPool, normalizeParams } from './filter-pool.js';
@@ -10,15 +11,7 @@ import { requiresFramework } from './requires-framework.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 let cachedManifest = null;
 function resolveResourcePath(...segments) {
-    const candidates = [
-        path.resolve(__dirname, '../../../resource', ...segments),
-        path.resolve(__dirname, '../../resource', ...segments),
-    ];
-    for (const candidate of candidates) {
-        if (fs.existsSync(candidate))
-            return candidate;
-    }
-    return candidates[0];
+    return path.resolve(__dirname, '../../resource', ...segments);
 }
 function loadManifest() {
     if (cachedManifest)
@@ -87,6 +80,7 @@ function postProcess(ranked, chunksById, limit) {
             title: chunk.title,
             content: chunk.content,
             source: chunk.source,
+            doc_urls: resolveFragmentDocUrls(chunk.source, chunk.content, getSourceFileContent(chunk.source)),
             product: chunk.product,
             framework: chunk.framework,
             types: chunk.types,
@@ -143,8 +137,11 @@ function assessConfidence(fragments, exactHits) {
     }
     return { confidence: 'low', status: 'low_confidence' };
 }
-function buildAgentMessage(status, fragments, confidence) {
-    const tail = '合成答案后请调用 `record_answer`；用户反馈请调用 `record_feedback`。';
+function buildAgentMessage(status, fragments, confidence, references) {
+    const citeTail = references?.length
+        ? '作答时 MUST 在答案末尾附「**参考文档**」小节，逐条列出 `meta.references`（或各 fragment 的 `doc_urls`）中的 URL，便于用户核对；禁止编造未出现的链接。'
+        : '若 fragments 含 `doc_urls`，作答时须在末尾附「**参考文档**」列出对应 URL；禁止编造链接。';
+    const tail = `${citeTail} 合成答案后请调用 \`record_answer\`；用户反馈请调用 \`record_feedback\`。`;
     if (status === 'needs_framework') {
         return '【硬规则】问题依赖具体平台实现，但未指定 framework，全平台混检信息密度低且被禁止。MUST 先调用 `present_framework_choice`（传入 product），等用户选定 android/ios/flutter/react/vue/uni-app 等后再调用本工具，并 MUST 带上 **product + framework**。禁止传空 framework 硬搜。';
     }
@@ -179,7 +176,7 @@ export function searchKnowledge(params) {
         return {
             status: 'needs_framework',
             confidence: 'none',
-            message: buildAgentMessage('needs_framework', [], 'none'),
+            message: buildAgentMessage('needs_framework', [], 'none', undefined),
             query: params,
             meta: {
                 pool_size: manifest.chunks.length,
@@ -203,6 +200,7 @@ export function searchKnowledge(params) {
     const ranked = rankSubsetWithIndex(norm.prompt, pool.map((chunk) => chunk.id), productIndex, boosts);
     const fragments = postProcess(ranked, chunksById, norm.limit);
     const urlMappingSources = [...new Set(fragments.map((f) => f.source).filter((source) => isUrlMappingSource(source)))];
+    const references = buildReferences(fragments);
     // P0-3：相对阈值评估置信度（替代原硬编码 0.5 死阈值）
     const { confidence, status } = assessConfidence(fragments, exactHits);
     const topScore = fragments[0]?.score;
@@ -210,13 +208,14 @@ export function searchKnowledge(params) {
     return {
         status,
         confidence,
-        message: buildAgentMessage(status, fragments, confidence),
+        message: buildAgentMessage(status, fragments, confidence, references),
         query: params,
         meta: {
             pool_size: allChunks.length,
             filtered_size: pool.length,
             exact_hits: exactHits,
             ...(urlMappingSources.length ? { url_mapping_sources: urlMappingSources } : {}),
+            ...(references.length ? { references } : {}),
             ...(topScore !== undefined ? { top_score: Number(topScore.toFixed(2)) } : {}),
             ...(secondScore !== undefined ? { second_score: Number(secondScore.toFixed(2)) } : {}),
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencentcloud/sdk-mcp",
-  "version": "1.6.0-beta.2",
+  "version": "1.6.0",
   "description": "Tencent Cloud MCP Server for SDK",
   "type": "module",
   "main": "index.js",

package/resource/index/doc-source-urls.json

@@ -0,0 +1 @@
+{"knowledge/rtcengine/web/how_to_run_web_sdk_demo.md":"https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-10-basic-get-started-with-demo.md","knowledge/rtcengine/web/plugin/20-advanced-customized-capture-rendering.md":"https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-20-advanced-customized-capture-rendering.md","knowledge/rtcengine/web/plugin/21-advanced-auto-play-policy.md":"https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-21-advanced-auto-play-policy.md","knowledge/rtcengine/web/plugin/22-advanced-audio-mixer.md":"https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-22-advanced-audio-mixer.md","knowledge/rtcengine/web/plugin/23-advanced-support-detection.md":"https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-23-advanced-support-detection.md","knowledge/rtcengine/web/plugin/24-advanced-network-quality.md":"https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-24-advanced-network-quality.md","knowledge/rtcengine/web/plugin/25-advanced-device-change.md":"https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-25-advanced-device-change.md","knowledge/rtcengine/web/plugin/26-advanced-publish-cdn-stream.md":"https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-26-advanced-publish-cdn-stream.md","knowledge/rtcengine/web/plugin/27-advanced-small-stream.md":"https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-27-advanced-small-stream.md","knowledge/rtcengine/web/plugin/28-advanced-beauty.md":"https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-28-advanced-beauty.md","knowledge/rtcengine/web/plugin/29-advanced-water-mark.md":"https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-29-advanced-water-mark.md","knowledge/rtcengine/web/plugin/30-advanced-cross-room-link.md":"https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-30-advanced-cross-room-link.md","knowledge/rtcengine/web/plugin/31-advanced-plugins-overview.md":"https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-31-advanced-plugins-overview.md","knowledge/rtcengine/web/plugin/34-advanced-proxy.md":"https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-34-advanced-proxy.md","knowledge/rtcengine/web/plugin/35-advanced-ai-denoiser.md":"https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-35-advanced-ai-denoiser.md","knowledge/rtcengine/web/plugin/36-advanced-virtual-background.md":"https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-36-advanced-virtual-background.md","knowledge/rtcengine/web/plugin/37-advanced-voice-changer.md":"https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-37-advanced-voice-changer.md","knowledge/rtcengine/web/plugin/38-advanced-basic-beauty.md":"https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-38-advanced-basic-beauty.md","knowledge/rtcengine/web/plugin/39-advanced-video-decoder.md":"https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-39-advanced-video-decoder.md","knowledge/rtcengine/web/plugin/40-advanced-video-mixer.md":"https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-40-advanced-video-mixer.md","knowledge/rtcengine/web/plugin/41-advanced-small-stream-auto-switcher.md":"https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-41-advanced-small-stream-auto-switcher.md","knowledge/rtcengine/web/plugin/42-advanced-realtime-transcriber.md":"https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-42-advanced-realtime-transcriber.md","knowledge/rtcengine/web/plugin/43-advanced-face-detection.md":"https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-43-advanced-face-detection.md"}