fix：修改示例插件和vtb插件自动生成config

2025-06-16 22:10:21 +08:00
parent b1b1dda1d6
commit f6215cd560
5 changed files with 333 additions and 0 deletions
--- a/docs/plugins/config-access-guide.md
+++ b/docs/plugins/config-access-guide.md
@@ -1,5 +1,11 @@
 # 🔧 插件配置访问指南

+> **💡 阅读须知**
+>
+> 本文主要介绍如何在插件的 **Action** 或 **Command** 组件中 **访问（读取）** 配置值。
+>
+> 如果你还不了解如何为插件 **定义** 配置并让系统 **自动生成** 带注释的 `config.toml` 文件，请务必先阅读 ➡️ **[⚙️ 插件配置定义指南](configuration-guide.md)**。
+
 ## 问题描述

 在插件开发中，你可能遇到这样的问题：
--- a/docs/plugins/configuration-guide.md
+++ b/docs/plugins/configuration-guide.md
@@ -0,0 +1,202 @@
+# ⚙️ 插件配置定义指南
+
+本文档将指导你如何为你的插件定义一个健壮、规范且自带文档的配置文件。
+
+## 核心理念：Schema驱动的配置
+
+在新版插件系统中，我们引入了一套 **配置Schema（模式）驱动** 的机制。你不再需要手动创建和维护 `config.toml` 文件，而是通过在插件代码中 **声明配置的结构**，系统将为你完成剩下的工作。
+
+**核心优势:**
+
+- **自动化 (Automation)**: 如果配置文件不存在，系统会根据你的声明 **自动生成** 一份包含默认值和详细注释的 `config.toml` 文件。
+- **规范化 (Standardization)**: 所有插件的配置都遵循统一的结构，提升了可维护性。
+- **自带文档 (Self-documenting)**: 配置文件中的每一项都包含详细的注释、类型说明、可选值和示例，极大地降低了用户的使用门槛。
+- **健壮性 (Robustness)**: 在代码中直接定义配置的类型和默认值，减少了因配置错误导致的运行时问题。
+- **易于管理 (Easy Management)**: 生成的配置文件可以方便地加入 `.gitignore`，避免将个人配置（如API Key）提交到版本库。
+
+---
+
+## 如何定义配置
+
+配置的定义在你的插件主类（继承自 `BasePlugin`）中完成，主要通过两个类属性：
+
+1.  `config_section_descriptions`: 一个字典，用于描述配置文件的各个区段（`[section]`）。
+2.  `config_schema`: 核心部分，一个嵌套字典，用于定义每个区段下的具体配置项。
+
+### `ConfigField`：配置项的基石
+
+每个配置项都通过一个 `ConfigField` 对象来定义。
+
+```python
+from src.plugin_system.base.config_types import ConfigField
+
+@dataclass
+class ConfigField:
+    """配置字段定义"""
+    type: type          # 字段类型 (例如 str, int, float, bool, list)
+    default: Any        # 默认值
+    description: str    # 字段描述 (将作为注释生成到配置文件中)
+    example: Optional[str] = None       # 示例值 (可选)
+    required: bool = False              # 是否必需 (可选, 主要用于文档提示)
+    choices: Optional[List[Any]] = None # 可选值列表 (可选)
+```
+
+---
+
+## 完整示例
+
+让我们以一个功能丰富的 `MutePlugin` 为例，看看如何定义它的配置。
+
+### 1. 插件代码 (`plugin.py`)
+
+```python
+# src/plugins/built_in/mute_plugin/plugin.py
+
+# ... 其他导入 ...
+from src.plugin_system import BasePlugin, register_plugin
+from src.plugin_system.base.config_types import ConfigField
+from typing import List, Tuple, Type
+
+@register_plugin
+class MutePlugin(BasePlugin):
+    """禁言插件"""
+
+    # 插件基本信息
+    plugin_name = "mute_plugin"
+    plugin_description = "群聊禁言管理插件，提供智能禁言功能"
+    plugin_version = "2.0.0"
+    plugin_author = "MaiBot开发团队"
+    enable_plugin = True
+    config_file_name = "config.toml"
+
+    # 步骤1: 定义配置节的描述
+    config_section_descriptions = {
+        "plugin": "插件基本信息配置",
+        "components": "组件启用控制",
+        "mute": "核心禁言功能配置",
+        "smart_mute": "智能禁言Action的专属配置",
+        "logging": "日志记录相关配置"
+    }
+
+    # 步骤2: 使用ConfigField定义详细的配置Schema
+    config_schema = {
+        "plugin": {
+            "name": ConfigField(type=str, default="mute_plugin", description="插件名称", required=True),
+            "version": ConfigField(type=str, default="2.0.0", description="插件版本号"),
+            "enabled": ConfigField(type=bool, default=False, description="是否启用插件"),
+            "description": ConfigField(type=str, default="群聊禁言管理插件", description="插件描述", required=True)
+        },
+        "components": {
+            "enable_smart_mute": ConfigField(type=bool, default=True, description="是否启用智能禁言Action"),
+            "enable_mute_command": ConfigField(type=bool, default=False, description="是否启用禁言命令Command")
+        },
+        "mute": {
+            "min_duration": ConfigField(type=int, default=60, description="最短禁言时长（秒）"),
+            "max_duration": ConfigField(type=int, default=2592000, description="最长禁言时长（秒），默认30天"),
+            "templates": ConfigField(
+                type=list,
+                default=["好的，禁言 {target} {duration}，理由：{reason}", "收到，对 {target} 执行禁言 {duration}"],
+                description="成功禁言后发送的随机消息模板"
+            )
+        },
+        "smart_mute": {
+            "keyword_sensitivity": ConfigField(
+                type=str,
+                default="normal",
+                description="关键词激活的敏感度",
+                choices=["low", "normal", "high"] # 定义可选值
+            ),
+        },
+        "logging": {
+            "level": ConfigField(
+                type=str,
+                default="INFO",
+                description="日志记录级别",
+                choices=["DEBUG", "INFO", "WARNING", "ERROR"]
+            ),
+            "prefix": ConfigField(type=str, default="[MutePlugin]", description="日志记录前缀", example="[MyMutePlugin]")
+        }
+    }
+
+    def get_plugin_components(self) -> List[Tuple[ComponentInfo, Type]]:
+        # ... 组件注册逻辑 ...
+        # 在这里可以通过 self.get_config() 来获取配置值
+        pass
+
+```
+
+### 2. 自动生成的配置文件 (`config.toml`)
+
+当 `mute_plugin` 首次加载且其目录中不存在 `config.toml` 时，系统会自动创建以下文件：
+
+```toml
+# mute_plugin - 自动生成的配置文件
+# 群聊禁言管理插件，提供智能禁言功能
+
+# 插件基本信息配置
+[plugin]
+
+# 插件名称 (必需)
+name = "mute_plugin"
+
+# 插件版本号
+version = "2.0.0"
+
+# 是否启用插件
+enabled = false
+
+# 插件描述 (必需)
+description = "群聊禁言管理插件"
+
+
+# 组件启用控制
+[components]
+
+# 是否启用智能禁言Action
+enable_smart_mute = true
+
+# 是否启用禁言命令Command
+enable_mute_command = false
+
+
+# 核心禁言功能配置
+[mute]
+
+# 最短禁言时长（秒）
+min_duration = 60
+
+# 最长禁言时长（秒），默认30天
+max_duration = 2592000
+
+# 成功禁言后发送的随机消息模板
+templates = ["好的，禁言 {target} {duration}，理由：{reason}", "收到，对 {target} 执行禁言 {duration}"]
+
+
+# 智能禁言Action的专属配置
+[smart_mute]
+
+# 关键词激活的敏感度
+# 可选值: low, normal, high
+keyword_sensitivity = "normal"
+
+
+# 日志记录相关配置
+[logging]
+
+# 日志记录级别
+# 可选值: DEBUG, INFO, WARNING, ERROR
+level = "INFO"
+
+# 日志记录前缀
+# 示例: [MyMutePlugin]
+prefix = "[MutePlugin]"
+
+```
+
+## 最佳实践
+
+1.  **定义优于创建**: 始终优先在 `plugin.py` 中定义 `config_schema`，而不是手动创建 `config.toml`。
+2.  **描述清晰**: 为每个 `ConfigField` 和 `config_section_descriptions` 编写清晰、准确的描述。这会直接成为你的插件文档的一部分。
+3.  **提供合理默认值**: 确保你的插件在默认配置下就能正常运行（或处于一个安全禁用的状态）。
+4.  **gitignore**: 将 `plugins/*/config.toml` 或 `src/plugins/built_in/*/config.toml` 加入 `.gitignore`，以避免提交个人敏感信息。
+5.  **访问配置**: 在插件的任何地方，统一使用 `self.api.get_config("section.key", "default_value")` 来安全地获取配置值。详细请参考 [**插件配置访问指南**](config-access-guide.md)。 
--- a/docs/plugins/quick-start.md
+++ b/docs/plugins/quick-start.md
@@ -1,5 +1,13 @@
 # 🚀 快速开始指南

+本指南将带你用5分钟时间，从零开始创建一个功能完整的MaiBot插件。
+
+> **💡 配置先行**
+>
+> 在开始之前，强烈建议你先阅读 ➡️ **[⚙️ 插件配置定义指南](configuration-guide.md)**。
+>
+> 了解如何通过 `config_schema` 定义插件配置，可以让系统为你自动生成带详细注释的 `config.toml` 文件，这是现代插件开发的最佳实践。
+
 ## 📖 概述

 这个指南将带你在5分钟内创建你的第一个MaiBot插件。我们将创建一个简单的问候插件，展示插件系统的基本概念。