dsh-mc-server-manager：在 DSH 裏管理本地 Minecraft Paper 服務器¶

前言¶

如果你在家用 DSH 起過 Minecraft 服務器，大概會遇到這幾個麻煩：要手動翻目錄找 jar、改 server.properties 得自己敲、插件要靠腳本去 Modrinth 下、備份世界更是得記住 save-all 的時機。更難受的是，Agent 想幫你打理服務器時，它沒有工具可用，只能給你貼一行命令讓你自己執行。

下面介紹的插件 mamawhes/dsh-mc-server-manager 就是解決這件事的：它給 DSH 加一個側欄面板，把建服、啓停、裝插件、備份世界這些操作變成圖形界面；同時註冊一組 mc_* Agent 工具，讓模型在對話裏直接執行同樣的操作。插件當前版本 0.1.0，僅支持 Paper 服務端，維護者 mamawhes 個人維護（GitHub 顯示創建於 2026-11-04，星標 0）。

這是什麼¶

一句話定位：DSH 宿主插件，在本機管理 Minecraft Paper 服務器。

它做兩件原來需要靠 shell 完成的事：

把服務器生命週期搬進 DSH 側欄面板，進程由宿主插件直接託管，數據放在 ~/.dsh/minecraft，不污染工作區。
註冊 mc_* 工具，Agent 可以在對話裏建服、啓停、裝插件、備份世界，不需要用戶粘貼命令。

目標服務端只有 Paper，Fabric / Forge / Vanilla 未實現。

安裝與啓用¶

安裝命令來自 README 原文，按 profile 分開：

dsh plugin --profile web add dsh-mc-server-manager
dsh plugin --profile desktop add dsh-mc-server-manager

安裝後需要重啓 DSH 進程。瀏覽器打開側欄，出現「MC 服務器」入口即生效；沒有就刷新一次頁面。

尚未發佈 npm 時可以從源碼裝（README 給出的形式）：

dsh plugin --profile desktop add github:mamawhes/dsh-mc-server-manager

環境要求：DSH >=0.1.7-rc.1 <0.3.0-0（README 註明已在 0.2.1-rc.5 實測）、Node.js >=22、平臺 macOS / Linux（備份依賴系統 zip / unzip）。Service端 Java 版本對應關係要留意：Paper 1.20–1.21.11 需要 Java 21，Paper 26.1+ 需要 Java 25。

側欄面板：圖形化運維¶

打開「MC 服務器」入口，是一個不綁定會話的全局面板。包括：

服務器生命週期：新建（自動從 PaperMC 下載 jar）、啓動、停止、重啓、刪除。
Java 環境管理：掃描本機 Java（PATH / JAVA_HOME / Homebrew / SDKMAN / JDK 目錄 / 插件安裝目錄），按 Paper 版本校驗最低版本，一鍵下載安裝 JDK（優先 Amazon Corretto，回退 Eclipse Temurin / Adoptium，支持 25/21/17/11/8），也能爲每臺服務器固定或自動選擇運行時。
控制台：每 1.5 秒增量拉取實時日誌，支持直接發送控制台命令。
插件管理：列出 plugins/（從 jar 的 plugin.yml 讀出真實插件名與版本），啓用 / 禁用（*.jar.disabled）、刪除、從 URL 安裝、從 Modrinth 按服務器版本安裝。新建服務器時默認裝 LuckPerms 與 EssentialsX，已存在則跳過，失敗只告警不阻塞創建。
存檔管理：列出世界與維度目錄，創建 zip 備份（運行中先 save-off + save-all flush，完成後 save-on），恢復（自動保留 backups/rollback-* 回滾點），刪除備份。
服務器參數：server.properties 圖形化編輯，常用鍵中文標籤、按類型校驗，未知鍵原樣保留；運行中修改會提示重啓生效。
遊戲規則：gamerule 讀取 / 修改；運行中通過控制台批量讀取並回讀確認，停止時從 world/level.dat 讀取。

Agent 工具：在對話裏操作¶

面板概覽頁有「讓 Agent 執行」，提供檢查狀態 / 啓動 / 停止 / 備份世界 / 查看插件 / 查看參數等一鍵動作。點擊後會把一條帶服務器上下文的指令發送到當前對話並切過去，Agent 立即執行；沒有打開的會話時才新建會話並預填指令。也可以直接在對話框裏描述需求。

