gardel/Mofox-Core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 添加新的插件和清单管理工具

Browse Source 
- 引入了“hello_world_plugin”和“take_picture_plugin”及其各自的清单文件。
- 实现了“manifest_tool.py”，用于创建、验证和管理插件清单。
- 添加了“test_version_compatibility.py”，用于测试版本规范化、比较和兼容性检查。
- 增强了“manifest_utils.py”，增加了版本比较和验证功能。
This commit is contained in:
墨梓柒
2025-06-19 23:13:06 +08:00
parent 264561144d
commit 1fab6dc710
18 changed files with 1823 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

194
docs/plugins/manifest-guide.md Normal file
View File

@@ -0,0 +1,194 @@
# 📄 插件Manifest系统指南
## 概述
MaiBot插件系统现在强制要求每个插件都必须包含一个 `_manifest.json` 文件。这个文件描述了插件的基本信息、依赖关系、组件等重要元数据。
## 🔧 Manifest文件结构
### 必需字段
以下字段是必需的，不能为空：
```json
{
"manifest_version": 3,
"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`

113
docs/plugins/manifest-implementation-summary.md Normal file
View File

@@ -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": 3,
"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文件
- **✅ 灵活性**：可选字段真正可选，最小化配置负担
- **✅ 可维护性**：完整的验证和错误报告系统
- **✅ 易用性**：命令行工具和详细文档
- **✅ 扩展性**：为未来功能扩展奠定基础
系统已准备就绪，可以开始全面推广使用！🎉

19
plugins/hello_world_plugin/_manifest.json Normal file
View File

@@ -0,0 +1,19 @@
{
"manifest_version": 3,
"name": "hello_world_plugin",
"version": "1.0.0",
"description": "我的第一个MaiCore插件，包含问候功能",
"author": {
"name": "你的名字",
"url": ""
},
"license": "GPL-v3.0-or-later",
"host_application": {
"min_version": "0.8.0",
"max_version": "0.8.0"
},
"keywords": [],
"categories": [],
"default_locale": "zh-CN",
"locales_path": "_locales"
}

19
plugins/take_picture_plugin/_manifest.json Normal file
View File

@@ -0,0 +1,19 @@
{
"manifest_version": 3,
"name": "take_picture_plugin",
"version": "1.0.0",
"description": "提供生成自拍照和展示最近照片的功能",
"author": {
"name": "SengokuCola",
"url": ""
},
"license": "GPL-v3.0-or-later",
"host_application": {
"min_version": "0.8.0",
"max_version": "0.8.0"
},
"keywords": [],
"categories": [],
"default_locale": "zh-CN",
"locales_path": "_locales"
}

257
scripts/manifest_tool.py Normal file
View File

@@ -0,0 +1,257 @@
"""
插件Manifest管理命令行工具
提供插件manifest文件的创建、验证和管理功能
"""
import os
import sys
import argparse
import json
from pathlib import Path
from src.common.logger import get_logger
from src.plugin_system.utils.manifest_utils import (
ManifestValidator,
)
# 添加项目根目录到Python路径
project_root = Path(__file__).parent.parent.parent.parent
sys.path.insert(0, str(project_root))
logger = get_logger("manifest_tool")
def create_minimal_manifest(plugin_dir: str, plugin_name: str, description: str = "", author: str = "") -> bool:
"""创建最小化的manifest文件
Args:
plugin_dir: 插件目录
plugin_name: 插件名称
description: 插件描述
author: 插件作者
Returns:
bool: 是否创建成功
"""
manifest_path = os.path.join(plugin_dir, "_manifest.json")
if os.path.exists(manifest_path):
print(f"❌ Manifest文件已存在: {manifest_path}")
return False
# 创建最小化manifest
minimal_manifest = {
"manifest_version": 3,
"name": plugin_name,
"version": "1.0.0",
"description": description or f"{plugin_name}插件",
"author": {
"name": author or "Unknown"
}
}
try:
with open(manifest_path, "w", encoding="utf-8") as f:
json.dump(minimal_manifest, f, ensure_ascii=False, indent=2)
print(f"✅ 已创建最小化manifest文件: {manifest_path}")
return True
except Exception as e:
print(f"❌ 创建manifest文件失败: {e}")
return False
def create_complete_manifest(plugin_dir: str, plugin_name: str) -> bool:
"""创建完整的manifest模板文件
Args:
plugin_dir: 插件目录
plugin_name: 插件名称
Returns:
bool: 是否创建成功
"""
manifest_path = os.path.join(plugin_dir, "_manifest.json")
if os.path.exists(manifest_path):
print(f"❌ Manifest文件已存在: {manifest_path}")
return False
# 创建完整模板
complete_manifest = {
"manifest_version": 3,
"name": plugin_name,
"version": "1.0.0",
"description": f"{plugin_name}插件描述",
"author": {
"name": "插件作者",
"url": "https://github.com/your-username"
},
"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": ["keyword1", "keyword2"],
"categories": ["Category1"],
"default_locale": "zh-CN",
"locales_path": "_locales",
"plugin_info": {
"is_built_in": False,
"plugin_type": "general",
"components": [
{
"type": "action",
"name": "sample_action",
"description": "示例动作组件"
}
]
}
}
try:
with open(manifest_path, "w", encoding="utf-8") as f:
json.dump(complete_manifest, f, ensure_ascii=False, indent=2)
print(f"✅ 已创建完整manifest模板: {manifest_path}")
print("💡 请根据实际情况修改manifest文件中的内容")
return True
except Exception as e:
print(f"❌ 创建manifest文件失败: {e}")
return False
def validate_manifest_file(plugin_dir: str) -> bool:
"""验证manifest文件
Args:
plugin_dir: 插件目录
Returns:
bool: 是否验证通过
"""
manifest_path = os.path.join(plugin_dir, "_manifest.json")
if not os.path.exists(manifest_path):
print(f"❌ 未找到manifest文件: {manifest_path}")
return False
try:
with open(manifest_path, "r", encoding="utf-8") as f:
manifest_data = json.load(f)
validator = ManifestValidator()
is_valid = validator.validate_manifest(manifest_data)
# 显示验证结果
print("📋 Manifest验证结果:")
print(validator.get_validation_report())
if is_valid:
print("✅ Manifest文件验证通过")
else:
print("❌ Manifest文件验证失败")
return is_valid
except json.JSONDecodeError as e:
print(f"❌ Manifest文件格式错误: {e}")
return False
except Exception as e:
print(f"❌ 验证过程中发生错误: {e}")
return False
def scan_plugins_without_manifest(root_dir: str) -> None:
"""扫描缺少manifest文件的插件
Args:
root_dir: 扫描的根目录
"""
print(f"🔍 扫描目录: {root_dir}")
plugins_without_manifest = []
for root, dirs, files in os.walk(root_dir):
# 跳过隐藏目录和__pycache__
dirs[:] = [d for d in dirs if not d.startswith('.') and d != '__pycache__']
# 检查是否包含plugin.py文件（标识为插件目录）
if "plugin.py" in files:
manifest_path = os.path.join(root, "_manifest.json")
if not os.path.exists(manifest_path):
plugins_without_manifest.append(root)
if plugins_without_manifest:
print(f"❌ 发现 {len(plugins_without_manifest)} 个插件缺少manifest文件:")
for plugin_dir in plugins_without_manifest:
plugin_name = os.path.basename(plugin_dir)
print(f" - {plugin_name}: {plugin_dir}")
print("💡 使用 'python manifest_tool.py create-minimal <插件目录>' 创建manifest文件")
else:
print("✅ 所有插件都有manifest文件")
def main():
"""主函数"""
parser = argparse.ArgumentParser(description="插件Manifest管理工具")
subparsers = parser.add_subparsers(dest="command", help="可用命令")
# 创建最小化manifest命令
create_minimal_parser = subparsers.add_parser("create-minimal", help="创建最小化manifest文件")
create_minimal_parser.add_argument("plugin_dir", help="插件目录路径")
create_minimal_parser.add_argument("--name", help="插件名称")
create_minimal_parser.add_argument("--description", help="插件描述")
create_minimal_parser.add_argument("--author", help="插件作者")
# 创建完整manifest命令
create_complete_parser = subparsers.add_parser("create-complete", help="创建完整manifest模板")
create_complete_parser.add_argument("plugin_dir", help="插件目录路径")
create_complete_parser.add_argument("--name", help="插件名称")
# 验证manifest命令
validate_parser = subparsers.add_parser("validate", help="验证manifest文件")
validate_parser.add_argument("plugin_dir", help="插件目录路径")
# 扫描插件命令
scan_parser = subparsers.add_parser("scan", help="扫描缺少manifest的插件")
scan_parser.add_argument("root_dir", help="扫描的根目录路径")
args = parser.parse_args()
if not args.command:
parser.print_help()
return
try:
if args.command == "create-minimal":
plugin_name = args.name or os.path.basename(os.path.abspath(args.plugin_dir))
success = create_minimal_manifest(
args.plugin_dir,
plugin_name,
args.description or "",
args.author or ""
)
sys.exit(0 if success else 1)
elif args.command == "create-complete":
plugin_name = args.name or os.path.basename(os.path.abspath(args.plugin_dir))
success = create_complete_manifest(args.plugin_dir, plugin_name)
sys.exit(0 if success else 1)
elif args.command == "validate":
success = validate_manifest_file(args.plugin_dir)
sys.exit(0 if success else 1)
elif args.command == "scan":
scan_plugins_without_manifest(args.root_dir)
except Exception as e:
print(f"❌ 执行命令时发生错误: {e}")
sys.exit(1)
if __name__ == "__main__":
main()

