spark-analyzer

---
name: spark-analyzer
description: |
license: MIT
---

# Spark Profile Analyzer

分析 Minecraft Spark 性能分析报告（`.sparkprofile` 二进制文件），输出中文性能分析报告。

## 使用方式

当用户提供一个 `.sparkprofile` 文件时，使用捆绑的 `scripts/analyze_spark.py` 脚本来解析和分析它。

### 步骤

1. **确定文件路径** — 用户可能提供文件名或完整路径。如果只有文件名，在用户的工作目录中搜索（使用 Glob）。

2. **运行分析脚本**：
   ```bash
   python "<skill-path>/scripts/analyze_spark.py" "<path-to-sparkprofile>"
   ```

3. **解读输出** — 脚本会输出完整的分析报告。阅读报告后，用中文向用户总结关键发现，重点关注：
   - 最大的 CPU 消耗来源（按游戏系统分类）
   - 是否有命令方块、红石、漏斗等突出问题
   - 序列化/Codec 开销是否偏高
   - GC 性能是否正常
   - 实体 Tick 是否成为瓶颈
   - 权限检查（LuckPerms）开销

4. **给出建议** — 基于分析结果给出具体的优化建议，例如：
   - 减少高频命令方块
   - 降低视距/模拟距离
   - 检查实体数量（`/spark health`）
   - 优化数据包中的 Function
   - 调整 JVM 参数或 GC 配置

### 注意事项

- 脚本需要 Python 3，无需额外依赖（仅使用标准库 `struct` 和 `collections`）
- `.sparkprofile` 是 protobuf 二进制格式，不是文本文件，不能用文本编辑器查看
- Windows 环境下脚本已处理 GBK 编码问题
- 分析报告为中文

### 分析维度

脚本会从以下维度分析服务器性能：

| 分类 | 说明 |
|------|------|
| 序列化(Codec/NBT) | Mojang DataResult/Codec 框架的 CPU 开销 |
| 命令系统 | Brigadier 命令解析、命令方块执行 |
| 实体 Tick | 生物、玩家、实体的每 tick 更新 |
| 区块操作 | 区块加载、保存、生成 |
| 权限检查 | LuckPerms 等权限查询 |
| 红石 | 红石电路更新 |
| 漏斗 | 漏斗物品传输 |
| 方块实体 | 熔炉、箱子等功能方块 |
| AI/寻路 | 生物 AI 和路径查找 |
| 网络 | 数据包发送和接收 |