# perm_plugin — 权限管理插件

让机器人主人（OWNER）直接在聊天框里管理用户权限，无需修改配置文件或重启。

---

## 快速上手：我不知道从哪开始？

发送以下命令获取帮助或查看插件列表：

```
/权限 帮助
/权限 插件
```

---

## 命令触发词

`/perm` 和 `/权限` 效果完全相同，任选其一。

---

## 子命令一览

> **提示**：不知道插件名？先发 `/权限 插件` 查看所有已注册插件及其命令名。

| 子命令（英文） | 子命令（中文） | 作用 |
|--------------|-------------|------|
| `status` | `查看` | 查看某用户的权限状态 |
| `set` | `设置` | 设置某用户的全局权限级别 |
| `reset` | `重置` | 恢复某用户到默认权限 |
| `allow` | `授权` | 为某用户开放某插件的所有命令 |
| `deny` | `禁止` | 为某用户禁止某插件的所有命令 |
| `clear` | `清除` | 移除对某用户的命令级别覆盖 |
| `list` | `名单` | 查看哪些用户有某插件的权限 |
| `plugins` | `插件` / `插件列表` | 列出所有插件及其命令名 |
| `help` | `帮助` | 显示帮助信息 |

---

## 指定用户的两种方式

### 方式一：直接 @提及（推荐）

在支持 AT 消息的平台（如 QQ）中，直接 @ 对方即可，无需手动输入 ID。

```
/权限 设置 @张三 operator
```

### 方式二：手动填写 `platform:user_id`

适用于无法 @ 到对方的情况：

```
/权限 设置 qq:1919810 operator
```

---

## 权限级别说明

| 级别 | 说明 |
|------|------|
| `owner` | 主人，最高权限，可使用 `/权限` 命令 |
| `operator` | 管理员，可使用大部分机器人功能 |
| `user` | 普通用户（默认） |
| `guest` | 访客，只能使用最基础的功能 |

---

## 使用示例

### 第一步：不知道插件名？先查

```
/权限 插件
```

输出示例：

```
已注册插件及命令列表：

  【greeting_plugin】
    ○ hello

  【notify_plugin】
    ○ notify

使用示例：
  /权限 授权 @用户 greeting_plugin    — 授权该插件的全部命令
  /权限 禁止 @用户 greeting_plugin    — 禁止该插件的全部命令
  /权限 名单 greeting_plugin           — 查看谁有该插件的权限
```

### 查看用户权限

```
/权限 查看 @张三
/perm status qq:1919810
```

### 提升权限为管理员

```
/权限 设置 @张三 operator
```

### 授权某插件

```
/权限 授权 @张三 greeting_plugin
```

### 授权所有插件

```
/权限 授权 @张三 all
```

### 禁止某插件

```
/权限 禁止 @张三 web_search_tool
```

### 清除某插件的授权覆盖（恢复按全局权限判断）

```
/权限 清除 @张三 greeting_plugin
```

### 重置全局权限到默认值

```
/权限 重置 @张三
```

### 查看谁有某插件权限

```
/权限 名单 greeting_plugin
```

---

## 注意事项

- 本命令仅限 `OWNER` 级别用户使用。
- `allow` / `deny` 是命令级别的强制覆盖，优先级高于全局权限。
- `clear` 只删除覆盖记录，不改变全局权限；`reset` 只删除全局权限记录，不影响命令级覆盖。
- 使用 `all` 时会对所有已注册命令（除 perm_plugin 自身）批量操作。
