⛏️ minecraft-companion — Minecraft AI 伴侣（MCP 服务器）

一个跑在 Minecraft 里的 AI 机器人：mineflayer 当身体，大模型当大脑，MCP 当接口。 任何支持 MCP 的客户端（AstrBot / Claude / Cursor / 自写脚本）都能通过 SSE 连上来，指挥机器人做游戏内操作。

✨ 特性

• 🧠 大脑桥（默认接 AstrBot）：机器人不直连 LLM，统一走 AstrBot /api/v1/chat —— 同一个脑子：QQ 和游戏里是同一个 AI，共享人格+记忆，零 API key 配置

• 🎒 创造模式工具：creative-give 协议级发放任意物品，不需要 /give 权限

• 🪃 跟随玩家：follow-player 持续跟随（动态寻路、掉线自愈、可指定玩家）

• 🔒 身体控制权锁：guardian 保命 > 玩家任务 > 自主生活，动作类工具统一走 withBody，多客户端不会抢身体

• ⚔️ 战斗 / 生存 / 采集：自动寻路打怪、生存守护（残血撤退、自动进食）

• 📊 49 个 MCP 工具（13 分类）：感知、移动、建造、采集、合成、熔炼、农业、战斗、仓库、创造、技能、记忆、社交，全协议实现

🤖 AI Agent 部署？（一句话部署）

如果你是 AI agent（LLM），用户丢给你压缩包说"部署好让我玩我的世界"：

📖 看 AGENT_DEPLOY.md —— 专为 AI 写的部署指南（一键命令 + 配置决策表 + 排查清单） 一句话方案：解压 → node setup.js --auto → node dist/main.js → 接入 MCP :3001/mcp

智能配置引导（人和 AI 通用）

node setup.js          # 交互式，Enter 用默认值
node setup.js --auto   # 全自动：装依赖 + 检测 AstrBot + 生成配置

• 自动探测本机 AstrBot(6185) → 大脑走 astrbot 桥模式，无需 API key

• 不在 AstrBot 环境 → 需提供 OpenAI 兼容 API key（或 brain.mode=none 纯工具模式）

• 已有配置自动备份 .bak

🚀 快速开始

1. 环境要求

• Node.js 18+

• 一个 Minecraft Java 版服务器（1.20 ~ 1.21.1，1.21.1 实测）

• 正版 / 离线 / Yggdrasil（LittleSkin 等外置登录） 账号

2. 安装

npm install

3. 配置

# 首次使用：把模板复制成正式配置，然后填自己的服务器和账号
copy config\config.example.json config\config.json

编辑 config/config.json（字段含义见 配置说明）。

4. 启动

npm start          # 或 node dist/main.js

看到以下日志即成功：

✅ 已进入游戏！位置: (x, y, z)
🛡️ 生存守护已启动
🛰 MCP SSE 服务: http://127.0.0.1:3001/mcp

5. 接入 MCP 客户端

SSE 地址：http://127.0.0.1:3001/mcp

• AstrBot：MCP 服务器添加 SSE 类型，填上面的地址（支持多客户端，可带 ?clientId=名字 区分）

• Claude Desktop / 其他：用 SSE transport 指向同一地址

• 自写脚本：参考 tools/test-mcp.js（node tools/test-mcp.js <工具名> "参数=值"）

⚙️ 配置说明

🧰 工具清单（MCP tools，共 49 个）

🔁 MCP 断连自愈与日志（排查指南）

问题：AstrBot ↔ 本 bot 的 MCP 连接是一次性 SSE。bot 重启 / AstrBot 后启动时， 连接会静默失效——AstrBot 后台甚至可能仍显示"已连接"（它只检查运行时对象， 不检查真实 session），但每次工具调用都报 MCP session is not available for MCP function tools.

三层自愈（按推荐顺序，A 必须有，B/C 可选）：

A. 游戏内直报（本仓库内置，无需配置） src/brain.ts 检测到工具调用因 session 不可用而失败时，不再把 LLM 编的假话发给玩家， 而是直报"我跟大脑的连接断了"，并在 logs/app.log 留 WARN。玩家看到后去后台重存一次即可恢复。

