前言¶

在 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