# mc-query Skill

Minecraft 服务器信息查询能力。通过本地脚本直接读取服务器数据，无需经过 ops-manager。

## 脚本清单

| 脚本 | 功能 | 输出 |
|---|---|---|
| `mc_query.py status` | 服务器运行状态 | 人数、内存、CPU、TPS、版本、存档大小、磁盘 |
| `mc_query.py players` | 玩家信息 | 最近动态、在线时间排行、死亡排行、成就排行 |
| `mc_query.py world` | 世界详情 | 世界时间、实体统计、网络流量、活跃模组 |
| `mc_query.py all` | 全部信息 | 综合输出 |

## 使用方法

```python
import subprocess, json

# 获取服务器状态（JSON）
result = subprocess.run(
    ["python3", "YOUR_WORKSPACE_PATH/scripts/mc_query.py", "status", "--json"],
    capture_output=True, text=True, timeout=30
)
data = json.loads(result.stdout)

# 获取玩家排行
result = subprocess.run(
    ["python3", "YOUR_WORKSPACE_PATH/scripts/mc_query.py", "players", "--json"],
    capture_output=True, text=True, timeout=30
)
data = json.loads(result.stdout)

# 获取世界详情
result = subprocess.run(
    ["python3", "YOUR_WORKSPACE_PATH/scripts/mc_query.py", "world", "--json"],
    capture_output=True, text=True, timeout=30
)
data = json.loads(result.stdout)
```

## JSON 返回示例

### status
```json
{
  "players": {"online": 3, "max": 20, "list": "Alice, Bob, Charlie"},
  "memory": {"used_mb": 4096, "used_gb": "4.0GB"},
  "cpu": "15.2%",
  "uptime": "2天5小时30分钟",
  "tps": {"tps_1m": 19.8},
  "version": "NeoForge 21.1.72",
  "world_size": "12.3G",
  "disk": {"used": "45.2GB", "total": "100.0GB", "percent": "45.2%"},
  "load": {"avg": 0.85, "percent": "28.3%", "cores": 8}
}
```

### players
```json
{
  "recent_events": [{"type": "join", "player": "Alice"}],
  "playtime": [
    {"name": "Alice", "seconds": 45000, "formatted": "12小时30分钟"}
  ],
  "deaths": [{"name": "Charlie", "deaths": 23}],
  "achievements": [{"name": "Alice", "achievements": 47}]
}
```

### world
```json
{
  "world_time": {"day": 123, "time": "14:30", "phase": "白天"},
  "entities": {"total": 1523, "hostile": 234, "friendly": 890, "other": 399},
  "top_entities": {"sheep": 120, "zombie": 89},
  "network": {"rx_gb": 1.2, "tx_gb": 0.8},
  "mods": ["create", "appliedenergistics2", "farmersdelight"]
}
```

## 注意事项

- 所有脚本依赖 `mc_config.py` 中的 RCON 配置
- 脚本设计为功能正交：每个只做一件事，可组合使用
- 输出到 QQ 时禁止使用 Markdown（不用 `#`, `*`, `` ` ``, `>`, `-` 列表等）