B. watchdog 自动重连（推荐，开源可用，无硬编码路径） mcp-watchdog.ps1：轮询 bot 端口(:3001)，检测到 down→up 重启边沿或 AstrBot 后台报 disconnected / 0 工具时，自动调 AstrBot 管理 API PATCH /api/v1/mcp/servers/enabled 触发重连。零 token、纯本地 HTTP。

# 常驻模式
.\mcp-watchdog.ps1 -CmdConfig <你的AstrBot>/data/cmd_config.json
# 单次检查（适合计划任务，每 30s 跑一次）
.\mcp-watchdog.ps1 -CmdConfig <你的AstrBot>/data/cmd_config.json -Once
# 或设环境变量，参数可省
$env:ASTRBOT_CMD_CONFIG = '<你的AstrBot>/data/cmd_config.json'
.\mcp-watchdog.ps1 -Once

watchdog 从 cmd_config.json 的 dashboard.jwt_secret 自签 JWT 调管理 API， 仅需后台管理账号密码在 cmd_config 里有 jwt_secret（默认有），不依赖外置密码。 状态存 logs/mcp-watchdog.state，脚本重启不会误判"重启边沿"。

C. AstrBot 源码补丁（可选增强，治"后台假连接"） patches/astrbot-mcp-autoreconnect.patch：给 AstrBot 的 mcp_client.py 打补丁后， session 丢失时调用前自动重连一次，玩家无感恢复。属可选： AstrBot 升级会覆盖，需重打。

# 备份原文件后应用（补丁内路径相对 AstrBot 安装根目录）
cd <你的AstrBot根目录>
git apply --no-index 或 patch -p1 < minecraft-companion/patches/astrbot-mcp-autoreconnect.patch
# Windows 无 patch 命令时：用文件对比工具手动照补丁改，或重新打

🔍 出问题先查日志（都在本仓库 logs/ 下，自动轮转）：

快速搜关键行：

Select-String -Path logs\app.log -Pattern "ERROR|WARN|断开|重连|session|直报" | Select-Object -Last 30

🛠️ 常见问题

Q：AstrBot 侧 MCP 显示"未连接"或工具数 0？ A：先启动 bot、后启动 AstrBot（或 bot 重启过）时注册不会自动补。去 AstrBot MCP 服务器设置里重新保存/编辑一次该服务器（触发 PATCH）即可重连；或按"先 bot 后 AstrBot"的顺序启动。

Q：建房卡住一直刷 "No available actions"？ A：图纸起点悬空或 chunk 未加载。已自动处理（自动走位加载 chunk + 45s 停滞取消）；手动调用旧版时请让 bot 先走到建造区。

Q：creative-give 发了物品但背包没有？ A：快捷栏槽位（0-8）部分服务器保护，已自动跳过；若全被拒，检查 mc.auth 是否有权限 / 是否创造模式。

Q：连不上 MCP？ A：确认 mcpPort 没被占用，http://127.0.0.1:3001/mcp 浏览器能返回 SSE 响应。

Q：机器人不动 / 动作冲突？ A：身体控制权锁机制下，观察类工具不占用身体，动作类同一时刻只允许一个会话执行（guardian 保命可抢占）。等 2 分钟无动作自动让出。

🔧 开发说明

• src/ 是唯一源码（TypeScript），改功能请改 src/，然后 npm run build 产出 dist/，重启生效

• dist/ 是 tsc 编译产物，不要手改 dist（会被下次 build 覆盖）；早期 v1.0/1.1 时代的"dist 手改"说明已废弃

• npm run build 编译检查 + 产出；tsc --noEmit 仅类型检查

• tools/test-mcp.js：免客户端调用工具，调试神器

• 新增工具：在 src/tools/xxx.ts 里 mcp.registerTool(...)，并在 src/tools/index.ts 注册

• 动作类工具会自动走身体锁（mcp-server.ts 的 ACTION_TOOLS 白名单）；技能侧复合动作在 src/skills/index.ts

📄 免责声明

• 机器人使用你的账号登录，请遵守服务器规则，勿用于作弊/破坏

• 配置文件含账号密码与 API Key，请勿提交到公开仓库

• 项目仅作学习交流，作者不对滥用行为负责

