MCBE-AI-Agent

# MCBE GPT Agent v2.0 - 现代化重构

## 概述

这是 [MCBE WebSocket GPT](https://github.com/rice-awa/MCBE_WebSocket_gpt) 项目的完全重构版本，采用现代化异步架构，基于 PydanticAI 框架，支持多种 LLM 提供商，实现了 WebSocket 和 LLM 请求的完全解耦。

## 核心特性

### 🚀 现代化架构
- **异步非阻塞**: WebSocket 通信与 LLM 请求完全分离
- **消息队列**: 使用 `asyncio.Queue` 实现生产者-消费者模式
- **类型安全**: 全面使用 Pydantic 进行数据验证
- **结构化日志**: 基于 structlog 的现代日志系统

### 🤖 AI Agent 能力
- **PydanticAI 框架**: 类型安全的 AI Agent 实现
- **流式响应**: 支持实时流式输出，按完整句子发送
- **Agent Tools**: 内置 Minecraft 命令执行、MCWiki 搜索等工具
- **动态系统提示词**: 根据玩家信息动态调整
- **模型预热**: 启动时自动预热 LLM 模型，提高首次响应速度
- **命令响应回传**: Agent 执行命令后自动回传 commandResponse，工具调用更流畅

### 🔌 多 LLM 支持
- **DeepSeek**: deepseek-reasoner (支持思维链)
- **OpenAI**: GPT-5 等模型
- **Anthropic**: Claude Sonnet 4.5
- **Ollama**: 本地模型支持

### 🎮 用户友好
- **非阻塞通信**: LLM 请求不影响 MC 连接
- **实时切换模型**: 游戏内动态切换 LLM
- **上下文管理**: 灵活的对话历史控制
- **JWT 认证**: 安全的令牌认证机制
- **ScriptEvent 支持**: 支持发送 scriptevent，方便后续对接SAPI

## 项目结构

```
MCBE-AI-Agent/
├── config/                 # 配置管理
│   ├── settings.py        # Pydantic Settings
│   └── logging.py         # 日志配置
├── models/                # 数据模型
│   ├── messages.py        # WebSocket 消息
│   ├── minecraft.py       # MC 协议模型
│   └── agent.py           # Agent 相关模型
├── core/                  # 核心模块
│   ├── queue.py           # 消息队列 (MessageBroker)
│   ├── events.py          # 事件系统
│   └── exceptions.py      # 自定义异常
├── services/              # 服务层
│   ├── agent/            # AI Agent 服务
│   │   ├── core.py       # PydanticAI Agent
│   │   ├── providers.py  # LLM Provider 注册表
│   │   ├── worker.py     # Agent Worker
│   │   ├── tools.py      # Agent 工具定义
│   │   └── mcwiki.py     # MCWiki 搜索工具
│   ├── websocket/        # WebSocket 服务
│   │   ├── server.py     # WS 服务器
│   │   ├── connection.py # 连接管理
│   │   └── minecraft.py  # MC 协议处理
│   └── auth/             # 认证服务
│       └── jwt_handler.py
├── storage/               # 存储层 (TODO)
├── tests/                 # 测试用例
├── docs/                  # 文档
├── data/                  # 数据文件
├── cli.py                 # 应用入口与 CLI 工具
└── pyproject.toml        # 项目配置
```

## 架构设计

### 消息流转

```
┌─────────────┐          ┌──────────────┐         ┌─────────────┐
│  Minecraft  │          │   Message    │         │   Agent     │
│   Client    │◀────────▶│   Broker     │◀───────▶│   Worker    │
│             │          │              │         │             │
│ WebSocket   │          │  Request Q   │         │ PydanticAI  │
│  Handler    │          │ Response Q   │         │   Stream    │
└─────────────┘          └──────────────┘         └─────────────┘
     │                         │                         │
     │  非阻塞提交请求           │                         │
     ├────────────────────────▶│                         │
     │                         │   Worker 消费请求        │ 
     │                         ├────────────────────────▶│
     │                         │                         │
     │                         │  ◀───── 流式响应 ─────── │
     │  ◀────── 响应队列 ────── │                         │
     │  独立发送协程             │                         │
     └────────────────────────▶MC (tellraw)
```

### 核心优势

1. **非阻塞设计**
   - WebSocket Handler 提交请求后立即返回
   - 独立的响应发送协程处理 LLM 输出
   - MC 客户端 ping/pong 不受 LLM 延迟影响

2. **类型安全**
   ```python
   class ChatRequest(BaseMessage):
       type: Literal["chat"] = "chat"
       content: str
       player_name: str | None = None
       use_context: bool = True
   ```

3. **依赖注入**
   ```python
   @dataclass
   class AgentDependencies:
       connection_id: UUID
       player_name: str
       settings: Settings
       http_client: httpx.AsyncClient
       send_to_game: Callable
       run_command: Callable
   ```

## 快速开始

### 1. 准备环境 (推荐)

强烈建议在 Python 虚拟环境中运行项目，以避免依赖冲突：

**Windows:**
```powershell
python -m venv venv
.\venv\Scripts\activate
```

**Linux/macOS:**
```bash
python3 -m venv venv
source venv/bin/activate
```

**Termux (Android):**
```bash
pkg install python -y
python -m venv venv
source venv/bin/activate
```

### 2. 安装依赖

```bash
cd MCBE-AI-Agent
pip install -r requirements.txt
```

### 3. 初始化配置

```bash
python cli.py init
```

这会从 `.env.example` 复制创建 `.env` 文件，编辑并填入 API 密钥：

```env
DEEPSEEK_API_KEY=your-api-key-here
SECRET_KEY=your-secret-key
WEBSOCKET_PASSWORD=your-password
```

### 4. 查看配置信息

```bash
python cli.py info
```

### 5. 测试 LLM 连接

```bash
python cli.py test-provider deepseek
```

### 6. 启动服务器

```bash
python cli.py serve
```

### 开发模式

开发模式适用于本地开发和调试，启用后会跳过身份验证步骤。

**启用方式：**

方式一：命令行参数
```bash
python cli.py serve --dev
```

方式二：环境变量
```bash
# 在 .env 文件中设置
DEV_MODE=true
```

**开发模式特性：**
- 跳过 WebSocket 连接的身份验证
- 连接时自动认证，无需执行 `#登录` 命令
- 启动时显示明确的警告信息
- 日志中标记 `dev_mode=true`

**⚠️ 安全警告：**
- 开发模式**仅用于本地开发和调试**
- **切勿在生产环境中启用**，否则任何人都可以连接服务器
- 启用时会在控制台和日志中显示警告信息

## Termux 部署指南

### 1. 准备工作

在 Termux 中安装必要的包：

```bash
# 更换清华源（可选）
termux-change-repo

# 更新包管理器
pkg update && pkg upgrade -y

# 安装基础工具
pkg install python git wget curl -y

```

### 2. 获取项目

```bash
# 克隆项目(如无法使用git克隆可直接下载压缩包到本地，解压使用)
git clone https://github.com/rice-awa/MCBE-AI-Agent
cd MCBE-AI-Agent

# 创建虚拟环境
python -m venv venv
source venv/bin/activate
```

### 3. 安装依赖

```bash
# 安装项目依赖
pip install -r requirements.txt
```

### 4. Termux 特定配置

由于 Termux 的特殊环境，可能需要调整一些配置：

```bash
# 1. 确保主机设置为 0.0.0.0 而不是 localhost
# 编辑 .env 文件
HOST=0.0.0.0
PORT=8080

# 2. 获取 Termux 的 IP 地址
ifconfig | grep inet

# 3. 确保 Termux 可以监听端口
# 可能需要允许 Termux 的网络访问权限
```

### 5. 启动服务

```bash
# 启动服务器
python cli.py serve

# 或使用守护进程方式（使用 tmux 或 screen）
pkg install tmux -y
tmux new -s mcbe_agent
source venv/bin/activate
python cli.py serve
# 按 Ctrl+B 然后按 D 分离会话
```

### 6. Minecraft 连接

在 MCBE 中使用 Termux 的 IP 地址或本地回环地址：

```
/wsserver localhost:8080
```

## 游戏内使用

### 1. 连接服务器

在 Minecraft 聊天框输入：
```
/wsserver <服务器IP>:8080
```

### 2. 登录认证

```
#登录 123456
```

### 3. 开始聊天

```
AGENT 聊天 你好，请介绍一下自己
```

### 4. 其他命令

```
AGENT 上下文 启用          # 启用对话上下文
AGENT 上下文 关闭          # 关闭对话上下文
AGENT 上下文 状态          # 查看当前状态
切换模型 openai          # 切换到 OpenAI
切换模型 deepseek        # 切换回 DeepSeek
帮助                     # 显示帮助信息
运行命令 time set day    # 执行游戏命令
```

## Termux 常见问题

### 1. 端口无法访问

**解决方案**:
```bash
# 检查 Termux 是否具有必要权限
termux-setup-storage

# 使用 ngrok 绕过防火墙
ngrok http 8080
```

### 2. Python 包安装失败
**解决方案**:
```bash
# 更新 pip 和 setuptools
pip install --upgrade pip setuptools wheel

# 使用清华源加速
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
```

### 3. 内存不足

**解决方案**:
```bash
# 使用轻量级模型
DEFAULT_MODEL=deepseek-chat  # 而不是 deepseek-reasoner

# 减少工作线程
LLM_WORKER_COUNT=1

# 优化虚拟内存
pkg install tur-repo -y
pkg install zram -y
```

### 4. 后台运行

**使用 tmux**:
```bash
# 安装 tmux
pkg install tmux -y

# 创建新会话
tmux new -s mcbe_agent

# 在会话中启动
cd ~/MCBE-AI-Agent
source venv/bin/activate
python cli.py serve

# 分离会话: Ctrl+B, 然后按 D
# 重新连接: tmux attach -t mcbe_agent
```

**使用 nohup**:
```bash
nohup python cli.py serve > mcbe.log 2>&1 &
```

## 配置说明

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `HOST` | 服务器地址 | `0.0.0.0` |
| `PORT` | 服务器端口 | `8080` |
| `SECRET_KEY` | JWT 密钥 | - |
| `WEBSOCKET_PASSWORD` | 登录密码 | `123456` |
| `DEEPSEEK_API_KEY` | DeepSeek API Key | - |
| `OPENAI_API_KEY` | OpenAI API Key | - |
| `ANTHROPIC_API_KEY` | Anthropic API Key | - |
| `DEFAULT_PROVIDER` | 默认 LLM | `deepseek` |
| `LLM_WORKER_COUNT` | Worker 数量 | `2` |
| `STREAM_SENTENCE_MODE` | true=流式按句输出，false=关闭流式并在完成后按句子分批输出 | `true` |
| `LOG_LEVEL` | 日志级别 | `INFO` |
| `ENABLE_WS_RAW_LOG` | WebSocket 原始日志开关 | `true` |
| `ENABLE_LLM_RAW_LOG` | LLM 原始日志开关 | `true` |
| `DEV_MODE` | 开发模式 (跳过身份验证) | `false` |

### Settings 配置

在代码中可以通过 `Settings` 类访问所有配置：

```python
from config import get_settings

settings = get_settings()
print(settings.default_provider)
print(settings.list_available_providers())
```

## 架构亮点

### 1. MessageBroker - 消息队列

```python
class MessageBroker:
    """消息代理 - WS 和 Agent 解耦的核心"""

    async def submit_request(self, connection_id, payload, priority=0):
        """非阻塞提交请求"""

    async def send

[truncated…]