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