3D AI Town

Executive Summary

摘要

本报告系统梳理了 3D AI Town 项目从零到单体建筑精细化的完整技术探索过程，覆盖技术选型、架构设计、建模方法论、光影调校、多智能体引擎、资产管线六大维度。

19

NPM 依赖包

23

源代码文件

4,378

JavaScript 代码行

11/11

技术验证通过率

99%

资产压缩率峰值

核心结论：纯 Claude Code + Three.js 程序化建模可以产出高质量可交互3D建筑。关键突破是模块化组件系统——每个门、窗、柱子、工位都是独立命名的可交互对象，这是AI生成的静态模型永远做不到的。

Technology Stack

技术栈全景

三层架构：浏览器运行时 → 构建工具 → 离线资产管线，共19个依赖全部验证通过。

浏览器运行时

技术	版本	职责定位	验证状态
Three.js	0.183.2	3D 渲染引擎核心 — WebGL2 渲染管线、场景图、材质系统、后处理	✅ Pass
Spark.js	0.1.10	3D Gaussian Splatting — 照片级环境渲染，与 Mesh 深度合成	✅ Pass
Yuka	0.7.8	游戏 AI 引擎 — 转向行为、有限状态机、路径跟随、实体管理	✅ Pass
Recast Navigation	0.43.0	导航网格 — WASM Recast/Detour 移植，运行时 NavMesh 生成	✅ Pass
Litegraph.js	0.7.18	可视化节点编辑器 — ComfyUI 同款引擎，20种自定义节点类型	✅ Pass
Tweakpane	4.0.5	参数调试面板 — 实时调整场景参数	✅ Pass
Dexie.js	4.x	IndexedDB 封装 — 公司状态/Agent记忆/任务历史持久化	✅ Pass
DeepSeek API	Chat v1	LLM 对话引擎 — NPC 动态对话，OpenAI 兼容接口	✅ HTTP 200

离线资产管线

技术	版本	职责定位	验证数据
Blender	5.0.1	无头 Python 脚本 — 减面/UV展开/LOD生成/Lightmap烘焙	118KB→33KB
glTF-Transform	4.3.0	模型优化管线 — Draco压缩/量化/纹理WebP/去重/剪枝	73.3% 压缩率
Meshoptimizer	1.0.1	网格简化算法	✅ Pass
Sharp	0.34.5	纹理压缩处理（PNG→WebP）	✅ Pass
Draco3D	1.5.7	Google 顶点数据压缩编码	✅ Pass
KTX-Parse	1.1.0	GPU 纹理格式解析（Basis Universal）	✅ Pass

Architecture

系统架构

23个源文件，按职责分层为6个模块域。

// 项目结构 — 6大模块域

ai-town-3d/
├── src/
│   ├── main.js                  // 主入口 · 渲染循环 · 事件系统
│   ├── world.js                 // 场景构建 · 灯光 · 地面
│   │
│   ├── components/              // ★ 模块化建筑组件系统
│   │   ├── building.js          // 773行 · 交互式罗马风格二层建筑
│   │   ├── materials.js         // 程序化材质库 · Canvas法线/粗糙度贴图
│   │   └── primitives.js        // 基础几何体工具函数
│   │
│   ├── company/                 // ★ 多智能体公司引擎
│   │   ├── Company.js           // 5种公司模板 · 生命周期管理
│   │   ├── Agent.js             // 6种角色Agent · LLM集成
│   │   ├── Orchestrator.js      // 编排器 · DAG并行执行 · 黑板模式
│   │   └── TaskQueue.js         // 任务队列 · 依赖解析 · 状态机
│   │
│   ├── scene/                   // 场景管理
│   │   ├── sceneManager.js      // 室外↔室内相机过渡动画
│   │   └── interior.js          // 室内空间生成模板
│   │
│   ├── workflow/                // 可视化流程编排
│   │   ├── nodes.js             // 20种自定义Litegraph节点
│   │   └── editor.js            // 编辑器UI · 保存/加载/运行
│   │
│   ├── ui/                      // 运营面板
│   │   └── dashboard.js         // 公司仪表盘 · Agent状态 · 日志
│   │
│   ├── chat.js                  // DeepSeek LLM 对话接口
│   ├── npc.js                   // NPC系统 · Yuka状态机 · 5个居民
│   ├── controls.js              // WASD 第三人称控制器
│   ├── splat.js                 // Gaussian Splatting 加载
│   ├── modelLoader.js           // glTF/GLB 模型加载器
│   ├── navmesh.js               // NavMesh 导航网格
│   └── db.js                    // IndexedDB 持久化层
│
├── scripts/
│   ├── blender-batch.py         // Blender 无头批处理
│   └── optimize-gltf.mjs        // glTF 优化管线
│
└── package.json                 // 19 dependencies

Key Achievements

核心成果

🏛️

模块化交互建筑系统

773行代码构建罗马风格二层建筑。每个门、窗、柱子、工位都是独立可交互对象——这是本项目最大的技术突破。

