DSH File Viewer

English | 中文

Online: dsh.r2049.cn

A universal, read-only file preview layer for DeepSeek Harness:
open and inspect files right inside the web UI — no external application needed.

Preview ≠ Execute. The viewer is strictly read-only: previewing a file never
runs shell commands, scripts, macros, or HTML. SVG is rendered through <img>,
and Markdown is sanitized before display.

Supported file types

How it works

• Host half (dist/index.js) registers the /fileviewer loopback RPC
  channel and exposes both a fileViewerContent provider registry and a
  fileViewerHost bounded service for trusted transport plugins. The viewer does
  not assume content lives in a local folder: other host plugins can register
  readers for locators such as artifact://run/report.json, object storage,
  generated output, or remote APIs. A boundary-checked ctx.fs provider is
  installed only when that service is available, preserving local-file
  compatibility without making it a hard dependency.
• Client half (dist/client.js) provides the fileViewer service
  (ctx.get('fileViewer') → openFile(path, { line, renderer })) and renders
  a right-docked viewer column (styled like the Harness details panel)
  through the shell.overlay slot. It opens from:
  • produced-file chips in the conversation (conversation.chat.turnTail,
    priority -1 — clicking an agent-generated file previews it in-app), or
  • the "浏览文件 / Browse files" entry added to each workspace row's
    "…" menu (see the compatibility patch below).
• Workspace "…" menu patch (scripts/patch-workspace-menu.mjs): the
  workspace browser renders its row menu from a hardcoded list with no slot
  hook, so this script applies three guarded, idempotent edits to the
  installed @deepseek-ai/dsh-client-ui-workspace client bundle: a
  browseFiles menu item (zh/en labels), an onSelect branch calling
  window.__dsfvBrowseWorkspace(workspaceId), and the two dictionary keys.
  It aborts loudly on version drift and can be re-run safely after Harness
  updates (node scripts/patch-workspace-menu.mjs).
• Large-file strategy: < 5 MB whole-file, 5–50 MB chunked streaming,
  > 50 MB head-only with explicit "Load more / Go to end" navigation. Range
  reads are capped (8 MiB per call) and text/CSV rows are windowed, so a
  500 MB log never lands in browser memory.
• Theming: styles use --dsw-alias-* tokens and match Harness's details
  panel proportions, so light/dark follow the Harness theme automatically.

Public API

// client side, any web plugin:
const fileViewer = ctx.get('fileViewer')
fileViewer.openFile('/workspace/output/report.csv')
fileViewer.openFile('artifact://run-42/report.csv')
fileViewer.openFile('/workspace/src/main.ts', { line: 125 })
fileViewer.openFile('/workspace/data.bin', { renderer: 'text' }) // force a renderer

Provide content from another host plugin

Register a provider once, then open its locators from any client plugin. The
provider owns locator matching, authorization, metadata, and range reads; the
viewer owns preview selection, bounded RPC transfer, and rendering.

import type { FileViewerContentRegistry } from 'dsh-file-viewer'
const report = new TextEncoder().encode('{"status":"ok"}')

ctx.inject(['fileViewerContent'], runtime => {
  const content = runtime.get<FileViewerContentRegistry>('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')
})

Providers may additionally implement list() for directory-like locators and
openExternal() for source-specific hand-off. register() returns an
unregister function, making provider lifetime follow the supplying plugin.

Trusted transport plugins can inject fileViewerHost and forward an explicit
allowlist of its endpoints. This is how dsh-remote previews files on a Remote
Host: access checks remain owned by the selected File Viewer content provider,
while the transport applies its own authentication, size limits, and method
allowlist. openExternal is intentionally not part of that remote surface.

Browser-only plugins can register the same reader directly on the client
service—no host RPC or local path is required:

import type { FileViewerClientService } from 'dsh-file-viewer'
const markdown = new TextEncoder().encode('# Live preview')

ctx.inject(['fileViewer'], runtime => {
  const viewer = runtime.get<FileViewerClientService>('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')
})

Configuration

# cordis.patch.yml / settings
- id: dsh-file-viewer
  name: dsh-file-viewer
  config:
    enabled: true
    extraRoots:
      - /srv/data          # optional extra directories the viewer may read

Development

npm install            # (use a reachable registry if npmjs TLS is flaky)
npm run build          # declarations + esbuild → dist/types + dist/index.js + dist/client.js
npm run check          # tsc (strict) over src and tests
npm test               # vitest: mime, renderer, paths, large-file, csv, json, file-service

Install into a DSH profile

# from the repo root (the profile resolves relative specs from your cwd)
dsh plugin --profile web add /path/to/dsh-file-viewer
# compatibility patch: add "浏览文件" to each workspace's "…" menu
node scripts/patch-workspace-menu.mjs
# then restart the web service (preflight on 43124 → 43123), see
# scripts/restart-dsh-web.sh for the safe pattern used in this repo.

Client-only changes hot-reload via dsh-client-hmr; node-half changes need a
web restart. Re-run scripts/patch-workspace-menu.mjs after any Harness
update that reinstalls @deepseek-ai/dsh-client-ui-workspace.

Security notes

• Path validation is enforced host-side on realpath'd targets against allowed
  roots (fs.contains) by the optional local-files provider. Custom providers
  are responsible for authorization within their own locator namespace.
• Markdown is rendered with html: false and sanitized with DOMPurify
  (scripts, iframes, event handlers and javascript: URLs removed).
• SVG is never injected as HTML — it is displayed through <img>.
• Binary detection: NUL scan + magic bytes; "Open as text" is always an
  explicit user action.
• Per-renderer error boundaries: a broken PDF/JSON can never crash the
  Harness UI.

License

MIT