详细介绍

NapCatQQ Server Manager Skill for ArkOps-Ai

通过 NapCatQQ 框架实现 QQ 机器人管理 Minecraft 服务器，让 AI 能够通过 QQ 执行服务器命令、管理玩家、监控状态等。

概述

NapCatQQ Server Manager 是一个基于 ArkOps-Ai 框架的 Skill 插件，通过 NapCatQQ 机器人实现 QQ 与 Minecraft 服务器的无缝对接。管理员和玩家可以通过 QQ 群与 AI 对话，实现对服务器的远程管理。

核心优势

远程管理：无需连接服务器控制台，通过 QQ 即可管理服务器
AI 驱动：基于 ArkOps-Ai 的 AI 能力，自然语言理解用户意图
权限控制：三级权限系统，确保操作安全
实时监控：随时查看服务器状态、玩家信息
聊天同步：服务器聊天与 QQ 群消息双向同步

适用场景

服务器管理员外出时远程管理服务器
玩家通过 QQ 查询服务器状态
自动化服务器运维
跨平台消息通知

功能特性

服务器管理

功能	说明
命令执行	执行任意控制台命令
状态监控	查看 TPS、内存使用、在线人数
世界管理	获取世界信息、设置时间、设置天气
广播消息	向所有在线玩家发送消息

玩家管理

功能	说明
在线列表	查看所有在线玩家及详细信息
玩家信息	查询指定玩家的状态、位置、等级等
踢出玩家	将玩家踢出服务器
封禁/解封	封禁或解封玩家
传送	将玩家传送到其他玩家或坐标位置

消息通信

功能	说明
QQ 消息	向 QQ 群发送消息
私聊玩家	向指定玩家发送私聊消息
聊天同步	服务器聊天与 QQ 群双向同步

系统架构

整体架构

┌─────────────────────────────────────────────────────────┐
│                    QQ 用户/管理员                          │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│                   NapCatQQ 机器人                         │
│              (OneBot 11 协议)                             │
└────────────────────────┬────────────────────────────────┘
                         │ HTTP API
                         ▼
┌─────────────────────────────────────────────────────────┐
│                  NapCatClient                             │
│            (OneBot 11 HTTP 客户端)                        │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│               NapCatQQSkill (Skill 主类)                  │
│  ┌──────────────────────────────────────────────────┐   │
│  │  工具定义 (Tools)                                 │   │
│  │  - execute_command                               │   │
│  │  - get_server_status                             │   │
│  │  - get_online_players                            │   │
│  │  - ...                                           │   │
│  └──────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────┐   │
│  │  系统提示词 (System Prompt)                       │   │
│  └──────────────────────────────────────────────────┘   │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│                  ArkOps-Ai 核心                           │
│  ┌──────────────────────────────────────────────────┐   │
│  │  AI 模型 (LLM)                                    │   │
│  │  - 理解用户意图                                    │   │
│  │  - 选择合适工具                                    │   │
│  │  - 生成工具参数                                    │   │
│  └──────────────────────────────────────────────────┘   │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│              Minecraft Server (Purpur)                    │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Bukkit API                                       │   │
│  │  - 执行命令                                       │   │
│  │  - 管理玩家                                       │   │
│  │  - 控制世界                                       │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

组件说明

组件	说明
NapCatQQ	QQ 机器人框架，实现 OneBot 11 协议
NapCatClient	Java HTTP 客户端，调用 OneBot 11 API
NapCatQQSkill	Skill 主类，实现工具定义和执行逻辑
ArkOps-Ai	AI 核心框架，处理自然语言和工具调用
Minecraft Server	Purpur 服务器，执行实际的游戏操作

快速开始

环境要求

组件	版本要求
Java	21+
Minecraft Server	Purpur 1.20+
ArkOps-Ai	2.0.0+
NapCatQQ	4.18.0+
Maven	3.8+

1. 安装 NapCatQQ

参考 NapCatQQ 官方文档安装并配置 NapCatQQ。

确保启用了 HTTP API 服务，默认监听地址为 http://localhost:3000。

2. 编译 Skill

cd napcat-qq-skill
mvn clean package -DskipTests

编译成功后，在 target/ 目录下生成 NapCatQQ-Skill-2.0.0.jar。

3. 部署 Skill

将生成的 jar 文件复制到 ArkOps-Ai 的 skills 目录：

# Windows
copy target\NapCatQQ-Skill-2.0.0.jar plugins\ArkOps-Ai\skills\

# Linux
cp target/NapCatQQ-Skill-2.0.0.jar plugins/ArkOps-Ai/skills/

4. 配置 Skill

编辑 NapCatQQSkill.java 中的配置参数：

// NapCatQQ API 地址
this.napCatBaseUrl = "http://localhost:3000";

