原创 开源 MC服主必备：越用越懂你的AI智能体，服务器卡顿自动排查 v2.2.0

[MD] # Kilacraft-AI > 第一个让每个服务器都拥有「越用越懂你」的AI智能体插件 — 基于 LLM 意图识别与技能执行框架 [](https://github.com/axy-yxa/Kilacraft-AI/tags) [](https://github.com/axy-yxa/Kilacraft-AI) [](https://adoptium.net/) [](https://github.com/axy-yxa/Kilacraft-AI/blob/main/LICENSE) [](https://discord.gg/nNmhcZHDxr) *** [/MD]


[MD] *** ## 版本兼容 **最低要求：Minecraft 1.16.5 + Java 17** | Minecraft 版本 | Java 要求 | 支持的服务端 | | :--------------: | :------: | :---------------------------: | | **1.16.5** | Java 17+ | Paper / Purpur / Leaf / Folia | | **1.17 - 1.19** | Java 17+ | 全部 | | **1.20 - 1.21+** | Java 21+ | 全部 | > 一套 JAR 包兼容所有版本，基于 Spigot 1.16.5 API 开发，完整支持 Folia 区域化线程调度。 ### 可选依赖 | 插件 | 版本 | 提供的功能 | | :------------------: | :------: | :---------------------: | | **CMI** | 9.8.6.4+ | 传送、家、地标、玩家增强信息、TPA | | **GlobalMarketPlus** | 1.3.8.0+ | 市场查询、余额、价格、商品列表 | | **MythicMobs** | 5.12.0+ | NPC 占位符（让 NPC 显示 AI 回复） | | **Vault** | 最新版 | 多货币系统支持 | | **Spark** | 最新版 | 服务器性能采样与分析（Paper 1.21+ 等已内置） | > 未安装时对应功能自动禁用，不影响核心对话。 *** ## 快速开始 ### 1. 安装 下载最新的 `Kilacraft-AI.jar`，放入服务器 `plugins/` 目录，启动服务器。 ### 2. 配置 API 编辑 `plugins/Kilacraft-AI/llm.yml`，填入你的 LLM API 信息： ```yaml llm: api_url: "https://api.deepseek.com/v1/chat/completions" api_key: "your-api-key" model: "deepseek-chat" ``` 支持所有 OpenAI 标准格式的厂商（DeepSeek、智谱AI、Moonshot、OpenAI、Groq、硅基流动、Gemini、OpenRouter 等），只需修改 `api_url` 和 `model` 即可切换。 ### 3. 测试 ``` /ai 你好 ``` 看到 AI 回复即配置成功。 > 重载配置使用 `/ai reload`，重载知识库使用 `/ai knowledge reload`，重载人格使用 `/ai personalities reload`。 *** ## 核心功能 ### AI 智能对话 [/MD]

[MD] **三种交互模式：** ``` # 命令模式 /kila 怎么获得钻石？ # 连续对话模式 /kilacraft chat > 我想建个农场 > AI: 好主意！你想种什么作物？ # 关键词触发（公共频道） @ai 这个怎么做？ ``` 命令别名：`/kilacraft`、`/kila`、`/ai`、`/zm` **流式输出与载体选择：** AI 回复逐字实时显示，消除等待感。支持 5 种输出载体，按场景独立配置： | 载体 | 效果 | 适合场景 | | :-------------: | :--------: | :-------: | | **SIDEBAR** | 右侧边栏，不遮挡视野 | 长文本回复（推荐） | | **BOSS\_BAR** | 顶部横条 | 中等长度文本 | | **ACTION\_BAR** | 物品栏上方 | 短文本提示 | | **CHAT** | 聊天栏 | 默认方式 | | **TITLE** | 屏幕中央 | 短文本高亮 | **AI 回复音效：** AI 开始回复时自动播放提示音效，仅触发玩家可听到。配置位于 `output.yml`： ```yaml output: sound: enabled: true sound_name: "ENTITY_PLAYER_LEVELUP" volume: 0.5 pitch: 1.2 ``` ### 知识库增强 让 AI 了解你的服务器规则、玩法、FAQ。只需在 `plugins/Kilacraft-AI/knowledge/` 目录放入 Markdown 或 TXT 文件： ```markdown # server_rules.md ## 如何获得领地？ 使用 /claim 命令来圈定你的领地。需要至少 10 个金币。 ``` 执行 `/kilacraft knowledge reload` 加载，玩家提问时 AI 会自动检索并引用。支持自定义词典，添加服务器特有术语可显著提升检索准确度。 [/MD]





