@lorrylurui/code-intelligence-mcp 2.0.4 → 2.0.6

package/README.md

@@ -10,6 +10,14 @@
 - Prompt: `reusable-code-advisor`
 - Cursor Skill：`reusable-code-advisor`（`.cursor/skills/reusable-code-advisor/`，
 
+## 开发
+
+```
+    1. npm run dev:mcp 启动mcp  server
+    2. npm run embedding:dev 启动本地python环境
+    3. npm run worker:embedding 启动worker队列
+```
+
 ## 1) 配置mcp servers
 
 ```
@@ -38,6 +46,39 @@
 MYSQL\*SYMBOLS_TABLE=frontend_collections_symbols
 INDEX_GLOB=xxx/\*\*/\_.{js,jsx,ts,tsx}
 
+# 召回效果优化
+
+你这个场景里，“召回优化”建议按 3 层做，效果最好：
+
+**1. 先把候选尽量捞全（Recall 层）**
+
+1. 提高语义检索候选池：把语义 `topK` 从现在的小值提高到 `50~200`，不要在第一层就截断太早。
+2. 语义 + 关键词并行召回：同时跑向量检索、名称/路径/描述关键词检索、结构字段检索（props/hooks/sideEffects），最后并集去重。
+3. 做查询扩展：`affix` 自动扩成 `fixed/sticky/offsetTop/offsetBottom/固钉/吸顶/吸底/固定定位`，提升召回覆盖率。
+4. 加别名词典：为组件建立别名（如 `Affix -> 固钉, 固定定位, sticky`），召回时强制并入。
+5. 路径先验加白名单：`Components/`、components这类目录可加权，`demo/examples/pages`不直接过滤，但降权。
+
+**2. 再做精排（Ranking 层）**
+
+1. 两阶段排序：第一阶段只看“能不能进池子”，第二阶段再做质量门槛。
+2. 显式命中强加权：用户 query 出现明确词（如 `affix`）时，名称/文件名命中要有明显 boost。
+3. 避免 usage 绑架：`usage_count` 只做弱特征，别让高 usage 的 demo/page 抢过真实组件。
+4. 引入轻量 reranker：对 Top-50 用交叉编码器或规则+LLM 打分，可明显提升 Top-1 准确率。
+
+**3. 建立评测闭环（Offline Eval）**
+
+1. 做一套 50~200 条真实查询集（中英混合、别名、口语化）。
+2. 每次改召回都跑：`Recall@10`、`Recall@50`、`MRR@10`、`nDCG@10`。
+3. 对失败样本做“误杀分析”：是没召回、被质量门槛挡掉、还是排序被 demo 抢位。
+
+你这个仓库当前最该优先做的 3 个点是：
+
+1. 把第一阶段候选池再放大（至少 50+）。
+2. 固化 query 扩展词典（Affix 这类高频组件先做）。
+3. 把质量门槛后移，先召回后精排，减少“找到了但被早期过滤掉”。
+
+如果你要，我可以下一步直接给你一版“可落地参数表”（每个阈值给默认值与调参范围），方便你马上 A/B。
+
 # 待优化项
 
 修复优先级：

package/dist/config/env.js

@@ -60,6 +60,15 @@ export const env = {
     get symbolsTable() {
         return process.env.SYMBOLS_TABLE ?? 'symbols';
     },
+    /**
+     * 文档 chunks 表名。
+     * 默认跟随 SYMBOLS_TABLE 派生，例如：symbols -> symbols_chunks，repo_a_symbols -> repo_a_symbols_chunks。
+     * 如需显式覆盖，仍可单独传入 CHUNKS_TABLE。
+     */
+    get chunksTable() {
+        const symbolsTable = process.env.SYMBOLS_TABLE ?? 'symbols';
+        return process.env.CHUNKS_TABLE ?? `${symbolsTable}_chunks`;
+    },
     /** Python FastAPI 嵌入服务根 URL，如 http://127.0.0.1:8765 */
     get embeddingServiceUrl() {
         return (process.env.EMBEDDING_SERVICE_URL ?? '').trim();

package/dist/config/tuning.js

@@ -0,0 +1,114 @@
+/**
+ * tuning.ts — 所有可调参数的集中配置。
+ *
+ * 生产环境中需要多次微调的阈值、权重和限制值均在此定义，
+ * 禁止在业务代码里直接写魔法数字。
+ */
+// ─── Chunk 切分参数 (chunkText.ts) ───────────────────────────────────────────
+/** 目标 chunk 字符数：达到此值后尽快在下一个边界处收敛当前块 */
+export const CHUNK_TARGET_CHARS = 900;
+/** 单个 chunk 最大字符数：超过此值必须做二次切分 */
+export const CHUNK_MAX_CHARS = 1200;
+/** 相邻 chunk 的重叠字符数：用于减少边界信息丢失 */
+export const CHUNK_OVERLAP_CHARS = 120;
+/** 句子/换行边界的最小位置比例：不足此比例则不回退到该边界，避免生成过短的 chunk */
+export const CHUNK_SENTENCE_BREAK_MIN_RATIO = 0.6;
+/** chunk 摘要的最大字符数（仅用于展示与 embedding 辅助信息） */
+export const CHUNK_SUMMARY_MAX_CHARS = 160;
+// ─── Chunk 语义检索参数 (chunkRepository.ts) ─────────────────────────────────
+/** 最低 cosine 相似度：低于此值的 chunk 不返回给调用方 */
+export const CHUNK_SIMILARITY_THRESHOLD = 0;
+/** 语义检索默认返回的 chunk 数量上限 */
+export const CHUNK_TOP_K = 8;
+// ─── Symbol 语义检索参数 (symbolRepository.ts) ───────────────────────────────
+/** 最低 cosine 相似度：低于此值的 symbol 不返回给调用方 */
+export const SYMBOL_SIMILARITY_THRESHOLD = 0;
+/** 语义检索默认返回的 symbol 数量上限 */
+export const SYMBOL_TOP_K = 20;
+// ─── Embedding 文本截断 (embedText.ts) ──────────────────────────────────────
+/** 源码片段送入 embedding 前的最大字符数，超出部分截断 */
+export const EMBED_MAX_CONTENT_LENGTH = 1200;
+// ─── 排名权重 (ranking.ts) ────────────────────────────────────────────────────
+/** 综合排名四维度权重，总和须为 1 */
+export const RANK_WEIGHTS = {
+    textMatch: 0.5,
+    usage: 0.3,
+    recency: 0.1,
+    commonPath: 0.1,
+};
+/** 每匹配到一个 callee 名称所增加的分数 */
+export const CALLEE_MATCH_SCORE_PER_MATCH = 0.05;
+/** callee 匹配分数的上限（防止大量 callee 匹配主导总分） */
+export const CALLEE_MATCH_SCORE_MAX = 0.2;
+/**
+ * Token 重叠度评分阶梯（按顺序匹配，首个满足条件的阶梯生效）。
+ * - minMatches: 查询 token 中至少命中的数量
+ * - minRatio: 命中比例下限
+ * - score: 对应的文本匹配分数
+ */
+export const TOKEN_OVERLAP_TIERS = [
+    { minMatches: 4, minRatio: 0.45, score: 0.78 },
+    { minMatches: 3, minRatio: 0.3, score: 0.68 },
+    { minMatches: 2, minRatio: 0.18, score: 0.56 },
+];
+/** 非 token-overlap 类型的文本匹配固定分数 */
+export const TEXT_MATCH_SCORES = {
+    nameContains: 0.85,
+    descriptionContains: 0.65,
+    weak: 0.2,
+};
+/**
+ * 时效性评分阶梯（按 maxDays 升序评估，首个满足条件的阶梯生效）。
+ * - maxDays: 创建距今天数上限
+ * - score: 对应的时效分数
+ */
+export const RECENCY_SCORE_TIERS = [
+    { maxDays: 7, score: 1.0 },
+    { maxDays: 30, score: 0.8 },
+    { maxDays: 90, score: 0.6 },
+    { maxDays: 180, score: 0.4 },
+];
+/** 无 createdAt 时使用的默认时效分数 */
+export const RECENCY_SCORE_DEFAULT = 0.4;
+/** createdAt 超出所有阶梯（>180天）时的最低时效分数 */
+export const RECENCY_SCORE_OLDEST = 0.25;
+/** 路径含 /common/ 或 /shared/ 的符号所获得的路径维度分数 */
+export const COMMON_PATH_SCORE_YES = 1;
+/** 路径不在 common/shared 目录时的路径维度分数 */
+export const COMMON_PATH_SCORE_NO = 0.35;
+/** 使用频率评分的 log 底数除数（值越大，曲线越平坦） */
+export const USAGE_SCORE_LOG_DIVISOR = 3;
+/** 语义相似度高于此值时，输出"语义相似度高"标签 */
+export const SEMANTIC_REASON_THRESHOLD_HIGH = 0.55;
+/** 语义相似度高于此值时，输出"语义相关"标签 */
+export const SEMANTIC_REASON_THRESHOLD_MED = 0.4;
+/** 使用频率分高于此值时，输出"使用频率高"标签 */
+export const USAGE_REASON_THRESHOLD_HIGH = 0.6;
+// ─── 推荐质量门控阈值 (recommendationService.ts) ─────────────────────────────
+/** 候选通过质量门控所需的最低综合分数 */
+export const MIN_RECOMMENDATION_SCORE = {
+    semantic: 0.5,
+    keyword: 0.45,
+};
+/** 语义模式下文本维度分数须达到的下限（用于高置信度路径） */
+export const MIN_SEMANTIC_TEXT_MATCH_SCORE = 0.6;
+/** 名称/路径字面命中时，放宽的综合分数下限 */
+export const MIN_LITERAL_MATCH_SCORE = 0.18;
+/** props/hooks 结构字段全部命中时，放宽的综合分数下限 */
+export const REQUIRED_FIELD_FALLBACK_MIN_SCORE = 0.4;
+/** 字面命中（名称或文件名匹配查询词）时，对优先级分数增加的值 */
+export const LITERAL_MATCH_PRIORITY_BOOST = 0.22;
+/** 路径为 demo/example 风格时，对优先级分数扣减的值 */
+export const DEMO_PATH_PRIORITY_PENALTY = 0.18;
+// ─── 搜索工具结果过滤 (tools/searchSymbols.ts) ───────────────────────────────
+/** 最终返回结果所需的最低综合评分 */
+export const SEARCH_SCORE_THRESHOLD = 0.45;
+/** 最终返回的 symbol 数量上限 */
+export const SEARCH_TOP_K = 20;
+// ─── RAG 上下文组装参数 (services/contextAssembler.ts) ───────────────────────
+/** 每个命中 chunk 向前后各扩展的邻块数量（减少边界截断信息丢失） */
+export const CONTEXT_ADJACENT_RADIUS = 1;
+/** 注入 prompt 的上下文总字符数预算（超出则从相似度最低的 chunk 开始截断） */
+export const CONTEXT_MAX_CHARS = 6000;
+/** 邻块扩展后保留的最大 chunk 数量 */
+export const CONTEXT_MAX_CHUNKS = 12;

package/dist/db/schema.js

@@ -49,3 +49,40 @@ export function getAllTableSQLs() {
         ...getSymbolsIndexSQLs(),
     ];
 }
+export function getChunksTableSQL() {
+    const tableName = env.chunksTable;
+    return `CREATE TABLE IF NOT EXISTS ${tableName} (
+  id            SERIAL PRIMARY KEY,
+  source_id     VARCHAR(255),
+  title         TEXT NOT NULL,
+  path          TEXT NOT NULL,
+  chunk_index   INT NOT NULL,
+  chunk_count   INT NOT NULL,
+  content       TEXT NOT NULL,
+  summary       TEXT,
+  category      VARCHAR(255),
+  meta          JSONB,
+  embedding     vector(384),
+  semantic_hash VARCHAR(64) NOT NULL,
+  status        SMALLINT NOT NULL DEFAULT ${DEFAULT_STATUS_ON_UPSERT},
+  created_at    TIMESTAMP NOT NULL DEFAULT NOW(),
+  updated_at    TIMESTAMP NOT NULL DEFAULT NOW(),
+  CONSTRAINT uk_${tableName}_path_chunk UNIQUE (path, chunk_index)
+)`;
+}
+export function getChunksIndexSQLs() {
+    const t = env.chunksTable;
+    return [
+        `CREATE INDEX IF NOT EXISTS idx_${t}_source_id ON ${t}(source_id)`,
+        `CREATE INDEX IF NOT EXISTS idx_${t}_semantic_hash ON ${t}(semantic_hash)`,
+        `CREATE INDEX IF NOT EXISTS idx_${t}_status ON ${t}(status)`,
+        `CREATE INDEX IF NOT EXISTS idx_${t}_path ON ${t}(path)`,
+    ];
+}
+export function getAllChunkTableSQLs() {
+    return [
+        getEnsureExtensionSQL(),
+        getChunksTableSQL(),
+        ...getChunksIndexSQLs(),
+    ];
+}

package/dist/index.js

@@ -6,6 +6,7 @@ async function main() {
     // 加载第三方项目的 .env（通过 INDEX_ROOT 指定，或默认当前工作目录）
     const projectRoot = process.env.INDEX_ROOT || process.cwd();
     loadProjectDotenv(projectRoot);
+    console.error('[code-intelligence-mcp] env.loaded env.projectRoot=%s', projectRoot);
     const server = createServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/indexer/babelParser.js

@@ -357,6 +357,7 @@ function createRowFromFunction(name, decl, filePath, projectRoot, isJsx) {
 function createRowFromClass(name, _decl, filePath, projectRoot) {
     const relPath = getRelativePathForDisplay(projectRoot, filePath);
     const category = inferCategoryFromPath(filePath);
+    const jsdoc = parseJsDocInfo(_decl);
     // 大写开头的类视为组件
     const type = /^[A-Z]/.test(name) ? 'component' : 'function';
     return {
@@ -364,7 +365,7 @@ function createRowFromClass(name, _decl, filePath, projectRoot) {
         type,
         category,
         path: relPath,
-        description: null,
+        description: jsdoc.description,
         // content meta.kind 暂时废弃不用，
         content: null,
         meta: {},

package/dist/indexer/chunkText.js

@@ -0,0 +1,164 @@
+import { createHash } from 'node:crypto';
+import { CHUNK_MAX_CHARS, CHUNK_OVERLAP_CHARS, CHUNK_SENTENCE_BREAK_MIN_RATIO, CHUNK_SUMMARY_MAX_CHARS, CHUNK_TARGET_CHARS, } from '../config/tuning.js';
+// 统一换行并去掉首尾空白，避免切分时混入无意义差异。
+function normalizeText(content) {
+    return content.replace(/\r\n/g, '\n').trim();
+}
+// 第一阶段：先按 Markdown 风格结构拆成 heading / paragraph / code 三类 block。
+function splitCodeAwareBlocks(content) {
+    const normalized = normalizeText(content);
+    if (!normalized)
+        return [];
+    const lines = normalized.split('\n');
+    const blocks = [];
+    let buffer = [];
+    let inCodeFence = false; // 追踪是否在代码块内，避免误把代码内容当普通文本切分。
+    const flushParagraphs = () => {
+        if (buffer.length === 0)
+            return;
+        const text = buffer.join('\n').trim();
+        buffer = [];
+        if (!text)
+            return;
+        const kind = text.startsWith('#') ? 'heading' : 'paragraph';
+        blocks.push({ kind, text });
+    };
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith('```')) {
+            if (inCodeFence) {
+                buffer.push(line);
+                blocks.push({ kind: 'code', text: buffer.join('\n').trim() });
+                buffer = [];
+                inCodeFence = false;
+            }
+            else {
+                flushParagraphs();
+                inCodeFence = true;
+                buffer.push(line);
+            }
+            continue;
+        }
+        if (inCodeFence) {
+            buffer.push(line);
+            continue;
+        }
+        if (trimmed.startsWith('#')) {
+            flushParagraphs();
+            blocks.push({ kind: 'heading', text: trimmed });
+            continue;
+        }
+        if (!trimmed) {
+            flushParagraphs();
+            continue;
+        }
+        buffer.push(line);
+    }
+    flushParagraphs();
+    return blocks;
+}
+// 第二阶段：如果某个单独 block 过长，再按自然边界做窗口切分，并保留 overlap。
+function sliceWithOverlap(text, maxChars, overlapChars) {
+    const normalized = text.trim();
+    if (!normalized)
+        return [];
+    if (normalized.length <= maxChars)
+        return [normalized];
+    const out = [];
+    let start = 0;
+    while (start < normalized.length) {
+        let end = Math.min(start + maxChars, normalized.length);
+        if (end < normalized.length) {
+            const window = normalized.slice(start, end);
+            // 优先回退到更自然的句子/换行边界，避免把一句话截成两半。
+            const sentenceBreak = Math.max(window.lastIndexOf('. '), window.lastIndexOf('。'), window.lastIndexOf('! '), window.lastIndexOf('? '), window.lastIndexOf('\n'));
+            if (sentenceBreak >
+                Math.floor(maxChars * CHUNK_SENTENCE_BREAK_MIN_RATIO)) {
+                // 边界不能太靠前，否则可能导致过多 chunk 和过短的上下文，设置一个阈值（如 maxChars 的 60%）来平衡。
+                end = start + sentenceBreak + 1;
+            }
+        }
+        out.push(normalized.slice(start, end).trim());
+        if (end >= normalized.length)
+            break;
+        start = Math.max(end - overlapChars, start + 1);
+    }
+    return out.filter(Boolean);
+}
+// 将当前累计 block 收敛成一个 chunk，并把末尾 overlap 作为下一块的前缀上下文。
+function finalizeChunk(chunks, currentBlocks, overlapChars) {
+    if (currentBlocks.length === 0)
+        return [];
+    const chunk = currentBlocks.join('\n\n').trim();
+    if (!chunk)
+        return [];
+    chunks.push(chunk);
+    if (overlapChars <= 0)
+        return [];
+    // 从上一个 chunk 末尾切出 overlapChars 长度的文本，作为下一 chunk 的前置上下文，减少边界信息丢失。
+    const tail = chunk.slice(-overlapChars).trim();
+    return tail ? [tail] : [];
+}
+// 对外主入口：结构切分优先，其次按 target/max 控制块大小，最后用 overlap 补边界。
+export function splitTextIntoChunks(content, options = {}) {
+    const targetChars = options.targetChars ?? CHUNK_TARGET_CHARS;
+    const maxChars = options.maxChars ?? CHUNK_MAX_CHARS;
+    const overlapChars = options.overlapChars ?? CHUNK_OVERLAP_CHARS;
+    // 1. 语义切分：按照结构拆分（eg: ```, #）
+    const blocks = splitCodeAwareBlocks(content);
+    if (blocks.length === 0)
+        return [];
+    const chunks = []; // 每一个元素是如下结构组成的字符串：0-首行，之后的索引对应值都是：上一个 chunk 的末尾 overlap 文本 + 当前 block 文本，块与块之间用双换行分隔。
+    let currentBlocks = [];
+    let currentLength = 0;
+    for (const block of blocks) {
+        // 2. 自然边界切分：每一个block再按照[.。!?、换行等]自然边界切分
+        const oversizedParts = block.text.length > maxChars
+            ? sliceWithOverlap(block.text, maxChars, overlapChars)
+            : [block.text];
+        for (const part of oversizedParts) {
+            // 3. overlap 滑动窗口：每当累计块接近目标大小或即将超出上限时，先把当前块收敛成一个 chunk，再开始下一块。每个新块的开头会带上前一个块末尾 overlapChars 长度的文本，减少边界信息丢失。
+            const additionLength = currentLength === 0 ? part.length : part.length + 2;
+            const wouldOverflowMax = currentLength > 0 && currentLength + additionLength > maxChars;
+            const reachedTarget = currentLength >= targetChars;
+            // 已接近目标大小或即将超出上限时，先收敛当前 chunk，再开始下一块。
+            if (wouldOverflowMax || reachedTarget) {
+                currentBlocks = finalizeChunk(chunks, currentBlocks, overlapChars);
+                currentLength = currentBlocks.join('\n\n').length;
+            }
+            currentBlocks.push(part);
+            currentLength = currentBlocks.join('\n\n').length;
+        }
+    }
+    finalizeChunk(chunks, currentBlocks, 0);
+    return chunks;
+}
+// 截取 chunk，做chunk embedding 时的摘要展示，提升检索结果的可读性和判断相关性的效率。
+function buildChunkSummary(content) {
+    const flattened = content.replace(/\s+/g, ' ').trim();
+    if (!flattened)
+        return null;
+    return flattened.slice(0, CHUNK_SUMMARY_MAX_CHARS);
+}
+// chunk hash 以 path + chunkIndex + content 生成，用于稳定标识具体分块。
+function computeChunkHash(path, chunkIndex, content) {
+    return createHash('sha256')
+        .update(`${path}#${chunkIndex}\n${content}`)
+        .digest('hex');
+}
+// 将原始文档输入转为可入库的 chunk 记录，附带索引、总块数、摘要和 semantic hash。
+export function buildDocumentChunks(document, options = {}) {
+    const chunks = splitTextIntoChunks(document.content, options);
+    return chunks.map((content, index) => ({
+        sourceId: document.sourceId ?? null,
+        title: document.title,
+        path: document.path,
+        chunkIndex: index,
+        chunkCount: chunks.length,
+        content,
+        summary: buildChunkSummary(content),
+        category: document.category ?? null,
+        meta: document.metadata ?? null,
+        semanticHash: computeChunkHash(document.path, index, content),
+    }));
+}

package/dist/indexer/embedText.js

@@ -1,5 +1,5 @@
 // 仅js类型使用，后续会删掉
-const MAX_CONTENT_LENGTH = 1200;
+import { EMBED_MAX_CONTENT_LENGTH } from '../config/tuning.js';
 function briefMeta(meta) {
     const keys = ['props', 'params', 'properties', 'hooks'];
     const parts = [];
@@ -23,7 +23,7 @@ export function indexedRowToEmbedText(row) {
         row.path,
         row.description ?? '',
         metaBit,
-        (row.content ?? '').slice(0, MAX_CONTENT_LENGTH),
+        (row.content ?? '').slice(0, EMBED_MAX_CONTENT_LENGTH),
     ]
         .filter((s) => s.length > 0)
         .join('\n');