@lorrylurui/code-intelligence-mcp 2.0.5 → 2.0.7

package/dist/config/env.js

@@ -60,6 +60,15 @@ export const env = {
     get symbolsTable() {
         return process.env.SYMBOLS_TABLE ?? 'symbols';
     },
+    /**
+     * 文档 chunks 表名。
+     * 默认跟随 SYMBOLS_TABLE 派生，例如：symbols -> symbols_chunks，repo_a_symbols -> repo_a_symbols_chunks。
+     * 如需显式覆盖，仍可单独传入 CHUNKS_TABLE。
+     */
+    get chunksTable() {
+        const symbolsTable = process.env.SYMBOLS_TABLE ?? 'symbols';
+        return process.env.CHUNKS_TABLE ?? `${symbolsTable}_chunks`;
+    },
     /** Python FastAPI 嵌入服务根 URL，如 http://127.0.0.1:8765 */
     get embeddingServiceUrl() {
         return (process.env.EMBEDDING_SERVICE_URL ?? '').trim();

package/dist/config/tuning.js

@@ -0,0 +1,114 @@
+/**
+ * tuning.ts — 所有可调参数的集中配置。
+ *
+ * 生产环境中需要多次微调的阈值、权重和限制值均在此定义，
+ * 禁止在业务代码里直接写魔法数字。
+ */
+// ─── Chunk 切分参数 (chunkText.ts) ───────────────────────────────────────────
+/** 目标 chunk 字符数：达到此值后尽快在下一个边界处收敛当前块 */
+export const CHUNK_TARGET_CHARS = 900;
+/** 单个 chunk 最大字符数：超过此值必须做二次切分 */
+export const CHUNK_MAX_CHARS = 1200;
+/** 相邻 chunk 的重叠字符数：用于减少边界信息丢失 */
+export const CHUNK_OVERLAP_CHARS = 120;
+/** 句子/换行边界的最小位置比例：不足此比例则不回退到该边界，避免生成过短的 chunk */
+export const CHUNK_SENTENCE_BREAK_MIN_RATIO = 0.6;
+/** chunk 摘要的最大字符数（仅用于展示与 embedding 辅助信息） */
+export const CHUNK_SUMMARY_MAX_CHARS = 160;
+// ─── Chunk 语义检索参数 (chunkRepository.ts) ─────────────────────────────────
+/** 最低 cosine 相似度：低于此值的 chunk 不返回给调用方 */
+export const CHUNK_SIMILARITY_THRESHOLD = 0;
+/** 语义检索默认返回的 chunk 数量上限 */
+export const CHUNK_TOP_K = 8;
+// ─── Symbol 语义检索参数 (symbolRepository.ts) ───────────────────────────────
+/** 最低 cosine 相似度：低于此值的 symbol 不返回给调用方 */
+export const SYMBOL_SIMILARITY_THRESHOLD = 0;
+/** 语义检索默认返回的 symbol 数量上限 */
+export const SYMBOL_TOP_K = 20;
+// ─── Embedding 文本截断 (embedText.ts) ──────────────────────────────────────
+/** 源码片段送入 embedding 前的最大字符数，超出部分截断 */
+export const EMBED_MAX_CONTENT_LENGTH = 1200;
+// ─── 排名权重 (ranking.ts) ────────────────────────────────────────────────────
+/** 综合排名四维度权重，总和须为 1 */
+export const RANK_WEIGHTS = {
+    textMatch: 0.5,
+    usage: 0.3,
+    recency: 0.1,
+    commonPath: 0.1,
+};
+/** 每匹配到一个 callee 名称所增加的分数 */
+export const CALLEE_MATCH_SCORE_PER_MATCH = 0.05;
+/** callee 匹配分数的上限（防止大量 callee 匹配主导总分） */
+export const CALLEE_MATCH_SCORE_MAX = 0.2;
+/**
+ * Token 重叠度评分阶梯（按顺序匹配，首个满足条件的阶梯生效）。
+ * - minMatches: 查询 token 中至少命中的数量
+ * - minRatio: 命中比例下限
+ * - score: 对应的文本匹配分数
+ */
+export const TOKEN_OVERLAP_TIERS = [
+    { minMatches: 4, minRatio: 0.45, score: 0.78 },
+    { minMatches: 3, minRatio: 0.3, score: 0.68 },
+    { minMatches: 2, minRatio: 0.18, score: 0.56 },
+];
+/** 非 token-overlap 类型的文本匹配固定分数 */
+export const TEXT_MATCH_SCORES = {
+    nameContains: 0.85,
+    descriptionContains: 0.65,
+    weak: 0.2,
+};
+/**
+ * 时效性评分阶梯（按 maxDays 升序评估，首个满足条件的阶梯生效）。
+ * - maxDays: 创建距今天数上限
+ * - score: 对应的时效分数
+ */
+export const RECENCY_SCORE_TIERS = [
+    { maxDays: 7, score: 1.0 },
+    { maxDays: 30, score: 0.8 },
+    { maxDays: 90, score: 0.6 },
+    { maxDays: 180, score: 0.4 },
+];
+/** 无 createdAt 时使用的默认时效分数 */
+export const RECENCY_SCORE_DEFAULT = 0.4;
+/** createdAt 超出所有阶梯（>180天）时的最低时效分数 */
+export const RECENCY_SCORE_OLDEST = 0.25;
+/** 路径含 /common/ 或 /shared/ 的符号所获得的路径维度分数 */
+export const COMMON_PATH_SCORE_YES = 1;
+/** 路径不在 common/shared 目录时的路径维度分数 */
+export const COMMON_PATH_SCORE_NO = 0.35;
+/** 使用频率评分的 log 底数除数（值越大，曲线越平坦） */
+export const USAGE_SCORE_LOG_DIVISOR = 3;
+/** 语义相似度高于此值时，输出"语义相似度高"标签 */
+export const SEMANTIC_REASON_THRESHOLD_HIGH = 0.55;
+/** 语义相似度高于此值时，输出"语义相关"标签 */
+export const SEMANTIC_REASON_THRESHOLD_MED = 0.4;
+/** 使用频率分高于此值时，输出"使用频率高"标签 */
+export const USAGE_REASON_THRESHOLD_HIGH = 0.6;
+// ─── 推荐质量门控阈值 (recommendationService.ts) ─────────────────────────────
+/** 候选通过质量门控所需的最低综合分数 */
+export const MIN_RECOMMENDATION_SCORE = {
+    semantic: 0.5,
+    keyword: 0.45,
+};
+/** 语义模式下文本维度分数须达到的下限（用于高置信度路径） */
+export const MIN_SEMANTIC_TEXT_MATCH_SCORE = 0.6;
+/** 名称/路径字面命中时，放宽的综合分数下限 */
+export const MIN_LITERAL_MATCH_SCORE = 0.18;
+/** props/hooks 结构字段全部命中时，放宽的综合分数下限 */
+export const REQUIRED_FIELD_FALLBACK_MIN_SCORE = 0.4;
+/** 字面命中（名称或文件名匹配查询词）时，对优先级分数增加的值 */
+export const LITERAL_MATCH_PRIORITY_BOOST = 0.22;
+/** 路径为 demo/example 风格时，对优先级分数扣减的值 */
+export const DEMO_PATH_PRIORITY_PENALTY = 0.18;
+// ─── 搜索工具结果过滤 (tools/searchSymbols.ts) ───────────────────────────────
+/** 最终返回结果所需的最低综合评分 */
+export const SEARCH_SCORE_THRESHOLD = 0.45;
+/** 最终返回的 symbol 数量上限 */
+export const SEARCH_TOP_K = 20;
+// ─── RAG 上下文组装参数 (services/contextAssembler.ts) ───────────────────────
+/** 每个命中 chunk 向前后各扩展的邻块数量（减少边界截断信息丢失） */
+export const CONTEXT_ADJACENT_RADIUS = 1;
+/** 注入 prompt 的上下文总字符数预算（超出则从相似度最低的 chunk 开始截断） */
+export const CONTEXT_MAX_CHARS = 6000;
+/** 邻块扩展后保留的最大 chunk 数量 */
+export const CONTEXT_MAX_CHUNKS = 12;

package/dist/db/schema.js

@@ -49,3 +49,40 @@ export function getAllTableSQLs() {
         ...getSymbolsIndexSQLs(),
     ];
 }
+export function getChunksTableSQL() {
+    const tableName = env.chunksTable;
+    return `CREATE TABLE IF NOT EXISTS ${tableName} (
+  id            SERIAL PRIMARY KEY,
+  source_id     VARCHAR(255),
+  title         TEXT NOT NULL,
+  path          TEXT NOT NULL,
+  chunk_index   INT NOT NULL,
+  chunk_count   INT NOT NULL,
+  content       TEXT NOT NULL,
+  summary       TEXT,
+  category      VARCHAR(255),
+  meta          JSONB,
+  embedding     vector(384),
+  semantic_hash VARCHAR(64) NOT NULL,
+  status        SMALLINT NOT NULL DEFAULT ${DEFAULT_STATUS_ON_UPSERT},
+  created_at    TIMESTAMP NOT NULL DEFAULT NOW(),
+  updated_at    TIMESTAMP NOT NULL DEFAULT NOW(),
+  CONSTRAINT uk_${tableName}_path_chunk UNIQUE (path, chunk_index)
+)`;
+}
+export function getChunksIndexSQLs() {
+    const t = env.chunksTable;
+    return [
+        `CREATE INDEX IF NOT EXISTS idx_${t}_source_id ON ${t}(source_id)`,
+        `CREATE INDEX IF NOT EXISTS idx_${t}_semantic_hash ON ${t}(semantic_hash)`,
+        `CREATE INDEX IF NOT EXISTS idx_${t}_status ON ${t}(status)`,
+        `CREATE INDEX IF NOT EXISTS idx_${t}_path ON ${t}(path)`,
+    ];
+}
+export function getAllChunkTableSQLs() {
+    return [
+        getEnsureExtensionSQL(),
+        getChunksTableSQL(),
+        ...getChunksIndexSQLs(),
+    ];
+}

package/dist/indexer/chunkText.js

@@ -0,0 +1,164 @@
+import { createHash } from 'node:crypto';
+import { CHUNK_MAX_CHARS, CHUNK_OVERLAP_CHARS, CHUNK_SENTENCE_BREAK_MIN_RATIO, CHUNK_SUMMARY_MAX_CHARS, CHUNK_TARGET_CHARS, } from '../config/tuning.js';
+// 统一换行并去掉首尾空白，避免切分时混入无意义差异。
+function normalizeText(content) {
+    return content.replace(/\r\n/g, '\n').trim();
+}
+// 第一阶段：先按 Markdown 风格结构拆成 heading / paragraph / code 三类 block。
+function splitCodeAwareBlocks(content) {
+    const normalized = normalizeText(content);
+    if (!normalized)
+        return [];
+    const lines = normalized.split('\n');
+    const blocks = [];
+    let buffer = [];
+    let inCodeFence = false; // 追踪是否在代码块内，避免误把代码内容当普通文本切分。
+    const flushParagraphs = () => {
+        if (buffer.length === 0)
+            return;
+        const text = buffer.join('\n').trim();
+        buffer = [];
+        if (!text)
+            return;
+        const kind = text.startsWith('#') ? 'heading' : 'paragraph';
+        blocks.push({ kind, text });
+    };
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith('```')) {
+            if (inCodeFence) {
+                buffer.push(line);
+                blocks.push({ kind: 'code', text: buffer.join('\n').trim() });
+                buffer = [];
+                inCodeFence = false;
+            }
+            else {
+                flushParagraphs();
+                inCodeFence = true;
+                buffer.push(line);
+            }
+            continue;
+        }
+        if (inCodeFence) {
+            buffer.push(line);
+            continue;
+        }
+        if (trimmed.startsWith('#')) {
+            flushParagraphs();
+            blocks.push({ kind: 'heading', text: trimmed });
+            continue;
+        }
+        if (!trimmed) {
+            flushParagraphs();
+            continue;
+        }
+        buffer.push(line);
+    }
+    flushParagraphs();
+    return blocks;
+}
+// 第二阶段：如果某个单独 block 过长，再按自然边界做窗口切分，并保留 overlap。
+function sliceWithOverlap(text, maxChars, overlapChars) {
+    const normalized = text.trim();
+    if (!normalized)
+        return [];
+    if (normalized.length <= maxChars)
+        return [normalized];
+    const out = [];
+    let start = 0;
+    while (start < normalized.length) {
+        let end = Math.min(start + maxChars, normalized.length);
+        if (end < normalized.length) {
+            const window = normalized.slice(start, end);
+            // 优先回退到更自然的句子/换行边界，避免把一句话截成两半。
+            const sentenceBreak = Math.max(window.lastIndexOf('. '), window.lastIndexOf('。'), window.lastIndexOf('! '), window.lastIndexOf('? '), window.lastIndexOf('\n'));
+            if (sentenceBreak >
+                Math.floor(maxChars * CHUNK_SENTENCE_BREAK_MIN_RATIO)) {
+                // 边界不能太靠前，否则可能导致过多 chunk 和过短的上下文，设置一个阈值（如 maxChars 的 60%）来平衡。
+                end = start + sentenceBreak + 1;
+            }
+        }
+        out.push(normalized.slice(start, end).trim());
+        if (end >= normalized.length)
+            break;
+        start = Math.max(end - overlapChars, start + 1);
+    }
+    return out.filter(Boolean);
+}
+// 将当前累计 block 收敛成一个 chunk，并把末尾 overlap 作为下一块的前缀上下文。
+function finalizeChunk(chunks, currentBlocks, overlapChars) {
+    if (currentBlocks.length === 0)
+        return [];
+    const chunk = currentBlocks.join('\n\n').trim();
+    if (!chunk)
+        return [];
+    chunks.push(chunk);
+    if (overlapChars <= 0)
+        return [];
+    // 从上一个 chunk 末尾切出 overlapChars 长度的文本，作为下一 chunk 的前置上下文，减少边界信息丢失。
+    const tail = chunk.slice(-overlapChars).trim();
+    return tail ? [tail] : [];
+}
+// 对外主入口：结构切分优先，其次按 target/max 控制块大小，最后用 overlap 补边界。
+export function splitTextIntoChunks(content, options = {}) {
+    const targetChars = options.targetChars ?? CHUNK_TARGET_CHARS;
+    const maxChars = options.maxChars ?? CHUNK_MAX_CHARS;
+    const overlapChars = options.overlapChars ?? CHUNK_OVERLAP_CHARS;
+    // 1. 语义切分：按照结构拆分（eg: ```, #）
+    const blocks = splitCodeAwareBlocks(content);
+    if (blocks.length === 0)
+        return [];
+    const chunks = []; // 每一个元素是如下结构组成的字符串：0-首行，之后的索引对应值都是：上一个 chunk 的末尾 overlap 文本 + 当前 block 文本，块与块之间用双换行分隔。
+    let currentBlocks = [];
+    let currentLength = 0;
+    for (const block of blocks) {
+        // 2. 自然边界切分：每一个block再按照[.。!?、换行等]自然边界切分
+        const oversizedParts = block.text.length > maxChars
+            ? sliceWithOverlap(block.text, maxChars, overlapChars)
+            : [block.text];
+        for (const part of oversizedParts) {
+            // 3. overlap 滑动窗口：每当累计块接近目标大小或即将超出上限时，先把当前块收敛成一个 chunk，再开始下一块。每个新块的开头会带上前一个块末尾 overlapChars 长度的文本，减少边界信息丢失。
+            const additionLength = currentLength === 0 ? part.length : part.length + 2;
+            const wouldOverflowMax = currentLength > 0 && currentLength + additionLength > maxChars;
+            const reachedTarget = currentLength >= targetChars;
+            // 已接近目标大小或即将超出上限时，先收敛当前 chunk，再开始下一块。
+            if (wouldOverflowMax || reachedTarget) {
+                currentBlocks = finalizeChunk(chunks, currentBlocks, overlapChars);
+                currentLength = currentBlocks.join('\n\n').length;
+            }
+            currentBlocks.push(part);
+            currentLength = currentBlocks.join('\n\n').length;
+        }
+    }
+    finalizeChunk(chunks, currentBlocks, 0);
+    return chunks;
+}
+// 截取 chunk，做chunk embedding 时的摘要展示，提升检索结果的可读性和判断相关性的效率。
+function buildChunkSummary(content) {
+    const flattened = content.replace(/\s+/g, ' ').trim();
+    if (!flattened)
+        return null;
+    return flattened.slice(0, CHUNK_SUMMARY_MAX_CHARS);
+}
+// chunk hash 以 path + chunkIndex + content 生成，用于稳定标识具体分块。
+function computeChunkHash(path, chunkIndex, content) {
+    return createHash('sha256')
+        .update(`${path}#${chunkIndex}\n${content}`)
+        .digest('hex');
+}
+// 将原始文档输入转为可入库的 chunk 记录，附带索引、总块数、摘要和 semantic hash。
+export function buildDocumentChunks(document, options = {}) {
+    const chunks = splitTextIntoChunks(document.content, options);
+    return chunks.map((content, index) => ({
+        sourceId: document.sourceId ?? null,
+        title: document.title,
+        path: document.path,
+        chunkIndex: index,
+        chunkCount: chunks.length,
+        content,
+        summary: buildChunkSummary(content),
+        category: document.category ?? null,
+        meta: document.metadata ?? null,
+        semanticHash: computeChunkHash(document.path, index, content),
+    }));
+}

