kb-memory 2.1.1__tar.gz → 2.1.2__tar.gz

{kb_memory-2.1.1 → kb_memory-2.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kb-memory
-Version: 2.1.1
+Version: 2.1.2
 Summary: Local-first agent memory & knowledge service: hybrid retrieval + memory governance (decay / dedup / freshness), REST + MCP dual protocol, fully usable offline without an LLM
 Author: fish827-08
 License-Expression: Apache-2.0
@@ -60,7 +60,7 @@ Dynamic: license-file
 
 <!-- GitHub Topics: mcp, memory-service, rag, ai-agent, knowledge-base, local-first, llm, claude-code, hybrid-search, embedding -->
 
-**kb** 是本地优先、完全免费的 Agent 记忆与知识服务（v2.1.1 · 自动化回归全绿，待人工验收）。
+**kb** 是本地优先、完全免费的 Agent 记忆与知识服务（v2.1.2）。
 
 > 开源协议：[Apache-2.0](LICENSE)（含专利授权，可商用）。
 
@@ -150,7 +150,7 @@ curl http://127.0.0.1:8000/api/v1/healthz
 >
 > **CPU 即可运行，不占显卡**：全新安装默认拿到 CPU 版 torch（`device=cpu`），
 > 不占用 GPU 显存，无独立显卡的机器也能完整使用。有显卡想加速（大库、批量入库）
-> 可另装 CUDA 版 torch，见 [AGENTS.md](AGENTS.md) 第 7 节；也可显式 `KB_DEVICE=cuda`。
+> 可另装 CUDA 版 torch 后显式 `KB_DEVICE=cuda` 启用 GPU 加速。
 >
 > **LLM 默认关闭（`KB_LLM_MODE=off`）**：服务启动不会探测/加载/调用任何大模型，
 > 零显存、零成本、纯离线；记忆写入、文档入库、混合检索完整可用。
@@ -398,18 +398,14 @@ python -m kb dedup --threshold 0.92           # 语义去重
 ```
 kb/            kb 服务源码（config / models / embedder / storage / bm25 / retriever /
                service / llm / ingest / watcher / api / mcp / cli + reranker / sparse / eval）
-tests/         kb 验收测试（417 项通过 / 1 跳过，含 eval_zh_50.jsonl 检索评测数据集）
-docs/          核心文档、当前设计（历史 spec/plan 已归档本地，不上传）
+tests/         kb 验收测试（425 项通过 / 1 跳过，含 eval_zh_50.jsonl 检索评测数据集）
+docs/          用户指南、开发者手册与设计文档
 kb_data/       kb 运行数据（gitignore）
-_archive/      旧学习项目 + 历史 spec/plan 归档（仅本地保留，禁止参考）
 ```
 
 ## 更多文档
 
-- **用户使用手册（人类用户入口）**：[docs/USER_GUIDE.md](docs/USER_GUIDE.md)
-- **AI 接力文档（AI 助手入口）**：[PROJECT.md](PROJECT.md)（项目状态 / 进度看板 / 接手指南）
+- **用户使用手册**：[docs/USER_GUIDE.md](docs/USER_GUIDE.md)
 - 设计文档（需求、架构、API、里程碑）：`docs/superpowers/specs/2026-08-23-kb-memory-service-design.md`
 - **v2.1 设计（当前）**：`docs/superpowers/specs/2026-10-20-kb-v2.1-design.md`
 - 开发者维护手册：`docs/DEV_HANDBOOK.md`
-- AI 协作规范：`AGENTS.md`
-- 历史 spec / 节点计划已归档到本地 `_archive/docs/`（不上传，不再作为开发依据）

{kb_memory-2.1.1 → kb_memory-2.1.2}/README.md

@@ -10,7 +10,7 @@
 
 <!-- GitHub Topics: mcp, memory-service, rag, ai-agent, knowledge-base, local-first, llm, claude-code, hybrid-search, embedding -->
 
-**kb** 是本地优先、完全免费的 Agent 记忆与知识服务（v2.1.1 · 自动化回归全绿，待人工验收）。
+**kb** 是本地优先、完全免费的 Agent 记忆与知识服务（v2.1.2）。
 
 > 开源协议：[Apache-2.0](LICENSE)（含专利授权，可商用）。
 
@@ -100,7 +100,7 @@ curl http://127.0.0.1:8000/api/v1/healthz
 >
 > **CPU 即可运行，不占显卡**：全新安装默认拿到 CPU 版 torch（`device=cpu`），
 > 不占用 GPU 显存，无独立显卡的机器也能完整使用。有显卡想加速（大库、批量入库）
-> 可另装 CUDA 版 torch，见 [AGENTS.md](AGENTS.md) 第 7 节；也可显式 `KB_DEVICE=cuda`。
+> 可另装 CUDA 版 torch 后显式 `KB_DEVICE=cuda` 启用 GPU 加速。
 >
 > **LLM 默认关闭（`KB_LLM_MODE=off`）**：服务启动不会探测/加载/调用任何大模型，
 > 零显存、零成本、纯离线；记忆写入、文档入库、混合检索完整可用。
@@ -348,18 +348,14 @@ python -m kb dedup --threshold 0.92           # 语义去重
 ```
 kb/            kb 服务源码（config / models / embedder / storage / bm25 / retriever /
                service / llm / ingest / watcher / api / mcp / cli + reranker / sparse / eval）
-tests/         kb 验收测试（417 项通过 / 1 跳过，含 eval_zh_50.jsonl 检索评测数据集）
-docs/          核心文档、当前设计（历史 spec/plan 已归档本地，不上传）
+tests/         kb 验收测试（425 项通过 / 1 跳过，含 eval_zh_50.jsonl 检索评测数据集）
+docs/          用户指南、开发者手册与设计文档
 kb_data/       kb 运行数据（gitignore）
-_archive/      旧学习项目 + 历史 spec/plan 归档（仅本地保留，禁止参考）
 ```
 
 ## 更多文档
 
-- **用户使用手册（人类用户入口）**：[docs/USER_GUIDE.md](docs/USER_GUIDE.md)
-- **AI 接力文档（AI 助手入口）**：[PROJECT.md](PROJECT.md)（项目状态 / 进度看板 / 接手指南）
+- **用户使用手册**：[docs/USER_GUIDE.md](docs/USER_GUIDE.md)
 - 设计文档（需求、架构、API、里程碑）：`docs/superpowers/specs/2026-08-23-kb-memory-service-design.md`
 - **v2.1 设计（当前）**：`docs/superpowers/specs/2026-10-20-kb-v2.1-design.md`
 - 开发者维护手册：`docs/DEV_HANDBOOK.md`
-- AI 协作规范：`AGENTS.md`
-- 历史 spec / 节点计划已归档到本地 `_archive/docs/`（不上传，不再作为开发依据）

kb_memory-2.1.2/kb/__init__.py

@@ -0,0 +1,2 @@
+"""kb：本地 Agent 记忆与知识服务。"""
+__version__ = "2.1.2"  # 对应 git tag v2.1.2（生命周期日志 version= 字段用）

{kb_memory-2.1.1 → kb_memory-2.1.2}/kb/api.py

@@ -562,7 +562,7 @@ def create_app(settings: Settings | None = None,
                     "未安装 watchdog，目录监听已禁用"
                     "（pip install \"kb-memory[ingest]\" 可启用）")
             else:
-                watcher = KBWatcher(kb, wd)
+                watcher = KBWatcher(kb, wd, ignore_dir=kb.settings.data_dir)
                 watcher.start()
         # 本地监控 Agent（TASK-0017）：serve 模式默认启用，仅读配置决定间隔；
         # TestClient 测试默认不启动（monitor_enabled 默认 False，测试按需开）
@@ -811,11 +811,9 @@ def create_app(settings: Settings | None = None,
         try:
             return kb.ask(body.question, agent_id=body.agent_id,
                           client=body.client, project=body.project)
-        except LLMDisabledError:
+        except LLMDisabledError as exc:
             raise HTTPException(status_code=503, detail={
-                "error": "LLM_DISABLED",
-                "message": "未检测到可用的 LLM：请在 .env 配置 KB_LLM_MODE=local "
-                           "（Ollama）或 KB_LLM_API_KEY 启用云端（任意 OpenAI 兼容服务商）"})
+                "error": "LLM_DISABLED", "message": str(exc)})
 
     @app.get("/api/v1/audit")
     def audit(client: str | None = None, project: str | None = None,

{kb_memory-2.1.1 → kb_memory-2.1.2}/kb/watcher.py

@@ -47,10 +47,16 @@ def _is_supported(path: Path) -> bool:
 class KBWatcher:
     """目录监听器：watchdog Observer 采集事件 + 后台 worker 去抖处理。"""
 
-    def __init__(self, service, watch_dir: Path, debounce_seconds: float = 2.0):
-        """service 为 KBService；watch_dir 为监听目录（仅顶层，不递归）。"""
+    def __init__(self, service, watch_dir: Path, debounce_seconds: float = 2.0,
+                 ignore_dir: Path | None = None):
+        """service 为 KBService；watch_dir 为监听目录（仅顶层，不递归）。
+
+        ignore_dir 为服务数据目录：与 watch_dir 重合时 start() 跳过监听，
+        避免把 bm25_corpus.json 等数据文件反复入库（自我入库死循环）。
+        """
         self.service = service
         self.watch_dir = Path(watch_dir)
+        self.ignore_dir = Path(ignore_dir) if ignore_dir is not None else None
         self.debounce_seconds = debounce_seconds
         self._pending: dict[Path, float] = {}        # 待入库路径 → 最近一次事件时间
         self._deletes: queue.Queue[str] = queue.Queue()  # 待删除 source（文件名）
@@ -60,6 +66,15 @@ class KBWatcher:
         self._worker: threading.Thread | None = None
 
     # ---- 生命周期 ----
+    def _overlaps_data_dir(self) -> bool:
+        """监听目录是否就是数据目录（相对路径/符号链接解析后比较）。"""
+        if self.ignore_dir is None:
+            return False
+        try:
+            return self.watch_dir.resolve() == self.ignore_dir.resolve()
+        except OSError:
+            return False
+
     def start(self) -> None:
         """启动 watchdog Observer 与后台处理线程。
 
@@ -75,6 +90,11 @@ class KBWatcher:
             logger.info("监听目录不存在或不可用，跳过目录监听：%s",
                         self.watch_dir)
             return
+        if self._overlaps_data_dir():
+            logger.warning(
+                "监听目录与数据目录相同（%s），已跳过目录监听以避免自我入库；"
+                "请把 KB_WATCH_DIR 指向数据目录之外", self.watch_dir)
+            return
         self._observer = Observer()
         self._observer.schedule(_EventHandler(self), str(self.watch_dir),
                                 recursive=False)

{kb_memory-2.1.1 → kb_memory-2.1.2}/kb_memory.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kb-memory
-Version: 2.1.1
+Version: 2.1.2
 Summary: Local-first agent memory & knowledge service: hybrid retrieval + memory governance (decay / dedup / freshness), REST + MCP dual protocol, fully usable offline without an LLM
 Author: fish827-08
 License-Expression: Apache-2.0
@@ -60,7 +60,7 @@ Dynamic: license-file
 
 <!-- GitHub Topics: mcp, memory-service, rag, ai-agent, knowledge-base, local-first, llm, claude-code, hybrid-search, embedding -->
 
-**kb** 是本地优先、完全免费的 Agent 记忆与知识服务（v2.1.1 · 自动化回归全绿，待人工验收）。
+**kb** 是本地优先、完全免费的 Agent 记忆与知识服务（v2.1.2）。
 
 > 开源协议：[Apache-2.0](LICENSE)（含专利授权，可商用）。
 
@@ -150,7 +150,7 @@ curl http://127.0.0.1:8000/api/v1/healthz
 >
 > **CPU 即可运行，不占显卡**：全新安装默认拿到 CPU 版 torch（`device=cpu`），
 > 不占用 GPU 显存，无独立显卡的机器也能完整使用。有显卡想加速（大库、批量入库）
-> 可另装 CUDA 版 torch，见 [AGENTS.md](AGENTS.md) 第 7 节；也可显式 `KB_DEVICE=cuda`。
+> 可另装 CUDA 版 torch 后显式 `KB_DEVICE=cuda` 启用 GPU 加速。
 >
 > **LLM 默认关闭（`KB_LLM_MODE=off`）**：服务启动不会探测/加载/调用任何大模型，
 > 零显存、零成本、纯离线；记忆写入、文档入库、混合检索完整可用。
@@ -398,18 +398,14 @@ python -m kb dedup --threshold 0.92           # 语义去重
 ```
 kb/            kb 服务源码（config / models / embedder / storage / bm25 / retriever /
                service / llm / ingest / watcher / api / mcp / cli + reranker / sparse / eval）
-tests/         kb 验收测试（417 项通过 / 1 跳过，含 eval_zh_50.jsonl 检索评测数据集）
-docs/          核心文档、当前设计（历史 spec/plan 已归档本地，不上传）
+tests/         kb 验收测试（425 项通过 / 1 跳过，含 eval_zh_50.jsonl 检索评测数据集）
+docs/          用户指南、开发者手册与设计文档
 kb_data/       kb 运行数据（gitignore）
-_archive/      旧学习项目 + 历史 spec/plan 归档（仅本地保留，禁止参考）
 ```
 
 ## 更多文档
 
-- **用户使用手册（人类用户入口）**：[docs/USER_GUIDE.md](docs/USER_GUIDE.md)
-- **AI 接力文档（AI 助手入口）**：[PROJECT.md](PROJECT.md)（项目状态 / 进度看板 / 接手指南）
+- **用户使用手册**：[docs/USER_GUIDE.md](docs/USER_GUIDE.md)
 - 设计文档（需求、架构、API、里程碑）：`docs/superpowers/specs/2026-08-23-kb-memory-service-design.md`
 - **v2.1 设计（当前）**：`docs/superpowers/specs/2026-10-20-kb-v2.1-design.md`
 - 开发者维护手册：`docs/DEV_HANDBOOK.md`
-- AI 协作规范：`AGENTS.md`
-- 历史 spec / 节点计划已归档到本地 `_archive/docs/`（不上传，不再作为开发依据）

{kb_memory-2.1.1 → kb_memory-2.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kb-memory"
-version = "2.1.1"
+version = "2.1.2"
 description = "Local-first agent memory & knowledge service: hybrid retrieval + memory governance (decay / dedup / freshness), REST + MCP dual protocol, fully usable offline without an LLM"
 readme = "README.md"
 requires-python = ">=3.10"

{kb_memory-2.1.1 → kb_memory-2.1.2}/tests/test_n10_ask.py

@@ -51,4 +51,6 @@ def test_禁用转503(env_isolated):
         r = c.post("/api/v1/ask", json={"question": "测试"})
         assert r.status_code == 503
         assert r.json()["error"] == "LLM_DISABLED"
-        assert "Ollama" in r.json()["message"]
+        # 默认 KB_LLM_MODE=off：必须说明是主动关闭，而不是误报 Ollama 不可用
+        assert "已关闭" in r.json()["message"]
+        assert "KB_LLM_MODE=off" in r.json()["message"]

{kb_memory-2.1.1 → kb_memory-2.1.2}/tests/test_n15_watcher.py

@@ -39,3 +39,38 @@ def test_文件删除级联清理(env_isolated):
         assert s.list_records(q="将被删除")[1] == 0
     finally:
         w.stop()
+
+
+def test_监听目录与数据目录相同时跳过(tmp_path, caplog):
+    """watch_dir == data_dir 时 listener 会把自己的 bm25 语料反复入库，必须跳过。"""
+    from kb.watcher import KBWatcher
+
+    class FakeService:
+        def add_document(self, path):  # pragma: no cover - 不应被调用
+            raise AssertionError("不应入库")
+
+    data = tmp_path / "data"
+    data.mkdir()
+    w = KBWatcher(FakeService(), data, ignore_dir=data)
+    with caplog.at_level("WARNING", logger="kb.watcher"):
+        w.start()
+    try:
+        assert w._observer is None
+        assert w._worker is None
+        assert "自我入库" in caplog.text
+    finally:
+        w.stop()
+
+
+def test_监听目录与数据目录不同仍正常监听(tmp_path):
+    """ignore_dir 只拦截与监听目录重合的数据目录，不影响正常监听。"""
+    from kb.watcher import KBWatcher
+
+    watch = tmp_path / "watch"; watch.mkdir()
+    data = tmp_path / "data"; data.mkdir()
+    w = KBWatcher(object(), watch, ignore_dir=data)
+    w.start()
+    try:
+        assert w._observer is not None and w._worker is not None
+    finally:
+        w.stop()

{kb_memory-2.1.1 → kb_memory-2.1.2}/tests/test_v21_bootstrap.py

@@ -107,7 +107,7 @@ class FailingFirstPipRunner(FakeRunner):
         if "pip install kb-memory" in joined \
                 and "--extra-index-url" not in joined:
             return SimpleNamespace(returncode=1, stdout="")
-        return SimpleNamespace(returncode=0, stdout="2.1.1\n")
+        return SimpleNamespace(returncode=0, stdout="2.1.2\n")
 
 
 def test_pip源缺包时自动官方兜底(boot, tmp_path, capsys):

kb_memory-2.1.1/kb/__init__.py

@@ -1,2 +0,0 @@
-"""kb：本地 Agent 记忆与知识服务。"""
-__version__ = "2.1.1"  # 对应 git tag v2.1.1（生命周期日志 version= 字段用）