@lorrylurui/code-intelligence-mcp 2.0.4 → 2.0.6

package/dist/services/recommendationService.js

@@ -1,10 +1,128 @@
+/**
+ * ──────────────────────────────────────────────────────────────────────────────
+ * [Agent 闭环流程总览]
+ *
+ * recommendComponent (核心 agent 主循环)
+ *
+ * 1. 解析输入，生成 query 变体（query rewrite，多轮尝试）
+ * 2. 对每个 query 变体依次尝试：
+ *    2.1. 搜索候选（优先语义，异常时回退关键词）
+ *    2.2. 结构字段补充搜索（props/hooks）
+ *    2.3. 合并去重、按 category 过滤、过滤不可复用项
+ *    2.4. 排序、Top-K 详情补查（enrich）
+ *    2.5. 质量门控（quality gate，必须命中 requiredProps/hooks 或高分）
+ *    2.6. 优先级调整（如名称/路径命中加分、demo 路径降权）
+ *    2.7. 命中则立即返回推荐结果，记录 debug trace
+ *    2.8. 未命中则进入下一 query 变体（自动重试）
+ * 3. 所有变体均未命中则返回无结果，debug trace 记录所有尝试
+ *
+ * 关键特性：
+ * - query rewrite + retry（自动多轮尝试）
+ * - 结构/语义/关键词多路融合
+ * - Top-K 详情补查
+ * - 质量门控与优先级调整
+ * - 全流程 debug trace（可用于 agent 反思/可观测性）
+ *
+ * 总结：
+ * “实现了一个单 agent 闭环推荐系统，支持 query 自动重写与多轮重试，融合语义/结构/关键词多路检索，Top-K 详情补查，质量门控与优先级调整，并输出全流程 debug trace，便于 agent 反思和可观测性。”
+ * ──────────────────────────────────────────────────────────────────────────────
+ */
 import { rankSemanticHits, rankSymbols } from './ranking.js';
+import { DEMO_PATH_PRIORITY_PENALTY, LITERAL_MATCH_PRIORITY_BOOST, MIN_LITERAL_MATCH_SCORE, MIN_RECOMMENDATION_SCORE, MIN_SEMANTIC_TEXT_MATCH_SCORE, REQUIRED_FIELD_FALLBACK_MIN_SCORE, } from '../config/tuning.js';
+/** 跳过原因标识 */
+const SKIPPED_REASON = {
+    NO_COMBINED: 'no_combined',
+    NO_QUALIFIED: 'no_qualified',
+};
+/** 查询方式标识 */
+const QUERIED_BY = {
+    SEMANTIC: 'semantic',
+    KEYWORD: 'keyword',
+};
+/** 回退原因标识 */
+const FALLBACK_REASON = {
+    SEMANTIC_ERROR: 'semantic_error_fallback_keyword',
+};
+/** 推荐结果文案 */
+const RECOMMENDATION_MESSAGE = {
+    FOUND: '已找到可复用组件候选，首选已按综合匹配度排序。',
+    NOT_FOUND: '未找到符合条件的可复用组件。',
+};
+/** 详情补查的 top-k 条数 */
+const ENRICH_TOP_K = 3;
+/** 最多取查询变体数量 */
+const MAX_QUERY_VARIANTS = 2;
+/** 结构/语义搜索 limit 倍数 */
+const STRUCTURE_LIMIT_MULTIPLIER = 4;
+/** 结构/语义搜索 limit 最小值 */
+const STRUCTURE_LIMIT_MIN = 12;
+/** 关键词搜索命中时的默认相似度补值 */
+const DEFAULT_KEYWORD_SIMILARITY = 0.55;
 function uniqueStrings(values = []) {
     return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
 }
+const QUERY_REWRITE_PATTERNS = [
+    /^帮我找(找)?(一个|一下)?/g,
+    /^有没有(现成的)?/g,
+    /^请推荐(一个|一下)?/g,
+    /可复用/g,
+    /现成的/g,
+    /封装好的/g,
+    /(组件|函数|hook|工具|util)(实现)?/gi,
+];
+/**
+ * 对原始查询进行清洗和变体生成，去掉无意义的词，提炼更核心的查询内容
+ */
+function buildQueryVariants(rawQuery) {
+    const base = rawQuery.trim();
+    if (!base)
+        return [];
+    let rewritten = base;
+    for (const pattern of QUERY_REWRITE_PATTERNS) {
+        rewritten = rewritten.replace(pattern, ' ');
+    }
+    rewritten = rewritten.replace(/\s+/g, ' ').trim();
+    if (!rewritten || rewritten === base) {
+        return [base];
+    }
+    return uniqueStrings([base, rewritten]);
+}
 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,84 +169,435 @@ 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'];
