diff --git a/core/managers/command_manager.py b/core/managers/command_manager.py index 43d9091..5d84e28 100644 --- a/core/managers/command_manager.py +++ b/core/managers/command_manager.py @@ -225,8 +225,7 @@ class CommandManager: help_text += f" 功能: {description}\n" help_text += f" 用法: {usage}\n" - await bot.send(event, MessageSegment.image(help_pic)) - # await bot.send(event, help_text.strip()) + await bot.send(event, help_text.strip()) # 实例化全局唯一的命令管理器 diff --git a/docs/core-concepts/architecture.md b/docs/core-concepts/architecture.md index f086ec2..20dcb17 100644 --- a/docs/core-concepts/architecture.md +++ b/docs/core-concepts/architecture.md @@ -6,8 +6,9 @@ Neobot是面向内部开发者的,我会开源,但是写的很烂。。。 ### Python 3.14 + JIT 镀铬酸钾创项目的时候用的 Python 3.14 3.14兼容JIT,那就这样吧 -* **何原理**: 提前编译了源代码, -* **何用途**: 密集CPU运算能提升一些 +* **何原理**: 运行时把热点代码编译成机器码(Just-In-Time) +* **何用途**: 密集CPU运算能提升一些,尤其是插件里的循环和函数调用 +* **怎么开**: 启动时加 `-X jit` 参数 ### Mypyc 编译 (AOT) 光 JIT 还不够。。核心模块(`core/ws.py`, `core/managers/*.py`)我编译成了C扩展 diff --git a/docs/core-concepts/performance.md b/docs/core-concepts/performance.md index b495881..79f588a 100644 --- a/docs/core-concepts/performance.md +++ b/docs/core-concepts/performance.md @@ -60,7 +60,37 @@ Python 自带的 `json` 库性能好像不太好,特别是在处理 OneBot 这 * Rust 编写 * 支持直接返回 `bytes`,减少内存复制。 -## 5. Mypyc 编译 (AOT Compilation) +## 5. Python 3.14 JIT (Just-In-Time Compilation) + +### 痛点 +Python 解释器一边解析一边执行,遇到循环和函数调用就得反复解释。像消息处理这种高频循环,解释开销就特别明显。 + +### 解决方案 +Python 3.14 自带了一个实验性的 JIT 编译器。启动时加上 `-X jit` 参数,它就会在运行时把热点代码编译成机器码。 + +**JIT 怎么工作的?** +1. **监控**: 解释器运行时会统计哪些函数、哪些循环被调最得频繁。 +2. **编译**: 把这些“热点”代码编译成机器码。 +3. **替换**: 下次再执行到这段代码,直接跑机器码,跳过解释步骤。 + +**哪些代码受益最大?** +- `plugins/` 里的业务逻辑(比如 B站解析、代码沙箱)。 +- 循环密集的操作(比如遍历消息段、处理大量群消息)。 +- 频繁调用的工具函数。 + +### 如何启用? +启动机器人时加上 `-X jit` 参数: + +```bash +python -X jit main.py +``` + +### 收益 +* **热点代码加速**: 经常跑的代码能快 2-10 倍(看具体场景)。 +* **零配置**: 不用改代码,加个启动参数就行。 +* **与 Mypyc 互补**: JIT 负责动态、灵活的插件代码;Mypyc 负责静态、类型明确的核心模块。两者结合,全面覆盖。 + +## 6. Mypyc 编译 (AOT Compilation) ### 痛点 Python 作为一种解释型语言,在处理 CPU 密集型任务时性能较差。对于机器人框架的核心部分,如 WebSocket 消息解析、事件分发和插件管理,这些代码被高频调用,其性能直接影响机器人的响应速度和吞吐量。 @@ -84,7 +114,7 @@ python setup_mypyc.py 脚本会自动查找并编译预设的模块列表。 ### 特别注意:关于事件模型的编译 -`Mypyc` 对 Python 的某些动态特性和高级用法支持尚不完善。在实践中,我们发现 `dataclass` 与 `Mypyc` 存在一些兼容性问题,尤其是在使用继承和某些高级特性(如 `slots=True`)时,可能会导致编译失败或运行时错误(例如 `AttributeError: attribute '__dict__' of 'type' objects is not writable`)。 +`Mypyc` 对 Python 某些动态特性和高级用法支持尚不完善。在实践中,我们发现 `dataclass` 与 `Mypyc` 存在一些兼容性问题,尤其是在使用继承和某些高级特性(如 `slots=True`)时,可能会导致编译失败或运行时错误(例如 `AttributeError: attribute '__dict__' of 'type' objects is not writable`)。 - **当前状态**:为了确保稳定性,`setup_mypyc.py` 脚本**默认不编译** `models/events/` 目录下的事件模型文件。这些文件虽然也被频繁使用,但它们的结构相对复杂,与 `Mypyc` 的兼容性问题仍在探索中。 - **未来展望**:我们会持续关注 `Mypyc` 的更新,当其对 `dataclass` 的支持得到改善后,会重新尝试将事件模型加入编译列表,以实现极致的性能。 diff --git a/docs/deployment.md b/docs/deployment.md index 62e8d2f..e2b1ca7 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -24,7 +24,10 @@ pip install -r requirements.txt ### c. 编译核心模块 (可选,但为获得最佳性能强烈建议) -为了最大化性能,你可以将项目中的核心 Python 模块编译成 C 语言扩展。这将大幅提升机器人的响应速度和处理效率。 +为了最大化性能,我们提供了两层级性能优化方案: + +#### 1. Mypyc 编译 (AOT - Ahead-of-Time) +将核心 Python 模块编译成 C 语言扩展。这将大幅提升机器人的响应速度和处理效率。 ```bash # 确保你在虚拟环境中 @@ -35,6 +38,16 @@ python setup_mypyc.py > **注意**: 编译产物是平台相关的(例如,在 Windows 上编译的 `.pyd` 文件不能在 Linux 上使用)。因此,**请务必在你最终部署的服务器环境(例如 Linux)上执行此编译步骤**。更多关于 Mypyc 编译的细节,请参考 [性能优化详解](core-concepts/performance.md)。 +#### 2. Python 3.14 JIT (Just-In-Time) +即使不编译核心模块,你也可以通过启用 Python 3.14 自带的 JIT 编译器来获得性能提升。JIT 会在运行时将热点代码编译为机器码。 + +**如何启用**: 在启动命令中添加 `-X jit` 参数,或者在下面的 pm2 配置中添加 JIT 参数。 + +**性能策略**: +- **AOT (Mypyc)**: 负责静态、类型明确的核心模块(WebSocket、管理器、工具函数) +- **JIT**: 负责动态、灵活的插件代码(B站解析、代码沙箱等业务逻辑) +- **两者结合**: 可获得最佳性能,全面覆盖所有代码路径 + ## 2. 使用进程管理器 你想直接 `python main.py` 然后关掉 SSH?那机器人也跟着停了。必须用进程管理器来守护它。 @@ -58,6 +71,7 @@ module.exports = { name : "neobot", script : "main.py", interpreter: "/path/to/your/bot/venv/bin/python", // 指定虚拟环境里的 python + args: "-X jit", // 启用 Python 3.14 JIT 编译器 max_memory_restart: "500M", // 内存超过 500M 自动重启 env: { "PYTHONUNBUFFERED": "1" // 禁用 python 输出缓冲,日志能实时看