@lorrylurui/code-intelligence-mcp 2.0.2 → 2.0.3

package/README.md

@@ -4,6 +4,7 @@
 - Tool: `search_symbols`
 - Tool: `get_symbol_detail`
 - Tool: `search_by_structure`
+- Tool: `recommend_component`
 - Tool: `reindex`
 - Tool: `incUsage`
 - Prompt: `reusable-code-advisor`

package/dist/indexer/babelParser.js

@@ -4,8 +4,61 @@
 import * as babelParser from '@babel/parser';
 import * as bt from '@babel/types';
 import { getRelativePathForDisplay, inferCategoryFromPath, inferCategoryFromName, } from './heuristics.js';
+import { makeParamPlaceholder } from './paramPlaceholder.js';
 import { computeFileHash } from './tsAstNormalizer.js';
 import { computeSemanticHashJs } from './jsAstNormalizer.js';
+function inheritLeadingComments(target, source) {
+    const sourceComments = source
+        ?.leadingComments;
+    const targetNode = target;
+    if (!targetNode.leadingComments && sourceComments) {
+        targetNode.leadingComments = sourceComments;
+    }
+    return target;
+}
+function normalizeJsDocType(type) {
+    const text = type.trim().toLowerCase();
+    if (text.includes('string'))
+        return 'string';
+    if (text.includes('number'))
+        return 'number';
+    if (text.includes('boolean'))
+        return 'boolean';
+    if (text.includes('array'))
+        return 'array';
+    if (text.includes('object'))
+        return 'object';
+    if (text.includes('window') || text.includes('htmlelement'))
+        return 'object';
+    if (text.includes('void'))
+        return 'void';
+    if (text.includes('null'))
+        return 'null';
+    return 'unknown';
+}
+function parseJsDocInfo(node) {
+    const comments = node.leadingComments;
+    if (!comments?.length)
+        return { description: null };
+    const block = comments.find((comment) => comment.type === 'CommentBlock');
+    if (!block?.value)
+        return { description: null };
+    const lines = block.value
+        .split('\n')
+        .map((line) => line.replace(/^\s*\*\s?/, '').trim())
+        .filter(Boolean);
+    const descriptionLines = lines.filter((line) => !line.startsWith('@'));
+    const returnLine = lines.find((line) => line.startsWith('@returns') || line.startsWith('@return'));
+    const returnMatch = returnLine?.match(/@returns?\s+\{([^}]+)\}/);
+    return {
+        description: descriptionLines.length
+            ? descriptionLines.join(' ')
+            : null,
+        ...(returnMatch
+            ? { returnType: normalizeJsDocType(returnMatch[1]) }
+            : {}),
+    };
+}
 /** 从 JS 文件内容解析导出的代码块 */
 export function parseJsFile(filePath, content, projectRoot) {
     const out = [];
@@ -77,7 +130,7 @@ function processStatement(stmt, filePath, isJsx, projectRoot) {
         if (bt.isFunctionDeclaration(decl)) {
             const name = decl.id?.name;
             if (name) {
-                out.push(createRowFromFunction(name, decl, filePath, projectRoot, isJsx));
+                out.push(createRowFromFunction(name, inheritLeadingComments(decl, stmt), filePath, projectRoot, isJsx));
             }
         }
         else if (bt.isClassDeclaration(decl)) {
@@ -96,7 +149,7 @@ function processStatement(stmt, filePath, isJsx, projectRoot) {
                     if (name &&
                         (bt.isArrowFunctionExpression(init) ||
                             bt.isFunctionExpression(init))) {
-                        const fnDecl = arrowToFunction(name, init);
+                        const fnDecl = inheritLeadingComments(arrowToFunction(name, init), stmt);
                         out.push(createRowFromFunction(name, fnDecl, filePath, projectRoot, isJsx));
                     }
                 }
@@ -123,20 +176,20 @@ function processStatement(stmt, filePath, isJsx, projectRoot) {
                             const value = prop.value;
                             if (bt.isFunctionExpression(value) ||
                                 bt.isArrowFunctionExpression(value)) {
-                                const fnDecl = arrowToFunction(name, bt.isArrowFunctionExpression(value)
+                                const fnDecl = inheritLeadingComments(arrowToFunction(name, bt.isArrowFunctionExpression(value)
                                     ? value
-                                    : value);
+                                    : value), stmt);
                                 out.push(createRowFromFunction(name, fnDecl, filePath, projectRoot, isJsx));
                             }
                         }
                     }
                 }
                 else if (bt.isFunctionExpression(right)) {
-                    const fnDecl = arrowToFunction('default', right);
+                    const fnDecl = inheritLeadingComments(arrowToFunction('default', right), stmt);
                     out.push(createRowFromFunction('default', fnDecl, filePath, projectRoot, isJsx));
                 }
                 else if (bt.isArrowFunctionExpression(right)) {
-                    const fnDecl = arrowToFunction('default', right);
+                    const fnDecl = inheritLeadingComments(arrowToFunction('default', right), stmt);
                     out.push(createRowFromFunction('default', fnDecl, filePath, projectRoot, isJsx));
                 }
             }
