Merge branch 'dev' of https://github.com/MaiM-with-u/MaiBot into dev

2025-06-19 23:23:18 +08:00
parent 43425b3c1f 50657e653e
commit d153887b8a
20 changed files with 1810 additions and 122 deletions
--- a/docs/plugins/manifest-guide.md
+++ b/docs/plugins/manifest-guide.md
@@ -0,0 +1,194 @@
+# 📄 插件Manifest系统指南
+
+## 概述
+
+MaiBot插件系统现在强制要求每个插件都必须包含一个 `_manifest.json` 文件。这个文件描述了插件的基本信息、依赖关系、组件等重要元数据。
+
+## 🔧 Manifest文件结构
+
+### 必需字段
+
+以下字段是必需的，不能为空：
+
+```json
+{
+  "manifest_version": 1,
+  "name": "插件显示名称",
+  "version": "1.0.0",
+  "description": "插件功能描述",
+  "author": {
+    "name": "作者名称"
+  }
+}
+```
+
+### 可选字段
+
+以下字段都是可选的，可以根据需要添加：
+
+```json
+{
+  "license": "MIT",
+  "host_application": {
+    "min_version": "1.0.0",
+    "max_version": "4.0.0"
+  },
+  "homepage_url": "https://github.com/your-repo",
+  "repository_url": "https://github.com/your-repo",
+  "keywords": ["关键词1", "关键词2"],
+  "categories": ["分类1", "分类2"],
+  "default_locale": "zh-CN",
+  "locales_path": "_locales",
+  "plugin_info": {
+    "is_built_in": false,
+    "plugin_type": "general",
+    "components": [
+      {
+        "type": "action",
+        "name": "组件名称",
+        "description": "组件描述"
+      }
+    ]
+  }
+}
+```
+
+## 🛠️ 管理工具
+
+### 使用manifest_tool.py
+
+我们提供了一个命令行工具来帮助管理manifest文件：
+
+```bash
+# 扫描缺少manifest的插件
+python scripts/manifest_tool.py scan src/plugins
+
+# 为插件创建最小化manifest文件
+python scripts/manifest_tool.py create-minimal src/plugins/my_plugin --name "我的插件" --author "作者"
+
+# 为插件创建完整manifest模板
+python scripts/manifest_tool.py create-complete src/plugins/my_plugin --name "我的插件"
+
+# 验证manifest文件
+python scripts/manifest_tool.py validate src/plugins/my_plugin
+```
+
+### 验证示例
+
+验证通过的示例：
+```
+✅ Manifest文件验证通过
+```
+
+验证失败的示例：
+```
+❌ 验证错误:
+  - 缺少必需字段: name
+  - 作者信息缺少name字段或为空
+⚠️ 验证警告:
+  - 建议填写字段: license
+  - 建议填写字段: keywords
+```
+
+## 🔄 迁移指南
+
+### 对于现有插件
+
+1. **检查缺少manifest的插件**：
+   ```bash
+   python scripts/manifest_tool.py scan src/plugins
+   ```
+
+2. **为每个插件创建manifest**：
+   ```bash
+   python scripts/manifest_tool.py create-minimal src/plugins/your_plugin
+   ```
+
+3. **编辑manifest文件**，填写正确的信息。
+
+4. **验证manifest**：
+   ```bash
+   python scripts/manifest_tool.py validate src/plugins/your_plugin
+   ```
+
+### 对于新插件
+
+创建新插件时，建议的步骤：
+
+1. **创建插件目录和基本文件**
+2. **创建完整manifest模板**：
+   ```bash
+   python scripts/manifest_tool.py create-complete src/plugins/new_plugin
+   ```
+3. **根据实际情况修改manifest文件**
+4. **编写插件代码**
+5. **验证manifest文件**
+
+## 📋 字段说明
+
+### 基本信息
+- `manifest_version`: manifest格式版本，当前为3
+- `name`: 插件显示名称（必需）
+- `version`: 插件版本号（必需）
+- `description`: 插件功能描述（必需）
+- `author`: 作者信息（必需）
+  - `name`: 作者名称（必需）
+  - `url`: 作者主页（可选）
+
+### 许可和URL
+- `license`: 插件许可证（可选，建议填写）
+- `homepage_url`: 插件主页（可选）
+- `repository_url`: 源码仓库地址（可选）
+
+### 分类和标签
+- `keywords`: 关键词数组（可选，建议填写）
+- `categories`: 分类数组（可选，建议填写）
+
+### 兼容性
+- `host_application`: 主机应用兼容性（可选）
+  - `min_version`: 最低兼容版本
+  - `max_version`: 最高兼容版本
+
+### 国际化
+- `default_locale`: 默认语言（可选）
+- `locales_path`: 语言文件目录（可选）
+
+### 插件特定信息
+- `plugin_info`: 插件详细信息（可选）
+  - `is_built_in`: 是否为内置插件
+  - `plugin_type`: 插件类型
+  - `components`: 组件列表
+
+## ⚠️ 注意事项
+
+1. **强制要求**：所有插件必须包含`_manifest.json`文件，否则无法加载
+2. **编码格式**：manifest文件必须使用UTF-8编码
+3. **JSON格式**：文件必须是有效的JSON格式
+4. **必需字段**：`manifest_version`、`name`、`version`、`description`、`author.name`是必需的
+5. **版本兼容**：当前只支持manifest_version = 3
+
+## 🔍 常见问题
+
+### Q: 为什么要强制要求manifest文件？
+A: Manifest文件提供了插件的标准化元数据，使得插件管理、依赖检查、版本兼容性验证等功能成为可能。
+
+### Q: 可以不填写可选字段吗？
+A: 可以。所有标记为"可选"的字段都可以不填写，但建议至少填写`license`和`keywords`。
+
+### Q: 如何快速为所有插件创建manifest？
+A: 可以编写脚本批量处理：
+```bash
+# 扫描并为每个缺少manifest的插件创建最小化manifest
+python scripts/manifest_tool.py scan src/plugins
+# 然后手动为每个插件运行create-minimal命令
+```
+
+### Q: manifest验证失败怎么办？
+A: 根据验证器的错误提示修复相应问题。错误会导致插件加载失败，警告不会。
+
+## 📚 参考示例
+
+查看内置插件的manifest文件作为参考：
+- `src/plugins/built_in/core_actions/_manifest.json`
+- `src/plugins/built_in/doubao_pic_plugin/_manifest.json`
+- `src/plugins/built_in/tts_plugin/_manifest.json`
--- a/docs/plugins/manifest-implementation-summary.md
+++ b/docs/plugins/manifest-implementation-summary.md
@@ -0,0 +1,113 @@
+# ✅ MaiBot插件Manifest系统实现完成
+
+## 🎉 实现成果
+
+### 1. **强制Manifest要求** ✅
+- 修改了`BasePlugin`类，强制要求所有插件必须包含`_manifest.json`文件
+- 插件加载时会验证manifest文件的存在性和格式正确性
+- 缺少manifest或格式错误的插件将无法加载，并显示明确的错误信息
+
+### 2. **完善的验证系统** ✅
+- 实现了`ManifestValidator`类，支持完整的manifest格式验证
+- 区分必需字段和可选字段，只有必需字段错误才会导致加载失败
+- 提供详细的验证报告，包括错误和警告信息
+
+### 3. **可选字段真正可选** ✅
+- 所有示例中标记为可选的字段都可以不填写
+- 必需字段：`manifest_version`、`name`、`version`、`description`、`author.name`
+- 可选字段：`license`、`homepage_url`、`repository_url`、`keywords`、`categories`等
+
+### 4. **管理工具** ✅
+- 创建了`scripts/manifest_tool.py`命令行工具
+- 支持创建最小化manifest、完整模板、验证文件、扫描缺失等功能
+- 提供友好的命令行界面和详细的使用说明
+
+### 5. **内置插件适配** ✅
+- 为所有内置插件创建了符合规范的manifest文件：
+  - `core_actions`: 核心动作插件
+  - `doubao_pic_plugin`: 豆包图片生成插件  
+  - `tts_plugin`: 文本转语音插件
+  - `vtb_plugin`: VTB虚拟主播插件
+  - `mute_plugin`: 静音插件
+  - `take_picture_plugin`: 拍照插件
+
+### 6. **增强的插件信息显示** ✅
+- 插件管理器现在显示更丰富的插件信息
+- 包括许可证、关键词、分类、版本兼容性等manifest信息
+- 更好的错误报告和故障排除信息
+
+### 7. **完整的文档** ✅
+- 创建了详细的manifest系统指南：`docs/plugins/manifest-guide.md`
+- 包含字段说明、使用示例、迁移指南、常见问题等
+- 提供了最佳实践和开发建议
+
+## 📋 核心特性对比
+
+| 特性 | 实现前 | 实现后 |
+|------|--------|--------|
+| **Manifest要求** | 可选 | **强制要求** |
+| **字段验证** | 无 | **完整验证** |
+| **可选字段** | 概念模糊 | **真正可选** |
+| **错误处理** | 基础 | **详细错误信息** |
+| **管理工具** | 无 | **命令行工具** |
+| **文档** | 基础 | **完整指南** |
+
+## 🔧 使用示例
+
+### 最小化Manifest示例
+```json
+{
+  "manifest_version": 1,
+  "name": "我的插件",
+  "version": "1.0.0", 
+  "description": "插件描述",
+  "author": {
+    "name": "作者名称"
+  }
+}
+```
+
+### 验证失败示例
+```bash
+❌ 插件加载失败: my_plugin - 缺少manifest文件: /path/to/plugin/_manifest.json
+❌ 插件加载失败: bad_plugin - manifest验证失败: 缺少必需字段: name
+```
+
+### 成功加载示例
+```bash
+✅ 插件加载成功: core_actions v1.0.0 (5个ACTION) [GPL-v3.0-or-later] 关键词: core, chat, reply... - 系统核心动作插件
+```
+
+## 🚀 下一步建议
+
+### 1. **插件迁移**
+- 使用`manifest_tool.py scan`扫描所有插件目录
+- 为缺少manifest的插件创建文件
+- 逐步完善manifest信息
+
+### 2. **开发者指导**
+- 在插件开发文档中强调manifest的重要性
+- 提供插件开发模板，包含标准manifest
+- 建议在CI/CD中加入manifest验证
+
+### 3. **功能增强**
+- 考虑添加manifest版本迁移工具
+- 支持从manifest自动生成插件文档
+- 添加插件依赖关系验证
+
+### 4. **用户体验**
+- 在插件管理界面显示manifest信息
+- 支持按关键词和分类筛选插件
+- 提供插件兼容性检查
+
+## ✨ 总结
+
+MaiBot插件Manifest系统现已完全实现，提供了：
+
+- **✅ 强制性要求**：所有插件必须有manifest文件
+- **✅ 灵活性**：可选字段真正可选，最小化配置负担
+- **✅ 可维护性**：完整的验证和错误报告系统
+- **✅ 易用性**：命令行工具和详细文档
+- **✅ 扩展性**：为未来功能扩展奠定基础
+
+系统已准备就绪，可以开始全面推广使用！🎉