前言¶

在 DeepSeek Harness（DSH）里接 CAD，常见做法是让模型生成并执行 FreeCAD Python 脚本。路径难控、难复现，几何结果也不易以结构化方式回传给模型。维护者 zhaizhoux 的 dsh-cad-freecad 走另一条路：用纯 JSON 描述模型，由本机 FreeCAD 1.0+ 的 OCCT 内核建模；插件返回精确几何报告，并按需导出 STEP、IGES、STL 等格式。它不执行用户代码，文档里也没有表达式求值器——边界写在 ADR-0001。

下面按定位、能力、安装与用法说明这款客户端类 DSH 插件（分类见 SkillHub 目录页）。

这是什么¶

dsh-cad-freecad 把本机 FreeCAD 变成安全、声明式的 CAD 建模后端：参数化实体、精确几何报告、多格式导出，并提供独立 CLI 与本地浏览器 UI。

• 维护者：zhaizhoux
• 仓库：github.com/zhaizhoux/dsh-cad-freecad
• 许可证：MIT（见仓库 package.json，当前版本 1.0.0）
• 三种入口互不依赖：DSH 插件（12 个 fcad_* 工具）、bin/cli.mjs CLI、bin/cli.mjs serve 本地 Web UI

插件以 DSH server 类型注册；@deepseek-ai/dsh-tools 为可选 peer dependency，缺失时可降级为独立 CLI / UI 模式。核心引擎仅依赖 Node 标准库，README 写明无需 npm install 即可跑 CLI 与测试。

设计要点¶

先交代几条与选型相关的约束，便于判断是否匹配你的场景。

1. 声明式、可复现：同一份文档与同一组参数应得到同一模型；每次保存产生不可变修订，历史不覆盖。
2. 精确几何：体积、面积、包围盒、质心、拓扑、有效性校验等来自 OCCT，而非估算；导出为真实 B-rep 相关文件。
3. 只读外部源：import / convert 只读取 STEP / IGES / BREP，不修改源文件。
4. 本地闭环：Web UI 只监听 127.0.0.1，一次性 token、HttpOnly Cookie、CSP，无外部资源与遥测（见 README 安全边界）。
5. 工具命名：Harness 工具统一 fcad_ 前缀，避免与 dsh-cad-design 的 cad_* 冲突。

前置条件¶

探测 freecadcmd 的顺序：DSH_CAD_FREECAD_CMD → 配置项 freecadCmd → 常见安装路径 → PATH。可用 doctor 查看：

node bin/cli.mjs doctor

在仓库根目录执行；若已克隆插件，路径为插件内的 bin/cli.mjs。安装为 DSH 插件后，也可通过 fcad_doctor 工具做同类检查。

安装与启用¶

README 建议使用独立 profile，勿改动日常 desktop / web profile：

dsh profile create cad-dev
dsh plugin --profile cad-dev add dsh-cad-freecad
dsh --profile cad-dev --dump-config

第三步用于确认 compose 配置里已包含 dsh-cad-freecad。社区插件目录在 skillhub.cn，与 DeepSeek / 幻方无官方从属关系；安装前请自行查看源码与 MIT 许可证。插件在当前 dsh 进程权限下运行，配置可通过 cordis.patch.yml 注入（如 timeoutSeconds、maxFeatures、workDir、allowExport 等，均有默认与硬上限，见 README）。

Harness 插件：12 个 fcad_* 工具¶

lib/index.js 向 DSH 注册工具；每个工具带 object-rooted parameters、output.schema，并用 output.render 把结构化结果压成模型可读的短摘要。统一返回信封：成功 { ok: true, ... }，失败 { ok: false, error: { code, message, details } }。

典型智能体流程可以是：fcad_validate → fcad_build → fcad_export 或 fcad_preview，用 fcad_param 做参数迭代。

声明式 DSL 简述¶

模型用 JSON 描述；数值可为有限数字或 $parameter 引用，不支持 "$outer / 2" 这类表达式。features 中形状引用只能指向更早的 feature id；result 必须指向已存在的 feature。默认 units: "mm"，result 可为最后一个 feature。

README 中的垫圈示例（可直接对照 examples/washer.json）：

{
  "schema": "dsh.cad.freecad/document@1",
  "name": "参数化垫圈",
  "units": "mm",
  "parameters": { "outer": 30, "inner": 14, "t": 4 },
  "features": [
    { "op": "cylinder", "id": "outer", "radius": "$outer", "height": "$t" },
    { "op": "cylinder", "id": "bore",  "radius": "$inner", "height": "$t" },
    { "op": "boolean",  "id": "washer", "mode": "cut", "parts": ["outer", "bore"] }
  ],
  "result": "washer"
}

支持 14 类 op（box、cylinder、boolean、hole_pattern、fillet 等），完整约束见仓库 docs/DSL.md 或 CLI：

node bin/cli.mjs schema

examples/ 另有法兰、六角螺母、L 型支架、台阶块等 5 个示例。

独立 CLI 与本地 UI¶

不启动 DSH 时，可直接用 CLI（仍需本机 FreeCAD 参与建模）：

node bin/cli.mjs validate examples/washer.json
node bin/cli.mjs build examples/washer.json --id washer --preview --out drawing.svg
node bin/cli.mjs param washer --set '{"outer":40}'
node bin/cli.mjs export washer --format step --out washer.step

validate 对非法文档返回非零退出码，可用于 CI。常用状态目录默认为 ~/.dsh-cad-freecad，可用 --work-dir 覆盖。

本地浏览器 UI：

node bin/cli.mjs serve --port 8770

控制台会打印带一次性 token 的 http://127.0.0.1:8770/?token=... 地址；界面含 JSON 编辑、示例、参数修改、四视图预览与导出。

导出与几何报告¶

导出含 STEP、IGES、STL、BREP（OCCT）、SVG / DXF（零依赖生成器）、以及带完整几何报告的 JSON。导入仅支持 STEP / IGES / BREP。几何报告字段包括 valid、volume、area、bbox、center_of_mass、topology、checks 及建模步骤轨迹等（见 README 表格）。

适用场景与注意¶

更适合：需要在 DSH 或脚本/CI 中做可复现参数化实体、要把精确度量回传给模型、或要在本机闭环调试 CAD 而不执行任意 Python 的场景。

务必注意：

• 不执行用户代码、不支持 DSL 内表达式——不能替代「任意 FreeCAD 宏」类需求。
• 建模与导出依赖本机 freecadcmd；未安装 FreeCAD 时仍可跑大部分单元测试（README：93 项），真机端到端需设置 DSH_CAD_FREECAD_CMD。
• 插件与 CLI 在操作系统用户权限下读写 workDir 与 artifact；生产环境请核对 cordis.patch.yml 中的上限与 allowExport / allowModelWrite 等开关。

结尾¶

dsh-cad-freecad 用声明式 JSON + 本机 OCCT 把 CAD 能力收成 DSH 可调用的 fcad_* 工具链，并保留不依赖 Harness 的 CLI 与 127.0.0.1 Web UI。进一步细节见 SkillHub 目录页 与 GitHub 仓库 README。