add doc

2025-06-20 12:08:15 +08:00
parent 16df1661b1
commit 68f3a9504a
3 changed files with 181 additions and 19 deletions
--- a/docs/plugins/command-components.md
+++ b/docs/plugins/command-components.md
@@ -509,6 +509,4 @@ async def execute(self) -> Tuple[bool, Optional[str]]:
 - ✅ 智能建议和帮助
 - ✅ 随机化的互动

---

-🎉 **现在你已经掌握了Command组件开发的完整知识！继续学习 [API参考](api/) 来了解所有可用的接口。**
--- a/docs/plugins/configuration-guide.md
+++ b/docs/plugins/configuration-guide.md
@@ -9,10 +9,11 @@
 ## 📖 目录

 1. [配置架构变更说明](#配置架构变更说明)
-2. [配置定义：Schema驱动的配置系统](#配置定义schema驱动的配置系统)
-3. [配置访问：在Action和Command中使用配置](#配置访问在action和command中使用配置)
-4. [完整示例：从定义到使用](#完整示例从定义到使用)
-5. [最佳实践与注意事项](#最佳实践与注意事项)
+2. [配置版本管理](#配置版本管理)
+3. [配置定义：Schema驱动的配置系统](#配置定义schema驱动的配置系统)
+4. [配置访问：在Action和Command中使用配置](#配置访问在action和command中使用配置)
+5. [完整示例：从定义到使用](#完整示例从定义到使用)
+6. [最佳实践与注意事项](#最佳实践与注意事项)

 ---

@@ -31,6 +32,181 @@
  - 用户可调整的行为参数


+---
+
+## 配置版本管理
+
+### 🎯 版本管理概述
+
+插件系统提供了强大的**配置版本管理机制**，可以在插件升级时自动处理配置文件的迁移和更新，确保配置结构始终与代码保持同步。
+
+### 🔄 配置版本管理工作流程
+
+```mermaid
+graph TD
+    A[插件加载] --> B[检查配置文件]
+    B --> C{配置文件存在?}
+    C -->|不存在| D[生成默认配置]
+    C -->|存在| E[读取当前版本]
+    E --> F{有版本信息?}
+    F -->|无版本| G[跳过版本检查<br/>直接加载配置]
+    F -->|有版本| H{版本匹配?}
+    H -->|匹配| I[直接加载配置]
+    H -->|不匹配| J[配置迁移]
+    J --> K[生成新配置结构]
+    K --> L[迁移旧配置值]
+    L --> M[保存迁移后配置]
+    M --> N[配置加载完成]
+    D --> N
+    G --> N
+    I --> N
+    
+    style J fill:#FFB6C1
+    style K fill:#90EE90
+    style G fill:#87CEEB
+    style N fill:#DDA0DD
+```
+
+### 📊 版本管理策略
+
+#### 1. 配置版本定义
+
+在 `config_schema` 的 `plugin` 节中定义 `config_version`：
+
+```python
+config_schema = {
+    "plugin": {
+        "enabled": ConfigField(type=bool, default=False, description="是否启用插件"),
+        "config_version": ConfigField(type=str, default="1.2.0", description="配置文件版本"),
+    },
+    # 其他配置...
+}
+```
+
+#### 2. 版本检查行为
+
+- **无版本信息** (`config_version` 不存在)
+  - 系统会**跳过版本检查**，直接加载现有配置
+  - 适用于旧版本插件的兼容性处理
+  - 日志显示：`配置文件无版本信息，跳过版本检查`
+
+- **有版本信息** (存在 `config_version` 字段)
+  - 比较当前版本与期望版本
+  - 版本不匹配时自动执行配置迁移
+  - 版本匹配时直接加载配置
+
+#### 3. 配置迁移过程
+
+当检测到版本不匹配时，系统会：
+
+1. **生成新配置结构** - 根据最新的 `config_schema` 生成新的配置结构
+2. **迁移配置值** - 将旧配置文件中的值迁移到新结构中
+3. **处理新增字段** - 新增的配置项使用默认值
+4. **更新版本号** - `config_version` 字段自动更新为最新版本
+5. **保存配置文件** - 迁移后的配置直接覆盖原文件（不保留备份）
+
+### 🔧 实际使用示例
+
+#### 版本升级场景
+
+假设你的插件从 v1.0 升级到 v1.1，新增了权限管理功能：
+
+**旧版本配置 (v1.0.0):**
+```toml
+[plugin]
+enabled = true
+config_version = "1.0.0"
+
+[mute]
+min_duration = 60
+max_duration = 3600
+```
+
+**新版本Schema (v1.1.0):**
+```python
+config_schema = {
+    "plugin": {
+        "enabled": ConfigField(type=bool, default=False, description="是否启用插件"),
+        "config_version": ConfigField(type=str, default="1.1.0", description="配置文件版本"),
+    },
+    "mute": {
+        "min_duration": ConfigField(type=int, default=60, description="最短禁言时长（秒）"),
+        "max_duration": ConfigField(type=int, default=2592000, description="最长禁言时长（秒）"),
+    },
+    "permissions": {  # 新增的配置节
+        "allowed_users": ConfigField(type=list, default=[], description="允许的用户列表"),
+        "allowed_groups": ConfigField(type=list, default=[], description="允许的群组列表"),
+    }
+}
+```
+
+**迁移后配置 (v1.1.0):**
+```toml
+[plugin]
+enabled = true  # 保留原值
+config_version = "1.1.0"  # 自动更新
+
+[mute]
+min_duration = 60  # 保留原值
+max_duration = 3600  # 保留原值
+
+[permissions]  # 新增节，使用默认值
+allowed_users = []
+allowed_groups = []
+```
+
+#### 无版本配置的兼容性
+
+对于没有版本信息的旧配置文件：
+
+**旧配置文件（无版本）:**
+```toml
+[plugin]
+enabled = true
+# 没有 config_version 字段
+
+[mute]
+min_duration = 120
+```
+
+**系统行为:**
+- 检测到无版本信息
+- 跳过版本检查和迁移
+- 直接加载现有配置
+- 新增的配置项在代码中使用默认值访问
+
+### 📝 配置迁移日志
+
+系统会详细记录配置迁移过程：
+
+```log
+[MutePlugin] 检测到配置版本需要更新: 当前=v1.0.0, 期望=v1.1.0
+[MutePlugin] 生成新配置结构...
+[MutePlugin] 迁移配置值: plugin.enabled = true
+[MutePlugin] 更新配置版本: plugin.config_version = 1.1.0 (旧值: 1.0.0)
+[MutePlugin] 迁移配置值: mute.min_duration = 120
+[MutePlugin] 迁移配置值: mute.max_duration = 3600
+[MutePlugin] 新增节: permissions
+[MutePlugin] 配置文件已从 v1.0.0 更新到 v1.1.0
+```
+
+### ⚠️ 重要注意事项
+
+#### 1. 版本号管理
+- 当你修改 `config_schema` 时，**必须同步更新** `config_version`
+- 建议使用语义化版本号 (例如：`1.0.0`, `1.1.0`, `2.0.0`)
+- 配置结构的重大变更应该增加主版本号
+
+#### 2. 迁移策略
+- **保留原值优先**: 迁移时优先保留用户的原有配置值
+- **新增字段默认值**: 新增的配置项使用Schema中定义的默认值
+- **移除字段警告**: 如果某个配置项在新版本中被移除，会在日志中显示警告
+
+#### 3. 兼容性考虑
+- **旧版本兼容**: 无版本信息的配置文件会跳过版本检查
+- **不保留备份**: 迁移后直接覆盖原配置文件，不保留备份
+- **失败安全**: 如果迁移过程中出现错误，会回退到原配置
+
 ---

 ## 配置定义：Schema驱动的配置系统
--- a/docs/plugins/dependency-management.md
+++ b/docs/plugins/dependency-management.md
@@ -31,8 +31,7 @@ from src.plugin_system import BasePlugin, PythonDependency, register_plugin

@register_plugin
 class MyPlugin(BasePlugin):
-    plugin_name = "my_plugin"
-    plugin_description = "我的示例插件"
+    name = "my_plugin"
    
    # 声明Python包依赖
    python_dependencies = [
@@ -324,14 +323,3 @@ for plugin_name, status in result['plugin_status'].items():
   print("安装日志:", result['install_log'])
   print("失败详情:", result['failed_installs'])
   ```
-
-## 🔗 相关文档
-
- [🚀 快速开始指南](quick-start.md) - 创建你的第一个插件
- [⚡ Action组件详解](action-components.md) - Action开发指南
- [💻 Command组件详解](command-components.md) - Command开发指南
- [📋 开发规范](development-standards.md) - 代码规范和最佳实践
-
---
-
-通过依赖管理系统，你的插件将更加健壮和易于维护。开始使用这些功能让你的插件开发更加高效吧！ 🚀