这是 MCBE WebSocket GPT 项目的完全重构版本，采用现代化异步架构，基于 PydanticAI 框架，支持多种 LLM 提供商，实现了 WebSocket 和 LLM 请求的完全解耦。

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

• PydanticAI 框架: 类型安全的 AI Agent 实现
• 流式响应: 支持实时流式输出，按完整句子发送
• Agent Tools: 内置 Minecraft 命令执行、MCWiki 搜索等工具
• 动态系统提示词: 根据玩家信息动态调整
• 模型预热: 启动时自动预热 LLM 模型，提高首次响应速度
• 命令响应回传: Agent 执行命令后自动回传 commandResponse，工具调用更流畅
• MCP 扩展: 支持通过 MCP (Model Context Protocol) 接入外部工具服务器，动态扩展 Agent 能力
• AI 聊天广播控制: 支持将 AI 回复从私聊切换为全服广播，或指定特定玩家广播

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

• 非阻塞通信: LLM 请求不影响 MC 连接
• 实时切换模型: 游戏内动态切换 LLM
• 上下文管理: 灵活的对话历史控制
• 多人会话隔离: 同一 /wsserver 连接下按玩家隔离历史、上下文、模型、模板和变量，避免多人串扰
• 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. 类型安全

   class ChatRequest(BaseMessage):
       type: Literal["chat"] = "chat"
       content: str
       player_name: str | None = None
       use_context: bool = True

3. 多人会话隔离

   • MCBE 单个 /wsserver 连接可承载多个玩家
   • 对话历史、会话锁按 (connection_id, player_name, conversation_id) 分桶；上下文开关、当前模型、模板和自定义变量按 (connection_id, player_name) 分桶
   • ConnectionState.player_name 仅表示最近发言者，处理聊天、UI、上下文、设置和切换模型时必须使用本次事件的 sender
   • 同一玩家请求串行处理，不同玩家可并行处理，避免上下文串扰和 UI 响应推给错人

4. 依赖注入

   @dataclass
   class AgentDependencies:
       connection_id: UUID
       player_name: str
       settings: Settings
       http_client: httpx.AsyncClient
       send_to_game: Callable
       run_command: Callable

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

Windows:

python -m venv venv
.\venv\Scripts\activate

Linux/macOS:

python3 -m venv venv
source venv/bin/activate

Termux (Android):

pkg install python -y
python -m venv venv
source venv/bin/activate

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

python cli.py init

这会创建两个本地配置文件：

• .env：只保存密钥、密码等敏感内容，不提交到 Git。
• config.json：保存普通应用配置，不提交到 Git；模板来自 config.example.json。

先编辑 .env 填入密钥：

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

再按需编辑 config.json。JSON 字符串可以使用 ${VAR} 引用 .env 或进程环境变量，例如：

{
  "providers": {
    "deepseek": {
      "api_key": "${DEEPSEEK_API_KEY}",
      "base_url": "https://api.deepseek.com",
      "model": "deepseek-chat"
    }
  }
}

如果 ${VAR} 指向的变量缺失或为空，服务启动会失败并显示对应 JSON 路径和变量名。

python cli.py info

python cli.py test-provider deepseek

python cli.py serve

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

启用方式：

方式一：命令行参数

python cli.py serve --dev

方式二：配置文件

{
  "dev_mode": true
}

开发模式特性：

• 跳过 WebSocket 连接的身份验证
• 连接时自动认证，无需执行 #登录 命令
• 启动时显示明确的警告信息
• 日志中标记 dev_mode=true

⚠️ 安全警告：

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

Runtime Harness 会在 Agent 工具调用时写入隐私友好的 JSONL 摘要，用于定位重复失败、高风险工具调用和高耗时工具，并通过 CLI 生成反馈建议。

审计配置位于 config.json 的 agent.runtime_harness 下，默认随 config.example.json 启用：

{
  "agent": {
    "runtime_harness": {
      "enabled": true,
      "audit_enabled": true,
      "audit_path": "logs/runtime_harness_tools.jsonl",
      "audit_max_records": 5000
    }
  }
}

