Merge branch 'main' into dev

docs/core-concepts/performance.md

@@ -119,4 +119,22 @@ python setup_mypyc.py
 - **当前状态**：为了确保稳定性，`setup_mypyc.py` 脚本**默认不编译** `models/events/` 目录下的事件模型文件。这些文件虽然也被频繁使用，但它们的结构相对复杂，与 `Mypyc` 的兼容性问题仍在探索中。
 - **未来展望**：我们会持续关注 `Mypyc` 的更新，当其对 `dataclass` 的支持得到改善后，会重新尝试将事件模型加入编译列表，以实现极致的性能。
 
+## 7. 健壮的 WebSocket 连接池
+
+### 痛点
+在高并发或网络不稳定的情况下，单个 WebSocket 连接可能会因为各种原因（如超时、服务器重启、网络波动）而中断或变得不可靠。如果框架依赖于单一的、不稳定的连接，会导致 API 调用频繁失败，甚至整个机器人无响应。
+
+### 解决方案
+`NeoBot` 实现了一个健壮的 `WebSocket 连接池` (`core/ws_pool.py`)，它不仅管理多个连接，还具备智能的健康检查和恢复机制。
+
+- **多连接管理**: 启动时会建立一个包含多个 WebSocket 连接的池，API 调用会被分发到这些连接上，实现负载均衡。
+- **自动健康检查**: 连接池会定期对池中的每个连接进行健康检查（发送 `get_status` 心跳包）。如果一个连接在规定时间内没有响应，它会被标记为“不健康”。
+- **故障转移与恢复**: 当一个 API 调用需要使用连接时，连接池会自动选择一个“健康”的连接。如果所有连接都不健康，它会尝试重新建立新的连接，直到成功为止。
+- **无感切换**: 对于上层调用者（如插件开发者）来说，这一切都是透明的。你只需要正常调用 `bot.call_api()`，连接池会在底层处理好所有的连接问题。
+
+### 收益
+- **高可用性**: 即使部分连接失效，机器人依然可以通过健康的连接继续提供服务，大大减少了因网络问题导致的停机时间。
+- **高并发性能**: 通过连接池，多个 API 请求可以并行地通过不同的连接发送，提高了在高并发场景下的吞吐量。
+- **自动恢复**: 无需手动重启机器人，连接池能够自动从网络故障中恢复，增强了系统的稳定性和无人值守能力。
+
 通过这种方式，我们在保证核心模块性能的同时，也维持了项目的稳定性和可维护性。

docs/getting-started.md

@@ -44,6 +44,8 @@ source venv/bin/activate
 pip install -r requirements.txt
 ```
 
+这个文件里包含了所有需要的 Python 库，比如 `aiohttp` (HTTP 请求), `orjson` (JSON 解析), `jinja2` (模板渲染), `psutil` (系统监控) 等等。
+
 ### d. 安装 Playwright 依赖
 
 我们用 Playwright 来截图画画，它需要一个浏览器核心。

docs/plugin-development/index.md

@@ -72,3 +72,9 @@ Bot 应该会回复你：“你好，[你的昵称]！”
     *   `args: str`: 如果命令有参数（比如 `/echo hello world`），`args` 就是 `hello world` 这部分字符串。
 
 就这么简单，一个最基础的插件就写完了。
+
+## 进阶阅读
+
+- [指令处理](./command-handling.md): 了解如何处理参数、获取用户输入。
+- [最佳实践](./best-practices.md): 学习如何编写更健壮、更高效的插件。
+- [插件详解：/status 状态监控](./status-plugin.md): 深入了解内置的状态监控插件是如何实现的。