Minecraft 1.20.1 · Forge 47.x · Java 17+（开发环境 Java 21）
在游戏中接入大语言模型（LLM）的 AI 助手模组：按 H 打开对话窗口与 AI 聊天，AI 可以查看游戏状态、以玩家上下文 + 控制台权限执行任意原版/模组命令、联网查询 MC 百科、读写 mod 配置、创建数据包实现复杂机制，并支持语音输入。
- 按
H打开原版风格对话窗口，滚动历史、输入历史（↑↓）、思维链轨迹可折叠 - 函数调用（function calling）循环：AI 可调用工具实现效果，工具轮数上限可配置
- Token 统计：会话累计消耗 / 上下文占用 / 服务端缓存命中率实时显示
- 历史按「用户轮次」整体裁剪，保证 prompt 前缀稳定以命中 DeepSeek 上下文缓存（0.1x 计费）
- 可随时停止对话、一键新会话
| 类别 | 工具 |
|---|---|
| 状态查看 | get_player_state / get_nearby_entities / get_inventory / get_world_info / scan_blocks / get_looking_at(视线射线检测) |
| 命令执行 | execute_commands（玩家上下文+权限4，@s/@p 可用，逐条返回输出） / command_help(游戏内命令语法查询) / list_structures |
| 查询 | get_recipe（服务器配方表，含模组） / search_jei / lookup_jei_recipe（JEI 集成，可选依赖） |
| 配置 | list_configs / read_mod_config / write_mod_config（自动备份 .bak，路径安全限定） |
| 数据包 | write_datapack_file / list_datapack（AI 可直接创建 advancement+function 机制） |
| 联网 | web_search(Bing→百度) / fetch_web_page(白名单域名+编码处理+截断) |
| 聊天 | send_chat_message |
- 按
L说话（可自定义热键），松开识别；识别结果可直接发送或填入输入框等确认 - 内置国内主流服务预设：硅基流动 SiliconFlow（推荐）/ 火山方舟·豆包 / 阿里云百炼 FunASR / OpenAI / 自定义
- 阿里云新版接口支持（JSON+base64 直传 + 工作空间专属域名
{workspaceId}占位） - 录音设备可选、麦克风自检、开始/结束提示音效
- AI 调用工具完成任务后，右上角弹出原版成就样式 toast + 提示音效（可独立开关）
- 对话渲染缓存（历史未变不重算换行），长任务不掉帧
- 思维链分组上限 30 条；工具轮次上限默认 20（防 AI 空转）
- 工具结果写入历史前截断（默认 1500 字符），控制 token 消耗
- 系统提示词内置执行策略：批量合并命令、失败止损、查询高效
当前版本仅支持简体中文：游戏内菜单、设置界面、提示信息、AI 回复均使用中文。 英文语言文件（
lang/en_us.json）已预留，多语言支持将在后续版本提供。
推荐使用 DeepSeek（deepseek-chat，或 deepseek-v4-flash）：
- 国内直连无需代理，延迟低、价格便宜
- 完整支持函数调用（function calling），本模组工具系统的理想搭配
- API Key 在 DeepSeek 开放平台 申请
任何 OpenAI 兼容接口均可使用（在设置界面修改 API 地址与模型名即可）。
- 将
mcagent-1.4.0.jar放入mods/（需 Forge 47.x，Minecraft 1.20.1） - 进入游戏按
H→ 左上角「设置」→ 填入 API Key（DeepSeek 或任意 OpenAI 兼容服务） - 语音输入：设置 → 语音 → 选择服务预设并填入对应平台 Key（硅基流动推荐，免费额度）
- 对话示例：
- "给我 64 个钻石"
- "在我面前 10 格生成一座村庄"（
list_structures+/place structure） - "查看我准星对准的方块"（
get_looking_at） - "做一个手持木棒攻击僵尸时召唤闪电的数据包"（
write_datapack_file）
配置文件：config/mcagent-common.toml（apiKey、模型、提示词、上限、白名单等全部可调）
- Forge 47.3.0 / 官方映射，
--release 17编译（游戏运行于 Java 21） - 网络层：SimpleChannel 双通道（C2S 命令执行 / 通用服务端查询，requestId 关联 CompletableFuture）
- 命令执行：
CommandSourceStack以「请求玩家为实体 + 权限等级 4」构造，@s/@p选择器正确解析，输出经自定义CommandSource捕获回传 - AI 会话：专用工作线程跑函数调用循环，活动回调实时驱动 GUI 思维链显示，HTTP 请求 500ms 粒度响应取消
- JSON：游戏自带 Gson；HTTP：
java.net.http.HttpClient - JEI 集成：
IJeiPlugin（compileOnly 可选依赖，运行时检测）
# JDK 17+（开发用 21），Gradle 8.7（wrapper 已配置腾讯云镜像）
./gradlew build # 产出 build/libs/mcagent-1.4.0.jar
./gradlew runClient # 启动开发环境本模组在设计与实现过程中调研、参考了以下开源项目（致谢）：
| 项目 | 借鉴内容 |
|---|---|
| RIvance/minecraft-chatgpt-assistant | Forge 端 AI 聊天助手整体形态、配置菜单思路 |
| podkarpacie/CommandForge-MCP | 工具集设计（实体/命令/NBT/数据包分类）、安全验证思想 |
| aaronaalmendarez/gemini-minecraft | 配方查询（Recipe Mastery）、注册表扫描、Undo 快照思路 |
| TartaricAcid/TouhouLittleMaid（车万女仆） | 语音在线 API 方案（阿里云/Siliconflow 多提供商、Java Sound 麦克风管理、推键说话）；因此放弃本地 Vosk 打包（native 库与 Connector 冲突导致启动崩溃） |
| moeru-ai/airi | Minecraft agent 提示词设计：错误熔断、行动预算、上下文管理（执行策略段） |
| MineDojo/Voyager | 迭代执行原则：环境反馈 → 修正 → 自检；技能复用思想（数据包工具） |
| Pryzmm/Shriek | Vosk 语音集成调研（最终因 JNA 与 Sinytra Connector 冲突未采用） |
| Jaffe2718/Microphone-Text-Input | 语音识别模式设计（AUTO_SEND / RELEASE_KEY_TO_INPUT） |
| alphacep/vosk-api | 离线语音识别方案调研 |
- AI 以**控制台权限（等级 4）**执行命令，
requireOp默认关闭（LAN 内任何玩家可用），请谨慎使用 - AI 可读写 config 目录内所有 mod 配置、创建数据包文件——均限定在安全路径内
- 语音/AI Key 明文存储于配置文件，请勿分享
MIT