• enabled：运行时 Harness 总开关；关闭后提示词、schema 增强和审计都会停止。
• audit_enabled：只控制工具审计写入。
• audit_path：JSONL 审计文件路径。
• audit_max_records：保留最近 N 条记录，超出后自动轮转。

每行是一条工具调用摘要，包含工具名、用途、风险等级、调用状态、耗时、有限会话标识、参数预览和结果摘要。审计不会记录玩家原始消息，也不会记录完整工具返回内容；参数只按工具目录声明的白名单预览，敏感字段会被脱敏。

tail -n 20 logs/runtime_harness_tools.jsonl

输出文本报告：

python cli.py runtime-harness analyze

常用选项：

python cli.py runtime-harness analyze --recent 200
python cli.py runtime-harness analyze --json
python cli.py runtime-harness analyze --no-llm

• --recent N：分析最近 N 条审计记录；默认使用 audit_max_records。
• --json：输出机器可读 JSON，便于脚本或 CI 收集。
• --no-llm：跳过默认 Provider 的 LLM 建议，只输出规则聚合建议。

默认模式会使用当前 providers.default 对聚合统计生成 2-4 条中文改进建议。发送给 LLM 的内容只包含总量、失败率、平均耗时、风险分布、重点问题工具和规则建议；如果默认 Provider 不可用，CLI 会保留规则建议并显示回退原因。

完整 Agent 运行追踪写入独立的 append-only JSONL journal（默认 logs/agent_traces.jsonl），与 Runtime Harness 工具摘要审计分离。

在 config.json 的 agent 下配置：

{
  "agent": {
    "agent_trace_enabled": true,
    "agent_trace_include_content": false,
    "agent_trace_path": "logs/agent_traces.jsonl",
    "agent_trace_max_records": 10000,
    "agent_trace_api_host": "127.0.0.1",
    "agent_trace_api_port": 8787
  }
}

• agent_trace_enabled：是否记录 trace 事件（默认 false）。
• agent_trace_include_content：是否持久化完整正文（默认 false，仅在 trace 开启时生效）；完整内容为 opt-in。
• agent_trace_path：journal 路径。
• agent_trace_api_host / agent_trace_api_port：本地只读 API 默认绑定。

python cli.py trace serve
# open http://127.0.0.1:8787
python cli.py trace list --recent 20
python cli.py trace list --status failed --player alex
python cli.py trace show <trace_id>
python cli.py trace show <trace_id> --json
python cli.py trace health

• API 为本地只读（GET），不修改 journal。
• 完整正文仅在 agent_trace_include_content=true 时写入；默认只有元数据与摘要字段。
• WebSocket 原始报文日志（enable_ws_raw_log）与本 journal 相互独立，不会互相替代。
• 静态审计工作台：web/trace/（无构建步骤，由 trace serve 按仓库根路径托管，不依赖进程 CWD）。
• journal 轮转会重写文件以保留最近 N 条记录（agent_trace_max_records），按设计面向本地/开发体量，不适合超大生产写入。
• 离线验收夹具矩阵见 tests/test_trace_integration.py（no-tool / single-tool / approval / deny / failure / cancel / multiplayer / privacy）。

当前仓库已经接入一条可用的 Python <-> Addon <-> 游戏桥接链路，用于让 Agent 通过 Addon 获取更稳定的游戏内上下文，如玩家背包，实体信息等。打包好的 Addon 可在release获取

python cli.py serve --dev

如需验证配置是否已生效，可先执行：

python cli.py info

Addon 工程位于 MCBE-AI-Agent-addon/，本地调试前至少执行一次依赖安装、测试、构建和本地部署。

cd MCBE-AI-Agent-addon
npm install
npm test
npm run build
npm run local-deploy

说明：

• npm install：安装 @minecraft/server、@minecraft/server-ui 与构建依赖。
• npm test：运行桥接协议、路由与 UI 状态容器相关测试。
• npm run build：构建行为包脚本。
• npm run local-deploy：将本地构建结果部署到 Minecraft 本地开发目录。

