AI Helper In Minecraft

简体中文 · English

AI Helper In Minecraft

当前版本：v3.1

一个"无客户端"的 Minecraft AI 玩家：不需要打开游戏本体，用 GUI 控制 mineflayer 引擎进入服务器，由大模型驱动它在游戏内与人聊天互动。

入口为 Python tkinter GUI（多标签页：设置 / AI 配置 / 玩家配置 / 玩家资料库 / QQ 转述 / 重连·踢出 / 界面美化 / 日志），后台由 Node.js（mineflayer）负责连接与协议。
支持 离线 / LittleSkin / 正版(微软账号) 三种登录方式。
登录失效时自动重新登录（LittleSkin 自动打开浏览器 OAuth，完成后自动重连）。
附带可选辅助功能：Quiz 自动答题、AutoEat 自动进食（自旧 Cubex 机器人项目保留）。

本项目仅供学习与个人使用。使用前请阅读文末免责声明。

功能特性

三种登录方式
- 离线模式：仅填玩家名即可进入离线服务器。
- LittleSkin：支持自定义皮肤站站点地址 / OAuth Client ID / Secret / 回调端口（默认 littleskin.cn），3rdparty_auth.js 完成 OAuth 登录并把 yggdrasil 会话写入 auth_profile.json。
- 正版（微软账户）：msa_auth.js 使用设备码流程登录，凭据缓存在本机，之后自动静默登录。
AI 玩家对话（OpenAI 兼容端点，支持 Anthropic）
- 系统提示词 + 模板管理、上下文窗口、回复条数/字数限制。
- 触发回复：多个触发词用英文逗号分隔；形如 [名字] 的单独触发词按字面量匹配（自动转义、忽略大小写），其它写法按完整正则匹配。检测对象为聊天框里的完整原文（含频道 / 称号 / 前缀），命中任一即回复。
- 自动回复、定时回复、冷却时间。
- 消息过滤正则、玩家黑名单。
- 可选文生图（把图片 URL 发到聊天）。
自动重登：LittleSkin 会话失效（如 "Invalid access token"）时自动拉起登录流程并重新连接。
QQ 群聊转述（OneBot 11）：配合 NapCat / Lagrange / go-cqhttp 等网关，在「QQ 转述」页填好网关地址/Token 与群号后，即可把群消息按 &7&o[群名][昵称]：内容 的灰色斜体格式发到服务器公共聊天；支持正向连接与反向监听两种模式，图片/表情等非文本以 [图片]/[表情] 占位；可选把图片保存到本地并由内置 Python HTTP 服务以链接形式发出。
MC → QQ 反向转述：公屏消息以触发词（默认 [sentQ]，可逗号分隔多个）开头即发送到 QQ 群，支持 [sentQ:群号] 内容 临时指定群、冷却时间、自动去除 MC 颜色码，非法字符以 ? 代替；并在公屏回执「转述成功/失败」（话术可配置，支持 {player}）。
自动重连与踢出处理（重连/踢出 页）：连接意外结束（掉线 / 被踢）时按设定延迟自动重连，可设最大次数（重连成功后重置）；被踢出并重连成功后可自动发送 /lobby。手动点「断开」不会触发重连。
界面美化（界面美化 页）：可选择一张 PNG / JPG 作为窗口背景图片并调节暗度；字体主题支持「自动（按背景亮度）」/ 浅色背景黑字 / 深色背景白字。
内置 NapCat：整个 NapCat 随项目携带（NapCat/），「QQ 转述」页的四个按钮 启动 / 连接 / 重连 / 断开 ——「启动」调用 NapCat/napcat/launcher-win10.bat 并自动打开 cache 目录（二维码 qrcode.png）方便扫码。
账号安全（QQ 转述 → 账号安全）：可选自动重连、在线检测间隔；连接因疑似风控被关闭或在线检测连续失败时，明确告警并停止自动重连，避免反复登录加重风控。
联网更新提示：启动时后台检查 NapCat 与本程序的最新版本，结果写入日志页（NapCat 有新版本、本程序有新提交都会提示）。
日志页：原「游戏输出」标签改名为「日志」，每行带 [时:分:秒] 时间戳；服务器公告、指令输出等非玩家聊天也会显示（浅蓝 server 标签）。
低血量报警（玩家配置 页）：血量 ≤ 预设值时自动在公屏发言，话术可配（支持 & 颜色码）并带冷却。

