@lorrylurui/code-intelligence-mcp 1.2.0 → 2.0.1

package/dist/prompts/reusableCodeAdvisorPrompt.js

@@ -7,7 +7,7 @@ const REUSABLE_CODE_ADVISOR_MARKDOWN = `# 可复用代码推荐
 
 当用户需要可复用代码或实现类需求时，按顺序执行：
 
-1. 调用 search_symbols 检索候选，type 根据用户需求传（component/util/selector/type）
+1. 调用 search_symbols 检索候选，type 根据用户需求传（component/function/hook/class/type/interface）；描述功能意图时设置 semantic=true
 2. 如果用户指定了结构过滤条件（props/params/properties/hooks），额外调用 search_by_structure 做结构匹配
 3. 先 search_symbols(limit=20) 拉候选，再对 Top 3 调用 get_symbol_detail 做深度判断
 4. 若仅凭签名/摘要无法判断，对最相关的若干候选调用 get_symbol_detail 获取详情
@@ -16,9 +16,25 @@ const REUSABLE_CODE_ADVISOR_MARKDOWN = `# 可复用代码推荐
    - **API 是否简单**、入参是否合适
    - **依赖与副作用**风险
    - **复用安全性**（稳定性、耦合度、是否便于扩展）
-6. 给出**唯一首选**推荐，并说明理由，同时使用 **AskUserQuestion **工具,提供两个选项: 
+6. 给出**唯一首选**推荐，并说明理由，同时使用 **AskUserQuestion** 工具，提供两个选项：
    - 采纳推荐
    - 取消
+7. 用户选择"采纳推荐"后，立即调用 inc_usage 工具记录该行为（symbolId 从搜索结果的 id 字段获取），不要遗漏此步骤。
+
+## 不适用场景
+
+以下情况不要调用搜索工具：
+- 用户只是问代码如何写（概念性问题），不需要检索已有实现
+- 用户明确说"新建一个"、"自己实现"、"不用已有的"
+- 查询过于通用（如只说"utils"），先与用户确认具体需求再搜索
+
+## 搜索结果判断
+
+根据 semanticSimilarity 决定推荐置信度：
+- **> 0.85**：高置信度，可直接推荐
+- **0.6 – 0.85**：中等置信度，需结合 description 和 get_symbol_detail 综合判断
+- **< 0.6**：低置信度，说明可能无合适实现，明确告知用户
+- **空结果**：明确说"未找到已有实现"，不要凭空推荐
 
 ## 回复结构
 
@@ -30,7 +46,7 @@ const REUSABLE_CODE_ADVISOR_MARKDOWN = `# 可复用代码推荐
 - **理由：** 1～3 条要点
 - **其他候选：** 简要列出及取舍（同步标注副作用）
 - **用法提示：** 结合用户场景的最小集成说明
-- **是否采纳：** 展示两个选项: 选项1.采纳推荐 选项2.取消。等待用户确认
+- **是否采纳：** 展示两个选项：选项1. 采纳推荐  选项2. 取消。等待用户确认
 
 ## 约束
 
@@ -38,12 +54,6 @@ const REUSABLE_CODE_ADVISOR_MARKDOWN = `# 可复用代码推荐
 - 若无合适代码块，明确说明，并给出最接近的选项及差距。
 - 推理简洁，面向落地实现。
 
