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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kb-memory
-Version: 2.1.0
+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.0 · 自动化回归全绿，待人工验收）。
+**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.0 → 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.0 · 自动化回归全绿，待人工验收）。
+**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.0 → kb_memory-2.1.2}/kb/api.py

@@ -17,6 +17,7 @@ from pydantic import BaseModel, Field, field_validator
 
 from kb import __version__
 from kb.config import Settings, get_settings
+from kb.idle import start_idle_watchdog
 from kb.logging_setup import setup_logging
 from kb.monitor import MonitorAgent, run_once_summary
 from kb.mcp import create_mcp_server
@@ -507,7 +508,8 @@ def _wrap_api_key(app, settings):
 
 def create_app(settings: Settings | None = None,
                enable_watcher: bool = False) -> FastAPI:
-    """应用工厂；全局单例 KBService 挂 app.state.kb（REST 与 MCP 共享该实例）。
+    """应用工厂；全局单例 KBService 在工厂内创建，由 REST/MCP 共享。
+    返回经鉴权/charset/访问日志中间件包装的 ASGI 应用（外部拿不到 .state）。
     统一错误 JSON：{"error": "<CODE>", "message": "<人话>"}。
 
     enable_watcher=True 时（仅 serve 模式）在 lifespan 中挂目录监听线程；
