Skip to main content

dsh-drag-and-drop

20Stars4Forks2Issues0Watchers

Drag a local file into DSH Web UI to automatically insert its absolute path instead of uploading the file content. The file itself remains untouched—no upload, copy, or move operations.

Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki
Language
JavaScript
License
BSD-3-Clause
Branch
main
dshdsh-plugin

Install

cmdweb profile
$ dsh plugin --profile web add dsh-drag-and-drop

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

Install via your agent

Install the DeepSeek Harness plugin bill9109/dsh-drag-and-drop for me: review the repository at https://github.com/bill9109/dsh-drag-and-drop first, then run the install command and verify the plugin loads successfully.

Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.

Quick Summary

Implement "drag-to-insert-path" in DSH Web UI: drag a local file or folder from the system file manager to any position on the page, and the plugin writes the original OS absolute path into the current session input box. The file itself is not uploaded, copied, or moved.

Core Capabilities

  • Drag a local file or folder to any position in the Web UI, and write the original absolute path into the current session input box
  • During drag, show full-page dimming + blur hint, submit on release
  • Drag multiple files/folders at once, each path added on a new line to the draft (does not overwrite existing input)
  • Supports macOS, Linux, Windows native paths, including Windows drive letters and UNC network paths
  • When the browser hides the path for security reasons, retrieve the real path on the machine by searching in order: "current Workspace → other Workspaces → Desktop/Documents/Downloads → three-layer shallow scan → system index (Spotlight / plocate / locate / Everything) → controlled directory search"
  • For multiple candidates with identical names and sizes, use three-segment sampling (start/middle/end) for fingerprint matching; only compute full SHA-256 if large files still conflict; if all are identical, present a candidate list for user selection

Technical Implementation

  • Language: TypeScript (compiles to both Node-side host bundle and browser-side client bundle, committed to lib/)
  • Key dependencies: @deepseek-ai/cordis (host-side Cordis context); @deepseek-ai/dsh-client-runtime, @deepseek-ai/dsh-client-ui-conversation (client-side runtime and conversation service); @deepseek-ai/dsh-host-webserver (registers /file-drop/locate route)
  • Architecture pattern: DSH bundle dual-end architecture. The host half registers a precise path /file-drop/locate POST route on webServer via Cordis effect, responsible for local path location and fingerprint computation; the client half mounts the plugin to dsh.profile.bundles through cordis.patch.yml, and injects into DSH's runtime and conversation UI services via dsh.client.inject, listening for dragenter / dragover / dragleave / drop events on window, writing parsed paths to the input state service via conversation.input.for(scope).setDraft() (does not directly modify DOM)
  • Entry files: src/index.ts (host), src/client/index.ts (client), cordis.patch.yml (bundle injection point)

Use Cases

You want DSH to directly operate on real files on your local machine—for example, having an Agent read ~/Downloads/log.txt, modify ~/projects/foo/bar.py, or run ~/scripts/build.sh. However, due to browser sandbox security, browsers do not give web pages the real paths of dragged files. Normal drag-and-drop either uploads a copy or requires manually typing error-prone paths. This plugin completes the chain on the machine running DSH: drag once, and the original absolute path is in the input box. The file itself never leaves its directory.

Prerequisites & Compatibility

DependencyMinimum VersionNotes
DSHNot declaredOnly declares web profile in package.json#dsh.client.platform, install with --profile web
Node.js^20.0.0 or >=22.0.0From package.json#engines.node
PlatformmacOS / Linux / WindowsCross-platform; Linux recommends plocate, Windows recommends Everything CLI, Windows has PowerShell fallback
Native modulesNoneUses only Node.js built-ins (node:os / node:path / node:fs/promises / node:crypto / node:child_process / node:http) and browser WebCrypto

Installation

dsh plugin --profile web add github:bill9109/dsh-drag-and-drop

After installing or upgrading, please restart the DSH Web service, then hard refresh in browser (Cmd/Ctrl+Shift+R). The client bundle only mounts on fresh page load.

Configuration

This plugin requires no additional configuration. Install and use—no Schema, no config.yaml, no environment variables read.

FAQ

Q: Does dragging a file upload it to the server? Does it copy or move the file?

