kernelCAD

来源范围：此仓库包含可复用的 CAD 运行时、CLI、MCP 工具和无头渲染器。托管产品 UI 和商业制造服务由其他项目单独维护。使用 npm run build 构建可复用工具；使用 npm run dev 启动独立渲染器。

kernelCAD - 面向 Agent 的 CAD 运行时

kernelCAD 可将机械设计意图转化为可编辑的 .kcad.ts 源码、 确定性的审查证据，以及可导出的制造工件。

核心循环以源码为先：设计简述 -> 可编辑的 .kcad.ts -> 已评估模型 -> 确定性验证 -> 指导式修订 -> 导出包。

kernelCAD 并不打算成为 Fusion、Onshape 或 SolidWorks 的浏览器克隆。 Replicad/OpenCASCADE 是内核层。kernelCAD 是内核之上的 Agent 优先工作流 层：确定性 CAD 源码、特征历史、诊断、验证、变体和人工审查。

安装

已在 ChatGPT 和 Claude 中提供：无需安装

kernelCAD 可作为已连接的应用在 ChatGPT（Apps SDK，支持在聊天中使用 Studio 查看器和绘制审查）以及 Claude / claude.ai（自定义连接器）中运行。从聊天 设置中添加并登录：

• ChatGPT：连接指南 或 ChatGPT → 设置 → 连接器
• Claude：连接指南 或 claude.ai → 设置 → 连接器，URL https://mcp.kernelcad.com/mcp

所有平台使用同一个账户。 以下编码 Agent 插件使用相同的托管 服务（https://mcp.kernelcad.com/mcp）和相同的 kernelCAD 登录信息。在 Claude Code、 Codex、Cursor、Gemini 或 Grok 中保存的模型，可通过同一个 Studio 分享链接（/p/<slug>）打开；你在 ChatGPT 或 Claude 中也会看到该链接。请在每个 客户端中使用同一个账户登录。

询问你的 Agent：“查看 kernelcad.com 并安装 mcp”。 面向 Agent 的安装说明涵盖 托管设置、本地 CLI 设置和连接验证。

本地 CLI：一行命令

适用于 Node.js 用户（Node.js 22.12 或更高版本）：

npm install --global kernelcad

如需包含 Node.js 的独立安装，Linux 和 macOS 用户可运行：

curl -fsSL https://kernelcad.com/install.sh | sh

在 Windows PowerShell 中运行：

irm https://kernelcad.com/install.ps1 | iex

直接安装程序会下载平台归档文件，验证其 SHA-256 校验和， 并将其安装到用户主目录下。要固定版本，可在 Linux/macOS 上设置 KERNELCAD_VERSION=vX.Y.Z，或在 PowerShell 中设置 $env:KERNELCAD_VERSION='vX.Y.Z'。 提供适用于 Linux x64/ARM64、macOS Intel/Apple Silicon 和 Windows x64 的构建版本。直接安装无需单独安装 Node.js。

编码 Agent：一条命令

一条命令即可将你的 Agent 连接到托管的 kernelCAD MCP 服务 （https://mcp.kernelcad.com/mcp），并添加 kernelCAD 技能。无需在本地运行任何内容， 也无需安装 OpenCASCADE。可匿名使用；如需使用账户功能，请通过客户端的 OAuth 提示登录。

Agent	一键命令
Claude Code	claude plugin install kernelcad --marketplace w1ne/kernelCAD-web
Codex	codex plugin marketplace add w1ne/kernelCAD-web && codex plugin add kernelcad@kernelcad
Cursor	将 kernelCAD MCP 添加到 Cursor（仅 MCP）
Gemini CLI	gemini extensions install https://github.com/w1ne/kernelCAD-web --consent --auto-update
Grok Build	grok plugin marketplace add w1ne/kernelCAD-web && grok plugin install kernelcad --trust
VS Code / Copilot	code --add-mcp '{"name":"kernelcad","type":"http","url":"https://mcp.kernelcad.com/mcp"}'
仅安装技能（任何 Agent）	npx skills add w1ne/kernelCAD-web

在 Claude Code 中，你也可以输入 /plugin marketplace add w1ne/kernelCAD-web ，然后输入 /plugin install kernelcad@kernelcad。安装后请重启应用。 Claude Desktop、ChatGPT、Windsurf、Cline、Zed、Continue，以及更新、卸载和 Cursor 技能安装说明，请参阅 docs/usage/agent-plugin-install.md。

展示

下面每个模型都从所示的自然语言提示词开始。AI Agent 通过 kernelCAD 自带的创作循环（CLI / MCP）编写模型：撰写 .kcad.ts 源码、运行 evaluate、渲染七视图检查图、查看渲染结果、修正问题并重复此过程。这些都不是一次性生成的。 showcase/ 中的每个文件夹都包含参数化源文件、转台 GIF（kernelcad animate --turntable，发布视图），以及一则简短说明，介绍要观察的内容和已运行的检查。

