Workspace File Explorer (fexp)

English · 中文

!GitHub Release !License !GitHub Stars 

A dynamic Cordis plugin for DSH (DeepSeek Harness) that browses workspace directories and files from the left sidebar. Two entry points — the "File Explorer" pill at the top of the sidebar and the "Open Directory" button in the session header — slide out a 320px panel that locates the current workspace directory. Click a directory to enter it, click a file to preview its text content. The toolbar can open the current directory in the system file explorer with one click, and file references can be appended to the chat input while previewing.

Since v1.5.0 this is a static bundle plugin loaded automatically from the profile layer stack — install once, and it activates on every DSH startup with no manual define/run needed.

Features

• Dual entry points (SVG vector icons; colors use theme CSS variables, so text stays readable on light, dark, and any custom theme):

- "File Explorer" pill button at the top of the sidebar, right of the "Workspaces" title (shown when the sidebar is wide; auto-hidden while the "Search sessions" box is expanded so it never covers the search input, v1.5.1) - "Open Directory" button in the session header bar

• Browse panel (slides out from either entry, 320px, overlays the left area):

- Automatically locates the current workspace directory (current session cwd); re-locates automatically when you switch workspaces, while re-opening in the same workspace keeps your last position - Directories first, then files (with sizes); click a directory to enter, click a file to preview - Breadcrumb navigation at any level; toolbar: current workspace / root / up one level / refresh / open in system file explorer - File preview: text content (256KB default limit, 1MB max), with clear messages for binary or oversized files - Preview header: file name / size / [Add to chat] / close preview

• Open in system file explorer: one click opens the current directory in the OS file manager (DSH native host.openPath, Invoke-Item on Windows)
• Add to chat (v1.6.0): appends a DSH @ file-command reference to the input draft (without overwriting existing content; multiple files add space-separated): files under the session cwd use the relative form (@client/client.js), files outside keep the absolute path, and paths with spaces follow the official quoted grammar (@"path with spaces"); the input box shows only a short reference, and DSH's native FILE_REFERENCE_PROMPT makes the model treat @-prefixed paths as explicitly referenced files to read via the read tool
• Icons (v1.4.0): Google Material Icons official library (fonts.google.com/icons, Apache 2.0), solid fill style stays crisp at small sizes, consistent with Chrome/Android first-party visuals

Screenshots

Quick Start

# Install (static bundle, recommended; published to npm)
dsh plugin --profile web add fexp-file-explorer

For local development or unpublished copies use file: pointing at this repository (the path must NOT contain spaces):

dsh plugin --profile web add file:/path/to/fexp-file-explorer

Restart dsh web and the plugin activates automatically: the "File Explorer" pill appears at the top of the sidebar and the "Open Directory" button appears in the session header. No manual define/run required.

Usage

1. Open the panel: click "File Explorer" in the sidebar or "Open Directory" in the session header; the 320px panel slides out from the left, locating the current workspace directory; 2. Browse: click a directory to enter it; use the toolbar "up one level / root / refresh" or jump to any level via the breadcrumbs; 3. Preview files: click a file to preview its text content at the bottom of the panel (256KB default limit); 4. Add to chat: while previewing, click "Add to chat" to append a DSH @ file reference (@relative-path / @"path with spaces") to the input draft, then edit and send; 5. Open in system file explorer: the rightmost toolbar button opens the current directory in the OS file manager (Invoke-Item on Windows).

Repository Contents

Two Forms

Dynamic fallback steps:

1. Have an agent read host-source.js and client-source.js; 2. cordis_define: plugin: { kind: "new", idPrefix: "fexp" }, name/purpose from manifest.json (purpose includes the CAPABILITIES: fs, rpc declaration), code.host/code.client as the full contents of the two source files; 3. cordis_run to activate; success when the panel appears.

> The dynamic form does not survive DSH restarts and must be reloaded; the static bundle form has no such limitation.

Technical Notes

