Skip to content

README.zh-CN.md

Latest commit

 

History

History
235 lines (162 loc) · 7.51 KB

README.zh-CN.md

File metadata and controls

235 lines (162 loc) · 7.51 KB
Raw
Aedifex Logo

Aedifex

内置 AI 设计助手的开源 3D 建筑编辑器

用自然语言设计建筑 — AI 自动创建墙体、放置门窗、布局家具，实时预览变更。基于 WebGPU 驱动。

MIT License

English | 中文

demo-2.5x.mp4

功能特性

结构与布局

  • 墙体系统 — 绘制墙体，自动斜接处理，可调节厚度和高度，自动对齐 0.5m 网格。
  • 门窗系统 — 在墙上放置门窗，支持自定义尺寸、开启方向和铰链位置。
  • 房间识别 — 墙体围合后自动检测房间（Zone），显示面积、形状分析和空间信息。
  • 多楼层 — 支持楼层堆叠、展开、独显模式，每层独立平面图。
  • 楼板、天花板与屋顶 — 基于多边形的楼板、天花板和屋顶分段绘制。

家具与物品

  • 内置目录 — 沙发、桌椅、床、书架、灯具、树木等丰富的家具目录。
  • 智能放置 — 碰撞检测、墙面吸附对齐、房间边界约束，确保物品始终在房间内。
  • 可交互物品 — 开关灯光、调节灯亮度等交互功能。

材质系统

  • 10 种预设 — 白色、砖块、混凝土、木材、玻璃、金属、石膏、瓷砖、大理石和自定义。
  • 自定义属性 — 每个节点独立设置颜色、粗糙度、金属度、透明度。
  • 全节点支持 — 墙体、楼板、门、窗、天花板、屋顶均可应用材质。

视图与导航

  • 街景漫游 — 第一人称步行模式，WASD 移动、鼠标环顾、Q/E 上下浮动，从室内视角体验设计。
  • 明暗主题 — 一键切换亮色/暗色视口主题。
  • 指南针 — 始终可见的方位指示器。
  • 相机控制 — 鼠标和触摸板操作。Mac 触摸板优化：双指滑动平移 + 捏合缩放 + 右键旋转。

导出

  • GLB — glTF 二进制格式，适用于 Web 和游戏引擎。
  • STL — 用于 3D 打印。
  • OBJ — 通用交换格式。

AI 设计助手

  • 自然语言 — 用文字描述需求：「创建一个 5m x 4m 的房间，布置成卧室。」
  • 35 种工具 — 覆盖家具、墙体、门窗、楼板、天花板、屋顶、楼梯、分区、楼层、建筑、扫描参考、批量操作、多方案提议和确认式预览等完整设计动作。
  • 幽灵预览 — AI 建议以半透明预览显示，确认后才执行。
  • 智能循环 — AI 自动迭代调整位置，处理碰撞和边界约束，在请求模糊时主动向用户提问。
  • 目录匹配 — 模糊名称匹配 + 形状变体警告（如请求圆桌但只有方桌时会提醒）。

快速开始

环境要求

  • Node.js 20+
  • pnpm 9+（npm install -g pnpm）
  • 支持 WebGPU 的浏览器：Chrome 113+、Edge 113+、或 Firefox Nightly

安装与启动

# 克隆
git clone https://github.com/TangSY/aedifex.git
cd aedifex

# 安装依赖
pnpm install

# 启动开发服务器（所有包 + 编辑器）
pnpm dev

# 打开 http://localhost:3002

AI 设计助手配置（可选）

AI 设计助手需要 OpenAI 兼容的 API 密钥。未配置时编辑器正常使用，但 AI 面板不可用。

  1. 复制示例配置：
cp .env.example apps/editor/.env.local
  1. 编辑 apps/editor/.env.local，填入你的 API 密钥：
# 必填 — OpenAI API 密钥（或任何 OpenAI 兼容服务商）
AI_API_KEY=sk-your-api-key-here

# 可选 — 更换 API 地址以使用兼容服务商（如 Azure、本地 LLM）
AI_BASE_URL=https://api.openai.com/v1

# 可选 — 模型选择（以下为默认值）
AI_CHAT_MODEL=gpt-4o
AI_SUMMARIZE_MODEL=gpt-4o-mini

说明： AI 助手在服务端调用 OpenAI 兼容 API，密钥不会暴露到浏览器。支持所有实现了 OpenAI Chat Completions API 的服务商（OpenAI、Azure OpenAI、Anthropic 代理、本地 Ollama 等）。

操作指南

鼠标

操作 输入
选择 左键点击
平移 中键拖动，或 空格 + 左键拖动
旋转 右键拖动
缩放 滚轮

触摸板（Mac）

操作 手势
平移 双指滑动
缩放 双指捏合
旋转 右键拖动（双指点按 + 拖动）

街景漫游

操作 输入
移动 WASD
环顾 鼠标
上升/下降 Q / E
退出 Escape

架构

Turborepo 单仓库，5 个发布包 + 编辑器应用：

aedifex/
├── apps/editor/         # Next.js 16 应用（入口）
├── packages/core/       # 数据模型、状态管理（Zustand）、几何系统、空间查询
├── packages/viewer/     # 3D 渲染（React Three Fiber + WebGPU）
├── packages/editor/     # 编辑器 UI：工具、面板、选择管理、AI 助手
├── packages/mcp/        # MCP server：35 个工具，提供自然语言场景控制
└── packages/ui/         # 共享 shadcn/ui 基础组件
包 职责
core 节点 Schema（Zod）、场景存储 + 撤销重做（Zundo）、几何系统、空间网格、事件总线
viewer 渲染器、相机、灯光、后处理、楼层/扫描/参考系统
editor 工具、面板、选择管理、AI 助手、自定义相机控制
mcp Model Context Protocol server，将场景操作暴露给 Claude Desktop / Cursor
ui 编辑器使用的共享 shadcn/ui 基础组件

场景数据模型

节点存储为扁平字典，通过 parentId 表达层级：

Site → Building → Level → Wall → Door / Window
                        → Zone（房间）
                        → Slab / Ceiling / Roof
                        → Item（家具）

关键文件

路径 说明
packages/core/src/schema/ 节点类型定义（Zod schemas）
packages/core/src/schema/material.ts 材质系统（10 种预设 + 自定义属性）
packages/core/src/store/use-scene.ts 场景状态存储
packages/core/src/systems/ 几何生成系统
packages/viewer/src/components/renderers/ 节点渲染器
packages/viewer/src/components/viewer/ Viewer 主组件
packages/editor/src/components/tools/ 编辑器工具（墙体、区域、物品、楼板）
packages/editor/src/components/ai/ AI 助手（Prompt、Agent 循环、验证器）
packages/editor/src/components/editor/first-person-controls.tsx 街景漫游模式
packages/editor/src/components/editor/export-manager.tsx 场景导出（GLB、STL、OBJ）

技术栈

层级 技术
渲染 Three.js（WebGPU）、React Three Fiber、Drei
框架 React 19、Next.js 16
状态 Zustand + Zundo（撤销/重做）
校验 Zod
几何 three-bvh-csg（布尔运算）
工具 TypeScript 5、Turborepo、pnpm

贡献

参见 CONTRIBUTING.md 了解开发规范。

# 构建所有包
turbo build

# 构建指定包
turbo build --filter=@aedifex/core

致谢

Aedifex 基于 Pascal Group Inc. 的开源项目 Pascal Editor 构建，采用 MIT 协议。感谢原作者在 3D 建筑编辑器核心方面的出色工作。

许可证

MIT

友情链接