@lorrylurui/code-intelligence-mcp 2.0.8 → 2.1.0

package/README.md

@@ -45,3 +45,24 @@
 
 MYSQL\*SYMBOLS_TABLE=frontend_collections_symbols
 INDEX_GLOB=xxx/\*\*/\_.{js,jsx,ts,tsx}
+
+## 4) 离线测评
+
+```javascript
+npx tsx src/cli/eval-recommendation-cli.ts
+# 或指定 limit
+npx tsx src/cli/eval-recommendation-cli.ts --limit 10
+
+npm run eval
+```
+
+## 5）分析离线测评结果
+
+```javascript
+npm run analyze                                          # 自动读最新结果文件
+npm run analyze -- offline_eval/results/2026-05-27.jsonl  # 指定文件
+npm run analyze -- --baseline offline_eval/results/2026-05-26.jsonl  # 与 baseline 对比 delta
+
+```
+
+或者直接引用eval-analysis.prompt.md 对最新结果分析

package/dist/cli/eval-analyze-cli.js

@@ -0,0 +1,314 @@
+/**
+ * eval-analyze-cli.ts — 离线评测结果分析工具
+ *
+ * 用法：
+ *   npm run analyze                             # 自动读取 offline_eval/results/ 最新文件
+ *   npm run analyze -- offline_eval/results/2026-05-27.jsonl
+ *   npm run analyze -- --dir offline_eval/results --baseline offline_eval/results/2026-05-26.jsonl
+ *
+ * 输出：
+ *   - 关键指标汇总（含与 baseline 对比 delta）
+ *   - 按语言/符号类型分组 Recall@10
+ *   - 失败归因分布
+ *   - 主要发现（自动检测中英文差距、类型推断问题、误触等）
+ *   - 建议优先级列表
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as readline from 'node:readline';
+// ─── CLI 参数 ────────────────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+function getArg(flag, fallback) {
+    const idx = args.indexOf(flag);
+    return idx !== -1 && args[idx + 1] ? args[idx + 1] : fallback;
+}
+const RESULTS_DIR = getArg('--dir', 'offline_eval/results');
+const BASELINE_PATH = getArg('--baseline', '');
+// ─── 分析阈值（可按实际结果微调） ────────────────────────────────────────────
+const THRESHOLDS = {
+    /** 中英文 Recall@10 差距超过此值时触发"中文召回偏弱"发现 */
+    ZH_EN_RECALL_GAP: 0.1,
+    /** 函数类 Recall@10 低于此值时触发"函数类型推断"发现 */
+    FUNC_RECALL_LOW: 0.5,
+    /** no_semantic_recall 占比超过此值时触发"归因主导"发现 */
+    NO_SEMANTIC_DOMINANCE: 0.5,
+    /** no_semantic_recall 占比超过此值时输出归因修正建议 */
+    NO_SEMANTIC_REC_TRIGGER: 0.3,
+    /** quality_gate_rejected 条数超过此值时输出质量门控建议 */
+    QG_COUNT_MIN: 2,
+    /** ranked_below_topk 条数超过此值时输出排名调整建议 */
+    RANKED_COUNT_MIN: 1,
+    /** 终端横向进度条宽度（字符数） */
+    BAR_WIDTH: 20,
+    /** 中文零召回示例最多展示条数 */
+    ZH_ZERO_EXAMPLE_LIMIT: 4,
+    /** 误触示例最多展示条数 */
+    FP_EXAMPLE_LIMIT: 3,
+};
+function findLatestResultsFile() {
+    // 支持直接传路径（不带 flag）
+    const explicit = args.find((a) => a.endsWith('.jsonl') && !a.startsWith('--'));
+    if (explicit)
+        return explicit;
+    if (!fs.existsSync(RESULTS_DIR)) {
+        throw new Error(`Results directory not found: ${RESULTS_DIR}`);
+    }
+    const files = fs
+        .readdirSync(RESULTS_DIR)
+        .filter((f) => f.endsWith('.jsonl'))
+        .sort()
+        .reverse();
+    if (files.length === 0) {
+        throw new Error(`No .jsonl result files found in ${RESULTS_DIR}`);
+    }
+    return path.join(RESULTS_DIR, files[0]);
+}
+// ─── 文件加载 ─────────────────────────────────────────────────────────────────
+async function loadResults(filePath) {
+    const results = [];
+    const rl = readline.createInterface({
+        input: fs.createReadStream(filePath),
+        crlfDelay: Infinity,
+    });
+    for await (const line of rl) {
+        const trimmed = line.trim();
+        if (trimmed)
+            results.push(JSON.parse(trimmed));
+    }
+    return results;
+}
+// ─── 工具函数 ─────────────────────────────────────────────────────────────────
+/**
+ * 计算平均值，空数组时返回 0。
+ */
+function avg(nums) {
+    if (nums.length === 0)
+        return 0;
+    return nums.reduce((s, n) => s + n, 0) / nums.length;
+}
+function pct(n) {
+    return (n * 100).toFixed(1) + '%';
+}
+function delta(curr, base) {
+    if (base === undefined)
+        return '';
+    const d = curr - base;
+    const sign = d >= 0 ? '+' : '';
+    return ` (${sign}${pct(d)})`;
+}
+function recallByTag(results, tag) {
+    const tagged = results.filter((r) => !r.isNegativeSample && r.tags.includes(tag));
+    return {
+        recall: avg(tagged.map((r) => r.recallMain ?? 0)),
+        count: tagged.length,
+    };
+}
+/**
+ * 计算各项指标的平均值，返回一个汇总对象。
+ */
+function computeMetrics(positive, negative) {
+    return {
+        recallMain: avg(positive.map((r) => r.recallMain ?? 0)),
+        recall50: avg(positive.map((r) => r.recall50 ?? 0)),
+        firstHitScore: avg(positive.map((r) => r.firstHitScore ?? 0)),
+        rankingQuality: avg(positive.map((r) => r.rankingQuality ?? 0)),
+        coverage: positive.filter((r) => (r.recallMain ?? 0) > 0).length /
+            (positive.length || 1),
+        top1Acc: positive.filter((r) => r.top1Correct === true).length /
+            (positive.length || 1),
+        fpRate: negative.filter((r) => r.falsePositive).length /
+            (negative.length || 1),
+    };
+}
+// ─── 主分析逻辑 ───────────────────────────────────────────────────────────────
+async function analyze() {
+    const filePath = findLatestResultsFile();
+    const fileName = path.basename(filePath);
+    const results = await loadResults(filePath);
+    const positive = results.filter((r) => !r.isNegativeSample);
+    const negative = results.filter((r) => r.isNegativeSample);
+    const metrics = computeMetrics(positive, negative);
+    // 如果不传 --baseline，baseMetrics 就是 undefined，delta() 函数返回空字符串，指标后面不显示涨跌。
+    let baseMetrics;
+    if (BASELINE_PATH && fs.existsSync(BASELINE_PATH)) {
+        const baseResults = await loadResults(BASELINE_PATH);
+        const basePos = baseResults.filter((r) => !r.isNegativeSample);
+        const baseNeg = baseResults.filter((r) => r.isNegativeSample);
+        baseMetrics = computeMetrics(basePos, baseNeg);
+    }
+    // 失败归因统计
+    const allFailures = positive.flatMap((r) => r.failures);
+    const failureCounts = {};
+    for (const f of allFailures) {
+        failureCounts[f.type] = (failureCounts[f.type] ?? 0) + 1;
+    }
+    const totalFailures = allFailures.length;
+    // 分组 Recall（按语言 + 类型标签）
+    const tagGroups = [
+        'en',
+        'zh',
+        'zh-en',
+        'component',
+        'hook',
+        'function',
+        'util',
+        'form',
+    ];
+    const tagRecalls = new Map();
+    for (const tag of tagGroups) {
+        const stat = recallByTag(positive, tag);
+        if (stat.count > 0)
+            tagRecalls.set(tag, stat);
+    }
+    // 零召回 query
+    const zeroRecall = positive.filter((r) => r.recallMain === 0);
+    // 误触（false positive）示例
+    const fpExamples = negative.filter((r) => r.falsePositive);
+    // ─── 输出报告 ──────────────────────────────────────────────────────────────
+    const sep = '='.repeat(60);
+    const sub = '─'.repeat(60);
+    console.log('\n' + sep);
+    console.log(`数据来源：${fileName}`);
+    console.log(sep);
+    // ── 关键指标 ──
+    console.log('\n关键指标\n');
+    console.log(`  召回率(Recall@10):             ${pct(metrics.recallMain).padStart(7)}${delta(metrics.recallMain, baseMetrics?.recallMain)}`);
+    console.log(`  首位命中分(MRR@10):             ${pct(metrics.firstHitScore).padStart(7)}${delta(metrics.firstHitScore, baseMetrics?.firstHitScore)}`);
+    console.log(`  首条准确率(Top-1):              ${pct(metrics.top1Acc).padStart(7)}${delta(metrics.top1Acc, baseMetrics?.top1Acc)}`);
+    console.log(`  误触率(FP):                    ${pct(metrics.fpRate).padStart(7)}${delta(metrics.fpRate, baseMetrics?.fpRate)}`);
+    console.log(`\n  总 query 数：${results.length}（正例 ${positive.length}，负例 ${negative.length}）`);
+    // ── 分组 Recall ──
+    console.log('\n' + sub);
+    console.log('按语言/符号类型 Recall@10\n');
+    for (const [tag, stat] of tagRecalls) {
+        const bar = '█'
+            .repeat(Math.round(stat.recall * THRESHOLDS.BAR_WIDTH))
+            .padEnd(THRESHOLDS.BAR_WIDTH);
+        console.log(`  ${tag.padEnd(12)} ${bar} ${pct(stat.recall).padStart(7)}  (${stat.count} queries)`);
+    }
+    // ── 失败归因 ──
+    console.log('\n' + sub);
+    console.log('失败归因分布\n');
+    const failureActionHints = {
+        no_semantic_recall: '→ 扩展 queryVariants / 中文同义词映射 / 调大 SYMBOL_TOP_K',
+        quality_gate_rejected: '→ 按 type 降低质量门控阈值',
+        ranked_below_topk: '→ 调整 RANK_WEIGHTS / LITERAL_MATCH_PRIORITY_BOOST',
+        reusability_filtered: '→ 检查 isReusableCandidate 路径规则',
+        structure_filtered: '→ 检查 category 过滤条件',
+    };
+    const sortedFailures = Object.entries(failureCounts).sort((a, b) => b[1] - a[1]);
+    for (const [type, count] of sortedFailures) {
+        const p = totalFailures > 0
+            ? ((count / totalFailures) * 100).toFixed(1)
+            : '0.0';
+        const hint = failureActionHints[type] ?? '';
+        console.log(`  ${type.padEnd(28)} ${String(count).padStart(3)} (${p}%)  ${hint}`);
+    }
+    // ── 主要发现 ──
+    console.log('\n' + sub);
+    console.log('主要发现\n');
+    const findings = [];
+    // 发现1：中英文召回差距
+    const zhStat = tagRecalls.get('zh');
+    const enStat = tagRecalls.get('en');
+    if (zhStat &&
+        enStat &&
+        enStat.recall - zhStat.recall > THRESHOLDS.ZH_EN_RECALL_GAP) {
+        const zhZero = positive
+            .filter((r) => r.tags.includes('zh') && r.recallMain === 0)
+            .map((r) => `"${r.query}"`)
+            .slice(0, THRESHOLDS.ZH_ZERO_EXAMPLE_LIMIT);
+        findings.push(`中文 query 召回明显弱于英文\n` +
+            `   中文 Recall@10 = ${pct(zhStat.recall)}，英文 = ${pct(enStat.recall)}，差距 ${pct(enStat.recall - zhStat.recall)}\n` +
+            `   零召回中文 query 示例：${zhZero.join('、')}`);
+    }
+    // 发现2：函数类类型推断
+    const funcStat = tagRecalls.get('function');
+    if (funcStat && funcStat.recall < THRESHOLDS.FUNC_RECALL_LOW) {
+        findings.push(`函数类 query 召回偏低（Recall@10 = ${pct(funcStat.recall)}）\n` +
+            `   可能原因：类型推断关键词缺少 function/formatter/validate，导致回退到 component 候选池`);
+    }
+    // 发现3：no_semantic_recall 主导
+    const noSemanticCount = failureCounts['no_semantic_recall'] ?? 0;
+    if (noSemanticCount / (totalFailures || 1) >
+        THRESHOLDS.NO_SEMANTIC_DOMINANCE) {
+        findings.push(`失败以 no_semantic_recall 为主（${noSemanticCount}/${totalFailures} 条，${((noSemanticCount / (totalFailures || 1)) * 100).toFixed(0)}%）\n` +
+            `   注意：该分类会掩盖 quality_gate_rejected 等更具体原因（当 DB 中无对应 id 时降级记录）`);
+    }
+    // 发现4：误触
+    if (fpExamples.length > 0) {
+        findings.push(`负例误触 ${fpExamples.length} 条（False Positive = ${pct(metrics.fpRate)}）\n` +
+            `   示例：${fpExamples
+                .slice(0, THRESHOLDS.FP_EXAMPLE_LIMIT)
+                .map((r) => `"${r.query}"`)
+                .join('、')}`);
+    }
+    // 发现5：零召回 query 总数
+    if (zeroRecall.length > 0) {
+        const byTag = (tag) => zeroRecall.filter((r) => r.tags.includes(tag)).length;
+        findings.push(`${zeroRecall.length} 条正例 Recall@10 = 0\n` +
+            `   其中 zh:${byTag('zh')}，en:${byTag('en')}，component:${byTag('component')}，hook:${byTag('hook')}，function:${byTag('function')}`);
+    }
+    findings.forEach((f, i) => console.log(`${i + 1}. ${f}\n`));
+    // ── 建议优先级 ──
+    console.log(sub);
+    console.log('建议优先级（按预期收益排序）\n');
+    const recs = [];
+    if (zhStat &&
+        enStat &&
+        enStat.recall - zhStat.recall > THRESHOLDS.ZH_EN_RECALL_GAP) {
+        recs.push({
+            priority: '高',
+            action: '强化中文同义词扩展（导航栏→navigation bar、日期格式化→format date 等）',
+            reason: `中英召回差距 ${pct(enStat.recall - zhStat.recall)}，影响 ${zhStat.count} 条 query`,
+        });
+    }
+    if (funcStat && funcStat.recall < THRESHOLDS.FUNC_RECALL_LOW) {
+        recs.push({
+            priority: '高',
+            action: '补类型推断关键词（category: function、query: formatter/validate/format）',
+            reason: `函数类 Recall@10 = ${pct(funcStat.recall)}，类型误判导致错误候选池`,
+        });
+    }
+    if (noSemanticCount / (totalFailures || 1) >
+        THRESHOLDS.NO_SEMANTIC_REC_TRIGGER) {
+        recs.push({
+            priority: '中高',
+            action: '修正 eval 失败归因逻辑（name+path 查 DB id，避免 no_semantic_recall 兜底掩盖）',
+            reason: `${noSemanticCount} 条记为 no_semantic_recall，诊断精度不足`,
+        });
+    }
+    const qgCount = failureCounts['quality_gate_rejected'] ?? 0;
+    if (qgCount > THRESHOLDS.QG_COUNT_MIN) {
+        recs.push({
+            priority: '中高',
+            action: '按 symbol type 分阈值降低质量门控（函数/Hook 可比组件更宽松）',
+            reason: `${qgCount} 条被 quality gate 拦截`,
+        });
+    }
+    const rankedCount = failureCounts['ranked_below_topk'] ?? 0;
+    if (rankedCount > THRESHOLDS.RANKED_COUNT_MIN) {
+        recs.push({
+            priority: '中',
+            action: '加强 index-priority tie-break（同目录 index/menu/panel 命中时强制 index 优先）',
+            reason: `${rankedCount} 条有正确候选但排名未进 Top-K`,
+        });
+    }
+    if (recs.length === 0) {
+        recs.push({
+            priority: '中',
+            action: '持续扩充 query_set.jsonl 覆盖更多边界场景',
+            reason: '当前指标已较好，可增加测试覆盖度',
+        });
+    }
+    recs.forEach((r, i) => {
+        console.log(`${i + 1}. [${r.priority}] ${r.action}`);
+        console.log(`   原因：${r.reason}`);
+        console.log();
+    });
+    console.log(sep + '\n');
+}
+analyze().catch((e) => {
+    console.error(e instanceof Error ? e.message : e);
+    process.exit(1);
+});

