liguobao/dsh-file-viewer

DSH File Viewer

在线使用： dsh.r2049.cn

面向 DeepSeek Harness 的通用只读文件预览层：无需打开外部应用，即可在 Web 界面中查看文件。

预览不等于执行。 查看器严格只读：预览文件不会执行 Shell 命令、脚本、宏或 HTML。SVG 通过  显示，Markdown 会在展示前进行安全清理。

支持的文件类型

| 类型 | 渲染方式 |
|---|---|
| PNG / JPG / GIF / WEBP / SVG / BMP | 图片（适应窗口、缩放、拖动、尺寸信息） |
| PDF | PDF.js（翻页、页码输入、缩放、适应宽度/页面） |
| CSV / TSV | 数据表格（自动识别分隔符、固定表头、行号、搜索、排序、调整列宽、窗口化行、分块加载） |
| TXT / LOG / OUT / INI / CONF | 文本（行号、自动换行、搜索、字号、分块导航） |
| JS / TS / Python / Go / Rust / Java / C/C++ / C# / Shell / HTML / CSS / SQL / … | 源码（highlight.js 语法高亮，只读） |
| Markdown | 安全预览 + 源码 |
| JSON / JSONL | 树形视图（展开/折叠、复制值或路径）+ 源码 |
| YAML | 源码 + 解析后的树形视图 |
| 其他格式 | 后备视图（元数据、外部打开、定位文件、复制路径、可选“作为文本打开”） |

工作原理

- Host 端（dist/index.js）注册 /fileviewer 认证 RPC 通道，并提供 fileViewerContent 内容提供器注册表，以及供受信任传输插件使用的受限 fileViewerHost 服务。内容不必来自本地目录：其他 Host 插件可以为 artifact://run/report.json、对象存储、生成产物或远程 API 等 locator 注册读取器。只有在 ctx.fs 可用时，插件才会安装带边界校验的本地文件提供器；在 DSH v0.1.2+ 包图中，它会从 ctx.workspaceRegistry 发现 workspace roots，从 ctx.sessions 发现实时 session cwd，并通过 ctx.sessionController 执行原生外部打开。
- Client 端（dist/client.js）提供 fileViewer 服务（ctx.get('fileViewer') → openFile(path, { line, renderer })），并将文件查看器作为与“对话”“轨迹”并列的 Harness Tab 展示。可以从对话中的产物文件标签，或 Workspace 行“…”菜单中的浏览文件 / Browse files入口打开。
- Workspace“…”菜单补丁（scripts/patch-workspace-menu.mjs）：由于 Workspace 行菜单目前没有 Slot，此脚本会对 deepseek-harness 新版源码 checkout（已验证到 dsh-v0.1.5-rc.1）或已安装的 @deepseek-ai/dsh-client-ui-workspace 客户端包执行带守卫、可重复运行的修改，加入浏览文件入口及中英文文案。Harness 更新后可以安全地重新运行；若上游结构发生变化，脚本会明确报错并停止。
- 大文件策略：小于 5 MB 时整文件读取；5–50 MB 分块流式读取；大于 50 MB 默认只读取开头，并提供“加载更多 / 跳到末尾”。单次范围读取上限为 8 MiB，文本和 CSV 行采用窗口化渲染，因此不会把 500 MB 日志一次性载入浏览器内存。
- 主题：样式只使用 --dsw-alias-* 变量并遵循 Harness 面板比例，可自动适配明暗主题。

兼容性

dsh-file-viewer v0.3.4 起同时支持 DSH v0.1.1-rc.2 和采用破坏性新包图的
v0.1.2+，已验证到 dsh-v0.1.5-rc.1。在 rc2 上，Host RPC 通道会显式声明仅允许
loopback，Workspace 发现使用旧版 apiProxy fallback；在 v0.1.2+ 上则会额外使用
ctx.workspaceRegistry、ctx.sessions 和 ctx.sessionController。Client 元数据
只依赖受支持包图共有的包，再由它们的传递依赖提供各版本对应的运行时服务。
在 v0.1.2+ 上，查看器还会接收 conversation.view focus request，并将其中
不透明的 focus 值作为文件 locator 打开。