1. 启动 Python 服务：python cli.py serve --dev。
2. 在 MCBE-AI-Agent-addon/ 下执行 npm run local-deploy，确保最新脚本已部署。
3. 进入启用了对应开发包的世界，等待 Addon 初始化。
4. 在游戏内确认模拟玩家 MCBEAI_TOOL 已生成。
5. 使用 /wsserver <服务器IP>:8080 连接 Python 服务；开发模式下会自动跳过 #登录。
6. 执行一次正常聊天命令，例如 AGENT 聊天 读取一下我当前附近的实体，观察 Python 日志与游戏内行为。
7. 手持原版命令方块 minecraft:command_block 并使用，确认游戏内聊天面板可以打开。
8. 在面板中发送一条消息，确认本地历史、统计信息和设置保存行为正常；如果 Python 未收到 UI 消息，请按面板提示在聊天框手动发送等价的 AGENT 聊天 <消息>。

当前桥接方向是 Python -> scriptevent -> Addon -> 模拟玩家聊天分片 -> Python。建议按下面的方式确认链路完整：

1. 先确认 MCBEAI_TOOL 存在。
2. 触发一个会调用 Addon 能力的 Agent 请求，例如：

AGENT 聊天 请读取我的玩家状态并告诉我当前位置

1. Python 侧应向游戏发送 scriptevent mcbews:bridge_req <json>。
2. Addon 侧处理后，会驱动 MCBEAI_TOOL 以聊天分片形式回传 MCBEAI|RESP|...。
3. Python 侧会在 WebSocket PlayerMessage 事件流中拦截这些分片并完成重组，最终把工具结果继续交给 Agent。

如果第 3 步已发出但最终超时，通常表示：

• Addon 未正确部署或世界未启用最新行为包。
• MCBEAI_TOOL 未生成或被移除。
• 聊天分片没有成功回到 Python 所连接的 WebSocket 事件流。

• get_player_snapshot：获取目标玩家基础快照，包括位置、维度、朝向和基础状态。
• get_look_block：获取目标玩家视线射线命中的方块（getBlockFromViewDirection），默认当前对话玩家。
• get_inventory_snapshot：获取目标玩家背包槽位与物品快照。
• find_entities：按类型、名称、标签、距离等条件查找实体。
• run_world_command：由 Addon 在世界侧执行命令并返回结果。

当前 UI 实现为第一阶段游戏内聊天面板，不替代现有聊天命令入口。也就是说：

• 现有 AGENT 聊天、AGENT 上下文、切换模型、运行命令 等聊天命令仍然是主入口。
• 面板入口绑定为使用原版命令方块物品 minecraft:command_block，避免抢占聊天监听。
• 面板支持发送消息、本地聊天记录、设置保存和统计信息；发送消息会记录本地历史，并提示等价的 AGENT 聊天 <消息>。
• 当前本地 @minecraft/server-ui 类型只暴露 ActionFormData / ModalFormData，暂不能直接使用官方 DDUI CustomForm / Observable。
• 后续如果类型和运行时支持真正 DDUI，可在 Addon 的表单适配层中替换实现，而不重写业务状态。

• Addon -> Python 的响应回传依赖模拟玩家 MCBEAI_TOOL 发送聊天分片，不是独立的回传通道。
• Python 侧通过 WebSocket PlayerMessage 事件流拦截桥接分片，因此桥接能力依赖聊天事件正常上送。
• run_world_command 在当前本地依赖版本下基于同步 runCommand 实现，不是异步命令管线。
• 第一阶段 UI 不新增 Addon -> Python 专用上行协议，也不伪造真实玩家聊天事件；如果 UI 消息没有进入 Python，请按面板提示手动发送等价聊天命令。
• 响应同步尚未启用，统计中的响应片段数会保持为 0；后续可通过 scriptevent mcbews:text_resp <json> 接入 Python -> Addon UI 同步。

在 Termux 中安装必要的包：

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

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

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

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

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

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

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

// 1. 确保 config.json 中主机设置为 0.0.0.0 而不是 localhost
{
  "server": {
    "host": "0.0.0.0",
    "port": 8080
  }
}

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

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

# 启动服务器
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 分离会话

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

