版本号统一，常量移动至base包 (#3281)

Co-authored-by: 赵天乐(tyler zhao) <189870321+tyler-ztl@users.noreply.github.com>

Author: LIghtJUNction

.github/copilot-instructions.md

@@ -1,63 +1,63 @@
-# AstrBot Development Instructions
-
-AstrBot is a multi-platform LLM chatbot and development framework written in Python with a Vue.js dashboard. It supports multiple messaging platforms (QQ, Telegram, Discord, etc.) and various LLM providers (OpenAI, Anthropic, Google Gemini, etc.).
-
-Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
-
-## Working Effectively
-
-### Bootstrap and Install Dependencies
-- **Python 3.10+ required** - Check `.python-version` file
-- Install UV package manager: `pip install uv`
-- Install project dependencies: `uv sync` -- takes 6-7 minutes. NEVER CANCEL. Set timeout to 10+ minutes.
-- Create required directories: `mkdir -p data/plugins data/config data/temp`
-
-### Running the Application
-- Run main application: `uv run main.py` -- starts in ~3 seconds
-- Application creates WebUI on http://localhost:6185 (default credentials: `astrbot`/`astrbot`)
-- Application loads plugins automatically from `packages/` and `data/plugins/` directories
-
-### Dashboard Build (Vue.js/Node.js)
-- **Prerequisites**: Node.js 20+ and npm 10+ required
-- Navigate to dashboard: `cd dashboard`
-- Install dashboard dependencies: `npm install` -- takes 2-3 minutes. NEVER CANCEL. Set timeout to 5+ minutes.
-- Build dashboard: `npm run build` -- takes 25-30 seconds. NEVER CANCEL.
-- Dashboard creates optimized production build in `dashboard/dist/`
-
-### Testing
-- Do not generate test files for now.
-
-### Code Quality and Linting
-- Install ruff linter: `uv add --dev ruff`
-- Check code style: `uv run ruff check .` -- takes <1 second
-- Check formatting: `uv run ruff format --check .` -- takes <1 second
-- Fix formatting: `uv run ruff format .`
-- **ALWAYS** run `uv run ruff check .` and `uv run ruff format .` before committing changes
-
-### Plugin Development
-- Plugins load from `packages/` (built-in) and `data/plugins/` (user-installed)
-- Plugin system supports function tools and message handlers
-- Key plugins: python_interpreter, web_searcher, astrbot, reminder, session_controller
-
-### Common Issues and Workarounds
-- **Dashboard download fails**: Known issue with "division by zero" error - application still works
-- **Import errors in tests**: Ensure `uv run` is used to run tests in proper environment
-=- **Build timeouts**: Always set appropriate timeouts (10+ minutes for uv sync, 5+ minutes for npm install)
-
-## CI/CD Integration
-- GitHub Actions workflows in `.github/workflows/`
-- Docker builds supported via `Dockerfile`
-- Pre-commit hooks enforce ruff formatting and linting
-
-## Docker Support
-- Primary deployment method: `docker run soulter/astrbot:latest`
-- Compose file available: `compose.yml`
-- Exposes ports: 6185 (WebUI), 6195 (WeChat), 6199 (QQ), etc.
-- Volume mount required: `./data:/AstrBot/data`
-
-## Multi-language Support
-- Documentation in Chinese (README.md), English (README_en.md), Japanese (README_ja.md)
-- UI supports internationalization
-- Default language is Chinese
-
-Remember: This is a production chatbot framework with real users. Always test thoroughly and ensure changes don't break existing functionality.
+# AstrBot 开发指南
+
+AstrBot 是一个使用 Python 编写、配备 Vue.js 仪表盘的多平台 LLM 聊天机器人开发框架。它支持多个消息平台（QQ、Telegram、Discord 等）和多种 LLM 提供商（OpenAI、Anthropic、Google Gemini 等）。
+
+始终优先参考这些指南，仅在遇到与此处信息不符的意外情况时才回退到搜索或 bash 命令。
+
+## 高效工作
+
+### 引导和安装依赖
+- **需要 Python 3.10+** - 检查 `.python-version` 文件
+- 安装 UV 包管理器：`pip install uv`
+- 安装项目依赖：`uv sync` -- 很快几分钟。绝不要取消。设置超时时间为 10+ 分钟。
+- 创建必需的目录：`mkdir -p data/plugins data/config data/temp`
+
+### 运行应用程序
+- 运行主应用程序：`uv run main.py` -- 约 3 秒启动
+- 应用程序在 http://localhost:6185 创建 WebUI（默认凭据：`astrbot`/`astrbot`）
+- 应用程序自动从 `packages/` 和 `data/plugins/` 目录加载插件
+
+### 仪表盘构建（Vue.js/Node.js）
+- **前置要求**：需要 Node.js 20+ 和 npm 10+
+- 导航到仪表盘：`cd dashboard`
+- 安装仪表盘依赖：`npm install` -- 需要 2-3 分钟。绝不要取消。设置超时时间为 5+ 分钟。
+- 构建仪表盘：`npm run build` -- 需要 25-30 秒。绝不要取消。
+- 仪表盘在 `dashboard/dist/` 创建优化的生产构建
+
+### 测试
+- 暂时不要生成测试文件。
+
+### 代码质量和检查
+- 安装 ruff 检查器：`uv add --dev ruff`
+- 检查代码风格：`uv run ruff check .` -- 耗时 <1 秒
+- 检查格式：`uv run ruff format --check .` -- 耗时 <1 秒
+- 修复格式：`uv run ruff format .`
+- **始终**在提交更改前运行 `uv run ruff check .` 和 `uv run ruff format .`
+
+### 插件开发
+- 插件从 `packages/`（内置）和 `data/plugins/`（用户安装）加载
+- 插件系统支持函数工具和消息处理器
+- 关键插件：python_interpreter、web_searcher、astrbot、reminder、session_controller
+
+### 常见问题和解决方法
+- **仪表盘下载失败**：已知的"除以零"错误问题 - 应用程序仍可正常工作
+- **测试中的导入错误**：确保使用 `uv run` 在适当的环境中运行测试
+- **构建超时**：始终设置适当的超时时间（uv sync 为 10+ 分钟，npm install 为 5+ 分钟）
+
+## CI/CD 集成
+- GitHub Actions 工作流在 `.github/workflows/` 中
+- 通过 `Dockerfile` 支持 Docker 构建
+- Pre-commit 钩子强制执行 ruff 格式化和检查
+
+## Docker 支持
+- 主要部署方法：`docker run soulter/astrbot:latest`
+- 可用的 Compose 文件：`compose.yml`
+- 暴露端口：6185（WebUI）、6195（WeChat）、6199（QQ）等
+- 需要挂载卷：`./data:/AstrBot/data`
+
+## 多语言支持
+- 文档包括中文（README.md）、英文（README_en.md）、日文（README_ja.md）
+- UI 支持国际化
+- 默认语言为中文
+
+请记住：这是一个有真实用户的生产聊天机器人框架。始终进行彻底测试，确保更改不会破坏现有功能。

astrbot/__main__.py

@@ -0,0 +1,95 @@
+import argparse
+import asyncio
+import mimetypes
+import os
+import sys
+
+from astrbot.base import LOGO, AstrbotPaths
+from astrbot.core import LogBroker, LogManager, db_helper, logger
+from astrbot.core.config.default import VERSION
+from astrbot.core.initial_loader import InitialLoader
+from astrbot.core.utils.io import download_dashboard, get_dashboard_version
+
+
+def check_env():
+    if not (sys.version_info.major == 3 and sys.version_info.minor >= 10):
+        logger.error("请使用 Python3.10+ 运行本项目。")
+        exit()
+
+    # os.makedirs("data/config", exist_ok=True)
+    # os.makedirs("data/plugins", exist_ok=True)
+    # os.makedirs("data/temp", exist_ok=True)
+
+    # 针对问题 #181 的临时解决方案
+    mimetypes.add_type("text/javascript", ".js")
+    mimetypes.add_type("text/javascript", ".mjs")
+    mimetypes.add_type("application/json", ".json")
+
+
+async def check_dashboard_files(webui_dir: str | None = None):
+    """下载管理面板文件"""
+    # 指定webui目录
+    if webui_dir:
+        if os.path.exists(webui_dir):
+            logger.info(f"使用指定的 WebUI 目录: {webui_dir}")
+            return webui_dir
+        logger.warning(f"指定的 WebUI 目录 {webui_dir} 不存在，将使用默认逻辑。")
+
+    data_dist_path = str(AstrbotPaths.astrbot_root / "dist")
+    if os.path.exists(data_dist_path):
+        v = await get_dashboard_version()
+        if v is not None:
+            # 存在文件
+            if v == f"v{VERSION}":
+                logger.info("WebUI 版本已是最新。")
+            else:
+                logger.warning(
+                    f"检测到 WebUI 版本 ({v}) 与当前 AstrBot 版本 (v{VERSION}) 不符。",
+                )
+        return data_dist_path
+
+    logger.info(
+        "开始下载管理面板文件...高峰期（晚上）可能导致较慢的速度。如多次下载失败，请前往 https://github.com/AstrBotDevs/AstrBot/releases/latest 下载 dist.zip，并将其中的 dist 文件夹解压至 data 目录下。",
+    )
+
+    try:
+        await download_dashboard(version=f"v{VERSION}", latest=False)
+    except Exception as e:
+        logger.critical(f"下载管理面板文件失败: {e}。")
+        return None
+
+    logger.info("管理面板下载完成。")
+    return data_dist_path
+
+
+def main():
+    parser = argparse.ArgumentParser(description="AstrBot")
+    parser.add_argument(
+        "--webui-dir",
+        type=str,
+        help="指定 WebUI 静态文件目录路径",
+        default=None,
+    )
+    args = parser.parse_args()
+
+    check_env()
+
+    # 启动日志代理
+    log_broker = LogBroker()
+    LogManager.set_queue_handler(logger, log_broker)
+
+    # 检查仪表板文件
+    webui_dir = asyncio.run(check_dashboard_files(args.webui_dir))
+
+    db = db_helper
+
+    # 打印 logo
+    logger.info(LOGO)
+
+    core_lifecycle = InitialLoader(db, log_broker)
+    core_lifecycle.webui_dir = webui_dir
+    asyncio.run(core_lifecycle.start())
+
+
+if __name__ == "__main__":
+    main()

astrbot/base/__init__.py

@@ -1,7 +1,9 @@
 from .abc import IAstrbotPaths
+from .const import LOGO
 from .paths import AstrbotPaths
 
 __all__ = [
     "IAstrbotPaths",
     "AstrbotPaths",
+    "LOGO",
 ]

astrbot/base/abc.py

@@ -43,6 +43,16 @@ def data(self) -> Path:
     def log(self) -> Path:
         """获取模块日志目录."""
 
+    @property
+    @abstractmethod
+    def temp(self) -> Path:
+        """获取模块临时目录."""
+
+    @property
+    @abstractmethod
+    def plugins(self) -> Path:
+        """获取插件目录."""
+
     @abstractmethod
     def reload(self) -> None:
         """重新加载环境变量."""

astrbot/base/const.py

@@ -0,0 +1,9 @@
+LOGO = r"""
+     ___           _______.___________..______      .______     ______   .___________.
+    /   \         /       |           ||   _  \     |   _  \   /  __  \  |           |
+   /  ^  \       |   (----`---|  |----`|  |_)  |    |  |_)  | |  |  |  | `---|  |----`
+  /  /_\  \       \   \       |  |     |      /     |   _  <  |  |  |  |     |  |
+ /  _____  \  .----)   |      |  |     |  |\  \----.|  |_)  | |  `--'  |     |  |
+/__/     \__\ |_______/       |__|     | _| `._____||______/   \______/      |__|
+
+"""

astrbot/base/paths.py

@@ -19,13 +19,15 @@
 
 
 class AstrbotPaths(IAstrbotPaths):
-    """Class to manage and provide paths used by Astrbot Canary."""
+    """统一化路径获取."""
 
     load_dotenv()
     astrbot_root: ClassVar[Path] = Path(
         getenv("ASTRBOT_ROOT", Path.home() / ".astrbot")
     ).absolute()
 
+    _instances: ClassVar[dict[str, AstrbotPaths]] = {}
+
     def __init__(self, name: str) -> None:
         self.name: str = name
         # 确保根目录存在
@@ -35,8 +37,11 @@ def __init__(self, name: str) -> None:
     def getPaths(cls, name: str) -> AstrbotPaths:
         """返回Paths实例,用于访问模块的各类目录."""
         normalized_name: NormalizedName = canonicalize_name(name)
+        if normalized_name in cls._instances:
+            return cls._instances[normalized_name]
         instance: AstrbotPaths = cls(normalized_name)
         instance.name = normalized_name
+        cls._instances[normalized_name] = instance
         return instance
 
     @property
@@ -68,7 +73,7 @@ def config(self) -> Path:
 
     @property
     def data(self) -> Path:
-        """返回模块数据目录."""
+        """返回模块/插件数据目录."""
         data_path = self.astrbot_root / "data" / self.name
         data_path.mkdir(parents=True, exist_ok=True)
         return data_path
@@ -80,6 +85,20 @@ def log(self) -> Path:
         log_path.mkdir(parents=True, exist_ok=True)
         return log_path
 
+    @property
+    def temp(self) -> Path:
+        """返回模块临时文件目录."""
+        temp_path = self.astrbot_root / "temp" / self.name
+        temp_path.mkdir(parents=True, exist_ok=True)
+        return temp_path
+
+    @property
+    def plugins(self) -> Path:
+        """返回插件目录."""
+        plugin_path = self.astrbot_root / "plugins" / self.name
+        plugin_path.mkdir(parents=True, exist_ok=True)
+        return plugin_path
+
     @classmethod
     def is_root(cls, path: Path) -> bool:
         """检查路径是否为 Astrbot 根目录."""

astrbot/cli/__init__.py

@@ -1 +1 @@
-__version__ = "3.5.23"
+"""AstrBot CLI入口"""

astrbot/cli/__main__.py

@@ -1,27 +1,22 @@
 """AstrBot CLI入口"""
 
 import sys
+from importlib.metadata import version
 
 import click
 
-from . import __version__
+from astrbot.base import LOGO
+
 from .commands import conf, init, plug, run
 
-logo_tmpl = r"""
-     ___           _______.___________..______      .______     ______   .___________.
-    /   \         /       |           ||   _  \     |   _  \   /  __  \  |           |
-   /  ^  \       |   (----`---|  |----`|  |_)  |    |  |_)  | |  |  |  | `---|  |----`
-  /  /_\  \       \   \       |  |     |      /     |   _  <  |  |  |  |     |  |
- /  _____  \  .----)   |      |  |     |  |\  \----.|  |_)  | |  `--'  |     |  |
-/__/     \__\ |_______/       |__|     | _| `._____||______/   \______/      |__|
-"""
+__version__ = version("astrbot")
 
 
 @click.group()
 @click.version_option(__version__, prog_name="AstrBot")
 def cli() -> None:
     """The AstrBot CLI"""
-    click.echo(logo_tmpl)
+    click.echo(LOGO)
     click.echo("Welcome to AstrBot CLI!")
     click.echo(f"AstrBot CLI version: {__version__}")
 

astrbot/cli/commands/cmd_plug.py

@@ -4,6 +4,8 @@
 
 import click
 
+from astrbot.base import AstrbotPaths
+
 from ..utils import (
     PluginStatus,
     build_plug_list,
@@ -47,8 +49,7 @@ def display_plugins(plugins, title=None, color=None):
 @click.argument("name")
 def new(name: str):
     """创建新插件"""
-    base_path = _get_data_path()
-    plug_path = base_path / "plugins" / name
+    plug_path = AstrbotPaths.getPaths(name).plugins
 
     if plug_path.exists():
         raise click.ClickException(f"插件 {name} 已存在")

astrbot/cli/utils/basic.py

@@ -9,18 +9,19 @@
 def check_astrbot_root(path: str | Path) -> bool:
     """检查路径是否为 AstrBot 根目录"""
     warnings.warn(
-    "请使用 AstrbotPaths 类代替本模块中的函数",
-    DeprecationWarning,
-    stacklevel=2,
+        "请使用 AstrbotPaths 类代替本模块中的函数",
+        DeprecationWarning,
+        stacklevel=2,
     )
     return AstrbotPaths.is_root(Path(path))
 
+
 def get_astrbot_root() -> Path:
     """获取Astrbot根目录路径"""
     warnings.warn(
-    "请使用 AstrbotPaths 类代替本模块中的函数",
-    DeprecationWarning,
-    stacklevel=2,
+        "请使用 AstrbotPaths 类代替本模块中的函数",
+        DeprecationWarning,
+        stacklevel=2,
     )
     return AstrbotPaths.astrbot_root