[MD] *** ## 进阶功能 ### 玩家画像与社交 **玩家画像**：AI 自动分析玩家的对话历史，为每个玩家建立八维度行为画像，并在后续对话中动态注入画像摘要作为参考上下文。**AI 越来越懂你的玩家。** [/MD]

[MD] | 维度 | 说明 | 示例 | | :---: | :---: | :---: | | 游戏风格 | 玩家的玩法偏好 | 战斗型、探索型、建造型 | | 性格特征 | 行为模式 | 友好、幽默、直接 | | 兴趣偏好 | 感兴趣的领域和活动 | 经济交易、红石、建筑 | | 交互禁忌 | 不喜欢的内容或行为 | 不要称呼名字、不要催促 | | 回复偏好 | 期望 AI 的回复方式 | 简短直接、不用 emoji | | 空间记忆 | 提到的地点、基地位置 | 主基地在沙漠 (1200,64,-800) | | 已知事实 | 玩家明确声明的事实 | Steve 是好友、家在沙漠神殿旁 | | 特别观察 | AI 自由观察 | "该玩家最近对附魔系统特别感兴趣" | 玩家登录/退出时自动触发分析（三重门控，防止浪费 API 调用）。配置项位于 `llm.yml`： ```yaml agent: profile: enabled: true min_interval_minutes: 30 # 最小分析间隔 min_message_delta: 20 # 最小新增消息数 ``` **社交关系**：自动追踪玩家间的交互行为（私聊、TPA、技能交互），构建社交关系图谱。关系强度采用递减累加算法，长期不互动的关系会自然衰减。 - 好友间的里程碑事件（击杀 BOSS、完成袭击、宠物战死等）会出现在对方的登录问候中 - AI 能感知"谁和谁是朋友"，在对话中自然提及好友动态 [/MD]


[MD] ### 登录问候 玩家登录时 AI 自动发送个性化问候语。基于画像、离线事件和好友动态，每次问候都是独一无二的。 **首次登录**：欢迎新玩家，介绍 AI 助手功能。支持自定义服务器信息（在 `greeting.yml` 中配置 `server_info`）。 [/MD]


[MD] **回归登录（三大分类数据聚合）：** | 分类 | 数据来源 | 示例 | | :---: | :---: | :---: | | 自有事件 | 玩家离线期间服务器上发生的事 | 商品卖出、收到款项 | | 好友动态 | 好友离线期间的里程碑 | 好友击杀了末影龙 | | 游玩亮点 | 上次问候后的重要事件 | 宠物战死、触发图腾、击杀监守者 | [/MD]

[MD] ``` # 首次登录 嘿 Hub，欢迎来到风铃雪途！我是你的AI帮手，直接 /ai 就能找我。 我能帮你查物品、逛市场、挂机做任务，有啥问题尽管问。 # 回归登录（离线 3 天） 欢迎回来！你上架的钻石卖出去了。你的好友 Steve 击杀了末影龙，Hub 现在也在线。 # 掉线重连（离线 10 秒） 嘿，刚走就回来啦？ ``` ### 人格系统与 NPC 对话 在 `personalities.yml` 中定义不同风格的 AI 人格，配合 MythicMobs 可让 NPC 拥有独立人格和对话能力： ```yaml common_prompt: "你是 Minecraft 服务器的 NPC，正在和玩家 {player} 对话。" 狐狸: | 你是一只聪明的狐狸 NPC，说话俏皮可爱。 喜欢用"~"结尾，经常使用表情符号。 ``` **NPC 对话方式：** 方式一（回调命令，推荐）： ```yaml fox_npc_skill: Skills: - cmd{c="kilacraft plugins 狐狸 服务器的规则是什么 <caster.uuid> myplugin handle_ai {response} <caster.name>"} @self ``` 方式二（MythicMobs 占位符）： ```yaml fox_npc_skill: Skills: - cmd{c="kilacraft plugins 狐狸 服务器的规则是什么 <caster.uuid>"} @self - message{msg="<caster.ai.answer{type=狐狸}>"} @trigger ``` > 插件命令仅限控制台执行，每个 `UUID_人格` 组合有独立历史记录。 ### 挂机任务系统 通过自然语言创建后台监控任务，条件满足时自动通知或执行操作。 [/MD]




