人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手【免费下载链接】airi 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器目标是接近 Neuro-sama 的高度支持实时语音聊天、Minecraft 和 Factorio 游玩支持 Web / macOS / Windows。项目地址https://gitcode.com/moeru-ai/airi点击查看免费下载AIRI 的 Minecraft 集成是一个独立服务工作区它把 Mineflayer 运行时连接到 Minecraft 服务器加载位于 src/cognitive 的认知栈并通过 src/airi 桥接层将状态、上下文与命令流量回传 AIRI 主程序使 Stage 设置壳可以观察并驱动这个游戏内机器人。本文从部署配置、四层认知架构到 AIRI 桥接原理结合仓库源码逐层剖析这套能听懂自然语言、能自主玩 Minecraft的智能体实现读完即可掌握它的启动方式、事件流转链路与各层源码位置并了解当前 Mineflayer 运行时向 Fabric Mod 迁移的演进方向。服务定位与弃用说明这个工作区运行 AIRI 的专属 Minecraft 机器人服务包名为proj-airi/minecraft-bot见 package.json。它做的事情可以概括为三点把 Mineflayer 运行时接入 Minecraft 服务器让机器人真正进入游戏世界在机器人进程内加载完整的认知栈src/cognitive实现感知、反射、推理与行动通过src/airi桥接层把状态status、上下文context与命令command流量回传 AIRI供 Stage 设置壳观察服务状态。弃用说明Deprecation Notice该服务目前正处于弃用路径上。基于 Mineflayer 的机器人预计将被Fabric Mod 运行时取代后者将成为未来 Minecraft 集成的主要界面。仓库建议当前本地开发与维护仍可使用本服务但除非属于迁移计划的一部分否则不要在 Mineflayer 运行时之上构建新的长期功能。安全边界为什么只建议连接可信服务器原文档明确警告不要把这个机器人连接到你不信任的公网服务器。原因在于运行时可以执行由 JavaScript 生成的动作计划来控制机器人。这些脚本运行在隔离环境isolated-vm沙箱中但它们仍然驱动着一个真实的本地进程该进程拥有你的 Minecraft 会话、本地网络可达性以及其他机器侧资源。恶意或敌对服务器仍可能诱导机器人执行非预期动作甚至损害你的系统。请把本服务仅当作本地开发与可信服务器专用工具。这一警告在源码中同样醒目main.ts在开启 MCP 服务器、Debug 服务器或 Prismarine Viewer 时会打印完整的安全横幅明确指出这些端点完全没有鉴权暴露后可能导致远程代码执行RCE与机器人被完全接管.env 中的 debug 配置段也重复了同样的安全提示。环境准备与快速启动安装与启动步骤在仓库根目录安装工作区依赖pnpm i复制环境变量模板cp integrations/minecraft/.env integrations/minecraft/.env.local编辑integrations/minecraft/.env.local。在 AIRI 中打开Settings - Connection复制 WebSocket 认证令牌并填入AIRI_WS_TOKENpaste-your-token-here若令牌发生变化需要更新.env.local并重启机器人。启动服务两种等价方式# 从仓库根目录按工作区过滤执行 pnpm -F proj-airi/minecraft-bot dev# 或进入 integrations/minecraft/ 后直接执行 pnpm dev机器人应自动同时连接 AIRI 与 Minecraft 服务器。启动脚本细节见 package.json 的scriptsdev与start都通过NODE_OPTIONS--no-node-snapshot tsx --env-file.env --env-file-if-exists.env.local src/main.ts启动先加载模板.env若存在.env.local则叠加覆盖。环境变量清单与校验规则所有环境变量都由 src/composables/config.ts 中的 zod schema 集中校验启动时通过initEnv()执行safeParse非法配置会抛出错误并打印每个字段的具体原因。完整清单如下环境变量必填默认值说明OPENAI_API_BASEURL是—LLM API 基地址必须是 http/https URLOPENAI_API_KEY是—LLM API 密钥OPENAI_MODEL是deepseek-chat主对话模型OPENAI_REASONING_MODEL是deepseek-reasoner推理/规划模型AIRI_WS_TOKEN否—从 AIRI Settings - Connection 复制的 WebSocket 认证令牌AIRI_WS_BASEURL否ws://localhost:6121/wsAIRI 服务器 WebSocket 地址须为 ws/wssAIRI_CLIENT_NAME否minecraft-bot在 AIRI 中注册的客户端名称BOT_USERNAME是airi-bot机器人游戏用户名BOT_HOSTNAME是localhostMinecraft 服务器地址BOT_PORT否25565服务器端口1~65535 的整数BOT_AUTH否—认证方式mojang/microsoft/offlineBOT_VERSION否1.20Minecraft 协议版本BOT_MASTER_USERNAME否—机器人主人的游戏名用于让机器人识别主人例如主人攻击时不会逃跑ENABLE_MCP_SERVER否false开启 MCP REPL 服务器无鉴权谨慎ENABLE_DEBUG_SERVER否false开启调试服务器无鉴权谨慎ENABLE_MINECRAFT_VIEWER否false开启 Prismarine Viewer端口 3007无鉴权谨慎关于在线账号认证.env 给出了微软Microsoft认证的说明取消注释BOT_AUTHmicrosoft后机器人启动时会弹出认证链接登录令牌会以_live-cache.json、_mca-cache.json、_xbl-cache.json三个文件缓存在用户目录Linux 为~/.minecraftmacOS 为~/Library/Application Support/minecraftWindows 为%appdata%/.minecraft。连接可靠性调优src/main.ts 中对 AIRI 连接的心跳参数做了特殊调优机器人的 Node 事件循环偶尔会因繁忙的 mineflayer 数据包处理与感知 tick 静默约 30 秒导致默认 30s 的readTimeout被触发、连接被误杀从而让机器人频繁上下线。因此代码把读超时放宽到120 秒仍低于服务器单次漏跳 60 秒的 TTL并把 ping 间隔设为 20 秒保证事件循环一旦空闲即可立即恢复连接。四层认知架构总览AIRI 的 Minecraft 智能体建立在受认知科学启发的四层认知架构之上目标是让机器人具备反应式reactive、意识式conscious以及物理落地physically grounded的行为。整体架构如下这套架构的数据流主线是感知层收集所有事件 → 高优先级事件直达反射层、全部事件进入意识层 → 反射层可通过抑制信号阻止意识层做冗余的 LLM 调用 → 意识层规划后向执行层发起执行请求。在源码层面各层之间通过一个带链路追踪的中央事件总线解耦见 src/cognitive/event-bus.ts。它的关键设计包括每个事件带有idnanoid、traceId、parentId与时间戳emitChild可以基于父事件派生子事件形成完整调用链订阅模式支持*全量、prefix:*前缀匹配与精确匹配因此感知层产出raw:*、规则引擎产出signal:*、反射层转发为conscious:signal:*各层各取所需事件负载会被deepFreeze深冻结保证消费方无法篡改单个订阅者抛错不会拖垮整个分发循环。依赖装配由 src/cognitive/container.ts 通过 awilix 依赖注入容器完成eventBus、ruleEngine、perceptionPipeline、reflexManager、brain、taskExecutor、airiBridge、minecraftContextService都被注册为单例其中规则引擎的rulesDir特意使用fileURLToPath而非URL.pathname——因为后者在 Windows 上会产生/D:/...这种带前导斜杠的路径导致规则加载器静默读到 0 条规则、整个感知规则引擎失效。Layer A感知层Perception源码位置src/cognitive/perception/感知层是机器人的感官输入中枢它收集原始 Mineflayer 信号并通过事件注册表 规则引擎管道把原始信号翻译成带类型的事件/信号。核心管道如下events/definitions/*事件定义把 Mineflayer 事件绑定为归一化的原始事件EventRegistry发出raw:modality:kind事件到认知事件总线RuleEngine评估 YAML 规则产出供 Reflex/Conscious 层消费的signal:*派生事件。关键文件包括 events/index.ts、rules/engine.ts、rules/*.yaml 与 pipeline.ts。src/cognitive/perception/pipeline.ts 在init时以 32 格距离maxDistance: 32把事件注册表挂到 bot 上原始事件以raw:${modality}:${kind}命名写入事件总线。事件定义是高度工程化的以 events/definitions/damage-taken.ts 为例它监听 mineflayer 的health事件通过前后血量差判定伤害量再结合attacker-tracker记录真正造成伤害的实体与fall-tracker基于物理 tick 记忆下落过程以识别摔落伤害推断伤害来源判定顺序为岩浆 → 溺水 → 火焰 → 摔落 → 真实攻击者 → 最近实体 → unknown尽量规避主人站在旁边却被当成怪物攻击者这类误判。规则引擎由 src/cognitive/perception/rules/engine.ts 实现它订阅raw:*事件对每条 YAML 规则做事件类型匹配matchEventType、where 条件匹配matchWhere再交给时间窗检测器temporal-detector判断是否达到阈值触发触发后渲染描述模板并发出signal:type子事件。检测器支持threshold、window、mode滑动/滚动与groupBy按实体/来源/全局分组等参数默认时间槽slotMs为 20ms还保留 TypeScript 规则作为复杂逻辑的逃生舱。仓库在 rules.test.ts 中对规则解析、时间窗与模板渲染做了系统性测试。仓库内置的规则库生动展示了感知层的实际玩法rules/danger/damage.yaml 与 danger/low-health.yaml血量临界阈值 1、窗口 500ms时发出saliency_high信号提示先离开岩浆/火/水能吃的食物立刻吃生肉用熔炉烹饪没食物就撤退找食物attention/movement.yaml14 次移动/2 秒窗口触发entity_attention描述玩家 xxx 正在附近移动attention/punch.yaml10 格内 5 次挥臂/2 秒滑动模式判定为玩家在附近挥拳social/teabag.yaml1 秒内 6 次快速潜行判定为 teabag 社交手势。Layer B反射层Reflex源码位置src/cognitive/reflex/反射层负责即时、本能式的反应基于有限状态机FSM模式保证可预测、快速响应。组件Reflex Managerreflex-manager.ts协调各反射行为抑制机制Inhibition反射可以抑制意识层处理防止冗余的 LLM 响应。抑制机制在源码中体现为 shouldForwardSignalToConscious 这一纯函数规则相当精细entity_attention移动/挥拳注意类信号完全由反射行为处理永不转发给意识层机器人正在攻击bot.pvp.target存在时常规的damage信号会被抑制——否则脑层会在每次挨打时重新规划并stop自己的攻击形成边打边撤的致命抖动注释里明确提到这让机器人在对付放风筝的掠夺者时送命而关键的low_health信号action ! damage仍会送达脑层让它决定是否撤退。反射行为注册于 src/cognitive/reflex/runtime.ts运行时会为每个行为维护冷却时间 打分 模式匹配选择最高分的行为执行。行为实现位于 behaviors/auto-eat自动进食auto-eat.ts血量 ≤ 6约 3 颗心且饱食度低于 18 时零 token、不经过 LLM 直接进食最佳现成食物冷却 3 秒、优先级 1000碾压一切被动行为战斗期间不进食避免把武器换掉生肉留给意识层用熔炉烹饪。defend防御反击defend.ts仅当敌对生物实际对机器人造成伤害时才反击通过 attacker-tracker 判定绝不攻击玩家主人或任何玩家被攻击都属于意识层的决策范围它会持有整场战斗attackEntity跑到完成避免脑层每次受击都切换攻击/逃跑。escape-hazard危险逃离与idle-gaze空闲凝视等其余行为共同构成反射行为库。反射运行时还实现了自动跟随能力当处于空闲模式且跟随目标可见时通过GoalFollow让机器人跟随指定玩家一旦进入工作/游荡模式或防御战斗接管自动跟随会被压制战斗结束后自动恢复相关逻辑与注释见 runtime.ts。此外运行时设有 10 秒的BEHAVIOR_RUN_DEADLOCK_MS死锁断路器防止异步行为 Promise 永不落定时行为槽被永久锁死。Layer C意识层Conscious源码位置src/cognitive/conscious/意识层负责复杂推理、规划与高层决策。原文档特别强调物理执行已经不再发生在这一层思考与行动被严格分离。组件Brainbrain.ts事件队列编排、LLM 回合生命周期、安全/预算护栏、调试 REPL 集成。源码中可以看到它的工程细节事件按优先级分档玩家聊天与 AIRI 命令为最高优先级 0普通感知为 1系统反馈为 2无动作跟进为 3对话历史上限 200 条、事件队列上限 256、单次 LLM 尝试超时 60 秒还内置无动作跟进预算默认 3、上限 8防止模型在没做任何事时反复空转追问与错误爆发护栏5 回合内 3 次错误即触发引导模型调用giveUp并一次性说明原因。JavaScript Plannerjs-planner.ts在沙箱中执行规划/运行时逻辑仅暴露受控的工具与全局量。LLM 输出的候选代码会先经过语法防火墙纯散文回复含中文/日文等 CJK 叙述行会被识别并直接驳回避免意外标识符这类难懂的错误死循环通过isolated-vm工作线程执行默认单回合超时 750ms、内存上限 32MB、单回合最多 5 个动作、最多 64 次桥接调用、桥接超时 30 秒。脚本无法直接拿到 live 的 mineflayer 对象只能通过botCall桥按方法名调用且end、quit、事件订阅/派发等危险方法在BOT_METHOD_DENYLIST中被显式禁止位置型参数会自动封送为Vec3。Query Runtimequery-dsl.ts为规划脚本提供只读的世界/背包/实体查询助手包括方块查询链within、isOre、whereName、first、实体查询链whereType、whereName、背包查询链count、has、summary以及gaze、map、craftable等能力。源码特意为self暴露pos/position/location三个坐标别名因为 LLM 经常猜错属性名而崩溃对查询结果为空却读取坐标这类高频错误brain.ts 的augmentDecisionError还会把原始报错改写为带具体修复建议先判空再取坐标的可行动指导让模型下一回合就能自愈。Task Statetask-state.ts提供取消令牌CancellationToken与任务生命周期原语供动作执行层协作。入口src/cognitive/index.ts 把认知引擎作为 mineflayer 插件暴露在 bot 生成后装配容器、初始化各层并把游戏内聊天直接桥接为signal:chat_message事件机器人自己的消息会被过滤不会自问自答聊天中发送!pause可随时暂停/恢复认知引擎。Layer D执行层Action源码位置src/cognitive/action/执行层负责在世界中真正完成任务隔离做Doing与想Thinking。组件Task Executortask-executor.ts运行归一化的动作指令并发出动作生命周期事件action:started/action:completed/action:failed。中断类错误ActionError且 code 为INTERRUPTED不会产生失败反馈——这是stop工具被调用时的正常路径。Action Registryaction-registry.ts校验参数并派发工具调用。每个动作自带 zod schemaperformAction会先schema.parse校验 LLM 传来的参数再按 schema 定义的顺序调用底层技能。Tool Catalogllm-actions.ts动作/工具定义与 schema 集合绑定到 mineflayer 技能。仓库已内置的工具包括chat发聊天消息feedback默认 false 以避免反馈循环、giveUp承认卡住并暂停自主处理、skip跳过本回合、stop强制停止所有动作、goToPlayer带前后距离测量的寻路跟随、followPlayer/clearFollowTarget交给反射层管理的空闲自动跟随、goToCoordinate全 A* 寻路自动破拆挡路方块等底层技能分布在 src/skills/采集方块、合成、战斗、移动、容器、背包、世界交互等与 src/libs/mineflayer/bot 包装器、插件运行时。事件流示例建造一座房子原文档用建房子场景串起了整条认知流水线结合上面的源码可以还原每一步的真实调用链Player: build a house ↓ [Perception] 事件被检测到 ↓ [Conscious] 架构师Architect即 LLM 规划规划结构 ↓ [Action] 执行器Executor接管计划并管理建造循环 - Step 1: 收集木材调用 ActionRegistry 工具如 gather-wood / collectBlock - Step 2: 合成木板调用 crafting 技能 - Step 3: 建造墙壁调用 placeBlock / world-interactions ↓ [Conscious] Brain 确认完成House is ready!对应到真实代码路径玩家聊天经 index.ts 成为signal:chat_message→ ReflexManager 更新社交上下文并转发为conscious:signal:chat_message→ Brain 入队并驱动 LLM 回合 → LLM 输出 JS 计划经 JavaScriptPlanner 沙箱执行tool桥接调用 TaskExecutor → ActionRegistry 校验参数并派发到具体技能。整个回合的 LLM 输入、工具调用结果与错误都会写入llmLog供调试面板与下一回合的模型自省使用。项目结构integrations/minecraft/src/ ├── airi/ # AIRI 桥接、模块壳、状态发布 ├── cognitive/ # 感知 → 反射 → 意识 → 执行 │ ├── perception/ # 事件定义 规则评估 │ │ ├── events/ │ │ │ ├── index.ts │ │ │ └── definitions/* │ │ ├── rules/ │ │ │ ├── *.yaml │ │ │ ├── engine.ts │ │ │ ├── loader.ts │ │ │ └── matcher.ts │ │ └── pipeline.ts │ ├── reflex/ # 快速、基于规则的反应 │ │ ├── reflex-manager.ts │ │ ├── runtime.ts │ │ ├── context.ts │ │ └── behaviors/idle-gaze.ts │ ├── conscious/ # LLM 驱动的推理 │ │ ├── brain.ts # 核心推理循环/编排 │ │ ├── js-planner.ts # JS 规划沙箱 │ │ ├── query-dsl.ts # 只读查询运行时 │ │ ├── llm-log.ts # 回合/日志查询助手 │ │ ├── task-state.ts # 任务生命周期枚举/助手 │ │ └── prompts/ # Prompt 定义如 brain-prompt.ts │ ├── action/ # 任务执行层 │ │ ├── task-executor.ts # 执行动作并发出生命周期事件 │ │ ├── action-registry.ts # 工具派发 schema 校验 │ │ ├── llm-actions.ts # 工具目录 │ │ └── types.ts │ ├── event-bus.ts # 事件总线核心 │ ├── container.ts # 依赖注入装配 │ ├── index.ts # 认知系统入口 │ └── types.ts # 共享认知类型 ├── composables/ │ ├── config.ts # 环境变量 schema 默认值 │ ├── runtime-config.ts # 持久化的本地运行时配置 │ └── bot.ts ├── debug/ # 调试仪表盘、MCP REPL、viewer 集成 ├── libs/ │ └── mineflayer/ # Mineflayer bot 包装/适配器 ├── skills/ # 原子 bot 能力 ├── plugins/ # Mineflayer/bot 插件 ├── utils/ # 辅助工具 ├── minecraft-bot-runtime.ts # 机器人生命周期包装重连/重配置 └── main.ts # 机器人入口设计原则关注点分离Separation of Concerns每一层职责明确——感知负责接收反射负责本能意识负责思考执行负责动手事件驱动Event-Driven通过中央事件系统实现松耦合event-bus.ts抑制控制Inhibition Control反射防止不必要的 LLM 调用reflex-manager.ts可扩展性Extensibility新增反射行为或意识行为都很容易——反射行为只需注册进 runtime.ts 的registerBehavior新工具只需在 llm-actions.ts 追加定义认知真实性Cognitive Realism模拟人类感知 → 反应 → 深思的过程。未来增强路线原文档规划的增强方向仓库尚未实现属路线图内容感知层⏱️ 时间上下文窗口记住近期事件、 显著性检测过滤噪音、优先重要事件反射层 躲避敌对生物、️ 紧急战斗响应意识层 情绪状态管理、 长期记忆集成、 人格驱动响应。与 AIRI 服务器的桥接认知引擎与 AIRI 主程序之间通过 src/airi/ 两个核心模块通信airi-bridge.ts负责事件进出spark:command来自 AIRI 的高层指令intent可为plan/proposal/action/pause/resume/reroute/context。桥接层会把它路由为signal:airi_command强制唤醒一次全新的决策循环而不是静默塞进历史——即使指令误标为context意图也不会被吞掉真正的被动上下文走独立的context:update通道只入历史不唤醒循环context:update把 AIRI 的被动上下文注入认知事件流进入对话历史供模型参考module:announced模块宣告事件供其他子系统感知服务可用性回程方向spark:notify向 Stage 发送通知、spark:emit上报命令执行状态queued/working/done/dropped。minecraft-context-service.ts负责状态发布每 5 秒刷新一次minecraft:status上下文泳道把机器人用户名、服务器地址、坐标、血量、游戏模式、附近玩家、主人用户名等状态推给 AIRI并告诉 AIRI 如何通过内置工具builtIn_emitSparkCommand把用户的 Minecraft 指令放在guidance.options[0].label与steps中中继给机器人。同时main.ts 监听module:configure事件可在运行期通过 minecraft-bot-runtime.ts 的updateBotConfig动态重建机器人换服务器、改认证等SIGINT时优雅停止机器人并关闭 AIRI 连接。开发命令命令说明pnpm dev开发模式启动机器人pnpm lint运行 ESLintpnpm typecheckTypeScript 类型检查tsc --noEmitpnpm test运行测试vitest仓库配套了覆盖核心机制的测试可作为理解行为的活文档例如 rules.test.ts规则引擎、brain.test.ts脑层回合与预算、js-planner.test.ts规划沙箱与防火墙、query-dsl.test.ts查询 DSL、reflex-manager.test.ts反射转发/抑制、llm-actions.test.ts工具目录、airi-bridge.test.ts 与 minecraft-context-service.test.tsAIRI 桥接等。致谢与迁移展望该服务的认知架构设计受到了开源 Minecraft 智能体项目 mindcraft 的启发原文档的 Acknowledgements 部分明确致谢。在迁移层面随着 Fabric Mod 运行时成为未来的主集成面现有 Mineflayer 版本的职责将逐步收窄为本地开发与验证但四层认知架构、事件总线、YAML 规则引擎与思考/执行分离等核心设计仍然是后续 Minecraft 集成演进的重要资产。项目欢迎社区以 Pull Request 的方式参与贡献。赞分享人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手【免费下载链接】airi 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器目标是接近 Neuro-sama 的高度支持实时语音聊天、Minecraft 和 Factorio 游玩支持 Web / macOS / Windows。项目地址https://gitcode.com/moeru-ai/airi点击查看免费下载相关推荐AIRI Minecraft 智能体集成指南基于 Mineflayer 的四层认知架构与本地部署实践AIRI Minecraft 智能体集成指南基于 Mineflayer 的四层认知架构与本地部署实践 本篇技术指南围绕 Minecraft 智能体集成文档 h人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手后端AIRI Minecraft 集成基于 Mineflayer 的 LLM 游戏代理部署与四层认知架构解析AIRI Minecraft 集成基于 Mineflayer 的 LLM 游戏代理部署与四层认知架构解析 本指南介绍 AIRI 项目中 Minecraft 集人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手后端OpCore-Simplify6步生成OpenCore EFI指南OpCore Simplify6步生成OpenCore EFI指南 OpCore Simplify 把 OpenCore EFI 的搭建压到 6 步。硬件报告开发工具CLI上一篇open-pencil SDK:useNodeFontStatus 深入解析——在 Vue 编辑器中检测文本节点缺失字体下一篇OpCore Simplify黑苹果配置新革命一键安装告别技术门槛创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考