// NapCatQQ Token（在 NapCat HTTP Server 配置中设置）
this.napCatToken = "4drkBWWPzmNe1aOz";

// 目标 QQ 群号（用于发送消息）
this.targetGroupId = 123456789;

// 是否启用聊天同步
this.chatSyncEnabled = false;

4.1 配置 NapCat Token

在 NapCat 的 HTTP Server 配置中设置 Token：

打开 NapCat 配置界面
找到 HTTP Server 配置项
在 Token 字段中输入你的密钥（如 4drkBWWPzmNe1aOz）
保存配置并重启 NapCat

然后在 NapCatQQSkill.java 中设置相同的 Token：

this.napCatToken = "你的Token值";

注意：Token 用于身份验证，确保 Skill 中的 Token 与 NapCat 配置中的 Token 一致。

5. 启动服务器

启动 Minecraft 服务器，检查日志确认 Skill 注册成功：

[ArkOps-Ai] 已注册 Skill: NapCatQQ Server Manager v2.0.0 by ArkOps Team
[NapCatQQSkill] Initializing NapCatQQ Server Manager...
[NapCatQQSkill] NapCatQQ Server Manager enabled!
[NapCatQQSkill] QQ API URL: http://localhost:3000

6. 测试

在 QQ 群中发送消息测试：

用户：服务器状态怎么样？
AI：[调用 get_server_status 工具返回服务器状态]

工具详解

1. execute_command

执行控制台命令。

权限等级：ADMIN

参数：

参数	类型	必填	说明
command	string	是	要执行的命令（不包含 /）

示例：

{
  "command": "say 服务器即将重启"
}

返回值：命令执行结果

注意事项：

命令不包含前导 /
具有完整控制台权限，谨慎使用
危险命令可能导致服务器崩溃

2. get_server_status

获取服务器状态信息。

权限等级：PLAYER

参数：无

返回值：

{
  "server_version": "Purpur 1.20.4",
  "online_players": 15,
  "max_players": 100,
  "used_memory_mb": 2048,
  "max_memory_mb": 8192,
  "worlds": 3,
  "tps": 19.8
}

3. get_online_players

获取所有在线玩家列表。

权限等级：PLAYER

参数：无

返回值：

{
  "count": 3,
  "players": [
    {
      "name": "Steve",
      "uuid": "xxx-xxx-xxx",
      "health": 20.0,
      "level": 30,
      "gamemode": "SURVIVAL",
      "world": "world",
      "ping": 45
    }
  ]
}

4. get_player_info

获取指定玩家的详细信息。

权限等级：PLAYER

参数：

参数	类型	必填	说明
player_name	string	是	玩家名称

返回值：

{
  "name": "Steve",
  "uuid": "xxx-xxx-xxx",
  "health": 20.0,
  "max_health": 20.0,
  "food": 20,
  "level": 30,
  "exp": 0.5,
  "gamemode": "SURVIVAL",
  "world": "world",
  "x": 100.5,
  "y": 64.0,
  "z": -200.3,
  "ping": 45,
  "ip": "192.168.1.100"
}

5. kick_player

踢出玩家。

权限等级：ADMIN

参数：

参数	类型	必填	说明
player_name	string	是	玩家名称
reason	string	否	踢出原因

示例：

{
  "player_name": "Steve",
  "reason": "使用作弊客户端"
}

6. ban_player

封禁玩家。

权限等级：ADMIN

参数：

参数	类型	必填	说明
player_name	string	是	玩家名称
reason	string	否	封禁原因

7. unban_player

解封玩家。

权限等级：ADMIN

参数：

参数	类型	必填	说明
player_name	string	是	玩家名称

8. teleport_player

传送玩家。

权限等级：ADMIN

参数：

参数	类型	必填	说明
player_name	string	是	要传送的玩家
target	string	是	目标玩家名称或坐标 (x,y,z)

示例：

{
  "player_name": "Steve",
  "target": "Alex"
}

或传送到坐标：

{
  "player_name": "Steve",
  "target": "100,64,-200"
}

9. send_broadcast

发送广播消息。

权限等级：MODERATOR

参数：

参数	类型	必填	说明
message	string	是	广播消息内容

10. send_message_to_player

向玩家发送私聊消息。

权限等级：MODERATOR

参数：

参数	类型	必填	说明
player_name	string	是	玩家名称
message	string	是	消息内容

11. set_time

设置世界时间。

权限等级：ADMIN

参数：

参数	类型	必填	说明
time	string	是	时间值
world	string	否	世界名称

时间值：

值	说明
day	白天 (1000 ticks)
night	夜晚 (13000 ticks)
sunrise	日出 (23000 ticks)
noon	正午 (6000 ticks)
数字	自定义 tick 值

12. set_weather

设置世界天气。

