[开源]Kilacraft-AI - 专为 Minecraft 服务器打造的轻量级 AI Agent『1.16.5-1.21+』

Zm_***

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

【v1.4.3 正式发布】零依赖 · 低内存 · 高性能 · 易扩展 · 完全开源
让每个 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 包兼容所有后续版本。

Minecraft 版本	Java 要求	服务端核心支持	说明
1.16.x (1.16.1-4)	-	❌ 不支持	官方核心均不支持此范围
1.16.5	Java 17+	⚠️ Paper等(需参数)	CraftBukkit/Spigot 不支持 Java 17+
1.17.x - 1.19.x	Java 17+	✅ 完全支持	Spigot/Paper/Purpur/Leaf/Folia
1.20.x - 1.21.x	Java 21+	✅ 完全支持	服务端核心要求 Java 21 启动

🎁 可选依赖

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

插件	最低版本	功能
MythicMobs	5.12.0+	NPC 占位符（让 NPC 显示 AI 回复）
GlobalMarketPlus	1.3.8.0+	经济系统（余额、价格、商品查询）
Vault	最新版	多货币系统支持

==================================================
🌟 功能展示
==================================================

1️⃣ 智能对话系统

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

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

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

复制代码

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

1. 玩家: /kilacraft chat
   
2. → 已进入连续对话模式！
   
3. 玩家: 我想建个农场
   
4. AI: 好主意！你想种什么作物呢？小麦、胡萝卜还是甜菜根？

复制代码

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

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

复制代码

--------------------------------------------------

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

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

使用方法：

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

示例文件 (server_rules.md)：

1. # 服务器规则
   
2. 
   
3. ## 基本规则
   
4. 1. 禁止作弊和使用外挂
   
5. 2. 保持友好，禁止辱骂他人
   
6. 
   
7. ## 常见问题
   
8. ## 如何获得领地？
   
9. 使用 /claim 命令来圈定你的领地。需要至少 10 个金币。

复制代码

智能检索效果：

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

复制代码

技术优势：

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

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

1. knowledge:
   
2.   custom_dictionary:
   
3.     enabled: true  # 启用自定义词典
   
4.     words:
   
5.       - "圈地"
   
6.       - "领地"
   
7.       - "红石"
   
8.       - "村民交易"

复制代码

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

--------------------------------------------------

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

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

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

两种任务模式：

• 单意图快速路径：简单查询直接执行（如：钻石多少钱？）
• 多步骤任务编排：复杂任务自动分解（如：查一下钻石价格，看看我余额够不够买 10 个）
  

配置灵活可控：

1. agent:
   
2.   enabled: true                    # 总开关（优先级最高）
   
3.   enable_chat_listener: true       # 关键词触发是否启用 Agent
   
4.   enable_command: true             # /kilacraft 命令是否启用 Agent
   
5.   
   
6.   # 历史对话上下文配置
   
7.   intent_history_count: 5          # 意图识别时使用 5 轮历史
   
8.   analysis_history_count: 2        # 结果分析时使用 2 轮历史

复制代码

失败回退机制：
如果意图识别失败或技能执行出错，系统会自动回退到普通 AI 对话，返回有意义的错误消息而非技术性报错。

--------------------------------------------------

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

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

基本用法：

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

复制代码

典型应用场景（NPC 智能对话）：
让 MythicMobs NPC 拥有不同性格，与玩家自然交流。

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

复制代码

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

--------------------------------------------------

5️⃣ 经济系统集成（GlobalMarketPlus）

让你的市场插件“会说话”！通过自然语言查询市场信息。
特色功能：自然语言理解、多物品联合查询、最优价格计算、库存不足提示。
安全说明：只读操作，不会消耗物品或金钱。

--------------------------------------------------

6️⃣ Bukkit API 动态调用（37 个内置 API）

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

支持的 API 类别：

• 玩家物品栏：主手/副手物品查询
• 玩家状态：生命值、饥饿值、氧气、经验、睡眠等
• 玩家信息：位置坐标、游戏模式、飞行状态、Ping 值等
• 世界信息：时间、天气、世界类型、种子、出生点等
• 服务器信息：在线玩家、最大人数、版本、MOTD 等
  

权限精细控制：

1. kilacraft.api.player.inventory  # 物品栏查询
   
2. kilacraft.api.player.status     # 状态查询
   
3. kilacraft.api.world.info        # 世界信息查询

复制代码

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

第一步：安装插件

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

第二步：配置 API 密钥
编辑 plugins/Kilacraft-AI/config.yml：

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

复制代码

获取 API Key：

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

第三步：重载配置
/kilacraft reload  # 重载主配置和语言配置

第四步：测试对话
/kila 你好
如果看到 AI 回复，恭喜！配置成功！🎉

==================================================
📊 性能与资源占用
==================================================

内存占用对比：

