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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kb-memory
-Version: 2.1.0
+Version: 2.1.1
 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.1 · 自动化回归全绿，待人工验收）。
 
 > 开源协议：[Apache-2.0](LICENSE)（含专利授权，可商用）。
 

{kb_memory-2.1.0 → kb_memory-2.1.1}/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.1 · 自动化回归全绿，待人工验收）。
 
 > 开源协议：[Apache-2.0](LICENSE)（含专利授权，可商用）。
 

kb_memory-2.1.1/kb/__init__.py

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

{kb_memory-2.1.0 → kb_memory-2.1.1}/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:
@@ -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:

{kb_memory-2.1.0 → kb_memory-2.1.1}/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.1}/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.1/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.1}/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.1}/kb_memory.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kb-memory
-Version: 2.1.0
+Version: 2.1.1
 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.1 · 自动化回归全绿，待人工验收）。
 
 > 开源协议：[Apache-2.0](LICENSE)（含专利授权，可商用）。
 

{kb_memory-2.1.0 → kb_memory-2.1.1}/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.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kb-memory"
-version = "2.1.0"
+version = "2.1.1"
 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.1}/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.1\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.1}/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= 字段用）