企业官网建设流程全解析

• 人工智能
• AI Agent
• MCP 服务
• 工具调用
• GUI 自动化
• 语音
• 数字人
• 交互助手

本篇技术指南围绕 Minecraft 智能体集成文档 展开，讲解 AIRI 如何通过 Mineflayer 连接 Minecraft 服务器，让智能体接收上下文、执行游戏内动作并回传状态。你将掌握从源码安装、.env.local配置、桌面端 Auth Token 绑定到启动联调的全过程，并深入理解其底层“感知 → 反射 → 意识 → 动作”四层认知架构与 AIRI 事件桥接机制，为基于可信服务器的本地开发与维护提供可直接落地的实战方案。

一、集成概览与适用场景

Minecraft 集成是 AIRI 众多“赛博生命”落地载体之一。它通过 Mineflayer 这类 Node.js 机器人库，将 AIRI 与 Minecraft 服务器连接起来：智能体既能从游戏中接收上下文，也能执行游戏内动作，并把自身状态回传给 AIRI。

从仓库现状看，该服务是一个独立的 pnpm workspace，名为@proj-airi/minecraft-bot（见 integrations/minecraft/package.json），其职责在 integrations/minecraft/README.md 中有明确描述：

它把 Mineflayer 运行时连接到 Minecraft 服务器，加载src/cognitive中的认知栈，并将状态、上下文和命令流量桥接回 AIRI，使 Stage 设置外壳可以观察该服务。

适用场景：面向本地开发和维护。需要注意，README 与集成文档都明确标注了弃用（Deprecation）声明——当前基于 Mineflayer 的实现有计划迁移到 Fabric 运行时，因此在 Mineflayer 上开展新的长期功能开发并不被推荐；现有能力仍可用于当前本地开发与维护。

二、前提条件与源码安装

当前 Minecraft 智能体仅支持从源码安装使用。搭建本地开发环境时，需要依次满足以下前提：

1. 仓库根目录已安装依赖：

   pnpm i

2. 可访问的本地或受信任 Minecraft 服务器：连接地址与端口由配置文件提供。

3. 可用的 AIRI 与模型服务配置：即 AIRI 本体的 WebSocket 服务可访问。

4. 可用的 OpenAI 兼容 API：为智能体的“大脑”（LLM 规划/对话代理）提供推理能力。

::: warning 凭据安全 API Key、服务地址和 Minecraft 服务器凭据只应保存在本地.env.local文件中。不要提交、截图或发送这些配置。 这里配置的 API Key 与 AIRI 本体不相同且不互通，建议为 Minecraft 服务配置独立的 Key。 :::

这一点在 启动后台客户端 的日志提示中也有呼应：若AIRI_WS_TOKEN配置错误，会提示到Settings → Connection复制令牌并重启机器人。

三、配置：从模板到.env.local

3.1 复制模板

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

然后编辑integrations/minecraft/.env.local，填写 Minecraft 服务器、AIRI 与模型服务所需的配置。

3.2 获取并绑定 AIRI Auth Token

在桌面版中，打开设置 → 连接，显示并复制Auth Token，然后添加以下 AIRI 通道配置：

AIRI_WS_BASEURL=ws://localhost:6121/ws AIRI_CLIENT_NAME=minecraft-bot AIRI_WS_TOKEN=<Auth Token from Settings → Connection>

• AIRI_WS_BASEURL：AIRI 服务端的 WebSocket 地址，默认ws://localhost:6121/ws，仅接受ws:或wss:协议（由 config.ts 的wsUrlString校验）。
• AIRI_CLIENT_NAME：机器人在 AIRI 侧的注册名称，默认minecraft-bot；桌面端下发命令时正是向该名称的通道发送spark:command。
• AIRI_WS_TOKEN：AIRI 的认证令牌。若令牌变更，需同步更新.env.local并重启机器人。

3.3 必填字段表（以 DeepSeek 为例）

以下字段为必填项，表内以 DeepSeek 为例给出填写建议（摘自集成文档）：

3.4 配置的底层校验与默认值

从源码看，所有环境变量在启动时都会经过 config.ts 中Zod schema的严格校验：