权限等级：ADMIN

参数：

参数	类型	必填	说明
weather	string	是	天气类型
duration	number	否	持续时间（秒）
world	string	否	世界名称

天气类型：

值	说明
clear	晴天
rain	下雨
thunder	雷暴

13. get_world_info

获取世界信息。

权限等级：PLAYER

参数：

参数	类型	必填	说明
world	string	否	世界名称

返回值：

{
  "name": "world",
  "environment": "NORMAL",
  "time": 1000,
  "difficulty": "HARD",
  "has_storm": false,
  "is_thundering": false,
  "spawn_x": 0,
  "spawn_y": 64,
  "spawn_z": 0,
  "players": 15
}

14. send_qq_message

向 QQ 群发送消息。

权限等级：MODERATOR

参数：

参数	类型	必填	说明
message	string	是	消息内容

15. toggle_chat_sync

切换聊天同步开关。

权限等级：ADMIN

参数：

参数	类型	必填	说明
enabled	boolean	是	true 启用，false 关闭

权限系统

权限等级

等级	说明	可用工具
PLAYER	所有玩家可用	查询类工具
MODERATOR	需要管理员权限	消息发送类工具
ADMIN	需要高级管理员权限	服务器管理工具

权限分配

工具	PLAYER	MODERATOR	ADMIN
get_server_status	✓	✓	✓
get_online_players	✓	✓	✓
get_player_info	✓	✓	✓
get_world_info	✓	✓	✓
send_broadcast		✓	✓
send_message_to_player		✓	✓
send_qq_message		✓	✓
execute_command			✓
kick_player			✓
ban_player			✓
unban_player			✓
teleport_player			✓
set_time			✓
set_weather			✓
toggle_chat_sync			✓

使用场景

场景 1：远程查看服务器状态

用户：服务器现在有多少人在线？
AI：[调用 get_server_status]
AI 回复：当前服务器有 15 人在线，TPS 19.8，内存使用 2048MB/8192MB

场景 2：管理违规玩家

用户：那个叫 Steve 的玩家在用挂，把他踢出去
AI：[调用 kick_player]
AI 回复：已将 Steve 踢出服务器，原因：使用作弊客户端

场景 3：调整游戏环境

用户：把主世界时间改成白天，天气设为晴天
AI：[调用 set_time, set_weather]
AI 回复：已将主世界时间设为白天，天气设为晴天

场景 4：发送服务器公告

用户：通知所有玩家服务器今晚 10 点维护
AI：[调用 send_broadcast]
AI 回复：已发送广播：服务器将于今晚 10 点进行维护，请提前保存好物品

场景 5：传送玩家

用户：把 Alex 传送到 Steve 那里
AI：[调用 teleport_player]
AI 回复：已将 Alex 传送到 Steve 的位置

场景 6：执行复杂命令

用户：给所有在线玩家发送经验
AI：[调用 execute_command 执行 "xp 100 @a"]
AI 回复：已执行命令，所有玩家获得 100 经验

配置说明

NapCatQQ 配置

确保 NapCatQQ 配置文件中启用了 HTTP 服务：

# NapCatQQ 配置文件
http:
  enabled: true
  host: 0.0.0.0
  port: 3000

Skill 配置

在 NapCatQQSkill.java 中修改配置：

@Override
public void onEnable(JavaPlugin mainPlugin) {
    this.mainPlugin = mainPlugin;

    // NapCatQQ API 地址
    this.napCatBaseUrl = "http://localhost:3000";

    // 目标 QQ 群号
    this.targetGroupId = 123456789L;

    // 聊天同步开关
    this.chatSyncEnabled = false;

    // 初始化客户端
    this.client = new NapCatClient(napCatBaseUrl);

    // 注册事件
    Bukkit.getPluginManager().registerEvents(this, mainPlugin);
}

开发指南

项目结构

napcat-qq-skill/
├── pom.xml                                    # Maven 配置
├── README.md                                  # 项目文档
└── src/main/java/com/arkops/
    ├── skill/
    │   └── Skill.java                         # Skill 接口定义
    └── napcatskill/
        ├── NapCatClient.java                  # OneBot 11 HTTP 客户端
        └── NapCatQQSkill.java                 # Skill 主类

添加新工具

在 getTools() 方法中添加工具定义：

tools.add(createTool(
    "new_tool_name",
    "工具描述",
    createPropsBuilder()
        .add("param1", "string", "参数描述", true)
        .build()
));

在 getToolPermissionLevel() 中设置权限：

case "new_tool_name":
    return "ADMIN";

在 executeTool() 中实现执行逻辑：

case "new_tool_name":
    String param1 = args.get("param1").getAsString();
    return executeNewTool(param1);

添加私有方法实现具体逻辑：