模型	提示词	参数	预览
扭转六边形花瓶	中空外壳，高约 150 mm，从 70 mm 渐缩至 50 mm，六边形截面扭转 120°，壁厚 2 mm，底部封闭	height baseDia mouthDia twistDeg wall
滚花控制旋钮	Ø40 × 22 mm，菱形滚花握持部，凸起指针，6 mm D 形轴孔，M3 紧定螺钉孔	diameter height knurlDepth knurlTwistDeg knurlTeeth shaftDia dFlatDepth boreDepth skirtHeight
蜂窝支架	带圆角的 L 形支架，含生成式六边形格栅	thickness innerFillet cellSize web
NACA 2412 机翼	根据 NACA 方程生成的真实翼型，渐缩放样	semiSpan rootChord tipChord leSweep dihedralRise washoutDeg
锥齿轮传动	90° 啮合锥齿轮副	gearDeg pinionTeeth gearTeeth
离心叶轮	7 个后弯掠叶片	bladeCount wrapDeg backplateThickness boreDia keyWidth
行星齿轮级	太阳轮、行星轮、齿圈、行星架	carrierDeg sunTeeth planetTeeth planetCount
9 缸星形发动机	圆形曲轴箱，九个带散热片的星形排列气缸，圆顶缸盖，螺旋桨轮毂	cylinderCount barrelLength

有些检查不止是看图：

• 经过检查而非仅仅绘制的机构。 行星齿轮级和锥齿轮传动是带有转动配合、由齿数决定的齿轮比，以及已声明齿轮副传动的装配体。kernelCAD 的机构真实性检查（evaluate_script → mechanism: "real"）会在应用传动耦合的情况下，让每个机构在其运动范围内转动，并检查齿轮是否重叠。kernelcad validate --include-interference 确认这两个装配体均无问题。
• 制造证据。 蜂窝支架声明了 FDM 打印门槛。kernelcad dfm 检查通过（最薄壁厚 2.0 mm，无无支撑悬垂），而 kernelcad export step 会写出 B-rep，随后可用 kernelcad inspect step 读取孔的信息。

理念

1. Agent 优先：主要接口是 .kcad.ts、CLI 和 MCP。UI 用于审查和调整生成的设计。
2. 可编辑源文件：几何体是确定性的源代码，包含明确的特征历史、参数、装配体和诊断信息。
3. 以验证为中心：实用的 CAD 输出需要通过确定性审查，检查约束、硬件适配、间隙和可导出性。
4. 工作流优先于基本图元：产品进展以意图级工作流衡量，而不是以复制每个传统 CAD 按钮为准。

参考零件精度

无头 OCCT 门槛会将 27 个原生 .kcad.ts 参考零件与解析计算或记录的 OCCT 体积、表面积和边界框数值进行核对。目前的关键指标是 25/27 个参考零件匹配；预期通过门槛为 25/25，另有两个已记录的已知失败项及其原因，详见评分卡。请参阅参考零件评分卡及其本地验证演示。

Agent 工作流

对于 Agent 和贡献者，.kcad.ts 源文件是设计的唯一事实来源。渲染的 PNG/MP4 文件、STEP/STL 导出文件、评分 JSON 和捕获运行元数据均为生成的证据或交付物。提示词说明、源文件和来源元数据仍属于源文件。先修改源文件，再重新生成明确指定的目标；除非有意重建演示或发布包，否则应避免大范围刷新生成产物。

在进行视觉判断前，先运行确定性检查：

kernelcad evaluate model.kcad.ts
# then run review_cad from an MCP client connected through `kernelcad mcp`
kernelcad export step model.kcad.ts -o model.step
kernelcad export stl model.kcad.ts -o model.stl

将从 SolidWorks 或其他 CAD 应用导出的 STEP 装配体转换为 KernelCAD 项目：

kernelcad import-step robot.step --out robot-kcad
kernelcad evaluate robot-kcad/robot.kcad.ts

该包包含一个 .kcad.ts 根装配体、一个 manifest.json（记录源产品路径、单位、放置位置、颜色和几何测量值），以及按几何内容寻址的精确原生 OCCT BREP 资源。字节完全相同的产品定义会共用一个资源。原始 STEP 装配层级记录在清单中；当前的 KernelCAD 场景则会展平为可独立放置的实例。系统会递归读取本地 STEP DOCUMENT_FILE 依赖项，将其纳入导入来源哈希，并要求这些依赖项位于输入目录内。组件颜色会保留；此导入不支持逐面颜色映射。系统不会推断配合关系、关节、运动、特征历史，也不会读取原生 SolidWorks/Parasolid 数据。 请参阅保留的导入演示、资源包和验证证据。

生成渲染产物后，应检查图像或视频本身，并报告可见内容：比例、接口、悬空几何体、遮挡、摄像机取景，以及必需特征是否清晰可辨。测试通过不能替代视觉证据。

需要视觉证据时，请保留确定性的检查包：

kernelcad render inspect model.kcad.ts model.inspect

v1 包会写入清单和规范化 RGB 视图。它还可以输出机器可读的 mask、depth 和 normals 通道：

kernelcad render inspect model.kcad.ts model.inspect --channels rgb,mask,depth,normals

如果需要单独审查某个特定特征 ID 或装配体部件，请使用 --focus <names> 或 --hide <names>。将更丰富的通道保留在同一个清单数据包中；不要替换规范化 RGB 视图。