• OPENAI_API_BASEURL必须是http/https合法 URL；OPENAI_API_KEY、OPENAI_MODEL、OPENAI_REASONING_MODEL均不允许为空字符串；
• BOT_PORT必须是 1～65535 之间的整数；
• BOT_AUTH必须是mojang、microsoft、offline三者之一；
• 校验失败时initEnv()会抛出错误并终止启动，日志中会打印形如path: message的精确错误位置。

同时，config.ts内置了一套默认值，未设置时可兜底：

另有两个可选配置值得留意：

• BOT_AUTH：默认离线登录；如需正版登录，参考integrations/minecraft/.env中说明，取消注释BOT_AUTH='microsoft'，启动时弹出微软账号认证链接。.env模板中附有关于认证令牌缓存位置（${hash}_live-cache.json等，位于~/.minecraft、~/Library/Application Support/minecraft、%appdata%/.minecraft）的详细注释。
• BOT_MASTER_USERNAME：机器人在游戏内的主人用户名。配置后机器人会把该玩家识别为“主人”（例如被主人击打时不会逃跑），并出现在回传 AIRI 的状态上下文中。

3.5 调试与开发开关（默认关闭）

.env模板还提供了三个调试开关，用于开发期观察机器人的内部状态：

ENABLE_MCP_SERVER=false ENABLE_DEBUG_SERVER=false ENABLE_MINECRAFT_VIEWER=false

• ENABLE_MCP_SERVER：启动 MCP REPL 服务，可在 调试服务 中以 REPL 方式向 Brain 注入代码执行；
• ENABLE_DEBUG_SERVER：启动 Debug 仪表盘 / Web 端调试服务（见 debug/server.ts）；
• ENABLE_MINECRAFT_VIEWER：通过 prismarine-viewer 在3007端口以第一人称视角渲染机器人视野（见 main.ts 的setupMineflayerViewer）。

::: warning 安全警示 MCP Server、Debug Server、Prismarine Viewer 端点完全无认证。开启后任何能访问到这些端口的人都可以读取机器人内部状态甚至导致远程代码执行（RCE），切勿暴露到公网或不可信的内网。 :::

四、启动与运行

在仓库根目录执行：

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

或者在integrations/minecraft/目录内直接执行：

pnpm dev

对应的脚本定义为tsx --env-file=.env --env-file-if-exists=.env.local src/main.ts（见 package.json），即优先加载.env模板，若存在.env.local则覆盖之——这正是“只把密钥写进.env.local”能生效的原因。

启动后，智能体会自动连接 AIRI 与 Minecraft 服务器。开发环境可查看终端日志确认连接和动作状态。在游戏中发送文字即可与 AIRI 交互，例如!pause可以暂停/恢复认知引擎（见 CognitiveEngine 的 chat 事件处理）。

4.1 启动流程拆解

从 main.ts 可以看到完整的启动链路：

1. initLogger()初始化日志，initEnv()校验并加载环境变量；
2. 若开启了调试开关，打印安全警示横幅；
3. 创建 AIRI 客户端Client，以name: config.airi.clientName连接AIRI_WS_BASEURL。这里有一个值得注意的实现细节：由于 Mineflayer 数据包处理偶尔会让 Node 事件循环静默约 30 秒，默认 30s 的 readTimeout 会导致连接被误判为断开，因此代码将心跳读超时放宽到120s、心跳间隔设为20s；
4. 通过MinecraftBotRuntime创建受管理的机器人：组装mineflayer-armor-manager、mineflayer-auto-eat、mineflayer-collectblock、mineflayer-pathfinder、mineflayer-pvp、mineflayer-tool六个插件，并启用最多 5 次的重连；
5. 向机器人加载CognitiveEngine认知引擎（见 cognitive/index.ts），把 AIRI 客户端注入认知容器；
6. 监听module:configure事件，动态更新机器人配置（如启用/停用、换服务器）。

机器人生命周期由 minecraft-bot-runtime.ts 管理：监听spawn/end/kicked/error事件并广播bot:connected/bot:disconnected/bot:error，支持运行时热切换配置。

五、四层认知架构：感知 → 反射 → 意识 → 动作

