# SolidWorks Skill + MCP

**AI Skill + MCP toolkit for reliable desktop CAD automation.**

让 Codex、Claude、Cursor 等 Agent 通过自然语言调用真实 CAD 软件，并对执行结果进行验证与追踪。

> Tool success is not treated as task success.

工具调用成功，不代表任务真的完成；需要 Review 的任务会经过结果验证后再交付。

当前主产品版本为 **v2.1.0**：默认交付 Agent Skill ZIP 与标准 MCPB，不要求安装桌面程序。CAD Studio 是独立版本、可选发布的图形界面渠道。下载入口和升级说明见 [v2.1.0 发布说明](docs/releases/v2.1.0.md)。

可选的 CAD Studio 会对各生产执行器统一检查交付文件是否为本轮新增或内容已变化；旧文件拒绝交付，证据不足转为待复核。扫描范围、兼容性与验证方法见[本轮交付门禁](references/delivery-freshness.md)。

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![GitHub Release](https://img.shields.io/github/v/release/dreamchaseryuan/solidworks-skill-mcp)](https://github.com/dreamchaseryuan/solidworks-skill-mcp/releases)
[![GitHub Stars](https://img.shields.io/github/stars/dreamchaseryuan/solidworks-skill-mcp?style=flat)](https://github.com/dreamchaseryuan/solidworks-skill-mcp)
[![MCP](https://img.shields.io/badge/MCP-stdio--server-blue)](mcp-server/README.md)
[![Skill + MCP CI](https://github.com/dreamchaseryuan/solidworks-skill-mcp/actions/workflows/skill-mcp-release.yml/badge.svg)](https://github.com/dreamchaseryuan/solidworks-skill-mcp/actions/workflows/skill-mcp-release.yml)

```text
User → Agent (Codex / Claude / Cursor) → Skill / MCP → Execution Core → CAD → Artifacts + Evidence
```

AI 负责理解意图、查证 API、规划步骤；Execution Core 保证执行过程可追踪、可验证、失败可恢复。

---

## See It In Action

<p align="center">
  <img src="assets/showcase/solidworks-engineering-drawing-demo.gif" alt="代码驱动 SolidWorks 生成复杂测试件与 GB/T 工程图" width="900">
</p>

一个真实流程：自然语言需求 → Agent 调用 Skill → SolidWorks 生成原生 `SLDPRT + SLDDRW` → 导出 PDF → 自动复核尺寸与证据。

| 案例 | 能力 | 状态 |
|---|---|---|
| [M6×1 真实螺纹孔](subskills/solidworks-threaded-holes/README.md) | Metric Tap Thread，重建后回读 | `verified` |
| [CNC 多圆角/倒角安装座](subskills/solidworks-fillet-chamfer-cnc/README.md) | 语义选边、可变半径、face/full-round/setback | `stable` |
| [标准渐开线直齿轮](references/gears.md) | 模数/齿数/压力角驱动实体 | `pilot` |

---

## Prerequisites

| 项 | 要求 | 检查方法 |
|---|---|---|
| 操作系统 | Windows 10/11 x64 | 原生 `SLDPRT` / `SLDASM` / `SLDDRW` 依赖 SolidWorks COM，其他系统仅可用开放格式能力 |
| Python | 3.10+（本机真机验收使用 3.12） | `python -V` |
| Node.js | 20+（工作台、MCP 注册与 Skill 安装器） | `node -v` |
| Git | 任意较新版本（安装器通过 `git clone` / `git pull` 获取与更新仓库） | `git --version` |
| SolidWorks | 2024 或 2026，需合法许可 | `python scripts/cad_doctor.py` |
| AutoCAD | 可选，仅 DWG/DXF 子技能需要 | — |

安装 Python 依赖：

```powershell
python -m pip install -r requirements.txt
# 只有开放格式（OCCT）能力才需要：
python -m pip install -r requirements-occt.txt
```

只读环境自检（不会打开或关闭 CAD）：

```powershell
python scripts/cad_doctor.py           # 发现的安装路径、版本、COM 注册状态
python scripts/sw_capability_probe.py  # 类型库与能力清单
```

模板与材料库**默认自动探测**，不需要写死路径。只有非标准安装位置才需要
[`config/runtime.example.json`](config/runtime.example.json) 与 `SOLIDWORKS_TYPELIB_DIRS`，
见 [`config/README.md`](config/README.md)。

---

## Quick Start

**Skill + MCP 是主产品**，二者任选其一即可；CAD Studio 是第三个可选桌面渠道，不参与核心发布门禁。

### Option 1 — Skill

```powershell
npx github:dreamchaseryuan/solidworks-skill-mcp --target claude
```

该命令获取本仓库并执行根目录的 `install.js`（`package.json` 的 `bin` 入口）。

**默认行为（安全优先，2026-10-28 起）**：

- 只装到**已经存在** skills 目录的客户端（`.agents` / `.claude` / `.codex` / `.cursor` / `.openclaw`）；
  一个都没检测到时**不会替你创建目录**，而是提示改用 `--target` 显式指定。
- 目标目录已存在但**不是本仓库的 git 检出**（手动放置、解压、或其他来源）时，
  **拒绝安装且不删除任何文件**。
- 由本仓库安装的目录用 `git pull --ff-only` 更新；无法快进时**只报告，不删除**。
- 默认自动安装 Python 依赖；Windows 上没有 Python 3.10+ 时尝试使用 winget 为当前用户安装 Python 3.12。失败时给出提示；`--no-install-deps` 可关闭此行为。
- 非 Windows 平台默认拒绝（SolidWorks COM 不可用）；确需使用开放格式能力加 `--allow-non-windows`。

| 参数 | 作用 |
|---|---|
| `--target claude,codex` | 装到指定客户端；`all` 表示全部支持项 |
| `--dry-run` | 只打印将要执行的动作，不写盘 |
| `--install-deps` | 安装 `requirements.txt` + `mcp-server/requirements.txt`（默认） |
| `--no-install-deps` | 不自动安装 Python 和 Python 依赖 |
| `--no-register-mcp` | 跳过 MCP 配置注册（默认注册，覆盖前自动备份 `.bak-<时间戳>`） |
| `--force-reinstall` | 旧目录先改名为 `.bak-<时间戳>` 再重装（**不删除**） |

安装使用 `git clone --depth 1`，只取工作树、不拉完整历史。仓库完整工作树约 13 MB，
其中 `apps/`（桌面端源码，约 6 MB）与 Skill 运行无关。
若 `npx` 在当前网络环境不可用，改用下方 Option 2 的克隆方式，再执行 `node install.js`。

### Option 2 — MCP

支持 MCP Bundle 的客户端可直接从 [GitHub Releases](https://github.com/dreamchaseryuan/solidworks-skill-mcp/releases) 导入
`SolidWorks-Automation-Skill-2.1.0.mcpb`；该包同时提供标准版与 Smithery 版。

```powershell
git clone https://github.com/dreamchaseryuan/solidworks-skill-mcp.git
cd solidworks-skill-mcp
python -m pip install -r requirements.txt -r mcp-server/requirements.txt
node mcp-server/register_all_ai_mcp.js --help          # 查看全部参数
node mcp-server/register_all_ai_mcp.js --clients codex,claude-code,cursor
```

注册脚本会写入对应客户端的 MCP 配置，并在写入前生成 `.bak` 备份；加 `--strict` 可让任一客户端失败时非零退出。

### Option 3 — Optional CAD Studio Desktop

从 [GitHub Releases](https://github.com/dreamchaseryuan/solidworks-skill-mcp/releases) 下载 Windows 安装包。

桌面端启动本地执行器时，如果 Windows 没有可用的 Python 3.10+，会尝试通过 winget 为当前用户安装 Python 3.12；无法安装时显示错误。环境诊断仍只读。SolidWorks 必须由用户另行安装并具备许可；API 查证所需的 7-Zip、Python 包和可验证的本地 API Help 按需自动配置，详情见 [`references/api-lookup.md`](references/api-lookup.md)。

> **Start with Skill or MCP. Install the desktop app only when you need a GUI.**

| 层级 | 入口 | 适合谁 | 需要 GUI | 典型用法 |
|---|---|---|---|---|
| 主产品 | **Skill** | 支持 skill 导入的 Agent 客户端 | 否 | 自然语言驱动 SolidWorks |
| 主产品 | **MCP** | Codex / Claude / Cursor / Windsurf 等 MCP 客户端 | 否 | MCPB 导入或命令行注册，Agent 自动 Tool Calling |
| 可选桌面端 | **CAD Studio** | 需要图形界面管理项目/任务/预览/交付 | 是 | 桌面端提交任务；独立构建与发布 |

Skill 与 MCP 共用同一套能力清单（`capabilities.yaml`）、脚本与证据系统，是默认安装路径。CAD Studio 只是可选的 GUI 封装，不会阻塞 Skill/MCP 独立发版，也不要求所有用户承担 WebView2、Python 环境、签名和 Windows 安装包维护成本。安装后可用 `python scripts/cad_doctor.py` 做环境诊断；桌面端细节见 [`docs/CAD_STUDIO_USER_MANUAL.md`](docs/CAD_STUDIO_USER_MANUAL.md)。

---

## Why This Project

LLM 会规划，但常见的 AI CAD 自动化有几个真实问题：

- LLM 会规划，但不会真正操作桌面 CAD 软件
- Tool 返回 `success` 不代表任务真的完成
- CAD API 版本、环境、Backend 差异复杂
- 固定 Tool 集合覆盖不完所有工程需求
- Agent 执行过程通常不可追踪、不可审计

本项目的解法：

| 问题 | 方案 |
|---|---|
| 自然语言 → 真实操作 | Skill / MCP 接入真实 COM 与后端 |
| Tool success ≠ Task success | Verification-first completion |
| Backend 失败 | Backend Router + Recovery Decision |
| 能力缺失 | Capability Gap → 交还 Agent 查证 |
| 执行不可追踪 | 结构化 Trace |
| 是否可靠 | Golden Workflow Eval |

---

## Architecture

```text
User / Agent
  ↓
Skill / MCP
  ↓
Execution Core（Capability · Verification · Recovery Decision · Trace）
  ↓
Backend Router
  ↓
Python COM / C# / OCCT
  ↓
CAD Software
  ↓
Artifacts + Evidence
```

- **Root Skill** = 通用能力、规则与执行基础设施（连接、建模、审查、MCP）。
- **Subskills** = 专项领域工作流（工程图、螺纹孔、CNC 圆角、VibeCAD、AutoCAD），由 Root Skill 按需调用，不需要用户手动启动。
- **Execution Core** = 内部可靠执行层：统一状态、结果验证、失败恢复决策与执行追踪。它是内部实现，**不是独立服务、不需要用户启动**。
- **Capability Gap** = 找不到能力时结构化返回 `CAPABILITY_GAP`，交还 Agent 查证，而不是「做不了」：

  ```text
  Existing Tools → Tool Composition → Backend Fallback → Capability Gap
    → Agent 查 references / 官方 API / SDK → 最小实现 → Verification
  ```

  Execution Core 自身**不会自动联网执行未知代码**。

详细：[`docs/architecture/execution-core.md`](docs/architecture/execution-core.md)

---

## Reliability

当前附带 **43 个 deterministic reliability scenarios**（12 nominal + 31 robustness），
覆盖正常执行、故障注入、后端回退、能力缺口与策略门禁；由 `golden-workflows.yaml` 的 12 个 workflow 派生。

| Metric | Current baseline |
|---|---|
| Nominal workflow | 12/12 first-pass（baseline v4，warning 归 guardrail，等待人工复核） |
| Injected false-completion cases | all detected |
| Escaped false completion | 0 in current deterministic benchmark |
| Regression suite | 当前方案 B 验证记录见 [可靠性修复与验收](docs/architecture/scheme-b-reliability.md) |

> 这是 **deterministic engineering benchmark**（Fake Handler/Reviewer + 故障注入），
> 不是生产 SLA 或真实用户成功率。详见 [`docs/architecture/v2-evaluation.md`](docs/architecture/v2-evaluation.md)。

### 验证边界（Verification Boundary）

本项目的验证分三层，**结论不能跨层套用**：

| 层 | 在哪里跑 | 覆盖什么 | 不覆盖什么 |
|---|---|---|---|
| L1 离线回归 | 任意机器 | `pytest`（全量，当前 1728 项）、`evals/runner.py`（12 workflow / 43 scenario）、治理单测（当前 93 项） | 需要 SolidWorks / AutoCAD 进程的一切 |
| L2 托管 CI | GitHub 托管 `windows-2022` | Skill/MCP 主产品由 `skill-mcp-release.yml` 验证并执行 `test-and-build` 必需检查；可选桌面端由 `windows-release.yml` 手动构建 | 真实 CAD 执行 |
| L3 真实 CAD 验收 | **仅维护者本机**（Windows 11 + SolidWorks 2026 SP01.1） | Golden 五轮真机、装配/工程图/运动算例等真机回归 | 其它机器、其它版本 |

必须明确的三点：

1. **远端不存在 CAD 真机执行证据。** 仓库没有自托管 Runner，`Windows CAD Regression` 工作流为手动触发、
   **不是必需检查**，当前无法执行。任何"远程 CAD CI 已通过"的表述都是错的。
2. **本机通过 ≠ 跨机器通过。** 换一台机器请按 `Prerequisites` 与 `docs/CAD_STUDIO_USER_MANUAL.md` 重新自检，
   不要直接引用维护者的验收结论。
3. **L2 通过 ≠ 治理闭环。** 必需检查只保护 `main`；指向特性分支的 PR（含 stacked PR）不受该规则约束。

原生 SolidWorks 操作当前以 **2026** 为支持与验收目标。方案 B 保留现有执行架构，修复失败状态、原生阵列、草图可编辑性和文档归属，并提供可选 HTTP 与可验证的产物取回。

**完整模式暴露 69 个命名工具；默认发现模式只暴露 3 个检索入口**（`sw_search_tools` /
`sw_describe_tool` / `sw_call_tool`）。原有命名工具保持兼容；发现模式
按需检索；写操作经过策略检查，审批行为与信任边界取决于配置。模式切换、审批与回滚见
[`mcp-server/README.md`](mcp-server/README.md)。

---

## Capabilities & Status

| Category | 你能做什么 | 状态 |
|---|---|---|
| Modeling | 零件建模、草图/拉伸/旋转、齿轮、钣金、焊件 | `verified` + `pilot` |
| Assembly | 装配、Mate、干涉检查、爆炸视图 | `verified` |
| Drawing | GB/T 工程图、尺寸链、孔表、BOM | `verified` + `pilot` |
| Export | STEP / STL / IGES / PDF / DXF / DWG | `verified` |
| Motion | 运动算例、旋转马达、结果门禁 | `pilot` |
| Design Audit | 中性文档设计规则、基线对比、丝杠/皮带电机扭矩初筛 | `pilot` |
| Drilling Panel | 面板孔位识别、基准及图纸规格候选 | `pilot` |
| Tolerances | 已显示尺寸公差只读提取，CSV 输出 | `pilot` |
| Rename Preview / Copy | 属性改名预览；受限独立零件和单配置嵌套装配复制到新名称 | `pilot` |
| Sprocket | 近似链轮几何演示实体，非生产齿形 | `pilot` |
| Spring | 开放端等螺距圆线弹簧实体 | `pilot` |
| FEA | CalculiX 线性/非线性求解编排与审计 | `pilot` |
| DFM / Routing | 制造复核、路由复核 | `pilot` |
| Surface / Mold | 受限 Loft/Sweep/Thicken、模具计划 | `pilot` |
| AutoCAD | DWG/DXF 二维绘图、图层/标注/预览 | `verified` / `pilot` / `blocked` |
| Open-format | OCCT 无头写入 STEP/BREP/STL/OBJ/GLB 等 | `verified` |

状态等级（`capabilities.yaml` 定义）：

| Status | 含义 |
|---|---|
| `verified` | 真机验证完成，可按已知范围使用 |
| `stable` | 长期回归覆盖 |
| `pilot` | 已实现但仍需人工复核 |
| `blocked` | 当前环境或能力不允许自动交付 |

真机基线：SolidWorks 2024 / 2026、AutoCAD 2024。未验证能力不会被包装成无人值守交付。

- 完整能力矩阵（每个能力的精确等级/版本/限制）→ [`capabilities.yaml`](capabilities.yaml)
- 领域工作流 → [`subskills/`](subskills/) · [`SUBSKILLS.md`](SUBSKILLS.md)

---

## No SolidWorks Installed?

没有 SolidWorks 时，部分开放格式任务仍可完成：

`STEP · IGES · BREP · STL · OBJ · GLB · DXF · SVG · PDF · PNG`

（通过 OCCT/OCP 隔离进程真实写入。）

但原生 `SLDPRT / SLDASM / SLDDRW` 仍需要合法 SolidWorks 环境。

---

## Examples

[`examples/`](examples/) 目录包含从基础零件到装配、工程图、Motion、FEA 的可运行示例。

---

## Documentation

| Topic | Link |
|---|---|
| MCP Setup | [`mcp-server/README.md`](mcp-server/README.md) |
| CAD Studio | [`docs/CAD_STUDIO_USER_MANUAL.md`](docs/CAD_STUDIO_USER_MANUAL.md) |
| Architecture | [`docs/architecture/execution-core.md`](docs/architecture/execution-core.md) |
| Reliability Eval | [`docs/architecture/v2-evaluation.md`](docs/architecture/v2-evaluation.md) |
| Capability Matrix | [`capabilities.yaml`](capabilities.yaml) |
| Subskills | [`SUBSKILLS.md`](SUBSKILLS.md) |
| API / Backend | [`references/`](references/) |
| Design audit / drive sizing | [`references/design-rule-check.md`](references/design-rule-check.md) · [`references/drive-sizing.md`](references/drive-sizing.md) |
| Drilling panel analysis | [`subskills/solidworks-engineering-drawing/references/drilling-panel-gdt.md`](subskills/solidworks-engineering-drawing/references/drilling-panel-gdt.md) |
| Native GD&T / structured drawing generation (SW2026 pilot) | [`subskills/solidworks-engineering-drawing/references/native-gdt.md`](subskills/solidworks-engineering-drawing/references/native-gdt.md) |
| Common datums / projected zones / extended GD&T (SW2026 pilot) | [`subskills/solidworks-engineering-drawing/references/gdt-extended-options.md`](subskills/solidworks-engineering-drawing/references/gdt-extended-options.md) |
| Tolerance extraction | [`references/tolerance-extraction.md`](references/tolerance-extraction.md) |
| Rename preview | [`references/rename-preview.md`](references/rename-preview.md) |
| Approximate sprocket | [`references/sprocket.md`](references/sprocket.md) |
| Open helical spring | [`references/spring.md`](references/spring.md) |
| Troubleshooting | [`references/troubleshooting.md`](references/troubleshooting.md) |

---

## Roadmap & Contributing

**Roadmap**：更广的真机验证 · 更可靠的能力路由 · 更好的 CAD Studio 可观测性 · 更多 verified 子技能 · 社区贡献工作流。

**Contributing**：新增能力时，先查 `capabilities.yaml`，优先复用现有 backend，新增 tests + evidence，不要把未验证 capability 标为 `verified`。详见 [`CONTRIBUTING.md`](CONTRIBUTING.md)。

---

## License & Community

[MIT](LICENSE) · [Code of Conduct](CODE_OF_CONDUCT.md) · [GitHub Issues](https://github.com/dreamchaseryuan/solidworks-skill-mcp/issues) · [Star History](https://star-history.com/#dreamchaseryuan/solidworks-skill-mcp&Date)

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=dreamchaseryuan/solidworks-skill-mcp&amp;type=Date&amp;theme=dark">
  <img src="https://api.star-history.com/svg?repos=dreamchaseryuan/solidworks-skill-mcp&amp;type=Date" alt="SolidWorks Skill + MCP 星标趋势" width="960">
</picture>

---

## English

**SolidWorks Skill + MCP** is an AI Skill + MCP toolkit for reliable desktop CAD automation. Codex, Claude, Cursor, and other agents drive real SolidWorks / CAD workflows through natural language, with verification, deterministic recovery decisions, and execution tracing. **Skill and MCP are the primary products.** CAD Studio is an optional, independently versioned desktop GUI and does not block the core release.

---

<sub>关注抖音 @balance. · 嵌入式开发、SolidWorks 自动化和 AI 辅助工程实践持续更新</sub>

### 装配干涉检查 API

`solidworks_interference_check` 使用 `IAssemblyDoc.InterferenceDetectionManager`，
通过 `GetInterferences()` 计算并读取 `IInterference.Components` 和体积，最后调用
`Done()`。隐藏实体和已忽略结果参与检查；同一个多实体零件内部的相交不计入。
计算失败、计数读取失败、数组数量不一致或结束检查失败均返回 `blocked`，不会误报零干涉。
抑制组件不参与计算；零结果仍需核对组件解析状态和设计意图。
离线回归覆盖调用顺序、失败处理和 SI 体积换算（26 项通过）。
SOLIDWORKS 2026 SP4.1（34.4.1）、Python 3.10 上已通过 MCP 实测正常返回；
该真机样例为零干涉，非零结果读取仍以离线回归为证据。