-## 使用反馈
-
-当选择‘采纳推荐’必须调用 inc_usage 工具记录采纳行为，调用格式如下：
-“inc_usage({ symbolId: <选中的代码块 id> })”
-其中 symbolId 从 search_symbols 或 search_by_structure 返回结果的 id 字段获取。这条记录会用于后续排序优化。
-
 ## 更多示例
 
 与仓库内 \`.cursor/skills/reusable-code-advisor/examples.md\` 中的示例一致（在 Cursor 或本地打开该文件查看）。

package/dist/repositories/symbolRepository.js

@@ -1,10 +1,9 @@
 import { env } from '../config/env.js';
-import { getMySqlPool } from '../db/mysql.js';
+import { getPool } from '../db/postgres.js';
 import { createEmbeddingClient } from '../services/embeddingClient.js';
-import { cosineSimilarity } from '../services/vectorMath.js';
 import { SEARCHABLE_STATUS } from '../config/symbolStatus.js';
-const THREADHOLD_SIMILARITY_BEFORE_RANKED = 0.5;
-const TOP_K_FOR_RANKING = 100; // 进入复杂排序的候选数上限（语义相似度初筛后保留的结果数，过大会增加排序成本）
+const SIMILARITY_THRESHOLD = 0.5;
+const TOP_K = 20;
 const inMemorySymbols = [
     {
         id: 1,
@@ -42,6 +41,7 @@ function parseEmbedding(raw) {
     }
     if (typeof raw === 'string') {
         try {
+            // pgvector 返回 "[x1,x2,...]"，恰好是合法 JSON 数组
             const j = JSON.parse(raw);
             if (!Array.isArray(j))
                 return null;
@@ -85,7 +85,7 @@ function getMetaArray(meta, key) {
 export class SymbolRepository {
     pool;
     constructor() {
-        this.pool = getMySqlPool();
+        this.pool = getPool();
     }
     async search(query, type) {
         if (!this.pool) {
@@ -97,31 +97,28 @@ export class SymbolRepository {
                         (s.description ?? '').toLowerCase().includes(q)));
             });
         }
-        const params = [`%${query}%`];
+        const params = [
+            `%${query}%`,
+            SEARCHABLE_STATUS,
+        ];
         let sql = `
-      SELECT id, name, type, category, path, description, content, CAST(meta AS CHAR) AS meta, usage_count, created_at
-      FROM ${env.mysqlSymbolsTable}
-      WHERE (name LIKE ? OR description LIKE ?)
-        AND status = ${SEARCHABLE_STATUS}
+      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)
+        AND status = $2
     `;
-        params.push(`%${query}%`);
         if (type) {
-            sql += ' AND 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);
+        const { rows } = await this.pool.query(sql, params);
         return rows.map((r) => mapRow(r));
     }
     /**
-   * Phase 5：对自然语言查询做向量检索，启用分桶采样策略，返回代码
-  块与余弦相似度。
-   * 分桶策略：
-   * - 第一层：按 category 占比计算每个分类应采样条数（保底10条）
-   * - 第二层：每个 path 子桶内乱序后采样 Math.max(5,
-  floor(catLimit / pathCount)) 条
-  * 最终选择topK，进入排序
-   */
+     * 语义向量检索：将 query 嵌入后用 pgvector <=> 运算符（cosine distance）在数据库内完成相似度排序。
+     * 不再需要在 Node 拉取全量向量做内存计算。
+     */
     async searchSemanticHits(query, opts) {
         if (!env.embeddingServiceUrl) {
             throw new Error('语义检索需配置 EMBEDDING_SERVICE_URL 并启动嵌入服务');
@@ -129,111 +126,47 @@ export class SymbolRepository {
         if (!this.pool) {
             return [];
         }
-        const candidateLimit = opts?.candidateLimit ?? 3000;
-        const limit = opts?.limit ?? TOP_K_FOR_RANKING;
-        const type = opts?.type;
+        const limit = opts?.limit ?? TOP_K;
         const client = createEmbeddingClient(env.embeddingServiceUrl);
         const [queryVec] = await client.embed([query.trim()]);
         if (!queryVec?.length) {
             throw new Error('查询向量为空');
         }
-        // 查询足够的数据以支持分桶采样（3倍候选数以覆盖各桶）
-        const fetchLimit = candidateLimit * 3;
+        // pgvector 向量字面量格式：[x1,x2,...]
+        const vecLiteral = `[${queryVec.join(',')}]`;
+        const params = [vecLiteral, SEARCHABLE_STATUS];
+        // 1 - cosine_distance = cosine_similarity；多取一倍候选后在应用层过阈值
         let sql = `
-      SELECT id, name, type, category, path, description, content, CAST(meta AS CHAR) AS meta, usage_count, created_at, embedding
-      FROM ${env.mysqlSymbolsTable}
+      SELECT id, name, type, category, path, description, content, meta::text AS meta,
+             usage_count, created_at,
+             1 - (embedding <=> $1::vector) AS similarity
+      FROM ${env.symbolsTable}
       WHERE embedding IS NOT NULL
