feat: 实现统一的错误处理机制和增强日志系统

添加错误码定义和统一响应格式
增强日志记录功能，支持模块专用日志记录器
实现全局异常捕获和友好错误提示
更新文档说明错误处理机制

docs/core-concepts/error-handling.md

@@ -0,0 +1,194 @@
+# 错误处理机制
+
+NEO Bot 采用了统一的错误处理机制，确保在各种异常情况下提供清晰、一致的错误信息。本文档将介绍系统的错误处理架构、错误码定义和使用方法。
+
+## 1. 错误处理架构
+
+### 1.1 自定义异常体系
+
+系统定义了一套完整的自定义异常类体系，覆盖了各种常见的错误场景：
+
+- **WebSocket 相关错误**：`WebSocketError`、`WebSocketConnectionError`、`WebSocketAuthenticationError`
+- **插件相关错误**：`PluginError`、`PluginLoadError`、`PluginReloadError`、`PluginNotFoundError`
+- **配置相关错误**：`ConfigError`、`ConfigNotFoundError`、`ConfigValidationError`
+- **权限相关错误**：`PermissionError`
+- **命令相关错误**：`CommandError`、`CommandNotFoundError`、`CommandParameterError`
+- **Redis 相关错误**：`RedisError`
+- **浏览器管理器相关错误**：`BrowserManagerError`、`BrowserPoolError`
+- **代码执行相关错误**：`CodeExecutionError`
+
+所有自定义异常类都位于 `core.utils.exceptions` 模块中。
+
+### 1.2 统一的错误码系统
+
+系统使用统一的错误码来标识不同类型的错误，错误码规则如下：
+
+- `1xxx`：系统级错误
+- `2xxx`：WebSocket 相关错误
+- `3xxx`：插件相关错误
+- `4xxx`：配置相关错误
+- `5xxx`：权限相关错误
+- `6xxx`：命令相关错误
+- `7xxx`：Redis 相关错误
+- `8xxx`：浏览器管理器相关错误
+- `9xxx`：代码执行相关错误
+
+完整的错误码定义可以在 `core.utils.error_codes` 模块的 `ErrorCode` 类中找到。
+
+### 1.3 统一的错误响应格式
+
+系统提供了统一的错误响应格式，确保所有模块返回一致的错误信息：
+
+```json
+{
+  "code": 错误代码,
+  "message": 错误消息,
+  "success": false,
+  "data": 附加数据（可选）,
+  "request_id": 请求ID（可选）
+}
+```
+
+## 2. 日志记录增强
+
+### 2.1 模块专用日志记录器
+
+系统提供了 `ModuleLogger` 类，用于创建模块专用的日志记录器，自动添加模块标识：
+
+```python
+from core.utils.logger import ModuleLogger
+
+# 创建模块专用日志记录器
+logger = ModuleLogger("MyModule")
+
+# 使用日志记录器
+logger.info("模块初始化完成")
+logger.error("发生错误")
+logger.exception("发生异常")
+```
+
+### 2.2 异常详情记录
+
+系统提供了 `log_exception` 函数，用于记录自定义异常的详细信息：
+
+```python
+from core.utils.logger import log_exception
+from core.utils.exceptions import PluginError
+
+try:
+    # 代码逻辑
+    raise PluginError("插件加载失败", plugin_name="test_plugin")
+except Exception as e:
+    log_exception(e, module_name="PluginManager")
+```
+
+## 3. 核心模块的错误处理
+
+### 3.1 WebSocket 模块
+
+WebSocket 模块使用自定义异常类处理各种连接错误：
+
+- `WebSocketConnectionError`：连接失败
+- `WebSocketAuthenticationError`：认证失败
+- `WebSocketError`：其他 WebSocket 相关错误
+
+### 3.2 插件管理器模块
+
+插件管理器模块使用自定义异常类处理各种插件操作错误：
+
+- `PluginLoadError`：插件加载失败
+- `PluginReloadError`：插件重载失败
+- `PluginNotFoundError`：插件未找到
+
+### 3.3 配置加载器模块
+
+配置加载器模块使用自定义异常类处理各种配置加载错误：
+
+- `ConfigNotFoundError`：配置文件未找到
+- `ConfigValidationError`：配置验证失败
+- `ConfigError`：其他配置相关错误
+
+## 4. 全局异常捕获
+
+系统在主程序入口添加了全局异常捕获机制，确保所有未处理的异常都能被捕获并提供友好的错误信息：
+
+- 捕获并记录所有未处理的异常
+- 生成统一格式的错误响应
+- 根据错误类型给出不同的排查建议
+- 提供详细的错误信息和日志记录位置
+
+## 5. 如何在插件中使用错误处理
+
+### 5.1 抛出自定义异常
+
+在插件中，您可以使用系统提供的自定义异常类来抛出更精确的错误：
+
+```python
+from core.utils.exceptions import CommandParameterError
+from core.utils.logger import ModuleLogger
+
+logger = ModuleLogger("MyPlugin")
+
+@matcher.command("test")
+async def test_command(bot, event, args):
+    if len(args) < 1:
+        raise CommandParameterError("test", "缺少必要参数")
+    
+    # 命令逻辑
+```
+
+### 5.2 捕获并处理异常
+
+在插件中，您可以捕获并处理异常，提供更友好的错误信息：
+
+```python
+from core.utils.exceptions import PluginError
+from core.utils.logger import ModuleLogger
+
+logger = ModuleLogger("MyPlugin")
+
+@matcher.command("test")
+async def test_command(bot, event, args):
+    try:
+        # 可能抛出异常的代码
+        result = await some_operation()
+        await bot.send(event, f"操作结果: {result}")
+    except PluginError as e:
+        logger.error(f"插件操作失败: {e}")
+        await bot.send(event, f"操作失败: {e.message}")
+    except Exception as e:
+        logger.exception(f"发生未知错误: {e}")
+        await bot.send(event, "操作失败，请检查日志获取详细信息")
+```
+
+## 6. 错误排查建议
+
+### 6.1 WebSocket 错误
+
+- 检查 WebSocket 服务是否正在运行
+- 检查配置文件中的 WebSocket 地址和令牌是否正确
+- 检查网络连接是否正常
+
+### 6.2 插件错误
+
+- 检查插件目录是否存在
+- 检查插件文件是否有语法错误
+- 检查插件是否符合插件开发规范
+
+### 6.3 配置错误
+
+- 检查配置文件 config.toml 是否存在
+- 检查配置文件格式是否正确
+- 检查所有必填配置项是否都已设置
+
+## 7. 总结
+
+NEO Bot 的错误处理机制提供了：
+
+- 完整的自定义异常类体系
+- 统一的错误码系统
+- 一致的错误响应格式
+- 增强的日志记录功能
+- 全局异常捕获和友好提示
+
+这些功能确保了系统在各种异常情况下都能提供清晰、一致的错误信息，便于开发和维护。

docs/index.md

@@ -17,6 +17,7 @@
 *   [性能优化](./core-concepts/performance.md): 页面池、JIT、Mypyc... 
 *   [消息流](./core-concepts/event-flow.md): 看看一条消息从被接收到被回复是如何运行的
 *   [核心](./core-concepts/singleton-managers.md): `matcher`, `browser_manager`... 认识这些核心模块。
+*   [错误处理](./core-concepts/error-handling.md): 了解系统的错误处理机制和错误码定义。
 
 ### 3. API 参考
 *   [API 总览](./api/index.md): 所有 API 的快速导航和调用方式