@tencentcloud/sdk-mcp 1.6.4 → 1.6.6

package/knowledge/build-index.js

@@ -5,7 +5,7 @@ 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 [];

package/knowledge/chunker.js

@@ -36,11 +36,83 @@ function splitByHeading(content, level) {
     return sections;
 }
 function isFaqLike(source, content) {
-    return /faq|error-code|error_code|TXLiteAVCode/i.test(source) || (content.match(/^###\s+/gm) ?? []).length >= 3;
+    return /faq|error-code|error_code|TXLiteAVCode|unsupported-features/i.test(source)
+        || (content.match(/^###\s+/gm) ?? []).length >= 3;
+}
+function shouldForceSectionSplit(source, meta) {
+    return source.endsWith('unsupported-features.md') || meta.doc_kind === 'unsupported_summary';
 }
 function isChatUrlMapping(source) {
     return /knowledge\/chat\/urls\/.+\.md$/i.test(source.replace(/\\/g, '/'));
 }
+function containsCodeBlock(body) {
+    return /```[\s\S]*?```/.test(body);
+}
+function extractApiNames(body) {
+    const names = new Set();
+    const upperNoise = new Set(['SDK', 'API', 'HTTP', 'HTTPS', 'JSON']);
+    for (const match of body.matchAll(/`([a-z][A-Za-z0-9_]{2,})`/g)) {
+        names.add(match[1]);
+    }
+    for (const match of body.matchAll(/\b([a-z]+[A-Z][A-Za-z0-9_]*)\b/g)) {
+        names.add(match[1]);
+    }
+    for (const match of body.matchAll(/\b([A-Z][A-Za-z0-9_]*\.[a-zA-Z_][A-Za-z0-9_]*)\b/g)) {
+        names.add(match[1]);
+    }
+    for (const match of body.matchAll(/\b(I[A-Z][A-Za-z0-9_]*)\b/g)) {
+        names.add(match[1]);
+    }
+    for (const match of body.matchAll(/\b([A-Z][A-Za-z0-9_]*\.[A-Z_][A-Z0-9_]*)\b/g)) {
+        names.add(match[1]);
+    }
+    for (const match of body.matchAll(/\b([A-Z_]{3,})\b/g)) {
+        const token = match[1];
+        if (!upperNoise.has(token))
+            names.add(token);
+    }
+    return [...names].slice(0, 90);
+}
+function extractKeyPhrases(title, body) {
+    const firstParagraph = body
+        .replace(/^#{1,6}\s+.+$/gm, '')
+        .split(/\n\s*\n/)
+        .map((p) => p.trim())
+        .find(Boolean) ?? '';
+    const phrases = [title, firstParagraph]
+        .flatMap((part) => part.split(/[，。；;\n]/))
+        .map((s) => s.trim())
+        .filter((s) => s.length >= 2)
+        .slice(0, 8);
+    return [...new Set(phrases)];
+}
+function buildChunk(meta, source, title, body, id, char_start, char_end) {
+    const api_names = extractApiNames(body);
+    const key_phrases = extractKeyPhrases(title, body);
+    return {
+        id,
+        corpus: meta.corpus,
+        product: meta.product,
+        framework: meta.framework,
+        types: meta.types,
+        scenario: meta.scenario,
+        variant: meta.variant,
+        scope: meta.scope,
+        doc_kind: meta.doc_kind,
+        capability_status: meta.capability_status,
+        retrievable_scope: meta.retrievable_scope,
+        title,
+        source,
+        content: body,
+        symbols: extractSymbols(body),
+        error_codes: extractErrorCodes(body),
+        ...(api_names.length ? { api_names } : {}),
+        ...(containsCodeBlock(body) ? { contains_code: true } : {}),
+        ...(key_phrases.length ? { key_phrases } : {}),
+        char_start,
+        char_end,
+    };
+}
 function parseUrlMappingRows(content) {
     const lines = content.split('\n');
     let sectionTitle = '';
@@ -78,28 +150,12 @@ function chunkUrlMapping(source, content, meta) {
         return [];
     }
     const baseSlug = sourceSlug(source);
-    const chunks = [];
-    for (const row of rows) {
+    return rows.map((row) => {
         const sectionLine = row.sectionTitle ? `### ${row.sectionTitle}\n\n` : '';
         const body = `${sectionLine}| 子问题 | 目标文档 |\n|--------|---------|\n| ${row.label} | \`${row.url}\` |`;
         const headingSlug = slugify(row.label);
-        chunks.push({
-            id: `${baseSlug}#${headingSlug}`,
-            corpus: meta.corpus,
-            product: meta.product,
-            framework: meta.framework,
-            types: meta.types,
-            scenario: meta.scenario,
-            title: row.label,
-            source,
-            content: body,
-            symbols: extractSymbols(body),
-            error_codes: extractErrorCodes(body),
-            char_start: row.lineStart,
-            char_end: row.lineEnd,
-        });
-    }
-    return chunks;
+        return buildChunk(meta, source, row.label, body, `${baseSlug}#${headingSlug}`, row.lineStart, row.lineEnd);
+    });
 }
 export function chunkMarkdown(source, content, meta) {
     const chunks = [];
@@ -110,49 +166,22 @@ export function chunkMarkdown(source, content, meta) {
             return urlChunks;
         }
     }
-    if (content.length < 2048) {
+    const forceSectionSplit = shouldForceSectionSplit(source, meta);
+    if (content.length < 2048 && !forceSectionSplit) {
         const { body, char_start, char_end } = trimSliceOffsets(content, 0);
         if (!body)
             return chunks;
-        chunks.push({
-            id: `${baseSlug}#full`,
-            corpus: meta.corpus,
-            product: meta.product,
-            framework: meta.framework,
-            types: meta.types,
-            scenario: meta.scenario,
-            title: pathBasename(source),
-            source,
-            content: body,
-            symbols: extractSymbols(body),
-            error_codes: extractErrorCodes(body),
-            char_start,
-            char_end,
-        });
+        chunks.push(buildChunk(meta, source, pathBasename(source), body, `${baseSlug}#full`, char_start, char_end));
         return chunks;
     }
-    const level = isFaqLike(source, content) ? 3 : 2;
+    const level = forceSectionSplit ? 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);
         if (!body)
             continue;
         const headingSlug = slugify(section.title);
-        chunks.push({
-            id: `${baseSlug}#${headingSlug}`,
-            corpus: meta.corpus,
-            product: meta.product,
-            framework: meta.framework,
-            types: meta.types,
-            scenario: meta.scenario,
-            title: section.title,
-            source,
-            content: body,
-            symbols: extractSymbols(body),
-            error_codes: extractErrorCodes(body),
-            char_start,
-            char_end,
-        });
+        chunks.push(buildChunk(meta, source, section.title, body, `${baseSlug}#${headingSlug}`, char_start, char_end));
     }
     return chunks.length > 0 ? chunks : chunkMarkdown(source, content.slice(0, 2048), meta);
 }

package/knowledge/path-meta.js

@@ -10,7 +10,10 @@ function inferTypesFromFilename(fileName, baseTypes) {
         types.push('api');
     if (lower === 'faq.md')
         types.push('faq');
-    if (lower === 'integration.md' || lower.endsWith('-integration.md'))
+    // 文件名 = integration.md 不再默认 push integration（由上游 framework 分支显式声明 type）
+    //   live 分支 core 文档的 filename = integration.md 应是 type=core，不是 type=integration
+    //   chat/preset/integration.md 等仍由 preset 分支的 types.push('integration') 处理
+    if (lower.endsWith('-integration.md'))
         types.push('integration');
     if (/live-.*-interaction|voice-/.test(lower))
         types.push('feature');
@@ -26,6 +29,29 @@ const DIR_TO_FRAMEWORK = {
 function normalizeFrameworkDir(dir) {
     return DIR_TO_FRAMEWORK[dir] ?? dir;
 }
+function inferDocMeta(fileName) {
+    const lower = fileName.toLowerCase();
+    if (lower === 'capability-matrix.md') {
+        return { doc_kind: 'capability_matrix' };
+    }
+    if (lower === 'unsupported-features.md') {
+        return { doc_kind: 'unsupported_summary', capability_status: 'unsupported' };
+    }
+    if (lower.endsWith('-unsupported.md')) {
+        return { doc_kind: 'negative_faq', capability_status: 'unsupported' };
+    }
+    return {};
+}
+function inferShareScope(fileName) {
+    const lower = fileName.toLowerCase();
+    if (lower === 'usersig.md') {
+        return [
+            'usersig', 'sdkappid', 'secretkey', 'sdk 密钥', '鉴权', '签名',
+            'gentestusersig', 'tls', 'hmac',
+        ];
+    }
+    return 'always';
+}
 export function inferPathMeta(relativeSource) {
     const normalized = relativeSource.replace(/\\/g, '/');
     const parts = normalized.split('/');
@@ -35,7 +61,18 @@ export function inferPathMeta(relativeSource) {
     let framework = ['*'];
     let types = corpus === 'integration' ? ['integration'] : [];
     let scenario = null;
-    if (normalized.startsWith('knowledge/chat/') || normalized.startsWith('integration/chat/')) {
+    let variant;
+    let doc_kind;
+    let capability_status;
+    let retrievable_scope;
+    if (normalized.startsWith('knowledge/share/')) {
+        // 通配语料（跨产品共享）显式建模，不再依赖默认兜底路径。
+        product = '*';
+        framework = ['*'];
+        types.push('faq', 'product');
+        retrievable_scope = inferShareScope(fileName);
+    }
+    else if (normalized.startsWith('knowledge/chat/') || normalized.startsWith('integration/chat/')) {
         product = 'chat';
         if (parts.includes('preset') && parts.length >= 4) {
             framework = [normalizeFrameworkDir(parts[parts.indexOf('preset') + 1])];
@@ -67,6 +104,22 @@ export function inferPathMeta(relativeSource) {
                 }
             }
         }
+        // chat FAQ / best-practice 平台拆分：
+        //   - 新结构：knowledge/chat/best-practice/{platform}/{topic}.md
+        //   - 旧结构：knowledge/chat/faq/{platform}.md（保留兼容）
+        // 两者都统一标记为 types=['faq']，便于通过 types=faq 命中“经验类问答”。
+        if (parts[1] === 'chat' && parts[2] === 'best-practice' && parts.length >= 5) {
+            const fwSlug = normalizeFrameworkDir(parts[3]);
+            framework = [fwSlug];
+            types.push('faq');
+        }
+        if (parts[1] === 'chat' && parts[2] === 'faq' && parts.length >= 4) {
+            const fwSlug = fileName.replace(/\.mdx?$/, '');
+            if (fwSlug) {
+                framework = [fwSlug];
+                types.push('faq');
+            }
+        }
         if (fileName === 'faq.md')
             types.push('faq');
     }
@@ -74,10 +127,24 @@ export function inferPathMeta(relativeSource) {
         product = 'call';
         const presetIdx = parts.indexOf('preset');
         const coreIdx = parts.indexOf('core-sdk');
-        if (presetIdx >= 0 && parts[presetIdx + 1])
+        if (presetIdx >= 0 && parts[presetIdx + 1]) {
             framework = [normalizeFrameworkDir(parts[presetIdx + 1])];
-        if (coreIdx >= 0 && parts[coreIdx + 1])
+            variant = 'preset';
+        }
+        if (coreIdx >= 0 && parts[coreIdx + 1]) {
             framework = [normalizeFrameworkDir(parts[coreIdx + 1])];
+            variant = 'core-sdk';
+        }
+        // callkit 最佳实践目录：knowledge/callkit/best-practice/{platform}/{topic}.md
+        // 统一按 FAQ/经验类知识处理，支持 types=faq + frameworks={platform} 的精确检索。
+        if (parts[1] === 'callkit' && parts[2] === 'best-practice' && parts.length >= 5) {
+            framework = [normalizeFrameworkDir(parts[3])];
+            types.push('faq');
+            // calls 相关最佳实践既是 FAQ 也是 API 语义，避免 types=api 时被误过滤。
+            if (/(callengine-invitation|callkit-call-vs-calls)\.md$/i.test(fileName)) {
+                types.push('api');
+            }
+        }
         if (parts.includes('faq'))
             types.push('faq', 'error_code');
         if (fileName === 'api.md')
@@ -86,36 +153,114 @@ export function inferPathMeta(relativeSource) {
             types.push('api', 'feature');
     }
     else if (normalized.includes('/livekit/')) {
+        // livekit 目录结构：
+        //   preset/{framework}/                     → 旧结构（如 preset/vue）
+        //   preset/{scenario}/{platform}/           → 新结构（如 preset/live/android）
+        //   core-sdk/live/{platform}/*.md          → 视频直播 core 文档（framework 标签: [live, platform]，types=[core]）
+        //   core-sdk/voice/{platform}/*.md         → 语聊房 core 文档（framework 标签: [voice, platform]，types=[core]）
+        //   core-sdk/features/{platform}/*.md      → 跨场景功能模块（framework 标签: [features, platform]，types=[feature]）
+        //   core-sdk/api-reference/{platform}/*.md → 客户端 API（framework 标签: [platform]，types=[api]）
+        //   写写上"功能模块"是 video live / voice 共享节点，所以 features/ 下文档 type=feature 而非 core
         product = 'live';
         if (parts.includes('voice'))
             scenario = 'voice';
-        if (parts.includes('/live/'))
+        if (parts.includes('live'))
             scenario = 'live';
-        if (parts.includes('preset') && parts.includes('vue'))
-            framework = ['vue'];
-        if (parts.includes('core-sdk') && parts.length >= 4) {
-            const fwIdx = parts.indexOf('core-sdk') + 2;
-            if (parts[fwIdx] && !['live', 'voice'].includes(parts[fwIdx])) {
-                framework = [normalizeFrameworkDir(parts[fwIdx])];
+        const presetIdx = parts.indexOf('preset');
+        const coreIdx = parts.indexOf('core-sdk');
+        if (presetIdx >= 0 && parts[presetIdx + 1]) {
+            const presetLevel1 = normalizeFrameworkDir(parts[presetIdx + 1]);
+            const presetLevel2 = parts[presetIdx + 2] ? normalizeFrameworkDir(parts[presetIdx + 2]) : undefined;
+            // 兼容两种 preset 目录：
+            // - preset/{framework}（旧）
+            // - preset/{scenario}/{platform}（新）
+            if ((presetLevel1 === 'live' || presetLevel1 === 'voice') && presetLevel2) {
+                scenario = presetLevel1;
+                framework = [presetLevel2];
+            }
+            else {
+                framework = [presetLevel1];
+            }
+            variant = 'preset';
+            types.push('feature');
+        }
+        if (coreIdx >= 0 && parts.length >= 4) {
+            // core-sdk 下的 4 个子目录（live/voice/features/api-reference），每个下挂 platform 子目录
+            const sub = parts[coreIdx + 1];
+            const platform = parts[coreIdx + 2];
+            if (sub === 'live' && platform) {
+                framework = ['live', normalizeFrameworkDir(platform)];
+                types.push('core');
+                if (fileName === 'integration.md') {
+                    types.push('api', 'integration');
+                }
+                variant = 'core-sdk';
+            }
+            else if (sub === 'voice' && platform) {
+                framework = ['voice', normalizeFrameworkDir(platform)];
+                types.push('core');
+                if (fileName === 'integration.md') {
+                    types.push('api', 'integration');
+                }
+                variant = 'core-sdk';
+            }
+            else if (sub === 'features' && platform) {
+                framework = ['features', normalizeFrameworkDir(platform)];
+                types.push('feature');
+                variant = 'core-sdk';
+            }
+            else if (sub === 'api-reference' && platform) {
+                // api-reference 沿用旧逻辑：framework = platform，types = api
+                framework = [normalizeFrameworkDir(platform)];
+                types.push('api');
+                variant = 'core-sdk';
+            }
+            else {
+                // 兜底（不在 4 个已知子目录下）：framework = 子目录名
+                framework = [normalizeFrameworkDir(sub ?? '*')];
+                variant = 'core-sdk';
+                types.push('feature', 'api');
             }
         }
         if (parts.includes('components'))
             types.push('component');
-        if (parts.includes('api-reference'))
-            types.push('api');
-        if (parts.includes('core-sdk'))
-            types.push('feature', 'api');
         if (fileName === 'faq.md')
             types.push('faq');
+        // 与 roomkit 对齐：core-sdk 下 capability-matrix.md / unsupported-features.md
+        //   视为能力边界文档（doc_kind + capability_status），方便检索层按 doc_kind 过滤
+        const docMeta = inferDocMeta(fileName);
+        doc_kind = docMeta.doc_kind;
+        capability_status = docMeta.capability_status ?? capability_status;
+        if (doc_kind === 'capability_matrix' || doc_kind === 'unsupported_summary' || doc_kind === 'negative_faq') {
+            types.push('feature', 'faq');
+        }
     }
     else if (normalized.includes('/roomkit/')) {
         product = 'room';
-        if (parts.includes('vue'))
-            framework = ['vue'];
+        const presetIdx = parts.indexOf('preset');
+        const coreIdx = parts.indexOf('core-sdk');
+        if (presetIdx >= 0 && parts[presetIdx + 1]) {
+            framework = [normalizeFrameworkDir(parts[presetIdx + 1])];
+            variant = 'preset';
+        }
+        if (coreIdx >= 0 && parts[coreIdx + 1]) {
+            framework = [normalizeFrameworkDir(parts[coreIdx + 1])];
+            variant = 'core-sdk';
+            types.push('feature');
+            if (framework[0] === 'vue') {
+                capability_status = 'supported';
+            }
+        }
         if (parts.includes('features'))
             types.push('feature');
         if (parts.includes('faq'))
             types.push('faq', 'error_code');
+        const docMeta = inferDocMeta(fileName);
+        doc_kind = docMeta.doc_kind;
+        capability_status = docMeta.capability_status ?? capability_status;
+        if (doc_kind === 'capability_matrix' || doc_kind === 'unsupported_summary' || doc_kind === 'negative_faq') {
+            types.push('feature', 'faq');
+        }
     }
     else if (normalized.startsWith('knowledge/trtc/')) {
         product = 'native_trtc_sdk';
@@ -134,26 +279,32 @@ export function inferPathMeta(relativeSource) {
         //   knowledge/push/overview/{topic}.md                  → 跨平台综述（接入前准备/流程/选型/计费等），framework=*，types=[product]
         //   knowledge/push/integration/{platform}.md            → framework=平台 slug，types=[integration]
         //   knowledge/push/config/android/{vendor}.md           → framework=android（vendor 厂商靠 BM25 命中），types=[integration]
+        //   knowledge/push/api-reference/{platform}.md          → framework=平台 slug，types=[api]
         product = 'push';
-        const category = parts[2]; // overview | integration | config
+        const category = parts[2]; // overview | integration | config | api-reference
         if (category === 'overview') {
             framework = ['*'];
             types.push('product');
         }
         else if (category === 'integration') {
-            const fwSlug = fileName.replace(/\.mdx?$/, ''); // android / ios / donut / ...
+            const fwSlug = fileName.replace(/\.mdx?$/, '');
             if (fwSlug) {
                 framework = [fwSlug];
             }
             types.push('integration');
         }
         else if (category === 'config' && 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 if (category === 'api-reference') {
+            const fwSlug = fileName.replace(/\.mdx?$/, '');
+            if (fwSlug) {
+                framework = [fwSlug];
+            }
+            types.push('api');
+        }
         else {
             types.push('integration');
         }
@@ -167,11 +318,20 @@ export function inferPathMeta(relativeSource) {
     types = inferTypesFromFilename(fileName, types);
     if (types.length === 0)
         types = ['faq'];
+    const primaryFramework = framework[0];
+    const scope = product !== '*' && variant && primaryFramework && primaryFramework !== '*'
+        ? `${product}:${variant}:${primaryFramework}`
+        : undefined;
     return {
         product,
         framework,
         types: uniq(types),
         scenario,
         corpus,
+        variant,
+        scope,
+        doc_kind,
+        capability_status,
+        retrievable_scope,
     };
 }