[MD] ``` 玩家: 帮我盯着 Steve 上线 AI: 好的！Steve 上线后会第一时间通知你。 [30 分钟后...] 🔔 Steve 已上线服务器！ ``` ``` 玩家: 盯着 Steve 上线，上线后查一下他手里拿的什么 AI: 好的！Steve 上线后会自动查询他手中的物品。 [Steve 上线后...] 🔔 Steve 已上线！查询到他主手拿着钻石剑 x1。 ``` **支持 20 种监控类型（19 事件监听 + 自定义轮询）：** | 监控类型 | 说明 | | :-------: | :----------: | | 玩家上线/下线 | 监视指定玩家上下线 | | 玩家死亡/重生 | 监视死亡事件和重生 | | 玩家传送/切换世界 | 监视位置变动 | | 等级变化 | 监视玩家升级/降级 | | 天气变化 | 监视世界天气 | | 睡眠/物品损坏 | 进入床、离开床、物品损坏 | | 钓鱼 | 钓到鱼时通知或触发后续动作 | | 聊天 | 暗号触发自动化流程 | | 方块破坏 | 挖到指定矿物触发后续动作 | | 实体死亡 | BOSS 击杀检测 | | 实体生成 | 刷怪塔效率监控 | | 实体爆炸 | 防炸服预警 | | 熔炉烧炼 | 物品烧完时通知 | | 作物生长 | 作物成熟通知或自动操作 | **自定义条件轮询** — 监控任意 Skill 返回的数值条件： ``` 玩家: 当我的血量低于 10 时告诉我 玩家: 当我的余额低于 1000 时提醒我 玩家: 当我达到 30 级时帮我查一下钻石价格 ``` 管理命令：`/kilacraft afk` 查询、`/kilacraft afk cancel` 取消。每人同时仅一个任务。 ### 服务器健康监控 基于 Spark 的实时服务器性能监控与 AI 智能诊断系统，守护线程 24/7 后台运行，异常自动检测与告警。 **自动监控：** 守护线程每 10 秒轮询 TPS/MSPT/CPU 指标，超过阈值自动启动 Spark Profiler 采样，完成后调用推理模型生成诊断报告。 **手动采样：** 主动排查问题时使用： ```bash /kilacraft profile start [30-120] # 启动采样（秒） /kilacraft profile status # 查看状态 /kilacraft profile stop # 中断并丢弃 ``` **诊断报告：** 包含服务器状态概览、插件耗时与热点方法触发路径（self time）、AI 诊断结论与优化建议。报告保存在 `plugins/Kilacraft-AI/reports/`，永久保存。 [/MD]
[MD] **告警通知：** 支持游戏内通知 + Discord Webhook / 钉钉群机器人外部推送（仅自动模式）。可用 `/kilacraft notify test` 测试通知渠道。 [/MD]

