@tencentcloud/sdk-mcp 1.4.7 → 1.6.0-beta.1

package/knowledge/search/search-knowledge.js

@@ -0,0 +1,226 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { attachPoolContent } from '../content-loader.js';
+import { rankSubsetWithIndex } from '../bm25.js';
+import { getProductsBM25Index } from '../bm25-cache.js';
+import { filterPool, normalizeParams } from './filter-pool.js';
+import { runExactLookup } from './exact-lookup.js';
+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];
+}
+function loadManifest() {
+    if (cachedManifest)
+        return cachedManifest;
+    const manifestPath = resolveResourcePath('index', 'manifest.json');
+    if (!fs.existsSync(manifestPath)) {
+        throw new Error('manifest.json not found. Run `npm run build` in zh/ first.');
+    }
+    cachedManifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    return cachedManifest;
+}
+function postProcess(ranked, chunksById, limit) {
+    const sourceCount = {};
+    const urlMappingSourceCount = {};
+    /** 已入选的 push config/android/{vendor} 文件，用于抑制其他厂商噪声 */
+    let selectedVendorFile = null;
+    const fragments = [];
+    for (const item of ranked) {
+        const chunk = chunksById.get(item.id);
+        if (!chunk)
+            continue;
+        const isUrlMapping = Boolean(isUrlMappingSource(chunk.source));
+        if (isUrlMapping) {
+            const urlCount = urlMappingSourceCount[chunk.source] ?? 0;
+            if (urlCount >= 1)
+                continue;
+            urlMappingSourceCount[chunk.source] = urlCount + 1;
+        }
+        else {
+            const count = sourceCount[chunk.source] ?? 0;
+            if (count >= 3)
+                continue;
+            sourceCount[chunk.source] = count + 1;
+        }
+        // 当用户明确问某厂商时，抑制同目录下其他厂商文档的噪声
+        // 规则：如果已有 config/android/{vendor}.md 入选，
+        // 后续其他 config/android/{other}.md 跳过
+        const isVendorDoc = chunk.source.match(/^knowledge\/push\/config\/android\/[a-z]+\.md$/);
+        if (isVendorDoc) {
+            if (!selectedVendorFile) {
+                selectedVendorFile = chunk.source;
+            }
+            else if (chunk.source !== selectedVendorFile) {
+                continue; // 跳过其他厂商
+            }
+        }
+        // 当已明确命中了厂商配置页后，后续的 push 通用文件（integration/、其他 config/）不再有意义
+        // 只保留同厂商文件（已由 vendor dedup 处理）和 overview 综述，其他 push 通用文档视为噪声
+        if (selectedVendorFile && chunk.source.startsWith('knowledge/push/') && !chunk.source.includes('/overview/')) {
+            if (chunk.source !== selectedVendorFile)
+                continue;
+        }
+        const firstPush = fragments.length === 0;
+        if (firstPush) {
+            // 首条不设分数截止，至少保证 1 条返回
+        }
+        else {
+            // 分数衰减到 top 的 5% 以下时停止，不硬填到 limit
+            const topScore = fragments[0].score;
+            if (topScore > 0 && item.score < topScore * 0.05)
+                break;
+        }
+        fragments.push({
+            rank: fragments.length + 1,
+            score: item.score,
+            title: chunk.title,
+            content: chunk.content,
+            source: chunk.source,
+            product: chunk.product,
+            framework: chunk.framework,
+            types: chunk.types,
+            chunk_id: chunk.id,
+        });
+        if (fragments.length >= limit)
+            break;
+    }
+    return fragments;
+}
+function isUrlMappingSource(source) {
+    const normalized = source.replace(/\\/g, '/');
+    const match = normalized.match(/knowledge\/chat\/urls\/(.+\.md)$/);
+    if (!match)
+        return null;
+    return match[1].replace(/\.md$/, '').replace(/\/index$/, '');
+}
+function partitionFragments(fragments) {
+    const urlMapping = [];
+    const localDoc = [];
+    for (const fragment of fragments) {
+        if (isUrlMappingSource(fragment.source)) {
+            urlMapping.push(fragment);
+        }
+        else {
+            localDoc.push(fragment);
+        }
+    }
+    const urlMappingKinds = [...new Set(urlMapping.map((f) => isUrlMappingSource(f.source)).filter(Boolean))];
+    return { urlMapping, localDoc, urlMappingKinds };
+}
+/**
+ * P0-3：相对阈值的置信度评估。
+ * - high：top ≥ 50 或有精确命中（exactHits 非空）
+ * - medium：top ≥ 10 且 top / second ≥ 1.3（区分度足够）
+ * - low：top 较低或与 second 接近（同水位竞争，agent 应谨慎）
+ * - none：fragments 为空
+ */
+function assessConfidence(fragments, exactHits) {
+    if (fragments.length === 0) {
+        return { confidence: 'none', status: 'empty' };
+    }
+    const top = fragments[0].score;
+    const second = fragments[1]?.score ?? 0;
+    if (exactHits.length > 0 || top >= 50) {
+        return { confidence: 'high', status: 'success' };
+    }
+    const ratio = second > 0 ? top / second : Infinity;
+    if (top >= 10 && ratio >= 1.3) {
+        return { confidence: 'medium', status: 'success' };
+    }
+    if (top >= 5 && ratio >= 1.15) {
+        return { confidence: 'medium', status: 'success' };
+    }
+    return { confidence: 'low', status: 'low_confidence' };
+}
+function buildAgentMessage(status, fragments, confidence) {
+    const tail = '合成答案后请调用 `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 硬搜。';
+    }
+    const { urlMapping, localDoc, urlMappingKinds } = partitionFragments(fragments);
+    const hasUrlMapping = urlMapping.length > 0;
+    const hasLocalDoc = localDoc.length > 0;
+    const urlKindLabel = urlMappingKinds.join(' / ') || 'urls';
+    if (status === 'success' && fragments.length > 0) {
+        const confidenceHint = confidence === 'high' ? '(confidence=high)'
+            : confidence === 'medium' ? '(confidence=medium，top 与次优区分度一般，作答时如有不确定可向用户确认)'
+                : '';
+        if (hasUrlMapping && !hasLocalDoc) {
+            return `知识库命中 **L1 URL 映射**${confidenceHint}（${urlKindLabel}，共 ${urlMapping.length} 条片段）。这些 fragments **仅为官网文档入口**（cloud.tencent.com / web.sdk.qcloud.com 等），**不含** REST API、错误码、Webhook 全文。MUST：① 在 fragments 中匹配用户问题对应的**目标 URL**；② **自行抓取**该 URL 的官网文档后再合成答案；③ 禁止仅复述映射表或臆造 API/错误码细节。${tail}`;
+        }
+        if (hasUrlMapping && hasLocalDoc) {
+            return `知识库返回 ${fragments.length} 条片段${confidenceHint}：${localDoc.length} 条本地文档 + ${urlMapping.length} 条 URL 映射（${urlKindLabel}）。**本地文档片段**（preset/integration 等）可直接基于 content 作答；**URL 映射片段** MUST 提取其中目标 URL 并**自行抓取**官网文档后再作答，禁止仅复述映射表。${tail}`;
+        }
+        return `知识库已返回 ${fragments.length} 条有效片段${confidenceHint}。请**仅基于 fragments** 合成答案；**不要**并行 web_search 或再去官网抓文档。${tail}`;
+    }
+    if (status === 'low_confidence') {
+        if (hasUrlMapping) {
+            return `知识库置信度偏低（confidence=low：top 分数低或与次优过于接近），但命中 URL 映射（${urlKindLabel}）。请从 fragments 提取目标 URL 并**自行抓取**官网文档后作答；若映射表未覆盖用户问题，向用户说明不确定之处。${tail}`;
+        }
+        return `知识库置信度偏低（confidence=low：top 分数低或与次优过于接近，可能未精确命中用户问题）。请基于已有 fragments 尽力作答，并**主动向用户说明不确定之处**；可考虑让用户补充更具体的描述（如组件名 / API 名 / 错误码）后重新检索。**不要**默认并行 web_search。${tail}`;
+    }
+    return `知识库未命中有效片段。请向用户说明并确认 product/framework 是否准确；若仍无 platform 信息且问题依赖具体客户端，应先 \`present_framework_choice\`。${tail}`;
+}
+export function searchKnowledge(params) {
+    const norm = normalizeParams(params);
+    if (requiresFramework(norm)) {
+        const manifest = loadManifest();
+        return {
+            status: 'needs_framework',
+            confidence: 'none',
+            message: buildAgentMessage('needs_framework', [], 'none'),
+            query: params,
+            meta: {
+                pool_size: manifest.chunks.length,
+                filtered_size: 0,
+                exact_hits: [],
+            },
+            fragments: [],
+        };
+    }
+    const manifest = loadManifest();
+    const allChunks = manifest.chunks;
+    const pool = filterPool(allChunks, norm);
+    const { boosts, exactHits } = runExactLookup(norm.prompt, pool, norm);
+    // P0-4：用 product 级缓存的 BM25 索引对子集打分（首次构建，后续命中缓存）
+    // 索引基于该 product 全量 chunks（含 integration corpus）；
+    // 子集 ranking 只对 filteredPool.map(id) 打分，IDF 用更稳的产品级全量统计。
+    // 支持多 product 同时检索（products 数组），跨域问题如 Chat + Push 能同时命中各方知识。
+    const productIndex = getProductsBM25Index(allChunks, norm.product);
+    const poolWithContent = attachPoolContent(pool);
+    const chunksById = new Map(poolWithContent.map((chunk) => [chunk.id, chunk]));
+    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)))];
+    // P0-3：相对阈值评估置信度（替代原硬编码 0.5 死阈值）
+    const { confidence, status } = assessConfidence(fragments, exactHits);
+    const topScore = fragments[0]?.score;
+    const secondScore = fragments[1]?.score;
+    return {
+        status,
+        confidence,
+        message: buildAgentMessage(status, fragments, confidence),
+        query: params,
+        meta: {
+            pool_size: allChunks.length,
+            filtered_size: pool.length,
+            exact_hits: exactHits,
+            ...(urlMappingSources.length ? { url_mapping_sources: urlMappingSources } : {}),
+            ...(topScore !== undefined ? { top_score: Number(topScore.toFixed(2)) } : {}),
+            ...(secondScore !== undefined ? { second_score: Number(secondScore.toFixed(2)) } : {}),
+        },
+        fragments,
+    };
+}
+export { normalizeParams, filterPool };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencentcloud/sdk-mcp",
-  "version": "1.4.7",
+  "version": "1.6.0-beta.1",
   "description": "Tencent Cloud MCP Server for SDK",
   "type": "module",
   "main": "index.js",
@@ -10,24 +10,24 @@
     "url": "xx"
   },
   "dependencies": {
+    "@grpc/grpc-js": "^1.5.1",
+    "@grpc/proto-loader": "^0.6.6",
     "@modelcontextprotocol/sdk": "1.27.1",
     "@types/express": "^5.0.1",
+    "@types/hashring": "^3.2.1",
     "@types/node": "^22.15.32",
     "@types/uuid": "^10.0.0",
-    "express": "^5.1.0",
-    "shx": "^0.3.4",
-    "typescript": "^5.8.2",
-    "zod": "^3.24.2",
     "agentkeepalive": "^4.1.4",
-    "@grpc/grpc-js": "^1.5.1",
-    "@grpc/proto-loader": "^0.6.6",
-    "@types/hashring": "^3.2.1",
     "axios": "^0.25.0",
     "debug": "^4.3.1",
+    "express": "^5.1.0",
     "hashring": "^3.2.0",
     "protobufjs": "^6.11.2",
     "semver": "^7.3.5",
-    "uuid": "^8.3.2"
+    "shx": "^0.3.4",
+    "typescript": "^5.8.2",
+    "uuid": "^8.3.2",
+    "zod": "^3.24.2"
 },
   "author": "Tencent Cloud Terminal R&D Center",
   "keywords": [

package/resource/_schema/feature-aliases.yaml

@@ -0,0 +1,10 @@
+chat:
+  theme.md: ["主题", "主题定制", "theme", "换肤", "深色模式", "TUITheme", "自定义界面"]
+live:
+  live-co-guest-interaction.md: ["连麦", "观众连麦", "co_guest", "CoGuest"]
+  live-host-interaction.md: ["PK", "主播连线", "co_host"]
+  live-base-beauty.md: ["美颜", "base_beauty"]
+  voice-co-guest-interaction.md: ["语聊房上麦", "上麦", "voice co guest", "co guest"]
+room:
+  screen-share.md: ["屏幕分享", "screen share", "startScreenShare"]
+  virtual-background.md: ["虚拟背景", "virtual background"]

package/resource/_schema/goal-tags.yaml

@@ -0,0 +1,72 @@
+get_web_chat_uikit_integration:
+  full-featured:
+    root: integration
+    path: chat/preset/{framework}/integration.md
+  chat-only:
+    root: integration
+    path: chat/preset/{framework}/integration.md
+get_native_chat_uikit_integration:
+  full-featured:
+    root: integration
+    path: chat/preset/{framework}/integration.md
+  chat-only:
+    root: integration
+    path: chat/preset/{framework}/integration.md
+get_web_call_uikit_integration:
+  integration:
+    root: integration
+    path: callkit/preset/{framework}/integration.md
+get_native_call_uikit_integration:
+  integration:
+    root: integration
+    path: callkit/preset/{framework}/integration.md
+get_native_callkit_core_integration:
+  make_call:
+    root: knowledge
+    path: callkit/core-sdk/{framework}/make-call.md
+  answer_call:
+    root: knowledge
+    path: callkit/core-sdk/{framework}/answer-call.md
+  offline_push:
+    root: knowledge
+    path: callkit/core-sdk/{framework}/offline-push.md
+get_web_live_uikit_integration:
+  liveList:
+    root: integration
+    path: livekit/preset/live/vue/live-list-integration.md
+  livePlayer-desk:
+    root: integration
+    path: livekit/preset/live/vue/live-player-desk-integration.md
+  livePlayer-h5:
+    root: integration
+    path: livekit/preset/live/vue/live-player-h5-integration.md
+  livePusher:
+    root: integration
+    path: livekit/preset/live/vue/live-pusher-integration.md
+  CoGuestPanel:
+    root: integration
+    path: livekit/preset/live/vue/components/co-guest-panel.md
+get_native_livekit_core_integration:
+  host_streaming:
+    root: knowledge
+    path: livekit/core-sdk/{scenario}/{framework}/*-integration.md
+  audience_streaming:
+    root: knowledge
+    path: livekit/core-sdk/{scenario}/{framework}/*-integration.md
+  live_list:
+    root: knowledge
+    path: livekit/core-sdk/{scenario}/{framework}/*-list.md
+get_web_room_uikit_integration:
+  integration:
+    root: integration
+    path: roomkit/preset/vue/integration.md
+get_web_room_core_integration:
+  room-state:
+    root: knowledge
+    path: roomkit/vue/features/room-state.md
+  device-detection:
+    root: knowledge
+    path: roomkit/vue/features/device-detection.md
+  device-state:
+    root: knowledge
+    path: roomkit/vue/features/device-state.md

package/resource/_schema/products.yaml

@@ -0,0 +1,16 @@
+chat:
+  knowledge_root: chat
+  integration_root: chat
+call:
+  knowledge_root: callkit
+  integration_root: callkit
+live:
+  knowledge_root: livekit
+  integration_root: livekit
+room:
+  knowledge_root: roomkit
+  integration_root: roomkit
+rtcengine:
+  knowledge_root: rtcengine
+native_trtc_sdk:
+  knowledge_root: trtc

package/resource/_schema/trtc-intents.yaml

@@ -0,0 +1,27 @@
+android:
+  core_api: TRTCCloud
+  type_def: TRTCCloudDef
+  callback: TRTCCloudListener
+  statistics: TRTCStatistics
+  audio_effect: TXAudioEffectManager
+  beauty: TXBeautyManager
+  device: TXDeviceManager
+  error_code: TXLiteAVCode
+ios:
+  core_api: TRTCCloud
+  type_def: TXLiveSDKTypeDef
+  callback: TRTCCloudDelegate
+  statistics: TRTCStatistics
+  audio_effect: TXAudioEffectManager
+  beauty: TXBeautyManager
+  device: TXDeviceManager
+  error_code: TXLiteAVCode
+c++:
+  core_api: ITRTCCloud
+  type_def: TRTCTypeDef
+  callback: TRTCCloudCallback
+  statistics: ITRTCStatistics
+  audio_effect: ITXAudioEffectManager
+  beauty: null
+  device: ITXDeviceManager
+  error_code: TXLiteAVCode

package/resource/_schema/types.yaml

@@ -0,0 +1,44 @@
+integration:
+  globs:
+    - integration/**/*
+component:
+  globs:
+    - knowledge/**/components/*.md
+    - knowledge/chat/preset/vue/features/*.md
+    - knowledge/chat/preset/react/features/*.md
+    - knowledge/chat/preset/react/components/*.md
+    - knowledge/chat/preset/android/features/*.md
+feature:
+  globs:
+    - knowledge/**/features/*.md
+    - knowledge/livekit/core-sdk/**/*.md
+api:
+  globs:
+    - knowledge/**/api.md
+    - knowledge/**/client-api.md
+    - knowledge/**/api-reference/*.md
+plugin:
+  globs:
+    - knowledge/rtcengine/web/plugin/*.md
+sdk:
+  globs:
+    - knowledge/chat/urls/sdk/*.md
+faq:
+  # Chat 无 preset/*/faq.md；排障语料在 knowledge/chat/preset/** 与 urls/
+  globs:
+    - knowledge/**/faq.md
+    - knowledge/**/faq/**/*.md
+error_code:
+  globs:
+    - knowledge/chat/urls/error-code.md
+    - knowledge/**/error_code*.md
+    - knowledge/**/TXLiteAVCode.md
+product:
+  globs:
+    - knowledge/chat/urls/product.md
+server_api:
+  globs:
+    - knowledge/chat/urls/restapi.md
+webhook:
+  globs:
+    - knowledge/chat/urls/webhook.md

package/resource/index/component-slugs.json

@@ -0,0 +1 @@
+{"chat-setting":["chat-setting","chatsetting","chat_setting"],"contact-list":["contact-list","contactlist","contact_list"],"conversation-actions":["conversation-actions","conversationactions","conversation_actions"],"conversation-list":["conversation-list","conversationlist","conversation_list"],"conversation-preview":["conversation-preview","conversationpreview","conversation_preview"],"conversation-search":["conversation-search","conversationsearch","conversation_search"],"message-input":["message-input","messageinput","message_input"],"message-list":["message-list","messagelist","message_list"],"search":["search","search","search"],"theme":["theme","theme","theme"],"chat-header":["chat-header","chatheader","chat_header"]}