package/dist/cli/eval-recommendation-cli.js

@@ -0,0 +1,297 @@
+/**
+ * eval-recommendation-cli.ts — 推荐质量离线评测 CLI
+ *
+ * 用法：
+ *   npx tsx src/cli/eval-recommendation-cli.ts [--query-set offline_eval/query_set.jsonl] [--limit 10] [--output offline_eval/results/]
+ *
+ * 输出：
+ *   - stdout: 评测摘要（Recall@10 / Recall@50 / MRR@10 / nDCG@10）
+ *   - results/<date>.jsonl: 每条 query 的详细结果 + 失败分类
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as readline from 'node:readline';
+import { RecommendationService } from '../services/recommendationService.js';
+import { SymbolRepository } from '../repositories/symbolRepository.js';
+import { classifySymbolFailure } from '../types/evalTrace.js';
+// ─── CLI 参数 ────────────────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+function getArg(flag, fallback) {
+    const idx = args.indexOf(flag);
+    return idx !== -1 && args[idx + 1] ? args[idx + 1] : fallback;
+}
+const QUERY_SET_PATH = getArg('--query-set', 'offline_eval/query_set.jsonl');
+const OUTPUT_DIR = getArg('--output', 'offline_eval/results');
+const TOP_K_MAIN = Number(getArg('--limit', '10')); // Recall@K_MAIN / MRR@K / nDCG@K
+const RECALL_WIDE_K = 50; // 宽口径召回深度（用于 Recall@50），不是测试集数量
+const REL_RELEVANT_MIN = 1; // rel >= 1 计入相关结果
+const REL_PRIMARY = 2; // rel = 2 表示主答案/最高相关度
+// ─── 指标计算 ─────────────────────────────────────────────────────────────────
+/**
+ * 覆盖率 Recall@K：前 K 条结果中命中的相关条目占全部相关条目的比例。
+ * 衡量「应该找到的有多少被找到了」，与排名顺序无关。
+ * 负例（expected 全为 rel=0）视为完全命中，返回 1。
+ */
+function recallAtK(returnedNames, expected, k) {
+    const relevant = expected.filter((e) => e.rel >= REL_RELEVANT_MIN);
+    if (relevant.length === 0)
+        return 1;
+    const topK = returnedNames.slice(0, k);
+    const hits = relevant.filter((e) => topK.includes(e.name));
+    // 召回率@k = 真实召回的 / 所有相关的
+    return hits.length / relevant.length;
+}
+/**
+ * 倒数排名均值 MRR@K（Mean Reciprocal Rank）：第一个相关结果出现在第 r 位时得分为 1/r。
+ * 衡量「最佳结果排多靠前」；未命中则返回 0。
+ */
+function mrrAtK(returnedNames, expected, k) {
+    const relevantNames = new Set(expected.filter((e) => e.rel >= REL_RELEVANT_MIN).map((e) => e.name));
+    const topK = returnedNames.slice(0, k);
+    for (let i = 0; i < topK.length; i++) {
+        // 有一个命中的 就返回对应的 MRR 分数，越靠前分数越高；如果都没命中，最后返回 0。
+        if (relevantNames.has(topK[i]))
+            return 1 / (i + 1);
+    }
+    return 0;
+}
+/**
+ * 归一化折损累积增益 nDCG@K（Normalized Discounted Cumulative Gain）：综合考虑相关度分级（rel 0/1/2）
+ * 与排名位置的加权得分，再除以理想排序下的最大得分做归一化。
+ * 越靠前、相关度越高的结果得分越高；完全理想排序时返回 1。
+ */
+function ndcgAtK(returnedNames, expected, k) {
+    const relMap = new Map(expected.map((e) => [e.name, e.rel]));
+    const topK = returnedNames.slice(0, k);
+    const dcg = topK.reduce((sum, name, idx) => {
+        const rel = relMap.get(name) ?? 0;
+        return sum + (Math.pow(2, rel) - 1) / Math.log2(idx + 2);
+    }, 0);
+    const idealRels = expected
+        .map((e) => e.rel)
+        .sort((a, b) => b - a)
+        .slice(0, k);
+    const idcg = idealRels.reduce((sum, rel, idx) => {
+        return sum + (Math.pow(2, rel) - 1) / Math.log2(idx + 2);
+    }, 0);
+    return idcg === 0 ? 1 : dcg / idcg;
+}
+/**
+ * 返回失败阶段原因数组（无 ID 时按名称降级处理）
+ */
+function classifyFailuresFromTrace(expected, returnedNames, evalTrace, idByName) {
+    const relevant = expected.filter((e) => e.rel >= REL_RELEVANT_MIN);
+    const failures = [];
+    for (const exp of relevant) {
+        if (returnedNames.includes(exp.name))
+            continue;
+        const id = idByName.get(exp.name);
+        if (evalTrace !== undefined && id !== undefined) {
+            const failType = classifySymbolFailure(id, evalTrace);
+            if (failType !== 'found') {
+                failures.push({
+                    name: exp.name,
+                    expectedPath: exp.path,
+                    type: failType,
+                });
+            }
+        }
+        else {
+            // DB 中无此 symbol，降级为 no_semantic_recall
+            failures.push({
+                name: exp.name,
+                expectedPath: exp.path,
+                type: 'no_semantic_recall',
+            });
+        }
+    }
+    return failures;
+}
+// ─── ID 解析（从返回结果中建立 name→id 映射） ────────────────────────────────
+function buildIdMapFromResult(recommended, alternatives) {
+    const map = new Map();
+    if (recommended)
+        map.set(recommended.name, recommended.id);
+    alternatives.forEach((a) => map.set(a.name, a.id));
+    return map;
+}
+// ─── 汇总统计 ─────────────────────────────────────────────────────────────────
+function avg(nums) {
+    if (nums.length === 0)
+        return 0;
+    return nums.reduce((s, n) => s + n, 0) / nums.length;
+}
+function formatPct(n) {
+    return (n * 100).toFixed(1) + '%';
+}
+function printSummary(results, kMain, baseline) {
+    const positive = results.filter((r) => !r.isNegativeSample);
+    const negative = results.filter((r) => r.isNegativeSample);
+    const recallMain = avg(positive.map((r) => r.recallMain ?? 0));
+    const recall50 = avg(positive.map((r) => r.recall50 ?? 0));
+    const firstHitScore = avg(positive.map((r) => r.firstHitScore ?? 0));
+    // const rankingQuality = avg(positive.map((r) => r.rankingQuality ?? 0));
+    const coverage = positive.filter((r) => (r.recallMain ?? 0) > 0).length /
+        (positive.length || 1);
+    const top1Acc = positive.filter((r) => r.top1Correct === true).length /
+        (positive.length || 1);
+    const fpRate = negative.filter((r) => r.falsePositive).length / (negative.length || 1);
+    const diff = (metric, val) => {
+        if (!baseline || !(metric in baseline))
+            return '';
+        const delta = val - baseline[metric];
+        return delta >= 0
+            ? ` (+${formatPct(delta)})`
+            : ` (${formatPct(delta)})`;
+    };
+    console.log('\n' + '='.repeat(60));
+    console.log(`=== Eval Report  ${new Date().toISOString().slice(0, 10)} ===`);
+    console.log('='.repeat(60));
+    console.log(`Queries total:  ${results.length}  (positive: ${positive.length}, negative: ${negative.length})`);
+    console.log('');
+    console.log(`召回率(Recall@${kMain}):         ${formatPct(recallMain)}${diff('recallMain', recallMain)}`);
+    console.log(`首位命中分(MRR@${kMain}):         ${formatPct(firstHitScore)}${diff('firstHitScore', firstHitScore)}`);
+    console.log(`首条准确率(Top-1):               ${formatPct(top1Acc)}${diff('top1Acc', top1Acc)}`);
+    console.log(`误触率(FP):                      ${formatPct(fpRate)}  (负例被错误推荐)`);
+    console.log('');
+    // ── Failure breakdown ──
+    const allFailures = positive.flatMap((r) => r.failures);
+    const failureCounts = {
+        no_semantic_recall: 0,
+        reusability_filtered: 0,
+        structure_filtered: 0,
+        ranked_below_topk: 0,
+        quality_gate_rejected: 0,
+        found: 0,
+    };
+    for (const f of allFailures)
+        failureCounts[f.type]++;
+    const totalExpected = positive.reduce((s, r) => s + r.failures.length + (r.recallMain === 1 ? 1 : 0), 0);
+    console.log('--- Failure Breakdown ---');
+    const failureActionHints = {
+        no_semantic_recall: '→ 调大 SYMBOL_TOP_K / 增加 queryVariants 数量',
+        reusability_filtered: '→ 检查 isReusableCandidate 路径规则是否误杀',
+        structure_filtered: '→ 检查 category 过滤条件',
+        ranked_below_topk: '→ 调整 RANK_WEIGHTS / LITERAL_MATCH_PRIORITY_BOOST',
+        quality_gate_rejected: '→ 调低 MIN_RECOMMENDATION_SCORE 阈值',
+        found: '',
+    };
+    for (const [type, count] of Object.entries(failureCounts)) {
+        if (type === 'found')
+            continue;
+        const pct = totalExpected > 0
+            ? ((count / totalExpected) * 100).toFixed(1)
+            : '0.0';
+        const hint = failureActionHints[type];
+        console.log(`  ${type.padEnd(26)} ${String(count).padStart(3)} (${pct}%)  ${hint}`);
+    }
+    console.log('='.repeat(60) + '\n');
+}
+// ─── 主流程 ───────────────────────────────────────────────────────────────────
+async function loadQuerySet(filePath) {
+    const cases = [];
+    const rl = readline.createInterface({
+        input: fs.createReadStream(filePath),
+        crlfDelay: Infinity,
+    });
+    for await (const line of rl) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        if (trimmed.startsWith('#') || trimmed.startsWith('//'))
+            continue;
+        cases.push(JSON.parse(trimmed));
+    }
+    return cases;
+}
+async function runEval() {
+    console.log(`Loading query set: ${QUERY_SET_PATH}`);
+    const cases = await loadQuerySet(QUERY_SET_PATH);
+    console.log(`Loaded ${cases.length} queries. Running eval with limit=${TOP_K_MAIN}/${RECALL_WIDE_K}...\n`);
+    const repository = new SymbolRepository();
+    const service = new RecommendationService(repository);
+    const results = [];
+    for (const queryCase of cases) {
+        const isNegative = queryCase.expected.length === 0;
+        const wideResult = await service.recommendComponent({
+            ...queryCase.input,
+            limit: RECALL_WIDE_K,
+            evalMode: true,
+        });
+        const wideNames = [
+            ...(wideResult.recommended ? [wideResult.recommended.name] : []),
+            ...wideResult.alternatives.map((a) => a.name),
+        ];
+        const mainNames = wideNames.slice(0, TOP_K_MAIN);
+        const allReturned = [
+            ...(wideResult.recommended ? [wideResult.recommended] : []),
+            ...wideResult.alternatives,
+        ];
+        const idByName = buildIdMapFromResult(wideResult.recommended, wideResult.alternatives);
+        const recallMain = isNegative
+            ? null
+            : recallAtK(mainNames, queryCase.expected, TOP_K_MAIN);
+        const recall50 = isNegative
+            ? null
+            : recallAtK(wideNames, queryCase.expected, RECALL_WIDE_K);
+        const firstHitRank = isNegative
+            ? null
+            : mrrAtK(mainNames, queryCase.expected, TOP_K_MAIN);
+        // const rankingQuality = isNegative
+        //     ? null
+        //     : ndcgAtK(mainNames, queryCase.expected, TOP_K_MAIN);
+        const top1Correct = isNegative
+            ? null
+            : queryCase.expected.some((e) => e.rel === REL_PRIMARY &&
+                wideResult.recommended?.name === e.name);
+        const failures = isNegative
+            ? []
+            : classifyFailuresFromTrace(queryCase.expected, wideNames, wideResult.evalTrace, idByName);
+        const falsePositive = isNegative && allReturned.length > 0;
+        const qr = {
+            queryId: queryCase.id,
+            query: queryCase.input.query,
+            tags: queryCase.tags,
+            recallMain,
+            recall50,
+            firstHitScore: firstHitRank,
+            // rankingQuality,
+            top1Correct,
+            returnedNames: mainNames,
+            failures,
+            isNegativeSample: isNegative,
+            falsePositive,
+        };
+        results.push(qr);
+        const status = isNegative
+            ? falsePositive
+                ? '✗ False Positive）' // 负例，但系统返回了结果 → 误触发（False Positive）
+                : '✓ True Negative' // 负例，系统正确返回空   → 真负例（True Negative）
+            : recallMain === 1
+                ? `✓ R@${TOP_K_MAIN}=1.0 完全召回`
+                : `✗ R@${TOP_K_MAIN}=${(recallMain ?? 0).toFixed(2)} 不完全召回`;
+        console.log(`  [${queryCase.id}] ${queryCase.input.query.slice(0, 40).padEnd(40)}  ${status}`);
+    }
+    printSummary(results, TOP_K_MAIN, null);
+    if (OUTPUT_DIR) {
+        fs.mkdirSync(OUTPUT_DIR, { recursive: true });
+        const dateStr = new Date().toISOString().slice(0, 10);
+        const outPath = path.join(OUTPUT_DIR, `${dateStr}.jsonl`);
+        const lines = results.map((r) => JSON.stringify(r)).join('\n');
+        fs.writeFileSync(outPath, lines + '\n', 'utf8');
+        console.log(`Report written to: ${outPath}`);
+    }
+    // 如果有正例查询完全没有召回任何相关结果，视为严重问题，输出警告并退出非 0 状态码以示 CI 失败。
+    const zeroRecall = results.filter((r) => !r.isNegativeSample && r.recallMain === 0);
+    if (zeroRecall.length > 0) {
+        console.log(`\nWARN: ${zeroRecall.length} positive queries have Recall@${TOP_K_MAIN}=0:`);
+        for (const r of zeroRecall) {
+            console.log(`  [${r.queryId}] ${r.query}`);
+        }
+        process.exit(1);
+    }
+}
+runEval().catch((err) => {
+    console.error('Eval failed:', err);
+    process.exit(1);
+});

