@lorrylurui/code-intelligence-mcp 2.0.4 → 2.0.6

package/dist/indexer/indexProject.js

@@ -3,7 +3,9 @@
  * 同时分析调用关系，填充 meta.callers / meta.callees。
  */
 import fg from 'fast-glob';
-import { join, resolve } from 'node:path';
+import * as babelParser from '@babel/parser';
+import * as bt from '@babel/types';
+import { dirname, join, resolve } from 'node:path';
 import { Node, Project } from 'ts-morph';
 import { readFileSync, existsSync } from 'node:fs';
 import { extractInterfaceOrTypeMeta, extractMetaFromCallable, } from './extractMeta.js';
@@ -12,6 +14,40 @@ import { parseJsFile } from './babelParser.js';
 import { isParamPlaceholder } from './paramPlaceholder.js';
 import { computeFileHash, computeSemanticHash } from './tsAstNormalizer.js';
 const CALLERS_LIMIT = 20;
+const BABEL_PLUGINS = [
+    'jsx',
+    'typescript',
+    'classPrivateMethods',
+    'classPrivateProperties',
+    'decorators-legacy',
+    'doExpressions',
+    'exportDefaultFrom',
+    'functionBind',
+    'logicalAssignment',
+    'nullishCoalescingOperator',
+    'objectRestSpread',
+    'optionalChaining',
+    'optionalCatchBinding',
+];
+function isCallerDebugEnabled() {
+    return /^(1|true|yes|on)$/i.test(process.env.DEBUG_CALLERS ?? '');
+}
+function getCallerDebugMatch() {
+    return (process.env.DEBUG_CALLERS_MATCH ?? '').trim().toLowerCase();
+}
+function shouldLogCallerDebug(parts) {
+    if (!isCallerDebugEnabled())
+        return false;
+    const match = getCallerDebugMatch();
+    if (!match)
+        return true;
+    return parts.some((part) => part?.toLowerCase().includes(match));
+}
+function logCallerDebug(stage, payload, parts) {
+    if (!shouldLogCallerDebug(parts))
+        return;
+    console.error(`[callers.debug] ${stage} ${JSON.stringify(payload)}`);
+}
 /** 判断文件类型 */
 function isJsFile(filePath) {
     return filePath.endsWith('.js') || filePath.endsWith('.jsx');
@@ -30,9 +66,9 @@ function mergeCallableMeta(symbolType, raw) {
     const paramTypeFields = raw.paramTypeFields;
     const { params: _p, paramTypeFields: _f, ...rest } = raw;
     if (symbolType === 'component' && params?.length) {
-        const props = [
-            ...new Set([...(paramTypeFields ?? []), ...params]),
-        ].filter((name) => name.toLowerCase() !== 'props' && !isParamPlaceholder(name)).sort();
+        const props = [...new Set([...(paramTypeFields ?? []), ...params])]
+            .filter((name) => name.toLowerCase() !== 'props' && !isParamPlaceholder(name))
+            .sort();
         return { ...rest, ...(props.length ? { props } : {}) };
     }
     return { ...rest, ...(params?.length ? { params } : {}) };
@@ -198,6 +234,142 @@ export const DEFAULT_IGNORE = [
     '**/dist-srv/**',
     '**/.turbo/**',
 ];
+function resolveImportedSourceFile(currentFilePath, moduleSpecifier) {
+    if (!moduleSpecifier.startsWith('.'))
+        return null;
+    const base = resolve(dirname(currentFilePath), moduleSpecifier);
+    const candidates = [
+        base,
+        `${base}.ts`,
+        `${base}.tsx`,
+        `${base}.js`,
+        `${base}.jsx`,
+        join(base, 'index.ts'),
+        join(base, 'index.tsx'),
+        join(base, 'index.js'),
+        join(base, 'index.jsx'),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+function applyRelationMaps(rows, callersMap, calleesMap) {
+    for (const row of rows) {
+        const key = `${row.name}|${row.path}`;
+        const callers = callersMap.get(key);
+        const callees = calleesMap.get(key);
+        if (callers?.size) {
+            row.meta.callers = [...callers].slice(0, CALLERS_LIMIT).map((s) => {
+                const [name, ...pathParts] = s.split('|');
+                return { name, path: pathParts.join('|') };
+            });
+        }
+        if (callees?.size) {
+            row.meta.callees = [...callees].slice(0, CALLERS_LIMIT).map((s) => {
+                const [name, ...pathParts] = s.split('|');
+                return { name, path: pathParts.join('|') };
+            });
+        }
+    }
+}
+function analyzeJsRelations(jsFiles, symbolMap, projectRoot, rows) {
+    const callersMap = new Map();
+    const calleesMap = new Map();
+    for (const filePath of jsFiles) {
+        const relPath = getRelativePathForDisplay(projectRoot, filePath);
+        const callerRows = rows.filter((row) => row.path === relPath);
+        if (callerRows.length === 0)
+            continue;
+        logCallerDebug('js-file-start', {
+            filePath,
+            relPath,
+            callerRows: callerRows.map((row) => row.name),
+        }, [filePath, relPath, ...callerRows.map((row) => row.name)]);
+        let ast;
+        try {
+            ast = babelParser.parse(readFileSync(filePath, 'utf-8'), {
+                sourceType: 'module',
+                plugins: [...BABEL_PLUGINS],
+                strictMode: false,
+            });
+        }
+        catch (error) {
+            console.error(`[analyzeJsRelations] Failed to parse ${filePath}:`, error);
+            continue;
+        }
+        for (const stmt of ast.program.body) {
+            if (!bt.isImportDeclaration(stmt))
+                continue;
+            const moduleSpecifier = stmt.source.value;
+            if (typeof moduleSpecifier !== 'string')
+                continue;
+            const importedFile = resolveImportedSourceFile(filePath, moduleSpecifier);
+            logCallerDebug('js-import-resolve', {
+                from: relPath,
+                moduleSpecifier,
+                importedFile,
+            }, [relPath, moduleSpecifier, importedFile]);
+            if (!importedFile)
+                continue;
+            const importedRelPath = getRelativePathForDisplay(projectRoot, importedFile);
+            const importedNames = stmt.specifiers
+                .map((spec) => {
+                if (bt.isImportSpecifier(spec)) {
+                    return bt.isIdentifier(spec.imported)
+                        ? spec.imported.name
+                        : spec.imported.value;
+                }
+                if (bt.isImportDefaultSpecifier(spec)) {
+                    return spec.local.name;
+                }
+                return null;
+            })
+                .filter((name) => Boolean(name));
+            logCallerDebug('js-import-specifiers', {
+                from: relPath,
+                moduleSpecifier,
+                importedRelPath,
+                importedNames,
+            }, [relPath, moduleSpecifier, importedRelPath, ...importedNames]);
+            for (const callerRow of callerRows) {
+                const callerKey = `${callerRow.name}|${callerRow.path}`;
+                for (const importedName of importedNames) {
+                    const targetKey = `${importedName}|${importedRelPath}`;
+                    const target = symbolMap.get(targetKey);
+                    logCallerDebug('js-import-target', {
+                        callerKey,
+                        targetKey,
+                        hit: Boolean(target),
+                        availableKeysInFile: [...symbolMap.keys()].filter((key) => key.endsWith(`|${importedRelPath}`)),
+                    }, [callerKey, targetKey, importedRelPath, importedName]);
+                    if (!target)
+                        continue;
+                    const calleeSet = calleesMap.get(callerKey) || new Set();
+                    calleeSet.add(`${target.name}|${target.path}`);
+                    calleesMap.set(callerKey, calleeSet);
+                    const callerSet = callersMap.get(`${target.name}|${target.path}`) ||
+                        new Set();
+                    callerSet.add(callerKey);
+                    callersMap.set(`${target.name}|${target.path}`, callerSet);
+                    logCallerDebug('js-link-added', {
+                        callerKey,
+                        calleeKey: `${target.name}|${target.path}`,
+                    }, [callerKey, target.name, target.path]);
+                }
+            }
+        }
+    }
+    applyRelationMaps(rows, callersMap, calleesMap);
+    for (const row of rows) {
+        logCallerDebug('js-row-final', {
+            row: `${row.name}|${row.path}`,
+            callers: row.meta.callers ?? [],
+            callees: row.meta.callees ?? [],
+        }, [row.name, row.path]);
+    }
+}
 /**
  * 按 glob 收集文件，用 ts-morph 加载并遍历每个文件的导出，生成全部代码块行。
  * 同时分析调用关系，填充 meta.callers / meta.callees。
@@ -269,6 +441,10 @@ export async function indexProject(opts) {
                             });
                         }
                         symbolMap.get(key).exports.add(exportName);
+                        logCallerDebug('symbol-map-add-ts', {
+                            key,
+                            exportName,
+                        }, [row.name, row.path, exportName]);
                     }
                 }
             }
@@ -291,6 +467,10 @@ export async function indexProject(opts) {
                     });
                 }
                 symbolMap.get(key).exports.add(row.name);
+                logCallerDebug('symbol-map-add-js', {
+                    key,
+                    exportName: row.name,
+                }, [row.name, row.path]);
             }
         }
         catch (e) {
@@ -307,6 +487,9 @@ export async function indexProject(opts) {
         project.addSourceFilesAtPaths(tsFiles);
         analyzeRelations(project, symbolMap, projectRoot, out);
     }
+    if (jsFiles.length > 0) {
+        analyzeJsRelations(jsFiles, symbolMap, projectRoot, out);
+    }
     return out;
 }
 /**
@@ -392,25 +575,13 @@ function analyzeRelations(project, symbolMap, projectRoot, rows) {
             }
         });
     }
-    // 写入 rows 的 meta
+    applyRelationMaps(rows, callersMap, calleesMap);
     for (const row of rows) {
-        const key = `${row.name}|${row.path}`;
-        const callers = callersMap.get(key);
-        const callees = calleesMap.get(key);
-        if (callers?.size) {
-            row.meta.callers = [...callers].slice(0, CALLERS_LIMIT).map((s) => {
-                // ✅ 反序列化回对象
-                const [name, ...pathParts] = s.split('|');
-                return { name, path: pathParts.join('|') };
-            });
-        }
-        if (callees?.size) {
-            row.meta.callees = [...callees].slice(0, CALLERS_LIMIT).map((s) => {
-                const [name, ...pathParts] = s.split('|');
-                // path:为了防止路径里万一含有 | 字符时截断错误。
-                return { name, path: pathParts.join('|') };
-            });
-        }
+        logCallerDebug('ts-row-final', {
+            row: `${row.name}|${row.path}`,
+            callers: row.meta.callers ?? [],
+            callees: row.meta.callees ?? [],
+        }, [row.name, row.path]);
     }
     console.error(`[analyzeRelations] processed ${rows.length} symbols`);
 }

package/dist/indexer/jsAstNormalizer.js

@@ -171,17 +171,32 @@ function traverseNode(node, cb) {
     }
 }
 export function inferBehaviorFromJS(node) {
-    const behavior = [];
+    const behavior = new Set();
+    const add = (label) => {
+        behavior.add(label);
+    };
     // 遍历 AST
     traverseNode(node, (n) => {
         // fetch / axios
         if (t.isCallExpression(n) && t.isIdentifier(n.callee)) {
             const name = n.callee.name.toLowerCase();
             if (name.includes('fetch') || name.includes('axios')) {
-                behavior.push('performs network request');
+                add('performs network request');
             }
             if (name.includes('settimeout')) {
-                behavior.push('uses timer');
+                add('uses timer');
+            }
+            if (name.includes('getscroll')) {
+                add('tracks scroll position');
+            }
+            if (name.includes('getoffset')) {
+                add('computes element offset');
+            }
+            if (name.includes('throttle')) {
+                add('throttles position updates');
+            }
+            if (name.includes('addeventlistener')) {
+                add('listens to viewport events');
             }
         }
         if (t.isCallExpression(n) &&
@@ -190,17 +205,32 @@ export function inferBehaviorFromJS(node) {
             const prop = n.callee.property.name;
             if (prop === 'getBoundingClientRect' ||
                 prop === 'getComputedStyle') {
-                behavior.push('reads dom layout');
+                add('reads dom layout');
             }
+            if (prop === 'addEventListener') {
+                add('listens to viewport events');
+            }
+        }
+        if (t.isIdentifier(n)) {
+            const name = n.name.toLowerCase();
+            if (name === 'offsettop' || name === 'offsetbottom') {
+                add('supports offset positioning');
+            }
+            if (name === 'scrolltop') {
+                add('tracks scroll position');
+            }
+        }
+        if (t.isStringLiteral(n) && n.value.toLowerCase() === 'fixed') {
+            add('uses fixed positioning');
         }
         // localStorage
         if (t.isMemberExpression(n) &&
             t.isIdentifier(n.object) &&
             n.object.name === 'localStorage') {
-            behavior.push('uses local storage');
+            add('uses local storage');
         }
     });
-    return Array.from(new Set(behavior));
+    return [...behavior].sort();
 }
 export function extractNormalizedSignatureJS(node) {
     if (t.isFunctionDeclaration(node) || t.isFunctionExpression(node)) {

package/dist/prompts/reusableCodeAdvisorPrompt.js

@@ -3,22 +3,30 @@ const REUSABLE_CODE_ADVISOR_DESCRIPTION = '在实现需求时检索并推荐最
 /** 与 SKILL.md 中 `# 可复用代码推荐` 起至约束、示例说明为止的正文一致（无 YAML frontmatter）。 */
 const REUSABLE_CODE_ADVISOR_MARKDOWN = `# 可复用代码推荐
 
-## 工作流
-
-当用户需要可复用代码或实现类需求时，按顺序执行：
-
-1. 如果用户是在找可复用组件，优先调用 recommend_component，由它完成候选搜索、结构过滤和排序。
-2. 只有当用户明确要求手动检索、或需要更细粒度控制时，才组合调用 search_symbols / search_by_structure / get_symbol_detail。
-3. 若仅凭摘要无法判断，对最相关的若干候选调用 get_symbol_detail 获取详情。
-4. 从以下维度对比候选：
-   - 与用户需求的**功能匹配度**
-   - **API 是否简单**、入参是否合适
-   - **依赖与副作用**风险
-   - **复用安全性**（稳定性、耦合度、是否便于扩展）
-5. 给出**唯一首选**推荐，并说明理由，同时使用 **AskUserQuestion** 工具，提供两个选项：
-   - 采纳推荐
-   - 取消
-6. 用户选择"采纳推荐"后，立即调用 inc_usage 工具记录该行为（symbolId 从搜索结果的 id 字段获取），不要遗漏此步骤。
+## 工作流（三级降级链，严格按序，每级有结果即终止）
+
+### 第一级：recommend_component（唯一首选）
+1. 用户询问可复用组件/函数/util/工具 → 必须先调用 \`recommend_component\`
+2. 返回 recommended != null → 将工具返回文本**原样输出**，**完全停止**，不得继续调用任何工具
+3. 返回 recommended = null → 进入第二级
+
+### 第二级：search_symbols（仅在第一级无结果时）
+4. 调用 \`search_symbols\`（semantic=true，传入原始 query）
+5. 返回非空结果 → 取第一条，按固定回复结构输出，**完全停止**
+6. 返回空结果 → 进入第三级
+
+### 第三级：输出无结果模板
+7. 直接输出无结果固定模板，**完全停止**
+8. 禁止进行 grep、read file、file search 等文件系统操作
+
+## 硬性约束
+
+- **不得跳过第一级直接调用 search_symbols**：对任何"帮我找 X""有没有 X"类问题，第一步永远是 \`recommend_component\`
+- **工具返回后不得自由发挥**：输出必须以工具返回结果为唯一事实来源，按模板格式输出，禁止改写为散文或追加额外检索过程
+- **禁止文件系统兜底**：MCP 三级链全部无结果后，只输出无结果模板，不读文件、不 grep
+- **禁止工作区外路径**：禁止引用或读取工作区外文件（如 \`/Users/.../not_git_private/...\`）
+- **禁止过程叙述**：不得输出"我先检索""Ran search_symbols""Read file"等过程描述
+- 用户选择"采纳推荐"后，立即调用 \`inc_usage\`（symbolId 从结果 id 字段获取）
 
 ## 不适用场景
 
@@ -30,32 +38,53 @@ const REUSABLE_CODE_ADVISOR_MARKDOWN = `# 可复用代码推荐
 ## 搜索结果判断
 
 根据 semanticSimilarity 决定推荐置信度：
-- **> 0.85**：高置信度，可直接推荐
-- **0.6 – 0.85**：中等置信度，需结合 description 和 get_symbol_detail 综合判断
-- **< 0.6**：低置信度，说明可能无合适实现，明确告知用户
+- **> 0.85**：高置信度，直接推荐
+- **0.6 – 0.85**：中等置信度，需结合 description 综合判断
+- **< 0.6**：低置信度，明确告知用户可能无合适实现
 - **空结果**：明确说"未找到已有实现"，不要凭空推荐
 
-## 回复结构
+## 回复结构（固定模板，不得改写）
+
+> ⚠️ 以下模板中的所有字段值（symbolId、使用范围、副作用、理由等）**均由 \`recommend_component\` 工具返回文本中已填好**，禁止自行推断或从代码文件中读取。LLM 只需将工具返回的文本**原样复制输出**，不得改写、补全或省略任何字段。
 
-按此结构输出（字段名可保留英文或改为中文小标题，二选一全文统一）：
+有结果时：
 
-- **首选：** <代码块名>
-- **使用范围：** 展示 meta.callers（被哪些模块调用），用于评估稳定性和适用范围；若无调用记录则显示"新增"
-- **副作用：** 展示 meta.sideEffects（network/timer/dom/storage/mutation），优先推荐无副作用的方案，标注有副作用的方案风险
-- **理由：** 1～3 条要点
-- **其他候选：** 简要列出及取舍（同步标注副作用）
-- **用法提示：** 结合用户场景的最小集成说明
-- **是否采纳：** 展示两个选项：选项1. 采纳推荐  选项2. 取消。等待用户确认
+首选：<符号名> — <文件路径>
+使用范围：<callers 或 "新增">
+副作用：<sideEffects 或 "无">
+理由：
+1. <要点1>
+2. <要点2>
+其他候选：<候选A（副作用）>; <候选B（副作用）>
+用法提示：
+<最小集成示例>
+是否采纳：
+1. 采纳推荐
+2. 取消
 
-## 约束
+> 输出上述模板后**等待用户在聊天框输入回复**，识别规则：
+> - 用户输入 **"1"、"采纳"、"采纳推荐"、"ok"、"好的"** 或类似确认词 → 从上方输出文本中读取 \`symbolId：<id>\` 那一行的值，立即调用 \`inc_usage\` 工具传入该 id，调用成功后回复"✓ 已记录使用，可直接集成"
+> - 用户输入 **"2"、"取消"、"不用了"** 或类似否定词 → 回复"好的，已取消"，停止
+> - 用户输入其他内容（如追问细节）→ 正常回答，回答结束后再次展示"是否采纳"选项
 
-- 优先推荐已有可复用代码块，避免轻易建议新写一套。
-- 若无合适代码块，明确说明，并给出最接近的选项及差距。
-- 推理简洁，面向落地实现。
+无结果时：
 
-## 更多示例
+首选：未找到已有实现
+使用范围：无
+副作用：无
+理由：
+1. 当前索引中没有满足条件的符号
+2. 已尝试可用检索方式，仍无可用候选
+其他候选：无
+用法提示：
+// 可先创建一个最小可复用实现
+是否采纳：
+1. 让我新建一个最小可复用实现
+2. 取消
 
-与仓库内 \`.cursor/skills/reusable-code-advisor/examples.md\` 中的示例一致（在 Cursor 或本地打开该文件查看）。
+> 输出上述模板后**等待用户在聊天框输入回复**，识别规则：
+> - 用户输入 **"1"、"新建"、"帮我创建"** 或类似确认词 → 进入新建流程，引导用户确认最小接口设计
+> - 用户输入 **"2"、"取消"、"不用了"** → 回复"好的，已取消"，停止
 `;
 export function registerReusableCodeAdvisorPrompt(server) {
     server.prompt('reusable-code-advisor', REUSABLE_CODE_ADVISOR_DESCRIPTION, {

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