DSH 和 React 包在本插件中是由宿主提供的 optional peer dependencies。
v0.1.2+ profile 关闭了 peer 自动安装（autoInstallPeers: false），因此安装
本插件时不应额外安装或要求 profile 再声明一份内置平台包。由于 npm semver 不会让
=0.1.2-alpha.1 =0.1.5-rc.1  {
const content = runtime.get('fileViewerContent')!
runtime.effect(() => content.register({
id: 'run-artifacts',
supports: locator => locator.startsWith('artifact://'),
async stat(locator) {
if (locator !== 'artifact://run-42/report.json') return undefined
return {
name: 'report.json',
mime: 'application/json',
size: report.byteLength,
}
},
async read(locator, { offset, length }) {
if (locator !== 'artifact://run-42/report.json') throw new Error('Not found')
return report.slice(offset, offset + length)
},
}), 'register run artifact viewer')
})

内容提供器还可以实现 list()，为目录型 locator 提供列表；也可以实现 openExternal()，完成来源相关的外部交接。register() 会返回注销函数，使提供器生命周期与供应插件保持一致。

受信任的传输插件可以注入 fileViewerHost，并转发明确允许的端点集合。dsh-remote 正是通过这种方式预览远端 Host 文件：访问检查仍由所选 File Viewer 内容提供器负责，传输层则执行自身的身份验证、大小限制和方法白名单。远端接口不会暴露 openExternal。

纯浏览器插件也可以直接在 Client 服务上注册相同的读取器，无需 Host RPC 或本地路径：
ts
import type { FileViewerClientService } from 'dsh-file-viewer'
const markdown = new TextEncoder().encode('# Live preview')

ctx.inject(['fileViewer'], runtime => {
const viewer = runtime.get('fileViewer')!
runtime.effect(() => viewer.registerContentProvider({
id: 'live-preview',
supports: locator => locator === 'memory://preview.md',
async stat() { return { name: 'preview.md', size: markdown.byteLength } },
async read(_locator, { offset, length }) {
return markdown.slice(offset, offset + length)
},
}), 'register live preview')
viewer.openFile('memory://preview.md')
})

配置
yaml
cordis.patch.yml / 设置
- id: dsh-file-viewer
name: dsh-file-viewer
config:
enabled: true
extraRoots:
- /srv/data          # 可选的额外可读目录

开发
bash
npm install
npm run build          # 类型声明 + esbuild → dist/types + dist/index.js + dist/client.js
npm run check          # 对 src 和 tests 执行严格 TypeScript 检查
npm test               # vitest：mime、renderer、paths、large-file、csv、json、file-service

安装到 DSH Profile
bash
在仓库根目录执行；Profile 会从当前目录解析相对路径
dsh plugin --profile web add /path/to/dsh-file-viewer
兼容补丁：在每个 Workspace 的“…”菜单中加入“浏览文件”
针对 v0.1.2+ 源码 checkout：
DSH_HARNESS_SOURCE=/path/to/deepseek-harness node scripts/patch-workspace-menu.mjs
或针对已安装的 profile 包：
node scripts/patch-workspace-menu.mjs
然后重启 Web 服务。安全重启流程见 scripts/restart-dsh-web.sh。

仅修改 Client 时可通过 dsh-client-hmr 热更新；修改 Node 端后需要重启 Web 服务。Harness 更新并重新安装 @deepseek-ai/dsh-client-ui-workspace 后，请再次运行 scripts/patch-workspace-menu.mjs。

安全说明

- 可选的本地文件提供器会在 Host 端对真实路径执行允许根目录校验（DSH v0.1.2+ workspace 路径、实时 session cwd、Host cwd 和配置的额外 roots，经 fs.contains 校验）。自定义提供器必须在自己的 locator 命名空间内负责授权。
- Markdown 使用 html: false 渲染，并通过 DOMPurify 移除脚本、iframe、事件处理器和 javascript: URL。
- SVG 不会作为 HTML 注入，只通过  显示。
- 插件会通过 NUL 扫描和魔数识别二进制文件；“作为文本打开”始终需要用户明确操作。
- 每个渲染器都有独立错误边界；损坏的 PDF/JSON 不会导致 Harness 界面崩溃。

许可证

MIT