CraftAgent

模组

· 作者 prskid1000

一款 Minecraft Fabric 模组,将智能 AI 驱动的 NPC 带入你的世界。NPC 使用大型语言模型(LLM)来理解上下文、做出决策并与玩家互动。

0 本站下载 0 关注 更新于 10 个月前

最新 3.2.5 · 1.21.8 · Fabric

一键开服(送7天)

CraftAgent

一款 Minecraft Fabric 模组,将智能 AI NPC 带入你的世界。NPC 使用大型语言模型 (LLM) 来理解上下文、做出决策并与玩家互动。

功能

  • ? AI 驱动 NPC:使用 LLM(Ollama、LM Studio)进行智能决策
  • ? 自主行动:NPC 执行 Minecraft 命令与世界互动
  • ? 对话记忆:SQLite 持久化对话历史
  • ? 世界环境感知:NPC 理解周围环境(方块、实体、物品栏、导航、视线)
  • ? 多 LLM 支持:Ollama 和 LM Studio (OpenAI 兼容)
  • ? 客户端-服务器架构:客户端 GUI 配置,服务端处理 NPC 逻辑
  • ?️ 命令系统:使用 Brigadier 发现并执行所有 Minecraft 命令
  • ? Web 仪表板:内置 Web UI (),基于 LLM 处理间隔自动刷新
  • ? 邮件系统:NPC 可通过邮件系统发送和接收消息
  • ? 定向聊天消息:使用 "npcName: message" 格式向特定 NPC 发送消息,或向所有 NPC 广播
  • ? 记忆系统:私有和共享记忆(privateBook, sharebook)用于持久知识
  • ⚡ 结构化动作:LLM 返回包含消息和可执行动作的结构化输出
  • ? 实时更新:Web UI 自动更新,无需手动刷新
  • ? 导航系统:NPC 可前往坐标、实体或方块,并带有状态跟踪
  • ?️ 视线检测:NPC 检测其视线范围内的物品、实体和方块
  • ⚡ 动作状态管理:跟踪当前动作(挖掘、建造、制作、狩猎、农耕、钓鱼、战斗)
  • ?️ 高级动作:挖掘、建造、制作、狩猎、农耕、钓鱼和战斗动作
  • ⏸️ LLM 控制:切换以跳过每个 NPC 的 LLM 请求,以及手动触发 LLM 的命令

要求

  • Minecraft: 1.20.1 或 1.21.8
  • Java: 17 (1.20.1) 或 21 (1.21.8+)
  • Fabric Loader: 0.17.3+
  • LLM 服务: 本地运行的 Ollama 或 LM Studio

安装

对于玩家

  1. 从 Modrinth 或 CurseForge 下载最新的 JAR 文件
  2. 将 JAR 文件放入 mods 文件夹
  3. 安装并启动以下任一服务:
    • Ollama: 从 ollama.ai 下载并运行 ollama serve
    • LM Studio: 从 lmstudio.ai 下载并启动服务器
  4. 启动 Minecraft 并享受!

对于开发者

  1. 克隆仓库:

    git clone https://github.com/prskid1000/CraftAgent.git
    cd CraftAgent
    
  2. 构建项目:

    # Windows
    .\gradlew.bat :1.21.8:build
    
    # Linux/Mac
    ./gradlew :1.21.8:build
    
  3. 在 versions/1.21.8/build/libs/ 中找到编译后的 JAR 文件

构建

# 为特定版本构建
.\gradlew.bat :1.21.8:build

# 构建所有版本
.\gradlew.bat build

# 在开发环境中运行
.\gradlew.bat :1.21.8:runServer

用法