-        AND status = ${SEARCHABLE_STATUS}
+        AND status = $2
     `;
-        const params = [];
-        if (type) {
-            sql += ' AND type = ?';
-            params.push(type);
+        if (opts?.type) {
+            params.push(opts.type);
+            sql += ` AND type = $${params.length}`;
         }
-        sql += ' DESC LIMIT ?';
-        params.push(fetchLimit);
-        const [rows] = await this.pool.query(sql, params);
-        const withVec = rows
-            .map((r) => mapRow(r, { includeEmbedding: true }))
-            .filter((s) => s.embedding && s.embedding.length === queryVec.length);
-        // 分桶采样：按 category + path 两层分桶
-        const sampled = this.bucketSampling(withVec, candidateLimit);
-        return sampled
-            .map((s) => {
-            const sim = cosineSimilarity(queryVec, s.embedding);
-            const { embedding: _, ...rest } = s;
-            return { symbol: rest, similarity: sim };
-        })
-            .filter((x) => x.similarity >= THREADHOLD_SIMILARITY_BEFORE_RANKED) // 初筛阈值，过滤掉明显不相关的结果
-            .sort((a, b) => b.similarity - a.similarity)
+        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) => ({
+            symbol: mapRow(r),
+            similarity: Number(r.similarity),
+        }))
+            .filter((x) => x.similarity >= SIMILARITY_THRESHOLD)
             .slice(0, limit);
     }
-    /**
-   * 分桶采样核心逻辑
-   * - 第一层：按 category 占比计算每个分类应采样条数（保底10条）
-   * - 第二层：每个 path 子桶内乱序后采样 Math.max(5,
-  floor(catLimit / pathCount)) 条
-   */
-    bucketSampling(symbols, limit) {
-        if (symbols.length === 0)
-            return [];
-        // 按 category 分组
-        const categoryGroups = new Map();
-        for (const s of symbols) {
-            const cat = s.category ?? '__null__';
-            if (!categoryGroups.has(cat)) {
-                categoryGroups.set(cat, []);
-            }
-            categoryGroups.get(cat).push(s);
-        }
-        const total = symbols.length;
-        const sampled = [];
-        // 第一层：按 category 占比计算采样数，保底10条
-        for (const [, catSymbols] of categoryGroups) {
-            const catCount = catSymbols.length;
-            const catRatio = catCount / total;
-            const catLimit = Math.max(10, Math.floor(limit * catRatio));
-            // 按 path 分组（提取目录部分）
-            const pathGroups = new Map();
-            for (const s of catSymbols) {
-                const dir = s.path.includes('/')
-                    ? s.path.slice(0, s.path.lastIndexOf('/'))
-                    : '__root__';
-                if (!pathGroups.has(dir)) {
-                    pathGroups.set(dir, []);
-                }
-                pathGroups.get(dir).push(s);
-            }
-            const pathCount = pathGroups.size;
-            const perPathSample = Math.max(5, Math.floor(catLimit / pathCount));
-            // 第二层：每个 path 子桶内乱序后采样
-            for (const pathSymbols of pathGroups.values()) {
-                // 原地乱序（Fisher- Y ates）
-                for (let i = pathSymbols.length - 1; i > 0; i--) {
-                    const j = Math.floor(Math.random() * (i + 1));
-                    [pathSymbols[i], pathSymbols[j]] = [
-                        pathSymbols[j],
-                        pathSymbols[i],
-                    ];
-                }
-                const pathSampleCount = Math.min(perPathSample, pathSymbols.length);
-                sampled.push(...pathSymbols.slice(0, pathSampleCount));
-                if (sampled.length >= limit)
-                    break;
-            }
-            if (sampled.length >= limit)
-                break;
-        }
-        return sampled.slice(0, limit);
-    }
     async getByName(name) {
         if (!this.pool) {
             return (inMemorySymbols.find((s) => s.name.toLowerCase() === name.toLowerCase()) ?? null);
         }
-        const [rows] = await this.pool.query(`
-      SELECT id, name, type, category, path, description, content, CAST(meta AS CHAR) AS meta, usage_count, created_at
-      FROM ${env.mysqlSymbolsTable}
-      WHERE name = ?
+        const { rows } = await this.pool.query(`
+      SELECT id, name, type, category, path, description, content, meta::text AS meta, usage_count, created_at
+      FROM ${env.symbolsTable}
+      WHERE name = $1
       LIMIT 1
       `, [name]);
         if (rows.length === 0) {
@@ -254,8 +187,8 @@ export class SymbolRepository {
             }
             return false;
         }
