dsh-cad — CAD Plugin for DeepSeek Harness

English | 简体中文

A CAD plugin for DeepSeek Harness (dsh): an embedded 3D/2D CAD viewer plus a native parametric modeling tool family (OCCT kernel) in the Web UI, letting the agent build and inspect CAD geometry step by step — "model while you watch".

Preview

A full modeling session, end to end: the agent builds a parametric assembly from plain chat — a 120×80×8 base plate with R5 rounded corners, then four bolt instances placed at the corners — while the resident CAD panel tracks every step live (parts tree with per-instance colors, ViewCube, "装配体" assembly tab, 5 instances · 1,740 triangles). The finished assembly exports as a structured STEP document and the agent verifies it by reading the file back — 2 solids, 3 products, 2 assembly usages, 1,125.00 mm³:

Downloads

Cumulative downloads from the npm registry, refreshed daily by CI:

Feature Overview

Capability	Description
⚙️ Kernel chain: cadorange → occt.ts	Modeling goes through cadorange (the agent-native CAD runtime wrapping the occt.ts/OCCT WASM; public API + the supported cadorange/occt escape hatch for meshing/HLR/wire construction); the direct occt.ts adapter stays as the fallback tier — DSH_CAD_KERNEL pins one explicitly (the opencascade.js tier was removed in v0.15.1, −64MB install). The old "no editing after shell" seam is gone — fillet/chamfer/boolean keep working after shelling
🔍 CAD viewing	STL / OBJ / STEP / IGES / BREP / DCPRT (3D), DXF / SVG (2D); interactive viewport in the resident right panel (orbit / zoom / wireframe / pan), with a one-line result row in the conversation
🌗 Dark-mode surfaces	Every rendered surface follows the host theme — viewport slab, DXF/drawing strokes, the Three.js grid / XYZ triad / feature edges / default mesh color / sketch overlays, and the ViewCube plate; a theme flip restyles mounted viewers live. Overrides: --dsh-cad-bg, --dsh-cad-stroke, --dsh-cad-paper
🧭 CAD editor interactions	Onshape-style ViewCube (26-zone click-to-orient), hover/click face & edge picking with live measurement (area mm² / length mm), Faces+Edges / Faces / Wireframe render modes, switchable BRep demo parts (bracket / flange / shaft)
🏗️ Parametric modeling	Primitives, profile extrusion, loft, sweep, revolve, booleans, all-edge fillet/chamfer, shell, draft, patterns (linear/circular), transforms; profiles take curve segments (arcs/circles exact BRep; B-splines sampled approximation) — exact OCCT BRep, not a mesh approximation. cad_loft sections accept curves too: point loops, {through} splines or planar {profile} chains; smooth: true fits a periodic B-spline through point loops — one continuous B-spline lateral face instead of planar strips meeting at G0 creases
✏️ Named sketches	Standalone named profiles (Sketch1…) kept in the document (cad_sketch_new / edit / list / delete); extrude/revolve/sweep reference them by name, and cad_sketch_edit rewrites the definition in place + replays the log, rebuilding every dependent feature — the parametric loop. Sketches render as Onshape-style blue curves + plane frame in the viewport (refreshing live on edit), listed in a left-side feature tree (sketches + features, eye-toggle visibility, click-to-highlight bodies) over the Part tab
🗂️ Codex-style document tabs	The resident display panel gets a tab strip with a "+" menu: Part (Part Studio, the default) / Assembly (instance insert/move/remove) / Drawing (true hidden-line sheets); tabs are closable and keep their state
📁 Multi-document file space	Named documents per workspace (.dsh-cad/docs/), each session bound to its own active document — new sessions start empty instead of inheriting leftovers; a folder button in the panel lists every document (preview / delete), and cad_doc_new / cad_doc_open manage the modeling target from chat
📐 Engineering drawings	GB first-angle layout: front / top / left views + isometric, true OCCT hidden-line removal via the occt.ts kernel (an npm dependency, dashed); sheet frame, title block, overall dimensions, standard scale series; exports SVG / DXF
🔗 Constraint solving & motion	Ansatz geometric constraint solver (one command: npm install ansatz-wasm — a wasm dependency, no Rust toolchain, no native binary): entity/constraint modeling (assembly instances ↔ rigid3 poses mapped automatically), solve-with-writeback, full DOF/residual/redundancy/suggestion diagnostics (LLM-oriented), and parametric kinematic sweeps (cad_constraint / cad_solve / cad_motion)
📐 Geometry measurement	Exact volume (mm³), bounding box, triangle counts, DXF layers
📤 On-demand export	STEP (parametric) / STL (mesh); files are written only when the user asks
🖥️ Resident CAD panel	A permanent panel right of the conversation: Codex-style tabs (Part / Assembly / Drawing), tracking the latest model in real time while modeling. A host-independent liveness poll (GET /dsh-cad/docs → per-document op count) keeps the viewport following modeling ops even when the conversation meta pipeline goes stale, and auto-returns from a file preview
⚡ Zero-copy render pipeline	worker mesh → in-memory binary → three.js typed arrays; zero base64 / zero intermediate files / zero per-step disk writes
💾 Modeling document persistence	Operation log (JSON) + debounced disk mirror; automatically replayed to restore state after a process restart
🖼️ Image → profile	PNG sketch/screenshot → Otsu binarization → contour tracing → extrusion-ready polygon (cad_image_profile)
🔌 FreeCAD executor	Run the same op family on an external FreeCAD console (STEP in/out); requires a local FreeCAD install
☁️ Onshape executor	Run the same op family on Onshape over its signed REST API — zero local install; every op compiles to a standard Onshape feature pushed into the target Part Studio (no Feature Studio setup). Readback is three-tier: cheap per-part STL by default, readback: "step" for exact-BRep-derived named meshes via a server-side STEP translation, or readback: "none" — build only and return the document link (~3 calls, quota-friendliest). Exports .stl / .step / .x_t (Parasolid). Quota-aware errors distinguish credential problems from free-plan cooldowns; the Onshape document URL is always surfaced