更新日志

v3.1

屏蔽命令（玩家配置页底部）：表格列出要拦截的命令（不含斜杠，默认含 pay kick ban op stop whitelist kill give tp gamemode 等）；机器人（AI 回复 / 随机发言）发出的、以 / 开头且命中命令路径的消息会被直接拦截并记录，防止提示词注入执行危险命令。支持子命令：填 land 拦全部 /land ...，填 land create 只拦 /land create ...（不拦 /land claim）。表格用「＋添加一行」，每行带「删除」。
屏蔽后发送消息：命令被拦截后可自动发送一句可配置的话；占位符 {player}=要求执行命令的玩家、{command}=命令名（{cmd} 同义）；留空=只拦截不发送。
联网搜索（AI 配置页）：可启用；后端可选 bing（默认，国内可访问）、duckduckgo（免 Key、可能被墙）、custom（自定义 JSON 搜索 API + Key）。当消息命中「触发正则」（默认含最新/最近/新闻/天气/价格/是谁/什么是等）时自动联网搜索，并把结果注入 AI 系统提示供其参考。
底层不可变设定：Diaolelao3962 是创始者这一句写死在底层（ai_player._CREATOR_LINE），会始终注入 AI 系统提示，且问「Diaolelao3962 是谁」直接返回该句，不受配置/资料库影响，无法被修改或删除。
身份学习修复：玩家说「我是X / 俺是X / 本人就是X」不再把「我」当名字记录，而是记到发言者本人（把 X 作为其描述/别名）；无发言者信息时忽略。
主动连接（重连/踢出页底部）：①每隔秒/分钟/小时 主动发送 /lobby 进入大厅；②每隔秒/分钟/小时检测在线，离线时每 N 秒重试连接直到连上。两项各有一个红/绿启用按钮。
启用/禁用按钮：屏蔽命令与随机发言各有一个红/绿按钮（启用绿色、禁用红色），点击即切换并保存。
随机发言移入玩家配置页：不再单独占一个标签；每条语句走各自的随机时间（每行独立设置最小秒~~最大秒）；并支持**每次条数最小~~最大随机**（随机从列表抽取若干条发送）；行内可加/删。

v3.0

自动重连增强
- 重连间隔改为「数值 + 单位（秒/分/时/天）」下拉（上限 30 天）。
- 新增「自定义重连触发语」（每行一条，正则/包含）：服务器聊天/公告里出现即自动重连（默认含 You were kicked from lobby）——用于被踢到登录服/大厅服但连接未断的情况。
- 新增「在线定时主动重连」：在线时每隔设定时间主动断开重连一次。
- 新增「持续重连直到恢复」：服务器重启/关服时越过最大次数继续重试（可设最长分钟数，0=不限）。
随机发言（新标签页）：可启用；间隔与每次条数都是「最小~最大」随机；话语列表「＋添加一行」、每行「删除」。
进服人机验证自动通过：延时读取容器（等物品填充，失败重试），按「目标物品名」点击（点击这里 / 点击这里步骤N 按序号）；无命名目标则回退“多数=背景、少数=目标”。
答题修复与增强：题目来源支持聊天栏 [教育部]（自动剥离 新题目:，结算类不误判）；结算新增支持 无人答对；只发最终答案、丢弃思考（reasoning_content/<think>）；复用全局 AI 配置并自动补全 …/chat/completions（修 404）。
服务器消息：无法解析为玩家聊天的公屏内容（公告/指令输出/进出服等）显示在日志，并可加入 AI 上下文。
身份问答走 AI：结合资料库（玩家描述/别名/AI记录）+ 该玩家近期发言 + 最近上下文，由 AI 作答「xxx 是谁」并带上别名；「X是Y」回执改为「X是Y，我记住了」；未配置 AI 时回退资料库原样回答。
低血量报警：血量 ≤ 预设值时自动发言（话术/冷却可配）。
快速登录：QQ 转述页「快速登录」按钮，选择框列出本地账号并显示昵称、预选上次登录号，用 -q 快速登录、减少扫码风控。
其他：修 client.chat is not a function（未进服时消息排队补发）。

