让 AI 替你砍树挖矿：AIRI 的 Minecraft Agent 架构全解析与本地跑通指南-平芜编程栈

让 AI 替你砍树挖矿：AIRI 的 Minecraft Agent 架构全解析与本地跑通指南

【免费下载链接】airi💖🧸 Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi

AIRI 是一个自托管的 AI 虚拟伙伴项目，它的 Minecraft 集成让 AI 机器人真正登录服务器，听懂指令后砍树、挖矿、合成、盖房，生存本能还不花一分 token。

一个反常识的画面

先说个细节：当机器人血量掉到 3 格时，它不需要调用任何大模型，几毫秒内就会从物品栏掏出食物啃起来；僵尸一拳打过来，它的反击同样不经过 AI 推理。AIRI 做到了让 AI 以"可感知的角色"身份活进 Minecraft，而不只是调调 API。

项目速览

🗣️听懂指令：对机器人说"帮我建一座房子"，它会采集木材、合成木板、搭建墙体
🧠LLM 驱动决策：默认走 DeepSeek 等 OpenAI 兼容接口，可换成任意兼容服务
⚡无需 LLM 的生存本能：自动进食、自动反击、逃离危险，零 token 消耗
🔌双向回连 AIRI 主体：通过 WebSocket 把游戏状态上报给桌面端角色，形成双线叙事

服务入口在 integrations/minecraft/src/main.ts：读配置、连 AIRI、创建带自动重连的 Mineflayer（Node.js 版 Minecraft 协议库）机器人。

从零跑起来

前置条件：一个 Java 版 1.20 的 Minecraft 服务器（本地起一个即可）+ pnpm。

安装依赖：

git clone https://gitcode.com/GitHub_Trending/ai/airi cd airi pnpm i

配置：复制模板后编辑integrations/minecraft/.env.local，所有项由 composables/config.ts 里的 Zod Schema 严格校验：

cp integrations/minecraft/.env integrations/minecraft/.env.local

变量	说明
`OPENAI_API_KEY`/`OPENAI_API_BASEURL`	LLM 密钥与接口地址，兼容任意 OpenAI 协议服务
`OPENAI_MODEL`/`OPENAI_REASONING_MODEL`	对话模型与推理模型，默认 deepseek-chat / deepseek-reasoner
`BOT_USERNAME`/`BOT_HOSTNAME`/`BOT_PORT`	机器人名、服务器地址、端口（默认 25565）
`BOT_AUTH`	认证方式：`offline`/`mojang`/`microsoft`
`AIRI_WS_BASEURL`	AIRI 服务端 WebSocket 地址，默认`ws://localhost:6121/ws`
`ENABLE_MCP_SERVER`等	调试开关，默认全部关闭

启动：

pnpm -F @proj-airi/minecraft-bot dev

⚠️安全事项（官方 README 原样强调）：请勿连接不受信任的公开服务器。该 Agent 会执行 LLM 生成的 JavaScript 动作脚本来驱动真实进程，恶意服务器可能诱导它做出危险操作；MCP Server、Debug Server、Prismarine Viewer 三个调试端点均无鉴权，绝不能暴露到公网。

核心设计拆解

整套架构放在 src/cognitive/，按"感知 → 反射 → 意识 → 行动"四层组织，事件驱动、层间松耦合。

机器人怎么知道"自己受伤了"

感知层（src/cognitive/perception/）解决的是"把 mineflayer 的原始网络信号变成有意义的认知"。机制：事件定义把受伤、移动、聊天等原始信号归一化，再由 YAML 规则引擎评估后发出signal:*信号。比如 danger/damage.yaml 声明"500ms 窗口内受到任意伤害"即产生高显著性信号，附带伤害量与来源。想新增感知能力？加一个 YAML 文件就行。

为什么有些反应绝不能走 LLM

等 LLM 回完一轮，玩家早被僵尸拍死了。反射层（src/cognitive/reflex/）用有限状态机（FSM）实现"膝跳反应"：auto-eat.ts 在血量 ≤6 且饥饿值 <18 时立刻吃食物——注意这个细节：饱食度 ≥18 时身体已经在自然回血，此时进食纯属浪费食物，所以被刻意排除，连源码注释都写明了。还有防御反击与逃离危险。生存反射优先级最高（score=1000），并能向意识层发送 Inhibition 信号，阻止 LLM 做出冗余决策。

为什么 LLM 输出 JavaScript 而不是工具调用

传统 Function Calling 输出死板的 JSON，表达力有限。意识层（src/cognitive/conscious/）的做法更野：brain.ts 编排事件队列与 LLM 轮次，js-planner.ts 让 LLM 直接输出可执行的 JavaScript 脚本，在 isolated-vm 沙箱中运行；query-dsl.ts 提供只读世界查询，脚本里甚至能用query.map()生成 ASCII 俯视图"看"周围地形。系统提示词见 brain-prompt.md，亮点是"值优先规则"：先跑纯观察轮，下一轮才基于确认过的数据行动，避免 AI"想当然"。

"想"和"做"如何彻底分开

行动层（src/cognitive/action/）只负责执行：task-executor.ts 跑规范化动作指令，action-registry.ts 做参数校验与分发。原子技能在 src/skills/：挖矿、伐木、合成、战斗、导航。movement.ts 内置 A* 寻路且会自动挖开挡路的方块——机器人从地底爬到地表，一次goToCoordinate调用搞定。

一条链路走查：盖一座房子

玩家: "build a house" ↓ [感知层] 聊天事件被识别为指令 ↓ [意识层] Brain 排队事件，JS Planner 在沙箱中规划结构 ↓ [行动层] TaskExecutor 管理建造循环： ① 采集木材 → ② 合成木板 → ③ 搭建墙体 ↓ [反射层] 期间掉血？自动进食，不打断建造 ↓ [意识层] Brain 确认完成，经 AIRI 桥接上报"房子建好了"

调试与进阶

src/debug/ 下有一整套本地调试面板：开ENABLE_DEBUG_SERVER用 Web 界面实时看认知状态与动作，开ENABLE_MCP_SERVER手动向 Brain 注入脚本当"神之手"，开ENABLE_MINECRAFT_VIEWER在浏览器第一人称看世界。都别暴露到公网。

项目地图

模块	路径	职责
认知引擎入口	src/cognitive/index.ts	四层组件装配与生命周期
依赖注入容器	src/cognitive/container.ts	Awilix DI 接线
AIRI 桥接	src/airi/airi-bridge.ts	状态/指令双向同步
机器人运行时	src/minecraft-bot-runtime.ts	自动重连、热重配置
原子技能库	src/skills/	挖矿、伐木、合成、战斗、寻路

写在最后

要说局限：官方 README 已声明 Mineflayer 方案处于弃用过渡期，未来的主力形态是 Fabric Mod 运行时，不建议围绕它堆长期功能。但恰恰因为四层解耦干净，这套"有感官、有本能、有理性、有手脚"的设计几乎可以整体移植——任何想构建游戏 Agent 的人，抄它的分层思路都比抄它的代码更值。

AI 进游戏这件事，拼的从来不是模型多强，而是你敢不敢把"活下来"这件事从 prompt 里拿出来。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考