@tencent-rtc/mcp 1.4.7 → 1.6.0

package/index.js

@@ -18,4 +18,3 @@ main().catch((error) => {
     console.error('Server error:', error);
     process.exit(1);
 });
-//# sourceMappingURL=index.js.map

package/knowledge/bm25-cache.js

@@ -0,0 +1,73 @@
+import { attachPoolContent } from './content-loader.js';
+import { buildBM25Index, chunkSearchText } from './bm25.js';
+/**
+ * 按 product 维度 lazy 构建 BM25 索引并进程内缓存。
+ *
+ * 设计要点：
+ * - cache key = product（未指定时用 '*'，对全 manifest 建索引）
+ * - 索引基于该 product 全部 chunks（含 integration corpus），子集 ranking 只看 filteredPool.map(id)
+ * - 首次按 product 触发，后续命中缓存零开销；约 8 个 product 自然分摊冷启动成本
+ * - 不落盘，纯进程常驻；体积粗估 8~12MB（postings + idf）
+ */
+const indexCache = new Map();
+const GLOBAL_KEY = '*';
+function cacheKey(product) {
+    return product ?? GLOBAL_KEY;
+}
+function selectProductChunks(allChunks, product) {
+    if (!product)
+        return allChunks;
+    return allChunks.filter((chunk) => chunk.product === product || chunk.product === '*');
+}
+/**
+ * 获取 product 级 BM25 索引：缓存命中则零开销，否则按 product 切 chunks，
+ * attachPoolContent 拉正文后一次性建索引并入缓存。
+ *
+ * 性能特征：
+ * - 命中：O(1)
+ * - miss：O(P · avgDocLen) 仅一次，P 为该 product 的 chunk 数
+ */
+export function getProductBM25Index(allChunks, product) {
+    const key = cacheKey(product);
+    const cached = indexCache.get(key);
+    if (cached)
+        return cached;
+    const productChunks = selectProductChunks(allChunks, product);
+    const withContent = attachPoolContent(productChunks);
+    const index = buildBM25Index(withContent.map((chunk) => ({
+        id: chunk.id,
+        text: chunkSearchText(chunk),
+    })));
+    indexCache.set(key, index);
+    return index;
+}
+/**
+ * 多 product BM25 索引：products 数组中有任一未缓存时，
+ * 合并所有指定 product 的 chunks 构建索引并缓存（key = 排序 join）。
+ */
+export function getProductsBM25Index(allChunks, products) {
+    if (!products || products.length === 0)
+        return getProductBM25Index(allChunks, undefined);
+    if (products.length === 1)
+        return getProductBM25Index(allChunks, products[0]);
+    const key = [...products].sort().join('|');
+    const cached = indexCache.get(key);
+    if (cached)
+        return cached;
+    const productChunks = allChunks.filter((chunk) => products.includes(chunk.product) || chunk.product === '*');
+    const withContent = attachPoolContent(productChunks);
+    const index = buildBM25Index(withContent.map((chunk) => ({
+        id: chunk.id,
+        text: chunkSearchText(chunk),
+    })));
+    indexCache.set(key, index);
+    return index;
+}
+/** 测试用：清空缓存（生产代码不应调用） */
+export function clearBM25Cache() {
+    indexCache.clear();
+}
+/** 调试用：返回当前缓存的 product 列表 */
+export function listCachedProducts() {
+    return [...indexCache.keys()];
+}

package/knowledge/bm25.js