工具清單較大，常用的幾組：

狀態與生命週期：mc_list_servers（任何操作前先調用）、mc_server_status、mc_start_server / mc_stop_server（優雅停止，30s 超時後 SIGTERM/SIGKILL）。
Java：mc_list_java_runtimes、mc_install_java、mc_set_server_java。
服務器與參數：mc_create_server、mc_get_properties / mc_set_properties、mc_get_gamerules / mc_set_gamerule。
插件與存檔：mc_list_plugins / mc_install_plugin / mc_toggle_plugin / mc_remove_plugin；mc_list_worlds / mc_backup_world / mc_restore_world / mc_delete_backup。
控制台：mc_console_command。
EULA：mc_accept_eula，僅在用戶明確同意 EULA 後調用。

數據目錄¶

服務器數據統一放在 ~/.dsh/minecraft，大致結構如下：

~/.dsh/minecraft/
├─ settings.json        # 默認 Java 路徑
├─ java/                # 插件安裝的 JDK
└─ servers/<id>/
   ├─ server.json       # 顯示名、MC 版本、內存、EULA、Java 選擇
   ├─ paper.jar
   ├─ server.properties
   ├─ eula.txt
   ├─ plugins/          # 默認含 LuckPerms、EssentialsX
   ├─ backups/          # 備份 zip 與 rollback-*/ 回滾目錄
   └─ world/ world_nether/ world_the_end/ ...

根目錄可以用環境變量 DSH_MC_ROOT 或 patch 裏的 config.root 覆蓋。

HTTP 接口¶

面板背後是一組本地 HTTP 接口，前綴 /mc/api。節選：

GET    /mc/api/meta                         /mc/api/versions      /mc/api/java
POST   /mc/api/java/install                 /mc/api/java/select   /mc/api/java/probe
GET/POST    /mc/api/servers
GET/DELETE  /mc/api/servers/:id
POST   /mc/api/servers/:id/start|{stop,restart,eula,java,command,gamerules,backups,plugins,plugins-toggle}
GET    /mc/api/servers/:id/status|{console,players,properties,plugins,worlds,backups,latest-log}
PUT    /mc/api/servers/:id/properties
DELETE /mc/api/servers/:id/plugins/:file     /mc/api/servers/:id/backups/:name
POST   /mc/api/servers/:id/backups/:name/restore

適用場景與注意事項¶

適合誰：在 macOS / Linux 上用 DSH Web 端或桌面端跑 Paper 服務器、希望把運維操作交給面板或 Agent 的人。

裝之前要確認你能接受它做的事情：

執行本地進程：直接 spawn / kill Java 進程託管 Minecraft 服務器。
文件系統寫入：在 ~/.dsh/minecraft 下創建服務器目錄、寫 server.properties / eula.txt、打包與解壓世界存檔。
下載：從 fill.papermc.io、api.modrinth.com、Corretto CDN / Adoptium / GitHub Releases 拉取文件。
本地 HTTP 路由：/mc/api 不經過 DSH /api 的 cookie 鑑權，插件用 Origin 迴環校驗加僅本機默認監聽的組合自保，README 明確寫了不要把 DSH 暴露到公網後依賴本插件做管理。
EULA 是法律協議，插件不會替你接受，Agent 工具也只有在你明確同意後纔會 acceptEula=true。

已知限制：只支持 Paper；Java 安裝依賴網絡，離線環境需手動安裝 Java 後由掃描發現，或手動填 java 路徑；宿主重啓後無法接管仍在運行的 java 進程（狀態顯示爲已停止），啓動前確認端口未被佔用；自定義 HTTP 路由不走 DSH /api 鑑權，僅做 Origin 迴環校驗。

結尾¶

這個插件的價值在於把「運維一個 Paper 服務器」從敲命令變成一次面板點擊或一句指令，Agent 側和圖形界面覆蓋的是同一套能力。它目前還比較新（v0.1.0，僅 Paper），適合願意自己驗證、自己兜底的人。

目錄頁：https://www.skillhub.cn/plugins/mamawhes/dsh-mc-server-manager
GitHub：https://github.com/mamawhes/dsh-mc-server-manager

mamawhes/dsh-mc-server-manager