# PluginMarket

**Repository Path**: tf5488/plugin-market

## Basic Information

- **Project Name**: PluginMarket
- **Description**: 插件工具箱，提供开箱即用的工具集合。
- **Primary Language**: Python
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-07-09
- **Last Updated**: 2026-04-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PluginMarket

基于 **PyQt6 + qfluentwidgets** 的桌面插件管理器（“插件市场”原型），支持 **扫描/展示/启用/禁用/删除** 本地插件，并将启用状态持久化到配置文件。

## 文档导航

- 使用与开发（本文）：快速运行、目录结构、核心概念
- 更详细文档：
  - `docs/architecture.md`：架构与核心流程
  - `docs/configuration.md`：配置项与存储位置
  - `docs/plugin-development.md`：插件规范与示例
  - `plugin-examples/`：项目内置插件示例（可直接拷贝到插件目录测试）
  - `docs/release.md`：打包发布建议（可选）
  - `docs/troubleshooting.md`：报错排查（启动崩溃/依赖冲突等）

## ✨ 核心能力

- **插件发现**：扫描 `cfg.plugin_path` 指定目录下的子目录作为插件（跳过 `__*`）
- **元信息展示**：读取每个插件目录的 `config.json`（版本、作者、描述、图标）
- **运行与生命周期**：启用插件后以 **子进程运行**（每插件一个 `QProcess`），并执行 LOAD/ENABLE；禁用时终止子进程并执行 DISABLE
- **日志与控制台**：主进程捕获插件子进程 **stdout/stderr**，通过信号推送到 UI；主页提供每插件“控制台”入口实时查看日志
- **界面交互**：插件列表卡片 + 开关 + 打开文件夹 + 删除（带二次确认）

## 📦 技术栈

| 组件 | 选型 | 说明 |
|---|---|---|
| GUI | PyQt6 | Qt Widgets |
| UI 组件库 | qfluentwidgets（PyQt6-Fluent-Widgets） | Fluent 风格控件 |
| 配置 | `qfluentwidgets.QConfig` + JSON | 位于 `widget/config/config.json` |
| 插件运行 | `QProcess` + 插件 runner | 插件在独立子进程中运行，捕获 stdout/stderr |

## 🚀 快速开始

### 环境要求

- Python 3.8+（建议 3.10/3.11）

### 安装依赖

如果你不使用仓库自带的 `venv/`，推荐新建虚拟环境后安装：

```bash
pip install -r requirements.txt
```

> 说明：`PyQt6-WebEngine` 为可选依赖，仅 `plugin-examples/BrowserWindow` 示例需要（未安装会自动降级为 `QTextBrowser`）。

### 运行

```bash
python main.py
```

首次启动会检查 `cfg.plugin_path`，若为空或目录不存在，会弹窗要求选择插件目录。

## 📁 项目结构（关键部分）

```
plugin-market/
├── main.py                     # 程序入口：创建 QApplication / ToolsWindow
├── widget/                     # UI 层
│   ├── ToolsWindow.py          # 主窗口 + 导航 + 初始化插件系统
│   ├── market/                 # 插件页（列表/刷新/安装原型）
│   ├── setting/                # 设置页（插件路径选择）
│   ├── message/                # 弹窗（首次选择插件路径等）
│   └── config/
│       ├── config.py           # QConfig 定义与加载
│       └── config.json         # 实际配置文件（持久化）
├── Adapters/                   # 业务层：插件系统、事件系统
│   ├── Plugin.py               # PluginLoader/PluginManager 核心实现
│   ├── BasePlugin.py           # 插件接口抽象
│   └── Event/                  # 事件模型（当前为基础实现）
└── common/                     # 通用工具（文件读写、打开本地路径等）
```

## 🔧 配置位置与关键项

配置文件默认位于 `widget/config/config.json`，由 `widget/config/config.py` 在启动时加载。

- `plugin.plugin_path`：插件根目录（每个子目录一个插件）
- `plugin.sys_path`：程序设置的“系统位置”（当前在 `main.py` 中被设置为项目根目录）
- `plugin.enable_plugin`：已启用插件列表（用于启动时自动恢复启用）

详细说明见 `docs/configuration.md`。

## 🧩 插件目录与最小规范（当前实现）

每个插件是 `cfg.plugin_path` 下的一个目录，例如：

```
<plugin_path>/
└── HelloPlugin/
    ├── HelloPlugin.py
    └── config.json
```

- **目录名**：`HelloPlugin`（也是模块名）
- **入口类名**：同名 `HelloPlugin`（在 `HelloPlugin.py` 内定义）
- **插件类需要继承**：`Adapters.Plugin.Plugin`
- **元信息来自**：`config.json`

完整规范与示例见 `docs/plugin-development.md`。

## 🐛 常见问题

- **插件扫描不到**：确认 `plugin_path` 指向的目录存在，且插件目录内有 `config.json`；目录名不要以 `__` 开头。
- **启用时报错**：检查插件类是否继承 `Adapters.Plugin.Plugin` 且类名与目录名一致；查看控制台输出的异常信息。
- **图标不显示**：`config.json` 的 `icon` 可以是 `FIF.xxx/FluentIcon.xxx` 或插件目录内的文件相对路径。

## 📄 许可证

MIT，见 `LICENSE`。