前言¶
在 DSH 里做智能体或脚本开发时，工作区里常会混着机械零件、网格模型和导出文件。.step、.stl 这类资源若只能依赖外部 CAD 或独立查看器，切窗口、找路径会打断上下文。DeepSeek Harness 的插件生态把能力拆成可安装的扩展；dsh-cad-preview 由社区维护者 RichardYZLu 发布，归类为客户端插件，目标是在 DSH 右侧栏直接打开文件树里的 3D 文件，用轨道相机旋转、缩放，并可选线框、网格与坐标指示，而不离开当前 DSH 窗口。
下面介绍它解决什么问题、支持哪些格式、如何安装与日常使用，以及部署在非本机域名时的配置注意点。
这是什么¶
dsh-cad-preview（npm 包名 dsh-cad-preview，仓库 RichardYZLu/dsh-cad-preview）是面向 DSH Web 客户端的 CAD / 网格 3D 模型预览器。打开侧栏支持的扩展名后，侧栏内渲染可交互几何体；可与 dsh-better-sidebar 的文件查看器集成，也可挂到 DSH 自带的文档预览上。社区目录页：skillhub.cn 上的 dsh-cad-preview（与 DeepSeek / 幻方无官方从属，仅为独立插件索引）。
支持的格式与预览信息¶
先做格式区分：B-rep 与 OCCT 原生格式走 OpenCascade（WASM） 在 Worker 里离散；三角网格类走 three.js 各 Loader。
| 格式 | 解析方式 | 说明 |
|---|---|---|
.step .stp |
OpenCascade（WASM） | B-rep 离散：读实体、曲面与单位 |
.iges .igs |
OpenCascade（WASM） | 同上 |
.brep .brp |
OpenCascade（WASM） | OCCT 原生 BREP |
.stl |
three.js STLLoader | 二进制与 ASCII 均可 |
.3mf |
three.js 3MFLoader | 按 OPC 包解析 |
.obj |
three.js OBJLoader | 只取几何，忽略材质 |
.ply |
three.js PLYLoader | ASCII 与二进制均可 |
打开文件后，顶栏会显示：文件大小、包围盒尺寸（mm）、三角面数、解析耗时。
为什么用 Web Worker¶
.step 等 B-rep 解析在 OpenCascade 侧是同步、一口气跑完的，内存需求可达 GB 级。DSH 侧栏与聊天界面共用同一渲染进程；若把这段计算放在主线程，会拖住整个界面。
预览器把 CAD 内核放进 Web Worker（页面 bundle 不含内核，内核在 lib/client.worker.js）。效果是：解析期间仍可滚动、切换标签；关标签页可释放内核内存；取消解析可终止线程；坏文件主要影响该 Worker。OpenCascade WASM 约 7.6 MB，首次使用需从网络加载（失败时可点「重试」，插件也会自动重试一次）。
核心交互与外观¶
鼠标 / 触控板：
- 左键拖动：旋转
- 右键拖动（或 Shift + 左键）：平移
- 滚轮：缩放；触控板与触屏支持双指缩放
工具条与快捷键：
| 按钮 | 快捷键 | 作用 |
|---|---|---|
| 线框 | W |
隐藏面，只画结构线 |
| Z/Y 轴向上 | U |
CAD（Z 向上）与图形（Y 向上）约定切换 |
| 网格 | G |
地面网格 + 坐标轴 |
| 适配 | F |
重新框选模型，不改变当前视角 |
| 重置 | R |
模型居中落地、全部进画面、视角回初始 |
右下角红 X / 绿 Y / 蓝 Z 方向指示器随视角旋转，便于对照模型坐标系。默认外观为 ao+strong（环境光遮蔽 + 约 30° 结构线）；线框模式为 lines，结构线阈值可降到 1° 以保留圆柱侧面折边。
安装与启用¶
前置条件只有 DSH 本身，无其它依赖。装完后需 重启 DSH Desktop，插件在启动时挂载。
| 你的环境 | 挂到哪里 |
|---|---|
装了 dsh-better-sidebar |
注册为其文件查看器（.step 等可直接开标签页） |
| 只有 DSH 自带侧栏 | 注册进 DSH 自带文档预览 |
| 两者都有 | 两处都注册，互不影响 |
从 npm 安装（推荐）：
dsh plugin --profile web add dsh-cad-preview
从 GitHub 安装（须用完整 HTTPS，勿用 github:owner/repo 简写，以免 pnpm 解析为 SSH 导致 Permission denied）：
dsh plugin --profile web add https://github.com/RichardYZLu/dsh-cad-preview
锁定版本可在 URL 后加 #<tag>，例如 https://github.com/RichardYZLu/dsh-cad-preview#v0.3.6；不带 # 则跟随默认分支最新提交。
卸载：
dsh plugin --profile web remove dsh-cad-preview
典型用法¶
- 按上一节命令安装并重启 DSH Desktop。
- 在文件树中点击
.step、.stl等受支持扩展名的文件。 - 在侧栏预览中左键旋转、滚轮缩放，需要对照结构时用
W切线框，用F/R调整取景。 - 若通过隧道或局域网域名访问 GUI 且请求被 403 拒绝，在 profile 的
cordis.patch.yml中为插件配置trustedHosts（见下一节）。
适用场景与注意¶
适合： 在 DSH 工作区内快速核对 STEP/IGES/BREP 与 STL/3MF/OBJ/PLY，不必为看一眼模型单独开 CAD 或浏览器 tab。
权限与安全： 插件以当前 DSH 进程权限运行，会读取你打开的文件并加载远程 WASM 资源。安装前建议浏览 GitHub 仓库 源码与许可：包本身为 MIT；lib/occt-import-js.wasm 含 occt-import-js（MIT）与 OpenCascade Technology（LGPL-2.1 + OCCT exception），详见包内 lib/THIRD-PARTY-NOTICES.md。
非 loopback 域名： 插件路由带 Host 信任栅栏，默认只认 loopback。用例如 dsh.example.com 访问时，需在配置中声明信任域名：
# profile 的 cordis.patch.yml
- id: cad-preview
name: dsh-cad-preview
config:
trustedHosts:
- dsh.example.com
maxModelBytes: 8589934592
已在 DSH 侧给 /api、/sidebar 放行过的域名通常会被自动继承；被拒时响应体会说明被挡域名与应改的配置项。
其它界面提示（摘自 README）： 三角面数超过上限（默认提示中的上限为 12000000）需简化模型或只预览局部；「这个环境没有 Web Worker」表示当前页面无法安全 offload 解析，应在正常 DSH 窗口打开；CAD 解析线程相关错误在确认版本 ≥ 0.3.2 后可尝试重装。
结尾¶
dsh-cad-preview 把 STEP/STP/IGES/BREP 与常见网格格式收进 DSH 侧栏，用 Worker 隔离重型 B-rep 解析，并给出 orbit 相机、线框与坐标辅助。需要安装命令与细节时，以仓库 README 为准：
- 目录页：https://www.skillhub.cn/plugins/RichardYZLu/dsh-cad-preview
- GitHub：https://github.com/RichardYZLu/dsh-cad-preview