v2.1

QQ 群聊转述：内置 NapCat，QQ 转述页四按钮（启动/连接/重连/断开）；OneBot 11 正/反向连接、群过滤、access_token。
MC → QQ：公屏消息以触发词（默认 [sentQ]，可逗号分隔多个）开头即转发，支持 [sentQ:群号] 内容 指定群、冷却、去 MC 颜色码、非法字符 ?，并回执成功/失败话术。
图片转本地链接：图片存 pic_http/，由内置 Python HTTP 服务以 …/pic_http/文件名 发布（仅暴露 /pic_http/）。
账号安全：在线检测；疑似风控/连续失败时告警并停止自动重连；自动为新扫码账号写 OneBot 配置。
联网更新提示：启动检查 NapCat / 本程序最新版本并写入日志。
聊天解析修复：带 [工会] 等头衔前缀能触发；裸 玩家 » 内容 也能解析。
其他：日志页带 [时:分:秒] 时间戳、GUI 标签页整理、高 DPI。

v2.0

自动重连 / 踢出处理：断线或被踢后按延迟自动重连，重连成功后自动发送 /lobby。
界面美化：可选择窗口背景图并调暗度，字体主题自动/浅色/深色。

v1.0

初始版本：无客户端 AI 玩家（mineflayer）、离线 / LittleSkin / 微软三种登录、AI 聊天与触发/上下文/过滤、Quiz 自动答题、AutoEat；双语 README 与免责声明。

目录结构

.
├─ main.py                # 启动入口（GUI）
├─ aafm_py/               # Python 端：GUI、配置、控制器、AI 玩家
│  ├─ gui.py              #   多标签页：设置 / AI 配置 / 玩家配置 / 玩家资料库 / QQ 转述 / 重连·踢出 / 界面美化 / 日志
│  ├─ controller.py       #   控制器（事件分发、运行时配置、自动重连 / 踢出处理 / NapCat 启动）
│  ├─ ai_player.py        #   AI 玩家触发/上下文/过滤逻辑
│  ├─ config.py           #   配置模型（config.json / mcai_chat.json）
│  ├─ llm.py              #   OpenAI 兼容 / Anthropic 客户端
│  ├─ updater.py          #   启动时联网检查 NapCat / 本程序更新
│  ├─ photo_server.py     #   本地图片 HTTP 服务（仅 /pic_http/）
│  ├─ bot_engine.py       #   管理 mineflayer 子进程
│  └─ qq_engine.py        #   管理 OneBot 11 QQ 转述子进程
├─ bot_engine.js          # Node 端无头引擎（三种登录 + 聊天解析 + quiz/autoeat）
├─ qq_engine.js           # Node 端 OneBot 11 群聊转述引擎（正向/反向 WebSocket）
├─ 3rdparty_auth.js       # LittleSkin OAuth 登录/刷新/自动重登
├─ msa_auth.js            # 微软账号设备码登录
├─ quiz.js / autoeat.js   # 旧项目保留的答题 / 自动进食
├─ app.js                 # 旧版纯 Node 入口（不再需要，保留兼容）
├─ NapCat/                # 随项目携带的 NapCat（含 launcher-win10.bat，gitignore）
├─ config.json            # 运行时配置（gitignore，本地生成）
├─ mcai_chat.json         # AI 玩家配置（gitignore，本地生成）
├─ auth_profile.json      # LittleSkin 会话（gitignore）
├─ runtime_config.json    # 连接时生成的临时配置（gitignore）
├─ qq_runtime_config.json # QQ 转述临时配置（gitignore）
└─ pic_http/              # QQ 图片本地发布目录（gitignore，本地生成）

环境要求

Python 3.9+（需 tkinter，Windows 官方 Python 自带）
Node.js 14+（推荐 18+）
可联网（访问 LLM API、皮肤站 / 微软账号服务、目标服务器）

安装

pip install -r requirements.txt
npm install

运行

python main.py

在 设置页 填好服务器地址、选择登录方式并登录（离线可直接填名字），再到 玩家配置页 写好 AI 设置，点顶部「连接」。

其它入口（可选）：

