Preface

The DSH Web GUI originally only supported image attachments. When there’s a need to pass non-image files such as PDFs, code, or compressed archives to the agent via the web interface, there was a lack of a stable entry point. dsh-file-upload solves this problem: it saves or references files dragged into the page to a local staging directory, allowing the agent to read them while keeping the input field clean.

Plugin Overview

dsh-file-upload is a Web client plugin. It expands the DSH Web GUI’s attachment channel, which previously only supported images, to allow uploading any type of file.

Basic facts are as follows:

  • License: MIT
  • Runtime requirement: Node >=20
  • Plugin form: Persistent profile plugin, with dual declaration in dsh.bundle and dsh.client, automatically taking effect after DSH restart
  • Web declaration: dsh.client, platform web
  • Official service dependencies: webServer, slots, inputTriggers, conversation/sessions
  • Repository URL: https://github.com/GLFzr/dsh-file-upload

Core Capabilities

Drag-and-Drop of Any File

The plugin supports dragging any file, including multiple files and images, from anywhere on the page. Once files are dropped, they are uploaded or referenced to a local staging directory. A blue file chip appears in the input field, and the agent can directly read the file.

Direct Local File Reference and Upload Staging

In Chromium-based browsers (Edge/Chrome), when dragging files from the local machine, the plugin can directly reference the source file path, achieving zero upload and zero copy. If the browser cannot access the source file path, it falls back to the upload staging process.

File Chip

Files are inserted into the input field as a solid blue chip, displaying only the filename and format. Pressing Backspace or Delete removes the entire reference in one action.

The chip width adapts to the filename, and the actual width is measured using the composer’s real font before insertion.

The user interface hides .b64 suffixes, duplicate sequence numbers (_N), and staging directory paths; the full real path is submitted to the agent.

Two-Level Deduplication

Deduplication operates at two levels. If files have the same name, same size, and the source modification time recorded in the manifest matches, the fast path is taken, resulting in instant response and zero upload. Otherwise, a full upload is performed, and a byte-by-byte comparison using sha256 is used to decide.

Upload Directory Cleanup

The trash bin icon at the bottom of the sidebar, above the settings icon, opens the upload directory cleanup overlay. This overlay provides a file list, one-click cleanup of redundant _N copies, size-based cleanup, and complete clearance, with confirmation prompts before execution.

Integrity Verification and Loading Indicators

Upload verification includes checking for exact chunk lengths, completeness of all chunks, and consistency of decoded byte counts with declared values.

The spinning ring at the insertion point only displays when truly waiting and disappears instantly upon chip insertion.

Installation and Verification

Install using a local repository path:

dsh plugin --profile web add ./plugins/file-upload

After installation, run the following command to verify if the plugin layer appears:

dsh web --dump-config

The output should include the # == dsh-file-upload layer.

If you were previously using the old name dsh-drop-file-to-path, the plugin ID and route have been renamed to file-upload. After reinstalling with the new command, the old version does not need to be uninstalled.

Typical Usage

  1. After dragging in files, they are uploaded or referenced to a local staging directory. A blue file chip appears in the input field, and the agent can directly read the file.

  2. The trash bin icon at the bottom of the sidebar, above the settings icon, opens the upload directory cleanup overlay.

  3. If a binary file upload is rolled back, it will be saved to disk as base64 text with a .b64 extension appended. The agent must first base64 decode it before use.

  4. Local syntax checks and host tests can be performed:

node --check lib/index.js lib/client.js

node --test tests/host.test.mjs

Applicable Scenarios and Notes

Suitable for handling non-image files in the DSH Web GUI or scenarios where local files need to be passed to the agent via the web interface.

Notes:

  • Browser sandbox limitations: Web JavaScript cannot access local file disk paths; the agent can only read disk paths, so files need to be materialized to a local staging directory, defaulting to ~/.dsh-dropbox.
  • Large files must be fully uploaded on first drag; duplicate files hit deduplication and require zero upload.
  • Cleaning the upload directory will invalidate files referenced by historical sessions. Ensure no active sessions are in use before proceeding.
  • HTTP routes have cross-origin protection: returning 403 when Origin ≠ Host; local calls without Origin are unaffected.
  • Public versions of DSH without composer occurrence extensions will fall back to a fixed 1em chip, but submission, copying, and draft refresh will still function correctly.
  • The plugin runs with the file access capabilities of the current DSH process; check the source code and license before installation.

Reference Links

  • GitHub repository: https://github.com/GLFzr/dsh-file-upload
  • Directory page reference: https://www.skillhub.cn/plugins/GLFzr/dsh-file-upload