Back to Works
ArkOpsSkill

NapQQSkill

This implementation uses the NapCatQQ framework to enable QQ bots to manage Minecraft servers, allowing AI to execute server commands, manage players, and monitor status via QQ.

Internal Beta 2026-05-09 15:50:37

Details

NapCatQQ Server Manager Skill for ArkOps-Ai

Implement QQ bot management of Minecraft servers through the NapCatQQ framework, allowing AI to execute server commands, manage players, monitor status, etc. via QQ.

Overview

NapCatQQ Server Manager is a Skill plugin based on the ArkOps-Ai framework, achieving seamless integration between QQ and Minecraft servers through the NapCatQQ bot. Administrators and players can converse with AI through QQ groups to achieve remote server management.

Core Advantages

  • Remote Management: Manage the server via QQ without connecting to the server console
  • AI-Driven: Natural language understanding powered by ArkOps-Ai's AI capabilities
  • Permission Control: Three-level permission system ensuring operational security
  • Real-time Monitoring: Check server status and player information anytime
  • Chat Synchronization: Bidirectional synchronization between server chat and QQ group messages

Use Cases

  • Remote server management when administrators are away
  • Players querying server status via QQ
  • Automated server operations
  • Cross-platform notifications

Features

Server Management

Feature Description
Command Execution Execute any console command
Status Monitoring Check TPS, memory usage, player count
World Management Get world info, set time, set weather
Broadcast Messages Send messages to all online players

Player Management

Feature Description
Online List View all online players with detailed info
Player Info Query specific player's status, location, level, etc.
Kick Player Kick a player from the server
Ban/Unban Ban or unban a player
Teleport Teleport players to other players or coordinates

Message Communication

Feature Description
QQ Messages Send messages to QQ groups
Private Messages Send private messages to specific players
Chat Synchronization Bidirectional sync between server chat and QQ groups

System Architecture

Overall Architecture

┌─────────────────────────────────────────────────────────┐
│                    QQ Users/Administrators               │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│                   NapCatQQ Bot                           │
│              (OneBot 11 Protocol)                        │
└────────────────────────┬────────────────────────────────┘
                         │ HTTP API
                         ▼
┌─────────────────────────────────────────────────────────┐
│                  NapCatClient                            │
│            (OneBot 11 HTTP Client)                       │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│               NapCatQQSkill (Main Skill Class)           │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Tool Definitions (Tools)                         │   │
│  │  - execute_command                               │   │
│  │  - get_server_status                             │   │
│  │  - get_online_players                            │   │
│  │  - ...                                           │   │
│  └──────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────┐   │
│  │  System Prompt                                    │   │
│  └──────────────────────────────────────────────────┘   │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│                  ArkOps-Ai Core                          │
│  ┌──────────────────────────────────────────────────┐   │
│  │  AI Model (LLM)                                   │   │
│  │  - Understand user intent                         │   │
│  │  - Select appropriate tools                       │   │
│  │  - Generate tool parameters                       │   │
│  └──────────────────────────────────────────────────┘   │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│              Minecraft Server (Purpur)                   │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Bukkit API                                       │   │
│  │  - Execute commands                               │   │
│  │  - Manage players                                 │   │
│  │  - Control worlds                                 │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

Component Description

Component Description
NapCatQQ QQ bot framework implementing OneBot 11 protocol
NapCatClient Java HTTP client for calling OneBot 11 API
NapCatQQSkill Main Skill class implementing tool definitions and execution logic
ArkOps-Ai AI core framework processing natural language and tool calls
Minecraft Server Purpur server executing actual game operations

Quick Start

Requirements

Component Version
Java 21+
Minecraft Server Purpur 1.20+
ArkOps-Ai 2.0.0+
NapCatQQ 4.18.0+
Maven 3.8+

1. Install NapCatQQ

Refer to NapCatQQ Official Documentation for installation and configuration.

Ensure HTTP API service is enabled, default listening address is http://localhost:3000.

2. Build the Skill

cd napcat-qq-skill
mvn clean package -DskipTests

After successful build, NapCatQQ-Skill-2.0.0.jar will be generated in the target/ directory.

3. Deploy the Skill

Copy the generated jar file to ArkOps-Ai's skills directory:

# 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. Configure the Skill

Edit configuration parameters in NapCatQQSkill.java:

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

// NapCatQQ Token (set in NapCat HTTP Server configuration)
this.napCatToken = "4drkBWWPzmNe1aOz";

// Target QQ Group ID (for sending messages)
this.targetGroupId = 123456789;

// Enable chat synchronization
this.chatSyncEnabled = false;

4.1 Configure NapCat Token

Set Token in NapCat's HTTP Server configuration:

  1. Open NapCat configuration interface
  2. Find HTTP Server configuration item
  3. Enter your secret key in the Token field (e.g., 4drkBWWPzmNe1aOz)
  4. Save configuration and restart NapCat

Then set the same Token in NapCatQQSkill.java:

