项目地址: https://github.com/xiangechen/chili3d
在线体验: https://chili3d.com/(Cloudflare 部署:https://chili3d.pages.dev)
许可证: AGPL-3.0
包管理器: npm workspaces(根
package.json版本0.7.1;npm 上仅@chili3d/core已发布0.7.0,其余@chili3d/*为工作区包,截至 2026-10)版本: 0.7.1(GitHub tag
0.7.1,2026-09-19)
概述
Chili3D 主要特性:
- 纯前端 CAD:基于 Three.js + 自研
chili-wasm(Emscripten 直接绑定 Open CASCADE,源码在仓库cpp/,不是 opencascade.js) - 参数化建模:草图、特征树、捕捉与追踪(对象捕捉 / 工作平面捕捉 / 轴追踪 / 特征点识别)
- 基础几何:立方体、圆柱、圆锥、球、棱锥、环面;2D 直线/圆弧/圆/椭圆/矩形/多边形/贝塞尔
- 构造运算:布尔(并/差/交)、拉伸、旋转、扫掠、放样、偏移曲面与厚实体、线性/圆形阵列、形状检查与修复
- 编辑:倒角、圆角、修剪、打断、分割、缝合、简化、特征移除、子形状操作、复合体炸开
- 测量:角度、长度、长度和 / 面积和 / 体积和
- 数据交换:STEP / IGES / BREP / STL 导入导出,完整撤销重做事务栈
- 插件系统:
plugins/内置 helloworld-js / helloworld-ts / macro / visual-programming 示例,.chiliplugin拖拽安装 - 国际化:内置中/英文,Office 风格 Ribbon
环境准备:本地部署与二次开发
仓库使用 npm workspaces(根目录有 package-lock.json),Node + npm 即可:
git clone https://github.com/xiangechen/chili3d.git
cd chili3d
npm install
npm run dev # rspack dev server,http://localhost:8080
npm run build # 生产构建
npm run test # Rstest + Happy-DOM 全量测试
npm run testc # 带覆盖率
npm run check # Biome lint + 自动修复
npm run format # Biome + clang-format(TS 与 C++)
自研 WASM 模块已随仓库提供(packages/wasm/lib),只有需要改 C++ 绑定时才重新编译:
npm run setup:wasm # 一次性准备 Emscripten/CMake 依赖
npm run build:wasm # cmake --preset release 编译,产物回拷到 wasm 包 lib
Docker 部署(compose.yml 已在仓库根):
docker compose up -d # 构建并在 http://localhost:8080 提供服务
构建产物是静态站点,可直接部署到 Nginx / Cloudflare Pages / GitHub Pages。
在线试用(免安装)
直接打开 https://chili3d.com/:
- 选择「新建」或导入 STEP/IGES/BREP
- 左侧工具栏:Sketch / Box / Cylinder / Sphere / ...
- 右侧属性面板:编辑参数、变换
- 顶部 Ribbon:Boolean / Fillet / Chamfer / Offset / Array
- 文件 → 导出(STEP / IGES / BREP / STL)
核心 API
项目结构
chili3d/
├── cpp/ # chili-wasm:CMake + Emscripten 绑定 Open CASCADE
│ └── src/ # opencascade.cpp / factory.cpp / converter.cpp / shape.cpp / mesher.cpp ...
├── plugins/ # 插件示例(npm workspaces 的一部分)
│ ├── helloworld-js/ helloworld-ts/ macro/ visual-programming/
├── packages/
│ ├── core/ # 模型、命令、应用框架(@chili3d/core)
│ ├── three/ # Three.js 渲染(@chili3d/three)
│ ├── wasm/ # chili-wasm 的 TS 封装(@chili3d/wasm)
│ ├── builder/ # 拉伸/旋转/扫掠/放样等特征构建器(@chili3d/builder)
│ ├── element/ # Web Components 控件(@chili3d/element)
│ ├── parametric/ # 参数化功能定义
│ ├── ui/ # UI 组件
│ ├── web/ # 主 Web 应用(@chili3d/web)
│ ├── app/ # 应用入口(@chili3d/app)
│ ├── storage/ # 项目存储
│ ├── i18n/ # 国际化
│ └── ai/ # AI 助手集成(@chili3d/ai,依赖 @anthropic-ai/sdk 与 openai)
├── rspack.config.ts # 打包与 dev server
├── rstest.config.ts # 测试(rstest + happy-dom)
└── biome.json # lint / format(4 空格、110 列、双引号)
二次开发的正确姿势
Chili3D 是应用 + 插件模型,不是可 npm install 的嵌入式 SDK:@chili3d/* 中只有 @chili3d/core 发布到了 npm(0.7.0),web/wasm/app/builder 等仍是工作区包。因此二次开发有两条路:
- 写插件(推荐):在
plugins/下建包,导出Plugin对象,npm run package产出.chiliplugin,拖拽进应用安装。 - 改源码:fork 仓库,在
packages/*内扩展(npm run build会同时构建应用与plugins/)。
整站嵌入自有系统时可用 iframe,但 WASM 依赖 SharedArrayBuffer,宿主站点必须返回 COOP/COEP 头:
<iframe src="https://chili3d.com/" allow="cross-origin-isolated"
style="width:100%;height:100vh;border:0"></iframe>
需配置
Cross-Origin-Opener-Policy: same-origin与Cross-Origin-Embedder-Policy: require-corp(或本地 dev server 已是 cross-origin isolated)。
命令系统
命令是 ICommand 实现类,用 command() 装饰器注册到 CommandStore;元数据是 CommandData(key / icon / toggle / helpText / helpUrl / isApplicationCommand):
import { command, type I18nKeys, type IApplication, type ICommand, PubSub } from '@chili3d/core';
@command({
key: 'demo.hello' as any, // key 属于 CommandKeys 联合类型
icon: { type: 'path', value: 'icons/hello.svg' }, // 也可传 svg/png/url 或字符串
helpText: 'demo.hello.description' as any,
})
export class HelloWorldCommand implements ICommand {
async execute(application: IApplication): Promise<void> {
// 应用级通知走 PubSub 默认实例,文案 key 交给 i18n
PubSub.default.pub('showToast', 'demo.hello.message' as I18nKeys);
}
}
IApplication 暴露 mainWindow dataExchange visualFactory shapeProvider services storage views documents pluginManager lastCommand executingCommand activeView,以及 newDocument(name) / openDocument(id) / loadDocument(data) / loadFileFromUrl(url)。需要中途取消的命令继承 CancelableCommand(实现 ICancelableCommand,带 cancel() 与 disposeStack)。
插件契约(Plugin)
@chili3d/core 的 Plugin 类型是声明式的:把命令、Ribbon、i18n、服务与「AI 手册章节」一次性交给框架。
// plugins/my-plugin/src/index.ts
import type { CommandKeys, Plugin } from '@chili3d/core';
import { MyCommand } from './commands/my';
const MyPlugin: Plugin = {
commands: [MyCommand],
ribbons: [
{
tabName: 'ribbon.tab.manager',
groups: [{ groupName: 'ribbon.group.other', items: ['demo.hello' as CommandKeys] }],
},
],
// 追加到 AI 助手读取的应用手册,让助手知道按钮做什么
guide: [{ name: 'My Plugin', content: 'The “My” button …' }],
i18nResources: [
{ language: 'zh-CN', display: '简体中文', translation: { 'command.demo.hello': 'TS 插件' } },
],
};
export default MyPlugin;
配套文件:manifest.json(name / version / main: dist/main.js / engines.chili3d: ">=0.6" / importmap)与 importmap.json(插件运行时外部模块映射)。
直接调用几何内核
@chili3d/wasm 提供 initWasm():浏览器里由 Emscripten 自己取 .wasm,Node(如 MCP 服务与集成测试)需传入 wasmBinary:
import { initWasm } from '@chili3d/wasm';
// 浏览器
const wasm = await initWasm();
// Node:需要把二进制读出来
// const wasm = await initWasm({ wasmBinary: fs.readFileSync('packages/wasm/lib/chili-wasm.wasm') });
// wasm 上挂的是 OCCT 暴露出来的 BRep* / Geom* 类,构造结果再交给 @chili3d/wasm 的
// converter / factory / shapeProvider 转成 Chili3D 的 shape 与可视对象
@chili3d/wasm 的导出面:initWasm(wasm.ts)、converter、factory、shapeProvider,另有 geometry / shape / surface / curve / stlWriter 等内部模块;C++ 侧入口是 cpp/src/opencascade.cpp。
文件 I/O
- 项目文件:应用内保存为 Chili3D 自有 JSON 文档(
IStorage+Serialized),支持完整撤销/重做 - 导入:File → Import → STEP / IGES / BREP / STL
- 导出:File → Export → STEP / IGES / BREP / STL
- 插件包:
.chiliplugin(拖拽安装)
渲染层(@chili3d/three)
渲染包内是 threeView.ts / threeGeometry.ts / threeGeometryFactory.ts / threeHelper.ts / threeHighlighter.ts / materials.ts / meshExporter.ts / cameraController.ts / threeAnnotation.ts / outlinePass.js,负责把 shape 转成 three 几何、高亮、剖面、导出与相机控制。改材质与高亮行为从这里入手,命令与文档逻辑保持在 @chili3d/core,不要把 OCCT 调用写进 UI 层。
典型工作流
输入:2D 草图轮廓或 STEP/IGES 文件;输出:STEP/STL 模型或 .chiliplugin 插件包。
工作流一:在线参数化建模与导出
- 打开 https://chili3d.com/ 或本地部署实例
- 新建项目,使用 Sketch 工具绘制 2D 轮廓
- 通过 Extrude/Revolve 将草图转为 3D 实体
- 添加圆角、倒角等修饰特征
- 使用布尔运算(Union/Cut/Intersect)组合多个实体
- 导出为 STEP/STL 用于下游加工或 3D 打印
工作流二:开发一个插件并装入应用
- 复制
plugins/helloworld-ts作骨架(manifest.json+importmap.json+src/index.ts+src/commands/) - 用
@command({ key, icon, helpText })定义命令类,实现ICommand.execute(application) - 在
Plugin对象里声明commands/ribbons/i18nResources/guide npm install && npm run build && npm run package产出.chiliplugin- 打开 Chili3D,把
.chiliplugin拖进窗口 → Ribbon 出现按钮,点击执行 npm run test与npm run check通过后提交(Biome:4 空格、110 列、双引号)
适用场景
- 适合:教育、Web 演示、轻量 3D 建模、插件化定制、浏览器内 STEP/IGES 查看与转换
- 不适合:大型工业装配、需要严格约束求解的参数化家族建模(仍推荐 FreeCAD / 桌面 OCCT 应用)
性能要点
- WASM 内核走
SharedArrayBuffer,未启用 COOP/COEP 时退化为单线程 - 大模型先压缩 STEP,导入后转 BREP 缓存
- 渲染端关注
@chili3d/three的几何转换与高亮开销,避免每帧重建 BRep 网格 - 频繁布尔运算放在命令内一次性提交,减少撤销栈与网格重生成次数
- 浏览器内存有限,STEP 源文件建议控制在百 MB 以内,超出部分服务端处理
常见问题
| 问题 | 解决 |
|---|---|
| 加载 chili-wasm 失败 | 站点未启用 COOP/COEP;确认响应头与 cross-origin-isolated |
Node 里 initWasm() 取不到 wasm |
浏览器外的环境需显式传 wasmBinary(Emscripten 无法 fetch) |
| 无法导入 DWG | 目前不支持 DWG,先转 DXF/STEP |
| 中文菜单 | 在语言设置中切换中文(内置 zh-CN 资源) |
| 构建慢或内存溢出 | 用 npm run build(rspack 生产构建);确认未跑 dev 模式产物 |
| 插件不出现按钮 | 检查 manifest.json 的 main 路径、importmap.json 映射,以及 Ribbon items 是否为已注册命令 key |
| 改 C++ 绑定后无效果 | 需要 npm run setup:wasm + npm run build:wasm,产物才会回拷到 wasm 包 lib |
AI 使用建议
- 推荐工作流模式:区分「在线建模(引导 GUI 操作)」与「插件开发(TypeScript 写命令)」。插件路径优先复用
plugins/helloworld-ts骨架,按Plugin契约声明能力,不要臆造应用级启动 API。 - 关键注意事项:① COOP/COEP 与
SharedArrayBuffer是运行前提;② WASM 首次加载较慢,需要进度反馈;③ 命令key属于CommandKeys联合类型,新增命令要同步 i18n key;④ 浏览器内存有限,大模型应服务端预处理。 - 常用代码模式:
@command(...)定义命令 →application.activeView/application.documents操作当前文档 →PubSub.default.pub('showToast', key)通知 → 几何构造经@chili3d/wasm的 factory/converter 得到 shape →@chili3d/core的 visual 层显示。
相关技能
- astral3d — Web 3D 可视化与数字孪生框架(glTF/IFC 展示侧):../astral3d/SKILL.md
- occt — 桌面 C++ 几何内核(chili-wasm 绑定的同一内核):../occt/SKILL.md
- freecad — 桌面参数化 CAD(同样基于 OCCT):../freecad/SKILL.md
- openscad — 脚本化 CSG 建模(代码建模范式对照):../openscad/SKILL.md
参考资源
- 仓库:https://github.com/xiangechen/chili3d
- 在线应用:https://chili3d.com/ | Cloudflare 部署:https://chili3d.pages.dev
- 插件示例:仓库
plugins/helloworld-ts、plugins/helloworld-js - 中文教程(znlgis):https://znlgis.github.io/cad/chili3d/