# 📦 依赖管理完整示例 > 这个示例展示了如何在插件中正确使用Python依赖管理功能。 ## 🎯 示例插件：智能数据分析插件 这个插件展示了如何处理必需依赖、可选依赖，以及优雅降级处理。 ```python """ 智能数据分析插件 展示依赖管理的完整用法 """ from src.plugin_system import ( BasePlugin, BaseAction, register_plugin, ActionInfo, PythonDependency, ActionActivationType ) from src.common.logger import get_logger logger = get_logger("data_analysis_plugin") @register_plugin class DataAnalysisPlugin(BasePlugin): """智能数据分析插件""" plugin_name = "data_analysis_plugin" plugin_description = "提供数据分析和可视化功能的示例插件" plugin_version = "1.0.0" plugin_author = "MaiBot Team" # 声明Python包依赖 python_dependencies = [ # 必需依赖 - 核心功能 PythonDependency( package_name="requests", version=">=2.25.0", description="HTTP库，用于获取外部数据" ), # 可选依赖 - 数据处理 PythonDependency( package_name="pandas", version=">=1.3.0", optional=True, description="数据处理库，提供高级数据操作功能" ), # 可选依赖 - 数值计算 PythonDependency( package_name="numpy", version=">=1.20.0", optional=True, description="数值计算库，用于数学运算" ), # 可选依赖 - 数据可视化 PythonDependency( package_name="matplotlib", version=">=3.3.0", optional=True, description="绘图库，用于生成数据图表" ), # 特殊情况：导入名与安装名不同 PythonDependency( package_name="PIL", install_name="Pillow", version=">=8.0.0", optional=True, description="图像处理库，用于图表保存和处理" ), ] def get_plugin_components(self): """返回插件组件""" return [ # 基础数据获取（只依赖requests） (ActionInfo( name="fetch_data_action", description="获取外部数据", focus_activation_type=ActionActivationType.KEYWORD, normal_activation_type=ActionActivationType.KEYWORD, activation_keywords=["获取数据", "下载数据"], ), FetchDataAction), # 数据分析（依赖pandas和numpy） (ActionInfo( name="analyze_data_action", description="数据分析和统计", focus_activation_type=ActionActivationType.KEYWORD, normal_activation_type=ActionActivationType.KEYWORD, activation_keywords=["分析数据", "数据统计"], ), AnalyzeDataAction), # 数据可视化（依赖matplotlib） (ActionInfo( name="visualize_data_action", description="数据可视化", focus_activation_type=ActionActivationType.KEYWORD, normal_activation_type=ActionActivationType.KEYWORD, activation_keywords=["数据图表", "可视化"], ), VisualizeDataAction), ] class FetchDataAction(BaseAction): """数据获取Action - 仅依赖必需的requests库""" async def execute(self, action_input, context=None): """获取外部数据""" try: import requests # 模拟数据获取 url = action_input.get("url", "https://api.github.com/users/octocat") response = requests.get(url, timeout=10) response.raise_for_status() data = response.json() return { "status": "success", "message": f"成功获取数据，响应大小: {len(str(data))} 字符", "data": data, "capabilities": ["basic_fetch"] } except ImportError: return { "status": "error", "message": "缺少必需依赖：requests库", "hint": "请运行: pip install requests>=2.25.0", "error_code": "MISSING_DEPENDENCY" } except Exception as e: return { "status": "error", "message": f"数据获取失败: {str(e)}", "error_code": "FETCH_ERROR" } class AnalyzeDataAction(BaseAction): """数据分析Action - 支持多级功能降级""" async def execute(self, action_input, context=None): """分析数据，支持功能降级""" # 检查可用的依赖 has_pandas = self._check_dependency("pandas") has_numpy = self._check_dependency("numpy") # 获取输入数据 data = action_input.get("data", [1, 2, 3, 4, 5]) if has_pandas and has_numpy: return await self._advanced_analysis(data) elif has_numpy: return await self._numpy_analysis(data) else: return await self._basic_analysis(data) def _check_dependency(self, package_name): """检查依赖是否可用""" try: __import__(package_name) return True except ImportError: return False async def _advanced_analysis(self, data): """高级分析（使用pandas + numpy）""" import pandas as pd import numpy as np # 转换为DataFrame df = pd.DataFrame({"values": data}) # 高级统计分析 stats = { "count": len(df), "mean": df["values"].mean(), "median": df["values"].median(), "std": df["values"].std(), "min": df["values"].min(), "max": df["values"].max(), "quartiles": df["values"].quantile([0.25, 0.5, 0.75]).to_dict(), "skewness": df["values"].skew(), "kurtosis": df["values"].kurtosis() } return { "status": "success", "message": "高级数据分析完成", "data": stats, "method": "advanced", "capabilities": ["pandas", "numpy", "advanced_stats"] } async def _numpy_analysis(self, data): """中级分析（仅使用numpy）""" import numpy as np arr = np.array(data) stats = { "count": len(arr), "mean": np.mean(arr), "median": np.median(arr), "std": np.std(arr), "min": np.min(arr), "max": np.max(arr), "sum": np.sum(arr) } return { "status": "success", "message": "数值计算分析完成", "data": stats, "method": "numpy", "capabilities": ["numpy", "basic_stats"] } async def _basic_analysis(self, data): """基础分析（纯Python）""" stats = { "count": len(data), "mean": sum(data) / len(data) if data else 0, "min": min(data) if data else None, "max": max(data) if data else None, "sum": sum(data) } return { "status": "success", "message": "基础数据分析完成", "data": stats, "method": "basic", "capabilities": ["pure_python"], "note": "安装numpy和pandas可获得更多分析功能" } class VisualizeDataAction(BaseAction): """数据可视化Action - 展示条件功能启用""" async def execute(self, action_input, context=None): """数据可视化""" # 检查可视化依赖 visualization_available = self._check_visualization_deps() if not visualization_available: return { "status": "unavailable", "message": "数据可视化功能不可用", "reason": "缺少matplotlib和PIL依赖", "install_hint": "pip install matplotlib>=3.3.0 Pillow>=8.0.0", "alternative": "可以使用基础数据分析功能" } return await self._create_visualization(action_input) def _check_visualization_deps(self): """检查可视化所需的依赖""" try: import matplotlib import PIL return True except ImportError: return False async def _create_visualization(self, action_input): """创建数据可视化""" import matplotlib.pyplot as plt import io import base64 from PIL import Image # 获取数据 data = action_input.get("data", [1, 2, 3, 4, 5]) chart_type = action_input.get("type", "line") # 创建图表 plt.figure(figsize=(10, 6)) if chart_type == "line": plt.plot(data) plt.title("线性图") elif chart_type == "bar": plt.bar(range(len(data)), data) plt.title("柱状图") elif chart_type == "hist": plt.hist(data, bins=10) plt.title("直方图") else: plt.plot(data) plt.title("默认线性图") plt.xlabel("索引") plt.ylabel("数值") plt.grid(True) # 保存为字节流 buffer = io.BytesIO() plt.savefig(buffer, format='png', dpi=150, bbox_inches='tight') buffer.seek(0) # 转换为base64 image_base64 = base64.b64encode(buffer.getvalue()).decode() plt.close() # 释放内存 return { "status": "success", "message": f"生成{chart_type}图表成功", "data": { "chart_type": chart_type, "data_points": len(data), "image_base64": image_base64 }, "capabilities": ["matplotlib", "pillow", "visualization"] } # 测试和演示代码 async def demo_dependency_management(): """演示依赖管理功能""" print("🔍 插件依赖管理演示") print("=" * 50) # 创建插件实例 plugin = DataAnalysisPlugin() print("\n📦 插件依赖信息:") for dep in plugin.python_dependencies: status = "✅" if plugin._check_dependency_available(dep.package_name) else "❌" optional_str = " (可选)" if dep.optional else " (必需)" print(f" {status} {dep.package_name} {dep.version}{optional_str}") print(f" {dep.description}") print("\n🧪 功能测试:") # 测试数据获取 fetch_action = FetchDataAction() result = await fetch_action.execute({"url": "https://httpbin.org/json"}) print(f" 数据获取: {result['status']}") # 测试数据分析 analyze_action = AnalyzeDataAction() test_data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] result = await analyze_action.execute({"data": test_data}) print(f" 数据分析: {result['status']} (方法: {result.get('method', 'unknown')})") print(f" 可用功能: {result.get('capabilities', [])}") # 测试数据可视化 viz_action = VisualizeDataAction() result = await viz_action.execute({"data": test_data, "type": "line"}) print(f" 数据可视化: {result['status']}") print("\n💡 依赖管理建议:") missing_deps = plugin.plugin_info.get_missing_packages() if missing_deps: print(" 缺失的必需依赖:") for dep in missing_deps: print(f" - {dep.get_pip_requirement()}") print(f"\n 安装命令:") print(f" pip install {' '.join([dep.get_pip_requirement() for dep in missing_deps])}") else: print(" ✅ 所有必需依赖都已安装") if __name__ == "__main__": import asyncio # 为演示添加依赖检查方法 def _check_dependency_available(package_name): try: __import__(package_name) return True except ImportError: return False DataAnalysisPlugin._check_dependency_available = _check_dependency_available # 运行演示 asyncio.run(demo_dependency_management()) ``` ## 🎯 示例说明 ### 1. 依赖分层设计 这个示例展示了三层依赖设计： - **必需依赖**: `requests` - 核心功能必需 - **增强依赖**: `pandas`, `numpy` - 提供更强大的分析能力 - **可选依赖**: `matplotlib`, `PIL` - 提供可视化功能 ### 2. 优雅降级策略 ```python # 三级功能降级 if has_pandas and has_numpy: return await self._advanced_analysis(data) # 最佳体验 elif has_numpy: return await self._numpy_analysis(data) # 中等体验 else: return await self._basic_analysis(data) # 基础体验 ``` ### 3. 条件功能启用 ```python # 只有依赖可用时才提供功能 visualization_available = self._check_visualization_deps() if not visualization_available: return {"status": "unavailable", "install_hint": "..."} ``` ## 🚀 使用这个示例 ### 1. 复制代码 将示例代码保存为 `plugins/data_analysis_plugin/plugin.py` ### 2. 测试依赖检查 ```python from src.plugin_system import plugin_manager # 检查这个插件的依赖 result = plugin_manager.check_all_dependencies() print(result['plugin_status']['data_analysis_plugin']) ``` ### 3. 安装缺失依赖 ```python # 生成requirements文件 plugin_manager.generate_plugin_requirements("data_plugin_deps.txt") # 手动安装 # pip install -r data_plugin_deps.txt ``` ### 4. 测试功能降级 ```bash # 测试基础功能（只安装requests） pip install requests>=2.25.0 # 测试增强功能（添加数据处理） pip install numpy>=1.20.0 pandas>=1.3.0 # 测试完整功能（添加可视化） pip install matplotlib>=3.3.0 Pillow>=8.0.0 ``` ## 💡 最佳实践总结 1. **分层依赖设计**: 区分核心、增强、可选依赖 2. **优雅降级处理**: 提供多级功能体验 3. **明确错误信息**: 告诉用户如何解决依赖问题 4. **条件功能启用**: 根据依赖可用性动态调整功能 5. **详细依赖描述**: 说明每个依赖的用途 这个示例展示了如何构建一个既强大又灵活的插件，即使在依赖不完整的情况下也能提供有用的功能。