Minecraft 智能体的核心是四层认知架构（受认知科学启发，让机器人具备反应式、意识式与身体化行为），完整结构图见 README.md 中的 mermaid 图。其设计原则包括：关注点分离（各层职责独立）、事件驱动（通过集中事件总线解耦）、抑制控制（反射层拦截不必要的 LLM 调用）、可扩展性与认知仿真。

各层职责与关键源码如下：

5.1 Layer A：感知层（Perception）

位置：src/cognitive/perception/

感知层是“感觉输入中枢”，收集原始 Mineflayer 信号，并通过“事件注册表 + 规则引擎”流水线转换为类型化事件/信号：

• events/definitions/ 中的事件定义把 Mineflayer 事件绑定为标准化原始事件，现有定义包括system_message、arm_swing、sneak_toggle、entity_moved、fall_tracker、attacker_tracker、low_health、damage_taken（见 definitions/index.ts）；
• EventRegistry向认知事件总线发出raw:<modality>:<kind>事件；
• RuleEngine（见 rules/engine.ts）评估 YAML 规则并发出派生的signal:*事件，供反射/意识层消费。

感知流水线的初始化入口见 pipeline.ts，它把事件注册表挂载到 bot 上，扫描距离默认 32 格。

YAML 规则示例（social/teabag.yaml）：检测玩家快速潜行（teabagging）行为——以sighted:sneak_toggle为触发条件，在 1 秒滑动窗口内阈值 6 次，输出social_gesture信号。类似的规则还有 attention/movement.yaml（玩家移动，2 秒窗口内 14 次触发entity_attention）与 danger/low-health.yaml（血量危急，发出带有“先脱离火/岩浆/水、撤退进食”指引的saliency_high信号）。

5.2 Layer B：反射层（Reflex）

位置：src/cognitive/reflex/

反射层负责即时、本能式的反应，基于有限状态机（FSM）模式实现可预测的快速响应：

• reflex-manager.ts：协调反射行为，订阅signal:*事件并管理行为列表；
• 内置行为：escapeHazardBehavior（逃离危险）、defendBehavior（自卫）、autoEatBehavior（自动进食）、idleGazeBehavior（空闲注视），注册于反射运行时；
• 抑制机制（Inhibition）：反射层可以抑制意识层的处理，避免冗余的 LLM 调用。例如entity_attention信号完全由反射行为处理、不再转发；机器人在主动攻击时，常规damage信号被抑制（防止战斗抖动），而危急血量仍通过独立low_health信号传达给大脑。

反射层通过shouldForwardSignalToConscious决定哪些信号进入意识层（见 reflex-manager.ts）。

5.3 Layer C：意识层（Conscious）

位置：src/cognitive/conscious/

意识层负责复杂推理、规划与高层决策，不再承担任何物理执行：

• Brain（brain.ts）：事件队列编排、LLM 回合生命周期、安全/预算护栏、调试 REPL 集成，是认知系统的核心循环；
• JavaScript Planner（js-planner.ts）：基于isolated-vm的沙箱规划/运行时，向规划脚本暴露受限的工具与全局量，支持超时、内存上限、每回合动作数与桥接调用上限等约束；
• Query DSL（query-dsl.ts）：面向规划脚本的只读世界/背包/实体查询助手；
• Task State（task-state.ts）：取消令牌与任务生命周期原语；
• Patterns（patterns/）：行为模式目录与运行时，用于识别并复用常见决策套路。

LLM 代理（llm-agent.ts）基于 xsai 封装，直接使用OPENAI_API_BASEURL/OPENAI_API_KEY/OPENAI_MODEL构造（见 container.ts）。

5.4 Layer D：动作层（Action）

位置：src/cognitive/action/

动作层负责在世界中实际执行任务，把“做”（Doing）与“想”（Thinking）隔离：

• Task Executor（task-executor.ts）：执行规范化动作指令并发出动作生命周期事件（action:started/action:completed/action:failed）；
• Action Registry（action-registry.ts）：校验参数并分发工具调用；
• Tool Catalog（llm-actions.ts）：动作/工具定义与 schema，绑定到 Mineflayer 技能。已注册动作包括chat、giveUp、skip、stop、goToPlayer、collectBlock、placeBlock、breakBlockAt、equip、discard、putInChest、takeFromChest等。

