@lorrylurui/code-intelligence-mcp 2.0.5 → 2.0.7

package/dist/services/recommendationService.js

@@ -1,7 +1,92 @@
+/**
+ * ──────────────────────────────────────────────────────────────────────────────
+ * [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();
 }
@@ -113,12 +198,6 @@ const NON_REUSABLE_PATH_PATTERNS = [
     '.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
@@ -198,25 +277,26 @@ function hasStrongLiteralMatch(query, symbol) {
 function isStrongEnoughRecommendation(item, query, queriedBy, requiredProps, requiredHooks) {
     const hasRequiredFieldMatch = hasAllRequiredFields(item.symbol, requiredProps, requiredHooks);
     const hasLiteralMatch = hasStrongLiteralMatch(query, item.symbol);
-    if (queriedBy === 'semantic') {
+    if (queriedBy === QUERIED_BY.SEMANTIC) {
         return ((item.score >= MIN_RECOMMENDATION_SCORE.semantic &&
-            (item.reason.textMatch.score >= MIN_SEMANTIC_TEXT_SCORE ||
+            (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 >= 0.4));
+        (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 += 0.22;
+        score += LITERAL_MATCH_PRIORITY_BOOST;
         notes.push('名称或文件名命中查询');
     }
     if (isDemoLikePath(path)) {
-        score -= 0.18;
+        score -= DEMO_PATH_PRIORITY_PENALTY;
         notes.push('示例工程路径降权');
     }
     return {
@@ -231,125 +311,258 @@ export class RecommendationService {
     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 searchTypes = inferSearchTypes(input);
-        const preferSemantic = input.semantic ?? true;
-        const limit = input.limit ?? 5;
+    /**
+     * 根据查询和提示信息从仓库中获取候选结果，优先语义搜索并在出错时回退关键词搜索，返回搜索结果和相关的调试信息供后续处理使用。
+     * @param query 查询字符串
+     * @param searchTypes 搜索的符号类型
+     * @param preferSemantic 是否优先使用语义搜索
+     * @param limit 返回结果的数量限制
+     * @returns 包含搜索结果和调试信息的对象
+     */
+    async gatherSearchResults(query, searchTypes, preferSemantic, limit) {
         let queriedBy = preferSemantic
-            ? 'semantic'
-            : 'keyword';
-        let searchResults;
-        console.error('[code-intelligence-mcp] recommendComponent.searchTypes types=%s', JSON.stringify(searchTypes));
+            ? QUERIED_BY.SEMANTIC
+            : QUERIED_BY.KEYWORD;
+        let fallbackReason = null;
         if (preferSemantic) {
             try {
-                const semanticGroups = await Promise.all(searchTypes.map((type) => this.repository.searchSemanticHits(input.query, {
+                const semanticGroups = await Promise.all(searchTypes.map((type) => this.repository.searchSemanticHits(query, {
                     type,
-                    limit: Math.max(limit * 4, 12),
+                    limit: Math.max(limit * STRUCTURE_LIMIT_MULTIPLIER, STRUCTURE_LIMIT_MIN),
                 })));
-                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)),
-                }))));
+                const searchResults = semanticGroups.flat();
+                return {
+                    queriedBy,
+                    searchResults,
+                    fallbackReason,
+                };
             }
             catch {
-                queriedBy = 'keyword';
-                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,
-                }))));
+                queriedBy = QUERIED_BY.KEYWORD;
+                fallbackReason = FALLBACK_REASON.SEMANTIC_ERROR;
             }
         }
-        else {
-            const keywordGroups = await Promise.all(searchTypes.map((type) => this.repository.search(input.query, type)));
-            searchResults = keywordGroups
+        const keywordGroups = await Promise.all(searchTypes.map((type) => this.repository.search(query, type)));
+        return {
+            queriedBy,
+            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,
-            }))));
+                .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;
+        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 Promise.all(searchTypes.map((type) => this.repository.searchByStructure(structureFields, {
                 type,
-                limit: Math.max(limit * 4, 12),
+                limit: Math.max(limit * STRUCTURE_LIMIT_MULTIPLIER, STRUCTURE_LIMIT_MIN),
             })))).flat()
             : [];
-        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,
-        }))));
-        // 合并逻辑：先合并语义搜索（或关键词模糊搜索）和结构搜索结果去重
+        attempt.structureCount = structureResults.length;
         const mergedBeforeCategory = mergeCandidates([
             ...structureResults,
             ...searchResults.map((item) => item.symbol),
         ]);
-        // 再按 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: [],
-                queriedBy,
-                structureFilter: {
-                    requiredProps,
-                    requiredHooks,
-                },
-                message: '未找到符合条件的可复用组件。',
-            };
-        }
-        // 最后排序并切分首选/备选
-        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,
-            })), input.query)
-            : rankSymbols(input.query, combined);
-        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);
+            })), 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, input.query);
+            const adjusted = computeRecommendationPriority(item, queryVariant);
             return {
                 item,
                 adjustedScore: adjusted.score,
@@ -358,25 +571,33 @@ export class RecommendationService {
         })
             .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,
-        }))));
+        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/tools/queryDocs.js

