@lorrylurui/code-intelligence-mcp 2.0.4 → 2.0.6

package/dist/repositories/symbolRepository.js

@@ -1,9 +1,8 @@
 import { env } from '../config/env.js';
 import { getPool } from '../db/postgres.js';
+import { SYMBOL_SIMILARITY_THRESHOLD, SYMBOL_TOP_K } from '../config/tuning.js';
 import { createEmbeddingClient } from '../services/embeddingClient.js';
 import { SEARCHABLE_STATUS } from '../config/symbolStatus.js';
-const SIMILARITY_THRESHOLD = 0.5;
-const TOP_K = 20;
 const inMemorySymbols = [
     {
         id: 1,
@@ -82,21 +81,58 @@ function getMetaArray(meta, key) {
         return [];
     return value.filter((v) => typeof v === 'string');
 }
+function extractSearchTokens(query) {
+    const tokens = new Set();
+    const normalized = query.trim().toLowerCase();
+    for (const match of normalized.matchAll(/[a-z0-9_]+/g)) {
+        if (match[0].length >= 2)
+            tokens.add(match[0]);
+    }
+    for (const match of query.matchAll(/[\u4e00-\u9fff]{2,}/g)) {
+        const text = match[0];
+        for (let index = 0; index < text.length - 1; index += 1) {
+            tokens.add(text.slice(index, index + 2));
+        }
+    }
+    return [...tokens];
+}
+function buildSearchText(symbol) {
+    return [
+        symbol.name,
+        symbol.path,
+        symbol.description ?? '',
+        JSON.stringify(symbol.meta ?? {}),
+    ]
+        .join(' ')
+        .toLowerCase();
+}
+function countTokenMatches(text, tokens) {
+    return tokens.reduce((count, token) => text.includes(token.toLowerCase()) ? count + 1 : count, 0);
+}
 export class SymbolRepository {
     pool;
     constructor() {
         this.pool = getPool();
     }
     async search(query, type) {
+        console.error('[code-intelligence-mcp] repository.search.start query=%s type=%s table=%s searchableStatus=%s hasPool=%s', query, type ?? '', env.symbolsTable, String(SEARCHABLE_STATUS), String(Boolean(this.pool)));
         if (!this.pool) {
             const q = query.toLowerCase();
-            return inMemorySymbols.filter((s) => {
+            const tokens = extractSearchTokens(query);
+            const matched = inMemorySymbols.filter((s) => {
                 const typeOk = type ? s.type === type : true;
+                const text = buildSearchText(s);
                 return (typeOk &&
-                    (s.name.toLowerCase().includes(q) ||
-                        (s.description ?? '').toLowerCase().includes(q)));
+                    (text.includes(q) || countTokenMatches(text, tokens) >= 2));
             });
+            console.error('[code-intelligence-mcp] repository.search.memory count=%s top=%s', String(matched.length), JSON.stringify(matched.slice(0, 3).map((s) => ({
+                id: s.id,
+                name: s.name,
+                path: s.path,
+            }))));
+            return matched;
         }
+        const tokens = extractSearchTokens(query);
         const params = [
             `%${query}%`,
             SEARCHABLE_STATUS,
@@ -104,15 +140,46 @@ export class SymbolRepository {
         let sql = `
       SELECT id, name, type, category, path, description, content, meta::text AS meta, usage_count, created_at
       FROM ${env.symbolsTable}
-      WHERE (name ILIKE $1 OR description ILIKE $1)
+            WHERE (
+              name ILIKE $1 OR
+              description ILIKE $1 OR
+              path ILIKE $1 OR
+              meta::text ILIKE $1
+            )
         AND status = $2
     `;
+        if (tokens.length) {
+            const tokenClauses = tokens.map((token) => {
+                // 每个query token都要在name/description/path/meta中至少匹配一次才算匹配，来提升搜索的准确度，避免单个token过于泛匹配导致的排名干扰
+                params.push(`%${token}%`);
+                const index = params.length;
+                return `name ILIKE $${index} OR description ILIKE $${index} OR path ILIKE $${index} OR meta::text ILIKE $${index}`;
+            });
+            sql = `
+      SELECT id, name, type, category, path, description, content, meta::text AS meta, usage_count, created_at
+      FROM ${env.symbolsTable}
+            WHERE (
+              name ILIKE $1 OR
+              description ILIKE $1 OR
+              path ILIKE $1 OR
+              meta::text ILIKE $1 OR
+              (${tokenClauses.join(' OR ')})
+            )
+        AND status = $2
+    `;
+        }
         if (type) {
             params.push(type);
             sql += ` AND type = $${params.length}`;
         }
         sql += ' ORDER BY usage_count DESC LIMIT 20';
         const { rows } = await this.pool.query(sql, params);
+        console.error('[code-intelligence-mcp] repository.search.db table=%s rows=%s top=%s note=name/description only', env.symbolsTable, String(rows.length), JSON.stringify(rows.slice(0, 3).map((r) => ({
+            id: r.id,
+            name: r.name,
+            path: r.path,
+            type: r.type,
+        }))));
         return rows.map((r) => mapRow(r));
     }
     /**
@@ -120,13 +187,16 @@ export class SymbolRepository {
      * 不再需要在 Node 拉取全量向量做内存计算。
      */
     async searchSemanticHits(query, opts) {
+        console.error('[code-intelligence-mcp] repository.searchSemanticHits.start query=%s type=%s table=%s limit=%s threshold=%s searchableStatus=%s hasPool=%s', query, opts?.type ?? '', env.symbolsTable, String(opts?.limit ?? SYMBOL_TOP_K), String(SYMBOL_SIMILARITY_THRESHOLD), String(SEARCHABLE_STATUS), String(Boolean(this.pool)));
         if (!env.embeddingServiceUrl) {
+            console.error('[code-intelligence-mcp] repository.searchSemanticHits.error missingEmbeddingServiceUrl');
             throw new Error('语义检索需配置 EMBEDDING_SERVICE_URL 并启动嵌入服务');
         }
         if (!this.pool) {
+            console.error('[code-intelligence-mcp] repository.searchSemanticHits.noPool returnEmpty');
             return [];
         }
-        const limit = opts?.limit ?? TOP_K;
+        const limit = opts?.limit ?? SYMBOL_TOP_K;
         const client = createEmbeddingClient(env.embeddingServiceUrl);
         const [queryVec] = await client.embed([query.trim()]);
         if (!queryVec?.length) {
@@ -151,15 +221,26 @@ export class SymbolRepository {
         params.push(limit * 2); // 多取一倍以便 SIMILARITY_THRESHOLD 过滤后仍有足量结果
         sql += ` ORDER BY embedding <=> $1::vector LIMIT $${params.length}`;
         const { rows } = await this.pool.query(sql, params);
-        return rows
-            .map((r) => ({
+        const mapped = rows.map((r) => ({
             symbol: mapRow(r),
             similarity: Number(r.similarity),
+        }));
+        const passed = mapped.filter((x) => x.similarity >= SYMBOL_SIMILARITY_THRESHOLD);
+        console.error('[code-intelligence-mcp] repository.searchSemanticHits.db table=%s rawRows=%s passedThreshold=%s topRaw=%s', env.symbolsTable, String(rows.length), String(passed.length), JSON.stringify(mapped.slice(0, 5).map((x) => ({
+            id: x.symbol.id,
+            name: x.symbol.name,
+            path: x.symbol.path,
+            similarity: Number(x.similarity.toFixed(4)),
+        }))));
+        return passed
+            .map((r) => ({
+            symbol: r.symbol,
+            similarity: r.similarity,
         }))
-            .filter((x) => x.similarity >= SIMILARITY_THRESHOLD)
             .slice(0, limit);
     }
     async getByName(name) {
+        console.error('[code-intelligence-mcp] repository.getByName.start name=%s table=%s hasPool=%s', name, env.symbolsTable, String(Boolean(this.pool)));
         if (!this.pool) {
             return (inMemorySymbols.find((s) => s.name.toLowerCase() === name.toLowerCase()) ?? null);
         }
@@ -169,6 +250,7 @@ export class SymbolRepository {
       WHERE name = $1
       LIMIT 1
       `, [name]);
+        console.error('[code-intelligence-mcp] repository.getByName.db table=%s rows=%s', env.symbolsTable, String(rows.length));
         if (rows.length === 0) {
             return null;
         }
@@ -191,6 +273,7 @@ export class SymbolRepository {
         return result.rowCount !== null && result.rowCount > 0;
     }
     async searchByStructure(fields, opts) {
+        console.error('[code-intelligence-mcp] repository.searchByStructure.start fields=%s type=%s category=%s table=%s limit=%s hasPool=%s', JSON.stringify(fields), opts?.type ?? '', opts?.category ?? '', env.symbolsTable, String(opts?.limit ?? 20), String(Boolean(this.pool)));
         const normalized = fields.map((f) => f.trim()).filter(Boolean);
         if (normalized.length === 0)
             return [];
@@ -215,7 +298,13 @@ export class SymbolRepository {
             return normalized.every((field) => propPool.includes(field.toLowerCase()));
         };
         if (!this.pool) {
-            return inMemorySymbols.filter(matchesAll).slice(0, limit);
+            const matched = inMemorySymbols.filter(matchesAll).slice(0, limit);
+            console.error('[code-intelligence-mcp] repository.searchByStructure.memory matched=%s top=%s', String(matched.length), JSON.stringify(matched.slice(0, 3).map((s) => ({
+                id: s.id,
+                name: s.name,
+                path: s.path,
+            }))));
+            return matched;
         }
         const params = [];
         let sql = `
@@ -234,9 +323,13 @@ export class SymbolRepository {
         params.push(Math.max(limit * 5, 50));
         sql += ` ORDER BY usage_count DESC LIMIT $${params.length}`;
         const { rows } = await this.pool.query(sql, params);
-        return rows
-            .map((r) => mapRow(r))
-            .filter(matchesAll)
-            .slice(0, limit);
+        const mapped = rows.map((r) => mapRow(r));
+        const filtered = mapped.filter(matchesAll).slice(0, limit);
+        console.error('[code-intelligence-mcp] repository.searchByStructure.db table=%s scanned=%s matched=%s top=%s', env.symbolsTable, String(rows.length), String(filtered.length), JSON.stringify(filtered.slice(0, 3).map((s) => ({
+            id: s.id,
+            name: s.name,
+            path: s.path,
+        }))));
+        return filtered;
     }
 }

package/dist/server/createServer.js

@@ -8,25 +8,41 @@ import { createSearchByStructureTool } from '../tools/searchByStructure.js';
 import { createIncUsageTool } from '../tools/incUsage.js';
 import { RecommendationService } from '../services/recommendationService.js';
 import { createRecommendComponentTool } from '../tools/recommendComponent.js';
+import { createQueryDocsTool } from '../tools/queryDocs.js';
 export function createServer() {
+    console.error('[code-intelligence-mcp] createServer.init');
     const server = new McpServer({
         name: 'code-intelligence-mcp',
         version: '0.1.0',
     });
+    console.error('[code-intelligence-mcp] mcpServer.created name=code-intelligence-mcp version=0.1.0');
     const repository = new SymbolRepository();
+    console.error('[code-intelligence-mcp] repository.created');
     const recommendationService = new RecommendationService(repository);
+    console.error('[code-intelligence-mcp] recommendationService.created');
     const searchTool = createSearchSymbolsTool(repository);
     server.tool(searchTool.name, searchTool.description, searchTool.inputSchema, searchTool.handler);
+    console.error('[code-intelligence-mcp] tool.registered %s', searchTool.name);
     const detailTool = createGetSymbolDetailTool(repository);
     server.tool(detailTool.name, detailTool.description, detailTool.inputSchema, detailTool.handler);
+    console.error('[code-intelligence-mcp] tool.registered %s', detailTool.name);
     const structureTool = createSearchByStructureTool(repository);
     server.tool(structureTool.name, structureTool.description, structureTool.inputSchema, structureTool.handler);
+    console.error('[code-intelligence-mcp] tool.registered %s', structureTool.name);
     const reindexTool = createReindexTool();
     server.tool(reindexTool.name, reindexTool.description, reindexTool.inputSchema, reindexTool.handler);
+    console.error('[code-intelligence-mcp] tool.registered %s', reindexTool.name);
     const incUsageTool = createIncUsageTool(repository);
     server.tool(incUsageTool.name, incUsageTool.description, incUsageTool.inputSchema, incUsageTool.handler);
+    console.error('[code-intelligence-mcp] tool.registered %s', incUsageTool.name);
     const recommendComponentTool = createRecommendComponentTool(recommendationService);
     server.tool(recommendComponentTool.name, recommendComponentTool.description, recommendComponentTool.inputSchema, recommendComponentTool.handler);
+    console.error('[code-intelligence-mcp] tool.registered %s', recommendComponentTool.name);
     registerReusableCodeAdvisorPrompt(server);
+    console.error('[code-intelligence-mcp] prompt.registered reusable-code-advisor');
+    const queryDocsTool = createQueryDocsTool();
+    server.tool(queryDocsTool.name, queryDocsTool.description, queryDocsTool.inputSchema, queryDocsTool.handler);
+    console.error('[code-intelligence-mcp] tool.registered %s', queryDocsTool.name);
+    console.error('[code-intelligence-mcp] createServer.ready toolCount=7 promptCount=1');
     return server;
 }

package/dist/services/contextAssembler.js

@@ -0,0 +1,150 @@
+/**
+ * contextAssembler: RAG 上下文组装器。
+ *
+ * 完整流程：
+ *   topK hits
+ *     → 邻块扩展（getAdjacentChunks）：补全被截断的边界上下文
+ *     → 去重（path + chunk_index）：避免重复块被重复计费
+ *     → 相关性排序：命中块靠前，纯邻块靠后
+ *     → 字符预算截断：超出 CONTEXT_MAX_CHARS 时丢弃末尾块
+ *     → 文本渲染：拼成可直接注入 prompt 的 contextText
+ *
+ * 为什么需要邻块扩展？
+ *   chunk 切分时按结构和字符数截断，单个 chunk 可能只包含一段话的前半句。
+ *   取前后邻块（radius=1 即各一块）可以在不大幅增加 token 成本的前提下
+ *   把被截断的上下文还原，显著降低 LLM 产生"幻觉引用"的概率。
+ *
+ * 为什么要字符预算？
+ *   大多数 LLM 有 context window 限制。超出预算不仅导致截断错误，
+ *   还会因为过长的无关文本降低模型对真正相关段落的注意力权重（"lost in the middle"问题）。
+ *   控制预算 = 控制召回精度。
+ */
+import { CONTEXT_ADJACENT_RADIUS, CONTEXT_MAX_CHARS, CONTEXT_MAX_CHUNKS, } from '../config/tuning.js';
+/**
+ * 渲染单个 chunk 为可读文本块，附带来源元信息。
+ *
+ * 格式示例：
+ *   [来源: qa-doc/topK.md · 第2块/共5块 · 相似度 0.87]
+ *   topK 参数控制返回数量，默认值为...
+ */
+function renderChunk(chunk) {
+    const parts = [`来源: ${chunk.path}`];
+    parts.push(`第${chunk.chunkIndex + 1}块/共${chunk.chunkCount}块`);
+    if (chunk.similarity != null) {
+        parts.push(`相似度 ${chunk.similarity.toFixed(2)}`);
+    }
+    const header = `[${parts.join(' · ')}]`;
+    return `${header}\n${chunk.content}`;
+}
+export class ContextAssembler {
+    repo;
+    constructor(repo) {
+        this.repo = repo;
+    }
+    /**
+     * 组装 RAG 上下文。
+     *
+     * @param hits         来自 ChunkRepository.searchSemantic() 的 topK 结果（已按相似度降序）
+     * @param opts.maxChars         覆盖 CONTEXT_MAX_CHARS，用于运行时动态调整 token 预算
+     * @param opts.adjacentRadius   覆盖 CONTEXT_ADJACENT_RADIUS，0 表示不做邻块扩展
+     * @param opts.maxChunks        覆盖 CONTEXT_MAX_CHUNKS
+     */
+    async assemble(hits, opts) {
+        const maxChars = opts?.maxChars ?? CONTEXT_MAX_CHARS;
+        const radius = opts?.adjacentRadius ?? CONTEXT_ADJACENT_RADIUS;
+        const maxChunks = opts?.maxChunks ?? CONTEXT_MAX_CHUNKS;
+        const hitCount = hits.length;
+        // ── 步骤1：邻块扩展 ──────────────────────────────────────────────────
+        // 对每个命中块并行拉取前后邻块，补全被切分边界截断的上下文。
+        // 邻块本身没有 similarity 分数，排序时置于命中块之后。
+        const expanded = await this.expandWithAdjacentChunks(hits, radius);
+        // ── 步骤2：去重 ───────────────────────────────────────────────────────
+        // 多个命中块扩展后可能重叠，以 path+chunk_index 为键去重，保留先出现的版本
+        // （命中块在前，保留其 similarity；邻块在后，若与命中块重叠则丢弃邻块副本）。
+        const deduped = deduplicateChunks(expanded);
+        // ── 步骤3：排序 ───────────────────────────────────────────────────────
+        // similarity 有值（命中块）> similarity 无值（纯邻块）；同类内部按相似度降序。
+        const sorted = sortChunks(deduped);
+        // ── 步骤4：字符预算截断 ───────────────────────────────────────────────
+        const { selected, truncated } = applyBudget(sorted, maxChars, maxChunks);
+        // ── 步骤5：文本渲染 ───────────────────────────────────────────────────
+        const contextText = selected.map(renderChunk).join('\n\n---\n\n');
+        return {
+            chunks: selected,
+            contextText,
+            hitCount,
+            totalChunks: selected.length,
+            truncated,
+        };
+    }
+    /**
+     * 对每个命中块并行拉取邻块，返回命中块 + 所有邻块的扁平列表（含重复，由后续去重处理）。
+     * radius=0 时跳过数据库查询，直接返回原始命中列表。
+     */
+    async expandWithAdjacentChunks(hits, radius) {
+        if (radius <= 0 || hits.length === 0)
+            return [...hits];
+        // 并行拉取，避免串行 N 次查询放大延迟。
+        const adjacentGroups = await Promise.all(hits.map((hit) => this.repo.getAdjacentChunks(hit.path, hit.chunkIndex, radius)));
+        // 命中块在前，邻块紧随其后（之后去重时命中块的 similarity 会被保留）。
+        const result = [...hits];
+        for (const group of adjacentGroups) {
+            result.push(...group);
+        }
+        return result;
+    }
+}
+/** 以 `${path}::${chunkIndex}` 为键去重，保留先出现的副本（命中块的 similarity 优先）。 */
+function deduplicateChunks(chunks) {
+    const seen = new Set();
+    const result = [];
+    for (const chunk of chunks) {
+        const key = `${chunk.path}::${chunk.chunkIndex}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push(chunk);
+        }
+    }
+    return result;
+}
+/**
+ * 排序规则：
+ * 1. 有 similarity（命中块）排在无 similarity（纯邻块）之前
+ * 2. 同类内部按 similarity 降序
+ * 3. 纯邻块内部保持原有顺序（path + chunkIndex 升序，保证上下文连贯）
+ */
+function sortChunks(chunks) {
+    return [...chunks].sort((a, b) => {
+        const aHasSim = a.similarity != null;
+        const bHasSim = b.similarity != null;
+        if (aHasSim && !bHasSim)
+            return -1;
+        if (!aHasSim && bHasSim)
+            return 1;
+        if (aHasSim && bHasSim)
+            return (b.similarity ?? 0) - (a.similarity ?? 0);
+        // 纯邻块按路径+索引保持文档顺序
+        const pathCmp = a.path.localeCompare(b.path);
+        return pathCmp !== 0 ? pathCmp : a.chunkIndex - b.chunkIndex;
+    });
+}
+/**
+ * 从排好序的 chunk 列表中按字符预算和数量上限截取子集。
+ * 按顺序累加字符数，第一个超出预算的 chunk 及之后的全部丢弃。
+ */
+function applyBudget(chunks, maxChars, maxChunks) {
+    const selected = [];
+    let totalChars = 0;
+    for (const chunk of chunks) {
+        if (selected.length >= maxChunks) {
+            return { selected, truncated: true };
+        }
+        const chunkChars = renderChunk(chunk).length;
+        if (totalChars + chunkChars > maxChars && selected.length > 0) {
+            return { selected, truncated: true };
+        }
+        selected.push(chunk);
+        totalChars += chunkChars;
+    }
+    return { selected, truncated: false };
+}

package/dist/services/ranking.js

@@ -1,3 +1,4 @@
+import { CALLEE_MATCH_SCORE_MAX, CALLEE_MATCH_SCORE_PER_MATCH, COMMON_PATH_SCORE_NO, COMMON_PATH_SCORE_YES, RANK_WEIGHTS, RECENCY_SCORE_DEFAULT, RECENCY_SCORE_OLDEST, RECENCY_SCORE_TIERS, SEMANTIC_REASON_THRESHOLD_HIGH, SEMANTIC_REASON_THRESHOLD_MED, TEXT_MATCH_SCORES, TOKEN_OVERLAP_TIERS, USAGE_REASON_THRESHOLD_HIGH, USAGE_SCORE_LOG_DIVISOR, } from '../config/tuning.js';
 function clamp01(value) {
     if (value < 0)
         return 0;
@@ -5,40 +6,78 @@ function clamp01(value) {
         return 1;
     return value;
 }
+function extractTextTokens(text) {
+    // eg: query='useDebounceInput组件', tokens=['useDebounceInput', '组件']
+    const tokens = new Set();
+    const lower = text.trim().toLowerCase();
+    for (const match of lower.matchAll(/[a-z0-9_]+/g)) {
+        if (match[0].length >= 2)
+            tokens.add(match[0]);
+    }
+    for (const match of text.matchAll(/[\u4e00-\u9fff]{2,}/g)) {
+        const chunk = match[0];
+        for (let index = 0; index < chunk.length - 1; index += 1) {
+            tokens.add(chunk.slice(index, index + 2));
+        }
+    }
+    return [...tokens];
+}
+// 先对query进行切分，然后计算切分后的token在symbol的name/description/path中出现的数量和比例，来判断是否存在关键词重合，进而提升排名。
+function tokenOverlapScore(query, symbol) {
+    const queryTokens = extractTextTokens(query);
+    if (queryTokens.length === 0)
+        return 0;
+    const text = [symbol.name, symbol.description ?? '', symbol.path]
+        .join(' ')
+        .toLowerCase();
+    const matched = queryTokens.filter((token) => text.includes(token)).length;
+    const overlapRatio = matched / queryTokens.length;
+    for (const tier of TOKEN_OVERLAP_TIERS) {
+        if (matched >= tier.minMatches && overlapRatio >= tier.minRatio) {
+            return tier.score;
+        }
+    }
+    return 0;
+}
 function textMatchScore(query, symbol) {
     const q = query.trim().toLowerCase();
     if (!q)
-        return { score: 0, matchedBy: "weak" };
+        return { score: 0, matchedBy: 'weak' };
     const name = symbol.name.toLowerCase();
-    const description = (symbol.description ?? "").toLowerCase();
+    const description = (symbol.description ?? '').toLowerCase();
     if (name === q)
-        return { score: 1, matchedBy: "exact_name" };
+        return { score: 1, matchedBy: 'exact_name' };
     if (name.includes(q))
-        return { score: 0.85, matchedBy: "name_contains" };
+        return {
+            score: TEXT_MATCH_SCORES.nameContains,
+            matchedBy: 'name_contains',
+        };
     if (description.includes(q))
-        return { score: 0.65, matchedBy: "description_contains" };
-    return { score: 0.2, matchedBy: "weak" };
+        return {
+            score: TEXT_MATCH_SCORES.descriptionContains,
+            matchedBy: 'description_contains',
+        };
+    const overlapScore = tokenOverlapScore(query, symbol);
+    if (overlapScore > 0)
+        return { score: overlapScore, matchedBy: 'token_overlap' };
+    return { score: TEXT_MATCH_SCORES.weak, matchedBy: 'weak' };
 }
 function usageScore(usageCount) {
     // log scale to avoid very large usage monopolizing ranking.
-    return clamp01(Math.log10(usageCount + 1) / 3);
+    return clamp01(Math.log10(usageCount + 1) / USAGE_SCORE_LOG_DIVISOR);
 }
 function recencyScore(createdAt) {
     if (!createdAt)
-        return 0.4;
+        return RECENCY_SCORE_DEFAULT;
     const ts = new Date(createdAt).getTime();
     if (Number.isNaN(ts))
-        return 0.4;
+        return RECENCY_SCORE_DEFAULT;
     const days = (Date.now() - ts) / (1000 * 60 * 60 * 24);
-    if (days <= 7)
-        return 1;
-    if (days <= 30)
-        return 0.8;
-    if (days <= 90)
-        return 0.6;
-    if (days <= 180)
-        return 0.4;
-    return 0.25;
+    for (const tier of RECENCY_SCORE_TIERS) {
+        if (days <= tier.maxDays)
+            return tier.score;
+    }
+    return RECENCY_SCORE_OLDEST;
 }
 function daysSinceCreated(createdAt) {
     if (!createdAt)
@@ -50,62 +89,72 @@ function daysSinceCreated(createdAt) {
 }
 function commonPathScore(path) {
     const lower = path.toLowerCase();
-    return lower.includes("/common/") || lower.includes("/shared/") ? 1 : 0.35;
+    return lower.includes('/common/') || lower.includes('/shared/')
+        ? COMMON_PATH_SCORE_YES
+        : COMMON_PATH_SCORE_NO;
 }
-const RANK_WEIGHTS = {
-    textMatch: 0.5,
-    usage: 0.3,
-    recency: 0.1,
-    commonPath: 0.1
-};
 /**
- * Phase 5：以向量余弦相似度作为主文本维度，再叠加 usage / recency / common（与 `rankSymbols` 同权重）。
+ * Phase 5：以向量余弦相似度作为主文本维度，再叠加 usage / recency / common 和 calleeNames 匹配度。
+ * calleeNames 作为结构信息独立信号，不污染纯语义向量。
  */
-export function rankSemanticHits(hits) {
+export function rankSemanticHits(hits, query) {
     return hits
         .map(({ symbol, similarity }) => {
         const textScore = clamp01(similarity);
         const usage = usageScore(symbol.usageCount);
         const recency = recencyScore(symbol.createdAt);
         const common = commonPathScore(symbol.path);
+        // ✨ 新增：calleeNames 作为独立信号
+        let calleeMatchScore = 0;
+        if (query && Array.isArray(symbol.meta?.calleeNames)) {
+            const calleeNames = symbol.meta.calleeNames;
+            const queryLower = query.toLowerCase();
+            const matchedCallees = calleeNames.filter((callee) => queryLower.includes(callee.toLowerCase())).length;
+            if (matchedCallees > 0) {
+                calleeMatchScore = Math.min(matchedCallees * CALLEE_MATCH_SCORE_PER_MATCH, CALLEE_MATCH_SCORE_MAX);
+            }
+        }
         const score = textScore * RANK_WEIGHTS.textMatch +
             usage * RANK_WEIGHTS.usage +
             recency * RANK_WEIGHTS.recency +
-            common * RANK_WEIGHTS.commonPath;
+            common * RANK_WEIGHTS.commonPath +
+            calleeMatchScore;
         const reasonParts = [];
-        if (textScore >= 0.55)
-            reasonParts.push("语义相似度高");
-        else if (textScore >= 0.4)
-            reasonParts.push("语义相关");
-        if (usage >= 0.6)
-            reasonParts.push("使用频率高");
-        if (common >= 1)
-            reasonParts.push("位于 shared/common 路径");
+        if (textScore >= SEMANTIC_REASON_THRESHOLD_HIGH)
+            reasonParts.push('语义相似度高');
+        else if (textScore >= SEMANTIC_REASON_THRESHOLD_MED)
+            reasonParts.push('语义相关');
+        if (usage >= USAGE_REASON_THRESHOLD_HIGH)
+            reasonParts.push('使用频率高');
+        if (common >= COMMON_PATH_SCORE_YES)
+            reasonParts.push('位于 shared/common 路径');
+        if (calleeMatchScore > 0)
+            reasonParts.push('函数调用关系匹配');
         if (reasonParts.length === 0)
-            reasonParts.push("综合相关性较好");
+            reasonParts.push('综合相关性较好');
         return {
             symbol,
             score: Number(score.toFixed(3)),
             reason: {
                 textMatch: {
                     score: Number(textScore.toFixed(3)),
-                    matchedBy: "semantic"
+                    matchedBy: 'semantic',
                 },
                 usage: {
                     score: Number(usage.toFixed(3)),
-                    usageCount: symbol.usageCount
+                    usageCount: symbol.usageCount,
                 },
                 recency: {
                     score: Number(recency.toFixed(3)),
-                    daysSinceCreated: daysSinceCreated(symbol.createdAt)
+                    daysSinceCreated: daysSinceCreated(symbol.createdAt),
                 },
                 commonPath: {
                     score: Number(common.toFixed(3)),
-                    isCommonPath: common >= 1
+                    isCommonPath: common >= COMMON_PATH_SCORE_YES,
                 },
                 weights: RANK_WEIGHTS,
-                summary: reasonParts.join(" + ")
-            }
+                summary: reasonParts.join(' + '),
+            },
         };
     })
         .sort((a, b) => b.score - a.score);
@@ -122,39 +171,41 @@ export function rankSymbols(query, symbols) {
             recency * RANK_WEIGHTS.recency +
             common * RANK_WEIGHTS.commonPath;
         const reasonParts = [];
-        if (text.score >= 0.85)
-            reasonParts.push("文本匹配度高");
-        else if (text.score >= 0.65)
-            reasonParts.push("描述命中");
-        if (usage >= 0.6)
-            reasonParts.push("使用频率高");
-        if (common >= 1)
-            reasonParts.push("位于 shared/common 路径");
+        if (text.score >= TEXT_MATCH_SCORES.nameContains)
+            reasonParts.push('文本匹配度高');
+        else if (text.score >= TEXT_MATCH_SCORES.descriptionContains)
+            reasonParts.push('描述命中');
+        else if (text.matchedBy === 'token_overlap')
+            reasonParts.push('关键词片段高度重合');
+        if (usage >= USAGE_REASON_THRESHOLD_HIGH)
+            reasonParts.push('使用频率高');
+        if (common >= COMMON_PATH_SCORE_YES)
+            reasonParts.push('位于 shared/common 路径');
         if (reasonParts.length === 0)
-            reasonParts.push("综合相关性较好");
+            reasonParts.push('综合相关性较好');
         return {
             symbol,
             score: Number(score.toFixed(3)),
             reason: {
                 textMatch: {
                     score: Number(text.score.toFixed(3)),
-                    matchedBy: text.matchedBy
+                    matchedBy: text.matchedBy,
                 },
                 usage: {
                     score: Number(usage.toFixed(3)),
-                    usageCount: symbol.usageCount
+                    usageCount: symbol.usageCount,
                 },
                 recency: {
                     score: Number(recency.toFixed(3)),
-                    daysSinceCreated: daysSinceCreated(symbol.createdAt)
+                    daysSinceCreated: daysSinceCreated(symbol.createdAt),
                 },
                 commonPath: {
                     score: Number(common.toFixed(3)),
-                    isCommonPath: common >= 1
+                    isCommonPath: common >= COMMON_PATH_SCORE_YES,
                 },
                 weights: RANK_WEIGHTS,
-                summary: reasonParts.join(" + ")
-            }
+                summary: reasonParts.join(' + '),
+            },
         };
     })
         .sort((a, b) => b.score - a.score);