前言¶
在 DeepSeek Harness（DSH）工作区中直接查看 STL 模型，能省去在 Blender 或切片软件间切换的时间。dsh-preview-stl 插件为 DSH 增加了一个文档预览渲染器，点击 .stl 文件即可在右侧边栏渲染出交互式 3D 视口，并输出打印统计信息。
插件定位¶
dsh-preview-stl 是一个客户端插件，由用户 439436269-ctrl 维护。它解决的问题是：在本地浏览器中解析 STL 网格文件，无需上传、无需后端转换、无需额外切片软件，直接查看模型尺寸、体积、表面积和密封性。
核心功能¶
1. 文档预览渲染器¶
插件注册了一个 .stl 文件的预览渲染器。在 Workspace 文件列表中点击 STL 文件，右侧边栏会加载渲染视图。
2. 浏览器端解析¶
STL 文件流经经过身份验证的 /api/preview/stl 路由，在浏览器中完成解析：
- 二进制 STL：80 字节头部 + uint32 三角形计数 + 每个 50 字节的三角形数据
- ASCII STL：遵循标准语法的 facet normal / outer loop / vertex 格式
文件不会上传到服务器，也不会在宿主机上转换。
3. 交互式 WebGL 视口¶
使用与 dsh-preview-blender 相同的依赖-free WebGL 查看器，支持以下操作：
- 轨道旋转（orbit）
- 平移（pan）
- 滚轮缩放
- 双击重置视角
- 线框模式切换
- 自动旋转
- 接触阴影
- 三色轴三角架
STL 默认为 Z-up 坐标系，渲染前会旋转到 Y-up 视口坐标系。
4. 打印统计信息¶
插件在解析后报告以下数据：
- 文件格式（二进制 / ASCII + 头部信息）
- 文件大小
- 三角形数量
- 焊接顶点数量
- 边界框尺寸（毫米）
- 体积（立方厘米）
- 表面积（平方厘米）
- 密封性：边界边、非流形边、退化面
密封性计算通过在网格上焊接顶点并统计边使用次数完成。如果三角形数量超过 analysisMaxTriangles（默认 400,000），会跳过密封性检查以避免卡顿。
5. 单位转换¶
STL 文件本身是无单位的。插件通过 unitScale 配置项将 STL 单位映射到毫米：
unitScale = 1：假设 STL 单位为毫米（默认）unitScale = 10：假设 STL 单位为厘米unitScale = 25.4：假设 STL 单位为英寸
该配置会影响尺寸、体积和表面积的显示值。
安装与启用¶
插件安装命令如下：
dsh plugin --profile <profile> add dsh-preview-stl
安装后，插件会自动注册渲染器和路由，配置项可在设置 → 插件 → STL preview 中调整。
配置项¶
| 键 | 默认值 | 说明 |
|---|---|---|
enabled |
true |
注册渲染器和路由 |
routePath |
/api/preview/stl |
认证网格路由路径，必须位于 /api 下 |
extensions |
["stl"] |
触发 3D 预览的文件后缀 |
maxBytes |
536870912 |
最大可流式传输的 STL 大小（512 MiB） |
chunkBytes |
1048576 |
主机端分块读取的字节数 |
unitScale |
1 |
STL 单位到毫米的映射 |
color |
#c7d2e2 |
视口颜色（STL 不携带材质） |
analysisMaxTriangles |
400000 |
超过此值跳过密封性检查 |
适用场景¶
- 在 DSH 中快速浏览 STL 模型，检查几何完整性
- 获取模型的打印前统计信息（尺寸、体积、表面积）
- 在无额外软件的本地环境中查看 3D 模型
注意事项¶
- 插件依赖 DSH 0.2.x 版本（已验证兼容
0.2.0-rc.2和0.2.1-rc.2） - 需要浏览器支持 WebGL（桌面应用默认具备）
- ASCII STL 中超出标准语法的顶点颜色或面属性不会被解析
- 非常大的模型（数百万三角形）会在主线程解析，可能需要片刻；密封性检查会自动跳过
- 插件以当前 DSH 进程权限运行，安装前建议检查源码与许可证（MIT）
生态背景¶
DeepSeek Harness 的设计理念是「一切皆插件」。dsh-preview-stl 是社区维护的插件，通过 DSH 插件目录分发，与 DeepSeek 或幻方无官方从属关系。
