ahang1598 ZW3D 建模 Skill
本 Skill 为 ZW3D CAD 提供建模全链路能力：草图 → 实体 → 特征 → 装配 → 外观 → 查询。
前置条件：用户本机必须已安装并启动 ZW3D 3200 及以上版本。 若用户尚未安装 ZW3D（连接器报「No ZW3D installation detected」或连接失败），请先引导用户前往官方下载页安装：https://www.zwsoft.cn/product/zw3d 安装完成后需重新启动 ZW3D，并重新连接/添加 MCP 连接器。 若工具调用失败并提示连接错误，请先提示用户打开 ZW3D 应用程序。
启动前插件预检（强制执行）
目标：建模前确保「正确的 ZW3D 已启动 + 插件 DLL 已就位」，避免以无插件状态启动 ZW3D 导致 全部建模工具失败（表现：
no data returned from ZW3D/Failed to open event）。
三步走（按顺序）：
- 查路径：调
zw3d_status（resolve_remote: true）→ 取zw3d_exe/zw3d_runtime_dir/remote_path， 并校验文件真实存在。- 查不到或路径无效 → 不要猜路径，转「安装目录兜底」请用户提供目录。
- 验 DLL：确认
<ZW3D目录>\apilibs\内ZW3D_MCP.dll、.env已存在，且与插件缓存%LOCALAPPDATA%\ZWSOFT\ZW3D_MCP\plugins\v{版本}\node_modules\zw3d-mcp-plugin\bin\内容一致（大小 + SHA-1）。- 缺失/不一致 → 先部署再启动：① 以管理员身份重连连接器（launcher 自动部署）； ② 或按「安装目录兜底」步骤 5 的管理员 PowerShell Copy-Item 命令手动复制。
- 启 ZW3D：ZW3D 未运行时，用第 1 步拿到的
zw3d_exe启动（与 MCP 插件同源同版本，不另猜路径）； ZW3D 已在运行且步骤 2 做了新增部署 → 请用户关闭后重开 ZW3D（插件只在 ZW3D 启动瞬间加载）。
自检收尾：首个建模工具前先做 active root 查询；若返回 no data returned from ZW3D → 回到本预检或
「安装目录兜底」排查，不要盲目重试同一调用。
关闭/重启 ZW3D 一律先征得用户同意（见「进程管理约束」），优先引导用户自行操作，不代为强杀。
安装目录兜底：找不到或路径无效时（强制执行）
适用场景：MCP 无法把正确的 ZW3D 路径交给 Agent——①
zw3d_status（resolve_remote: true） 或zw3d://server/status查不到zw3d_exe/zw3d_runtime_dir/remote_path； ② 返回的路径经 Agent 文件系统校验不存在或不可用（zw3d.exe、ZW3dRemote.exe 缺失，或启动即失败）； ③ 建模持续no data returned from ZW3D/Failed to open event且 apilibs 缺 DLL。 命中以上情况时不要反复重试工具，进入本兜底流程。
为什么让用户提供目录是可靠路径：注册表可能缺键/被清理，自定义或绿色安装不会注册； 此时用户给出安装目录 + Agent 在目录及子目录搜索，是最快恢复方式。
步骤（按顺序执行）：
- 先自查并判定：调
zw3d_status（resolve_remote: true），用文件系统校验返回的zw3d_exe、remote_path是否真实存在；不存在或为空 → 判定"路径缺失/错误"，进入第 2 步。 - 请用户提供目录：询问"您的 ZW3D 装在哪个目录？"，提示典型位置
（
C:\Program Files\ZWSOFT\ZW3D WuKong 2027、D:\...\ZWSOFT\...），支持用户粘贴路径。 - 搜索启动文件（用户目录 + 子目录）：递归搜索（限深 3 层，避免全盘慢扫），目标：
- 主程序：
zw3d.exe - IPC 桥：
ZW3dRemote.exe - 插件目录：名为
apilibs的文件夹（内含 ZW3D_MCP.dll） - 参考命令（Agent 可用；把
<用户目录>换成实际路径）：# Git Bash find "<用户目录>" -maxdepth 3 \( -iname 'zw3d.exe' -o -iname 'ZW3dRemote.exe' -o -iname 'apilibs' \) 2>/dev/null # PowerShell 等价：Get-ChildItem "<用户目录>" -Recurse -Depth 2 -Include zw3d.exe,ZW3dRemote.exe -ErrorAction SilentlyContinue - 多版本共存：把命中的所有候选目录列给用户确认；也可用
ZW3D_MCP_PREFERRED_VERSION（如 3200）锁定目标版本。
- 主程序：
- 校验候选目录：确认该目录同时含
zw3d.exe与apilibs\（或ZW3dRemote.exe）； 版本须为受支持的 **ZW3D 3200+**（注册表ProductVersion形如32.xx）。 - 部署 DLL + .env：
- 源：插件缓存
%LOCALAPPDATA%\ZWSOFT\ZW3D_MCP\plugins\v{版本}\node_modules\zw3d-mcp-plugin\bin\（内含ZW3D_MCP.dll、.env；若缓存缺失，可重连连接器触发 launcher 下载）。 - 目标：
<候选目录>\apilibs\。 - Agent 先尝试直接复制并 SHA-1 校验一致性；
- 若
EPERM/EACCES（写Program Files需管理员）→ 给用户一条代入真实路径的 管理员 PowerShell 命令：Copy-Item "$env:LOCALAPPDATA\ZWSOFT\ZW3D_MCP\plugins\v3200\node_modules\zw3d-mcp-plugin\bin\ZW3D_MCP.dll" "<候选目录>\apilibs\" -Force Copy-Item "$env:LOCALAPPDATA\ZWSOFT\ZW3D_MCP\plugins\v3200\node_modules\zw3d-mcp-plugin\bin\.env" "<候选目录>\apilibs\" -Force - 或提示"以管理员身份运行 WorkBuddy 后重连连接器"（launcher 会自动部署）。
- 源：插件缓存
- 重启 ZW3D：请用户完全关闭并重新打开 ZW3D（插件只在启动时加载）。重新打开时优先用
zw3d_status返回的zw3d_exe（与插件同源），无效才用本流程搜到的目录。遵循「进程管理约束」： 不代为强杀进程，先征得用户同意、优先引导用户自行关闭。 - 自检收尾：重连后调
zw3d_status与 active root 查询确认链路打通；仍失败则回到本流程或 「常见错误场景」排查，不要盲目重试建模工具。 - 确未安装：若用户目录内也搜不到 → 引导安装：官方下载 https://www.zwsoft.cn/product/zw3d （安装后重新启动 ZW3D，并重新连接/添加 MCP 连接器）。
目录含空格属正常（如
ZW3D WuKong 2027），搜索/复制命令一律加引号；给用户的命令中<候选目录>需替换为实际路径，切忌原样粘贴。
工具发现机制（重要）
- ZW3D 的全部建模工具由 MCP 服务动态提供（
tools/list）。工具的名称、参数、输入 schema 与使用说明，一律以 MCP 服务返回的工具描述为准。 - 建模前，请先查询相关工具的 description 与 input schema，再按其说明调用。
- 工具调用失败时，优先读取该工具返回的错误信息，并结合「常见错误场景」排查。
进程管理约束（必须遵守）
- 严禁自行强行关闭 ZW3D 进程：未经用户同意，不得自行终止/结束 ZW3D 进程（包括但不限于调用结束进程、taskkill、强杀等任何方式）。
- 终止前必须提示并征得同意：凡涉及需要终止或重启 ZW3D 进程的操作，都必须先明确提示用户、说明原因，并得到用户明确同意后才可执行。
- 优先引导用户自行关闭：确需关闭 ZW3D 时，优先提示用户自行关闭，而非由 AI 代为强制结束。
工作流建议
- 建模前：用 active root 查询工具确认当前活动文档与文件类型。
- 新建零件：用空白零件/装配体创建命令（part 或 assembly）。
- 画实体优先用复合命令：草图+拉伸、草图+旋转、扫掠、放样等一步成型的复合命令。
- 不要两步走：不要先单独建草图再拉伸/旋转，复合命令内部会自动创建草图。
- 特征顺序：先完成主要几何特征，最后再添加倒圆角、倒角。
- 查询 ID 再操作：调用特征工具前，先用查询工具获取 face_id / edge_id / shape_id / feature_id。
- 装配流程：先创建装配体 → 插入零件 → 添加约束。
- 外观流程：搜索材质 → 应用材质。
常见错误场景
| 错误场景 | 表现 | 解决方案 |
|---|---|---|
| ZW3D 未启动 | 工具返回连接错误 | 先做「启动前插件预检」，再启动 ZW3D |
| 注册表查不到 ZW3D（自定义/绿色安装、键被清理） | zw3d_status 无 zw3d_exe / 返回 "No ZW3D installation detected" |
走「安装目录兜底」：请用户提供目录 → 搜索 zw3d.exe/apilibs → 部署 DLL |
| zw3d_exe 路径无效（Agent 校验不存在或启动即失败） | zw3d_status 有路径但文件不存在 / 启动秒退 |
路径错误→走「安装目录兜底」；路径正确→按预检部署 DLL 后重启 ZW3D |
| apilibs 缺 DLL/.env 或版本不一致 | no data returned from ZW3D / Failed to open event |
按「启动前插件预检」部署 DLL+.env 后重启 ZW3D，再重连连接器 |
| 部署被拒（非管理员） | EPERM / EACCES，连接被阻断（FATAL startup blocked） |
以管理员身份运行 WorkBuddy 重连，或在管理员 PowerShell 手动复制（见兜底步骤 5） |
| 实体 ID 无效 | 工具返回 "entity not found" | 用查询工具获取正确 ID |
| 布尔运算失败 | shape_id=0 | 检查目标实体是否存在 |
| 特征再生失败 | regen_status≠0 | 检查参数是否合理，面/边是否仍存在 |
| 草图轮廓不闭合 | 拉伸失败 | 确保 profile 首尾闭合 |
| 扫掠路径多段 | 返回错误 | 将多段路径合并为一条样条 |
| 重复插入组件 | 装配重影 | 删除多余组件 |
| 螺纹面非圆柱 | 标记螺纹报错 | 先确认目标面类型为圆柱 |
建模最佳实践
- 复合命令优先：用「草图+拉伸」等复合命令，而非分开调用草图 + 拉伸。
- ID 查询优先：操作前用查询工具获取精确 ID，不要猜测。
- 特征顺序：主要几何 → 孔/螺纹/筋/壳 → 最后倒圆角/倒角。
- 修改优先于重建：用参数修改工具调整，避免删除重建。
- 嵌套不相交轮廓：拉伸会被拆成多个实体，孔类特征用 remove 操作。
- 圆形阵列注意：spacing_angle 是相邻实例间距角（如 24 个实例用 15°），非总角度。
- 装配基础件：第一个插入的组件用 anchor=1 固定。