28扇窗（真实开口） 6根收分凹槽柱 20根InstancedMesh栏杆分段式墙体 LatheGeometry Canvas法线贴图 MeshPhysicalMaterial

🎨

程序化材质系统

完全无外部资源依赖。通过 Canvas 2D API 程序化生成 Color Map + Normal Map + Roughness Map。

石灰岩(Color+Normal+Rough) 瓦片(Color+Normal) 柱身凹槽(Normal) 木纹(Color) clearcoat漆面门 transmission玻璃

🤖

多智能体公司引擎

每栋建筑 = 一家AI公司。提交目标 → CEO分解 → Planner规划 → Creator执行 → Reviewer审核。DAG依赖链自动流转，支持并行。

5种公司模板 6种Agent角色 DAG任务队列黑板共享状态 DeepSeek LLM

⚡

资产优化管线

双管线：Blender 无头脚本（减面/UV/LOD） + glTF-Transform（Draco/WebP/量化）。实测 75MB → 777KB。

99% 压缩率 73.3% glTF优化 Blender 5.0.1 无头 Draco 编码 WebP 纹理

Building Specification

单体建筑技术规格

罗马风格二层交互式建筑，全程序化生成，零外部资源依赖。

外部组件清单

组件	工艺
三层退台石基座	BoxGeometry + 石材纹理
分段式墙体（4面×2层）	门窗位置真实镂空开口
28扇大窗户	边框条+玻璃+十字窗棂+窗台+楣石+拱心石
6根收分凹槽立柱	LatheGeometry收分曲线 + 法线贴图fluting + 三段柱头
双开门+拱形亮窗	clearcoat漆面 + 黄铜把手 + 放射窗棂
中央阳台（20根栏杆）	InstancedMesh + 贝塞尔曲线托架
三层额枋+齿饰	楣梁+壁带+檐口罗马建筑全套
三角山花	ShapeGeometry 三角楣饰
玻璃雨篷	transmission材质 + 金属框 + 斜撑
六角壁灯×2	CylinderGeometry六角 + ConeGeometry帽
落水管×2 / 烟囱	CylinderGeometry / BoxGeometry

内部组件清单

组件	数量/说明
木地板（程序化木板纹理）	2层
天花板 + 吊灯灯具	6盏
工位（桌+屏+键盘+椅）	7个 · 每个 isClickable
楼梯（14级+扶手）	1组
白板（金属框+笔槽）	1个 · isClickable
地毯	1F蓝灰色区域
盆栽（陶罐+绿植球）	4盆
隔断墙	1F 部分高度
迎宾垫	门内

Decision Review

关键决策复盘

决策点	最终选择	淘汰方案	复盘分析
建模方案	模块化组件系统	AI生成模型(Hunyuan/Tripo)	AI模型是单一mesh不可拆解交互。窗户不能打开、门不能点击、工位不能选中。组件系统每个部件独立命名，是可交互3D应用的唯一正确选择。
墙体结构	分段式（留开口）	实心Box + 表面贴片	这是最关键的转折点。实心Box墙挡住了所有窗户和门，耗费大量调试时间。改为分段式后窗户通透、室内可见。
窗框结构	四条边框条	实心Box frame	同理——实心Box的"frame"实际上是不透明白板。改为四条细条后窗户终于透光。
纹理方案	Canvas程序化生成	下载外部PBR纹理	零外部依赖，完全在Claude Code内闭环。质量略低于真实PBR纹理，但可控性和开发效率远超。
光影后处理	简洁自然光（无Bloom）	SSAO + Bloom + 多PointLight	惨痛教训。SSAO拖垮FPS(16fps)，Bloom让白墙发光变"灯箱"，PointLight叠加造成过曝。最终全部去掉，只保留最基础的三点光。
多Agent框架	自建轻量编排器(~300行)	LangGraph.js / Mastra	3D场景需要与渲染循环紧密集成，重框架引入的复杂度不值得。自建的Orchestrator+TaskQueue完全够用。

Lessons Learned

踩坑记录与核心教训

Day 1

环境Splat与程序化建筑视觉冲突

加载雪景街道+山谷 Splat(16MB)后与程序化方块建筑重叠混乱。教训：Splat适合做装饰，不适合做交互环境。

Day 1

SSAO + Bloom 性能崩溃

710 mesh + 半分辨率SSAO + 8个PointLight → 16 FPS。教训：后处理效果要在最后加，不要在开发早期叠加。

Day 2

AI生成模型不可交互

混元3D/Tripo生成的GLB是单一mesh，无法分拆出门窗家具。花了半天走了弯路。教训：交互需求优先于视觉需求。

Day 2

实心Box墙遮挡所有窗户

最难排查的bug——窗户代码正确但完全不可见。根因是墙体Box覆盖了整个窗口区域。改为分段式墙体后解决。

Day 2

窗框/门框白板遮挡

同理——用Box做frame = 实心白板。改为四条边框条后窗户终于透光。此类问题出现了3次才彻底根治。

Day 2

阳台方向反转

