前言¶
在 DeepSeek Harness（DSH）里做智能体或脚本开发时，工作区里常有 PDF、Office、图片、压缩包、CAD 或 3D 模型等文件。默认流程往往是先下载到本地再用系统软件打开，打断在浏览器里的工作节奏。社区插件 dsh-open-file-viewer（维护者 wenhongquan，分类：客户端）把通用预览能力接到 DSH Web 侧栏：基于 npm 包 @open-file-viewer/core，在右侧边栏直接渲染多种格式，无需先落盘到本地。
下面介绍插件定位、能力边界、安装方式，以及与 dsh-better-sidebar 的分工。
这是什么¶
dsh-open-file-viewer 是 DSH 右侧边栏的通用文件预览插件。它通过客户端模块系统认领 dsh-resource://file/** 资源，在浏览器内分页读取工作区文件字节并交给各格式渲染器展示。仓库构建产物已随 Git 提交，安装后可直接使用，不必在本地再跑构建（除非你要改源码）。
插件为只读预览：文本类文件的编辑与保存应交给 dsh-better-sidebar 的 CodeMirror 编辑器，本插件不抢占可编辑场景。
支持的格式与预览能力¶
README 中按类别列出了主要扩展名，涵盖常见办公与工程场景：
| 分类 | 代表格式 |
|---|---|
| 图片 | png、jpg、jpeg、gif、webp、avif、svg、bmp、ico、tif/tiff、heic/heif |
| 视频 / 音频 | mp4、webm、mov、mp3、wav、ogg、aac、flac、m3u8 等 |
| 文档 | pdf、epub、doc/docx、xls/xlsx、ppt/pptx、csv、odt、wps 等 |
| 文本 / 代码 | txt、md、json、yaml、xml、js/ts、py、go、rs、java、html、css 等 50+ |
| 压缩包 | zip、rar、7z、tar、gz、tgz、bz2、xz |
| 邮件 | eml、msg、mbox |
| 绘图 / 脑图 | drawio、dio、excalidraw、tldraw、xmind |
| CAD / 工程 | dxf、dwg、step/stp、iges/igs、ifc、skp、gds/gdsii 等 |
| 3D 模型 | gltf、glb、obj、stl、fbx、dae、ply、3mf、usd、usdz |
| GIS | geojson、topojson、kml、kmz、gpx、shp |
| 资源 | ttf、otf、woff/woff2、psd、ai、eps |
预览工具栏支持缩放、旋转、全屏、下载；PDF 额外支持打印与全文搜索。PDF 渲染使用打包内置的 pdfjs，不依赖外部 CDN。
安装与版本要求¶
官方推荐从 GitHub 直接安装（--profile web 表示 Web 浏览器侧栏环境）：
dsh plugin --profile web add https://github.com/wenhongquan/dsh-open-file-viewer.git
要求 DSH 0.1.7-rc.1 及以上，且运行在 Web（浏览器）侧栏。package.json 中当前版本为 0.1.0，许可证为 MIT。
若需从源码安装并本地构建，README 给出了 clone、pnpm 构建与本地路径添加的步骤；一般用户按方式一即可。
典型用法¶
- 完成上述安装并重启或刷新 DSH Web 客户端（按你当前 DSH 的插件生效方式操作）。
- 在工作区打开或选中支持的文件；插件以
extension优先级的标签类型认领dsh-resource://file/**地址，在右侧边栏打开预览面板。 - 使用工具栏进行缩放、旋转、全屏或下载；PDF 可使用打印与全文搜索。
未安装 dsh-better-sidebar 时，所有经原生标签认领系统进入的文件都由本插件处理，功能不受影响。
与 dsh-better-sidebar 的协作¶
若同时安装了 dsh-better-sidebar，本插件会通过其 registerFileViewer 扩展点注册预览器，分工如下：
- 3D、CAD、GIS、媒体、压缩包、邮件、绘图等二进制格式：从 better-sidebar 文件树打开时在本插件内渲染，而不是「无法预览 / 下载」兜底页。
- 图片、PDF、表格、Office（better-sidebar 的让渡清单）：仍由系统认领，本插件用原生标签渲染。
- 文本、代码、Markdown、HTML：留给 better-sidebar 的可编辑编辑器，本插件不抢。
工作原理（简要）¶
- 通过
dsh.client清单向客户端注册extension优先级标签，挂载预览面板。 - 文件字节经宿主
remote.workspaceFiles.readBytes分页读取（2 MiB 窗口），在浏览器内交给各格式插件渲染。 - 等待
remote.workspaceFiles命名空间就绪后再激活，避免与远端装配的激活竞态。
依赖方面，运行时核心为 @open-file-viewer/core（README 对应 package.json 中为 0.1.49）与 pdfjs-dist。
适用场景与注意¶
适合：在 DSH Web 环境内快速查看工作区附件、文档、模型与 GIS 数据，减少切换本地软件的次数。
注意：
- 插件在当前 DSH 进程权限下读取工作区文件；安装前请阅读仓库源码与 MIT 许可证，确认符合你的安全与合规要求。
- 仅支持 Web 侧栏 profile，与纯终端或非 Web 客户端的组合以你实际 DSH 版本为准。
- 社区目录 SkillHub 插件页 与 GitHub 仓库由社区维护，与 DeepSeek / 幻方无官方从属关系；DSH 生态遵循「一切皆插件」，安装来源以 README 为准。