📦 版本记录

📦 版本记录

v1.6.0 (2026-09-05) · P2

• 🎣 真实钓鱼流程（P2-1）：旧版"8s 硬收杆"（activateBlock 假抛竿、不检测咬钩）→ 新 src/tools/fishing.ts 共用核心 fishOnce：找水→就位→抛竿→等咬钩（mineflayer 粒子检测自动收杆）→背包快照 diff 判定鱼获。MCP fish 工具与 lifestyle fish 技能同一实现（同 buildShelterCore 思路，杜绝工具/技能逻辑分裂）；稀有鱼获（bow/enchanted_book/name_tag/nautilus_shell/saddle）触发 fished_rare 情绪 + 短期记忆

• ⚡ 事件双轨制落地（P2-2）：危险类改状态型 + 事件双轨 —— events.ts scanDanger 改边沿触发（威胁首次进入警戒 / 等级升级才发事件并触发情绪；离开警戒范围复位，恢复后新威胁可再提醒），"周围持续有谁"改由每次上下文构建的状态轨注入，事件层不再 60s 重复刷屏（同样根治"不满足前置条件不硬上"）

• 🧩 聊天上下文组装器（P2-3）：新增 src/chat-context.ts ChatContextBuilder，统一组装 world / self / danger状态轨 / player / recent_events / chat_history / shared_memories / player_observations / avoid_topics / 情绪语气 喂给大脑；玩家消息与自主 trigger 共用；brain.ts 保留旧拼接作未装配时兜底

• 📉 情绪衰减接入确认（P2-4）：核验 lifestyle tick 每 5s 已调 emotion.decay()（v1.4 已接），本轮技能 ctx 增加可选 emotion getter，自主钓鱼等技能路径同样能触发情绪

• 📜 日志轮转（P2-5）：utils.ts app.log 超 2MB 自动 size 轮转（保留 3 份）；新增 restart-with-rotate.ps1 启动脚本（stdout/stderr 重定向 + 启动前 size 轮转），替代外部裸 > restartN.log 无限增长的重定向方式

• 🎯 版本 bump → 1.6.0

v1.5.0 (2026-09-05)

v1.5.0 (2026-09-05)

• 🧠 记忆层 v2（蓝图第六节落地）：新增 memory-v2.ts + 独立 memory2.json —— 短期记忆（session 内 importance 淘汰）、长期记忆（地点/带情感事件/人物/成就/失败）、对话记忆（话题冷却 300s / 玩家画像 / 滚动摘要）。v1 memory.json 结构与写入零改动，两层并存。大脑上下文自动注入「记忆段」（短期印象/熟悉地点/难忘往事/画像/话题避免）

• 🎬 事件源接情绪补齐（P0-2）：guardian 濒死撤退 → 后怕(almost_died)、死亡 → 沮丧(lost_items)；挖到钻石 → 兴奋+成就事件+长期记忆；建成小屋 → 满足+长期事件

• 🧩 工具上下文新增 emotion/eventBus/memoryV2 注入通道（getter 形式，断线重连安全）

• 🧪 验证：verify-memory-v2.cjs 10 项断言全过（含畸形文件/损坏 json 防御）

• 🎯 版本 bump → 1.5.0

v1.4.0 (2026-09-05)

• 🧩 情绪+事件接线 v1（蓝图"注入不干预"落地）：emotion.ts / events.ts 正式启用——lifestyle 每 5s tick 复用状态快照做世界事件扫描（危险/环境/社交/成就，60s 去重），触发情绪（紧张/后怕/宁静…）并自然衰减（3%/tick）；大脑上下文注入「当前情绪 + 刚发生的事」——只作语气参考，不干预决策

• ⚡ 性能：EventWatcher 扫描从 4 次全量 getStatus() 收敛为 1 次（复用 lifestyle 快照）

• 🎯 版本 bump → 1.4.0（v1.3.2 = ① 重连泄漏修复快照）

v1.3.2 (2026-09-05)

• 🐛 修复断线重连泄漏：Guardian/Lifestyle/Companion 统一优雅 detach（定时器+监听器全清），断线/重连不再残留后台定时器抢身体——模拟 5 轮重连实测零泄漏（verify-reconnect.cjs 自检通过）