@@ -0,0 +1,113 @@
+/**
+ * query_docs MCP 工具：完整的 RAG 检索 + 上下文组装入口。
+ *
+ * 调用链：
+ *   query
+ *     → ChunkRepository.searchSemantic()   向量检索 topK chunk
+ *     → ContextAssembler.assemble()         邻块扩展 → 去重 → 字符预算截断 → 文本渲染
+ *     → 返回 contextText + sources          供 LLM 合成最终回答
+ *
+ * 为什么工具只返回 contextText 而不直接生成回答？
+ *   本 MCP server 没有内置 LLM，"合成回答"由调用方（Claude/GPT 等）完成。
+ *   工具负责"检索 + 组装"，调用方负责"理解 + 生成"，职责清晰、可独立测试。
+ */
+import { z } from 'zod';
+import { ChunkRepository } from '../repositories/chunkRepository.js';
+import { ContextAssembler } from '../services/contextAssembler.js';
+import { CHUNK_TOP_K, CONTEXT_ADJACENT_RADIUS, CONTEXT_MAX_CHARS, CONTEXT_MAX_CHUNKS, } from '../config/tuning.js';
+export const queryDocsInput = z.object({
+    /** 自然语言查询，将被向量化后用于语义检索 */
+    query: z.string().min(1),
+    /** 语义检索拉取的候选 chunk 数，最终受字符预算限制 */
+    limit: z.number().int().min(1).max(50).optional().default(CHUNK_TOP_K),
+    /**
+     * 每个命中 chunk 向前后各扩展的邻块数。
+     * 0 = 不扩展（纯向量检索结果）；1 = 各取一块（推荐）；2 = 各取两块（长文档）
+     */
+    adjacentRadius: z
+        .number()
+        .int()
+        .min(0)
+        .max(3)
+        .optional()
+        .default(CONTEXT_ADJACENT_RADIUS),
+    /** 上下文总字符数预算，超出时截断末尾 chunk */
+    maxChars: z.number().int().min(500).optional().default(CONTEXT_MAX_CHARS),
+    /** 扩展后保留的最大 chunk 数量 */
+    maxChunks: z
+        .number()
+        .int()
+        .min(1)
+        .max(30)
+        .optional()
+        .default(CONTEXT_MAX_CHUNKS),
+    /** 仅检索指定文档路径下的 chunk（精确路径过滤） */
+    path: z.string().optional(),
+});
+export function createQueryDocsTool() {
+    const repo = new ChunkRepository();
+    const assembler = new ContextAssembler(repo);
+    return {
+        name: 'query_docs',
+        description: '对文档知识库进行语义检索，返回与查询最相关的文档片段（已组装为可直接注入 prompt 的上下文文本）。\n' +
+            '使用场景：\n' +
+            '- 查找 QA 文档、架构说明、设计决策等非代码知识\n' +
+            '- 需要引用具体文档原文回答时\n' +
+            '- 回答后请基于返回的 contextText 中的原文进行陈述，不要凭空补充\n' +
+            '注意：本工具检索文档 chunk，代码符号请使用 search_symbols / recommend_component。',
+        inputSchema: queryDocsInput.shape,
+        handler: async (input) => {
+            // ── 阶段1：语义检索 ─────────────────────────────────────────────
+            const hits = await repo.searchSemantic(input.query, {
+                limit: input.limit,
+                path: input.path,
+            });
+            if (hits.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                contextText: '',
+                                sources: [],
+                                hitCount: 0,
+                                totalChunks: 0,
+                                truncated: false,
+                                message: '未找到相关文档片段，请尝试调整查询或确认文档已建立索引。',
+                            }),
+                        },
+                    ],
+                };
+            }
+            // ── 阶段2：邻块扩展 + 去重 + 预算截断 + 文本渲染 ───────────────
+            const assembled = await assembler.assemble(hits, {
+                maxChars: input.maxChars,
+                adjacentRadius: input.adjacentRadius,
+                maxChunks: input.maxChunks,
+            });
+            // sources 供调用方引用来源，避免 LLM 伪造引用。
+            const sources = assembled.chunks.map((chunk) => ({
+                path: chunk.path,
+                title: chunk.title,
+                chunkIndex: chunk.chunkIndex,
+                chunkCount: chunk.chunkCount,
+                similarity: chunk.similarity ?? null,
+                summary: chunk.summary ?? null,
+            }));
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            contextText: assembled.contextText,
+                            sources,
+                            hitCount: assembled.hitCount,
+                            totalChunks: assembled.totalChunks,
+                            truncated: assembled.truncated,
+                        }),
+                    },
+                ],
+            };
+        },
+    };
+}

package/dist/tools/searchSymbols.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { rankSemanticHits, rankSymbols } from '../services/ranking.js';
 import { isReusableCandidate } from '../services/recommendationService.js';
+import { SEARCH_SCORE_THRESHOLD, SEARCH_TOP_K } from '../config/tuning.js';
 export const searchSymbolsInput = z.object({
     query: z.string().min(1),
     type: z
@@ -11,8 +12,8 @@ export const searchSymbolsInput = z.object({
     semantic: z.boolean().optional().default(false),
     limit: z.number().int().min(1).max(100).optional().default(20),
 });
-const SCORE_THRESHOLD_FOR_FINAL = 0.45; // 综合排序分阈值（语义相似度占50%权重，原始0.5相似度 ≈ 综合0.35起）
-const TOP_K_FOR_FINAL_RESULTS = 20; // 结果上限,返回相似度高的，保证数据质量
+const SCORE_THRESHOLD_FOR_FINAL = SEARCH_SCORE_THRESHOLD; // 综合排序分阈値（语义相似度占50%权重，原始0.5相似度≈综合60.35起）
+const TOP_K_FOR_FINAL_RESULTS = SEARCH_TOP_K; // 结果上限,返回相似度高的，保证数据质量
 function toRankedResult(item) {
     return {
         id: item.symbol.id,

package/dist/types/chunk.js

@@ -0,0 +1 @@
+export {};

package/package.json

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