Skip to content

Commit 508de46

Browse files
JohnRichard4096JohnRichard4096
authored
Merge pull request #1 from LiteSuggarDEV/docs
更新MarkDown文档
2 parents 90ec8e0 + 58bf83d commit 508de46

File tree

8 files changed

+374
-83
lines changed

8 files changed

+374
-83
lines changed

‎.github/workflows/PR.yml‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
name: PullRequests CI/CD Pipeline
2+
3+
on:
4+
pull_request:
5+
branches:
6+
- main
7+
paths:
8+
- "**"
9+
10+
jobs:
11+
build:
12+
runs-on: ubuntu-latest
13+
14+
steps:
15+
- name: Checkout code
16+
uses: actions/checkout@v4
17+
18+
- name: Install uv
19+
uses: astral-sh/setup-uv@v5
20+
21+
- name: Set up Python
22+
run: uv python install
23+
24+
- name: Set environment
25+
run: |
26+
uv venv .venv
27+
uv sync
28+
29+
- name: Install dependencies
30+
run: |
31+
pipx install nb-cli
32+
33+
- name: Get Python path
34+
run: |
35+
PYTHON_BIN="$(uv run python -c 'import sys; print(sys.executable)')"
36+
echo "PYTHON_BIN=$PYTHON_BIN" >> $GITHUB_ENV
37+
38+
- name: Run Pyright
39+
uses: jakebailey/pyright-action@v2
40+
with:
41+
python-path: ${{ env.PYTHON_BIN }}
42+
pylance-version: latest-release
43+
44+
45+
- name: Build package
46+
run: uv build # 生成构建产物到dist目录
47+
48+
- name: Save build artifacts
49+
uses: actions/upload-artifact@v4
50+
with:
51+
name: python-package
52+
path: dist/* # 上传所有构建产物

‎README.md‎

Lines changed: 50 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -1,99 +1,70 @@
1-
# plugin-liteperm
2-
3-
基于权限节点+特殊权限+权限组的依赖权限管理插件！
4-
5-
>本项目灵感来自于[LuckPerms](https://github.com/LuckPerms/LuckPerms)
6-
71
# NoneBot Plugin LitePerms 文档
82

9-
## 📖 指令文档
10-
11-
### 通用命令结构
12-
13-
```
14-
/lp [对象类型] [操作类型] [操作] [目标] [值]
15-
```
16-
17-
---
18-
19-
### 用户权限管理 (lp user)
20-
21-
```
22-
/lp user [用户ID] [操作类型] [操作] [目标节点/组] [值]
23-
```
24-
25-
**操作类型**：
26-
27-
1. **permission** - 直接权限管理
28-
- `set [节点] [true/false]`：设置权限节点状态
29-
- `del [节点]`：删除权限节点
30-
- `check [节点]`：检查权限节点
31-
- `list`：列出所有权限
32-
33-
2. **parent** - 继承组管理
34-
- `add [组名]`：添加继承组
35-
- `del [组名]`：移除继承组
36-
- `set [组名]`：覆盖为指定组的权限
37-
38-
3. **perm_group** - 权限组管理
39-
- `add [组名]`：添加权限组
40-
- `del [组名]`：移除权限组
3+
<div align="center">
4+
<a href="https://github.com/JohnRichard4096/nonebot_plugin_liteperm/">
5+
<img src="https://github.com/user-attachments/assets/b5162036-5b17-4cf4-b0cb-8ec842a71bc6" width="200" alt="SuggarChat Logo">
6+
</a>
7+
<h1>LitePerms</h1>
8+
<h3>权限节点权限管理插件</h3>
9+
10+
<p>
11+
<a href="https://pypi.org/project/nonebot-plugin-liteperm/">
12+
<img src="https://img.shields.io/pypi/v/nonebot-plugin-liteperm?color=blue&style=flat-square" alt="PyPI Version">
13+
</a>
14+
<a href="https://www.python.org/">
15+
<img src="https://img.shields.io/badge/python-3.9+-blue?logo=python&style=flat-square" alt="Python Version">
16+
</a>
17+
<a href="https://nonebot.dev/">
18+
<img src="https://img.shields.io/badge/nonebot2-2.0.0rc4+-blue?style=flat-square" alt="NoneBot Version">
19+
</a>
20+
<a href="LICENSE">
21+
<img src="https://img.shields.io/github/license/LiteSuggarDEV/plugin-liteperm?style=flat-square" alt="License">
22+
</a>
23+
<a href="https://qm.qq.com/q/PFcfb4296m">
24+
<img src="https://img.shields.io/badge/QQ%E7%BE%A4-1002495699-blue?style=flat-square" alt="QQ Group">
25+
</a>
26+
</p>
27+
</div>
4128

42-
**示例**：
4329

44-
```
45-
/lp user 123456 permission set lp.admin true
46-
/lp user 123456 parent add admin_group
47-
```
30+
基于权限节点+特殊权限+权限组的依赖权限管理插件！
4831

49-
---
32+
>本项目灵感来自于[LuckPerms](https://github.com/LuckPerms/LuckPerms)
5033
51-
### 群组权限管理 (lp group)
34+
## 特性
5235

53-
```
54-
/lp group [群号] [操作类型] [操作] [目标节点/组] [值]
55-
```
36+
- 节点权限管理
37+
- 特殊权限管理
38+
- 权限组管理
39+
- 特定指令权限管理
5640

57-
（参数格式与用户权限管理相同）
41+
## 快速开始
5842

59-
---
43+
### 安装
6044

61-
### 权限组管理 (lp perm_group)
45+
- 使用pip安装
6246

63-
```
64-
/lp perm_group [组名] [操作类型] [操作] [目标节点/组] [值]
65-
```
47+
```bash
48+
pip install nonebot-plugin-liteperm
49+
```
6650

67-
**新增操作类型**：
51+
- 使用uv安装
6852

69-
- **to** - 组操作
70-
- `create`：创建新权限组
71-
- `remove`：删除权限组
53+
```bash
54+
uv add nonebot-plugin-liteperm
55+
```
7256

73-
**示例**：
57+
### 启用
7458

75-
```
76-
/lp perm_group admin to create
77-
/lp perm_group admin permission set system.* true
78-
```
79-
80-
---
59+
修改`pyproject.toml`，在`[tool.nonebot]`下的`plugins = ["nonebot_plugin_liteperm"]`添加插件
8160

82-
### 命令权限管理 (lp command)
61+
## 配置
8362

63+
```toml
64+
# 是否启用指令权限检查
65+
cmd_permission_checker=true
8466
```
85-
/lp command [命令名] [操作类型] [操作] [权限节点] [值]
86-
```
87-
88-
**操作类型**：
8967

90-
- [set_permission](file:///home/johnrichard/LiteSuggarDEV/plugin-liteperm/src/nonebot_plugin_liteperm/nodelib.py#L59-L74)：设置命令权限节点
91-
- `command del`：删除命令权限配置
92-
93-
**示例**：
94-
95-
```
96-
/lp command ping set_permission lp.user.ping true
97-
```
68+
## [指令文档](docs/commands.md)
9869

99-
---
70+
## [API文档](docs/API.md)

‎docs/API.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# API文档
2+
3+
4+
`nonebot-plugin-liteperm.api.rules`
5+
6+
## `PermissionChecker` 基类
7+
8+
- **功能**：权限检查器的抽象基类
9+
- **参数**：
10+
- `permission: str` - 要检查的权限节点
11+
- **方法**：
12+
- `checker() -> Callable[[Event, str], Awaitable[bool]]`
13+
📌 生成供 NoneBot Rule 使用的检查器闭包
14+
15+
```python
16+
async def _checker(event: Event, current_perm=current_perm) -> bool:
17+
return await self._check_permission(event, current_perm)
18+
```
19+
20+
- `_check_permission(event: Event, perm: str) -> bool`
21+
⚠️ 需子类实现的权限检查核心方法
22+
23+
## `UserPermissionChecker` 用户权限检查器
24+
25+
- **继承**：`PermissionChecker`
26+
- **功能**：检查用户权限
27+
- **检查逻辑**：
28+
1. 获取事件中的用户ID
29+
2. 查询用户数据
30+
3. 遍历用户的权限组
31+
4. 检查权限组中是否包含目标权限
32+
5. 最后检查用户自身的权限
33+
- **示例**：
34+
35+
```python
36+
user_check = UserPermissionChecker(permission="admin.access") # 实际替换为你的权限节点
37+
rule = Rule(user_check.checker())
38+
39+
40+
## `GroupPermissionChecker` 群组权限检查器
41+
42+
- **继承**：`PermissionChecker`
43+
- **参数**：
44+
- `only_group: bool = True` - 是否仅限群组事件
45+
- **功能**：检查群组权限
46+
- **检查逻辑**：
47+
1. 验证事件是否为群组事件
48+
2. 获取群组ID
49+
3. 查询群组数据
50+
4. 遍历群组的权限组
51+
5. 检查权限组中是否包含目标权限
52+
6. 最后检查群组自身的权限
53+
- **示例**：
54+
55+
```python
56+
group_check = GroupPermissionChecker(permission="group.manage") # 实际替换为你的权限节点
57+
rule = Rule(group_check.checker())
58+
59+
60+
## 类型定义
61+
62+
```python
63+
GroupEvent: TypeAlias = (
64+
GroupIncreaseNoticeEvent
65+
| GroupAdminNoticeEvent
66+
| GroupBanNoticeEvent
67+
| GroupDecreaseNoticeEvent
68+
| GroupMessageEvent
69+
| GroupRecallNoticeEvent
70+
| GroupRequestEvent
71+
| GroupUploadNoticeEvent
72+
)
73+
```
74+
75+
## 使用示例
76+
77+
```python
78+
from nonebot.rule import Rule
79+
from .rules import UserPermissionChecker, GroupPermissionChecker
80+
81+
# 创建用户权限检查器
82+
user_perm_checker = UserPermissionChecker(permission="plugin.admin")
83+
84+
# 创建群组权限检查器
85+
group_perm_checker = GroupPermissionChecker(permission="group.manage", only_group=True)
86+
87+
# 在事件处理器中使用
88+
@matcher.handle(rule=Rule(user_perm_checker.checker()))
89+
async def handle_admin_command():
90+
...
91+
92+
@matcher.handle(rule=Rule(group_perm_checker.checker()))
93+
async def handle_group_manage():
94+
...
95+
```
96+
97+
## 调试日志
98+
99+
权限检查过程会输出调试日志：
100+
101+
```shell
102+
DEBUG: checking user permission 123456 plugin.admin
103+
DEBUG: checking group permission 789012 group.manage
104+
```

0 commit comments

Comments
 (0)