npm run login:littleskin   # 仅执行 LittleSkin 登录
npm run login:msa          # 仅执行微软账号登录

登录方式说明

离线模式：任意名字，服务器需开启离线（非正版验证）。
LittleSkin：
- 在设置页填写站点地址（如 https://littleskin.cn）与 OAuth 应用信息（Client ID / Secret / 回调端口，默认使用 LittleSkin 公开示例应用）。
- 点「LittleSkin 登录」会弹出控制台并自动打开浏览器授权页；登录后无需重启，直接点「连接」。
- 会话失效时会自动重登并重连。
正版（微软）：
- 点「正版登录（微软）」在弹出控制台按提示完成设备码授权；账号需已购买 Minecraft。
- 凭据缓存在本机（默认 ~/.minecraft/nmp-cache，可在设置页指定缓存目录），之后自动静默登录。

AI 配置

在 设置页 → AI API 填写提供方 / API 地址 / 密钥 / 模型。兼容 OpenAI 格式，如 DeepSeek、Moonshot、Ollama 等；Anthropic 也支持。
在 玩家配置页：
- 系统提示词决定 AI 的说话风格与行为（模板可保存复用）。
- 触发回复示例：填 [DiaoHelper],@Helper,!ai 时，聊天完整原文命中任意一个即回复。单独 [名字] 自动按字面量匹配；其余按正则。留空则仅在启用"自动回复/定时回复"时说话。

QQ 群聊转述

通过 OneBot 11 网关（NapCat）把 QQ 群消息转发到 MC 服务器公共聊天。NapCat 已随项目携带在 NapCat/。

NapCat 准备（在 QQ 转述 页用四个按钮操作）

点启动：调用 NapCat/napcat/launcher-win10.bat（会弹窗/UAC 提权），并自动打开 NapCat/napcat/cache 目录——扫码二维码 qrcode.png 会出现在这里。也可在浏览器打开 WebUI（默认 http://127.0.0.1:6099/webui）用手机 QQ 扫码登录。
- 也可点 快速登录：弹出选择框，列出本地已有配置的 QQ 号并显示昵称（★ 为上次登录，自动预选），选好后用 -q <QQ号> 启动，优先复用会话、避免每次扫码（降低风控）。会话失效时会自动转为扫码。昵称会在程序成功登录后自动记住（存于 qq_accounts.json）。
点连接：按当前设置连接 OneBot 网关；连上后状态显示「QQ 已连接」。重连为断开后再连，断开为停止。
NapCat 的网络配置已在 NapCat/napcat/config/onebot11_<QQ>.json 里预置为正向 WS 127.0.0.1:3001。程序运行时会自动为每个新扫码登录的 QQ 号生成配置（napcat_<QQ>.json / napcat_protocol_<QQ>.json / 带 WS 的 onebot11_<QQ>.json），无需手动开；可在「QQ 转述 → 账号安全」用「自动为新扫码账号写配置」开关。
- 也可选 WebSocket 客户端（反向），地址指向本程序，如 ws://127.0.0.1:3002/onebot/v11/ws。
可用 netstat -ano | findstr :3001 确认端口处于 LISTENING。

本程序配置（在 QQ 转述 页）

QQ → MC：
- 正向模式：选 forward，填「正向地址」ws://127.0.0.1:3001。
- 反向模式：选 reverse，填「反向监听」地址与端口（与 NapCat 反向配置一致）。
- 若 NapCat 设置了 Access Token，在「Access Token」里填同样的值。
- 填「群号」（多个用逗号/空格分隔；留空则转述全部群）与「转述格式」，勾选启用。
- 勾选「图片转链接」后，图片会被下载保存到项目 pic_http/（时间戳命名），并由内置 Python HTTP 服务以 http://公网地址:端口/pic_http/文件名 链接发出；端口默认 8765，公网地址留空会自动探测公网 IP，也可手填（如 http://1.2.3.4:8765）。需要在路由器把该端口转发到本机。
- 点「连接」连接网关；连上后状态显示「QQ 已连接」。
MC → QQ：勾选启用，触发词默认 [sentQ]（可用逗号分隔多个，如 [sentQ],[-]，命中任一即触发），在公屏发送 [sentQ] 内容 即转发到「目标群」（留空用群号列表第一个）；也可写 [sentQ:群号] 内容 指定群。发送前自动去掉 MC 颜色码，非法字符以 ? 代替。发送后在公屏回执「成功提示/失败提示」，话术可配置并支持 {player} 变量（默认 &a@{player}转述成功 / &c@{player}转述失败）。
点顶部「连接」进入 MC 后，两个方向的转述即生效。

