Kilacraft-AI - 专为 Minecraft 服务器打造的轻量级 AI Agent

🚀 v1.4.2 正式发布 | 零依赖 · 低内存 · 高性能 · 易扩展 · 完全开源
让每个 Minecraft 服务器都能拥有智能 AI 助手

💎 核心优势

• 🚀 零中间件依赖：只需一个 JAR 文件，无需数据库、Redis 等额外服务
• 💾 极低内存占用：小型服务器仅需 8-12 MB，大型服务器约 30-50 MB（传统方案需 2-5 GB）
• ⚡ 开箱即用：5 分钟完成配置，立即投入使用
• 🔧 高度可定制：人格系统、知识库、语言配置全部可自定义
• 🌐 生态友好：开放 SPI 接口，第三方插件可无缝接入

🌐 项目地址与联系方式

• GitHub: https://github.com/axy-yxa/Kilacraft-AI
• Gitee: https://gitee.com/zm_mmm/kilacraft-ai
• 官方中文 Wiki: 点击查看
• Official English Wiki: Click Here
• QQ群: 1094391147
• Email: 1456133139@qq.com

💡 欢迎 Star ⭐、Fork 🔀 和提交 Issue/Pull Request！

📦 依赖要求与兼容性

✅ 版本兼容性

最低兼容版本：Minecraft 1.16.5 + Java 17

Kilacraft-AI 基于 Spigot 1.16.5 API 开发，一套 JAR 包兼容所有后续版本。

🎁 可选依赖

以下插件未安装时对应功能自动禁用，不影响核心对话功能：

🌟 功能展示

1️⃣ 智能对话系统

三种交互模式，满足所有场景

命令模式（适合偶尔询问）

玩家: /kila 怎么获得钻石？
AI: [Kilacraft-AI] 你可以通过以下方式获得钻石：
    1. 在 Y=-58 到 Y=-53 层挖矿
    2. 探索洞穴和峡谷
    3. 与其他玩家交易

连续对话模式（适合深度交流）

玩家: /kilacraft chat
→ 已进入连续对话模式！

玩家: 我想建个农场
AI: 好主意！你想种什么作物呢？小麦、胡萝卜还是甜菜根？

玩家: 小麦吧，需要什么工具？
AI: 种植小麦需要：
    1. 锄头（把泥土变成耕地）
    2. 水桶（灌溉附近土地）
    3. 种子（破坏草丛获得）

关键词触发（适合公共频道）

玩家: @ai 这个怎么做？
AI: [Kilacraft-AI] 请问具体是指什么呢？我可以帮你解答游戏机制、合成配方等问题。

2️⃣ 知识库增强（RAG 检索）

让 AI 了解你的服务器规则、玩法、FAQ！

使用方法：

1. 在 plugins/Kilacraft-AI/knowledge/ 创建 .md 或 .txt 文件
2. 写入服务器相关知识（规则、教程、FAQ 等）
3. 执行 /kilacraft knowledge reload 重新加载

示例文件 (server_rules.md)：

# 服务器规则

## 基本规则
1. 禁止作弊和使用外挂
2. 保持友好，禁止辱骂他人
3. 禁止破坏其他玩家的建筑

## 经济系统
4. 禁止使用刷钱漏洞
5. 交易需遵循市场规律

# 常见问题

## 如何获得领地？
使用 /claim 命令来圈定你的领地。需要至少 10 个金币。

## 怎么赚钱？
可以通过挖矿、钓鱼或在玩家商店出售物品来赚钱。

智能检索效果：

玩家: 我怎么才能圈地？
AI: [Kilacraft-AI] 你可以使用 /claim 命令来圈定你的领地。需要至少 10 个金币。
    （基于知识库中的"服务器规则"文档）

技术优势：

• 📑 Markdown 标题自动分段，精准定位相关内容
• 🔍 综合评分算法：完整问题匹配 + BM25 关键词评分 + 位置加权 + 精确匹配奖励
• 💾 缓存优化：二次检索速度提升 ~70%
• 🇨🇳 中文分词优化：HanLP TF-IDF + 智能停用词过滤
• 📚 自定义词典支持：可配置服务器特有术语（如“圈地”、“红石”、“村民交易”等），大幅提升分词准确性和检索效果

自定义词典配置（config.yml）：

