# 指令介绍

`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` 或 `*` 这类高影响权限做修改前，建议先确认对象是否写对。
