GsCore 插件开发指南（AI）

1. 插件基本结构

插件可以有两种形式：

单文件插件：单个 .py 文件
插件包：包含 __init__.py 的目录

2. 插件类定义

插件需要继承 Plugins 类，基本结构如下：

from gsuid_core.sv import Plugins, SV

# 定义插件类
class YourPlugin(Plugins):
    def __init__(
        self,
        name: str = '插件名称',
        pm: int = 6,  # 权限等级
        priority: int = 5,  # 优先级
        enabled: bool = True,  # 是否启用
        area: Literal['GROUP', 'DIRECT', 'ALL', 'SV'] = 'SV',  # 使用范围
        black_list: List = [],  # 黑名单
        white_list: List = [],  # 白名单
        prefix: Union[List[str], str] = [],  # 命令前缀
        force_prefix: List[str] = [],  # 强制前缀
        disable_force_prefix: bool = False,  # 是否禁用强制前缀
        allow_empty_prefix: Optional[bool] = None,  # 是否允许空前缀
    ):
        super().__init__(
            name=name,
            pm=pm,
            priority=priority,
            enabled=enabled,
            area=area,
            black_list=black_list,
            white_list=white_list,
            prefix=prefix,
            force_prefix=force_prefix,
            disable_force_prefix=disable_force_prefix,
            allow_empty_prefix=allow_empty_prefix,
        )

3. 命令定义

使用 SV 类定义命令：

# 定义命令
sv = SV(
    name='命令名称',
    pm=6,  # 权限等级
    priority=5,  # 优先级
    enabled=True,  # 是否启用
    area='ALL',  # 使用范围
    black_list=[],  # 黑名单
    white_list=[],  # 白名单
)

# 定义命令处理函数
@sv.on('command', '命令关键词')
async def your_command(bot: Bot, ev: Event):
    # 处理逻辑
    pass

4. 帮助系统

插件需要注册帮助信息：

from gsuid_core.help.utils import register_help

# 注册帮助
register_help(
    name='插件名称',
    help='帮助命令',
    icon=None  # 可选，插件图标
)

5. 状态监控

可以注册插件状态监控：

from gsuid_core.status.plugin_status import register_status

# 注册状态监控
register_status(
    ICON=your_icon,  # PIL Image对象
    plugin_name='插件名称',
    plugin_status={
        '状态名称': async_status_function
    }
)

6. 配置系统

插件可以定义配置项：

from gsuid_core.utils.plugins_config.models import (
    GsConfig,
    GsStrConfig,
    GsListStrConfig
)

# 定义配置项
class YourConfig(GsConfig):
    title: str = '配置标题'
    desc: str = '配置描述'
    data: str = '默认值'
    options: List[str] = []  # 可选值列表

7. Web控制台支持

插件可以注册Web控制台页面：

from gsuid_core.webconsole.mount_app import GsAdminSite

# 注册管理页面
@site.register_admin
class YourAdminPage(admin.AdminApp):
    page_schema = PageSchema(label="页面标题", icon="fa fa-icon")

8. 插件目录结构

推荐的标准插件目录结构：

your_plugin/
├── __init__.py          # 插件主入口
├── __full__.py          # 插件包合集（可选）
├── __nest__.py          # 嵌套插件（可选）
├── pyproject.toml       # 项目配置（可选）
├── src/                 # 源代码目录
│   └── your_plugin/     # 插件代码
├── tests/               # 测试目录
└── README.md           # 说明文档