knowledge:
  custom_dictionary:
    enabled: true  # 启用自定义词典
    words:
      - "圈地"
      - "领地"
      - "红石"
      - "附魔"
      - "村民交易"
      - "刷怪塔"
      - "末影龙"
      # 添加你的服务器特有词汇...

💡 提示：将服务器特有的游戏术语、玩法名称添加到自定义词典中，可以显著提升 AI 对玩家问题的理解准确度。

3️⃣ LLM 智能意图识别 + 多步骤任务编排

🧠 什么是智能意图识别？

Kilacraft-AI 不是简单地"回答问题"，而是理解你的真实意图并自动调用对应功能！

这是整个 Skill 系统的大脑，无论调用的是经济系统、Bukkit API 还是第三方插件的 Skill，都会经过这个智能引擎处理。

# Agent 工作流程
用户输入 → LLM 意图识别 → 判断任务类型 → 执行技能/任务 → 分析结果 → 生成回复

核心优势：

• 🎯 自然语言理解：玩家无需记忆命令，直接说人话即可
• 🤖 自动路由：AI 自动判断应该调用哪个 Skill
• 🔗 多步骤编排：复杂任务自动分解为多个有序步骤
• 💡 智能总结：LLM 综合分析所有结果，生成友好回复

📊 两种任务模式

模式 1：单意图快速路径（简单查询直接执行）

适用于简单的信息查询，零额外开销：

玩家: 钻石多少钱？
    ↓
AI 识别: 单意图 → market_query.query_price
    ↓
执行: 查询价格 API
    ↓
回复: 钻石当前价格：$100.00

其他常见单意图场景：查询物品、查看状态、获取时间等。

模式 2：多步骤任务编排（复杂任务自动分解）

当用户的请求需要多个 Skill 配合完成时，AI 会自动规划执行顺序：

玩家: 帮我查一下钻石的价格，如果不超过 100 就看看我的余额够不够买 10 个
    ↓
AI 识别: 多步骤任务
├─ 步骤 1: market_query.query_price (查询钻石价格)
├─ 步骤 2: market_query.query_balance (查询玩家余额)
└─ 步骤 3: LLM 综合分析 (对比价格和余额，给出建议)
    ↓
最终回复:
[Kilacraft-AI] 
    已为你查询：
    • 钻石价格：$80.00/个
    • 你的余额：$12,580
    
    💡 分析：购买 10 个钻石需要 $800，你的余额充足，完全可以购买！
    需要我帮你下单吗？

⚙️ 配置灵活可控

agent:
  enabled: true                    # 总开关（优先级最高）
  enable_chat_listener: true       # 关键词触发是否启用 Agent
  enable_command: true             # /kilacraft 命令是否启用 Agent
  
  # 历史对话上下文配置
  intent_history_count: 5          # 意图识别时使用 5 轮历史
  analysis_history_count: 2        # 结果分析时使用 2 轮历史
  
  prompts:
    system_prompt: "你是一个专业的 Minecraft 游戏助手..."
    analysis_prompt: "{results}\n请根据以上对话历史、当前输入、执行结果，给出综合性的分析和建议。"

配置说明：

• intent_history_count: 帮助 LLM 理解"再查一下那个物品"等指代性表达
• analysis_history_count: 让 LLM 在分析结果时参考对话上下文，使回复更自然
• 可通过关闭 enable_chat_listener 或 enable_command 在特定入口禁用 Agent 能力

4️⃣ 插件命令模式 + 人格系统（高级功能）

插件命令模式是 Kilacraft-AI 为第三方插件集成设计的专用接口，允许其他插件通过控制台以指定的人格调用 AI。

核心设计理念：

插件命令模式不是给服主手动执行的命令，而是供第三方插件在代码或配置中调用的 API 接口。

📋 基本用法

/kilacraft plugins <人格名称> <消息内容> <玩家 UUID> [回调命令...]

参数说明：

• <人格名称>：在 personalities.yml 中定义的人格（如 狐狸、严厉教师）
• <消息内容>：要发送给 AI 的消息
• <玩家 UUID>：目标玩家的 UUID
• [回调命令...]：可选但强烈推荐，AI 完成后自动执行的命令（支持 {response} 占位符）

重要特性：

