jfox-cli 0.5.0__tar.gz → 0.6.0__tar.gz

{jfox_cli-0.5.0 → jfox_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jfox-cli
-Version: 0.5.0
+Version: 0.6.0
 Summary: JFox - Zettelkasten 知识管理 CLI 工具
 Project-URL: Homepage, https://github.com/zhuxixi/jfox
 Project-URL: Repository, https://github.com/zhuxixi/jfox

{jfox_cli-0.5.0 → jfox_cli-0.6.0}/jfox/__init__.py

@@ -1,5 +1,5 @@
 """JFox - Zettelkasten 知识管理工具"""
 
-__version__ = "0.5.0"
+__version__ = "0.6.0"
 __author__ = "User"
 __email__ = "user@example.com"

{jfox_cli-0.5.0 → jfox_cli-0.6.0}/jfox/cli.py

@@ -424,13 +424,9 @@ def add(
         if not content:
             raise ValueError("请提供笔记内容（位置参数或 --content-file）")
 
-        # 如果指定了知识库，临时切换
-        if kb:
-            from .config import use_kb
+        from .config import use_kb
 
-            with use_kb(kb):
-                _add_note_impl(content, title, note_type, tags, source, output_format, template)
-        else:
+        with use_kb(kb):
             _add_note_impl(content, title, note_type, tags, source, output_format, template)
 
     except typer.Exit:
@@ -561,13 +557,9 @@ def search(
         if json_output:
             output_format = "json"
 
-        # 如果指定了知识库，临时切换
-        if kb:
-            from .config import use_kb
+        from .config import use_kb
 
-            with use_kb(kb):
-                _search_impl(query, top, note_type, tags, search_mode, output_format)
-        else:
+        with use_kb(kb):
             _search_impl(query, top, note_type, tags, search_mode, output_format)
 
     except Exception as e:
@@ -746,13 +738,9 @@ def status(
 ):
     """查看知识库状态"""
     try:
-        # 如果指定了知识库，临时切换
-        if kb:
-            from .config import use_kb
+        from .config import use_kb
 
-            with use_kb(kb):
-                _status_impl(output_format, json_output)
-        else:
+        with use_kb(kb):
             _status_impl(output_format, json_output)
 
     except Exception as e:
@@ -847,13 +835,9 @@ def list(
         if json_output:
             output_format = "json"
 
-        # 如果指定了知识库，临时切换
-        if kb:
-            from .config import use_kb
+        from .config import use_kb
 
-            with use_kb(kb):
-                _list_impl(note_type, tags, limit, output_format)
-        else:
+        with use_kb(kb):
             _list_impl(note_type, tags, limit, output_format)
 
     except Exception as e:
@@ -897,12 +881,9 @@ def show(
     支持通过笔记 ID 或标题定位。
     """
     try:
-        if kb:
-            from .config import use_kb
+        from .config import use_kb
 
-            with use_kb(kb):
-                _show_impl(note_ref)
-        else:
+        with use_kb(kb):
             _show_impl(note_ref)
 
     except Exception as e:
@@ -1046,13 +1027,9 @@ def refs(
         if json_output:
             output_format = "json"
 
-        # 如果指定了知识库，临时切换
-        if kb:
-            from .config import use_kb
+        from .config import use_kb
 
-            with use_kb(kb):
-                _refs_impl(note_id, search, output_format, json_output)
-        else:
+        with use_kb(kb):
             _refs_impl(note_id, search, output_format, json_output)
 
     except Exception as e:
@@ -1125,13 +1102,9 @@ def delete(
         if json_output:
             output_format = "json"
 
-        # 如果指定了知识库，临时切换
-        if kb:
-            from .config import use_kb
+        from .config import use_kb
 
-            with use_kb(kb):
-                _delete_impl(note_id, force, output_format)
-        else:
+        with use_kb(kb):
             _delete_impl(note_id, force, output_format)
 
     except typer.Exit:
@@ -1331,14 +1304,9 @@ def edit(
         if json_output:
             output_format = "json"
 
-        if kb:
-            from .config import use_kb
+        from .config import use_kb
 
-            with use_kb(kb):
-                _edit_impl(
-                    note_id, content, content_file, title, tags, note_type, source, output_format
-                )
-        else:
+        with use_kb(kb):
             _edit_impl(
                 note_id, content, content_file, title, tags, note_type, source, output_format
             )
@@ -1443,13 +1411,9 @@ def query(
 ):
     """语义搜索 + 知识图谱联合查询"""
     try:
-        # 如果指定了知识库，临时切换
-        if kb:
-            from .config import use_kb
+        from .config import use_kb
 
-            with use_kb(kb):
-                _query_impl(query_str, top, graph_depth, json_output)
-        else:
+        with use_kb(kb):
             _query_impl(query_str, top, graph_depth, json_output)
 
     except Exception as e:
@@ -1579,13 +1543,9 @@ def graph(
         if json_output:
             output_format = "json"
 
-        # 如果指定了知识库，临时切换
-        if kb:
-            from .config import use_kb
+        from .config import use_kb
 
-            with use_kb(kb):
-                _graph_impl(note_id, depth, stats, orphans, output_format, json_output)
-        else:
+        with use_kb(kb):
             _graph_impl(note_id, depth, stats, orphans, output_format, json_output)
 
     except Exception as e:
@@ -1654,13 +1614,9 @@ def daily(
         if json_output:
             output_format = "json"
 
-        # 如果指定了知识库，临时切换
-        if kb:
-            from .config import use_kb
+        from .config import use_kb
 
-            with use_kb(kb):
-                _daily_impl(date, output_format, json_output)
-        else:
+        with use_kb(kb):
             _daily_impl(date, output_format, json_output)
 
     except Exception as e:
@@ -1766,13 +1722,9 @@ def suggest_links(
         output_format = "json"
 
     try:
-        # 如果指定了知识库，临时切换
-        if kb:
-            from .config import use_kb
+        from .config import use_kb
 
-            with use_kb(kb):
-                _suggest_links_impl(content, top_k, threshold, output_format, json_output)
-        else:
+        with use_kb(kb):
             _suggest_links_impl(content, top_k, threshold, output_format, json_output)
 
     except Exception as e:
@@ -1799,13 +1751,9 @@ def inbox(
         if json_output:
             output_format = "json"
 
-        # 如果指定了知识库，临时切换
-        if kb:
-            from .config import use_kb
+        from .config import use_kb
 
-            with use_kb(kb):
-                _inbox_impl(limit, output_format, json_output)
-        else:
+        with use_kb(kb):
             _inbox_impl(limit, output_format, json_output)
 
     except Exception as e:
@@ -1985,13 +1933,9 @@ def index(
         if json_output:
             output_format = "json"
 
-        # 如果指定了知识库，临时切换
-        if kb:
-            from .config import use_kb
+        from .config import use_kb
 
-            with use_kb(kb):
-                _index_impl(action, output_format)
-        else:
+        with use_kb(kb):
             _index_impl(action, output_format)
 
     except typer.Exit:
@@ -2453,15 +2397,9 @@ def ingest_log(
         if json_output:
             output_format = "json"
 
-        # 如果指定了知识库，临时切换
-        if kb:
-            from .config import use_kb
+        from .config import use_kb
 
-            with use_kb(kb):
-                _ingest_log_impl(
-                    repo_path, limit, note_type, batch_size, output_format, json_output
-                )
-        else:
+        with use_kb(kb):
             _ingest_log_impl(repo_path, limit, note_type, batch_size, output_format, json_output)
 
     except ValueError as e:
@@ -2512,20 +2450,10 @@ def bulk_import(
 
         console.print(f"[yellow]Importing {len(notes_data)} notes...[/yellow]")
 
+        from .config import use_kb
         from .performance import bulk_import_notes
 
-        # 如果指定了知识库，临时切换
-        if kb:
-            from .config import use_kb
-
-            with use_kb(kb):
-                result = bulk_import_notes(
-                    notes_data=notes_data,
-                    note_type=note_type,
-                    batch_size=batch_size,
-                    show_progress=not json_output,
-                )
-        else:
+        with use_kb(kb):
             result = bulk_import_notes(
                 notes_data=notes_data,
                 note_type=note_type,
@@ -2659,8 +2587,11 @@ def daemon(
                 console.print("[dim]Daemon 未运行[/dim]")
                 return
             console.print("[yellow]正在停止 daemon...[/yellow]")
-            stop_daemon()
-            console.print("[green]✓ Daemon 已停止[/green]")
+            if stop_daemon():
+                console.print("[green]✓ Daemon 已停止[/green]")
+            else:
+                console.print("[red]✗ Daemon 停止失败，请手动终止进程[/red]")
+                raise typer.Exit(1)
 
         elif action == "status":
             info = get_daemon_status()

{jfox_cli-0.5.0 → jfox_cli-0.6.0}/jfox/config.py

@@ -1,11 +1,15 @@
 """配置管理"""
 
+import os
 from contextlib import contextmanager
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Optional
 
 import yaml
+from rich.console import Console
+
+_console = Console(stderr=True)
 
 
 def get_default_kb_path() -> Path:
@@ -148,15 +152,26 @@ def use_kb(kb_name: Optional[str] = None):
             # 在这个上下文中，操作都在 work 知识库上
             note = create_note(...)
 
+    优先级: --kb > JFOX_KB > 全局配置 default
+    当 kb_name 为 None 时，会先检查 JFOX_KB 环境变量，
+    若未设置则使用全局配置中的默认知识库。
+
     Args:
         kb_name: 知识库名称，None 表示使用当前默认知识库
 
     Raises:
         ValueError: 知识库不存在
     """
+    resolved_from_env = False
+
     if not kb_name:
-        yield
-        return
+        env_kb = os.environ.get("JFOX_KB", "").strip()
+        if env_kb:
+            kb_name = env_kb
+            resolved_from_env = True
+        else:
+            yield
+            return
 
     from .kb_manager import get_kb_manager
 
@@ -182,6 +197,12 @@ def use_kb(kb_name: Optional[str] = None):
         # 重置索引和搜索引擎（使用新的知识库路径）
         _reset_singletons()
 
+        if resolved_from_env:
+            _console.print(
+                f"Using knowledge base '{kb_name}' (from JFOX_KB environment variable)",
+                style="dim",
+            )
+
         yield
     finally:
         # 恢复原始配置

{jfox_cli-0.5.0 → jfox_cli-0.6.0}/jfox/daemon/process.py

@@ -88,6 +88,19 @@ def _http_health_check(host: str = DEFAULT_HOST, port: int = DEFAULT_PORT) -> Op
         return None
 
 
+def _http_shutdown(host: str = DEFAULT_HOST, port: int = DEFAULT_PORT) -> bool:
+    """请求 daemon 通过 /shutdown endpoint 自行停止"""
+    try:
+        import urllib.request
+
+        req = urllib.request.Request(f"http://{host}:{port}/shutdown", method="POST", data=b"")
+        with urllib.request.urlopen(req, timeout=3) as resp:
+            result = json.loads(resp.read().decode("utf-8"))
+        return result.get("status") == "shutting_down"
+    except (OSError, ValueError):
+        return False
+
+
 def is_daemon_running() -> bool:
     """检查 daemon 是否在运行（以 HTTP 健康检查为准）"""
     # 先尝试 PID 文件记录的地址
@@ -276,11 +289,32 @@ def stop_daemon() -> bool:
         port = data.get("port", DEFAULT_PORT)
 
     # 先检查是否真的在跑
-    if _http_health_check(host, port) is None:
+    health = _http_health_check(host, port)
+    if health is None:
         _remove_pid_file()
         return True
 
-    # 尝试停止
+    # 1. 优先通过 HTTP /shutdown 让 daemon 自行退出
+    logger.info("正在通过 /shutdown 请求 daemon 停止...")
+    shutdown_ok = _http_shutdown(host, port)
+
+    if shutdown_ok:
+        # 等待 daemon 自行退出（最多 3 秒）
+        for _ in range(6):
+            if _http_health_check(host, port) is None:
+                _remove_pid_file()
+                logger.info("Daemon 已通过 /shutdown 停止")
+                return True
+            time.sleep(0.5)
+
+    # 2. /shutdown 失败或超时，从 /health 获取真实 PID 后尝试 taskkill/kill
+    if pid == 0:
+        health = _http_health_check(host, port)
+        if health:
+            pid = health.get("pid", 0)
+            if not isinstance(pid, int):
+                pid = 0
+
     if pid > 0:
         try:
             if sys.platform == "win32":
@@ -294,7 +328,7 @@ def stop_daemon() -> bool:
         except (OSError, subprocess.SubprocessError) as e:
             logger.warning(f"停止 daemon 失败: {e}")
 
-    # 等待进程退出
+    # 等待进程退出（最多 5 秒）
     for _ in range(10):
         if _http_health_check(host, port) is None:
             _remove_pid_file()
@@ -302,9 +336,8 @@ def stop_daemon() -> bool:
             return True
         time.sleep(0.5)
 
-    # 超时未退出
+    # 超时未退出 — 不删 PID 文件，保留追踪信息
     logger.warning(f"Daemon 停止超时 (PID: {pid})")
-    _remove_pid_file()
     return False
 
 

{jfox_cli-0.5.0 → jfox_cli-0.6.0}/jfox/daemon/server.py

@@ -19,6 +19,9 @@ logger = logging.getLogger(__name__)
 # 全局 embedding 后端（模型加载后常驻内存）
 _backend = None
 
+# uvicorn Server 实例（用于 graceful shutdown）
+_server = None
+
 
 def _load_model():
     """启动时加载模型（标记为 daemon 进程，防止自引用）"""
@@ -76,6 +79,10 @@ class EncodeSingleRequest(BaseModel):
     text: str
 
 
+class ShutdownResponse(BaseModel):
+    status: str
+
+
 class EncodeSingleResponse(BaseModel):
     embedding: List[float]
     dimension: int
@@ -98,6 +105,14 @@ def health():
     )
 
 
+@app.post("/shutdown", response_model=ShutdownResponse)
+def shutdown():
+    """请求 daemon 自行停止"""
+    if _server:
+        _server.should_exit = True
+    return ShutdownResponse(status="shutting_down")
+
+
 @app.post("/encode", response_model=EncodeResponse)
 def encode(req: EncodeRequest):
     """批量文本编码"""
@@ -133,7 +148,10 @@ def main():
 
     import uvicorn
 
-    uvicorn.run(app, host=args.host, port=args.port, log_level="warning")
+    global _server
+    config = uvicorn.Config(app, host=args.host, port=args.port, log_level="warning")
+    _server = uvicorn.Server(config)
+    _server.run()
 
 
 if __name__ == "__main__":

{jfox_cli-0.5.0 → jfox_cli-0.6.0}/jfox/template_cli.py

@@ -42,11 +42,7 @@ def list_templates(
         if json_output:
             output_format = "json"
 
-        if kb:
-            with use_kb(kb):
-                manager = get_template_manager()
-                templates = manager.list_templates()
-        else:
+        with use_kb(kb):
             manager = get_template_manager()
             templates = manager.list_templates()
 
@@ -120,11 +116,7 @@ def show_template(
     try:
         from .config import use_kb
 
-        if kb:
-            with use_kb(kb):
-                manager = get_template_manager()
-                template = manager.get_template(name)
-        else:
+        with use_kb(kb):
             manager = get_template_manager()
             template = manager.get_template(name)
 
@@ -183,10 +175,7 @@ def create_template(
     try:
         from .config import use_kb
 
-        if kb:
-            with use_kb(kb):
-                manager = get_template_manager()
-        else:
+        with use_kb(kb):
             manager = get_template_manager()
 
         # Check if template exists
@@ -246,11 +235,7 @@ def edit_template(
     try:
         from .config import use_kb
 
-        if kb:
-            with use_kb(kb):
-                manager = get_template_manager()
-                template = manager.get_template(name)
-        else:
+        with use_kb(kb):
             manager = get_template_manager()
             template = manager.get_template(name)
 
@@ -294,10 +279,7 @@ def remove_template(
     try:
         from .config import use_kb
 
-        if kb:
-            with use_kb(kb):
-                manager = get_template_manager()
-        else:
+        with use_kb(kb):
             manager = get_template_manager()
 
         template = manager.get_template(name)

{jfox_cli-0.5.0 → jfox_cli-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "jfox-cli"
-version = "0.5.0"
+version = "0.6.0"
 description = "JFox - Zettelkasten 知识管理 CLI 工具"
 readme = "README.md"
 license = {text = "MIT"}

jfox_cli-0.6.0/tests/unit/test_use_kb_env_var.py

@@ -0,0 +1,94 @@
+"""
+测试类型: 单元测试
+目标模块: jfox.config.use_kb
+预估耗时: < 1秒
+依赖要求: 无外部依赖，使用 mock
+"""
+
+import os
+
+import pytest
+
+pytestmark = [pytest.mark.unit, pytest.mark.fast]
+from unittest.mock import Mock, patch
+
+from jfox.config import config, use_kb
+
+
+class TestUseKbEnvVar:
+    """测试 use_kb() 对 JFOX_KB 环境变量的支持"""
+
+    def test_env_var_used_when_kb_arg_none(self):
+        """当 kb_name 为 None 且 JFOX_KB 设置时，应切换到该知识库"""
+        with patch.dict(os.environ, {"JFOX_KB": "work"}):
+            with patch("jfox.config._reset_singletons"):
+                with patch("jfox.kb_manager.get_kb_manager") as mock_get_manager:
+                    mock_manager = Mock()
+                    mock_manager.config_manager.kb_exists.return_value = True
+                    mock_manager.config_manager.get_kb_path.return_value = (
+                        config.base_dir.parent / "work"
+                    )
+                    mock_get_manager.return_value = mock_manager
+
+                    with use_kb(None) as _:
+                        # 验证确实切换了知识库
+                        mock_manager.config_manager.get_kb_path.assert_called_once_with("work")
+
+    def test_cli_arg_overrides_env_var(self):
+        """当同时传入 kb_name 和设置 JFOX_KB 时，应优先使用传入的 kb_name"""
+        with patch.dict(os.environ, {"JFOX_KB": "work"}):
+            with patch("jfox.config._reset_singletons"):
+                with patch("jfox.kb_manager.get_kb_manager") as mock_get_manager:
+                    mock_manager = Mock()
+                    mock_manager.config_manager.kb_exists.return_value = True
+                    mock_manager.config_manager.get_kb_path.return_value = (
+                        config.base_dir.parent / "personal"
+                    )
+                    mock_get_manager.return_value = mock_manager
+
+                    with use_kb("personal") as _:
+                        # 验证使用的是传入的 "personal"，而不是环境变量的 "work"
+                        mock_manager.config_manager.get_kb_path.assert_called_once_with("personal")
+
+    def test_invalid_jfox_kb_raises_valueerror(self):
+        """当 JFOX_KB 指向不存在的知识库时，应抛出 ValueError"""
+        with patch.dict(os.environ, {"JFOX_KB": "nonexistent"}):
+            with patch("jfox.config._reset_singletons"):
+                with patch("jfox.kb_manager.get_kb_manager") as mock_get_manager:
+                    mock_manager = Mock()
+                    mock_manager.config_manager.kb_exists.return_value = False
+                    mock_get_manager.return_value = mock_manager
+
+                    with pytest.raises(ValueError, match="Knowledge base 'nonexistent' not found"):
+                        with use_kb(None):
+                            pass
+
+    def test_no_env_var_falls_back_to_global_default(self):
+        """当没有设置 JFOX_KB 且 kb_name 为 None 时，应直接使用当前默认知识库"""
+        with patch.dict(os.environ, {}, clear=False):
+            os.environ.pop("JFOX_KB", None)
+            with patch("jfox.kb_manager.get_kb_manager") as mock_get_manager:
+                # 不应调用 get_kb_manager，因为没有需要切换的知识库
+                original_base_dir = config.base_dir
+
+                with use_kb(None) as _:
+                    # 验证没有尝试获取 kb_manager
+                    mock_get_manager.assert_not_called()
+                    # 验证配置没有被修改
+                    assert config.base_dir == original_base_dir
+
+    def test_jfox_kb_with_whitespace_is_stripped(self):
+        """JFOX_KB 值包含首尾空格时应被去除"""
+        with patch.dict(os.environ, {"JFOX_KB": "  work  "}):
+            with patch("jfox.config._reset_singletons"):
+                with patch("jfox.kb_manager.get_kb_manager") as mock_get_manager:
+                    mock_manager = Mock()
+                    mock_manager.config_manager.kb_exists.return_value = True
+                    mock_manager.config_manager.get_kb_path.return_value = (
+                        config.base_dir.parent / "work"
+                    )
+                    mock_get_manager.return_value = mock_manager
+
+                    with use_kb(None) as _:
+                        # 验证去除了空格后使用的是 "work"
+                        mock_manager.config_manager.get_kb_path.assert_called_once_with("work")

{jfox_cli-0.5.0 → jfox_cli-0.6.0}/uv.lock

@@ -867,7 +867,7 @@ wheels = [
 
 [[package]]
 name = "jfox-cli"
-version = "0.5.0"
+version = "0.6.0"
 source = { editable = "." }
 dependencies = [
     { name = "chromadb" },