方案	内存占用	中间件依赖	适用服务器规模
Kilacraft-AI	8-50 MB	无	所有规模
LangChain + Vector	2-5 GB	Redis, PG	大型商业服
自建 RAG 系统	1-3 GB	MySQL	中大型服

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

性能优化措施：

• HTTP 连接池：复用连接，减少握手开销
• 异步非阻塞：API 请求不阻塞主线程
• 配置缓存：减少重复读取配置的开销
• 智能重试：网络波动自动重试，提高稳定性
  

==================================================
🎮 完整命令列表
==================================================

命令	权限	说明
/kilacraft <消息>	无	与 AI 对话
/kila <消息>	无	简写命令
/kilacraft chat	无	进入/退出连续对话模式
/kilacraft clear	kilacraft.clear.self	清除自己的对话历史
/kilacraft reload	kilacraft.reload	重载主配置和语言配置
/kilacraft knowledge reload	kilacraft.knowledge	重载知识库
/kilacraft personalities reload	kilacraft.personalities	重载人格配置
/kilacraft plugins ...	控制台专用	第三方插件调用（支持回调）

==================================================
🔧 高级配置详解
==================================================

1. Agent 能力配置

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

复制代码

2. 知识库分段配置

1. knowledge:
   
2.   enabled: true
   
3.   max_relevant_chunks: 3           # 每次检索最多返回 3 个片段
   
4.   segment:
   
5.     max_size: 500                  # 每个片段最大 500 字符
   
6.     min_size: 25                   # 最小 25 字符（小于此值忽略）
   
7.     overlap: 30                    # 片段重叠 30 字符（保持连贯性）

复制代码

3. 语言自定义
所有系统提示文本都可以在 language.yml 中自定义，支持颜色代码（§）和变量占位符（{player}, {seconds}）。

4. 人格系统配置

1. # personalities.yml
   
2. 狐狸: |
   
3.   你是一只聪明的狐狸 NPC，说话俏皮可爱。
   
4.   喜欢用"~"结尾，经常使用表情符号。

复制代码

==================================================
⚠️ 安全与权限管理
==================================================

内置 Skill 安全性：
Kilacraft-AI 内置的所有 Skill 都遵循安全第一原则：

• MarketQuerySkill：查询市场信息（余额、价格、商品列表等），只读操作。
• GenericBukkitAPISkill：查询玩家状态、世界信息、服务器信息，仅调用 getter 方法。
  

第三方 Skill 风险提示：
如果你安装了第三方插件开发的 Skill，请注意审查来源，并在测试环境验证功能是否正常、安全。

==================================================
❓ 常见问题 FAQ
==================================================

Q1: API 费用高吗？
A: 取决于使用频率。以 DeepSeek 为例，单次对话约消耗 500-1000 Token（约 0.001-0.002 元）。建议设置合理的冷却时间防止滥用。

Q2: 支持哪些 LLM 厂商？
A: 支持所有遵循 OpenAI 标准 API 格式的厂商（DeepSeek, 智谱 AI, Moonshot 等）。只需修改 config.yml 中的 api_url 和 model 即可切换。

Q3: 会不会卡顿服务器？
A: 不会。插件采用异步非阻塞执行，HTTP 连接池复用，且内存占用极低（8-50 MB）。

Q4: 如何保证数据安全？
A: API Key 存储在本地配置文件，对话历史仅保存在内存中（重启清空），支持世界限制和精细的权限控制。

Q5: 支持离线玩家对话吗？
A: 普通对话模式不支持。但插件命令模式支持！控制台可以通过 /kilacraft plugins 命令代为调用，即使玩家离线也可以生成 AI 回复。

==================================================
🐛 故障排除
==================================================

AI 不回复：

• 检查 config.yml 中的 api_key 是否正确。
• 检查服务器能否访问 API 地址（网络连接问题）。
• 检查是否在禁用的世界中（banned_worlds 配置）。
• 开启调试模式查看详细日志：settings.debug_mode: true
  

知识库检索不准确：

• 使用 Markdown 标题分段（#、##、###）。
• 每个知识点独立成段，避免大段文字。
• 调整 max_relevant_chunks 增加返回数量。
  

==================================================
🤝 支持与贡献
==================================================

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

• 爱发电: https://afdian.com/a/Zm_Mmm (支持微信/支付宝)
  

我们欢迎社区贡献！如果你有任何建议或发现问题：

• Star 项目：在 GitHub 或 Gitee 上给我们一个 Star
• 分享给朋友：推荐给其他服主和开发者
• 提交 Issue：报告问题或提出建议
• 提交 PR：修复 Bug 或添加新功能
  

==================================================
🔗 相关链接
==================================================

• 完整文档索引: 查看所有技术文档
• DeepSeek API 文档: https://platform.deepseek.com/api-docs/
• 智谱 AI 文档: https://open.bigmodel.cn/dev/api
• Moonshot 文档: https://platform.moonshot.cn/docs
  

最后更新: 2026-04-07
适用插件版本: Kilacraft-AI 1.4.2+
开源协议: MIT License