-        const [result] = await this.pool.query(`UPDATE ${env.mysqlSymbolsTable} SET usage_count = usage_count + 1 WHERE id = ?`, [symbolId]);
-        return result.affectedRows > 0;
+        const result = await this.pool.query(`UPDATE ${env.symbolsTable} SET usage_count = usage_count + 1 WHERE id = $1`, [symbolId]);
+        return result.rowCount !== null && result.rowCount > 0;
     }
     async searchByStructure(fields, opts) {
         const normalized = fields.map((f) => f.trim()).filter(Boolean);
@@ -286,21 +219,21 @@ export class SymbolRepository {
         }
         const params = [];
         let sql = `
-      SELECT id, name, type, category, path, description, content, CAST(meta AS CHAR) AS meta, usage_count, created_at
-      FROM ${env.mysqlSymbolsTable}
+      SELECT id, name, type, category, path, description, content, meta::text AS meta, usage_count, created_at
+      FROM ${env.symbolsTable}
       WHERE 1 = 1
     `;
         if (type) {
-            sql += ' AND type = ?';
             params.push(type);
+            sql += ` AND type = $${params.length}`;
         }
         if (category) {
-            sql += ' AND category LIKE ?';
             params.push(`%${category}%`);
+            sql += ` AND category ILIKE $${params.length}`;
         }
-        sql += ' ORDER BY usage_count DESC LIMIT ?';
         params.push(Math.max(limit * 5, 50));
-        const [rows] = await this.pool.query(sql, params);
+        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)

package/dist/services/embeddingQueue.js

@@ -1,13 +1,16 @@
 /**
  * BullMQ embedding 队列 producer。
  *
- * 设计要点：
- * - jobId = semanticHash → 相同语义模板自动去重，N 个符号相同 hash 只入队一次
- * - CI 流程只负责 enqueue，worker 异步消费，CI 不阻塞
- * - 调用方在进程退出前需调用 closeEmbeddingQueue() 释放连接
+ * 去重策略：
+ * - 同一 CI run 内：ci-index.ts 用 new Set(hashes) 去重后再入队，Redis 层无需 jobId 去重
+ * - 跨 CI run 的向量缓存：由 worker 查询 DB（status=online AND semantic_hash=?）决定是否调 API
+ * - 不使用 jobId，避免 BullMQ completed 状态残留导致后续 run 任务被跳过
+ *
+ * CI 流程只负责 enqueue，worker 异步消费，CI 不阻塞。
+ * 调用方在进程退出前需调用 closeEmbeddingQueue() 释放连接。
  */
 import { Queue } from 'bullmq';
-import Redis from 'ioredis';
+import { Redis } from 'ioredis';
 import { env } from '../config/env.js';
 let _queue = null;
 let _connection = null;
@@ -21,31 +24,29 @@ function getQueue() {
     }
     return _queue;
 }