237
scripts/test_version_compatibility.py Normal file
View File

@@ -0,0 +1,237 @@
#!/usr/bin/env python3
"""
版本兼容性检查测试脚本
测试版本号标准化、比较和兼容性检查功能
"""
import sys
import os
# 添加项目根目录到Python路径
project_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
sys.path.insert(0, project_root)
from src.plugin_system.utils.manifest_utils import VersionComparator
def test_version_normalization():
"""测试版本号标准化功能"""
print("🧪 测试版本号标准化...")
test_cases = [
("0.8.0-snapshot.1", "0.8.0"),
("0.8.0-snapshot.2", "0.8.0"),
("0.8.0", "0.8.0"),
("0.9.0-snapshot.1", "0.9.0"),
("1.0.0", "1.0.0"),
("2.1", "2.1.0"),
("3", "3.0.0"),
("", "0.0.0"),
("invalid", "0.0.0"),
]
for input_version, expected in test_cases:
result = VersionComparator.normalize_version(input_version)
status = "✅" if result == expected else "❌"
print(f" {status} {input_version} -> {result} (期望: {expected})")
def test_version_comparison():
"""测试版本号比较功能"""
print("\n🧪 测试版本号比较...")
test_cases = [
("0.8.0", "0.9.0", -1), # 0.8.0 < 0.9.0
("0.9.0", "0.8.0", 1), # 0.9.0 > 0.8.0
("1.0.0", "1.0.0", 0), # 1.0.0 == 1.0.0
("0.8.0-snapshot.1", "0.8.0", 0), # 标准化后相等
("1.2.3", "1.2.4", -1), # 1.2.3 < 1.2.4
("2.0.0", "1.9.9", 1), # 2.0.0 > 1.9.9
]
for v1, v2, expected in test_cases:
result = VersionComparator.compare_versions(v1, v2)
status = "✅" if result == expected else "❌"
comparison = "<" if expected == -1 else ">" if expected == 1 else "=="
print(f" {status} {v1} {comparison} {v2} (结果: {result})")
def test_version_range_check():
"""测试版本范围检查功能"""
print("\n🧪 测试版本范围检查...")
test_cases = [
("0.8.0", "0.7.0", "0.9.0", True), # 在范围内
("0.6.0", "0.7.0", "0.9.0", False), # 低于最小版本
("1.0.0", "0.7.0", "0.9.0", False), # 高于最大版本
("0.8.0", "0.8.0", "0.8.0", True), # 等于边界
("0.8.0", "", "0.9.0", True), # 只有最大版本限制
("0.8.0", "0.7.0", "", True), # 只有最小版本限制
("0.8.0", "", "", True), # 无版本限制
]
for version, min_ver, max_ver, expected in test_cases:
is_compatible, error_msg = VersionComparator.is_version_in_range(version, min_ver, max_ver)
status = "✅" if is_compatible == expected else "❌"
range_str = f"[{min_ver or '无限制'}, {max_ver or '无限制'}]"
print(f" {status} {version} 在范围 {range_str}: {is_compatible}")
if error_msg:
print(f" 错误信息: {error_msg}")
def test_current_version():
"""测试获取当前版本功能"""
print("\n🧪 测试获取当前主机版本...")
try:
current_version = VersionComparator.get_current_host_version()
print(f" ✅ 当前主机版本: {current_version}")
# 验证版本号格式
parts = current_version.split('.')
if len(parts) == 3 and all(part.isdigit() for part in parts):
print(f" ✅ 版本号格式正确")
else:
print(f" ❌ 版本号格式错误")
except Exception as e:
print(f" ❌ 获取当前版本失败: {e}")
def test_manifest_compatibility():
"""测试manifest兼容性检查"""
print("\n🧪 测试manifest兼容性检查...")
# 模拟manifest数据
test_manifests = [
{
"name": "兼容插件",
"host_application": {
"min_version": "0.1.0",
"max_version": "2.0.0"
}
},
{
"name": "版本过高插件",
"host_application": {
"min_version": "10.0.0",
"max_version": "20.0.0"
}
},
{
"name": "版本过低插件",
"host_application": {
"min_version": "0.1.0",
"max_version": "0.2.0"
}
},
{
"name": "无版本要求插件",
# 没有host_application字段
}
]
# 这里需要导入PluginManager来测试，但可能会有依赖问题
# 所以我们直接使用VersionComparator进行测试
current_version = VersionComparator.get_current_host_version()
for manifest in test_manifests:
plugin_name = manifest["name"]
if "host_application" in manifest:
host_app = manifest["host_application"]
min_version = host_app.get("min_version", "")
max_version = host_app.get("max_version", "")
is_compatible, error_msg = VersionComparator.is_version_in_range(
current_version, min_version, max_version
)
status = "✅" if is_compatible else "❌"
print(f" {status} {plugin_name}: {is_compatible}")
if error_msg:
print(f" {error_msg}")
else:
print(f" ✅ {plugin_name}: True (无版本要求)")
def test_additional_snapshot_formats():
"""测试额外的snapshot版本格式"""
print("\n🧪 测试额外的snapshot版本格式...")
test_cases = [
# 用户提到的版本格式
("0.8.0-snapshot.1", "0.8.0"),
("0.8.0-snapshot.2", "0.8.0"),
("0.8.0", "0.8.0"),
("0.9.0-snapshot.1", "0.9.0"),
# 边界情况
("1.0.0-snapshot.999", "1.0.0"),
("2.15.3-snapshot.42", "2.15.3"),
("10.5.0-snapshot.1", "10.5.0"),
# 不正确的snapshot格式（应该被忽略或正确处理）
("0.8.0-snapshot", "0.0.0"), # 无数字后缀，应该标准化为0.0.0
("0.8.0-snapshot.abc", "0.0.0"), # 非数字后缀，应该标准化为0.0.0
("0.8.0-beta.1", "0.0.0"), # 其他预发布版本，应该标准化为0.0.0
]
for input_version, expected in test_cases:
result = VersionComparator.normalize_version(input_version)
status = "✅" if result == expected else "❌"
print(f" {status} {input_version} -> {result} (期望: {expected})")
def test_snapshot_version_comparison():
"""测试snapshot版本的比较功能"""
print("\n🧪 测试snapshot版本比较...")
test_cases = [
# snapshot版本与正式版本比较
("0.8.0-snapshot.1", "0.8.0", 0), # 应该相等
("0.8.0-snapshot.2", "0.8.0", 0), # 应该相等
("0.9.0-snapshot.1", "0.8.0", 1), # 应该大于
("0.7.0-snapshot.1", "0.8.0", -1), # 应该小于
# snapshot版本之间比较
("0.8.0-snapshot.1", "0.8.0-snapshot.2", 0), # 都标准化为0.8.0，相等
("0.9.0-snapshot.1", "0.8.0-snapshot.1", 1), # 0.9.0 > 0.8.0
# 边界情况
("1.0.0-snapshot.1", "0.9.9", 1), # 主版本更高
("0.9.0-snapshot.1", "0.8.99", 1), # 次版本更高
]
for version1, version2, expected in test_cases:
result = VersionComparator.compare_versions(version1, version2)
status = "✅" if result == expected else "❌"
comparison = "<" if expected < 0 else "==" if expected == 0 else ">"
print(f" {status} {version1} {comparison} {version2} (结果: {result})")
def main():
"""主函数"""
print("🔧 MaiBot插件版本兼容性检查测试")
print("=" * 50)
try:
test_version_normalization()
test_version_comparison()
test_version_range_check()
test_current_version()
test_manifest_compatibility()
test_additional_snapshot_formats()
test_snapshot_version_comparison()
print("\n🎉 所有测试完成！")
except Exception as e:
print(f"\n❌ 测试过程中发生错误: {e}")
import traceback
traceback.print_exc()
sys.exit(1)
if __name__ == "__main__":
main()

