调试与问题解决指南

┌─────────────────────────────────────────────┐
│  第一步：复现问题                             │
│  - 问题能稳定复现吗？                         │
│  - 在什么条件下触发？                         │
└─────────────────┬───────────────────────────┘
                  ▼
┌─────────────────────────────────────────────┐
│  第二步：收集信息                             │
│  - 控制台报错信息（完整复制！）               │
│  - 服务器日志（latest.log）                  │
│  - 操作步骤记录                               │
└─────────────────┬───────────────────────────┘
                  ▼
┌─────────────────────────────────────────────┐
│  第三步：定位问题类型                         │
│  - 编译错误？运行时错误？功能性 Bug？         │
│  - 查看本章对应章节                           │
└─────────────────┬───────────────────────────┘
                  ▼
┌─────────────────────────────────────────────┐
│  第四步：使用 Prompt 模板向 AI 提问            │
│  - 复制对应章节的模板                         │
│  - 填入你的具体信息                           │
└─────────────────┬───────────────────────────┘
                  ▼
┌─────────────────────────────────────────────┐
│  第五步：验证修复                             │
│  - 重新构建并测试                            │
│  - 确认问题已解决且没有引入新问题              │
└─────────────────────────────────────────────┘

error: unresolved reference: getRebarItem
error: cannot find symbol: class CustomItemStack
error: Unresolved reference: onRightClick

// ❌ AI 生成的错误代码（使用了不存在的 API）
@EventHandler
fun onPlayerClick(event: PlayerInteractEvent) {
    val player = event.getPlayer()  // Bukkit 风格
    val item = event.getItem()      // 这个方法可能不存在
    if (item.getType() == Material.DIAMOND) {
        player.sendMessage("你拿着钻石！")
    }
}

// ✅ 正确的 Rebar 写法
@EventHandler
fun onPlayerClick(event: PlayerInteractEvent) {
    val player = event.player       // Kotlin 风格
    val item = event.item ?: return // 安全调用
    // 使用 Rebar 的物品系统进行判断
}

## 问题

编译时报错：[粘贴完整的错误信息]

## 项目背景

- 这是一个 Rebar 附属项目
- 请只使用 Rebar 提供的 API，不要使用 Bukkit/Paper 的原生 API
- 参考代码在 .trae/guide/ 目录下

## 要求

1. 找出导致编译错误的代码
2. 将其替换为正确的 Rebar API 调用
3. 说明为什么原来的写法是错的
4. 如果某个 API 你不确定是否存在，请明确标注出来

error: cannot find symbol: class RebarApi
error: module not found: io.github.pylonmc:rebar
Could not resolve: files-2.1/io/github/pylonmc/rebar/...

// AI 可能生成这样的混乱代码：
class MyAddon : JavaPlugin() {           // 继承 JavaPlugin？
    private var config: FileConfiguration? = null  // Java 风格
    
    fun onLoad() {                        // 方法命名
        config = this.config              // this 可省略
    }
    
    fun onEnable(): Boolean {             // 返回值类型？
        println("插件已启用")             // 应该用 logger
        return true
    }
}

请统一使用以下代码风格：
- 使用 Kotlin 惯用法（不要写 Java 风格的 Kotlin）
- 省略不必要的 this 引用
- 使用属性委托简化代码
- 使用扩展函数而不是工具类
- 遵循 Rebar 官方示例的命名规范

[12:34:56 ERROR]: [MyAddon] Could not pass event PlayerInteractEvent to MyAddon v1.0
java.lang.NullPointerException: Cannot invoke "String.length()" because "<local1>" is null
    at com.example.myaddon.MyListener.onPlayerInteract(MyListener.kt:23)
    at org.bukkit.plugin.java.JavaPluginLoader$1.execute(...)

## 运行时空指针异常

### 错误信息

### 出错代码（第 X 行附近）
```kotlin
// 粘贴出错位置的代码片段

### ClassCastException（类型转换异常）

当你尝试把一个对象强制转换为不兼容的类型时，就会抛出这个异常。

#### Rebar 中的正确类型转换方式

```kotlin
// ❌ 危险的直接强转
val myItem = item as MyCustomItem  // 如果 item 不是 MyCustomItem 就会崩溃