[MD] **历史查询：** 通过自然语言查询历史告警和报告： - "过去一天服务器有什么告警？" - "列出最近的诊断报告" - "我昨天升级了 MythicMobs，帮我看看性能有没有改善" > 完整配置指南见 `admin.yml`，需 Spark 插件 + 推理模型 API 密钥。Paper 1.21+/Folia/Purpur/Leaf/Pufferfish 已内置 Spark。 ### 玩家行为分析 通过自然语言查询服务器的玩家生态，权限要求：`kilacraft.admin.player`。 - **在线趋势**："过去一周玩家在线趋势怎么样？" — 登录/登出时间分布 - **活跃排行**："查看最活跃的玩家排行榜" — 登录次数、在线时长、最近登录 - **新玩家流入**："过去一周有多少新玩家加入？" — 数量与时间分布 - **画像覆盖率**："AI 画像分析覆盖了多少玩家？" — 已分析/待分析数量 - **社交洞察**："查看玩家社交网络分析" — 关系总数、平均强度、孤立玩家 - **指定玩家社交关系**："查一下 Steve 的社交关系" — 指定玩家的社交关系详情、关系强度、互动频次 ### 审计日志查询 通过自然语言查询 AI 技能的使用情况，权限要求：`kilacraft.admin.audit`。 - **执行记录**："查询玩家 Steve 使用了哪些技能" — 技能名称、参数、结果 - **使用统计**："查看技能使用统计排行" — 使用次数、成功/失败、平均耗时 - **错误追踪**："查看失败的技能执行记录" — 失败记录、错误信息、时间分布 *** ## AI 技能体系 AI 通过 Skill（技能）与服务器交互，每个 Skill 对应一类操作能力。所有 Skill 均为只读查询（除明确标注的写操作），细粒度权限控制。 ### 能力总览 | 类别 | 能力 | 依赖插件 | 权限节点 | | :---: | :--- | :---: | :---: | | **Bukkit API** | 72 个内置只读接口：玩家物品栏/状态/信息、世界信息、服务器信息、环境感知 | 无 | `kilacraft.api.*` | | **原版统计** | 80+ 原版累计统计查询（生涯记录），知识库驱动 BM25 检索，自动单位转换 | 无 | `kilacraft.bukkit_stats` | | **全球市场** | 搜索/上架/领取/求购/下架/转账/拍卖/批量出售/批量收购（9 种操作） | GlobalMarketPlus | `kilacraft.market.*` | | **CMI 集成** | 5 查询（家/地标/玩家信息/在线列表/AFK）+ 3 传送（家/地标/TPA） | CMI | `kilacraft.cmi.*` | | **挂机任务** | 19 事件监听 + 自定义轮询，自然语言创建，通知/回调双模式 | 无 | `kilacraft.afk` | | **通用工具** | 延时等待、主动通知、全服广播 | 无 | — | | **命令执行** | 以玩家身份执行服务器命令，继承权限系统（默认关闭） | 无 | `kilacraft.command.execute` | | **音效粒子** | AI 触发音效/粒子效果，仅调用者感知，YML 配置驱动 | 无 | `kilacraft.bukkit_fx` | | **服主管理** | 健康监控、玩家分析、审计日志（详见上方进阶功能） | Spark（可选） | `kilacraft.admin.*` | > 通配符 `kilacraft.api.*` 和 `kilacraft.cmi.*` 分别包含对应所有子权限。 [/MD]



