@lorrylurui/code-intelligence-mcp 1.0.7 → 1.0.9

package/README.md

@@ -156,11 +156,11 @@ npm run index
 
 可选环境变量（见 `.env.example`）：
 
-| 变量           | 含义                                             |
-| -------------- | ------------------------------------------------ |
-| `INDEX_ROOT`   | 工程根目录，默认当前工作目录                     |
-| `INDEX_GLOB`   | 空格分隔 glob，默认 `src/**/*.{ts,tsx}`         |
-| `INDEX_IGNORE` | 额外忽略的 glob 片段（空格分隔）                 |
+| 变量           | 含义                                    |
+| -------------- | --------------------------------------- |
+| `INDEX_ROOT`   | 工程根目录，默认当前工作目录            |
+| `INDEX_GLOB`   | 空格分隔 glob，默认 `src/**/*.{ts,tsx}` |
+| `INDEX_IGNORE` | 额外忽略的 glob 片段（空格分隔）        |
 
 **分类规则（首版启发式）**：`interface` / `type` → `type`；`.tsx` 且函数体含 JSX → `component`；路径或导出名含 `selector` → `selector`；其余导出函数 → `util`；`class` → `util`（可后续细化）。
 
@@ -293,3 +293,322 @@ Run with:
 - recommend-component
 - reusable-code-advisor
 ````
