Nethack MCP

NetHack MCP

一个用于播放nethack的开源插件。

构建

构建项目：

make install

此命令构建二进制文件并将其放入您的 PATH，假设你 已安装Go.

其他有用的目标：

• make test：运行测试
• make deps：下载依赖项
• make help：显示所有目标

构建NetHack

在运行系统之前，构建NetHack：

cd nethack-llm/sys/unix
sh setup.sh hints/linux
cd ../../
make

如何跑步

在单独的终端中运行这些脚本：

1. 终端1-启动NetHack:

   ./run.sh

这将在名为的tmux会话中启动NetHack nethack.

1. 终端2-启动代理:

   ./harness/opencode-nethack.sh

这将设置所需的环境变量并启动opencode 代理人。

1. 一旦进入 opencode 会话，指示代理：

> 玩网络黑客

环境变量

• NETHACK_TMUX_SESSION （默认值： nethack)：NetHack正在运行的tmux会话名称。由...使用 run.sh 为tmux会话命名 nethack-ctl 以及针对正确会话的线束。

• NETHACK_DUMP_FILENAME （可选）：JSON文件的路径，NetHack在每次转弯后都会在其中写入带注释的地图。如果未设置，则默认为 /tmp/${NETHACK_TMUX_SESSION}-map.json.

并行运行多个代理

要同时运行多个NetHack游戏代理，请使用不同的会话 通过设置名称 NETHACK_TMUX_SESSION 环境变量：

代理1（默认）：

# Terminal 1
./run.sh

# Terminal 2
./harness/opencode-nethack.sh

代理人2：

# Terminal 3
NETHACK_TMUX_SESSION=nethack2 ./run.sh

# Terminal 4
cp -r harness harness-copy
NETHACK_TMUX_SESSION=nethack2 ./harness-copy/opencode-nethack.sh

建筑

组件：

• nethack-ctl：一个Go CLI工具，用于捕获NetHack输出并发送按键

到它。

• Instrumented NetHack：修改后以JSON格式输出带注释的地图

每一个转弯。

• 开源MCP插件：包装 nethack-cli 命令作为MCP工具。
• 开放代码工具：AGENTS.md指示代理玩NetHack。

地图输出示例：

{
  "turn": 2,
  "dungeon_level": 1,
  "tiles": {
    "walls": [[69,10], [70,10], [72,10], [73,10], [74,10], [75,10], [76,10], [69,11], [76,11], [69,12], [76,12], [69,13], [76,13], [69,14], [70,14], [71,14], [72,14], [73,14], [74,14], [75,14], [76,14]],
    "open_spaces": [[71,10], [70,11], [71,11], [72,11], [73,11], [74,11], [75,11], [70,12], [72,12], [73,12], [74,12], [75,12], [70,13], [71,13], [72,13], [73,13], [74,13], [75,13]],
    "special": [[[71,12],"stairs up"]]
  },
  "monsters": [[[70,11],"the kitten","peaceful"], [[73,13],"the grid bug","hostile"]],
  "items": [[[73,11],"dwarf corpse"], [[73,11],"blue gem"], [[73,11],"10 darts"]],
  "hero": "70,13"
}

项目结构

• bin/：编译的二进制文件
• cmd/：入口点 nethack-ctl，MCP工具的CLI后端
• internal/：实施 nethack-ctl
• harness/：代理执行工作区

- opencode-nethack.sh：使用NetHack MCP工具启动opencode代理 - .opencode/plugin/nethack-ctl.ts：封装的opencode插件 nethack-ctl MCP工具中的CLI

• nethack-llm/：NetHack游戏分叉（git子模块）
• docs/：文档文件
• AGENTS.md：代理商发展指南
• run.sh：在tmux中启动NetHack
• Makefile：构建系统配置