package/dist/indexer/embedText.js

@@ -1,5 +1,5 @@
 // 仅js类型使用，后续会删掉
-const MAX_CONTENT_LENGTH = 1200;
+import { EMBED_MAX_CONTENT_LENGTH } from '../config/tuning.js';
 function briefMeta(meta) {
     const keys = ['props', 'params', 'properties', 'hooks'];
     const parts = [];
@@ -23,7 +23,7 @@ export function indexedRowToEmbedText(row) {
         row.path,
         row.description ?? '',
         metaBit,
-        (row.content ?? '').slice(0, MAX_CONTENT_LENGTH),
+        (row.content ?? '').slice(0, EMBED_MAX_CONTENT_LENGTH),
     ]
         .filter((s) => s.length > 0)
         .join('\n');

package/dist/repositories/chunkRepository.js

@@ -0,0 +1,181 @@
+import { env } from '../config/env.js';
+import { CHUNK_SIMILARITY_THRESHOLD, CHUNK_TOP_K } from '../config/tuning.js';
+import { SEARCHABLE_STATUS, SYMBOL_STATUS } from '../config/symbolStatus.js';
+import { getPool } from '../db/postgres.js';
+import { getAllChunkTableSQLs } from '../db/schema.js';
+import { buildDocumentChunks } from '../indexer/chunkText.js';
+import { createEmbeddingClient, embedAll, } from '../services/embeddingClient.js';
+// 统一解析 pgvector 返回值，兼容字符串格式与数组格式。
+function parseEmbedding(raw) {
+    if (raw == null)
+        return null;
+    if (Array.isArray(raw)) {
+        const nums = raw.map((item) => Number(item)).filter(Number.isFinite);
+        return nums.length === raw.length ? nums : null;
+    }
+    if (typeof raw === 'string') {
+        try {
+            const parsed = JSON.parse(raw);
+            return parseEmbedding(parsed);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+// 将数据库行映射为业务层 chunk 对象。
+function toStoredChunk(row) {
+    return {
+        id: row.id,
+        sourceId: row.source_id,
+        title: row.title,
+        path: row.path,
+        chunkIndex: row.chunk_index,
+        chunkCount: row.chunk_count,
+        content: row.content,
+        summary: row.summary,
+        category: row.category,
+        meta: row.meta ? JSON.parse(row.meta) : null,
+        semanticHash: row.semantic_hash,
+        embedding: parseEmbedding(row.embedding),
+        similarity: row.similarity ? Number(row.similarity) : undefined,
+        createdAt: row.created_at ?? null,
+        updatedAt: row.updated_at ?? null,
+    };
+}
+// 保留标题/路径/摘要：chunk截取/正文：完整chunk信息
+function chunkToEmbeddingText(chunk) {
+    return [chunk.title, chunk.path, chunk.summary ?? '', chunk.content]
+        .filter(Boolean)
+        .join('\n');
+}
+export class ChunkRepository {
+    pool;
+    constructor() {
+        this.pool = getPool();
+    }
+    // 确保 chunk 表和索引存在，便于独立运行写入流程。
+    async ensureSchema() {
+        if (!this.pool)
+            return;
+        for (const sql of getAllChunkTableSQLs()) {
+            await this.pool.query(sql);
+        }
+    }
+    async upsertDocument(document, options = {}) {
+        if (!this.pool)
+            return [];
+        await this.ensureSchema();
+        // 先做语义切分，再加 overlap，得到一个文档的 chunk 列表。
+        const built = buildDocumentChunks(document, options);
+        if (built.length === 0)
+            return [];
+        let embeddings = built.map(() => null);
+        if (env.embeddingServiceUrl) {
+            // 批量 embedding，减少网络往返和 API 调用开销。
+            const client = createEmbeddingClient(env.embeddingServiceUrl);
+            embeddings = await embedAll(client, built.map(chunkToEmbeddingText));
+        }
+        const db = await this.pool.connect();
+        try {
+            await db.query('BEGIN');
+            // 先删旧版本再写新版本，避免同 path 的历史 chunk 混入召回。
+            const existing = await db.query(`SELECT id FROM ${env.chunksTable} WHERE path = $1`, [document.path]);
+            if (existing.rowCount && existing.rowCount > 0) {
+                await db.query(`DELETE FROM ${env.chunksTable} WHERE path = $1`, [document.path]);
+            }
+            const sql = `
+                INSERT INTO ${env.chunksTable}
+                  (source_id, title, path, chunk_index, chunk_count, content, summary, category, meta,
+                   embedding, semantic_hash, status)
+                VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9::jsonb, $10::vector, $11, $12)
+                RETURNING id, source_id, title, path, chunk_index, chunk_count, content, summary, category,
+                          meta::text AS meta, embedding, semantic_hash, status, created_at, updated_at
+            `;
+            const inserted = [];
+            for (let index = 0; index < built.length; index += 1) {
+                const chunk = built[index];
+                const embedding = embeddings[index];
+                const vecLiteral = Array.isArray(embedding)
+                    ? `[${embedding.join(',')}]`
+                    : null;
+                // 无向量时写为 pending，后续可以复用 worker 补齐向量。
+                const { rows } = await db.query(sql, [
+                    chunk.sourceId,
+                    chunk.title,
+                    chunk.path,
+                    chunk.chunkIndex,
+                    chunk.chunkCount,
+                    chunk.content,
+                    chunk.summary,
+                    chunk.category,
+                    JSON.stringify(chunk.meta),
+                    vecLiteral,
+                    chunk.semanticHash,
+                    vecLiteral ? SYMBOL_STATUS.ONLINE : SYMBOL_STATUS.PENDING,
+                ]);
+                inserted.push(toStoredChunk(rows[0]));
+            }
+            await db.query('COMMIT');
+            return inserted;
+        }
+        catch (error) {
+            await db.query('ROLLBACK');
+            throw error;
+        }
+        finally {
+            db.release();
+        }
+    }
+    async searchSemantic(query, opts) {
+        if (!env.embeddingServiceUrl) {
+            throw new Error('语义 chunk 检索需配置 EMBEDDING_SERVICE_URL');
+        }
+        if (!this.pool)
+            return [];
+        const limit = opts?.limit ?? CHUNK_TOP_K;
+        const client = createEmbeddingClient(env.embeddingServiceUrl);
+        // 查询先向量化，再在数据库中用 pgvector 做相似度排序。
+        const [queryVec] = await client.embed([query.trim()]);
+        if (!queryVec?.length) {
+            throw new Error('查询向量为空');
+        }
+        const params = [
+            `[${queryVec.join(',')}]`,
+            SEARCHABLE_STATUS,
+        ];
+        let sql = `
+            SELECT id, source_id, title, path, chunk_index, chunk_count, content, summary, category,
+                   meta::text AS meta, embedding, semantic_hash, status, created_at, updated_at,
+                   1 - (embedding <=> $1::vector) AS similarity
+            FROM ${env.chunksTable}
+            WHERE embedding IS NOT NULL
+              AND status = $2
+        `;
+        if (opts?.path) {
+            params.push(opts.path);
+            sql += ` AND path = $${params.length}`;
+        }
+        params.push(limit * 2);
+        sql += ` ORDER BY embedding <=> $1::vector LIMIT $${params.length}`;
+        const { rows } = await this.pool.query(sql, params);
+        return rows
+            .map(toStoredChunk)
+            .filter((chunk) => (chunk.similarity ?? 0) >= CHUNK_SIMILARITY_THRESHOLD)
+            .slice(0, limit);
+    }
+    // 命中 chunk 后取前后邻块，提升回答时上下文完整性。
+    async getAdjacentChunks(path, chunkIndex, radius = 1) {
+        if (!this.pool)
+            return [];
+        const { rows } = await this.pool.query(`
+                SELECT id, source_id, title, path, chunk_index, chunk_count, content, summary, category,
+                       meta::text AS meta, embedding, semantic_hash, status, created_at, updated_at
+                FROM ${env.chunksTable}
+                WHERE path = $1 AND chunk_index BETWEEN $2 AND $3
+                ORDER BY chunk_index ASC
+            `, [path, Math.max(0, chunkIndex - radius), chunkIndex + radius]);
+        return rows.map(toStoredChunk);
+    }
+}

package/dist/repositories/symbolRepository.js

@@ -1,9 +1,8 @@
 import { env } from '../config/env.js';
 import { getPool } from '../db/postgres.js';
+import { SYMBOL_SIMILARITY_THRESHOLD, SYMBOL_TOP_K } from '../config/tuning.js';
 import { createEmbeddingClient } from '../services/embeddingClient.js';
 import { SEARCHABLE_STATUS } from '../config/symbolStatus.js';
-const SIMILARITY_THRESHOLD = 0;
-const TOP_K = 20;
 const inMemorySymbols = [
     {
         id: 1,
@@ -188,7 +187,7 @@ export class SymbolRepository {
      * 不再需要在 Node 拉取全量向量做内存计算。
      */
     async searchSemanticHits(query, opts) {
-        console.error('[code-intelligence-mcp] repository.searchSemanticHits.start query=%s type=%s table=%s limit=%s threshold=%s searchableStatus=%s hasPool=%s', query, opts?.type ?? '', env.symbolsTable, String(opts?.limit ?? TOP_K), String(SIMILARITY_THRESHOLD), String(SEARCHABLE_STATUS), String(Boolean(this.pool)));
+        console.error('[code-intelligence-mcp] repository.searchSemanticHits.start query=%s type=%s table=%s limit=%s threshold=%s searchableStatus=%s hasPool=%s', query, opts?.type ?? '', env.symbolsTable, String(opts?.limit ?? SYMBOL_TOP_K), String(SYMBOL_SIMILARITY_THRESHOLD), String(SEARCHABLE_STATUS), String(Boolean(this.pool)));
         if (!env.embeddingServiceUrl) {
             console.error('[code-intelligence-mcp] repository.searchSemanticHits.error missingEmbeddingServiceUrl');
             throw new Error('语义检索需配置 EMBEDDING_SERVICE_URL 并启动嵌入服务');
@@ -197,7 +196,7 @@ export class SymbolRepository {
             console.error('[code-intelligence-mcp] repository.searchSemanticHits.noPool returnEmpty');
             return [];
         }
-        const limit = opts?.limit ?? TOP_K;
+        const limit = opts?.limit ?? SYMBOL_TOP_K;
         const client = createEmbeddingClient(env.embeddingServiceUrl);
         const [queryVec] = await client.embed([query.trim()]);
         if (!queryVec?.length) {
@@ -226,7 +225,7 @@ export class SymbolRepository {
             symbol: mapRow(r),
             similarity: Number(r.similarity),
         }));
-        const passed = mapped.filter((x) => x.similarity >= SIMILARITY_THRESHOLD);
+        const passed = mapped.filter((x) => x.similarity >= SYMBOL_SIMILARITY_THRESHOLD);
         console.error('[code-intelligence-mcp] repository.searchSemanticHits.db table=%s rawRows=%s passedThreshold=%s topRaw=%s', env.symbolsTable, String(rows.length), String(passed.length), JSON.stringify(mapped.slice(0, 5).map((x) => ({
             id: x.symbol.id,
             name: x.symbol.name,

package/dist/server/createServer.js

@@ -8,6 +8,7 @@ import { createSearchByStructureTool } from '../tools/searchByStructure.js';
 import { createIncUsageTool } from '../tools/incUsage.js';
 import { RecommendationService } from '../services/recommendationService.js';
 import { createRecommendComponentTool } from '../tools/recommendComponent.js';
+import { createQueryDocsTool } from '../tools/queryDocs.js';
 export function createServer() {
     console.error('[code-intelligence-mcp] createServer.init');
     const server = new McpServer({
@@ -39,6 +40,9 @@ export function createServer() {
     console.error('[code-intelligence-mcp] tool.registered %s', recommendComponentTool.name);
     registerReusableCodeAdvisorPrompt(server);
     console.error('[code-intelligence-mcp] prompt.registered reusable-code-advisor');
-    console.error('[code-intelligence-mcp] createServer.ready toolCount=6 promptCount=1');
+    const queryDocsTool = createQueryDocsTool();
+    server.tool(queryDocsTool.name, queryDocsTool.description, queryDocsTool.inputSchema, queryDocsTool.handler);
+    console.error('[code-intelligence-mcp] tool.registered %s', queryDocsTool.name);
+    console.error('[code-intelligence-mcp] createServer.ready toolCount=7 promptCount=1');
     return server;
 }