[MD] *** ## 数据与安全 ### 数据持久化 同时支持 H2 嵌入式数据库（默认，零配置）和 MySQL，重启不丢失数据。多子服共享数据时推荐 MySQL，执行 `/kilacraft reload` 即可热切换，失败自动回退。 | 数据 | 说明 | |------|------| | 对话历史 | 玩家与 AI 的所有对话，30 秒批量刷盘 | | 玩家画像 | 八维度行为分析结果 | | 社交关系 | 玩家间交互强度与类型 | | 服务器事件 | 死亡、成就、交易等里程碑 | | 技能审计 | 所有 Skill 执行记录 | | 画像快照 | 画像历史版本 | > 数据保留天数可在 `database.yml` 中配置，过期数据自动清理。群组服数据隔离。 ### 安全机制 - **玩家数据隔离**：内置非合作式安全过滤，扫描 Skill 参数中的所有值，非本人且不在白名单的玩家名自动替换（消毒） - **第三方 Skill 防护**：即使第三方 Skill 尝试操作其他玩家，安全过滤器也会自动消毒 - **Skill 全球台账**：所有已注册第三方 Skill 的使用统计与安全审查状态可在 [Skill 全球台账](https://axy-yxa.github.io/Kilacraft-AI/skill-registry.html) 实时查看，通过审查的 Skill 标记为已审查 ### 开放 SPI 接口 第三方插件开发者可以通过 Skill SPI 接口将自己的功能暴露给 AI： - **API JAR** 仅 5 KB（compileOnly 依赖） - 实现 `SkillProvider` 接口即可注册自定义 Skill - 内置错误隔离，第三方 Skill 异常不影响核心流程 详见 [Skill SPI 接入文档](Skill-SPI-接入文档.md)。 *** ## 命令与权限 ### 命令列表 | 命令 | 权限 | 说明 | | :-------------------------------: | :-----------------------: | :---------: | | `/kilacraft <消息>` | 无 | 与 AI 对话 | | `/kila` `/ai` `/zm` | 无 | 简写命令 | | `/kilacraft chat` | 无 | 进入/退出连续对话模式 | | `/kilacraft clear` | `kilacraft.clear.self` | 清除自己的对话历史 | | `/kilacraft clear <玩家>` | `kilacraft.clear.other` | 清除指定玩家的历史 | | `/kilacraft reload` | `kilacraft.reload` | 重载配置 | | `/kilacraft knowledge reload` | `kilacraft.knowledge` | 重载知识库 | | `/kilacraft personalities reload` | `kilacraft.personalities` | 重载人格配置 | | `/kilacraft afk` | `kilacraft.afk` | 查询挂机任务 | | `/kilacraft afk cancel` | `kilacraft.afk` | 取消挂机任务 | | `/kilacraft tasks` | `kilacraft.tasks` | 查看定时任务状态（默认 OP） | | `/kilacraft profile start [秒]` | `kilacraft.admin.health` | 启动手动性能采样 | | `/kilacraft profile status` | `kilacraft.admin.health` | 查看采样状态 | | `/kilacraft profile stop` | `kilacraft.admin.health` | 中断采样并丢弃 | | `/kilacraft notify test` | `kilacraft.admin.health` | 测试外部通知渠道 | | `/kilacraft plugins ...` | 控制台专用 | 第三方插件调用 | ### Skill 权限 | 权限节点 | 默认 | 说明 | | :------------------------------: | :--: | :----------: | | `kilacraft.api.player.inventory` | true | 查询玩家物品栏 | | `kilacraft.api.player.status` | true | 查询玩家状态 | | `kilacraft.api.player.info` | true | 查询玩家信息 | | `kilacraft.api.world.info` | true | 查询世界信息 | | `kilacraft.api.server.info` | true | 查询服务器信息 | | `kilacraft.cmi.query` | true | CMI 信息查询 | | `kilacraft.cmi.teleport` | true | CMI 传送功能 | | `kilacraft.bukkit_fx` | true | 音效与粒子效果 | | `kilacraft.bukkit_stats` | true | 原版统计数据查询 | | `kilacraft.command.execute` | op | 命令执行（默认仅 OP） | | `kilacraft.tasks` | op | 查看定时任务状态（默认 OP） | | `kilacraft.admin.health` | op | 服务器健康监控 | | `kilacraft.admin.player` | op | 玩家行为分析 | | `kilacraft.admin.audit` | op | 审计日志查询 | | `kilacraft.admin.*` | op | 全部管理功能 | > 通配符 `kilacraft.api.*` 和 `kilacraft.cmi.*` 分别包含对应所有子权限。 *** ## 常见问题 **Q: API 费用高吗？** 以 DeepSeek 为例，单次对话约 ¥0.001-0.002。设置冷却时间（默认 5 秒）可有效控制成本。 **Q: 支持哪些 LLM？** 所有 OpenAI 标准格式的厂商均可。普通对话不支持思考/推理模型（如 deepseek-reasoner、o1），但服主管理功能的 AI 智能诊断支持配置推理模型（在 `admin.yml` 中配置）。 **Q: 会卡服吗？** 不会。所有 API 请求异步执行，内存占用 8-50 MB，HTTP 连接池复用，支持流式响应降低延迟。 **Q: 如何更新？** 备份 `plugins/Kilacraft-AI/` 目录保留配置，替换 JAR 文件，重启服务器。 *** ## 社区与资源 **源码仓库** [](https://github.com/axy-yxa/Kilacraft-AI) [](https://gitee.com/zm_mmm/kilacraft-ai) **交流社区** [](https://discord.gg/nNmhcZHDxr) [](https://qm.qq.com/q/1094391147) **文档资源** [](https://gitee.com/zm_mmm/kilacraft-ai/wikis/%E6%96%87%E6%A1%A3%E7%B4%A2%E5%BC%95) [](https://github.com/axy-yxa/Kilacraft-AI/wiki) [](https://axy-yxa.github.io/Kilacraft-AI/skill-registry.html) **反馈与贡献** [](https://github.com/axy-yxa/Kilacraft-AI/issues) [](https://github.com/axy-yxa/Kilacraft-AI/pulls) MIT License — 如果觉得有用，给个 ⭐ Star 支持一下！ [/MD]