From aa6fa8d336cac3cac9186b4ebe59f151966e1ad6 Mon Sep 17 00:00:00 2001
From: InfinityPacer <160988576+InfinityPacer@users.noreply.github.com>
Date: Mon, 9 Sep 2024 21:39:27 +0800
Subject: [PATCH] =?UTF-8?q?chore:=20Add=20=E6=8F=92=E4=BB=B6=E7=89=88?=
 =?UTF-8?q?=E6=9C=AC=E5=85=BC=E5=AE=B9=E4=B8=8E=E5=8D=87=E7=BA=A7=E6=96=B9?=
 =?UTF-8?q?=E6=A1=88.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/插件版本兼容与升级方案.md | 128 +++++++++++++++++++++++++++++++++
 1 file changed, 128 insertions(+)
 create mode 100644 docs/插件版本兼容与升级方案.md

diff --git a/docs/插件版本兼容与升级方案.md b/docs/插件版本兼容与升级方案.md
new file mode 100644
index 00000000..beb96f50
--- /dev/null
+++ b/docs/插件版本兼容与升级方案.md
@@ -0,0 +1,128 @@
+### **插件版本兼容与升级方案**
+
+#### 1. **插件目录结构**
+为了确保插件管理的灵活性和兼容性，插件根据不同版本进行隔离，同时可以通过全局 `package.json` 标识兼容性。以下是目录结构示例：
+
+```
+- plugins/       // 全局插件目录，默认支持 v1
+- plugins.v2/    // v2 专用插件目录，管理与 v1 不兼容的插件
+  - package.json // v2 专用的 package.json，管理特定 v2 插件
+- plugins.v3/    // v3 专用插件目录，管理与 v1、v2 不兼容的插件
+  - package.json // v3 专用的 package.json，管理特定 v3 插件
+- package.json   // 全局 package.json，管理 v1、v2、v3 插件的兼容性
+```
+
+- **v1 项目**：使用 `plugins` 目录，加载全局插件，默认支持 v1 项目。
+- **v2 项目**：使用 `plugins.v2` 目录管理 v2 项目专用插件，并通过全局 `package.json` 检查多版本兼容插件。
+- **v3 项目**：使用 `plugins.v3` 目录管理 v3 项目专用插件，依次检查 `plugins.v2` 和全局 `package.json`。
+
+#### 2. **全局 `package.json` 插件管理**
+全局 `package.json` 文件管理插件的默认兼容性。所有插件默认支持 v1 项目，并通过 `v2: true` 和 `v3: true` 字段标识插件是否支持 v2 或 v3 项目。以下是示例：
+
+```json
+{
+  "CustomSites": {
+    "name": "自定义站点",
+    "description": "增加自定义站点为签到和统计使用。",
+    "labels": "站点",
+    "version": "1.0",
+    "icon": "world.png",
+    "author": "lightolly",
+    "level": 2,
+    "v2": true, // 适配 v2 版本
+    "v3": false, // 不适配 v3，明确标记
+    "history": {
+      "v1.2": "功能更新，提升性能",
+      "v1.1": "修复小问题",
+      "v1.0": "初始版本"
+    }
+  }
+}
+```
+
+#### 3. **版本专属 `package.json` 文件**
+为了管理 v2 和 v3 项目中的插件依赖，`plugins.v2` 和 `plugins.v3` 目录分别拥有自己的 `package.json` 文件，管理特定版本插件。这些插件可能与 v1 或其他版本不兼容，因此需要在各自版本中独立维护。
+
+- **v2 的 `package.json` 文件示例**：
+```json
+{
+  "CustomSites": {
+    "name": "自定义站点",
+    "description": "增加自定义站点为签到和统计使用。",
+    "labels": "站点",
+    "version": "1.0",
+    "icon": "world.png",
+    "author": "lightolly",
+    "level": 2,
+    "history": {
+      "v1.0": "初始版本"
+    }
+  }
+}
+```
+
+- **v3 的 `package.json` 文件示例**：
+```json
+{
+  "CustomSites": {
+    "name": "自定义站点",
+    "description": "增加自定义站点为签到和统计使用。",
+    "labels": "站点",
+    "version": "1.0",
+    "icon": "world.png",
+    "author": "lightolly",
+    "level": 2,
+    "history": {
+      "v1.0": "初始版本"
+    }
+  }
+}
+```
+
+#### 4. **插件加载与版本检测**
+
+##### **v1 项目**
+- 默认只从 `plugins` 目录加载插件，不进行任何版本筛选。
+- `package.json` 中的所有插件默认被视为兼容 v1 项目。
+
+##### **v2 项目**
+- **优先加载 `plugins.v2` 目录中的插件**，并依赖 `plugins.v2/package.json` 管理插件版本和依赖。
+- 如果插件在 `plugins.v2` 中不存在，则检查全局 `package.json` 中是否有标记 `v2: true` 的插件，并从全局 `plugins` 目录加载这些插件。
+
+##### **v3 项目**
+- **优先加载 `plugins.v3` 目录中的插件**，并依赖 `plugins.v3/package.json` 管理插件版本和依赖。
+- 如果插件在 `plugins.v3` 中不存在，则从 `plugins.v2` 目录加载插件。
+- 如果 `plugins.v2` 中也不存在，则检查全局 `package.json` 中标记 `v3: true` 的插件，并从全局 `plugins` 目录加载。
+
+#### 5. **插件冲突处理**
+当同一插件存在于多个目录时，插件加载按照以下优先级处理：
+
+- **v3 项目**：
+  - 优先加载 `plugins.v3` 目录中的插件。
+  - 若该插件不存在于 `plugins.v3` 中，则加载 `plugins.v2` 目录中的插件。
+  - 最后，若 `plugins.v2` 中也不存在，则从全局 `plugins` 目录加载并检查全局 `package.json` 中标记为 `v3: true` 的插件。
+
+- **v2 项目**：
+  - 优先加载 `plugins.v2` 目录中的插件。
+  - 若该插件不存在，则从全局 `plugins` 目录加载并检查全局 `package.json` 中标记为 `v2: true` 的插件。
+
+- **v1 项目**：
+  - 仅加载 `plugins` 目录中的全局插件，不涉及版本兼容性检查。
+
+#### 6. **插件升级与管理**
+- **v1 项目**：所有插件的升级和管理在全局 `package.json` 和 `plugins` 目录中进行。
+  
+- **v2 和 v3 项目**：
+  - 插件可以通过 `package.json` 中的 `v2: true` 和 `v3: true` 字段在多版本项目中共享。
+  - 插件也可以独立管理在 `plugins.v2` 或 `plugins.v3` 目录中，以确保版本专属插件不会影响其他版本项目。
+
+#### 7. **向后兼容性**
+- **v1 项目**：继续只从 `plugins` 目录加载全局插件，不受 `v2` 和 `v3` 插件的影响，确保向后兼容性。
+  
+- **v2 和 v3 项目**：通过独立的 `plugins.v2` 和 `plugins.v3` 目录管理专属插件，同时依赖全局 `package.json` 来处理跨版本兼容插件。
+
+---
+
+### **总结**
+该方案结合了全局和版本专属的插件管理策略，确保了插件在不同项目版本中的兼容性和灵活性。全局 `package.json` 管理多版本兼容插件，而 `plugins.v2` 和 `plugins.v3` 目录则为各自项目管理特定版本插件。通过插件加载优先级和独立的 `package.json` 文件，实现了高效的插件版本控制和向后兼容性。
+