+
+---
+
+Code Intelligence 功能完整总结
+
+项目定位
+
+智能代码推荐系统：解决日常团队开发中可复用逻辑（组件、样式、selectors、类型声明等）重复开发问题，提高代码复
+用率。
+
+一、系统架构
+
+┌─────────────────────────────────────────────────────────────────┐  
+│ MCP Client (Claude/Cursor) │  
+│ 用户提问 → 模型分析 → 返回结果 │
+└─────────────────────────────────────────────────────────────────┘  
+ │  
+ ▼  
+┌─────────────────────────────────────────────────────────────────┐  
+│ MCP Server (Node.js) │  
+├─────────────────────────────────────────────────────────────────┤  
+│ Tools (4个) │ Prompts (1个) │ DB Layer │  
+│ - search_symbols │ - reusable-code- │ - MySQL │  
+│ - get_symbol_detail │ advisor │ - embedding │  
+│ - search_by_struct │ │ │  
+│ - reindex │ │ │  
+└─────────────────────────────────────────────────────────────────┘  
+ │  
+ ▼  
+┌─────────────────────────────────────────────────────────────────┐  
+│ Indexer (源码解析) │  
+│ ts-ormorph (TS/TSX) + Babel (JS/JSX) │  
+└─────────────────────────────────────────────────────────────────┘  
+ │  
+ ▼  
+┌─────────────────────────────────────────────────────────────────┐  
+│ Embedding Service (Python FastAPI) │  
+│ 向量化 + 语义检索 │  
+└─────────────────────────────────────────────────────────────────┘
+
+二、MCP Server Tools（4个）
+
+1. search_symbols 通用检索
+
+功能：根据 query 和 type 进行语义搜索，对结果进行权重排序
+
+入参：  
+{  
+ query: string, // 搜索关键词  
+ type?: 'component' | 'util' | 'selector' | 'type', // 可选  
+ semantic?: boolean, // 是否启用语义搜索（需 embedding 服务）
+ranked?: boolean, // 是否排序，默认 true  
+ limit?: number, // 返回数量，默认 20  
+}
+
+权重排序算法（RANK_WEIGHTS）：  
+const RANK_WEIGHTS = {  
+ textMatch: 0.4, // 文本匹配度  
+ usage: 0.3, // 使用频率  
+ recency: 0.15, // 最近更新时间  
+ commonPath: 0.15, // common 路径偏好  
+}
+
+score = textScore _ 0.4 + usage _ 0.3 + recency _ 0.15 + commonPath _ 0.15
+
+难点：
+
+- 多维度权重调优
+- 文本匹配算法（模糊匹配 + 语义匹配）
+- 冷启动时无 embedding 向量fallback 到文本匹配
+
+---
+
+2. get_symbol_detail 获取详情
+
+功能：根据 name 获取代码块的完整信息
+
+入参：  
+ {  
+ name: string, // 代码块名称  
+ }
+
+返回：完整代码块信息包括 meta（props/params/properties/hooks）
+
+难点：需要从 MySQL 解析 JSON 格式的 meta 字段
+
+---
+
+3. search_by_structure 结构化搜索
+
+功能：通过结构化字段搜索代码块，适用于 API 形态查询
+
+入参：  
+ {  
+ fields: string[], // 结构字段，如 ['onChange', 'value']  
+ type?: 'component' | 'util' | 'selector' | 'type',  
+ category?: string, // 业务分类  
+ limit?: number,  
+ }
+
+匹配逻辑：匹配 symbol.meta 中的：
+
+- props - 组件 props
+- params - 函数参数
+- properties - 对象属性
+- hooks - React hooks
+
+难点：
+
+- 不支持 LLM 向量检索，需全表扫描 + 内存过滤
+- 需要在 MySQL 中存储 JSON 格式的 meta
+
+---
+
+4. reindex 重建索引
+
+功能：扫描源码目录，解析并写入 MySQL + 向量
+
+入参：  
+ {  
+ projectRoot?: string, // 项目根目录，默认 cwd  
+ globPatterns?: string[], // glob 模式，默认 ['**/*.{ts,tsx}']  
+ ignore?: string[], // 忽略目录  
+ dryRun?: boolean, // 仅预览不写入  
+ }
+
+处理流程：
+
+1. 收集文件（fast-glob）  
+   ↓
+2. 分离 TS/TSX 和 JS/JSX  
+   ↓
+3. TS/TSX：ts-ormorph 解析  
+   JS/JSX：Babel 解析  
+   ↓
+4. 提取 meta（props/params/properties/hooks）  
+   ↓
+5. 写入 MySQL  
+   ↓
+6. 写入 embedding 向量（可选）
+
+难点：
+
+- ts-ormorph：需要 tsconfig.json，不存在时用默认配置
+- Babel 解析：支持 JSX、TypeScript、装饰器等语法
+- meta 提取：
+    - extractFunctionMeta：提取函数参数、返回值类型
+    - extractHooksFromBody：提取 useState/useEffect 等
+    - extractInterfaceOrTypeMeta：提取接口属性
+- 路径推断 category：从路径智能推断业务分类（如 src/components/form/\* → form）
+- 忽略规则：node_modules、dist、build、.git、coverage、.next、.nuxt、.venv 等
+
+---
+
+三、MCP Prompt（1个）
+
+reusable-code-advisor 多工具编排
+
+功能：在实现需求时检索并推荐最合适的可复用代码
+
+工作流：
+
+1. 调用 search_symbols 检索候选，type 根据用户需求传（component/util/selector/type）
+2. 如果用户指定了结构过滤条件（props/params/properties/hooks），额外调用 search_by_structure 做结构匹配
+3. 先 search_symbols(limit=20) 拉候选，再对 Top 3 调用 get_symbol_detail 做深度判断
+4. 若仅凭签名/摘要无法判断，调用 get_symbol_detail 获取详情
+5. 从以下维度对比候选：
+    - 功能匹配度
+    - API 是否简单、入参是否合适
+    - 依赖与副作用风险
+    - 复用安全性（稳定性、耦合度、是否便于扩展）
+6. 给出唯一首选推荐，并说明理由
+
+返回格式：
+
+- 首选：<代码块名>
+- 理由：1～3 条要点
+- 其他候选：简要列出及取舍
+- 用法提示：结合用户场景的最小集成说明
+
+难点：多工具组合调用逻辑、意图判断
+
+---
+
+四、GitHub Actions（CI/CD 检测评论）
+
+1. duplicate-check 工作流
+
+功能：检测代码重复实现，在 PR/Commit 上自动评论
+
+触发条件：
+
+- push 到 main 分支
+- PR opened/synchronize/reopened
+
+工作流：
+
+1. 计算变更文件列表（git diff）
+2. 运行 detect-duplicates 脚本
+3. 生成报告（JSON + Markdown）
+4. 上传 artifact
+5. 评论到 PR 或 Commit
+
+评论逻辑：
+
+- PR 事件：直接评论到 PR
+- Push 事件：查找关联 PR 并评论，无关联则评论到 Commit
+
+发布为 GitHub Action：
+
+- 仓库：lorrylurui/code-intelligence-check
+- 第三方使用：
+- uses: lorrylurui/code-intelligence-check@v1  
+  with:  
+   is-mock-mode: 'true' # 无需 MySQL
+
+---
+
+五、Embedding Service（Python FastAPI）
+
+功能
+
+- 文本向量化：将查询和代码块转为向量（384维 MiniLM）
+- 语义检索：余弦相似度计算
+
+API
+
+POST /embed  
+ Body: { "texts": ["查询文本"] }  
+ Response: { "embeddings": [[0.1, 0.2, ...]] }
+
+GET /health
+
+---
+
+六、数据库设计
+
+symbols 表
+
+CREATE TABLE symbols (  
+ id INT AUTO_INCREMENT PRIMARY KEY,  
+ name VARCHAR(255) NOT NULL COMMENT '代码块名称',  
+ type ENUM('component', 'util', 'selector', 'type') NOT NULL COMMENT '类型',
+category VARCHAR(100) COMMENT '业务分类',  
+ path VARCHAR(500) NOT NULL COMMENT '文件路径',  
+ description TEXT COMMENT '描述/文档',  
+ content LONGTEXT COMMENT '完整代码内容',  
+ meta JSON COMMENT '结构化元信息：props/params/properties/hooks',  
+ usage_count INT DEFAULT 0 COMMENT '使用频率',  
+ embedding JSON NULL COMMENT '向量',  
+ created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,  
+ INDEX idx_type (type),  
+ INDEX idx_category (category),  
+ INDEX idx_usage (usage_count DESC)  
+ );
+
+---
+
+七、环境配置
+
+环境变量
+
+┌───────────────────────┬──────────────┬───────────────────┐  
+ │ 变量 │ 说明 │ 默认值 │
+├───────────────────────┼──────────────┼───────────────────┤  
+ │ MYSQL_ENABLED │ 启用 MySQL │ false │  
+ ├───────────────────────┼──────────────┼───────────────────┤  
+ │ MYSQL_HOST │ MySQL 主机 │ - │  
+ ├───────────────────────┼──────────────┼───────────────────┤  
+ │ MYSQL_PORT │ MySQL 端口 │ 3306 │
+├───────────────────────┼──────────────┼───────────────────┤  
+ │ MYSQL_USER │ MySQL 用户 │ - │  
+ ├───────────────────────┼──────────────┼───────────────────┤  
+ │ MYSQL_PASSWORD │ MySQL 密码 │ - │  
+ ├───────────────────────┼──────────────┼───────────────────┤  
+ │ MYSQL_DATABASE │ 数据库名 │ code_intelligence │  
+ ├───────────────────────┼──────────────┼───────────────────┤  
+ │ MYSQL_SYMBOLS_TABLE │ 表名 │ symbols │  
+ ├───────────────────────┼──────────────┼───────────────────┤  
+ │ EMBEDDING_SERVICE_URL │ 向量服务 URL │ - │  
+ └───────────────────────┴──────────────┴───────────────────┘
+
+环境变量加载逻辑
+
+1. 加载本地 .env
+2. 加载第三方 .env（按变量维度覆盖，只覆盖第三方明确配置的变量）
+3. 命令行参数 --KEY=VALUE 优先级最高
+
+---
+
+八、技术难点总结
+
+┌────────────┬───────────────────────────────────────────────────┐  
+ │ 模块 │ 难点 │  
+ ├────────────┼───────────────────────────────────────────────────┤  
+ │ 权重排序 │ textMatch/usage/recency/commonPath 四维权重调优 │
+├────────────┼───────────────────────────────────────────────────┤  
+ │ TS 解析 │ ts-ormorph 需要 tsconfig.json，不存在时用默认配置 │  
+ ├────────────┼───────────────────────────────────────────────────┤  
+ │ JS 解析 │ Babel 支持 JSX/TS/装饰器等复杂语法 │  
+ ├────────────┼───────────────────────────────────────────────────┤  
+ │ Meta 提取 │ 函数/接口/类/hooks 的参数、返回值、类型解析 │  
+ ├────────────┼───────────────────────────────────────────────────┤  
+ │ 路径推断 │ 从文件路径智能推断业务分类（category） │  
+ ├────────────┼───────────────────────────────────────────────────┤
+│ 结构搜索 │ meta 存储为 JSON，全表扫描 + 内存过滤 │  
+ ├────────────┼───────────────────────────────────────────────────┤
+│ 向量检索 │ 向量生成、存储、余弦相似度计算 │  
+ ├────────────┼───────────────────────────────────────────────────┤
+│ 多工具编排 │ Prompt 中多 Tool 组合调用逻辑 │  
+ ├────────────┼───────────────────────────────────────────────────┤
+│ 环境加载 │ 本地/第三方 .env 按变量维度合并 │  
+ ├────────────┼───────────────────────────────────────────────────┤
+│ CI 评论 │ PR/Commit 评论逻辑、关联 PR 查找 │  
+ └────────────┴───────────────────────────────────────────────────┘
+
+---
+
+这就是完整详细的功能总结。如需补充其他细节请告诉我。

