MCAI - Minecraft AI 助手
MCAI 是一个 Fabric 模组,允许 AI 管理你的 Minecraft 服务器。整个项目均由 AI 开发。
TL;DR: 玩家输入 /ai how do I enchant a diamond sword?,AI 会给出回答。如果有人骂人?AI 会警告或踢出。危险操作需要管理员批准。
快速开始
| 功能 |
使用方法 |
| 与 AI 对话 |
/ai <问题> 或 !ai <问题> |
| AI 执行命令 |
/ai give me a diamond sword(需管理员审批) |
| AI 批量执行命令 |
/ai build a redstone circuit(命令链,只需一次审批) |
| 查看行为评分 |
/aiscore |
| 搜索维基 |
/aikb enchantment(支持在线维基查询) |
| 管理员批准 | /aiaccept <id> 批准 / /aireject <id> 拒绝 |
| 取消待处理 | /aicancel 取消最新 / /aicancel all 取消全部 |
特性
AI 聊天
- 玩家使用
!ai 或 /ai 与 AI 进行对话
- AI 拥有完整的服务器上下文(聊天记录、天气、时间、玩家信息)
- 支持带历史记录的多轮对话
- 人格模式:通过
/aipersona 切换 AI 人格——内置村民、猪灵、末影龙、苦力怕主题,支持双语(中/英),管理员可在 config/mcai/personas/ 中添加自定义人格
自动行为审查
- AI 每 30 分钟分析一次聊天记录
- 三级处罚机制:扣分 -> 黄牌 -> 红牌(踢出服务器)
- 管理员消息被视为可信;管理员可宣布服务器规则
管理员审批
- 危险命令(如 op、ban、kick)需要手动管理员审批
- 超时 3 分钟后自动取消待处理的审批请求
- 严格模式:仅白名单内的安全命令可跳过审批
- 以
/ 开头的 AI 文本将被阻止;所有命令必须通过工具系统和统一的审批流程
- 命令链:AI 可将多个命令打包为一个审批单元(
execute_command_chain),管理员只需批准一次即可执行全部命令,且命令间间隔可配置
- 玩家取消:玩家可使用
/aicancel 取消自己的待处理命令;AI 会收到取消通知,并不会重试相同命令
游戏知识库
- AI 在线搜索 minecraft.wiki / zh.minecraft.wiki 以获取最新的游戏知识(语言通过
wikiLanguage 设置)
- 支持中文和英文搜索,返回摘要及完整页面链接
安装
要求
步骤
- 下载最新的 JAR 文件
- 将其放入
mods/ 文件夹
- 启动服务器以自动生成配置
- 编辑
config/mcai/config.json,填入你的 API Key
- 配置会自动重载;或者手动运行
/aireload
单人游戏使用
模组也支持单人游戏(无需专用服务器):
- 安装 Fabric 客户端(相同版本 26.x)
- 将 JAR 文件放入
.minecraft/mods/ 文件夹
- 启动游戏并进入单人世界
- 配置和命令与服务端设置完全相同
- 你默认拥有世界所有者权限及完整的管理员权限
- (可选)安装 Mod Menu 以便在游戏中编辑配置
提示:在单人游戏中,行为审查系统会自动禁用(无需自己审查自己)。
命令
玩家命令
| 命令 |
描述 |
!ai <msg> /ai <msg> |
与 AI 聊天 |
/aiscore |
查看行为分数 |
/aicancel [id/all] |
取消你自己的待处理命令 |
管理员命令
| 命令 |
描述 |
/aiaccept <id> |
批准待处理的行动 |
/aireject <id> |
拒绝待处理的行动 |
/aiquery |
列出待批准的请求(显示唯一 ID) |
/aiclear |
清除 AI 聊天记录 |
/aireload |
手动重载配置(文件更改时自动重载) |
/airesetprompts |
将提示词文件重置为当前内置默认值 |
/aikb <keyword> |
搜索 Wiki 知识库 |
/aicontrol [chat/review] [on/off] |
切换 AI 聊天/审查功能 |
/aikill |
销毁所有 AI 线程 |
/aidebug start/stop/show/list/clear |
调试日志记录 |
/aipersona [list/set/current/view/reload] |
切换/查看/重载 AI 人格 |
审查管理
| 命令 |
描述 |
/aireview start |
触发手动审查 |
/aireview approve <id> |
批准踢出操作 |
/aireview reject <id> |
拒绝踢出操作 |
/aireview last |
查看上次审查结果 |
/aireview last reasoning |
查看 AI 推理过程 |
测试命令(仅限 OP)
| 命令 |
描述 |
/aitest score <player> |
查看玩家的行为分数 |
/aitest set <player> <score> |
设置玩家的行为分数 |
/aitest penalty <player> <points> |
模拟惩罚 |
/aitest reset <player> |
重置玩家的行为分数 |
/aitest review |
触发手动审查 |
/aitest chatlog |
查看聊天日志 |
配置
文件:config/mcai/config.json。更改后自动重新加载(或使用 /aireload)。
| 键 |
默认值 |
描述 |
apiEndpoint |
https://api.deepseek.com |
API 端点(不含 /chat/completions,格式因提供商而异) |
apiKey |
"" |
API 密钥 |
model |
deepseek-v4-flash |
模型名称 |
triggerPrefix |
!ai |
聊天触发前缀 |
maxTokens |
2048 |
最大响应令牌数 |
temperature |
0.75 |
响应随机性(0-1) |
thinkingLevel |
1 |
思考级别(0-3) |
strictMode |
true |
严格模式 |
aiCooldownSeconds |
60 |
非管理员 AI 冷却时间(秒) |
aiMaxConcurrent |
3 |
最大并发非管理员 AI 调用次数 |
compatibilityMode |
false |
兼容模式:仅发送基本字段以适配 LM Studio 等本地 API |
enableStream |
false |
流式输出(SSE),部分 API 仅支持流式模式 |
reviewIntervalMinutes |
30 |
审查间隔(分钟) |
yellowCardThreshold |
-30 |
黄牌阈值 |
redCardThreshold |
-60 |
红牌阈值 |
scoreRecoveryPerInterval |
5 |
每个周期分数恢复量 |
approvalTimeoutMinutes |
10 |
审批超时时间(分钟) |
wikiLanguage |
"zh_cn" |
AI 在线搜索语言:zh_cn 中文,en_us 英文(默认启用在线搜索) |
apiConnectTimeoutSeconds |
10 |
API 连接超时时间(秒) |
apiRequestTimeoutSeconds |
60 |
API 单次请求超时时间(秒) |
apiLoopTimeoutSeconds |
300 |
工具调用循环总超时时间(秒) |
commandExecTimeoutSeconds |
30 |
单个命令执行超时时间(秒) |
wikiConnectTimeoutSeconds |
5 |
Wiki 搜索连接超时时间(秒) |
wikiRequestTimeoutSeconds |
8 |
Wiki 搜索请求超时时间(秒) |
maxChainCommands |
10 |
每轮链式调用的最大命令数 |
contextMaxChars |
20000 |
AI 上下文最大字符数(自动截断) |
maxToolCalls |
15 |
每次对话轮次的最大工具调用次数 |
activePersona |
"default" |
当前人格 ID |
personaLanguage |
"" |
人格语言覆盖,为空则跟随客户端语言 |
promptLanguage |
"zh_cn" |
内置提示词语言 |
enableChatInterception |
true |
拦截聊天并转发至 AI |
enableCommandExecution |
true |
允许 AI 执行命令 |
enableAutoReview |
true |
启用自动行为审查 |
maxReviewCycles |
4 |
最大审查分析周期数 |
systemPromptPath |
"" |
系统提示词文件路径(位于 config/mcai/ 目录下) |
reviewPromptPath |
"" |
审查提示词文件路径 |
reviewApiEndpoint |
"" |
审查系统 API 端点,为空则跟随聊天配置 |
reviewApiKey |
"" |
审查系统 API 密钥,为空则跟随聊天配置 |
reviewModel |
"" |
审查系统模型,为空则跟随聊天配置 |
首次启动时会自动创建提示词文件 system_prompt.txt / review_prompt.txt。运行 /airesetprompts 可强制将其同步为当前内置版本。
知识库
AI 知识搜索通过在线 Wiki 完成——无需手动导入数据。
链接
Github
许可证
MIT License
MCAI - Minecraft AI Assistant
MCAI is a Fabric mod that lets AI manage your Minecraft server. This entire project is AI-developed.
TL;DR: Players type /ai how do I enchant a diamond sword?, AI answers. Someone swears? AI warns or kicks. Dangerous ops need admin approval.
Quick Start
| What |
How |
| Chat with AI |
/ai <question> or !ai <question> |
| AI executes commands |
/ai give me a diamond sword (admin approval) |
| AI batch commands |
/ai build a redstone circuit (command chain, one approval) |
| Check behavior score |
/aiscore |
| Search wiki |
/aikb enchantment (online Wiki available) |
| Admin approve |
/aiaccept <id> approve / /aireject <id> reject |
| Cancel pending |
/aicancel cancel latest / /aicancel all cancel all |
Features
AI Chat
- Players use
!ai or /ai to chat with AI
- AI has full server context (chat logs, weather, time, players)
- Multi-turn conversation with history
- Persona mode: switch AI persona with
/aipersona — built-in villager, piglin, ender dragon, creeper themes, bilingual (ZH/EN), admins can add custom personas in config/mcai/personas/
Auto Behavior Review
- AI analyzes chat every 30 minutes
- Three-tier penalty: score deduction -> yellow card -> red card (kick)
- Admin messages are trusted; admins can declare server rules
Admin Approval
- Dangerous commands (op, ban, kick) require manual admin approval
- 3-minute timeout auto-cancels pending approvals
- Strict mode: only whitelisted safe commands skip approval
- AI text starting with
/ is blocked; all commands must go through the Tool system and the unified approval flow
- Command Chain: AI can batch multiple commands into a single approval unit (
execute_command_chain), admin approves once to execute all, with configurable intervals between commands
- Player Cancel: Players can use
/aicancel to cancel their own pending commands; AI receives cancellation notice and won't retry the same command
Game Knowledge Base
- AI searches minecraft.wiki / zh.minecraft.wiki online for up-to-date game knowledge (language via
wikiLanguage)
- Supports Chinese and English search, returns summaries and full page links
Installation
Requirements
- Minecraft Fabric server 26.x
- Java 25
- A DeepSeek API Key (or any OpenAI-compatible API)
Steps
- Download the latest JAR
- Place it in
mods/ folder
- Start the server to auto-generate config
- Edit
config/mcai/config.json, fill in your API Key
- Config auto-reloads; or run
/aireload manually
Single-Player Usage
The mod works in single-player too (no dedicated server required):
- Install Fabric client (same version 26.x)
- Place the JAR in
.minecraft/mods/ folder
- Launch the game and enter a single-player world
- Config and commands are identical to the server setup
- You are the world owner with full admin permissions by default
- (Optional) Install Mod Menu for in-game config editing
Tip: The behavior review system is auto-disabled in single-player (no need to review yourself).
Commands
Player Commands
| Command |
Description |
!ai <msg> /ai <msg> |
Chat with AI |
/aiscore |
Check behavior score |
/aicancel [id/all] |
Cancel your own pending commands |
Admin Commands
| Command |
Description |
/aiaccept <id> |
Approve pending action |
/aireject <id> |
Reject pending action |
/aiquery |
List pending approvals (shows unique ids) |
/aiclear |
Clear AI chat history |
/aireload |
Manually reload config (auto-reloads on file change) |
/airesetprompts |
Reset prompt files to current built-in defaults |
/aikb <keyword> |
Search Wiki knowledge base |
/aicontrol [chat/review] [on/off] |
Toggle AI chat/review |
/aikill |
Destroy all AI threads |
/aidebug start/stop/show/list/clear |
Debug logging |
/aipersona [list/set/current/view/reload] |
Switch/view/reload AI persona |
Review Management
| Command |
Description |
/aireview start |
Trigger manual review |
/aireview approve <id> |
Approve kick |
/aireview reject <id> |
Reject kick |
/aireview last |
View last review result |
/aireview last reasoning |
View AI reasoning |
Test Commands (OP only)
| Command |
Description |
/aitest score <player> |
Check player behavior score |
/aitest set <player> <score> |
Set player behavior score |
/aitest penalty <player> <points> |
Simulate penalty |
/aitest reset <player> |
Reset player behavior score |
/aitest review |
Trigger manual review |
/aitest chatlog |
View chat log |
Configuration
File: config/mcai/config.json. Auto-reloads on change (or use /aireload).
| Key |
Default |
Description |
apiEndpoint |
https://api.deepseek.com |
API endpoint (without /chat/completions, format varies by provider) |
apiKey |
"" |
API key |
model |
deepseek-v4-flash |
Model name |
triggerPrefix |
!ai |
Chat trigger prefix |
maxTokens |
2048 |
Max response tokens |
temperature |
0.75 |
Response randomness (0-1) |
thinkingLevel |
1 |
Thinking level 0-3 |
strictMode |
true |
Strict mode |
aiCooldownSeconds |
60 |
Non-admin AI cooldown (seconds) |
aiMaxConcurrent |
3 |
Max concurrent non-admin AI calls |
compatibilityMode |
false |
Compatibility mode: send only basic fields for local APIs like LM Studio |
enableStream |
false |
Streaming output (SSE), some APIs only support streaming mode |
reviewIntervalMinutes |
30 |
Review interval (min) |
yellowCardThreshold |
-30 |
Yellow card threshold |
redCardThreshold |
-60 |
Red card threshold |
scoreRecoveryPerInterval |
5 |
Score recovery per cycle |
approvalTimeoutMinutes |
10 |
Approval timeout (min) |
wikiLanguage |
"zh_cn" |
AI online search language: zh_cn Chinese, en_us English (online search enabled by default) |
apiConnectTimeoutSeconds |
10 |
API connect timeout (seconds) |
apiRequestTimeoutSeconds |
60 |
API per-request timeout (seconds) |
apiLoopTimeoutSeconds |
300 |
Tool-call loop total timeout (seconds) |
commandExecTimeoutSeconds |
30 |
Per-command execution timeout (seconds) |
wikiConnectTimeoutSeconds |
5 |
Wiki search connect timeout (seconds) |
wikiRequestTimeoutSeconds |
8 |
Wiki search request timeout (seconds) |
maxChainCommands |
10 |
Max commands per chain |
contextMaxChars |
20000 |
Max context chars for AI (auto-truncated) |
maxToolCalls |
15 |
Max tool calls per conversation turn |
activePersona |
"default" |
Current persona ID |
personaLanguage |
"" |
Persona language override, empty=follow client language |
promptLanguage |
"zh_cn" |
Built-in prompt language |
enableChatInterception |
true |
Intercept chat and forward to AI |
enableCommandExecution |
true |
Allow AI to execute commands |
enableAutoReview |
true |
Enable auto behavior review |
maxReviewCycles |
4 |
Max review analysis cycles |
systemPromptPath |
"" |
System prompt file (under config/mcai/) |
reviewPromptPath |
"" |
Review prompt file |
reviewApiEndpoint |
"" |
Review system API endpoint, empty=follow chat config |
reviewApiKey |
"" |
Review system API key, empty=follow chat config |
reviewModel |
"" |
Review system model, empty=follow chat config |
Prompt files system_prompt.txt / review_prompt.txt are auto-created on first start. Run /airesetprompts to force-sync them to the current built-in versions.
Knowledge Base
AI knowledge search is done via online Wiki — no manual data import needed.
Links
Github
License
MIT License
评论 0
登录后参与评分
还没有评论,来抢沙发吧