this.napCatToken = "Your Token value";

Note: Token is used for authentication. Ensure the Token in Skill matches the Token in NapCat configuration.

5. Start the Server

Start the Minecraft server and check logs to confirm Skill registration success:

[ArkOps-Ai] Skill registered: 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. Test

Send a message in the QQ group to test:

User: How's the server status?
AI: [Calls get_server_status tool to return server status]

Tool Details

1. execute_command

Execute console commands.

Permission Level: ADMIN

Parameters:

Parameter Type Required Description
command string Yes Command to execute (without /)

Example:

{
  "command": "say Server is about to restart"
}

Return Value: Command execution result

Notes:

  • Commands should not have leading /
  • Has full console permissions, use with caution
  • Dangerous commands may cause server crashes

2. get_server_status

Get server status information.

Permission Level: PLAYER

Parameters: None

Return Value:

{
  "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

Get list of all online players.

Permission Level: PLAYER

Parameters: None

Return Value:

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

4. get_player_info

Get detailed information of a specific player.

Permission Level: PLAYER

Parameters:

Parameter Type Required Description
player_name string Yes Player name

Return Value:

{
  "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

Kick a player.

Permission Level: ADMIN

Parameters:

Parameter Type Required Description
player_name string Yes Player name
reason string No Kick reason

Example:

{
  "player_name": "Steve",
  "reason": "Using cheat client"
}

6. ban_player

Ban a player.

Permission Level: ADMIN

Parameters:

Parameter Type Required Description
player_name string Yes Player name
reason string No Ban reason

7. unban_player

Unban a player.

Permission Level: ADMIN

Parameters:

Parameter Type Required Description
player_name string Yes Player name

8. teleport_player

Teleport a player.

Permission Level: ADMIN

Parameters:

Parameter Type Required Description
player_name string Yes Player to teleport
target string Yes Target player name or coordinates (x,y,z)

Example:

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

Or teleport to coordinates:

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

9. send_broadcast

Send a broadcast message.

Permission Level: MODERATOR

Parameters:

Parameter Type Required Description
message string Yes Broadcast message content

10. send_message_to_player

Send a private message to a player.

Permission Level: MODERATOR

Parameters:

Parameter Type Required Description
player_name string Yes Player name
message string Yes Message content

11. set_time

Set world time.

Permission Level: ADMIN

Parameters:

Parameter Type Required Description
time string Yes Time value
world string No World name

Time Values:

Value Description
day Daytime (1000 ticks)
night Night (13000 ticks)
sunrise Sunrise (23000 ticks)
noon Noon (6000 ticks)
number Custom tick value

12. set_weather

Set world weather.

Permission Level: ADMIN

Parameters:

Parameter Type Required Description
weather string Yes Weather type
duration number No Duration (seconds)
world string No World name

Weather Types:

Value Description
clear Clear
rain Rain
thunder Thunderstorm

13. get_world_info

Get world information.

Permission Level: PLAYER

Parameters:

Parameter Type Required Description
world string No World name

Return Value:

{
  "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

Send a message to QQ group.

Permission Level: MODERATOR

Parameters:

Parameter Type Required Description
message string Yes Message content

15. toggle_chat_sync

Toggle chat synchronization.

Permission Level: ADMIN

Parameters:

Parameter Type Required Description
enabled boolean Yes true to enable, false to disable

Permission System

Permission Levels

Level Description Available Tools
PLAYER Available to all players Query tools
MODERATOR Requires moderator permissions Message sending tools
ADMIN Requires admin permissions Server management tools

Permission Assignment

Tool 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 ✓

Use Cases

Case 1: Remote Server Status Check

User: How many players are online now?
AI: [Calls get_server_status]
AI Reply: Currently 15 players online, TPS 19.8, memory usage 2048MB/8192MB

Case 2: Managing Violating Players

User: That player Steve is using hacks, kick him out
AI: [Calls kick_player]
AI Reply: Steve has been kicked from the server, reason: Using cheat client

Case 3: Adjusting Game Environment

User: Set the main world time to day and weather to clear
AI: [Calls set_time, set_weather]
AI Reply: Main world time set to day, weather set to clear

Case 4: Sending Server Announcements

User: Notify all players that the server will be maintained at 10 PM tonight
AI: [Calls send_broadcast]
AI Reply: Broadcast sent: Server will be maintained at 10 PM tonight, please save your items in advance

Case 5: Teleporting Players

User: Teleport Alex to Steve
AI: [Calls teleport_player]
AI Reply: Alex has been teleported to Steve's location

Case 6: Executing Complex Commands

User: Give experience to all online players
AI: [Calls execute_command with "xp 100 @a"]
AI Reply: Command executed, all players received 100 experience

Configuration

NapCatQQ Configuration

Ensure HTTP service is enabled in NapCatQQ configuration file:

# NapCatQQ Configuration
http:
  enabled: true
  host: 0.0.0.0
  port: 3000

Skill Configuration

Modify configuration in NapCatQQSkill.java:

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

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

    // Target QQ Group ID
    this.targetGroupId = 123456789L;

    // Chat sync toggle
    this.chatSyncEnabled = false;

    // Initialize client
    this.client = new NapCatClient(napCatBaseUrl);

    // Register events
    Bukkit.getPluginManager().registerEvents(this, mainPlugin);
}

Development Guide

Project Structure

napcat-qq-skill/
├── pom.xml                                    # Maven Configuration
├── README.md                                  # Project Documentation
└── src/main/java/com/arkops/
    ├── skill/
    │   └── Skill.java                         # Skill Interface Definition
    └── napcatskill/
        ├── NapCatClient.java                  # OneBot 11 HTTP Client
        └── NapCatQQSkill.java                 # Main Skill Class

Adding New Tools

  1. Add tool definition in getTools() method:
tools.add(createTool(
    "new_tool_name",
    "Tool description",
    createPropsBuilder()
        .add("param1", "string", "Parameter description", true)
        .build()
));
  1. Set permission in getToolPermissionLevel():
case "new_tool_name":
    return "ADMIN";
  1. Implement execution logic in executeTool():
case "new_tool_name":
    String param1 = args.get("param1").getAsString();
    return executeNewTool(param1);
  1. Add private method to implement specific logic:
private String executeNewTool(String param1) {
    // Implement logic
    return "Result";
}
  1. Add tool description in getSystemPrompt():
"- new_tool_name: Tool description\n" +

Build Project

mvn clean package -DskipTests

FAQ

Q1: Skill Registration Failed

Problem: No Skill registration log seen when server starts

Solution:

  1. Confirm jar file is placed in plugins/ArkOps-Ai/skills/ directory
  2. Check if ArkOps-Ai plugin is loaded normally
  3. Check server logs for error messages

Q2: NapCatQQ Connection Failed

Problem: Connection error returned when calling QQ API

Solution:

  1. Confirm NapCatQQ is running
  2. Check if napCatBaseUrl configuration is correct
  3. Confirm firewall is not blocking connection
  4. Test if API is accessible: curl http://localhost:3000/get_login_info

Q3: Command Execution No Response

Problem: No result returned after calling execute_command

Solution:

  1. Confirm command format is correct (without leading /)
  2. Check server logs for command execution errors
  3. Confirm command can be executed normally in console

Q4: Player Offline

Problem: Player offline message when operating on player

Solution:

  1. Use get_online_players to confirm player is online
  2. Check if player name spelling is correct
  3. Some tools (such as ban, unban) can operate on offline players

Q5: QQ Message Send Failed

Problem: send_qq_message returns error

Solution:

  1. Confirm targetGroupId is configured correctly
  2. Confirm bot has joined the target group
  3. Check NapCatQQ logs for permission errors

Notes

Security Mechanisms

AISessionContext Session-Level Permissions

NapCatQQ Skill uses ArkOps-Ai's AISessionContext mechanism for permission control:

  1. QQ user messages are processed through OpsCommandHandler.handleQQMessage(), framework creates AISessionContext carrying user's real permissions
  2. AI only sees tools matching user's permissions (filterToolsByPermission)
  3. Every tool call goes through dual permission verification (SkillManager.executeTool(context))
  4. No longer use dispatchCommand("ops") method (causes AI to run with CONSOLE permissions)
  5. No longer use keyword matching or prefix injection methods (unreliable, has bypass vulnerabilities)

Permission Levels

Level Description
DISABLED Blacklisted users, messages directly rejected
PLAYER Can only query server status, player lists, etc.
ADMIN Can execute commands, kick players, set time/weather, etc.
SUPER_ADMIN Full permissions, including banning, restarting server, etc.

Performance Considerations

  1. Memory Usage: Large player queries may affect server performance
  2. Concurrency Control: Avoid executing multiple time-consuming operations simultaneously
  3. Caching Mechanism: Implement caching for frequently queried data

Compatibility

  1. Minecraft Version: Supports Purpur 1.20+
  2. Java Version: Requires Java 21+
  3. ArkOps-Ai Version: Requires 2.0.0+
  4. NapCatQQ Version: Requires 4.18.0+

Dependencies

Project Version Link
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/

License

This Skill is still in development and internal testing phase, not yet open for use. Thank you for your attention, please wait patiently for the follow-up release. If you are interested in this project, you can contact DreamArkMC@163.com to apply for beta testing.

Related Works

ArkOpsSkill
KnowledgeBaseSkill

Skill, a knowledge base based on ArkOps-Ai

Internal Beta
View Details
ArkOpsSkill
LogSkill

Player behavior logs based on ArkOpsAi Skill

Internal Beta
View Details
ArkOpsSkill
MemorySkill

Long-Memory Skill Based on ArkOpsAi and Alibaba Cloud Vector Search Service

Internal Beta
View Details