-/**
- * 将一个 semanticHash 对应的 embedding 任务入队。
- * 若队列中已存在相同 jobId（semanticHash）的待处理任务，BullMQ 自动忽略重复请求。
- */
-export async function enqueueEmbedding(semanticHash) {
-    await getQueue().add('embed', { semanticHash }, {
-        jobId: semanticHash, // 去重键：相同 hash 幂等
+/** 单个 semanticHash 入队 */
+export async function enqueueEmbedding(semanticHash, symbolsTable) {
+    await getQueue().add('embed', { semanticHash, symbolsTable: symbolsTable ?? env.symbolsTable }, {
         attempts: 5,
         backoff: { type: 'exponential', delay: 5_000 },
     });
 }
-/** 批量入队，适合全量扫描场景 */
-export async function enqueueEmbeddingBatch(semanticHashes) {
+/**
+ * 批量入队（同一 CI run 内已由调用方 new Set 去重）。
+ * worker 消费时查 DB 决定是否真正调 embedding API。
+ */
+export async function enqueueEmbeddingBatch(semanticHashes, symbolsTable) {
+    const table = symbolsTable ?? env.symbolsTable;
     const queue = getQueue();
     const jobs = semanticHashes.map((hash) => ({
         name: 'embed',
-        data: { semanticHash: hash },
+        data: { semanticHash: hash, symbolsTable: table },
         opts: {
-            jobId: hash,
             attempts: 5,
             backoff: { type: 'exponential', delay: 5_000 },
         },
     }));
-    // BullMQ addBulk 会跳过已存在 jobId 的任务
-    await queue.addBulkJobs(jobs);
+    await queue.addBulk(jobs);
 }
 /** 进程退出前关闭连接（CI 脚本必须调用，否则进程挂起） */
 export async function closeEmbeddingQueue() {

package/dist/services/reindex.js

@@ -1,64 +1,108 @@
-import { resolve } from 'node:path';
-import { loadProjectDotenv } from '../config/env.js';
-import { getMySqlPool } from '../db/mysql.js';
-import { indexedRowToEmbedText } from '../indexer/embedText.js';
-import { indexProject } from '../indexer/indexProject.js';
+import { resolve, join } from 'node:path';
+import { readFileSync } from 'node:fs';
+import fg from 'fast-glob';
+import { env } from '../config/env.js';
+import { getPool } from '../db/postgres.js';
+import { getAllTableSQLs } from '../db/schema.js';
+import { indexProject, DEFAULT_IGNORE } from '../indexer/indexProject.js';
 import { upsertSymbols } from '../indexer/persistSymbols.js';
-import { initCategoryEmbeddings, resolveCategory, } from '../indexer/categoryClassifier.js';
-import { createEmbeddingClient, embedAll, } from '../services/embeddingClient.js';
+import { computeFileHash } from '../indexer/tsAstNormalizer.js';
+import { getRelativePathForDisplay } from '../indexer/heuristics.js';
+import { enqueueEmbeddingBatch, closeEmbeddingQueue, } from '../services/embeddingQueue.js';
+import { SYMBOL_STATUS } from '../config/symbolStatus.js';
 export async function runReindex(options = {}) {
     const projectRoot = resolve(options.projectRoot ?? process.cwd());
-    const { dryRun = false } = options;
-    // 1️ 加载第三方 .env：只覆盖未定义的变量 → 保留 MCP Server 自身配置
-    loadProjectDotenv(projectRoot);
-    // 2️ 打印生效的环境变量（便于调试）
-    console.error(`[reindex] projectRoot=${projectRoot}, dryRun=${dryRun}, ` +
-        `MYSQL_HOST=${process.env.MYSQL_HOST}`);
-    // 3️⃣ 只有需要写入数据库时才检查 MySQL 并建立连接
-    const embeddingServiceUrl = process.env.EMBEDDING_SERVICE_URL;
-    if (!dryRun && embeddingServiceUrl) {
-        // 初始化 category embeddings
-        await initCategoryEmbeddings();
-    }
+    const { dryRun = false, forceRebuild = false } = options;
+    console.error(`[reindex] projectRoot=${projectRoot}, dryRun=${dryRun}, forceRebuild=${forceRebuild}, PG_URL=${process.env.PG_URL ? '(set)' : '(not set)'}, SYMBOLS_TABLE=${env.symbolsTable}`);
     let pool = null;
     if (!dryRun) {
-        pool = getMySqlPool();
-        await pool.query('SELECT 1'); // 测试连接
-        console.error('[reindex] MySQL connection successful');
+        pool = getPool();
+        await pool.query('SELECT 1');
+        console.error('[reindex] PostgreSQL connection successful');
+        // 确保 extension + table + indexes 存在（幂等，多租户表名安全）
+        for (const sql of getAllTableSQLs()) {
+            await pool.query(sql);
+        }
+        console.error(`[reindex] schema ready: ${env.symbolsTable}`);
+    }
+    // ─── 1. glob 解析出全量文件列表（绝对路径）──────────────────────────
+    const ignore = [...DEFAULT_IGNORE, ...(options.ignore ?? [])];
+    const patterns = (options.globPatterns ?? ['src/**/*.{ts,tsx}']).map((p) => p.startsWith('/') ? p : join(projectRoot, p).replace(/\\/g, '/'));
+    const allFiles = await fg(patterns, {
+        absolute: true,
+        ignore,
+        onlyFiles: true,
+        dot: false,
+    });
+    console.error(`[reindex] glob found ${allFiles.length} file(s)`);
+    // ─── 2. file_hash 过滤：跳过 AST 未变的文件（CPU 优化）────────────────
+    // forceRebuild 时跳过此过滤，file_hash 不可复用（模板/模型变更时相同文件产出不同 content）
+    let filesToIndex = allFiles;
+    let skippedFiles = 0;
+    if (!forceRebuild && pool && allFiles.length > 0) {
+        // 计算所有文件当前 hash
+        const currentFileHashes = new Map(); // relPath → hash
+        for (const absPath of allFiles) {
+            const content = readFileSync(absPath, 'utf-8');
+            const relPath = getRelativePathForDisplay(projectRoot, absPath);
+            currentFileHashes.set(relPath, computeFileHash(content));
+        }
+        // 一次性批量查 DB 已有的 file_hash
+        const relPaths = [...currentFileHashes.keys()];
+        const { rows: dbRows } = await pool.query(`SELECT DISTINCT path, file_hash FROM ${env.symbolsTable}
+             WHERE path = ANY($1) AND file_hash IS NOT NULL`, [relPaths]);
+        const dbFileHash = new Map(dbRows.map((r) => [r.path, r.file_hash]));
+        filesToIndex = allFiles.filter((absPath) => {
+            const relPath = getRelativePathForDisplay(projectRoot, absPath);
+            return currentFileHashes.get(relPath) !== dbFileHash.get(relPath);
+        });
+        skippedFiles = allFiles.length - filesToIndex.length;
+        console.error(`[reindex] file_hash: ${skippedFiles} unchanged (skipped), ${filesToIndex.length} changed (to parse)`);
     }
-    let rows = await indexProject({
+    else if (forceRebuild) {
+        console.error(`[reindex] forceRebuild=true, skipping file_hash filter — parsing all ${allFiles.length} file(s)`);
+    }
+    if (filesToIndex.length === 0) {
+        console.error('[reindex] all files unchanged, nothing to do');
+        return {
+            projectRoot,
+            extractedCount: 0,
+            skippedFiles,
+            enqueuedCount: 0,
+            upserted: false,
+        };
+    }
+    // ─── 3. 只对变更文件做 AST 解析 ──────────────────────────────────
+    const rows = await indexProject({
         projectRoot,
-        globPatterns: options.globPatterns,
-        ignore: options.ignore,
+        globPatterns: filesToIndex,
     });
-    console.error(`[reindex] extracted ${rows.length} symbol(s) from ${projectRoot}`);
-    let embeddingsComputed = false;
-    let embeddingPayload;
-    if (!options.dryRun && rows.length > 0 && embeddingServiceUrl) {
-        try {
-            const client = createEmbeddingClient(embeddingServiceUrl);
-            // 先实现ts语义模板,js保留原逻辑
-            const texts = rows.map((row) => row.semantic_hash ?? indexedRowToEmbedText(row));
-            const vecs = await embedAll(client, texts);
-            console.error('==vecs', vecs?.length);
-            // 生成category
-            rows = await resolveCategory(rows, vecs);
-            embeddingPayload = vecs;
-            embeddingsComputed = true;
+    console.error(`[reindex] extracted ${rows.length} symbol(s) from ${filesToIndex.length} changed file(s)`);
+    // ─── 4. 写库（全部 pending）→ 入队，worker 异步处理 embedding + category ──
+    const nullPayload = rows.map(() => null);
+    const pendingHashes = [
+        ...new Set(rows.map((r) => r.semantic_hash).filter(Boolean)),
+    ];
+    if (!dryRun) {
+        // forceRebuild：先清空 DB 中已有的 embedding，使 worker cache check 必然 miss
+        if (forceRebuild && pendingHashes.length > 0) {
+            await pool.query(`UPDATE ${env.symbolsTable}
+                 SET embedding = NULL, status = $1
+                 WHERE semantic_hash = ANY($2)`, [SYMBOL_STATUS.PENDING, pendingHashes]);
+            console.error(`[reindex] forceRebuild: cleared embeddings for ${pendingHashes.length} semantic_hash(es)`);
         }
-        catch (err) {
-            console.error('[reindex] embedding skipped (service error):', err);
-            embeddingPayload = rows.map(() => null);
+        await upsertSymbols(pool, rows, nullPayload);
+        if (pendingHashes.length > 0) {
+            await enqueueEmbeddingBatch(pendingHashes, env.symbolsTable);
+            console.error(`[reindex] enqueued ${pendingHashes.length} semantic_hash(es) → worker will handle embedding asynchronously`);
         }
+        await closeEmbeddingQueue();
     }
-    if (!options.dryRun) {
-        await upsertSymbols(pool, rows, embeddingPayload);
-    }
-    console.error('===out', JSON.stringify(rows));
     return {
         projectRoot,
         extractedCount: rows.length,
-        upserted: !options.dryRun,
-        embeddingsComputed,
+        skippedFiles,
+        enqueuedCount: pendingHashes.length,
+        upserted: !dryRun,
     };
 }

package/dist/tools/getSymbolDetail.js

@@ -5,7 +5,9 @@ export const getSymbolDetailInput = z.object({
 export function createGetSymbolDetailTool(repository) {
     return {
         name: 'get_symbol_detail',
-        description: '按名称获取单个代码块的完整详情。',
+        description: '获取单个代码块的完整详情（含源码、参数类型、调用关系、副作用）。\n' +
+            '仅在以下情况调用：search_symbols 返回的摘要信息不足以判断是否适用（如签名模糊、副作用不明确）。\n' +
+            '通常对 top 1-3 候选调用，不要对所有结果批量调用。',
         inputSchema: getSymbolDetailInput.shape,
         handler: async (input) => {
             const symbol = await repository.getByName(input.name);

package/dist/tools/incUsage.js

@@ -6,7 +6,9 @@ export const incUsageInput = z.object({
 export function createIncUsageTool(repository) {
     return {
         name: 'inc_usage',
-        description: '当开发者采纳了某个推荐代码块时，调用此工具记录。usage_count 会 +1，用于后续排序优化。',
+        description: '在用户明确确认"采纳推荐"后调用，记录复用行为用于排序优化（usage_count +1）。\n' +
+            '注意：仅在用户主动确认采纳时调用，不要在推荐后自动调用。\n' +
+            'symbolId 从 search_symbols 或 search_by_structure 返回结果的 id 字段获取。',
         inputSchema: incUsageInput.shape,
         handler: async (input) => {
             const success = await repository.incUsage(input.symbolId);
@@ -15,7 +17,10 @@ export function createIncUsageTool(repository) {
                     content: [
                         {
                             type: 'text',
-                            text: JSON.stringify({ error: '未找到该代码块', symbolId: input.symbolId }, null, 2),
+                            text: JSON.stringify({
+                                error: '未找到该代码块',
+                                symbolId: input.symbolId,
+                            }, null, 2),
                         },
                     ],
                 };
@@ -24,7 +29,11 @@ export function createIncUsageTool(repository) {
                 content: [
                     {
                         type: 'text',
-                        text: JSON.stringify({ ok: true, symbolId: input.symbolId, message: 'usage_count 已 +1' }, null, 2),
+                        text: JSON.stringify({
+                            ok: true,
+                            symbolId: input.symbolId,
+                            message: 'usage_count 已 +1',
+                        }, null, 2),
                     },
                 ],
             };

package/dist/tools/reindex.js

@@ -9,7 +9,9 @@ export const reindexInput = z.object({
 export function createReindexTool() {
     return {
         name: 'reindex',
-        description: '重建源码代码块索引并写入 MySQL；设置 dryRun=true 时仅预览抽取数量，不落库、不调用嵌入服务。若配置 EMBEDDING_SERVICE_URL，非 dryRun 时会写入向量列。',
+        description: '⚠️ 高成本操作（耗时可能超过数分钟），仅在用户明确要求"重建索引"时调用，不要因搜索结果不佳而自动调用。\n' +
+            '重建源码代码块索引并写入 MySQL。设置 dryRun=true 时仅预览抽取数量，不落库。\n' +
+            '写入后 embedding 由后台 worker 异步处理，队列清空后打印完成信号。',
         inputSchema: reindexInput.shape,
         handler: async (input) => {
             const startedAt = Date.now();

package/dist/tools/searchByStructure.js

@@ -13,7 +13,9 @@ export const searchByStructureInput = z.object({
 export function createSearchByStructureTool(repository) {
     return {
         name: 'search_by_structure',
-        description: '通过结构化字段（如 props/params/properties/hooks）搜索代码块，适用于 API 形态的查询。',
+        description: '按代码块的结构字段（props/params/hooks）检索，适合已知接口形态时使用。\n' +
+            '示例：需要一个接受 value、onChange、error 三个 prop 的输入组件 → fields: ["value", "onChange", "error"], type: "component"\n' +
+            '与 search_symbols 配合：先语义检索候选，再用本工具做 API 结构过滤以精确匹配。',
         inputSchema: searchByStructureInput.shape,
         handler: async (input) => {
             const rows = await repository.searchByStructure(input.fields, {

package/dist/tools/searchSymbols.js

@@ -10,12 +10,16 @@ export const searchSymbolsInput = z.object({
     semantic: z.boolean().optional().default(false),
     limit: z.number().int().min(1).max(100).optional().default(20),
 });
-const THREADHOLD_SIMILARITY_FOR_FINAL = 0.6;
+const SCORE_THRESHOLD_FOR_FINAL = 0.45; // 综合排序分阈值（语义相似度占50%权重，原始0.5相似度 ≈ 综合0.35起）
 const TOP_K_FOR_FINAL_RESULTS = 20; // 结果上限,返回相似度高的，保证数据质量
 export function createSearchSymbolsTool(repository) {
     return {
         name: 'search_symbols',
-        description: '通过关键词和可选的类型搜索代码块。设置 semantic=true 可进行自然语言/意图式搜索（此功能需要 embedding 服务 + 已索引的向量）。',
+        description: '搜索项目中已有的可复用代码块（函数、组件、Hook、类型等）。在生成新代码之前必须先调用本工具，确认是否已有实现。\n' +
+            '- 有明确名称时（如 "useDebounce"）：semantic=false（默认），直接关键词检索\n' +
+            '- 描述功能意图时（如 "防抖"、"处理表单提交"）：semantic=true，进行语义检索（需 embedding 服务已就绪）\n' +
+            '- 不确定 type 时省略该参数，不要猜测\n' +
+            '- 返回结果含 semanticSimilarity 字段：>0.85 高置信度可直接推荐，0.6-0.85 需结合 description 判断，<0.6 说明可能无合适实现',
         inputSchema: searchSymbolsInput.shape,
         handler: async (input) => {
             if (input.semantic) {
@@ -38,8 +42,7 @@ export function createSearchSymbolsTool(repository) {
                         reasonDetail: item.reason,
                         semanticSimilarity: Number((simById.get(item.symbol.id) ?? 0).toFixed(4)),
                     }))
-                        .filter((x) => x.semanticSimilarity >=
-                        THREADHOLD_SIMILARITY_FOR_FINAL) // 阈值过滤，去掉明显不相关的结果
+                        .filter((x) => x.score >= SCORE_THRESHOLD_FOR_FINAL) // 基于综合排序分过滤，保留 usage/recency 高的结果
                         .slice(0, TOP_K_FOR_FINAL_RESULTS)
                     : hits.map((h) => ({
                         id: h.symbol.id,
@@ -73,7 +76,7 @@ export function createSearchSymbolsTool(repository) {
                     reason: item.reason.summary,
                     reasonDetail: item.reason,
                 }))
-                    .filter((x) => x.score >= THREADHOLD_SIMILARITY_FOR_FINAL) // 阈值过滤，去掉明显不相关的结果
+                    .filter((x) => x.score >= SCORE_THRESHOLD_FOR_FINAL) // 基于综合排序分过滤
                     .slice(0, TOP_K_FOR_FINAL_RESULTS)
                 : rows.map((r) => ({
                     id: r.id,