jfox-cli 0.4.2__tar.gz → 0.4.3__tar.gz

{jfox_cli-0.4.2 → jfox_cli-0.4.3}/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to jfox-cli will be documented in this file.
 
+## [0.4.3] - 2026-04-28
+
+### Features
+- 内网模型自动下载（3步降级重试链） (#173)
+
+### Fixes
+- **daemon**: eliminate deprecation warnings in daemon log (#171)
+
+[0.4.3]: https://github.com/zhuxixi/jfox/compare/v0.4.2...v0.4.3
+
 ## [0.4.2] - 2026-04-22
 
 ### Features

{jfox_cli-0.4.2 → jfox_cli-0.4.3}/PKG-INFO

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

{jfox_cli-0.4.2 → jfox_cli-0.4.3}/jfox/__init__.py

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

{jfox_cli-0.4.2 → jfox_cli-0.4.3}/jfox/cli.py

@@ -88,6 +88,10 @@ def _main(
 # 添加子命令
 app.add_typer(template_app, name="template", help="Manage note templates")
 
+# Model 下载子命令
+model_app = typer.Typer(name="model", help="模型管理")
+app.add_typer(model_app, name="model", help="模型管理")
+
 console = Console(legacy_windows=False)
 
 
@@ -2674,6 +2678,84 @@ def daemon(
         raise typer.Exit(1)
 
 
+def _download_impl(
+    model: Optional[str],
+    force: bool = False,
+) -> dict:
+    """下载模型实现（可复用）"""
+    from .embedding_backend import EmbeddingBackend
+    from .model_downloader import ModelDownloader
+
+    # 解析模型名
+    if model is None or model == "auto":
+        backend = EmbeddingBackend()
+        device = backend._resolve_device()
+        model = backend._resolve_model_name(device)
+
+    downloader = ModelDownloader(model)
+
+    if force and downloader._check_cached():
+        import shutil
+
+        shutil.rmtree(downloader._model_cache, ignore_errors=True)
+
+    ok = downloader.ensure_cached()
+    return {
+        "model": model,
+        "success": ok,
+        "cache_dir": str(downloader._model_cache),
+        "instructions": downloader.get_manual_instructions() if not ok else "",
+    }
+
+
+@model_app.command("download")
+def download(
+    model: Optional[str] = typer.Option(
+        None, "--model", "-m", help="模型名（默认从配置读取，auto 则按设备自动选择）"
+    ),
+    force: bool = typer.Option(False, "--force", "-f", help="强制重新下载（覆盖已有缓存）"),
+    kb: Optional[str] = typer.Option(
+        None, "--kb", "-k", help="目标知识库名称（模型下载不依赖知识库）"
+    ),
+    output_format: str = typer.Option("table", "--format", help="输出格式: json, table"),
+    json_output: bool = typer.Option(False, "--json", help="JSON 输出快捷方式"),
+):
+    """
+    手动下载 embedding 模型
+
+    自动尝试 3 种下载方式（huggingface_hub → 镜像站 → curl）。
+    通常不需要手动调用，daemon start 会自动执行。
+
+    示例:
+
+        jfox model download                    # 下载默认模型
+        jfox model download --model bge-m3     # 下载指定模型
+        jfox model download --force            # 强制重新下载
+        jfox model download --json             # JSON 输出
+    """
+    # kb 参数保持 CLI 一致性（模型下载不依赖知识库）
+    _ = kb
+
+    if json_output:
+        output_format = "json"
+
+    console.print(f"[yellow]准备下载模型: {model or 'auto'}[/yellow]")
+
+    result = _download_impl(model=model, force=force)
+
+    if output_format == "json":
+        console.print(output_json(result))
+    else:
+        if result["success"]:
+            console.print(f"[green]✓ 模型下载完成: {result['model']}[/green]")
+        else:
+            console.print("[red]✗ 模型下载失败[/red]")
+            console.print(Panel(result["instructions"], title="手动下载"))
+
+    if not result["success"]:
+        raise typer.Exit(1)
+
+
 # 入口点
 def main():
     """CLI 入口点"""

{jfox_cli-0.4.2 → jfox_cli-0.4.3}/jfox/daemon/process.py

@@ -47,7 +47,7 @@ def _read_pid_file() -> Optional[dict]:
         return None
     try:
         return json.loads(PID_FILE.read_text(encoding="utf-8"))
-    except Exception:
+    except (OSError, ValueError):
         return None
 
 
@@ -84,7 +84,7 @@ def _http_health_check(host: str = DEFAULT_HOST, port: int = DEFAULT_PORT) -> Op
 
         resp = urllib.request.urlopen(f"http://{host}:{port}/health", timeout=2)
         return json.loads(resp.read().decode("utf-8"))
-    except Exception:
+    except (OSError, ValueError):
         return None
 
 
@@ -126,7 +126,7 @@ def _check_model_cache() -> dict:
                     model_name = _GPU_DEFAULT_MODEL
                 else:
                     model_name = _CPU_DEFAULT_MODEL
-            except Exception:
+            except (ImportError, OSError):
                 model_name = _CPU_DEFAULT_MODEL
 
         # 检查 HuggingFace 缓存
@@ -150,7 +150,7 @@ def _check_model_cache() -> dict:
             "model_name": model_name,
             "size_hint": size_hint,
         }
-    except Exception as e:
+    except (ImportError, OSError, ValueError) as e:
         logger.debug(f"Model cache check failed, assuming download needed: {e}")
         return {"needs_download": True, "model_name": "unknown", "size_hint": ""}
 
@@ -185,6 +185,17 @@ def start_daemon(host: str = DEFAULT_HOST, port: int = DEFAULT_PORT) -> bool:
         )
         timeout = FIRST_RUN_TIMEOUT
 
+        # 自动下载模型（内网降级重试）
+        try:
+            from ..model_downloader import ModelDownloader
+
+            downloader = ModelDownloader(cache_info["model_name"])
+            if not downloader.ensure_cached():
+                logger.error("模型自动下载失败")
+                # 不阻断启动，让 daemon 自己去尝试加载（会暴露更详细的错误日志）
+        except (ImportError, OSError) as e:
+            logger.warning(f"模型下载检查异常: {e}")
+
     # 构建启动命令（Windows 使用 pythonw.exe 避免控制台窗口）
     cmd = [
         _get_pythonw_executable(),
@@ -218,7 +229,7 @@ def start_daemon(host: str = DEFAULT_HOST, port: int = DEFAULT_PORT) -> bool:
         )
         logger.info(f"Daemon 进程已启动 (PID: {proc.pid})")
         logger.info(f"Daemon 日志文件: {DAEMON_LOG_FILE}")
-    except Exception as e:
+    except (OSError, subprocess.SubprocessError) as e:
         log_file.close()
         logger.error(f"启动 daemon 失败: {e}")
         return False
@@ -280,7 +291,7 @@ def stop_daemon() -> bool:
                 )
             else:
                 os.kill(pid, 15)  # SIGTERM
-        except Exception as e:
+        except (OSError, subprocess.SubprocessError) as e:
             logger.warning(f"停止 daemon 失败: {e}")
 
     # 等待进程退出

{jfox_cli-0.4.2 → jfox_cli-0.4.3}/jfox/daemon/server.py

@@ -8,6 +8,7 @@
 import argparse
 import logging
 import os
+from contextlib import asynccontextmanager
 from typing import List
 
 from fastapi import FastAPI
@@ -15,13 +16,10 @@ from pydantic import BaseModel
 
 logger = logging.getLogger(__name__)
 
-app = FastAPI(title="JFox Embedding Daemon")
-
 # 全局 embedding 后端（模型加载后常驻内存）
 _backend = None
 
 
-@app.on_event("startup")
 def _load_model():
     """启动时加载模型（标记为 daemon 进程，防止自引用）"""
     global _backend
@@ -42,6 +40,15 @@ def _load_model():
         os._exit(1)
 
 
+@asynccontextmanager
+async def lifespan(app):
+    _load_model()
+    yield
+
+
+app = FastAPI(title="JFox Embedding Daemon", lifespan=lifespan)
+
+
 # =============================================================================
 # 请求/响应模型
 # =============================================================================

jfox_cli-0.4.3/jfox/model_downloader.py

@@ -0,0 +1,224 @@
+"""模型下载器 - 支持内网自动降级下载"""
+
+import logging
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Optional
+from urllib.parse import quote
+
+logger = logging.getLogger(__name__)
+
+# 镜像站地址
+_HF_MIRROR = "https://hf-mirror.com"
+
+# 重试超时（秒）
+_TIMEOUT_HF_HUB = 60
+_TIMEOUT_CURL = 120
+
+# 需要下载的文件列表（按重要性排序）
+_REQUIRED_FILES = [
+    "model.safetensors",
+    "config.json",
+    "tokenizer.json",
+    "tokenizer_config.json",
+    "sentence_bert_config.json",
+]
+
+
+class ModelDownloader:
+    """模型下载器，支持全自动降级重试链"""
+
+    def __init__(self, model_name: str):
+        self.model_name = model_name
+        self._hf_hub_cache = self._get_hf_hub_cache()
+        # 同时替换正反斜杠，防止路径遍历
+        safe_name = model_name.replace("/", "--").replace("\\", "--")
+        self._model_cache = self._hf_hub_cache / f"models--{safe_name}"
+
+    def _get_hf_hub_cache(self) -> Path:
+        """获取 HuggingFace Hub 缓存目录"""
+        try:
+            import huggingface_hub.constants
+
+            return Path(huggingface_hub.constants.HUGGINGFACE_HUB_CACHE)
+        except ImportError:
+            hf_home = os.environ.get("HF_HOME", str(Path.home() / ".cache" / "huggingface"))
+            return Path(hf_home) / "hub"
+
+    def ensure_cached(self) -> bool:
+        """
+        确保模型已缓存。按重试链逐层降级。
+        返回 True 表示成功（无论哪一步成功）。
+        """
+        if self._check_cached():
+            logger.info(f"模型已缓存: {self.model_name}")
+            return True
+
+        logger.info(f"缓存未命中: {self.model_name}，开始下载")
+
+        # Step 1: 正常下载
+        logger.info("步骤 1: 使用 huggingface_hub 正常下载...")
+        if self._try_hf_hub_download():
+            logger.info("步骤 1 成功，模型已缓存")
+            return True
+        logger.warning("步骤 1 失败，进入步骤 2")
+
+        # Step 2: 镜像站下载
+        logger.info(f"步骤 2: 切换 HF_ENDPOINT={_HF_MIRROR} 重试...")
+        if self._try_hf_hub_download(endpoint=_HF_MIRROR):
+            logger.info("步骤 2 成功，模型已缓存")
+            return True
+        logger.warning("步骤 2 失败，进入步骤 3")
+
+        # Step 3: curl 子进程下载
+        logger.info("步骤 3: 使用 curl 子进程从镜像站下载...")
+        if self._try_curl_download():
+            logger.info("步骤 3 成功，模型已缓存")
+            return True
+        logger.error("步骤 3 失败，所有自动方式均已尝试")
+
+        return False
+
+    def _check_cached(self) -> bool:
+        """检查模型是否已在 HuggingFace 缓存目录中存在"""
+        if not self._model_cache.exists():
+            return False
+        snapshots_dir = self._model_cache / "snapshots"
+        if not snapshots_dir.exists():
+            return False
+        # 检查至少有一个 snapshot 且包含 model.safetensors
+        try:
+            for snapshot in snapshots_dir.iterdir():
+                if snapshot.is_dir():
+                    if (snapshot / "model.safetensors").exists():
+                        return True
+        except OSError:
+            logger.warning(f"无法遍历缓存目录: {snapshots_dir}")
+            return False
+        return False
+
+    def _try_hf_hub_download(self, endpoint: Optional[str] = None) -> bool:
+        """
+        使用 huggingface_hub 下载模型。
+        endpoint=None 为正常模式；endpoint 为镜像站地址。
+        """
+        env_backup = None
+        try:
+            from huggingface_hub import hf_hub_download
+
+            if endpoint:
+                env_backup = os.environ.get("HF_ENDPOINT")
+                os.environ["HF_ENDPOINT"] = endpoint
+
+            # 下载核心文件
+            hf_hub_download(
+                repo_id=self.model_name,
+                filename="model.safetensors",
+                cache_dir=str(self._hf_hub_cache),
+                local_files_only=False,
+            )
+            # 尝试下载其他必要文件（不失败）
+            for fname in _REQUIRED_FILES[1:]:
+                try:
+                    hf_hub_download(
+                        repo_id=self.model_name,
+                        filename=fname,
+                        cache_dir=str(self._hf_hub_cache),
+                        local_files_only=False,
+                    )
+                except (OSError, ValueError):
+                    pass  # 非核心文件，缺失不影响基本功能
+
+            return True
+        except Exception as e:
+            logger.warning(f"huggingface_hub 下载失败: {e}")
+            return False
+        finally:
+            if env_backup is not None:
+                os.environ["HF_ENDPOINT"] = env_backup
+            elif endpoint and "HF_ENDPOINT" in os.environ:
+                del os.environ["HF_ENDPOINT"]
+
+    def _try_curl_download(self) -> bool:
+        """
+        使用 curl 子进程下载模型文件到 HF 缓存目录。
+        按 HF 缓存目录结构放置，使 sentence-transformers 认为"模型已缓存"。
+        """
+        if not shutil.which("curl"):
+            logger.warning("系统未安装 curl，跳过步骤 3")
+            return False
+
+        # 构建镜像站 URL（对模型名进行 URL 编码，防止特殊字符破坏 URL）
+        encoded_name = quote(self.model_name, safe="/")
+        base_url = f"{_HF_MIRROR}/{encoded_name}/resolve/main"
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            tmp_path = Path(tmpdir)
+            downloaded = []
+
+            for fname in _REQUIRED_FILES:
+                url = f"{base_url}/{fname}"
+                dest = tmp_path / fname
+                logger.info(f"下载 {fname}...")
+                try:
+                    result = subprocess.run(
+                        [
+                            "curl",
+                            "-L",
+                            "-f",
+                            "-s",
+                            "-S",
+                            "--connect-timeout",
+                            "10",
+                            "--max-time",
+                            str(_TIMEOUT_CURL),
+                            "-o",
+                            str(dest),
+                            url,
+                        ],
+                        capture_output=True,
+                        text=True,
+                        timeout=_TIMEOUT_CURL + 5,
+                    )
+                    if result.returncode == 0 and dest.exists() and dest.stat().st_size > 0:
+                        downloaded.append(fname)
+                    else:
+                        logger.debug(f"{fname} 下载失败或为空，跳过")
+                except (OSError, subprocess.TimeoutExpired) as e:
+                    logger.debug(f"{fname} 下载异常: {e}")
+
+            if "model.safetensors" not in downloaded:
+                logger.error("model.safetensors 下载失败，步骤 3 未完成")
+                return False
+
+            # 按 HF 缓存目录结构放置
+            import hashlib
+
+            commit_hash = hashlib.sha256(self.model_name.encode()).hexdigest()[:12]
+            snapshot_dir = self._model_cache / "snapshots" / commit_hash
+            snapshot_dir.mkdir(parents=True, exist_ok=True)
+
+            for fname in downloaded:
+                src = tmp_path / fname
+                dst = snapshot_dir / fname
+                shutil.copy2(str(src), str(dst))
+
+            # 创建 refs 指向 snapshot
+            refs_dir = self._model_cache / "refs"
+            refs_dir.mkdir(parents=True, exist_ok=True)
+            (refs_dir / "main").write_text(commit_hash, encoding="utf-8")
+
+            return True
+
+    def get_manual_instructions(self) -> str:
+        """获取手动下载说明"""
+        return (
+            f"自动下载失败。请手动下载模型:\n"
+            f"  1. 访问 {_HF_MIRROR}/{self.model_name}\n"
+            f"  2. 下载 model.safetensors 和 config.json\n"
+            f"  3. 放置到 {self._model_cache}/snapshots/\n"
+            f"  或运行: bash scripts/download-model-intranet.sh"
+        )

{jfox_cli-0.4.2 → jfox_cli-0.4.3}/jfox/performance.py

@@ -141,7 +141,7 @@ class BatchProcessor:
                 except Exception as e:
                     logger.warning(f"Failed to encode batch {i}: {e}")
                     # 失败时返回零向量
-                    dim = backend.model.get_sentence_embedding_dimension()
+                    dim = backend.dimension
                     results.extend([[0.0] * dim] * len(batch))
 
                 if progress and task is not None:

{jfox_cli-0.4.2 → jfox_cli-0.4.3}/pyproject.toml

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

jfox_cli-0.4.3/scripts/download-model-intranet.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# =============================================================================
+# JFox 内网模型下载脚本
+# 当 huggingface_hub 无法工作时，使用 curl 手动下载模型
+# =============================================================================
+
+MODEL_NAME="${1:-sentence-transformers/all-MiniLM-L6-v2}"
+HF_MIRROR="https://hf-mirror.com"
+
+# 获取 HF 缓存目录
+HF_HOME="${HF_HOME:-$HOME/.cache/huggingface}"
+HUB_CACHE="${HUGGINGFACE_HUB_CACHE:-$HF_HOME/hub}"
+MODEL_CACHE="$HUB_CACHE/models--${MODEL_NAME//\//--}"
+
+info()  { echo -e "\033[0;32m[INFO]\033[0m $*"; }
+warn()  { echo -e "\033[1;33m[WARN]\033[0m $*"; }
+error() { echo -e "\033[0;31m[ERROR]\033[0m $*" >&2; }
+
+# 检查 curl
+if ! command -v curl > /dev/null 2>&1; then
+    error "curl 未安装，请先安装 curl"
+    exit 1
+fi
+
+info "目标模型: $MODEL_NAME"
+info "缓存目录: $MODEL_CACHE"
+
+# 生成伪 commit hash
+COMMIT_HASH=$(echo -n "$MODEL_NAME" | sha256sum | cut -c1-12)
+SNAPSHOT_DIR="$MODEL_CACHE/snapshots/$COMMIT_HASH"
+
+mkdir -p "$SNAPSHOT_DIR"
+
+# 下载文件列表
+FILES=("model.safetensors" "config.json" "tokenizer.json" "tokenizer_config.json")
+
+for fname in "${FILES[@]}"; do
+    URL="$HF_MIRROR/$MODEL_NAME/resolve/main/$fname"
+    DEST="$SNAPSHOT_DIR/$fname"
+
+    if [ -f "$DEST" ] && [ -s "$DEST" ]; then
+        info "$fname 已存在，跳过"
+        continue
+    fi
+
+    info "下载 $fname..."
+    if curl -L -f -s -S --connect-timeout 10 --max-time 120 \
+         -o "$DEST" "$URL"; then
+        info "$fname 下载完成"
+    else
+        warn "$fname 下载失败或不存在，跳过"
+        rm -f "$DEST"
+    fi
+done
+
+# 检查核心文件
+if [ ! -f "$SNAPSHOT_DIR/model.safetensors" ]; then
+    error "model.safetensors 下载失败"
+    exit 1
+fi
+
+# 创建 refs
+mkdir -p "$MODEL_CACHE/refs"
+echo "$COMMIT_HASH" > "$MODEL_CACHE/refs/main"
+
+info "模型下载完成: $MODEL_CACHE"
+info "现在可以运行: jfox daemon start"

jfox_cli-0.4.3/tests/integration/test_model_download.py

@@ -0,0 +1,105 @@
+"""模型下载集成测试"""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from jfox.model_downloader import ModelDownloader
+
+pytestmark = [pytest.mark.integration]
+
+
+class TestModelDownloadRetryChain:
+    """mock 网络层，验证完整重试链按顺序执行"""
+
+    @pytest.fixture
+    def downloader(self, tmp_path):
+        with patch(
+            "jfox.model_downloader.ModelDownloader._get_hf_hub_cache",
+            return_value=tmp_path / "hub",
+        ):
+            return ModelDownloader("sentence-transformers/all-MiniLM-L6-v2")
+
+    def test_full_chain_step1_succeeds(self, downloader):
+        """Step 1 成功，后续步骤不执行"""
+        with patch.object(downloader, "_try_hf_hub_download", side_effect=[True, False]) as mock_hf:
+            with patch.object(downloader, "_try_curl_download") as mock_curl:
+                result = downloader.ensure_cached()
+                assert result is True
+                assert mock_hf.call_count == 1
+                mock_curl.assert_not_called()
+
+    def test_full_chain_step1_fails_step2_succeeds(self, downloader):
+        """Step 1 失败，Step 2 成功"""
+        with patch.object(downloader, "_try_hf_hub_download", side_effect=[False, True]) as mock_hf:
+            with patch.object(downloader, "_try_curl_download") as mock_curl:
+                result = downloader.ensure_cached()
+                assert result is True
+                calls = mock_hf.call_args_list
+                assert len(calls) == 2
+                assert calls[0][1].get("endpoint") is None
+                assert calls[1][1].get("endpoint") is not None
+                mock_curl.assert_not_called()
+
+    def test_full_chain_step1_2_fail_step3_succeeds(self, downloader):
+        """Step 1/2 失败，Step 3 成功"""
+        with patch.object(downloader, "_try_hf_hub_download", return_value=False):
+            with patch.object(downloader, "_try_curl_download", return_value=True) as mock_curl:
+                result = downloader.ensure_cached()
+                assert result is True
+                mock_curl.assert_called_once()
+
+    def test_full_chain_all_fail(self, downloader):
+        """全部失败，返回 False"""
+        with patch.object(downloader, "_try_hf_hub_download", return_value=False):
+            with patch.object(downloader, "_try_curl_download", return_value=False):
+                result = downloader.ensure_cached()
+                assert result is False
+
+    def test_daemon_start_calls_downloader(self):
+        """验证 daemon start 启动前调用下载检查"""
+        from jfox.daemon.process import start_daemon
+
+        with patch("jfox.daemon.process._http_health_check", return_value=None):
+            with patch("jfox.daemon.process._check_model_cache") as mock_cache:
+                mock_cache.return_value = {
+                    "needs_download": True,
+                    "model_name": "test-model",
+                    "size_hint": "90MB",
+                }
+                with patch(
+                    "jfox.model_downloader.ModelDownloader",
+                ) as mock_cls:
+                    mock_downloader = MagicMock()
+                    mock_downloader.ensure_cached.return_value = True
+                    mock_cls.return_value = mock_downloader
+
+                    with patch("jfox.daemon.process.subprocess.Popen"):
+                        with patch(
+                            "jfox.daemon.process._http_health_check",
+                            side_effect=[None, {"pid": 123}],
+                        ):
+                            start_daemon()
+                            mock_cls.assert_called_once_with("test-model")
+                            mock_downloader.ensure_cached.assert_called_once()
+
+    def test_cli_model_download_command(self):
+        """验证 CLI model download 命令正确调用 downloader"""
+        from typer.testing import CliRunner
+
+        from jfox.cli import app
+
+        runner = CliRunner()
+
+        with patch(
+            "jfox.model_downloader.ModelDownloader",
+        ) as mock_cls:
+            mock_downloader = MagicMock()
+            mock_downloader.ensure_cached.return_value = True
+            mock_downloader._check_cached.return_value = False
+            mock_cls.return_value = mock_downloader
+
+            result = runner.invoke(app, ["model", "download"])
+            assert result.exit_code == 0
+            mock_cls.assert_called_once()
+            mock_downloader.ensure_cached.assert_called_once()

{jfox_cli-0.4.2 → jfox_cli-0.4.3}/tests/unit/test_daemon_process.py

@@ -139,10 +139,13 @@ class TestDaemonModelCacheCheck:
         assert FIRST_RUN_TIMEOUT > STARTUP_TIMEOUT
         assert FIRST_RUN_TIMEOUT >= 300
 
+    @patch("jfox.model_downloader.ModelDownloader.ensure_cached", return_value=True)
     @patch("jfox.daemon.process._check_model_cache")
     @patch("jfox.daemon.process.subprocess.Popen")
     @patch("jfox.daemon.process._http_health_check")
-    def test_first_run_uses_extended_timeout(self, mock_health, mock_popen, mock_cache):
+    def test_first_run_uses_extended_timeout(
+        self, mock_health, mock_popen, mock_cache, mock_ensure
+    ):
         """首次下载模型时应使用 FIRST_RUN_TIMEOUT"""
         from jfox.daemon.process import start_daemon
 

jfox_cli-0.4.3/tests/unit/test_model_downloader.py

@@ -0,0 +1,111 @@
+"""ModelDownloader 单元测试"""
+
+import os
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from jfox.model_downloader import _HF_MIRROR, ModelDownloader
+
+
+class TestModelDownloader:
+    """ModelDownloader 单元测试"""
+
+    @pytest.fixture
+    def downloader(self, tmp_path):
+        """创建带临时缓存的 downloader"""
+        with patch(
+            "jfox.model_downloader.ModelDownloader._get_hf_hub_cache",
+            return_value=tmp_path / "hub",
+        ):
+            d = ModelDownloader("sentence-transformers/all-MiniLM-L6-v2")
+            return d
+
+    def test_check_cached_when_not_exists(self, downloader):
+        """缓存不存在时返回 False"""
+        assert downloader._check_cached() is False
+
+    def test_check_cached_when_exists(self, downloader):
+        """缓存存在时返回 True"""
+        snapshot = downloader._model_cache / "snapshots" / "abc123"
+        snapshot.mkdir(parents=True)
+        (snapshot / "model.safetensors").write_text("fake")
+        assert downloader._check_cached() is True
+
+    def test_check_cached_missing_model_file(self, downloader):
+        """有 snapshot 但缺少 model.safetensors 时返回 False"""
+        snapshot = downloader._model_cache / "snapshots" / "abc123"
+        snapshot.mkdir(parents=True)
+        (snapshot / "config.json").write_text("fake")
+        assert downloader._check_cached() is False
+
+    def test_ensure_cached_early_return_when_cached(self, downloader):
+        """已缓存时直接返回 True，不走重试链"""
+        snapshot = downloader._model_cache / "snapshots" / "abc123"
+        snapshot.mkdir(parents=True)
+        (snapshot / "model.safetensors").write_text("fake")
+
+        with patch.object(downloader, "_try_hf_hub_download") as mock_hf:
+            result = downloader.ensure_cached()
+            assert result is True
+            mock_hf.assert_not_called()
+
+    def test_ensure_cached_step1_succeeds(self, downloader):
+        """Step 1 成功，后续步骤不执行"""
+        with patch.object(downloader, "_try_hf_hub_download", side_effect=[True, False]) as mock_hf:
+            with patch.object(downloader, "_try_curl_download") as mock_curl:
+                result = downloader.ensure_cached()
+                assert result is True
+                assert mock_hf.call_count == 1
+                mock_curl.assert_not_called()
+
+    def test_ensure_cached_step1_fails_step2_succeeds(self, downloader):
+        """Step 1 失败，Step 2 成功"""
+        with patch.object(downloader, "_try_hf_hub_download", side_effect=[False, True]) as mock_hf:
+            with patch.object(downloader, "_try_curl_download") as mock_curl:
+                result = downloader.ensure_cached()
+                assert result is True
+                assert mock_hf.call_count == 2
+                mock_curl.assert_not_called()
+
+    def test_ensure_cached_step1_2_fail_step3_succeeds(self, downloader):
+        """Step 1/2 失败，Step 3 成功"""
+        with patch.object(downloader, "_try_hf_hub_download", return_value=False) as mock_hf:
+            with patch.object(downloader, "_try_curl_download", return_value=True) as mock_curl:
+                result = downloader.ensure_cached()
+                assert result is True
+                assert mock_hf.call_count == 2
+                mock_curl.assert_called_once()
+
+    def test_ensure_cached_all_fail(self, downloader):
+        """全部失败，返回 False"""
+        with patch.object(downloader, "_try_hf_hub_download", return_value=False):
+            with patch.object(downloader, "_try_curl_download", return_value=False):
+                result = downloader.ensure_cached()
+                assert result is False
+
+    def test_try_hf_hub_download_sets_env(self, downloader):
+        """验证镜像模式设置了 HF_ENDPOINT 环境变量"""
+        env_before = os.environ.get("HF_ENDPOINT")
+
+        with patch("huggingface_hub.hf_hub_download") as mock_download:
+            mock_download.side_effect = Exception("network")
+            downloader._try_hf_hub_download(endpoint=_HF_MIRROR)
+
+        # 调用后环境变量应被恢复
+        assert os.environ.get("HF_ENDPOINT") == env_before
+
+    def test_try_curl_download_no_curl(self, downloader):
+        """curl 不存在时返回 False"""
+        with patch("jfox.model_downloader.shutil.which", return_value=None):
+            result = downloader._try_curl_download()
+            assert result is False
+
+    def test_cleanup_partial(self, downloader):
+        """验证部分下载残留被清理（通过 TemporaryDirectory 自动实现）"""
+        with patch("jfox.model_downloader.shutil.which", return_value="curl"):
+            with patch("jfox.model_downloader.subprocess.run") as mock_run:
+                mock_run.return_value = MagicMock(returncode=0)
+                result = downloader._try_curl_download()
+                # curl 未实际下载文件，返回 False；TemporaryDirectory 自动清理
+                assert result is False

{jfox_cli-0.4.2 → jfox_cli-0.4.3}/uv.lock

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