---

项目简介 | Project Overview

| 简体中文 | English |
|---------|---------|
| MineOpBot 是一个 Minecraft Java 版 Fabric 模组，通过 OpenAI 兼容 API 将 AI 助手集成到游戏中。玩家可以通过游戏内命令与 AI 进行对话，AI 可以理解玩家意图并执行游戏操作。 | MineOpBot is a Minecraft Java Edition Fabric mod that integrates an AI assistant into the game via OpenAI-compatible APIs. Players can chat with the AI using in-game commands, and the AI can understand player intentions and execute game actions. |

核心特性 | Core Features

| 简体中文 | English |
|---------|---------|
| AI 对话集成 - 支持 OpenAI 兼容 API（OpenAI、DeepSeek、Claude 等） | AI Chat Integration - Supports OpenAI-compatible APIs (OpenAI, DeepSeek, Claude, etc.) |
| 流式响应 - 实时显示 AI 回复，提供流畅的交互体验 | Streaming Responses - Real-time display of AI responses for smooth interaction |
| Action 系统 - AI 可通过 JSON 格式响应执行 Minecraft 命令 | Action System - AI can execute Minecraft commands via JSON-formatted responses |
| 多配置管理 - 支持多个 AI 配置，运行时动态切换 | Multi-Config Management - Supports multiple AI configs with runtime switching |
| 用户信息模式 (UIM) - 向 AI 提供玩家的完整游戏状态信息 | User Information Mode (UIM) - Provides AI with complete player game state information |
| 会话管理 - 每位玩家独立的聊天历史记录 | Session Management - Independent chat history for each player |

模块说明 | Module Description

1. Command Module (org.mineopbot.command) | 命令模块

| 简体中文 | English |
|---------|---------|
| 命令注册与处理模块，提供玩家与模组交互的入口。 | Command registration and processing module, providing the entry point for player interaction with the mod. |

command/
├── MineOpBotCommand.java      # 命令注册中心 | Command Registration Center
└── handler/
    ├── AiReplyHandler.java    # AI 回复协调器 | AI Reply Coordinator
    ├── MessageHelper.java     # 消息格式化工具 | Message Formatting Utility
    └── command/
        ├── ChatCommandHandler.java    # 聊天命令处理 | Chat Command Handler
        ├── ConfigCommandHandler.java  # 配置命令处理 | Config Command Handler
        └── StatusCommandHandler.java  # 状态命令处理 | Status Command Handler

2. AI Module (org.mineopbot.ai) | AI 模块

| 简体中文 | English |
|---------|---------|
| AI 核心功能模块，负责与 AI API 的交互。 | AI core functionality module, responsible for interacting with AI APIs. |

ai/
├── chat/
│   ├── AiChatManager.java              # 聊天会话管理 | Chat Session Manager
│   ├── AiChatStreamingResponseHandler.java  # 流式响应处理 | Streaming Response Handler
│   └── UserInformationMessage.java     # 用户信息构建 (UIM) | User Info Builder (UIM)
├── config/
│   ├── AiConfig.java           # 配置数据模型 | Config Data Model
│   ├── AiConfigManager.java    # 配置管理器 | Config Manager
│   └── AiConfigStore.java      # 配置持久化存储 | Config Persistent Storage
├── action/
│   ├── MineOpBotAction.java    # Action 接口定义 | Action Interface Definition
│   ├── ActionManager.java      # Action 注册与执行 | Action Registration & Execution
│   ├── ActionParser.java       # AI 响应解析器 | AI Response Parser
│   ├── ActionCallback.java     # 异步回调接口 | Async Callback Interface
│   └── command/
│       └── ExecuteCommandAction.java  # 命令执行 Action | Command Execution Action
└── util/
    └── UserMessageCommandParser.java  # 消息命令解析 | Message Command Parser

3. Mixin Module (org.mineopbot.mixin) | Mixin 模块

| 简体中文 | English |
|---------|---------|
| Mixin 扩展模块，用于修改或扩展 Minecraft 原版行为。 | Mixin extension module for modifying or extending vanilla Minecraft behavior. |

---

使用方法 | Usage

安装 | Installation

| 步骤 | Step | 中文说明 | English Description |
|-----|------|---------|---------------------|
| 1 | 1 | 确保已安装 Minecraft 1.21.4 和 Fabric Loader 0.18.4+ | Ensure Minecraft 1.21.4 and Fabric Loader 0.18.4+ are installed |
| 2 | 2 | 安装 Fabric API | Install Fabric API |
| 3 | 3 | 将模组 JAR 文件放入 mods 文件夹 | Place the mod JAR file into the mods folder |
| 4 | 4 | 启动游戏 | Launch the game |

配置 | Configuration

| 简体中文 | English |
|---------|---------|
| 首次运行后，在游戏对话框输入 /mineopbot config add <name> <apiKey> <baseUrl> <model> 命令，即可在 游戏目录/config/ 下创建配置文件： | After the first run, enter the command /mineopbot config add <name> <apiKey> <baseUrl> <model> in the game chat to create a configuration file in game_directory/config/: |

mineopbot_configs.json

{
  "configs": [
    {
      "name": "openai",
      "apiKey": "sk-your-api-key",
      "baseUrl": "https://api.openai.com/v1",
      "modelName": "gpt-4o"
    },
    {
      "name": "deepseek",
      "apiKey": "sk-your-api-key",
      "baseUrl": "https://api.deepseek.com/v1",
      "modelName": "deepseek-chat"
    }
  ]
}

| 简体中文 | English |
|---------|---------|
| 支持任何 OpenAI 兼容的 API 服务 | Supports any OpenAI-compatible API service |

命令介绍 | Command Reference