// ✅ 安全的类型转换
val myItem = item as? MyCustomItem  // 转换失败返回 null
if (myItem != null) {
    // 安全地使用 myItem
}

// ✅ 使用 when 进行类型判断
when (item) {
    is MyCustomItem -> { /* 处理 */ }
    is AnotherItem -> { /* 处理 */ }
    else -> { /* 其他情况 */ }
}

// 在传入参数前添加校验
require(probability in 0.0..1.0) { "概率必须在 0~1 之间，当前值: $probability" }
require(amount in 1..64) { "物品数量必须在 1~64 之间，当前值: $amount" }

// 或者使用协程返回 Result
fun safeCreateItem(amount: Int): Result<ItemStack> {
    return if (amount in 1..64) {
        Result.success(createItemInternal(amount))
    } else {
        Result.failure(IllegalArgumentException("无效的数量: $amount"))
    }
}

// 检查你的主类中是否有这行代码：
server.pluginManager.registerEvents(MyListener(), this)
//                                              ^^^^ 必须是 plugin 实例

@EventHandler
fun onPlayerInteract(event: PlayerInteractEvent) {
    // 添加这些日志来追踪问题
    logger.info("事件触发！Action: ${event.action}, Item: ${event.item}")
    
    if (event.action == Action.RIGHT_CLICK_AIR || event.action == Action.RIGHT_CLICK_BLOCK) {
        logger.info("是右键操作，继续处理...")
        
        val item = event.item ?: run {
            logger.info("物品为空，跳过")
            return
        }
        
        logger.info("物品类型: ${item.type}, 名称: ${item.displayName}")
        
        // 你的逻辑...
    }
}

# 期望看到的日志：
[INFO] 事件触发！Action: RIGHT_CLICK_AIR, Item: ItemStack{...}
[INFO] 是右键操作，继续处理...
[INFO] 物品类型: xxx, 名称: 我的自定义物品

# 如果只看到第一行，说明 Action 判断有问题
# 如果看到"物品为空"，说明 item 获取方式有问题
# 如果都正常但还是没反应，说明是你的业务逻辑有问题

## 功能性 Bug：右键无反应

### 问题描述
玩家手持自定义物品右键时，没有任何反应（预期应该触发 XXX 效果）

### 已确认的信息
- ✅ 物品可以正常获取和使用
- ✅ 插件已成功加载（无加载错误）
- ❓ 事件是否被触发：未知

### 当前的事件监听代码
```kotlin
// 粘贴你的事件监听代码

// 粘贴监听器注册的代码

### "概率不对，总是出同一个东西"

#### 可能的原因

1. **随机种子固定**：每次启动使用相同的 Random 实例
2. **概率计算错误**：累积概率算法写错了
3. **配置读取错误**：概率值读成了默认值
4. **缓存问题**：结果被缓存了，没有重新计算

#### 排查步骤

```kotlin
// 检查 1：Random 实例是否正确创建
private val random = Random(System.currentTimeMillis())  // ✅ 基于时间
// private val random = Random(12345)                     // ❌ 固定种子

// 检查 2：概率算法是否正确
fun rollItem(): String {
    val roll = random.nextDouble()
    var cumulative = 0.0
    for ((item, prob) in dropTable) {
        cumulative += prob
        if (roll <= cumulative) {
            return item
        }
    }
    return dropTable.last().first  // 兜底
}

// 添加日志验证
logger.info("Roll: $roll, 结果: ${rollItem()}")

// 使用 System.currentTimeMillis() 而不是 tick 计数
var startTime: Long = 0

@EventHandler
fun onPlayerInteract(event: PlayerInteractEvent) {
    when (event.action) {
        Action.RIGHT_CLICK_AIR, Action.RIGHT_CLICK_BLOCK -> {
            if (!isHolding) {
                startTime = System.currentTimeMillis()
                isHolding = true
                logger.info("开始长按: $startTime")
            }
        }
        else -> {
            if (isHolding) {
                val duration = System.currentTimeMillis() - startTime
                logger.info("长按结束，持续时间: ${duration}ms")
                // 处理长按结果...
                isHolding = false
            }
        }
    }
}

