koishi-plugin-minecraft-command 1.0.0 → 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 johntime2005
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+# koishi-plugin-minecraft-command
+
+Koishi 的 Minecraft 服务器命令插件，通过聊天平台远程执行 Minecraft 服务器命令。需配合 [koishi-plugin-minecraft-adapter](https://github.com/johntime2005/koishi-plugin-minecraft-adapter) 使用。
+
+## 功能特性
+
+- **在线玩家查询**: 查看服务器在线玩家列表
+- **消息广播**: 在 Minecraft 服务器中广播消息
+- **玩家传送**: 传送玩家到指定位置或其他玩家
+- **物品给予**: 给予玩家指定物品
+- **天气控制**: 设置服务器天气（晴天/雨天/雷暴）
+- **时间控制**: 设置服务器时间（白天/黑夜/自定义游戏刻）
+- **自定义命令**: 执行任意 Minecraft 服务器命令
+- **权限管理**: 基于 Koishi 内置权限系统的分级权限控制
+- **中文别名**: 所有命令均支持中文别名
+
+## 前置需求
+
+- [Koishi](https://koishi.chat/) v4.17.9+
+- [koishi-plugin-minecraft-adapter](https://github.com/johntime2005/koishi-plugin-minecraft-adapter) — Minecraft 适配器插件（必须先安装并配置好）
+
+## 安装
+
+```bash
+npm install koishi-plugin-minecraft-command
+```
+
+## 配置
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `botId` | `string` | `''` | 指定 Minecraft Bot ID（selfId），留空则自动选择第一个可用的 Minecraft Bot |
+| `userAuthority` | `number` | `1` | 普通命令（mc.list / mc.say）所需的 Koishi 用户权限等级 |
+| `adminAuthority` | `number` | `3` | 管理命令（mc.tp / mc.give / mc.weather / mc.time / mc.cmd）所需的 Koishi 用户权限等级 |
+
+### 配置示例
+
+```yaml
+plugins:
+  minecraft-command:
+    botId: ''
+    userAuthority: 1
+    adminAuthority: 3
+```
+
+## 命令列表
+
+### 普通命令
+
+普通命令需要用户权限等级 >= `userAuthority`（默认 1）。
+
+| 命令 | 中文别名 | 说明 | 示例 |
+|------|----------|------|------|
+| `mc.list` | `mc.在线` | 查看在线玩家 | `mc.list` |
+| `mc.say <消息>` | `mc.广播` | 在服务器中广播消息 | `mc.say 大家好` |
+
+### 管理命令
+
+管理命令需要用户权限等级 >= `adminAuthority`（默认 3）。
+
+| 命令 | 中文别名 | 说明 | 示例 |
+|------|----------|------|------|
+| `mc.tp <玩家> <目标>` | `mc.传送` | 传送玩家到目标位置或玩家 | `mc.tp Steve Alex`<br>`mc.tp Steve 100 64 200` |
+| `mc.give <玩家> <物品> [数量]` | `mc.给予` | 给予玩家物品 | `mc.give Steve diamond 64` |
+| `mc.weather <类型>` | `mc.天气` | 设置服务器天气 | `mc.weather clear` |
+| `mc.time <值>` | `mc.时间` | 设置服务器时间 | `mc.time day`<br>`mc.time 6000` |
+| `mc.cmd <命令>` | `mc.命令` | 执行任意服务器命令 | `mc.cmd op Steve` |
+
+### 天气类型
+
+| 值 | 说明 |
+|----|------|
+| `clear` | 晴天 |
+| `rain` | 雨天 |
+| `thunder` | 雷暴 |
+
+### 时间值
+
+| 值 | 说明 |
+|----|------|
+| `day` | 白天 |
+| `night` | 黑夜 |
+| `noon` | 正午 |
+| `midnight` | 午夜 |
+| 数字 | 游戏刻（如 `6000`） |
+
+## 权限说明
+
+本插件使用 Koishi 内置权限系统，通过用户的 `authority`（权限等级）控制命令访问。
+
+### 权限等级
+
+| 等级 | 说明 | 可用命令 |
+|------|------|----------|
+| 0 | 未授权用户 | 无 |
+| 1（默认 `userAuthority`） | 普通用户 | `mc.list`、`mc.say` |
+| 3（默认 `adminAuthority`） | 管理员 | 所有命令 |
+
+> 可通过插件配置调整 `userAuthority` 和 `adminAuthority` 的值。
+
+### 如何设置用户权限
+
+1. **通过 Koishi 控制台**：在「用户管理」页面找到目标用户，修改其 `authority` 字段
+2. **通过 `authorize` 命令**（需安装 admin 插件）：
+   ```
+   authorize 3 -u @用户
+   ```
+
+### 推荐配置
+
+```yaml
+# 默认配置即可满足大多数场景
+minecraft-command:
+  userAuthority: 1    # 普通用户可执行查询和广播
+  adminAuthority: 3   # 管理员可执行传送、给予、天气、时间等管理命令
+```
+
+## 相关项目
+
+- [koishi-plugin-minecraft-adapter](https://github.com/johntime2005/koishi-plugin-minecraft-adapter) — Minecraft 适配器插件（本插件的前置依赖）
+- [鹊桥 (QueQiao)](https://github.com/17TheWord/QueQiao) — Minecraft 服务端通信插件/Mod
+- [Koishi](https://koishi.chat/) — 跨平台聊天机器人框架
+
+## 链接
+
+- [GitHub 仓库](https://github.com/johntime2005/koishi-plugin-minecraft-command)
+- [问题反馈](https://github.com/johntime2005/koishi-plugin-minecraft-command/issues)
+- [npm 包](https://www.npmjs.com/package/koishi-plugin-minecraft-command)
+
+## 许可证
+
+[MIT](LICENSE)

package/lib/index.d.ts

@@ -2,11 +2,8 @@ import { Context, Schema } from 'koishi';
 export declare const name = "minecraft-command";
 export interface Config {
     botId: string;
-    allowedChannels: string[];
-    allowedUsers: string[];
-    adminUsers: string[];
-    adminAuthority: number;
     userAuthority: number;
+    adminAuthority: number;
 }
 export declare const Config: Schema<Config>;
 export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -12,21 +12,12 @@ exports.Config = koishi_1.Schema.object({
     botId: koishi_1.Schema.string()
         .description('指定 Minecraft Bot ID（selfId），留空则自动选择第一个可用的 Minecraft Bot')
         .default(''),
-    allowedChannels: koishi_1.Schema.array(koishi_1.Schema.string())
-        .description('允许执行命令的频道/群组 ID 列表（留空则不限制频道）')
-        .default([]),
-    allowedUsers: koishi_1.Schema.array(koishi_1.Schema.string())
-        .description('允许执行普通命令的用户 ID 列表（留空则不限制用户）')
-        .default([]),
-    adminUsers: koishi_1.Schema.array(koishi_1.Schema.string())
-        .description('允许执行管理命令的用户 ID 列表（mc.cmd / mc.tp / mc.give / mc.weather / mc.time）')
-        .default([]),
-    adminAuthority: koishi_1.Schema.number()
-        .description('管理命令所需的 Koishi authority 等级（与 adminUsers 为「或」关系，满足其一即可）')
-        .default(3),
     userAuthority: koishi_1.Schema.number()
-        .description('普通命令所需的 Koishi authority 等级')
+        .description('普通命令（mc.list / mc.say）所需的 Koishi 用户权限等级')
         .default(1),
+    adminAuthority: koishi_1.Schema.number()
+        .description('管理命令（mc.tp / mc.give / mc.weather / mc.time / mc.cmd）所需的 Koishi 用户权限等级')
+        .default(3),
 });
 function apply(ctx, config) {
     function findBot() {
@@ -56,48 +47,13 @@ function apply(ctx, config) {
         }
         return await bot.executeCommand(command);
     }
-    function extractAuthority(user) {
-        if (user != null && typeof user === 'object' && 'authority' in user) {
-            return typeof user.authority === 'number' ? user.authority : 0;
-        }
-        return 0;
-    }
-    function checkPermission(channelId, userId, authority, requireAdmin) {
-        if (config.allowedChannels.length > 0) {
-            if (!channelId || !config.allowedChannels.includes(channelId)) {
-                return '此频道不允许执行 Minecraft 命令';
-            }
-        }
-        if (requireAdmin) {
-            // adminUsers 列表 或 authority >= adminAuthority，满足其一即可
-            const inAdminList = userId ? config.adminUsers.includes(userId) : false;
-            const hasAuth = authority >= config.adminAuthority;
-            if (!inAdminList && !hasAuth) {
-                return '你没有权限执行此管理命令';
-            }
-        }
-        else {
-            // allowedUsers 为空则不限制；非空时需在列表中 或 authority 满足要求
-            if (config.allowedUsers.length > 0) {
-                const inUserList = userId ? config.allowedUsers.includes(userId) : false;
-                const hasAuth = authority >= config.userAuthority;
-                if (!inUserList && !hasAuth) {
-                    return '你没有权限执行此命令';
-                }
-            }
-        }
-        return undefined;
-    }
     ctx.command('mc', 'Minecraft 服务器管理')
         .usage('通过子命令管理 Minecraft 服务器：mc.list / mc.say / mc.tp / mc.give / mc.weather / mc.time / mc.cmd');
-    ctx.command('mc.list', '查看在线玩家')
+    ctx.command('mc.list', '查看在线玩家', { authority: config.userAuthority })
         .alias('mc.在线')
         .action(async ({ session }) => {
         if (!session)
             return;
-        const denied = checkPermission(session.channelId, session.userId, extractAuthority(session.user), false);
-        if (denied)
-            return denied;
         try {
             const result = await runCommand('list');
             return result || '命令已执行，但服务器未返回数据';
@@ -107,14 +63,11 @@ function apply(ctx, config) {
             return `执行失败: ${e.message}`;
         }
     });
-    ctx.command('mc.say <message:text>', '在服务器中广播消息')
+    ctx.command('mc.say <message:text>', '在服务器中广播消息', { authority: config.userAuthority })
         .alias('mc.广播')
         .action(async ({ session }, message) => {
         if (!session)
             return;
-        const denied = checkPermission(session.channelId, session.userId, extractAuthority(session.user), false);
-        if (denied)
-            return denied;
         if (!message)
             return '请输入要广播的消息';
         try {
@@ -126,15 +79,12 @@ function apply(ctx, config) {
             return `广播失败: ${e.message}`;
         }
     });
-    ctx.command('mc.tp <player:string> <target:text>', '传送玩家到目标位置或玩家')
+    ctx.command('mc.tp <player:string> <target:text>', '传送玩家到目标位置或玩家', { authority: config.adminAuthority })
         .alias('mc.传送')
         .usage('示例:\n  mc.tp Steve Alex        — 将 Steve 传送到 Alex\n  mc.tp Steve 100 64 200  — 将 Steve 传送到坐标')
         .action(async ({ session }, player, target) => {
         if (!session)
             return;
-        const denied = checkPermission(session.channelId, session.userId, extractAuthority(session.user), true);
-        if (denied)
-            return denied;
         if (!player || !target)
             return '用法: mc.tp <玩家名> <目标玩家或坐标>';
         try {
@@ -146,15 +96,12 @@ function apply(ctx, config) {
             return `传送失败: ${e.message}`;
         }
     });
-    ctx.command('mc.give <player:string> <item:string> [count:number]', '给予玩家物品')
+    ctx.command('mc.give <player:string> <item:string> [count:number]', '给予玩家物品', { authority: config.adminAuthority })
         .alias('mc.给予')
         .usage('示例: mc.give Steve diamond 64')
         .action(async ({ session }, player, item, count) => {
         if (!session)
             return;
-        const denied = checkPermission(session.channelId, session.userId, extractAuthority(session.user), true);
-        if (denied)
-            return denied;
         if (!player || !item)
             return '用法: mc.give <玩家名> <物品ID> [数量]';
         const amount = count ?? 1;
@@ -167,15 +114,12 @@ function apply(ctx, config) {
             return `给予失败: ${e.message}`;
         }
     });
-    ctx.command('mc.weather <type:string>', '设置服务器天气')
+    ctx.command('mc.weather <type:string>', '设置服务器天气', { authority: config.adminAuthority })
         .alias('mc.天气')
         .usage('可选值: clear (晴天) / rain (雨天) / thunder (雷暴)')
         .action(async ({ session }, type) => {
         if (!session)
             return;
-        const denied = checkPermission(session.channelId, session.userId, extractAuthority(session.user), true);
-        if (denied)
-            return denied;
         if (!type)
             return '请指定天气类型: clear / rain / thunder';
         const validTypes = ['clear', 'rain', 'thunder'];
@@ -191,15 +135,12 @@ function apply(ctx, config) {
             return `设置天气失败: ${e.message}`;
         }
     });
-    ctx.command('mc.time <value:string>', '设置服务器时间')
+    ctx.command('mc.time <value:string>', '设置服务器时间', { authority: config.adminAuthority })
         .alias('mc.时间')
         .usage('可选值: day / night / noon / midnight / 游戏刻数字 (如 6000)')
         .action(async ({ session }, value) => {
         if (!session)
             return;
-        const denied = checkPermission(session.channelId, session.userId, extractAuthority(session.user), true);
-        if (denied)
-            return denied;
         if (!value)
             return '请指定时间值: day / night / noon / midnight / 游戏刻数字';
         const presets = ['day', 'night', 'noon', 'midnight'];
@@ -217,15 +158,12 @@ function apply(ctx, config) {
             return `设置时间失败: ${e.message}`;
         }
     });
-    ctx.command('mc.cmd <command:text>', '执行任意 Minecraft 服务器命令')
+    ctx.command('mc.cmd <command:text>', '执行任意 Minecraft 服务器命令', { authority: config.adminAuthority })
         .alias('mc.命令')
         .usage('直接执行原始服务器命令，如: mc.cmd op Steve')
         .action(async ({ session }, command) => {
         if (!session)
             return;
-        const denied = checkPermission(session.channelId, session.userId, extractAuthority(session.user), true);
-        if (denied)
-            return denied;
         if (!command)
             return '请输入要执行的命令';
         try {

package/package.json

@@ -1,14 +1,23 @@
 {
   "name": "koishi-plugin-minecraft-command",
   "description": "Execute Minecraft server commands from chat platforms via koishi-plugin-minecraft-adapter",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
   "files": [
-    "lib"
+    "lib",
+    "README.md"
   ],
   "license": "MIT",
   "author": "johntime2005",
+  "homepage": "https://github.com/johntime2005/koishi-plugin-minecraft-command",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/johntime2005/koishi-plugin-minecraft-command.git"
+  },
+  "bugs": {
+    "url": "https://github.com/johntime2005/koishi-plugin-minecraft-command/issues"
+  },
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "npm run build"
@@ -31,12 +40,27 @@
     "command",
     "rcon",
     "mc",
-    "game"
+    "game",
+    "server",
+    "管理",
+    "queqiao",
+    "鹊桥"
   ],
   "koishi": {
     "description": {
       "en": "Execute Minecraft server commands from chat platforms, works with minecraft-adapter",
       "zh": "通过聊天平台执行 Minecraft 服务器命令，与 minecraft-adapter 联动"
+    },
+    "category": "gametool",
+    "public": [
+      "botId",
+      "userAuthority",
+      "adminAuthority"
+    ],
+    "service": {
+      "required": [
+        "adapter"
+      ]
     }
   }
 }