@lorrylurui/code-intelligence-mcp 2.0.7 → 2.0.9

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

@@ -0,0 +1,296 @@
+/**
+ * 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 TOP_K_WIDE = 50; // Recall@50（宽口径）
+// ─── 指标计算 ─────────────────────────────────────────────────────────────────
+/**
+ * 覆盖率 Recall@K：前 K 条结果中命中的相关条目占全部相关条目的比例。
+ * 衡量「应该找到的有多少被找到了」，与排名顺序无关。
+ * 负例（expected 全为 rel=0）视为完全命中，返回 1。
+ */
+function recallAtK(returnedNames, expected, k) {
+    const relevant = expected.filter((e) => e.rel >= 1);
+    if (relevant.length === 0)
+        return 1;
+    const topK = returnedNames.slice(0, k);
+    const hits = relevant.filter((e) => topK.includes(e.name));
+    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 >= 1).map((e) => e.name));
+    const topK = returnedNames.slice(0, k);
+    for (let i = 0; i < topK.length; i++) {
+        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 >= 1);
+    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 mrr = avg(positive.map((r) => r.mrrMain ?? 0));
+    const ndcg = avg(positive.map((r) => r.ndcgMain ?? 0));
+    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(`Recall@50:    ${formatPct(recall50)}${diff('recall50', recall50)}`);
+    console.log(`MRR@${kMain}:       ${formatPct(mrr)}${diff('mrr', mrr)}`);
+    console.log(`nDCG@${kMain}:      ${formatPct(ndcg)}${diff('ndcg', ndcg)}`);
+    console.log(`Top1 Acc:     ${formatPct(top1Acc)}${diff('top1Acc', top1Acc)}`);
+    console.log(`False Pos:    ${formatPct(fpRate)}  (negative samples incorrectly returned results)`);
+    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;
+        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}/${TOP_K_WIDE}...\n`);
+    const repository = new SymbolRepository();
+    const service = new RecommendationService(repository);
+    const results = [];
+    for (const queryCase of cases) {
+        const isNegative = queryCase.expected.length === 0;
+        // Run with wide limit (Recall@50)
+        const wideResult = await service.recommendComponent({
+            ...queryCase.input,
+            limit: TOP_K_WIDE,
+            evalMode: true,
+        });
+        const wideNames = [
+            ...(wideResult.recommended ? [wideResult.recommended.name] : []),
+            ...wideResult.alternatives.map((a) => a.name),
+        ];
+        // Run with main limit for MRR/nDCG (or reuse wide result slice)
+        const mainNames = wideNames.slice(0, TOP_K_MAIN);
+        // Build id map from returned results
+        const allReturned = [
+            ...(wideResult.recommended ? [wideResult.recommended] : []),
+            ...wideResult.alternatives,
+        ];
+        const idByName = buildIdMapFromResult(wideResult.recommended, wideResult.alternatives);
+        // Metrics (skip for negative samples)
+        const recallMain = isNegative
+            ? null
+            : recallAtK(mainNames, queryCase.expected, TOP_K_MAIN);
+        const recall50 = isNegative
+            ? null
+            : recallAtK(wideNames, queryCase.expected, TOP_K_WIDE);
+        const mrrMain = isNegative
+            ? null
+            : mrrAtK(mainNames, queryCase.expected, TOP_K_MAIN);
+        const ndcgMain = isNegative
+            ? null
+            : ndcgAtK(mainNames, queryCase.expected, TOP_K_MAIN);
+        const top1Correct = isNegative
+            ? null
+            : queryCase.expected.some((e) => e.rel === 2 && wideResult.recommended?.name === e.name);
+        // Failure classification
+        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,
+            mrrMain,
+            ndcgMain,
+            top1Correct,
+            returnedNames: mainNames,
+            failures,
+            isNegativeSample: isNegative,
+            falsePositive,
+        };
+        results.push(qr);
+        // Progress
+        const status = isNegative
+            ? falsePositive
+                ? '✗ FP'
+                : '✓ TN'
+            : 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}`);
+    }
+    // Print summary
+    printSummary(results, TOP_K_MAIN, null);
+    // Write JSONL report
+    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}`);
+    }
+    // Exit with non-zero if any positive query has recall=0
+    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/indexer/persistSymbols.js

@@ -1,29 +1,22 @@
 import { env } from '../config/env.js';
-import { getAllTableSQLs } from '../db/schema.js';
 import { SYMBOL_STATUS } from '../config/symbolStatus.js';
 /**
  * 依赖表上 `(path, name)` 唯一键：新行插入，已存在则更新类型/描述/内容与 meta；**不**修改 `usage_count`。
+ * 事务与连接生命周期由调用方管理。
  * @param rows 来自 `indexProject`；空数组时立即返回，不开启事务。
  * @param embeddings 与 `rows` 等长；某项为 `null` 表示本行不更新已有 `embedding`（新行则写入 NULL）。
  *   - 有值 → status 置为 online(2)
  *   - null  → 新行写 pending(1)，已有行保持原 status
  */
-export async function upsertSymbols(pool, rows, embeddings) {
+export async function upsertSymbols(client, rows, embeddings) {
     if (rows.length === 0)
         return;
     if (embeddings && embeddings.length !== rows.length) {
         throw new Error('upsertSymbols: embeddings length must match rows');
     }
     const actor = process.env.GITHUB_USERNAME?.trim() || 'system';
-    const client = await pool.connect();
-    try {
-        // 确保 extension + 表 + 基础索引存在
-        for (const sql of getAllTableSQLs()) {
-            await client.query(sql);
-        }
-        await client.query('BEGIN');
-        const t = env.symbolsTable;
-        const sql = `
+    const t = env.symbolsTable;
+    const sql = `
     INSERT INTO ${t}
       (name, type, category, path, description, content, meta,
        insert_user, updated_user, embedding, semantic_hash, file_hash, status)
@@ -36,48 +29,40 @@ export async function upsertSymbols(pool, rows, embeddings) {
       meta          = EXCLUDED.meta,
       updated_user  = EXCLUDED.updated_user,
       embedding     = CASE
-                        WHEN EXCLUDED.embedding IS NOT NULL THEN EXCLUDED.embedding
-                        WHEN EXCLUDED.semantic_hash != ${t}.semantic_hash THEN NULL
-                        ELSE ${t}.embedding
+                        WHEN EXCLUDED.embedding IS NOT NULL THEN EXCLUDED.embedding  -- 本次带了新向量，直接使用
+                        WHEN EXCLUDED.semantic_hash != ${t}.semantic_hash THEN NULL  -- 结构变了，旧向量作废，等重算
+                        ELSE ${t}.embedding                                          -- 结构未变，复用旧向量
                       END,
       semantic_hash = EXCLUDED.semantic_hash,
       file_hash     = EXCLUDED.file_hash,
       status        = CASE
-                        WHEN EXCLUDED.embedding IS NOT NULL THEN ${SYMBOL_STATUS.ONLINE}
-                        WHEN EXCLUDED.semantic_hash != ${t}.semantic_hash THEN ${SYMBOL_STATUS.PENDING}
-                        ELSE ${t}.status
+                        WHEN EXCLUDED.embedding IS NOT NULL THEN ${SYMBOL_STATUS.ONLINE}   -- 本次带了新向量 → 直接 online
+                        WHEN EXCLUDED.semantic_hash != ${t}.semantic_hash THEN ${SYMBOL_STATUS.PENDING}  -- 结构变了，需重新 embedding → pending
+                        WHEN ${t}.embedding IS NOT NULL THEN ${SYMBOL_STATUS.ONLINE}        -- 结构未变且已有向量（含 offline 恢复）→ online
+                        ELSE ${SYMBOL_STATUS.PENDING}                                       -- 结构未变但无向量（首次 or 之前失败）→ pending
                       END,
       updated_at    = NOW()
   `;
