前言¶
在 DSH 里让模型处理 CAD，常见做法是上传模型到云端或自己写脚本调 OCC/OpenCascade。前者有数据与合规顾虑，后者要在 DSH 侧维护 Python 与几何库。dsh-freecad 走另一条路：几何计算全部在 FreeCAD 进程里完成，插件只做工具注册、参数校验和文件传递，模型不出本机，也不在 DSH 里单独装 Python。
下面介绍该插件的定位、能力与安装方式，便于在客户端 profile 里接入 STEP 检视、简单编辑和出图流程。
这是什么¶
dsh-freecad 由 Negulons 维护（npm 包作者署名为蓝色大肥鱼），在 SkillHub 插件目录 中归类为客户端插件。MIT 许可证；当前 npm 版本为 0.4.2。
一句话定位：把对话里的自然语言意图转成 FreeCAD 可执行的几何操作——读取 STEP/STP（及 IGES/BREP）、按参数编辑立体模型、再生成第一角法二维加工图（SVG/DXF/PDF/PNG）。它不是 CAD 内核，也不是云端服务；FreeCAD 打不开的文件，这里同样打不开。
核心功能¶
插件向 DSH 注册五组工具，长度单位均为 mm。
| 工具 | 作用 |
|---|---|
freecad_status |
检查 freecadcmd 路径、版本、worker 是否就绪；排错时优先调用 |
freecad_inspect_step |
读 STEP/STP 等：包围盒、体积、面/边/顶点、对象列表、孔识别（含斜孔、腰形孔等）；detail: true 可分页读面/边明细 |
freecad_edit_step |
平移/旋转/缩放/镜像、钻孔、布尔增删、倒圆角/倒角；导出新 STEP，可选存 FCStd |
freecad_step_to_drawing |
HLR 隐藏线消除 → 主/俯/右视图与轴测图，自动图幅比例、总尺寸、孔表与标题栏，多格式导出 |
freecad_measure |
不改模型，测量点/面/边距离、夹角、圆柱/圆边直径，供补标注使用 |
README 明确说明：不是生产级出图工具。图纸目前侧重总宽/总高与孔表，凸台直径、台阶高度、孔位等常需人工补标或先用 freecad_measure 再让模型补全；无剖视图、形位公差等。完整限制见仓库 docs/limitations.md。
环境要求¶
| 依赖 | 要求 |
|---|---|
| 操作系统 | Windows 10/11 已实测；Linux / macOS 需手动指定 freecadcmd |
| FreeCAD | 1.0 或 1.1，且带 freecadcmd |
| DSH | 支持 bundle（dsh.bundle.patch）的版本 |
| Node.js | 18+（DSH 自带即可） |
已验证组合示例：Windows 11 + FreeCAD 1.1.4（便携版）+ DSH Desktop。
安装与启用¶
插件是普通 DSH bundle，装入 profile 后必须重启 DSH 才会挂载。
方式 A：DSH 插件页（推荐）¶
打开 DSH 的插件页，输入 dsh-freecad 搜索并安装，然后重启 DSH。插件页会写入 profile 依赖、dsh.profile.bundles 与 cordis.patch.yml，无需手改文件。若重启后「设置 → FreeCAD」未出现，可再重启一次。
方式 B：npm 与安装脚本¶
先安装包，再执行仓库提供的安装脚本（会备份被改动的文件）：
npm i dsh-freecad # 或 pnpm add dsh-freecad
node node_modules/dsh-freecad/scripts/install.mjs
装完之后¶
重启 DSH 后，可在对话中说「检查一下 FreeCAD 状态」，或调用 freecad_status，确认 freecadcmd 路径与版本。
非 Windows 或便携版安装时，在 DSH → 设置 → FreeCAD 填入 freecadcmd 完整路径；也可通过 profile 的 config.freecadPath 或环境变量 FREECAD_CMD。路径解析顺序：设置页 → profile 配置 → 环境变量 → Windows 默认 Program Files 路径。该配置保存后立即生效，无需重启 DSH。
典型用法¶
仓库 README 给出的对话示例可直接复现（产物默认落在工作目录，如图纸目录 <输入名>_drawing/、编辑后的 <原名>_edited.step）：
你：读一下 examples/demo_bracket.step，告诉我它有几个孔、多大。
你：把它转成 A3 加工图，带轴测图，输出 PNG 和 DXF。
你：在顶面中心加一个 Ø8 通孔，倒 C1 角，另存一份。
示例 STEP 经 freecad_step_to_drawing 可生成 A3 图纸，SVG/DXF/PDF/PNG 可同时输出。
适用场景与注意¶
适合：需要在 DSH 对话中本地检视 STEP、做常见机加特征编辑（孔、倒角、简单布尔）、快速出第一角法草图供内部沟通或再人工补标的使用者；强调数据不出本机、无遥测。
注意：
- 插件以当前 DSH 进程权限运行，可读写其能访问的路径；安装前建议查看 GitHub 源码 与 MIT 许可证，并确认 FreeCAD（LGPL）运行时依赖符合你的合规要求。
- 改
dsh/*.py后 worker 每次调用会重载；改index.js或lib/client.js须重启 DSH。 - SkillHub 为社区插件目录，与 DeepSeek / 幻方无官方从属关系；星标等元数据以目录与 GitHub 页面为准（截至资料抓取时 GitHub 约 3 stars）。
结尾¶
dsh-freecad 是 DSH 生态里面向 FreeCAD 的薄桥接层：不替代 FreeCAD，也不承诺工厂级图纸，但在「对话驱动 + 本机几何」这条线上步骤清晰、工具边界明确。进一步参数语义与架构说明见仓库 docs/tools.md、docs/architecture.md。
