Minecraft-CaYa-Bot-Panel

<p align="center"> <img src="docs/logo/icon.png" alt="Minecraft CaYa Bot 面板 Logo" width="220"> </p> <h1 align="center">Minecraft CaYa Bot 面板</h1> **基于 Mineflayer 的 Minecraft Java 版多机器人控制与自动化面板。** [](https://nodejs.org/) [](https://www.typescriptlang.org/) [](https://react.dev/) [](https://github.com/PrismarineJS/mineflayer) [](https://www.minecraft.net/) [](#项目状态) --- ## 简易安装 ### 要求 - **Node.js 18 或更新版本** — 推荐使用 Node.js 22 LTS。 - 您拥有或被允许在 **Minecraft Java 版** 服务器上使用机器人。 - 当前机器人登录模式为**离线认证**。暂未实现高级/微软认证。 ### 1. 下载并安装 ```bash git clone https://github.com/CaYatur/Minecraft-CaYa-Bot-Panel.git cd Minecraft-CaYa-Bot-Panel npm install ``` ### 2. 启动面板 ```bash npm run dev ``` 打开： - **网页面板：** `http://localhost:3000` - **API 和 Socket.IO：** `http://localhost:3001` ### 3. 连接您的第一个机器人 1. 打开 **服务器** 并创建服务器配置文件。 2. 返回 **面板** 并选择 **添加机器人**。 3. 选择服务器、机器人用户名和 Minecraft 版本。 4. 启动机器人并打开其详情页。 > 服务器默认监听 `127.0.0.1`。这是故意的：面板具有强大的机器人控制端点，不应未经身份验证层和反向代理而公开暴露。 ### 生产构建 ```bash npm run typecheck npm run build npm run start -w server ``` 生产构建后，Node.js 服务器将从以下地址提供编译后的网页界面： ```text http://localhost:3001 ``` 可选的服务器环境变量： ```text CAYA_HOST=127.0.0.1 CAYA_PORT=3001 ``` --- ## 截图 > 直接从当前应用程序界面（**英文**）使用种子本地演示数据捕获。截图不包含真实的服务器凭证或私人玩家数据。 <p align="center"> <img src="docs/screenshots/hero.png" alt="CaYa Bot 面板仪表盘和高级自动化概述" width="100%" /> </p> ### 多机器人仪表盘和实时系统日志 在一个屏幕上监控机器人状态、健康状况、饥饿度、位置、延迟、活跃工作和应用程序事件。 <p align="center"> <img src="docs/screenshots/dashboard.png" alt="CaYa Bot 面板多机器人仪表盘" width="100%" /> </p> ### 高级自动化规则配置 配置触发器权限、冷却时间、并发策略、运行时限制、初始变量和可重用事件上下文。 <p align="center"> <img src="docs/screenshots/automation-overview.png" alt="CaYa Bot 面板高级自动化规则编辑器" width="100%" /> </p> ### 嵌套 IF/ELSE 和任务结果流程 构建嵌套的 `AND`/`OR` 条件组，等待队列工作，保存结果，重试失败的操作，并根据任务状态分支。 <p align="center"> <img src="docs/screenshots/automation-flow.png" alt="CaYa Bot 面板嵌套自动化流程" width="100%" /> </p> ### 丢弃特定物品自动化 丢弃精确数量，每个匹配堆栈，或仅丢弃保留的库存阈值以上的数量。受保护的物品可以保留，丢弃的计数可以被后续节点使用。 <p align="center"> <img src="docs/screenshots/automation-drop-items.png" alt="CaYa Bot 面板丢弃特定物品自动化" width="100%" /> </p> ### 示意图构造 构建工作空间包括变换、原点选择、实时进度、材料赤字、部分构建行为、集合控制和脚手架清理。 <p align="center"> <img src="docs/screenshots/build-system.png" alt="CaYa Bot 面板示意图构造工作空间" width="100%" /> </p> --- ## CaYa Bot 面板是什么？ CaYa Bot 面板是一个用于创建和操作多个 Minecraft Java 机器人的本地 Web 应用程序，集成了实时机器人监控、库存管理、移动、战斗、生存行为、资源收集、递归合成、示意图构造和可编程自动化引擎。 该项目围绕三个原则设计： 1. **可见状态：** 聊天记录、日志、库存、任务、健康状况、位置、战斗、构建进度和错误实时显示在面板中。 2. **任务导向行为：** 长期运行的操作被放入优先级感知任务队列中，而不是作为不受控制的后台循环执行。 3. **权限和现实性：** 聊天控制的自动化可以限制为授权玩家，移动/战斗行为旨在保持物理上可实现，以模拟正常玩家的操作。 --- ## 主要功能 | 领域 | 功能 | |---|---| | **多机器人管理** | 多个机器人配置文件、多个服务器配置文件、启动/停止所有、自动启动、重新连接处理、独立运行时状态 | | **实时仪表盘** | 连接状态、健康状况、饥饿度、经验值、延迟、维度、坐标、当前任务、队列、系统日志和综合聊天 | | **聊天** | 实时 Minecraft 聊天、面板到服务器消息、解析的玩家/服务器行、速率限制和授权命令发送者 | | **库存** | 实时装备、主库存和快捷栏、装备/使用动作、丢弃特定自动化、保护物品策略和最佳装备支持 | | **移动** | 前往坐标、跟随玩家、航点、冲刺控制、人类化转向、边缘安全、桥梁、跑酷和梯子/藤蔓处理 | | **水移动** | 表面辅助、电流处理、上升支持和更稳定的水到陆地过渡 | | **战斗** | 攻击、自我防御、逃跑、保护玩家、目标跟踪、敌对生物清理、可配置的攻击范围/反应/CPS 行为 | | **生存** | 自动进食、食物获取、水安全、危险逃避、桶处理和可配置的摔落保护 | | **智能收集** | 单独的表面和地下策略、木材收集、矿物挖掘、任意方块收集和掉落物品拾取 | | **递归合成** | 配方依赖规划、原材料获取、合成台使用、熔炉链和存储提取 | | **存储** | 箱子、陷阱箱、桶、放置的潜影盒和便携式潜影盒的临时使用/恢复 | | **示意图构建** | `.schem`、`.schematic`、`.litematic` 和 `.caya.json`、旋转、镜像、材料规划、部分构建和脚手架清理 | | **AI 代理（MCP + Ollama）** | 使用 LLM 驱动机器人：本地 Ollama 模型在游戏中扮演（聊天回复、任务、创造性构建）或任何 MCP 客户端（Claude Code、Cursor、VS Code…）将机器人用作工具 — 50+ 工具、信任系统、持久内存、自动驾驶 | | **高级自动化** | 嵌套 IF/ELSE、AND/OR/NOT 组、变量、任务结果捕获、循环、等待、重试、超时和错误分支 | | **本地化** | 英语、土耳其语和自动区域检测 | | **持久性** | 服务器配置文件、机器人配置文件、规则、航点、示意图索引和日志存储为 JSON/文件 | --- ## MCP / AI 代理系统 **MCP / AI** 选项卡通过两种独立的方式将机器人连接到语言模型。两种路径共享相同的工具注册表（50+ 工具），每个工具都通过正常的任务队列和现实层执行 — 模型只能执行玩家通过面板可以执行的操作。 ```text ┌─────────────────────┐ 工具 ┌──────────────────┐ │ Ollama（本地 LLM） │ ───────────────► │ │ │ 游戏内代理 │ │ 代理工具 │ 任务队列 / └─────────────────────┘ │ 注册表（50+） │ ───► 现实层 ───► Minecraft ┌─────────────────────┐ /mcp 端点 │ │ │ Claude Code、Cursor │ ───────────────► │ │ │ VS Code、任何客户端 │ （JSON-RPC/HTTP） └──────────────────┘ └─────────────────────┘ ``` 启用 **MCP / AI** 中的主开关，然后使用任一或两种模式。 ### 模式 1 — 使用 Ollama 的游戏内 AI 本地 [Ollama](https://ollama.com) 模型在游戏中驱动机器人：它回答聊天、接受任务、收集、合成、战斗（如果允许）和设计/构建结构。 1. 安装 Ollama 并拉取 **支持工具** 的模型： ```bash ollama pull qwen2.5 # 或：llama3.1, qwen3, mistral-nemo, gpt-oss ``` 2. 在 **MCP / AI → Ollama** 中，选择模型（下拉列表显示已安装的模型）并启用代理。 3. 在 **机器人代理** 下，至少为一个机器人启用 **代理**。 4. 通过 **代理聊天** 控制台或在游戏聊天中通过机器人名称地址与机器人聊天（`CaYa selam, 10 demir kaz`）。 游戏内行为完全可配置：仅在被寻址时回复、耳语处理、每玩家冷却时间、最大回复长度、角色文本和回复语言。**关闭游戏内回复** 会将对话限制在面板的代理聊天中。 > 小模型（≤8B）可能会滥用工具或产生幻觉。对于严肃的使用，建议使用更强大的工具调用模型，如 `qwen3.5:35b` 或 `gpt-oss:20b`。 ### 模式 2 — 外部 MCP 客户端（Claude Code、Cursor、VS Code…） 面板在 `http://127.0.0.1:3001/mcp` 处公开了一个 **模型上下文协议** 服务器（可流式 HTTP，JSON-RPC 2.0）。任何支持 MCP 的工具都可以控制机器人。 **Claude Code（CLI）：** ```bash claude mcp add --transport http caya-bot http://127.0.0.1:3001/mcp ``` **Cursor** — `.cursor/mcp.json`（项目）或 `~/.cursor/mcp.json`（全局）： ```json { "mcpServers": { "caya-bot": { "url": "http://127.0.0.1:3001/mcp" } } } ``` **VS Code（Copilot 代理模式）** — `.vscode/mcp.json`: ```json { "servers": { "caya-bot": { "type": "http", "url": "http://127.0.0.1:3001/mcp" } } } ``` **Windsurf** — `~/.codeium/windsurf/mcp_config.json`: ```json { "mcpServers": { "caya-bot": { "serverUrl": "http://127.0.0.1:3001/mcp" } } } ``` **Gemini CLI** — `~/.gemini/settings.json`: ```json { "mcpServers": { "caya-bot": { "httpUrl": "http://127.0.0.1:3001/mcp" } } } ``` **Claude Desktop 和其他仅支持 stdio 的客户端** — 使用 [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) 在客户端的 MCP 配置中桥接： ```json { "mcpServers": { "caya-bot": { "command": "npx", "args": ["-y", "mcp-remote", "http://127.0.0.1:3001/mcp"] } } } ``` > 配置格式会演变 — 如果代码片段与您的客户端版本不匹配，您需要的唯一事实是：**传输 = 可流式 HTTP**，**网址 = `http://127.0.0.1:3001/mcp`**。当面板中的 **需要 Bearer Token** 启用时，还请发送 `Authorization: Bearer <token>`（Claude Code：`--header "Authorization: Bearer <token>"`；JSON 配置通常接受 `headers` 对象）。 大多数工具接受可选的 `bot` 参数；当恰好有一个机器人启用了代理时，它将被自动选中。典型的会话：`list_bots` → `get_status` → `mine_ore { ore: "iron", count: 10 }` → `get_tasks`. ### 工具类别 每个类别都可以在 **工具权限** 中切换；信息/感知工具始终开启。 | 类别 | 工具 | |---|---| | 信息/感知（始终开启） | `list_bots`、`get_status`、`get_inventory`、`look_around`、`find_blocks`、`get_recent_chat`、`get_tasks`、`get_build_status`、`list_waypoints`、`list_schematics`、`list_trusted_players`、`stop_all` | | 聊天 | `send_chat`、`send_whisper` | | 移动 | `goto`、`goto_player`、`follow_player`、`goto_waypoint`、`interact_block` | | 收集 | `collect_wood`、`mine_ore`、`collect_blocks`、`collect_drops`、`hunt_animals` | | 合成与生存 | `craft_item`、`preview_craft_plan`、`cook_food`、`eat_now`、`sleep_in_bed`、`wake_up` | | 库存/存储 | `deposit_items`、`withdraw_items`、`give_item_to_player`、`drop_items`、`equip_item` | | 构建（创造性） | `plan_structure`、`build_structure`、`build_schematic`、`stop_build` | | 防御 | `set_self_defense`、`protect_player`、`flee`、`stop_combat` | | 攻击 *(默认关闭)* | `attack_player`、`clear_hostile_mobs` | | 信任 | `trust_player`、`untrust_player` | | 内存 | `remember`、`recall_memories`、`forget_memory` | | 航点 | `save_waypoint_here` | | 实用模式 *(默认关闭)* | `server_command`、`fly_to`，以及 `mine_ore { utility: true }` | ### 无示意图的创造性构建 模型通过组合参数化形状来设计结构 — `box`、`hollow_box`、`floor`、`wall`、`pillar`、`line`、`cylinder`、`ring`、`sphere`、`dome`、`pyramid`、`cone`、`stairs`、`roof_gable` 和原始 `blocks`。放置 `air` 会雕刻早期的单元格，从而形成门、窗户和室内空间。`plan_structure` 会预先演练设计（尺寸 + 材料列表 vs. 库存），`build_structure` 将其交给真正的构建引擎（脚手架、材料收集、进度、修复），而 `get_build_status` 会将阶段进度流式传输回模型。设计以 `AI · <name>` 存储在示意图库中，现有库示意图可以使用 `build_schematic` 构建。 ### 信任系统 当信任系统开启时，只有信任列表中的玩家才能通过游戏聊天给予代理命令。未信任的玩家要么被忽略，要么仅收到聊天回复（无工具）—— 可配置。模型本身可以通过 `trust_player` 管理列表，前提是您明确允许。 ### 自动驾驶 给予机器人一个目标（“收集 64 个橡木原木，然后建造一个小木屋”），并启用 **自动驾驶**：模型会定期决定下一个具体步骤，尽早醒来完成任务/失败或被攻击，并在报告目标完成时停止。 ### 实用模式（仅限允许的服务器） 默认关闭。在您**自己的** 服务器（或明确允许自动化）上，您可以解锁模型的非现实路径：服务器斜杠命令（`/tp`、`/give`、`/gamemode`... 需要 OP）、创造性飞行（`fly_to`）和快速实用挖掘。战斗现实性（先看后击、距离、人类时机）**永远**不受此模式影响。 ### 内存 `remember` / `recall_memories` 为每个机器人提供一个持久的长期内存（`data/agent-memory/`），该内存在重启后存活——基地位置、所有者、承诺。 --- ## 高级自动化引擎 自动化系统可以用作简单的触发条件-动作编辑器或嵌套的工作流引擎。 ### 触发器 规则可以对以下事件做出反应： - 聊天文本或斜杠样式命令 - 机器人被攻击 - 玩家进入或离开范围 - 跟随目标超出范围 - 玩家加入或离开事件 - 健康或饥饿阈值 - 物品数量阈值 - 获得物品 - 库存满 - 定时间隔 - 机器人生成和死亡 - 任务完成或失败 ### 条件 规则可以检查： - 联机/离线状态 - 任务队列是否空闲或繁忙 - 活动任务类型和任务标签 - 战斗模式和活动跟随目标 - 健康和饥饿 - 物品存在和物品数量 - 附近或远处的玩家 - 维度 - 白天/黑夜状态 - 任意值和之前的操作结果 高级流程支持嵌套条件组： ```text 全部 ├─ 机器人空闲 ├─ 健康 >= 12 └─ 任意 ├─ 铁锭数量 < 32 └─ {forceRun} 为真 ``` 可用的群组运算符有： - `全部` — 所有子项必须为真 - `任意` — 至少一个子项必须为真 - `否定` — 反转嵌套条件 ### 流程节点 可视化高级编辑器支持： - **动作** — 运行机器人动作 - **IF / ELSE** — 创建嵌套条件分支 - **设置变量** — 在工作流上下文中存储值 - **等待** — 等待持续时间或直到条件为真 - **重复** — 固定次数或条件循环 - **停止流程** — 完成或故意失败工作流 每个动作节点还可以定义： - 结果变量名 - 是否等待创建的任务完成 - 超时 - 重试次数 - 重试之间的延迟 - 继续出错行为 - 节点特定的错误分支 ### 任务结果分支 一个动作可以将其结果存储在自定义名称下： ```text 保存为：ironResult 等待任务：是 ``` 后续节点可以读取： ```text {ironResult.status} {ironResult.taskId} {ironResult.taskType} {ironResult.label} {ironResult.error} {ironResult.progressDone} {ironResult.progressTotal} ``` 典型的状态包括： ```text 完成 · 排队 · 完成 · 失败 · 取消 · 超时 ``` ### 示例工作流 ```text 当授权玩家发送：/iron 10 如果机器人空闲 动作 智能收集铁锭 数量：{arg0} 数量模式：添加 等待任务：是 保存结果为：ironResult 如果 {ironResult.status} 等于 done 发送聊天：收集 {arg0} 个额外的铁。 否则 面板通知：铁任务失败：{ironResult.error} 如果机器人不空闲 发送聊天：我当前正忙于 {task}：{label}。 ``` ### 上下文变量 可用于规则的常用变量包括： ```text {player} 聊天发送者或相关玩家 {text} 原始聊天消息 {command} 解析后的命令名称 {arg}、{arg0}... 命令参数 {task}、{taskType} 活动任务类型 {label} 活动任务标签 {taskState} 运行中、空闲、无... {busy}、{idle} 数值状态标志 {queueLength} 队列任务数 {queueTypes} 以逗号分隔的任务类型 {health}、{food} 当前生命值 {position} x, y, z {dimension} 当前维度 {combatMode} 当前战斗模式 {activeTarget} 战斗目标 {followPlayer} 跟随的玩家 {branch} then 或 else {error} 当前错误消息 {failedAction} 失败的操作 {last.status} 上一个操作结果 {loopIndex} 零基循环索引 {loopNumber} 一基循环索引 {attempt} 重试尝试次数 {runId} 高级流程运行标识符 ``` 规则受到冷却和每分钟最大触发次数设置的保护。高级流程还支持最大运行时间、最大步骤数和并发策略。 --- ## 智能资源收集 收集是策略感知的。机器人不会将每个物品都视为矿石，并且不会对树和地下资源使用相同的路径策略。 ### 地表资源 对于原木和类似的地表资源，收集器优先： - 附近掉落的物品 - 可见的匹配树或方块 - 地表友好的路径 - 树上最低可达的原木 - 来自同一棵树的相连原木 - 无法触及的目标的临时黑名单 在正常收集木材时，禁用地形隧道挖掘，防止机器人挖穿山脉以到达树。 ### 地下资源 矿石收集使用单独的策略，允许受控挖掘和地下路径查找。不会无限追逐无法触及或无效的目标。 ### 数量模式 收集和挖掘动作公开两种不同的数量语义： | 模式 | 示例（背包已有 10 个物品） | |---|---| | **添加 `+N`** | 请求 10 → 最终目标为 20 | | **目标总数 `N`** | 请求 10 → 任务已完成 | 此区别对于自动化命令与建造/合成依赖规划非常重要。 ### 掉落物品 机器人可以收集由挖掘、砍树、合成、战斗或手动掉落产生的物品实体。收集通过库存变化验证，而不是假设在实体附近行走成功。 --- ## 合成与依赖规划 智能合成层递归解析合成配方及其源材料。 示例： ```text 云杉木板 └─ 云杉原木 黑橡木栅栏 ├─ 黑橡木板 │ └─ 黑橡木原木 └─ 木棍 └─ 木板 铁锭 ├─ 原铁 / 铁矿石 └─ 熔炉燃料 ``` 规划器可以： - 使用背包中已有的物品 - 拾取附近掉落的物品 - 从附近的存储中提取 - 解析和合成中间材料 - 收集缺少的原材料 - 在需要时使用基于熔炉的生产 - 在材料可用后继续更大的建造或任务 --- ## 存储与潜影盒支持 存储层可以从以下位置搜索和提取匹配的材料： - 箱子 - 被陷阱的箱子 - 桶 - 放置在世界中的潜影盒 - 携带在机器人背包中的潜影盒 世界存储被打开但不会被破坏。可以暂时将便携式潜影盒放置在安全位置，打开，使用，然后破坏并再次收集。如果无法验证恢复，则操作会明显失败，而不是默默丢失潜影盒。 --- ## 示意图建造 支持的格式： ```text WorldEdit：.schem / .schematic Litematica：.litematic CaYa JSON：.caya.json ``` 建造系统提供： - 示意图库和上传接口 - 尺寸和方块数量预览 - 旋转：`0°`、`90°`、`180°`、`270°` - 镜像 X 和镜像 Z - 机器人位置或自定义原点 - 优先放置附近或逐层放置 - 实时方块动画和最近方块历史 - 实时材料需求 - 自动收集缺少的材料 - 在没有所有材料的情况下部分建造 - 合成和存储集成 - 脚手架块配置 - 脚手架清理 - 已放置、跳过和失败的计数器 - 取消和任务中断恢复 可以重试暂时的放置失败。材料使用和剩余材料表格在建造过程中更新，而不是仅在开始时计算一次。 --- ## 移动系统 移动层围绕 `mineflayer-pathfinder` 构建，具有额外的项目级安全和稳定性逻辑。 功能包括： - 移至坐标 - 跟随玩家，配置距离 - 保存的航点 - 受控冲刺行为 - 平滑/人性化转向 - 卡住检测和路线刷新 - 边缘和掉落安全 - 可选的间隙桥接 - 在桥接前尝试跑酷 - 配置的 2-4 方块间隙处理 - 爬梯子、藤蔓和脚手架 - 水流和表面辅助 - 按任务类型控制挖掘和脚手架策略 在路径查找、战斗、建造、生存和手动控制之间协调移动所有权，以减少冲突的视角或按键状态更新。 --- ## 战斗与伴侣行为 战斗可按机器人配置。 可用的行为包括： - 直接攻击玩家 - 清除敌对生物 - 对生物、玩家、两者或两者都不进行自我防御 - 在配置的生命值阈值下逃跑 - 保护一个或多个玩家 - 跟随/攻击/保护同伴开关 - 目标距离、反应延迟、转身速度和 CPS 限制 - 武器选择 - 可选的附近威胁清除行为 - 死亡位置和战利品恢复支持 - 无法触及目标的检测和临时目标抑制 项目故意避免传送、穿墙攻击或瞬时瞄准。 --- ## 生存系统 生存行为可为每个机器人单独配置： - 在饥饿阈值以下自动进食 - 食物黑名单 - 食物获取、狩猎和烹饪工作流程 - 水面和陆地搜索守卫 - 火、熔岩和岩浆逃脱逻辑 - 危险逃脱时可选使用水桶 - 空桶收集水/熔岩 - 坠落风险估计 - 可用物品和表面时的 MLG 式着陆尝试 - 已放置的水、船或方块的可选恢复 坠落保护是尽力而为的，取决于延迟、可用库存、服务器刻度率、防作弊行为和机器人下的几何形状。 --- ## 库存与聊天 ### 库存 面板显示： - 盔甲槽 - 副手 - 主库存 - 快速栏和选定槽 - 堆叠计数 - 耐久度 - 附魔 可用操作包括选择、装备和使用物品，以及可配置的保留/禁止物品策略。 #### 丢弃特定物品自动化 自动化规则可以删除库存物品，而无需依赖通用全堆栈丢弃命令。操作支持： - **丢弃 `N` 个物品** — 最多丢弃请求的确切数量 - **丢弃所有匹配项** — 丢弃每个匹配的库存堆栈 - **保留 `N`，丢弃多余** — 保留最低库存并仅丢弃多余部分 - **确切名称** 或 **名称包含** 匹配 - 对机器人 `keepItems` 列表中的物品的可选保护 - 当不存在匹配物品时的可选失败 - 可选的全额强制执行 - 通过 `{dropResult.status}` 和 `{dropResult.progressDone}` 等字段捕获任务结果 装备和副手槽仍然受保护。由于丢弃是不可逆的，因此不会默默地重新排队中断的丢弃任务。 ### 聊天 聊天界面将 Minecraft 聊天与内部应用程序日志分开。系统错误和任务诊断保留在面板中，除非用户创建的自动化明确发送 Minecraft 消息。 聊天触发的规则可以限制为每个机器人的 **授权玩家列表**。全局速率限制器减少了垃圾邮件和被踢的风险。 --- ## 完全取消和任务优先级 任务系统遵循类似于以下的优先级模型： ```text 生存紧急 > 自我防御 > 直接用户命令 > 自动化工作 > 空闲行为 ``` 完全取消操作停止了可见队列之外的内容。它还使活动自动化运行无效，清除移动目标，释放控制状态，取消挖掘/建造助手，并防止相同的自动化在短抑制窗口期间立即重新创建任务。 --- ## 架构 ```mermaid flowchart LR 浏览器[React Web 面板] <-->|REST + Socket.IO| API[Express / Socket.IO 服务器] API --> 管理员[机器人管理器] API --> 规则[自动化规则引擎] 管理员 --> B1[机器人实例 1] 管理员 --> B2[机器人实例 2] 管理员 --> BN[机器人实例 N] 规则 --> B1 规则 --> B2 规则 --> BN B1 --> 队列1[优先级任务队列] B1 --> 模块1[移动 · 战斗 · 生存 · 收集 · 合成 · 建造] B2 --> 队列2[优先级任务队列] B2 --> 模块2[移动 · 战斗 · 生存 · 收集 · 合成 · 建造] B1 <-->|Minecraft 协议| 服务器[Minecraft Java 服务器] B2 <-->|Minecraft 协议| 服务器 BN <-->|Minecraft 协议| 服务器 API <--> 数据[(data/*.json + 示意图 + 日志)] ``` ### 技术栈 | 层 | 技术 | |---|---| | 机器人运行时 | Mineflayer | | 路径查找 | mineflayer-pathfinder | | 工具选择 | mineflayer-tool | | 盔甲处理 | mineflayer-armor-manager | | 示意图解析 | prismarine-schematic, prismarine-nbt | | 后端 | Node.js, Express, Socket.IO, TypeScript | | 前端 | React, React Router, Zustand, Vite, Tailwind CSS | | 持久化 | 本地 JSON 和文件存储 | --- ## 项目结构 ```text Minecraft-CaYa-Bot-Panel/ ├─ data/ 本地持久状态 │ ├─ bots.json │ ├─ servers.json │ ├─ rules.json │ ├─ waypoints.json │ ├─ schematics/ │ └─ logs/ ├─ scripts/ 烟雾和行为测试脚本 ├─ server/ │ └─ src/ │ ├─ api/ REST 和 Socket.IO 适配器 │ ├─ constants/ 共享事件名称 │ ├─ core/ 机器人管理器、机器人实例、任务队列 │ ├─ modules/ │ │ ├─ agent/ MCP 端点、Ollama 代理、工具注册表、内存 │ │ ├─ automation/ 规则、蓝图和高级流程节点 │ │ ├─ build/ 示意图解析和构造 │ │ ├─ catalog/ Minecraft 物品/方块目录 │ │ ├─ chat/ 聊天解析 │ │ ├─ combat/ 战斗和同伴行为 │ │ ├─ craft/ 合成和递归依赖规划 │ │ ├─ gather/ 表面、矿石和掉落收集 │ │ ├─ inventory/ 库存操作和快照 │ │ ├─ movement/ 路径查找、跑酷和水辅助 │ │ ├─ survival/ 食物、危险、水和坠落防护 │ │ └─ world/ 共享世界内存 │ ├─ persistence/ JSON 存储助手 │ ├─ types.ts │ └─ index.ts ├─ test-server/ 本地 Flying Squid 测试服务器 ├─ web/ │ └─ src/ │ ├─ components/ 机器人面板和高级流程编辑器 │ ├─ i18n/ 英语和土耳其语词典 │ ├─ lib/ API、套接字和共享 UI 类型 │ ├─ pages/ 仪表盘、机器人、规则、示意图、MCP/AI、服务器 │ ├─ stores/ Zustand 状态 │ └─ App.tsx ├─ TODO.md 详细路线图和设计决策 ├─ package.json npm 工作区和根脚本 └─ README.md ``` --- ## 命令 | 命令 | 目的 | |---|---| | `npm run dev` | 以开发模式启动后端和网络面板 | | `npm run dev:server` | 仅启动后端 | | `npm run dev:web` | 仅启动 Vite 前端 | | `npm run typecheck` | 在两个工作区运行严格的 TypeScript 检查 | | `npm run build` | 为生产环境构建后端和前端 | | `npm run start -w server` | 启动编译后的生产服务器 | | `npm run testserver` | 在 `127.0.0.1:25566` 上启动本地离线测试服务器 | | `npm run smoke` | 运行端到端烟雾测试 | | `npm run test:combat` | 运行战斗焦点检查 | | `npm run test:full` | 运行更广泛的行为套件 | | `npm run test:grok` | 运行存储库中包含的扩展烟雾套件 | | `npm run test:all` | 运行完整的脚本测试链 | --- ## 本地测试服务器 包含一个用于开发的轻量级离线测试服务器： ```bash npm run testserver ``` 它监听： ```text 127.0.0.1:25566 ``` 然后，在第二个终端中： ```bash npm run dev npm run smoke ``` 参见 [`test-server/README.md`](test-server/README.md) 以获取有关测试服务器的额外指导。 --- ## 数据和备份 运行时数据存储在 `data/` 下。在进行大规模迁移或实验性更改之前，请备份此目录。 重要文件包括： ```text data/servers.json 服务器配置文件 data/bots.json 机器人配置文件和每机器人设置 data/rules.json 自动化规则和高级流程 data/waypoints.json 保存的坐标 data/schematics/ 上传的示意图文件和索引 data/logs/ 应用程序日志 ``` 请勿将真实的服务器地址、私人玩家列表或敏感的操作数据提交到公共存储库。 --- ## 安全说明 - API 默认绑定到 `127.0.0.1`。 - 目前没有多用户登录或基于角色的网络身份验证。 - 请勿将 `3001` 端口直接暴露给公共互联网。 - 将聊天命令自动化限制为授权的玩家名称。 - 在生产服务器上启用自动化规则之前，请先查看它们。 - 将破坏性库存和建造操作放在明确的条件后面。 - 仅在您拥有的服务器或允许使用机器人的服务器上使用机器人。 --- ## 故障排除 ### `npm install` 或原生软件包错误 删除依赖项并在与项目运行的相同操作系统上重新安装： **Windows PowerShell：** ```powershell Remove-Item -Recurse -Force node_modules Remove-Item -Recurse -Force server/node_modules -ErrorAction SilentlyContinue Remove-Item -Recurse -Force web/node_modules -ErrorAction SilentlyContinue npm install ``` 请勿在 Windows、Linux、macOS、WSL 或 Docker 之间复制 `node_modules`。Esbuild 和 Rollup 等软件包使用特定于平台的二进制文件。 ### 面板打开但 API 已断开连接 检查后端是否在 `3001` 端口运行，另一个应用程序是否正在使用该端口。 ```bash npm run dev:server ``` ### 机器人无法加入 检查： - 主机和端口 - 选定的 Minecraft 版本 - 服务器在线/离线身份验证模式 - 用户名有效性 - 白名单和禁止状态 - ViaVersion/代理行为 - 机器人日志面板中的踢出原因 ### 机器人重复执行失败的任务 使用 **重置工作** 或完全取消操作。然后检查活动自动化规则，特别是可能重新创建工作的间隔、任务失败和错误分支。 ### 取消建造后机器人卡住 **停止** 和 **重置工作** 在几秒钟内释放机器人，即使服务器请求卡在半空中：已取消的运行程序不会解绑任务队列（记录为 *"任务强制分离"*），所有放置/装备/窗口操作都在硬超时下运行，路径查找器在引擎完全退出之前会重复释放。如果您在某些服务器上仍然看到重置后的移动，请捕获日志面板输出并打开问题。 ### AI 代理无响应 - **主开关** 和 **Ollama** 必须同时启用，选择模型，并为机器人启用 **代理**。 - 模型必须支持工具调用（`llama3.1`、`qwen2.5/3`、`mistral-nemo`、`gpt-oss`...）。普通聊天模型会以清晰的错误失败。 - 游戏内回复还需要 *回复游戏消息* 和（默认）通过名称地址机器人；悄悄话始终计入。 - 对于外部 MCP 客户端，`/mcp` 端点切换必须打开 - 禁用的端点返回 HTTP 403。 ### 建造报告缺少材料 检查材料是否： - 已在库存中 - 可在附近的箱子/桶/潜影盒存储中 - 可通过其他材料合成 - 可在当前维度 和搜索半径内 - 需要特殊放置支持的方块状态 ### 坠落保护仍然失败 MLG 行为对延迟、服务器 TPS、库存选择、防作弊规则和复杂的着陆表面敏感。请将其视为紧急援助，而不是保证的免疫。 --- ## 当前限制 - 不支持 Minecraft **基岩版**。 - 当前机器人连接流程中未实现微软/高级身份验证。 - 网络面板尚未包含用户帐户或远程访问安全。 - JSON 持久性旨在用于本地/小型部署；对于大型安装，数据库可能更合适。 - Minecraft 物理和防作弊行为因服务器实现和版本而异。 - 一些复杂的方块和红石导向的示意图状态可能需要额外的放置处理程序。 - 自动化战斗、移动、MLG 和建造仍然是尽力而为的系统，在实际服务器使用期间应监控。 --- ## 项目状态 CaYa Bot 面板处于积极开发中。存储库目前包含多机器人生命周期管理、聊天、库存、任务队列、移动、战斗、生存、收集、合成、存储、示意图构建、本地化和高级自动化流程的工作实现。 详细的开发计划、验收标准、设计原则和未来待办事项在 [`TODO.md`](TODO.md) 中维护。 --- ## 贡献 通过问题和拉取请求欢迎贡献。 在提交更改之前： ```bash npm install npm run typecheck npm run build npm run test:all ``` 推荐的贡献规则： 1. 保持服务器和网页类型同步。 2. 将新的Socket.IO事件名称添加到共享事件定义中。 3. 在英文和土耳其语i18n字典中保留面向用户的字符串。 4. 不要自动将内部日志发送到Minecraft聊天。 5. 在长时间运行的操作中尊重任务取消令牌。 6. 避免查找、移动和路径查找器所有权冲突。 7. 记录新的行为和配置字段。 8. 在可能的情况下，为固定的回归添加目标测试。 --- ## 合理使用 本软件旨在用于个人服务器、开发环境和明确允许自动化的服务器。 服务器所有者可以禁止机器人、自动战斗、资源收集或模式构建。 您有责任遵守您连接的每个服务器的规则。 --- ## 许可证 由CaYaDev（ÇAĞAN TURGUT）开发 [`MIT License`](LICENSE) --- <p align="center"> 为Minecraft Java自动化、实验和本地服务器管理而构建。 </p>