package/dist/config/queryRewrite.js

@@ -0,0 +1,95 @@
+/**
+ * queryRewrite.ts — query 预处理配置：噪音词清洗 + 同义词/别名扩展。
+ *
+ * 用于 buildQueryVariants，通过消除口语化干扰词和补充同义词变体，
+ * 提升语义检索的 recall（尤其是中英混用、别名查询场景）。
+ */
+// ─── 噪音词清洗正则（从 recommendationService 迁移） ────────────────────────
+/**
+ * 依次对原始 query 做替换，去掉无实际语义的口语词。
+ * 注意：每个 pattern 带 /g 标志，替换后产生多余空格由调用方合并。
+ */
+export const NOISE_PATTERNS = [
+    /^帮我找(找)?(一个|一下)?/g,
+    /^有没有(现成的)?/g,
+    /^请推荐(一个|一下)?/g,
+    /可复用/g,
+    /现成的/g,
+    /封装好的/g,
+    /(组件|函数|hook|工具|util)(实现)?/gi,
+];
+// ─── 同义词/别名字典 ─────────────────────────────────────────────────────────
+/**
+ * 每个 key 为一组同义词的首选英文词根，value 为同一概念的其他表达形式（中文、缩写、别名）。
+ *
+ * 匹配规则：任意一项（key 或 value 中的词）出现在 query 里即视为命中，
+ * 然后取组内第一个当前 query 中未出现的词作为替代词，生成同义扩展变体。
+ *
+ * 新增规则：key 使用最短、最通用的英文词根；中文词放在 value 数组最前。
+ */
+export const SYNONYM_MAP = {
+    // 表单输入
+    input: ['输入框', '输入', 'textfield', 'textinput'],
+    textarea: ['文本域', '多行输入', 'multiline'],
+    select: ['选择器', '下拉框', '下拉', 'dropdown'],
+    checkbox: ['复选框', '勾选'],
+    radio: ['单选框', '单选'],
+    // 弹层
+    dialog: ['弹窗', '弹框', '对话框', 'modal', 'popup'],
+    tooltip: ['提示', '气泡提示', '悬浮提示', 'popover'],
+    drawer: ['抽屉', '侧边栏', 'sidebar'],
+    // 反馈
+    loading: ['加载', '加载中', 'spinner'],
+    skeleton: ['骨架屏', '占位图', 'placeholder'],
+    notification: ['通知', '消息', '提醒', 'toast'],
+    alert: ['警告', '警示', '提示框'],
+    // 数据展示
+    table: ['表格'],
+    list: ['列表'],
+    pagination: ['分页', '翻页', 'pager'],
+    tabs: ['标签页', '选项卡', 'tab'],
+    badge: ['徽标', '角标', '标记'],
+    tag: ['标签', 'chip'],
+    // 导航
+    navigation: ['导航', 'nav'],
+    menu: ['菜单'],
+    breadcrumb: ['面包屑'],
+    // 媒体/布局
+    carousel: ['轮播', '走马灯', 'slider', 'swiper'],
+    upload: ['上传', '文件上传', 'file upload'],
+    image: ['图片', '图像', 'img'],
+    // 常用 Hook
+    debounce: ['防抖', '去抖', 'usedebounce'],
+    throttle: ['节流', 'usethrottle'],
+    // 搜索
+    search: ['搜索', '查询', 'filter'],
+    // 按钮
+    button: ['按钮', 'btn'],
+};
+// ─── 同义词扩展函数 ──────────────────────────────────────────────────────────
+/**
+ * 在 query 中查找 SYNONYM_MAP 里命中的词，替换成同组内一个当前未出现的词，
+ * 生成同义扩展变体。若未命中任何同义词则返回 null。
+ *
+ * @example
+ * buildSynonymVariant('弹窗 onChange') // => 'dialog onChange'
+ * buildSynonymVariant('input onChange') // => '输入框 onChange'
+ */
+export function buildSynonymVariant(query) {
+    const lower = query.toLowerCase();
+    for (const [canonical, aliases] of Object.entries(SYNONYM_MAP)) {
+        const allTerms = [canonical, ...aliases];
+        const matchedTerm = allTerms.find((t) => lower.includes(t.toLowerCase()));
+        if (!matchedTerm)
+            continue;
+        const substitute = allTerms.find((t) => !lower.includes(t.toLowerCase()) && t !== matchedTerm);
+        if (!substitute)
+            continue;
+        // 大小写不敏感替换
+        const replaced = query.replace(new RegExp(matchedTerm.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'gi'), substitute);
+        const trimmed = replaced.replace(/\s+/g, ' ').trim();
+        if (trimmed && trimmed !== query)
+            return trimmed;
+    }
+    return null;
+}