对于真实硬件，请优先使用 lib.fromSTEP(...) 获取目录或供应商提供的几何体，而不是使用虚假的占位方块或圆柱体。这样，安装座、间隙和机构检查才能基于实际部件进行。

功能

• 无头核心：无需 DOM，即可在 Node.js 或 Web Workers 中运行 CAD 操作。
• Agent API：kernelCAD API 支持参数、装配体、NURBS、SDF 实体、钣金工作流、内省和反馈循环。
• 审查驾驶舱：基于浏览器的 3D 预览，可用于检查生成的设计和验证结果。
• 标准导出：生成 STEP/STL 文件。
• 稳健内核：基于 OpenCASCADE 构建；在仍使用 Replicad 的地方，将其作为内核实现细节。

开始使用

npm install --global kernelcad

npm 包要求 Node.js 22.12 或更高版本。若要进行独立安装， 请使用上方的平台安装程序。

将以下内容放入 bracket.kcad.ts：

const w = param('Width', 60, { unit: 'mm' });
const h = param('Height', 40, { unit: 'mm' });
const t = param('Thickness', 5, { unit: 'mm' });

const base = box(w, h, t);
const hole = cylinder(t + 2, 4).translate(w / 2, h / 2, -1);
return base.subtract(hole).fillet(1);

运行：

kernelcad evaluate bracket.kcad.ts
kernelcad export stl bracket.kcad.ts -o bracket.stl

就是这么简单。对于 Agent：kernelcad mcp 会运行一个 MCP 服务，其中包含动态模型自省工具。对象工具响应除了序列化 JSON 文本外，还会包含 structuredContent，以便 MCP 客户端验证已声明的输出架构。 请参阅 SKILL.md（随安装包附带），了解完整的 API 功能和编写指南。

与 Claude Desktop 搭配使用

kernelCAD 作为 MCP 服务运行，因此 Claude Desktop 可以在本地驱动它。完成单行安装后，在 Claude Desktop 配置文件中添加一项：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "kernelcad": {
      "command": "kernelcad",
      "args": ["mcp"]
    }
  }
}

重启 Claude Desktop。kernelCAD MCP 工具（review_cad、模型自省、导出辅助工具等）会显示在工具列表中。

首次在本地完整运行 evaluate_script 构建时，会返回 viewerUrl。在 Studio 中打开一次：之后的完整构建和源代码编辑工具调用都会在同一个会话链接后替换源代码、历史记录和几何体。查看器由 MCP 进程在 127.0.0.1 上提供服务，并会一直运行到该进程关闭；它不是公开分享链接。试运行不会更改查看器。构建失败时，仍会显示上次构建的模型；构建成功但 DFM 检查失败的模型仍可查看。此处显示的构建诊断并非完整的 CAD／物理审查。

已发布的软件包包含 Studio 包。在检出版本中运行 MCP 时， 请先运行 npm run build:mcp-viewer。如果无法提供该包，构建结果会将 viewerError 与 CAD 诊断分开列出。托管 MCP 和 --cloud 仍会使用网关的 Studio／项目 URL。

本地查看器工作流。

对于托管工作流，请在现有连接指南中登录。 其中提供了适用于你客户端的当前连接器和 OAuth 步骤。托管工具集取决于身份验证、所选配置文件和服务端原生工具； 请通过已连接服务的发现功能获取工具，而不要假设其与本地列表相同。

本地安装程序现已可用。应用前可预览配置更改：

kernelcad install --claude-desktop --dry-run
kernelcad install --claude-desktop

其他托管设置指南：ChatGPT、 Claude、 Claude Code、 Codex、 Gemini CLI、 Grok Build、 Cursor，以及 VS Code。

浏览生成的本地 MCP 工具参考，了解完整的输入／输出架构和行为注释；也可在设计指南中搜索现有方案和注明来源及日期的制造目录快照。

对于本地 Studio， get_selection 和 set_selection 可与 MCP Agent 共享面／边选取。请在 Studio 中打开同一脚本并使用其会话令牌；模型重建后，选取将失效。

有关可选内核选择和回退诊断，请参阅 实验性受保护 SMLib 内核指南及其 工作流演示包。

参与贡献

面向希望修改内核或可视化调试器的贡献者：Web 应用和开发工作流（克隆仓库、npm install、npm run dev）：

git clone https://github.com/w1ne/kernelCAD-web.git
cd kernelCAD-web
npm install
npm run dev          # web visual debugger at localhost:5173
npm run build:cli    # build the CLI bundle into dist/cli/
npm run test         # full vitest suite
npm run qc           # quick quality gate (lint + typecheck + tests)

署名

导出的文件会在其元数据字段中标注 kernelCAD（STEP FILE_NAME、GLB asset.generator、STL 标头、DXF 或 XML 注释），公开查看器页面会显示一个较小的“Made with kernelCAD”链接。可自托管用户和分支项目可在 src/shared/links/attribution.ts 中修改此项。请参阅 ATTRIBUTION.md。

许可证

MIT — 请参阅 LICENSE。kernelCAD 名称受商标政策保护。