koishi-plugin-best-jrrp/readme.md

支持真随机的今日人品（运势），可任意自定义消息，支持随机图片，还带有排行、分析、货币等功能。

# koishi-plugin-best-jrrp

[![npm](https://img.shields.io/npm/v/koishi-plugin-best-jrrp?style=flat-square)](https://www.npmjs.com/package/koishi-plugin-best-jrrp)

支持真随机的今日人品（运势），可任意自定义消息，支持随机图片，还带有排行、分析、货币等功能。

## 功能特性

- **多种计算算法**：支持线性同余、正态分布，以及基于大气噪声的 Random.org 真随机 API。
- **丰富的显示格式**：人品值可以显示为二进制、八进制、十六进制，甚至是动态生成的数学表达式。
- **高度自定义消息**：可配置不同分数范围、特定分数或特定日期的消息。消息模板支持多种占位符，包括 at 用户、一言、本地/网络图片等。
- **灵活的货币系统**：与 `koishi-plugin-monetary` 深度联动，可通过一个简单的规则输入框，实现固定值、随机范围、人品值倍率等多种复杂的奖惩逻辑。
- **全面的数据查询**：支持查询特定日期的人品值（支持自然语言，如“昨天”），或预测未来特定分数将在哪天出现。
- **排行榜与数据分析**：查看今日人气之星，并通过深度统计报告（如走势图、分布热图）分析个人运气走势。
- **灵活的数据管理**：管理员可以按用户或日期（支持自然语言）清除人品数据。

## 命令列表

- `jrrp` - 获取今日人品值。首次使用可获得货币奖励。
- `jrrp.date [date:date]` - 查询指定日期的人品值（支持 "MM-DD", "YYYY-MM-DD", "昨天" 等格式）。
- `jrrp.score [score]` - 预测未来何时会出现指定的人品分数（真随机模式下禁用）。
- `jrrp.rank` - 查看今日人品排行榜。
- `jrrp.analyse` - 分析你的人品数据统计信息。
- `jrrp.clear` - 清除人品数据（需要4级权限）。

## 配置说明

插件配置主要分为基础配置、样式配置、消息配置和强大的货币配置。

### 1. 基础配置

```yaml
# 启用日期查询
enableDate: true
# 启用人品预测
enableScore: true
# 启用人品排行
enableRank: true
# 启用数据分析
enableAnalyse: true
# 计算方式: gaussian(正态分布)/linear(线性同余)/randomorg(真随机)
algorithm: linear
# 密钥 - Random.org (使用真随机时需填写)
apiKey: ''
```

### 2. 样式配置

```yaml
# 是否启用数值格式化
enableScoreFormat: true
# 仅在指定日期启用格式化 (MM-DD格式, 留空则始终启用)
formatDate: '4-1'
# 格式化样式: binary(二进制)/octal(八进制)/hex(十六进制)/simple(简单表达式)/complex(复杂表达式)
scoreFormat: 'simple'
```

### 3. 消息配置

```yaml
# 消息内容 (支持 {money} 等占位符)
template: '{at}你今天的人品值是：{score}{message}'
# 图源地址 (可以是网络JSON链接或本地文件夹路径)
imagesPath: 'https://raw.githubusercontent.com/YisRime/koishi-plugin-onebot-tool/main/resource/pixiv.json'
# 启用区间消息
enableRange: true
# ... 区间消息与特殊消息配置 ...```

### 4. 货币配置 (`koishi-plugin-monetary` 联动)

```yaml
# 启用货币支持
enableMonetary: false
# 签到奖励
rewardRule: '50-150'
# 启用累签惩罚
enableRepeatPenalty: false
# 累签惩罚
penaltyRule: '50'
```

## 货币系统详解

本插件可通过 `rewardRule` 和 `penaltyRule` 两个配置项，实现高度灵活的奖惩逻辑。

### 规则语法

您可以在规则输入框中使用以下任意一种格式：

| 格式 | 示例 | 说明 |
| :--- | :--- | :--- |
| **固定值** | `50` | 奖励或惩罚一个固定的数值。奖励规则中可使用负数，如 `-50`。 |
| **随机整数范围** | `50-100` | 在指定的两个整数之间（包含边界）随机取一个值。 |
| **固定倍率** | `1.5x` | 基于当前获得的人品分数，乘以一个固定的倍率。 |
| **随机倍率范围** | `0.5x-1.5x` | 基于人品分数，乘以一个在指定范围内的随机倍率。 |

### 工作机制

- **`rewardRule` (奖励规则)**: 当用户当天**第一次**使用 `jrrp` 命令时触发。
  - 示例: 设置为 `1.5x`，用户人品值为 80，则奖励 `80 * 1.5 = 120` 货币。
- **`penaltyRule` (惩罚规则)**: 当用户在同一天**重复**使用 `jrrp` 命令时触发。
  - 规则计算出的值将**自动转为负数**进行扣除。
  - 示例: 设置为 `50-100`，用户重复签到，将被随机扣除 50 到 100 的货币。
  - **注意**: 扣除操作会检查用户余额，若余额不足，则不会执行。

## 算法详解

### 线性同余算法 (linear)

默认算法。使用线性同余生成器，通过一个简单的哈希函数（基于用户ID和日期）生成伪随机数。计算速度快，分布均匀。

### 正态分布算法 (gaussian)

使用正态分布（高斯分布）进行计算。生成的分数会更倾向于聚集在中间值（50）附近，而两端（0和100）的极值出现的概率较低。

### Random.org API (randomorg)

通过调用 Random.org 的 API 获取基于大气噪声的真随机数。

- **需要提供有效的 API 密钥**。
- 当 API 请求失败或超时时，会自动降级使用**线性同余算法**。
- 在此模式下，`jrrp.day` 和 `jrrp.score` 命令将被禁用，因为真随机数是无法预测的。

## 消息配置

消息模板 (`template`) 支持丰富的占位符：

- `{at}`: @当前用户。
- `{username}`: 当前用户的昵称。
- `{score}`: 经过格式化后的人品分数值。
- `{message}`: 根据分数和日期匹配到的区间或特殊消息。
- `{money}`: 显示本次操作中获得的奖励（正数）或惩罚（负数）。若无货币变动，则此占位符被移除。
- `{hitokoto}`: 从 `v1.hitokoto.cn` 获取一句话。
- `{image:URL}`: 发送指定 URL 的图片。
- `{pixiv}`: 发送一张来自 `imagesPath` 的随机图片。
- `{~}`: 消息分隔符，可将一条消息分段发送。