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

package/knowledge/path-meta.js

@@ -0,0 +1,175 @@
+function uniq(arr) {
+    return [...new Set(arr)];
+}
+function inferTypesFromFilename(fileName, baseTypes) {
+    const types = [...baseTypes];
+    const lower = fileName.toLowerCase();
+    if (/error.?code|txliteavcode/.test(lower))
+        types.push('error_code');
+    if (lower === 'client-api.md' || lower === 'api.md' || lower === 'index.md')
+        types.push('api');
+    if (lower === 'faq.md')
+        types.push('faq');
+    if (lower === 'integration.md' || lower.endsWith('-integration.md'))
+        types.push('integration');
+    if (/live-.*-interaction|voice-/.test(lower))
+        types.push('feature');
+    if (lower.includes('plugin') || /^\d+-advanced-/.test(lower))
+        types.push('plugin');
+    return uniq(types);
+}
+/** 目录名 → 标准 framework 值：消除 android-view / ios-uikit 这类内部目录命名泄漏到元数据标签 */
+const DIR_TO_FRAMEWORK = {
+    'android-view': 'android',
+    'ios-uikit': 'ios',
+};
+function normalizeFrameworkDir(dir) {
+    return DIR_TO_FRAMEWORK[dir] ?? dir;
+}
+export function inferPathMeta(relativeSource) {
+    const normalized = relativeSource.replace(/\\/g, '/');
+    const parts = normalized.split('/');
+    const corpus = parts[0] === 'integration' ? 'integration' : 'knowledge';
+    const fileName = parts[parts.length - 1] ?? '';
+    let product = '*';
+    let framework = ['*'];
+    let types = corpus === 'integration' ? ['integration'] : [];
+    let scenario = null;
+    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])];
+        }
+        if (parts.includes('features')) {
+            types.push('feature');
+            if (parts.includes('preset')) {
+                const fw = normalizeFrameworkDir(parts[parts.indexOf('preset') + 1]);
+                if (fw === 'vue' || fw === 'react') {
+                    types.push('component');
+                }
+            }
+        }
+        if (parts.includes('urls')) {
+            if (fileName === 'product.md')
+                types.push('product');
+            else if (fileName === 'restapi.md')
+                types.push('server_api');
+            else if (fileName === 'webhook.md')
+                types.push('webhook');
+            else if (fileName === 'error-code.md')
+                types.push('error_code');
+            const urlsSdkIdx = parts.indexOf('sdk');
+            if (urlsSdkIdx >= 0 && parts[urlsSdkIdx - 1] === 'urls') {
+                const sdkFile = parts[urlsSdkIdx + 1];
+                if (sdkFile?.endsWith('.md')) {
+                    framework = [sdkFile.replace(/\.md$/, '')];
+                    types.push('sdk', 'api');
+                }
+            }
+        }
+        if (fileName === 'faq.md')
+            types.push('faq');
+    }
+    else if (normalized.includes('/callkit/')) {
+        product = 'call';
+        const presetIdx = parts.indexOf('preset');
+        const coreIdx = parts.indexOf('core-sdk');
+        if (presetIdx >= 0 && parts[presetIdx + 1])
+            framework = [normalizeFrameworkDir(parts[presetIdx + 1])];
+        if (coreIdx >= 0 && parts[coreIdx + 1])
+            framework = [normalizeFrameworkDir(parts[coreIdx + 1])];
+        if (parts.includes('faq'))
+            types.push('faq', 'error_code');
+        if (fileName === 'api.md')
+            types.push('api');
+        if (coreIdx >= 0)
+            types.push('api', 'feature');
+    }
+    else if (normalized.includes('/livekit/')) {
+        product = 'live';
+        if (parts.includes('voice'))
+            scenario = 'voice';
+        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])];
+            }
+        }
+        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');
+    }
+    else if (normalized.includes('/roomkit/')) {
+        product = 'room';
+        if (parts.includes('vue'))
+            framework = ['vue'];
+        if (parts.includes('features'))
+            types.push('feature');
+        if (parts.includes('faq'))
+            types.push('faq', 'error_code');
+    }
+    else if (normalized.startsWith('knowledge/trtc/')) {
+        product = 'native_trtc_sdk';
+        framework = [parts[2] ?? '*'];
+        types.push('api', 'error_code');
+    }
+    else if (normalized.startsWith('knowledge/rtcengine/')) {
+        product = 'rtcengine';
+        framework = ['web'];
+        if (parts.includes('plugin'))
+            types.push('plugin');
+        types.push('api', 'faq');
+    }
+    else if (normalized.startsWith('knowledge/push/')) {
+        // push 结构：
+        //   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]
+        product = 'push';
+        const category = parts[2]; // overview | integration | config
+        if (category === 'overview') {
+            framework = ['*'];
+            types.push('product');
+        }
+        else if (category === 'integration') {
+            const fwSlug = fileName.replace(/\.mdx?$/, ''); // android / ios / donut / ...
+            if (fwSlug) {
+                framework = [fwSlug];
+            }
+            types.push('integration');
+        }
+        else if (category === 'config' && parts[3]) {
+            // config/{platform}/{vendor}.md：platform 决定 framework，vendor 靠关键词
+            framework = [parts[3]];
+            types.push('integration');
+        }
+        else {
+            types.push('integration');
+        }
+    }
+    if (corpus === 'integration') {
+        types = ['integration'];
+    }
+    else if (types.length === 0) {
+        types = ['faq'];
+    }
+    types = inferTypesFromFilename(fileName, types);
+    if (types.length === 0)
+        types = ['faq'];
+    return {
+        product,
+        framework,
+        types: uniq(types),
+        scenario,
+        corpus,
+    };
+}

