Minecraft 机器人 Ruqii/dsh-minecraft

dsh-minecraft

在 DeepSeek Harness 里玩 Minecraft。智能体通过一个实时运行的 Mineflayer 机器人加入真实服务器，用工具来看、走路和挖矿。

dsh plugin --profile <name> add dsh-minecraft

十二个工具

| 工具 | 作用 |
| mc_connect | 加入服务器。默认 127.0.0.1:25565。 |
| mc_observe | 位置、生命、饥饿、物品栏、附近的方块和实体——外加自上次观察以来发生的事。 |
| mc_find | 某类方块中最近的暴露方块，带坐标。 |
| mc_goto | 走到某处，寻路时绕开障碍。 |
| mc_dig | 破坏方块并捡起掉落物。 |
| mc_craft | 用物品栏里已有的材料合成物品。 |
| mc_place | 把物品栏里的方块放到世界里。 |
| mc_equip | 手持指定物品——挖掘用的是手上的东西。 |
| mc_smelt | 在已经摆好的熔炉里熔炼，燃料由你指定。 |
| mc_attack | 挥击近战范围内最近的某类实体。 |
| mc_eat | 吃掉携带的食物，然后换回原来手持的物品。 |
| mc_disconnect | 离开，并结束录制。 |

给一句话——获得一把铁镐——智能体会自己理出木板、木棍、工作台、木镐、圆石、石镐、铁矿石、熔炉和熔炼，大约十二分钟搞定。这一整套流程都不在插件里。

每个工具只暴露一个游戏动作。它们都不做规划，也都不修复错误。mc_craft 在范围内没有工作台时会失败并说明原因——它不会悄悄放一个。它会报告缺哪些材料——它不会去帮你拿。没有 mc_get_diamond，以后也不会有。

这不是为了纯粹。评测衡量的是参赛者没有被给予的东西。如果配方链住在插件里，评测就不再衡量智能体会不会玩，而是开始衡量这个插件有多好——每个装了它的参赛者得分都一样。

不允许穿墙看东西

如果你在搭自己的东西，这部分值得抄。

Mineflayer 读的是客户端那份世界副本，所以每次方块查询默认都是透视。findBlocks 直接遍历原始区块段数据，完全不做视线检测。出生点附近，半径 32：

coal_ore 303 hits iron_ore 30 hits

每一个都埋在实心岩石下面。获得钻石的全部难度就在于不知道它在哪——挖到 Y-59，鱼骨挖矿，碰运气。一个用查询就能回答这个问题的工具，不会让智能体变成更好的玩家。它直接删掉了任务。

所以只有至少有一个面没被盖住的方块才会被报告，这大致就是玩家走过一个开口时能看到的。对着实时世界测，过滤与不过滤对比：

coal_ore 303 -> 0 grass_block 400 -> 400
iron_ore 30 -> 0 stone 400 -> 99

埋着的矿石没了；地表感知没动。同样的过滤也适用于 mc_observe 的方块普查也有同样的漏洞。

这是欺骗的下限，不是视觉的模型。 没人去过的洞穴里，暴露的接缝照样会被报告。真正的视线检测会更严格——而且还会让智能体记不住自己路过什么，这未必就对。

mc_observe 会报告你错过了什么

智能体只在工具运行时才醒着，而世界在这期间一直在动。所以观察会排空一个小日志，里面是上一次查看以来累积的事件——受到的伤害、死亡、被踢：

at 6, 64, -8 on grass_block -- health 14, food 20, overworld
inventory: spruce_log x3
blocks within reach: dirt x165, grass_block x80, spruce_leaves x31
entities: zombie 6.2m
since you last looked: health 14, food 20

没有这一行，智能体走上一分钟，到达时只剩 14 点生命值，却不知道为什么。

看它玩

默认开启。连上后，机器人会报告一个链接：

watch live at http://localhost:3017

打开它，你就能透过机器人的眼睛看它玩。不用配置，不用文件，不用 ffmpeg。MC_VIEW=off 可以关掉；如果 3017 端口被占用，端口会往上移。

它会自己构建原生模块

prismarine-viewer 需要 canvas，而 DSH 配置档安装插件依赖时不运行安装脚本——所以包到手时是完整的，唯独缺了那个关键的二进制文件：

Cannot find module '../build/Release/canvas.node'

早先的版本会打印这行，让你去跑 npm rebuild canvas，然后放弃。让用户去跑一条代码自己就能跑的命令，还是为了用户主动要的功能，这就是个附带了说明书的 bug——所以它自己跑了。大约三秒，只跑一次，跑的时候会说 (built the canvas module first)。

录制 mp4

看，对人来说就够了。评测板要的是文件，没有视频的运行不管走多远都记 0.0 分。

MC_RECORD_DIR=/somewhere dsh --profile <name> "...play..."

帧从同一个实时视图经无头 Chrome 截取，由 ffmpeg 在 mc_disconnect 时封装。outcome.json 是持续写入的，所以运行在时限内被杀掉时，帧目录和报告都还在——大多数限时运行都是这个下场。

| 变量 | 作用 |
| MC_RECORD_DIR | 写入 frames/、run.mp4 和 outcome.json 的位置。不设置就只开实时视图。 |
| MC_SEED | 记录进 outcome.json；插件读不到服务商的种子。 |
| CHROME_PATH | 默认是 macOS 的 Google Chrome 路径。 |
| MC_VIEW | off 关闭实时视图。 |
| MC_ONE_LIFE | 1 在第一次死亡时结束运行——见下文。 |