@@ -150,7 +203,9 @@ function processStatement(stmt, filePath, isJsx, projectRoot) {
                     const right = expr.right;
                     if (bt.isFunctionExpression(right) ||
                         bt.isArrowFunctionExpression(right)) {
-                        const fnDecl = arrowToFunction(name, bt.isArrowFunctionExpression(right) ? right : right);
+                        const fnDecl = inheritLeadingComments(arrowToFunction(name, bt.isArrowFunctionExpression(right)
+                            ? right
+                            : right), stmt);
                         out.push(createRowFromFunction(name, fnDecl, filePath, projectRoot, isJsx));
                     }
                 }
@@ -162,18 +217,18 @@ function processStatement(stmt, filePath, isJsx, projectRoot) {
         const decl = stmt.declaration;
         if (bt.isFunctionDeclaration(decl)) {
             const name = decl.id?.name || 'default';
-            out.push(createRowFromFunction(name, decl, filePath, projectRoot, isJsx));
+            out.push(createRowFromFunction(name, inheritLeadingComments(decl, stmt), filePath, projectRoot, isJsx));
         }
         else if (bt.isClassDeclaration(decl)) {
             const name = decl.id?.name || 'default';
             out.push(createRowFromClass(name, decl, filePath, projectRoot));
         }
         else if (bt.isArrowFunctionExpression(decl)) {
-            const fnDecl = arrowToFunction('default', decl);
+            const fnDecl = inheritLeadingComments(arrowToFunction('default', decl), stmt);
             out.push(createRowFromFunction('default', fnDecl, filePath, projectRoot, isJsx));
         }
         else if (bt.isFunctionExpression(decl)) {
-            const fnDecl = arrowToFunction('default', decl);
+            const fnDecl = inheritLeadingComments(arrowToFunction('default', decl), stmt);
             out.push(createRowFromFunction('default', fnDecl, filePath, projectRoot, isJsx));
         }
     }
