新增插件Python依赖管理系统，支持自动检查和安装依赖，优化依赖配置和错误处理，更新相关文档和示例代码。
This commit is contained in:
minecraft1024a
@@ -1,40 +1,192 @@
|
||||
# 📦 插件依赖管理系统
|
||||
# 插件Python依赖管理系统
|
||||
|
||||
现在的Python依赖包管理依然存在问题，请保留你的`python_dependencies`属性，等待后续重构。
|
||||
## 概述
|
||||
|
||||
## 📚 详细教程
|
||||
插件系统现在支持自动检查和安装Python包依赖。当插件初始化时，系统会：
|
||||
|
||||
### PythonDependency 类详解
|
||||
1. 检查插件所需的Python包是否已安装
|
||||
2. 验证包版本是否满足要求
|
||||
3. 自动安装缺失的依赖包（可配置）
|
||||
4. 提供详细的错误信息和日志
|
||||
|
||||
`PythonDependency`是依赖声明的核心类：
|
||||
## 配置依赖
|
||||
|
||||
### 方式1: 简单字符串列表（向后兼容）
|
||||
|
||||
```python
|
||||
PythonDependency(
|
||||
package_name="PIL", # 导入时的包名
|
||||
version=">=11.2.0", # 版本要求
|
||||
optional=False, # 是否为可选依赖
|
||||
description="图像处理库", # 依赖描述
|
||||
install_name="pillow" # pip安装时的包名（可选）
|
||||
from src.plugin_system import BasePlugin
|
||||
|
||||
@register_plugin
|
||||
class MyPlugin(BasePlugin):
|
||||
# 简单的字符串列表格式
|
||||
python_dependencies: List[str] = [
|
||||
"requests",
|
||||
"beautifulsoup4>=4.9.0",
|
||||
"httpx[socks]"
|
||||
]
|
||||
```
|
||||
|
||||
### 方式2: 详细的PythonDependency对象（推荐）
|
||||
|
||||
```python
|
||||
from src.plugin_system import BasePlugin, PythonDependency
|
||||
|
||||
@register_plugin
|
||||
class MyPlugin(BasePlugin):
|
||||
python_dependencies: List[PythonDependency] = [
|
||||
PythonDependency(
|
||||
package_name="requests",
|
||||
version=">=2.25.0",
|
||||
description="HTTP请求库",
|
||||
optional=False
|
||||
),
|
||||
PythonDependency(
|
||||
package_name="beautifulsoup4",
|
||||
version=">=4.9.0",
|
||||
description="HTML解析库",
|
||||
optional=False
|
||||
),
|
||||
PythonDependency(
|
||||
package_name="httpx",
|
||||
install_name="httpx[socks]", # 安装时使用的名称
|
||||
description="支持SOCKS代理的HTTP客户端",
|
||||
optional=True
|
||||
)
|
||||
]
|
||||
```
|
||||
|
||||
## PythonDependency参数说明
|
||||
|
||||
- `package_name`: 包名称（用于import检查）
|
||||
- `version`: 版本要求，支持PEP 440格式（如 ">=1.0.0", "==2.1.3"）
|
||||
- `install_name`: pip安装时使用的名称（如果与package_name不同）
|
||||
- `description`: 依赖描述，用于日志和错误信息
|
||||
- `optional`: 是否为可选依赖，可选依赖缺失不会阻止插件加载
|
||||
|
||||
## 全局配置
|
||||
|
||||
创建 `mmc/config/dependency_config.toml` 文件来配置依赖管理行为：
|
||||
|
||||
```toml
|
||||
[dependency_management]
|
||||
# 是否启用自动安装
|
||||
auto_install = true
|
||||
|
||||
# 安装超时时间（秒）
|
||||
auto_install_timeout = 300
|
||||
|
||||
# 是否使用代理
|
||||
use_proxy = false
|
||||
proxy_url = ""
|
||||
|
||||
# pip安装选项
|
||||
pip_options = [
|
||||
"--no-warn-script-location",
|
||||
"--disable-pip-version-check"
|
||||
]
|
||||
|
||||
# 是否允许自动安装（主开关）
|
||||
allowed_auto_install = true
|
||||
|
||||
# 安装前是否提示用户
|
||||
prompt_before_install = false
|
||||
|
||||
# 日志级别
|
||||
install_log_level = "INFO"
|
||||
```
|
||||
|
||||
## 代理配置
|
||||
|
||||
如果需要通过代理安装包，可以配置：
|
||||
|
||||
```toml
|
||||
[dependency_management]
|
||||
use_proxy = true
|
||||
proxy_url = "http://proxy.example.com:8080"
|
||||
# 或者 SOCKS5 代理
|
||||
# proxy_url = "socks5://proxy.example.com:1080"
|
||||
```
|
||||
|
||||
## 编程方式配置
|
||||
|
||||
也可以通过代码动态配置依赖管理：
|
||||
|
||||
```python
|
||||
from src.plugin_system.utils.dependency_config import configure_dependency_settings
|
||||
|
||||
# 禁用自动安装
|
||||
configure_dependency_settings(auto_install=False)
|
||||
|
||||
# 设置代理
|
||||
configure_dependency_settings(
|
||||
use_proxy=True,
|
||||
proxy_url="http://proxy.example.com:8080"
|
||||
)
|
||||
|
||||
# 修改超时时间
|
||||
configure_dependency_settings(auto_install_timeout=600)
|
||||
```
|
||||
|
||||
#### 参数说明
|
||||
## 工作流程
|
||||
|
||||
| 参数 | 类型 | 必需 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `package_name` | str | ✅ | Python导入时使用的包名（如`requests`） |
|
||||
| `version` | str | ❌ | 版本要求，使用pip格式（如`>=1.0.0`, `==2.1.3`） |
|
||||
| `optional` | bool | ❌ | 是否为可选依赖，默认`False` |
|
||||
| `description` | str | ❌ | 依赖的用途描述 |
|
||||
| `install_name` | str | ❌ | pip安装时的包名，默认与`package_name`相同，用于处理安装名称和导入名称不一致的情况 |
|
||||
1. **插件初始化**: 当插件类被实例化时，系统自动检查依赖
|
||||
2. **依赖标准化**: 将字符串格式的依赖转换为PythonDependency对象
|
||||
3. **检查已安装**: 尝试导入每个依赖包并检查版本
|
||||
4. **自动安装**: 如果启用，自动安装缺失的依赖
|
||||
5. **错误处理**: 记录详细的错误信息和安装日志
|
||||
|
||||
#### 版本格式示例
|
||||
## 日志输出示例
|
||||
|
||||
```python
|
||||
# 常用版本格式
|
||||
PythonDependency("requests", ">=2.25.0") # 最小版本
|
||||
PythonDependency("numpy", ">=1.20.0,<2.0.0") # 版本范围
|
||||
PythonDependency("pillow", "==8.3.2") # 精确版本
|
||||
PythonDependency("scipy", ">=1.7.0,!=1.8.0") # 排除特定版本
|
||||
```
|
||||
[Plugin:web_search_tool] 开始自动安装Python依赖: ['asyncddgs', 'httpx[socks]']
|
||||
[Plugin:web_search_tool] ✅ 成功安装: asyncddgs
|
||||
[Plugin:web_search_tool] ✅ 成功安装: httpx[socks]
|
||||
[Plugin:web_search_tool] 🎉 所有依赖安装完成
|
||||
[Plugin:web_search_tool] Python依赖检查通过
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
当依赖检查失败时，系统会：
|
||||
|
||||
1. 记录详细的错误信息
|
||||
2. 如果是可选依赖缺失，仅记录警告
|
||||
3. 如果是必需依赖缺失且自动安装失败，阻止插件加载
|
||||
4. 提供清晰的解决建议
|
||||
|
||||
## 最佳实践
|
||||
|
||||
1. **使用详细的PythonDependency对象** 以获得更好的控制和文档
|
||||
2. **合理设置可选依赖** 避免非核心功能阻止插件加载
|
||||
3. **指定版本要求** 确保兼容性
|
||||
4. **添加描述信息** 帮助用户理解依赖的用途
|
||||
5. **测试依赖配置** 在不同环境中验证依赖是否正确
|
||||
|
||||
## 安全考虑
|
||||
|
||||
- 自动安装功能默认启用，但可以通过配置禁用
|
||||
- 所有安装操作都有详细的日志记录
|
||||
- 支持设置安装超时以避免长时间挂起
|
||||
- 可以通过`allowed_auto_install`全局禁用自动安装
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 依赖安装失败
|
||||
|
||||
1. 检查网络连接
|
||||
2. 验证代理设置
|
||||
3. 检查pip配置
|
||||
4. 查看详细的错误日志
|
||||
|
||||
### 版本冲突
|
||||
|
||||
1. 检查现有包的版本
|
||||
2. 调整版本要求
|
||||
3. 考虑使用虚拟环境
|
||||
|
||||
### 导入错误
|
||||
|
||||
1. 确认包名与导入名一致
|
||||
2. 检查可选依赖配置
|
||||
3. 验证安装是否成功
|
||||
|
||||
|
||||
Reference in New Issue
Block a user