diff --git a/.github/workflows/PR.yml b/.github/workflows/PR.yml new file mode 100644 index 0000000..97c2a06 --- /dev/null +++ b/.github/workflows/PR.yml @@ -0,0 +1,52 @@ +name: PullRequests CI/CD Pipeline + +on: + pull_request: + branches: + - main + paths: + - "**" + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Install uv + uses: astral-sh/setup-uv@v5 + + - name: Set up Python + run: uv python install + + - name: Set environment + run: | + uv venv .venv + uv sync + + - name: Install dependencies + run: | + pipx install nb-cli + + - name: Get Python path + run: | + PYTHON_BIN="$(uv run python -c 'import sys; print(sys.executable)')" + echo "PYTHON_BIN=$PYTHON_BIN" >> $GITHUB_ENV + + - name: Run Pyright + uses: jakebailey/pyright-action@v2 + with: + python-path: ${{ env.PYTHON_BIN }} + pylance-version: latest-release + + + - name: Build package + run: uv build # 生成构建产物到dist目录 + + - name: Save build artifacts + uses: actions/upload-artifact@v4 + with: + name: python-package + path: dist/* # 上传所有构建产物 \ No newline at end of file diff --git a/README.md b/README.md index c505952..4b1fac2 100644 --- a/README.md +++ b/README.md @@ -1,99 +1,70 @@ -# plugin-liteperm - -基于权限节点+特殊权限+权限组的依赖权限管理插件！ - ->本项目灵感来自于[LuckPerms](https://github.com/LuckPerms/LuckPerms) - # NoneBot Plugin LitePerms 文档 -## 📖 指令文档 - -### 通用命令结构 - -``` -/lp [对象类型] [操作类型] [操作] [目标] [值] -``` - ---- - -### 用户权限管理 (lp user) - -``` -/lp user [用户ID] [操作类型] [操作] [目标节点/组] [值] -``` - -**操作类型**： - -1. **permission** - 直接权限管理 - - `set [节点] [true/false]`：设置权限节点状态 - - `del [节点]`：删除权限节点 - - `check [节点]`：检查权限节点 - - `list`：列出所有权限 - -2. **parent** - 继承组管理 - - `add [组名]`：添加继承组 - - `del [组名]`：移除继承组 - - `set [组名]`：覆盖为指定组的权限 - -3. **perm_group** - 权限组管理 - - `add [组名]`：添加权限组 - - `del [组名]`：移除权限组 +
+ + SuggarChat Logo + +

LitePerms

+

权限节点权限管理插件

+ +

+ + PyPI Version + + + Python Version + + + NoneBot Version + + + License + + + QQ Group + +