@@ -542,6 +544,10 @@ def create_app(settings: Settings | None = None,
             serve_log.info("鉴权已启用（KB_API_KEY 已配置，要求 Bearer/X-API-Key）")
         else:
             serve_log.info("鉴权未启用（本地模式，KB_API_KEY 为空）")
+        # v2.1 空闲卸载：守护线程必须在工厂内部启动——create_app 最终返回
+        # 中间件包装后的 ASGI 函数，外部拿不到 app.state.kb。
+        idle_stop = start_idle_watchdog(lambda: kb.embedder,
+                                        kb.settings.idle_unload_seconds)
         # N29 启动安全警告：非回环监听 + 未鉴权 → warning 日志（终端醒目横幅由 serve 命令负责）
         warn = exposure_warning(kb.settings.api_host, kb.settings.api_key)
         if warn:
@@ -556,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，测试按需开）
@@ -570,6 +576,7 @@ def create_app(settings: Settings | None = None,
                 serve_log.info("服务就绪 records=%s", kb.stats().get("records"))
                 yield
         finally:
+            idle_stop.set()
             if monitor is not None:
                 monitor.stop()
             if watcher is not None:
@@ -804,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.0 → kb_memory-2.1.2}/kb/cli.py

@@ -14,12 +14,28 @@ from rich.table import Table
 
 from kb.config import Settings, get_settings
 from kb.governance import days_since
+from kb.idle import start_idle_watchdog  # 兼容既有导入：kb.cli.start_idle_watchdog
 from kb.service import KBService
 
 app = typer.Typer()
 console = Console()
 
 
+@app.callback(invoke_without_command=True)
+def _version_option(
+        ctx: typer.Context,
+        version: bool = typer.Option(
+            False, "--version", "-V", is_eager=True,
+            help="显示版本并退出 / Show version and exit")):
+    if version:
+        from kb import __version__
+        console.print(f"kb {__version__}")
+        raise typer.Exit()
+    if ctx.invoked_subcommand is None:
+        console.print(ctx.get_help())
+        raise typer.Exit()
+
+
 def _default_project() -> str:
     """当前目录名规整为合法项目名；无法规整时回退全局库（空串）。
 
@@ -387,8 +403,11 @@ def ask(
     except LLMDisabledError:
         # LLM 不可用：检索结果仍有价值，输出命中并给出配置指引
         hits = svc.search(question, top_k=top_k)
-        console.print("[yellow]LLM 不可用（本地 Ollama 未响应且未配置云端 "
-                      "Key），以下为检索结果（仅检索未生成）[/yellow]")
+        if getattr(getattr(svc, "settings", None), "llm_mode", "") == "off":
+            reason = "LLM 已关闭（KB_LLM_MODE=off，默认不调用 LLM）"
+        else:
+            reason = "LLM 不可用（本地 Ollama 未响应且未配置云端 Key）"
+        console.print(f"[yellow]{reason}，以下为检索结果（仅检索未生成）[/yellow]")
         console.print(f"配置指引：在 .env 设 KB_LLM_MODE=local 并配置 KB_LLM_MODEL=（先用 "
                       "ollama pull 选一个模型，名称以 ollama list 为准），或设"
                       " KB_LLM_API_KEY 启用云端（任意 OpenAI 兼容服务商）")
@@ -409,39 +428,6 @@ def ask(
         raise typer.Exit(code=1)
 
 
-def start_idle_watchdog(embedder, idle_seconds: int,
-                        check_seconds: float | None = None):
-    """启动空闲卸载守护线程（daemon），返回停止事件；idle_seconds<=0 不启动。
-
-    每轮调用 embedder.unload_if_idle()，空闲超时后卸载模型并释放显存；
-    兜底异常记 WARNING，守护线程永不因单次失败退出。
-    English: Start the idle-unload daemon thread and return its stop event;
-    idle_seconds<=0 disables it. Each tick calls embedder.unload_if_idle(),
-    releasing memory/VRAM after the idle timeout; exceptions are logged as
-    WARNING so the thread never dies on a single failure.
-    """
-    import logging
-    import threading
-    stop = threading.Event()
-    if idle_seconds <= 0:
-        return stop
-    interval = (check_seconds if check_seconds is not None
-                else max(1.0, min(30.0, idle_seconds / 4)))
-
-    def _loop() -> None:
-        log = logging.getLogger("kb.idle")
-        while not stop.wait(interval):
-            try:
-                target = embedder() if callable(embedder) else embedder
-                if target.unload_if_idle():
-                    log.info("嵌入模型空闲超过 %s 秒，已卸载", idle_seconds)
-            except Exception as exc:  # noqa: BLE001 - 守护线程不因单次失败退出
-                log.warning("空闲卸载检查失败：%s", exc)
-
-    threading.Thread(target=_loop, name="kb-idle-unload", daemon=True).start()
-    return stop
-
-
 @app.command()
 def serve(non_interactive: bool = typer.Option(
         False, "--non-interactive",
@@ -468,15 +454,12 @@ def serve(non_interactive: bool = typer.Option(
         console.print(f"[bold red]{warn}[/bold red]")
         console.print(f"[bold red]{'!' * 68}[/bold red]\n")
     app = create_app(s, enable_watcher=True)
-    idle_stop = start_idle_watchdog(lambda: app.state.kb.embedder,
-                                    s.idle_unload_seconds)
     # kb.pid 由服务进程自身管理：启动前写入（真实存活到此处才写，不再由
     # start_kb.bat 猜写）；无论正常退出还是异常，退出时清理，不留指向死进程的旧 pid。
     write_pid_file()
     try:
         uvicorn.run(app, host=s.api_host, port=s.api_port)
     finally:
-        idle_stop.set()
         remove_pid_file()
 
 

{kb_memory-2.1.0 → kb_memory-2.1.2}/kb/discovery.py

@@ -76,6 +76,15 @@ def _running(host: str, port: int) -> bool:
         return False
 
 
+def _absolute_data_dir(value) -> str:
+    """把数据目录解析为绝对路径：相对路径按服务启动时的 cwd 落盘，where 必须显示真实位置。"""
+    path = Path(value).expanduser()
+    try:
+        return str(path.resolve())
+    except OSError:
+        return str(path.absolute())
+
+
 def discover(settings=None) -> dict:
     """按 manifest → PATH → 当前解释器 的顺序发现服务安装。
 
@@ -93,7 +102,8 @@ def discover(settings=None) -> dict:
             "source": "manifest",
             "python": manifest["python"],
             "version": manifest.get("version") or _package_version(),
-            "data_dir": manifest.get("data_dir") or str(settings.data_dir),
+            "data_dir": _absolute_data_dir(
+                manifest.get("data_dir") or settings.data_dir),
             "venv": manifest.get("venv") or "",
             "running": _running(host, port),
             "endpoint": f"http://{host}:{port}/mcp/",
@@ -111,7 +121,7 @@ def discover(settings=None) -> dict:
             "source": "path",
             "python": python,
             "version": _package_version(),
-            "data_dir": str(settings.data_dir),
+            "data_dir": _absolute_data_dir(settings.data_dir),
             "venv": "",
             "running": _running(host, port),
             "endpoint": f"http://{host}:{port}/mcp/",
@@ -121,7 +131,7 @@ def discover(settings=None) -> dict:
         "source": "package",
         "python": sys.executable,
         "version": _package_version(),
-        "data_dir": str(settings.data_dir),
+        "data_dir": _absolute_data_dir(settings.data_dir),
         "venv": "",
         "running": _running(host, port),
         "endpoint": f"http://{host}:{port}/mcp/",

kb_memory-2.1.2/kb/idle.py

@@ -0,0 +1,36 @@
+"""空闲卸载守护线程（v2.1 资源占用优化）。
+
+独立模块以便 create_app（服务生命周期）与 CLI 复用；create_app 返回的是
+经中间件包装的 ASGI 函数，无法再从外部访问 app.state，因此守护线程必须在
+工厂内部、拿得到 KBService 的地方启动。
+"""
+import logging
+import threading
+
+
+def start_idle_watchdog(embedder, idle_seconds: int,
+                        check_seconds: float | None = None):
+    """启动空闲卸载守护线程（daemon），返回停止事件；idle_seconds<=0 不启动。
+
+    embedder 可以是 Embedder 实例，也可以是返回实例的可调用对象（延迟解析，
+    兼容测试替身与延迟初始化）。每轮调用 unload_if_idle()；异常记 WARNING，
+    守护线程不因单次失败退出。
+    """
+    stop = threading.Event()
+    if idle_seconds <= 0:
+        return stop
+    interval = (check_seconds if check_seconds is not None
+                else max(1.0, min(30.0, idle_seconds / 4)))
+
+    def _loop() -> None:
+        log = logging.getLogger("kb.idle")
+        while not stop.wait(interval):
+            try:
+                target = embedder() if callable(embedder) else embedder
+                if target.unload_if_idle():
+                    log.info("嵌入模型空闲超过 %s 秒，已卸载", idle_seconds)
+            except Exception as exc:  # noqa: BLE001 - 守护线程不因单次失败退出
+                log.warning("空闲卸载检查失败：%s", exc)
+
+    threading.Thread(target=_loop, name="kb-idle-unload", daemon=True).start()
+    return stop

{kb_memory-2.1.0 → kb_memory-2.1.2}/kb/service.py

@@ -767,6 +767,10 @@ class KBService:
         - v2.1: with project, retrieval covers that project's sub-store plus the global store;
           an ask access-audit is emitted."""
         if self.llm.status is LLMStatus.DISABLED:
+            if self.settings.llm_mode == "off":
+                raise LLMDisabledError(
+                    "LLM 已关闭（KB_LLM_MODE=off，默认不调用 LLM）；"
+                    "如需 /ask 问答请配置 local/auto/cloud")
             raise LLMDisabledError("LLM 不可用：本地 Ollama 未响应且未配置云端 Key")
         results = sorted(self.search(question, top_k=5, agent_id=agent_id,
                                      client=client, project=project),

{kb_memory-2.1.0 → 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.0 → 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.0
+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.0 · 自动化回归全绿，待人工验收）。
+**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.0 → kb_memory-2.1.2}/kb_memory.egg-info/SOURCES.txt

@@ -14,6 +14,7 @@ kb/embedder.py
 kb/eval.py
 kb/governance.py
 kb/i18n.py
+kb/idle.py
 kb/ingest.py
 kb/llm.py
 kb/logging_setup.py

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kb-memory"
-version = "2.1.0"
+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.0 → 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.0 → 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.0 → kb_memory-2.1.2}/tests/test_v21_bootstrap.py

@@ -96,3 +96,37 @@ def test_清单发现与仅启动(boot, tmp_path, capsys):
 def test_无清单时状态提示(boot, capsys):
     assert boot.main(["--status", "--port", "1"]) == 1
     assert "未找到安装清单" in capsys.readouterr().out
+
+
+class FailingFirstPipRunner(FakeRunner):
+    """首次 pip 安装 kb-memory 返回 1，模拟镜像未同步新包。"""
+
+    def __call__(self, cmd, check=False, capture_output=False, text=False):
+        self.calls.append(list(cmd))
+        joined = " ".join(cmd)
+        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.2\n")
+
+
+def test_pip源缺包时自动官方兜底(boot, tmp_path, capsys):
+    inst = tmp_path / "inst"
+    venv_python = boot.venv_python(inst / "venv")
+    venv_python.parent.mkdir(parents=True)
+    venv_python.write_text("", encoding="utf-8")
+    runner = FailingFirstPipRunner()
+    rc = boot.main(["--yes", "--no-start", "--dir", str(inst),
+                    "--port", "1"], runner=runner)
+    assert rc == 0
+    joined = [" ".join(c) for c in runner.calls]
+    assert any("--extra-index-url https://pypi.org/simple/" in j
+               for j in joined)
+    assert "官方 PyPI 兜底重试" in capsys.readouterr().out
+    assert boot.read_manifest() is not None
+
+
+def test_兜底命令不重复追加(boot):
+    cmd = ["python", "-m", "pip", "install", "kb-memory[ingest]",
+           "--extra-index-url", "https://example.com/simple/"]
+    assert boot.fallback_command(cmd) is None

{kb_memory-2.1.0 → kb_memory-2.1.2}/tests/test_v21_runtime.py

@@ -45,6 +45,36 @@ def test_空闲守护线程可启停(env_isolated):
         stop.set()
 
 
+def test_服务生命周期启动并停止空闲守护(tmp_path, monkeypatch, env_isolated):
+    """create_app 返回包装后的 ASGI 函数，外部拿不到 app.state；守护线程必须在
+    lifespan 内用工厂里的 KBService 启动，否则空闲卸载永远不会生效。"""
+    from fastapi.testclient import TestClient
+    from kb import api as api_module
+    from kb.config import Settings
+    from kb.embedder import Embedder
+
+    started = {}
+    stopped = threading.Event()
+
+    class FakeStop:
+        def set(self):
+            stopped.set()
+
+    def fake_start(target, idle_seconds, check_seconds=None):
+        started["idle_seconds"] = idle_seconds
+        resolved = target() if callable(target) else target
+        started["target_is_embedder"] = isinstance(resolved, Embedder)
+        return FakeStop()
+
+    monkeypatch.setattr(api_module, "start_idle_watchdog", fake_start)
+    settings = Settings(data_dir=tmp_path / "data", log_dir=tmp_path / "logs",
+                        idle_unload_seconds=42, llm_mode="off", watch_dir="")
+    with TestClient(api_module.create_app(settings)):
+        assert started["idle_seconds"] == 42
+        assert started["target_is_embedder"] is True
+    assert stopped.is_set(), "服务停止时应通知守护线程退出"
+
+
 def test_发现顺序_manifest优先(tmp_path, monkeypatch, env_isolated):
     from kb import discovery
     fake_home = tmp_path / "home"
@@ -96,6 +126,42 @@ def test_where命令输出(env_isolated):
         assert key in result.output
 
 
+def test_version选项(env_isolated):
+    from typer.testing import CliRunner
+    from kb import __version__
+    from kb.cli import app
+    result = CliRunner().invoke(app, ["--version"])
+    assert result.exit_code == 0, result.output
+    assert __version__ in result.output
+
+
+def test_发现数据目录为绝对路径(tmp_path, monkeypatch, env_isolated):
+    """相对 data_dir 实际按启动 cwd 落盘；where 必须显示绝对路径，避免误解。"""
+    from kb import discovery
+    from kb.config import Settings
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    monkeypatch.setattr(Path, "home", classmethod(lambda cls: fake_home))
+    monkeypatch.setattr(discovery.shutil, "which", lambda name: None)
+    monkeypatch.chdir(tmp_path)
+    settings = Settings(data_dir=Path("relative_data"),
+                        log_dir=tmp_path / "logs", llm_mode="off",
+                        watch_dir="")
+    info = discovery.discover(settings)
+    assert Path(info["data_dir"]) == (tmp_path / "relative_data").resolve()
+
+
+def test_ask关闭时提示已关闭(monkeypatch, env_isolated):
+    from kb.service import KBService, LLMDisabledError
+    monkeypatch.setenv("KB_LLM_MODE", "off")
+    from kb import config
+    config.get_settings.cache_clear()
+    svc = KBService()
+    with pytest.raises(LLMDisabledError) as exc:
+        svc.ask("任意问题")
+    assert "已关闭" in str(exc.value)
+
+
 @pytest.mark.skipif(os.name == "nt", reason="Windows 启动项由 .cmd 实现")
 def test_linux_systemd_unit内容(tmp_path, monkeypatch, env_isolated):
     from kb import discovery

kb_memory-2.1.0/kb/__init__.py

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