dsh-cad-viewer

dsh plugin --profile web add dsh-cad-viewer

dsh-cad-viewer

把 3D 模型库和完整的 CAD 查看器嵌入 dsh Web GUI：会话区多出一个 「3D模型」tab，agent 用 CadQuery 建好的模型直接落进库里，可在线查看、导出成 10 种 CAD / 网格 / 图纸格式。




npm 包页 · [更新日志](CHANGELOG.md) · [AI 生成声明](#ai-生成声明) · [MIT 许可证](LICENSE)

截图

模型库 —— tab 的默认视图。文件夹、全库搜索、拖拽移动；卡片菜单里有重命名 / 移动到… / 导出 / 删除。图中子菜单头部显示「仅有网格 · 由三角网格重建几何」，因为该条目由 add_3dmodel 创建（没有保存 CadQuery 源码）；build_3dmodel 的条目会显示「已保存 CadQuery 源码 · 导出为精确几何」。

工作台 —— 每个模型一个标签页，挂载上游 three-cad-viewer 的完整界面（工具栏 / 导航树 / 画布），文案已中文化，工具栏上多了 导出 按钮（在 ? 之前）。

这个插件是什么

• 模型库 —— 文件夹、全库搜索、拖拽移动、重命名 / 移动 / 删除，以及 10 种格式导出。
• 工作台 —— 为库中任意模型挂载 three-cad-viewer 完整界面；左 / 右键旋转、中键平移、滚轮缩放。
• 对话内嵌卡片 —— 调用过模型工具的那条消息末尾出现可折叠卡片，全屏 即以工作台打开同一模型。
• 五个 agent 工具 —— add_3dmodel / build_3dmodel（建模入库）、list_3dmodels（读列表）、delete_3dmodel（删条目）、cadquery_env（探测 CadQuery 环境）。
• 服务端存储 —— 一个条目一个 JSON 文件，同一 dsh 实例下所有设备看到同一份库；不用 IndexedDB、不依赖外部服务、没有构建步骤。

安装

三条路等价，装完都要做[启用与验证](#启用与验证)。

从 npm 安装（推荐）

dsh plugin --profile web add dsh-cad-viewer

包页 <https://www.npmjs.com/package/dsh-cad-viewer>。tarball 与仓库源码一致，只含运行所需的文件——lib/、assets/、docs/、cordis.patch.yml、CHANGELOG.md、THIRD-PARTY-NOTICES.md，加上 npm 必含的 package.json / README.md / LICENSE；dev/ 与 screenshots.json 不随包分发。

从 GitHub 或本地目录安装

dsh plugin --profile web add github:CMoyuer/dsh-cad-viewer

git clone https://github.com/CMoyuer/dsh-cad-viewer.git
cd dsh-cad-viewer && pnpm install
dsh plugin --profile web add .

dsh plugin add 会在 profile 目录里执行 pnpm，再按实际安装结果校正 dsh.profile.bundles——声明了 dsh.bundle 的包自动进插件层，不用手工编辑。插件目录不在 profile 下时请用绝对路径。

启用与验证

服务端插件只在启动时加载，改完要重启 dsh web。

dsh --profile web --dump-config    # 组合树里应出现 id: cad-viewer
curl -s -o /dev/null -w "%{http_code} %{content_type}\n" http://127.0.0.1:3080/3dmodel/api/items
curl -s -o /dev/null -w "%{http_code} %{content_type}\n" http://127.0.0.1:3080/tcv/three-cad-viewer.esm.min.js

期望 200 application/json; charset=utf-8 与 200 text/javascript; charset=utf-8。路由缺失时不是 404——SPA fallback 会返回 200 text/html，所以要看 content-type，不能只看状态码。之后刷新 GUI，打开 3D模型 tab（在「画廊」之后）。

用法

模型库

agent 生成的模型会立刻出现（按创建时间排序）；点卡片即在工作台打开。

操作 · 方式

打开模型 · 点击卡片

重命名 · 双击名称，或 ⋯ → 重命名

移动 · 拖到目标文件夹（或「返回上一级」），或 ⋯ → 移动到…

导出 · ⋯ → 悬停「导出」（右键卡片后悬停或点击同样可以），再选格式

删除 · ⋯ → 删除

新建文件夹 · 在模型库面板空白处右键 → 新建文件夹（右键卡片会自动收起它）

搜索 · 搜索框（全库）

返回上一层 · 「返回上一级」卡片，或把卡片拖到它上面

右键卡片时菜单在鼠标位置弹出。删除文件夹不会删除内容：其中的模型与子文件夹上移一层。

库也可以交给 agent 操作：list_3dmodels 读回条目与 id，delete_3dmodel 删条目（见 [Agent 工具](#agent-工具)）。

导出

同一个格式子菜单出现在两处：模型库卡片的 ⋯ → 导出，以及工作台工具栏的 导出 按钮（在 ? 之前）。

分组 · 格式

精确几何 · STEP .step、BREP .brep

网格 · STL .stl、3MF .3mf、AMF .amf、VRML .wrl、VTP .vtp、TJS .json

二维图纸 · SVG .svg、DXF .dxf

导出什么，取决于该条目有没有保存 CadQuery 源码（子菜单顶部会写明是哪种）：

• 保存过源码的条目（build_3dmodel 创建）：重跑脚本再交给 CadQuery 自己的 exporter，STEP / BREP 是真正的实体，文件也小。
• 只有网格的条目（add_3dmodel 创建，或旧版本入库）：由三角网格重建。STEP / BREP 把每个三角面做成平面片再缝合成壳——CAD 能打开，但表面是面片化的，文件也大（约 1 万面 → 约 20 MB）；网格格式则与查看器里看到的三角形完全一致。SVG 用「轮廓 + 特征边」投影（对三角面汤做隐藏线消除要几分钟，因此不做）。

导出在服务端串行执行，界面有进度对话框（可点「后台继续」，下载仍会完成）。单次上限由 cadqueryExportTimeout 控制（默认 5 分钟）。

工作台与内嵌卡片

每个模型一个标签页，× 关闭并回到模型库。查看器的工具栏与导航树与上游一致，区别是：Pin as PNG 按钮被移除、文案中文化、多一个 导出 按钮。

某轮对话调用过模型工具时，消息末尾出现可折叠卡片：左侧标题，收起 折叠，全屏 在工作台打开同一模型；加载失败会显示重试入口。删除库里的条目不会清空已经渲染出来的卡片。

Agent 工具

工具 · 作用

add_3dmodel · 把 three-cad-viewer Shape（cad-format JSON）存入模型库，并在消息末尾渲染内嵌卡片。

build_3dmodel · 运行 CadQuery 脚本，tessellate 后入库，并保存脚本（上限 256 KB）以便日后导出精确几何。装配体会拆成每个零件一个树节点，可单独显示/隐藏。

list_3dmodels · 只读读回模型库：id、标题、所属文件夹路径、入库时间、零件/三角面数、是否存了 CadQuery 源码，以及文件夹清单。支持 query（标题/名称/id 子串）、folder（文件夹 id、名称或路径片段；/ 表示根目录）、limit（默认 100，上限 500）。

delete_3dmodel · 从模型库删除条目（连同网格与已保存的 CadQuery 源码，没有撤销）。用 id 精确删除，或用 title 精确匹配（忽略大小写与首尾空格）；标题匹配到多条时一条都不删，而是把候选列回来，确认后才用 all: true 全删。文件夹本身不受影响。

cadquery_env · 只读探测 CadQuery 环境（解释器是否在、四个包能否导入），并给出补齐缺口的准确命令。

// add_3dmodel：model 是 { version, parts[] }，每个 part 带 shape:{ vertices, triangles, normals, edges }
{ "model": { /* … */ }, "title": "Bracket", "height": 320 }

// build_3dmodel：脚本必须 import cadquery as cq 并给 model 赋值
{ "script": "import cadquery as cq\nmodel = cq.Workplane('XY').box(20, 20, 10)", "title": "Box", "tolerance": 0.1 }

// list_3dmodels：不带参数就是整个库；下面的写法只看「零件」文件夹里标题含“齿轮”的前 10 条
{ "query": "齿轮", "folder": "零件", "limit": 10 }

// delete_3dmodel：id 与 title 都给时会互相校验，对不上就不删
{ "id": "8fb74096-b054-4a49-b4d4-6bd5a6e6f804", "title": "支架" }

• 去重键是「几何 + 标题」：相同几何 + 相同标题再存一次只会更新原条目，不会多出第二条。
• 标题不唯一：add_3dmodel 的去重键包含几何，所以几何不同的模型可以同名。按标题删除前先用 list_3dmodels 看清楚有几条。
• 改现有模型必须先问用户：用户要求修改库里已有的模型时，agent 要先问是替换原条目、还是保留原条目并另存一份副本。注意同标题重存不等于替换——去重键是「几何 + 标题」，几何一变就会多出一条、原条目原样保留；替换的正确顺序是先存修改版，再按 id 删掉旧条目（中间失败也不会丢东西）。这条约定写在 add_3dmodel 与 build_3dmodel 的工具描述里，delete_3dmodel 的描述也指明它是替换的后半步。
• build_3dmodel 的 model 必须是带 .tessellate() 的 cq.Workplane / cq.Shape；装配体

…(truncated)