| 命令
Command | 描述
Description | 示例
Example |
|----------------|-------------------|----------------|
| /mineopbot | 显示帮助信息
Display help information | /mineopbot |
| /mineopbot chat <message> | 与 AI 对话
Chat with AI | /mineopbot chat 你好 |
| /mineopbot chat <message> UIM | 带 UIM 模式的对话
Chat with UIM mode enabled | /mineopbot chat 我在哪里 UIM |
| /mineopbot status | 查看当前 AI 配置状态
View current AI configuration status | /mineopbot status |
| /mineopbot config list | 列出所有配置
List all configurations | /mineopbot config list |
| /mineopbot config add <name> <apiKey> <baseUrl> <model> | 添加新配置
Add new configuration | /mineopbot config add myai sk-xxx https://api.xxx.com/v1 gpt-4 |
| /mineopbot config remove <name> | 删除配置
Remove configuration | /mineopbot config remove myai |
| /mineopbot config switch <name> | 切换当前配置
Switch current configuration | /mineopbot config switch deepseek |

---

已实现功能 | Implemented Features

AI 对话系统 | AI Chat System

| 状态 | 中文 | English |
|-----|------|---------|
| [x] | OpenAI 兼容 API 集成 | OpenAI-compatible API integration |
| [x] | 流式响应显示 | Streaming response display |
| [x] | 会话历史管理 | Session history management |
| [x] | 自定义系统提示词 | Custom system prompt |

配置管理 | Configuration Management

| 状态 | 中文 | English |
|-----|------|---------|
| [x] | 多配置支持 | Multi-configuration support |
| [x] | 运行时配置切换 | Runtime configuration switching |
| [x] | JSON 持久化存储 | JSON persistent storage |
| [x] | API Key 安全显示 | API Key secure display |

Action 系统 | Action System

| 状态 | 中文 | English |
|-----|------|---------|
| [x] | Action 注册机制 | Action registration mechanism |
| [x] | command_execute - 执行 Minecraft 命令 | command_execute - Execute Minecraft commands |
| [x] | AI 响应 JSON 解析 | AI response JSON parsing |
| [x] | 异步执行与回调 | Async execution and callback |

用户信息模式 (UIM) | User Information Mode (UIM)

| 状态 | 中文 | English |
|-----|------|---------|
| [x] | 玩家位置与维度信息 | Player position and dimension info |
| [x] | 生命值与饥饿值 | Health and hunger values |
| [x] | 装备信息 | Equipment information |
| [x] | 游戏模式与经验 | Game mode and experience |
| [x] | 移动状态 | Movement status |

---

TODO | 待办事项

| 中文 | English |
|------|---------|
| Block Action - 添加方块操作相关 Action | Block Action - Add block manipulation actions |
| 持久化对话记录 - 保存玩家的聊天历史 | Persistent Chat History - Save player chat history |
| 权限分级 - 不同权限等级的玩家可使用的功能不同 | Permission Levels - Different features available based on player permission levels |
| 知识库 - 集成 RAG 知识库，增强 AI 对 Minecraft 的理解 | Knowledge Base - Integrate RAG knowledge base to enhance AI's understanding of Minecraft |

---

开发环境 | Development Environment

环境要求 | Requirements

| 中文 | English |
|------|---------|
| JDK 21+ | JDK 21+ |
| Gradle 9.1.0+ | Gradle 9.1.0+ |

构建项目 | Building the Project

| 平台 | Platform | 命令
Command |
|------|----------|----------------|
| Windows | Windows | .\gradlew build |
| Linux/macOS | Linux/macOS | ./gradlew build |

运行测试环境 | Running Test Environment

| 目标 | Target | 命令
Command |
|------|--------|----------------|
| 服务端 | Server | .\gradlew runServer |
| 客户端 | Client | .\gradlew runClient |

---

技术栈 | Tech Stack

| 技术
Technology | 版本
Version | 用途
Usage |
|-------------------|----------------|--------------|
| Minecraft | 1.21.4 | 目标游戏版本
Target game version |
| Fabric Loader | 0.18.4 | 模组加载器
Mod loader |
| Fabric API | 0.119.4+1.21.4 | Fabric API 模块
Fabric API modules |
| LangChain4j | 1.11.0 | AI API 集成
AI API integration |
| Java | 21 | 编程语言
Programming language |

---

项目结构 | Project Structure

| 路径
Path | 说明
Description |
|-------------|-------------------|
| src/main/java/org/mineopbot/ | 源代码目录
Source code directory |
| MineOpBot.java | 主入口
Main entry point |
| MineOpBotClient.java | 客户端入口
Client entry point |
| ai/ | AI 模块
AI module |
| command/ | 命令模块
Command module |
| mixin/ | Mixin 模块
Mixin module |
| src/main/resources/ | 资源目录
Resources directory |
| fabric.mod.json | Fabric 模组元数据
Fabric mod metadata |
| mineopbot.mixins.json | Mixin 配置
Mixin configuration |
| assets/mineopbot/ | 模组资源
Mod assets |
| config/ | 配置示例
Configuration examples |
| prompt/ | 系统提示词
System prompts |
| build.gradle | 构建配置
Build configuration |
| gradle.properties | Gradle 属性
Gradle properties |
| LICENSE | 许可证
License |

---

License | 许可证

| 简体中文 | English |
|---------|---------|
| 本项目采用 CC0 1.0 Universal 许可证。 | This project is licensed under the CC0 1.0 Universal License. |

---

Contributing | 贡献指南

| 简体中文 | English |
|---------|---------|
| 欢迎贡献！请随时提交 Pull Request。 | Contributions are welcome! Please feel free to submit a Pull Request. |
| 1. Fork 本仓库
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开 Pull Request | 1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request |

---