• 🛡️ 防崩溃：陪伴层延迟问候/关心补 try/catch，断线后触发不再可能炸进程

• 🧩 新增基础模块：emotion.ts（情绪系统 valence/arousal，13 事件触发+衰减）与 events.ts（事件层 EventBus/EventWatcher，危险/环境/社交/成就检测）——为"人类视角感知 + 世界主动推送"铺路（本版未启用，接线见后续版本）

• 🎯 版本号正式 bump 1.3.0 → 1.3.2

v1.3.0 (2026-08-31)

• 🪃 跟随玩家：新增 follow-player / stop-follow（动态寻路、1.5s 检测、掉线自愈、身体锁独占）

• 🔒 身体锁补全：jump / fly-to 等动作工具统一走 withBody，与 body-controller 白名单对齐，杜绝抢身体

• 🧠 大脑桥纯转发版：brain 不再内置人设/直连 LLM，统一转发 AstrBot /api/v1/chat（人设与记忆归 AstrBot 管，bot 只当"传话筒+执行手"）

• 🔗 MCP 多客户端：SSE 支持 ?clientId=名字 区分多方控制

• 📊 49 个工具（13 分类）全量可用

• 🐛 修复：建房期间大脑不再重复指挥（工具互斥）、欢迎语跨进程持久化不重复刷

• 🗑️ 清理：移除已停用的 build-schem 工具引用与示例图纸（开源合规检查）

v1.2.0 (2026-08-30)

• 🤖 AI 一键部署：新增 AGENT_DEPLOY.md（给 AI agent 的部署指南）+ setup.js 智能配置引导（node setup.js --auto 全自动：装依赖/检测 AstrBot/生成配置/已有配置保护）

• 🧠 大脑免配置：自动探测本机 AstrBot(6185) → 自动选 astrbot 桥模式，无需 API key

• 🔗 寻路大升级：换用 @nxg-org/mineflayer-pathfinder@0.0.26，gotoSmart 卡住自救链（挖方块→tp→喊救命）

• 🛡️ 配置校验增强：启动时明确报出缺失字段，并提示用 setup.js 引导

• 📖 README 新增"AI Agent 部署"快速入口

v1.1.0 (2026-08-30)

• 📘 新增 PROJECT_DOC.md 项目总文档（初心实录/架构/计划/踩坑记录）

• 🧠 大脑记忆注入：每次回复前把「当前目标 / 历史目标 / 玩家偏好 / 最近经历」拼进上下文，机器人不再"失忆"

• 🔒 单活跃控制者锁：动作类工具同一时刻只允许一个会话执行，其他会话提示"bot 正被另一个会话控制"，2 分钟无动作自动让出

• ⏱️ 建房停滞检测：build-schem 45 秒无实际进度自动取消并播报

• ✂️ 修复双句回复：send-chat 直接发话后 5 秒内大脑不再重复转发

• 📣 欢迎语只发一次：跨进程/断线重连不再重复刷欢迎语

v1.0.0 (2026-08-29)

• 首个可运行版本：mineflayer 身体 + AstrBot/LLM 大脑 + MCP SSE 接口

• 40+ MCP 工具：感知 / 移动 / 放置 / 合成 / 熔炼 / 钓鱼 / 繁殖 / 种田 / 战斗 / 图纸建房 / 创造模式发物品

🙏 Acknowledgements / 致谢

参考与启发（设计思路参考、代码独立实现）

本项目的功能设计与实现思路参考并受以下开源项目启发。除下文显式标注处，本项目代码均独立实现，与下列项目无代码复用关系；各项目版权归原作者所有：

随仓库分发的第三方代码（代码复用/分发，各版权归原作者，按各自许可证使用）

运行依赖

• mineflayer 生态（mineflayer、minecraft-data、pathfinder、tool、schematic、nbt 等，均 MIT）

• @nxg-org/mineflayer-pathfinder（寻路）

• MCP SDK @modelcontextprotocol/sdk、prismarine-viewer（顶视图渲染）、pngjs、zod、express 等（见 package.json）

本项目以 MIT 协议开源。使用本仓库意味着你确认并接受上述第三方组件的许可证条款。