jfox-cli 0.3.2__tar.gz → 0.4.0__tar.gz

jfox_cli-0.4.0/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(cp \"C:/Users/zhuzh/.claude/skills/jfox-ingest/SKILL.md\" \"skills-recommend/claude-code/jfox-ingest/SKILL.md\")",
+      "Bash(cp \"C:/Users/zhuzh/.claude/skills/jfox-organize/SKILL.md\" \"skills-recommend/claude-code/jfox-organize/SKILL.md\")",
+      "Bash(cp \"C:/Users/zhuzh/.claude/skills/jfox-common/SKILL.md\" \"skills-recommend/claude-code/jfox-common/SKILL.md\")"
+    ]
+  }
+}

{jfox_cli-0.3.2 → jfox_cli-0.4.0}/PKG-INFO

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

jfox_cli-0.4.0/docs/superpowers/plans/2026-04-15-session-summary-confirmation.md

@@ -0,0 +1,135 @@
+# Session Summary Confirmation Flow Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add user confirmation and note type selection steps to the jfox-session-summary skill before writing to the knowledge base.
+
+**Architecture:** Insert two new steps (confirm content + select type) between summary generation and `jfox add`. The modification is purely in the skill Markdown document — no Python code changes.
+
+**Tech Stack:** Skill document (Markdown), AskUserQuestion tool
+
+**Spec:** `docs/superpowers/specs/2026-04-15-session-summary-confirmation-design.md`
+
+---
+
+### Task 1: Rewrite SKILL.md workflow section
+
+**Files:**
+- Modify: `skills-recommend/claude-code/jfox-session-summary/SKILL.md`
+
+This is the only task. The file is a single skill document — no decomposition needed.
+
+- [ ] **Step 1: Read current SKILL.md**
+
+Read `skills-recommend/claude-code/jfox-session-summary/SKILL.md` to confirm current content matches expectations (3-step workflow, Step 2 hardcodes `--type fleeting`).
+
+- [ ] **Step 2: Replace Step 2 and add new Steps 2–3**
+
+Replace the entire `### Step 2: 写入知识库` section and everything after it (through end of file) with the new 5-step workflow. The exact replacement content:
+
+Replace the old `### Step 2` and `### Step 3` sections (lines 42–96) with:
+
+```markdown
+### Step 2: 用户确认
+
+将生成的总结用普通文本输出，供用户阅读。然后使用 `AskUserQuestion` 询问：
+
+- 问题：`笔记内容是否 OK？`
+- 选项：
+  - `内容没问题` → 继续 Step 3
+  - `需要修改` → 用户在 "Other" 中输入修改意见，根据意见调整总结后回到 Step 2 重新展示和确认
+
+循环直到用户满意为止。
+
+### Step 3: 选择笔记类型
+
+用户确认内容后，使用 `AskUserQuestion` 询问笔记类型：
+
+- 问题：`选择笔记类型`
+- 选项：
+  - `fleeting`（推荐）— 会话记录是临时性笔记，后续可提炼为 permanent
+  - `literature` — 如果会话有明确的参考资料来源
+  - `permanent` — 如果总结已经是成熟的知识
+
+### Step 4: 写入知识库
+
+使用 Step 3 选定的笔记类型执行写入：
+
+```bash
+jfox add "<markdown-escaped-summary>" \
+  --title "Session: <topic>" \
+  --type <Step 3 选定的类型> \
+  --tag session \
+  --kb <kb-name> \
+  --format json
+```
+
+**注意**：
+- 标题格式统一为 `Session: <简短主题>`
+- 类型使用 Step 3 的选择结果，不再硬编码 `fleeting`
+- 标签统一使用 `session`
+- 内容中的双引号需要转义，或使用 `--content-file` 从临时文件读取
+
+### Step 5: 处理长内容
+
+如果总结超过 500 字或包含特殊字符，优先使用 `--content-file`：
+
+```bash
+# 写入临时文件
+cat > /tmp/session-summary.md << 'EOF'
+<总结内容>
+EOF
+
+# 从文件导入
+jfox add --content-file /tmp/session-summary.md \
+  --title "Session: <topic>" \
+  --type <Step 3 选定的类型> \
+  --tag session \
+  --kb <kb-name> \
+  --format json
+```
+
+## 命令参考
+
+```bash
+# 直接添加（短内容）
+jfox add "<summary>" --title "Session: <topic>" --type <type> --tag session --kb <name>
+
+# 从文件添加（长内容或含特殊字符）
+jfox add --content-file <path> --title "Session: <topic>" --type <type> --tag session --kb <name>
+
+# 验证写入
+jfox show <note_id> --format json
+```
+
+## 错误处理
+
+- **"Knowledge base not found"**: 提示用户先运行 `/jfox-common` 创建知识库
+- **内容过长导致 shell 解析失败**: 切换到 `--content-file` 方式
+- **特殊字符转义问题**: 使用单引号包裹内容，或写入临时文件
+```
+
+- [ ] **Step 3: Verify the file reads correctly**
+
+Read the full updated `SKILL.md` and confirm:
+1. Step 1 (生成会话总结) is unchanged
+2. Step 2 (用户确认) has AskUserQuestion with "内容没问题" and "需要修改" options, plus loop description
+3. Step 3 (选择笔记类型) has AskUserQuestion with fleeting/literature/permanent options
+4. Step 4 (写入知识库) uses `<Step 3 选定的类型>` not hardcoded `fleeting`
+5. Step 5 (处理长内容) also uses `<Step 3 选定的类型>`
+6. 命令参考 section shows `--type <type>` not `--type fleeting`
+7. No leftover hardcoded `fleeting` in any `jfox add` example (except the Step 3 option description)
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add skills-recommend/claude-code/jfox-session-summary/SKILL.md
+git commit -m "feat(skill): add user confirmation and note type selection to session-summary
+
+Inserts Step 2 (content confirmation via AskUserQuestion) and Step 3
+(note type selection) before writing to knowledge base. Users can now
+review the generated summary, request modifications, and choose between
+fleeting/literature/permanent note types.
+
+Closes #154"
+```

jfox_cli-0.4.0/docs/superpowers/specs/2026-04-15-session-summary-confirmation-design.md

@@ -0,0 +1,52 @@
+# jfox-session-summary 用户确认流程设计
+
+**Date**: 2026-04-15
+**Issue**: #154
+**Status**: Draft
+
+## 背景
+
+当前 `jfox-session-summary` skill 生成总结后直接写入知识库，硬编码 `--type fleeting`。用户无法审查内容或选择笔记类型。
+
+## 改动范围
+
+仅修改 `skills-recommend/claude-code/jfox-session-summary/SKILL.md`。不涉及 CLI 命令或 Python 代码变更。
+
+## 新流程
+
+当前 3 步扩展为 5 步：
+
+| Step | 内容 | 状态 |
+|------|------|------|
+| Step 1 | 生成会话总结 | 不变 |
+| Step 2 | 展示总结 + 用户确认 | **新增** |
+| Step 3 | 选择笔记类型 | **新增** |
+| Step 4 | `jfox add --type <选择>` | 原 Step 2 |
+| Step 5 | 处理长内容 | 原 Step 3，不变 |
+
+### Step 2：展示总结 + 用户确认
+
+1. 用普通文本输出完整总结内容，供用户阅读
+2. 使用 `AskUserQuestion` 询问「笔记内容是否 OK？」
+   - **内容没问题** → 继续 Step 3
+   - **需要修改** → 用户在 Other 中输入修改意见 → 根据意见调整总结 → 回到 Step 2 重新展示和确认
+3. 循环直到用户满意为止
+
+### Step 3：选择笔记类型
+
+使用 `AskUserQuestion` 询问「选择笔记类型」：
+
+- **fleeting**（推荐）— 会话记录是临时性笔记，后续可提炼为 permanent
+- **literature** — 会话有明确的参考资料来源
+- **permanent** — 总结已经是成熟的知识
+
+### Step 4：写入知识库
+
+`jfox add` 的 `--type` 参数使用 Step 3 的选择结果，不再硬编码 `fleeting`。其余参数（`--title`、`--tag session`、`--kb`）不变。
+
+## 不在范围内
+
+- 不修改 `jfox add` CLI 命令本身
+- 不增加新的笔记类型
+- 不改变总结模板格式（Step 1 不变）
+- 不做自动检测笔记类型的智能逻辑

{jfox_cli-0.3.2 → jfox_cli-0.4.0}/jfox/__init__.py

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

{jfox_cli-0.3.2 → jfox_cli-0.4.0}/jfox/cli.py

@@ -8,6 +8,8 @@ from datetime import datetime
 from pathlib import Path
 from typing import List, Optional
 
+import yaml
+
 # Windows 下强制 UTF-8 输出，避免中文乱码
 if sys.platform == "win32":
     if hasattr(sys.stdout, "reconfigure"):
@@ -52,6 +54,9 @@ for _lib in (
 
 logger = logging.getLogger(__name__)
 
+# config set 支持的配置项
+_VALID_CONFIG_KEYS = {"device", "embedding_model", "batch_size"}
+
 # 创建应用
 app = typer.Typer(
     name="jfox",
@@ -569,6 +574,104 @@ def search(
         raise typer.Exit(1)
 
 
+def _warn_dimension_change(new_model: str):
+    """切换 embedding 模型时警告用户重建索引"""
+    if new_model == "auto":
+        return  # auto 模式不需要警告
+    try:
+        import chromadb
+
+        chroma_path = config.chroma_dir
+        if not chroma_path.exists():
+            return
+        client = chromadb.PersistentClient(path=str(chroma_path))
+        collection = client.get_collection("notes")
+        if collection.count() == 0:
+            return  # 空索引，无需警告
+    except Exception:
+        return
+
+    # 有已有索引 + 换了模型 = 需要重建
+    console.print(
+        f"\n[yellow]⚠ 模型已更改为 {new_model}[/yellow]\n"
+        f"[yellow]  如果检索结果异常，请重建索引:[/yellow]\n"
+        f"  jfox index rebuild\n"
+    )
+
+
+def _config_set_impl(key: str, value: str):
+    """设置知识库配置项"""
+    if key not in _VALID_CONFIG_KEYS:
+        raise ValueError(f"不支持的配置项: {key}，可选值: {', '.join(sorted(_VALID_CONFIG_KEYS))}")
+
+    config_path = config.zk_dir / "config.yaml"
+
+    # 读取现有配置
+    if config_path.exists():
+        with open(config_path, "r", encoding="utf-8") as f:
+            data = yaml.safe_load(f) or {}
+    else:
+        data = {}
+
+    # 类型转换
+    if key == "batch_size":
+        value = int(value)
+
+    # 写入配置
+    data[key] = value
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(config_path, "w", encoding="utf-8") as f:
+        yaml.dump(data, f, allow_unicode=True, sort_keys=False)
+
+    # 同步更新内存中的 config 对象
+    setattr(config, key, value if key != "batch_size" else int(value))
+
+    # 重置 backend 单例，让新配置在下次使用时生效
+    from .embedding_backend import reset_backend
+
+    reset_backend()
+
+    console.print(f"[green]✓ {key} = {value}[/green]")
+
+    # 切换模型时检查维度
+    if key == "embedding_model":
+        _warn_dimension_change(value)
+
+
+@app.command(name="config")
+def config_cmd(
+    action: str = typer.Argument(..., help="操作: set"),
+    key: str = typer.Argument(None, help="配置项名称"),
+    value: str = typer.Argument(None, help="配置值"),
+):
+    """
+    查看/修改知识库配置
+
+    示例:
+
+        jfox config set device cuda
+        jfox config set device auto
+        jfox config set embedding_model BAAI/bge-m3
+        jfox config set embedding_model auto
+    """
+    try:
+        if action == "set":
+            if key is None:
+                console.print("[red]✗ 缺少配置项名称[/red]")
+                raise typer.Exit(1)
+            if value is None:
+                console.print("[red]✗ 缺少配置值[/red]")
+                raise typer.Exit(1)
+            _config_set_impl(key, value)
+        else:
+            console.print(f"[red]✗ 未知操作: {action}[/red]")
+            console.print("  可用操作: set")
+            raise typer.Exit(1)
+    except ValueError as e:
+        console.print(f"[red]✗ {e}[/red]")
+        raise typer.Exit(1)
+
+
 def _status_impl(output_format: str, json_output: bool):
     """查看知识库状态的内部实现"""
     from .formatters import OutputFormatter
@@ -587,8 +690,9 @@ def _status_impl(output_format: str, json_output: bool):
         },
         "stats": stats,
         "backend": {
-            "type": "CPU",
-            "model": backend.model_name if backend.model else "not loaded",
+            "type": backend.resolved_device,
+            "model": backend.model_name or "auto (未加载)",
+            "dimension": backend.dimension,
         },
     }
 
@@ -612,8 +716,9 @@ def _status_impl(output_format: str, json_output: bool):
         table.add_row("Fleeting", str(stats["by_type"].get("fleeting", 0)))
         table.add_row("Literature", str(stats["by_type"].get("literature", 0)))
         table.add_row("Permanent", str(stats["by_type"].get("permanent", 0)))
-        table.add_row("Backend", "CPU")
-        table.add_row("Model", backend.model_name)
+        table.add_row("Backend", backend.resolved_device)
+        table.add_row("Model", backend.model_name or "auto (未加载)")
+        table.add_row("Dimension", str(backend.dimension))
 
         console.print(table)
     else:
@@ -2520,6 +2625,7 @@ def daemon(
                     table.add_row("端口", str(info["port"]))
                     table.add_row("模型", info["model"])
                     table.add_row("维度", str(info["dimension"]))
+                    table.add_row("设备", info.get("device", "unknown"))
                     console.print(table)
                 else:
                     console.print("[green]✓ Daemon 已启动[/green]")
@@ -2546,6 +2652,7 @@ def daemon(
                 table.add_row("端口", str(info["port"]))
                 table.add_row("模型", info.get("model", "unknown"))
                 table.add_row("维度", str(info.get("dimension", "unknown")))
+                table.add_row("设备", info.get("device", "unknown"))
                 console.print(table)
             else:
                 console.print("[dim]Daemon 未运行[/dim]")

{jfox_cli-0.3.2 → jfox_cli-0.4.0}/jfox/config.py

@@ -28,10 +28,10 @@ class ZKConfig:
     zk_dir: Path = field(init=False)
     chroma_dir: Path = field(init=False)
 
-    # NPU 配置
-    embedding_model: str = "sentence-transformers/all-MiniLM-L6-v2"
-    embedding_dimension: int = 384
-    device: str = "auto"  # auto / npu / gpu / cpu
+    # Embedding 配置
+    embedding_model: str = "auto"  # auto = 根据 device 自动选择模型
+    embedding_dimension: int = 0  # 0 = 动态，由模型决定
+    device: str = "auto"  # auto / cuda / cpu
     batch_size: int = 32
 
     # 检索配置
@@ -122,13 +122,14 @@ config = get_config()
 
 
 def _reset_singletons():
-    """重置所有缓存的单例（搜索引擎、向量存储、BM25 索引）"""
+    """重置所有缓存的单例（搜索引擎、向量存储、BM25 索引、embedding 后端）"""
     import importlib
 
     for module_name, fn_name in [
         (".bm25_index", "reset_bm25_index"),
         (".search_engine", "reset_search_engine"),
         (".vector_store", "reset_vector_store"),
+        (".embedding_backend", "reset_backend"),
     ]:
         try:
             module = importlib.import_module(module_name, package="jfox")

{jfox_cli-0.3.2 → jfox_cli-0.4.0}/jfox/daemon/process.py

@@ -16,6 +16,23 @@ from typing import Optional
 
 from . import DEFAULT_HOST, DEFAULT_PORT
 
+
+def _get_pythonw_executable() -> str:
+    """获取 pythonw.exe 路径（Windows 无控制台入口）
+
+    Windows 上优先使用 pythonw.exe 避免 daemon 子进程弹出控制台窗口。
+    如果 pythonw.exe 不存在则回退到 sys.executable。
+    非 Windows 平台直接返回 sys.executable。
+    """
+    if sys.platform != "win32":
+        return sys.executable
+
+    pythonw = sys.executable.replace("python.exe", "pythonw.exe")
+    if pythonw != sys.executable and Path(pythonw).exists():
+        return pythonw
+    return sys.executable
+
+
 logger = logging.getLogger(__name__)
 
 STARTUP_TIMEOUT = 60  # 模型加载可能较慢
@@ -107,8 +124,16 @@ def start_daemon(host: str = DEFAULT_HOST, port: int = DEFAULT_PORT) -> bool:
         )
         return True
 
-    # 构建启动命令
-    cmd = [sys.executable, "-m", "jfox.daemon.server", "--host", host, "--port", str(port)]
+    # 构建启动命令（Windows 使用 pythonw.exe 避免控制台窗口）
+    cmd = [
+        _get_pythonw_executable(),
+        "-m",
+        "jfox.daemon.server",
+        "--host",
+        host,
+        "--port",
+        str(port),
+    ]
 
     kwargs = {}
     if sys.platform == "win32":
@@ -222,5 +247,6 @@ def get_daemon_status() -> Optional[dict]:
         "port": port,
         "model": health.get("model", "unknown"),
         "dimension": health.get("dimension", 384),
+        "device": health.get("device", "unknown"),
         "started_at": data.get("started_at") if data else None,
     }

{jfox_cli-0.3.2 → jfox_cli-0.4.0}/jfox/daemon/server.py

@@ -26,12 +26,17 @@ def _load_model():
     """启动时加载模型（标记为 daemon 进程，防止自引用）"""
     global _backend
     os.environ["JFOX_DAEMON_PROCESS"] = "1"
+    from ..config import config
     from ..embedding_backend import EmbeddingBackend
 
-    _backend = EmbeddingBackend()
+    model_name = config.embedding_model if config.embedding_model != "auto" else None
+    _backend = EmbeddingBackend(device=config.device, model_name=model_name)
     try:
         _backend.load()
-        logger.info(f"Daemon: 模型已加载 ({_backend.model_name})")
+        logger.info(
+            f"Daemon: 模型已加载 {_backend.model_name} "
+            f"(device={_backend._resolved_device}, dimension={_backend._resolved_dim})"
+        )
     except Exception as e:
         logger.error(f"Daemon: 模型加载失败，进程退出: {e}")
         os._exit(1)
@@ -46,6 +51,7 @@ class HealthResponse(BaseModel):
     status: str
     model: str
     dimension: int
+    device: str  # 实际使用的设备
     pid: int
 
 
@@ -80,6 +86,7 @@ def health():
         status="ok",
         model=_backend.model_name,
         dimension=_backend.dimension,
+        device=_backend.resolved_device,
         pid=os.getpid(),
     )
 

jfox_cli-0.4.0/jfox/embedding_backend.py

@@ -0,0 +1,174 @@
+"""Embedding Backend - 支持 daemon 加速 + GPU (CUDA)"""
+
+import logging
+import os
+from typing import List, Optional
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+# 默认模型
+_GPU_DEFAULT_MODEL = "BAAI/bge-m3"
+_CPU_DEFAULT_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
+
+
+class EmbeddingBackend:
+    """嵌入模型后端（支持 daemon 代理 + GPU 加速）"""
+
+    def __init__(self, model_name: Optional[str] = None, device: str = "auto"):
+        self.model_name = model_name  # None/"auto" 表示由 device 自动决定
+        self.device = device
+        self.model = None
+        self._daemon_client = None  # 延迟初始化
+        self._use_daemon: Optional[bool] = None  # None=未检测
+        self._resolved_device: Optional[str] = None  # 实际解析后的设备
+        self._resolved_dim: Optional[int] = None  # 实际嵌入维度
+
+    def _resolve_device(self) -> str:
+        """解析 device 字符串为实际设备名"""
+        if self.device != "auto":
+            return self.device
+        try:
+            import torch
+
+            if torch.cuda.is_available():
+                device_name = torch.cuda.get_device_name(0)
+                logger.info(f"检测到 CUDA 可用 ({device_name}), 使用 GPU")
+                return "cuda"
+        except Exception:
+            # ImportError: torch 未安装; 其他: CUDA 驱动异常等
+            pass
+        logger.info("CUDA 不可用, 使用 CPU")
+        return "cpu"
+
+    def _resolve_model_name(self, resolved_device: str) -> str:
+        """根据 device 和用户配置决定使用哪个模型"""
+        if self.model_name is not None and self.model_name != "auto":
+            return self.model_name
+        return _GPU_DEFAULT_MODEL if resolved_device == "cuda" else _CPU_DEFAULT_MODEL
+
+    def _check_daemon(self) -> bool:
+        """检测是否使用 daemon（仅检测一次，缓存结果）"""
+        if self._use_daemon is not None:
+            return self._use_daemon
+
+        # daemon 进程内不应连接自己
+        if os.environ.get("JFOX_DAEMON_PROCESS"):
+            self._use_daemon = False
+            return False
+
+        try:
+            from .daemon.process import _get_daemon_url, is_daemon_running
+
+            if is_daemon_running():
+                from .daemon.client import DaemonClient
+
+                url = _get_daemon_url()
+                client = DaemonClient(url)
+                if client.available:
+                    self._daemon_client = client
+                    self._use_daemon = True
+                    logger.info("使用远程 embedding daemon")
+                    return True
+        except Exception:
+            pass
+
+        self._use_daemon = False
+        return False
+
+    def load(self):
+        """加载模型（支持 device 自动检测和 GPU 加速）"""
+        if self.model is not None:
+            return
+
+        # 解析 device 和 model（即使 daemon 模式也需要，用于 status 显示）
+        if self._resolved_device is None:
+            self._resolved_device = self._resolve_device()
+        if self.model_name is None or self.model_name == "auto":
+            self.model_name = self._resolve_model_name(self._resolved_device)
+
+        if self._check_daemon():
+            return  # daemon 已持有模型，无需本地加载
+
+        try:
+            from sentence_transformers import SentenceTransformer
+
+            self.model = SentenceTransformer(self.model_name, device=self._resolved_device)
+            self._resolved_dim = self.model.get_sentence_embedding_dimension()
+            logger.info(
+                f"模型已加载: {self.model_name} "
+                f"(device={self._resolved_device}, dimension={self._resolved_dim})"
+            )
+        except Exception as e:
+            logger.error(f"加载模型失败: {e}")
+            raise
+
+    def encode(self, texts: List[str], batch_size: int = 32) -> np.ndarray:
+        """文本编码（优先使用 daemon）"""
+        # 优先使用 daemon
+        if self._check_daemon() and self._daemon_client is not None:
+            try:
+                return self._daemon_client.encode(texts, batch_size=batch_size)
+            except Exception as e:
+                logger.warning(f"Daemon 编码失败，回退到本地: {e}")
+                self._use_daemon = False
+
+        if self.model is None:
+            self.load()
+
+        try:
+            return self.model.encode(
+                texts, batch_size=batch_size, show_progress_bar=False, convert_to_numpy=True
+            )
+        except Exception as e:
+            logger.error(f"编码失败: {e}")
+            raise
+
+    def encode_single(self, text: str) -> np.ndarray:
+        """单文本编码"""
+        return self.encode([text])[0]
+
+    @property
+    def dimension(self) -> int:
+        """返回嵌入维度（动态读取）"""
+        if self._resolved_dim is not None:
+            return self._resolved_dim
+        if self.model is not None:
+            return self.model.get_sentence_embedding_dimension()
+        # daemon 模式下从 daemon client 获取维度
+        if self._daemon_client is not None:
+            return self._daemon_client.dimension
+        # 未加载时：如果 model_name 已确定，估算维度
+        if self.model_name and self.model_name != "auto":
+            if "bge-m3" in self.model_name or "bge-large" in self.model_name:
+                return 1024
+        return 384  # 默认 MiniLM 维度
+
+    @property
+    def resolved_device(self) -> str:
+        """实际使用的设备（auto 解析后）"""
+        return self._resolved_device or "unknown"
+
+
+# Global backend instance
+_backend: Optional[EmbeddingBackend] = None
+
+
+def get_backend() -> EmbeddingBackend:
+    """获取全局 embedding 后端实例（从 config 读取配置）"""
+    global _backend
+    if _backend is None:
+        from .config import config
+
+        model_name = config.embedding_model
+        if model_name == "auto":
+            model_name = None  # 交给 EmbeddingBackend 根据 device 自动决定
+        _backend = EmbeddingBackend(model_name=model_name, device=config.device)
+    return _backend
+
+
+def reset_backend():
+    """重置全局 embedding 后端（用于测试或特殊场景）"""
+    global _backend
+    _backend = None

{jfox_cli-0.3.2 → jfox_cli-0.4.0}/pyproject.toml

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