阳台栏杆朝建筑内部而非外部。根因是Z轴方向搞混。教训：建筑坐标系必须统一（+Z=前方）。

Day 2

Bloom导致整栋楼发光

白色墙面亮度接近1.0超过Bloom阈值，加上emissive材质，导致整栋楼变成"发光体"。最终方案：彻底移除Bloom。

三条核心教训：

1. 交互 > 美观。 漂亮的AI生成模型不可交互 = 无用。模块化组件虽然朴素，但每个部件可点击、可动画、可替换。

2. 减法 > 加法。 SSAO、Bloom、多PointLight 看起来很酷，堆在一起 = 性能崩溃 + 视觉混乱。最终方案是最简洁的。

3. 实心Box是建筑建模的万恶之源。 用Box做墙/做窗框 = 封死所有开口。分段式/边框条是唯一正确做法。

Completion Status

项目完成度评估

Phase 1 · 技术验证

100%

Phase 2 · 资产管线

85%

Phase 3 · 建筑组件系统

75%

Phase 4 · AI公司引擎

60%

Phase 5 · 流程编排

50%

Phase 6 · 多建筑小镇

15%

Iteration Roadmap

后续迭代与优化方向

🏗️

P0 · 组件工厂 + 快速指令系统

建立 JSON Schema 驱动的建筑生成系统。一条指令 = 一栋完整建筑。

// 快速指令预设表
const presets = {
  "三层科技公司": {
    floors: 3, style: "modern", width: 14, depth: 10,
    facade: "glass_curtain", roof: "flat",
    interior: "open_office",
    agents: ["CEO", "CTO", "Dev×3", "Design", "QA"]
  },
  "街角咖啡店": {
    floors: 1, style: "cottage", width: 8, depth: 6,
    facade: "brick_warm", roof: "gable",
    interior: "cafe",
    agents: ["Barista", "Cashier"]
  },
  "罗马研究院": {
    floors: 2, style: "roman", width: 16, depth: 12,
    facade: "limestone", roof: "pediment",
    interior: "lab",
    agents: ["Director", "Researcher×2", "Analyst", "Writer"]
  }
};

// 一行代码生成
const building = createFromPreset("罗马研究院", { x: 20, z: 0 });

🪟

P0 · 组件模板库扩展

类型	变体
墙面	灰泥 / 砖石 / 玻璃幕墙 / 木板
屋顶	坡顶 / 平顶 / 穹顶 / 锯齿顶
门	单门 / 双门 / 旋转门 / 卷帘门
窗	方窗 / 拱窗 / 落地窗 / 天窗
室内	开放办公 / 隔间 / 会议室 / 服务器房

🎨

P1 · 材质升级路径

方向	方案
外部PBR纹理	ambientCG / PolyHaven 免费CC0
HDR环境图	PolyHaven .hdr 天空贴图
Lightmap烘焙	Blender Cycles → UV2
法线烘焙	高模→低模 normal map

⚡

P1 · 性能优化

措施	预期收益
静态Mesh合并(merge)	Draw calls -60%
LOD系统	远景性能 3×
InstancedMesh扩展	减少100+ mesh
WebGPU迁移(待Spark支持)	渲染2-3×

🤖

P2 · AI能力增强

能力	方案
LLM驱动建筑生成	"三层科技公司" → JSON → 程序化生成
Agent记忆持久化	对话历史存Dexie.js
公司间协作	A公司产出 → B公司输入
3D任务可视化	白板实时Kanban

Quick Reference

开发指令速查表

CLI 命令

命令	说明
`npm run dev`	启动开发服务器
`npm run build`	生产构建
`npm run optimize in out`	glTF 优化管线
`npm run optimize in out --simplify 0.5`	优化 + 简化50%
`npm run blender -- -i in -o out -d 0.5`	Blender 减面+UV

浏览器操作

操作	效果
鼠标拖拽	旋转视角
滚轮缩放	远近调整
右键拖拽	平移画面
双击建筑	进入室内
ESC	退出建筑
单击建筑	显示公司信息

Conclusion

结论与展望

本次技术探索验证了一个关键命题：

纯 Claude Code 编程环境下，使用 Three.js 程序化建模 + 模块化组件设计，可以构建高精度、可交互、可编排的3D智能建筑。

这不是"看起来像3D"的静态渲染，而是每个门可以打开、每个窗户可以操作、每个工位可以点击、每个Agent可以对话的完全交互式3D应用。

下一步的核心方向是组件工厂化 + 快速指令系统——让一条JSON预设 = 一栋完整的AI公司建筑，从而快速铺开整个小镇。

🏛️

3D AI Town · 从一栋建筑开始，建造一个世界

WebGL 交互式智能建筑技术研究报告

摘要

技术栈全景

浏览器运行时

离线资产管线

系统架构

核心成果

单体建筑技术规格

外部组件清单

内部组件清单

关键决策复盘

踩坑记录与核心教训

项目完成度评估

后续迭代与优化方向

开发指令速查表

CLI 命令

浏览器操作

结论与展望