• 🔒 仅限控制台执行：玩家无法直接使用此命令
• 🌐 独立历史记录：每个 UUID_人格 组合独立
• ⏱️ 专用冷却时间：使用 plugins_cooldown_seconds 配置（默认 3 秒）
• 💬 回调命令支持：AI 完成后自动执行，{response} 替换为实际回复

💡 典型应用场景

NPC 智能对话（最常见用途）：让 MythicMobs NPC 拥有不同性格，与玩家自然交流。

# MythicMobs 技能配置示例
fox_npc_skill:
  Skills:
  - cmd{c="kilacraft plugins 狐狸 服务器的规则是什么 <caster.uuid> myplugin handle_ai {response} <caster.name>"} @self

工作流程：

玩家右键点击 "狐狸 NPC"
    ↓
插件执行控制台命令
    ↓
AI 生成回复（异步，约 2-5 秒）
    ↓
自动执行回调命令：/myplugin handle_ai "嘻嘻~ 服务器规则很简单哦！✨..." 玩家名
    ↓
你的插件接收并显示：
[NPC 狐狸] 嘻嘻~ 服务器规则很简单哦！✨

💡 提示：如果你是第三方插件开发者，建议先阅读 插件命令模式详解 文档，了解完整的集成流程和最佳实践。

5️⃣ 经济系统集成（GlobalMarketPlus）（扩展功能）

让你的市场插件“会说话”！通过自然语言查询市场信息。

玩家: 钻石多少钱？
AI: [Kilacraft-AI] 钻石当前价格：$100.00/个

玩家: 我还有多少余额？
AI: [Kilacraft-AI] 你的余额：$12,580

玩家: 市场上有什么商品？
AI: [Kilacraft-AI] 当前在售商品列表：
    • 钻石 x15 - $100.00/个
    • 铁锭 x32 - $20.00/个
    • ...

特色功能：

• ✅ 自然语言理解：“买 5 个木棍”自动识别物品和数量
• ✅ 多物品联合查询：“钻石:2,木棍:1”一次查多个
• ✅ 最优价格计算：从便宜到贵智能组合
• ✅ 库存不足提示：显示所有在售详情

安全说明：

• 📖 只读操作：MarketQuerySkill 仅查询信息，不会消耗物品或金钱
• 🔒 权限控制：每个动作都有独立的权限节点
• 🛡️ 错误隔离：执行出错不影响其他功能

6️⃣ Bukkit API 动态调用（37 个内置 API）（扩展功能）

无需写代码，AI 直接调用原版 API 查询玩家状态、世界信息、服务器信息！

玩家: 我手上拿着什么？
AI: [Kilacraft-AI] 你主手拿着：钻石剑 x1

玩家: 我还有多少血？
AI: [Kilacraft-AI] 生命值：18.5/20.0

玩家: 现在是什么时间？
AI: [Kilacraft-AI] 世界时间：06:00（早晨）

玩家: 天气怎么样？
AI: [Kilacraft-AI] 当前天气：晴朗

玩家: 服务器上有多少人在线？
AI: [Kilacraft-AI] 在线玩家：15/100

支持的 API 类别：

• 📦 玩家物品栏：主手/副手物品查询
• ❤️ 玩家状态：生命值、饥饿值、氧气、经验、睡眠、攻击冷却、着火、冰冻、挂机
• 📍 玩家信息：位置坐标、游戏模式、飞行状态、Ping 值、载具、死亡点
• 🌍 世界信息：时间、天气、世界类型、种子、出生点、高度限制、生物生成规则、PVP 设置
• 🖥️ 服务器信息：在线玩家、最大人数、版本、MOTD、世界列表

权限精细控制：

# 可通过权限插件（如 LuckPerms）控制每个玩家/组的访问权限
kilacraft.api.player.inventory  # 物品栏查询
kilacraft.api.player.status     # 状态查询
kilacraft.api.player.info       # 基础信息查询
kilacraft.api.world.info        # 世界信息查询
kilacraft.api.server.info       # 服务器信息查询

安全说明：

• 📖 只读操作：GenericBukkitAPISkill 仅调用 getter 方法，不修改任何数据
• 🔒 权限控制：每个 API 都有独立的权限节点
• 🛡️ 错误隔离：执行出错不影响其他功能

⚙️ 快速开始（5 分钟上手）

第一步：安装插件

