docs: refactor and relocate version and usage notes in README

Author: HowieHz

README.md

@@ -56,161 +56,12 @@
 
 感谢所有支持本项目的用户和开发者，也特别感谢 Halo CMS 团队为插件生态提供的优秀平台。
 
-## 版本说明
-
-插件提供两个版本：
-
-- **全量版**：包含所有功能，包括代码高亮等依赖 JS 的相关功能。
-- **轻量版**：轻量级版本，不包含 JS 相关功能和相关依赖。
-
-### 轻量版的优势
-
-- 更小的插件体积
-- 更快的启动速度
-- 更低的内存占用
-- 更低的系统性能要求
-- 支持全平台（全量版仅支持以下平台：Linux ARM64、Linux x86_64、macOS ARM64、macOS x86_64、Windows x86_64）
-
-### 轻量版本缺少的功能
-
-- 代码高亮（Shiki.js 渲染）
-
-<!-- - 图表渲染（Mermaid）
-- 公式渲染（KaTeX） -->
-
-- 其他 JS 运行时相关功能
-
-如果您需要上述功能，请使用全量版。
-
-## 全量版使用须知
-
-⏱️ **首次使用提示**: 全量版的 JavaScript 功能（如 Shiki 代码高亮）在首次调用时需要 1~3 秒进行环境初始化。这是正常现象，之后的调用速度会非常快。
-
-> ⚠️ **重要**: 全量版依赖 Javet 加载 Node.js 原生库（基于 JNI），受 Halo 插件架构限制，存在[已知问题](#全量版已知问题)。
-
-### 基本使用要求
-
-1. **请勿热重载更新**: 请勿直接覆盖更新（如使用应用商店/插件列表的快捷更新操作）
-2. **正确的更新流程**:
-    - 方法一：停止插件 → 卸载插件 → **重启 Halo** → 安装新版本 → 启动插件
-    - 方法二：停止插件 → 卸载插件 → 安装新版本 → **重启 Halo** → 启动插件
-3. **卸载推荐做法**: 在卸载全量版后**重启 Halo** 确保原生库资源完全释放。
-
-### 全量版已知问题
-
-- 问题一：卸载后重新安装全量版插件，不重启就启用。调用 JS 相关 API 时会出现错误：
-    - **首次安装并启动**: 正常工作
-    - **禁用后重新启用**: 正常工作
-    - **卸载后重新安装**: ❌ 会出现 `JavetException: Javet library is not loaded` 错误
-    - **重启 Halo 后**: 恢复正常工作
-
-#### 问题一解决方案
-
-安装好新版本插件后**先别启用**！   
-在启用新版本插件之前，请**先重启 Halo CMS**。
-
-未来版本会将引擎作为前置依赖插件，更新本插件不再需要重启。
-
-<details>
-<summary>📖 技术原因分析（展开查看详细说明）</summary>
-
-根据错误日志和 Halo 架构分析:
-
-**问题根源**:
-
-1. **Halo 插件架构**: 根据 [Halo 开发文档 - 插件架构](https://docs.halo.run/developer-guide/core/framework), Halo 使用
-   Spring Plugin Framework 实现插件隔离
-    - 每个插件拥有独立的 Spring ApplicationContext
-    - 每个插件使用独立的 classloader 加载资源
-    - 插件间通过 ExtensionPoint 机制通信
-    - classloader 完全隔离,无法跨插件共享类或资源
-
-2. **Javet 原生库加载机制**:
-    - Javet 需要从 JAR 中提取原生库文件(`.dll`/`.so`/`.dylib`)到临时目录
-    - JVM 通过 JNI 加载这些原生库文件
-    - 原生库文件一旦加载,会被 JVM 锁定
-
-3. **冲突发生过程**:
-    - 安装插件时,Javet 提取原生库文件到 `C:\Users\用户名\AppData\Local\Temp\javet\进程ID\`（以 Windows 举例）
-    - JVM 加载这些文件并锁定
-    - 卸载插件时,虽然 classloader 被销毁,但原生库文件仍被 JVM 锁定,无法删除
-    - 重新安装时,Javet 尝试提取新文件到同一位置
-    - 因为文件被锁定,提取失败
-    - Javet 初始化失败,报错 `Javet library is not loaded because <null>`
-
-**典型错误日志解读**:
-
-```
-WARN - Failed to write to ...libjavet-node-windows-x86_64.v.4.1.7.dll because it is locked
-ERROR - Native Library already loaded in another classloader
-ERROR - JavetException: Javet library is not loaded because <null>
-```
-
-这三条日志清晰地展示了整个失败过程:
-
-1. 尝试写入文件失败(文件被锁定)
-2. 检测到库已在其他 classloader 中加载
-3. 初始化失败，因为无法提取必要的库文件
-
-**为什么重启有效**:
-
-- 重启 Halo 会终止 JVM 进程
-- JVM 终止时会释放所有文件锁
-- 临时目录中的原生库文件会被清理
-- 新的 Halo 进程启动后，Javet 可以正常提取和加载原生库
-
-**为什么 Javet 文档中提到的 JVM 参数无效**:
-
-`-Djavet.lib.loading.suppress.error=true` 这个参数的作用是:
-
-- 抑制 Javet 在检测到"already loaded in another classloader"时的错误日志
-- **但无法解决文件锁定问题**
-- 当库文件无法提取时，Javet 根本无法完成初始化
-- 因此该参数在这个场景下无效
-
-**架构层面的限制**:
-
-这个问题是 JVM/JNI + 插件 classloader 隔离的固有矛盾:
-
-- Halo 的插件隔离设计保证了安全性和稳定性
-- 但也导致原生库这类 JVM 级别资源难以管理
-- 类似问题在所有使用 classloader 隔离的插件系统中都存在
-- 这不是 Javet 或本插件的 bug，而是架构层面的限制
-
-**相关技术文档**:
-
-- [Javet - Load and Unload](https://www.caoccao.com/Javet/reference/resource_management/load_and_unload.html)
-- [Javet Issue #124 - Classloader Reload](https://github.com/caoccao/Javet/issues/124)
-- [Halo - Plugin Framework](https://docs.halo.run/developer-guide/core/framework)
-
-</details>
-
-## TODO
-
-<details><summary>展开折叠内容</summary>
-
-- [ ] 提供随机文章 API
-- [ ] 提供预计阅读时间 API，及相关配置项
-- [ ] 提供图表渲染 API
-- [ ] 提供公式渲染 API
-- [ ] 分离 Node.js 环境支持为可选前置插件（预计 3.0 版本实现）
-
-</details>
-
 ## 文档目录
 
 - [halo-plugin-extra-api](#halo-plugin-extra-api)
   - [简介](#简介)
   - [核心理念](#核心理念)
   - [功能介绍](#功能介绍)
-  - [版本说明](#版本说明)
-    - [轻量版的优势](#轻量版的优势)
-    - [轻量版本缺少的功能](#轻量版本缺少的功能)
-  - [全量版使用须知](#全量版使用须知)
-    - [基本使用要求](#基本使用要求)
-    - [全量版已知问题](#全量版已知问题)
-      - [问题一解决方案](#问题一解决方案)
-  - [TODO](#todo)
   - [文档目录](#文档目录)
   - [Finder API 文档](#finder-api-文档)
     - [文档类型定义](#文档类型定义)
@@ -228,11 +79,19 @@ ERROR - JavetException: Javet library is not loaded because <null>
       - [配置选项](#配置选项)
       - [支持的主题](#支持的主题)
       - [补充说明](#补充说明)
+  - [版本说明](#版本说明)
+    - [轻量版的优势](#轻量版的优势)
+    - [轻量版本缺少的功能](#轻量版本缺少的功能)
+  - [全量版使用须知](#全量版使用须知)
+    - [基本使用要求](#基本使用要求)
+    - [全量版已知问题](#全量版已知问题)
+      - [问题一解决方案](#问题一解决方案)
   - [下载和安装](#下载和安装)
     - [稳定版](#稳定版)
     - [开发版](#开发版)
       - [下载步骤](#下载步骤)
   - [开发指南/贡献指南](#开发指南贡献指南)
+  - [TODO](#todo)
   - [许可证](#许可证)
 
 ## Finder API 文档
@@ -657,8 +516,140 @@ extraApiRenderFinder.renderCodeHtml(htmlContent)
 - 补充说明：
     - 双主题模式会生成两个并列的 div 元素
 
+## 版本说明
+
+插件提供两个版本：
+
+- **全量版**：包含所有功能，包括代码高亮等依赖 JS 的相关功能。
+- **轻量版**：轻量级版本，不包含 JS 相关功能和相关依赖。
+
+### 轻量版的优势
+
+- 更小的插件体积
+- 更快的启动速度
+- 更低的内存占用
+- 更低的系统性能要求
+- 支持全平台（全量版仅支持以下平台：Linux ARM64、Linux x86_64、macOS ARM64、macOS x86_64、Windows x86_64）
+
+### 轻量版本缺少的功能
+
+- 代码高亮（Shiki.js 渲染）
+
+<!-- - 图表渲染（Mermaid）
+- 公式渲染（KaTeX） -->
+
+- 其他 JS 运行时相关功能
+
+如果您需要上述功能，请使用全量版。
+
+## 全量版使用须知
+
+⏱️ **首次使用提示**: 全量版的 JavaScript 功能（如 Shiki 代码高亮）在首次调用时需要 1~3 秒进行环境初始化。这是正常现象，之后的调用速度会非常快。
+
+> ⚠️ **重要**: 全量版依赖 Javet 加载 Node.js 原生库（基于 JNI），受 Halo 插件架构限制，存在[已知问题](#全量版已知问题)。
+
+### 基本使用要求
+
+1. **请勿热重载更新**: 请勿直接覆盖更新（如使用应用商店/插件列表的快捷更新操作）
+2. **正确的更新流程**:
+    - 方法一：停止插件 → 卸载插件 → **重启 Halo** → 安装新版本 → 启动插件
+    - 方法二：停止插件 → 卸载插件 → 安装新版本 → **重启 Halo** → 启动插件
+3. **卸载推荐做法**: 在卸载全量版后**重启 Halo** 确保原生库资源完全释放。
+
+### 全量版已知问题
+
+- 问题一：卸载后重新安装全量版插件，不重启就启用。调用 JS 相关 API 时会出现错误：
+    - **首次安装并启动**: 正常工作
+    - **禁用后重新启用**: 正常工作
+    - **卸载后重新安装**: ❌ 会出现 `JavetException: Javet library is not loaded` 错误
+    - **重启 Halo 后**: 恢复正常工作
+
+#### 问题一解决方案
+
+安装好新版本插件后**先别启用**！   
+在启用新版本插件之前，请**先重启 Halo CMS**。
+
+未来版本会将引擎作为前置依赖插件，更新本插件不再需要重启。
+
+<details>
+<summary>📖 技术原因分析（展开查看详细说明）</summary>
+
+根据错误日志和 Halo 架构分析:
+
+**问题根源**:
+
+1. **Halo 插件架构**: 根据 [Halo 开发文档 - 插件架构](https://docs.halo.run/developer-guide/core/framework), Halo 使用
+   Spring Plugin Framework 实现插件隔离
+    - 每个插件拥有独立的 Spring ApplicationContext
+    - 每个插件使用独立的 classloader 加载资源
+    - 插件间通过 ExtensionPoint 机制通信
+    - classloader 完全隔离,无法跨插件共享类或资源
+
+2. **Javet 原生库加载机制**:
+    - Javet 需要从 JAR 中提取原生库文件(`.dll`/`.so`/`.dylib`)到临时目录
+    - JVM 通过 JNI 加载这些原生库文件
+    - 原生库文件一旦加载,会被 JVM 锁定
+
+3. **冲突发生过程**:
+    - 安装插件时,Javet 提取原生库文件到 `C:\Users\用户名\AppData\Local\Temp\javet\进程ID\`（以 Windows 举例）
+    - JVM 加载这些文件并锁定
+    - 卸载插件时,虽然 classloader 被销毁,但原生库文件仍被 JVM 锁定,无法删除
+    - 重新安装时,Javet 尝试提取新文件到同一位置
+    - 因为文件被锁定,提取失败
+    - Javet 初始化失败,报错 `Javet library is not loaded because <null>`
+
+**典型错误日志解读**:
+
+```
+WARN - Failed to write to ...libjavet-node-windows-x86_64.v.4.1.7.dll because it is locked
+ERROR - Native Library already loaded in another classloader
+ERROR - JavetException: Javet library is not loaded because <null>
+```
+
+这三条日志清晰地展示了整个失败过程:
+
+1. 尝试写入文件失败(文件被锁定)
+2. 检测到库已在其他 classloader 中加载
+3. 初始化失败，因为无法提取必要的库文件
+
+**为什么重启有效**:
+
+- 重启 Halo 会终止 JVM 进程
+- JVM 终止时会释放所有文件锁
+- 临时目录中的原生库文件会被清理
+- 新的 Halo 进程启动后，Javet 可以正常提取和加载原生库
+
+**为什么 Javet 文档中提到的 JVM 参数无效**:
+
+`-Djavet.lib.loading.suppress.error=true` 这个参数的作用是:
+
+- 抑制 Javet 在检测到"already loaded in another classloader"时的错误日志
+- **但无法解决文件锁定问题**
+- 当库文件无法提取时，Javet 根本无法完成初始化
+- 因此该参数在这个场景下无效
+
+**架构层面的限制**:
+
+这个问题是 JVM/JNI + 插件 classloader 隔离的固有矛盾:
+
+- Halo 的插件隔离设计保证了安全性和稳定性
+- 但也导致原生库这类 JVM 级别资源难以管理
+- 类似问题在所有使用 classloader 隔离的插件系统中都存在
+- 这不是 Javet 或本插件的 bug，而是架构层面的限制
+
+**相关技术文档**:
+
+- [Javet - Load and Unload](https://www.caoccao.com/Javet/reference/resource_management/load_and_unload.html)
+- [Javet Issue #124 - Classloader Reload](https://github.com/caoccao/Javet/issues/124)
+- [Halo - Plugin Framework](https://docs.halo.run/developer-guide/core/framework)
+
+</details>
+
 ## 下载和安装
 
+全量版和轻量版的区别请看：[版本说明](#版本说明)
+使用全量版前请看：[全量版使用须知](#全量版使用须知)
+
 ### 稳定版
 
 稳定版通过 GitHub Releases 发布，建议生产环境使用。
@@ -700,6 +691,18 @@ extraApiRenderFinder.renderCodeHtml(htmlContent)
 
 参见 [CONTRIBUTING.md](./CONTRIBUTING.md)
 
+## TODO
+
+<details><summary>展开折叠内容</summary>
+
+- [ ] 提供随机文章 API
+- [ ] 提供预计阅读时间 API，及相关配置项
+- [ ] 提供图表渲染 API
+- [ ] 提供公式渲染 API
+- [ ] 分离 Node.js 环境支持为可选前置插件（预计 3.0 版本实现）
+
+</details>
+
 ## 许可证
 
 [AGPL-3.0](./LICENSE) © HowieHz