• Host half: the static bundle form lives in lib/index.js and mounts three JSON routes via webServer (/fexp/default-root, /fexp/list-dir, /fexp/read-file) on top of the DSH fs service (resolve/listDir/stat/readText) and sandboxPolicy.workspaceRoot; the dynamic fallback in host-source.js exposes the same three methods as Package-private RPCs via harness.handle.
• Client half: uses only additive slots (shell.overlay, conversation.session.header.actions, conversation.input.dock, sidebar.footer.action) and never replaces built-in UI; plain JS + React.createElement, no JSX/TS. The static form registers via window.__ModuleLoader__.load, replaces host.call with fetches to same-origin routes, and replaces styles.insert with a self-managed <style> tag.
• Startup race fix (v1.0.0): useStore self-heals by re-reading state right after subscribing, so a probe update landing before the subscription is never lost; sidebarWide defaults to true so the top button stays visible even if the probe fails.
• Open in explorer (v1.1.0/1.5.2): the path goes to DSH native host.openPath (Invoke-Item on Windows). Since v1.5.2 it calls the native API directly (POST /api/host.openPath, the official client-request envelope protocol, same-origin) — intercepting plugins like dsh-better-sidebar monkey-patch workspaces.openPath and reroute "open directory" into "open file in the sidebar editor", which rejects directories with "…" is a directory; direct calls bypass the patched channel, falling back to workspaces.openPath when fetch is unavailable or the network layer fails; no new Host RPC, no spawn/external network capability.
• Add to chat (v1.2.0~v1.6.0): a hidden bridge inside the session-scoped conversation.input.dock slot captures the standard inputActions (setDraft) and useInput (draft subscription); "Add to chat" calls setDraft(existing draft + reference) — the same official channel the built-in UI uses to write the input box. Pure client capability, no new Host RPC. Since v1.6.0 the inserted reference uses the DSH @ file-command grammar (mirroring the official file-reference formatFileMention): relative path inside the cwd, absolute path outside, quoted @"…" when the path contains spaces; DSH's system-prompt FILE_REFERENCE_PROMPT makes the model treat @-prefixed paths as explicitly referenced files to read via the read tool, so no long Markdown link is needed.
• Workspace binding (v1.2.2): the panel-loading effect was guarded by path === null, so after browsing once (or entering a subdirectory), closing and reopening — or switching workspaces — never reloaded, leaving the previous workspace's directory on screen. A boundWs binding state now re-binds and reloads the current workspace directory whenever boundWs !== current wsPath on open or workspace switch; re-opening in the same workspace keeps the last position. Both entries go through openPanelFor; the toolbar "current workspace" goes through bindWorkspace.
• Theme contrast (v1.2.3): entry buttons used hard-coded inline colors (near-white #e8edf3 text) that vanished on light themes; they now use CSS classes .fexp-entry-btn / .fexp-entry-btn-active with theme CSS variables (label-primary text, bg-layer-1/2 background, border-l2 border, brand-primary active state), adapting automatically to any theme with hover feedback.
• Icon library (v1.4.0): Google Material Icons official paths, solid fill rendering (fill="currentColor", no stroke), default size 16px; the Lucide line icons from v1.3.0 are superseded.
• Search-box avoidance (v1.5.1): the "File Explorer" pill is fixed-positioned on the "Workspaces" title row, so it landed exactly on top of the expanded "Search sessions" box. TopToggle now watches the search button's aria-expanded attribute with a MutationObserver (the expanded search button carries aria-expanded="true" and its next sibling is an input[type=text], which distinguishes it from the session rows / group-collapse buttons that also use aria-expanded); the entry button hides while the search box is expanded and reappears when it collapses. Host unchanged.

Security & Boundaries

• Capability declaration: CAPABILITIES: fs, rpc — filesystem access (the host fs service) and regular RPC only; no network requests, no spawn/process, no credential access.
• Security review: WARN level (38/300 since v1.5.2; 33/300 before); reviewed by plugin_security_review / plugin_security_audit (see dsh-plugin-security-review).
• Known limitations: file preview defaults to a 256KB limit (1MB max); oversized files return a clear FS_TOO_LARGE error and should be read by the assistant in conversation. The static bundle loads with the profile; the dynamic fallback form does not survive DSH restarts and must be rebuilt.

Version History

Maintenance

• Commit convention: Conventional Commits with Chinese descriptions (feat: feature / fix: bug fix / docs: docs / refactor: refactor / chore: chores); source / manifest / README stay in sync.
• Agent collaboration: read AGENTS.md before making changes; rebuild and change workflows are documented there.
• Releases: tag (vX.Y.Z) and gh release create after each feature iteration; the docs site builds automatically on GitHub Pages (https://shanhaifish.github.io/fexp-file-explorer/).