semcode-mcp 0.1.0__tar.gz → 0.1.2__tar.gz

{semcode_mcp-0.1.0 → semcode_mcp-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: semcode-mcp
-Version: 0.1.0
+Version: 0.1.2
 Summary: Semantic code search MCP server: Tree-sitter AST chunking + voyage-code-3 embeddings + hybrid retrieval (sqlite-vec + FTS5 + RRF) + Voyage rerank-2.5 + call graph expansion
 Project-URL: Homepage, https://github.com/huawang1258/semantic-code-mcp
 Project-URL: Repository, https://github.com/huawang1258/semantic-code-mcp
@@ -51,7 +51,7 @@ Description-Content-Type: text/markdown
 
 「效果优先」技术栈：**Tree-sitter AST 切分 + voyage-code-3 embedding（int8 量化）+ sqlite-vec 向量库 + BM25 全文 + RRF 融合 + Voyage rerank-2.5 重排 + Call Graph 图扩展**。一个 `VOYAGE_API_KEY` 跑通 embedding + rerank 全链路。
 
-工程特性：**watchdog 文件实时监控 + 多工作区 LRU 管理 + MCP progress notification + cancel signal**。
+工程特性：**watchdog 文件实时监控 + 多工作区 LRU 管理 + MCP progress notification + 协程级取消**（取消后立即返回；已在飞的索引批次在后台跑完并持久化，不丢数据也不重复计费重建）。
 
 ## 架构
 
@@ -69,7 +69,7 @@ codebase_search(query, dir)
   Retriever ── 向量召回 + BM25召回 ── RRF融合 ── rerank（Voyage/Cohere）── Call Graph扩展 ── top_n 代码片段
         │
         ▼
-  MCP Server ── async tools + progress notification + cancel signal
+  MCP Server ── async tools + progress notification + 协程级取消
 ```
 
 | 模块 | 职责 |
@@ -186,7 +186,16 @@ npx 用法把 `command/args` 换成 `"npx", ["-y", "semcode-mcp"]`；
 | Cohere（可选后端） | 查询文本 + top-50 候选代码块全文 | 仅 `SCM_RERANK_BACKEND=cohere` 时；默认零发送 |
 | 自配 LLM 端点（可选，默认关） | 仅查询文本（不含代码） | `SCM_QUERY_EXPANSION=on` 时 |
 
-供应商对 API 数据的保留/训练策略请以其当前条款为准自行评估（Voyage/Cohere 均声明 API 数据默认不用于训练，本项目不替其背书）。
+### ⚠️ Voyage 数据条款（重要，索引闭源代码前必读）
+
+按 Voyage [TOS](https://www.voyageai.com/tos) Section 3(iii)（2026-07 复核）：
+
+- **默认（opt-out 前）提交内容可被 Voyage 用于训练和改进模型**
+- Opt-out 需要：账户绑定支付方式 + 组织 Admin 身份，dashboard → Terms of Service → 底部 toggle 切到 Opted Out
+- Opt-out 后为 zero-day retention（处理完即删），但**不追溯**之前提交的数据，且免费额度可能被作废
+- Batch API 上传的文件会保留 30 天（本工具不使用 Batch API）
+
+**用于公司/闭源代码前，先完成 opt-out 或使用全本地模式。** Cohere（可选 rerank 后端）条款请自行评估。
 
 ### 始终留在本地的
 

{semcode_mcp-0.1.0 → semcode_mcp-0.1.2}/README.md

@@ -4,7 +4,7 @@
 
 「效果优先」技术栈：**Tree-sitter AST 切分 + voyage-code-3 embedding（int8 量化）+ sqlite-vec 向量库 + BM25 全文 + RRF 融合 + Voyage rerank-2.5 重排 + Call Graph 图扩展**。一个 `VOYAGE_API_KEY` 跑通 embedding + rerank 全链路。
 
-工程特性：**watchdog 文件实时监控 + 多工作区 LRU 管理 + MCP progress notification + cancel signal**。
+工程特性：**watchdog 文件实时监控 + 多工作区 LRU 管理 + MCP progress notification + 协程级取消**（取消后立即返回；已在飞的索引批次在后台跑完并持久化，不丢数据也不重复计费重建）。
 
 ## 架构
 
@@ -22,7 +22,7 @@ codebase_search(query, dir)
   Retriever ── 向量召回 + BM25召回 ── RRF融合 ── rerank（Voyage/Cohere）── Call Graph扩展 ── top_n 代码片段
         │
         ▼
-  MCP Server ── async tools + progress notification + cancel signal
+  MCP Server ── async tools + progress notification + 协程级取消
 ```
 
 | 模块 | 职责 |
@@ -139,7 +139,16 @@ npx 用法把 `command/args` 换成 `"npx", ["-y", "semcode-mcp"]`；
 | Cohere（可选后端） | 查询文本 + top-50 候选代码块全文 | 仅 `SCM_RERANK_BACKEND=cohere` 时；默认零发送 |
 | 自配 LLM 端点（可选，默认关） | 仅查询文本（不含代码） | `SCM_QUERY_EXPANSION=on` 时 |
 
-供应商对 API 数据的保留/训练策略请以其当前条款为准自行评估（Voyage/Cohere 均声明 API 数据默认不用于训练，本项目不替其背书）。
+### ⚠️ Voyage 数据条款（重要，索引闭源代码前必读）
+
+按 Voyage [TOS](https://www.voyageai.com/tos) Section 3(iii)（2026-07 复核）：
+
+- **默认（opt-out 前）提交内容可被 Voyage 用于训练和改进模型**
+- Opt-out 需要：账户绑定支付方式 + 组织 Admin 身份，dashboard → Terms of Service → 底部 toggle 切到 Opted Out
+- Opt-out 后为 zero-day retention（处理完即删），但**不追溯**之前提交的数据，且免费额度可能被作废
+- Batch API 上传的文件会保留 30 天（本工具不使用 Batch API）
+
+**用于公司/闭源代码前，先完成 opt-out 或使用全本地模式。** Cohere（可选 rerank 后端）条款请自行评估。
 
 ### 始终留在本地的
 

{semcode_mcp-0.1.0 → semcode_mcp-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "semcode-mcp"
-version = "0.1.0"
+version = "0.1.2"
 description = "Semantic code search MCP server: Tree-sitter AST chunking + voyage-code-3 embeddings + hybrid retrieval (sqlite-vec + FTS5 + RRF) + Voyage rerank-2.5 + call graph expansion"
 readme = "README.md"
 license = "MIT"

{semcode_mcp-0.1.0 → semcode_mcp-0.1.2}/src/semantic_code_mcp/chunker.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 
 import hashlib
 import importlib
+import threading
 from dataclasses import dataclass, field
 from pathlib import Path
 
@@ -125,7 +126,9 @@ LINE_OVERLAP = 10
 MIN_CHUNK_LINES = 3
 MIN_CHUNK_CHARS = 40
 
-_PARSER_CACHE: dict = {}
+# per-thread parser 缓存：tree-sitter Parser 对象非线程安全，多 workspace
+# 并发 sync 时共享同一 parser 会产生数据竞争（错误解析/崩溃）
+_PARSER_TLS = threading.local()
 
 
 @dataclass
@@ -170,9 +173,12 @@ _LANG_MODULES = {
 
 
 def _get_parser(lang: str):
-    """获取并缓存 parser，失败返回 None（该语言回退按行切）。"""
-    if lang in _PARSER_CACHE:
-        return _PARSER_CACHE[lang]
+    """获取并缓存 parser（每线程独立），失败返回 None（该语言回退按行切）。"""
+    cache = getattr(_PARSER_TLS, "cache", None)
+    if cache is None:
+        cache = _PARSER_TLS.cache = {}
+    if lang in cache:
+        return cache[lang]
     parser = None
     spec = _LANG_MODULES.get(lang)
     if spec is not None:
@@ -183,7 +189,7 @@ def _get_parser(lang: str):
             parser = Parser(language)
         except Exception:
             parser = None
-    _PARSER_CACHE[lang] = parser
+    cache[lang] = parser
     return parser
 
 

{semcode_mcp-0.1.0 → semcode_mcp-0.1.2}/src/semantic_code_mcp/embedder.py

@@ -65,6 +65,9 @@ class Embedder:
         self._dim: int | None = None
         self._query_cache: OrderedDict[str, list[float]] = OrderedDict()
         self._query_cache_max = 32
+        # 缓存锁：多 workspace 并发检索共享同一 Embedder，OrderedDict 读改
+        # 无锁会在淘汰竞态下 KeyError（重复 miss 多发一次请求可接受，无害）
+        self._cache_lock = threading.Lock()
 
     @property
     def dim(self) -> int:
@@ -81,14 +84,32 @@ class Embedder:
 
     def embed_query(self, text: str) -> list[float]:
         """检索用：embedding 单条查询（带 LRU 缓存）。"""
-        if text in self._query_cache:
-            self._query_cache.move_to_end(text)
-            return self._query_cache[text]
-        result = self._embed([text], "query")[0]
-        self._query_cache[text] = result
-        if len(self._query_cache) > self._query_cache_max:
-            self._query_cache.popitem(last=False)
-        return result
+        return self.embed_queries([text])[0]
+
+    def embed_queries(self, texts: list[str]) -> list[list[float]]:
+        """检索用：批量 embedding 多条查询，与输入一一对应。
+
+        复合查询主查询 + 子查询合并成一次请求（省 N-1 次网络往返）；
+        命中缓存的不重发，只有未命中子集上行。
+        """
+        with self._cache_lock:
+            cached = {t: self._query_cache[t] for t in texts if t in self._query_cache}
+            for t in cached:
+                self._query_cache.move_to_end(t)
+        missing = [t for t in dict.fromkeys(texts) if t not in cached]
+        fresh: dict[str, list[float]] = {}
+        if missing:
+            # 网络调用在锁外：持锁发请求会把并发查询串行化
+            for t, vec in zip(missing, self._embed(missing, "query")):
+                fresh[t] = vec
+            with self._cache_lock:
+                for t, vec in fresh.items():
+                    self._query_cache[t] = vec
+                    self._query_cache.move_to_end(t)
+                while len(self._query_cache) > self._query_cache_max:
+                    self._query_cache.popitem(last=False)
+        # 输出只从本地快照组装，不依赖缓存在锁外的存活性（并发淘汰不影响正确性）
+        return [cached[t] if t in cached else fresh[t] for t in texts]
 
     def _embed(self, texts: list[str], input_type: str) -> list[list[float]]:
         results: list[list[float]] = []
@@ -155,6 +176,10 @@ class LocalEmbedder:
         self._dim: int | None = None
         self._query_cache: OrderedDict[str, list[float]] = OrderedDict()
         self._query_cache_max = 32
+        # 与 Embedder 同款缓存锁；另加 encode 串行锁——SentenceTransformer 推理
+        # 非线程安全，且 CPU 推理并发也无吞吐收益
+        self._cache_lock = threading.Lock()
+        self._encode_lock = threading.Lock()
 
     @property
     def dim(self) -> int:
@@ -164,25 +189,39 @@ class LocalEmbedder:
 
     def embed_documents(self, texts: list[str]) -> list[list[float]]:
         clipped = [(t or " ")[:_MAX_CHARS_PER_TEXT] for t in texts]
-        embs = self.st.encode(
-            clipped, batch_size=self.batch_size,
-            normalize_embeddings=True, show_progress_bar=False,
-        )
+        with self._encode_lock:
+            embs = self.st.encode(
+                clipped, batch_size=self.batch_size,
+                normalize_embeddings=True, show_progress_bar=False,
+            )
         return [e.tolist() for e in embs]
 
     def embed_query(self, text: str) -> list[float]:
-        if text in self._query_cache:
-            self._query_cache.move_to_end(text)
-            return self._query_cache[text]
+        with self._cache_lock:
+            if text in self._query_cache:
+                self._query_cache.move_to_end(text)
+                return self._query_cache[text]
         kwargs = {"normalize_embeddings": True, "show_progress_bar": False}
         if self._query_prompt:
             kwargs["prompt_name"] = self._query_prompt
-        result = self.st.encode([text[:_MAX_CHARS_PER_TEXT]], **kwargs)[0].tolist()
-        self._query_cache[text] = result
-        if len(self._query_cache) > self._query_cache_max:
-            self._query_cache.popitem(last=False)
+        with self._encode_lock:
+            # double-check：排队等锁期间同 key 可能已被先行线程算完，
+            # 不查会让 N 个并发同 key 请求重复推理 N 次（本地模型延迟放大）
+            with self._cache_lock:
+                if text in self._query_cache:
+                    self._query_cache.move_to_end(text)
+                    return self._query_cache[text]
+            result = self.st.encode([text[:_MAX_CHARS_PER_TEXT]], **kwargs)[0].tolist()
+        with self._cache_lock:
+            self._query_cache[text] = result
+            while len(self._query_cache) > self._query_cache_max:
+                self._query_cache.popitem(last=False)
         return result
 
+    def embed_queries(self, texts: list[str]) -> list[list[float]]:
+        """与 Embedder.embed_queries 同接口；本地推理无网络往返，逐条等价。"""
+        return [self.embed_query(t) for t in texts]
+
 
 def create_embedder(**kwargs):
     """按 SCM_EMBED_BACKEND 选择后端：voyage（默认）/ local。"""

{semcode_mcp-0.1.0 → semcode_mcp-0.1.2}/src/semantic_code_mcp/indexer.py

@@ -43,6 +43,9 @@ SKIP_FILENAMES = {
 }
 # agent 指导文件：架构/规范信息密度最高，很多仓库把它们 gitignore 了，索引时豁免
 FORCE_INCLUDE_FILENAMES = {"AGENTS.md", "CLAUDE.md", "GEMINI.md", "AGENT.md", ".windsurfrules", ".cursorrules"}
+# 点目录白名单：隐藏目录默认全排除，但 CI workflow / agent 配置的检索价值高
+# （"发布流程在哪定义"类查询必需）；仍受 gitignore 约束
+DOT_DIR_ALLOWLIST = {".github", ".gitlab", ".windsurf", ".devin", ".claude", ".cursor", ".codex", ".agent"}
 # 单批 embedding 的最大累计块数（跨文件合并，减少 API 往返）
 BATCH_CHUNKS = 256
 
@@ -116,10 +119,10 @@ class _EmbedPipeline:
         offset = 0
         for fp, fh, mt, sz, cs in batch:
             n = len(cs)
-            if n:
-                store.add_chunks(cs, embeddings[offset:offset + n])
-                offset += n
-            store.set_file_hash(fp, fh, mtime=mt, size=sz)
+            # 单事务原子替换：删旧 + 插新 + 指纹，中途崩溃整体回滚，
+            # 不会出现旧数据已删但新数据未写的中间态
+            store.replace_file(fp, cs, embeddings[offset:offset + n], fh, mtime=mt, size=sz)
+            offset += n
         if self.on_write:
             self.on_write(len(batch), len(all_chunks))
 
@@ -189,7 +192,8 @@ class Indexer:
         for dirpath, dirnames, filenames in os.walk(self.root):
             dirnames[:] = [
                 d for d in dirnames
-                if d not in DEFAULT_IGNORE_DIRS and not d.startswith(".")
+                if d not in DEFAULT_IGNORE_DIRS
+                and (not d.startswith(".") or d in DOT_DIR_ALLOWLIST)
             ]
             if ".gitignore" in filenames:
                 gi = Path(dirpath) / ".gitignore"
@@ -242,10 +246,11 @@ class Indexer:
 
     def _iter_source_files(self):
         for dirpath, dirnames, filenames in os.walk(self.root):
-            # 原地过滤忽略目录与隐藏目录
+            # 原地过滤忽略目录与隐藏目录（白名单内的点目录放行）
             dirnames[:] = [
                 d for d in dirnames
-                if d not in DEFAULT_IGNORE_DIRS and not d.startswith(".")
+                if d not in DEFAULT_IGNORE_DIRS
+                and (not d.startswith(".") or d in DOT_DIR_ALLOWLIST)
             ]
             for fn in filenames:
                 p = Path(dirpath) / fn
@@ -308,7 +313,7 @@ class Indexer:
         buf_chunks = 0
         try:
             for done, (fp, fh, mt, sz) in enumerate(to_index, 1):
-                self.store.delete_file(fp)
+                # 不提前删旧数据：由 replace_file 在写回时单事务完成删+插
                 chunks = chunk_file(fp)
                 chunks_total += len(chunks)
                 buf.append((fp, fh, mt, sz, chunks))
@@ -397,7 +402,7 @@ class Indexer:
         buf_chunks = 0
         try:
             for done, (fp, fh, mt, sz) in enumerate(to_index, 1):
-                self.store.delete_file(fp)
+                # 不提前删旧数据：由 replace_file 在写回时单事务完成删+插
                 chunks = chunk_file(fp)
                 buf.append((fp, fh, mt, sz, chunks))
                 buf_chunks += len(chunks)

{semcode_mcp-0.1.0 → semcode_mcp-0.1.2}/src/semantic_code_mcp/retriever.py

@@ -17,6 +17,7 @@ import fnmatch
 import os
 import re
 import time
+from concurrent.futures import ThreadPoolExecutor
 
 from .embedder import Embedder
 from .expander import create_expander
@@ -141,12 +142,19 @@ _COMPOUND_SUB_WEIGHT = 0.7
 _COMPOUND_PROBE_TOP = 10
 # 子查询 rerank 分数混合：探针块用整句 rerank 分天然吃亏（"清理 100 天"
 # 在整句里只占小半权重），单独用子查询文本再 rerank 一次，
-# 最终分取 max(整句分, 子查询分 × 此系数)
-_COMPOUND_SUB_RERANK_MIX = 0.9
-# 子查询分参与混合/保底的最低门槛：实测"清理"这种宽泛短词的字面命中
-# （clearCache/clear 工具方法）全部 ≤0.14，真业务清理实现 ≥0.22，
-# 0.2 是天然分界线；低于门槛的子查询信号不参与任何提分
-_COMPOUND_SUB_MIN_SCORE = 0.2
+# 混合分 = 整句 top 分 × 子查询相对强度 × 此系数（子意图最佳代表
+# ≈ 整句最佳的 95 折；Voyage 分数域窄，0.9 的提拔量不足以越过
+# 中间名次的密集分数带，0.95 实测 K1 探针 rank5→rank4）
+_COMPOUND_SUB_RERANK_MIX = 0.95
+# 子查询分参与混合/保底的最低门槛，按 rerank 后端分档标定（分数分布不同，
+# 绝对阈值跨后端不通用）：
+# - cohere（rerank-v3.5）分布宽：实测"清理"这种宽泛短词的字面命中
+#   （clearCache/clear 工具方法）全部 ≤0.14，真业务清理实现 ≥0.22，0.2 是分界线
+# - voyage（rerank-2.5）分布窄且整体偏高：无关块 <0.5，字面噪声（0.63）与
+#   真业务（0.645）重叠不可分——0.55 只拦"彻底无关"，字面噪声由
+#   "子意图已有代表则不动"（6.5）与 must_contain 探针兜底
+_COMPOUND_SUB_MIN_SCORE = {"voyage": 0.55, "cohere": 0.2}
+_COMPOUND_SUB_MIN_DEFAULT = 0.2
 
 
 class Retriever:
@@ -355,7 +363,10 @@ class Retriever:
         把调用者/被调用者作为关联结果附加（带 relation 字段）。
         """
         # 1. 向量召回 + 2. BM25 召回（原查询）
-        q_emb = self.embedder.embed_query(query)
+        # 复合查询提前拆分，主查询 + 子查询合批一次 embed（省 N-1 次往返）
+        subs = self._compound_subqueries(query)
+        embs = self.embedder.embed_queries([query, *subs])
+        q_emb, sub_embs = embs[0], embs[1:]
         rank_lists = [
             [cid for cid, _ in self.store.search_vector(q_emb, top_k)],
             [cid for cid, _ in self.store.search_fts(query, top_k)],
@@ -386,10 +397,9 @@ class Retriever:
                 weights.append(weights[0])
         # 2.9 复合意图拆分（"生成+清理"）：单次向量召回对双动作查询天然偏科，
         #     各子查询独立召回后低权重并入 RRF，两个意图都能拿到席位
-        subs = self._compound_subqueries(query)
+        min_sub = _COMPOUND_SUB_MIN_SCORE.get(self.rerank_backend, _COMPOUND_SUB_MIN_DEFAULT)
         sub_probes: list[list[int]] = []  # 每个子查询自己的前 N 名（保底探针/分数混合用）
-        for sub in subs:
-            s_emb = self.embedder.embed_query(sub)
+        for sub, s_emb in zip(subs, sub_embs):
             sub_lists = [[cid for cid, _ in self.store.search_vector(s_emb, top_k)]]
             sub_fts = (
                 self.store.search_fts_trigram(sub, top_k)
@@ -438,22 +448,29 @@ class Retriever:
             #     子查询文本打分才能反映它对那半意图的真实相关性
             if subs and sub_probes:
                 by_id = {c.get("id"): c for c in candidates}
-                for sub, probe in zip(subs, sub_probes):
-                    sub_cands = [by_id[cid] for cid in probe if cid in by_id]
-                    if not sub_cands:
-                        continue
-                    try:
-                        scored = self._rerank(sub, sub_cands, len(sub_cands))
-                    except Exception:
-                        continue
+                # 混合量纲锚定整句 top 分：Voyage 分数域窄（整句/子查询分都挤在
+                # 0.5-0.8，裸子查询分 ×0.9 永远赢不了整句分，混合失效）；
+                # 改为整句 top × 子查询相对强度，两后端语义一致：
+                # 子查询的最佳代表 ≈ 整句最佳的 _COMPOUND_SUB_RERANK_MIX 折
+                full_top = max((c.get("score", 0.0) for c in candidates), default=0.0)
+                tasks = [
+                    (sub, [by_id[cid] for cid in probe if cid in by_id])
+                    for sub, probe in zip(subs, sub_probes)
+                ]
+                tasks = [(s, c) for s, c in tasks if c]
+                scored_lists = self._rerank_many(tasks)
+                for (sub, _), scored in zip(tasks, scored_lists):
+                    sub_top = max((s["score"] for s in scored), default=0.0)
                     for s in scored:
                         c = by_id.get(s.get("id"))
                         if c is None:
                             continue
                         c["_sub_score"] = max(c.get("_sub_score", 0.0), s["score"])
-                        if s["score"] >= _COMPOUND_SUB_MIN_SCORE:
+                        if s["score"] >= min_sub and sub_top > 0:
                             c["score"] = max(
-                                c["score"], s["score"] * _COMPOUND_SUB_RERANK_MIX
+                                c["score"],
+                                full_top * (s["score"] / sub_top)
+                                * _COMPOUND_SUB_RERANK_MIX,
                             )
         # 4.5 调用链意图：结构化命中注入高分（并入统一打分管线，测试调用方会被后续降权拆开）
         intent_hits = self._caller_intent_hits(query)
@@ -548,7 +565,7 @@ class Retriever:
                     (
                         by_id[cid] for cid in probe
                         if cid in by_id and cid not in rescued_ids
-                        and by_id[cid].get("_sub_score", 0.0) >= _COMPOUND_SUB_MIN_SCORE
+                        and by_id[cid].get("_sub_score", 0.0) >= min_sub
                         and not (path_filter and not self._path_match(
                             by_id[cid].get("file_path", ""), path_filter))
                     ),
@@ -657,6 +674,22 @@ class Retriever:
                 scores[doc_id] = scores.get(doc_id, 0.0) + w / (k + rank + 1)
         return sorted(scores.items(), key=lambda x: x[1], reverse=True)
 
+    def _rerank_many(self, tasks: list[tuple[str, list[dict]]]) -> list[list[dict]]:
+        """批量 rerank（子查询分数混合用），失败项降级为空列表。
+
+        多个子查询并行发送（纯网络 IO，省一次往返延迟）；
+        评测限速场景（SCM_RERANK_MIN_INTERVAL>0）保持串行，不破坏全局请求间隔。"""
+        def one(sub: str, cands: list[dict]) -> list[dict]:
+            try:
+                return self._rerank(sub, cands, len(cands))
+            except Exception:
+                return []
+
+        if len(tasks) > 1 and _rerank_min_interval() <= 0:
+            with ThreadPoolExecutor(max_workers=len(tasks)) as ex:
+                return list(ex.map(lambda t: one(*t), tasks))
+        return [one(s, c) for s, c in tasks]
+
     def _rerank(self, query: str, candidates: list[dict], top_n: int) -> list[dict]:
         docs = [self._doc_text(c) for c in candidates]
         min_interval = _rerank_min_interval()

{semcode_mcp-0.1.0 → semcode_mcp-0.1.2}/src/semantic_code_mcp/server.py

@@ -8,7 +8,7 @@
   - 多工作区 LRU 管理（SCM_MAX_WORKSPACES，默认 8）
   - watchdog 文件监控 + 2s debounce（SCM_WATCH=0 禁用）
   - MCP progress notification（索引进度实时回报）
-  - Cancel signal 支持（客户端取消即刻中止）
+  - 协程级取消（取消后立即返回；已在飞的索引批次后台跑完并持久化，不丢数据）
   - 首次全量索引 / 后续 watcher 增量（O(变更数) 极速）
 """
 from __future__ import annotations

{semcode_mcp-0.1.0 → semcode_mcp-0.1.2}/src/semantic_code_mcp/store.py

@@ -38,10 +38,16 @@ def _is_boilerplate_symbol(name: str) -> bool:
     return bool(_ACCESSOR_RE.match(name)) or name in _BOILERPLATE_NAMES
 
 
+# 索引格式版本：切块算法 / embed 上下文文本格式（_embed_text）变更时必须 bump。
+# 文件 hash 没变不代表块/向量还有效：切块边界或上下文头变了，旧块与新块
+# 不可比，必须拒绝静默混用（由 _check_profile 拦截并提示重建）。
+INDEX_FORMAT = "1"
+
+
 class CodeStore:
     """单个工作区的索引存储。"""
 
-    def __init__(self, db_path: str, dim: int, dtype: str = "float") -> None:
+    def __init__(self, db_path: str, dim: int, dtype: str = "float", embed_model: str = "") -> None:
         self.db_path = db_path
         self.dim = dim
         self.dtype = dtype if dtype in ("float", "int8") else "float"
@@ -49,7 +55,52 @@ class CodeStore:
         self.db.enable_load_extension(True)
         sqlite_vec.load(self.db)
         self.db.enable_load_extension(False)
+        # 跨进程治理：WAL 允许多进程并发读 + 单写不互斥读；busy_timeout 让并发写
+        # 排队等待而不是立即抛 SQLITE_BUSY（本机源码版 + uvx 发布版可能同时运行）
+        try:
+            self.db.execute("PRAGMA journal_mode=WAL")
+            self.db.execute("PRAGMA busy_timeout=5000")
+        except Exception:
+            pass
         self._init_schema()
+        self._check_profile(embed_model)
+
+    def _check_profile(self, embed_model: str) -> None:
+        """索引 profile 校验：换 embedding 模型/维度后旧向量不可比，必须拒绝混用。
+
+        meta 表记录 (embed_model, dim, dtype)。不匹配时抛错并提示删库重建，
+        而不是静默把不同模型的向量混进同一个向量空间。embed_model 为空
+        （单元测试 fake embedder）时跳过模型名校验，但仍校验 dim/dtype。
+        """
+        cur = self.db.cursor()
+        cur.execute("CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT)")
+        rows = dict(cur.execute("SELECT key, value FROM meta").fetchall())
+        want = {
+            "embed_model": embed_model,
+            "dim": str(self.dim),
+            "dtype": self.dtype,
+            "index_format": INDEX_FORMAT,
+        }
+        has_chunks = bool(cur.execute("SELECT 1 FROM chunks LIMIT 1").fetchone())
+        for key, val in want.items():
+            if key == "embed_model" and not val:
+                continue
+            old = rows.get(key)
+            if old is None:
+                # 缺失时认领当前值：仅对「库确实由当前算法/模型构建」成立。
+                # 历史上 chunker/默认模型从未变过，认领事实正确；今后变更
+                # 必须 bump INDEX_FORMAT/换模型名，让不匹配分支拦住旧库。
+                cur.execute("INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)", (key, val))
+            elif old != val and has_chunks:
+                self.db.commit()
+                raise RuntimeError(
+                    f"索引 profile 不匹配：DB 的 {key}={old!r}，当前配置 {key}={val!r}。"
+                    f"不同 embedding 配置的向量不可混用，请删除索引文件后重建：{self.db_path}"
+                )
+            elif old != val:
+                # 库还是空的：直接更新 profile（如 fake 测试库先建后配）
+                cur.execute("INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)", (key, val))
+        self.db.commit()
 
     @staticmethod
     def _trigram_supported(cur) -> bool:
@@ -180,6 +231,19 @@ class CodeStore:
     def add_chunks(self, chunks: list[CodeChunk], embeddings: list[list[float]]) -> int:
         """批量写入代码块及其向量。blob_hash 重复的自动跳过。返回新增条数。"""
         cur = self.db.cursor()
+        added = self._insert_chunk_rows(cur, chunks, embeddings)
+        self.db.commit()
+        return added
+
+    def _insert_chunk_rows(self, cur, chunks: list[CodeChunk], embeddings: list[list[float]]) -> int:
+        """插入 chunk 相关全部行（chunks/vec/fts/edges），不 commit（由调用方控制事务）。"""
+        if len(chunks) != len(embeddings):
+            # zip 静默截断是数据完整性事故：供应商少返回向量时部分写入
+            # + 指纹照更新 = 永久静默缺索引。抱错让 replace_file 整体回滚，
+            # 下次 sync 重试该文件。
+            raise ValueError(
+                f"chunks({len(chunks)}) 与 embeddings({len(embeddings)}) 数量不一致，拒绝部分写入"
+            )
         added = 0
         for chunk, emb in zip(chunks, embeddings):
             cur.execute(
@@ -219,12 +283,16 @@ class CodeStore:
                     (chunk_id, callee),
                 )
             added += 1
-        self.db.commit()
         return added
 
     def delete_file(self, file_path: str) -> None:
         """删除某文件的所有代码块（向量 + 全文 + 元数据）。"""
         cur = self.db.cursor()
+        self._delete_file_rows(cur, file_path)
+        self.db.commit()
+
+    def _delete_file_rows(self, cur, file_path: str) -> None:
+        """删除某文件全部行，不 commit（由调用方控制事务）。"""
         rows = cur.execute("SELECT id FROM chunks WHERE file_path = ?", (file_path,)).fetchall()
         ids = [r[0] for r in rows]
         if ids:
@@ -235,7 +303,37 @@ class CodeStore:
                 cur.execute(f"DELETE FROM fts_chunks_tri WHERE rowid IN ({marks})", ids)
             cur.execute(f"DELETE FROM edges WHERE caller_id IN ({marks})", ids)
             cur.execute("DELETE FROM chunks WHERE file_path = ?", (file_path,))
-        self.db.commit()
+
+    def replace_file(
+        self,
+        file_path: str,
+        chunks: list[CodeChunk],
+        embeddings: list[list[float]],
+        file_hash: str,
+        mtime: float = 0.0,
+        size: int = 0,
+    ) -> int:
+        """单事务原子替换一个文件的索引：删旧行 + 插新行 + 更新指纹。
+
+        任何一步失败整体回滚，不会出现「旧数据已删、新数据未写、指纹还在」
+        的静默丢失状态（旧实现 delete/add/set_hash 三次独立 commit，进程在
+        中间崩溃会让该文件永远不被重新索引）。
+        """
+        cur = self.db.cursor()
+        try:
+            self._delete_file_rows(cur, file_path)
+            added = self._insert_chunk_rows(cur, chunks, embeddings)
+            cur.execute(
+                "INSERT INTO files (file_path, file_hash, mtime, size) VALUES (?, ?, ?, ?) "
+                "ON CONFLICT(file_path) DO UPDATE SET file_hash = excluded.file_hash, "
+                "mtime = excluded.mtime, size = excluded.size",
+                (file_path, file_hash, mtime, size),
+            )
+            self.db.commit()
+        except Exception:
+            self.db.rollback()
+            raise
+        return added
 
     # ---------- 文件指纹（增量） ----------
 

{semcode_mcp-0.1.0 → semcode_mcp-0.1.2}/src/semantic_code_mcp/workspace.py

@@ -166,7 +166,8 @@ class WorkspaceManager:
     def _create_workspace(self, resolved: str) -> Workspace:
         """创建新的 workspace 实例。"""
         db_path = self._db_path_for(resolved)
-        store = CodeStore(db_path, self.embedder.dim, dtype=self.embedder.output_dtype)
+        store = CodeStore(db_path, self.embedder.dim, dtype=self.embedder.output_dtype,
+                          embed_model=getattr(self.embedder, "model", ""))
         # rerank 后端/模型由 Retriever 按 SCM_RERANK_BACKEND / SCM_RERANK_MODEL 自行选择
         retriever = Retriever(store, self.embedder)
         indexer = Indexer(resolved, store, self.embedder)