Installation

The plugin is published to npm — one line:

dsh plugin --profile web add dsh-cad

The installer applies the bundled cordis.patch.yml (declared in the dsh.bundle manifest) automatically, so there is nothing to configure by hand.

Version requirements

• Node.js and dsh CLI (@deepseek-ai/dsh): minimum versions live in the badge row above and the engines field of package.json — kept out of the prose so they never go stale

Install from source (dev mode)

git clone https://github.com/LAU-MARS/dsh-cad.git
cd dsh-cad
npm install && npm run build && npm test   # deps include occt.ts (true-HLR drawing kernel, ~20MB wasm)

npm install -g @deepseek-ai/dsh pnpm
dsh web                                  # let the first launch init the profile, then Ctrl-C

dsh plugin --profile web add /path/to/dsh-cad

dsh web

The patch insert ships as cordis.patch.yml in the package root and is applied by the installer via the same dsh.bundle manifest.

Set DEEPSEEK_API_KEY and you are ready — for example:

• “open bracket.stl” → cad_view
• “model a 100×60×5 plate, punch a ⌀20 hole in the middle, R2 fillets on the four corners, add a ⌀16 boss 20 tall, export plate.step” → cad_create_prim + cad_boolean + cad_fillet + cad_export, with the 3D tab updating live at every step
• “build a snowman” → spheres + a cone nose + a cylinder hat (precise at/axis placement)
• “add two more b1, one rotated 90 degrees” → cad_assembly_insert + cad_assembly_move, the Assembly tab updates live
• “make an A3 drawing of b1 and export dxf” → cad_drawing (three views + iso + dashed hidden lines + dimensions) → cad_export .dxf

Modeling Tool Family