private String executeNewTool(String param1) {
    // 实现逻辑
    return "结果";
}

在 getSystemPrompt() 中添加工具说明：

"- new_tool_name: 工具描述\n" +

编译项目

mvn clean package -DskipTests

常见问题

Q1: Skill 注册失败

问题：服务器启动时没有看到 Skill 注册日志

解决：

确认 jar 文件已放入 plugins/ArkOps-Ai/skills/ 目录
检查 ArkOps-Ai 插件是否正常加载
查看服务器日志是否有错误信息

Q2: NapCatQQ 连接失败

问题：调用 QQ API 时返回连接错误

解决：

确认 NapCatQQ 正在运行
检查 napCatBaseUrl 配置是否正确
确认防火墙未阻止连接
测试 API 是否可访问：curl http://localhost:3000/get_login_info

Q3: 命令执行无响应

问题：调用 execute_command 后没有返回结果

解决：

确认命令格式正确（不包含前导 /）
检查服务器日志是否有命令执行错误
确认命令在控制台中可以正常执行

Q4: 玩家不在线

问题：操作玩家时提示玩家不在线

解决：

使用 get_online_players 确认玩家在线
检查玩家名称拼写是否正确
某些工具（如 ban、unban）可以操作离线玩家

Q5: QQ 消息发送失败

问题：调用 send_qq_message 返回错误

解决：

确认 targetGroupId 已正确配置
确认机器人已加入目标群
检查 NapCatQQ 日志是否有权限错误

注意事项

安全机制

AISessionContext 会话级权限

NapCatQQ Skill 使用 ArkOps-Ai 的 AISessionContext 机制进行权限控制：

QQ 用户消息通过 OpsCommandHandler.handleQQMessage() 处理，框架创建携带用户真实权限的 AISessionContext
AI 只会看到与用户权限匹配的工具列表（filterToolsByPermission）
每次工具调用都会经过双重权限校验（SkillManager.executeTool(context)）
不再使用 dispatchCommand("ops") 方式（会导致 AI 以 CONSOLE 权限运行）
不再使用 关键词匹配或前缀注入方式（不可靠，存在绕过漏洞）

权限级别

级别	说明
DISABLED	黑名单用户，消息直接拒绝
PLAYER	仅能查询服务器状态、玩家列表等
ADMIN	可执行命令、踢人、设置时间/天气等
SUPER_ADMIN	全部权限，包括封禁、重启服务器等

性能考虑

内存使用：大量玩家查询可能影响服务器性能
并发控制：避免同时执行多个耗时操作
缓存机制：频繁查询的数据建议实现缓存

兼容性

Minecraft 版本：支持 Purpur 1.20+
Java 版本：需要 Java 21+
ArkOps-Ai 版本：需要 2.0.0+
NapCatQQ 版本：需要 4.18.0+

依赖项目

项目	版本	链接
ArkOps-Ai	2.0.0+	-
NapCatQQ	4.18.0+	https://napneko.github.io/
OneBot 11	-	https://github.com/botuniverse/onebot-11
Purpur	1.20+	https://purpurmc.org/
Paper API	1.21.8	https://papermc.io/

许可证

该 Skill 仍处于开发与内部测试阶段，暂未开放使用。感谢您的关注，请耐心等待后续发布。如果你对本项目感兴趣可以联系DreamArkMC@163.com申请参加内测。

NapCatQQSkill

详细介绍

NapCatQQ Server Manager Skill for ArkOps-Ai

概述

核心优势

适用场景

功能特性

服务器管理

玩家管理

消息通信

系统架构

整体架构

组件说明

快速开始

环境要求

1. 安装 NapCatQQ

2. 编译 Skill

3. 部署 Skill

4. 配置 Skill

4.1 配置 NapCat Token

5. 启动服务器

6. 测试

工具详解

1. execute_command

2. get_server_status

3. get_online_players

4. get_player_info

5. kick_player

6. ban_player

7. unban_player

8. teleport_player

9. send_broadcast

10. send_message_to_player

11. set_time

12. set_weather

13. get_world_info

14. send_qq_message

15. toggle_chat_sync

权限系统

权限等级

权限分配

使用场景

场景 1：远程查看服务器状态

场景 2：管理违规玩家

场景 3：调整游戏环境

场景 4：发送服务器公告

场景 5：传送玩家

场景 6：执行复杂命令

配置说明

NapCatQQ 配置

Skill 配置

开发指南

项目结构

添加新工具

编译项目

常见问题

Q1: Skill 注册失败

Q2: NapCatQQ 连接失败

Q3: 命令执行无响应

Q4: 玩家不在线

Q5: QQ 消息发送失败

注意事项

安全机制

AISessionContext 会话级权限

权限级别

性能考虑

兼容性

依赖项目

许可证

相关项目