minecraft-ai-building

minecraft-ai-building

游戏内一句 /aibuild "盖座塔"——AI 自主规划、施工、离屏渲染自检，迭代到验收通过。

快速开始 · 工作原理 · 实测证据 · 文档 · English

一棵地标树的诞生：agent 自主规划骨架、挂叶、布灯（deepseek-flash 路由批次，实机截图）

把 coding agent CLI（Kimi Code 等）接入 Minecraft（Java 1.21.11 + Fabric 单机）： mod 暴露 HTTP API，独立 stdio MCP 桥把 agent 的工具调用翻译进游戏。

状态：活跃开发中。当前焦点是大树生成器离线重写（scratch/tree_lab/），房屋体系冻结维护。冷启动恢复见 docs/HANDOFF.md。

为什么做这个

让 LLM 在 Minecraft 里自由盖房子，最先暴露的不是能力问题，是审美坍缩：不加以 约束时，agent 会反复盖出雷同的房子。这不是体感——E9 实验用同一中性提示词连跑 8 次、 预注册统计阈值实测：同任务组材质 Jaccard 相似度 0.729，而引入随机抽签的对照组降到 0.561（见 docs/experiments.md）。

纯树干版：看骨架形态	全叶版：看最终剪影

抽签器作用下的生成树群像——多样性是抽签抽出来的，不是模型自发产生的

类似的坑还有一串：AI 徒手摆楼梯朝向必歪、屋顶几何写着写着就漏、家具堵死房门让人 进不去。这些问题的共同点是可以被程序精确判定——那就不该交给模型赌运气。

所以本项目的核心理念是：

算得准的全给程序，AI 只做审美决策。

LLM 的不确定性由确定性代码围住：几何、结构、验收全部程序化；模型的发挥空间被收拢 到它真正擅长、且机器算不准的地方——选风格、定体量、做取舍。

快速开始

# 构建 mod（需要 JDK 21）
cd aibuild-mod && ./gradlew build
# 产物 aibuild-mod/build/libs/aibuild-1.0.0.jar → 放进游戏 mods 目录

# bridge 单元测试（不需要游戏）
cd mc-mcp-bridge && ./gradlew test

运行需求：Minecraft Java 1.21.11 + Fabric 单机存档；一个 coding agent CLI （Kimi Code 等）；Python 3（生成器仅用标准库）。agent 模型与额度配置在 <游戏目录>/aibuild/config.json。

它是怎么工作的

实际体验：访谈 agent 先在聊天框里和你敲定剪影、气质与构图——需求钉死才施工

游戏内 /aibuild 拉起无头 agent 进程；mod 暴露 HTTP API（放置/回读/渲染/快照）； 独立 stdio MCP 桥（mc-mcp-bridge，手写 JSON-RPC 2.0、零 SDK）把 agent 的工具调用 翻译成 HTTP。围绕这条链路，不确定性被一层层确定性机制围住：

• 访谈 agent 先行：开工前访谈定稿需求（提案制，带约束/自由二选一），需求钉死才施工
• 风格卡 + 抽签器：19 张风格卡定义审美空间，抽签决定用哪张——治审美坍缩
• 61 个参数化生成器：屋顶/楼梯/巨树/家具等全部确定性 Python（stdlib only）， AI 填参数不写几何
• 7 项机器验收器：可行走性/支撑/连通性等硬指标不过就不算完
• 渲染多角度出图：离屏 GL 渲染供人工验收——agent 看不了图，只能核结构摘要， 审美验收权永远在人
• 快照/undo + 多会话并发：4 个 agent 并行盖小镇互不干扰，429/异常退出自动续跑， 会话状态原子落盘可重启恢复

早期冒烟版：球形棒棒糖	v45：分叉与剪影层次

树生成器的迭代对照——离屏渲染管线把「丑」变成可量化、可回看的验收信号，不靠肉眼回忆

成果示例：AI 从自然语言指令自主盖出的完整城堡

仓库布局：aibuild-mod/（Fabric mod：游戏内命令、HTTP API、离屏渲染管线）、 mc-mcp-bridge/（MCP 桥，85 个单元测试独立可测）。生成器与卡作为默认资产打包在 aibuild-mod/src/main/resources/assets/aibuild/defaults/（patterns/ 61 个 Python 生成器 + 7 个验收器，styles/ 19 张风格卡），mod 首次运行时释放到游戏目录供 agent 使用。

实测证据

实验	结果
E2 单 agent 基线	16.1 分钟盖完一座庄园（36 轮 / 52 次工具调用 / 放置约 13.8 万块，零失败）
E4 复赛	3 agent 25.9 分钟盖完临水小镇（约 3 倍于庄园体量，83 轮 / 27,218 块，零失败零自愈）
bridge 单测	85/85 全绿（mock backend，不需要游戏）
模型路由	地标树建造切换到 deepseek-v4-flash：14/14 成功，均值 7.9 分钟/棵、¥0.24/棵——比 K3 档快 2.2 倍、便宜约 96%
成本审计	91 会话总成本 ¥345.28（K3 真实定价），单栋均值 ¥4.84，E2 庄园 ¥8.50。逐 token 对账见 docs/quant-audit-2026-08-13.md

文档索引

• docs/specs/ — 设计文档（总体设计、bridge HTTP API、房屋细节目录）
• docs/HANDOFF.md — 跨窗口交接文档（30 秒冷启动恢复，"血泪纪律"清单）
• docs/experiments.md — E0–E9、E13 实验记录（含失败复盘与 A/B 统计实验）
• docs/quant-audit-2026-08-13.md — 成本/ token 量化审计（定价错误修正，逐 token 对账）
• docs/BACKLOG.md — 任务积压与重开条件

English

An in-game coding agent that autonomously plans, builds, and self-inspects Minecraft structures from a single natural-language command. Key idea: deterministic code fences the LLM — parameterized generators and machine validators handle everything that can be computed exactly; the AI only makes aesthetic decisions. Custom zero-SDK JSON-RPC/MCP bridge (85 unit tests), 19 style cards + lottery against mode collapse (A/B-tested with pre-registered thresholds), offscreen-render self-inspection loop, multi-agent concurrent builds. Active development; see docs/HANDOFF.md for the engineering log.

License

• 代码（aibuild-mod/、mc-mcp-bridge/、生成器脚本）：AGPLv3——衍生作品必须同协议开源并署名，网络提供服务同样触发。
• 非代码资产（docs/、风格卡、实验语料、图片）：CC BY-NC-SA 4.0——署名、非商用、相同方式共享。