一条命

one_life 榜按第一次死亡前到达的层级计分。Minecraft 不会因为你死了就停下——你就地重生——所以没有这条规则，它只是个计分约定，智能体可以在第二条命里刷到钻石。

MC_ONE_LIFE=1 让它变成真的。第一次死亡后，所有动作工具都会拒绝执行，并说明已经达到的进度；mc_observe 仍然可用，智能体能看到发生了什么；结果里带有 deaths 和 milestones_at_death，在死亡发生的那一刻记录，而不是事后回忆。

和录制一样，它不是工具：一局是否结束，不是智能体能决定的事。

录制不是工具：被拍摄也不是智能体能决定的事。

计分发生在哪里

这是为 trapstreet.run 上的 Minecraft 榜单做的，榜单让智能体在实时世界里跑，并给它做到的事排名：

- Obtain a Diamond——爬完整棵科技树，从木头到钻石。
- One Life——同一棵树，只不过第一次死亡之后做的事都不算数。

用这个插件不需要上面任何一个；连到你自己的服务器，让智能体去挖矿，单干就行。

如果你觉得那些太简单，就自己做一个。 trapstreet 上的任务就是一个仓库，里面有 traptask.yaml、一个裁判，还有一个文件说明什么算数——有账号的人都能注册一个，只有创建者能改。One Life 正是如此：和它的兄弟榜单同一个游戏、同一棵科技树，只改了一条规则，用了一个 expected.json 和一个裁判。其他值得一试的规则——hardcore、没有工作台、十分钟内进下界、速通指定种子——只差一个 fork 和一个下午。

要求

一台智能体能连上的 Minecraft Java 1.20.4 服务器，离线模式。

Java 没有随附，而且即使装了也常常不在 PATH 里—— brew install openjdk@21 会把它留在 /opt/homebrew/opt/openjdk@21/bin/java，除非你做链接。Paper 1.20.4 要 Java 17–21；同一台机器上更新的 JDK 不是安全的默认选择。

值得知道的 bug，因为每一个看起来都像玩法问题

寻路悄无声息地什么都没做。 mineflayer-pathfinder 是 CJS，Node 的具名导出检测会在顶层暴露 Movements 和 pathfinder，但不暴露 goals——那个只存在于 default 上。解构顶层不会报错；它给你 undefined，然后每次移动都返回：

did not arrive (Cannot read properties of undefined (reading 'GoalNear'))

读起来像寻路失败。这样导入：

const pf = await import('mineflayer-pathfinder')
const { goals, Movements } = pf.default ?? pf

挖掘什么都没收集到。 打掉方块会把掉落物留在地上；只有走过去才会捡起来。智能体看到 dug spruce_log, gained 0 item(s)，分不清是工具坏了还是半米外躺着一根原木。

第一个修复是走到方块坐标——错得离谱，后来才暴露出来。智能体从半山腰挖树干，把机器人送到半空中的一点，而原木躺在下面的地上；它在剩下的运行时间里一直推断是服务商扣下了掉落物。mc_dig 现在会走到物品实体那里，如果仍然够不到，就说明它躺在哪儿，而不是用一句含糊的话应付三种不同的原因。

合成报告成功，背包却没变。 bot.craft 可能什么都没做就返回成功——窗口事务偶尔会丢失，而且不报错。工具输出 crafted wooden_pickaxe -- gained nothing，材料却原封未动。现在它会等背包真正发生变化，并报告世界给出的结果，而不是那个 promise 做了什么。

这些问题没有一个是靠调用工具、检查返回值发现的。每一个都需要给智能体一个真实目标，然后看着它失败，而每次调用看起来都正常。

走路会悄悄卸下机器人的装备。 Pathfinder 靠放置方块来搭桥跨越缺口，这会把那个方块拿在手上。装备镐子、走路、挖掘——机器人挥着泥土，而石头什么都不掉。走路并不表示要手持什么，所以现在它会恢复。同样的缺陷后来在 mc_place 里也发现了，它会装备自己放置的方块，然后一直拿着。

items_gained 统计错了对象。 它衡量的是背包总变化量，而不是这个方块的掉落物有没有到。地上有杂物时——pathfinder 挖泥土来够到某处，机器人踩到一件散落的物品——总数加一，一块躺在地上的圆石就被记为已收集。现在它会读取 block.drops，报告 1 x cobblestone，而不是一个光秃秃的数字。这个缺陷从第一个版本就存在，只是地面碰巧干净时一直看不见。

mc_goto 可能永远挂住。 pathfinder.goto 不接受超时——thinkTimeout 限制的是搜索，不是行走——所以智能体在同一个坐标上站了十分钟，没有报错，也没有日志，直到运行被杀死。现在限制为 60s。加上上限之后又暴露出更糟的一个：pathfinder.stop() 会留下一个内部标志，把下一个目标置空，所以一次超时就会让剩下的运行时间里移动全部失效。

伤害报告得太晚。 智能体在两次工具调用之间是瞎的，所以挨打只会在下一次 mc_observe 时浮现。在 easy 难度下，一次运行十二分钟就拿到了铁镐，然后被同一只骷髅杀死四次——在一次反复挖掘的窗口里，生命值从 9、6.5、4、1.5 掉到 0。mc_dig 现在会报告挖掘时受到的伤害，mc_goto 会在机器人开始挨打的瞬间中止行走。它只报告，不反应。反击和逃跑仍然是智能体自己的问题，而这两件事都没有工具。

License

MIT