dsh-filelens

dsh-filelens

English | 中文

FileLens — a right-column file explorer for the DeepSeek Harness web UI.
Browse a lazy directory tree, preview many formats, search file names and
contents, open multiple tabs, and inline-edit text files — with containment
guards and version-guarded writes built in.

A single npm package ships both halves:

• Host half — the filelens Remote service (root / list / search /
  grep / read / readMore / readHex / write / readImage) over the
  host fs service. Invocation definitions are registered into the Host
  Typert registry at runtime (typert.local) — no generated artifacts, no
  decorator markers, install-shape agnostic.
• Browser half — the details-column UI, wired to the Host through the same
  /api Remote transport the built-in client connection uses. No
  ctx.remote namespace injection is needed, so there is nothing to deadlock
  or misconfigure.

Features

• Lazy directory tree — expand/collapse, hidden-dotfile toggle, breadcrumb
  navigation, drag-resizable column, and every entry is shown (no per
  directory cap). Refresh keeps your open tabs. The tree and open previews
  auto-sync with the disk (~2.5 s poll): added/removed entries appear and
  disappear, and previews reload when file content changes.
• Multi-tab preview — drag-sortable tabs, Ctrl+Tab / Ctrl+Shift+Tab
  cycling; per-tab "pretty/raw" and word-wrap preferences.
• Typed rendering
  • Markdown: headings, lists, task lists, quotes, aligned tables, fenced
    code with syntax highlighting and a copy button, auto TOC, blue links
    (URL scheme whitelisted).
  • Images: zoom 0.2–8×, rotate, 1:1 reset, download, pixel dimensions.
  • JSON (pretty + highlighted), CSV/TSV tables, diff/log coloring.
  • 30+ languages syntax-highlighted with line numbers and cross-line block
    comment handling.
  • Binary files get a hex view (offset + hex + ASCII).
• Large files — 256 KB head preview with incremental "load more" (the Host
  continues the same stream — no re-read from the start), virtual scrolling
  beyond 800 lines.
• Search — recursive filename search (depth 8 / 3000 dirs / 300 results),
  content grep (≤256 KB text files, 5 hits per file, click to jump to line),
  Ctrl+P quick-open palette. Searches are cancelable per family, so
  keystrokes never pile up heavy scans on the shared host.
• Conversation links — clicking a file mention in a conversation switches
  the tree to that file's own folder and highlights the file row.
• Workspace awareness — the panel is a session-scoped details seat: it
  resolves the current session's workspace on open, so switching between
  sessions with different workspaces re-roots the panel automatically.
• Inline editing — text files edit in place; saves write through the host
  fs service with a version guard (see Security).
• Right-click menu — copy path / open in system / reveal in folder / open
  in new tab.
• State persistence — expanded dirs and open tabs survive reloads via
  localStorage (key dsh-filex-state); the root always follows the current
  workspace, never a stale stored one.

Install

Prerequisites

• A running DeepSeek Harness installation (the dsh CLI).
• A profile to install into — the default deployment boots the web profile
  (dsh web is its alias). The examples below use web; any name works and
  the first add initializes it.

Option A — from the GitHub repository

dsh plugin --profile web add github:Han-Yao94/dsh-filelens

Option B — from the release tarball (no build step)

Download dsh-filelens-1.0.0.tgz from the
releases page, then:

dsh plugin --profile web add ./dsh-filelens-1.0.0.tgz

Option C — from npm (once published)

dsh plugin --profile web add dsh-filelens

Web GUI bundle

If the profile does not exist yet, the first add initializes it with
@deepseek-ai/dsh-base; the browser GUI additionally needs the web-app
bundle:

dsh plugin --profile web add @deepseek-ai/dsh-web-app

Then boot with dsh --profile web (or dsh web).

Git installs and build scripts

The package ships a prepare script that builds lib/ from source, and the
lib/ artifacts are committed as well, so a clone works either way. pnpm ≥10
refuses to run a git dependency's prepare script until it is explicitly
allowed — if the first add fails, copy the exact package key pnpm printed
into the profile's pnpm-workspace.yaml and re-run:

allowBuilds:
  dsh-filelens: true

That allowance executes the package's build code on your machine at install
time; only allow packages whose source you trust, and prefer pinning a
commit: github:Han-Yao94/dsh-filelens#<sha>.

Verify the install

dsh --profile web --dump-config   # look for a "# == dsh-filelens" layer

Usage

Open the panel with the folder icon in the conversation header (or the
details column), then:

Action	How
Navigate the tree	click, or ↑ / ↓ / ← / → / Enter
Open a file	click its row (preview tab opens)
Open a file's folder	click a file mention in a conversation
Close back to the tree	Esc
Search names / contents	search box; toggle 文件名/内容 (name/content) mode
Quick open	Ctrl+P, type to filter, Enter to open
Find in file	Ctrl+F, Enter / Shift+Enter next / previous, Esc to close
Switch tabs	click, Ctrl+Tab, Ctrl+Shift+Tab, Ctrl+W closes
Edit a text file	the pencil button (disabled until the file is fully loaded)
Save / cancel	Ctrl+S or the 保存 button / 取消
Zoom an image	0.2–8× buttons, rotate, 1:1, download
Copy code	copy button on fenced code blocks

Security model

Layer	Enforcement
Explorer root	every read/write is containment-guarded against an explicit root; the guard is fail-closed (a root that cannot resolve, or a target outside it, rejects the call)
Writes	file.write requires an explicit root — link-opened or restored tabs may read without one by explicit user intent, but never write
Version guard	saves carry the FsVersion observed at read time; a file changed elsewhere rejects the save with stale instead of silently overwriting
Truncation guard	files not fully loaded (>256 KB) cannot be edited, so a save can never truncate the rest of the file
Host sandbox	the underlying fs sandbox (e.g. workspace-write) remains the outermost boundary
Markdown	link/image URLs are scheme-whitelisted (javascript:/data: render inert)

Failures are never silent: save / load-more / root-pick errors surface in an
in-panel notice.

Architecture

• One package, two halves. The Loader row (id: filelens) loads the Host
  service; the browser half is picked up automatically from the dsh.client
  declaration.
• No generated artifacts. The Host registers its nine invocation
  definitions into typert.local at service construction (src-json codecs,
  zero extra dependencies), so the gateway resolves them in any install shape.
• Direct transport. The browser half POSTs the same client-request
  envelope to /api that the built-in connection uses — no ctx.remote
  namespace injection, no mount-order pitfalls.
• Host-side engineering. Incremental reads continue a cached stream
  (O(n) per session instead of O(n²)); search/grep walks abort on a new
  request via AbortController; errors map to structured FsError codes.
• Zero runtime npm dependencies beyond the @deepseek-ai/cordis /
  @deepseek-ai/dsh-typert-protocol peers the harness already provides.

Notes

• The column width drag range inherits the host's details-column constants
  (stock hosts allow a narrower range than the development layout; FileLens
  works with both).
• Editing writes to disk — review the content before saving; the version
  guard protects against concurrent external changes.
• The details seat is session-scoped: each session gets its own panel
  state, and switching sessions re-roots to that session's workspace.

Development

npm install
npm run build                       # tsc (host half) + esbuild (browser bundle)
node scripts/make-client.mjs        # regenerate src/client from ../client.js

The UI logic source of truth is ../client.js (the dynamic-plugin edition);
make-client.mjs transforms it into the static client half.

License

MIT. The SVG icon paths in the UI are derived from the Lucide icon set (ISC)
— see LICENSE for the full notices.