213 lines
4.6 KiB
Plaintext
213 lines
4.6 KiB
Plaintext
# 指令介绍
|
||
|
||
`konaperm` - 用于查看和修改 Bot 内部权限系统记录的管理员指令
|
||
|
||
## 权限要求
|
||
|
||
只有拥有 `admin` 权限的主体才能使用本指令。
|
||
|
||
## 格式
|
||
|
||
```text
|
||
konaperm list <platform> <entity_type> <external_id> [page]
|
||
konaperm get <platform> <entity_type> <external_id> <perm>
|
||
konaperm set <platform> <entity_type> <external_id> <perm> <val>
|
||
```
|
||
|
||
## 子命令说明
|
||
|
||
### `list`
|
||
|
||
列出指定对象及其继承链上的显式权限记录，按分页输出。
|
||
|
||
参数：
|
||
|
||
- `platform` 平台名，如 `ob11`、`discord`、`sys`
|
||
- `entity_type` 对象类型，如 `user`、`group`、`global`
|
||
- `external_id` 平台侧对象 ID；全局对象通常写 `global`
|
||
- `page` 页码，可省略，默认 `1`
|
||
|
||
### `get`
|
||
|
||
查询某个对象对指定权限的最终判断结果，并说明它是从哪一层继承来的。
|
||
|
||
参数：
|
||
|
||
- `platform`
|
||
- `entity_type`
|
||
- `external_id`
|
||
- `perm` 权限键，如 `admin`、`plugin.xxx.use`
|
||
|
||
### `set`
|
||
|
||
为指定对象写入显式权限。
|
||
|
||
参数：
|
||
|
||
- `platform`
|
||
- `entity_type`
|
||
- `external_id`
|
||
- `perm` 权限键
|
||
- `val` 设置值
|
||
|
||
`val` 支持以下写法：
|
||
|
||
- 允许：`y` `yes` `allow` `true` `t`
|
||
- 拒绝：`n` `no` `deny` `false` `f`
|
||
- 清除：`null` `none`
|
||
|
||
其中：
|
||
|
||
- 允许 表示显式授予该权限
|
||
- 拒绝 表示显式禁止该权限
|
||
- 清除 表示删除该层的显式设置，重新回退到继承链判断
|
||
|
||
## 对象格式
|
||
|
||
本指令操作的对象由三段组成：
|
||
|
||
```text
|
||
<platform>.<entity_type>.<external_id>
|
||
```
|
||
|
||
例如：
|
||
|
||
- `ob11.user.123456789`
|
||
- `ob11.group.987654321`
|
||
- `sys.global.global`
|
||
|
||
## 当前支持的 `PermEntity` 值
|
||
|
||
以下内容按当前实现整理，便于手工查询和设置权限。
|
||
|
||
### `sys`
|
||
|
||
- `sys.global.global`
|
||
|
||
这是系统总兜底对象。
|
||
|
||
### `ob11`
|
||
|
||
- `ob11.global.global`
|
||
- `ob11.group.<group_id>`
|
||
- `ob11.user.<user_id>`
|
||
|
||
常见场景：
|
||
|
||
- 给整个 OneBot V11 平台统一授权：`ob11.global.global`
|
||
- 给某个 QQ 群授权：`ob11.group.群号`
|
||
- 给某个 QQ 用户授权：`ob11.user.QQ号`
|
||
|
||
### `discord`
|
||
|
||
- `discord.global.global`
|
||
- `discord.guild.<guild_id>`
|
||
- `discord.channel.<channel_id>`
|
||
- `discord.user.<user_id>`
|
||
|
||
常见场景：
|
||
|
||
- 给整个 Discord 平台统一授权：`discord.global.global`
|
||
- 给某个服务器授权：`discord.guild.服务器ID`
|
||
- 给某个频道授权：`discord.channel.频道ID`
|
||
- 给某个用户授权：`discord.user.用户ID`
|
||
|
||
### `minecraft`
|
||
|
||
- `minecraft.global.global`
|
||
- `minecraft.server.<server_name>`
|
||
- `minecraft.player.<player_uuid_hex>`
|
||
|
||
常见场景：
|
||
|
||
- 给整个 Minecraft 平台统一授权：`minecraft.global.global`
|
||
- 给某个服务器授权：`minecraft.server.服务器名`
|
||
- 给某个玩家授权：`minecraft.player.玩家UUID的hex`
|
||
|
||
### `console`
|
||
|
||
- `console.global.global`
|
||
- `console.channel.<channel_id>`
|
||
- `console.user.<user_id>`
|
||
|
||
### 快速参考
|
||
|
||
```text
|
||
sys.global.global
|
||
|
||
ob11.global.global
|
||
ob11.group.<group_id>
|
||
ob11.user.<user_id>
|
||
|
||
discord.global.global
|
||
discord.guild.<guild_id>
|
||
discord.channel.<channel_id>
|
||
discord.user.<user_id>
|
||
|
||
minecraft.global.global
|
||
minecraft.server.<server_name>
|
||
minecraft.player.<player_uuid_hex>
|
||
|
||
console.global.global
|
||
console.channel.<channel_id>
|
||
console.user.<user_id>
|
||
```
|
||
|
||
## 权限继承
|
||
|
||
权限不是只看当前对象，还会按继承链回退。
|
||
|
||
例如对 `ob11.user.123456` 查询时，通常会从更具体的对象一路回退到：
|
||
|
||
1. 当前用户
|
||
2. 平台全局对象
|
||
3. 系统全局对象
|
||
|
||
权限键本身也支持逐级回退。比如查询 `plugin.demo.use` 时，可能依次命中：
|
||
|
||
1. `plugin.demo.use`
|
||
2. `plugin.demo`
|
||
3. `plugin`
|
||
4. `*`
|
||
|
||
所以 `get` 返回的结果可能来自更宽泛的权限键，或更上层的继承对象。
|
||
|
||
## 示例
|
||
|
||
```text
|
||
konaperm list ob11 user 123456
|
||
```
|
||
|
||
查看 `ob11.user.123456` 及其继承链上的权限记录第一页。
|
||
|
||
```text
|
||
konaperm get ob11 user 123456 admin
|
||
```
|
||
|
||
查看该用户最终是否拥有 `admin` 权限，以及命中来源。
|
||
|
||
```text
|
||
konaperm set ob11 user 123456 admin allow
|
||
```
|
||
|
||
显式授予该用户 `admin` 权限。
|
||
|
||
```text
|
||
konaperm set ob11 user 123456 admin deny
|
||
```
|
||
|
||
显式拒绝该用户 `admin` 权限。
|
||
|
||
```text
|
||
konaperm set ob11 user 123456 admin none
|
||
```
|
||
|
||
删除该用户这一层对 `admin` 的显式设置，恢复继承判断。
|
||
|
||
## 注意事项
|
||
|
||
- 这是系统级管理指令，误操作可能直接影响其他插件的权限控制。
|
||
- `list` 只列出显式记录；没有显示出来不代表最终一定无权限，可能是从上层继承。
|
||
- `get` 显示的是最终命中的结果，比 `list` 更适合排查“为什么有/没有某个权限”。
|
||
- 对 `admin` 或 `*` 这类高影响权限做修改前，建议先确认对象是否写对。
|