-        for (let i = 0; i < rows.length; i++) {
-            const r = rows[i];
-            const emb = embeddings?.[i];
-            // pgvector 接受 "[x1,x2,...]" 格式字符串
-            const vecStr = emb != null ? `[${emb.join(',')}]` : null;
-            const statusVal = vecStr !== null ? SYMBOL_STATUS.ONLINE : SYMBOL_STATUS.PENDING;
-            await client.query(sql, [
-                r.name,
-                r.type,
-                r.category,
-                r.path,
-                r.description,
-                r.content,
-                JSON.stringify(r.meta),
-                actor,
-                actor,
-                vecStr, // $10 → cast as vector, null 时写 NULL
-                r.semantic_hash,
-                r.file_hash,
-                statusVal,
-            ]);
-        }
-        await client.query('COMMIT');
-    }
-    catch (e) {
-        await client.query('ROLLBACK');
-        throw e;
-    }
-    finally {
-        client.release();
+    for (let i = 0; i < rows.length; i++) {
+        const r = rows[i];
+        const emb = embeddings?.[i];
+        // pgvector 接受 "[x1,x2,...]" 格式字符串
+        const vecStr = emb != null ? `[${emb.join(',')}]` : null;
+        const statusVal = vecStr !== null ? SYMBOL_STATUS.ONLINE : SYMBOL_STATUS.PENDING;
+        await client.query(sql, [
+            r.name,
+            r.type,
+            r.category,
+            r.path,
+            r.description,
+            r.content,
+            JSON.stringify(r.meta),
+            actor,
+            actor,
+            vecStr, // $10 → cast as vector, null 时写 NULL
+            r.semantic_hash,
+            r.file_hash,
+            statusVal,
+        ]);
     }
 }

