fix: make desktop plugin dependency loading safer on Windows (#7446)

* fix: make desktop plugin dependency loading safer on Windows

* fix: restore dependency recovery after precheck fallback

* test: cover version mismatch reinstall path

* refactor: clarify dependency recovery state handling

* style: format star manager with ruff

* fix: skip dependency recovery for plugin import errors

* fix: surface unexpected dependency recovery failures

Author: zouyonghe

astrbot/core/star/star_manager.py

@@ -11,6 +11,8 @@
 import sys
 import tempfile
 import traceback
+from dataclasses import dataclass
+from enum import Enum, auto
 from types import ModuleType
 
 import yaml
@@ -37,6 +39,7 @@
 from astrbot.core.utils.io import remove_dir
 from astrbot.core.utils.metrics import Metric
 from astrbot.core.utils.requirements_utils import (
+    MissingRequirementsPlan,
     plan_missing_requirements_install,
 )
 
@@ -77,6 +80,19 @@ def __init__(
         self.error = error
 
 
+class ImportDependencyRecoveryMode(Enum):
+    DISABLED = auto()
+    PRELOAD_AND_RECOVER = auto()
+    RECOVER_ON_FAILURE = auto()
+    REINSTALL_ON_FAILURE = auto()
+
+
+@dataclass(frozen=True)
+class ImportDependencyRecoveryState:
+    mode: ImportDependencyRecoveryMode
+    install_plan: MissingRequirementsPlan | None = None
+
+
 @contextlib.contextmanager
 def _temporary_filtered_requirements_file(
     *,
@@ -137,7 +153,10 @@ async def _install_requirements_with_precheck(
             requirements_path,
             fallback_reason,
         )
-        await pip_installer.install(requirements_path=requirements_path)
+        await pip_installer.install(
+            requirements_path=requirements_path,
+            allow_target_upgrade=bool(install_plan.version_mismatch_names),
+        )
         return
 
     logger.info(
@@ -148,7 +167,10 @@ async def _install_requirements_with_precheck(
     with _temporary_filtered_requirements_file(
         install_lines=install_plan.install_lines,
     ) as filtered_requirements_path:
-        await pip_installer.install(requirements_path=filtered_requirements_path)
+        await pip_installer.install(
+            requirements_path=filtered_requirements_path,
+            allow_target_upgrade=bool(install_plan.version_mismatch_names),
+        )
 
 
 class PluginManager:
@@ -332,33 +354,106 @@ async def _ensure_plugin_requirements(
             logger.exception(str(dependency_error))
             raise dependency_error from e
 
+    @staticmethod
+    def _resolve_import_dependency_recovery_state(
+        requirements_path: str,
+        *,
+        reserved: bool,
+    ) -> ImportDependencyRecoveryState:
+        if reserved or not os.path.exists(requirements_path):
+            return ImportDependencyRecoveryState(ImportDependencyRecoveryMode.DISABLED)
+
+        install_plan = plan_missing_requirements_install(requirements_path)
+        if install_plan is None:
+            return ImportDependencyRecoveryState(
+                ImportDependencyRecoveryMode.RECOVER_ON_FAILURE
+            )
+        if install_plan.version_mismatch_names:
+            return ImportDependencyRecoveryState(
+                ImportDependencyRecoveryMode.REINSTALL_ON_FAILURE,
+                install_plan=install_plan,
+            )
+
+        return ImportDependencyRecoveryState(
+            ImportDependencyRecoveryMode.PRELOAD_AND_RECOVER,
+            install_plan=install_plan,
+        )
+
+    @staticmethod
+    def _try_import_from_installed_dependencies(
+        path: str,
+        module_str: str,
+        root_dir_name: str,
+        requirements_path: str,
+        import_exc: Exception,
+    ) -> ModuleType | None:
+        try:
+            logger.info(
+                f"插件 {root_dir_name} 导入失败，尝试从已安装依赖恢复: {import_exc!s}"
+            )
+            pip_installer.prefer_installed_dependencies(
+                requirements_path=requirements_path
+            )
+            module = __import__(path, fromlist=[module_str])
+            logger.info(
+                f"插件 {root_dir_name} 已从 site-packages 恢复依赖，跳过重新安装。"
+            )
+            return module
+        except (ImportError, ModuleNotFoundError) as recover_exc:
+            logger.info(
+                f"插件 {root_dir_name} 已安装依赖恢复失败，将重新安装依赖: {recover_exc!s}"
+            )
+            return None
+
     async def _import_plugin_with_dependency_recovery(
         self,
         path: str,
         module_str: str,
         root_dir_name: str,
         requirements_path: str,
+        *,
+        reserved: bool = False,
     ) -> ModuleType:
+        recovery_state = self._resolve_import_dependency_recovery_state(
+            requirements_path,
+            reserved=reserved,
+        )
+
+        if recovery_state.mode is ImportDependencyRecoveryMode.PRELOAD_AND_RECOVER:
+            try:
+                pip_installer.prefer_installed_dependencies(
+                    requirements_path=requirements_path
+                )
+            except Exception as preload_exc:
+                logger.info(
+                    f"插件 {root_dir_name} 预加载已安装依赖失败，将继续常规导入: {preload_exc!s}"
+                )
+
         try:
             return __import__(path, fromlist=[module_str])
-        except (ModuleNotFoundError, ImportError) as import_exc:
-            if os.path.exists(requirements_path):
-                try:
-                    logger.info(
-                        f"插件 {root_dir_name} 导入失败，尝试从已安装依赖恢复: {import_exc!s}"
-                    )
-                    pip_installer.prefer_installed_dependencies(
-                        requirements_path=requirements_path
-                    )
-                    module = __import__(path, fromlist=[module_str])
-                    logger.info(
-                        f"插件 {root_dir_name} 已从 site-packages 恢复依赖，跳过重新安装。"
-                    )
-                    return module
-                except Exception as recover_exc:
-                    logger.info(
-                        f"插件 {root_dir_name} 已安装依赖恢复失败，将重新安装依赖: {recover_exc!s}"
-                    )
+        except ModuleNotFoundError as import_exc:
+            if recovery_state.mode in {
+                ImportDependencyRecoveryMode.PRELOAD_AND_RECOVER,
+                ImportDependencyRecoveryMode.RECOVER_ON_FAILURE,
+            }:
+                recovered_module = self._try_import_from_installed_dependencies(
+                    path,
+                    module_str,
+                    root_dir_name,
+                    requirements_path,
+                    import_exc,
+                )
+                if recovered_module is not None:
+                    return recovered_module
+            elif (
+                recovery_state.mode is ImportDependencyRecoveryMode.REINSTALL_ON_FAILURE
+            ):
+                assert recovery_state.install_plan is not None
+                logger.info(
+                    "插件 %s 预检查检测到版本不匹配，跳过已安装依赖恢复: %s",
+                    root_dir_name,
+                    sorted(recovery_state.install_plan.version_mismatch_names),
+                )
 
             await self._check_plugin_dept_update(target_plugin=root_dir_name)
             return __import__(path, fromlist=[module_str])
@@ -788,6 +883,7 @@ async def load(
                         module_str=module_str,
                         root_dir_name=root_dir_name,
                         requirements_path=requirements_path,
+                        reserved=reserved,
                     )
                 except Exception as e:
                     error_trace = traceback.format_exc()

astrbot/core/utils/pip_installer.py

@@ -982,6 +982,7 @@ async def install(
         package_name: str | None = None,
         requirements_path: str | None = None,
         mirror: str | None = None,
+        allow_target_upgrade: bool = True,
     ) -> None:
         args, requested_requirements = self._build_pip_args(
             package_name, requirements_path, mirror
@@ -995,15 +996,17 @@ async def install(
             target_site_packages = get_astrbot_site_packages_path()
             os.makedirs(target_site_packages, exist_ok=True)
             _prepend_sys_path(target_site_packages)
-            args.extend(
-                [
-                    "--target",
-                    target_site_packages,
-                    "--upgrade",
-                    "--upgrade-strategy",
-                    "only-if-needed",
-                ]
-            )
+            # `allow_target_upgrade` only matters for packaged desktop installs that
+            # write into the shared `data/site-packages` target directory.
+            args.extend(["--target", target_site_packages])
+            if allow_target_upgrade:
+                args.extend(
+                    [
+                        "--upgrade",
+                        "--upgrade-strategy",
+                        "only-if-needed",
+                    ]
+                )
 
         with self._core_constraints.constraints_file() as constraints_file_path:
             if constraints_file_path:

astrbot/core/utils/requirements_utils.py

@@ -29,10 +29,17 @@ class ParsedPackageInput:
     requirement_names: frozenset[str]
 
 
+@dataclass(frozen=True)
+class MissingRequirementsAnalysis:
+    missing_names: frozenset[str]
+    version_mismatch_names: frozenset[str] = frozenset()
+
+
 @dataclass(frozen=True)
 class MissingRequirementsPlan:
     missing_names: frozenset[str]
     install_lines: tuple[str, ...]
+    version_mismatch_names: frozenset[str] = frozenset()
     fallback_reason: str | None = None
 
 
@@ -394,24 +401,39 @@ def find_missing_requirements(requirements_path: str) -> set[str] | None:
 def find_missing_requirements_from_lines(
     requirement_lines: Sequence[str],
 ) -> set[str] | None:
+    analysis = classify_missing_requirements_from_lines(requirement_lines)
+    if analysis is None:
+        return None
+
+    return set(analysis.missing_names)
+
+
+def classify_missing_requirements_from_lines(
+    requirement_lines: Sequence[str],
+) -> MissingRequirementsAnalysis | None:
     required = list(iter_requirements(lines=requirement_lines))
     if not required:
-        return set()
+        return MissingRequirementsAnalysis(missing_names=frozenset())
 
     installed = collect_installed_distribution_versions(get_requirement_check_paths())
     if installed is None:
         return None
 
     missing: set[str] = set()
+    version_mismatch_names: set[str] = set()
     for name, specifier in required:
         installed_version = installed.get(name)
         if not installed_version:
             missing.add(name)
             continue
         if specifier and not _specifier_contains_version(specifier, installed_version):
             missing.add(name)
+            version_mismatch_names.add(name)
 
-    return missing
+    return MissingRequirementsAnalysis(
+        missing_names=frozenset(missing),
+        version_mismatch_names=frozenset(version_mismatch_names),
+    )
 
 
 def build_missing_requirements_install_lines(
@@ -449,9 +471,11 @@ def plan_missing_requirements_install(
     if not can_precheck or requirement_lines is None:
         return None
 
-    missing = find_missing_requirements_from_lines(requirement_lines)
-    if missing is None:
+    analysis = classify_missing_requirements_from_lines(requirement_lines)
+    if analysis is None:
         return None
+    missing = analysis.missing_names
+    version_mismatch_names = analysis.version_mismatch_names
 
     install_lines = build_missing_requirements_install_lines(
         requirements_path,
@@ -468,12 +492,14 @@ def plan_missing_requirements_install(
         )
         return MissingRequirementsPlan(
             missing_names=frozenset(missing),
+            version_mismatch_names=frozenset(version_mismatch_names),
             install_lines=(),
             fallback_reason="unmapped missing requirement names",
         )
 
     return MissingRequirementsPlan(
         missing_names=frozenset(missing),
+        version_mismatch_names=frozenset(version_mismatch_names),
         install_lines=install_lines,
     )
 

main.py

@@ -51,7 +51,7 @@ def check_env() -> None:
 
     site_packages_path = get_astrbot_site_packages_path()
     if site_packages_path not in sys.path:
-        sys.path.insert(0, site_packages_path)
+        sys.path.append(site_packages_path)
 
     os.makedirs(get_astrbot_config_path(), exist_ok=True)
     os.makedirs(get_astrbot_plugin_path(), exist_ok=True)

tests/test_main.py

@@ -60,6 +60,48 @@ def test_check_env(monkeypatch):
         check_env()
 
 
+def test_check_env_appends_user_site_packages_after_runtime_paths(monkeypatch):
+    astrbot_root = "/tmp/astrbot-root"
+    site_packages_path = "/tmp/astrbot-site-packages"
+    original_sys_path = list(sys.path)
+
+    monkeypatch.setattr(sys, "version_info", _version_info(3, 12))
+    monkeypatch.setattr("main.get_astrbot_root", lambda: astrbot_root)
+    monkeypatch.setattr("main.get_astrbot_site_packages_path", lambda: site_packages_path)
+    monkeypatch.setattr("main.get_astrbot_config_path", lambda: "/tmp/config")
+    monkeypatch.setattr("main.get_astrbot_plugin_path", lambda: "/tmp/plugins")
+    monkeypatch.setattr("main.get_astrbot_temp_path", lambda: "/tmp/temp")
+    monkeypatch.setattr("main.get_astrbot_knowledge_base_path", lambda: "/tmp/kb")
+    monkeypatch.setattr(sys, "path", ["/runtime/lib", *original_sys_path])
+
+    with mock.patch("os.makedirs"):
+        check_env()
+
+    assert sys.path[0] == astrbot_root
+    assert sys.path[-1] == site_packages_path
+    assert sys.path.index(site_packages_path) > sys.path.index("/runtime/lib")
+
+
+def test_check_env_does_not_append_duplicate_user_site_packages(monkeypatch):
+    astrbot_root = "/tmp/astrbot-root"
+    site_packages_path = "/tmp/astrbot-site-packages"
+    original_sys_path = list(sys.path)
+
+    monkeypatch.setattr(sys, "version_info", _version_info(3, 12))
+    monkeypatch.setattr("main.get_astrbot_root", lambda: astrbot_root)
+    monkeypatch.setattr("main.get_astrbot_site_packages_path", lambda: site_packages_path)
+    monkeypatch.setattr("main.get_astrbot_config_path", lambda: "/tmp/config")
+    monkeypatch.setattr("main.get_astrbot_plugin_path", lambda: "/tmp/plugins")
+    monkeypatch.setattr("main.get_astrbot_temp_path", lambda: "/tmp/temp")
+    monkeypatch.setattr("main.get_astrbot_knowledge_base_path", lambda: "/tmp/kb")
+    monkeypatch.setattr(sys, "path", [astrbot_root, *original_sys_path, site_packages_path])
+
+    with mock.patch("os.makedirs"):
+        check_env()
+
+    assert sys.path.count(site_packages_path) == 1
+
+
 def test_version_info_comparisons():
     """Test _version_info comparison operators with tuples and other instances."""
     v3_10 = _version_info(3, 10)