SolidWorks Automation Skill

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.1。CAD Studio 展示工程阶段验收项，工作台和对话中的明确改动会标记受影响的旧结果。技能 ZIP、MCPB、CAD Studio 安装版与便携版使用同版运行时。下载和升级见 v2.1.1 发布说明。

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

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

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

See It In Action

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

Related MCP server: SolidWorks Automation Skill

Prerequisites

安装 Python 依赖：

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

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

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

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

Quick Start

三种入口任选其一即可，不需要同时启动。

Option 1 — Skill

npx github:wzyn20051216/solidworks-automation-skill --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。

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

Option 2 — MCP

支持 MCPB 的 Windows 桌面客户端可导入发布页的标准 .mcpb 扩展。若当前发行尚未附带该文件，也可从 Git 检出构建。首次安装、uv 准备和构建方法见 MCPB 扩展说明。

git clone https://github.com/wzyn20051216/solidworks-automation-skill.git
cd solidworks-automation-skill
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 — CAD Studio 桌面版

从 GitHub Releases 下载 Windows 安装包。

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

Choose one entry point. You do not need to run all three.

三者是平级入口，共用同一套能力清单（capabilities.yaml）、脚本与证据系统。安装后可用 python scripts/cad_doctor.py 做环境诊断；详细安装与 CLI 见 docs/CAD_STUDIO_USER_MANUAL.md。

Why This Project

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

• LLM 会规划，但不会真正操作桌面 CAD 软件

• Tool 返回 success 不代表任务真的完成

• CAD API 版本、环境、Backend 差异复杂

• 固定 Tool 集合覆盖不完所有工程需求

• Agent 执行过程通常不可追踪、不可审计

本项目的解法：

Architecture

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 查证，而不是「做不了」：

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

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

详细：docs/architecture/execution-core.md

Reliability

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

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

验证边界（Verification Boundary）

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

必须明确的三点：

1. 远端不存在 CAD 真机执行证据。 仓库没有自托管 Runner，Windows CAD Regression 工作流为手动触发、 不是必需检查，当前无法执行。任何"远程 CAD CI 已通过"的表述都是错的。

2. 本机通过 ≠ 跨机器通过。 换一台机器请按 Prerequisites 与 docs/CAD_STUDIO_USER_MANUAL.md 重新自检， 不要直接引用维护者的验收结论。

3. L2 通过 ≠ 治理闭环。 必需检查只保护 main；指向特性分支的 PR（含 stacked PR）不受该规则约束。

近期原生 SolidWorks 回归以 2026 SP1.1 为基线，部分能力另有 2024 真机记录。以 能力清单 中对应能力的 verified_versions、等级和限制为准；未列出的版本需单独验证。环境诊断只检查安装和运行条件，工程功能按实际任务验收。

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

Capabilities & Status

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

SolidWorks 按上述能力清单核对。AutoCAD 真机证据覆盖对应的 2024 能力；试点功能保留人工复核。

• 完整能力矩阵（每个能力的精确等级/版本/限制）→ capabilities.yaml

• 领域工作流 → subskills/ · SUBSKILLS.md

No SolidWorks Installed?

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

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

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

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

Examples

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

Documentation

Roadmap & Contributing

Roadmap（详见 docs/ROADMAP.md：原理演示类 skill、电机扭矩 / 气缸选型核验等）：更广的真机验证 · 更可靠的能力路由 · 更好的 CAD Studio 可观测性 · 更多 verified 子技能 · 社区贡献工作流。

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

License & Community

MIT · GitHub Issues · Star History

贡献者 / Contributors

• @balance.（原作者，抖音）：嵌入式开发、SolidWorks 自动化和 AI 辅助工程实践

• SolidWorks API 文档 · pywin32 · 所有提交 Issue / PR 的贡献者

English

SolidWorks Automation Skill 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. Three peer entry points — Skill, MCP, and CAD Studio — share one capability registry (capabilities.yaml). Choose one; no extra runtime service is required. See Quick Start above.

装配干涉检查 API

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