Minecraft AI Builder

从图片或文字描述 → AI 分析 → 结构化设计 → Minecraft .schem → 3D 预览 → 自动粘贴到 Paper + FAWE 服务器。

v2.0 — 前端推倒重来, monorepo + React 19 + react-three-fiber + 4 步 Wizard。

架构

图片/文字 → [Layer 1: 分析]   AnalysisReport
         → [Layer 2: 设计]   BuildPlan DSL  ← 核心 IR
         → [Layer 3: 施工]   Schematic + 3D预览 + 材料统计
Mineflayer Bot → Paper Server (FAWE)

项目结构 (monorepo)

.
├── apps/
│   └── web/                  React 19 + Vite + TS 前端 (取代旧 frontend_new/)
├── packages/
│   ├── shared-types/         OpenAPI → TS 类型 (pnpm gen:types 生成)
│   └── api-client/           TanStack Query hooks, 走 vite proxy
├── backend/                  FastAPI 后端 (Python 3.13)
│   ├── app/
│   ├── scripts/export-openapi.py
│   └── openapi.json          (生成, 入 .gitignore)
├── bot/                      Mineflayer 桥 (占位, 待实现)
├── package.json              workspace 根
├── pnpm-workspace.yaml
└── tsconfig.base.json

快速开始

前置依赖

• Node.js ≥ 20
• pnpm ≥ 9 (npm i -g pnpm)
• Python 3.13
• 一个运行中的 Paper + FAWE Minecraft 服务器
• 一个 LLM API key (OpenRouter / Anthropic / DeepSeek) — 留空则用 mock 关键字服务

1. 安装

# JS 部分
pnpm install

# Python 部分
cd backend
pip install -r requirements.txt
cd ..

2. 配置环境变量

# 后端 (放 backend/.env)
cp .env.example backend/.env
# 编辑 backend/.env, 设置 AI_API_KEY

# 前端 (放 apps/web/.env, 可选)
cp apps/web/.env.example apps/web/.env

3. 生成共享类型 (后端 → 前端)

pnpm gen:types

这会:

1. 跑 backend/scripts/export-openapi.py 导出 backend/openapi.json
2. 跑 openapi-typescript 生成 packages/shared-types/src/api.d.ts

改后端 Pydantic 模型后, 重新跑这条命令。

4. 启动

开 3 个终端:

# Terminal 1: 后端
pnpm backend:dev
# 跑在 http://localhost:8000

# Terminal 2: 前端
pnpm dev
# 跑在 http://localhost:5173 (Vite proxy /api → :8000)

# Terminal 3: Mineflayer bot (待实现)
cd bot
# node index.js  # 这条命令现在会失败, 见 bot/README

5. 使用

打开 http://localhost:5173, 4 步流程:

1. 上传 — 拖入图片 / 输入文字
2. 确认 — AI 返回建筑概要, 调整比例
3. 预览 — R3F 3D 视图, 切层, 看材料
4. 粘贴 — 设坐标, 发送给 bot

开发常用命令

pnpm dev                 # 启动前端
pnpm build               # 构建所有 workspace
pnpm typecheck           # TS 检查所有
pnpm gen:types           # 重新生成 OpenAPI → TS 类型
pnpm backend:openapi     # 只导 openapi.json
pnpm backend:dev         # 只跑后端

设计原则

• 三层分离: 分析 ≠ 设计 ≠ 施工
• 类型驱动: OpenAPI 单一来源, 前后端类型强一致
• Wizard 状态机: 4 步清晰流程, URL 可直达
• 零调试残留: 没有 hardcode 的 "2开间" 按钮指向不存在的文件
• 组件拆分: 旧 Viewer3D.vue 383 行 → 拆成 BlockColors / BlockShapes / useVoxelBuckets / VoxelMesh / ViewerCanvas / LayerToggle / MaterialLegend

已知遗留 / 未来工作

• bot/index.js 待实现 (Mineflayer 入口)
• 后端 services/llm_service.py 是旧实现, 已被 ai_service.py 替代, 待删除
• 后端 v1 /api/assembly 仍存在以防回滚, 后续 v2 稳定后可删
• 大图上传 (base64) 体积优化: 可改 presigned URL
• i18n: UI 仍用中文, 未抽离
• 单元测试: 4 步跑通后再补

验收清单

• apps/web/vite.config.ts 代理指向 :8000 (不是 :8006)
• 主页没有 "2开间/5开间" 调试按钮
• 没有任何 any 类型
• Viewer3D.vue 等价物被拆到 ≥ 4 个文件
• pnpm typecheck 通过
• 改后端字段后 pnpm gen:types 同步生效
• README 写明 4 步流程