小編精選 - 技術文章翻譯 · 04月11日

以 AI 對話式驅動的開源 3D 建築設計編輯器 — Aedifex

用 AI 對話式驅動的開源 3D 建築設計編輯器 — Aedifex

![主動規避不合理的位置.png](https://i.imgur.com/uGOhF36.jpeg)

一句話介紹

Aedifex 是一個在瀏覽器中運行的 3D 建築編輯器，整合了基於大型語言模型的 AI 設計助理。你可以透過自然語言描述設計意圖，AI 會直接在三維場景中執行拉牆、開窗、擺放家具等操作——不需要學習任何專業建模工具。

專案基於上游開源 3D 編輯器核心深度改造，重新設計了場景資料架構與渲染管線，並在此基礎上構建完整的 AI 輔助設計能力。

開源地址：github.com/TangSY/aedi…

體驗地址：aedifex.app

為什麼做 Aedifex

起因

最初是在 GitHub 上看到一個開源的 3D 建築編輯器專案，基礎能力不錯——牆體、門窗、家具擺放都有，使用 Three.js 渲染，瀏覽器裡就能跑。但互動方式仍是傳統那一套：左側工具列選工具、右側屬性面板調參數、中間畫布上點來點去。能用，但對非專業使用者來說門檻不低。

當時正好在研究 AI Agent 的落地場景，想找一個合適的領域做深度整合。看到這個編輯器時覺得方向對了：3D 建築設計天生適合自然語言互動——人描述空間時用的就是「客廳放一組沙發、對面擺電視櫃」這類語句，而編輯器的每一個操作（建牆、開窗、放家具）都可以被抽象成結構化的工具呼叫。把 AI Agent 接入編輯器的操作介面，使用者就不需要學習任何工具，直接用自然語言描述即可。

這個想法促使我在原專案的基礎上開始改造。

改造過程

真正動手後才發現，「接入 AI」遠不是加個對話框那麼簡單。原專案的資料結構、渲染方案、互動邏輯都是為手動編輯設計的，要讓 AI 成為核心交互方式，幾乎每一層都需要重新設計。

場景資料重構

原專案的節點結構不太適合 AI 操作——AI 需要快速定位並操作任意節點。改為設計為「扁平字典 + parentId 參照」的架構：所有節點（牆體、門窗、家具、樓板、屋頂等）平鋪存放在一個 Record<nodeid, node> 字典中，透過 parentId 表達層級關係，任何節點都可以透過 ID 直接索引。同時引入了 schema 版本管理與資料遷移框架，為後續的結構演進留出空間。

這個資料結構也決定了編輯器的建模能力邊界：牆體建造支援自動倒角與 0.5m 網格吸附，門窗透過 CSG 布林運算在牆面上精確切割開洞，天花板、樓板、屋頂都支援自訂多邊形輪廓。多層建築透過 Level 節點組織，支援逐層檢視或爆炸視圖。

渲染與材質

渲染層面，上游專案已具備不錯基礎：Three.js WebGPU 渲染、SSGI 全域光照、後處理管線、亮暗主題切換等。Aedifex 在此基礎上做了一些可靠性優化（WebGPU 裝置遺失監測、後處理錯誤自動復原等），但整體渲染架構沿用上游設計。材質系統提供 10 種預設（木材、磚石、混凝土、玻璃、金屬、大理石等），支援完整的 PBR 參數控制，所有節點類型皆可套用。

改造的重點不在渲染——上游專案在這方面已做得很好。真正從零構建的是下列讓 AI 能理解並操作三維空間的能力。

空間語義層

這是整個 AI 能力的基礎，也是改造中投入最多的部分。

單純把場景資料丟給模型，它只能看到一堆座標數字，並不真正理解空間關係。因此建立了一套場景序列化系統，每次對話時自動分析當前場景，提取出結構化的上下文資訊：每個房間的尺寸形狀與 AABB 邊界、所有家具的位置與類別、牆面朝向及其上的門窗位置、樓層結構等。整個上下文控制在 4000 token 以內，透過內容哈希做快取，避免重複計算。

空間偵測基於網格洪泛填充演算法（以 0.5m 為解析度掃描整個樓層），標記每個網格單元為地面、牆體、室外或室內，自動識別封閉區域生成房間（Zone），並透過 Shoelace 公式計算面積。牆面也會被標註內外朝向。

有了這層空間語義，AI 才能真正理解使用者的自然語言描述。當你說「把沙發前面的茶几往右挪一點」，AI 就能精確知道「沙發前面」是指哪裡、「茶几」是哪個節點、「右」在當前空間中代表的方向。這是基於真實場景資料的空間推理，不是關鍵字匹配。

28 種 AI 工具

AI 在 Aedifex 中不是一個聊天視窗，而是一個擁有完整操作能力的 Agent。目前定義了 28 種結構化工具呼叫，涵蓋建築設計的全流程：

類別 / 工具 / 說明

結構建造：add_wall、add_slab、add_ceiling、add_roof — 畫牆、鋪地、加頂、建屋頂（支援 7 種型式：坡屋頂、人字頂、單坡、荷蘭式等）
門窗開設：add_door、add_window — 在指定牆面精確開洞，支援配置規格參數
家具佈置：add_item、move_item、remove_item — 從 100+ 件家具目錄中選取、擺放、調整屬性
修改：update_wall、update_material、update_item — 修改尺寸、材質、PBR 參數等
批量操作：batch_operations — 多個操作原子執行，保證一致性
主動交互：ask_user、propose_placement — 遇到歧義主動確認，提供 2–3 種方案供選擇

每一個操作的結果都是真實的三維物件——可以繼續手動編輯、可以匯出為 GLB/STL/OBJ、可以用第一人稱走進去檢視。

家具目錄與智慧匹配

內建了 100+ 件家具模型，涵蓋客廳、臥室、廚房、衛浴、戶外等場景。每件家具都有完整的 metadata：尺寸、類別、標籤、GLB 模型路徑、縮圖、縮放偏移參數，以及是否靠牆放置（attachTo: 'wall'）。

AI 選擇家具時會經過多階匹配：先精確匹配 ID，再匹配名稱，最後做模糊子串搜尋。還支援形狀描述匹配——使用者說「圓形茶几」、「L 型沙發」、「雙人床」，系統能自動篩選對應形狀的款式。若匹配不到會按類別推薦相似選項，而不是靜默失敗。

多層碰撞驗證與佈局優化

AI 放家具不能隨心所欲——不能擺到房間外面、不能與既有家具重疊、靠牆家具要自動貼合。這不是單純的碰撞檢測，而是一套四層驗證體系：

家具碰撞檢測：基於網格空間分區（0.5m 單元格，類似模擬人生的網格），每件家具佔據的網格單元會被記錄，新放置的物品透過 AABB 檢測判斷是否重疊，支援旋轉物品的足跡計算
房間邊界鉗位：家具不會被放到房間多邊形之外，超出邊界的座標會被自動修正到最近的合法位置
牆體交叉檢測：新建牆體時檢查是否與既有牆體交叉（允許 T 形連接，但拒絕 X 形交叉）
批量操作內碰撞：同一次 batch_operations 中的多個物品之間也會做碰撞檢測，衝突時自動偏移

驗證通過後，還有一層佈局優化引擎做後處理：靠牆家具自動吸附到最近牆面（0.3m 閾值內）；家具朝向自動修正（面向房間中心）；功能組間距規則強制執行（沙發到茶几 0.4m、沙發到電視櫃 2.5m）；所有家具組之間保持最小 0.6m 通道寬度。這層優化讓 AI 放出來的家具不只是「不重疊」，而是「佈局合理」。

幽靈預覽機制

這是讓使用者放心使用 AI 的關鍵設計。AI 產生的操作不會立即寫入場景，而是先建立帶臨時標記的節點，以半透明的「幽靈」形式在 3D 檢視器中展示預覽效果。預覽期間撤銷歷史會被暫停，不污染操作記錄。使用者確認後臨時節點轉為正式節點，拒絕則完整還原原始狀態。系統還會保存被刪除節點的快照，確保任何情況下都能回退。

這意味著你可以放心用自然語言反覆試探，不用擔心搞亂既有設計。

Agentic Loop：迭代式 AI 對話

Aedifex 的 AI 不是簡單的一問一答。每次使用者發出指令後，AI 進入一個最多 8 輪的迭代循環：執行操作 → 觀察結果 → 判斷是否需要繼續。

例如使用者說「幫我佈置一個完整的客廳」，AI 不會只放一件家具就停下。它會在一輪循環中依序放置沙發、茶几、電視櫃、落地燈，每放一件都會檢查空間衝突與佈局合理性，遇到不確定的地方（例如剩餘空間放不下使用者想要的大件家具）會主動透過 ask_user 工具詢問，而不是猜測。整個過程對使用者來說就是一次對話，但背後可能經歷多輪工具呼叫與決策。

上下文管理與對話壓縮

支援連續多輪對話，從空房間一步步聊到整套佈置完成。但對話越長，送給模型的 token 越多，成本與延遲也會上升。

系統內建了 token 預估器，支援 CJK 字元的準確估算（±20% 精度），即時監控對話長度。當消耗超過模型上下文視窗的 85% 時，會自動呼叫摘要模型壓縮歷史對話——保留關鍵的設計決策與當前場景狀態，丟棄中間的試探與調整細節。壓縮對使用者透明，不會中斷對話流程。

基於大型語言模型的天然多語言能力，AI 支援任何自然語言互動——中文、英文、日語、法語、西班牙語，你用什麼語言說，它就用什麼語言回應。

實際使用效果

用一個範例說明完整交互流程——從零設計一個客廳：

<div><div><div></div><span>arduino</span></div><div><div> <span>體驗AI代碼助手</span></div><div> <span>代碼解讀</span></div><div>複製代碼</div></div></div>```
<span>→ <span>"建一個 5m × 4m 的客廳"</span></span>
<span>  AI 畫出四面牆，自動偵測封閉區域生成房間</span>
<span></span>
<span>→ <span>"南面牆開一扇 2.4 米的落地窗"</span></span>
<span>  AI 在南牆精確位置切出窗洞</span>
<span></span>
<span>→ <span>"L 型沙發靠西牆，對面放電視櫃"</span></span>
<span>  AI 從目錄匹配家具，自動貼牆放置</span>
<span></span>
<span>→ <span>"茶几放沙發前面，旁邊來一盞落地燈"</span></span>
<span>  AI 計算空間關係，居中放置茶几，落地燈放在不遮擋動線的位置</span>


四句話，一個完整的客廳佈局就出來了。

AI 遇到歧義不會自行決定，而是停下來確認：

<div><div><div></div><span>arduino</span></div><div><div> <span>體驗AI代碼助手</span></div><div> <span>代碼解讀</span></div><div>複製代碼</div></div></div>```
<span>→ <span>"把客廳的桌子刪了"</span></span>
<span> AI：客廳裡有餐桌和茶几，你要刪哪一張？</span>
<span></span>
<span>→ <span>"在這面牆上開個門"</span></span>
<span> AI：這面牆上已經有窗戶了，開門需要移走窗戶，確認繼續嗎？</span>

編輯器交互能力

AI 是核心交互方式，但手動編輯能力同樣完整。

撤銷重做與操作歷史

撤銷重做支援最近 50 步操作歷史，基於 Zundo 的智慧差異檢測——每次撤銷時透過物件參照比較找出實際變更的節點，只重新渲染這些節點及其父節點（觸發合併幾何體更新），而不是整個場景。場景變更檢測也做了優化：用單調遞增的 nodesVersion 計數器替代 JSON.stringify 全量比較，從 O(N) 降到 O(1)，用於自動儲存的變更判斷。

AI 操作還有獨立的操作歷史面板：每次 AI 確認的操作會記錄在可摺疊的列表中，支援「單次操作撤銷」——不需要回退到某個時間點，可以直接撤銷中間的某一步操作並恢復對應的節點快照。

2D 平面圖面板

7500 行程式碼的完整 2D 編輯介面，與 3D 視圖即時同步。在 2D 視圖中繪製的牆體會即時出現在三維場景中，選中的物體在兩個視圖中同步高亮。

支援牆體繪製與即時標註尺寸、0.5m 網格吸附、門窗在牆面上的參數化定位、房間多邊形與樓板的可視化編輯、參考圖片匯入（支援縮放 0.01x–100x）、公制/英制單位切換。編輯器提供 3D、2D、分割畫面三種視圖模式。

第一人稱漫遊

透過 Pointer Lock API 實現沉浸式體驗：WASD 控制前後左右移動，滑鼠控制視角，Q/E 鍵升降，Shift 鍵衝刺（移動速度翻倍至 10m/s）。視點高度固定在 1.65m（模擬真人站立視角），俯仰角範圍限制在 ±85°，防止畫面翻轉。

3D 框選與批量操作

在 3D 檢視中拉框選取多個物體，支援批量移動、刪除、修改材質。框選邏輯獨立實作（561 行），處理了透視投影下的物體拾取精度問題。

音效回饋

內建事件驅動的音效系統：網格吸附、家具拾取/放置/刪除/旋轉、結構建造/拆除都有對應音效回饋，透過獨立的 SFX Bus 管理，使用者可在設定中開關。

自動儲存

帶狀態機的自動儲存系統：1 秒 debounce 防抖、預覽模式暫停儲存、待儲存佇列合併、BeforeUnload 事件觸發緊急刷新防止資料遺失。儲存狀態在 idle → pending → saving → saved → error 之間流轉，UI 即時反映當前狀態。

其他交互細節

羅盤 HUD 固定在右上角，每 3 幀更新一次朝向，紅色三角始終指向北方，旋轉角度變化小於 0.5° 時跳過渲染。設計完成後可以匯出為 GLB（Unity / Unreal / Blender）、STL（3D 列印）、OBJ（通用交換格式），匯出時自動剝離編輯器圖層（網格線、選區高亮等），只保留純淨的三維模型資料。

AI 安全設計

在 AI 交互層面也做了一些安全考量。使用者輸入會經過 prompt 注入防護處理：剝離 Markdown 標題語法、過濾 SYSTEM/INSTRUCTIONS/ASSISTANT 等關鍵詞前綴、清除分隔線標記，防止惡意輸入竄改 AI 的行為規則。

AI 的行為規則也經過仔細設計：語言鎖定（使用者用什麼語言提問，AI 就用什麼語言回答，不會中英混雜）；批量刪除前必須透過 ask_user 工具向使用者確認；嚴格遵守數量指令（使用者說「放一把椅子」就只放一把，不會自作聰明多放幾把）；兩個以上相關操作自動合併為 batch_operations 原子執行，保證場景一致性。

現在的樣子

經過這些改造，Aedifex 已經不是原專案加個 AI 對話框了，而是一個「以 AI Agent 為核心交互方式重新設計的 3D 建築編輯工具」。

大多數時候，你只需要用自然語言描述你想要的空間，AI 就能理解你的意圖並直接操作場景。這是我認為 3D 設計工具應有的交互方式：不需要學習工具，只需要描述你想要什麼。

專案架構

Aedifex 採用 Turborepo + pnpm 管理的 monorepo 結構，程式碼按職責拆分為多個獨立套件：

<div><div><div></div><span>bash</span></div><div><div> <span>體驗AI代碼助手</span></div><div> <span>代碼解讀</span></div><div>複製代碼</div></div></div>```
<span>aedifex/</span>
<span>  apps/</span>
<span>    app-editor/         <span># Next.js 應用，整合所有 packages</span></span>
<span>  packages/</span>
<span>    core/               <span># 核心庫：Zod schema、Zustand 狀態、空間系統</span></span>
<span>    viewer/             <span># 3D 渲染器：R3F 元件、後處理、匯出</span></span>
<span>    editor/             <span># 編輯器：UI 面板、AI 系統、互動工具</span></span>
<span>    ui/                 <span># 共享 UI 元件庫（Headless + Tailwind）</span></span>


每個套件職責明確、邊界清晰：`core` 不依賴任何 React 渲染邏輯，可獨立用於資料處理與驗證；`viewer` 只負責三維渲染，不包含編輯器 UI；`editor` 組合前兩者提供完整編輯體驗。這種分層讓未來擴展變得容易——例如要做一個只讀的模型預覽頁，只需引入 `core` + `viewer` 即可，不會帶入編輯器的程式碼。

### 類型安全：從編譯期到執行期

整個專案使用 TypeScript 嚴格模式，但編譯期的型別檢查只能覆蓋程式碼內部邏輯。對於外部資料（使用者輸入、AI 回傳的操作參數、檔案匯入的場景資料），光靠 TypeScript 不夠——型別資訊在執行期並不存在。

因此所有核心資料結構都用 **Zod** 定義 schema，實現編譯期 + 執行期的雙重型別安全。每種場景節點（牆體、門窗、家具、屋頂等）都有對應的 Zod schema，定義欄位型別、預設值、取值範圍。資料寫入場景時必須經過 `parse()` 驗證，不合規的資料會在入口處被攔截，而不是在渲染時才拋錯。

節點類型透過 Zod 的 `discriminatedUnion` 實現安全的執行期判別——拿到一個節點物件，可以根據 `type` 欄位準確判斷它是牆體還是家具，TypeScript 也能自動推導出對應的欄位型別，不需要手動型別斷言。

節點 ID 生成也做了規範：每種型別有固定前綴（如屋頂節點的 ID 以 `rseg_` 開頭），透過自訂產生器自動建立，便於除錯時快速識別節點型別。

---

技術棧
---

層級 / 選型理由
- 渲染：Three.js WebGPU + React Three Fiber — 瀏覽器端最強的 3D 方案，WebGPU 性能顯著優於 WebGL，R3F 讓 Three.js 與 React 生態整合
- 框架：Next.js 15 + React 19 — App Router + SSR，首屏載入快，SEO 友好
- 狀態管理：Zustand + Zundo — 輕量級狀態管理，Zundo 提供時間旅行能力（撤銷重做），支援按欄位分區追蹤幾何
- 幾何運算：three-bvh-csg — CSG 布林運算實現牆面開洞，BVH 空間索引加速碰撞查詢
- AI：OpenAI 兼容 API — 不綁廠商，支援 OpenAI、Azure、Ollama 等任何兼容端點
- 型別/驗證：TypeScript 5.9 + Zod — 編譯期型別檢查 + 執行期 schema 驗證，雙重保障
- UI：Tailwind CSS 4 + Lucide Icons — 原子化樣式、圖示體系一致，元件庫 headless 設計便於主題客製
- 工具鏈：Turborepo + pnpm — 增量建置，套件間依賴自動拓撲排序，CI 快取命中率高

---

快速開始
----

<div><div><div></div><span>bash</span></div><div><div> <span>體驗AI代碼助手</span></div><div> <span>代碼解讀</span></div><div>複製代碼</div></div></div>```
<span>git <span>clone</span> https://github.com/TangSY/aedifex.git</span>
<span><span>cd</span> aedifex</span>
<span>pnpm install</span>
<span>pnpm dev</span>

訪問 localhost:3000 即可使用。編輯器的所有基礎功能（建牆、門窗、家具、材質、匯出、第一人稱漫遊）開箱即用，不需要任何設定。

AI 功能需要額外設定環境變數：

<div><div><div></div><span>bash</span></div><div><div> <span>體驗AI代碼助手</span></div><div> <span>代碼解讀</span></div><div>複製代碼</div></div></div>```
<span><span># .env.local</span></span>
<span>AI_API_KEY=your-api-key</span>
<span>AI_BASE_URL=https://api.openai.com/v1  <span># 可選，預設 OpenAI</span></span>
<span>AI_MODEL=gpt-5.4                         <span># 可選，預設模型</span></span>



相容任何 OpenAI 格式的 API 端點——官方 OpenAI、Azure OpenAI、本地 Ollama、DeepSeek 等皆可。只要介面遵循 OpenAI 的 Chat Completions 格式並支援 Function Calling，就能直接接入。

---

參與貢獻
----

Aedifex 採用 MIT 授權開源，歡迎任何形式的參與：

- **Star** — 最直接的支持，也幫助更多人發現這個專案
- **Issue** — 回報 Bug、提出功能建議、討論設計方案
- **Pull Request** — 程式碼貢獻，無論大小
- **分享** — 在社群媒體、技術社群、身邊的設計師朋友中推薦

如果你對以下方向感興趣，特別歡迎參與：

- **家具模型擴充** — 目前內建 100+ 件，涵蓋主要場景但還有很大擴展空間
- **AI 工具增強** — 更多的操作類型、更智慧的空間推理
- **渲染效果優化** — 紋理貼圖、環境光遮蔽、更豐富的材質表現
- **國際化** — UI 介面的多語系支援（AI 對話已天然支援多語言）

**GitHub**：[github.com/TangSY/aedi…](https://link.juejin.cn?target=https%3A%2F%2Fgithub.com%2FTangSY%2Faedifex)

**線上體驗**：[aedifex.app](https://link.juejin.cn?target=https%3A%2F%2Faedifex.app)

---

原文出處：https://juejin.cn/post/7626208064598736948