> For the complete documentation index, see [llms.txt](https://spiter.gitbook.io/spiter/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://spiter.gitbook.io/spiter/spiter-8.0/quan-xian-wen-dang.md).

# 权限文档

***

### 一、权限总览 <a href="#yi-quan-xian-zong-lan" id="yi-quan-xian-zong-lan"></a>

| 权限节点                            | 一句话作用                             | 谁需要      |
| ------------------------------- | --------------------------------- | -------- |
| `spiter.command`                | 使用所有 `/spiter` 系列指令的总开关           | 管理员      |
| `spiter.alerts`                 | 实时接收作弊检测报警                        | 管理员      |
| `spiter.notify`                 | 接收"静默观察"通知（更低调）                   | 管理员      |
| `spiter.verbose`                | 开发模式下查看每条检测的详细日志                  | 开发者      |
| `spiter.freeze`                 | 冻结/解冻玩家                           | 管理员      |
| `spiter.cps.left`               | 绕过左键 CPS 速率限制                     | 白名单玩家    |
| `spiter.cps.right`              | 绕过右键 CPS 速率限制                     | 白名单玩家    |
| `spiter.bypass`                 | 完全不被检测                            | 高信任玩家    |
| `spiter.debug`                  | 聊天栏查看调试输出                         | 开发者      |
| `spiter.punishment.<groupName>` | 选用 `punishment.yml` 里指定 group 的规则 | 高级玩家分组管理 |

***

### 二、`spiter.command` <a href="#er-spiter.command" id="er-spiter.command"></a>

**是什么**：所有 `/spiter` 子指令的**总闸门**。

**附加条件**：即便你拥有此权限，**还必须在配置文件 `admin` 名单里**才会真正生效。两项必须同时满足。

***

### 三、`spiter.alerts` <a href="#san-spiter.alerts" id="san-spiter.alerts"></a>

**是什么**：实时接收作弊检测报警

**何时检查 / 何时加载**：

* **进服时**：如果同时在 admin 名单且拥有此权限，会自动订阅报警（受配置 `enable_alerts_on_join` 控制）
* **运行中**：通过 `/spiter alerts` 切换开关状态

**使用感受**：开 → 看到红字报警；关 → 不再接收。

**注意**：与 `spiter.notify` **互斥**——开 alerts 会自动关 notify，反之亦然。

***

### 四、`spiter.notify` <a href="#si-spiter.notify" id="si-spiter.notify"></a>

**是什么**：与 `spiter.alerts` 同源但更"低调"的另一条推送通道。专用于**暗中摸排疑似作弊者**，不广播、不踢人。

**何时检查 / 何时加载**：

* 运行时通过 `/spiter notify` 切换
* 进服时，特定玩家会被强制加入此通道（开发通道，正式上线前请配置化）

**使用感受**：和 alerts 互斥，开启 notify 时会从 alerts 列表移除。

***

### 五、`spiter.verbose` <a href="#wu-spiter.verbose" id="wu-spiter.verbose"></a>

***

### 六、`spiter.freeze` <a href="#liu-spiter.freeze" id="liu-spiter.freeze"></a>

**是什么**：对目标玩家施加"冻结"状态。

**何时检查 / 何时加载**：

* 执行 `/spiter freeze add/remove <玩家>` 时检查权限

**被冻结玩家的体验**：

* 🚫 不能移动（移动会被强制拉回原位）
* 🚫 不能受任何伤害
* 🚫 不能使用物品（喝药水、吃食物）
* 🚫 不能射箭

**典型用法**：管理员发现疑似作弊者但还在观察，先 freeze 防止他继续操作，避免误踢后无证据。

***

### 七、`spiter.cps.left` / `spiter.cps.right` <a href="#qi-spiter.cps.leftspiter.cps.right" id="qi-spiter.cps.leftspiter.cps.right"></a>

**是什么**：绕过左键 / 右键的 CPS（每秒点击次数）速率限制。

**何时检查 / 何时加载**：

* 每次点击事件触发时检查
* **前提**：配置 `cps_limit_left_enable: true`（或 `right`）开关必须打开，否则权限无效

**典型人群**：建筑党、连点党、PK 高手。

***

### 八、`spiter.bypass` <a href="#ba-spiter.bypass" id="ba-spiter.bypass"></a>

**是什么**：让该玩家在 Spiter 眼里**完全隐身**——所有检测项都不会作用于他。

**何时检查 / 何时加载**：

* 玩家登录时一次性写入，整个会话保持不变

**重要依赖**：本权限**必须配合**配置 `player_bypass: true` 才生效。两个开关同时为 true 才会真正绕过。

***

### 九、`spiter.debug` <a href="#jiu-spiter.debug" id="jiu-spiter.debug"></a>

***

### 十、`spiter.punishment.<groupName>` <a href="#shi-spiter.punishment.groupname" id="shi-spiter.punishment.groupname"></a>

\
**关联权限插件命令**：`/lp user <玩家> permission set spiter.punishment.<名字> true`

#### 10.1 是什么 <a href="#id-10.1-shi-shen-me" id="id-10.1-shi-shen-me"></a>

根据权限尾段，从 `punishment.yml` 中选取对应的 **group（一套独立的"违规→惩罚"规则）** 作为该玩家的惩罚阈值。

把一个 group 名字赋给玩家权限 `spiter.punishment.<名字>`，该玩家就使用这套规则。 **`default` 组是兜底**：没有任何 `spiter.punishment.*` 权限的玩家都进这里。

#### 10.2 何时检查 / 何时加载 <a href="#id-10.2-he-shi-jian-cha-he-shi-jia-zai" id="id-10.2-he-shi-jian-cha-he-shi-jia-zai"></a>

* **玩家进服时**一次性匹配
* **配置热重载时**重新匹配
* 玩家没有 `spiter.punishment.*` 任意权限 → 直接用 `default` 组

#### 10.3 匹配规则 <a href="#id-10.3-pi-pei-gui-ze" id="id-10.3-pi-pei-gui-ze"></a>

从 `punishment.yml` 的 group 列表里**逐个试**，首个命中的就用它的规则。 所以权限名要尽量精确，不要给一个玩家同时下发 `spiter.punishment.vip` 和 `spiter.punishment.staff`。

#### 10.4 group 命名约束 <a href="#id-10.4group-ming-ming-yue-shu" id="id-10.4group-ming-ming-yue-shu"></a>

* 必须与 `punishment.yml` 里的 group 名字**完全一致**
* 建议小写无空格（合法字符 `a-z 0-9 . _ -`）
* `default` 必须存在

#### 10.5 字段说明 <a href="#id-10.5-zi-duan-shuo-ming" id="id-10.5-zi-duan-shuo-ming"></a>

| 字段               | 含义                                    | 是否必填 |
| ---------------- | ------------------------------------- | ---- |
| `check`          | 触发本惩罚的 check 名称列表，支持通配 `*` 和否定 `!xxx` | ✅    |
| `decay.interval` | 每隔多少 秒 把 VL 衰减一次                      | ✅    |
| `decay.amount`   | 每次衰减扣多少 VL                            | ✅    |
| `intervals`      | VL 到达阈值时执行的动作（一次性触发）                  | ✅    |
| `loop`           | 周期性动作                                 | ✅    |

#### 10.6 动作前缀 <a href="#id-10.6-dong-zuo-qian-zhui" id="id-10.6-dong-zuo-qian-zhui"></a>

| 前缀             | 作用                        | 示例                                   |
| -------------- | ------------------------- | ------------------------------------ |
| `[notify]`     | 发给所有开启 alerts/notify 的管理员 | `[notify] %prefix%%player% 疑似 reach` |
| `[command]`    | 以控制台身份执行指令                | `[command] kick %player% 检测`         |
| `[mitigation]` | 启用内置反制（如取消伤害/反弹）          | `[mitigation] attack_damage`         |

***

### 十一、配置联动表 <a href="#shi-yi-pei-zhi-lian-dong-biao" id="shi-yi-pei-zhi-lian-dong-biao"></a>

有些权限**单独下发没意义**，必须配合配置文件开关才起作用：

| 权限                 | 依赖配置                           | 含义             |
| ------------------ | ------------------------------ | -------------- |
| `spiter.bypass`    | `player_bypass: true`          | 总闸：关 → 权限无效    |
| `spiter.cps.left`  | `cps_limit_left_enable: true`  | 左键 CPS 限速开关    |
| `spiter.cps.right` | `cps_limit_right_enable: true` | 右键 CPS 限速开关    |
| `spiter.alerts`    | `enable_alerts_on_join: true`  | 进服时自动开启 alerts |
| `spiter.command`   | `hide_spiter: true`            | 是否对无权限玩家隐藏命令   |
| `spiter.verbose`   | Spiter 全局 `devMode`            | 开发模式总开关        |
| `spiter.debug`     | Spiter 全局 `devMode`            | 开发模式总开关        |

***