前言¶

在 DeepSeek Harness（DSH）里和智能体聊 CAD 或网格模型时，常见做法是切到 FreeCAD、MeshLab 等桌面软件打开 .step、.stl，或在对话里只看路径、看不到几何。DSH 的 Web 客户端本来侧重文本与文档预览，工程类 3D 文件没有统一的内嵌查看入口。

dsh-3d-viewer（维护者 yanzhaohui1999，GitHub 仓库 yanzhaohui1999/dsh-3d-viewer）是分类为客户端的 DSH 插件：在侧栏里用 WebGL 打开 .step / .stp / .stl / .glb / .gltf，STEP 在浏览器内用 OpenCASCADE WASM 转网格，不依赖本机 Python/OCP，也不写临时文件。装了 dsh-better-sidebar 时可在文件树里双击模型；未装时降级到 DSH 原生右侧栏文档预览，同一套渲染器。

下面介绍定位、能力、安装与日常使用，以及使用时的边界与许可说明。

这是什么¶

• 名称：dsh-3d-viewer（npm 包名与插件标识一致，当前版本 0.1.0，见仓库 package.json）。
• 一句话：在 DSH Web 侧栏注册 3D 模型预览器，支持 STEP/STP/STL/GLB/GLTF。
• 运行面：仅 web 客户端（dsh.client.platform: web，immediately: true）；宿主侧 index.js 的 apply() 为空，逻辑在构建产物 lib/client.js 中。

插件动机在 README 里写得很直接：CAD 的 STEP/STL 平时多在 FreeCAD 里看；在 DSH 里聊到模型时，若文件能在侧栏直接旋转查看，就不必切窗口、也不必先转格式。

核心功能¶

支持的格式与解析方式¶

OpenCASCADE 的 wasm 已内联进 lib/client.js（通过 wasmBinary 传入），运行时不需要再额外拉取 wasm 文件。

两条注册路径（软降级）¶

1. 已安装 dsh-better-sidebar：在其文件树中双击模型文件，经 registerFileViewer 在 3D 视图中打开。peerDependencies 要求 dsh-better-sidebar >= 0.19.0（optional）；README 建议版本 0.28.x（0.24.1 在 DSH 0.2.1 上可能停在 pending (waiting for service: webRuntime)，该服务在 0.2.1-rc.1 已改名为 webStartup）。
2. 未安装 better-sidebar：走 DSH 原生右侧栏文档预览（documentPreviews + sidebar.right.tab.document），同一渲染器；注册经 ctx.inject 子 fiber 完成，避免直接读 documentPreviews 时 Cordis 注入错误。

交互与视图¶

STEP/STL 会套用 CAD 常用的 Z-up → Y-up 旋转；glTF 规范本身为 Y-up，插件仅对 STEP/STL 做该旋转（zUp 标记），避免 GLB 模型朝向错误。

WebGL 与界面语言¶

WebGL 上下文丢失（GPU 复位、标签页休眠等）时会取消默认行为，恢复后重建渲染器并重新挂载模型，减轻黑屏卡住。

工具栏、状态行、插件标题及「空文件 / 不支持 WebGL」等提示支持中英文：有 DSH 的 locale 服务时跟随宿主语言（设置 → 通用）；否则按浏览器语言（zh* 为中文，其余英文）。STEP/STL/glTF 解析失败时的诊断文案目前仍为中文（README「没验证的部分」有说明）。

安装与启用¶

插件以本地目录形式加入 Web profile，安装命令须在该插件仓库根目录执行（不要把下面的 . 换成 GitHub 短名拼接）：

# 在仓库根目录执行
dsh plugin --profile web add .

README 记载：该命令会同时写入 dependencies 和 dsh.profile.bundles（2026-11-03 在 DSH 0.2.1-rc.3 上实测，pnpm add 之后 bundles 会自动出现 dsh-3d-viewer）。也可在 Web 界面「插件」→「添加插件」→ 本地目录填写同一路径。

lib/client.js 已构建并随仓库提交，安装前不需要 npm install 或本地构建；three、occt-import-js、esbuild 仅为 devDependencies，重装 profile 时不会带进运行时。

维护者若需从源码重建客户端 bundle：

npm ci
npm run build

典型用法¶

在 DSH 里打开模型¶

1. 确保 Web profile 已包含本插件；推荐同时安装 dsh-better-sidebar@0.28.x。
2. 启动 DSH Web（例如 dsh --profile web 或你的日常 profile）。
3. 在右侧栏「文件」树中找到 .step、.stl 或 .glb 等文件：better-sidebar 路径下双击打开 3D 预览；原生文档预览路径下按 DSH 文档预览方式打开对应扩展名文件。
4. 用鼠标旋转、缩放、平移；需要时用工具条切换正交视图或导出截图。

仓库自带 10 mm 立方体样例：samples/cube-10mm.step、samples/cube-10mm.stl，可用于对照验收。

仓库内自检（可选）¶

维护者或审阅源码时，可在克隆后的仓库根目录做 Node 与无头浏览器验收（README 已给出命令与期望输出），例如 STEP 包围盒校验：

node scripts/verify-step.mjs

或指定自有文件：

node scripts/verify-step.mjs path/to/your.step

端到端渲染、STL/GLB 烟雾测试等见 README「验收」一节；无头 Chrome 路径可用环境变量 CHROME_PATH 覆盖默认的 macOS Google Chrome 路径。

适用场景与注意¶

适合谁¶

• 在 DSH Web 里处理机械 CAD（STEP/STL）或简单 glTF/GLB 资源，希望在侧栏内完成「看一眼几何」而非频繁切桌面软件的智能体开发者或用户。
• 已使用或愿意安装 dsh-better-sidebar、习惯在侧栏文件树里点文件的工作流。

限制与未验证项（来自 README）¶

• 压缩 GLB/GLTF：仅验过未压缩模型；带 DRACO / KTX2 的模型会失败（未接解码器）。
• 深色画布：背景写死 #11161c，不跟随宿主浅色主题。
• 单位：底部读数统一标 mm，对 STEP/STL 合理；glTF 规范无单位，数字仅表示模型空间尺寸。
• 原生降级路径：注册已在无 better-sidebar 的 profile 测过；但该实例未完整跑过「取字节 + 画面」的端到端 GUI。
• 其它 DSH 版本：维护者主要在 0.2.1-rc 系列验证；升级宿主前建议自行试跑。

安全与许可¶

• 插件代码在 你当前 DSH 进程权限下作为客户端 bundle 执行；安装前应阅读 GitHub 源码 与分发许可。本仓库以 MIT 发布；随 lib/client.js 分发的 three.js@0.169.0（MIT）与 occt-import-js@0.0.23 / OpenCASCADE wasm（LGPL-2.1）许可文本在 licenses/ 目录。社区目录 SkillHub 插件页 与 GitHub 为公开信息来源，与 DeepSeek / 幻方无官方从属关系；DSH 生态遵循「一切皆插件」，目录站点为社区汇总。

结尾¶

dsh-3d-viewer 把工程类 3D 预览收进 DSH Web 侧栏：STEP 靠浏览器内 WASM 网格化，STL/GLB 前端直读，并与 better-sidebar 或原生文档预览两套入口对齐。若你的对话里经常出现模型路径，可以在 Web profile 用官方文档中的 dsh plugin --profile web add . 装好插件后，直接用侧栏打开 samples/cube-10mm.step 试一遍交互。

• 社区目录：https://www.skillhub.cn/plugins/yanzhaohui1999/dsh-3d-viewer
• 源码与完整验收说明：https://github.com/yanzhaohui1999/dsh-3d-viewer