package/dist/indexer/extractMeta.js

@@ -1,7 +1,7 @@
 /**
  * 从 AST 抽取写入 `symbols.meta` 的结构化字段（props/params、hooks、返回值、类型成员等）。
  */
-import { Node, } from 'ts-morph';
+import { Node, SyntaxKind, } from 'ts-morph';
 /**
  * 将节点收窄为可调用的函数形态，便于统一抽取参数与函数体。
  * @returns 若不是函数声明/表达式/箭头函数则为 `undefined`。
@@ -77,7 +77,7 @@ export function extractReturnTypeText(fn) {
     return rt ? rt.getText() : null;
 }
 /**
- * 汇总单个可调用代码块的元数据：`params`、可选 `hooks`、可选 `returnType`。
+ * 汇总单个可调用代码块的元数据：`params`、可选 `hooks`、可选 `returnType`、可选 `sideEffects`。
  * @returns 扁平对象，由上层按 `component`/`util` 再映射为 `props` 或保留 `params`。
  */
 export function extractFunctionMeta(fn) {
@@ -85,11 +85,13 @@ export function extractFunctionMeta(fn) {
     const paramTypeFields = extractParamTypeFieldNames(fn);
     const hooks = extractHooksFromBody(fn);
     const returnType = extractReturnTypeText(fn);
+    const sideEffects = extractSideEffects(fn);
     return {
         params,
         ...(paramTypeFields.length ? { paramTypeFields } : {}),
         ...(hooks.length ? { hooks } : {}),
         ...(returnType ? { returnType } : {}),
+        ...(sideEffects.length ? { sideEffects } : {}),
     };
 }
 /**
@@ -116,3 +118,94 @@ export function extractInterfaceOrTypeMeta(node) {
     }
     return { kind: 'unknown' };
 }
+/**
+ * 静态分析函数体的副作用。
+ * @returns 副作用类型数组，去重排序后写入 `meta.sideEffects`。
+ */
+export function extractSideEffects(node) {
+    const effects = new Set();
+    // 1. 检测网络请求
+    node.forEachDescendant((n) => {
+        if (Node.isCallExpression(n)) {
+            const expr = n.getExpression();
+            const text = expr.getText().toLowerCase();
+            // fetch、axios、xhr、ajax、superagent 等
+            if (text === 'fetch' ||
+                text === 'axios' ||
+                text === 'xhr' ||
+                text === 'ajax' ||
+                text.startsWith('axios.') ||
+                text.includes('request')) {
+                effects.add('network');
+            }
+            // XMLHttpRequest
+            if (text.includes('xmlhttprequest')) {
+                effects.add('network');
+            }
+        }
+    });
+    // 2. 检测计时器
+    node.forEachDescendant((n) => {
+        if (Node.isCallExpression(n)) {
+            const text = n.getExpression().getText();
+            if (text === 'setTimeout' ||
+                text === 'setInterval' ||
+                text === 'requestAnimationFrame' ||
+                text === 'setImmediate') {
+                effects.add('timer');
+            }
+        }
+    });
+    // 3. 检测 DOM / 全局对象操作
+    node.forEachDescendant((n) => {
+        if (Node.isExpressionStatement(n)) {
+            const text = n.getText();
+            // document. / window. 开头的赋值或调用
+            if (/\bdocument\.\w+/.test(text) ||
+                /\bwindow\.\w+/.test(text) ||
+                /\bnavigator\.\w+/.test(text) ||
+                /\blocation\.\w+/.test(text)) {
+                // 区分读取和写入
+                if (/=/.test(text) && !text.includes('===') && !text.includes('==')) {
+                    effects.add('dom');
+                }
+            }
+        }
+    });
+    // 4. 检测存储操作
+    node.forEachDescendant((n) => {
+        if (Node.isCallExpression(n)) {
+            const text = n.getExpression().getText();
+            if (text.includes('localStorage') ||
+                text.includes('sessionStorage') ||
+                text.includes('cookie')) {
+                effects.add('storage');
+            }
+        }
+    });
+    // 5. 检测入参修改（检测 mutation pattern）
+    // 如 props.items.push(...), obj.x = ...
+    const params = node.getKind() === SyntaxKind.FunctionDeclaration
+        ? node.getParameters()
+        : node.getKind() === SyntaxKind.ArrowFunction
+            ? node.getParameters()
+            : node.getKind() === SyntaxKind.FunctionExpression
+                ? node.getParameters()
+                : [];
+    if (params.length > 0) {
+        const paramNames = new Set(params.map((p) => p.getName()));
+        node.forEachDescendant((n) => {
+            if (Node.isExpressionStatement(n)) {
+                const text = n.getText();
+                // 检测 param.x = ... 或 param.push/pop/splice 等
+                for (const param of paramNames) {
+                    if (text.includes(`${param}.`) || text.startsWith(`${param} =`)) {
+                        effects.add('mutation');
+                        break;
+                    }
+                }
+            }
+        });
+    }
+    return [...effects].sort();
+}

package/dist/indexer/indexProject.js

@@ -1,5 +1,6 @@
 /**
  * 扫描源码目录，用 ts-morph 解析 TS/TSX，Babel 解析 JS/JSX，生成待写入 MySQL 的代码块行。
+ * 同时分析调用关系，填充 meta.callers / meta.callees。
  */
 import fg from 'fast-glob';
 import { join, resolve } from 'node:path';
@@ -159,6 +160,7 @@ const DEFAULT_IGNORE = [
 ];
 /**
  * 按 glob 收集文件，用 ts-morph 加载并遍历每个文件的导出，生成全部代码块行。
+ * 同时分析调用关系，填充 meta.callers / meta.callees。
  * @returns 数组可交给 `upsertSymbols`；无匹配文件时返回空数组（不写库）。
  */
 export async function indexProject(opts) {
@@ -167,6 +169,7 @@ export async function indexProject(opts) {
     const ignore = [...DEFAULT_IGNORE, ...(opts.ignore ?? [])];
     console.error(`[indexProject] patterns: ${patterns.join(', ')}`);
     const files = await fg(patterns, {
+        // 根据pattern收集文件列表，支持绝对路径和相对路径（相对于projectRoot），并自动排除node_modules、dist等常见目录。
         absolute: true,
         ignore,
         onlyFiles: true,
@@ -180,6 +183,7 @@ export async function indexProject(opts) {
     const tsFiles = files.filter(isTsFile);
     const jsFiles = files.filter(isJsFile);
     const out = [];
+    const symbolMap = new Map(); // name -> { name, path, exports }
     // 处理 TS/TSX 文件（只有 tsconfig.json 存在时才处理）
     const tsConfigPath = join(projectRoot, 'tsconfig.json');
     const hasTsConfig = existsSync(tsConfigPath);
@@ -191,12 +195,19 @@ export async function indexProject(opts) {
         });
         project.addSourceFilesAtPaths(tsFiles);
         for (const sf of project.getSourceFiles()) {
+            const relPath = getRelativePathForDisplay(projectRoot, sf.getFilePath());
             const exported = sf.getExportedDeclarations();
             for (const [exportName, decls] of exported) {
                 for (const decl of decls) {
                     const row = processDeclaration(exportName, decl, sf, projectRoot);
                     if (row) {
                         out.push(row);
+                        // 建立符号映射
+                        const key = `${row.name}|${row.path}`;
+                        if (!symbolMap.has(key)) {
+                            symbolMap.set(key, { name: row.name, path: row.path, exports: new Set() });
+                        }
+                        symbolMap.get(key).exports.add(exportName);
                     }
                 }
             }
@@ -208,10 +219,107 @@ export async function indexProject(opts) {
             const content = readFileSync(file, 'utf-8');
             const rows = parseJsFile(file, content, projectRoot);
             out.push(...rows);
+            // 建立符号映射
+            for (const row of rows) {
+                const key = `${row.name}|${row.path}`;
+                if (!symbolMap.has(key)) {
+                    symbolMap.set(key, { name: row.name, path: row.path, exports: new Set() });
+                }
+                symbolMap.get(key).exports.add(row.name);
+            }
         }
         catch (e) {
             console.error(`[indexProject] Failed to parse ${file}:`, e);
         }
     }
+    // 分析调用关系，填充 meta.callers / meta.callees
+    if (tsFiles.length > 0 && hasTsConfig) {
+        const project = new Project({
+            tsConfigFilePath: tsConfigPath,
+            skipAddingFilesFromTsConfig: true,
+            skipFileDependencyResolution: true,
+        });
+        project.addSourceFilesAtPaths(tsFiles);
+        analyzeRelations(project, symbolMap, projectRoot, out);
+    }
     return out;
 }
+/**
+ * 分析调用关系，填充每个符号的 meta.callers 和 meta.callees
+ */
+function analyzeRelations(project, symbolMap, projectRoot, rows) {
+    // 构造快速查找：exportName -> [ {name, path} ]
+    const exportToSymbol = new Map();
+    for (const [key, value] of symbolMap) {
+        for (const exp of value.exports) {
+            const list = exportToSymbol.get(exp) || [];
+            list.push({ name: value.name, path: value.path });
+            exportToSymbol.set(exp, list);
+        }
+    }
+    // 收集所有 callers 和 callees
+    const callersMap = new Map(); // key = "name|path" -> set of callers
+    const calleesMap = new Map(); // key = "name|path" -> set of callees
+    for (const sf of project.getSourceFiles()) {
+        const filePath = sf.getFilePath();
+        const relPath = getRelativePathForDisplay(projectRoot, filePath);
+        // 获取当前文件导出的符号
+        const exported = sf.getExportedDeclarations();
+        const fileExportNames = new Set();
+        for (const [name, decls] of exported) {
+            fileExportNames.add(name);
+        }
+        // 遍历 AST 查找调用
+        sf.forEachDescendant((node) => {
+            // 1. 函数调用
+            if (Node.isCallExpression(node)) {
+                const expr = node.getExpression();
+                const name = Node.isIdentifier(expr) ? expr.getText() : null;
+                if (name && exportToSymbol.has(name)) {
+                    const targets = exportToSymbol.get(name);
+                    // 当前文件是谁在调用
+                    for (const [expName, decls] of exported) {
+                        for (const decl of decls) {
+                            const callerKey = `${expName}|${relPath}`;
+                            for (const target of targets) {
+                                // callees: 我调用了谁
+                                const calleeSet = calleesMap.get(callerKey) || new Set();
+                                calleeSet.add({ name: target.name, path: target.path });
+                                calleesMap.set(callerKey, calleeSet);
+                                // callers: 谁调用了我
+                                const callerSet = callersMap.get(`${target.name}|${target.path}`) || new Set();
+                                callerSet.add({ name: expName, path: relPath });
+                                callersMap.set(`${target.name}|${target.path}`, callerSet);
+                            }
+                        }
+                    }
+                }
+            }
+            // 2. Import 导入
+            if (Node.isImportDeclaration(node)) {
+                const moduleSpec = node.getModuleSpecifier().getText();
+                // 简单处理：只处理从 ./ 或 ../ 开始的相对导入
+                if (moduleSpec.startsWith("'.") || moduleSpec.startsWith('".')) {
+                    const importPath = moduleSpec.slice(1, -1); // 去掉引号
+                    // 尝试匹配已索引的符号
+                    // 这里简化处理，暂不展开
+                }
+            }
+        });
+    }
+    // 写入 rows 的 meta
+    for (const row of rows) {
+        const key = `${row.name}|${row.path}`;
+        const callers = callersMap.get(key);
+        const callees = calleesMap.get(key);
+        if (callers && callers.size > 0) {
+            row.meta = row.meta || {};
+            row.meta.callers = [...callers].slice(0, 20); // 限制数量
+        }
+        if (callees && callees.size > 0) {
+            row.meta = row.meta || {};
+            row.meta.callees = [...callees].slice(0, 20);
+        }
+    }
+    console.error(`[analyzeRelations] processed ${rows.length} symbols`);
+}

package/dist/prompts/reusableCodeAdvisorPrompt.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-const REUSABLE_CODE_ADVISOR_DESCRIPTION = '在实现需求时检索并推荐最合适的可复用代码代码块（函数/类/模块等）。在用户要求复用现有代码、询问是否已有组件/函数/服务、或要在多个代码块中选最优时使用。';
+const REUSABLE_CODE_ADVISOR_DESCRIPTION = '在实现需求时检索并推荐最合适的可复用代码代码块（组件/函数/类/模块等）。在用户要求复用现有代码、询问是否已有组件/函数/服务、或要在多个代码块中选最优时使用。';
 /** 与 SKILL.md 中 `# 可复用代码推荐` 起至约束、示例说明为止的正文一致（无 YAML frontmatter）。 */
 const REUSABLE_CODE_ADVISOR_MARKDOWN = `# 可复用代码推荐
 
@@ -7,24 +7,26 @@ const REUSABLE_CODE_ADVISOR_MARKDOWN = `# 可复用代码推荐
 
 当用户需要可复用代码或实现类需求时，按顺序执行：
 
-1. 先判断意图：若意图是“组件推荐”（如推荐表单组件、弹窗组件、列表组件等），优先调用 \`recommend_component\`；否则走通用多工具流程。
-2. 通用多工具流程中，先调用 \`search_symbols\` 检索可能满足需求的候选代码块；query 用短英文/关键词（如 formInput），需要限定类型时再加 type（如 component），不要用整句中文。
-3. 执行细则：先 \`search_symbols(limit=20)\` 拉候选，再对 Top 3 调用 \`get_symbol_detail\` 做深度判断。
-4. 若仅凭签名/摘要无法判断，对最相关的若干候选调用 \`get_symbol_detail\` 获取详情。
+1. 调用 search_symbols 检索候选，type 根据用户需求传（component/util/selector/type）
+2. 如果用户指定了结构过滤条件（props/params/properties/hooks），额外调用 search_by_structure 做结构匹配
+3. 先 search_symbols(limit=20) 拉候选，再对 Top 3 调用 get_symbol_detail 做深度判断
+4. 若仅凭签名/摘要无法判断，对最相关的若干候选调用 get_symbol_detail 获取详情
 5. 从以下维度对比候选：
    - 与用户需求的**功能匹配度**
    - **API 是否简单**、入参是否合适
    - **依赖与副作用**风险
    - **复用安全性**（稳定性、耦合度、是否便于扩展）
-6. 给出**唯一首选**推荐，并说明理由。
+6. 给出**唯一首选**推荐，并说明理由
 
 ## 回复结构
 
 按此结构输出（字段名可保留英文或改为中文小标题，二选一全文统一）：
 
-- **首选：** \`<代码块名>\`
+- **首选：** <代码块名>
+- **使用范围：** 展示 meta.callers（被哪些模块调用），用于评估稳定性和适用范围；若无调用记录则显示"新增"
+- **副作用：** 展示 meta.sideEffects（network/timer/dom/storage/mutation），优先推荐无副作用的方案，标注有副作用的方案风险
 - **理由：** 1～3 条要点
-- **其他候选：** 简要列出及取舍
+- **其他候选：** 简要列出及取舍（同步标注副作用）
 - **用法提示：** 结合用户场景的最小集成说明
 
 ## 约束
@@ -33,6 +35,12 @@ 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

@@ -167,6 +167,22 @@ export class SymbolRepository {
         }
         return mapRow(rows[0]);
     }
+    /**
+     * 将指定代码块的 usage_count +1，用于用户采纳推荐后记录。
+     */
+    async incUsage(symbolId) {
+        if (!this.pool) {
+            // 内存模式：找到并 +1
+            const idx = inMemorySymbols.findIndex((s) => s.id === symbolId);
+            if (idx >= 0) {
+                inMemorySymbols[idx].usageCount++;
+                return true;
+            }
+            return false;
+        }
+        const [result] = await this.pool.query(`UPDATE ${env.mysqlSymbolsTable} SET usage_count = usage_count + 1 WHERE id = ?`, [symbolId]);
+        return result.affectedRows > 0;
+    }
     async searchByStructure(fields, opts) {
         const normalized = fields.map((f) => f.trim()).filter(Boolean);
         if (normalized.length === 0)

package/dist/server/createServer.js

@@ -1,12 +1,11 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { registerRecommendComponentPrompt } from "../prompts/recommendComponentPrompt.js";
 import { registerReusableCodeAdvisorPrompt } from "../prompts/reusableCodeAdvisorPrompt.js";
 import { SymbolRepository } from "../repositories/symbolRepository.js";
 import { createSearchSymbolsTool } from "../tools/searchSymbols.js";
 import { createGetSymbolDetailTool } from "../tools/getSymbolDetail.js";
-import { createRecommendComponentTool } from "../tools/recommendComponent.js";
 import { createReindexTool } from "../tools/reindex.js";
 import { createSearchByStructureTool } from "../tools/searchByStructure.js";
+import { createIncUsageTool } from "../tools/incUsage.js";
 export function createServer() {
     const server = new McpServer({
         name: "code-intelligence-mcp",
@@ -19,11 +18,10 @@ export function createServer() {
     server.tool(detailTool.name, detailTool.description, detailTool.inputSchema, detailTool.handler);
     const structureTool = createSearchByStructureTool(repository);
     server.tool(structureTool.name, structureTool.description, structureTool.inputSchema, structureTool.handler);
-    const recommendTool = createRecommendComponentTool(repository);
-    server.tool(recommendTool.name, recommendTool.description, recommendTool.inputSchema, recommendTool.handler);
     const reindexTool = createReindexTool();
     server.tool(reindexTool.name, reindexTool.description, reindexTool.inputSchema, reindexTool.handler);
-    registerRecommendComponentPrompt(server);
+    const incUsageTool = createIncUsageTool(repository);
+    server.tool(incUsageTool.name, incUsageTool.description, incUsageTool.inputSchema, incUsageTool.handler);
     registerReusableCodeAdvisorPrompt(server);
     return server;
 }

package/dist/services/embeddingClient.js

@@ -1,28 +1,27 @@
 export function createEmbeddingClient(baseUrl) {
-    const root = baseUrl.replace(/\/$/, "");
+    const root = baseUrl.replace(/\/$/, '');
     return {
         async embed(texts) {
             if (texts.length === 0)
                 return [];
             const res = await fetch(`${root}/embed`, {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
                 body: JSON.stringify({ texts }),
-                signal: AbortSignal.timeout(180_000)
+                signal: AbortSignal.timeout(180_000),
             });
             if (!res.ok) {
-                const t = await res.text().catch(() => "");
-                throw new Error(`embedding service HTTP ${res.status}${t ? `: ${t.slice(0, 200)}` : ""}`);
+                const t = await res.text().catch(() => '');
+                throw new Error(`embedding service HTTP ${res.status}${t ? `: ${t.slice(0, 200)}` : ''}`);
             }
             const data = (await res.json());
             if (!data.embeddings || !Array.isArray(data.embeddings)) {
-                throw new Error("embedding service returned invalid JSON (missing embeddings)");
+                throw new Error('embedding service returned invalid JSON (missing embeddings)');
             }
             return data.embeddings;
-        }
+        },
     };
 }
-/** Chunked embed to avoid huge request bodies. */
 export async function embedAll(client, texts, chunkSize = 48) {
     const out = [];
     for (let i = 0; i < texts.length; i += chunkSize) {

package/dist/services/vectorMath.js

@@ -1,4 +1,4 @@
-/** Cosine similarity for equal-length numeric vectors. */
+// 计算两个向量的余弦相似度，返回值在 -1 到 1 之间，1 表示完全相似，0 表示不相关，-1 表示完全相反。
 export function cosineSimilarity(a, b) {
     if (a.length === 0 || b.length !== a.length)
         return 0;

package/dist/tools/incUsage.js

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+export const incUsageInput = z.object({
+    /** 要增加使用计数的代码块 ID（从搜索结果中获取） */
+    symbolId: z.number().int().positive(),
+});
+export function createIncUsageTool(repository) {
+    return {
+        name: 'inc_usage',
+        description: '当开发者采纳了某个推荐代码块时，调用此工具记录。usage_count 会 +1，用于后续排序优化。',
+        inputSchema: incUsageInput.shape,
+        handler: async (input) => {
+            const success = await repository.incUsage(input.symbolId);
+            if (!success) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ error: '未找到该代码块', symbolId: input.symbolId }, null, 2),
+                        },
+                    ],
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ ok: true, symbolId: input.symbolId, message: 'usage_count 已 +1' }, null, 2),
+                    },
+                ],
+            };
+        },
+    };
+}

package/dist/tools/recommendComponent.js

@@ -8,7 +8,23 @@ export const recommendComponentInput = z.object({
 export function createRecommendComponentTool(repository) {
     return {
         name: "recommend_component",
-        description: "基于关键词检索 + 可选结构过滤 + 排序 + 详情补全，推荐最合适的可复用组件。",
+        description: `推荐最合适的可复用组件。
+
+工作流（自动完成，无需关心内部细节）：
+1. 关键词检索：根据 query 在 component 类型中搜索候选
+2. 结构过滤：如果传了 props 参数，按结构匹配进一步过滤
+3. 语义排序：对候选进行语义相似度排序
+4. 详情补全：获取 Top 结果的完整代码详情
+5. 返回推荐：输出 Top N 结果及评分、理由
+
+输入参数：
+- query：搜索关键词，如 "form"、"modal"、"table"
+- props（可选）：结构过滤所需的 props，如 ["onChange", "value"]
+- limit（可选）：返回数量，默认 3，最大 20
+
+输出：
+- results 数组，每项包含 name、path、score、reason、detail
+- 如果没有合适结果，会返回最接近的候选并说明差距`,
         inputSchema: recommendComponentInput.shape,
         handler: async (input) => {
             const result = await recommendComponent(input.query, repository, {

package/dist/tools/searchByStructure.js

@@ -1,27 +1,28 @@
 // 按结构字段检索（匹配 meta.props / meta.params / meta.properties / meta.hooks）
-import { z } from "zod";
-import { rankSymbols } from "../services/ranking.js";
+import { z } from 'zod';
+import { rankSymbols } from '../services/ranking.js';
 export const searchByStructureInput = z.object({
     fields: z.array(z.string().min(1)).min(1),
-    type: z.enum(["component", "util", "selector", "type"]).optional(),
+    type: z.enum(['component', 'util', 'selector', 'type']).optional(),
     category: z.string().optional(),
     limit: z.number().int().min(1).max(100).optional().default(20),
-    ranked: z.boolean().optional().default(true)
+    ranked: z.boolean().optional().default(true),
 });
 export function createSearchByStructureTool(repository) {
     return {
-        name: "search_by_structure",
-        description: "Search symbols by structured fields like props/params/properties/hooks. Use for API-shape queries.",
+        name: 'search_by_structure',
+        description: '通过结构化字段（如 props/params/properties/hooks）搜索代码块，适用于 API 形态的查询。',
         inputSchema: searchByStructureInput.shape,
         handler: async (input) => {
             const rows = await repository.searchByStructure(input.fields, {
                 type: input.type,
                 category: input.category,
-                limit: input.limit
+                limit: input.limit,
             });
-            const query = input.fields.join(" ");
+            const query = input.fields.join(' ');
             const resultRows = input.ranked
                 ? rankSymbols(query, rows).map((item) => ({
+                    id: item.symbol.id,
                     name: item.symbol.name,
                     type: item.symbol.type,
                     category: item.symbol.category,
@@ -31,25 +32,26 @@ export function createSearchByStructureTool(repository) {
                     score: item.score,
                     reason: item.reason.summary,
                     reasonDetail: item.reason,
-                    meta: item.symbol.meta
+                    meta: item.symbol.meta,
                 }))
                 : rows.map((r) => ({
+                    id: r.id,
                     name: r.name,
                     type: r.type,
                     category: r.category,
                     path: r.path,
                     description: r.description,
                     usageCount: r.usageCount,
-                    meta: r.meta
+                    meta: r.meta,
                 }));
             return {
                 content: [
                     {
-                        type: "text",
-                        text: JSON.stringify(resultRows, null, 2)
-                    }
-                ]
+                        type: 'text',
+                        text: JSON.stringify(resultRows, null, 2),
+                    },
+                ],
             };
-        }
+        },
     };
 }

package/dist/tools/searchSymbols.js

@@ -22,6 +22,7 @@ export function createSearchSymbolsTool(repository) {
                 const simById = new Map(hits.map((h) => [h.symbol.id, h.similarity]));
                 const resultRows = input.ranked
                     ? rankSemanticHits(hits).map((item) => ({
+                        id: item.symbol.id,
                         name: item.symbol.name,
                         type: item.symbol.type,
                         path: item.symbol.path,
@@ -33,6 +34,7 @@ export function createSearchSymbolsTool(repository) {
                         semanticSimilarity: Number((simById.get(item.symbol.id) ?? 0).toFixed(4)),
                     }))
                     : hits.map((h) => ({
+                        id: h.symbol.id,
                         name: h.symbol.name,
                         type: h.symbol.type,
                         path: h.symbol.path,
@@ -52,6 +54,7 @@ export function createSearchSymbolsTool(repository) {
             const rows = await repository.search(input.query, input.type);
             const resultRows = input.ranked
                 ? rankSymbols(input.query, rows).map((item) => ({
+                    id: item.symbol.id,
                     name: item.symbol.name,
                     type: item.symbol.type,
                     path: item.symbol.path,
@@ -62,6 +65,7 @@ export function createSearchSymbolsTool(repository) {
                     reasonDetail: item.reason,
                 }))
                 : rows.map((r) => ({
+                    id: r.id,
                     name: r.name,
                     type: r.type,
                     path: r.path,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lorrylurui/code-intelligence-mcp",
-    "version": "1.0.7",
+    "version": "1.0.9",
     "private": false,
     "description": "MCP server 提供仓库内可复用代码块（ts/tsx/js/jsx/css/less）的索引和查询能力，支持基于代码上下文的智能推荐。",
     "type": "module",