Amagine3D

从硬件需求到可编辑的 3D 设计

Amagine3D 是 Amagine 面向硬件创造开发的开源 3D 能力层。
输入产品描述和参考图，再补充关键尺寸，Amagine3D 就能围绕内部器件完成外壳和装配结构，并输出可继续编辑的源码。STEP、STL 和 3MF 可按任务导出。

能力 · 案例 · 快速开始 · English

Apache 2.0 Node.js 22.19.0+ Vite 7.3.6 build123d + OCP

Amagine3D 生成的 BUSY Bar 外壳旋转展示

## 从需求到可编辑的硬件结构 Amagine3D 目前聚焦可打印的智能硬件外壳及相关结构，可以从自然语言、参考图片、尺寸与已有几何出发，建立完整设计。 设计会从内部元器件出发安排安装位和接口，再完成外壳、控制件与散热结构。需要分件时，盖体、铰链或卡扣会连同装配间隙和打印公差一起进入设计。对于铰链或滑盖这样的刚性结构，系统还可以沿设定的运动路径检查碰撞与运行间隙。 每次生成都会记录同一份语义场景，其中包含零件、特征、接口、材料和 BRep 主数据。制造几何保留可编辑 Python 与 build123d 源码，并导出真实 STEP。产品外包络优先用少量关键截面放样，其他结构按需采用拉伸、旋转、扫掠和 BRep 特征；能够保留预期外形的直纹放样或分段曲面也适用。相同几何会生成 STL、显示用 GLB，以及按打印机 profile 验证的 3MF 包，并支持一个物理零件内部的永久颜色分区。 在背后，3D-native Agent 会先把需求整理为不可变 intent，再建立唯一的可变语义场景。BRep 与颜色导出器把该场景编译为同一种证据协议。Agent 会读取实测尺寸、特征归属、壁厚、打印方向、铺盘、连接、干涉和导出文件回读结果，并在接受候选版本前渲染和读取最新模型。通过外、内放样做差得到的空腔仍需检验实际壁厚，截面内缩本身不保证三维法向等厚。 对于外观主导且没有用户参考图的请求，工作流会引导 Agent 在允许联网时寻找并实际查看少量相关图片，记录来源和可观察的比例、形体关系，先用主形体预览对照，再细化结构。工程尺寸仍以元器件图纸或明确的假设为依据。 ## 案例：BUSY Bar 桌面设备外壳 上方 GIF 展示的是 Amagine3D 参考 [BUSY Bar](https://busy.app/) 公开产品信息生成的一套桌面设备外壳。BUSY Bar 是一款用于显示自定义状态的效率多功能设备，内置番茄钟和应用，支持全面自定义、开源，并对开发者和硬件爱好者友好。Amagine3D 为它生成了可拆分外壳：正面留出显示区，顶部布置实体控制件，内部则按器件与接口安排空间。 Agent 先根据参考图确定显示区和控制件的位置，再围绕内部器件完成外壳分件。决定外观与装配的关键尺寸都保留为可编辑参数，可以在生成后继续调整。 这次生成产出了完整的 build123d 源码、STEP、STL 和检查报告。工作台可以继续预览、测量和修改模型；参数变化会写回源码并重新构建几何，整个结果也会随项目保存。 设计参考：[BUSY Bar 官方网站](https://busy.app/)。 ## 3D-native Agent Amagine3D 将 3D-native Agent 定义为一套以三维设计状态为核心的 Agent 架构。三维设计状态记录当前版本中各个零件的几何及其空间关系。Agent 的下一步动作由这个状态决定，执行结果也会写回其中。 ```text 用户需求与物理约束 │ ▼ 已接受的 3D 设计状态 │ 创建候选版本 ▼ ┌── 自主内环 ───────┐ │ 读取模型 → 规划修改 │ │ ↑ ↓ │ │ 分析结果 ← 执行检查 │ └────────┬───────────┘ │ 检查通过 ▼ 提交为新的设计版本 │ ▼ 保存状态并生成产物 ``` 在这套架构中，一次设计任务包含两个层级。自主内环负责产生候选设计，提交环节负责判断这个候选能否成为新的正式版本。两者分开运行，使 Agent 可以反复尝试，同时不破坏已经通过检查的设计。 自主内环的每一轮都从当前设计状态开始。Agent 先读取零件之间的空间关系，再决定需要修改的结构。修改后的模型会在真实几何环境中执行，系统直接测量生成结果，并检查装配干涉、运动路径和导出文件。检查结果会返回给 Agent。如果某项要求没有满足，Agent 会根据具体的测量值定位问题，修改受影响的部分，然后开始下一轮。这个过程使用的是实际生成的几何，而不是模型对结果的文字判断。 当候选设计满足当前任务的检查条件后，它才会进入提交环节。系统会把候选结果与用户约束和上一版设计进行比较。检查通过后，候选设计会被保存为新的基线，源码和制造文件也随之归档；如果修改引入了新的问题，系统会保留上一版结果，并让 Agent 继续修正。所有候选改动都保留在隔离的会话工作区内。 当前版本已经把语义场景作为这份设计状态。它记录物理零件、特征归属、接口、材料、BRep 主数据与产物绑定，同时保持原始 intent 不变。放样外壳与机械结构都以有效 BRep 实体作为制造零件。导出器输出同一种 build report，并明确记录 semantic 到 print 坐标系的刚性变换；显示与打印网格均从制造几何派生。 ## Beyond CAD CAD 是 Amagine3D 的起点。完整的硬件创造还需要理解现实中的器件、空间关系和已有资产，让不同来源的 3D 信息在设计与制造之间持续流动。 Amagine3D 会继续丰富这份共同 3D 上下文中的器件语义：让系统知道一个模型代表屏幕、电池、PCB 还是连接器，理解它如何安装、需要避让什么、会影响哪些开孔和外壳尺寸，并在器件变化时更新相关结构。 未来的输入可以在参考图片与元器件几何之外扩展到网格、扫描和点云，为可编辑 CAD 提供尺度、外形特征与空间关系。当前生成工作流聚焦 BRep 建模及经过验证的制造输出。 这套 3D 状态会继续延伸到制造。几何修复、壁厚、尺度、打印方向、支撑和制造文件不再是设计结束后的独立步骤，而会成为 Agent 推进硬件项目的一部分。 我们的目标，是让一个硬件构思可以从参考图、真实元器件和空间约束开始，在同一个 3D 设计过程中生长为能够装配和制造的产品。 ## 快速开始 ### 环境要求 - Node.js 22.19.0 或更新版本 - Python 3.10 至 3.13 - npm - 现代桌面浏览器 - OpenAI Responses 兼容的 API 密钥或模型网关 初始化脚本会在仓库内创建 `.venv`，并安装锁定版本的 build123d、 OCP、Manifold、trimesh 和 lib3mf。宿主电脑不需要安装桌面 CAD 软件。 ### 安装并运行 ```bash git clone https://github.com/amagine-ai/Amagine3D.git cd Amagine3D npm install cp .env.example .env npm run dev ``` 配置 `.env` 后打开 `http://127.0.0.1:6160`。本地 API 默认监听 `http://127.0.0.1:6161`。首次启动会准备 `.venv`；依赖指纹没有变化时， 后续启动会直接复用。`npm install` 也会安装 SDK 使用的当前平台 Codex runtime，用户不需要另行全局安装 Codex。 ### 服务端配置 ```dotenv LLM_API_KEY=... LLM_MODEL=openai/gpt-5.5 LLM_BASE_URL=https://gateway.example.com/v1 LLM_API_TYPE=openai-responses LLM_THINKING_LEVEL=medium CODEX_WEB_SEARCH_ENABLED=true PORT=6161 WEB_PORT=6160 AGENT_RUN_IDLE_TIMEOUT_MS=1800000 AGENT_RUN_HARD_TIMEOUT_MS=7200000 ``` 这些值只由本地 Express 服务端读取。对应 `LLM_*` 未配置时，也会复用已有的 `CODEX_API_KEY`/`OPENAI_API_KEY` 与 `OPENAI_BASE_URL`。Codex 原生实时搜索与工作区网络访问 默认开启，无需独立搜索服务密钥。只能在服务端环境中设置 `CODEX_WEB_SEARCH_ENABLED=false` 关闭；前端没有开关，对话请求中的字段也不能覆盖此配置。修改后需重启服务。 配置已开启不代表供应商的搜索、原图获取或图像感知能力已验证：健康接口仅报告搜索配置与 `untested` 验证状态，不会自动调用供应商。请勿通过客户端环境变量暴露 API 密钥，也不要提交 `.env`。 每轮使用 `workspace-write` 与 `approvalPolicy: never`：Codex 可以在当前会话的 执行目录中直接工作，无需用户反复点击确认；目录外写入仍由沙箱拦截。命令进程只获得 精简后的 shell 环境，类似密钥的变量会被移除。连续无活动超时由原生 Codex 事件刷新， 整轮硬超时则是独立的绝对安全上限。 ## 系统架构 `React/Vite 界面 -> Express API -> Codex SDK/runtime -> 隔离工作区 -> a3d/Python CAD` ```text Amagine3D/ ├── src/ │ ├── components/cad-workbench/ 对话、文件、预览、参数和存储面板 │ ├── components/CadViewer.tsx Three.js 模型查看与交互 │ ├── lib/ 流式 API 客户端及产物、会话辅助逻辑 │ └── App.tsx, types.ts 应用外壳与前后端共用协议 ├── server/ │ ├── routes/ Agent 对话流与会话、产物 API │ ├── artifacts*.ts, sessions.ts 产物发现、打包、回收与会话持久化 │ ├── uploads.ts 经校验的图片输入 │ └── app.ts, index.ts Express 启动、静态托管与运行时组装 ├── packages/a3d-runtime/ │ └── src/ Codex 适配、稳定事件、沙箱与运行监督 ├── bin/a3d 会话安全的 CAD 命令行 ├── skills/ │ └── text-a3d/ 精简 CAD 指引与语义场景编译器 │ └── color/BACKEND.md 内部颜色分区、材料与 3MF 后端 ├── bundled-projects/ 工作台内置的只读示例项目 ├── workspace/sessions// 生成的源码、模型、报告和预览图 ├── .amagine-state/ Agent 会话、上传文件和本地运行状态 ├── scripts/ Python 环境安装与许可证检查 └── tests/ 服务端、运行时、产物与 UI 逻辑测试 ``` 私有 `@amagine3d/a3d-runtime` package 为每个产品会话启动或恢复一个原生 Codex 线程，并把 SDK 事件转换成稳定的应用契约。Express 服务端负责产品会话持久化，再将 这些事件流式传给工作台，本身不再导入 Codex SDK 类型。产品层只增加精简的 `AGENTS.md` 指引与 `text-a3d` Skill。`a3d` 命令包装已有的 Python 编译、校验、 打包与渲染入口；由 Codex 自主决定何时调用，不再运行服务端自定义修复状态机。 每个会话拥有独立工作区和 Codex 状态目录。可编辑源码、制造文件、报告与预览都保留 在该目录，浏览器通过 Three.js 渲染生成模型。更完整的设计见 [威胁模型](./threat-model.zh-CN.md) 和 [安全上报](./SECURITY.zh-CN.md)。 ## 项目状态 Amagine3D 正在持续迭代。当前公开版本聚焦可单色或多色打印的 BRep 几何，以关键截面控制的放样外包络结合参数化机械结构。曲面连续性可以较粗，同时保留有效实体、可编辑源码、真实 STEP 和制造检查。完整工作流已在 Chrome 与 Edge 桌面浏览器中测试。 ## 参与贡献 欢迎提交范围清楚的 issue 和 pull request。提交改动前请阅读 [CONTRIBUTING.zh-CN.md](./CONTRIBUTING.zh-CN.md)，并运行仓库检查： ```bash npm run typecheck npm test npm run build ``` 安全问题请按照 [SECURITY.zh-CN.md](./SECURITY.zh-CN.md) 中的私密流程上报。 ## 核心依赖与致谢 Amagine3D 建立在以下开源项目之上： | 项目 | 用途 | | --------------------------------------------------------------------------------------------------------- | ---------------------- | | [build123d](https://github.com/gumyr/build123d) | 参数化 CAD 建模 | | [Open CASCADE Technology](https://dev.opencascade.org/) 与 [CadQuery OCP](https://github.com/CadQuery/OCP) | 精确几何内核与 Python 绑定 | | [Three.js](https://github.com/mrdoob/three.js) | 3D 预览、选择与测量 | | [trimesh](https://github.com/mikedh/trimesh) | mesh 处理与检查 | | [Manifold](https://github.com/elalish/manifold) | 派生网格的布尔检查 | | [lib3mf](https://github.com/3MFConsortium/lib3mf) | 3MF 写入与回读 | | [OpenAI Codex](https://github.com/openai/codex) | Agent 线程、工作区执行与流式事件 | 应用运行后可通过 `/licenses` 查看许可证页面。仓库内的许可证文本和生产 npm 依赖清单位于 [`public/licenses/`](../public/licenses/)。源码仓库的分发边界与 第三方署名说明见 [`THIRD_PARTY_NOTICES.md`](./THIRD_PARTY_NOTICES.md)。 ## 许可证 Amagine3D 采用 [Apache License 2.0](../LICENSE)。 Copyright 2026 [amagine-ai](https://github.com/amagine-ai)。详见 [NOTICE](../NOTICE)。