dsh-workspace-explorer

English | 中文

A workspace file explorer for the DeepSeek Harness Web UI: a right-side panel showing the current workspace's directory tree — click or drag a file to send its reference to the model.

Inspired by the VS Code / Cursor project tree, filling the gap of a missing directory view in DSH after workspaces are added.

🖥 Live Demo (GitHub Pages)

🔗 Try the interactive preview

An interactive mock of the panel UI — no DeepSeek Harness needed to try it. The real plugin runs inside the Harness web UI as a dynamic Cordis plugin.

Screenshots · 截图

Features

• 📂 Right-docked top panel — a dsh-web-ui-style side panel pinned to the top-right corner: browse the current workspace (session cwd) file tree, switch workspaces from the dropdown, register folders with +, drag the left edge to resize (280–640px)
• 🗂 Top tab bar — click at the top of the panel to switch between Files and Settings; the Settings page tunes behavior live (hide noise dirs, show sizes, reference format, preview lines, panel width) and mirrors into DSH Settings → Workspace Explorer
• 🗂 Lazy-loading tree — directories load on demand; noise dirs (node_modules, .git, dist, __pycache__, …) are hidden automatically
• 🎨 File-type icons — filled, color-coded document badges per extension (TS / JS / Python / JSON / Markdown / image / config / shell, …); amber folders that brighten when expanded
• 🖱 Click to insert — click a file row to append a [file: relative-path] reference to the composer; after sending, the model resolves it with its read tool
• 🖱 Drag & drop — drop a file into the composer to insert at the caret (fullscreen dashed hint); dropping elsewhere appends to the end
• 🌓 Theme-aware — built entirely on DSH's --dsw-alias-* design tokens; adapts to light/dark with a native dialog look (24px radius, lv3 shadow, l3 header rule)
• 🔍 Search & filter — filter files by name across loaded directories (flat result list with a match count)
• 👁 Inline preview — peek the first 60 lines of any text file; insert the reference, or paste the full content for small files (≤ 32 KB)
• 🌐 i18n — zh/en dictionaries registered through DSH's locale service; the panel follows the DSH UI language

Quick Start

Installation & usage

Way 1 · Dynamic plugin paste — full UI (recommended) A dynamic Cordis plugin: no build step, no config changes.

1. In the DSH web UI, have an agent run cordis_define (or use the dynamic plugin panel) with idPrefix wsex.
2. Paste the whole dynamic/host.js into Host code.
3. Paste the whole dynamic/client.js into Client code.
4. cordis_run to activate; authorize on the Run card when it first appears.
5. Click the 📁 Files button at the bottom of the sidebar → expand directories → click a file, or drag it into the composer, then send.

Way 2 · npm source package npm install @jiyr0119/dsh-workspace-explorer — the package ships dynamic/host.js / dynamic/client.js for the Way-1 paste flow, with semver releases.

Way 3 · Storefront (dsh plugin add / dsh-market) — native install (v0.3.0) dsh plugin --profile web add -w @jiyr0119/dsh-workspace-explorer@latest (or the market one-click button). The package ships a native host half (lib/index.js, webServer JSON routes incl. /dsh-we/api/config) and a browser bundle (lib/client.js via dsh.plugin.json) with the full interaction — top tab bar (Files / Settings) + a live settings page. The 0.3.0 build passes; last-mile verification against a real DSH mount is pending (see docs/native-package.md). The dynamic paste flow (Way 1) remains the zero-build option.

ℹ️ pnpm note: modern pnpm (9/10) refuses to add a dependency at the workspace root (ERR_PNPM_ADDING_TO_ROOT), hence the -w flag above. Alternative: create ~/.dsh/profiles/web/.npmrc containing ignore-workspace-root-check=true.

⚠️ Common misconception: a listing alone never auto-installs anything — users still click install. With Way 3 the panel now appears after install (native bundle); before 0.2.0, storefront installs only mounted the host entry with no UI.

See docs/install.md for details.

Usage

1. Click the 📁 "Files" button at the bottom of the sidebar to open the panel.
2. Expand directories to browse files.
3. Click a file, or drag it into the composer, then send.
4. Use the Settings tab at the top of the panel (or DSH Settings → Workspace Explorer) to adjust panel behavior.

Project Structure

dsh-workspace-explorer/
├── README.md             # Docs — English (default)
├── README.zh.md          # Docs — 中文
├── LICENSE               # MIT
├── CHANGELOG.md          # Release notes
├── manifest.json         # Plugin metadata
├── package.json          # Repo metadata (not an npm package)
├── demo/
│   ├── index.html        # Interactive mock preview (GitHub Pages)
│   └── preview.gif       # Demo animation (README)
├── .github/
│   └── workflows/
│       └── pages.yml     # Deploys demo/ to GitHub Pages
├── docs/
│   ├── install.md        # Install guide
│   ├── native-package.md # Native DSH package roadmap (upstream PR sketch)
│   └── publish.md        # Publishing workflow (GitHub + npm)
└── src/
    ├── host.js           # Host half: fs listing + ws-tree.list RPC
    └── client.js         # Client half: panel + icons + drag & drop

Implementation Notes

Capability	Mechanism
Directory listing	Host fs.resolve / fs.listDir
Host→Client RPC	harness.handle('ws-tree.list' / 'ws-tree.peek') ↔ host.call(...)
Panel	shell.overlay slot (useWorkspaces / useSessions)
Toggle button	sidebar.footer.action slot
Composer write	conversation.input.dock → inputActions.setDraft
Drag & drop	HTML5 DnD; native caret insert in the textarea, append elsewhere
Theming	--dsw-alias-* CSS variables (light/dark)

Version

Current version v0.3 — top tab bar (Files / Settings) + live settings page; features and visuals aligned with DSH's native UI. See CHANGELOG.md for release notes.

Roadmap

Done ✅

• v0.1 core: right-side file tree, click / drag-to-composer references, native DSH look
• Search & filter; inline preview (first 60 lines); content insertion for small files (≤ 32 KB)
• i18n (zh/en via the DSH locale service, follows the DSH UI language)
• Demo language toggle, GitHub Pages preview, demo GIF, storefront screenshots
• npm source package + dsh.bundle contract + awesome-dsh-plugin PR (#1158, pending merge)

Track A — UX polish

• Multi-select & batch insert file references (Shift / Cmd)
• Draggable / resizable panel that remembers position & width
• Full keyboard navigation (↑↓ to move, Enter to insert, Esc to close)
• Path actions: copy path, reveal in the OS file manager

Track B — Productivity

• Content search across loaded dirs (host-side grep)
• Recent files / favorites
• Paginated preview for large files (next / previous page)
• File operations (rename / delete / new, under the fs permission fence)

Track C — Ecosystem & distribution

• npm @jiyr0119/dsh-workspace-explorer (v0.1.1 publishing)
• awesome-dsh-plugin listing (PR #1158)
• Native DSH package (@Remote namespace; needs upstream support) — see docs/native-package.md
• dsh-genie hardened install (host-side persistence)
• CI: lint + e2e + automated release

Track D — Quality & maintainability

• Virtual scrolling (huge directories)
• Light / dark theme regression checks
• Playwright e2e for the demo and the real plugin

License

MIT