摘要：想用一句自然语言搭建房间，并把 AI 生成的结果继续拖拽、修改、导出吗？ArchAgent 是一个基于 Electron、React、Three.js 和 React Three Fiber 的开源 3D 空间设计智能体。它接入腾讯混元 Hy3、混元生图和混元生 3D，将“聊天、参考图、GLB 资产、可编辑场景、模型导出”串成完整闭环。
适合读者：正在做 Electron 桌面应用、React Three Fiber/Three.js 编辑器、AI Agent、图生 3D，或希望了解 AI 如何安全接入本地创作工具的开发者。
项目地址：https://github.com/xy200303/ArchAgent
开源协议：AGPL-3.0-only
先看效果：ArchAgent 能做什么？
这不是一个只会输出文字的聊天机器人。ArchAgent 把 AI 放进空间设计工作台中，核心能力包括：
• 输入一句需求，创建并迭代房间、墙体、门窗、楼板和家具布局；
• 上传参考图，生成设计预览或提取单件物体，再生成可摆放的 GLB 资产；
• 在 3D 视图直接选中、拖动、绘墙、修改属性，并支持撤销重做；
• 将资产登记到本机构件库，跨项目检索、复用和实例化；
• 导出 GLB、GLTF、OBJ、STL 和可编辑的 scene-json。
一、为什么 AI 空间设计不能只停留在聊天框？
建筑与室内设计场景中，模型给出一段方案说明或一张效果图还不够。设计结果需要继续修改：门窗位置不合理时可以调整，家具资产可以复用，定稿后还能交付给下游工具。
ArchAgent 想解决的正是这个问题：把 AI 的设计决策变为可验证、可编辑、可追溯的三维场景，而不是留在一次性的聊天记录里。对用户来说，AI 不再只是“给建议”，而是成为可以参与建模、资产管理和场景迭代的设计助手。
例如输入：“创建一个 5m × 4m 的卧室：南墙放一扇门和一扇窗，北墙摆放一张双人床和两个床头柜。”
系统会把需求转化为创建墙、门、窗和家具的场景命令；用户可以在 3D 视图继续检查和修改，也可以继续对话调整布局，最后导出 GLB、GLTF、OBJ、STL 或可编辑的 scene-json。
自然语言 / 参考图片 → 设计理解与工具规划 → 场景命令 + 3D 资产
↓
可编辑 3D 场景 → 多格式导出
二、Electron + React Three Fiber 架构：把权限留在桌面端
ArchAgent 使用 Electron 构建桌面应用，并采用 Main / Preload / Renderer 分层：
Renderer：React 工作台、聊天界面、R3F 3D 视图
↓ window.archAgent
Preload：受限 IPC Bridge
↓ IPC
Main：项目、场景、资源、Agent 与模型服务
├─ Hy3 Chat Completions
├─ hy-image-v3.0
└─ hy-3d-3.0
Renderer 专注交互和渲染；Main 进程负责项目持久化、受控文件访问、场景命令执行、模型 API 调用与导入导出；Preload 只暴露明确列出的能力。这样做避免 API Key 进入前端，也避免 Agent 或网页界面获得任意本机路径的访问权限。
层级与技术、职责对应表：
• 桌面容器：Electron + electron-vite，负责窗口、主进程与打包；
• UI：React 19 + TypeScript + Redux Toolkit，负责工作台状态与交互；
• 三维渲染：Three.js + React Three Fiber + Drei，负责场景渲染、相机与编辑交互；
• 场景几何：自定义场景契约、JSCAD、replicad，负责参数化构件与模型交换；
• Agent：pi-coding-agent + OpenAI-compatible API，负责工具规划和多轮对话；
• 模型能力：腾讯混元 Hy3、混元生图、混元生 3D，负责理解需求、生成预览和 GLB 资产。
三、AI Agent 如何安全修改 3D 场景：SceneCommand 设计
项目没有简单地让模型输出一段 JSON，而是定义了一套稳定的场景领域契约。
SceneSnapshot 是唯一可编辑的场景快照，持久化为项目中的 .agent/scene.json；SceneCommand 表示对场景的创建、更新、删除和重新摆放。建筑节点以米为单位，X/Z 表示地面平面，Y 表示高度。
当前节点包括：wall、slab、ceiling、column、zone、stair、fence、door、window、asset。
完整的数据流如下：
用户 / Agent / 编辑器手势 → SceneCommand → Main 进程 SceneService（校验、Reducer、撤销重做、持久化）→ SceneSnapshot → React Three Fiber 负责渲染
这套设计带来三个收益，也是构建 AI 3D 编辑器时最值得复用的经验：
1. 可编辑：AI 创建的墙、门、窗是带参数的领域节点，而不是不可拆分的网格。
2. 可验证：Agent 工具需要读取真实节点 ID 与场景版本，提交的命令还要经过 Reducer 校验。
3. 交互一致：对话、表单修改、绘墙、拖拽和导入资产都走同一条命令通道，避免多套状态相互覆盖。
SceneService 是唯一权威状态，R3F 视图只消费快照并提交操作。这个约束能有效避免 Three 对象、React 状态和项目文件各自修改数据的常见问题。
四、React Three Fiber 3D 编辑器：看得到，也改得动
ArchAgent 使用 Three.js + React Three Fiber 作为唯一 WebGL 渲染路径，并把领域状态和渲染细节分开：
• ArchitectureSceneLayer 将墙、楼板、门窗等语义节点转为 Three 几何；墙体根据门窗开口切分，而不是用贴图伪造。
• ImportedAssetLayer 加载受控项目目录内的 GLB、GLTF、OBJ、STL 模型，并通过包围框反馈选择状态。
• R3FCameraControls 和导航球管理平移、缩放、预设视角与旋转，只保存视图状态。
• WallDrawingOverlay 与拖拽控制器把绘墙、移动构件等手势转为命令预览，再由用户确认提交。
• SceneExportBridge 只导出创作几何，剔除网格、导航球和选中描边等编辑辅助元素。
交互上接近 CAD/BIM：点击构件选中，长按拖动可在地面吸附预览，绘墙按 0.25 米网格吸附，并支持自由、顶视、正视和右视等预设相机。
一个重要原则是：渲染层不能直接修改场景快照。R3F 负责把快照投影为画面，并将手势翻译成命令；真正的校验、历史记录和持久化仍由 Main 进程负责。
五、混元 AI 多模型闭环：从参考图到可复用 GLB 资产
不同模型能力被分配到合适的环节：
• 对话与规划：Hy3 Chat Completions，作用是理解需求、查看场景、选择工具、生成场景命令；
• 图像处理：hy-image-v3.0，作用是生成设计预览，或从复杂图中提取干净的单物体参考图；
• 3D 资产生成：hy-3d-3.0，作用是根据文本或单件参考图生成 GLB 并登记到构件库。
针对户型图、平面图和复杂实景图，系统不会直接触发昂贵的 3D 生成，而是先执行重建确认流程：
资料分析 → 资产检索 / 单件拆分计划 → 必答项 → 用户确认 → 并行生成或复用资产 → 逐件摆放
这一流程将“整间房”的模糊需求拆成适合图生 3D 的单件资产，并在生成前展示假设、待确认问题、可复用资产和待生成资产，降低无效调用与返工。生成后的资产进入本机构件库，同类资产可以生成一次、在多个场景中以不同变换重复实例化。
六、多模态资源系统：让 Agent 看懂文件但不泄露路径
用户上传文件、Agent 生成文件和派生文件在 ArchAgent 中统一登记为 SessionResource，对外只使用稳定的 resource_id，真实路径仅保存在 Main 进程。
资源会记录类型、来源、父资源、状态和确认状态。例如，从室内照片裁剪出的沙发图会保留原始照片的父资源关系；后续生成的 GLB 与导出结果也可以继续追溯。
不同资源按类型转换后再进入模型上下文：
• 图片以多模态图像块提供；
• PDF、DOCX、Markdown 返回相关文本片段，必要时渲染关键页；
• CSV、JSON、数据库只提供 schema、样本、统计或受限查询结果；
• GLB、OBJ、STL 返回预览图和模型元数据，而不是传入二进制数据。
它既能控制 token 与像素预算，也确保模型看不到绝对路径、密钥或未经授权的本地文件。
七、Electron 安全实践：让 AI Agent 有能力，但不越权
桌面 Agent 比普通网页更需要权限约束。ArchAgent 的几个边界包括：
• HY3_API_KEY 仅由 Electron Main 进程加载和使用；
• Renderer 通过 preload 暴露的 window.archAgent 调用明确列出的 IPC 能力，不启用 Node 集成；
• 项目、附件和会话资源由 Main 进程统一管理，Agent 工具不接受任意本机路径；
• exec_bash 默认关闭；即使开启，也应限定可信任务、用途与预期产物；
• Agent 不直接修改 Three 对象或项目 JSON，所有场景改动都经过命令校验。
这些约束不是功能限制，而是让“AI 修改三维场景”可控、可审计的基础。
八、3 分钟运行 ArchAgent：本地开发与验证
在 Windows PowerShell 中执行：
npm install
Copy-Item .env.example .env.local
npm run dev
然后至少配置以下参数：
HY3_API_KEY=你的密钥
HY3_BASE_URL=https://tokenhub.tencentmaas.com/v1
HY3_CHAT_MODEL=hy3
完整体验需要通过 Electron 启动，直接在浏览器打开 Renderer 页面无法使用 preload IPC、项目文件、会话资源和场景服务。提交前建议运行：
npm run typecheck
npm test
git diff --check
九、写在最后：AI 3D 应用的工程化关键
ArchAgent 解决的不是“如何让 AI 画一张效果图”，而是“如何让 AI 的设计决策成为可继续工作的三维资产”。项目用 SceneCommand 连接 Agent 和编辑器，用 R3F 承担统一 3D 视图，用资源系统管理多模态输入输出，并用 Electron 的进程隔离守住密钥、文件和执行权限。
如果你也在探索“Agent + 三维编辑器”，建议优先建立这样一条原则：不要让模型直接管理渲染对象，而要让它提交可验证的领域命令。这会让智能化能力真正进入可维护的工程流程。
后续可以继续完善参数化建筑构件、PBR 材质和贴图、变换操控器、捕捉对齐、实例化与 LOD，并将户型图理解、图生图、图生 3D 和场景布局发展为更完整、可审计的设计工作流。
项目源码已开源：https://github.com/xy200303/ArchAgent。如果这篇文章对你有帮助，欢迎点赞、收藏并关注；也欢迎 Star 项目，或在评论区交流你在 Electron、Three.js、React Three Fiber 或 AI Agent 项目中遇到的问题。
原文地址:https://blog.csdn.net/m0_73370855/article/details/163034561