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

.github/workflows/release.yml

@@ -7,11 +7,11 @@ on:
   workflow_dispatch:
     inputs:
       ref:
-        description: "Git ref to build (branch/tag/SHA)"
+        description: "Git ref to release from (branch/tag/SHA); leave empty to use selected branch"
         required: false
-        default: "master"
+        default: ""
       tag:
-        description: "Release tag to publish assets to (for example: v4.14.6)"
+        description: "Release tag to publish assets to (required for workflow_dispatch, for example: v4.14.6)"
         required: false
 
 permissions:
@@ -30,7 +30,7 @@ jobs:
         uses: actions/checkout@v6
         with:
           fetch-depth: 0
-          ref: ${{ inputs.ref || github.ref }}
+          ref: ${{ inputs.ref != '' && inputs.ref || github.ref_name }}
 
       - name: Resolve tag
         id: tag
@@ -41,7 +41,8 @@ jobs:
           elif [ -n "${{ inputs.tag }}" ]; then
             tag="${{ inputs.tag }}"
           else
-            tag="$(git describe --tags --abbrev=0)"
+            echo "workflow_dispatch requires 'tag' input (for example: v4.17.5)." >&2
+            exit 1
           fi
           if [ -z "$tag" ]; then
             echo "Failed to resolve tag." >&2
@@ -140,7 +141,7 @@ jobs:
         uses: actions/checkout@v6
         with:
           fetch-depth: 0
-          ref: ${{ inputs.ref || github.ref }}
+          ref: ${{ inputs.ref != '' && inputs.ref || github.ref_name }}
 
       - name: Resolve tag
         id: tag
@@ -151,7 +152,8 @@ jobs:
           elif [ -n "${{ inputs.tag }}" ]; then
             tag="${{ inputs.tag }}"
           else
-            tag="$(git describe --tags --abbrev=0)"
+            echo "workflow_dispatch requires 'tag' input (for example: v4.17.5)." >&2
+            exit 1
           fi
           if [ -z "$tag" ]; then
             echo "Failed to resolve tag." >&2
@@ -163,10 +165,29 @@ jobs:
         uses: astral-sh/setup-uv@v7
 
       - name: Setup Python
+        id: setup-python
         uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 
+      - name: Resolve packaged CPython runtime source
+        shell: bash
+        env:
+          SETUP_PYTHON_PATH: ${{ steps.setup-python.outputs.python-path }}
+        run: |
+          if [ -z "$SETUP_PYTHON_PATH" ]; then
+            echo "actions/setup-python did not return python-path output." >&2
+            exit 1
+          fi
+          "$SETUP_PYTHON_PATH" - <<'PY' >> "$GITHUB_ENV"
+          import pathlib
+          import sys
+
+          executable = pathlib.Path(sys.executable).resolve()
+          runtime_root = executable.parent if sys.platform == "win32" else executable.parent.parent
+          print(f"ASTRBOT_DESKTOP_CPYTHON_HOME={runtime_root}")
+          PY
+
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
@@ -271,7 +292,7 @@ jobs:
         uses: actions/checkout@v6
         with:
           fetch-depth: 0
-          ref: ${{ inputs.ref || github.ref }}
+          ref: ${{ inputs.ref != '' && inputs.ref || github.ref_name }}
 
       - name: Resolve tag
         id: tag
@@ -282,7 +303,8 @@ jobs:
           elif [ -n "${{ inputs.tag }}" ]; then
             tag="${{ inputs.tag }}"
           else
-            tag="$(git describe --tags --abbrev=0)"
+            echo "workflow_dispatch requires 'tag' input (for example: v4.17.5)." >&2
+            exit 1
           fi
           if [ -z "$tag" ]; then
             echo "Failed to resolve tag." >&2
@@ -355,7 +377,7 @@ jobs:
         uses: actions/checkout@v6
         with:
           fetch-depth: 0
-          ref: ${{ inputs.ref || github.ref }}
+          ref: ${{ inputs.ref != '' && inputs.ref || github.ref_name }}
 
       - name: Set up Python
         uses: actions/setup-python@v6

.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/knowledge_base/kb_db_sqlite.py

@@ -13,16 +13,19 @@
     KBMedia,
     KnowledgeBase,
 )