package/dist/prompts/reusableCodeAdvisorPrompt.js

@@ -65,7 +65,7 @@ const REUSABLE_CODE_ADVISOR_MARKDOWN = `# 可复用代码推荐
 > 输出上述模板后**等待用户在聊天框输入回复**，识别规则：
 > - 用户输入 **"1"、"采纳"、"采纳推荐"、"ok"、"好的"** 或类似确认词 → 从上方输出文本中读取 \`symbolId：<id>\` 那一行的值，立即调用 \`inc_usage\` 工具传入该 id，调用成功后回复"✓ 已记录使用，可直接集成"
 > - 用户输入 **"2"、"取消"、"不用了"** 或类似否定词 → 回复"好的，已取消"，停止
-> - 用户输入其他内容（如追问细节）→ 正常回答，回答结束后再次展示"是否采纳"选项
+> - 用户输入其他内容（如追问细节、props、最小接入方式）→ 可以继续补充说明，但回答结尾**必须再次原样展示**"是否采纳"的两个选项，不得省略
 
 无结果时：
 
@@ -85,6 +85,7 @@ const REUSABLE_CODE_ADVISOR_MARKDOWN = `# 可复用代码推荐
 > 输出上述模板后**等待用户在聊天框输入回复**，识别规则：
 > - 用户输入 **"1"、"新建"、"帮我创建"** 或类似确认词 → 进入新建流程，引导用户确认最小接口设计
 > - 用户输入 **"2"、"取消"、"不用了"** → 回复"好的，已取消"，停止
+> - 用户输入其他内容（如追问为何没找到、想先看候选）→ 可以继续解释，但回答结尾**必须再次原样展示**"是否采纳"的两个选项，不得省略
 `;
 export function registerReusableCodeAdvisorPrompt(server) {
     server.prompt('reusable-code-advisor', REUSABLE_CODE_ADVISOR_DESCRIPTION, {

package/dist/repositories/chunkRepository.js

@@ -151,7 +151,7 @@ export class ChunkRepository {
                    1 - (embedding <=> $1::vector) AS similarity
             FROM ${env.chunksTable}
             WHERE embedding IS NOT NULL
-              AND status = $2
+              AND status = $2::smallint
         `;
         if (opts?.path) {
             params.push(opts.path);

package/dist/repositories/symbolRepository.js

@@ -146,7 +146,7 @@ export class SymbolRepository {
               path ILIKE $1 OR
               meta::text ILIKE $1
             )
-        AND status = $2
+        AND status = $2::smallint
     `;
         if (tokens.length) {
             const tokenClauses = tokens.map((token) => {
@@ -165,7 +165,7 @@ export class SymbolRepository {
               meta::text ILIKE $1 OR
               (${tokenClauses.join(' OR ')})
             )
-        AND status = $2
+        AND status = $2::smallint
     `;
         }
         if (type) {
@@ -212,7 +212,7 @@ export class SymbolRepository {
              1 - (embedding <=> $1::vector) AS similarity
       FROM ${env.symbolsTable}
       WHERE embedding IS NOT NULL
-        AND status = $2
+                AND status = $2::smallint
     `;
         if (opts?.type) {
             params.push(opts.type);
@@ -248,8 +248,9 @@ export class SymbolRepository {
       SELECT id, name, type, category, path, description, content, meta::text AS meta, usage_count, created_at
       FROM ${env.symbolsTable}
       WHERE name = $1
+                AND status = $2::smallint
       LIMIT 1
-      `, [name]);
+      `, [name, SEARCHABLE_STATUS]);
         console.error('[code-intelligence-mcp] repository.getByName.db table=%s rows=%s', env.symbolsTable, String(rows.length));
         if (rows.length === 0) {
             return null;
@@ -310,8 +311,9 @@ 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 1 = 1
+                        WHERE status = $1::smallint
     `;
+        params.push(SEARCHABLE_STATUS);
         if (type) {
             params.push(type);
             sql += ` AND type = $${params.length}`;

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