前言¶

在 DSH 中扩展 agent 能力时，常见需求是把外部工具、本地服务或客户端操作封装成可调用工具。dsh-mc-agent 针对 Minecraft 做了这一步：它通过 LAN 协议驱动 Mineflayer 机器人，支持自主生存、挖矿砍树、游戏内聊天和实时地图；同时提供内置启动器，处理 Microsoft 登录、版本下载与 Java 游戏进程启动。

该插件标注 UNOFFICIAL，与 Mojang Studios / Microsoft 无官方关联；不包含、不分发 Mojang 游戏内容，游戏文件从 Mojang 官方端点下载。

这是什么¶

dsh-mc-agent 是由 hellosky983 维护的 DSH 插件，许可证为 MIT。它把游戏数据与能力暴露为 mc_* 工具，供 DSH agent 通过对话调用；默认可作为 DSH 聊天界面中的 Minecraft 标签页使用，也可切换为全屏启动器。

它主要解决三件事：

1、AI 代理：通过 LAN 协议直连游戏，驱动真实的 Mineflayer 机器人，支持自主生存、挖矿砍树、游戏内聊天、实时地图。

2、视觉与控制：mc_screenshot 截取游戏窗口、mc_see 用 DashScope Qwen-VL 识别画面、mc_control 用 xdotool 模拟键鼠。

3、内置启动器：官方版本清单、一键安装 client jar/libraries/assets、Microsoft 登录、Java 游戏进程启动。

核心功能¶

Mineflayer 快速模式¶

mc_bot_* 工具通过 LAN 协议实时读取位置、背包、血量、周围方块，并执行精确控制。这种模式直接读取游戏内数据，适合需要快速状态与精确操作的场景。

视觉与控制闭环¶

mc_screenshot 截取游戏窗口，mc_see 将截图交给 DashScope Qwen-VL 进行视觉理解，mc_control 使用 xdotool 模拟键鼠输入。组合起来，agent 可以基于画面状态做下一步动作。

启动器能力¶

内置启动器使用官方版本清单，安装 client jar、libraries、assets，并启动 Java 游戏进程。Microsoft 登录使用用户自己注册的 Azure 应用 client id，通过设备码流程登录。

对话工具¶

除了启动器与机器人控制，插件还提供以下能力：

• mc_analyze_crash：AI 崩溃分析
• mc_world_info / mc_mods / mc_version_advice：游戏助手
• mc_set_goals / mc_goals / mc_complete_goal：自主生存目标框架

这些工具让 agent 可以在对话中查询存档、模组、版本建议、崩溃报告，并推进目标。

安装与启用¶

环境要求：Node.js 18+，DSH 0.1.0-rc.6，启动游戏需要 Java；不同 MC 版本对 Java 版本有要求，如 1.21+ 需 Java 21+。

方式 A：装入已有 DSH profile¶

先克隆仓库：

git clone https://github.com/hellosky983/dsh-mc-agent.git

然后编辑目标 profile 的 package.json。将 dsh-mc-agent 加入 dependencies，并在 dsh.profile.bundles 中加入 bundle 名称：

{
  "dependencies": {
    "dsh-mc-agent": "link:/path/to/dsh-mc-agent"
  },
  "dsh": {
    "profile": {
      "bundles": ["dsh-mc-agent"]
    }
  }
}

如果 profile 已有其他 bundle，需要在原有 bundles 数组中追加，而不是覆盖。

进入 profile 目录安装依赖并重启 DSH：

cd <profile目录>
pnpm install

方式 B：创建独立 profile¶

适合与现有 DSH 实例隔离。

克隆仓库：

git clone https://github.com/hellosky983/dsh-mc-agent.git

创建 <项目>/dsh-home/profiles/minecraft/package.json：

{
  "name": "dsh-profile-minecraft",
  "private": true,
  "dependencies": {
    "dsh-mc-agent": "link:../../../dsh-mc-agent"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "dsh-mc-agent"
      ]
    }
  }
}

安装并启动独立实例：

cd <项目>/dsh-home/profiles/minecraft
pnpm install
DSH_HOME=<项目>/dsh-home dsh --profile minecraft --port 39970

浏览器打开：

http://127.0.0.1:39970

典型用法¶

配置 Microsoft 登录¶

1、在 Azure 门户创建 App registration，允许 public client flows。

2、复制 Application (client) ID。

3、在启动器设置中填写 Microsoft client id。

4、使用设备码登录。

这里必须使用自己注册的 Azure 应用 client id，不使用他人注册的 client id。

对话驱动游戏¶

完成登录和启动后，可以在 DSH 对话中调用工具。常见链路包括：

1、使用 mc_set_goals 设定自主生存目标，再用 mc_goals 查看目标、mc_complete_goal 推进目标。

2、使用 mc_bot_* 读取位置、背包、血量、周围方块，并执行精确控制。

3、使用 mc_screenshot、mc_see、mc_control 形成视觉与控制闭环。

4、使用 mc_analyze_crash 分析崩溃；使用 mc_world_info、mc_mods、mc_version_advice 查询存档、模组与版本建议。

卸载¶

从 profile 的 package.json 中删除 dsh-mc-agent 的 dependencies 条目和 dsh.profile.bundles 条目，然后重新安装依赖并重启 DSH：

cd <profile目录>
pnpm install

如要清理插件本地数据，可删除 ~/.dsh-mc/；游戏目录 ~/.minecraft/ 不受影响，可保留。

适用场景与注意¶

适合：

• 希望把 Minecraft 的启动、运行状态、存档和崩溃信息接入 DSH agent
• 希望 agent 能读取游戏内数据并执行挖矿、移动、放置等操作
• 希望用视觉模型理解游戏画面并做键鼠控制

注意：

1、非官方：插件标注 UNOFFICIAL，与 Mojang Studios / Microsoft 无关联。

2、账号要求：不提供离线模式，游玩必须使用用户自己的微软账号登录；Microsoft 登录需使用自己注册的 Azure 应用 client id。

3、权限：插件会读写 ~/.minecraft，写 ~/.dsh-mc，并访问 Mojang、Microsoft、DashScope 等网络端点；mc_control 会执行 xdotool 模拟键鼠，mc_screenshot 会截取 Minecraft 窗口。

4、运行权限：插件以当前 DSH 进程权限运行，安装前应检查源码、许可证与依赖。

5、数据：无遥测、无第三方统计；账号 token 保存在 ~/.dsh-mc/account.json，权限 600。

结尾¶

dsh-mc-agent 的价值在于把 Minecraft 启动、Mineflayer 机器人、视觉控制和对话工具放进同一个 DSH 插件里，让 agent 不只是能聊游戏，也能读取游戏状态并执行操作。

仓库地址：https://github.com/hellosky983/dsh-mc-agent