Tool	Description
cad_view	Open a CAD file and render it in the viewer (resident panel)
cad_info	Read-only geometry metadata (format / counts / bounding box / units / layers)
cad_create_prim	Primitives (mm, Z-up); at for placement, axis for orientation (exact axis-angle rotation)
cad_sketch_new	Create a named sketch (Sketch1…): {start, segments} / {circle} / flat points loop — referenced by name from the profile features
cad_sketch_edit	Redefine a sketch (回改): the definition op is rewritten in place and the log replayed — every referencing feature rebuilds
cad_sketch_list	List the document's sketches (name / form / size)
cad_sketch_delete	Delete a sketch (refused while features still reference it)
cad_extrude_profile	Extrude a closed XY-plane profile along +Z into a solid — inline points/segments/circle or a named sketch (sketch)
cad_loft	Loft: skin a solid through successive closed sections (each a [x,y,z,…] loop in its own plane, or a curve/profile section); sections may differ in shape and point count; smooth fits a periodic B-spline through point loops for a crease-free skin; ruled for straight sides
cad_revolve	Solid of revolution: revolve a closed profile around an axis (profile coords = (radius, height); curve segments supported — rounded rims exact); optional angle; accepts a named sketch
cad_chamfer	Chamfer: bevel every sharp edge with one equal distance (mm)
cad_pattern	Pattern: linear (delta spacing) or circular (principal axis + at point + sweep angle); creates copy bodies, fuse afterwards for one body
cad_shell	Shell: hollow to a wall thickness (inward, outer skin preserved); open lists outward normals of the faces to open (empty = sealed). Runs on the occt.ts kernel; the result is a HOSTED body
cad_draft	Draft: tilt the walls angle degrees about a neutral plane (mold release); direction is the pull direction, walls auto-selected by default. Runs on the occt.ts kernel; the result is a HOSTED body
cad_sweep	Sweep: pipe a closed 2D profile along a 3D [x,y,z,…] path; the profile is auto-placed on the start plane, so no manual orientation; accepts a named sketch
cad_boolean	fuse / cut / common (classic hole punching: plate cut cylinder)
cad_fillet	Constant-radius fillet on all sharp edges
cad_transform	Translate / Euler rotate / mirror
cad_volume	Exact BRep volume (mm³)
cad_drawing	Engineering drawing: front/top/left + isometric views, dashed hidden lines, frame, title block, overall dimensions, standard scale, A4/A3
cad_assembly_insert	Insert a body into the assembly as a placed instance (at position, rotate orientation)
cad_assembly_move	Set an instance's absolute placement
cad_assembly_remove	Remove an instance from the assembly (the body stays)
cad_constraint	Declare the constraint model: entities (assembly-instance bindings) + constraints (distance/angle/mate/coaxial…), persisted in the op log
cad_solve	Solve with Ansatz and write poses back; returns DOF/residual/redundancy/suggestion diagnostics
cad_motion	Kinematic sweep: drive one constraint value from from to to, solve frame by frame, apply the last pose, return the motion table
cad_export	Export STEP / STL / DCPRT (the native replayable part document) to a workspace path; target: "assembly" writes the assembly STEP, target: "drawing" writes the sheet as SVG / DXF
cad_delete	Delete a body
cad_docs	List the workspace's modeling documents (id / name / bodies / updated, active marked)
cad_doc_new	Create a named document and make it the session's modeling target (start multi-part projects here)
cad_doc_open	Open an existing document (by id or name) as the session's modeling target — bodies replay exactly
cad_doc_rename	Rename a document
cad_doc_delete	Permanently delete a document (requires confirm: true)
cad_freecad	Run an op program on an external FreeCAD executor (optional STEP input / export)
cad_fusion	Run an op program on an external Fusion 360 executor (GUI bridge; optional export)
cad_onshape	Run an op program on the Onshape cloud (signed REST API): creates or drives a document, returns its URL; readback: "step" for exact BRep meshes; exports .stl / .step / .x_t (Parasolid)
cad_image_profile	PNG → contours → extrusion-ready polygon points
cad_script	Deterministic script evaluation for geometry math (profile point arrays, arc coordinates): js runs in-process (Node vm — works even when the host shell is unavailable), py uses a system Python

After every modeling step: the chat result row updates in place (stable viewId + versioned URL), and the resident panel's "Part" tab tracks the latest model in real time.

Connectors (roadmap)

Modeling runs on the occt.ts kernel via cadorange (OCCT in the browser — zero install). The connectors below refer to external CAD engines acting as executors for the same tool family, planned for future support:

Connector	Suite	Platform	Status
Built-in kernel	CAD modeling kernel based on OCCT + WebGL, runs in the browser — zero install	All platforms (WebGL rendering)	✅ Built-in
FreeCAD	open-source parametric suite — natural local executor via its Python API (console + GUI window modes)	Windows / macOS / Linux	✅ Available (needs local install)
Fusion 360	Autodesk CAD/CAM — resident add-in + spool bridge (no headless; the Fusion window doubles as a viewer)	Windows / macOS	🧪 Experimental (cad_fusion)
SolidWorks	Dassault Systèmes industry-standard 3D CAD, COM/.NET automation	Windows only	🚧 Windows demo scaffold (scripts/solidworks-bridge/)
Onshape	PTC cloud-native SaaS CAD, fully in the browser — signed REST API (cad.onshape.com or chamber hosts); every op compiles to a standard Onshape feature pushed into the Part Studio, results read back as per-part STL + mass properties, the cloud is the viewer	All platforms (browser)	✅ Available (cad_onshape; set DSH_ONSHAPE_ACCESS_KEY / DSH_ONSHAPE_SECRET_KEY)
ZW3D（中望3D）	ZWSOFT all-in-one CAD/CAM	Windows / Linux	🚧 Planned
GstarCAD 3D（浩辰3D）	Gstarsoft 3D CAD	Windows	🚧 Planned

All external engines implement the same GeometryExecutor contract (available() / run(opProgram) → meshes), so the WebGL display layer never changes — swapping a backend changes only the quality of the produced geometry.

Architecture

cad_view(path)                        modeling tools (cad_create_prim, …)
  → import worker (occt-import-js)      → modeling worker (occt.ts WASM via cadorange)
  → CadScene JSON (base64-f32)          → exact BRep geometry + meshing
  → GET /dsh-cad/scene/<id>            → in-memory binary scene (f32/u32 packed)
                                        → GET /dsh-cad/bin/<docId>
            ↓ session presentationMeta (viewId + versioned URL) ↓
        browser card + persistent "3D" tab (three.js / SVG, Z-up, XYZ axes)

• Two workers: import (occt-import-js, read-only STEP/IGES/BREP) and modeling (cadorange over the occt.ts wasm) are separate, both lazily started
• Zero-copy pipeline: modeling scenes use zero base64 / zero large JSON arrays / zero per-step disk writes (disk mirror debounced 1.5s, replayed only on service restart); cad_export is the only explicit file export
• Modeling document: <workspace>/.dsh-cad/model.json operation log; all bodies are restored by replay after a restart
• Drawing HLR kernel: hidden lines run on occt.ts (npm dependency, npm i occt.ts) — true OCCT removal, no fallback engine, a missing kernel is a hard error. Kernel APIs: hiddenLines() true hidden-line removal, byte-level STEP/BRep readStep/readBrep/writeStep/writeBrep without MEMFS, tessellation with built-in feature-edge extraction, and a hasError()/lastError() error contract. Geometry crosses kernels as STEP bytes and the projected segments are remapped into the sheet frame. Kernel dist resolution: DSH_OCCTJS_DIST env var → Node's own resolution of the occt.ts dependency (walks up every parent node_modules — npm/yarn flat and pnpm symlink layouts all hit) → <repo>/../opencascade-ts/dist (sibling checkout) → vendor/ → node_modules/opencascade-ts
• Constraint solving (Ansatz): the solver is the npm dependency ansatz-wasm (a wasm-bindgen build, single package ~538KB, zero deps) — installing dsh-cad pulls it automatically, and npm install ansatz-wasm alone upgrades it. No Rust toolchain, no native binary, platform independent. Resolution: the npm package (node_modules) → a DSH_ANSATZ_WASM directory → a sibling Ansatz checkout's pkg-node. The solver speaks one JSON envelope contract, with tool-layer errors (e.g. unsupported_constraint) surfaced verbatim for the LLM. Assembly placements (translate + XYZ Euler degrees) map bidirectionally to the solver's rigid3 poses (translate + exponential-map rotation, radians). Solver capability is staged (point-distance-to-origin today) — the plumbing contract is finished and needs no changes as it grows
• Kernel chain: modeling goes through cadorange (agent-native CAD runtime; public build123d-style API for prims/curve-segment profiles (TRUE B-spline interpolation)/loft/sweep/revolve/booleans (cleaned by default)/ fillet/chamfer/shell/draft/native mirror/centroid, plus the supported cadorange/occt escape hatch for viewer tessellation, engineering-drawing HLR (zero STEP hops, one wasm session) and wire construction); the direct occt.ts adapter stays as the fallback tier (DSH_CAD_KERNEL pins one; see docs/cadorange-integration.md for the verb-by-verb mapping). Editing after shelling is seamless. Assembly STEP export writes a structured document (cadorange exportStepAssembly): one root product plus one named, placed child per instance — instance separation survives the file (STL stays a single fused mesh). Instance separation stays in the assembly scene/document for the fuse paths. Face selection matches describe() plane normals (outermost along ±normal)
• Client: esbuild single-file CJS factory (three.js inlined ~560KB, react provided by the host module table), Z-up CAD convention, empty scene with XYZ axis labels and a ground grid always displayed