@@ -235,6 +290,7 @@ function arrowToFunction(name, arrow) {
 function createRowFromFunction(name, decl, filePath, projectRoot, isJsx) {
     const relPath = getRelativePathForDisplay(projectRoot, filePath);
     const category = inferCategoryFromPath(filePath) || inferCategoryFromName(name);
+    const jsdoc = parseJsDocInfo(decl);
     // 检测是否有 JSX
     const hasJsx = isJsx || containsJsx(decl);
     // 判断类型：
@@ -247,9 +303,34 @@ function createRowFromFunction(name, decl, filePath, projectRoot, isJsx) {
         : isJsx || /^[A-Z]/.test(name)
             ? 'component'
             : 'function';
-    const params = decl.params
-        .filter((p) => bt.isIdentifier(p))
-        .map((p) => p.name);
+    const params = decl.params.flatMap((param, index) => {
+        if (bt.isIdentifier(param)) {
+            return [makeParamPlaceholder(index)];
+        }
+        if (bt.isAssignmentPattern(param) && bt.isIdentifier(param.left)) {
+            return [makeParamPlaceholder(index)];
+        }
+        if (bt.isRestElement(param) && bt.isIdentifier(param.argument)) {
+            return [makeParamPlaceholder(index, true)];
+        }
+        if (bt.isObjectPattern(param)) {
+            return param.properties
+                .map((prop) => {
+                if (bt.isObjectProperty(prop) &&
+                    bt.isIdentifier(prop.key)) {
+                    return prop.key.name;
+                }
+                if (bt.isRestElement(prop) &&
+                    bt.isIdentifier(prop.argument)) {
+                    return `...${prop.argument.name}`;
+                }
+                return null;
+            })
+                .filter((value) => Boolean(value))
+                .sort();
+        }
+        return [makeParamPlaceholder(index)];
+    });
     const hooks = extractHooksFromBody(decl);
     const sideEffects = extractSideEffects(decl);
     return {
@@ -257,12 +338,14 @@ function createRowFromFunction(name, decl, filePath, projectRoot, isJsx) {
         type,
         category,
         path: relPath,
-        description: null,
+        description: jsdoc.description,
         content: `function ${decl.id?.name || 'anonymous'}(${params.join(', ')}) { ... }`,
         meta: {
             kind: 'function',
             params,
-            returnType: getReturnType(decl),
+            ...(getReturnType(decl, jsdoc)
+                ? { returnType: getReturnType(decl, jsdoc) }
+                : {}),
             ...(hooks.length ? { hooks } : {}),
             ...(sideEffects.length ? { sideEffects } : {}),
         },
@@ -328,28 +411,28 @@ function containsJsx(node) {
     visit(node);
     return found;
 }
-function getReturnType(fn) {
-    if (!fn.returnType)
-        return undefined;
-    const rt = fn.returnType;
-    if (bt.isTSTypeAnnotation(rt)) {
-        const inner = rt.typeAnnotation;
-        if (bt.isTSStringKeyword(inner))
-            return 'string';
-        if (bt.isTSNumberKeyword(inner))
-            return 'number';
-        if (bt.isTSBooleanKeyword(inner))
-            return 'boolean';
-        if (bt.isTSVoidKeyword(inner))
-            return 'void';
-        if (bt.isTSAnyKeyword(inner))
-            return 'any';
-        if (bt.isTSUnknownKeyword(inner))
-            return 'unknown';
-        if (bt.isTSNullKeyword(inner))
-            return 'null';
+function getReturnType(fn, jsdoc) {
+    if (fn.returnType) {
+        const rt = fn.returnType;
+        if (bt.isTSTypeAnnotation(rt)) {
+            const inner = rt.typeAnnotation;
+            if (bt.isTSStringKeyword(inner))
+                return 'string';
+            if (bt.isTSNumberKeyword(inner))
+                return 'number';
+            if (bt.isTSBooleanKeyword(inner))
+                return 'boolean';
+            if (bt.isTSVoidKeyword(inner))
+                return 'void';
+            if (bt.isTSAnyKeyword(inner))
+                return 'any';
+            if (bt.isTSUnknownKeyword(inner))
+                return 'unknown';
+            if (bt.isTSNullKeyword(inner))
+                return 'null';
+        }
     }
-    return undefined;
+    return jsdoc?.returnType;
 }
 /**
  * 遍历 Babel AST 节点，收集所有满足条件的回调
@@ -460,6 +543,12 @@ function extractSideEffects(fn) {
             if (calleeTextLower.includes('xmlhttprequest')) {
                 effects.add('network');
             }
+            if (bt.isMemberExpression(n.callee) &&
+                bt.isIdentifier(n.callee.property) &&
+                (n.callee.property.name === 'getBoundingClientRect' ||
+                    n.callee.property.name === 'getComputedStyle')) {
+                effects.add('dom');
+            }
         }
         // 2. 计时器
         if (bt.isCallExpression(n)) {

package/dist/indexer/extractMeta.js

@@ -2,6 +2,7 @@
  * 从 AST 抽取写入 `symbols.meta` 的结构化字段（props/params、hooks、返回值、类型成员等）。
  */
 import { Node, SyntaxKind, } from 'ts-morph';
+import { makeParamPlaceholder } from './paramPlaceholder.js';
 /**
  * 将节点收窄为可调用的函数形态，便于统一抽取参数与函数体。
  * @returns 若不是函数声明/表达式/箭头函数则为 `undefined`。
@@ -16,22 +17,25 @@ function asFn(node) {
     return undefined;
 }
 /**
- * 取第一个形参的「对外可见名」：对象解构取各属性名，单参数取标识符文本。
+ * 提取稳定参数结构：普通位置参数统一为 `$pN`，对象解构保留字段名。
  * @returns 用于后续在 `component` 中映射为 `props`，在 `util` 中保留为 `params`。
  */
 function extractParamNames(fn) {
     const params = fn.getParameters();
-    if (params.length === 0)
-        return [];
-    const first = params[0];
-    const nameNode = first.getNameNode();
-    if (Node.isObjectBindingPattern(nameNode)) {
-        return nameNode.getElements().map((el) => el.getName());
-    }
-    if (Node.isIdentifier(nameNode)) {
-        return [nameNode.getText()];
-    }
-    return [];
+    return params.flatMap((param, index) => {
+        const nameNode = param.getNameNode();
+        if (Node.isObjectBindingPattern(nameNode)) {
+            return nameNode
+                .getElements()
+                .map((el) => el.getName())
+                .filter(Boolean)
+                .sort();
+        }
+        if (Node.isIdentifier(nameNode)) {
+            return [makeParamPlaceholder(index, param.isRestParameter())];
+        }
+        return [makeParamPlaceholder(index, param.isRestParameter())];
+    });
 }
 /**
  * 从第一个参数的类型信息提取字段名（例如 `props: DialogProps` -> `title/content/onClose`）。

package/dist/indexer/heuristics.js

@@ -31,6 +31,8 @@ export function hasJsxInNode(node) {
  * @returns 命中 `components|features|...`
  */
 export function inferCategoryFromPath(filePath) {
+    const normalized = filePath.toLowerCase().replace(/\\/g, '/');
+    const segments = normalized.split('/').filter(Boolean);
     const markers = [
         'components',
         'features',
@@ -44,9 +46,10 @@ export function inferCategoryFromPath(filePath) {
         'types',
         'apis',
     ];
-    for (const m of markers) {
-        if (filePath.toLowerCase().includes(`/${m}/`)) {
-            return m;
+    for (let i = segments.length - 1; i >= 0; i--) {
+        const segment = segments[i];
+        if (markers.includes(segment)) {
+            return segment;
         }
     }
     return null;
@@ -69,9 +72,7 @@ export function inferCategoryFromName(originName) {
     return null;
 }
 export function isHookLike(exportName) {
-    if (/use$/i.test(exportName))
-        return true;
-    return false;
+    return /^use[A-Z0-9_]/.test(exportName);
 }
 /**
  * 读取节点（或父节点）上第一段 JSDoc 的 **描述正文**（不含 `@tag`）。

package/dist/indexer/indexProject.js

@@ -9,6 +9,7 @@ import { readFileSync, existsSync } from 'node:fs';
 import { extractInterfaceOrTypeMeta, extractMetaFromCallable, } from './extractMeta.js';
 import { getLeadingDocDescription, getRelativePathForDisplay, hasJsxInNode, isHookLike, isTsxFile, } from './heuristics.js';
 import { parseJsFile } from './babelParser.js';
+import { isParamPlaceholder } from './paramPlaceholder.js';
 import { computeFileHash, computeSemanticHash } from './tsAstNormalizer.js';
 const CALLERS_LIMIT = 20;
 /** 判断文件类型 */
@@ -31,8 +32,8 @@ function mergeCallableMeta(symbolType, raw) {
     if (symbolType === 'component' && params?.length) {
         const props = [
             ...new Set([...(paramTypeFields ?? []), ...params]),
-        ].filter((name) => name.toLowerCase() !== 'props');
-        return { ...rest, props: props.length ? props : params };
+        ].filter((name) => name.toLowerCase() !== 'props' && !isParamPlaceholder(name)).sort();
+        return { ...rest, ...(props.length ? { props } : {}) };
     }
     return { ...rest, ...(params?.length ? { params } : {}) };
 }

package/dist/indexer/jsAstNormalizer.js

@@ -15,6 +15,7 @@
  */
 import { createHash } from 'node:crypto';
 import * as t from '@babel/types';
+import { makeParamPlaceholder } from './paramPlaceholder.js';
 // ─────────────────────────────────────────────
 // JSDoc 类型提取
 // ─────────────────────────────────────────────
@@ -43,6 +44,9 @@ function parseJSDoc(jsdoc) {
 }
 function normalizeType(type) {
     type = type.trim().toLowerCase();
+    if (type.includes('window') || type.includes('htmlelement')) {
+        return 'object';
+    }
     if (type.includes('string'))
         return 'string';
     if (type.includes('number'))
@@ -59,22 +63,42 @@ function normalizeType(type) {
     }
     return 'unknown';
 }
+function normalizeObjectPattern(param, jsdoc) {
+    const props = param.properties
+        .map((p) => {
+        if (p.type === 'ObjectProperty' && p.key?.name) {
+            const name = p.key.name;
+            const type = jsdoc?.params[name] ?? 'unknown';
+            return `${name}:${type}`;
+        }
+        if (p.type === 'RestElement' && p.argument?.name) {
+            return `...${p.argument.name}:unknown`;
+        }
+        return 'unknown';
+    })
+        .sort();
+    return `{${props.join(';')}}`;
+}
 function normalizeParam(param, fallbackName, jsdoc) {
     if (param.type === 'Identifier') {
-        const name = param.name;
-        const type = jsdoc?.params[name] ?? 'unknown';
-        return `${name}:${type}`;
+        const type = jsdoc?.params[param.name] ?? 'unknown';
+        return `${fallbackName}:${type}`;
     }
     if (param.type === 'ObjectPattern') {
-        const props = param.properties.map((p) => {
-            if (p.key?.name) {
-                const name = p.key.name;
-                const type = jsdoc?.params[name] ?? 'unknown';
-                return `${name}:${type}`;
-            }
-            return 'unknown';
-        });
-        return `{${props.sort().join(';')}}`;
+        return normalizeObjectPattern(param, jsdoc);
+    }
+    if (param.type === 'AssignmentPattern') {
+        const left = normalizeParam(param.left, fallbackName, jsdoc);
+        return `${left}=$default`;
+    }
+    if (param.type === 'RestElement') {
+        if (param.argument?.type === 'Identifier') {
+            const type = jsdoc?.params[param.argument.name] ?? 'unknown';
+            return `...${fallbackName}:${type}`;
+        }
+        if (param.argument?.type === 'ObjectPattern') {
+            return `...${normalizeObjectPattern(param.argument, jsdoc)}`;
+        }
     }
     return `${fallbackName}:unknown`;
 }
@@ -108,14 +132,14 @@ function inferReturnType(node) {
 function normalizeFunction(node) {
     const jsdocText = getJSDoc(node);
     const jsdoc = jsdocText ? parseJSDoc(jsdocText) : undefined;
-    const params = node.params.map((p, i) => normalizeParam(p, `$p${i}`, jsdoc));
+    const params = node.params.map((p, i) => normalizeParam(p, makeParamPlaceholder(i), jsdoc));
     const returnType = jsdoc?.returnType ?? inferReturnType(node);
     return `fn(${params.join(',')})=>${returnType}`;
 }
 function normalizeArrowFunction(node) {
     const jsdocText = getJSDoc(node);
     const jsdoc = jsdocText ? parseJSDoc(jsdocText) : undefined;
-    const params = node.params.map((p, i) => normalizeParam(p, `$p${i}`, jsdoc));
+    const params = node.params.map((p, i) => normalizeParam(p, makeParamPlaceholder(i), jsdoc));
     // const params = node.params.map((p, i) => normalizeParam(p, `$p${i}`));
     const returnType = jsdoc?.returnType ?? inferReturnType(node);
     return `fn(${params.join(',')})=>${returnType}`;
@@ -160,6 +184,15 @@ export function inferBehaviorFromJS(node) {
                 behavior.push('uses timer');
             }
         }
+        if (t.isCallExpression(n) &&
+            t.isMemberExpression(n.callee) &&
+            t.isIdentifier(n.callee.property)) {
+            const prop = n.callee.property.name;
+            if (prop === 'getBoundingClientRect' ||
+                prop === 'getComputedStyle') {
+                behavior.push('reads dom layout');
+            }
+        }
         // localStorage
         if (t.isMemberExpression(n) &&
             t.isIdentifier(n.object) &&

package/dist/indexer/paramPlaceholder.js

@@ -0,0 +1,6 @@
+export function makeParamPlaceholder(index, isRest = false) {
+    return `${isRest ? '...' : ''}$p${index}`;
+}
+export function isParamPlaceholder(name) {
+    return /^\.\.\.\$p\d+$|^\$p\d+$/.test(name);
+}

package/dist/indexer/tsAstNormalizer.js

@@ -7,6 +7,7 @@
  */
 import { createHash } from 'node:crypto';
 import { Node, SyntaxKind } from 'ts-morph';
+import { makeParamPlaceholder } from './paramPlaceholder.js';
 // ─────────────────────────────────────────────
 // 内置类型白名单：不替换为 $T
 // ─────────────────────────────────────────────
@@ -101,8 +102,9 @@ export function normalizeNode(node) {
     const paramNames = new Map();
     let paramIdx = 0;
     function allocParam(name) {
-        if (!paramNames.has(name))
-            paramNames.set(name, `$p${paramIdx++}`);
+        if (!paramNames.has(name)) {
+            paramNames.set(name, makeParamPlaceholder(paramIdx++));
+        }
         return paramNames.get(name);
     }
     function visit(n) {
@@ -191,7 +193,7 @@ function normalizeParameter(param, index) {
         destrProps.sort();
         return `${prefix}{${destrProps.join(',')}}:${typeStr}${suffix}`;
     }
-    return `${prefix}$p${index}:${typeStr}${suffix}`;
+    return `${makeParamPlaceholder(index, param.isRestParameter())}:${typeStr}${suffix}`;
 }
 function normalizeTypeWithStructure(typeNode) {
     // 如果是类型字面量 { name: string, age: number }
@@ -211,11 +213,12 @@ function normalizeTypeWithStructure(typeNode) {
     // 如果是类型引用（e.g. Param, Array<string>, Promise<User>）
     if (Node.isTypeReference(typeNode)) {
         const typeName = typeNode.getTypeName().getText();
+        const normalizedTypeName = normalizeTypeName(typeName);
         // 优先处理泛型参数（不管是否在白名单中）
         const typeArgs = typeNode.getTypeArguments();
         if (typeArgs.length > 0) {
             const normalizedArgs = typeArgs.map((arg) => normalizeTypeWithStructure(arg));
-            return `${typeName}<${normalizedArgs.join(',')}>`;
+            return `${normalizedTypeName}<${normalizedArgs.join(',')}>`;
         }
         // 没有泛型参数时，检查是否是基础类型
         if (BUILTIN_TYPES.has(typeName)) {
@@ -253,7 +256,7 @@ function normalizeTypeWithStructure(typeNode) {
         catch (e) {
             // 解析失败，回退到类型名
         }
-        return typeName;
+        return normalizedTypeName;
     }
     // 其他情况（联合类型、交叉类型、基础类型等）
     return normalizeTypeString(typeNode.getText());

package/dist/prompts/reusableCodeAdvisorPrompt.js

@@ -7,19 +7,18 @@ const REUSABLE_CODE_ADVISOR_MARKDOWN = `# 可复用代码推荐
 
 当用户需要可复用代码或实现类需求时，按顺序执行：
 
-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 获取详情
-5. 从以下维度对比候选：
+1. 如果用户是在找可复用组件，优先调用 recommend_component，由它完成候选搜索、结构过滤和排序。
+2. 只有当用户明确要求手动检索、或需要更细粒度控制时，才组合调用 search_symbols / search_by_structure / get_symbol_detail。
+3. 若仅凭摘要无法判断，对最相关的若干候选调用 get_symbol_detail 获取详情。
+4. 从以下维度对比候选：
    - 与用户需求的**功能匹配度**
    - **API 是否简单**、入参是否合适
    - **依赖与副作用**风险
    - **复用安全性**（稳定性、耦合度、是否便于扩展）
-6. 给出**唯一首选**推荐，并说明理由，同时使用 **AskUserQuestion** 工具，提供两个选项：
+5. 给出**唯一首选**推荐，并说明理由，同时使用 **AskUserQuestion** 工具，提供两个选项：
    - 采纳推荐
    - 取消
-7. 用户选择"采纳推荐"后，立即调用 inc_usage 工具记录该行为（symbolId 从搜索结果的 id 字段获取），不要遗漏此步骤。
+6. 用户选择"采纳推荐"后，立即调用 inc_usage 工具记录该行为（symbolId 从搜索结果的 id 字段获取），不要遗漏此步骤。
 
 ## 不适用场景
 

package/dist/server/createServer.js

@@ -6,12 +6,15 @@ import { createGetSymbolDetailTool } from "../tools/getSymbolDetail.js";
 import { createReindexTool } from "../tools/reindex.js";
 import { createSearchByStructureTool } from "../tools/searchByStructure.js";
 import { createIncUsageTool } from "../tools/incUsage.js";
+import { RecommendationService } from "../services/recommendationService.js";
+import { createRecommendComponentTool } from "../tools/recommendComponent.js";
 export function createServer() {
     const server = new McpServer({
         name: "code-intelligence-mcp",
         version: "0.1.0"
     });
     const repository = new SymbolRepository();
+    const recommendationService = new RecommendationService(repository);
     const searchTool = createSearchSymbolsTool(repository);
     server.tool(searchTool.name, searchTool.description, searchTool.inputSchema, searchTool.handler);
     const detailTool = createGetSymbolDetailTool(repository);
@@ -22,6 +25,8 @@ export function createServer() {
     server.tool(reindexTool.name, reindexTool.description, reindexTool.inputSchema, reindexTool.handler);
     const incUsageTool = createIncUsageTool(repository);
     server.tool(incUsageTool.name, incUsageTool.description, incUsageTool.inputSchema, incUsageTool.handler);
+    const recommendComponentTool = createRecommendComponentTool(recommendationService);
+    server.tool(recommendComponentTool.name, recommendComponentTool.description, recommendComponentTool.inputSchema, recommendComponentTool.handler);
     registerReusableCodeAdvisorPrompt(server);
     return server;
 }

package/dist/services/recommendationService.js

@@ -0,0 +1,132 @@
+import { rankSemanticHits, rankSymbols } from './ranking.js';
+function uniqueStrings(values = []) {
+    return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
+}
+function normalizeToken(value) {
+    return value.trim().toLowerCase();
+}
+function getMetaStrings(symbol, key) {
+    const value = symbol.meta?.[key];
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === 'string');
+}
+function getCallers(symbol) {
+    const value = symbol.meta?.callers;
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === 'object' &&
+        item !== null &&
+        typeof item.name === 'string' &&
+        typeof item.path === 'string');
+}
+function toCandidate(symbol, score, reason, requiredProps, requiredHooks) {
+    const props = getMetaStrings(symbol, 'props');
+    const hooks = getMetaStrings(symbol, 'hooks');
+    const sideEffects = getMetaStrings(symbol, 'sideEffects');
+    return {
+        id: symbol.id,
+        name: symbol.name,
+        type: symbol.type,
+        path: symbol.path,
+        description: symbol.description,
+        usageCount: symbol.usageCount,
+        category: symbol.category,
+        score: Number(score.toFixed(3)),
+        reason,
+        matchedProps: requiredProps.filter((field) => props.map(normalizeToken).includes(normalizeToken(field))),
+        matchedHooks: requiredHooks.filter((field) => hooks.map(normalizeToken).includes(normalizeToken(field))),
+        callers: getCallers(symbol),
+        sideEffects,
+    };
+}
+function mergeCandidates(symbols) {
+    const seen = new Set();
+    const merged = [];
+    for (const symbol of symbols) {
+        if (seen.has(symbol.id))
+            continue;
+        seen.add(symbol.id);
+        merged.push(symbol);
+    }
+    return merged;
+}
+export class RecommendationService {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    async recommendComponent(input) {
+        const requiredProps = uniqueStrings(input.requiredProps);
+        const requiredHooks = uniqueStrings(input.requiredHooks);
+        const structureFields = uniqueStrings([...requiredProps, ...requiredHooks]);
+        const preferSemantic = input.semantic ?? true;
+        const limit = input.limit ?? 5;
+        let queriedBy = preferSemantic
+            ? 'semantic'
+            : 'keyword';
+        let searchResults;
+        if (preferSemantic) {
+            try {
+                searchResults = await this.repository.searchSemanticHits(input.query, {
+                    type: 'component',
+                    limit: Math.max(limit * 4, 12),
+                });
+            }
+            catch {
+                queriedBy = 'keyword';
+                searchResults = (await this.repository.search(input.query, 'component')).map((symbol) => ({ symbol, similarity: 0 }));
+            }
+        }
+        else {
+            searchResults = (await this.repository.search(input.query, 'component')).map((symbol) => ({ symbol, similarity: 0 }));
+        }
+        const structureResults = structureFields.length
+            ? await this.repository.searchByStructure(structureFields, {
+                type: 'component',
+                category: input.category,
+                limit: Math.max(limit * 4, 12),
+            })
+            : [];
+        const combined = mergeCandidates([
+            ...structureResults,
+            ...searchResults.map((item) => item.symbol),
+        ]).filter((symbol) => input.category
+            ? (symbol.category ?? '')
+                .toLowerCase()
+                .includes(input.category.toLowerCase())
+            : true);
+        if (combined.length === 0) {
+            return {
+                recommended: null,
+                alternatives: [],
+                queriedBy,
+                structureFilter: {
+                    requiredProps,
+                    requiredHooks,
+                },
+                message: '未找到符合条件的可复用组件。',
+            };
+        }
+        const ranked = queriedBy === 'semantic'
+            ? rankSemanticHits(combined.map((symbol) => ({
+                symbol,
+                similarity: searchResults.find((item) => item.symbol.id === symbol.id)
+                    ?.similarity ?? 0.55,
+            })))
+            : rankSymbols(input.query, combined);
+        const candidates = ranked.map((item) => toCandidate(item.symbol, item.score, item.reason.summary, requiredProps, requiredHooks));
+        return {
+            recommended: candidates[0] ?? null,
+            alternatives: candidates.slice(1, limit),
+            queriedBy,
+            structureFilter: {
+                requiredProps,
+                requiredHooks,
+            },
+            message: candidates.length > 0
+                ? '已找到可复用组件候选，首选已按综合匹配度排序。'
+                : '未找到符合条件的可复用组件。',
+        };
+    }
+}

package/dist/tools/recommendComponent.js

@@ -1,44 +1,27 @@
-import { z } from "zod";
-import { recommendComponent } from "../skills/recommendComponent.js";
+import { z } from 'zod';
 export const recommendComponentInput = z.object({
     query: z.string().min(1),
-    props: z.array(z.string().min(1)).optional(),
-    limit: z.number().int().min(1).max(20).optional().default(3)
+    requiredProps: z.array(z.string().min(1)).optional(),
+    requiredHooks: z.array(z.string().min(1)).optional(),
+    category: z.string().optional(),
+    semantic: z.boolean().optional().default(true),
+    limit: z.number().int().min(1).max(10).optional().default(5),
 });
-export function createRecommendComponentTool(repository) {
+export function createRecommendComponentTool(recommendationService) {
     return {
-        name: "recommend_component",
-        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
-- 如果没有合适结果，会返回最接近的候选并说明差距`,
+        name: 'recommend_component',
+        description: '高层推荐工具：当用户想找可复用 UI 组件时优先调用本工具。输入用户需求、必需 props/hooks 后，工具会自动完成候选搜索、结构过滤和首选推荐。',
         inputSchema: recommendComponentInput.shape,
         handler: async (input) => {
-            const result = await recommendComponent(input.query, repository, {
-                props: input.props,
-                limit: input.limit
-            });
+            const result = await recommendationService.recommendComponent(input);
             return {
                 content: [
                     {
-                        type: "text",
-                        text: JSON.stringify(result, null, 2)
-                    }
-                ]
+                        type: 'text',
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
             };
-        }
+        },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lorrylurui/code-intelligence-mcp",
-    "version": "2.0.2",
+    "version": "2.0.3",
     "private": false,
     "description": "MCP server 提供仓库内可复用代码块（ts/tsx/js/jsx/css/less）的索引和查询能力，支持基于代码上下文的智能推荐。",
     "type": "module",
@@ -16,6 +16,8 @@
         "dev": "tsx watch --clear-screen=false --exclude node_modules --exclude dist src/index.ts",
         "dev:mcp": "node ./scripts/mcp-dev-watch.mjs",
         "build": "tsc -p tsconfig.json",
+        "test": "vitest run",
+        "test:watch": "vitest",
         "start": "node dist/index.js",
         "index": "tsx src/cli/index-codebase-cli.ts",
         "ci-index": "tsx src/cli/ci-index-cli.ts",
@@ -44,7 +46,8 @@
         "@types/node": "^22.10.1",
         "@types/pg": "^8.20.0",
         "tsx": "^4.19.2",
-        "typescript": "^5.6.3"
+        "typescript": "^5.6.3",
+        "vitest": "^3.2.4"
     },
     "publishConfig": {
         "registry": "https://registry.npmjs.org/",