15
src/plugin_system/__init__.py
View File

@@ -23,13 +23,21 @@ from src.plugin_system.core.plugin_manager import plugin_manager
from src.plugin_system.core.component_registry import component_registry
from src.plugin_system.core.dependency_manager import dependency_manager
# 导入工具模块
from src.plugin_system.utils import (
ManifestValidator,
ManifestGenerator,
validate_plugin_manifest,
generate_plugin_manifest
)
__version__ = "1.0.0"
__all__ = [
# 基础类
"BasePlugin",
"BaseAction",
"BaseAction",
"BaseCommand",
# 类型定义
"ComponentType",
@@ -47,4 +55,9 @@ __all__ = [
# 装饰器
"register_plugin",
"ConfigField",
# 工具函数
"ManifestValidator",
"ManifestGenerator",
"validate_plugin_manifest",
"generate_plugin_manifest",
]

158
src/plugin_system/base/base_plugin.py
View File

@@ -3,6 +3,7 @@ from typing import Dict, List, Type, Optional, Any, Union
import os
import inspect
import toml
import json
from src.common.logger import get_logger
from src.plugin_system.base.component_types import (
PluginInfo,
@@ -37,6 +38,10 @@ class BasePlugin(ABC):
python_dependencies: List[PythonDependency] = [] # Python包依赖
config_file_name: Optional[str] = None # 配置文件名
# 新增：manifest文件相关
manifest_file_name: str = "_manifest.json" # manifest文件名
manifest_data: Dict[str, Any] = {} # manifest数据
# 新增：配置定义
config_schema: Dict[str, Union[Dict[str, ConfigField], str]] = {}
config_section_descriptions: Dict[str, str] = {}
@@ -51,13 +56,14 @@ class BasePlugin(ABC):
self.plugin_dir = plugin_dir # 插件目录路径
self.log_prefix = f"[Plugin:{self.plugin_name}]"
# 加载manifest文件
self._load_manifest()
# 验证插件信息
self._validate_plugin_info()
# 加载插件配置
self._load_plugin_config()
# 创建插件信息对象
self._load_plugin_config() # 创建插件信息对象
self.plugin_info = PluginInfo(
name=self.plugin_name,
description=self.plugin_description,
@@ -68,17 +74,161 @@ class BasePlugin(ABC):
config_file=self.config_file_name or "",
dependencies=self.dependencies.copy(),
python_dependencies=self.python_dependencies.copy(),
# 新增：manifest相关信息
manifest_data=self.manifest_data.copy(),
license=self.get_manifest_info("license", ""),
homepage_url=self.get_manifest_info("homepage_url", ""),
repository_url=self.get_manifest_info("repository_url", ""),
keywords=self.get_manifest_info("keywords", []).copy() if self.get_manifest_info("keywords") else [],
categories=self.get_manifest_info("categories", []).copy() if self.get_manifest_info("categories") else [],
min_host_version=self.get_manifest_info("host_application.min_version", ""),
max_host_version=self.get_manifest_info("host_application.max_version", ""),
)
logger.debug(f"{self.log_prefix} 插件基类初始化完成")
def _validate_plugin_info(self):
"""验证插件基本信息"""
"""验证插件基本信息"""
if not self.plugin_name:
raise ValueError(f"插件类 {self.__class__.__name__} 必须定义 plugin_name")
if not self.plugin_description:
raise ValueError(f"插件 {self.plugin_name} 必须定义 plugin_description")
def _load_manifest(self):
"""加载manifest文件（强制要求）"""
if not self.plugin_dir:
raise ValueError(f"{self.log_prefix} 没有插件目录路径，无法加载manifest")
manifest_path = os.path.join(self.plugin_dir, self.manifest_file_name)
if not os.path.exists(manifest_path):
error_msg = f"{self.log_prefix} 缺少必需的manifest文件: {manifest_path}"
logger.error(error_msg)
raise FileNotFoundError(error_msg)
try:
with open(manifest_path, "r", encoding="utf-8") as f:
self.manifest_data = json.load(f)
logger.debug(f"{self.log_prefix} 成功加载manifest文件: {manifest_path}")
# 验证manifest格式
self._validate_manifest()
# 从manifest覆盖插件基本信息（如果插件类中未定义）
self._apply_manifest_overrides()
except json.JSONDecodeError as e:
error_msg = f"{self.log_prefix} manifest文件格式错误: {e}"
logger.error(error_msg)
raise ValueError(error_msg) #noqa
except IOError as e:
error_msg = f"{self.log_prefix} 读取manifest文件失败: {e}"
logger.error(error_msg)
raise IOError(error_msg) #noqa
def _apply_manifest_overrides(self):
"""从manifest文件覆盖插件信息"""
if not self.manifest_data:
return
# 如果插件类中的信息为空，则从manifest中获取
if not self.plugin_name:
self.plugin_name = self.manifest_data.get("name", "")
if not self.plugin_description:
self.plugin_description = self.manifest_data.get("description", "")
if self.plugin_version == "1.0.0": # 默认版本
self.plugin_version = self.manifest_data.get("version", "1.0.0")
if not self.plugin_author:
author_info = self.manifest_data.get("author", {})
if isinstance(author_info, dict):
self.plugin_author = author_info.get("name", "")
else:
self.plugin_author = str(author_info)
def _validate_manifest(self):
"""验证manifest文件格式（使用强化的验证器）"""
if not self.manifest_data:
return
# 导入验证器
from src.plugin_system.utils.manifest_utils import ManifestValidator
validator = ManifestValidator()
is_valid = validator.validate_manifest(self.manifest_data)
# 记录验证结果
if validator.validation_errors or validator.validation_warnings:
report = validator.get_validation_report()
logger.info(f"{self.log_prefix} Manifest验证结果:\n{report}")
# 如果有验证错误，抛出异常
if not is_valid:
error_msg = f"{self.log_prefix} Manifest文件验证失败"
if validator.validation_errors:
error_msg += f": {'; '.join(validator.validation_errors)}"
raise ValueError(error_msg)
def _generate_default_manifest(self, manifest_path: str):
"""生成默认的manifest文件"""
if not self.plugin_name:
logger.debug(f"{self.log_prefix} 插件名称未定义，无法生成默认manifest")
return
default_manifest = {
"manifest_version": 3,
"name": self.plugin_name,
"version": self.plugin_version,
"description": self.plugin_description or "插件描述",
"author": {
"name": self.plugin_author or "Unknown",
"url": ""
},
"license": "MIT",
"host_application": {
"min_version": "1.0.0",
"max_version": "4.0.0"
},
"keywords": [],
"categories": [],
"default_locale": "zh-CN",
"locales_path": "_locales"
}
try:
with open(manifest_path, "w", encoding="utf-8") as f:
json.dump(default_manifest, f, ensure_ascii=False, indent=2)
logger.info(f"{self.log_prefix} 已生成默认manifest文件: {manifest_path}")
except IOError as e:
logger.error(f"{self.log_prefix} 保存默认manifest文件失败: {e}")
def get_manifest_info(self, key: str, default: Any = None) -> Any:
"""获取manifest信息
Args:
key: 信息键，支持点分割的嵌套键（如 "author.name"）
default: 默认值
Returns:
Any: 对应的值
"""
if not self.manifest_data:
return default
keys = key.split(".")
value = self.manifest_data
for k in keys:
if isinstance(value, dict) and k in value:
value = value[k]
else:
return default
return value
def _generate_and_save_default_config(self, config_file_path: str):
"""根据插件的Schema生成并保存默认配置文件"""
if not self.config_schema:

15
src/plugin_system/base/component_types.py
View File

@@ -131,6 +131,15 @@ class PluginInfo:
python_dependencies: List[PythonDependency] = None # Python包依赖
config_file: str = "" # 配置文件路径
metadata: Dict[str, Any] = None # 额外元数据
# 新增：manifest相关信息
manifest_data: Dict[str, Any] = None # manifest文件数据
license: str = "" # 插件许可证
homepage_url: str = "" # 插件主页
repository_url: str = "" # 插件仓库地址
keywords: List[str] = None # 插件关键词
categories: List[str] = None # 插件分类
min_host_version: str = "" # 最低主机版本要求
max_host_version: str = "" # 最高主机版本要求
def __post_init__(self):
if self.components is None:
@@ -141,6 +150,12 @@ class PluginInfo:
self.python_dependencies = []
if self.metadata is None:
self.metadata = {}
if self.manifest_data is None:
self.manifest_data = {}
if self.keywords is None:
self.keywords = []
if self.categories is None:
self.categories = []
def get_missing_packages(self) -> List[PythonDependency]:
"""检查缺失的Python包"""

175
src/plugin_system/core/plugin_manager.py
View File

@@ -1,4 +1,4 @@
from typing import Dict, List, Optional, Any, TYPE_CHECKING
from typing import Dict, List, Optional, Any, TYPE_CHECKING, Tuple
import os
import importlib
import importlib.util
@@ -76,51 +76,92 @@ class PluginManager:
logger.debug(f"插件模块加载完成 - 成功: {total_loaded_modules}, 失败: {total_failed_modules}")
# 第二阶段：实例化所有已注册的插件类
from src.plugin_system.base.base_plugin import get_registered_plugin_classes
from src.plugin_system.base.base_plugin import get_registered_plugin_classes
plugin_classes = get_registered_plugin_classes()
total_registered = 0
total_failed_registration = 0
for plugin_name, plugin_class in plugin_classes.items():
# 使用记录的插件目录路径
plugin_dir = self.plugin_paths.get(plugin_name)
try:
# 使用记录的插件目录路径
plugin_dir = self.plugin_paths.get(plugin_name)
# 如果没有记录，则尝试查找（fallback）
if not plugin_dir:
plugin_dir = self._find_plugin_directory(plugin_class)
if plugin_dir:
self.plugin_paths[plugin_name] = plugin_dir
# 如果没有记录，则尝试查找（fallback）
if not plugin_dir:
plugin_dir = self._find_plugin_directory(plugin_class)
if plugin_dir:
self.plugin_paths[plugin_name] = plugin_dir # 实例化插件（可能因为缺少manifest而失败）
plugin_instance = plugin_class(plugin_dir=plugin_dir)
plugin_instance = plugin_class(plugin_dir=plugin_dir)
# 检查插件是否启用
if not plugin_instance.enable_plugin:
logger.info(f"插件 {plugin_name} 已禁用，跳过加载")
continue
# 检查插件是否启用
if not plugin_instance.enable_plugin:
logger.info(f"插件 {plugin_name} 已禁用，跳过加载")
continue
# 检查版本兼容性
is_compatible, compatibility_error = self.check_plugin_version_compatibility(
plugin_name, plugin_instance.manifest_data
)
if not is_compatible:
total_failed_registration += 1
self.failed_plugins[plugin_name] = compatibility_error
logger.error(f"❌ 插件加载失败: {plugin_name} - {compatibility_error}")
continue
if plugin_instance.register_plugin():
total_registered += 1
self.loaded_plugins[plugin_name] = plugin_instance
if plugin_instance.register_plugin():
total_registered += 1
self.loaded_plugins[plugin_name] = plugin_instance
# 📊 显示插件详细信息
plugin_info = component_registry.get_plugin_info(plugin_name)
if plugin_info:
component_types = {}
for comp in plugin_info.components:
comp_type = comp.component_type.name
component_types[comp_type] = component_types.get(comp_type, 0) + 1
# 📊 显示插件详细信息
plugin_info = component_registry.get_plugin_info(plugin_name)
if plugin_info:
component_types = {}
for comp in plugin_info.components:
comp_type = comp.component_type.name
component_types[comp_type] = component_types.get(comp_type, 0) + 1
components_str = ", ".join([f"{count}个{ctype}" for ctype, count in component_types.items()])
logger.info(
f"✅ 插件加载成功: {plugin_name} v{plugin_info.version} ({components_str}) - {plugin_info.description}"
)
components_str = ", ".join([f"{count}个{ctype}" for ctype, count in component_types.items()])
# 显示manifest信息
manifest_info = ""
if plugin_info.license:
manifest_info += f" [{plugin_info.license}]"
if plugin_info.keywords:
manifest_info += f" 关键词: {', '.join(plugin_info.keywords[:3])}" # 只显示前3个关键词
if len(plugin_info.keywords) > 3:
manifest_info += "..."
logger.info(
f"✅ 插件加载成功: {plugin_name} v{plugin_info.version} ({components_str}){manifest_info} - {plugin_info.description}"
)
else:
logger.info(f"✅ 插件加载成功: {plugin_name}")
else:
logger.info(f"✅ 插件加载成功: {plugin_name}")
else:
total_failed_registration += 1
self.failed_plugins[plugin_name] = "插件注册失败"
logger.error(f"❌ 插件注册失败: {plugin_name}")
except FileNotFoundError as e:
# manifest文件缺失
total_failed_registration += 1
self.failed_plugins[plugin_name] = "插件注册失败"
logger.error(f"❌ 插件加载失败: {plugin_name}")
error_msg = f"缺少manifest文件: {str(e)}"
self.failed_plugins[plugin_name] = error_msg
logger.error(f"❌ 插件加载失败: {plugin_name} - {error_msg}")
except ValueError as e:
# manifest文件格式错误或验证失败
total_failed_registration += 1
error_msg = f"manifest验证失败: {str(e)}"
self.failed_plugins[plugin_name] = error_msg
logger.error(f"❌ 插件加载失败: {plugin_name} - {error_msg}")
except Exception as e:
# 其他错误
total_failed_registration += 1
error_msg = f"未知错误: {str(e)}"
self.failed_plugins[plugin_name] = error_msg
logger.error(f"❌ 插件加载失败: {plugin_name} - {error_msg}")
logger.debug("详细错误信息: ", exc_info=True)
# 获取组件统计信息
stats = component_registry.get_registry_stats()
@@ -136,19 +177,28 @@ class PluginManager:
f"📊 总览: {total_registered}个插件, {total_components}个组件 (Action: {action_count}, Command: {command_count})"
)
# 显示详细的插件列表
logger.info("📋 已加载插件详情:")
# 显示详细的插件列表 logger.info("📋 已加载插件详情:")
for plugin_name, _plugin_class in self.loaded_plugins.items():
plugin_info = component_registry.get_plugin_info(plugin_name)
if plugin_info:
# 插件基本信息
version_info = f"v{plugin_info.version}" if plugin_info.version else ""
author_info = f"by {plugin_info.author}" if plugin_info.author else "unknown"
info_parts = [part for part in [version_info, author_info] if part]
license_info = f"[{plugin_info.license}]" if plugin_info.license else ""
info_parts = [part for part in [version_info, author_info, license_info] if part]
extra_info = f" ({', '.join(info_parts)})" if info_parts else ""
logger.info(f" 📦 {plugin_name}{extra_info}")
# Manifest信息
if plugin_info.manifest_data:
if plugin_info.keywords:
logger.info(f" 🏷️ 关键词: {', '.join(plugin_info.keywords)}")
if plugin_info.categories:
logger.info(f" 📁 分类: {', '.join(plugin_info.categories)}")
if plugin_info.homepage_url:
logger.info(f" 🌐 主页: {plugin_info.homepage_url}")
# 组件列表
if plugin_info.components:
action_components = [c for c in plugin_info.components if c.component_type.name == "ACTION"]
@@ -162,6 +212,18 @@ class PluginManager:
command_names = [c.name for c in command_components]
logger.info(f" ⚡ Command组件: {', '.join(command_names)}")
# 版本兼容性信息
if plugin_info.min_host_version or plugin_info.max_host_version:
version_range = ""
if plugin_info.min_host_version:
version_range += f">={plugin_info.min_host_version}"
if plugin_info.max_host_version:
if version_range:
version_range += f", <={plugin_info.max_host_version}"
else:
version_range += f"<={plugin_info.max_host_version}"
logger.info(f" 📋 兼容版本: {version_range}")
# 依赖信息
if plugin_info.dependencies:
logger.info(f" 🔗 依赖: {', '.join(plugin_info.dependencies)}")
@@ -453,6 +515,47 @@ class PluginManager:
return dependency_manager.generate_requirements_file(all_dependencies, output_path)
def check_plugin_version_compatibility(self, plugin_name: str, manifest_data: Dict[str, Any]) -> Tuple[bool, str]:
"""检查插件版本兼容性
Args:
plugin_name: 插件名称
manifest_data: manifest数据
Returns:
Tuple[bool, str]: (是否兼容, 错误信息)
"""
if "host_application" not in manifest_data:
# 没有版本要求，默认兼容
return True, ""
host_app = manifest_data["host_application"]
if not isinstance(host_app, dict):
return True, ""
min_version = host_app.get("min_version", "")
max_version = host_app.get("max_version", "")
if not min_version and not max_version:
return True, ""
try:
from src.plugin_system.utils.manifest_utils import VersionComparator
current_version = VersionComparator.get_current_host_version()
is_compatible, error_msg = VersionComparator.is_version_in_range(
current_version, min_version, max_version
)
if not is_compatible:
return False, f"版本不兼容: {error_msg}"
else:
logger.debug(f"插件 {plugin_name} 版本兼容性检查通过")
return True, ""
except Exception as e:
logger.warning(f"插件 {plugin_name} 版本兼容性检查失败: {e}")
return True, "" # 检查失败时默认允许加载
# 全局插件管理器实例
plugin_manager = PluginManager()

19
src/plugin_system/utils/__init__.py Normal file
View File

@@ -0,0 +1,19 @@
"""
插件系统工具模块
提供插件开发和管理的实用工具
"""
from src.plugin_system.utils.manifest_utils import (
ManifestValidator,
ManifestGenerator,
validate_plugin_manifest,
generate_plugin_manifest
)
__all__ = [
"ManifestValidator",
"ManifestGenerator",
"validate_plugin_manifest",
"generate_plugin_manifest"
]

459
src/plugin_system/utils/manifest_utils.py Normal file
View File

@@ -0,0 +1,459 @@
"""
插件Manifest工具模块
提供manifest文件的验证、生成和管理功能
"""
import json
import os
import re
from typing import Dict, Any, Optional, Tuple, List
from src.common.logger import get_logger
from src.config.config import MMC_VERSION
logger = get_logger("manifest_utils")
class VersionComparator:
"""版本号比较器
支持语义化版本号比较，自动处理snapshot版本
"""
@staticmethod
def normalize_version(version: str) -> str:
"""标准化版本号，移除snapshot标识
Args:
version: 原始版本号，如 "0.8.0-snapshot.1"
Returns:
str: 标准化后的版本号，如 "0.8.0"
"""
if not version:
return "0.0.0"
# 移除snapshot部分
normalized = re.sub(r'-snapshot\.\d+', '', version.strip())
# 确保版本号格式正确
if not re.match(r'^\d+(\.\d+){0,2}$', normalized):
# 如果不是有效的版本号格式，返回默认版本
return "0.0.0"
# 尝试补全版本号
parts = normalized.split('.')
while len(parts) < 3:
parts.append('0')
normalized = '.'.join(parts[:3])
return normalized
@staticmethod
def parse_version(version: str) -> Tuple[int, int, int]:
"""解析版本号为元组
Args:
version: 版本号字符串
Returns:
Tuple[int, int, int]: (major, minor, patch)
"""
normalized = VersionComparator.normalize_version(version)
try:
parts = normalized.split('.')
return (int(parts[0]), int(parts[1]), int(parts[2]))
except (ValueError, IndexError):
logger.warning(f"无法解析版本号: {version}，使用默认版本 0.0.0")
return (0, 0, 0)
@staticmethod
def compare_versions(version1: str, version2: str) -> int:
"""比较两个版本号
Args:
version1: 第一个版本号
version2: 第二个版本号
Returns:
int: -1 if version1 < version2, 0 if equal, 1 if version1 > version2
"""
v1_tuple = VersionComparator.parse_version(version1)
v2_tuple = VersionComparator.parse_version(version2)
if v1_tuple < v2_tuple:
return -1
elif v1_tuple > v2_tuple:
return 1
else:
return 0
@staticmethod
def is_version_in_range(version: str, min_version: str = "", max_version: str = "") -> Tuple[bool, str]:
"""检查版本是否在指定范围内
Args:
version: 要检查的版本号
min_version: 最小版本号（可选）
max_version: 最大版本号（可选）
Returns:
Tuple[bool, str]: (是否兼容, 错误信息)
"""
if not min_version and not max_version:
return True, ""
version_normalized = VersionComparator.normalize_version(version)
# 检查最小版本
if min_version:
min_normalized = VersionComparator.normalize_version(min_version)
if VersionComparator.compare_versions(version_normalized, min_normalized) < 0:
return False, f"版本 {version_normalized} 低于最小要求版本 {min_normalized}"
# 检查最大版本
if max_version:
max_normalized = VersionComparator.normalize_version(max_version)
if VersionComparator.compare_versions(version_normalized, max_normalized) > 0:
return False, f"版本 {version_normalized} 高于最大支持版本 {max_normalized}"
return True, ""
@staticmethod
def get_current_host_version() -> str:
"""获取当前主机应用版本
Returns:
str: 当前版本号
"""
return VersionComparator.normalize_version(MMC_VERSION)
class ManifestValidator:
"""Manifest文件验证器"""
# 必需字段（必须存在且不能为空）
REQUIRED_FIELDS = [
"manifest_version",
"name",
"version",
"description",
"author"
]
# 可选字段（可以不存在或为空）
OPTIONAL_FIELDS = [
"license",
"host_application",
"homepage_url",
"repository_url",
"keywords",
"categories",
"default_locale",
"locales_path",
"plugin_info"
]
# 建议填写的字段（会给出警告但不会导致验证失败）
RECOMMENDED_FIELDS = [
"license",
"keywords",
"categories"
]
SUPPORTED_MANIFEST_VERSIONS = [3]
def __init__(self):
self.validation_errors = []
self.validation_warnings = []
def validate_manifest(self, manifest_data: Dict[str, Any]) -> bool:
"""验证manifest数据
Args:
manifest_data: manifest数据字典
Returns:
bool: 是否验证通过（只有错误会导致验证失败，警告不会）
"""
self.validation_errors.clear()
self.validation_warnings.clear()
# 检查必需字段
for field in self.REQUIRED_FIELDS:
if field not in manifest_data:
self.validation_errors.append(f"缺少必需字段: {field}")
elif not manifest_data[field]:
self.validation_errors.append(f"必需字段不能为空: {field}")
# 检查manifest版本
if "manifest_version" in manifest_data:
version = manifest_data["manifest_version"]
if version not in self.SUPPORTED_MANIFEST_VERSIONS:
self.validation_errors.append(f"不支持的manifest版本: {version}，支持的版本: {self.SUPPORTED_MANIFEST_VERSIONS}")
# 检查作者信息格式
if "author" in manifest_data:
author = manifest_data["author"]
if isinstance(author, dict):
if "name" not in author or not author["name"]:
self.validation_errors.append("作者信息缺少name字段或为空")
# url字段是可选的
if "url" in author and author["url"]:
url = author["url"]
if not (url.startswith("http://") or url.startswith("https://")):
self.validation_warnings.append("作者URL建议使用完整的URL格式")
elif isinstance(author, str):
if not author.strip():
self.validation_errors.append("作者信息不能为空")
else:
self.validation_errors.append("作者信息格式错误，应为字符串或包含name字段的对象")
# 检查主机应用版本要求（可选）
if "host_application" in manifest_data:
host_app = manifest_data["host_application"]
if isinstance(host_app, dict):
min_version = host_app.get("min_version", "")
max_version = host_app.get("max_version", "")
# 验证版本字段格式
for version_field in ["min_version", "max_version"]:
if version_field in host_app and not host_app[version_field]:
self.validation_warnings.append(f"host_application.{version_field}为空")
# 检查当前主机版本兼容性
if min_version or max_version:
current_version = VersionComparator.get_current_host_version()
is_compatible, error_msg = VersionComparator.is_version_in_range(
current_version, min_version, max_version
)
if not is_compatible:
self.validation_errors.append(f"版本兼容性检查失败: {error_msg} (当前版本: {current_version})")
else:
logger.debug(f"版本兼容性检查通过: 当前版本 {current_version} 符合要求 [{min_version}, {max_version}]")
else:
self.validation_errors.append("host_application格式错误，应为对象")
# 检查URL格式（可选字段）
for url_field in ["homepage_url", "repository_url"]:
if url_field in manifest_data and manifest_data[url_field]:
url = manifest_data[url_field]
if not (url.startswith("http://") or url.startswith("https://")):
self.validation_warnings.append(f"{url_field}建议使用完整的URL格式")
# 检查数组字段格式（可选字段）
for list_field in ["keywords", "categories"]:
if list_field in manifest_data:
field_value = manifest_data[list_field]
if field_value is not None and not isinstance(field_value, list):
self.validation_errors.append(f"{list_field}应为数组格式")
elif isinstance(field_value, list):
# 检查数组元素是否为字符串
for i, item in enumerate(field_value):
if not isinstance(item, str):
self.validation_warnings.append(f"{list_field}[{i}]应为字符串")
# 检查建议字段（给出警告）
for field in self.RECOMMENDED_FIELDS:
if field not in manifest_data or not manifest_data[field]:
self.validation_warnings.append(f"建议填写字段: {field}")
# 检查plugin_info结构（可选）
if "plugin_info" in manifest_data:
plugin_info = manifest_data["plugin_info"]
if isinstance(plugin_info, dict):
# 检查components数组
if "components" in plugin_info:
components = plugin_info["components"]
if not isinstance(components, list):
self.validation_errors.append("plugin_info.components应为数组格式")
else:
for i, component in enumerate(components):
if not isinstance(component, dict):
self.validation_errors.append(f"plugin_info.components[{i}]应为对象")
else:
# 检查组件必需字段
for comp_field in ["type", "name", "description"]:
if comp_field not in component or not component[comp_field]:
self.validation_errors.append(f"plugin_info.components[{i}]缺少必需字段: {comp_field}")
else:
self.validation_errors.append("plugin_info应为对象格式")
return len(self.validation_errors) == 0
def get_validation_report(self) -> str:
"""获取验证报告"""
report = []
if self.validation_errors:
report.append("❌ 验证错误:")
for error in self.validation_errors:
report.append(f" - {error}")
if self.validation_warnings:
report.append("⚠️ 验证警告:")
for warning in self.validation_warnings:
report.append(f" - {warning}")
if not self.validation_errors and not self.validation_warnings:
report.append("✅ Manifest文件验证通过")
return "\n".join(report)
class ManifestGenerator:
"""Manifest文件生成器"""
def __init__(self):
self.template = {
"manifest_version": 3,
"name": "",
"version": "1.0.0",
"description": "",
"author": {
"name": "",
"url": ""
},
"license": "MIT",
"host_application": {
"min_version": "1.0.0",
"max_version": "4.0.0"
},
"homepage_url": "",
"repository_url": "",
"keywords": [],
"categories": [],
"default_locale": "zh-CN",
"locales_path": "_locales"
}
def generate_from_plugin(self, plugin_instance) -> Dict[str, Any]:
"""从插件实例生成manifest
Args:
plugin_instance: BasePlugin实例
Returns:
Dict[str, Any]: 生成的manifest数据
"""
manifest = self.template.copy()
# 基本信息
manifest["name"] = plugin_instance.plugin_name
manifest["version"] = plugin_instance.plugin_version
manifest["description"] = plugin_instance.plugin_description
# 作者信息
if plugin_instance.plugin_author:
manifest["author"]["name"] = plugin_instance.plugin_author
# 组件信息
components = []
plugin_components = plugin_instance.get_plugin_components()
for component_info, component_class in plugin_components:
component_data = {
"type": component_info.component_type.value,
"name": component_info.name,
"description": component_info.description
}
# 添加激活模式信息（对于Action组件）
if hasattr(component_class, 'focus_activation_type'):
activation_modes = []
if hasattr(component_class, 'focus_activation_type'):
activation_modes.append(component_class.focus_activation_type.value)
if hasattr(component_class, 'normal_activation_type'):
activation_modes.append(component_class.normal_activation_type.value)
component_data["activation_modes"] = list(set(activation_modes))
# 添加关键词信息
if hasattr(component_class, 'activation_keywords'):
keywords = getattr(component_class, 'activation_keywords', [])
if keywords:
component_data["keywords"] = keywords
components.append(component_data)
manifest["plugin_info"] = {
"is_built_in": True,
"plugin_type": "general",
"components": components
}
return manifest
def save_manifest(self, manifest_data: Dict[str, Any], plugin_dir: str) -> bool:
"""保存manifest文件
Args:
manifest_data: manifest数据
plugin_dir: 插件目录
Returns:
bool: 是否保存成功
"""
try:
manifest_path = os.path.join(plugin_dir, "_manifest.json")
with open(manifest_path, "w", encoding="utf-8") as f:
json.dump(manifest_data, f, ensure_ascii=False, indent=2)
logger.info(f"Manifest文件已保存: {manifest_path}")
return True
except Exception as e:
logger.error(f"保存manifest文件失败: {e}")
return False
def validate_plugin_manifest(plugin_dir: str) -> bool:
"""验证插件目录中的manifest文件
Args:
plugin_dir: 插件目录路径
Returns:
bool: 是否验证通过
"""
manifest_path = os.path.join(plugin_dir, "_manifest.json")
if not os.path.exists(manifest_path):
logger.warning(f"未找到manifest文件: {manifest_path}")
return False
try:
with open(manifest_path, "r", encoding="utf-8") as f:
manifest_data = json.load(f)
validator = ManifestValidator()
is_valid = validator.validate_manifest(manifest_data)
logger.info(f"Manifest验证结果:\n{validator.get_validation_report()}")
return is_valid
except Exception as e:
logger.error(f"读取或验证manifest文件失败: {e}")
return False
def generate_plugin_manifest(plugin_instance, save_to_file: bool = True) -> Optional[Dict[str, Any]]:
"""为插件生成manifest文件
Args:
plugin_instance: BasePlugin实例
save_to_file: 是否保存到文件
Returns:
Optional[Dict[str, Any]]: 生成的manifest数据
"""
try:
generator = ManifestGenerator()
manifest_data = generator.generate_from_plugin(plugin_instance)
if save_to_file and plugin_instance.plugin_dir:
generator.save_manifest(manifest_data, plugin_instance.plugin_dir)
return manifest_data
except Exception as e:
logger.error(f"生成manifest文件失败: {e}")
return None

55
src/plugins/built_in/core_actions/_manifest.json Normal file
View File

@@ -0,0 +1,55 @@
{
"manifest_version": 3,
"name": "核心动作插件 (Core Actions)",
"version": "1.0.0",
"description": "系统核心动作插件，提供基础聊天交互功能，包括回复、不回复、表情包发送和聊天模式切换等核心功能。",
"author": {
"name": "MaiBot团队",
"url": "https://github.com/MaiM-with-u"
},
"license": "GPL-v3.0-or-later",
"host_application": {
"min_version": "0.8.0",
"max_version": "0.8.0"
},
"homepage_url": "https://github.com/MaiM-with-u/maibot",
"repository_url": "https://github.com/MaiM-with-u/maibot",
"keywords": ["core", "chat", "reply", "emoji", "action", "built-in"],
"categories": ["Core System", "Chat Management"],
"default_locale": "zh-CN",
"locales_path": "_locales",
"plugin_info": {
"is_built_in": true,
"plugin_type": "action_provider",
"components": [
{
"type": "action",
"name": "reply",
"description": "参与聊天回复，发送文本进行表达"
},
{
"type": "action",
"name": "no_reply",
"description": "暂时不回复消息，等待新消息或超时"
},
{
"type": "action",
"name": "emoji",
"description": "发送表情包辅助表达情绪"
},
{
"type": "action",
"name": "change_to_focus_chat",
"description": "切换到专注聊天，从普通模式切换到专注模式"
},
{
"type": "action",
"name": "exit_focus_chat",
"description": "退出专注聊天，从专注模式切换到普通模式"
}
]
}
}

4
src/plugins/built_in/core_actions/plugin.py
View File

@@ -340,9 +340,11 @@ class CoreActionsPlugin(BasePlugin):
- Reply: 回复动作
- NoReply: 不回复动作
- Emoji: 表情动作
注意：插件基本信息优先从_manifest.json文件中读取
"""
# 插件基本信息
# 插件基本信息（作为fallback，优先从manifest读取）
plugin_name = "core_actions"
plugin_description = "系统核心动作插件，提供基础聊天交互功能"
plugin_version = "1.0.0"

45
src/plugins/built_in/doubao_pic_plugin/_manifest.json Normal file
View File

@@ -0,0 +1,45 @@
{
"manifest_version": 3,
"name": "豆包图片生成插件 (Doubao Image Generator)",
"version": "1.2.0",
"description": "基于火山引擎豆包模型的AI图片生成插件，支持智能LLM判定、高质量图片生成、结果缓存和多尺寸支持。",
"author": {
"name": "MaiBot团队",
"url": "https://github.com/MaiM-with-u"
},
"license": "GPL-v3.0-or-later",
"host_application": {
"min_version": "0.8.0",
"max_version": "0.8.0"
},
"homepage_url": "https://github.com/MaiM-with-u/maibot",
"repository_url": "https://github.com/MaiM-with-u/maibot",
"keywords": ["ai", "image", "generation", "doubao", "volcengine", "art"],
"categories": ["AI Tools", "Image Processing", "Content Generation"],
"default_locale": "zh-CN",
"locales_path": "_locales",
"plugin_info": {
"is_built_in": true,
"plugin_type": "content_generator",
"api_dependencies": ["volcengine"],
"components": [
{
"type": "action",
"name": "doubao_image_generation",
"description": "根据描述使用火山引擎豆包API生成高质量图片",
"activation_modes": ["llm_judge", "keyword"],
"keywords": ["画", "图片", "生成", "画画", "绘制"]
}
],
"features": [
"智能LLM判定生成时机",
"高质量AI图片生成",
"结果缓存机制",
"多种图片尺寸支持",
"完整的错误处理"
]
}
}

19
src/plugins/built_in/mute_plugin/_manifest.json Normal file
View File

@@ -0,0 +1,19 @@
{
"manifest_version": 3,
"name": "mute_plugin",
"version": "2.0.0",
"description": "群聊禁言管理插件，提供智能禁言功能",
"author": {
"name": "MaiBot开发团队",
"url": ""
},
"license": "GPL-v3.0-or-later",
"host_application": {
"min_version": "0.8.0",
"max_version": "0.8.0"
},
"keywords": [],
"categories": [],
"default_locale": "zh-CN",
"locales_path": "_locales"
}

43
src/plugins/built_in/tts_plugin/_manifest.json Normal file
View File

@@ -0,0 +1,43 @@
{
"manifest_version": 3,
"name": "文本转语音插件 (Text-to-Speech)",
"version": "1.1.0",
"description": "将文本转换为语音进行播放的插件，支持多种语音模式和智能语音输出场景判断。",
"author": {
"name": "MaiBot团队",
"url": "https://github.com/MaiM-with-u"
},
"license": "GPL-v3.0-or-later",
"host_application": {
"min_version": "0.8.0",
"max_version": "0.8.0"
},
"homepage_url": "https://github.com/MaiM-with-u/maibot",
"repository_url": "https://github.com/MaiM-with-u/maibot",
"keywords": ["tts", "voice", "audio", "speech", "accessibility"],
"categories": ["Audio Tools", "Accessibility", "Voice Assistant"],
"default_locale": "zh-CN",
"locales_path": "_locales",
"plugin_info": {
"is_built_in": true,
"plugin_type": "audio_processor",
"components": [
{
"type": "action",
"name": "tts_action",
"description": "将文本转换为语音进行播放",
"activation_modes": ["llm_judge", "keyword"],
"keywords": ["语音", "tts", "播报", "读出来", "语音播放", "听", "朗读"]
}
],
"features": [
"文本转语音播放",
"智能场景判断",
"关键词触发",
"支持多种语音模式"
]
}
}

19
src/plugins/built_in/vtb_plugin/_manifest.json Normal file
View File

@@ -0,0 +1,19 @@
{
"manifest_version": 3,
"name": "vtb_plugin",
"version": "0.1.0",
"description": "虚拟主播情感表达插件",
"author": {
"name": "MaiBot开发团队",
"url": ""
},
"license": "GPL-v3.0-or-later",
"host_application": {
"min_version": "0.8.0",
"max_version": "0.8.0"
},
"keywords": [],
"categories": [],
"default_locale": "zh-CN",
"locales_path": "_locales"
}