+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 === QUERIED_BY.SEMANTIC) {
+        return ((item.score >= MIN_RECOMMENDATION_SCORE.semantic &&
+            (item.reason.textMatch.score >= MIN_SEMANTIC_TEXT_MATCH_SCORE ||
+                hasRequiredFieldMatch)) ||
+            (hasLiteralMatch && item.score >= MIN_LITERAL_MATCH_SCORE));
+    }
+    return (item.score >= MIN_RECOMMENDATION_SCORE.keyword ||
+        (hasRequiredFieldMatch &&
+            item.score >= REQUIRED_FIELD_FALLBACK_MIN_SCORE));
+}
+function computeRecommendationPriority(item, query) {
+    let score = item.score;
+    const notes = [];
+    const path = item.symbol.path.toLowerCase();
+    if (hasStrongLiteralMatch(query, item.symbol)) {
+        score += LITERAL_MATCH_PRIORITY_BOOST;
+        notes.push('名称或文件名命中查询');
+    }
+    if (isDemoLikePath(path)) {
+        score -= DEMO_PATH_PRIORITY_PENALTY;
+        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;
     }
+    /**
+     * 根据查询和提示信息从仓库中获取候选结果，优先语义搜索并在出错时回退关键词搜索，返回搜索结果和相关的调试信息供后续处理使用。
+     * @param query 查询字符串
+     * @param searchTypes 搜索的符号类型
+     * @param preferSemantic 是否优先使用语义搜索
+     * @param limit 返回结果的数量限制
+     * @returns 包含搜索结果和调试信息的对象
+     */
+    async gatherSearchResults(query, searchTypes, preferSemantic, limit) {
+        let queriedBy = preferSemantic
+            ? QUERIED_BY.SEMANTIC
+            : QUERIED_BY.KEYWORD;
+        let fallbackReason = null;
+        if (preferSemantic) {
+            try {
+                const semanticGroups = await Promise.all(searchTypes.map((type) => this.repository.searchSemanticHits(query, {
+                    type,
+                    limit: Math.max(limit * STRUCTURE_LIMIT_MULTIPLIER, STRUCTURE_LIMIT_MIN),
+                })));
+                const searchResults = semanticGroups.flat();
+                return {
+                    queriedBy,
+                    searchResults,
+                    fallbackReason,
+                };
+            }
+            catch {
+                queriedBy = QUERIED_BY.KEYWORD;
+                fallbackReason = FALLBACK_REASON.SEMANTIC_ERROR;
+            }
+        }
+        const keywordGroups = await Promise.all(searchTypes.map((type) => this.repository.search(query, type)));
+        return {
+            queriedBy,
+            searchResults: keywordGroups
+                .flat()
+                .map((symbol) => ({ symbol, similarity: 0 })),
+            fallbackReason,
+        };
+    }
+    /**
+     * 对排名靠前的候选项进行详情补查
+     */
+    async enrichTopCandidatesWithDetail(ranked) {
+        const topSymbols = ranked
+            .slice(0, ENRICH_TOP_K)
+            .map((item) => item.symbol);
+        if (topSymbols.length === 0) {
+            return { ranked, enrichedCount: 0 };
+        }
+        const detailMap = new Map();
+        await Promise.all(topSymbols.map(async (symbol) => {
+            try {
+                const detail = await this.repository.getByName(symbol.name);
+                if (detail && detail.id === symbol.id) {
+                    detailMap.set(symbol.id, detail);
+                }
+            }
+            catch {
+                // 详情补查失败时继续主流程，避免影响推荐输出。
+            }
+        }));
+        if (detailMap.size === 0) {
+            return { ranked, enrichedCount: 0 };
+        }
+        const enriched = ranked.map((item) => {
+            const detail = detailMap.get(item.symbol.id);
+            return detail ? { ...item, symbol: detail } : item;
+        });
+        return {
+            ranked: enriched,
+            enrichedCount: detailMap.size,
+        };
+    }
+    /**
+     * Agent 主循环：根据输入生成 query 变体，依次尝试多轮检索，融合语义/结构/关键词，Top-K 详情补查，质量门控，优先级调整。
+     * 命中即返回推荐，否则遍历所有变体，最终输出 debug trace。
+     */
     async recommendComponent(input) {
+        this.logStart(input);
+        const { requiredProps, requiredHooks, structureFields, searchTypes, preferSemantic, limit, queryVariants, } = this.preprocessInput(input);
+        let queriedBy = preferSemantic
+            ? QUERIED_BY.SEMANTIC
+            : QUERIED_BY.KEYWORD;
+        let lastRankedCandidates = [];
+        let lastCombinedCount = 0;
+        let selectedQuery = null;
+        let fallbackReason = null;
+        const attempts = [];
+        this.logSearchTypes(searchTypes);
+        for (const queryVariant of queryVariants) {
+            const { attempt, combined, searchResults, gathered } = await this.tryQueryVariant({
+                queryVariant,
+                input,
+                searchTypes,
+                preferSemantic,
+                limit,
+                structureFields,
+                requiredProps,
+                requiredHooks,
+            });
+            queriedBy = gathered.queriedBy;
+            if (!fallbackReason && gathered.fallbackReason) {
+                fallbackReason = gathered.fallbackReason;
+            }
+            lastCombinedCount = combined.length;
+            this.logAttemptCheckpoint('attempt.summary', attempt);
+            if (combined.length === 0) {
+                attempt.skippedReason = SKIPPED_REASON.NO_COMBINED;
+                this.logAttemptCheckpoint('attempt.skipped.no_combined', attempt);
+                attempts.push(attempt);
+                continue;
+            }
+            const candidates = await this.rankAndEnrichCandidates({
+                combined,
+                searchResults,
+                queryVariant,
+                queriedBy,
+                requiredProps,
+                requiredHooks,
+                attempt,
+                limit,
+            });
+            lastRankedCandidates = candidates;
+            if (candidates.length > 0) {
+                selectedQuery = queryVariant;
+                attempts.push(attempt);
+                this.logAttemptCheckpoint('attempt.success', attempt);
+                this.logAttemptsTrace('recommendComponent.result.found', {
+                    selectedQuery,
+                    queriedBy,
+                    attempts,
+                    fallbackReason,
+                });
+                return this.buildResult({
+                    recommended: candidates[0] ?? null,
+                    alternatives: candidates.slice(1, limit),
+                    queriedBy,
+                    requiredProps,
+                    requiredHooks,
+                    attempts,
+                    selectedQuery,
+                    fallbackReason,
+                });
+            }
+            this.logAttemptCheckpoint('attempt.no_candidate_after_rank', attempt);
+            attempts.push(attempt);
+        }
+        this.logAttemptsTrace('recommendComponent.result.not_found', {
+            selectedQuery,
+            queriedBy,
+            attempts,
+            fallbackReason,
+        });
+        return this.buildResult({
+            recommended: null,
+            alternatives: [],
+            queriedBy,
+            requiredProps,
+            requiredHooks,
+            attempts,
+            selectedQuery,
+            fallbackReason,
+        });
+    }
+    logStart(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 ?? []));
+    }
+    logSearchTypes(searchTypes) {
+        console.error('[code-intelligence-mcp] recommendComponent.searchTypes types=%s', JSON.stringify(searchTypes));
+    }
+    preprocessInput(input) {
         const requiredProps = uniqueStrings(input.requiredProps);
         const requiredHooks = uniqueStrings(input.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;
-        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 queryVariants = buildQueryVariants(input.query).slice(0, MAX_QUERY_VARIANTS);
+        const res = {
+            requiredProps,
+            requiredHooks,
+            structureFields,
+            searchTypes,
+            preferSemantic,
+            limit,
+            queryVariants,
+        };
+        console.error('[code-intelligence-mcp] recommendComponent.preprocess queryVariants=%s requiredProps=%s requiredHooks=%s structureFields=%s searchTypes=%s preferSemantic=%s limit=%s', JSON.stringify(queryVariants), JSON.stringify(requiredProps), JSON.stringify(requiredHooks), JSON.stringify(structureFields), JSON.stringify(searchTypes), String(preferSemantic), String(limit));
+        return res;
+    }
+    async tryQueryVariant({ queryVariant, input, searchTypes, preferSemantic, limit, structureFields, requiredProps, requiredHooks, }) {
+        const gathered = await this.gatherSearchResults(queryVariant, searchTypes, preferSemantic, limit);
+        const searchResults = gathered.searchResults;
+        const attempt = {
+            query: queryVariant,
+            queriedBy: gathered.queriedBy,
+            searchCount: searchResults.length,
+            structureCount: 0,
+            combinedCount: 0,
+            qualifiedCount: 0,
+            detailEnrichedCount: 0,
+        };
         const structureResults = structureFields.length
-            ? await this.repository.searchByStructure(structureFields, {
-                type: 'component',
-                category: input.category,
-                limit: Math.max(limit * 4, 12),
-            })
+            ? (await Promise.all(searchTypes.map((type) => this.repository.searchByStructure(structureFields, {
+                type,
+                limit: Math.max(limit * STRUCTURE_LIMIT_MULTIPLIER, STRUCTURE_LIMIT_MIN),
+            })))).flat()
             : [];
-        const combined = mergeCandidates([
+        attempt.structureCount = structureResults.length;
+        const mergedBeforeCategory = mergeCandidates([
             ...structureResults,
             ...searchResults.map((item) => item.symbol),
-        ]).filter((symbol) => input.category
+        ]);
+        let combined = mergedBeforeCategory.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: '未找到符合条件的可复用组件。',
-            };
+        if (combined.length === 0 &&
+            input.category &&
+            mergedBeforeCategory.length) {
+            combined = mergedBeforeCategory;
+        }
+        const reusableCandidates = combined.filter(isReusableCandidate);
+        if (reusableCandidates.length > 0) {
+            combined = reusableCandidates;
         }
-        const ranked = queriedBy === 'semantic'
+        attempt.combinedCount = combined.length;
+        return { attempt, combined, searchResults, gathered };
+    }
+    async rankAndEnrichCandidates({ combined, searchResults, queryVariant, queriedBy, requiredProps, requiredHooks, attempt, limit, }) {
+        const ranked = queriedBy === QUERIED_BY.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));
+            })), queryVariant)
+            : rankSymbols(queryVariant, combined);
+        const enriched = await this.enrichTopCandidatesWithDetail(ranked);
+        const enrichedRanked = enriched.ranked;
+        attempt.detailEnrichedCount = enriched.enrichedCount;
+        const qualifiedRanked = enrichedRanked.filter((item) => isStrongEnoughRecommendation(item, queryVariant, queriedBy, requiredProps, requiredHooks));
+        attempt.qualifiedCount = qualifiedRanked.length;
+        if (qualifiedRanked.length === 0) {
+            attempt.skippedReason = SKIPPED_REASON.NO_QUALIFIED;
+        }
+        const prioritizedRanked = qualifiedRanked
+            .map((item) => {
+            const adjusted = computeRecommendationPriority(item, queryVariant);
+            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.rank query=%s queriedBy=%s enriched=%s qualified=%s candidates=%s', queryVariant, queriedBy, String(enrichedRanked.length), String(qualifiedRanked.length), String(candidates.length));
+        return candidates;
+    }
+    logAttemptCheckpoint(stage, attempt) {
+        console.error('[code-intelligence-mcp] recommendComponent.%s query=%s queriedBy=%s search=%s structure=%s combined=%s qualified=%s enriched=%s skipped=%s', stage, attempt.query, attempt.queriedBy, String(attempt.searchCount), String(attempt.structureCount), String(attempt.combinedCount), String(attempt.qualifiedCount), String(attempt.detailEnrichedCount), attempt.skippedReason ?? 'none');
+    }
+    logAttemptsTrace(stage, payload) {
+        console.error('[code-intelligence-mcp] %s selectedQuery=%s queriedBy=%s attempts=%s fallbackReason=%s', stage, payload.selectedQuery ?? 'none', payload.queriedBy, JSON.stringify(payload.attempts), payload.fallbackReason ?? 'none');
+    }
+    buildResult({ recommended, alternatives, queriedBy, requiredProps, requiredHooks, attempts, selectedQuery, fallbackReason, }) {
         return {
-            recommended: candidates[0] ?? null,
-            alternatives: candidates.slice(1, limit),
+            recommended,
+            alternatives,
             queriedBy,
             structureFilter: {
                 requiredProps,
                 requiredHooks,
             },
-            message: candidates.length > 0
-                ? '已找到可复用组件候选，首选已按综合匹配度排序。'
-                : '未找到符合条件的可复用组件。',
+            message: recommended !== null
+                ? RECOMMENDATION_MESSAGE.FOUND
+                : RECOMMENDATION_MESSAGE.NOT_FOUND,
+            debug: {
+                attempts,
+                selectedQuery,
+                retryUsed: attempts.length > 1,
+                fallbackReason,
+            },
         };
     }
 }

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);