底层技能（Skills）封装在 src/skills/：移动/寻路（movement.ts，基于mineflayer-pathfinder的GoalNear，支持/tp作弊传送）、战斗（combat.ts，自动装备最高攻击力武器并扫描 48 格内目标）、采集（collect-block.ts）、合成（crafting.ts）、容器交互（containers.ts）等。

5.5 事件流示例：“建造一栋房子”

Player: "build a house" ↓ [Perception] Event detected ↓ [Conscious] Architect plans the structure ↓ [Action] Executor takes the plan and manages the construction loop: - Step 1: Collect wood (calls ActionRegistry tool) - Step 2: Craft planks - Step 3: Build walls ↓ [Conscious] Brain confirms completion: "House is ready!"

六、AIRI 事件桥接：智能体如何“连接”桌面端

除游戏内聊天外，智能体还通过AiriBridge（airi-bridge.ts）与 AIRI 服务端进行结构化通信，这也是文档中“接收上下文、执行游戏内动作并回传状态”的技术底座：

• 接收spark:command：AIRI 服务器的高层指令（携带 intent / interrupt / priority / guidance 等字段）会被转换为signal:airi_command事件，强制触发一次新的意识决策循环——即使被标记为contextintent 也不会静默归档，避免指令被“悄悄丢弃”；
• 接收context:update：作为被动上下文写入历史（signal:airi_context），不唤醒决策循环；
• 发送spark:notify：向proj-airi:stage-*目标推送通知（如“机器人上线”事件）；
• 发送context:update：把 Minecraft 状态上下文（服务器、坐标、血量、游戏模式、在线玩家、主人用户名等）回传给 AIRI，并声明“桌面命令中继可用”，指导 Stage 调用builtIn_emitSparkCommand工具向minecraft-bot通道下发指令；
• 发送spark:emit：对命令回执queued/working/done/dropped等状态；
• setCommandAvailable作为最终接收侧可用性闸门：机器人离线时，命令会被回执为dropped。

该桥接行为由 airi-bridge.test.ts 覆盖验证。Minecraft 状态上下文的发布则封装在 minecraft-context-service.ts，它每 5 秒刷新一次状态（minecraft:statuslane），机器人在线/离线时分别生成不同的状态文本，让桌面端明确知道“命令中继是否可用”。

七、安全与限制

::: danger 安全警告 不要将该智能体连接到不受信任的公共服务器。它会驱动本地 Minecraft 会话和网络连接；即使动作计划在隔离环境中执行，恶意服务器仍可能造成非预期行为。 :::

这条警告并非空穴来风，从源码可得到三重印证：

1. 可执行任意动作计划：动作执行链路（Task Executor → Action Registry → Skills）最终会驱动真实的本机进程控制 Minecraft 会话，具备本机网络可达性与部分机器侧资源访问能力；
2. 调试端口无认证：MCP Server / Debug Server / Prismarine Viewer 一旦开启即为未认证端点，暴露即意味着机器人内部状态甚至 RCE 风险（main.ts 启动时会打印醒目的安全横幅）；
3. 隔离不等于无害：JavaScript Planner 虽在isolated-vm沙箱中运行，但沙箱只是限制脚本自身，机器人动作仍真实作用于世界与系统。

因此请只把它当作本地开发与受信任服务器专用工具：API Key、服务地址与服务器凭据只写入.env.local；密钥不与 AIRI 本体共用；不要在公网开放调试端口。

八、开发命令速查

在integrations/minecraft/目录下可用以下命令（见 package.json）：

九、结语

AIRI 的 Minecraft 智能体把 LLM 驱动的“大脑”装进了一个可以自由移动、采集、合成、战斗的赛博身体里：感知层把世界翻译成信号，反射层提供本能反应，意识层负责思考与规划，动作层负责落地执行，再通过 AIRI 事件桥接与桌面端闭环。当前实现面向本地开发与维护，并已在迁移到 Fabric 运行时的路线图上——如果你正在探索“给 AI 一个游戏身体”的落地形态，这份集成文档与integrations/minecraft目录下的源码、测试与 YAML 规则，是一份难得的完整参考。

• 人工智能
• AI Agent
• MCP 服务
• 工具调用
• GUI 自动化
• 语音
• 数字人
• 交互助手