package/dist/config/tuning.js

@@ -100,6 +100,10 @@ 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;
+/** 文件名为 index.js/ts/tsx/jsx 时对优先级分数的加成（优先推荐组件目录入口文件） */
+export const INDEX_FILE_PRIORITY_BOOST = 0.18;
+/** 同目录中存在 index 文件时，对其他非入口子文件的优先级扣减（避免 menu.js / panel.js 等内部实现抢占推荐位） */
+export const SAME_DIR_INDEX_EXISTS_PENALTY = 0.25;
 // ─── 搜索工具结果过滤 (tools/searchSymbols.ts) ───────────────────────────────
 /** 最终返回结果所需的最低综合评分 */
 export const SEARCH_SCORE_THRESHOLD = 0.45;

package/dist/indexer/chunkText.js

@@ -117,19 +117,51 @@ export function splitTextIntoChunks(content, options = {}) {
             ? 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;
+            // ── 3. 滑动窗口 + overlap ─────────────────────────────────────────
+            // 目标：把 parts 依次合并到 currentBlocks，直到"该收了"再收敛成一个 chunk。
+            // 收敛后 finalizeChunk 会把末尾 overlapChars 个字符带入下一块，减少边界信息丢失。
+            //
+            // 执行示例（targetChars=20, maxChars=30, overlapChars=5）：
+            //
+            //   part="Hello world"(11)   currentLength=0  → 直接 push
+            //     currentBlocks=["Hello world"]  currentLength=11
+            //
+            //   part="Foo bar baz"(11)   additionLength=11+2=13  currentLength+13=24 ≤ 30，未达目标 → 直接 push
+            //     currentBlocks=["Hello world","Foo bar baz"]  currentLength=24
+            //
+            //   part="A long sentence"(15)  additionLength=15+2=17  currentLength+17=41 > 30 → wouldOverflowMax=true
+            //     → finalizeChunk: chunks=["Hello world\n\nFoo bar baz"]
+            //                      overlap="r baz"(末5字符)  currentBlocks=["r baz"]  currentLength=5
+            //     → push "A long sentence"
+            //       currentBlocks=["r baz","A long sentence"]  currentLength=5+2+15=22
+            //
+            //   最终 finalizeChunk(overlap=0): chunks 追加 "r baz\n\nA long sentence"
+            // ─────────────────────────────────────────────────────────────────
+            // SEP=2 对应 blocks.join('\n\n') 中每条边界的 '\n\n' 长度；
+            // 首个 block 无分隔符，所以 currentLength===0 时不加。
+            const SEP = 2;
+            const additionLength = currentLength === 0 ? part.length : SEP + part.length;
+            // 两种情况需要先收敛当前 chunk：
+            // 1. wouldOverflowMax：加入本 part 后超出硬上限，被动截断；
+            // 2. reachedTarget   ：当前已达目标大小，主动分块，保持粒度均匀。
             const wouldOverflowMax = currentLength > 0 && currentLength + additionLength > maxChars;
             const reachedTarget = currentLength >= targetChars;
-            // 已接近目标大小或即将超出上限时，先收敛当前 chunk，再开始下一块。
             if (wouldOverflowMax || reachedTarget) {
+                // finalizeChunk 写入 chunks，并把末尾 overlap 文本返回作为新 currentBlocks 起点。
                 currentBlocks = finalizeChunk(chunks, currentBlocks, overlapChars);
+                // overlap 文本长度不固定，必须重算（不能增量推导）。
                 currentLength = currentBlocks.join('\n\n').length;
             }
             currentBlocks.push(part);
-            currentLength = currentBlocks.join('\n\n').length;
+            // flush 后 currentBlocks 可能含 overlap（length ≥ 1），也可能为空（length === 0）；
+            // 增量计算避免每次重新 join 整个数组。
+            currentLength =
+                currentLength === 0
+                    ? part.length
+                    : currentLength + SEP + part.length;
         }
     }
