MSLX Plugin Lishang：一个 Minecraft 服务器管理插件的开发之旅

前言

在 Minecraft 服务器的日常运维中，管理员常常需要在不同工具之间来回切换——查看玩家上下线记录、获取服务器连接地址、复制给小伙伴。这些操作虽然简单，但反复执行也颇为繁琐。

mslx-plugin-lishang 正是为了解决这些痛点而生的一个小工具合集。它是一个运行在 MSLX 面板上的插件，专注于提升服务器管理员的日常操作效率。

本文基于项目 v1.0.0 版本撰写。

项目概览

mslx-plugin-lishang 的核心定位是 "lishang 的小功能合集"，目前主要提供三大能力：

所有功能都直接嵌入在 MSLX 面板的 UI 中，无需离开面板即可完成操作。

技术架构

整体分层

┌──────────────────────────────────────────┐
│               MSLX 宿主面板               │
│  ┌────────────────────────────────────┐  │
│  │      mslx-plugin-lishang (插件)     │  │
│  │  ┌──────────┐  ┌────────────────┐  │  │
│  │  │  前端 UI  │  │   后端 API     │  │  │
│  │  │ Vue 3    │  │ ASP.NET Core   │  │  │
│  │  │ TDesign  │  │ C# / .NET 10   │  │  │
│  │  │ UnoCSS   │  │                │  │  │
│  │  └──────────┘  └────────────────┘  │  │
│  └────────────────────────────────────┘  │
└──────────────────────────────────────────┘

后端：ASP.NET Core + MSLX SDK

插件后端基于 ASP.NET Core 构建，运行在 .NET 10 上。核心入口是 MSLXPluginEntry 类，它实现了 MSLX SDK 提供的 IPlugin 接口：

public class MSLXPluginEntry : IPlugin
{
    public string Id => "mslx-plugin-lishang"; 
    public string Name => "lishang的小功能合集";
    public string Description => "使用AI进行创作的插件，包含了lishang的一些小功能实现";
    public string Version => "1.0";
    public string MinSDKVersion => "1.4.3";
}

LishangController 提供了三个 RESTful API 端点：

• GET /api/plugins/mslx-plugin-lishang/lishang/server/{id} — 获取服务器连接地址（自动读取 server.properties 中的端口号）
• GET /api/plugins/mslx-plugin-lishang/lishang/player-sessions/{id} — 获取玩家上下线记录
• GET/POST /api/plugins/mslx-plugin-lishang/lishang/config — 读写配置

玩家会话追踪的实现

这是项目中最有趣的部分。它通过解析 Minecraft 服务器的 logs/latest.log 文件来追踪玩家行为：

1. 扫描日志中 joined the game 和 left the game 关键字
2. 通过字符串解析提取玩家名称和时间戳
3. 将 join/left 事件配对为完整的会话记录
4. 与会话历史进行合并去重后持久化存储

这种纯文本解析的方式避免了在 Minecraft 服务端安装任何额外插件，做到了对服务器零侵入。

前端：Vue 3 + TDesign + 原生 ESM 注入

前端技术栈选择：

关键设计：依赖外部化

这是本项目架构中最精妙的设计决策。通过 Vite 的 vite-plugin-external 插件，前端构建时将以下依赖标记为外部：

// vite.config.ts
createExternal({
  externals: {
    vue: 'Vue',
    'vue-router': 'VueRouter',
    pinia: 'Pinia',
    'tdesign-vue-next': 'TDesign',
    'mslx-request': 'mslxRequest'
  }
})

这意味着插件的构建产物中不包含 Vue、TDesign 等库的代码，而是在运行时直接复用宿主面板已加载的这些库。好处显而易见：

• 打包体积极小：插件入口文件几乎只有业务逻辑代码
• 加载速度快：无需重复下载已存在的框架代码
• UI 风格一致：与宿主共享 TDesign 主题变量，完美融入面板
• 状态共享：通过 window.MSLX_Stores 访问宿主的 Pinia Store

插件注册与扩展注入

插件通过 pluginEntry.ts 声明自己的路由和 UI 扩展点：

export const pluginConfig = {
    name: 'LishangPlugin',
    version: '1.0.0',
    routes: [
        // 配置页面的路由注册
    ],
    extensions: [
        {
            slot: 'instance-console-overview-bottom',
            component: InstanceCardInject,
        }
    ]
};

