前言¶

在 DeepSeek Harness（DSH）里做智能体或脚本开发时，工作区里常会堆着 .stl 模型：零件原型、扫描网格、切片前的中间体。以往要在 DSH 里看模型，往往要切到外部查看器或切片软件，尺寸、体积、是否水密也得另算。下面介绍的 dsh-stl-preview 把 STL 注册为文档预览类型：在 Workspace files 里点选文件，右侧 Sidebar 即出现可交互的 3D 视口，并附带尺寸、体积、表面积与水密性等数值，解析在浏览器内完成，不依赖 Blender、切片器或额外网络上传。

这是什么¶

dsh-stl-preview 由维护者 439436269-ctrl 发布，分类为客户端插件。它为 .stl 注册文档预览渲染器，通过经认证的 /api/stl-preview 路由把文件字节流式读到前端，在页面里解析二进制与 ASCII STL，用无额外依赖的 WebGL 视口绘制三角网格，并输出与 3D 打印相关的统计量。视口交互与 dsh-blend-preview 同源：轨道旋转、平移、滚轮缩放、双击复位、线框、自动旋转、接触阴影与坐标轴。

核心功能¶

文档预览与数据流¶

1. 在 Workspace files 中点击 .stl 文件，右侧 Sidebar 的 document preview 打开该文件。
2. 客户端请求 GET /api/stl-preview?path=…，由主机按块读取原始字节（默认每块 1 MiB），连接服务在读取前完成认证（Host/Origin 与 session cookie）。
3. 浏览器内 parseStl 解析网格；不将文件上传到第三方，也不在主机上做格式转换。

3D 视口¶

• STL 约定为 Z 轴向上，绘制前旋转到视口使用的 Y-up。
• 支持 orbit、pan、滚轮 zoom、双击 reset、wireframe、auto-rotate、contact shadow、axis triad。
• 默认网格颜色 #c7d2e2（STL 本身不带材质），可在配置中修改。

统计与分析¶

插件在面板中报告：

体积采用有符号四面体求和（|Σ v0·(v1×v2)/6|），面积为三角面面积之和。三角面数超过 analysisMaxTriangles（默认 400000）时跳过水密性分析，界面会说明原因，避免大网格卡死标签页。

无单位 STL¶

STL 文件不带长度单位。通过 unitScale 指定「每个 STL 单位对应多少毫米」：默认 1 表示按毫米理解；若模型以厘米建模可设为 10，英寸可设为 25.4。尺寸、体积与面积均受此缩放影响。

环境与要求¶

• DeepSeek Harness 0.2.x；包内声明与 0.2.0-rc.2、0.2.1-rc.2 兼容。
• 浏览器或桌面端需具备 WebGL（DSH 桌面应用通常已满足）。
• 插件包要求 Node >= 22（开发与构建）；运行侧不依赖 Node 做预览。
• 当前 npm 包版本 0.1.0，许可证 MIT。

安装与启用¶

在对应 profile 下执行官方安装命令：

dsh plugin --profile <profile> add dsh-stl-preview

桌面 profile 由 Electron 应用管理：可在插件管理 UI 中安装，或手动写入 compose 后重启。包内附带 cordis.patch.yml，插件行会自动合并进配置。

在 Settings → Plugins → STL preview（命名空间 stl-preview）中可调整行为。常用配置项如下：

典型用法¶

1. 安装并确认 enabled 为 true，按需设置 unitScale（尤其模型不是按毫米导出时）。
2. 将 .stl 放入 DSH 工作区，在 Workspace files 中单击该文件。
3. 右侧 Sidebar 加载视口后，用鼠标旋转、平移、缩放查看模型；需要检查打印可行性时查看体积、表面积与水密性相关条目。
4. 若三角面极多且水密性未显示，对照 analysisMaxTriangles；必要时在本地用其他工具简化网格后再预览。

数据路径可概括为：

Workspace file click
        │
        ▼
document preview body (lib/client.js)
        │  GET /api/stl-preview?path=…
        ▼
parseStl(bytes)  →  analyzeStl + setGeometry（Z-up → Y-up）

适用场景与注意¶

适合：在 DSH 内快速核对 STL 外形与包围盒；在提交切片或打印前看一眼体积、表面积与水密性提示；与智能体工作流共用同一工作区，减少切出 DSH 的次数。

限制与注意（来自上游 README）：

• 百万级三角面在主线程解析可能较慢；水密性分析有三角面上限。
• 超出标准语法的 ASCII STL（例如额外顶点色、非标准 facet 属性）仅按位置与法线处理。
• 极大文件受 maxBytes 约束。

安全与权限：插件以当前 DSH 进程权限运行，并可注册 /api 下的路由读取工作区文件。安装前请阅读 GitHub 仓库 源码与 MIT 许可证，确认符合你的环境策略。DSH 社区插件目录为独立站点，与 DeepSeek / 幻方无官方从属关系。

结尾¶

dsh-stl-preview 把 STL 变成 DSH 右侧栏的一等公民：本地认证拉流、浏览器内解析、无依赖 WebGL 预览，并集中展示打印常关心的数值。需要目录说明或 issue 时，可访问插件页与仓库：

• 目录页：https://www.skillhub.cn/plugins/439436269-ctrl/dsh-stl-preview
• GitHub：https://github.com/439436269-ctrl/dsh-stl-preview