+    // 收尾兜底，确保剩余内容不丢失
     finalizeChunk(chunks, currentBlocks, 0);
     return chunks;
 }

package/dist/services/embeddingQueue.js

@@ -15,6 +15,7 @@ import { env } from '../config/env.js';
 let _queue = null;
 let _connection = null;
 function getQueue() {
+    // worker3 往 Redis 写 job
     if (!_queue) {
         _connection = new Redis(env.redisUrl, {
             maxRetriesPerRequest: null, // BullMQ required

package/dist/services/recommendationService.js

@@ -28,7 +28,8 @@
  * ──────────────────────────────────────────────────────────────────────────────
  */
 import { rankSemanticHits, rankSymbols } from './ranking.js';
-import { DEMO_PATH_PRIORITY_PENALTY, LITERAL_MATCH_PRIORITY_BOOST, MIN_LITERAL_MATCH_SCORE, MIN_RECOMMENDATION_SCORE, MIN_SEMANTIC_TEXT_MATCH_SCORE, REQUIRED_FIELD_FALLBACK_MIN_SCORE, } from '../config/tuning.js';
+import { DEMO_PATH_PRIORITY_PENALTY, INDEX_FILE_PRIORITY_BOOST, LITERAL_MATCH_PRIORITY_BOOST, MIN_LITERAL_MATCH_SCORE, MIN_RECOMMENDATION_SCORE, MIN_SEMANTIC_TEXT_MATCH_SCORE, REQUIRED_FIELD_FALLBACK_MIN_SCORE, SAME_DIR_INDEX_EXISTS_PENALTY, } from '../config/tuning.js';
+import { NOISE_PATTERNS, buildSynonymVariant } from '../config/queryRewrite.js';
 /** 跳过原因标识 */
 const SKIPPED_REASON = {
     NO_COMBINED: 'no_combined',
@@ -50,8 +51,8 @@ const RECOMMENDATION_MESSAGE = {
 };
 /** 详情补查的 top-k 条数 */
 const ENRICH_TOP_K = 3;
-/** 最多取查询变体数量 */
-const MAX_QUERY_VARIANTS = 2;
+/** 最多取查询变体数量（原始 + 清洗 + 同义词扩展） */
+const MAX_QUERY_VARIANTS = 3;
 /** 结构/语义搜索 limit 倍数 */
 const STRUCTURE_LIMIT_MULTIPLIER = 4;
 /** 结构/语义搜索 limit 最小值 */
@@ -61,31 +62,33 @@ const DEFAULT_KEYWORD_SIMILARITY = 0.55;
 function uniqueStrings(values = []) {
     return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
 }
-const QUERY_REWRITE_PATTERNS = [
-    /^帮我找(找)?(一个|一下)?/g,
-    /^有没有(现成的)?/g,
-    /^请推荐(一个|一下)?/g,
-    /可复用/g,
-    /现成的/g,
-    /封装好的/g,
-    /(组件|函数|hook|工具|util)(实现)?/gi,
-];
 /**
- * 对原始查询进行清洗和变体生成，去掉无意义的词，提炼更核心的查询内容
+ * 对原始查询进行清洗和变体生成：
+ * 1. 噪音词清洗（去掉口语化前缀、无意义词）
+ * 2. 同义词扩展（中英互转、别名替换）
+ * 生成最多 MAX_QUERY_VARIANTS 个去重变体，按从精确到宽泛排序。
  */
 function buildQueryVariants(rawQuery) {
     const base = rawQuery.trim();
     if (!base)
         return [];
-    let rewritten = base;
-    for (const pattern of QUERY_REWRITE_PATTERNS) {
-        rewritten = rewritten.replace(pattern, ' ');
-    }
-    rewritten = rewritten.replace(/\s+/g, ' ').trim();
-    if (!rewritten || rewritten === base) {
-        return [base];
+    // Step 1: 噪音词清洗
+    let cleaned = base;
+    for (const pattern of NOISE_PATTERNS) {
+        cleaned = cleaned.replace(pattern, ' ');
     }
-    return uniqueStrings([base, rewritten]);
+    cleaned = cleaned.replace(/\s+/g, ' ').trim();
+    if (!cleaned)
+        cleaned = base;
+    // Step 2: 同义词扩展（基于清洗后的 query，减少噪音干扰匹配）
+    const synonymVariant = buildSynonymVariant(cleaned);
+    // 候选：原始 → 清洗后（若不同）→ 同义词扩展（若不同）
+    const candidates = [
+        base,
+        cleaned,
+        ...(synonymVariant ? [synonymVariant] : []),
+    ];
+    return uniqueStrings(candidates);
 }
 function normalizeToken(value) {
     return value.trim().toLowerCase();
@@ -205,6 +208,14 @@ function isDemoLikePath(path, strict = false) {
         : DEMO_LIKE_PATH_SEGMENTS_SOFT;
     return segments.some((segment) => normalizedPath.includes(segment));
 }
+/**
+ * 判断文件是否为组件目录入口文件（index.js / index.ts / index.tsx / index.jsx）。
+ * 入口文件是组件的公共 API，应优先于内部子文件被推荐。
+ */
+function isIndexFile(filePath) {
+    const basename = filePath.split('/').pop()?.toLowerCase() ?? '';
+    return /^index\.(js|ts|tsx|jsx)$/.test(basename);
+}
 /**
  * 判断是否为可复用候选，过滤掉明显的测试/示例代码。虽然有可能误伤一些真实组件，但优先保证推荐结果的实用性和专业度。
  * @param symbol 要判断的代码符号
@@ -295,6 +306,10 @@ function computeRecommendationPriority(item, query) {
         score += LITERAL_MATCH_PRIORITY_BOOST;
         notes.push('名称或文件名命中查询');
     }
+    if (isIndexFile(path)) {
+        score += INDEX_FILE_PRIORITY_BOOST;
+        notes.push('组件目录入口文件优先');
+    }
     if (isDemoLikePath(path)) {
         score -= DEMO_PATH_PRIORITY_PENALTY;
         notes.push('示例工程路径降权');
@@ -306,6 +321,49 @@ function computeRecommendationPriority(item, query) {
             : item.reason.summary,
     };
 }
+/**
+ * 同目录 index 文件降权：当结果集中某目录已有 index 文件时，对该目录内其他子文件扭扣分，
+ * 解决 index.js 因内容稀疏（仅有 re-export）导致 embedding 分低而被内部子文件抑制的问题。
+ */
+function applyDirectoryIndexPenalty(entries) {
+    // 找出结果集中哪些目录已有 index 文件
+    const dirsWithIndex = new Set();
+    for (const entry of entries) {
+        const p = entry.item.symbol.path;
+        if (isIndexFile(p)) {
+            const dir = p.includes('/')
+                ? p.substring(0, p.lastIndexOf('/'))
+                : '';
+            dirsWithIndex.add(dir);
+        }
+    }
+    if (dirsWithIndex.size === 0)
+        return entries;
+    // 对同目录中的非入口文件手动扣分
+    return entries.map((entry) => {
+        const p = entry.item.symbol.path;
+        if (isIndexFile(p))
+            return entry;
+        const dir = p.includes('/') ? p.substring(0, p.lastIndexOf('/')) : '';
+        if (!dirsWithIndex.has(dir))
+            return entry;
+        const newScore = Number(Math.max(0, entry.adjustedScore - SAME_DIR_INDEX_EXISTS_PENALTY).toFixed(3));
+        return {
+            ...entry,
+            adjustedScore: newScore,
+            adjustedReason: `${entry.adjustedReason} + 同目录入口文件已命中，内部子文件降权`,
+        };
+    });
+}
+function accToEvalTrace(acc) {
+    return {
+        semanticIds: [...acc.semanticIds],
+        reusableIds: [...acc.reusableIds],
+        combinedIds: [...acc.combinedIds],
+        qualifiedIds: [...acc.qualifiedIds],
+        returnedIds: [...acc.returnedIds],
+    };
+}
 export class RecommendationService {
     repository;
     constructor(repository) {
@@ -400,6 +458,15 @@ export class RecommendationService {
         let selectedQuery = null;
         let fallbackReason = null;
         const attempts = [];
+        const evalAcc = input.evalMode
+            ? {
+                semanticIds: new Set(),
+                reusableIds: new Set(),
+                combinedIds: new Set(),
+                qualifiedIds: new Set(),
+                returnedIds: new Set(),
+            }
+            : undefined;
         this.logSearchTypes(searchTypes);
         for (const queryVariant of queryVariants) {
             const { attempt, combined, searchResults, gathered } = await this.tryQueryVariant({
@@ -411,6 +478,7 @@ export class RecommendationService {
                 structureFields,
                 requiredProps,
                 requiredHooks,
+                evalAcc,
             });
             queriedBy = gathered.queriedBy;
             if (!fallbackReason && gathered.fallbackReason) {
@@ -433,6 +501,7 @@ export class RecommendationService {
                 requiredHooks,
                 attempt,
                 limit,
+                evalAcc,
             });
             lastRankedCandidates = candidates;
             if (candidates.length > 0) {
@@ -454,6 +523,7 @@ export class RecommendationService {
                     attempts,
                     selectedQuery,
                     fallbackReason,
+                    evalTrace: evalAcc ? accToEvalTrace(evalAcc) : undefined,
                 });
             }
             this.logAttemptCheckpoint('attempt.no_candidate_after_rank', attempt);
@@ -474,6 +544,7 @@ export class RecommendationService {
             attempts,
             selectedQuery,
             fallbackReason,
+            evalTrace: evalAcc ? accToEvalTrace(evalAcc) : undefined,
         });
     }
     logStart(input) {
@@ -505,9 +576,12 @@ export class RecommendationService {
         console.error('[code-intelligence-mcp] recommendComponent.preprocess queryVariants=%s requiredProps=%s requiredHooks=%s structureFields=%s searchTypes=%s preferSemantic=%s limit=%s', JSON.stringify(queryVariants), JSON.stringify(requiredProps), JSON.stringify(requiredHooks), JSON.stringify(structureFields), JSON.stringify(searchTypes), String(preferSemantic), String(limit));
         return res;
     }
-    async tryQueryVariant({ queryVariant, input, searchTypes, preferSemantic, limit, structureFields, requiredProps, requiredHooks, }) {
+    async tryQueryVariant({ queryVariant, input, searchTypes, preferSemantic, limit, structureFields, requiredProps, requiredHooks, evalAcc, }) {
         const gathered = await this.gatherSearchResults(queryVariant, searchTypes, preferSemantic, limit);
         const searchResults = gathered.searchResults;
+        if (evalAcc) {
+            searchResults.forEach((r) => evalAcc.semanticIds.add(r.symbol.id));
+        }
         const attempt = {
             query: queryVariant,
             queriedBy: gathered.queriedBy,
@@ -542,10 +616,14 @@ export class RecommendationService {
         if (reusableCandidates.length > 0) {
             combined = reusableCandidates;
         }
+        if (evalAcc) {
+            reusableCandidates.forEach((s) => evalAcc.reusableIds.add(s.id));
+            combined.forEach((s) => evalAcc.combinedIds.add(s.id));
+        }
         attempt.combinedCount = combined.length;
         return { attempt, combined, searchResults, gathered };
     }
-    async rankAndEnrichCandidates({ combined, searchResults, queryVariant, queriedBy, requiredProps, requiredHooks, attempt, limit, }) {
+    async rankAndEnrichCandidates({ combined, searchResults, queryVariant, queriedBy, requiredProps, requiredHooks, attempt, limit, evalAcc, }) {
         const ranked = queriedBy === QUERIED_BY.SEMANTIC
             ? rankSemanticHits(combined.map((symbol) => ({
                 symbol,
@@ -564,14 +642,17 @@ export class RecommendationService {
             };
         });
         priorityScored.sort((a, b) => b.adjustedScore - a.adjustedScore);
+        // 同目录 index 文件降权：对同目录非入口子文件扭扣，确保 index.js > menu.js / panel.js
+        const reranked = applyDirectoryIndexPenalty(priorityScored);
+        reranked.sort((a, b) => b.adjustedScore - a.adjustedScore);
         // 对优先级预排序后的 Top-K 做详情补查（getByName 补全完整 meta）
-        const enriched = await this.enrichTopCandidatesWithDetail(priorityScored.map((e) => e.item));
+        const enriched = await this.enrichTopCandidatesWithDetail(reranked.map((e) => e.item));
         attempt.detailEnrichedCount = enriched.enrichedCount;
-        // 将补查结果回填到 priorityScored，保持优先级排序
+        // 将补查结果回填到 reranked，保持优先级排序
         const enrichedPriorityScored = enriched.ranked.map((item, idx) => ({
             item,
-            adjustedScore: priorityScored[idx]?.adjustedScore ?? item.score,
-            adjustedReason: priorityScored[idx]?.adjustedReason ?? item.reason.summary,
+            adjustedScore: reranked[idx]?.adjustedScore ?? item.score,
+            adjustedReason: reranked[idx]?.adjustedReason ?? item.reason.summary,
         }));
         // 质量门控：score 阈值 + requiredProps/Hooks 命中校验（依赖完整 meta，必须在补查之后）
         const qualifiedRanked = enrichedPriorityScored.filter((entry) => isStrongEnoughRecommendation(entry.item, queryVariant, queriedBy, requiredProps, requiredHooks));
@@ -579,8 +660,14 @@ export class RecommendationService {
         if (qualifiedRanked.length === 0) {
             attempt.skippedReason = SKIPPED_REASON.NO_QUALIFIED;
         }
+        if (evalAcc) {
+            qualifiedRanked.forEach((e) => evalAcc.qualifiedIds.add(e.item.symbol.id));
+        }
         // 已按优先级排序，直接构建候选结果
         const candidates = qualifiedRanked.map((entry) => toCandidate(entry.item.symbol, entry.adjustedScore, entry.adjustedReason, requiredProps, requiredHooks));
+        if (evalAcc) {
+            candidates.forEach((c) => evalAcc.returnedIds.add(c.id));
+        }
         console.error('[code-intelligence-mcp] recommendComponent.rank query=%s queriedBy=%s enriched=%s qualified=%s candidates=%s', queryVariant, queriedBy, String(enrichedPriorityScored.length), String(qualifiedRanked.length), String(candidates.length));
         return candidates;
     }
@@ -590,7 +677,7 @@ export class RecommendationService {
     logAttemptsTrace(stage, payload) {
         console.error('[code-intelligence-mcp] %s selectedQuery=%s queriedBy=%s attempts=%s fallbackReason=%s', stage, payload.selectedQuery ?? 'none', payload.queriedBy, JSON.stringify(payload.attempts), payload.fallbackReason ?? 'none');
     }
-    buildResult({ recommended, alternatives, queriedBy, requiredProps, requiredHooks, attempts, selectedQuery, fallbackReason, }) {
+    buildResult({ recommended, alternatives, queriedBy, requiredProps, requiredHooks, attempts, selectedQuery, fallbackReason, evalTrace, }) {
         return {
             recommended,
             alternatives,
@@ -608,6 +695,7 @@ export class RecommendationService {
                 retryUsed: attempts.length > 1,
                 fallbackReason,
             },
+            evalTrace,
         };
     }
 }

package/dist/types/evalTrace.js

@@ -0,0 +1,25 @@
+/**
+ * evalTrace.ts — 推荐主链各阶段符号 ID 追踪，仅在 evalMode=true 时填充。
+ *
+ * 用于 eval CLI 做 per-symbol 失败分类（误杀分析），
+ * 判断 expected symbol 在哪个阶段丢失：
+ *   semanticIds → reusableIds → combinedIds → qualifiedIds → returnedIds
+ */
+/**
+ * 根据 EvalTrace 对单个 expected symbol 进行失败分类。
+ * @param symbolId DB 中的 symbol.id（需提前通过名称解析）
+ * @param trace 该次推荐调用的 EvalTrace
+ */
+export function classifySymbolFailure(symbolId, trace) {
+    if (trace.returnedIds.includes(symbolId))
+        return 'found';
+    if (!trace.semanticIds.includes(symbolId))
+        return 'no_semantic_recall';
+    if (!trace.reusableIds.includes(symbolId))
+        return 'reusability_filtered';
+    if (!trace.combinedIds.includes(symbolId))
+        return 'structure_filtered';
+    if (!trace.qualifiedIds.includes(symbolId))
+        return 'ranked_below_topk';
+    return 'quality_gate_rejected';
+}

package/dist/workers/embeddingWorker.js

@@ -14,6 +14,11 @@
  * 大仓分片：
  * - 直接启动多个 worker 进程（同一 Redis）即可水平扩展，BullMQ 原生分布式协调
  */
+// env.redisUrl (同一个 Redis)  url+name('embedding') 决定了 BullMQ 的队列，生产者和消费者通过它们读写同一个队列实现通信
+//        │
+//        ├─ Queue('embedding')      → LPUSH bull:embedding:wait  ...  ← Producer 写
+//        ├─ Worker('embedding')     → BRPOPLPUSH bull:embedding:wait  ← Worker 消费
+//        └─ QueueEvents('embedding')→ SUBSCRIBE bull:embedding:events ← 监听事件
 import { Worker, QueueEvents } from 'bullmq';
 import { Redis } from 'ioredis';
 import { env } from '../config/env.js';
@@ -91,11 +96,14 @@ async function processEmbedJob(job, pool) {
  */
 export async function startEmbeddingWorker(opts = {}) {
     const { concurrency = 5, rpmLimit = 100 } = opts;
+    // worker1 负责从 Redis 拉 job。
+    // BullMQ Worker 用它执行 BRPOPLPUSH 这类阻塞命令来抢占 job、加锁、标记完成/失败。阻塞命令会占住整个连接，无法复用。
     const connection = new Redis(env.redisUrl, {
         maxRetriesPerRequest: null,
         enableReadyCheck: false,
     });
-    // 独立连接监听队列事件（BullMQ 要求不共用 Worker 连接）
+    // worker2 负责订阅 Redis 的 Pub/Sub 事件频道。
+    // 给 QueueEvents 用。BullMQ 在 Redis 里发 Pub/Sub 事件（drained、completed、failed…），监听方需要独立的连接订阅这些事件频道。如果共用 connection，阻塞命令会让 Pub/Sub 订阅无法正常工作，所以 BullMQ 官方要求两个连接必须分开。
     const eventsConnection = new Redis(env.redisUrl, {
         maxRetriesPerRequest: null,
         enableReadyCheck: false,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lorrylurui/code-intelligence-mcp",
-    "version": "2.0.8",
+    "version": "2.1.0",
     "private": false,
     "description": "MCP server 提供仓库内可复用代码块（ts/tsx/js/jsx/css/less）的索引和查询能力，支持基于代码上下文的智能推荐。",
     "type": "module",
@@ -9,8 +9,8 @@
         "dist"
     ],
     "bin": {
-        "code-intelligence-mcp": "./dist/index.js",
-        "code-intelligence-index": "./dist/cli/index-codebase-cli.js"
+        "code-intelligence-mcp": "dist/index.js",
+        "code-intelligence-index": "dist/cli/index-codebase-cli.js"
     },
     "scripts": {
         "dev": "tsx watch --clear-screen=false --exclude node_modules --exclude dist src/index.ts",
@@ -21,6 +21,8 @@
         "start": "node dist/index.js",
         "index": "tsx src/cli/index-codebase-cli.ts",
         "ci-index": "tsx src/cli/ci-index-cli.ts",
+        "eval": "tsx src/cli/eval-recommendation-cli.ts",
+        "analyze": "tsx src/cli/eval-analyze-cli.ts",
         "worker:embedding": "tsx src/cli/embedding-worker-cli.ts",
         "embedding:dev": "cd embedding-service && python3 -m uvicorn app:app --host 127.0.0.1 --port 8765",
         "docker:up": "docker compose up -d",