+from astrbot.core.utils.astrbot_path import get_astrbot_knowledge_base_path
 
 
 class KBSQLiteDatabase:
-    def __init__(self, db_path: str = "data/knowledge_base/kb.db") -> None:
+    def __init__(self, db_path: str | None = None) -> None:
         """初始化知识库数据库
 
         Args:
-            db_path: 数据库文件路径, 默认为 data/knowledge_base/kb.db
+            db_path: 数据库文件路径, 默认位于 AstrBot 数据目录下的 knowledge_base/kb.db
 
         """
+        if db_path is None:
+            db_path = str(Path(get_astrbot_knowledge_base_path()) / "kb.db")
         self.db_path = db_path
         self.DATABASE_URL = f"sqlite+aiosqlite:///{db_path}"
         self.inited = False

astrbot/core/knowledge_base/kb_mgr.py

@@ -3,6 +3,7 @@
 
 from astrbot.core import logger
 from astrbot.core.provider.manager import ProviderManager
+from astrbot.core.utils.astrbot_path import get_astrbot_knowledge_base_path
 
 # from .chunking.fixed_size import FixedSizeChunker
 from .chunking.recursive import RecursiveCharacterChunker
@@ -13,7 +14,7 @@
 from .retrieval.rank_fusion import RankFusion
 from .retrieval.sparse_retriever import SparseRetriever
 
-FILES_PATH = "data/knowledge_base"
+FILES_PATH = get_astrbot_knowledge_base_path()
 DB_PATH = Path(FILES_PATH) / "kb.db"
 """Knowledge Base storage root directory"""
 CHUNKER = RecursiveCharacterChunker()
@@ -27,7 +28,7 @@ def __init__(
         self,
         provider_manager: ProviderManager,
     ) -> None:
-        Path(DB_PATH).parent.mkdir(parents=True, exist_ok=True)
+        DB_PATH.parent.mkdir(parents=True, exist_ok=True)
         self.provider_manager = provider_manager
         self._session_deleted_callback_registered = False
 

astrbot/core/provider/sources/sensevoice_selfhosted_source.py

@@ -7,12 +7,14 @@
 import os
 import re
 from datetime import datetime
+from pathlib import Path
 from typing import cast
 
 from funasr_onnx import SenseVoiceSmall
 from funasr_onnx.utils.postprocess_utils import rich_transcription_postprocess
 
 from astrbot.core import logger
+from astrbot.core.utils.astrbot_path import get_astrbot_temp_path
 from astrbot.core.utils.io import download_file
 from astrbot.core.utils.tencent_record_helper import tencent_silk_to_wav
 
@@ -50,7 +52,9 @@ async def initialize(self) -> None:
 
     async def get_timestamped_path(self) -> str:
         timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-        return os.path.join("data", "temp", f"{timestamp}")
+        temp_dir = Path(get_astrbot_temp_path())
+        temp_dir.mkdir(parents=True, exist_ok=True)
+        return str(temp_dir / timestamp)
 
     async def _is_silk_file(self, file_path) -> bool:
         silk_header = b"SILK"

astrbot/core/star/star_manager.py

@@ -40,6 +40,13 @@
         logger.warning("未安装 watchfiles，无法实现插件的热重载。")
 
 
+class PluginDependencyInstallError(Exception):
+    def __init__(self, plugin_name: str, requirements_path: str, message: str) -> None:
+        super().__init__(message)
+        self.plugin_name = plugin_name
+        self.requirements_path = requirements_path
+
+
 class PluginManager:
     def __init__(self, context: Context, config: AstrBotConfig) -> None:
         self.updator = PluginUpdator()