命令

  • /craftagent - 打开配置 GUI

  • /craftagent add <name> <llmType> - 创建新 NPC

  • /craftagent remove <name> - 移除 NPC(保留数据)

  • /craftagent <npcName> llm - 手动触发指定 NPC 的 LLM 调用(NPC 名称不区分大小写)

  • /craftagent <npcName> <action> - 在指定 NPC 上执行动作(NPC 名称不区分大小写)

    记忆动作:

    • /craftagent Steve sharedbook add "Iron Mine" "Iron mine located at coordinates 150, 64, -200"
    • /craftagent Steve sharedbook add BaseLocation "Our base is at spawn"
    • /craftagent Steve sharedbook remove "Iron Mine"
    • /craftagent Steve privatebook add "Secret Plan" "I will build a house tomorrow"
    • /craftagent Steve privatebook add Notes "Remember to craft more tools"
    • /craftagent Steve privatebook remove "Secret Plan"

    通信动作:

    • /craftagent Steve mail send Alice "Hello there! Want to mine together?"
    • /craftagent Steve mail send Bob "Found some diamonds at 200, 50, -100"

    导航动作:

    • /craftagent Steve travel to 100 64 200
    • /craftagent Steve travel to entity Zombie
    • /craftagent Steve travel to block iron_ore
    • /craftagent Steve travel stop

    挖掘动作:

    • /craftagent Steve mine iron_ore 5
    • /craftagent Steve mine diamond_ore
    • /craftagent Steve mine at 150 64 -200

    建造动作:

    • /craftagent Steve build stone_bricks at 100 65 200
    • /craftagent Steve place oak_planks at 101 65 201

    制作动作:

    • /craftagent Steve craft iron_pickaxe
    • /craftagent Steve craft wooden_sword

    狩猎动作:

    • /craftagent Steve hunt zombie
    • /craftagent Steve hunt Creeper
    • /craftagent Steve hunt Skeleton

    农耕动作:

    • /craftagent Steve farm plant wheat at 50 64 50
    • /craftagent Steve farm plant carrot at 51 64 51
    • /craftagent Steve farm harvest at 50 64 50
    • /craftagent Steve farm harvest

    钓鱼动作:

    • /craftagent Steve fish
    • /craftagent Steve fish stop

    战斗动作:

    • /craftagent Steve attack Zombie
    • /craftagent Steve attack zombie
    • /craftagent Steve defend

聊天消息

玩家可以通过聊天向 NPC 发送消息。消息会自动路由到 NPC:

  • 定向消息:steve: Do your homework - 仅发送给名为 "steve" 的 NPC(不区分大小写)
  • 广播消息:Do your homework - 发送给所有 NPC

NPC 名称匹配不区分大小写,因此 steve、STEVE 和 Steve 都匹配同一个 NPC。

有用的 Minecraft 键

  • F3: 打开显示坐标、FPS、区块信息和其他技术细节的调试屏幕。在给予 NPC 旅行指令时,可用于查找坐标。
  • F3+P: 切换失去焦点时的暂停状态。启用后,当你切换到其他窗口(Alt+Tab)时,游戏将继续运行,这有助于在后台监控 NPC。

Web 仪表盘

CraftAgent 包含一个内置的 Web 仪表盘,用于实时监控 NPC。该仪表盘会在 Minecraft 服务器启动时自动启动。

访问仪表盘:

  1. 启动安装了 CraftAgent 的 Minecraft 服务器
  2. 打开你的网页浏览器并导航至:
  3. 仪表盘将显示所有活跃 NPC 及其当前状态

仪表盘功能:

  • NPC 概览:查看所有 NPC 的基本信息(名称、年龄、性别、生命值、饥饿值、位置、当前动作、导航状态)
  • 状态选项卡:实时统计数据,包括生命值和饥饿值的进度条、位置坐标以及生物群系信息
  • 上下文选项卡:详细的世界上下文信息,包括:
    • 状态信息(位置、生命值、饥饿值、生物群系)
    • 物品栏详情(快捷栏、主物品栏、护甲、副手)
    • 附近方块表格(类型、位置、挖掘等级、所需工具)
    • 附近实体表格(名称、类型、ID、玩家状态)
    • 导航状态(当前状态、目的地、在该状态下的持续时间)
    • 当前动作(动作类型、描述、持续时间、特定于动作的数据)
    • 视线数据:
      • 视线内的物品(类型、数量、位置、距离)
      • 视线内的实体(名称、类型、ID、玩家状态)
      • 目标方块(NPC 注视的位置)
      • 可见方块(视线范围内可见的方块)
  • 消息选项卡:对话历史记录,带有角色徽章和时间戳
  • 邮件选项卡:来自其他 NPC 和玩家的邮件消息
  • 记忆选项卡:NPC 的持久化记忆,包括:
    • 私人书页(NPC 专属记忆)
    • 共享书页(所有 NPC 均可访问)

自动刷新:

  • 仪表盘基于最大 LLM 处理间隔进行自动刷新
  • 所有数据(NPC、消息、邮件、记忆)都会按照配置的间隔自动更新
  • 无需手动刷新——用户界面与服务器保持同步
  • 触发更新的时机包括:
    • 创建或删除 NPC
    • 对话历史中添加新消息
    • 发送或接收邮件消息
    • 记忆(私人/共享书页)更新