A: No. The plugin only reads metadata like filename, size, modification time from the dragged item in the browser. Only when there are multiple candidates with the same name and size does it read a small amount of file content to compute fingerprints for comparison. Throughout the process, the file stays in its original directory—no uploading, copying, moving, modifying, or deleting.

Q: Why is there no response after installation?

A: The client bundle only mounts on fresh page load, so after installation or upgrade you must first restart the DSH Web service, then hard refresh in browser (Cmd/Ctrl+Shift+R). You can use dsh --profile web --dump-config | grep drag-and-drop to confirm the bundle is registered to the profile.

Q: Dragging on a large disk takes a long time to produce results. How to speed up?

A: Drag resolution speed depends on local indexing. Linux recommends installing plocate, Windows recommends installing Everything CLI (provides es.exe), macOS has Spotlight built in—no extra configuration needed. Placing files inside your Workspace or common directories also hits faster shallow scan paths.

Q: After dragging, an incorrect duplicate file was inserted. What to do?

A: Candidates are first filtered by exact filename and size, then compared using three-segment sampling fingerprint (start/middle/end). If large files still cannot be distinguished after sampling, full SHA-256 is computed. If there are still byte-identical duplicates, the plugin pops up a candidate path list for you to select.

Q: After dragging, the browser shows "unsupported image format" prompt. Is this normal?

A: This is actively replaced by the plugin: when dragging a file/folder but the target is not an image, the original toast displays as "Unsupported image format: xxx (file path inserted by drag plugin)". The plugin tells you "handled by drag plugin," the original absolute path has been written to the session input box, not a real failure.

Q: Can folders be dragged? What happens when dragging multiple at once?

A: Both files and folders can be dragged. When dragging multiple items, the plugin resolves each using the "Workspace priority → system index" strategy, writing each candidate path on a new line to the current session input draft. Existing draft content won't be lost; it gets appended on new lines.

Q: How to upgrade, how to uninstall?

A: Upgrade with dsh plugin --profile web update github:bill9109/dsh-drag-and-drop; uninstall with dsh plugin --profile web remove @omdsh-dev/dsh-drag-and-drop, then restart Web service and hard refresh browser. For local checkout installation, upgrade by re-running add on the replaced directory.

Difficulty Level

Beginner — one dsh plugin command to install and use. No config files, no environment variables. After installation, restart Web + hard refresh browser to take effect.

Known Issues & Limitations

  • After dragging, if the browser hides the path and the file is located outside all searchable roots (current/other Workspaces, Desktop/Documents/Downloads, user home, Linux's /mnt and /media, Windows fixed drives), it cannot be located and will show "Failed to locate original path" toast (README.md:82)
  • Single external index command (Spotlight / plocate / locate / es.exe / PowerShell) has 3-second timeout, keeps up to 100 candidate paths; falls back to next-level search on timeout or too many hits (src/platform-search.ts:8-9, src/locator.ts:11)
  • Shallow three-directory scan expands up to 4,096 direct subdirectories per search root; recursive search visits up to 20,000 directory entries per root, max 12 levels deep (src/locator.ts:11-15)
  • Folder structure matching supports up to 10,000 entries, max 32 levels deep, doesn't follow symlinks or Windows junctions (src/directory.ts:3-4, src/directory-node.ts:18)
  • Large files (> 8 MB) with multiple candidate sampling fingerprint conflicts compute full SHA-256, which can be noticeably slow for very large files (src/locator.ts:205-207, src/fingerprint.ts:36-51)
  • Drag request body (POST /file-drop/locate) capped at 4 MB, rejected by host if exceeded (src/index.ts:8)
  • On Windows, Everything CLI (es.exe) output uses console active code page (GBK on Chinese systems), plugin decodes with both UTF-8 and GBK and selects results that can reproduce the requested filename; if your system code page is neither UTF-8 nor GBK, non-ASCII filenames may still not match precisely (src/platform-search.ts:100-117)
  • Does not read config.yaml; the old README's pnpm add + config.yaml workflow is deprecated (README.md:55)
  • No TODO / FIXME / HACK / XXX comments found in source; the three-layer shallow scan added in 0.1.5 primarily solves "files at depth 2 missed by direct subitem scan, exhausted by 20,000-item recursive budget" problem (CHANGELOG.md:14-19)

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/bill9109/dsh-drag-and-drop)

Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.

← Back to plugin directory