solidworks-automation
"SolidWorks CAD 自动化技能,优先覆盖经验证的零件、孔槽、装配、工程图、导出和交付复核;所有能力等级以 capabilities.yaml 为准,未验证能力必须走人工复核。"
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/wzyn20051216/solidworks-automation-skill with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/wzyn20051216/solidworks-automation-skill'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/wzyn20051216--solidworks-automation-skill)HTML
<a href="/listings/wzyn20051216--solidworks-automation-skill"><img src="/api/listings/wzyn20051216--solidworks-automation-skill/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
三种入口**任选其一**即可,不需要同时启动。
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`。
| 参数 | 作用 | |---|---| | `--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
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](https://github.com/wzyn20051216/solidworks-automation-skill/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)。
> **Choose one entry point. You do not need to run all three.**
| 入口 | 适合谁 | 需要 GUI | 典型用法 | |---|---|---|---| | **Skill** | 支持 skill 导入的 Agent 客户端 | 否 | 自然语言驱动 SolidWorks | | **MCP** | Codex / Claude / Cursor / Windsurf 等 MCP 客户端 | 否 | Agent 自动 Tool Calling | | **CAD Studio** | 需要图形界面管理项目/任务/预览/交付 | 是 | 桌面端提交任务 |
三者是**平级入口**,共用同一套能力清单(`capabilities.yaml`)、脚本与证据系统。安装后可用 `python scripts/cad_doctor.py` 做环境诊断;详细安装与 CLI 见 [`docs/CAD_STUDIO_USER_MANUAL.md`](docs/CAD_STUDIO_USER_MANUAL.md)。
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 328 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- ---
- name: solidworks-automation
- description: "SolidWorks CAD 自动化技能,优先覆盖经验证的零件、孔槽、装配、工程图、导出和交付复核;所有能力等级以 capabilities.yaml 为准,未验证能力必须走人工复核。"
- metadata: { "openclaw": { "homepage": "https://github.com/wzyn20051216/solidworks-automation-skill", "os": ["win32"], "requires": { "anyBins": ["python", "py"] } } }
- ---
- # SolidWorks 自动化技能
- ## 快速开始
- ### 环境要求
- - Windows 系统;原生 SolidWorks 操作以 SolidWorks 2026 为支持与验收目标,开放格式无头写入不要求安装 CAD 软件
- - Python 3.10+;原生 Windows CAD 自动化另需 `pywin32` / `comtypes`
- - MCP/工具化调用需要 `mcp` / `pydantic`
- - 工程图最终交付审查需要 `PyMuPDF`;它从 SolidWorks 导出 PDF 回读实际尺寸文字边界,已包含在 `requirements.txt`
- - 处理 GLB/GLTF/OBJ/STL 网格参考模型时,可能还需要 `trimesh` / `pygltflib` / `numpy` / `Pillow`
- - 如果通过 OpenClaw 使用,确保技能目录位于 `~/.openclaw/skills/solidworks-automation/` 或 `~/.agents/skills/solidworks-automation/`
- ### 入口自检
- 所有代理在执行 SolidWorks 自动化前,先运行技能自检:
- ```bash
- python SKILL_DIR/scripts/sw_preflight.py
- ```
- 桌面端或 CLI 执行前建议先运行环境诊断:
- ```powershell
- python SKILL_DIR/scripts/cad_studio.py doctor
- ```
- `capabilities.yaml` 是 Skill、MCP、队列和 UI 共用的能力唯一真源。能力等级为 `verified`、`pilot`、`reference_only` 或 `not_implemented`;后两者不得作为无人值守交付。该清单还维护 Python、C# PIA/Add-in、原生 C++、SWBasic、OCCT 和外部求解器的原子操作路由;执行前可用 `python scripts/backend_router.py --list` 查询,规则见 `references/language-backend-routing.md`。
- ### 多入口与多后端
- - CAD Studio 与 Skill/CLI/MCP 是平级入口,共用 Automation Job、NeutralCadDocument、Preview Manifest、Evidence Graph 和能力清单。
- - 检测不到 SolidWorks/AutoCAD 时,只阻断 `SLDPRT/SLDASM/SLDDRW/DWG` 等原生格式;开放格式任务优先路由到 `headless_open_format_writing`。
- - 需要设计规则审查或丝杠/皮带电机扭矩初筛时,读取 `references/design-rule-check.md` 和 `references/drive-sizing.md`,以用户提供或经验证采集的中性文档为输入;缺失证据标为 `review_required`,结果必须由工程师复核。
- - 需要识别钻孔面板孔位或规划图纸候选时,读取 `subskills/solidworks-engineering-drawing/references/drilling-panel-gdt.md`;孔型、基准和公差不得凭几何猜定,候选规格不得冒充已验证工程图。
- - 用户要求基准、复合公差框或 GD&T 自动落图时,读取 `subskills/solidworks-engineering-drawing/references/native-gdt.md`。已有图纸先用 `scripts/sw_gdt_copy.py --source 图纸.slddrw --inspect` 查明目标,再写新副本;从模型新出图使用现有 MCP `solidworks_generate_drawing` 或 `scripts/sw_drawing_package.py`,提供结构化尺寸、基本尺寸、基准及单框/复合框要求。SW2026 保存重开核验原生关联、全部层和基准材料修饰,源文件保留,结果需目视复核;旧自由文字不猜测落图。
- - 公共基准、子基准组、投影公差带、轮廓偏置、CZ/SZ、局部范围和其他高级 GD&T,继续读取 `subskills/solidworks-engineering-drawing/references/gdt-extended-options.md`,通过同一工具提交结构化成员与 `options`;每个成员都须核对,写入后保存重开核验全部新语义。
- - 要提取已保存模型的已显示尺寸公差时,使用 `scripts/sw_tolerance_extract.py`;它只读当前配置,结果不覆盖隐藏尺寸或其他配置,角度、装配和图纸读取仍需验证。
- - 需要按属性批量改名时,先用 `scripts/sw_file_rename.py` 生成只读预览;受限独立零件可用 `scripts/sw_rename_copy.py`,单配置嵌套装配可用 `scripts/sw_assembly_rename.py` 在新目录创建副本并重开核验。源文件及外部使用位置不改;图纸、Toolbox、多配置及其他未验证引用仍受阻断,详见 `references/rename-preview.md`。
- - 需要链轮外观或几何演示时,读取 `references/sprocket.md` 并使用 `scripts/sw_sprocket.py` 在新建空零件中创建近似实体;此模型未验证链条啮合或制造要求,不能作为生产级标准链轮。
- - 需要开放端等螺距圆线弹簧实体时,读取 `references/spring.md` 并使用 `scripts/sw_spring.py`;输入高度是螺旋中心线轴向行程而非实体自由高度,材料、端部和工程性能必须复核。
- - 无头写入使用 `scripts/headless_cad_writer.py`;OCCT/OCP 隔离进程真实写入 STEP、IGES、BREP、STL、OBJ、GLB,二维后端写入 DXF、SVG、PDF、PNG,并生成几何与 SHA-256 证据。
- - DXF 交付会额外生成 `preview_scene`;已有 DXF 可通过 `python scripts/cad_studio.py preview-dxf --input drawing.dxf --output drawing.scene.json` 或 MCP `cadstudio_build_dxf_preview_scene` 转成受限 PreviewScene。该命令只读白名单实体并拒绝覆盖旧文件。
- - OCCT 当前覆盖盒体、圆柱、布尔合并、圆柱孔切除、直纹/受限平滑 Loft、直线/单圆弧 Sweep、闭壳 Knit 和开放面 Thicken;复杂路径、自交偏置或缺少 OCP 运行时时保持 `blocked`。禁止通过改扩展名或空文件伪造支持。
- - `delivery-preview` 只允许显示当前任务真实产物;固定样例必须标记 `demo-showcase` 与 `isDemo: true`,不得进入交付判断。
- 规则:
- 1. 检测到缺少 `comtypes` / `win32com` / `pythoncom` 时,默认执行 `python -m pip install "pywin32>=305" "comtypes>=1.2.0"` 补齐依赖;安装失败时说明原因和手动方法。
- 2. 环境变量 `SW_AUTO_INSTALL_DEPENDENCIES=off` 或 `sw_preflight.py --no-install` 可关闭自动安装。
- 3. 检测不到 SolidWorks 安装或 COM 注册时,停止原生 SolidWorks 操作;若原生格式并非必需且 `fallbackPolicy=allow_open_formats`,继续执行无头开放格式后端,不要把整个任务误标为失败。
- ### Python 依赖提醒
- 按任务最小化安装依赖,不要在普通零件建模时强制安装网格转换库;工程图交付需要标准 `requirements.txt` 中的 PyMuPDF:
- ```powershell
- # 核心 SolidWorks COM 自动化依赖
- python -m pip install -r SKILL_DIR\requirements.txt
- # 仅在需要 GLB/GLTF/OBJ/STL 网格检查、缩放或转换时安装
- python -m pip install -r SKILL_DIR\requirements-mesh.txt
- ```
- 执行涉及 GLB/GLTF/FBX/BLEND 转 OBJ/STL 的任务前,先用 `importlib.util.find_spec()` 检查
- `trimesh`、`pygltflib`、`PIL` 是否可用;缺失时先提示用户需要安装哪些库和用途,再安装或给出手动命令。
- ### 连接 SolidWorks
- ```python
- import sys; sys.path.insert(0, r"SKILL_DIR/scripts")
- from sw_connect import mm
- from sw_part import sketch, sketch_circle, extrude_boss
- from sw_sketch_quality import fully_define_sketch
- from sw_session import SolidWorksSession
- with SolidWorksSession(version=2026) as session:
- model = session.new_part()
- with sketch(model, "Front Plane") as sketch_name:
- sketch_circle(model, 0, 0, mm(25))
- fully_define_sketch(model)
- if extrude_boss(model, sketch_name, mm(50)) is None:
- raise RuntimeError("拉伸失败")
- if not session.save(model, r"C:\temp\cylinder.sldprt"):
- raise RuntimeError("保存失败")
- if not session.export(model, r"C:\temp\cylinder.step"):
- raise RuntimeError("导出失败")
- ```
- > 将 `SKILL_DIR` 替换为此技能的实际安装路径。
- 模型交付要回读草图的约束状态、尺寸与关系,禁止批量 Fix 代替设计参数;保存重开后验证草图被目标特征消费、关键尺寸可改且孔位保持正确。基础圆/矩形可用 `fully_define_sketch()`;复杂草图应明确设计尺寸和关系,再用 `inspect_model_sketches()` 验收,缺证据时保留人工复核。
- 会话上下文只清理本轮登记的文档和确认归属的空实例;达到文档预算时先处理本轮文件。执行标记失败、重建失败、未知检查结果或人工复核尚未完成时,不得宣称任务完成。远程 MCP 通过 `artifact_refs` 取回 PNG 或原始文件并核对 SHA-256,规则见 `mcp-server/README.md`。
- ## 核心工作流
- 根据用户需求选择对应模块:
- | 需求 | 脚本 | 参考文档 |
- |---|---|---|
- | 入口自检与依赖补齐 | `scripts/sw_preflight.py` | `references/troubleshooting.md` |
- | 无 CAD 开放格式写入 | `scripts/headless_cad_writer.py`、`scripts/cad_studio.py write-open-format` | `capabilities.yaml`、公共 CAD Core Schema |
- | 高级能力/类型库探测 | `scripts/sw_capability_probe.py` | `references/complex-mechanical-routing.md` |
- | Python/C#/C++/SWBasic/OCCT 后端选择 | `scripts/backend_router.py` | `references/language-backend-routing.md`、`capabilities.yaml` |
- | C# 进程内 Add-in 宿主、事件与 UI | `scripts/sw_addin_host.ps1`、`scripts/sw_addin_host.py` | `references/solidworks-addin-host.md` |
- | 多模型宏生成防护 | `scripts/sw_macro_guard.py` | `references/openclaw.md` |
- | 友好会话 API | `scripts/sw_session.py` | - |
- | 连接与文档管理 | `scripts/sw_connect.py` | - |
- | 外观与材质 | `scripts/sw_appearance.py` | `references/appearance.md` |
- | 零件建模(草图+特征) | `scripts/sw_part.py` | `references/part-modeling.md` |
- | 标准外啮合直齿轮实体 | `scripts/sw_gear.py` | `references/gears.md` |
- | 盲孔/沉孔/沉头孔/半圆端槽与孔位验收 | `scripts/sw_hole_features.py`、`scripts/sw_review.py` | `references/complex-hole-features.md`、`references/review.md` |
- | 自然语言到参数化设计计划 / VibeCAD | `subskills/solidworks-vibecad/scripts/plan_from_brief.py` | `subskills/solidworks-vibecad/SKILL.md`、`subskills/solidworks-vibecad/README.md` |
- | 多圆角/倒角 CNC 机加工件 | `subskills/solidworks-fillet-chamfer-cnc/scripts/create_cnc_mount_template.py`;高级圆角用 `verify_advanced_fillets.py` | `subskills/solidworks-fillet-chamfer-cnc/SKILL.md`、`subskills/solidworks-fillet-chamfer-cnc/references/cnc-fillet-chamfer-lessons.md` |
- | 螺丝孔/螺纹孔、攻丝底孔 | `subskills/solidworks-threaded-holes/scripts/create_threaded_hole_template.py` | `subskills/solidworks-threaded-holes/SKILL.md`、`subskills/solidworks-threaded-holes/references/threaded-hole-lessons.md` |
- | AutoCAD DWG/DXF 二维绘图、线稿转 CAD、批量改图 | `subskills/autocad-automation/scripts/acad_draw.py`、`subskills/autocad-automation/scripts/acad_review.py` | `subskills/autocad-automation/SKILL.md`、`subskills/autocad-automation/references/troubleshooting.md` |
- | 装配体操作、齿轮联动/铰链/可拖动运动配合 | `scripts/sw_assembly.py` | `references/assembly.md` |
- | Motion Study 运动算例、旋转马达与结果审计 | `scripts/sw_motion.py` | `references/motion-study.md`、`references/complex-mechanical-routing.md` |
- | 工程图出图 | `scripts/sw_drawing.py` | `references/drawing.md` |
- | 文件导出 | `scripts/sw_export.py` | `references/export.md` |
- | 配置族创建/激活、参数修改与自定义属性 | `scripts/sw_document_data.py` | `references/advanced.md` |
- | 装配 BOM CSV 与 Pack and Go | `scripts/sw_delivery.py` | `references/export.md` |
- | OBJ/STL 高还原网格参考导入 | `scripts/sw_import_mesh_reference.py` | `references/mesh-reference-import.md` |
- | 结果自审查 | `scripts/sw_review.py` | `references/review.md` |
- | 语义实体引用 | `scripts/sw_entity_reference.py` | 逐步替代 Face1/Edge1 和屏幕坐标 |
- | DFM 制造风险复核 | `scripts/dfm_review.py`、`scripts/dfm_profiles.py`、`scripts/cad_studio.py check-dfm` | 供应商 profile、B-Rep 证据、机加工、钣金、激光切割、3D 打印和注塑声明型规则检查 |
- | Routing 中性复核与前置 | `scripts/routing_review.py`、`scripts/cad_studio.py check-routing`、`scripts/cad_studio.py routing-preflight` | 端点、分段、长度、弯曲半径、碰撞/间隙、支撑、Routing BOM;原生写入必须等加载项/许可证证据 |
- | FEA 前置、输入与受限求解 | `scripts/fea_analysis.py`、`scripts/fea_convergence.py`、`scripts/cad_studio.py fea-preflight/prepare-fea/run-fea/run-fea-convergence` | CalculiX 2.23 已验证线性/非线性静力、塑性、面接触、最终步 COPEN/CPRESS/CSLIP 与线性/非线性网格收敛;全部仍需工程复核 |
- | 复杂曲面与模具 | `scripts/advanced_geometry.py`、`scripts/advanced_geometry_ocp.py`、`scripts/advanced_surface_ocp.py`、`scripts/cad_studio.py review-advanced-geometry/create-ocp-loft/create-ocp-surface` | 直纹/平滑 Loft、受限 Sweep/Knit/Thicken 可写并重开 B-Rep;G1/G2 和曲率半径只返回离散采样证据 |
- | 本地 MCP Server | `mcp-server/server.py` | `mcp-server/README.md`、`references/mcp-server.md` |
- | MCP 协议验证 | `scripts/validate_mcp.py` | `mcp-server/README.md` |
- | 版本化 API 查证 | `scripts/sw_api_lookup.py` | `references/api-lookup.md` |
- | OpenClaw 控制 SolidWorks | - | `references/openclaw.md` |
- | 钣金/焊件/仿真/属性 | - | `references/advanced.md` |
- | 企业 Agent / 本地优先与云 RAG | `apps/desktop/cad_workbench/knowledge_retrieval.py` | `references/enterprise-agent-rag.md` |
- | Codex/Claude/Gemini/OpenCode Provider Adapter | `apps/desktop/cad_workbench/agent_providers.py` | `references/agent-provider-architecture.md` |
- | 综合机械工程 DAG 自动编排 | `apps/desktop/cad_workbench/engineering_orchestrator.py` | `references/complex-mechanical-routing.md` |
- | 常见错误排查 | - | `references/troubleshooting.md` |
- Pack and Go 在 SW2026 SP01.1 的基础两零件装配上已连续三次通过原生回归:`SavePackAndGo()` 实际输出装配体和两个零件,状态码均为 0,未使用暂存回退。部分版本的 `GetDocumentNames()` 仍可能在保存前只枚举顶层文件;不要用 `AddExternalDocuments` 补装配体原生零件,应先执行原生保存,再审计实际落盘依赖。若落盘仍缺依赖,`scripts/sw_delivery.py::pack_and_go()` 默认按 `GetDependencies2` 生成带 manifest 和 SHA-256 的 `pilot` 暂存包;需要严格原生语义时使用 `fallback_policy="blocked"`。外部引用、Toolbox、配置和工程图仍必须人工复核,因此总能力保持 `pilot`。
- ## OpenClaw 协作方式
- 1. 先确认 SolidWorks 版本、界面语言、输入文件路径、输出路径,以及目标操作(建模 / 装配 / 出图 / 导出)。
- 2. 优先复用 `{baseDir}/scripts` 下已有模块,不要重复手写 COM 连接逻辑。
- 3. 在 OpenClaw 的 `exec` / `shell` 能力中执行短小、一次性的 Python 脚本,最小导入集如下:
- ```python
- import sys
- sys.path.insert(0, r"{baseDir}/scripts")
- from sw_connect import connect_solidworks, mm, deg, new_document
- ```
- 4. 执行后检查返回对象是否为 `None`、保存/导出是否成功、输出文件是否落盘。
- 5. 生成或修改模型后必须做结果自审查:导出至少一个等轴测预览图,必要时导出前/俯/右视图,并通过截图或 BMP 目视检查几何是否符合用户意图。
- 6. 如果需要更完整的 OpenClaw 工作流、提示词示例和排障建议,再读取 `references/openclaw.md`。
- ## 使用流程
- 1. 先根据原子操作运行 `backend_router.py`,再结合 `preferredBackend`、`requiredOutputs`、`nativeFormatRequired` 和 `fallbackPolicy` 判定后端;不要先假定 Python、C# 或 SolidWorks 必然可用。普通任务优先 Automation 等价接口,明确要求仅非托管 C++ 支持的原始 `I*` 指针语义时才升级到原生 C++。
- 事件订阅、PropertyManagerPage、TaskPane 或长期驻留 UI 走 `solidworks_addin_ui_events` 路由,优先 C# Add-in;必须检查 HKLM 注册、64 位 TLB 注册和 `host-status.json`,不能只凭 `LoadAddIn=0` 宣称成功。SW2026 的 PMP Handler 必须公开、COM 可见并提供 `IDispatch` class interface。
- 2. 需要原生 SolidWorks 格式时运行 `sw_preflight.py`;缺依赖默认自动安装,缺 SolidWorks 则只阻断原生阶段。
- 3. 不需要原生格式或允许开放格式回退时,运行 `python scripts/cad_studio.py write-open-format --input model.cadstudio.json --out-dir output`。
- 4. 需要制造性快速复核时,运行 `python scripts/cad_studio.py check-dfm --input model.cadstudio.json --output output/dfm_report.json --process machining`;支持 `--profile supplier.json` 和 `--brep-evidence brep.json`。报告缺少材料、壁厚、K 因子、割缝、成型空间或要求的 B-Rep 证据时返回 `blocked`,规则通过也必须人工复核。
- 5. 原生 SolidWorks 路线优先用 `SolidWorksSession()` 管理连接、打开、新建、保存、导出;需要底层控制时再组合 `sw_connect.py`、`sw_part.py` 等函数。
- 6. 当用户需求偏自然语言、参数不完整或需要“行业知识库 + 提示词模板 + 参数化设计计划”时,先读取 `subskills/solidworks-vibecad/SKILL.md`,生成 `design_plan.json` 和执行摘要。
- 7. 圆角/倒角很多的 CNC 件、安装座、连接块、支架,先读取 `subskills/solidworks-fillet-chamfer-cnc/SKILL.md`,按“基础体 -> 外轮廓圆角/倒角 -> 孔槽切除 -> 孔口倒角 -> 审查”的稳定顺序执行。
- 8. 螺丝孔、螺纹孔、攻牙孔、M3/M4/M5/M6/M8 盲孔或贯穿孔任务,先读取 `subskills/solidworks-threaded-holes/SKILL.md`;默认按“参数/孔位校验 -> 攻丝底孔 -> Metric Tap 真实 Thread -> CosmeticThread/证据螺旋线降级 -> 孔口倒角 -> 重建后特征证据 -> 属性和审查”的稳定路线执行。Hole Wizard、外螺纹、英制/管螺纹和现有零件改孔仍按 pilot 处理。
- **齿轮路由门禁:** 当用户说“画/建模/生成齿轮”时,先读取 `references/gears.md`,不得把实体齿轮需求替换成 Gear Mate。只有标准外啮合直齿轮且已知模数、齿数、压力角、齿宽和轴孔时,才使用 `scripts/sw_gear.py`;制造任务不得臆造参数,仅做视觉 demo 时可显式声明默认值。斜齿、锥齿、内齿、齿条、蜗轮蜗杆、变位或生产级修形/侧隙必须转专用路线或人工复核,不强套标准直齿轮脚本。“齿轮联动/传动/配合”才路由到 `sw_assembly.add_gear_mate_by_cylinders()`。
- 9. 普通盲孔、通孔、圆柱沉孔、锥形沉头孔、半圆端槽或孔阵列任务,读取 `references/complex-hole-features.md` 并优先调用 `scripts/sw_hole_features.py`;创建参数证据必须再与 `collect_geometry_measurements()`、`validate_hole_positions()` 和剖视图交叉复核。
- 10. SolidWorks 零件图、装配图、GB/T 工程图、尺寸链、孔表、BOM、标题栏或工程图审视任务,先读取 `subskills/solidworks-engineering-drawing/SKILL.md`;该子技能消费根技能的模型、孔槽和属性证据。AutoCAD 的 DWG/DXF、二维图纸、线稿转 CAD、批量改图或 AutoCAD 原生预览任务,读取 `subskills/autocad-automation/SKILL.md`。机械/3D 打印开孔交付必须按可制造图纸处理:所有孔、槽、接口、水口、螺丝孔和螺丝柱同时给出规格、数量和定位尺寸;图面拥挤时用孔表/槽表,不得用长引线替代关键尺寸。
- 11. 当用户要求真实产品“原版外观”“1:1 复刻”“不像概念版”,先读取 `references/mesh-reference-import.md`:公开网格/蓝图参考优先,不要在低保真手搓底稿上反复精修;需要导入 OBJ/STL 时优先用 `scripts/sw_import_mesh_reference.py`。
- 12. 如果必须由大模型生成 VBA 宏,先使用 `sw_macro_guard.py` 做模型分流、代码校验、重试和本地模板兜底。
- 13. 使用 `session.export()` 或 `sw_export.py` 保存/导出文件。
- 14. 使用 `sw_review.py` 导出预览图并自审查;如果有 GUI/桌面截图能力,打开 SolidWorks 视图截图复核。
- 15. 遇到钣金、焊件、复杂曲面、模具、Routing、Simulation/FEA、复杂 Motion 或配置族任务,先运行 `sw_capability_probe.py` 并读取 `references/complex-mechanical-routing.md`;Routing 使用 `routing-preflight/check-routing`,FEA 使用 `fea-preflight/prepare-fea/run-fea/run-fea-convergence`,复杂曲面使用 `review-advanced-geometry/create-ocp-loft/create-ocp-surface`。FEA 和高级曲面求解通过仍为 `review_required`。
- 16. 需要企业/项目机械知识时读取 `references/enterprise-agent-rag.md`;默认只用本地知识,云 RAG 必须显式启用、声明 `external_network` 并完成人工审批。
- 17. 当一个需求同时跨越零件、孔槽/圆角、装配 Mate、Motion、工程图/BOM 和多格式交付中的两个以上工程域时,调用 `apps/desktop/cad_workbench/engineering_orchestrator.py` 生成阶段 DAG。必须按依赖串行执行关键 CAD 写操作,每阶段独立保存产物和验收证据;局部修改只重规划受影响阶段及其后继,禁止把整项工程塞进一条超长 Prompt 后一次性宣称完成。
- ### 机械图纸默认底线
- 以后凡是本技能参与 CAD/机械结构/3D 打印项目,都默认执行这些底线:
- 1. 不把“看得懂的示意图”当成“能制造的工程图”。只要涉及开孔、开槽、接口、装配孔或打印外壳,必须补齐外形尺寸、壁厚/底厚、孔槽规格和定位尺寸。
- 2. 用户要求“中国常用格式”“国标风格”“严格规范”时,必须采用国内机械制图习惯:规范图幅/图框/标题栏、仿宋中文、分层线型、中心线/虚线、真实标注实体和技术要求。
- 3. 长引线只能做局部说明,不能替代尺寸链;不得跨视图、压孔、压中心线、压尺寸文字或侵入标题栏。
- 4. 密集孔槽必须优先用孔表、槽表或孔槽明细表,表内写清部位、规格、数量和定位;表格不能成为逃避定位尺寸的借口。
- 5. 交付前必须目视复核预览图,发现漏标、重叠、压线或标题栏侵入时先返工再汇报。
- ### 高还原外观/公开网格参考模型
- 当用户要求汽车、消费电子、雕塑等真实对象外观高还原时,先区分“视觉参考模型”和“工程可制造参数模型”:
- 1. 若用户要“像原版”,优先索取或查找公开 3D 模型/多视图蓝图,并记录来源、作者、许可证和下载日期;不要声称生成的是官方 Class-A 或扫描级模型。
- 2. `.glb/.gltf/.fbx/.blend` 先转换为 `.obj/.stl`;OBJ 优先保留材质,STL 作为无材质兜底。
- 3. 导入前用包围盒确认坐标轴和尺度,再按真实公称尺寸缩放。
- 4. 如果需要 Python 转换/缩放,先确认 `requirements-mesh.txt` 中的可选依赖可用;缺失时说明用途并提示安装。
- 5. OBJ/STL 导入 SolidWorks 时用 `sw_import_mesh_reference.py`;关键写法是 `LoadFile4(path, "r", create_empty_dispatch_variant(), errors)`,不要用 `OpenDoc6()` 或把 `None` 传给 `LoadFile4()`。
- 6. 结果审查必须看四视图和关键识别特征;“预览非空白”不能替代“像用户指定对象”。
- 7. 若用户后续要工程可编辑结构,应基于网格参考分件逆向重建,并明确说明网格导入件不是参数化实体。
- ### 多色外观要求
- 当模型包含车身、玻璃、灯组、轮胎、轮毂或其他多种颜色时:
- 1. 读取 `references/appearance.md`,统一使用 `sw_appearance.py`,禁止把普通 Python `list` 直接传给 COM 材质属性。
- 2. 源零件先设置文档级颜色;装配体中需要覆盖时再用组件级颜色。
- 3. 每次设置后调用 `verify_appearance()` 或 `apply_component_palette()` 回读 RGB;只检查 setter 返回值不算通过。
- 4. 保存与截图前调用 `model.ClearSelection2(True)`;`sw_review.save_preview()` 已内置该清理。
- 5. 目视确认至少三种预期颜色真实可见;“预览非空白”不能替代颜色检查。
- 6. 外观异常时先运行 `tests/solidworks_appearance_regression.py`,再重建用户模型。
- ### MCP Server 使用
- 当用户要求“让 SolidWorks 支持 MCP”“接入 Codex/Claude Desktop 工具调用”“不要每次生成一大段 Python 脚本”时:
- 1. 读取 `mcp-server/README.md`。
- 2. 若用户要求自动配置 MCP,优先运行多客户端注册器:`powershell -ExecutionPolicy Bypass -File mcp-server/register_all_ai_mcp.ps1 -InstallDependencies`;它会尝试注册 Codex、Claude Code、Claude Desktop、Cursor、Windsurf。
- 3. 使用本地 `stdio` MCP server:`python mcp-server/server.py`;默认是发现模式(`SW_MCP_DISCOVERY=search`),只暴露 `sw_search_tools` / `sw_describe_tool` / `sw_call_tool`。需要全部命名工具时设 `SW_MCP_DISCOVERY=full`。
- 4. 发现模式按「检索 → 读 Schema → 执行」使用:先 `sw_search_tools` 用中英文说法找候选,再 `sw_describe_tool` 确认参数,最后 `sw_call_tool`。不要凭猜测直接调用工具名。
- 5. 默认发现模式信任客户端已经取得当前任务的授权;在用户授权范围内执行建模,不要逐项
- 要求额外批准。涉及用户未授权的覆盖、关闭或其他高风险操作时仍须取得明确授权。
- 可为已保存文档的活动文档写操作提供 `document_target`(绝对 `path` 和 SolidWorks
- `process_id`),以校验目标;未提供时使用工具原有的活动文档行为。
- 如用户显式启用 `server` 逐次审批,工具返回请求 ID 时请用户在服务端运行
- `python scripts/sw_mcp_approve.py approve <请求ID>`;目标无法核验时停止并说明限制。
- 6. 无 CAD 开放格式写入优先调用 `cadstudio_write_open_format`;DFM、Routing、FEA 和复杂几何分别调用 `cadstudio_check_dfm`、`cadstudio_check_routing`、`cadstudio_routing_preflight`、`cadstudio_fea_preflight`、`cadstudio_prepare_fea`、`cadstudio_run_fea`、`cadstudio_run_fea_convergence`、`cadstudio_review_advanced_geometry`、`cadstudio_create_ocp_loft`、`cadstudio_create_ocp_surface`;SolidWorks 原生操作再调用白名单 `solidworks_*` 工具。
- 7. 不要暴露任意 Python/VBA 执行工具;新增 MCP 工具时应复用 `scripts/sw_*.py` 中已验证封装。
- 8. SolidWorks COM 操作必须串行执行;MCP server 内部已使用全局锁降低桌面会话冲突。
- 9. 基准 demo 使用 `examples/08_mini_fan_motion_assembly.py`;它验证自动建模、装配、Mate 和 Motion Study,不承诺圆角/倒角外观完美。
- ### 运动装配体要求
- 当用户要求“能动起来”“在 SolidWorks 里拖动”“铰链”“齿轮联动”“真实机械配合”时:
- 1. 先读取 `references/assembly.md` 的运动型装配工作流;如果用户明确要求 Motion Study / 运动算例 / 马达,再读取 `references/motion-study.md`。
- 2. 优先复用 `sw_assembly.py` 中的 `resolve_component()`、`get_assembly_entity()`、`find_largest_cylinder_face()`、`add_mate5_checked()`、`add_concentric_mate_by_cylinders()`、`add_gear_mate_by_cylinders()`。
- 3. 旋转件用同心 Mate 且 `lock_rotation=False`,不要用三基准面把轴、齿轮、上盖完全锁死。
- 4. 齿轮传动用真实 Gear Mate,不用脚本假动画冒充机械配合。
- 5. 创建后用 `collect_mate_feature_summary()` 或特征树遍历验证 MateGroup 下存在 `MateConcentric`、`MateGearDim` 等真实 Mate 特征。
- 6. 需要真实运动算例时,优先复用 `sw_motion.create_motion_study()`、`add_constant_speed_rotary_motor_by_cylinders()`、`calculate_and_play()` 创建 Motion Study 和马达。
- 7. 计算后调用 `sw_motion.validate_motion_studies()` 或 MCP `solidworks_validate_motion_study`,检查类型、时长、马达数量、结果存在性和 `results_out_of_date=False`;只看到时间轴、动画或 `Calculate=True` 不算验收通过。
- 8. 需要演示动画时可以额外脚本驱动组件位姿或 Mate Controller,但必须说明动画演示不等同于交互自由度;最终以 SolidWorks 中可拖动为准。
- ## GPT / Kimi / Claude 多模型策略
- 当代理需要让大模型生成 VBA 宏时,必须通过 `scripts/sw_macro_guard.py`:
- 1. **模型分流**:GPT 系列使用原有简洁提示词;Kimi / Claude / 未知模型自动加载强格式约束 Prompt,强制只输出 VBA 源码。
- 2. **本地模板兜底**:模型输出失败或解析失败时,不直接报错;按用户关键词(如“立方体”“圆柱”“拉伸”“草图”)选择内置 VBA 模板继续执行。
- 3. **输出校验**:执行前检查 `SldWorks`、`ModelDoc2`、`Sub`、`End Sub`,通过后才允许交给 SolidWorks;不通过则重试。
- 4. **超时/重试**:单次模型请求建议 `30s` 超时;解析失败自动重试 `1~2` 次,重试 Prompt 追加更强格式指令。
- 示例:
- ```python
- from sw_macro_guard import build_prompt, fallback_macro_for_request, validate_vba_macro
- prompt = build_prompt("画一个 50mm 圆柱", model_name="claude")
- macro = fallback_macro_for_request("画一个 50mm 圆柱")
- result = validate_vba_macro(macro)
- assert result.ok, result.issues
- ```
- ## 未封装 API 规则
- 当任务需要调用 `scripts/` 中尚未封装的 SolidWorks API 时:
- 1. 先读取 `references/api-lookup.md`,使用 `python SKILL_DIR/scripts/sw_api_lookup.py 接口 方法` 查询目标版本的本地类型库与官方文档;已知目标年份时加 `--version 2024`,多实例时加 `--process-id`。确认签名、单位、前提和版本差异。
- 2. 禁止凭记忆猜接口;尤其是长参数 COM 方法、`VARIANT` / by-ref 参数、枚举值、选择标记和 `SaveAs` 类接口。
- 3. 写代码时保留最小可运行脚本,并对每一步返回值做 `None` / `False` 检查。
- 4. 实现后必须真实运行,保存或导出目标文件,并使用 `sw_review.py` 生成预览图与审查报告。
- 5. 新发现的坑、错误码、兼容写法或稳定封装,要补充到 `references/troubleshooting.md` 或对应模块参考文档;常用逻辑再沉淀进 `scripts/`。
- 查证默认可访问 SolidWorks 官方文档,官网直读失败且没有缓存时使用匿名 Parallel 备用查询;仅发送公开版本、接口、成员及官方链接。`--offline` 或 `SW_API_LOOKUP_NETWORK=off` 禁止本工具联网,`--no-parallel` 或 `SW_API_LOOKUP_PARALLEL=off` 单独关闭 Parallel。离线可用本机帮助及上次获取的缓存,须留意版本证据和获取时间。文档不足时可在客户端允许的范围内使用其自带搜索,仅搜索公开 API 标识;客户端自己的联网权限由客户端控制。接口声明、官方说明和真机行为分别判断,缺少目标版本或运行验证时不得声称已验证兼容。
- 自然语言任务未指明 API 时,先运行 `python SKILL_DIR/scripts/sw_api_lookup.py --task "任务描述"` 自动查证常见候选;候选不是强制方案。无候选或规划中确定其他 API 时,先从现有封装确定接口与成员,再逐项查询对应版本,不要把任务全文发给第三方服务。
- ## 结果自审查
- 每次生成、修改、导入或导出 CAD 后都要做自审查,除非用户明确说不需要:
- 1. 检查 COM 返回值、特征对象、保存/导出返回值和输出文件大小。
- 2. 调用 `model.ForceRebuild3(False)`、`model.ViewZoomtofit2()` 刷新模型。
- 3. 用 `scripts/sw_review.py` 的 `run_review()` 导出 `isometric/front/top/right` 预览图并写入 `*_review_report.json`。
- 4. 读取报告里的 `evaluation.status`、`evaluation.issues`、`checks` 和预览图;通过截图或导出的 BMP 检查:主体是否存在、比例/方位是否合理、关键部件是否缺失、是否明显重叠或悬空、文件名和输出路径是否正确。
- 5. 若发现问题,先修脚本并重新生成,再汇报;不要只报告“保存成功”。
- 示例:
- ```python
- from sw_review import run_review
- model.ForceRebuild3(False)
- report, report_path = run_review(
- model,
- r"C:\temp\review",
- basename="car",
- expected_outputs=[r"C:\temp\car.sldprt", r"C:\temp\car.step"],
- )
- print(report_path)
- print(report["evaluation"])
- ```
- ## 关键注意事项
- - **单位**:API 统一使用**米**。用 `mm(50)` 转换 50mm 为 0.05m,用 `deg(90)` 转换角度
- - **版本**:可指定 SolidWorks 年份并核对目标实例;不同操作的兼容性以 `capabilities.yaml` 和实际版本证据为准,不能将连接成功视为所有功能兼容
- - **选择**:能拿到 COM 对象时优先用对象级 `Select2()`;基准面可用 `SelectByID2("PLANE")`,草图不要只依赖 `SelectByID2("SKETCH")`
- - **草图**:推荐用 `with sketch(model, "Front Plane") as sketch_name:` 自动进入/退出草图;`sw_part.py` 会缓存草图对象引用,避免 SW2024 中文版按名称选择草图失败
- - **添加组件**:装配体优先用 `sw_assembly.add_component()`;SW2024 中文版下 `AddComponent4` 可能返回 `None`,封装会用 `AddComponent5`、静默打开零件、重新激活装配体后重试
- - **外观**:对颜色要求高的模型优先拆成多零件装配体;材质数组必须用 `SAFEARRAY(double)` 编组,并回读 RGB 验证
- - **VARIANT**:by-ref 参数必须用 `VARIANT(pythoncom.VT_BYREF | pythoncom.VT_I4, 0)` 包装
- - **基准面名称**:`start_sketch()` 会自动兼容英文版 "Front/Top/Right Plane" 与中文版 "前视/上视/右视基准面"
- - **草图坐标**:基于草图平面的局部坐标系,单位为米
- - **运动装配**:先解析组件再选 Mate 实体;`GetCorresponding()` 用于把零件内面/特征映射到装配体上下文;同心 Mate 默认不锁旋转
- - **Motion Study**:`swmotionstudy.tlb` 需加载;pywin32 下 `CreateMotionStudy` / `Activate` / `Calculate` 可能表现为属性,优先用 `sw_motion.motion_member()` 兼容
README.md · README · 358 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # 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 发布说明](docs/releases/v2.1.1.md)。
- CAD Studio 会对各生产执行器统一检查交付文件是否为本轮新增或内容已变化;旧文件拒绝交付,证据不足转为待复核。扫描范围、兼容性与验证方法见[本轮交付门禁](references/delivery-freshness.md)。
- [](https://opensource.org/licenses/MIT)
- [](https://www.python.org/downloads/)
- [](https://github.com/wzyn20051216/solidworks-automation-skill/releases)
- [](https://github.com/wzyn20051216/solidworks-automation-skill)
- [](mcp-server/README.md)
- [](https://github.com/wzyn20051216/solidworks-automation-skill/actions/workflows/windows-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 | 原生建模需本机安装并许可;按能力查看 [已验证版本](capabilities.yaml) | `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
- 三种入口**任选其一**即可,不需要同时启动。
- ### Option 1 — Skill
- ```powershell
- 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`。
- | 参数 | 作用 |
- |---|---|
- | `--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
- 支持 MCPB 的 Windows 桌面客户端可导入发布页的标准 `.mcpb` 扩展。若当前发行尚未附带该文件,也可从 Git 检出构建。首次安装、`uv` 准备和构建方法见 [MCPB 扩展说明](mcp-server/README.md#windows-mcpb-扩展)。
- ```powershell
- 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](https://github.com/wzyn20051216/solidworks-automation-skill/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)。
- > **Choose one entry point. You do not need to run all three.**
- | 入口 | 适合谁 | 需要 GUI | 典型用法 |
- |---|---|---|---|
- | **Skill** | 支持 skill 导入的 Agent 客户端 | 否 | 自然语言驱动 SolidWorks |
- | **MCP** | Codex / Claude / Cursor / Windsurf 等 MCP 客户端 | 否 | Agent 自动 Tool Calling |
- | **CAD Studio** | 需要图形界面管理项目/任务/预览/交付 | 是 | 桌面端提交任务 |
- 三者是**平级入口**,共用同一套能力清单(`capabilities.yaml`)、脚本与证据系统。安装后可用 `python scripts/cad_doctor.py` 做环境诊断;详细安装与 CLI 见 [`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`(全量,当前 1045 项)、`evals/runner.py`(12 workflow / 43 scenario)、治理单测(当前 93 项) | 需要 SolidWorks / AutoCAD 进程的一切 |
- | L2 托管 CI | GitHub 托管 `windows-2022` | 与 L1 相同,外加前端/ Rust 构建与发布契约检查;作业名 `test-and-build`,是 `main` 的**唯一必需状态检查** | 真实 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 SP1.1** 为基线,部分能力另有 **2024** 真机记录。以 [能力清单](capabilities.yaml) 中对应能力的 `verified_versions`、等级和限制为准;未列出的版本需单独验证。环境诊断只检查安装和运行条件,工程功能按实际任务验收。
- **完整模式暴露 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 按上述能力清单核对。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) · [GitHub Issues](https://github.com/wzyn20051216/solidworks-automation-skill/issues) · [Star History](https://star-history.com/#wzyn20051216/solidworks-automation-skill&Date)
- <picture>
- <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=wzyn20051216/solidworks-automation-skill&type=Date&theme=dark">
- <img src="https://api.star-history.com/svg?repos=wzyn20051216/solidworks-automation-skill&type=Date" alt="SolidWorks Automation Skill 星标趋势" width="960">
- </picture>
- ---
- ## 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.
- ---
- <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 实测正常返回;
- 该真机样例为零干涉,非零结果读取仍以离线回归为证据。
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.