创建 NPC

  1. 启动你的 LLM 服务(Ollama 或 LM Studio)
  2. 使用 /craftagent create <name> <llmType> 或通过 /craftagent 打开 GUI
  3. 配置 NPC:
    • 名称:显示名称
    • LLM 类型:ollama 或 lm_studio
    • 模型:模型名称(例如 llama3)
    • URL:LLM 服务 URL(默认值:Ollama 为 http://localhost:11434,LM Studio 为 http://localhost:1234/v1)
    • 跳过 LLM 请求:切换此选项可禁用该 NPC 的自动 LLM 处理(适用于测试或在 LLM 服务不可用时使用)

控制 LLM 处理

  • 自动处理:NPC 会按照配置的间隔自动处理 LLM 调用(参见基础配置中的 llmProcessingInterval)
  • 跳过 LLM 请求:在 NPC 配置中启用“跳过 LLM 请求”切换开关,以禁用该 NPC 的所有 LLM 调用(包括自动和手动)
  • 手动触发:使用 /craftagent <npcName> llm 手动触发特定 NPC 的 LLM 调用(仅在 skipLLMRequests 禁用的情况下有效)

LLM 设置

Ollama

  1. 从 ollama.ai 安装
  2. 启动:ollama serve
  3. 拉取模型:ollama pull llama3
  4. 配置 NPC:LLM 类型 ollama,模型 llama3,URL http://localhost:11434

LM Studio

  1. 从 lmstudio.ai 安装
  2. 下载模型并启动本地服务器(端口 1234)
  3. 配置 NPC:LLM 类型 lm_studio,模型名称,URL http://localhost:1234/v1

架构

系统架构概览

graph TB
    subgraph "Client Side"
        GUI[OWO UI Screens]
        ClientNet[Client Network Manager]
        GUI --> ClientNet
    end
    
    subgraph "Server Side"
        Main[CraftAgent Mod]
        CmdMgr[Command Manager]
        NetHandler[Network Handler]
        NPCService[NPC Service]
        EventReg[EventListener Registerer]
        WebServer[Web Server :8080]
        
        Main --> CmdMgr
        Main --> NetHandler
        Main --> NPCService
        Main --> EventReg
        Main --> WebServer
    end
    
    subgraph "NPC Components"
        NPCFactory[NPC Factory]
        NPCEntity[Server Player Entity]
        EventHandler[NPCEventHandler]
        ContextProv[Context Provider]
        History[Conversation History]
        LLMClient[LLM Client]
        
        NPCService --> NPCFactory
        NPCFactory --> NPCEntity
        NPCFactory --> EventHandler
        NPCFactory --> ContextProv
        NPCFactory --> History
        NPCFactory --> LLMClient
    end
    
    subgraph "Data Layer"
        SQLite[(SQLite Database)]
        ConfigFiles[Config Files]
        Repos[Repositories]
        
        NPCService --> Repos
        Repos --> SQLite
        NPCService --> ConfigFiles
    end
    
    subgraph "External Services"
        Ollama[Ollama API]
        LMStudio[LM Studio API]
        
        LLMClient --> Ollama
        LLMClient --> LMStudio
    end
    
    ClientNet <--> NetHandler
    EventReg --> NPCService
    WebServer --> NPCService

组件架构

graph LR
    subgraph "核心服务"
        NPCService[NPC 服务<br/>生命周期管理]
        CoordinationService[协调服务<br/>NPC 通信]
        ConfigProvider[配置提供程序<br/>配置管理]
    end
    
    subgraph "NPC 实例"
        NPC[NPC 模型]
        EventHandler[事件处理器<br/>LLM 处理]
        ContextProvider[上下文提供程序<br/>世界状态]
        ConversationHistory[对话历史<br/>消息存储]
        MemoryManager[记忆管理器<br/>私有记忆]
    end
    
    subgraph "数据仓库"
        ConversationRepo[对话仓库]
        MessageRepo[消息仓库<br/>邮件系统]
        PrivateBookRepo[私人书籍仓库]
        SharebookRepo[共享书籍仓库]
    end
    
    subgraph "事件监听器"
        ChatListener[聊天消息监听器]
        AgeListener[年龄更新监听器]
        LLMScheduler[LLM 处理调度器]
    end
    
    NPCService --> NPC
    NPC --> EventHandler
    NPC --> ContextProvider
    NPC --> ConversationHistory
    NPC --> MemoryManager
    
    EventHandler --> ConversationHistory
    ContextProvider --> MessageRepo
    ContextProvider --> PrivateBookRepo
    ContextProvider --> SharebookRepo
    
    NPCService --> CoordinationService
    ChatListener --> NPCService
    AgeListener --> NPCService
    LLMScheduler --> EventHandler

NPC 生命周期流程

stateDiagram-v2
    [*] --> Created: /craftagent create
    Created --> Validating: 验证名称与配置
    Validating --> CheckingLLM: 名称有效
    Validating --> Error: 名称无效
    CheckingLLM --> Spawning: LLM 可达
    CheckingLLM --> Error: LLM 不可达
    Spawning --> Active: 实体生成
    Active --> Processing: LLM 调度器触发
    Processing --> Active: 响应已生成
    Active --> Removed: /craftagent remove
    Active --> Deleted: /craftagent delete
    Active --> Dead: 实体死亡事件
    Dead --> Removed: 自动移除
    Removed --> [*]: 数据保留
    Deleted --> [*]: 数据删除
    Error --> [*]

LLM 处理流程

sequenceDiagram
    participant Scheduler as LLM 处理调度器
    participant EventHandler as NPC 事件处理器
    participant History as 对话历史
    participant Context as 上下文提供程序
    participant LLM as LLM 客户端
    participant Ollama as Ollama/LM Studio
    participant ActionExecutor as 动作执行器
    participant WebServer as Web 服务器
    
    Scheduler->>EventHandler: processLLM()
    EventHandler->>History: performSummarizationIfNeeded()
    History-->>EventHandler: 如需则摘要
    EventHandler->>History: 获取对话消息
    EventHandler->>Context: buildContext()
    Context-->>EventHandler: WorldContext (状态、物品栏、方块、实体、记忆)
    EventHandler->>EventHandler: 格式化带上下文的消息
    EventHandler->>LLM: chat(messages, server)
    LLM->>Ollama: HTTP POST /api/chat
    Ollama-->>LLM: JSON 响应 {"message": "...", "actions": [...]}
    LLM-->>EventHandler: LLMResponse (结构化)
    EventHandler->>ActionExecutor: executeActions(actions)
    ActionExecutor->>ActionExecutor: 路由到处理器 (记忆、通信等)
    EventHandler->>History: 将响应添加到历史
    EventHandler->>ChatUtil: 发送消息到聊天
    EventHandler->>History: 存储响应
    EventHandler-->>Scheduler: 成功/失败

消息流程:玩家 → NPC

sequenceDiagram
    participant Player
    participant ChatListener as 聊天消息监听器
    participant NPCService
    participant MessageRepo as 消息仓库
    participant Context as 上下文提供程序
    participant LLM as LLM 客户端
    
    Player->>ChatListener: 发送聊天消息<br/>(定向: "npcName: message"<br/>或广播: "message")
    ChatListener->>ChatListener: 解析消息格式
    alt 定向消息 (npcName: message)
        ChatListener->>ChatListener: 按名称查找 NPC (不区分大小写)
        ChatListener->>NPCService: sendPlayerMessageToNpc(特定 NPC)
    else 广播消息
        ChatListener->>NPCService: sendPlayerMessageToNpc(所有 NPC)
    end
    NPCService->>MessageRepo: insert(message)
    MessageRepo-->>NPCService: 消息已存储
    Note over NPCService: 在下一次 LLM 调用期间,<br/>消息在上下文中可用
    NPCService-->>ChatListener: 完成
    ChatListener-->>Player: 消息已处理

消息流程:NPC → NPC

sequenceDiagram
    participant NPC1
    participant CoordinationService
    participant MessageRepo as 消息仓库
    participant NPC2
    participant ChatUtil
    participant Context as 上下文提供程序
    
    NPC1->>CoordinationService: sendDirectMessage(toNpc, message)
    CoordinationService->>MessageRepo: insert(message)
    MessageRepo-->>CoordinationService: 消息已存储
    CoordinationService->>ChatUtil: sendChatMessage()
    ChatUtil-->>NPC2: 在聊天中显示
    Note over CoordinationService: 在下一次 LLM 调用期间,<br/>消息在上下文中可用
    CoordinationService-->>NPC1: 完成

数据流架构

graph TD
    subgraph "输入源"
        PlayerChat[玩家聊天消息]
        GameEvents[游戏事件<br/>Tick、死亡等]
        WorldState[世界状态<br/>方块、实体、物品栏]
    end
    
    subgraph "处理层"
        EventHandler[事件处理器]
        ContextBuilder[上下文构建器]
        LLMProcessor[大语言模型处理器]
    end
    
    subgraph "存储层"
        ConversationDB[(对话历史)]
        MessageDB[(邮件消息)]
        PrivateMemoryDB[(私有记忆)]
        SharedMemoryDB [(共享记忆)]
        ConfigFiles[配置文件]
    end
    
    subgraph "输出"
        ChatOutput[聊天消息]
        CommandExecution[Minecraft 命令执行]
        WebDashboard[Web 仪表盘]
    end
    
    PlayerChat --> EventHandler
    GameEvents --> EventHandler
    WorldState --> ContextBuilder
    
    EventHandler --> LLMProcessor
    ContextBuilder --> LLMProcessor
    
    LLMProcessor --> ConversationDB
    EventHandler --> MessageDB
    EventHandler --> PrivateMemoryDB
    EventHandler --> SharedMemoryDB
    EventHandler --> ConfigFiles
    
    LLMProcessor --> ChatOutput
    LLMProcessor --> CommandExecution
    EventHandler --> WebDashboard

组件参考表

核心组件

组件 包名 职责 关键方法
CraftAgent me.prskid1000.craftagent 模组主初始化程序 onInitialize(), onStop()
NPCService me.prskid1000.craftagent.common NPC 生命周期管理 createNpc(), removeNpc(), deleteNpc()
NPCFactory me.prskid1000.craftagent.common NPC 实例创建 createNpc()
NPCEventHandler me.prskid1000.craftagent.event 事件处理与大语言模型调用 updateState(), processLLM()
ContextProvider me.prskid1000.craftagent.context 世界上下文收集 buildContext()
ConversationHistory me.prskid1000.craftagent.history 消息历史记录管理 add(), performSummarizationIfNeeded()
CoordinationService me.prskid1000.craftagent.coordination NPC 间通信 sendDirectMessage()
ActionProvider me.prskid1000.craftagent.action 将动作路由至处理器 executeAction(), isValidAction()
ActionProviderFactory me.prskid1000.craftagent.action 使用所有处理器创建 ActionProvider create()
ActionExecutor me.prskid1000.craftagent.action 执行由大语言模型生成的动作,解析命令 executeActions(), executeAction()
ActionParser me.prskid1000.craftagent.action 支持引号的通用命令解析器 parseQuotedArguments(), wasArgumentQuoted()
MemoryActionHandler me.prskid1000.craftagent.action 处理记忆相关动作 handleAction() (共享书/私有书)
CommunicationActionHandler me.prskid1000.craftagent.action 处理通信相关动作 handleAction() (发送邮件)
NavigationActionHandler me.prskid1000.craftagent.action 处理导航/移动相关动作 handleAction() (前往坐标/实体/方块)
MiningActionHandler me.prskid1000.craftagent.action 处理采矿相关动作 handleAction() (挖掘方块)
BuildingActionHandler me.prskid1000.craftagent.action 处理建造/放置相关动作 handleAction() (建造/放置方块)
CraftingActionHandler me.prskid1000.craftagent.action 处理制作相关动作 handleAction() (合成物品)
HuntingActionHandler me.prskid1000.craftagent.action 处理狩猎相关动作 handleAction() (猎杀怪物)
FarmingActionHandler me.prskid1000.craftagent.action 处理农耕相关动作 handleAction() (种植/收获作物)
FishingActionHandler me.prskid1000.craftagent.action 处理钓鱼相关动作 handleAction() (钓鱼/停止钓鱼)
CombatActionHandler me.prskid1000.craftagent.action 处理战斗相关动作 handleAction() (攻击/防御)
ActionStateManager me.prskid1000.craftagent.context 管理当前动作状态 setAction(), getActionDescription()
NavigationState me.prskid1000.craftagent.context 管理导航状态 setTravelingTo(), update(), hasArrived()
LineOfSightProvider me.prskid1000.craftagent.context 检测视线范围内的物品/实体/方块 getItemsInLineOfSight(), getEntitiesInLineOfSight()
WebServer me.prskid1000.craftagent.web 带有自动刷新功能的 Web 仪表盘 HTTP API 端点

事件监听器

监听器 包名 事件类型 用途
ChatMessageListener me.prskid1000.craftagent.listener ServerMessageEvents.CHAT_MESSAGE 通过邮件将玩家消息路由至 NPC。支持定向消息(格式:"npcName: message")和广播消息
AgeUpdateListener me.prskid1000.craftagent.listener ServerTickEvents.END_SERVER_TICK 随时间推移更新 NPC 年龄
LLMProcessingScheduler me.prskid1000.craftagent.listener ServerTickEvents.END_SERVER_TICK 为 NPC 调度大语言模型处理任务
EventListenerRegisterer me.prskid1000.craftagent.listener - 注册所有事件监听器

数据模型

模型 包 描述 关键字段
NPC me.prskid1000.craftagent.model 主要 NPC 数据结构 entity, llmClient, history, eventHandler, contextProvider, config
ConversationMessage me.prskid1000.craftagent.history 对话历史记录消息 message, role, timestamp
Message me.prskid1000.craftagent.model.database 邮件系统消息 senderUuid, recipientUuid, content, read
WorldContext me.prskid1000.craftagent.model.context 世界状态快照 state, inventory, nearbyBlocks, nearbyEntities, memoryData, navigation, lineOfSight, actionState
ContextData me.prskid1000.craftagent.model.context 上下文数据结构 BlockData, EntityData, ItemData, InventoryData, StateData, NavigationData, LineOfSightData, ActionStateData

仓库

仓库 包 用途 关键方法
ConversationRepository me.prskid1000.craftagent.database.repositories 对话历史记录存储 insert(), selectByUuid()
MessageRepository me.prskid1000.craftagent.database.repositories 邮件系统存储 insert(), selectByRecipient(), markAsRead()
PrivateBookPageRepository me.prskid1000.craftagent.database.repositories NPC 专属记忆 insert(), selectByUuid()
SharebookRepository me.prskid1000.craftagent.database.repositories NPC 间共享记忆 insert(), selectAll()

LLM 客户端

客户端 包 LLM 类型 API 端点
OllamaClient me.prskid1000.craftagent.llm.ollama Ollama /api/chat
LMStudioClient me.prskid1000.craftagent.llm.lmstudio LM Studio /chat/completions
LLMClient me.prskid1000.craftagent.llm 接口 -

配置

配置项 包 文件位置 用途
BaseConfig me.prskid1000.craftagent.config config/craftagent/base.json 全局设置(超时时间、区块半径等)
NPCConfig me.prskid1000.craftagent.config config/craftagent/npcs/{uuid}.json 每个 NPC 的设置(名称、LLM 类型、模型等)
ConfigProvider me.prskid1000.craftagent.config - 配置管理

数据流详情

上下文构建流程

graph LR
    A[ContextProvider.buildContext] --> B[获取 NPC 状态]
    A --> C[获取物品栏]
    A --> D[获取附近方块]
    A --> E[获取附近实体]
    A --> F[构建记忆数据]
    A --> G[构建导航数据]
    A --> H[构建视线数据]
    A --> I[构建动作状态数据]
    
    B --> J[StateData<br/>位置, 生命值, 食物值, 生物群系]
    C --> K[InventoryData<br/>护甲, 主手, 快捷栏, 副手]
    D --> L[BlockData 列表<br/>类型, 位置, 挖掘等级]
    E --> M[EntityData 列表<br/>ID, 名称, 是否为玩家]
    F --> N[记忆数据<br/>私有书, 邮件, 共享书]
    G --> O[NavigationData<br/>状态, 目标, 时间]
    H --> P[LineOfSightData<br/>物品, 实体, 方块]
    I --> Q[ActionStateData<br/>动作类型, 描述, 数据]
    
    J --> R[WorldContext]
    K --> R
    L --> R
    M --> R
    N --> R
    O --> R
    P --> R
    Q --> R

记忆系统结构

记忆类型 仓库 范围 访问模式
对话历史 ConversationRepository 每个 NPC 独立 生成时加载,关闭时保存
邮件消息 MessageRepository 每个 NPC 独立 接收时存储,访问时标记为已读
私人记忆 PrivateBookPageRepository 每个 NPC 独立 NPC 专属笔记和知识
共享记忆 SharebookRepository 全局 所有 NPC 均可访问

动作系统

NPC 可以通过结构化的 LLM 输出来执行动作。LLM 返回一个包含消息和动作列表的 JSON 响应:

{
  "message": "我发现了一个铁矿!",
  "actions": [
    "sharedbook add IronMine Location at 150, 64, -200",
    "mail send Alice Found iron, want to mine together?"
  ]
}

可用动作:

操作类型 格式 描述
记忆 - 共享书籍 sharedbook add <title> '<content>' 添加/更新共享记忆页面(所有 NPC 均可阅读)。标题可加引号或不加。内容必须用单引号 (') 或双引号 (") 包裹。
记忆 - 共享书籍 sharedbook remove <title> 移除共享记忆页面
记忆 - 私人书籍 privatebook add <title> '<content>' 添加/更新私人记忆页面(特定于某个 NPC)。标题可加引号或不加。内容必须用单引号 (') 或双引号 (") 包裹。
记忆 - 私人书籍 privatebook remove <title> 移除私人记忆页面
通信 mail send <npc_name> '<message>' 向另一个 NPC 发送邮件消息。收件人名称可加引号或不加。消息必须用单引号 (') 或双引号 (") 包裹。
导航 travel to <x> <y> <z> 前往指定坐标
导航 travel to entity <entity_name> 按名称前往附近的实体
导航 travel to block <block_type> 前往附近指定类型的方块
导航 travel stop 停止当前移动
采矿 mine <block_type> [count] 开采指定类型的方块(默认:1)
采矿 mine at <x> <y> <z> 在指定坐标开采方块
建造 build <block_type> at <x> <y> <z> 在坐标处放置方块(需要背包中有该方块)
建造 place <block_type> at <x> <y> <z> 放置方块(build 的别名)
制作 craft <item_name> 使用背包中的材料制作物品
狩猎 hunt <mob_type> 狩猎/攻击特定生物类型
狩猎 hunt <entity_name> 按名称狩猎/攻击实体
农耕 farm plant <crop_type> at <x> <y> <z> 在坐标处种植作物
农耕 farm harvest at <x> <y> <z> 在坐标处收割作物
农耕 farm harvest 收割附近成熟的作物
钓鱼 fish 开始钓鱼(抛出鱼竿)
钓鱼 fish stop 停止钓鱼(收杆)
战斗 attack <entity_name> 攻击特定实体
战斗 attack <entity_type> 按类型攻击实体
战斗 defend 进入防御姿态

操作解析:

  • 操作由 ActionExecutor 使用 ActionParser 工具进行一次解析
  • 解析器支持单引号和双引号,允许包含空格的参数
  • 解析后的数组传递给处理器:["sharedbook", "add", "title", "content"]
  • 内容和消息必须加引号,以处理多词文本和特殊字符

示例:

  • sharedbook add "My Title" "Content with spaces and special chars!"
  • sharedbook add title 'Simple content'
  • mail send "Alice" "Hello world message"
  • mail send Alice 'Hello world'

操作由 ActionExecutor 自动执行,它会解析命令并将它们路由到相应的处理器(MemoryActionHandler、CommunicationActionHandler 等)。

事件处理流程

graph TD
    A[游戏事件发生] --> B{事件类型}
    B -->|聊天消息| C[ChatMessageListener]
    B -->|服务器刻| D[AgeUpdateListener]
    B -->|服务器刻| E[LLMProcessingScheduler]
    
    C --> F[存储在邮件系统中]
    F --> H[在上下文中可用]
    
    D --> I[更新 NPC 年龄]
    I --> J[保存配置]
    
    E --> K[检查处理间隔]
    K -->|间隔已过| L[将 NPC 加入处理队列]
    L --> M[NPCEventHandler.processLLM]
    M --> N[构建上下文]
    N --> O[调用 LLM]
    O --> P[解析结构化响应]
    P --> Q{是否有操作?}
    Q -->|是| R[执行操作]
    R --> S[记忆/通信处理器]
    Q -->|否| T[更新历史记录]
    R --> T
    T --> U[发送聊天消息]
    U --> V[存储在历史记录中]

配置

配置文件位于 config/craftagent/ 目录下:

  • base.json:全局设置(超时时间、区块半径、调试模式)
  • npcs/{uuid}.json:每个 NPC 的设置(名称、LLM 类型、模型、性格)

基础配置字段

字段 类型 默认值 描述
llmTimeout int 30 LLM 请求超时时间(秒)
contextChunkRadius int 2 用于上下文的区块扫描半径
contextVerticalScanRange int 16 垂直方块扫描范围
maxNearbyBlocks int 50 上下文中最多包含的方块数
maxNearbyEntities int 10 上下文中最多包含的实体数
llmProcessingInterval int 5 LLM 处理周期之间的秒数
llmMinInterval int 2 NPC 处理之间的最小秒数
conversationHistoryLength int 5 摘要之前的最大聊天消息数
maxMessages int 50 每个 NPC 的最大邮件消息数
maxSharebookPages int 20 最大共享记忆页数
maxPrivatePages int 20 每个 NPC 的最大私人记忆页数
lineOfSightMaxRange int 64 视线检测的最大范围
lineOfSightItemDetectionRange int 32 视线内检测物品的范围

NPC 配置字段

字段 类型 默认值 描述
npcName String "Steve" 显示名称
uuid UUID random 唯一标识符
isActive boolean true NPC 是否处于活动状态
llmType LLMType LM_STUDIO LLM 提供商类型
llmModel String - 模型名称
ollamaUrl String " Ollama API URL
lmStudioUrl String " LM Studio API URL
age int 20 NPC 年龄(年)
gender String "neutral" 性别(male/female/neutral)
customSystemPrompt String "" 自定义系统提示覆盖
skipLLMRequests boolean false 如果为 true,则跳过向 LLM 发送请求(NPC 不会自动或手动处理 LLM 调用)

开发

关键组件

  • NPCService:管理 NPC 生命周期(创建、移除、删除、生成)
  • NPCEventHandler:处理事件和 LLM 交互,处理结构化输出
  • ContextProvider:收集世界状态信息(方块、实体、物品栏)
  • ActionProvider:将动作路由到相应的处理器(记忆、通信、导航、挖掘、建造、合成、狩猎、农耕、钓鱼、战斗)
  • ActionProviderFactory:工厂类,用于创建包含所有动作处理器的 ActionProvider,集中处理处理器创建逻辑
  • ActionExecutor:执行来自结构化 LLM 响应的动作,仅解析一次命令
  • ActionParser:支持引号参数的通用命令参数解析工具
  • MemoryActionHandler:处理与记忆相关的动作(共享书、私人书)
  • CommunicationActionHandler:处理通信动作(发送邮件)
  • NavigationActionHandler:处理导航/移动动作(前往坐标/实体/方块)
  • MiningActionHandler:处理挖掘动作(挖掘方块)
  • BuildingActionHandler:处理建造/放置动作(建造/放置方块)
  • CraftingActionHandler:处理合成动作(合成物品)
  • HuntingActionHandler:处理狩猎动作(猎杀生物)
  • FarmingActionHandler:处理农耕动作(种植/收获作物)
  • FishingActionHandler:处理钓鱼动作(钓鱼/停止钓鱼)
  • CombatActionHandler:处理战斗动作(攻击/防御)
  • ActionStateManager:跟踪当前动作状态并提供动作描述
  • NavigationState:管理导航状态(空闲、行进中、已到达)
  • LineOfSightProvider:检测 NPC 视线范围内的物品、实体和方块
  • MinecraftCommandUtil:通过 Brigadier 发现和执行 Minecraft 命令
  • LLMClient:LLM 提供商的接口(Ollama、LM Studio)
  • CoordinationService:通过邮件系统处理 NPC 间通信
  • WebServer:HTTP 服务器,用于通过自动刷新的 Web 仪表板监控 NPC

包结构

me.prskid1000.craftagent/
├── auth/              # 玩家授权
├── callback/          # 事件回调
├── client/            # 客户端代码(GUI、网络)
├── commands/          # Minecraft 命令
├── common/            # 核心服务(NPCService、NPCFactory)
├── config/            # 配置管理
├── constant/          # 常量和指令
├── context/           # 世界上下文收集
├── coordination/      # NPC 间通信
├── database/           # 数据持久化
│   ├── repositories/  # 数据库仓库
│   └── resources/     # 资源提供者
├── event/             # 事件处理
├── exception/         # 异常类
├── history/           # 对话历史
├── listener/          # 事件监听器
├── llm/               # LLM 客户端实现
│   ├── lmstudio/      # LM Studio 客户端
│   └── ollama/        # Ollama 客户端
├── memory/            # 记忆管理
├── mineskin/          # 皮肤管理
├── mixin/             # Minecraft Mixins
├── model/             # 数据模型
│   ├── context/       # 上下文数据结构
│   └── database/      # 数据库模型
├── networking/        # 网络数据包
├── thread/            # 线程管理
├── util/              # 工具类
└── web/               # Web 服务器

故障排除

  • NPC 无响应:检查 LLM 服务是否正在运行,验证配置文件中的 URL/模型
  • 命令无效:检查服务器日志,确保 NPC 具有所需权限
  • LLM 超时:在基础配置中增加 llmTimeout 或尝试使用更快的模型
  • 邮件无法工作:验证 MessageRepository 已初始化且 NPC UUID 正确
  • 上下文未更新:检查 ChunkManager 是否正在运行且区块已加载
  • 动作未执行:验证动作格式是否符合预期语法(参见“动作系统”部分)
  • Web UI 未更新:检查浏览器控制台是否有错误,验证服务器正在运行且刷新间隔已配置
  • 结构化输出解析失败:LLM 应返回包含 "message" 和 "actions" 字段的有效 JSON

贡献

欢迎贡献!请 Fork 项目,创建功能分支,并提交拉取请求。

许可证

本项目采用 LGPL-3.0 许可证。

链接

鸣谢

  • 作者:prskid1000
  • Fabric:模组加载器框架
  • Brigadier:命令系统(Mojang)
  • Ollama & LM Studio:LLM 提供商

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源