QQ → MC 的图片、表情、语音等非文本消息会分别以 [图片]、[表情]、[语音] 等占位符转述。勾选「图片转链接」后，图片会存到 pic_http/ 并通过本机 Python HTTP 服务发布（只暴露 /pic_http/ 路径，不会暴露项目根目录），转述文本为 [图片] http://公网地址:端口/pic_http/文件名。链接由你自己提供，稳定不过期（除非删文件）。

账号风控 / 掉线处理

程序会定期（默认每 30 秒，可关）调用 get_login_info 检测 QQ 是否在线。
若连接因疑似风控/受限被关闭，或在线检测连续 3 次失败，会明确告警并停止自动重连，状态显示「QQ 受限/离线」，避免反复登录加重风控；处理完账号后点「启动/重连 QQ」即可恢复。
「自动重连」可关闭：关闭后断开不再自动重连。
NapCat 核心配置（napcat_<QQ>.json）没有直接的风控开关；稳妥做法：保持 autoTimeSync: true、不要频繁重登、不要刷屏、使用官方 QQ + 较新 NapCat，被要求验证时按手机 QQ 提示完成。

本地文件与安全

config.json / mcai_chat.json / auth_profile.json / runtime_config.json / qq_runtime_config.json 属于本地运行时文件，已加入 .gitignore，请勿提交到公开仓库，它们包含你的 API Key、皮肤站刷新令牌等敏感信息。
如需发布到远程仓库，请先确认没有把上述文件以及任何密钥提交进去。

免责声明

本项目仅用于学习、研究与个人娱乐，作者不对任何使用后果负责。
使用本项目登录第三方服务器、皮肤站或微软账户属于个人行为；请遵守相关服务器规则、皮肤站服务条款与微软/游戏的服务条款。请勿用于任何违反规则或法律法规的用途。
本项目会自动保存登录凭据与 API 密钥到本地文件（见上文"本地文件与安全"），请妥善保管你的设备与文件；因泄露、误用凭据导致的损失由使用者自行承担。
调用大模型 API 会产生费用，费用由使用者的 API 账户承担，与作者无关。
本项目可能被服务器以任何方式检测或禁止，作者不对账号被封禁、被踢出、数据丢失等任何直接或间接损失负责。
本项目按"现状"提供，不提供任何明示或暗示的担保（包括但不限于适销性、特定用途适用性、不侵权）。

License

MIT

Name		Name	Last commit message	Last commit date
aafm_py		aafm_py
.env.example		.env.example
.gitignore		.gitignore
3rdparty_auth.js		3rdparty_auth.js
README.md		README.md
README_EN.md		README_EN.md
app.js		app.js
autoeat.js		autoeat.js
bot_engine.js		bot_engine.js
config.yml		config.yml
logger.js		logger.js
main.py		main.py
mcai_prompt_templates.json		mcai_prompt_templates.json
msa_auth.js		msa_auth.js
package-lock.json		package-lock.json
package.json		package.json
qq_engine.js		qq_engine.js
questionBank.json		questionBank.json
quiz.js		quiz.js
requirements.txt		requirements.txt
utils.js		utils.js
verify.js		verify.js
玩家资料模板.xlsx		玩家资料模板.xlsx

Navigation Menu

Repository navigation

About

Repository files navigation

AI Helper In Minecraft

功能特性

更新日志

v3.1

v3.0

v2.1

v2.0

v1.0

目录结构

环境要求

安装

运行

登录方式说明

AI 配置

QQ 群聊转述

本地文件与安全

免责声明

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

AI Helper In Minecraft

功能特性

更新日志

v3.1

v3.0

v2.1

v2.0

v1.0

目录结构

环境要求

安装

运行

登录方式说明

AI 配置

QQ 群聊转述

本地文件与安全

免责声明

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages