代理诊断工具包

一款供 Minecraft 模组作者使用的开发工具。 这不是一个游戏模组。 它不会添加物品、方块、配方，世界中也找不到任何内容。

它是为正在开发 Minecraft 模组的人准备的。 单独使用时，它也能完美工作，可以作为设置测试场景的一种方式，无需每次都输入相同的八条命令。 但其主要目的是帮助 AI 编码助手不再依赖开发者描述屏幕上发生的内容，而是将游戏实际执行的操作以程序可读的形式写入日志。

它通过以下方式实现：

• 准备一个测试场地
• 打包命令，以便一步完成场景设置
• 将世界中发生的事件记录到日志中
• 按需报告玩家、实体和方块的状态

它记录的所有内容都发生在服务器端，因此日志也在服务器端。 在单人游戏中，只需安装它即可。 命令需要操作员权限； 使用 /devtool help 可列出所有命令。

如果你正在使用 AI 助手，请让它查看 AGENTS.md 文件。 该文件会告诉它这个工具包能做什么，如何保持日志可读，以及在浪费一次测试运行之前需要了解的注意事项。

如果你是自己阅读，请从 README.md 开始，然后是 docs/commands.md 获取完整命令列表。

AI 使用声明： 此模组是使用 AI 代理协助开发的，采用了此代理工作流。 项目所有者在开发过程中审核了工作成果。

它的功能

测试场地。 一条命令即可构建一个封闭、明亮、空无一物的盒子，大小可任意指定。 重置它会清除内部所有东西并修复墙壁，并且每次尝试开始时运行都是安全的。 在里面死亡会将你送回场地，而不是你的床。

命令捆绑。 将一系列命令放入一个 JSON 文件中，用一条命令运行它。 支持命令之间的延迟、失败时停止，并且一个捆绑包可以调用另一个。 它们存在于你的配置文件夹中，而不是世界存档中，因此它们可以在创建新的测试世界后继续存在。

事件日志。 八种游戏事件，默认全部关闭，你可以单独开启，并可将每个事件限制在场地内或特定半径内，以保持日志清晰易读。

检查。 按需将玩家、实体、方块、物品栏或原始 NBT 报告为结构化文本。

会话和标记。 为一次运行命名，并在日志中放置带标签的书签，以便稍后找到有趣的部分。

自我报告。 询问模组它实际支持什么。 答案来自正在运行的构建版本，而不是可能过时的文档。

示例

设置可重复的运行

假设你正在测试当方块被放置时你的模组会做什么。

将此内容放入 config/devtool/bundles/mytest.json：

{
  "block_test": {
    "commands": [
      "devtool arena reset",
      "gamerule doMobSpawning false",
      "devtool log block_place on arena",
      "devtool session start block_test",
      "devtool mark READY"
    ]
  }
}

然后，每次你想要进行干净运行时：

/devtool run block_test

这会清空场地，阻止怪物进入，开始仅记录场地内的方块放置事件，并放置一个书签。 放置一个方块，日志将显示如下：

[DevToolkit][BLOCK_PLACE] side=SERVER worldTick=19051 block=minecraft:log meta=0
dimension=0 posX=177 posY=69 posZ=262 blockState=minecraft:log[axis=y,variant=oak]
placedBy=Developer placedById=928

一行，形状始终相同，位于 latest.log 中，紧挨着你自己的模组输出和 Forge 输出。 你的助手无需你描述任何内容就能读取它。

用于测试的场地

/devtool arena create 20 10 20

构建一个密封、明亮、空无一物的盒子，大小为二十格见方，以你站立的位置为中心，地板与你的脚齐平。 照明充足，内部不会生成任何东西。 你的重生点也会随之移动，因此测试中途死亡不会将你送回你的床。

每个维度一个，保存在世界存档中。 之后：

/devtool arena reset

修复你破坏的任何东西，清除所有怪物、掉落物品和杂散方块，并将你放回起始位置。 每次尝试开始时运行都是安全的，因为运行两次的结果与运行一次相同。

登录时自动运行你的设置

设置位于 config/devtool/devtool.cfg 中：场地默认设置、建造场地所用的方块、写入多少 NBT 后会被截断，以及以下内容。 任何可能未经请求就改变你的世界或设置的功能，在你主动开启之前都是关闭的。

join {
    B:enabled=true
    S:bundle=block_test
}

现在，每当操作员加入游戏时，该捆绑包就会运行。 登录后世界已准备就绪：场地已清理，怪物已关闭，记录已开始。 默认关闭，捆绑包名称默认为空，因此安装此模组本身不会改变任何内容。

询问世界中的内容

/devtool entities nearby 20
/devtool inspect entity @e[name=target]
/devtool nbt held

每条命令都会将结构化行写入日志而不是聊天中，因此助手可以直接读取答案，而无需你重新输入。