@@ -0,0 +1,147 @@
+const K1 = 1.5;
+const B = 0.75;
+/**
+ * 中文停用词：高频功能词，参与 BM25 会稀释关键术语权重。
+ * 覆盖：疑问代词、助词、人称、连接词、模糊量词、敬辞。
+ */
+const CN_STOPWORDS = new Set([
+    '怎么', '如何', '什么', '哪些', '哪个', '为何', '为啥', '是否',
+    '可以', '能够', '需要', '想要', '应该', '请问', '麻烦',
+    '一下', '一个', '这个', '那个', '这些', '那些', '里面', '外面',
+    '使用', '用法', '用于', '用来', '进行', '实现', '提供', '支持',
+    '问题', '情况', '场景', '方式', '方法', '功能', '能力',
+    '我们', '你们', '他们', '自己', '大家',
+    '以及', '或者', '还是', '但是', '然后', '所以', '因为', '如果',
+    '已经', '正在', '马上', '立即', '总是', '一直',
+]);
+/** 英文停用词：限制在常见 query 噪声词，避免误删技术语义词（如 'use', 'set' 这种命名前缀保留） */
+const EN_STOPWORDS = new Set([
+    'a', 'an', 'the', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+    'and', 'or', 'but', 'if', 'then', 'so', 'as', 'of', 'at', 'by', 'for', 'in', 'on', 'to',
+    'do', 'does', 'did', 'have', 'has', 'had',
+    'this', 'that', 'these', 'those',
+    'how', 'what', 'why', 'when', 'where', 'which', 'who',
+    'i', 'we', 'you', 'they', 'it', 'me', 'us', 'them',
+    'pls', 'please', 'thanks',
+]);
+function isStopwordCJK(token) {
+    return CN_STOPWORDS.has(token);
+}
+function isStopwordEN(token) {
+    return EN_STOPWORDS.has(token);
+}
+export function tokenize(text) {
+    const tokens = [];
+    const lower = text.toLowerCase();
+    // 英文/数字 token：跳过停用词；保留长度 ≥ 2 的（避免单字符 'i', 'a' 漏入）
+    for (const match of lower.matchAll(/[a-z0-9_]+/g)) {
+        const tok = match[0];
+        if (tok.length === 1)
+            continue;
+        if (isStopwordEN(tok))
+            continue;
+        tokens.push(tok);
+    }
+    // 中文 token：bigram + unigram 两级
+    // - bigram：跳过包含停用词单字的组合（如「怎么调用」的「怎么」）以及任一位是常见停用字
+    // - unigram：跳过纯停用单字（用一个收敛的单字停用集合）
+    const cjk = text.replace(/[^\u4e00-\u9fff]/g, '');
+    for (let i = 0; i < cjk.length - 1; i += 1) {
+        const bigram = cjk.slice(i, i + 2);
+        if (isStopwordCJK(bigram))
+            continue;
+        tokens.push(bigram);
+    }
+    // 单字仅保留有信息量的（中文单字普遍信息量低，全部塞入会拉低 IDF；
+    // 简化策略：只在 bigram 路径之外补充长度 ≥ 3 的连续单字组合的首尾，避免噪声爆炸）
+    // 实践上保留 unigram 但不参与停用词过滤——让 BM25 的 IDF 自然衰减它们的权重。
+    for (let i = 0; i < cjk.length; i += 1) {
+        tokens.push(cjk[i]);
+    }
+    return tokens;
+}
+export function buildBM25Index(documents) {
+    const postings = {};
+    const docLengths = {};
+    const docFreq = {};
+    let totalLength = 0;
+    for (const doc of documents) {
+        const tokens = tokenize(doc.text);
+        docLengths[doc.id] = tokens.length;
+        totalLength += tokens.length;
+        const termFreq = {};
+        for (const token of tokens) {
+            termFreq[token] = (termFreq[token] ?? 0) + 1;
+        }
+        for (const [term, freq] of Object.entries(termFreq)) {
+            if (!postings[term])
+                postings[term] = {};
+            postings[term][doc.id] = freq;
+            docFreq[term] = (docFreq[term] ?? 0) + 1;
+        }
+    }
+    const n = documents.length;
+    const avgDocLength = n > 0 ? totalLength / n : 0;
+    const idf = {};
+    for (const [term, df] of Object.entries(docFreq)) {
+        idf[term] = Math.log(1 + (n - df + 0.5) / (df + 0.5));
+    }
+    return {
+        version: 1,
+        avgDocLength,
+        docLengths,
+        idf,
+        postings,
+    };
+}
+export function scoreBM25(query, chunkId, index) {
+    const tokens = tokenize(query);
+    const docLength = index.docLengths[chunkId] ?? 0;
+    if (docLength === 0)
+        return 0;
+    let score = 0;
+    for (const term of tokens) {
+        const tf = index.postings[term]?.[chunkId] ?? 0;
+        if (tf === 0)
+            continue;
+        const idf = index.idf[term] ?? 0;
+        const numerator = tf * (K1 + 1);
+        const denominator = tf + K1 * (1 - B + B * (docLength / (index.avgDocLength || 1)));
+        score += idf * (numerator / denominator);
+    }
+    return score;
+}
+export function rankBM25(query, chunkIds, index, boosts = {}) {
+    return chunkIds
+        .map((id) => ({
+        id,
+        score: scoreBM25(query, id, index) + (boosts[id] ?? 0),
+    }))
+        .sort((a, b) => b.score - a.score);
+}
+/**
+ * BM25 检索文本：title 重复 3 次以提权（标题语义浓度远高于正文，按业界惯例 boost）。
+ * symbols / error_codes 同样保留以便精确名匹配；正文走原内容。
+ */
+export function chunkSearchText(parts) {
+    const titleBoosted = [parts.title, parts.title, parts.title].filter(Boolean).join(' ');
+    return [titleBoosted, parts.content ?? '', ...parts.symbols, ...parts.error_codes].filter(Boolean).join(' ');
+}
+export function rankPoolBM25(query, pool, boosts = {}) {
+    if (pool.length === 0)
+        return [];
+    const index = buildBM25Index(pool.map((chunk) => ({
+        id: chunk.id,
+        text: chunkSearchText(chunk),
+    })));
+    return rankBM25(query, pool.map((chunk) => chunk.id), index, boosts);
+}
+/**
+ * 基于预构建的 BM25 索引对一个 chunk-id 子集打分，跳过 tokenize + IDF 重算。
+ * 调用方需保证 chunkIds ⊆ index 已收录的 id 集合，否则未收录的 id 会返回 score=0。
+ */
+export function rankSubsetWithIndex(query, chunkIds, index, boosts = {}) {
+    if (chunkIds.length === 0)
+        return [];
+    return rankBM25(query, chunkIds, index, boosts);
+}

