Introduction¶

In DSH’s plugin system, agents often need to access local files. In existing approaches, dsh’s built-in file tools usually operate on the host machine where dsh is deployed; if dsh is deployed in a remote environment while the user’s browser is on another machine, the agent cannot directly manipulate local files on the browser’s machine.

dsh-browser-fs is used to fill this gap: it allows agents in the dsh web page to obtain user authorization for local directories via the File System Access API, and complete directory listing, text reading, and text writing through model tools provided by the plugin.

What is this¶

whitefirer/dsh-browser-fs is a client-side plugin for the dsh web interface, with the core goal of enabling dsh agents to read and write local files on the machine where the browser is located.

It mainly does three things:

• Register three model tools: browser_fs_list, browser_fs_read, and browser_fs_write;
• Build a WebSocket channel within the plugin to forward tool calls to the browser tab holding the authorization handle;
• On the browser side, register floating cards in the shell.overlay layer to display connection/authorization status and manage directory authorization.

The license is MIT. The repository address is:

https://github.com/whitefirer/dsh-browser-fs

Core Features¶

Authorizing Directories and Model Tools¶

The plugin allows users to authorize a local directory via the File System Access API. In full mode, selecting a directory requires readwrite permissions.

After authorization, the agent can call the following three tools:

browser_fs_list { path?, recursive? }
browser_fs_read { path, maxBytes? }
browser_fs_write { path, content }

Where:

• browser_fs_list is used to list directories;
• browser_fs_read is used to read text files;
• browser_fs_write is used to write text files.

The default upper limit of browser_fs_read is 256 KiB, and truncation is noted. Agent tools only support UTF-8 text read/write; binary write is out of scope.

Card Browsing and File Preview¶

The browser-side browser-fs card can provide browsing of the authorized directory’s content tree, and supports filename/path search and copying relative paths.

Clicking a filename in the directory tree opens a preview window, supporting image and text preview. Text preview only takes the first 64KB. Images are not fetched if they exceed 8MB.

In full mode, text preview can be edited and saved. Text/code preview supports syntax highlighting, and highlight.js uses lazy loading.

Images are only previewed within the card, and there is no full support for agent tools to read binary content.

Multi-Device and Connection Status¶

Multiple devices can authorize their own local directories respectively. The host side maintains an executor list and routes tool calls to the appropriate browser tab for execution.

When the client disconnects, it reconnects with exponential backoff, and supports abort and browser cancel frames.

Compatible Mode¶

The File System Access API requires HTTPS or localhost for a secure context. In a non-secure context, the plugin will automatically enter compatible mode.

The capability differences between full mode and compatible mode are as follows:

Installation and Enablement¶

First execute the installation command:

dsh plugin --profile web add dsh-browser-fs

Then restart dsh to make the plugin effective.

When developing locally or installing from source, you need to build first, then reinstall using a file: path:

npm run build
dsh plugin --profile web add file:/abs/path/to/dsh-browser-fs

After completion, restart dsh.

Two points to note during installation:

• The host side depends on @deepseek-ai/dsh-tools as a peerDependency;
• The client side defaults to a fixed WebSocket path /browser-fs/ws. If the host side modifies wsPath, the client side’s DEFAULT_WS_PATH needs to be synchronized and rebuilt.

Typical Usage¶

The following is a common workflow.

1. Open the dsh web page, click “Authorize Directory” in the bottom-right browser-fs card, and select a local directory.
2. Browse the authorized directory in the card, search by filename or path, and copy relative paths.
3. Let the agent call tools to operate files, for example:

browser_fs_list { path: "docs", recursive: true }

browser_fs_read { path: "docs/hello.txt" }

browser_fs_write { path: "docs/hello.txt", content: "hello" }

4. Click a filename in the directory tree to open a preview window and view image or text content. In full mode, text can be edited and saved.
5. If accessing via LAN or a phone via http, the plugin will automatically enter compatible mode, and you can use “Select Directory” or “Select Multiple Files” for read-only selection.

If full mode is required, you can obtain a secure context through one of the following methods:

• Forward access to localhost;
• Add the target origin to the insecure origin whitelist in the browser;
• Deploy HTTPS.

Applicable Scenarios and Precautions¶

This plugin is suitable for the following scenarios:

• dsh is deployed in a remote environment, and the agent needs to operate on local files on the machine where the browser is located;
• Users want to authorize a local directory instead of exposing the entire host file system to the agent;
• Need to see connection status, authorization status, directory tree, and file preview on the browser side;
• Multiple devices authorize their own local directories respectively, with tool calls routed by the host side.

Pre-use precautions:

• The File System Access API requires HTTPS or localhost secure context; when accessing the page remotely via pure HTTP, the authorization button will report a clear error.
• Browser tabs must be online and have authorized the directory, otherwise tool calls will immediately return a clear error.
• Agent tools only support UTF-8 text read/write; binary write is out of scope.
• The default upper limit of browser_fs_read is 256 KiB, and truncation is noted.
• Text preview only takes the first 64KB; images are not fetched if they exceed 8MB.
• Compatible mode is read-only, no handle persistence, and re-selection is required after refresh.
• The plugin runs with the permissions of the current dsh process. Source code and license should be checked before installation.

Conclusion¶

The value of dsh-browser-fs lies in connecting local files on the machine where the browser is located to the dsh agent toolchain: users authorize directories via the browser, agents complete directory listing, text reading, and text writing through explicit tools, and the browser side retains the status card, directory browsing, and preview capabilities.

Repository address:

https://github.com/whitefirer/dsh-browser-fs

Directory page link:

https://www.skillhub.cn/plugins/whitefirer/dsh-browser-fs