@@ -194,6 +201,13 @@ 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 PluginDependencyInstallError(
+                            plugin_name=p,
+                            requirements_path=pth,
+                            message="插件依赖安装失败，请检查插件 requirements.txt "
+                            "中的依赖版本或构建环境。",
+                        ) from e
         return True
 
     async def _import_plugin_with_dependency_recovery(
@@ -343,13 +357,21 @@ async def reload_failed_plugin(self, dir_name):
         async with self._pm_lock:
             if dir_name in self.failed_plugin_dict:
                 success, error = await self.load(specified_dir_name=dir_name)
-                if success:
-                    self.failed_plugin_dict.pop(dir_name, None)
-                    if not self.failed_plugin_dict:
-                        self.failed_plugin_info = ""
-                    return success, None
-                else:
+                if not success:
                     return False, error
+                plugin_reloaded = any(
+                    star.root_dir_name == dir_name
+                    for star in self.context.get_all_stars()
+                )
+                if not plugin_reloaded:
+                    return (
+                        False,
+                        f"插件 {dir_name} 重载失败：未在插件目录中找到可加载插件。",
+                    )
+                self.failed_plugin_dict.pop(dir_name, None)
+                if not self.failed_plugin_dict:
+                    self.failed_plugin_info = ""
+                return True, None
             return False, "插件不存在于失败列表中"
 
     async def reload(self, specified_plugin_name=None):
@@ -431,6 +453,8 @@ async def load(self, specified_module_path=None, specified_dir_name=None):
             return False, "未找到任何插件模块"
 
         fail_rec = ""
+        has_target_filter = bool(specified_module_path or specified_dir_name)
+        matched_target = False
 
         # 导入插件模块，并尝试实例化插件类
         for plugin_module in plugin_modules:
@@ -457,6 +481,7 @@ async def load(self, specified_module_path=None, specified_dir_name=None):
                     continue
                 if specified_dir_name and root_dir_name != specified_dir_name:
                     continue
+                matched_target = True
 
                 logger.info(f"正在载入插件 {root_dir_name} ...")
 
@@ -471,6 +496,15 @@ 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}插件安装失败，插件目录：{plugin_dir_path}"
+                        )
                     continue
 
                 # 检查 _conf_schema.json
@@ -706,6 +740,10 @@ async def load(self, specified_module_path=None, specified_dir_name=None):
             logger.error(f"同步指令配置失败: {e!s}")
             logger.error(traceback.format_exc())
 
+        if has_target_filter and not matched_target:
+            target_label = specified_dir_name or specified_module_path
+            return False, f"未找到指定插件：{target_label}"
+
         if not fail_rec:
             return True, None
         self.failed_plugin_info = fail_rec
@@ -781,10 +819,8 @@ async def install_plugin(self, repo_url: str, proxy=""):
         async with self._pm_lock:
             plugin_path = ""
             dir_name = ""
-            cleanup_required = False
             try:
                 plugin_path = await self.updator.install(repo_url, proxy)
-                cleanup_required = True
 
                 # reload the plugin
                 dir_name = os.path.basename(plugin_path)
@@ -829,10 +865,12 @@ async def install_plugin(self, repo_url: str, proxy=""):
 
                 return plugin_info
             except Exception:
-                if cleanup_required and dir_name and plugin_path:
-                    await self._cleanup_failed_plugin_install(
-                        dir_name=dir_name,
-                        plugin_path=plugin_path,
+                if plugin_path:
+                    plugin_dir_name = dir_name or os.path.basename(plugin_path)
+                    logger.warning(
+                        "%s插件安装失败，插件目录：%s",
+                        plugin_dir_name,
+                        plugin_path,
                     )
                 raise
 
@@ -1096,7 +1134,6 @@ async def install_plugin_from_file(self, zip_file_path: str):
         dir_name = os.path.basename(zip_file_path).replace(".zip", "")
         dir_name = dir_name.removesuffix("-master").removesuffix("-main").lower()
         desti_dir = os.path.join(self.plugin_store_path, dir_name)
-        cleanup_required = False
 
         # 第一步：检查是否已安装同目录名的插件，先终止旧插件
         existing_plugin = None
@@ -1118,7 +1155,6 @@ async def install_plugin_from_file(self, zip_file_path: str):
 
         try:
             self.updator.unzip_file(zip_file_path, desti_dir)
-            cleanup_required = True
 
             # 第二步：解压后，读取新插件的 metadata.yaml，检查是否存在同名但不同目录的插件
             try:
@@ -1195,9 +1231,9 @@ async def install_plugin_from_file(self, zip_file_path: str):
 
             return plugin_info
         except Exception:
-            if cleanup_required:
-                await self._cleanup_failed_plugin_install(
-                    dir_name=dir_name,
-                    plugin_path=desti_dir,
-                )
+            logger.warning(
+                "%s插件安装失败，插件目录：%s",
+                dir_name,
+                desti_dir,
+            )
             raise