Theming (dark mode)

The viewer follows the host appearance automatically. DSH publishes the theme as color-scheme on <html> plus body[data-ds-dark-theme]; the plugin resolves that (falling back to prefers-color-scheme) and themes every surface the host tokens cannot reach:

• the viewport slab behind the transparent WebGL canvas and 2D scenes,
• default 2D entity strokes (DXF / engineering-drawing entities),
• the Three.js ground grid, XYZ axis triad/labels, feature edges, default mesh color and sketch overlays,
• the ViewCube face plate (canvas texture).

A theme flip restyles mounted cards and the resident panel live — no reload and no lost camera. Engineering drawings loaded as SVG keep a white sheet; in dark mode it is framed as paper on the dark slab instead of filling the viewport.

Hosts can override the surfaces the plugin owns; an explicit definition wins in either theme:

CSS variable	Applies to	Default
--dsh-cad-bg	viewport background (any CSS background value)	light #f5f6f8→#e9ecf0, dark #1b1b1c→#151517
--dsh-cad-stroke	default 2D entity stroke	#4c5561 light / #c8ced6 dark
--dsh-cad-paper	drawing paper behind SVG sheets	#ffffff

:root { --dsh-cad-bg: #0b0d10; }          /* flat canvas in both themes */

Tests

npm test                             # full suite: converters / modeling worker (exact volume assertions) / DCPRT round-trip / FreeCAD + Onshape executors / image profiles / binary pipeline / document persistence
node test/route-check.mjs            # JSON scene routing layer
node test/visual/serve.mjs           # browser card/tab visual verification page (http://127.0.0.1:3987)

Representative assertions covered: the boolean-punched volume exactly equals the analytic value (28429.20 mm³), L-shaped profile extrusion 3000 mm³, volumes and bounding-box flips of sphere/cone/torus placed with at/axis, 8-byte alignment of the binary packing, an STL export round-trip (export → read back by the phase-1 parser), and a DCPRT document round-trip (serialize → replay on the OCCT worker → exact bounds).

Known Limitations

• DWG (closed-source) is unsupported; DXF bulge arcs are approximated by chords; glTF/3MF viewing is not implemented (the structure is reserved)
• cad_fillet is all-edge constant-radius (per-edge selection is unstable under embind); chamfer is not implemented
• Sketch extrusion supports polygon profiles only (arc profiles are constructed by boolean combinations of cylinders/tori)
• dsh framework limitation: an already-mounted single slot (the right-side details panel itself) does not respond to components registered later, so the persistent view is provided as the "3D" view tab (a list slot, the official composition)
• The host reads CAD files via node:fs (the platform fs service supports UTF-8 text only and cannot carry binary data)

Community

QQ Group (🇨🇳 China)	Feishu (🇨🇳 China)	X / Twitter (🌍 International)	Discord (🌍 International)
485038246 (join note: dsh-cad)	🚧 Coming soon	🚧 Coming soon	🚧 Coming soon

Contributors

Auto-generated from the commit history — thanks to everyone who has contributed!

License

MIT