refactor: 桌面端迁移 CPython 运行时并强化 Windows 打包稳定性

.gitignore

@@ -38,6 +38,10 @@ desktop/dist/
 desktop/out/
 desktop/resources/backend/astrbot-backend*
 desktop/resources/backend/*.exe
+desktop/resources/backend/app/
+desktop/resources/backend/python/
+desktop/resources/backend/launch_backend.py
+desktop/resources/backend/runtime-manifest.json
 desktop/resources/webui/*
 desktop/resources/.pyinstaller/
 package-lock.json

README.md

@@ -149,6 +149,7 @@ paru -S astrbot-git
 #### 桌面端 Electron 打包
 
 桌面端（Electron 打包，`pnpm` 工作流）构建流程请参阅：[`desktop/README.md`](desktop/README.md)。
+打包前需要准备 CPython 运行时目录，并设置 `ASTRBOT_DESKTOP_CPYTHON_HOME`（详见该文档）。
 
 ## 支持的消息平台
 

astrbot/core/star/star_manager.py

@@ -194,6 +194,11 @@ async def _check_plugin_dept_update(
                     await pip_installer.install(requirements_path=pth)
                 except Exception as e:
                     logger.error(f"更新插件 {p} 的依赖失败。Code: {e!s}")
+                    if target_plugin:
+                        raise Exception(
+                            "插件依赖安装失败，请检查插件 requirements.txt "
+                            "中的依赖版本或构建环境。"
+                        ) from e
         return True
 
     async def _import_plugin_with_dependency_recovery(
@@ -471,6 +476,19 @@ async def load(self, specified_module_path=None, specified_dir_name=None):
                 except Exception as e:
                     logger.error(traceback.format_exc())
                     logger.error(f"插件 {root_dir_name} 导入失败。原因：{e!s}")
+                    fail_rec += f"加载 {root_dir_name} 插件时出现问题，原因 {e!s}。\n"
+                    self.failed_plugin_dict[root_dir_name] = {
+                        "error": str(e),
+                        "traceback": traceback.format_exc(),
+                    }
+                    if not reserved:
+                        logger.warning(
+                            f"插件 {root_dir_name} 导入失败，已自动卸载该插件。"
+                        )
+                        await self._cleanup_failed_plugin_install(
+                            dir_name=root_dir_name,
+                            plugin_path=plugin_dir_path,
+                        )
                     continue
 
                 # 检查 _conf_schema.json

astrbot/core/utils/pip_installer.py

@@ -16,7 +16,6 @@
 
 logger = logging.getLogger("astrbot")
 
-_DISTLIB_FINDER_PATCH_ATTEMPTED = False
 _SITE_PACKAGES_IMPORT_LOCK = threading.RLock()
 
 
@@ -34,7 +33,7 @@ def _get_pip_main():
             raise ImportError(
                 "pip module is unavailable "
                 f"(sys.executable={sys.executable}, "
-                f"frozen={getattr(sys, 'frozen', False)}, "
+                f"packaged_electron={is_packaged_electron_runtime()}, "
                 f"ASTRBOT_ELECTRON_CLIENT={os.environ.get('ASTRBOT_ELECTRON_CLIENT')})"
             ) from exc
 
@@ -426,110 +425,6 @@ def _ensure_plugin_dependencies_preferred(
     _ensure_preferred_modules(candidate_modules, target_site_packages)
 
 
-def _get_loader_for_package(package: object) -> object | None:
-    loader = getattr(package, "__loader__", None)
-    if loader is not None:
-        return loader
-
-    spec = getattr(package, "__spec__", None)
-    if spec is None:
-        return None
-    return getattr(spec, "loader", None)
-
-
-def _try_register_distlib_finder(
-    distlib_resources: object,
-    finder_registry: dict[type, object],
-    register_finder,
-    resource_finder: object,
-    loader: object,
-    package_name: str,
-) -> bool:
-    loader_type = type(loader)
-    if loader_type in finder_registry:
-        return False
-
-    try:
-        register_finder(loader, resource_finder)
-    except Exception as exc:
-        logger.warning(
-            "Failed to patch pip distlib finder for loader %s (%s): %s",
-            loader_type.__name__,
-            package_name,
-            exc,
-        )
-        return False
-
-    updated_registry = getattr(distlib_resources, "_finder_registry", finder_registry)
-    if isinstance(updated_registry, dict) and loader_type not in updated_registry:
-        logger.warning(
-            "Distlib finder patch did not take effect for loader %s (%s).",
-            loader_type.__name__,
-            package_name,
-        )
-        return False
-
-    logger.info(
-        "Patched pip distlib finder for frozen loader: %s (%s)",
-        loader_type.__name__,
-        package_name,
-    )
-    return True
-
-
-def _patch_distlib_finder_for_frozen_runtime() -> None:
-    global _DISTLIB_FINDER_PATCH_ATTEMPTED
-
-    if not getattr(sys, "frozen", False):
-        return
-    if _DISTLIB_FINDER_PATCH_ATTEMPTED:
-        return
-
-    _DISTLIB_FINDER_PATCH_ATTEMPTED = True
-
-    try:
-        from pip._vendor.distlib import resources as distlib_resources
-    except Exception:
-        return
-
-    finder_registry = getattr(distlib_resources, "_finder_registry", None)
-    register_finder = getattr(distlib_resources, "register_finder", None)
-    resource_finder = getattr(distlib_resources, "ResourceFinder", None)
-
-    if not isinstance(finder_registry, dict):
-        logger.warning(
-            "Skip patching distlib finder because _finder_registry is unavailable."
-        )
-        return
-    if not callable(register_finder) or resource_finder is None:
-        logger.warning(
-            "Skip patching distlib finder because register API is unavailable."
-        )
-        return
-
-    for package_name in ("pip._vendor.distlib", "pip._vendor"):
-        try:
-            package = importlib.import_module(package_name)
-        except Exception:
-            continue
-
-        loader = _get_loader_for_package(package)
-        if loader is None:
-            continue
-
-        if _try_register_distlib_finder(
-            distlib_resources,
-            finder_registry,
-            register_finder,
-            resource_finder,
-            loader,
-            package_name,
-        ):
-            finder_registry = getattr(
-                distlib_resources, "_finder_registry", finder_registry
-            )
-
-
 class PipInstaller:
     def __init__(self, pip_install_arg: str, pypi_index_url: str | None = None) -> None:
         self.pip_install_arg = pip_install_arg
@@ -540,8 +435,10 @@ async def install(
         package_name: str | None = None,
         requirements_path: str | None = None,
         mirror: str | None = None,
+        wheel_only: bool = False,
     ) -> None:
         args = ["install"]
+        pip_install_args = self.pip_install_arg.split() if self.pip_install_arg else []
         requested_requirements: set[str] = set()
         if package_name:
             args.append(package_name)
@@ -563,13 +460,26 @@ async def install(
             args.extend(["--target", target_site_packages])
             args.extend(["--upgrade", "--force-reinstall"])
 
-        if self.pip_install_arg:
-            args.extend(self.pip_install_arg.split())
+        if pip_install_args:
+            args.extend(pip_install_args)
+        if wheel_only:
+            if not any(
+                token == "--only-binary" or token.startswith("--only-binary=")
+                for token in args
+            ):
+                args.extend(["--only-binary", ":all:"])
+            if "--prefer-binary" not in args:
+                args.append("--prefer-binary")
 
         logger.info(f"Pip 包管理器: pip {' '.join(args)}")
         result_code = await self._run_pip_in_process(args)
 
         if result_code != 0:
+            if wheel_only:
+                raise Exception(
+                    "安装失败：插件依赖 wheel-only 检测未通过或依赖安装失败，"
+                    "请检查是否存在无可用 wheel 的依赖。"
+                )
             raise Exception(f"安装失败，错误码：{result_code}")
 
         if target_site_packages:
@@ -602,7 +512,6 @@ def prefer_installed_dependencies(self, requirements_path: str) -> None:
 
     async def _run_pip_in_process(self, args: list[str]) -> int:
         pip_main = _get_pip_main()
-        _patch_distlib_finder_for_frozen_runtime()
 
         original_handlers = list(logging.getLogger().handlers)
         result_code, output = await asyncio.to_thread(

astrbot/core/utils/runtime_env.py

@@ -7,4 +7,4 @@ def is_frozen_runtime() -> bool:
 
 
 def is_packaged_electron_runtime() -> bool:
-    return is_frozen_runtime() and os.environ.get("ASTRBOT_ELECTRON_CLIENT") == "1"
+    return os.environ.get("ASTRBOT_ELECTRON_CLIENT") == "1"

desktop/README.md

@@ -6,11 +6,12 @@ This document describes how to build the Electron desktop app from source.
 
 - Electron desktop shell (`desktop/main.js`)
 - Bundled WebUI static files (`desktop/resources/webui`)
+- Bundled backend runtime payload (`desktop/resources/backend`)
 - App assets (`desktop/assets`)
 
 Current behavior:
 
-- Backend executable is bundled in the installer/package.
+- Backend CPython runtime and source are bundled in the installer/package.
 - App startup checks backend availability and auto-starts bundled backend when needed.
 - Runtime data is stored under `~/.astrbot` by default, not as a full AstrBot source project.
 
@@ -19,6 +20,7 @@ Current behavior:
 - Python environment ready in repository root (`uv` available)
 - Node.js available
 - `pnpm` available
+- A CPython runtime directory for packaged backend (contains runnable `python` and `site-packages`)
 
 Desktop dependency management uses `pnpm` with a lockfile:
 
@@ -31,12 +33,21 @@ Run commands from repository root:
 
 ```bash
 uv sync
+export ASTRBOT_DESKTOP_CPYTHON_HOME=/path/to/cpython-runtime
 pnpm --dir dashboard install
 pnpm --dir dashboard build
 pnpm --dir desktop install --frozen-lockfile
 pnpm --dir desktop run dist:full
 ```
 
+If you are already developing in this repository, you can directly reuse the local virtual environment as runtime:
+
+```bash
+uv sync
+export ASTRBOT_DESKTOP_CPYTHON_HOME="$(pwd)/.venv"
+pnpm --dir desktop run build:backend
+```
+
 Output files are generated under:
 
 - `desktop/dist/`
@@ -57,9 +68,25 @@ pnpm --dir desktop run dev
 
 ## Notes
 
-- `dist:full` runs WebUI build + backend build + Electron packaging.
+- `dist:full` runs WebUI build + backend runtime packaging + Electron packaging.
 - In packaged app mode, backend data root defaults to `~/.astrbot` (can be overridden by `ASTRBOT_ROOT`).
-- Backend build uses `uv run --with pyinstaller ...`, so no manual `PyInstaller` install is required.
+- Backend build requires `ASTRBOT_DESKTOP_CPYTHON_HOME` (or `ASTRBOT_DESKTOP_BACKEND_RUNTIME`) to point to a CPython runtime directory.
+
+## Packaged Backend Layout
+
+After `pnpm --dir desktop run build:backend`, backend payload is generated in `desktop/resources/backend`:
+
+```text
+desktop/resources/backend/
+  app/                   # AstrBot backend source snapshot used in packaged mode
+  python/                # Bundled CPython runtime directory
+  launch_backend.py      # Launcher executed by Electron
+  runtime-manifest.json  # Runtime metadata (python path, entrypoint, app path)
+```
+
+Electron reads `runtime-manifest.json` and starts backend with:
+- `python` from `python/`
+- `launch_backend.py` as entrypoint
 
 ## Runtime Directory Layout
 
@@ -122,6 +149,12 @@ Backend auto-start:
 - `ASTRBOT_BACKEND_AUTO_START=0` disables Electron-managed backend startup.
 - When disabled, backend must already be running at `ASTRBOT_BACKEND_URL` before launching app.
 
+Backend build errors:
+
+- `Missing CPython runtime source`: set `ASTRBOT_DESKTOP_CPYTHON_HOME` (or `ASTRBOT_DESKTOP_BACKEND_RUNTIME`).
+- `Cannot find Python executable in runtime`: runtime directory is invalid or incomplete.
+- `Failed to detect purelib from runtime python`: runtime Python cannot run correctly.
+
 If Electron download times out on restricted networks, configure mirrors before install:
 
 ```bash