1. 下载 Kilacraft-AI-1.4.2.jar
2. 放入服务器 plugins/ 目录
3. 启动服务器，等待生成配置文件

第二步：配置 API 密钥

编辑 plugins/Kilacraft-AI/config.yml：

llm:
  api_url: "https://api.deepseek.com/v1/chat/completions"
  api_key: "sk-your-api-key-here"  # ← 填入你的 API Key
  model: "deepseek-chat"
  temperature: 0.7
  max_tokens: 1000

获取 API Key：

• DeepSeek: https://platform.deepseek.com/
• 智谱 AI: https://open.bigmodel.cn/
• Moonshot: https://platform.moonshot.cn/

💡 提示：只需修改 api_url 和 model 即可切换不同厂商，无需改代码！

第三步：重载配置

修改配置后，有两种方式使配置生效：

方式 1：使用重载命令（推荐）

/kilacraft reload  # 重载主配置和语言配置

方式 2：重启服务器

/restart  # 或完全重启服务器

💡 提示：如果只是修改了 config.yml 或 language.yml，使用 /kilacraft reload 即可，无需重启服务器。如果修改了知识库或人格配置，需要使用对应的专用重载命令（见下方命令列表）。

第四步：测试对话

/kila 你好

如果看到 AI 回复，恭喜！配置成功！🎉

📊 性能与资源占用

内存占用对比

💡 说明：Kilacraft-AI 的内存占用根据知识库规模和在线玩家数量动态变化。小型服务器通常仅需 8-12 MB，大型服务器约 30-50 MB。详见下方详细评估。

对话历史内存评估

max_history: 10（默认）
每轮对话 ≈ 200 字符 ≈ 0.2 KB
每条消息包含 role + content 字段，实际约 0.3-0.4 KB
100 个活跃玩家 × 20 条 × 0.4 KB = 800 KB
1000 个活跃玩家 × 20 条 × 0.4 KB = 8 MB

结论：即使千人在线，对话历史占用也不到 10 MB！

优化建议：

• ✅ 调整 max_history 可控制每个玩家的内存占用
• ✅ 玩家退出后历史记录保留在内存中（重启清空）
• ✅ 使用 /kilacraft clear 可手动清除历史记录

🎮 完整命令列表

🚀 生态扩展：邀请开发者共建 AI Agent 生态

🌈 愿景

我们坚信：每个 Minecraft 插件都应该能与 AI 对话！

Kilacraft-AI 通过开放的 Skill SPI 接口，让第三方插件开发者可以轻松将自己的功能暴露给 AI Agent，实现：

• 💬 自然语言交互：玩家无需记忆复杂命令，直接用语言描述需求
• 🤖 智能意图识别：AI 自动理解玩家意图并调用对应功能
• 🔗 多步骤任务编排：跨插件功能组合，实现复杂工作流

📚 开发者资源

• SPI 接入文档：Kilacraft-AI-Skill-SPI-接入文档.md
• API JAR：Kilacraft-Skill-API-1.4.2.jar（仅 5 KB，compileOnly 依赖）
• 示例代码：文档中包含完整的 Hello World 和 PlayerStats 示例

🎯 适合集成的插件类型

🤝 联系我们

如果你是插件开发者，欢迎：

1. 阅读 SPI 文档，了解接入方式（5 分钟即可上手）
2. 为你的插件开发 Skill，让玩家能用自然语言调用你的功能
3. 提供反馈，帮助我们改进 Kilacraft-AI
4. 在社区分享，帮助更多服主了解 AI Agent 的价值

🏆 已集成的插件

• ✅ GlobalMarketPlus：经济系统深度集成（余额、价格、商品查询）
• ✅ Bukkit API：37 个原版 API 动态调用（玩家状态、世界信息、服务器信息）
• ✅ MythicMobs：占位符支持（NPC 显示 AI 回复）

期待你的插件成为下一个！ 🎉

🤝 支持与贡献

💖 支持项目开发

如果 Kilacraft-AI 帮助到了你，可以考虑支持项目的持续发展：

• 爱发电 - 支持微信/支付宝

你的支持将用于：

• 🚀 持续的功能更新与性能优化
• 🐛 Bug 修复与稳定性提升
• 📚 文档完善与教程制作
• 💬 社区支持与问题解答

感谢每一位支持者！🙏