/wsserver localhost:8080

在 Minecraft 聊天框输入：

/wsserver <服务器IP>:8080

#登录 123456

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

AGENT 对话 new 建筑规划     # 新建并切换到一个对话
AGENT 对话 switch default  # 切换到指定对话
AGENT 对话 clear           # 清除当前对话历史
AGENT 对话 list            # 查看当前连接内的对话
AGENT 上下文 启用          # 启用携带当前对话历史
AGENT 上下文 关闭          # 关闭携带历史但不清除对话
AGENT 上下文 状态          # 查看上下文开关与当前对话状态
AGENT 广播 状态           # 查看 AI 聊天广播策略（默认全服开启，见 config minecraft.ai_broadcast_default）
AGENT 广播 全服 关闭      # 关闭 AI 全服广播
AGENT 广播 全服 开启      # 开启 AI 全服广播
AGENT 广播 玩家 <名> 开启 # 指定玩家开启广播
AGENT 广播 关闭           # 关闭全服并清空指定玩家名单
切换模型 openai          # 切换到 OpenAI
切换模型 deepseek        # 切换回 DeepSeek
帮助                     # 显示帮助信息
运行命令 time set day    # 执行游戏命令

MCBE 世界通常只会通过 /wsserver 建立一条 WebSocket 连接，所有玩家的聊天框命令和 Addon UI 消息都会复用这条连接。后端不会再把 connection_id 视为单个玩家会话，而是使用 (connection_id, player_name) 区分真实玩家会话，并在玩家内使用 conversation_id 区分不同对话。

• 玩家 A 和玩家 B 的对话历史互不读取；同一玩家的不同对话也互不读取。
• AGENT 对话 负责新建、切换、清除、保存和恢复对话。
• AGENT 上下文 只负责是否在请求中携带当前对话历史，不再清除或保存对话。
• 切换模型、模板和变量设置只影响发起命令的玩家。
• Agent Worker 对同一玩家保持串行处理，但不同玩家请求可以并发执行。
• UI 响应同步使用当前消息的真实 player_name，避免响应写入其他玩家面板。
• 连接断开或注销时会清理该连接下所有玩家会话。

详细根因分析与修复记录见 claude_md/report/MULTIPLAYER_BUG_REPORT.md 和 claude_md/fix/MULTIPLAYER_SESSION_FIX.md。

解决方案:

# 检查 Termux 是否具有必要权限
termux-setup-storage

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

解决方案:

# 更新 pip 和 setuptools
pip install --upgrade pip setuptools wheel

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

解决方案:

// config.json
{
  "queue": {
    "llm_worker_count": 1
  }
}

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

使用 tmux:

# 安装 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:

nohup python cli.py serve > mcbe.log 2>&1 &

普通应用配置写入 config.json，敏感内容只保留在 .env。常用配置路径如下：

.env 仅用于敏感变量，例如 SECRET_KEY、WEBSOCKET_PASSWORD、DEEPSEEK_API_KEY、OPENAI_API_KEY、ANTHROPIC_API_KEY。

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

from config import get_settings

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

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

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

    async def send_response(self, connection_id, response):
        """发送响应到指定连接"""

关键特性:

• 优先级队列支持紧急请求
• 每连接独立响应队列
• 对话历史和会话锁按 (connection_id, player_name) 隔离
• 注销连接时清理该连接下全部玩家会话
• 支持多 Worker 并发消费

class ProviderRegistry:
    @classmethod
    def get_model(cls, config: LLMProviderConfig) -> Model:
        """统一的 LLM 创建接口"""

支持的提供商:

• DeepSeek (OpenAI-compatible)
• OpenAI
• Anthropic (Claude)
• Ollama (本地模型)

class ConnectionState:
    def get_player_session(self, player_name: str | None) -> PlayerSession:
        """获取指定玩家在当前连接下的独立会话状态"""

class ConnectionManager:
    async def _response_sender(self, state: ConnectionState):
        """独立的响应发送协程 - 不阻塞主循环"""

设计优势:

• 每个连接独立的发送协程
• 每名玩家独立保存上下文开关、当前模型、模板、变量和当前活动对话
• state.player_name 仅作为最近发言者指针，不能作为多人会话身份来源
• 超时机制避免永久阻塞
• 优雅的错误处理

@chat_agent.tool
async def run_minecraft_command(ctx: RunContext, command: str) -> str:
    """Agent 可以执行 MC 命令"""
    await ctx.deps.run_command(command)
    return f"已执行命令: /{command}"

Agent 能力:

• 类型安全的工具定义 (独立 tools.py 模块)
• 动态系统提示词
• 流式响应支持 (按完整句子发送)
• 依赖注入
• MCWiki 搜索工具集成

旧架构问题:

# 阻塞式 - LLM 请求阻塞 WS 消息处理
async for chunk in conversation.call_gpt(prompt):
    await websocket.send(chunk)  # WS 被阻塞

新架构解决方案:

# 非阻塞 - 提交后立即返回
await broker.submit_request(connection_id, chat_req)

# 独立协程处理响应
async def _response_sender():
    while True:
        response = await queue.get()
        await websocket.send(response)

• 多个 Agent Worker 并发处理请求
• 可通过 config.json 的 queue.llm_worker_count 配置 Worker 数量
• 自动负载均衡

# 使用 zerotier 创建虚拟局域网
pkg install zerotier-one -y
zerotier-one -d
zerotier-cli join <network_id>

# 或使用 tailscale
pkg install tailscale -y
tailscale up

# 安装性能监控工具
pkg install htop proot-distro -y

# 使用轻量级系统
proot-distro install ubuntu
proot-distro login ubuntu

# 清理缓存
pkg clean
pip cache purge

# 使用外部存储
termux-setup-storage
ln -s /storage/emulated/0/Download/mcbe_data ./data

创建 termux_start.sh:

#!/data/data/com.termux/files/usr/bin/bash

# 激活虚拟环境
source ~/MCBE-AI-Agent/venv/bin/activate

# 启动服务
cd ~/MCBE-AI-Agent
python cli.py serve

# 设置可执行权限
chmod +x termux_start.sh

1. 在 providers.py 添加创建方法：

@classmethod
def _create_custom_model(cls, config: LLMProviderConfig) -> Model:
    from custom_provider import CustomModel
    return CustomModel(config.model, api_key=config.api_key)

1. 在 get_model 中注册：

elif provider_name == "custom":
    return cls._create_custom_model(config)

在 services/agent/tools.py 中添加：

async def your_tool(ctx: RunContext[AgentDependencies], param: str) -> str:
    """工具描述"""
    # 实现逻辑
    return "结果"

然后在 services/agent/core.py 中注册：

from .tools import your_tool

chat_agent.tool(your_tool)

在 config.json 的 minecraft.commands（及默认命令配置）中添加：

COMMANDS = {
    "自定义命令": "custom_cmd",
}

然后在 server.py 中实现处理器：

async def handle_command(self, state, cmd_type, content):
    if cmd_type == "custom_cmd":
        await self.handle_custom(state, content)

# 检查端口监听
netstat -tulpn | grep 8080

# 检查防火墙
iptables -L

# 测试本地连接
curl http://localhost:8080/health

测试提供商连接：

python cli.py test-provider deepseek

检查日志：

tail -f logs/MCBE-AI-Agent.log

// config.json
{
  "queue": {
    "llm_worker_count": 1
  },
  "providers": {
    "deepseek": {
      "model": "deepseek-chat"
    }
  }
}

# 重新安装依赖
pip uninstall -r requirements.txt -y
pip install --no-cache-dir -r requirements.txt

# 使用预编译包
pip install --prefer-binary -r requirements.txt

当前架构使用 asyncio.Queue，单进程足够。如需分布式：

1. 替换 MessageBroker 为 Redis Streams
2. 实现 Pub/Sub 响应分发
3. 使用共享存储（Redis/PostgreSQL）

在 storage/ 目录实现：

• conversation.py: 对话历史存储
• session.py: 会话管理
• metrics.py: 使用统计

1. 生产环境配置

   • 更改 SECRET_KEY 为强随机值
   • 设置复杂的 WEBSOCKET_PASSWORD
   • 使用 HTTPS（通过反向代理）

