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
filelensRemote 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
dshCLI). - A profile to install into — the default deployment boots the
webprofile
(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-filelensOption 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.tgzOption C — from npm (once published)
dsh plugin --profile web add dsh-filelensWeb 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-appThen 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: trueThat 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" layerUsage
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
detailsseat issession-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.jsThe 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.