+
-**示例**： -``` -/lp user 123456 permission set lp.admin true -/lp user 123456 parent add admin_group -``` +基于权限节点+特殊权限+权限组的依赖权限管理插件！ ---- +>本项目灵感来自于[LuckPerms](https://github.com/LuckPerms/LuckPerms) -### 群组权限管理 (lp group) +## 特性 -``` -/lp group [群号] [操作类型] [操作] [目标节点/组] [值] -``` +- 节点权限管理 +- 特殊权限管理 +- 权限组管理 +- 特定指令权限管理 -（参数格式与用户权限管理相同） +## 快速开始 ---- +### 安装 -### 权限组管理 (lp perm_group) +- 使用pip安装 -``` -/lp perm_group [组名] [操作类型] [操作] [目标节点/组] [值] -``` + ```bash + pip install nonebot-plugin-liteperm + ``` -**新增操作类型**： +- 使用uv安装 -- **to** - 组操作 - - `create`：创建新权限组 - - `remove`：删除权限组 + ```bash + uv add nonebot-plugin-liteperm + ``` -**示例**： +### 启用 -``` -/lp perm_group admin to create -/lp perm_group admin permission set system.* true -``` - ---- +修改`pyproject.toml`，在`[tool.nonebot]`下的`plugins = ["nonebot_plugin_liteperm"]`添加插件 -### 命令权限管理 (lp command) +## 配置 +```toml +# 是否启用指令权限检查 +cmd_permission_checker=true ``` -/lp command [命令名] [操作类型] [操作] [权限节点] [值] -``` - -**操作类型**： -- [set_permission](file:///home/johnrichard/LiteSuggarDEV/plugin-liteperm/src/nonebot_plugin_liteperm/nodelib.py#L59-L74)：设置命令权限节点 -- `command del`：删除命令权限配置 - -**示例**： - -``` -/lp command ping set_permission lp.user.ping true -``` +## [指令文档](docs/commands.md) ---- +## [API文档](docs/API.md) diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 0000000..ce3af4f --- /dev/null +++ b/docs/API.md @@ -0,0 +1,104 @@ +# API文档 + + +`nonebot-plugin-liteperm.api.rules` + +## `PermissionChecker` 基类 + +- **功能**：权限检查器的抽象基类 +- **参数**： + - `permission: str` - 要检查的权限节点 +- **方法**： + - `checker() -> Callable[[Event, str], Awaitable[bool]]` + 📌 生成供 NoneBot Rule 使用的检查器闭包 + + ```python + async def _checker(event: Event, current_perm=current_perm) -> bool: + return await self._check_permission(event, current_perm) + ``` + + - `_check_permission(event: Event, perm: str) -> bool` + ⚠️ 需子类实现的权限检查核心方法 + +## `UserPermissionChecker` 用户权限检查器 + +- **继承**：`PermissionChecker` +- **功能**：检查用户权限 +- **检查逻辑**： + 1. 获取事件中的用户ID + 2. 查询用户数据 + 3. 遍历用户的权限组 + 4. 检查权限组中是否包含目标权限 + 5. 最后检查用户自身的权限 +- **示例**： + + ```python + user_check = UserPermissionChecker(permission="admin.access") # 实际替换为你的权限节点 + rule = Rule(user_check.checker()) + + +## `GroupPermissionChecker` 群组权限检查器 + +- **继承**：`PermissionChecker` +- **参数**： + - `only_group: bool = True` - 是否仅限群组事件 +- **功能**：检查群组权限 +- **检查逻辑**： + 1. 验证事件是否为群组事件 + 2. 获取群组ID + 3. 查询群组数据 + 4. 遍历群组的权限组 + 5. 检查权限组中是否包含目标权限 + 6. 最后检查群组自身的权限 +- **示例**： + + ```python + group_check = GroupPermissionChecker(permission="group.manage") # 实际替换为你的权限节点 + rule = Rule(group_check.checker()) + + +## 类型定义 + +```python +GroupEvent: TypeAlias = ( + GroupIncreaseNoticeEvent + | GroupAdminNoticeEvent + | GroupBanNoticeEvent + | GroupDecreaseNoticeEvent + | GroupMessageEvent + | GroupRecallNoticeEvent + | GroupRequestEvent + | GroupUploadNoticeEvent +) +``` + +## 使用示例 + +```python +from nonebot.rule import Rule +from .rules import UserPermissionChecker, GroupPermissionChecker + +# 创建用户权限检查器 +user_perm_checker = UserPermissionChecker(permission="plugin.admin") + +# 创建群组权限检查器 +group_perm_checker = GroupPermissionChecker(permission="group.manage", only_group=True) + +# 在事件处理器中使用 +@matcher.handle(rule=Rule(user_perm_checker.checker())) +async def handle_admin_command(): + ... + +@matcher.handle(rule=Rule(group_perm_checker.checker())) +async def handle_group_manage(): + ... +``` + +## 调试日志 + +权限检查过程会输出调试日志： + +```shell +DEBUG: checking user permission 123456 plugin.admin +DEBUG: checking group permission 789012 group.manage +``` diff --git a/docs/commands.md b/docs/commands.md new file mode 100644 index 0000000..ca428de --- /dev/null +++ b/docs/commands.md @@ -0,0 +1,165 @@ +# 指令文档 + +## 主指令 + +- **格式**：/lp +- **功能**：显示插件帮助信息 +- **响应**：LP LitePerms 请输入参数： lp user lp group lp perm_group lp command + +## 用户权限管理 + +
+ +### `lp user` - 用户权限管理 + +- **格式**：`lp user <用户ID> <操作类型> <操作> [目标] [值]` +- **操作类型**： + - `permission` - 权限节点操作 + - `parent` - 权限组继承操作 + - `perm_group` - 权限组管理 + +#### 用户权限节点操作 (`permission`) + +| 操作 | 格式 | 示例 | 说明 | +|-----------|-----------------------------------|--------------------------|--------------------------| +| `set` | `lp user permission set <节点> ` | `lp user 123 permission set admin.access true` | 设置权限节点状态 | +| `del` | `lp user permission del <节点>` | `lp user 123 permission del user.edit` | 删除权限节点 | +| `check` | `lp user permission check <节点>` | `lp user 123 permission check plugin.admin` | 检查是否拥有权限 | +| `list` | `lp user permission list` | `lp user 123 permission list` | 列出用户所有权限 | + +#### 用户权限组继承操作 (`parent`) + +| 操作 | 格式 | 示例 | 说明 | +|-----------|-----------------------------------|--------------------------|--------------------------| +| `add` | `lp user parent add <权限组>` | `lp user 123 parent add admin_group` | 添加继承的权限组 | +| `del` | `lp user parent del <权限组>` | `lp user 123 parent del vip_group` | 移除继承的权限组 | +| `set` | `lp user parent set <权限组>` | `lp user 123 parent set admin_group` | 覆盖为权限组的权限 | + +#### 用户权限组管理 (`perm_group`) + +| 操作 | 格式 | 示例 | 说明 | +|-----------|-----------------------------------|--------------------------|--------------------------| +| `add` | `lp user perm_group add <权限组>` | `lp user 123 perm_group add vip` | 添加用户到权限组 | +| `del` | `lp user perm_group del <权限组>` | `lp user 123 perm_group del guest` | 从权限组移除用户 | + +
+ +## 群组权限管理 + +
+ +### `lp group` - 群组权限管理 + +- **格式**：`lp group <群组ID> <操作类型> <操作> [目标] [值]` +- **操作类型**： + - `permission` - 权限节点操作 + - `parent` - 权限组继承操作 + - `perm_group` - 权限组管理 + +#### 群权限节点操作 (`permission`) + +| 操作 | 格式 | 示例 | 说明 | +|-----------|-----------------------------------|--------------------------|--------------------------| +| `set` | `lp group permission set <节点> ` | `lp group 456 permission set group.manage true` | 设置权限节点状态 | +| `del` | `lp group permission del <节点>` | `lp group 456 permission del group.kick` | 删除权限节点 | +| `check` | `lp group permission check <节点>` | `lp group 456 permission check plugin.admin` | 检查是否拥有权限 | +| `list` | `lp group permission list` | `lp group 456 permission list` | 列出群组所有权限 | + +#### 群权限组继承操作 (`parent`) + +| 操作 | 格式 | 示例 | 说明 | +|-----------|-----------------------------------|--------------------------|--------------------------| +| `add` | `lp group parent add <权限组>` | `lp group 456 parent add group_admin` | 添加继承的权限组 | +| `del` | `lp group parent del <权限组>` | `lp group 456 parent del group_vip` | 移除继承的权限组 | +| `set` | `lp group parent set <权限组>` | `lp group 456 parent set group_admin` | 覆盖为权限组的权限 | + +#### 群权限组管理 (`perm_group`) + +| 操作 | 格式 | 示例 | 说明 | +|-----------|-----------------------------------|--------------------------|--------------------------| +| `add` | `lp group perm_group add <权限组>` | `lp group 456 perm_group add vip` | 添加群组到权限组 | +| `del` | `lp group perm_group del <权限组>` | `lp group 456 perm_group del guest` | 从权限组移除群组 | + +
+ +## 权限组管理 + +
+ +### `lp perm_group` - 权限组管理 + +- **格式**：`lp perm_group <权限组名> <操作类型> <操作> [目标] [值]` +- **操作类型**： + - `permission` - 权限节点操作 + - `parent` - 权限组继承操作 + - `to` - 权限组管理 + +#### 权限节点操作 (`permission`) + +| 操作 | 格式 | 示例 | 说明 | +|-----------|-----------------------------------|--------------------------|--------------------------| +| `set` | `lp perm_group <组名> permission set <节点> ` | `lp perm_group admin permission set system.* true` | 设置权限节点状态 | +| `del` | `lp perm_group <组名> permission del <节点>` | `lp perm_group admin permission del user.edit` | 删除权限节点 | +| `check` | `lp perm_group <组名> permission check <节点>` | `lp perm_group admin permission check plugin.admin` | 检查是否拥有权限 | +| `list` | `lp perm_group <组名> permission list` | `lp perm_group admin permission list` | 列出权限组所有权限 | + +#### 权限组继承操作 (`parent`) + +| 操作 | 格式 | 示例 | 说明 | +|-----------|-----------------------------------|--------------------------|--------------------------| +| `add` | `lp perm_group <组名> parent add <权限组>` | `lp perm_group vip parent add base` | 添加继承的权限组 | +| `del` | `lp perm_group <组名> parent del <权限组>` | `lp perm_group vip parent del base` | 移除继承的权限组 | +| `set` | `lp perm_group <组名> parent set <权限组>` | `lp perm_group vip parent set admin` | 覆盖为权限组的权限 | + +#### 权限组管理 (`to`) + +| 操作 | 格式 | 示例 | 说明 | +|-----------|-----------------------------------|--------------------------|--------------------------| +| `create` | `lp perm_group <组名> to create` | `lp perm_group new_group to create` | 创建新权限组 | +| `remove` | `lp perm_group <组名> to remove` | `lp perm_group old_group to remove` | 删除权限组 | + +
+ +## 指令权限管理 + +
+ +### `lp command` - 命令权限设置 + +- **格式**：`lp command <命令名> <操作类型> <操作> [节点] [值]` +- **操作类型**： + - `set_permission` - 设置命令权限 + - `command` - 命令管理 + - `list` - 列表查看 + +#### 权限设置 (`set_permission`) + +| 操作 | 格式 | 示例 | 说明 | +|-----------|-----------------------------------|--------------------------|--------------------------| +| `set` | `lp command <命令> set_permission set <节点> ` | `lp command lp.admin set_permission set user.edit true` | 设置命令权限节点 | +| `del` | `lp command <命令> set_permission del <节点>` | `lp command lp.admin set_permission del user.edit` | 删除命令权限节点 | + +#### 命令管理 (`command`) + +| 操作 | 格式 | 示例 | 说明 | +|-----------|-----------------------------------|--------------------------|--------------------------| +| `del` | `lp command <命令> command del` | `lp command lp.user command del` | 删除命令的所有权限设置 | + +#### 列表查看 (`list`) + +| 操作 | 格式 | 示例 | 说明 | +|-----------|-----------------------------------|--------------------------|--------------------------| +| `list` | `lp command list` | `lp command list` | 列出所有已配置的命令权限 | + +
+ +## 通用参数说明 + +- 用户ID：QQ号或其他平台的用户标识 +- 群组ID：QQ群号或其他平台的群组标识 +- 权限组名：自定义的权限组名称 +- 命令名：插件中的命令名称（如 lp.user） +- 权限节点：使用点分隔的权限标识（如 plugin.admin） +- 值：true 或 false，表示权限状态 + +> **注意**：所有指令需要管理员权限（is_lp_admin）才能执行 \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index d59aa5c..8162209 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "nonebot_plugin_liteperm" -version = "0.0.1.dev2" +version = "0.0.1" description = "基于权限节点/权限组/特殊权限的Nonebot权限管理插件。" authors = [ { name = "JohnRichard4096", email = "windowserror@163.com" }, diff --git a/src/nonebot_plugin_liteperm/API/node.py b/src/nonebot_plugin_liteperm/API/node.py index 9646e5c..639482c 100644 --- a/src/nonebot_plugin_liteperm/API/node.py +++ b/src/nonebot_plugin_liteperm/API/node.py @@ -1 +1 @@ -from ..nodelib import Permissions \ No newline at end of file +from ..nodelib import Permissions # noqa: F401 diff --git a/src/nonebot_plugin_liteperm/config.py b/src/nonebot_plugin_liteperm/config.py index b660b5b..a84846d 100644 --- a/src/nonebot_plugin_liteperm/config.py +++ b/src/nonebot_plugin_liteperm/config.py @@ -45,7 +45,6 @@ class CommandConfig(BasicDataModel): class Config(BasicDataModel): - config_version: int = 1 cmd_permission_checker: bool = True def save_to_toml(self, path: Path): diff --git a/uv.lock b/uv.lock index 3102ed4..aead199 100644 --- a/uv.lock +++ b/uv.lock @@ -264,7 +264,7 @@ wheels = [ [[package]] name = "nonebot-plugin-liteperm" -version = "0.0.1.dev1" +version = "0.0.1" source = { editable = "." } dependencies = [ { name = "nonebot-adapter-onebot" },