@lorrylurui/code-intelligence-mcp 2.0.3 → 2.0.5

package/dist/services/recommendationService.js

@@ -5,6 +5,39 @@ function uniqueStrings(values = []) {
 function normalizeToken(value) {
     return value.trim().toLowerCase();
 }
+const CATEGORY_TYPE_HINTS = [
+    { keywords: ['util'], types: ['function'] },
+    { keywords: ['hook'], types: ['hook'] },
+    { keywords: ['type'], types: ['type', 'interface'] },
+    { keywords: ['class'], types: ['class'] },
+    { keywords: ['component'], types: ['component'] },
+];
+const QUERY_TYPE_HINTS = [
+    {
+        keywords: [' util', 'util ', 'helper', '函数', '方法', '计算', '获取'],
+        types: ['function'],
+    },
+    { keywords: ['hook', ' use'], types: ['hook'] },
+];
+function resolveTypesByHints(source, hints) {
+    for (const hint of hints) {
+        if (hint.keywords.some((keyword) => source.includes(keyword))) {
+            return [...new Set(hint.types)];
+        }
+    }
+    return [];
+}
+function inferSearchTypes(input) {
+    const query = input.query.toLowerCase();
+    const category = (input.category ?? '').toLowerCase();
+    const categoryTypes = resolveTypesByHints(category, CATEGORY_TYPE_HINTS);
+    if (categoryTypes.length > 0)
+        return categoryTypes;
+    const queryTypes = resolveTypesByHints(query, QUERY_TYPE_HINTS);
+    if (queryTypes.length > 0)
+        return queryTypes;
+    return ['component'];
+}
 function getMetaStrings(symbol, key) {
     const value = symbol.meta?.[key];
     if (!Array.isArray(value))
@@ -51,52 +84,249 @@ function mergeCandidates(symbols) {
     }
     return merged;
 }
+const NON_REUSABLE_PATH_SEGMENTS = [
+    '__tests__',
+    '__mocks__',
+    '/test/',
+    '/tests/',
+    '/fixtures/',
+    '/stories/',
+    '/story/',
+];
+const DEMO_LIKE_PATH_SEGMENTS_STRICT = [
+    '/one-ui-demo/',
+    '/example/',
+    '/examples/',
+    '/demo/',
+    '/demos/',
+];
+const DEMO_LIKE_PATH_SEGMENTS_SOFT = [
+    '/one-ui-demo/',
+    '/example/',
+    '/examples/',
+];
+const NON_REUSABLE_PATH_PATTERNS = [
+    '.test.',
+    '.spec.',
+    '.stories.',
+    '.story.',
+    '.mock.',
+];
+const NON_REUSABLE_NAME_TOKENS = ['mock', 'fixture', 'example', 'demo'];
+const MIN_RECOMMENDATION_SCORE = {
+    semantic: 0.5,
+    keyword: 0.45,
+};
+const MIN_SEMANTIC_TEXT_SCORE = 0.6;
+const MIN_LITERAL_MATCH_SCORE = 0.18;
+function isDemoLikePath(path, strict = false) {
+    const normalizedPath = path.toLowerCase();
+    const segments = strict
+        ? DEMO_LIKE_PATH_SEGMENTS_STRICT
+        : DEMO_LIKE_PATH_SEGMENTS_SOFT;
+    return segments.some((segment) => normalizedPath.includes(segment));
+}
+/**
+ * 判断是否为可复用候选，过滤掉明显的测试/示例代码。虽然有可能误伤一些真实组件，但优先保证推荐结果的实用性和专业度。
+ * @param symbol 要判断的代码符号
+ * @returns boolean 是否为可复用候选
+ */
+export function isReusableCandidate(symbol) {
+    const path = symbol.path.toLowerCase();
+    const name = symbol.name.toLowerCase();
+    if (isDemoLikePath(path, true) ||
+        NON_REUSABLE_PATH_SEGMENTS.some((segment) => path.includes(segment)) ||
+        NON_REUSABLE_PATH_PATTERNS.some((pattern) => path.includes(pattern))) {
+        return false;
+    }
+    return !NON_REUSABLE_NAME_TOKENS.some((token) => name === token || name.startsWith(token));
+}
+/**
+ * 判断推荐结果的props/hooks等结构字段是否满足查询要求，作为强相关推荐的加分项之一。虽然有可能遗漏一些未正确标注字段的结果，但优先保证推荐结果的相关性和准确性。
+ * @param symbol 要判断的代码符号
+ * @param requiredProps 必需的属性列表
+ * @param requiredHooks 必需的钩子列表
+ * @returns boolean 是否为强相关推荐结果
+ */
+function hasAllRequiredFields(symbol, requiredProps, requiredHooks) {
+    if (requiredProps.length === 0 && requiredHooks.length === 0) {
+        return false;
+    }
+    const props = getMetaStrings(symbol, 'props').map(normalizeToken);
+    const hooks = getMetaStrings(symbol, 'hooks').map(normalizeToken);
+    return (requiredProps.every((field) => props.includes(normalizeToken(field))) &&
+        requiredHooks.every((field) => hooks.includes(normalizeToken(field))));
+}
+function extractLiteralTokens(query) {
+    const tokens = new Set();
+    const genericTokens = new Set([
+        'component',
+        'components',
+        'hook',
+        'hooks',
+        'util',
+        'utils',
+        'function',
+        'functions',
+        'class',
+        'classes',
+        'type',
+        'types',
+    ]);
+    const normalized = query.trim().toLowerCase();
+    for (const match of normalized.matchAll(/[a-z0-9_]+/g)) {
+        const token = match[0];
+        if (token.length >= 3 && !genericTokens.has(token)) {
+            tokens.add(token);
+        }
+    }
+    return [...tokens];
+}
+// eg: query='useDebounceInput组件', symbol.name='useDebounceInput' => match; query='防抖组件', symbol.name='useDebounceInput' => match; query='input组件', symbol.name='useDebounceInput' => weak match
+function hasStrongLiteralMatch(query, symbol) {
+    const normalizedQuery = query.trim().toLowerCase();
+    const name = symbol.name.toLowerCase();
+    const path = symbol.path.toLowerCase();
+    const basename = path.split('/').pop() ?? '';
+    if (normalizedQuery &&
+        (name === normalizedQuery || path.includes(normalizedQuery))) {
+        return true;
+    }
+    const tokens = extractLiteralTokens(query);
+    return tokens.some((token) => name === token || name.includes(token) || basename.includes(token));
+}
+function isStrongEnoughRecommendation(item, query, queriedBy, requiredProps, requiredHooks) {
+    const hasRequiredFieldMatch = hasAllRequiredFields(item.symbol, requiredProps, requiredHooks);
+    const hasLiteralMatch = hasStrongLiteralMatch(query, item.symbol);
+    if (queriedBy === 'semantic') {
+        return ((item.score >= MIN_RECOMMENDATION_SCORE.semantic &&
+            (item.reason.textMatch.score >= MIN_SEMANTIC_TEXT_SCORE ||
+                hasRequiredFieldMatch)) ||
+            (hasLiteralMatch && item.score >= MIN_LITERAL_MATCH_SCORE));
+    }
+    return (item.score >= MIN_RECOMMENDATION_SCORE.keyword ||
+        (hasRequiredFieldMatch && item.score >= 0.4));
+}
+function computeRecommendationPriority(item, query) {
+    let score = item.score;
+    const notes = [];
+    const path = item.symbol.path.toLowerCase();
+    if (hasStrongLiteralMatch(query, item.symbol)) {
+        score += 0.22;
+        notes.push('名称或文件名命中查询');
+    }
+    if (isDemoLikePath(path)) {
+        score -= 0.18;
+        notes.push('示例工程路径降权');
+    }
+    return {
+        score: Number(Math.max(0, score).toFixed(3)),
+        reason: notes.length > 0
+            ? `${item.reason.summary} + ${notes.join(' + ')}`
+            : item.reason.summary,
+    };
+}
 export class RecommendationService {
     repository;
     constructor(repository) {
         this.repository = repository;
     }
     async recommendComponent(input) {
+        console.error('[code-intelligence-mcp] recommendComponent.start query=%s category=%s semantic=%s limit=%s requiredProps=%s requiredHooks=%s', input.query, input.category ?? '', String(input.semantic ?? true), String(input.limit ?? 5), JSON.stringify(input.requiredProps ?? []), JSON.stringify(input.requiredHooks ?? []));
         const requiredProps = uniqueStrings(input.requiredProps);
         const requiredHooks = uniqueStrings(input.requiredHooks);
-        const structureFields = uniqueStrings([...requiredProps, ...requiredHooks]);
+        const structureFields = uniqueStrings([
+            ...requiredProps,
+            ...requiredHooks,
+        ]);
+        const searchTypes = inferSearchTypes(input);
         const preferSemantic = input.semantic ?? true;
         const limit = input.limit ?? 5;
         let queriedBy = preferSemantic
             ? 'semantic'
             : 'keyword';
         let searchResults;
+        console.error('[code-intelligence-mcp] recommendComponent.searchTypes types=%s', JSON.stringify(searchTypes));
         if (preferSemantic) {
             try {
-                searchResults = await this.repository.searchSemanticHits(input.query, {
-                    type: 'component',
+                const semanticGroups = await Promise.all(searchTypes.map((type) => this.repository.searchSemanticHits(input.query, {
+                    type,
                     limit: Math.max(limit * 4, 12),
-                });
+                })));
+                searchResults = semanticGroups.flat();
+                console.error('[code-intelligence-mcp] recommendComponent.semanticHits count=%s top=%s', String(searchResults.length), JSON.stringify(searchResults.slice(0, 3).map((item) => ({
+                    id: item.symbol.id,
+                    name: item.symbol.name,
+                    path: item.symbol.path,
+                    similarity: Number(item.similarity.toFixed(4)),
+                }))));
             }
             catch {
                 queriedBy = 'keyword';
-                searchResults = (await this.repository.search(input.query, 'component')).map((symbol) => ({ symbol, similarity: 0 }));
+                const keywordGroups = await Promise.all(searchTypes.map((type) => this.repository.search(input.query, type)));
+                searchResults = keywordGroups
+                    .flat()
+                    .map((symbol) => ({ symbol, similarity: 0 }));
+                console.error('[code-intelligence-mcp] recommendComponent.semanticFailed fallback=keyword count=%s top=%s', String(searchResults.length), JSON.stringify(searchResults.slice(0, 3).map((item) => ({
+                    id: item.symbol.id,
+                    name: item.symbol.name,
+                    path: item.symbol.path,
+                }))));
             }
         }
         else {
-            searchResults = (await this.repository.search(input.query, 'component')).map((symbol) => ({ symbol, similarity: 0 }));
+            const keywordGroups = await Promise.all(searchTypes.map((type) => this.repository.search(input.query, type)));
+            searchResults = keywordGroups
+                .flat()
+                .map((symbol) => ({ symbol, similarity: 0 }));
+            console.error('[code-intelligence-mcp] recommendComponent.keywordOnly count=%s top=%s', String(searchResults.length), JSON.stringify(searchResults.slice(0, 3).map((item) => ({
+                id: item.symbol.id,
+                name: item.symbol.name,
+                path: item.symbol.path,
+            }))));
         }
         const structureResults = structureFields.length
-            ? await this.repository.searchByStructure(structureFields, {
-                type: 'component',
-                category: input.category,
+            ? (await Promise.all(searchTypes.map((type) => this.repository.searchByStructure(structureFields, {
+                type,
                 limit: Math.max(limit * 4, 12),
-            })
+            })))).flat()
             : [];
-        const combined = mergeCandidates([
+        console.error('[code-intelligence-mcp] recommendComponent.structureHits fields=%s count=%s top=%s', JSON.stringify(structureFields), String(structureResults.length), JSON.stringify(structureResults.slice(0, 3).map((symbol) => ({
+            id: symbol.id,
+            name: symbol.name,
+            path: symbol.path,
+        }))));
+        // 合并逻辑：先合并语义搜索（或关键词模糊搜索）和结构搜索结果去重
+        const mergedBeforeCategory = mergeCandidates([
             ...structureResults,
             ...searchResults.map((item) => item.symbol),
-        ]).filter((symbol) => input.category
+        ]);
+        // 再按 category 过滤（如果有 category 限制）
+        let combined = mergedBeforeCategory.filter((symbol) => input.category
             ? (symbol.category ?? '')
                 .toLowerCase()
                 .includes(input.category.toLowerCase())
             : true);
+        // LLM 可能把 "input" 之类词误当作 category，导致误筛空；若筛空则回退为不按 category 过滤。
+        if (combined.length === 0 &&
+            input.category &&
+            mergedBeforeCategory.length) {
+            console.error('[code-intelligence-mcp] recommendComponent.categoryFallback category=%s merged=%s -> useUnfiltered', input.category, String(mergedBeforeCategory.length));
+            combined = mergedBeforeCategory;
+        }
+        const reusableCandidates = combined.filter(isReusableCandidate);
+        if (reusableCandidates.length > 0) {
+            console.error('[code-intelligence-mcp] recommendComponent.reusableFilter before=%s after=%s removed=%s', String(combined.length), String(reusableCandidates.length), String(combined.length - reusableCandidates.length));
+            combined = reusableCandidates;
+        }
+        console.error('[code-intelligence-mcp] recommendComponent.combine merged=%s afterCategory=%s top=%s', String(mergedBeforeCategory.length), String(combined.length), JSON.stringify(combined.slice(0, 3).map((symbol) => ({
+            id: symbol.id,
+            name: symbol.name,
+            path: symbol.path,
+            category: symbol.category,
+        }))));
         if (combined.length === 0) {
+            console.error('[code-intelligence-mcp] recommendComponent.emptyResult query=%s queriedBy=%s requiredProps=%s requiredHooks=%s', input.query, queriedBy, JSON.stringify(requiredProps), JSON.stringify(requiredHooks));
             return {
                 recommended: null,
                 alternatives: [],
@@ -108,14 +338,34 @@ export class RecommendationService {
                 message: '未找到符合条件的可复用组件。',
             };
         }
+        // 最后排序并切分首选/备选
         const ranked = queriedBy === 'semantic'
             ? rankSemanticHits(combined.map((symbol) => ({
                 symbol,
-                similarity: searchResults.find((item) => item.symbol.id === symbol.id)
-                    ?.similarity ?? 0.55,
-            })))
+                similarity: searchResults.find((item) => item.symbol.id === symbol.id)?.similarity ?? 0.55,
+            })), input.query)
             : rankSymbols(input.query, combined);
-        const candidates = ranked.map((item) => toCandidate(item.symbol, item.score, item.reason.summary, requiredProps, requiredHooks));
+        const qualifiedRanked = ranked.filter((item) => isStrongEnoughRecommendation(item, input.query, queriedBy, requiredProps, requiredHooks));
+        console.error('[code-intelligence-mcp] recommendComponent.qualityGate before=%s after=%s queriedBy=%s', String(ranked.length), String(qualifiedRanked.length), queriedBy);
+        const prioritizedRanked = qualifiedRanked
+            .map((item) => {
+            const adjusted = computeRecommendationPriority(item, input.query);
+            return {
+                item,
+                adjustedScore: adjusted.score,
+                adjustedReason: adjusted.reason,
+            };
+        })
+            .sort((a, b) => b.adjustedScore - a.adjustedScore);
+        const candidates = prioritizedRanked.map((entry) => toCandidate(entry.item.symbol, entry.adjustedScore, entry.adjustedReason, requiredProps, requiredHooks));
+        console.error('[code-intelligence-mcp] recommendComponent.ranked count=%s top=%s', String(candidates.length), JSON.stringify(candidates.slice(0, 3).map((candidate) => ({
+            id: candidate.id,
+            name: candidate.name,
+            path: candidate.path,
+            score: candidate.score,
+            matchedProps: candidate.matchedProps,
+            matchedHooks: candidate.matchedHooks,
+        }))));
         return {
             recommended: candidates[0] ?? null,
             alternatives: candidates.slice(1, limit),

package/dist/services/reindex.js

@@ -10,6 +10,26 @@ 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';
+function isCallerDebugEnabled() {
+    return /^(1|true|yes|on)$/i.test(process.env.DEBUG_CALLERS ?? '');
+}
+function getCallerDebugMatch() {
+    return (process.env.DEBUG_CALLERS_MATCH ?? '').trim().toLowerCase();
+}
+function debugMatchedFiles(stage, files, projectRoot) {
+    if (!isCallerDebugEnabled())
+        return;
+    const match = getCallerDebugMatch();
+    const normalized = files.map((file) => getRelativePathForDisplay(projectRoot, file));
+    const matched = match
+        ? normalized.filter((file) => file.toLowerCase().includes(match))
+        : normalized;
+    console.error(`[callers.debug] ${stage} ${JSON.stringify({
+        match: match || null,
+        count: matched.length,
+        files: matched,
+    })}`);
+}
 export async function runReindex(options = {}) {
     const projectRoot = resolve(options.projectRoot ?? process.cwd());
     const { dryRun = false, forceRebuild = false } = options;
@@ -35,6 +55,7 @@ export async function runReindex(options = {}) {
         dot: false,
     });
     console.error(`[reindex] glob found ${allFiles.length} file(s)`);
+    debugMatchedFiles('reindex-all-files', allFiles, projectRoot);
     // ─── 2. file_hash 过滤：跳过 AST 未变的文件（CPU 优化）────────────────
     // forceRebuild 时跳过此过滤，file_hash 不可复用（模板/模型变更时相同文件产出不同 content）
     let filesToIndex = allFiles;
@@ -58,9 +79,13 @@ export async function runReindex(options = {}) {
         });
         skippedFiles = allFiles.length - filesToIndex.length;
         console.error(`[reindex] file_hash: ${skippedFiles} unchanged (skipped), ${filesToIndex.length} changed (to parse)`);
+        const skippedAbsFiles = allFiles.filter((absPath) => !filesToIndex.includes(absPath));
+        debugMatchedFiles('reindex-files-to-parse', filesToIndex, projectRoot);
+        debugMatchedFiles('reindex-files-skipped', skippedAbsFiles, projectRoot);
     }
     else if (forceRebuild) {
         console.error(`[reindex] forceRebuild=true, skipping file_hash filter — parsing all ${allFiles.length} file(s)`);
+        debugMatchedFiles('reindex-files-to-parse', filesToIndex, projectRoot);
     }
     if (filesToIndex.length === 0) {
         console.error('[reindex] all files unchanged, nothing to do');

package/dist/tools/getSymbolDetail.js

@@ -7,7 +7,8 @@ export function createGetSymbolDetailTool(repository) {
         name: 'get_symbol_detail',
         description: '获取单个代码块的完整详情（含源码、参数类型、调用关系、副作用）。\n' +
             '仅在以下情况调用：search_symbols 返回的摘要信息不足以判断是否适用（如签名模糊、副作用不明确）。\n' +
-            '通常对 top 1-3 候选调用，不要对所有结果批量调用。',
+            '通常对 top 1-3 候选调用，不要对所有结果批量调用。\n' +
+            '约束：若 recommend_component 已返回结果，默认不要调用本工具；仅在用户明确要求“看源码细节/二次验证”时调用。',
         inputSchema: getSymbolDetailInput.shape,
         handler: async (input) => {
             const symbol = await repository.getByName(input.name);

package/dist/tools/recommendComponent.js

@@ -1,4 +1,66 @@
 import { z } from 'zod';
+function formatCallers(callers) {
+    if (!callers.length)
+        return '新增';
+    return callers.map((caller) => `${caller.name}(${caller.path})`).join('; ');
+}
+function formatSideEffects(sideEffects) {
+    return sideEffects.length ? sideEffects.join('/') : '无';
+}
+function formatHasResult(result) {
+    const recommended = result.recommended;
+    if (!recommended)
+        return '';
+    const reasons = [];
+    if (recommended.matchedProps.length) {
+        reasons.push(`匹配到必需 props：${recommended.matchedProps.join(', ')}`);
+    }
+    if (recommended.matchedHooks.length) {
+        reasons.push(`匹配到必需 hooks：${recommended.matchedHooks.join(', ')}`);
+    }
+    if (reasons.length < 2) {
+        reasons.push('综合语义、结构字段和可复用性排序后为首选。');
+    }
+    const alternatives = result.alternatives.length
+        ? result.alternatives
+            .map((item) => `${item.name}（${formatSideEffects(item.sideEffects)}）`)
+            .join('; ')
+        : '无';
+    return `首选：${recommended.name} — ${recommended.path}
+symbolId：${recommended.id}
+使用范围：${formatCallers(recommended.callers)}
+副作用：${formatSideEffects(recommended.sideEffects)}
+理由：
+1. ${reasons[0] ?? '匹配度最高，适合直接复用。'}
+2. ${reasons[1] ?? 'API 形态与需求一致，接入成本低。'}
+其他候选：${alternatives}
+用法提示：
+\`\`\`tsx
+<${recommended.name} value={value} onChange={handleChange} />
+\`\`\`
+是否采纳（**请在聊天框输入 1 或 2**）：
+1️⃣ 采纳推荐 — 自动调用 inc_usage 记录使用
+2️⃣ 取消`;
+}
+function formatNoResult() {
+    return `首选：未找到已有实现
+使用范围：无
+副作用：无
+理由：
+1. 当前索引中没有满足条件的组件（例如必须包含 onChange）
+2. 已尝试可用检索方式，仍无可用候选
+其他候选：无
+用法提示：
+\`\`\`tsx
+// 可先创建一个受控 Input 组件，至少暴露 value + onChange
+\`\`\`
+是否采纳（**请在聊天框输入 1 或 2**）：
+1️⃣ 新建最小可复用组件
+2️⃣ 取消`;
+}
+function formatReply(result) {
+    return result.recommended ? formatHasResult(result) : formatNoResult();
+}
 export const recommendComponentInput = z.object({
     query: z.string().min(1),
     requiredProps: z.array(z.string().min(1)).optional(),
@@ -10,18 +72,32 @@ export const recommendComponentInput = z.object({
 export function createRecommendComponentTool(recommendationService) {
     return {
         name: 'recommend_component',
-        description: '高层推荐工具：当用户想找可复用 UI 组件时优先调用本工具。输入用户需求、必需 props/hooks 后，工具会自动完成候选搜索、结构过滤和首选推荐。',
+        description: '【降级链第一步，唯一首选工具】当用户询问有没有可复用的组件/函数/util，或需要找仓库中现有实现时，必须先调用本工具。\n' +
+            '本工具会自动完成候选搜索、结构过滤和首选推荐，无需再调其他搜索工具。\n' +
+            '⚠️ 输出约束（必须严格遵守）：\n' +
+            '- recommended != null：立即将工具返回的文本原样输出给用户，完全停止，不得调用任何其他工具，不得改写为散文或追加说明。\n' +
+            '- recommended = null：进入降级链第二步，调用 search_symbols（semantic=true）。\n' +
+            '- 任何情况下禁止调用 grep/read file/file search 作为本工具的后续动作。',
         inputSchema: recommendComponentInput.shape,
         handler: async (input) => {
-            const result = await recommendationService.recommendComponent(input);
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify(result, null, 2),
-                    },
-                ],
-            };
+            console.error('[code-intelligence-mcp] tool.recommend_component.called query=%s requiredProps=%s requiredHooks=%s category=%s semantic=%s limit=%s', input.query, JSON.stringify(input.requiredProps ?? []), JSON.stringify(input.requiredHooks ?? []), input.category ?? '', String(input.semantic ?? true), String(input.limit ?? 5));
+            try {
+                const result = await recommendationService.recommendComponent(input);
+                console.error('[code-intelligence-mcp] tool.recommend_component.done recommended=%s alternatives=%s queriedBy=%s', result.recommended ? 'yes' : 'no', String(result.alternatives.length), result.queriedBy);
+                const formattedReply = formatReply(result);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: formattedReply,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                console.error('[code-intelligence-mcp] tool.recommend_component.error', error);
+                throw error;
+            }
         },
     };
 }

package/dist/tools/searchByStructure.js

@@ -15,7 +15,8 @@ export function createSearchByStructureTool(repository) {
         name: 'search_by_structure',
         description: '按代码块的结构字段（props/params/hooks）检索，适合已知接口形态时使用。\n' +
             '示例：需要一个接受 value、onChange、error 三个 prop 的输入组件 → fields: ["value", "onChange", "error"], type: "component"\n' +
-            '与 search_symbols 配合：先语义检索候选，再用本工具做 API 结构过滤以精确匹配。',
+            '与 search_symbols 配合：先语义检索候选，再用本工具做 API 结构过滤以精确匹配。\n' +
+            '约束：当用户是在问“有没有可复用组件/帮我找组件”时，默认不要调用本工具；仅在用户明确要求二次验证时使用。',
         inputSchema: searchByStructureInput.shape,
         handler: async (input) => {
             const rows = await repository.searchByStructure(input.fields, {

package/dist/tools/searchSymbols.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { rankSemanticHits, rankSymbols } from '../services/ranking.js';
+import { isReusableCandidate } from '../services/recommendationService.js';
 export const searchSymbolsInput = z.object({
     query: z.string().min(1),
     type: z
@@ -12,14 +13,33 @@ export const searchSymbolsInput = z.object({
 });
 const SCORE_THRESHOLD_FOR_FINAL = 0.45; // 综合排序分阈值（语义相似度占50%权重，原始0.5相似度 ≈ 综合0.35起）
 const TOP_K_FOR_FINAL_RESULTS = 20; // 结果上限,返回相似度高的，保证数据质量
+function toRankedResult(item) {
+    return {
+        id: item.symbol.id,
+        name: item.symbol.name,
+        type: item.symbol.type,
+        path: item.symbol.path,
+        description: item.symbol.description,
+        usageCount: item.symbol.usageCount,
+        score: item.score,
+        reason: item.reason.summary,
+        reasonDetail: item.reason,
+    };
+}
+function filterReusableSymbols(items) {
+    return items.filter((item) => isReusableCandidate(item.symbol));
+}
 export function createSearchSymbolsTool(repository) {
     return {
         name: 'search_symbols',
-        description: '搜索项目中已有的可复用代码块（函数、组件、Hook、类型等）。在生成新代码之前必须先调用本工具，确认是否已有实现。\n' +
+        description: '【降级链第二步，非首选工具】搜索项目中已有的可复用代码块（函数、组件、Hook、类型等）。\n' +
+            '⚠️ 调用顺序约束：对于"帮我找 X 组件/util/函数"类问题，第一步必须是 recommend_component，不得跳过直接调用本工具。\n' +
+            '本工具仅在 recommend_component 返回 null（无推荐）后才允许调用，作为第二级降级检索。\n' +
             '- 有明确名称时（如 "useDebounce"）：semantic=false（默认），直接关键词检索\n' +
-            '- 描述功能意图时（如 "防抖"、"处理表单提交"）：semantic=true，进行语义检索（需 embedding 服务已就绪）\n' +
-            '- 不确定 type 时省略该参数，不要猜测\n' +
-            '- 返回结果含 semanticSimilarity 字段：>0.85 高置信度可直接推荐，0.6-0.85 需结合 description 判断，<0.6 说明可能无合适实现',
+            '- 描述功能意图时（如 "防抖"、"处理表单提交"）：semantic=true，进行语义检索\n' +
+            '- 不确定 type 时省略该参数\n' +
+            '- 本工具返回结果后，必须立即按固定模板输出，停止所有后续工具调用。\n' +
+            '- 本工具返回空结果后，输出无结果模板，完全停止，禁止 grep/read file/文件系统兜底。',
         inputSchema: searchSymbolsInput.shape,
         handler: async (input) => {
             if (input.semantic) {
@@ -27,9 +47,34 @@ export function createSearchSymbolsTool(repository) {
                     type: input.type,
                     limit: input.limit,
                 });
-                const simById = new Map(hits.map((h) => [h.symbol.id, h.similarity]));
+                const reusableHits = filterReusableSymbols(hits);
+                if (reusableHits.length === 0) {
+                    const keywordRows = (await repository.search(input.query, input.type)).filter((row) => isReusableCandidate(row));
+                    const fallbackRows = input.ranked
+                        ? rankSymbols(input.query, keywordRows)
+                            .map(toRankedResult)
+                            .filter((x) => x.score >= SCORE_THRESHOLD_FOR_FINAL)
+                            .slice(0, TOP_K_FOR_FINAL_RESULTS)
+                        : keywordRows.map((r) => ({
+                            id: r.id,
+                            name: r.name,
+                            type: r.type,
+                            path: r.path,
+                            description: r.description,
+                            usageCount: r.usageCount,
+                        }));
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify(fallbackRows, null, 2),
+                            },
+                        ],
+                    };
+                }
+                const simById = new Map(reusableHits.map((h) => [h.symbol.id, h.similarity]));
                 const resultRows = input.ranked
-                    ? rankSemanticHits(hits)
+                    ? rankSemanticHits(reusableHits, input.query)
                         .map((item) => ({
                         id: item.symbol.id,
                         name: item.symbol.name,
@@ -44,7 +89,7 @@ export function createSearchSymbolsTool(repository) {
                     }))
                         .filter((x) => x.score >= SCORE_THRESHOLD_FOR_FINAL) // 基于综合排序分过滤，保留 usage/recency 高的结果
                         .slice(0, TOP_K_FOR_FINAL_RESULTS)
-                    : hits.map((h) => ({
+                    : reusableHits.map((h) => ({
                         id: h.symbol.id,
                         name: h.symbol.name,
                         type: h.symbol.type,
@@ -62,20 +107,10 @@ export function createSearchSymbolsTool(repository) {
                     ],
                 };
             }
-            const rows = await repository.search(input.query, input.type);
+            const rows = (await repository.search(input.query, input.type)).filter((row) => isReusableCandidate(row));
             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,
-                    description: item.symbol.description,
-                    usageCount: item.symbol.usageCount,
-                    score: item.score,
-                    reason: item.reason.summary,
-                    reasonDetail: item.reason,
-                }))
+                    .map(toRankedResult)
                     .filter((x) => x.score >= SCORE_THRESHOLD_FOR_FINAL) // 基于综合排序分过滤
                     .slice(0, TOP_K_FOR_FINAL_RESULTS)
                 : rows.map((r) => ({

package/dist/workers/embeddingWorker.js

@@ -67,7 +67,6 @@ async function processEmbedJob(job, pool) {
     const meta = typeof row.meta === 'string' ? JSON.parse(row.meta) : (row.meta ?? {});
     const rowObj = { ...row, meta };
     console.error(`[worker] 🔄 embedding  [${ts()}]  table=${table}  hash=${shortHash}…  ${row.path}:${row.name}`);
-    // 与 reindex 保持一致：优先用 content（语义模板），降级用 indexedRowToEmbedText
     const doc = row.content ?? indexedRowToEmbedText(rowObj);
     const vectors = await embedClient.embed([doc]);
     vector = vectors[0];

package/package.json

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