dsh-file-explorer-kit
GitHub: https://github.com/ice5kysl/dsh-file-explorer-kit ｜ MIT License ｜ Target dsh: @deepseek-ai/dsh ≥ 0.1.1-rc.2 ｜ English · 简体中文
A dsh (DeepSeek Harness) plugin written to official conventions, in "bundle" form. It solves one pain point:
Your workspace holds lots of files, and every time you want a quick look at the directory structure or a file's contents, you have to switch to Finder / File Explorer — that's a hassle.
This plugin lets you browse workspace directories and preview files directly inside the session, without leaving dsh Web:
- A third session tab, "Files" (Chat | Trajectory | Files; shown as 对话 | 轨迹 | 文件 in the Chinese UI): registers into the official
conversation.view view ring, ordered after chat (order 0) and trajectory (order 10) at order 20, and the tab bar appears automatically; the tab label follows the interface language (文件 / Files);
- Opens rooted at the current session's workspace directory; directory breadcrumbs + a directory/file list (directories first, size / time, a toggle for hidden dotfiles), plus jump to any absolute path;
- Auto-refreshes while it is open (so you also see files the agent writes in the background); switch away and back, and the last directory is remembered per session;
- Bilingual zh/en UI: auto-detected from the browser language (zh → Chinese, anything else → English), and a 「中 / EN」 (Chinese / English) button in the top bar switches at any time and remembers the preference;
- Right-side preview: Markdown rendered by default (one-click
预览 (Preview) / Raw toggle; before rendering, content is parsed by marked and sanitized with DOMPurify to protect against XSS from malicious md files in the repo, and links inside the preview always open in a new tab), images shown inline, other text with line numbers (truncated with a notice when overly long), embedded PDF; binary files get a "Copy path / Open in file manager" action (via the official ctx.workspaces.openPath);
- All directory/file data flows through the host-side
/dsh-files read-only endpoints; the plugin never modifies any file.
Why host-side routes are needed (design notes; all based on the official docs/source)
The official browser contract only offers directory-level browsing (ctx.workspaces.listDirectory → host.listDirectory; DirectoryListing.entries contains only directory rows) — there are no file rows and no RPC that reads file contents. The conclusion we verified in dsh-workspace-kit — that "the client can only consume the ctx.remote.* generated at build time" — holds here as well. So previewing arbitrary workspace files is only possible through the official ctx.webServer.register route seam (dsh-host-webserver: WebRoute { kind, path, handler }; a named prefix takes priority over the fallback):
| Endpoint (GET) | Description |
|---|
/dsh-files/home | The host account's home directory |
/dsh-files/list?path=<abs> | Single-level directory: file + directory rows (kind/size/mtimeMs/hidden) + breadcrumbs, mirroring the official DirectoryListing semantics (missing path = home directory) |
/dsh-files/text?path=&maxBytes= | Text preview head (utf-8 decoded, NUL sniffing to detect binary, truncation marker; 300 KB server-side cap) |
/dsh-files/raw?path= | Raw byte stream (Content-Type guessed from the file extension, for <img>/PDF embedding) |
- Read-only, with no write endpoints; the client never assembles paths itself (every path comes from a server response or a workspace/session path provided by the framework).
- Every request passes a host-trust gate that mirrors the official
/api trust fence: a loopback Host passes straight through; a non-loopback one needs a same-origin Origin marker. This is not an authentication layer — consistent with the official web server (binds 127.0.0.1 by default; keep the loopback binding when deploying).
- The routes are registered in the plugin's
apply via ctx.effect(() => ctx.webServer.register(...)) and are released automatically when the plugin's fiber unmounts.
More detail — full route contract, error shape, and the permission/security boundary: docs/usage.md（中文：docs/usage.zh-CN.md）.
Quick install (personal dsh on this machine)
Published on npm — if you already run dsh Web, install in one line:
dsh plugin --profile web add dsh-file-explorer-kit
The git route below is for development / running the latest source.
Prerequisites: dsh on PATH (@deepseek-ai/dsh ≥ 0.1.1-rc.2), Node 20+.
# 0. Get the source (or use a local directory directly)
git clone https://github.com/ice5kysl/dsh-file-explorer-kit && cd dsh-file-explorer-kit
# 1. Build (produces lib/index.js + lib/client.js; npm install's prepare hook
# runs the build automatically)
npm install # installs build-time deps (typescript/esbuild/@types/marked/dompurify/lucide-react, etc.)
npm run build
# 2. Install into your web profile (equivalent to the official dsh plugin add bundle)
bash scripts/install-personal.sh # the script locates the plugin directory itself by walking up (run it straight from the repo root)
# What the script actually runs: dsh plugin --profile web add <this plugin directory>
# It appends this package to dsh.profile.bundles in ~/.dsh/profiles/web (after
# dsh-web-app); the in-package cordis.patch.yml inserts the single Loader line.
# 3. Verify the composition (no restart needed)
dsh --profile web --dump-config | grep -n "file-explorer"
# 4. Restart the GUI to activate
# Quit the current dsh web (Ctrl+C or kill the process), run dsh web again,
# then refresh the browser at http://127.0.0.1:3080
Once it is active:
- Open any session and the title bar shows three tabs — 对话 | 轨迹 | 文件 (Chat | Trajectory | Files); clicking "Files" browses that session's workspace directory in the body area (single-click a directory row to enter it, single-click a file row to preview; ↑↓/↵/⌫ keyboard navigation works).
- The top bar holds one row: breadcrumbs + a "Show hidden / Refresh / 中EN (Chinese/English)" control + an absolute-path jump box; the preview panel offers "Copy path / Open in file manager".
- Switch to another session and come back, and the "Files" tab remembers the directory that session last browsed (in-memory only; not across refreshes).
Compatible with dsh-workspace-kit: this plugin only takes an additive slot (a tab) in conversation.view and does no replacement-style shadowing, so both plugins can be enabled together.
Package / distribute (optional)
npm pack # produces dsh-file-explorer-kit-0.3.1.tgz (includes a prebuilt lib/; prepack builds automatically)
# On another machine: dsh plugin --profile web add ./dsh-file-explorer-kit-0.3.1.tgz
npm package name: dsh-file-explorer-kit — the plain dsh-file-explorer name on npm belongs to an unrelated plugin (joejojoking-cloud), so always install as dsh plugin add dsh-file-explorer-kit, never as dsh-file-explorer.
Development
npm run typecheck # tsc --noEmit (host + browser sources)
npm run build # esbuild: src/host → lib/index.js; src/client → lib/client.js
npm test # standalone smoke test of the host /dsh-files endpoints
Source layout:
src/host/ Host side: fs-server.ts (pure directory-scan / text-read functions),
index.ts (apply: registers the /dsh-files prefix routes via
ctx.effect + the host-trust gate)
src/client/ Browser side: FilesView.tsx (the file browser for the conversation.view
tab), browse-memory.ts (remembers the last directory per session),
files-api.ts (/dsh-files fetch client + types), actions.ts (openPath
binding), locale.ts (zh/EN detection and L()), icons.tsx (lucide SVG
row icons), index.ts (apply: conversation.view registration)
src/shared/ i18n.ts (pure localize/normalizeLocale, shared by host/client)
cordis.patch.yml bundle layer: inserts the single Loader entry dsh-file-explorer-kit
Compatibility / known limitations
- Target dsh:
@deepseek-ai/dsh v0.1.1-rc.2 (dsh web, profile web). The browser face targets that release's conversation.view view-ring contract (tabs are auto-listed from the entries; the body renders only the active view per only: <active id>) and ctx.workspaces.openPath; re-validate against the upstream contract on version upgrades.
- The "Files" tab only appears inside a session (the no-session hero state has no tabs) — an inherent boundary of session-level views.
- Styling is inline (light theme) and does not follow the system theme — the same tradeoff as dsh-workspace-kit v1.
- Security boundary: the endpoints are read-only;
/dsh-files keeps the official trust posture (it is not an authentication layer). If you deploy behind a container/proxy where the Host header is not loopback, keep the dsh web service on a loopback binding or extend the trusted() allowlist in src/host/index.ts.
- Integration with the LoopDSH platform's per-user instances is the same as for dsh-workspace-kit: see "Option A: idempotent pre-provisioning at harness startup" in
docs/plugins/loopdsh-integration.md inside the LoopDSH repository.