package/knowledge/build-index.js

@@ -0,0 +1,69 @@
+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');
+function walkMarkdownFiles(dir, baseRel) {
+    if (!fs.existsSync(dir))
+        return [];
+    const files = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const rel = `${baseRel}/${entry.name}`.replace(/\\/g, '/');
+        const abs = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === 'native_live')
+                continue;
+            files.push(...walkMarkdownFiles(abs, rel));
+        }
+        else if (entry.name.endsWith('.md') && entry.name !== 'workflow.md') {
+            files.push(rel);
+        }
+    }
+    return files;
+}
+function collectComponentSlugs(chunks) {
+    const slugs = {};
+    for (const chunk of chunks) {
+        const componentsMatch = chunk.source.match(/components\/([^/]+)\.md$/);
+        const chatFeaturesMatch = chunk.source.match(/^knowledge\/chat\/preset\/(vue|react)\/features\/([^/]+)\.md$/);
+        const slug = componentsMatch?.[1] ?? chatFeaturesMatch?.[2];
+        if (!slug)
+            continue;
+        slugs[slug] = [slug, slug.replace(/-/g, ''), slug.replace(/-/g, '_')];
+    }
+    return slugs;
+}
+export function buildKnowledgeIndex() {
+    const sources = [
+        ...walkMarkdownFiles(path.join(RESOURCE_ROOT, 'knowledge'), 'knowledge'),
+        ...walkMarkdownFiles(path.join(RESOURCE_ROOT, 'integration'), 'integration'),
+    ];
+    const chunks = [];
+    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 indexDir = path.join(RESOURCE_ROOT, 'index');
+    fs.mkdirSync(indexDir, { recursive: true });
+    const manifest = {
+        version: 1,
+        built_at: new Date().toISOString(),
+        chunks,
+    };
+    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);
+    }
+    console.warn(`build-knowledge-index: ${chunks.length} chunks (manifest-lite) from ${sources.length} files`);
+}

package/knowledge/chunker.js