# 1. 重载配置
/reload
# 或者如果插件支持的话
/myaddon reload

# 2. 查看当前加载的配置（需要在代码中添加调试命令）
/myaddon debug config

# 3. 检查配置文件位置
ls -la plugins/YourAddon/
cat plugins/YourAddon/config.yml

/spark tps

# 输出示例：
# ┃ TPS (m=19.97, t=20.00) MSPT (m=42.91, p99=48.21)
#
# 解读：
# - m=19.97: 平均 TPS（20 为完美）
# - t=20.00: 目标 TPS
# - m=42.91: 平均每 tick 毫秒数（50ms 为正常）
# - p99=48.21: 99% 分位的毫秒数

## Bug 描述

**现象**：玩家使用自定义筛子右键泥土时，应该有 30% 概率掉落钻石，
但实际上 100 次测试中没有一次掉落钻石。

**重现步骤**：
1. 给玩家自定义筛子 x1
2. 手持筛子，对着泥土方块右键
3. 观察掉落物

**预期行为**：30% 概率掉落钻石
**实际行为**：从未掉落过钻石（0/100）

**环境**：
- Minecraft 1.20.4
- Paper build 123
- Rebar x.y.z
- 我的附属 v0.1

**相关代码**：
[粘贴关键的代码片段]

**日志**：
[粘贴相关的日志输出]

我的插件坏了，概率不对，帮忙看看

✅ 完整的异常类型和消息
✅ 堆栈跟踪中与你代码相关的行
✅ 异常发生的时间戳
✅ 异常发生前的相关日志
✅ 插件版本和服务器版本

❌ 与你的插件无关的其他插件报错
❌ 几百行的重复日志
❌ 包含敏感信息的日志（IP、token 等）
❌ 截图中的日志（无法搜索和复制）

## 服务器日志

### 时间范围
从 [开始时间] 到 [结束时间]

### 关键日志

### 完整异常

【求助】自定义物品右键事件未触发

**环境**：MC 1.20.4 / Paper build 123 / Rebar 1.2.3

**问题描述**：
我创建了一个自定义筛子物品，希望玩家右键时触发筛选效果。
目前物品可以正常获取，但右键没有任何反应。

**已尝试**：
✅ 确认监听器已注册（server.pluginManager.registerEvents）
✅ 确认使用的是 RIGHT_CLICK_AIR 和 RIGHT_CLICK_BLOCK
❓ 添加了调试日志但未看到任何输出（怀疑事件未被触发）

**代码链接**：（如果是公开仓库可以贴链接，否则贴代码片段）

**日志**：（粘贴关键日志）

有人帮我看看吗，插件不工作 😭

## Bug 描述
清晰描述这个 bug 是什么

## 重现步骤
1. 去 '...'
2. 点击 '....'
3. 向下滑动 '...'
4. 看到错误

## 期望行为
描述你认为应该发生什么

## 截图
如果适用，添加截图来解释问题

## 环境
- OS: [e.g. Ubuntu 22.04]
- Minecraft version: [e.g. 1.20.4]
- Server software: [e.g. Paper build 123]
- Rebar version: [e.g. 1.2.3]

## 附加信息
这里可以添加其他相关信息

你的服务器目录/
├── logs/
│   ├── latest.log          # 最新的日志（实时更新）
│   ├── YYYY-MM-DD-x.log.gz # 历史日志（压缩存档）
│   └── debug.log           # 调试日志（如果启用）
└── ...

[12:34:56 INFO]: [MyAddon] 插件已启用 v1.0.0
[12:34:57 WARN]: [MyAddon] 配置文件未找到，使用默认配置
[12:34:58 ERROR]: [MyAddon] 发生错误: java.lang.NullPointerException
 │           ├─ 时间戳     │  ├─ 日志级别    │  ├─ 来源      │  ├─ 消息内容

# 实时查看最新日志（推荐）
tail -f logs/latest.log

# 搜索特定插件的日志
grep "\[MyAddon\]" logs/latest.log

# 搜索错误日志
grep "ERROR" logs/latest.log

# 查看最近 100 行
tail -n 100 logs/latest.log