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.
• 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.