@@ -0,0 +1,167 @@
+import { extractErrorCodes, extractSymbols } from './extractors.js';
+function slugify(text) {
+    return text
+        .trim()
+        .toLowerCase()
+        .replace(/[^\w\u4e00-\u9fff]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'section';
+}
+function sourceSlug(source) {
+    return source.replace(/\.md$/, '').replace(/[/\\]/g, '-');
+}
+function trimSliceOffsets(raw, fileStart) {
+    const leading = raw.length - raw.trimStart().length;
+    const trailing = raw.length - raw.trimEnd().length;
+    const char_start = fileStart + leading;
+    const char_end = fileStart + raw.length - trailing;
+    return { body: raw.slice(leading, raw.length - trailing), char_start, char_end };
+}
+function splitByHeading(content, level) {
+    const regex = new RegExp(`^${'#'.repeat(level)}\\s+(.+)$`, 'gm');
+    const sections = [];
+    const matches = [...content.matchAll(regex)];
+    if (matches.length === 0) {
+        return [{ title: 'full', raw: content, start: 0 }];
+    }
+    for (let i = 0; i < matches.length; i += 1) {
+        const match = matches[i];
+        const start = match.index ?? 0;
+        const end = i + 1 < matches.length ? (matches[i + 1].index ?? content.length) : content.length;
+        sections.push({
+            title: match[1].trim(),
+            raw: content.slice(start, end),
+            start,
+        });
+    }
+    return sections;
+}
+function isFaqLike(source, content) {
+    return /faq|error-code|error_code|TXLiteAVCode/i.test(source) || (content.match(/^###\s+/gm) ?? []).length >= 3;
+}
+function isChatUrlMapping(source) {
+    return /knowledge\/chat\/urls\/.+\.md$/i.test(source.replace(/\\/g, '/'));
+}
+function parseUrlMappingRows(content) {
+    const lines = content.split('\n');
+    let sectionTitle = '';
+    let offset = 0;
+    const rows = [];
+    for (const line of lines) {
+        const lineStart = offset;
+        const lineEnd = offset + line.length;
+        const heading = line.match(/^#{2,3}\s+(.+)$/);
+        if (heading) {
+            sectionTitle = heading[1].trim();
+            offset = lineEnd + 1;
+            continue;
+        }
+        const rowMatch = line.match(/^\|\s*([^|]+?)\s*\|\s*`?(https?:\/\/[^|`\s]+)`?\s*\|/);
+        if (rowMatch) {
+            const label = rowMatch[1].trim();
+            if (label && label !== '子问题' && label !== 'Query' && label !== 'Topic' && !/^-+$/.test(label)) {
+                rows.push({
+                    label,
+                    url: rowMatch[2],
+                    sectionTitle,
+                    lineStart,
+                    lineEnd,
+                });
+            }
+        }
+        offset = lineEnd + 1;
+    }
+    return rows;
+}
+function chunkUrlMapping(source, content, meta) {
+    const rows = parseUrlMappingRows(content);
+    if (rows.length === 0) {
+        return [];
+    }
+    const baseSlug = sourceSlug(source);
+    const chunks = [];
+    for (const row of rows) {
+        const sectionLine = row.sectionTitle ? `### ${row.sectionTitle}\n\n` : '';
+        const body = `${sectionLine}| Query | Documentation |\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;
+}
+export function chunkMarkdown(source, content, meta) {
+    const chunks = [];
+    const baseSlug = sourceSlug(source);
+    if (isChatUrlMapping(source)) {
+        const urlChunks = chunkUrlMapping(source, content, meta);
+        if (urlChunks.length > 0) {
+            return urlChunks;
+        }
+    }
+    if (content.length < 2048) {
+        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,
+        });
+        return chunks;
+    }
+    const level = 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,
+        });
+    }
+    return chunks.length > 0 ? chunks : chunkMarkdown(source, content.slice(0, 2048), meta);
+}
+export function toManifestChunk(chunk) {
+    const { content: _content, ...manifestChunk } = chunk;
+    return manifestChunk;
+}
+function pathBasename(source) {
+    const parts = source.split('/');
+    const file = parts[parts.length - 1] ?? source;
+    return file.replace(/\.md$/, '');
+}

package/knowledge/content-loader.js

@@ -0,0 +1,39 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const fileCache = new Map();
+function resolveResourceRoot() {
+    // npm: knowledge/ → ../resource/ 到包根；dev: dist/knowledge/ → ../resource/ 到 dist/resource/
+    return path.resolve(__dirname, '../resource');
+}
+function readSourceFile(source) {
+    const cached = fileCache.get(source);
+    if (cached !== undefined)
+        return cached;
+    const abs = path.join(resolveResourceRoot(), source);
+    const text = fs.readFileSync(abs, 'utf-8');
+    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);
+    return full.slice(chunk.char_start, chunk.char_end);
+}
+export function attachChunkContent(chunk) {
+    return { ...chunk, content: getChunkContent(chunk) };
+}
+/** 预读 pool 涉及的唯一 source，再批量挂载 content（供 BM25 与 fragments 使用） */
+export function attachPoolContent(pool) {
+    for (const source of new Set(pool.map((chunk) => chunk.source))) {
+        readSourceFile(source);
+    }
+    return pool.map((chunk) => attachChunkContent(chunk));
+}
+export function clearContentCache() {
+    fileCache.clear();
+}

package/knowledge/doc-url-resolver.js

@@ -0,0 +1,142 @@
+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 = /trtc\.io|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)
+        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;
+    if (LOCALHOST_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;
+}
+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 = {};
+    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;
+}

package/knowledge/extractors.js

@@ -0,0 +1,25 @@
+export function extractSymbols(content) {
+    const symbols = new Set();
+    for (const match of content.matchAll(/`([A-Za-z_][\w.]*)`/g)) {
+        symbols.add(match[1]);
+    }
+    for (const match of content.matchAll(/\b(use[A-Z]\w*)\b/g)) {
+        symbols.add(match[1]);
+    }
+    for (const match of content.matchAll(/\b([A-Z][A-Za-z0-9_]{2,})\b/g)) {
+        if (/^(TRTC|TX|ITX|ITRTC|V2TX|Login|Device|Room|Live|Call|CoGuest|CoHost|Battle|Gift|Barrage|Like|Seat|Audience|Beauty|Audio)/.test(match[1])) {
+            symbols.add(match[1]);
+        }
+    }
+    return [...symbols].slice(0, 50);
+}
+export function extractErrorCodes(content) {
+    const codes = new Set();
+    for (const match of content.matchAll(/\b(\d{5,7})\b/g)) {
+        codes.add(match[1]);
+    }
+    for (const match of content.matchAll(/\b(ERR_[A-Z0-9_]+)\b/g)) {
+        codes.add(match[1]);
+    }
+    return [...codes];
+}