2. API 密钥管理

   • 不要提交 .env 到版本控制
   • 使用密钥管理服务（如 AWS Secrets Manager）

3. Termux 特定安全

   • 定期更新 Termux 包
   • 使用强密码保护设备
   • 仅在有需要时开放端口

4. 速率限制

   • 在 MessageBroker 实现请求速率限制
   • 防止单用户滥用

• ✨ AI 聊天广播控制: 新增 AGENT 广播 命令，支持全服广播或指定玩家广播 AI 回复
• 🔧 会话隔离增强: 引入对话失效 epoch 机制，避免对话切换期间的竞态条件
• ⚡ 流控与发送加固: 统一流控中间件支持 sentence mode 语义分句，WebSocket 命令投递和响应发送更加健壮
• 🛡️ MCP 工具热重载: 支持运行时通过命令重载 MCP 工具集，自动跳过不健康的服务器

• 修复多人共享同一 /wsserver 连接时的玩家识别、上下文历史和 UI 响应串扰问题
• 将对话历史、会话锁、上下文开关、模型、模板和变量升级为 (connection_id, player_name) 维度隔离
• Agent Worker 改为同玩家串行、跨玩家并行处理请求
• UI 聊天路径和聊天框命令统一使用当前消息的真实 sender

• ✨ 开发模式: 新增开发模式功能，支持跳过身份验证用于本地开发调试
• 🔧 支持通过 --dev 命令行参数或 config.json 的 dev_mode 启用
• ⚠️ 开发模式下会显示明确的安全警告

• 🔧 日志控制优化: 新增 WebSocket 和 LLM 原始日志开关配置，支持按需启用
• ⚙️ 环境变量支持: 添加 ENABLE_WS_RAW_LOG 和 ENABLE_LLM_RAW_LOG 环境变量

• ✨ WebSocket run_command 响应回传: Agent 执行命令后自动回传 commandResponse，提升工具调用体验
• 🔧 断线时队列处理优化: 断线时自动完成队列中的 run_command futures，避免请求卡死
• ⚡ 流式响应处理优化: 优化增量事件内容缓存和处理逻辑，提升流式输出稳定性
• 🔄 响应处理逻辑重构: 重构流式与非流式响应处理流程，移除手动工具链回退逻辑
• 📝 配置外部化: Minecraft 命令配置和消息模板迁移至配置文件，便于定制
• 🔧 CLI 入口统一: 重构应用入口至 cli.py，统一命令行工具
• 🧪 测试完善: 完善基于 agent.iter() 的流式输出模式测试

• ✨ 新增 MCWiki 搜索工具，支持查询 Minecraft Wiki
• 🔧 Agent 工具定义重构，独立 tools.py 模块
• ⚡ 启动时预热 LLM 模型，提高首次响应速度
• 📝 流式输出优化，按完整句子发送
• 📡 支持通过 ScriptEvent 方式发送聊天消息
• 🔊 优化日志输出与响应记录

• 🎉 初始版本发布
• 🚀 现代化异步架构重构
• 🤖 PydanticAI Agent 框架集成
• 🔌 多 LLM 提供商支持
• 🎮 完整的游戏内命令系统

• 对话历史持久化
• Token 使用统计
• Web 管理界面
• 支持更多 Agent Tools
• 插件系统
• 多语言支持
• Docker 容器化
• Kubernetes 部署示例
• Termux 优化包

• Python 3.11+
• PydanticAI: AI Agent 框架
• Pydantic: 数据验证
• WebSockets: 实时通信
• httpx: 异步 HTTP 客户端
• PyJWT: JWT 认证
• structlog: 结构化日志
• Click: CLI 工具
• Termux: Android 终端环境

MIT

• 原项目: rice-awa/MCBE_WebSocket_gpt
• PydanticAI: pydantic/pydantic-ai
• Termux: termux/termux-app

版本: 2.4.0 最后更新: 2026-06-19 架构: 现代化异步 + PydanticAI 平台支持: Windows, Linux, macOS, Termux (Android)