extensions 中的 slot 指定了注入到宿主 UI 的插槽位置。instance-console-overview-bottom 意味着插件面板会出现在实例控制台概览页面的底部——这正是管理员最常浏览的位置。

功能详解

1. 连接地址配置

管理员可以在侧边栏菜单进入 lishang 配置 页面，设置公网连接地址。

┌──────────────────────────────────────┐
│  ⚙ lishang 配置                      │
│  设置插件的连接地址等参数              │
│                                      │
│  🌐 连接地址                          │
│  ┌──────────────────────┐ ┌────┐    │
│  │ example.com          │ │保存│    │
│  └──────────────────────┘ └────┘    │
│                                      │
│  设置后格式：{地址}:{端口}            │
└──────────────────────────────────────┘

配置通过 config.json 文件持久化存储在 %AppData%/MSLX/Plugins/mslx-plugin-lishang/ 目录下，重启后面板后依然有效。

2. 快捷复制服务器地址

在实例控制台中，插件面板会显示当前的连接地址（自动拼接端口号）：

┌──────────────────────────────────────┐
│  🧩 插件扩充面板           lishang   │
│                                      │
│  连接地址 example.com:10001          │
│          ↑ 点击即可复制              │
└──────────────────────────────────────┘

点击蓝色的地址文字，即可将其复制到剪贴板。端口号是自动从实例的 server.properties 文件中的 server-port 配置项读取的，无需手动输入。

3. 玩家上下线记录

插件面板展示历史会话记录表格（玩家名称 / 上线时间 / 下线时间），最多保留 30 条：

┌──────────────────────────────────────┐
│  历史记录                  共 5 条   │
│  玩家名称    上线时间    下线时间     │
│  PlayerA     14:30:22   14:35:10     │
│  PlayerB     14:40:05   14:42:33     │
│  Steve       15:01:18   15:20:45     │
└──────────────────────────────────────┘

会话数据通过 JSON 文件持久化，按服务器 ID 隔离存储，确保不会丢失历史记录。

构建与部署

项目通过 build.bat 一键构建：

build.bat

构建流程分为两步：

1. 前端构建：vue-tsc -b && vite build，输出 ESM 格式的 mslx-plugin-entry.js 和静态资源到 Frontend/dist/
2. 后端构建：dotnet build -c Release，并通过 ILRepack 将所有依赖 DLL 合并为单一程序集

合并后的产物只有 一个 DLL 文件 —— MSLX.Plugin.Lishang.dll。前端静态资源作为嵌入式资源打包在 DLL 内部，由 MSLX SDK 在运行时自动提供静态文件服务。

这种单一文件分发的设计极大地简化了插件的安装和分发——用户只需将 DLL 放入 MSLX 的 plugins 目录即可。

设计亮点总结

1. 极致轻量的插件架构

通过依赖外部化，插件本身几乎不携带冗余代码。Vue、TDesign、Vue Router、Pinia 全部从宿主复用，插件体积做到最小。

2. 零侵入的服务器交互

玩家会话追踪完全通过读取 Minecraft 服务器的标准日志文件实现，不需要在服务端安装任何 Mod 或 Plugin。这种设计适用于任何基于标准日志格式的 Minecraft 服务端（Vanilla、Spigot、Paper 等）。

3. 深度融合宿主生态

• 共享宿主的 Axios 实例（mslx-request），自动携带认证 Token
• 直接调用宿主的 TDesign 组件 API（MessagePlugin、DialogPlugin 等），UI 通知队列与主项目完美协调
• 透传宿主的 Pinia Store，实时响应主题切换和权限变更

4. 数据持久化策略

配置和会话数据均以 JSON 格式存储在用户应用数据目录下，按功能维度分文件管理，简单可靠。

技术栈一览

结语

mslx-plugin-lishang 虽然是一个小体量的项目，但它在插件架构设计上有不少值得借鉴的地方——尤其是依赖外部化 + 单一 DLL 分发的设计模式，为 MSLX 生态下的插件开发提供了一个清晰的范式。

无论是 MC 服务器管理员还是对插件系统感兴趣的开发者，希望这篇文章能带给你一些启发。

项目还在持续迭代中，欢迎提出建议和反馈！

原文发布于 2026 年 5 月 21 日