@lorrylurui/code-intelligence-mcp 2.0.5 → 2.0.6

package/README.md

@@ -45,3 +45,106 @@
 
 MYSQL\*SYMBOLS_TABLE=frontend_collections_symbols
 INDEX_GLOB=xxx/\*\*/\_.{js,jsx,ts,tsx}
+
+# 召回效果优化
+
+你这个场景里，“召回优化”建议按 3 层做，效果最好：
+
+**1. 先把候选尽量捞全（Recall 层）**
+
+1. 提高语义检索候选池：把语义 `topK` 从现在的小值提高到 `50~200`，不要在第一层就截断太早。
+2. 语义 + 关键词并行召回：同时跑向量检索、名称/路径/描述关键词检索、结构字段检索（props/hooks/sideEffects），最后并集去重。
+3. 做查询扩展：`affix` 自动扩成 `fixed/sticky/offsetTop/offsetBottom/固钉/吸顶/吸底/固定定位`，提升召回覆盖率。
+4. 加别名词典：为组件建立别名（如 `Affix -> 固钉, 固定定位, sticky`），召回时强制并入。
+5. 路径先验加白名单：`Components/`、components这类目录可加权，`demo/examples/pages`不直接过滤，但降权。
+
+**2. 再做精排（Ranking 层）**
+
+1. 两阶段排序：第一阶段只看“能不能进池子”，第二阶段再做质量门槛。
+2. 显式命中强加权：用户 query 出现明确词（如 `affix`）时，名称/文件名命中要有明显 boost。
+3. 避免 usage 绑架：`usage_count` 只做弱特征，别让高 usage 的 demo/page 抢过真实组件。
+4. 引入轻量 reranker：对 Top-50 用交叉编码器或规则+LLM 打分，可明显提升 Top-1 准确率。
+
+**3. 建立评测闭环（Offline Eval）**
+
+1. 做一套 50~200 条真实查询集（中英混合、别名、口语化）。
+2. 每次改召回都跑：`Recall@10`、`Recall@50`、`MRR@10`、`nDCG@10`。
+3. 对失败样本做“误杀分析”：是没召回、被质量门槛挡掉、还是排序被 demo 抢位。
+
+你这个仓库当前最该优先做的 3 个点是：
+
+1. 把第一阶段候选池再放大（至少 50+）。
+2. 固化 query 扩展词典（Affix 这类高频组件先做）。
+3. 把质量门槛后移，先召回后精排，减少“找到了但被早期过滤掉”。
+
+如果你要，我可以下一步直接给你一版“可落地参数表”（每个阈值给默认值与调参范围），方便你马上 A/B。
+
+# 待优化项
+
+修复优先级：
+✅8
+✅5
+✅134 done，但是第二层embedding需要优化，llm fallback太慢+漂移，也需要调整模型
+✅6
+✅27
+
+1.  meta里面有多个信息，哪些做结构化过滤，哪些做向量检索？
+    结论：ast normalizers后拼一个语义模板，用这个模板内容生成向量
+    ❓做法见qa-doc/semantic-phrase.md
+2.  对于 class类型，content字段保留关键方法或摘要，而不是完全为空
+    最新修改：content赋值为语义模板
+3.  category过于模糊，
+    这三层怎么做：category 优先使用规则和 embedding 分类，
+    LLM 只作为 fallback，避免不稳定和成本问题
+    ❓做法见qa-doc/category.md
+4.  type category meta.kind 字段是否多余了？type只有5个值，
+    type表达代码结构、category表达语义结构，kind？
+    type： function / component / hook / class / type / interface
+    category：最新的三层结构（还没实现，只有文档）
+    kind: 现在跟type重叠较多，建议弱化meta.kind → 只保留特殊情况：
+    ❓改造方法qa-doc/type-category-kind.md
+5.  在ci做增量索引时，把changed files,如果是1000+文件，性能爆炸，考虑用file hash 判断？embedding也没有优化缓存？
+    ❓见qa-doc/ci-hash-solution 方案：🥈 file hash + ast normalizer hash，新增semantic_hash
+    - CI 增量（git changed files 触发）
+      只需要 semantic_hash
+      file_hash 可省，因为文件必然变了
+    - 每日全量扫描
+      file_hash 用来跳过 AST 解析（CPU 优化）
+      semantic_hash 用来跳过 embedding（费用优化）
+      content_hash 删掉，职责完全被 semantic_hash 覆盖
+6.  大仓问题：
+    ❓big-repo.md
+    - ci embedding解耦，新增embedding_status, ci时，全量写入status='pending'-> ci finish
+    - ci如果检测到文件删除，则对被删除的代码块标记delete（这里需要新增字段）
+    - node+redis 消费写embedding job
+    - 对语义模板semantic_hash做向量缓存，semantic_hash相同即功能未变
+    - 大仓分片并行
+7.  content暂时用不到，但也不用删除，目前暴利截取4000字符需要优化：
+    content（降级为辅助字段）：✔ 不参与 embedding✔ 不参与排序✔ 不参与过滤✔ 用于：1. LLM改造建议 2.debug 3.future rerank
+    最简单：只存 signature
+    最优：content = {
+    signature: "function fetchData(url, options)",
+    snippet: "核心逻辑代码（<=300行）",
+    keyCalls: ["fetch", "cache"]
+    }
+8.  TopK???，首先去掉usage过滤，再做两次topk,1.根据余弦相似度选topk 2.对1的结果用现有的usage,updated_at等加权排序
+    ❓topK.md
+    现在：SQL过滤(type) → ORDER BY usage_count DESC LIMIT 3000→ embedding 相似度排序→ 取 top20
+    这个逻辑不对，导致query: "debounce function"，debounce 使用少 ❌ fetch 很热门 ✅，结果Top3000里全是 fetch / request， debounce 被过滤掉 ❌
+
+👉 优点：
+• 不阻塞 CI
+• 可扩展
+
+6. 大仓问题呢？
+
+# 简历里还没做的优化
+
+1. embedding基石 - 语义模板模板，使用ast数据拼装语义模板
+2. class的content为null
+3. category分层 1.规则 2.预设所有种类，使用embedding召回 3.llm兜底
+4. type meta.kind逻辑优化，现在太重叠了
+5. ci-hash-solution
+6. 大仓问题
+7. content优化
+8. ✅topk优化

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