package/knowledge/search/exact-lookup.js

@@ -0,0 +1,330 @@
+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');
+export const DOC_PATH_MAP = {
+    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',
+    },
+};
+export function inferNativeTRTCIntents(prompt) {
+    const normalizedPrompt = prompt.toLowerCase();
+    if (/enterroom|exitroom|startlocalpreview|mutelocalaudio|trtccloud\.|setlocal|setremote/.test(normalizedPrompt)) {
+        return ['core_api'];
+    }
+    if (/错误|报错|error|warning|code|排查/.test(normalizedPrompt)) {
+        return ['error_code'];
+    }
+    if (/回调|事件|监听|delegate|listener|callback|on[A-Z]/.test(prompt)) {
+        return ['callback'];
+    }
+    if (/参数|结构体|枚举|typedef|type ?def|trtcparams|编码|配置/.test(normalizedPrompt)) {
+        return ['type_def'];
+    }
+    if (/统计|网络质量|码率|帧率|statistics/.test(normalizedPrompt)) {
+        return ['statistics'];
+    }
+    if (/音效|bgm|混响|耳返|audio/.test(normalizedPrompt)) {
+        return ['audio_effect'];
+    }
+    if (/美颜|滤镜|beauty/.test(normalizedPrompt)) {
+        return ['beauty'];
+    }
+    if (/设备|摄像头|麦克风|扬声器|device/.test(normalizedPrompt)) {
+        return ['device'];
+    }
+    return ['core_api', 'error_code'];
+}
+function loadJson(fileName, fallback) {
+    const filePath = path.join(SCHEMA_ROOT, fileName);
+    if (!fs.existsSync(filePath))
+        return fallback;
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+}
+function loadFeatureAliases() {
+    const filePath = path.join(SCHEMA_ROOT, 'feature-aliases.yaml');
+    if (!fs.existsSync(filePath))
+        return {};
+    const text = fs.readFileSync(filePath, 'utf-8');
+    const result = {};
+    let currentProduct = '';
+    for (const line of text.split('\n')) {
+        const productMatch = line.match(/^(\w+):$/);
+        if (productMatch) {
+            currentProduct = productMatch[1];
+            result[currentProduct] = {};
+            continue;
+        }
+        const aliasMatch = line.match(/^\s+([\w.-]+\.md):\s*\[(.+)\]/);
+        if (aliasMatch && currentProduct) {
+            const aliases = aliasMatch[2]
+                .split(',')
+                .map((s) => s.trim().replace(/^["']|["']$/g, ''))
+                .filter(Boolean);
+            result[currentProduct][aliasMatch[1]] = aliases;
+        }
+    }
+    return result;
+}
+export function runExactLookup(prompt, pool, norm) {
+    const boosts = {};
+    const exactHits = [];
+    const lowerPrompt = prompt.toLowerCase();
+    const addBoost = (chunk, amount, label) => {
+        boosts[chunk.id] = (boosts[chunk.id] ?? 0) + amount;
+        if (!exactHits.includes(label))
+            exactHits.push(label);
+    };
+    // E1: error codes
+    const errorMatches = [
+        ...prompt.matchAll(/\b(\d{5,7})\b/g),
+        ...prompt.matchAll(/\b(ERR_[A-Z0-9_]+)\b/g),
+    ];
+    for (const match of errorMatches) {
+        const code = match[1];
+        for (const chunk of pool) {
+            if (chunk.error_codes.includes(code) || chunk.title.includes(code)) {
+                addBoost(chunk, 200, `E1:${code}`);
+            }
+        }
+    }
+    // P1-3：跟踪 E2 已 boost 的文件，避免 E4 在同文件重复满额放大（双重 boost 会压垮 BM25 文件内排序）
+    const e2BoostedFiles = new Set();
+    // E2: native TRTC intents（只在传了 framework 时 boost；未传 framework 由 requires-framework 拦截）
+    // 衰减策略：同文件首 chunk +100，第 2 个 +50，第 3 个 +25 ...（下限 +5），
+    // 让 BM25 原始打分主导文件内方法级排序，避免「createSubCloud 顶掉 enterRoom」。
+    if (norm.product?.includes('native_trtc_sdk') && norm.frameworks?.length) {
+        const intents = inferNativeTRTCIntents(prompt);
+        for (const fw of norm.frameworks) {
+            const platformMap = DOC_PATH_MAP[fw];
+            if (!platformMap)
+                continue;
+            for (const intent of intents) {
+                const docName = platformMap[intent];
+                if (!docName)
+                    continue;
+                const target = `knowledge/trtc/${fw}/${docName}.md`;
+                // 收集同文件 chunks 按 char_start 排序（即文件内顺序）
+                const fileChunks = pool
+                    .filter((c) => c.source === target || c.source.endsWith(`/${docName}.md`))
+                    .sort((a, b) => a.char_start - b.char_start);
+                for (let i = 0; i < fileChunks.length; i += 1) {
+                    const decay = Math.max(5, Math.floor(100 / Math.pow(2, i)));
+                    addBoost(fileChunks[i], decay, `E2:${docName}`);
+                    e2BoostedFiles.add(fileChunks[i].source);
+                }
+            }
+        }
+    }
+    // E3: component slugs
+    const componentSlugs = loadJson('../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;
+    for (const [slug, aliases] of Object.entries(slugs)) {
+        const hit = [slug, ...aliases].some((alias) => lowerPrompt.includes(alias.toLowerCase()));
+        if (!hit)
+            continue;
+        for (const chunk of pool) {
+            if (chunk.source.includes(`components/${slug}.md`) ||
+                chunk.source.includes(`features/${slug}.md`)) {
+                addBoost(chunk, 100, `E3:${slug}`);
+            }
+        }
+    }
+    // E4: symbols / Class.method
+    // P1-3：若 chunk 所在文件已被 E2 boost，则 E4 减半（避免双重放大压制 BM25 内序）
+    const symbolMatches = [
+        ...prompt.matchAll(/\b([A-Z][A-Za-z0-9_]*\.[A-Za-z_]\w*)\b/g),
+        ...prompt.matchAll(/\b(use[A-Z]\w*)\b/g),
+        ...prompt.matchAll(/\b(TRTC[A-Za-z0-9_]+|TX[A-Za-z0-9_]+)\b/g),
+    ];
+    for (const match of symbolMatches) {
+        const symbol = match[1];
+        for (const chunk of pool) {
+            if (chunk.symbols.includes(symbol)) {
+                const amount = e2BoostedFiles.has(chunk.source) ? 50 : 100;
+                addBoost(chunk, amount, `E4:${symbol}`);
+            }
+        }
+    }
+    // E5: feature aliases
+    const featureAliases = loadFeatureAliases();
+    const productKey = norm.product?.includes('room') ? 'room'
+        : norm.product?.includes('chat') ? 'chat'
+            : norm.product?.includes('live') || !norm.product?.length ? 'live'
+                : '';
+    if (productKey && featureAliases[productKey]) {
+        for (const [fileName, aliases] of Object.entries(featureAliases[productKey])) {
+            const hit = aliases.some((alias) => lowerPrompt.includes(alias.toLowerCase()) || lowerPrompt.includes(fileName.replace('.md', '')));
+            if (!hit)
+                continue;
+            for (const chunk of pool) {
+                if (chunk.source.endsWith(fileName)) {
+                    addBoost(chunk, 100, `E5:${fileName}`);
+                }
+            }
+        }
+    }
+    if (norm.scenario === 'voice') {
+        for (const chunk of pool) {
+            if (chunk.source.includes('/voice/') && /co-guest|上麦/.test(lowerPrompt)) {
+                if (chunk.source.includes('voice-co-guest-interaction')) {
+                    addBoost(chunk, 120, 'E5:voice-co-guest');
+                }
+            }
+        }
+    }
+    // E5.5: push overview boost——当用户问 push 综述类问题时把 overview/prepare.md 顶到前列。
+    // 关键词分两类：
+    //   (1) prepare.md 标题语义：开通服务 / 接入流程 / 厂商配置 / SDK 接入 / 高级功能
+    //   (2) 自然入口问法：准备工作 / 前置 / 前提 / 注意事项 / 是什么 / 计费
+    // 否则 BM25 会把各平台 integration.md 顶上来（"步骤/集成"等词在多平台文档高频）。
+    if (norm.product?.includes('push')) {
+        const isOverviewIntent = /开通|创建\s*Push|创建应用|SDKAppID|控制台|数据中心|接入流程|接入推送|厂商配置|SDK\s*接入|高级功能|准备工作|准备|前置|前提|注意事项|是什么|介绍|计费/i.test(prompt);
+        if (isOverviewIntent) {
+            for (const chunk of pool) {
+                if (chunk.source.includes('knowledge/push/overview/')) {
+                    addBoost(chunk, 150, 'E5.5:push-overview');
+                }
+            }
+        }
+        // E5.6: push 厂商精确命中——prompt 提到具体厂商时，把对应 config/android/{vendor}.md 顶到前列
+        // 否则 BM25 会被 integration/donut.md 这类高密度多语言文档顶掉真正相关的厂商配置文档
+        const VENDOR_MAP = {
+            huawei: /华为|huawei|hms|harmonyconnect/i,
+            xiaomi: /小米|xiaomi|miui|mipush/i,
+            oppo: /\boppo\b|colorpush/i,
+            vivo: /\bvivo\b|vpush/i,
+            honor: /荣耀|honor/i,
+            meizu: /魅族|meizu|flymepush/i,
+            fcm: /\bfcm\b|google\s*推送|firebase/i,
+        };
+        for (const [vendor, regex] of Object.entries(VENDOR_MAP)) {
+            if (!regex.test(prompt))
+                continue;
+            for (const chunk of pool) {
+                if (chunk.source === `knowledge/push/config/android/${vendor}.md`) {
+                    addBoost(chunk, 120, `E5.6:push-vendor:${vendor}`);
+                }
+            }
+        }
+    }
+    // E6: chat urls boost（L1 URL 映射；错误码单独指向 urls/error-code.md）
+    if (!norm.product?.length || norm.product.includes('chat')) {
+        if (/payload|登录|usersig|鉴权/i.test(prompt)) {
+            for (const chunk of pool) {
+                if (chunk.source.includes('knowledge/chat/urls/')) {
+                    addBoost(chunk, 100, 'E6:chat-urls');
+                }
+            }
+        }
+        const errorCodeIntent = /错误码/i.test(prompt) || errorMatches.length > 0 || norm.types?.includes('error_code');
+        if (errorCodeIntent) {
+            for (const chunk of pool) {
+                if (chunk.source.includes('knowledge/chat/urls/error-code.md')) {
+                    addBoost(chunk, 180, 'E6:chat-error-code-url');
+                }
+            }
+        }
+        // E7: URL 映射表行级匹配（chunk.title = 子问题列；仅 boost 最佳行）
+        const queryNorm = prompt
+            .toLowerCase()
+            .replace(/rest\s*api|服务端|server\s*api|api|怎么|如何|什么|用哪个|查询/g, '')
+            .replace(/\s+/g, '');
+        if (queryNorm.length >= 2) {
+            const candidates = [];
+            for (const chunk of pool) {
+                if (!chunk.source.includes('knowledge/chat/urls/'))
+                    continue;
+                const titleNorm = chunk.title.toLowerCase().replace(/\s+/g, '');
+                if (!titleNorm)
+                    continue;
+                let score = 0;
+                if (queryNorm === titleNorm) {
+                    score = 1000;
+                }
+                else if (titleNorm.includes(queryNorm)) {
+                    const trailing = titleNorm.slice(titleNorm.indexOf(queryNorm) + queryNorm.length);
+                    score = 800 - trailing.length * 80;
+                }
+                else if (queryNorm.includes(titleNorm)) {
+                    score = 700 + titleNorm.length;
+                }
+                else {
+                    const queryLoose = queryNorm.replace(/发送/g, '发');
+                    if (queryLoose.length >= 3 && titleNorm.includes(queryLoose)) {
+                        score = 500;
+                        if (/批量|群组|群流|广播|导入|公众号|已读|回执/.test(titleNorm)
+                            && !/批量|群组|群|已读|回执/.test(queryNorm)) {
+                            score -= 250;
+                        }
+                        if (/^单发/.test(titleNorm) && /发送|单聊/.test(queryNorm)) {
+                            score += 120;
+                        }
+                    }
+                }
+                if (score > 0) {
+                    candidates.push({ chunk, score });
+                }
+            }
+            candidates.sort((a, b) => b.score - a.score);
+            const top = candidates[0];
+            if (top) {
+                addBoost(top.chunk, 200 + Math.min(top.score, 100), `E7:url-row:${top.chunk.title}`);
+                const runnerUp = candidates[1];
+                if (runnerUp && top.score - runnerUp.score <= 20) {
+                    addBoost(runnerUp.chunk, 150 + Math.min(runnerUp.score, 80), `E7:url-row:${runnerUp.chunk.title}`);
+                }
+            }
+        }
+    }
+    // E8: 集成查阅意图 boost——prompt 含集成/接入/快速开始/接入文档等意图词时，
+    // 把 {integration|knowledge}/{product}/preset/{fw}/integration.md 系列文件顶到前列。
+    // 解决问题：集成文档内容长、词密度低，BM25 原始分常被短小的 features/ 文档压过。
+    // 注：android-view / ios-uikit 已迁到 knowledge corpus，但同样是集成指引，需要一并 boost。
+    const isIntegrationIntent = /集成|接入|快速开始|快速接入|集成文档|接入文档|集成指南|接入指南|接入流程|集成步骤|如何接入|如何集成|怎么接入|怎么集成/i.test(prompt);
+    if (isIntegrationIntent && norm.product?.length && norm.frameworks?.length) {
+        for (const chunk of pool) {
+            if (!norm.product.includes(chunk.product))
+                continue;
+            const fwMatch = norm.frameworks.some((fw) => chunk.framework.includes(fw));
+            if (!fwMatch)
+                continue;
+            // 命中 preset/{fw}/integration.md 系列（含 integration/ 和 knowledge/ 两种 corpus）
+            if (!chunk.source.includes('/preset/') || (!chunk.source.endsWith('integration.md') && !chunk.source.endsWith('-integration.md')))
+                continue;
+            addBoost(chunk, 120, `E8:integration-doc:${chunk.source}`);
+        }
+    }
+    return { boosts, exactHits };
+}

package/knowledge/search/filter-pool.js

@@ -0,0 +1,86 @@
+/**
+ * MCP framework enum → index 中对应的 framework 值列表。
+ * path-meta.ts 已通过 normalizeFrameworkDir 把目录名归一到标准 framework，
+ * 所有产品的 framework 均已对齐枚举值，无需额外别名扩展。
+ * web 匹配 react/vue/web（Chat/Call/Live Web 端覆盖）。
+ */
+const FRAMEWORK_SEARCH_ALIASES = {};
+function expandFrameworks(framework) {
+    if (!framework)
+        return undefined;
+    if (framework === 'web')
+        return ['react', 'vue', 'web'];
+    return FRAMEWORK_SEARCH_ALIASES[framework] ?? [framework];
+}
+/** Chat 无独立 faq.md；types 含 faq 时改为检索 knowledge/chat 全语料（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');
+    }
+    return resolved.length ? resolved : undefined;
+}
+/** 单平台产品的隐式 framework 推断：避免对显然唯一的平台再发起询问 */
+function inferImplicitFramework(products, framework) {
+    if (framework)
+        return framework;
+    if (products?.length === 1 && products[0] === 'rtcengine')
+        return 'web';
+    return undefined;
+}
+export function normalizeParams(params) {
+    const limit = Math.min(Math.max(params.limit ?? 8, 1), 16);
+    const effectiveFramework = inferImplicitFramework(params.product, params.framework);
+    const frameworks = expandFrameworks(effectiveFramework);
+    const types = resolveTypes(params.product, params.types);
+    return {
+        prompt: params.prompt,
+        product: params.product,
+        framework: effectiveFramework,
+        frameworks,
+        types,
+        scenario: params.scenario,
+        limit,
+    };
+}
+/**
+ * 跨平台类型集合：framework=['*'] 的 chunk 仅在 type 命中这些时才视为合理。
+ * - server_api / webhook / product：天然跨平台
+ * - faq / error_code：URL 映射页（chat/urls/error-code.md）与 callkit/faq/ 等按平台分 faq 文件，
+ *   都标记为 framework=['*']，按 framework 检索时不应被武断排除
+ */
+const CROSS_PLATFORM_CHUNK_TYPES = new Set([
+    'server_api',
+    'webhook',
+    'product',
+    'faq',
+    'error_code',
+]);
+function chunkIsCrossPlatform(chunkTypes) {
+    return chunkTypes.some((t) => CROSS_PLATFORM_CHUNK_TYPES.has(t));
+}
+export function filterPool(chunks, norm) {
+    return chunks.filter((chunk) => {
+        if (norm.product && !norm.product.includes(chunk.product) && chunk.product !== '*') {
+            return false;
+        }
+        if (norm.frameworks?.length) {
+            const isWildcardChunk = chunk.framework.includes('*');
+            // 收紧：framework=['*'] 仅在该 chunk 明确是跨平台 type（product/server_api/webhook）时放行；
+            // 否则要求 chunk.framework 与请求 framework 有交集。
+            const wildcardAllowed = isWildcardChunk && chunkIsCrossPlatform(chunk.types);
+            const explicitMatch = norm.frameworks.some((fw) => chunk.framework.includes(fw));
+            if (!explicitMatch && !wildcardAllowed)
+                return false;
+        }
+        if (norm.scenario && chunk.scenario && chunk.scenario !== norm.scenario) {
+            return false;
+        }
+        if (norm.types?.length && !norm.types.some((t) => chunk.types.includes(t))) {
+            return false;
+        }
+        return true;
+    });
+}

package/knowledge/search/requires-framework.js

@@ -0,0 +1,72 @@
+const PLATFORM_TYPES = new Set([
+    'api',
+    'component',
+    'feature',
+    'plugin',
+    'sdk',
+    'integration',
+]);
+const CROSS_PLATFORM_TYPES = new Set(['server_api', 'webhook', 'product']);
+const CROSS_PLATFORM_PROMPT = /计费|套餐|价格|UserSig\s*原理|签发流程|控制台|服务端\s*REST|云\s*API|Webhook|回调/i;
+const PLATFORM_PROMPT = /API|组件|怎么用|怎么开|怎么设置|怎么配置|虚拟背景|屏幕分享|enterRoom|SDK|插件|集成步骤|客户端|Feature|主题定制|连麦|上麦/i;
+/**
+ * push 必须问平台的强信号：仅当 prompt 明确提到具体「平台」（android/ios/flutter/...）时才拦询问。
+ * 厂商（小米/OPPO/华为/FCM 等）不算平台——它们全部归属 android 厂商配置子分类（knowledge/push/config/android/{vendor}.md），
+ * 问厂商问题不需要再让用户选平台。
+ */
+const PUSH_PLATFORM_SPECIFIC_PROMPT = /\b(android|ios|flutter|harmonyos|react[\s-]?native|unity|unreal|donut|uni[\s-]?app)\b/i;
+/**
+ * push 综述关键词：直接对应 knowledge/push/overview/prepare.md 的两个二级标题
+ *   - "## 开通 Push 服务"      → 开通 / 创建应用 / SDKAppID / 控制台 / 数据中心
+ *   - "## 接入流程说明"         → 接入流程 / 厂商配置 / SDK 接入 / 高级功能设置
+ * 命中即跨平台综述，无需问平台。
+ */
+const PUSH_OVERVIEW_PROMPT = /开通|创建\s*Push|创建应用|SDKAppID|控制台|数据中心|接入流程|接入推送|厂商配置|SDK\s*接入|高级功能|离线推送(?!\s*怎么)/i;
+function hasProduct(norm, p) {
+    return !!(norm.product?.includes(p));
+}
+/** chat error-code URL 同时列了「服务端 / Web / Native」三类入口，必须先问平台才能定位 */
+function isChatErrorCodeAmbiguous(norm) {
+    if (!hasProduct(norm, 'chat'))
+        return false;
+    if (norm.framework)
+        return false;
+    if (norm.types?.includes('error_code'))
+        return true;
+    return /错误码|error\s*code|ERR_/i.test(norm.prompt);
+}
+/** 未传 framework 时，是否应先 present_framework_choice 再检索 */
+export function requiresFramework(norm) {
+    if (norm.framework)
+        return false;
+    // 硬规则：chat 错误码场景必须问平台（服务端 / Web / Native 三个 URL）
+    if (isChatErrorCodeAmbiguous(norm))
+        return true;
+    // push：判定逻辑（自上而下）
+    if (hasProduct(norm, 'push')) {
+        if (norm.types?.length && norm.types.every((t) => CROSS_PLATFORM_TYPES.has(t))) {
+            return false;
+        }
+        if (PUSH_PLATFORM_SPECIFIC_PROMPT.test(norm.prompt))
+            return true;
+        if (PUSH_OVERVIEW_PROMPT.test(norm.prompt))
+            return false;
+        return false;
+    }
+    // native_trtc_sdk：所有平台相关咨询都依赖具体客户端（android/ios/c++），必须先问
+    if (hasProduct(norm, 'native_trtc_sdk'))
+        return true;
+    if (CROSS_PLATFORM_PROMPT.test(norm.prompt))
+        return false;
+    if (norm.types?.length) {
+        if (norm.types.some((t) => PLATFORM_TYPES.has(t)))
+            return true;
+        if (norm.types.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))) {
+            return false;
+        }
+    }
+    return PLATFORM_PROMPT.test(norm.prompt);
+}