Skip to content

更新MarkDown文档 #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JohnRichard4096 merged 1 commit into from
Jul 5, 2025
Merged

更新MarkDown文档 #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 52 additions & 0 deletions .github/workflows/PR.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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/* # 上传所有构建产物
129 changes: 50 additions & 79 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 [组名]`：移除权限组
<div align="center">
<a href="https://github.com/JohnRichard4096/nonebot_plugin_liteperm/">
<img src="https://github.com/user-attachments/assets/b5162036-5b17-4cf4-b0cb-8ec842a71bc6" width="200" alt="SuggarChat Logo">
</a>
<h1>LitePerms</h1>
<h3>权限节点权限管理插件</h3>

<p>
<a href="https://pypi.org/project/nonebot-plugin-liteperm/">
<img src="https://img.shields.io/pypi/v/nonebot-plugin-liteperm?color=blue&style=flat-square" alt="PyPI Version">
</a>
<a href="https://www.python.org/">
<img src="https://img.shields.io/badge/python-3.9+-blue?logo=python&style=flat-square" alt="Python Version">
</a>
<a href="https://nonebot.dev/">
<img src="https://img.shields.io/badge/nonebot2-2.0.0rc4+-blue?style=flat-square" alt="NoneBot Version">
</a>
<a href="LICENSE">
<img src="https://img.shields.io/github/license/LiteSuggarDEV/plugin-liteperm?style=flat-square" alt="License">
</a>
<a href="https://qm.qq.com/q/PFcfb4296m">
<img src="https://img.shields.io/badge/QQ%E7%BE%A4-1002495699-blue?style=flat-square" alt="QQ Group">
</a>
</p>
</div>

**示例**：

```
/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)
104 changes: 104 additions & 0 deletions docs/API.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
```
Loading