dsh-cad 0.2.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,190 @@
+# dsh-cad — CAD Plugin for DeepSeek Harness
+
+![dsh-cad banner](docs/img/banner.svg)
+
+[![homepage](https://img.shields.io/badge/homepage-dsh--cad-4D6BFE)](https://lau-mars.github.io/dsh-cad/)
+[![dsh plugin](https://img.shields.io/badge/dsh-plugin-4D6BFE)](https://github.com/deepseek-ai/deepseek-harness)
+[![Node](https://img.shields.io/badge/node-%3E%3D%2022-4D6BFE)](https://nodejs.org/)
+[![OCCT](https://img.shields.io/badge/kernel-OCCT-4D6BFE)](https://github.com/donalffons/opencascade.js)
+[![License: MIT](https://img.shields.io/badge/license-MIT-4D6BFE)](./LICENSE)
+
+English | [简体中文](./README.zh-CN.md)
+
+A CAD plugin for [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness):
+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
+
+The CAD editor at startup: the demo L-bracket parsed from the packaged
+`demo-bracket.brep` by OCCT — face + edge rendering, hover measurement of the
+picked face (4,800 mm²), a ViewCube navigation cube in the corner, and
+switchable demo parts (bracket / flange / shaft):
+
+![dsh-cad CAD editor](docs/img/bracket-preview.png)
+
+## Feature Overview
+
+| Capability | Description |
+| --- | --- |
+| 🔍 CAD viewing | STL / OBJ / STEP / IGES / BREP / DCPRT (3D), DXF / SVG (2D); interactive in-chat card (orbit / zoom / wireframe / pan) |
+| 🧭 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 (box/cylinder/sphere/cone/torus), profile extrusion, booleans (fuse/cut/common), all-edge fillet, transforms (translate/rotate/mirror) — exact OCCT BRep, not a mesh approximation |
+| 🗂️ 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 |
+| 📐 Engineering drawings | GB first-angle layout: front / top / left views + isometric, mesh-projected hidden-line removal (dashed), sheet frame, title block, overall dimensions, standard scale series; exports SVG / DXF |
+| 📐 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 |
+| ⚡ 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 |
+
+## Installation (dev mode)
+
+```sh
+git clone https://github.com/LAU-MARS/dsh-cad.git
+cd dsh-cad
+npm install && npm run build && npm test
+
+npm install -g @deepseek-ai/dsh@^0.1.1-rc.2 pnpm   # requires Node ≥ 22
+dsh web                                  # let the first launch init the profile, then Ctrl-C
+
+dsh plugin --profile web add /path/to/dsh-cad
+
+# append to ~/.dsh/profiles/web/cordis.patch.yml:
+#   - insert:
+#       - id: dsh-cad
+#         name: 'dsh-cad'
+
+dsh web
+```
+
+### Version requirements
+
+- **Node.js** ≥ 22
+- **dsh CLI** (`@deepseek-ai/dsh`): this plugin is developed against **0.1.0-rc.7**
+  (minimum supported version, declared in the `engines` field of `package.json`);
+  recommended **≥ 0.1.1-rc.2** (verified 2026-08-31)
+
+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 an interactive viewer card |
+| `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_extrude_profile` | Extrude a closed XY-plane polygon along +Z into a solid |
+| `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_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_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_image_profile` | PNG → contours → extrusion-ready polygon points |
+
+After every modeling step: **the same viewer card refreshes in place** (stable viewId +
+versioned URL), and the "3D" tab tracks the latest model in real time.
+
+## Connectors (roadmap)
+
+Modeling today runs on the **built-in WebGL-class kernel** (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 | cloud-native SaaS CAD, fully in the browser | All platforms (browser) | 🚧 Planned |
+| 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 (opencascade.js WASM)
+  → 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
+  (opencascade.js 1.1.1, full OCCT) are separate, both lazily started; the `_N`
+  suffix convention of embind overloaded constructors is wrapped in
+  `src/modeling/occt-adapter.cjs` (all verified at runtime)
+- **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
+- **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
+
+## Tests
+
+```sh
+npm test                             # 41 tests: converters / modeling worker (exact volume assertions) / DCPRT round-trip / FreeCAD executor / image profiles / binary pipeline
+node test/m0-kernel-check.cjs        # OCCT kernel API smoke test
+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)
+
+## Contributors
+
+Auto-generated from the commit history — thanks to everyone who has contributed!
+
+[![Contributors](https://contrib.rocks/image?repo=LAU-MARS/dsh-cad)](https://github.com/LAU-MARS/dsh-cad/graphs/contributors)
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,173 @@
+# dsh-cad — CAD Plugin for DeepSeek Harness
+
+![dsh-cad banner](docs/img/banner.svg)
+
+[![homepage](https://img.shields.io/badge/homepage-dsh--cad-4D6BFE)](https://lau-mars.github.io/dsh-cad/)
+[![dsh plugin](https://img.shields.io/badge/dsh-plugin-4D6BFE)](https://github.com/deepseek-ai/deepseek-harness)
+[![Node](https://img.shields.io/badge/node-%3E%3D%2022-4D6BFE)](https://nodejs.org/)
+[![OCCT](https://img.shields.io/badge/kernel-OCCT-4D6BFE)](https://github.com/donalffons/opencascade.js)
+[![License: MIT](https://img.shields.io/badge/license-MIT-4D6BFE)](./LICENSE)
+
+[English](./README.md) | 简体中文
+
+[DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) 的 CAD 插件：
+在 Web UI 中提供**内嵌 3D/2D CAD 查看器**与**原生参数化建模工具族**（OCCT 内核），
+让 agent 能够"边建边看"地完成 CAD 工作。
+
+## 预览
+
+启动即见的 CAD 编辑器：示例 L 型支架由内置的 `demo-bracket.brep` 经 OCCT
+解析渲染——面 + 边显示模式、悬停即测（拾取面 4,800 mm²）、角落 ViewCube
+导航块、支架 / 法兰 / 轴三种示例件一键切换：
+
+![dsh-cad CAD 编辑器](docs/img/bracket-preview.png)
+
+## 功能总览
+
+| 能力 | 说明 |
+| --- | --- |
+| 🔍 CAD 查看 | STL / OBJ / STEP / IGES / BREP / DCPRT（3D），DXF / SVG（2D），对话内嵌交互卡片（轨道旋转 / 缩放 / 线框 / 平移） |
+| 🧭 CAD 编辑器交互 | Onshape 风格 ViewCube（26 区域点击定向）、悬停/点选面与边实时测量（面积 mm² / 长度 mm）、面+边 / 面 / 线框三种渲染模式、支架 / 法兰 / 轴 BRep 示例件一键切换 |
+| 🏗️ 参数化建模 | 基本体（box/cylinder/sphere/cone/torus）、轮廓拉伸、布尔（fuse/cut/common）、全边圆角、变换（平移/旋转/镜像）—— OCCT 精确 BRep，非网格近似 |
+| 🗂️ Codex 式文档页签 | 右侧显示区页签栏 + 「+」菜单：**零件**（Part Studio，默认）/ **装配体**（实例插入/移动/移除）/ **工程图**（真实隐藏线图纸），页签可关闭、常驻不丢状态 |
+| 📐 工程图 | GB 第一角布局：主视图 / 俯视图 / 左视图 + 轴测图，网格投影隐藏线消除（虚线）、图框、标题栏、总尺寸标注、标准比例系列；导出 SVG / DXF |
+| 📐 几何测量 | 精确体积（mm³）、包围盒、三角统计、DXF 图层 |
+| 📤 按需导出 | STEP（参数化）/ STL（网格），仅在用户要求时写文件 |
+| 🖥️ 常驻 CAD 显示区 | 会话页右侧常驻面板：Codex 式页签（零件 / 装配体 / 工程图），建模时实时跟踪最新模型 |
+| ⚡ 直通渲染管道 | worker 网格 → 内存二进制 → three.js typed-array，零 base64 / 零中间文件 / 零每步落盘 |
+| 💾 建模文档持久化 | 操作日志（JSON）+ 防抖磁盘镜像，进程重启后自动重放恢复 |
+| 🖼️ 图片 → 轮廓 | PNG 草图/截图 → Otsu 二值化 → 轮廓追踪 → 可直接拉伸的多边形（`cad_image_profile`） |
+| 🔌 FreeCAD 执行器 | 在外部 FreeCAD 控制台运行同一 op 族（STEP 输入/输出闭环）；需本地安装 |
+
+## 安装（开发模式）
+
+```sh
+git clone https://github.com/LAU-MARS/dsh-cad.git
+cd dsh-cad
+npm install && npm run build && npm test
+
+npm install -g @deepseek-ai/dsh@^0.1.1-rc.2 pnpm   # 需要 Node ≥ 22
+dsh web                                  # 首次启动初始化 profile 后 Ctrl-C
+
+dsh plugin --profile web add /path/to/dsh-cad
+
+# ~/.dsh/profiles/web/cordis.patch.yml 追加：
+#   - insert:
+#       - id: dsh-cad
+#         name: 'dsh-cad'
+
+dsh web
+```
+
+### 版本要求
+
+- **Node.js** ≥ 22
+- **dsh CLI**（`@deepseek-ai/dsh`）：本项目开发基于 **0.1.0-rc.7**
+  （最低支持版本，已在 `package.json` 的 `engines` 字段声明）；
+  建议 **≥ 0.1.1-rc.2**（2026-08-31 实测通过）
+
+设置 `DEEPSEEK_API_KEY` 后对话即可使用，例如：
+
+- “打开 bracket.stl 看看” → `cad_view`
+- “画一个 100×60×5 的板，中间打 ⌀20 孔，四角 R2 圆角，加 ⌀16 高 20 凸台，导出 plate.step”
+  → `cad_create_prim` + `cad_boolean` + `cad_fillet` + `cad_export`，每步 3D 页签实时更新
+- “堆一个雪人” → 球体 + 圆锥鼻子 + 圆柱帽子（`at`/`axis` 精确定位）
+- “再放两个 b1，一个转到 90 度” → `cad_assembly_insert` + `cad_assembly_move`，装配体页签实时更新
+- “给 b1 出一张 A3 工程图，导出 dxf” → `cad_drawing`（三视图 + 轴测 + 虚线隐藏线 + 尺寸标注）→ `cad_export` `.dxf`
+
+## 模型工具族
+
+| 工具 | 说明 |
+| --- | --- |
+| `cad_view` | 打开 CAD 文件，渲染交互式查看器卡片 |
+| `cad_info` | 只读几何元信息（格式/数量/包围盒/单位/图层） |
+| `cad_create_prim` | 基本体（mm，Z-up），`at` 定位、`axis` 定向（精确轴角旋转） |
+| `cad_extrude_profile` | XY 平面闭合多边形沿 +Z 拉伸成实体 |
+| `cad_boolean` | fuse / cut / common（经典打孔：plate cut cylinder） |
+| `cad_fillet` | 全锐边等半径圆角 |
+| `cad_transform` | 平移 / 欧拉旋转 / 镜像 |
+| `cad_volume` | 精确 BRep 体积（mm³） |
+| `cad_drawing` | 工程图：主/俯/左 + 轴测四视图，隐藏线（虚线）、图框、标题栏、总尺寸、标准比例，A4/A3 |
+| `cad_assembly_insert` | 将零件以实例插入装配体（`at` 定位、`rotate` 定向） |
+| `cad_assembly_move` | 设置实例绝对位置/姿态 |
+| `cad_assembly_remove` | 从装配体移除实例（零件保留） |
+| `cad_export` | 导出 STEP / STL / DCPRT（原生可重放零件文档）到工作区路径；`target: "assembly"` 导出装配体 STEP，`target: "drawing"` 导出工程图 SVG / DXF |
+| `cad_delete` | 删除 body |
+| `cad_freecad` | 在外部 FreeCAD 执行器上运行 op 程序（可选 STEP 输入/导出） |
+| `cad_fusion` | 在外部 Fusion 360 执行器上运行 op 程序（GUI 桥；可选导出） |
+| `cad_image_profile` | PNG → 轮廓 → 可直接拉伸的多边形点集 |
+
+每步建模后：**同一查看器卡片原地刷新**（稳定 viewId + 版本化 URL），
+"3D" 页签实时跟踪最新模型。
+
+## 连接器（规划中）
+
+建模目前已由**内置的 WebGL 级建模器**承担（浏览器内的 OCCT 内核，零安装）；
+下表连接器指未来以**外部 CAD 引擎作为执行器**驱动同一工具族：
+
+| 连接器 | 套件 | 平台 | 状态 |
+| --- | --- | --- | --- |
+| **内置内核** | 基于 OCCT + WebGL 的 CAD 建模内核，浏览器内运行——零安装 | 全平台（WebGL 渲染） | ✅ 内置 |
+| FreeCAD | 开源参数化套件——可经其 Python API 作为本地执行器（控制台 + GUI 窗口双模式） | Windows / macOS / Linux | ✅ 可用（需本地安装） |
+| Fusion 360 | Autodesk CAD/CAM——常驻 Add-In + spool 桥（无 headless，Fusion 窗口即查看器） | Windows / macOS | 🧪 实验性（`cad_fusion`） |
+| SolidWorks | 达索系统的主流 3D CAD，COM/.NET 自动化 | 仅 Windows | 🚧 Windows demo 脚手架（`scripts/solidworks-bridge/`） |
+| Onshape | 云原生 SaaS CAD，完全在浏览器中 | 全平台（浏览器） | 🚧 规划中 |
+| 中望3D（ZW3D） | 中望软件的一体化 CAD/CAM | Windows / Linux | 🚧 规划中 |
+| 浩辰3D | 浩辰软件的 3D CAD | Windows | 🚧 规划中 |
+
+所有外部引擎实现同一 **GeometryExecutor 契约**（`available()` / `run(op程序) → 网格`），
+WebGL 显示层因此永不改变——更换后端只影响生成几何的质量。
+
+## 架构
+
+```
+cad_view(path)                        建模工具（cad_create_prim 等）
+  → 导入 worker（occt-import-js）       → 建模 worker（opencascade.js WASM）
+  → CadScene JSON（base64-f32）         → BRep 精确几何 + 网格化
+  → GET /dsh-cad/scene/<id>            → 内存二进制场景（f32/u32 打包）
+                                        → GET /dsh-cad/bin/<docId>
+            ↓ 会话 presentationMeta（viewId + 版本化 URL）↓
+        浏览器卡片 + 常驻 "3D" 页签（three.js / SVG，Z-up，XYZ 轴）
+```
+
+- **两个 worker**：导入（occt-import-js，只读 STEP/IGES/BREP）与建模（opencascade.js 1.1.1，
+  完整 OCCT）分离，均惰性启动；embind 重载构造器的 `_N` 后缀约定封装在
+  `src/modeling/occt-adapter.cjs`（全部经运行时实证）
+- **直通管道**：建模场景零 base64 / 零 JSON 大数组 / 零每步落盘（磁盘镜像 1.5s 防抖，
+  仅服务重启回放）；`cad_export` 是唯一的显式文件导出
+- **建模文档**：`<workspace>/.dsh-cad/model.json` 操作日志，重启后重放恢复全部 body
+- **客户端**：esbuild 单文件 CJS 工厂（three.js 内联 ~560KB，react 由宿主模块表提供），
+  Z-up CAD 惯例，带 XYZ 轴标签与地面网格的空场景常驻显示
+
+## 测试
+
+```sh
+npm test                             # 41 项：转换器 / 建模 worker（体积精确断言）/ DCPRT 往返 / FreeCAD 执行器 / 图片轮廓 / 二进制管道 / 文档持久化
+node test/m0-kernel-check.cjs        # OCCT 内核 API 冒烟
+node test/route-check.mjs            # JSON 场景路由层
+node test/visual/serve.mjs           # 浏览器卡片/页签视觉验证页（http://127.0.0.1:3987）
+```
+
+覆盖的代表性断言：布尔打孔体积精确等于解析值（28429.20 mm³）、L 型轮廓拉伸
+3000 mm³、球/锥/环带 `at`/`axis` 定位的体积与包围盒翻转、二进制打包 8 字节对齐、
+STL 导出往返（导出 → 一期解析器读回），以及 DCPRT 文档往返
+（序列化 → OCCT worker 重放 → 精确包围盒）。
+
+## 已知限制
+
+- DWG（闭源）不支持；DXF bulge 弧以弦线近似；glTF/3MF 查看未实现（结构已预留）
+- `cad_fillet` 为全边等半径（embind 下按边选择不稳定）；chamfer 未实现
+- 草图拉伸仅支持多边形轮廓（圆弧轮廓用布尔组合圆柱/圆环构造）
+- dsh 框架限制：已挂载的 single 槽（右侧 details 面板本体）不响应后注册组件，
+  故常驻显示区以 "3D" 视图页签提供（list 槽，官方组合方式）
+- 宿主读取 CAD 文件使用 node:fs（平台 fs 服务仅支持 UTF-8 文本，无法承载二进制）
+
+## 贡献者
+
+由提交历史自动生成，感谢每一位贡献者！
+
+[![Contributors](https://contrib.rocks/image?repo=LAU-MARS/dsh-cad)](https://github.com/LAU-MARS/dsh-cad/graphs/contributors)
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-cad
+      name: 'dsh-cad'

package/lib/b64.js

@@ -0,0 +1,12 @@
+/**
+ * Base64 codecs for typed arrays. Node (host) encodes; the browser card
+ * decodes. Kept dependency-free on both sides.
+ */
+/** Encode a Float32Array's buffer as base64 (Node, host side). */
+export function encodeF32B64(array) {
+    return Buffer.from(array.buffer, array.byteOffset, array.byteLength).toString('base64');
+}
+/** Encode a Uint32Array's buffer as base64 (Node, host side). */
+export function encodeU32B64(array) {
+    return Buffer.from(array.buffer, array.byteOffset, array.byteLength).toString('base64');
+}

package/lib/cad_connector/builtin-executor.js

@@ -0,0 +1,55 @@
+import { createModelClient } from '../modeling/client.js';
+function workerMeshToExecutorMesh(mesh) {
+    return {
+        bodyId: mesh.bodyId ?? mesh.name,
+        name: mesh.name,
+        positions: mesh.positions,
+        normals: mesh.normals,
+        indices: mesh.indices,
+        vertexCount: mesh.vertexCount,
+        triangleCount: mesh.triangleCount,
+    };
+}
+/** The shared WASM kernel always exists in this build. */
+export const BUILTIN_EXECUTOR = {
+    id: 'builtin',
+    label: 'Built-in OCCT kernel',
+    available: () => true,
+    run(program) {
+        return runOnIsolatedWorker(program);
+    },
+};
+async function runOnIsolatedWorker(program) {
+    const client = createModelClient();
+    try {
+        if (program.input !== undefined) {
+            throw new Error('the built-in executor does not load input files (use the cad_view/cad_freecad paths)');
+        }
+        const volumes = {};
+        let exported;
+        await client.run({ kind: 'reset' });
+        for (const op of program.ops) {
+            const kind = String(op.kind);
+            if (kind === 'volume') {
+                const result = await client.run({ kind: 'volume', target: String(op.target) });
+                if (result.volume !== undefined)
+                    volumes[String(op.target)] = result.volume;
+            }
+            else if (kind === 'export') {
+                const result = await client.run({ kind: 'export', target: String(op.target), format: (op.format ?? 'stl') });
+                // The worker writes into its WASM filesystem; the export path is
+                // surfaced by the cad_export tool path, not here.
+                exported = result.bytes !== undefined ? String(op.path ?? '') : undefined;
+            }
+            else {
+                await client.run(op);
+            }
+        }
+        const tessellated = await client.run({ kind: 'tessellate_all' });
+        const meshes = (tessellated.meshes ?? []).map(workerMeshToExecutorMesh);
+        return { meshes, volumes, exported };
+    }
+    finally {
+        client.dispose();
+    }
+}

package/lib/cad_connector/builtin.js

@@ -0,0 +1,8 @@
+export const BUILTIN_CONNECTOR = {
+    id: 'builtin',
+    label: 'Built-in kernel (OCCT + WebGL)',
+    vendor: 'dsh-cad',
+    language: 'webgl',
+    status: 'built-in',
+    binding: 'opencascade.js 1.1.1 WASM worker; three.js typed-array rendering, zero install',
+};