From 7868fb2b4178fb328c8ed3216dff5d5787654235 Mon Sep 17 00:00:00 2001
From: K2cr2O1 <2221577113@qq.com>
Date: Tue, 13 Jan 2026 10:18:48 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E6=80=A7=E8=83=BD?=
 =?UTF-8?q?=E4=BC=98=E5=8C=96=E6=96=87=E6=A1=A3=E5=B9=B6=E4=BF=AE=E5=A4=8D?=
 =?UTF-8?q?=E5=91=BD=E4=BB=A4=E7=AE=A1=E7=90=86=E5=99=A8=E5=B8=AE=E5=8A=A9?=
 =?UTF-8?q?=E8=BE=93=E5=87=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

更新性能优化相关文档，详细说明 Python 3.14 JIT 编译器的使用方法和原理，补充与 Mypyc 的互补策略。同时修复命令管理器中帮助信息的输出方式，移除图片发送仅保留文本输出。

调整部署文档结构，明确两种性能优化方案（AOT 和 JIT）的配置方法和适用场景。完善架构文档中关于 JIT 的原理和启用方式说明。
---
 core/managers/command_manager.py   |  3 +--
 docs/core-concepts/architecture.md |  5 +++--
 docs/core-concepts/performance.md  | 34 ++++++++++++++++++++++++++++--
 docs/deployment.md                 | 16 +++++++++++++-
 4 files changed, 51 insertions(+), 7 deletions(-)

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 输出缓冲，日志能实时看