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.
- Language
- JavaScript
- License
- BSD-3-Clause
- Branch
- main
Install
$ dsh plugin --profile web add dsh-drag-and-dropRun 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/locateroute) - Architecture pattern: DSH bundle dual-end architecture. The host half registers a precise path
/file-drop/locatePOST route onwebServervia Cordiseffect, responsible for local path location and fingerprint computation; the client half mounts the plugin todsh.profile.bundlesthroughcordis.patch.yml, and injects into DSH's runtime and conversation UI services viadsh.client.inject, listening fordragenter/dragover/dragleave/dropevents on window, writing parsed paths to the input state service viaconversation.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
| Dependency | Minimum Version | Notes |
|---|---|---|
| DSH | Not declared | Only declares web profile in package.json#dsh.client.platform, install with --profile web |
| Node.js | ^20.0.0 or >=22.0.0 | From package.json#engines.node |
| Platform | macOS / Linux / Windows | Cross-platform; Linux recommends plocate, Windows recommends Everything CLI, Windows has PowerShell fallback |
| Native modules | None | Uses 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
/mntand/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'spnpm add + config.yamlworkflow is deprecated (README.md:55) - No
TODO/FIXME/HACK/XXXcomments 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)
Install: dsh plugin --profile web add github:omdsh-dev/dsh-drag-and-drop
A DeepSeek Harness Web UI plugin: drag local files or folders onto any part of the page and their original absolute filesystem paths are inserted into the current conversation input — without uploading, moving, or copying anything.
Why this exists
A browser never hands a web page the real filesystem path of a dropped file — it exposes only a local file URI when it feels like it, and often nothing at all, for security. DSH, though, operates on real files: its tools read, run, and patch actual paths on the machine. Drop a file into an ordinary web input and you get either an upload (a copy that silently breaks the file's relationship with its neighboring dependencies) or a hand-typed path that is easy to get wrong.
This plugin closes that gap on the machine running DSH. It converts the browser's local file URI into the native absolute path, and when the browser hides the path entirely it resolves the file back to its real location — through the current Workspace, registered Workspaces, the OS file index, and a bounded directory search — then writes that path into the current conversation input. The file never leaves its directory.
Features
- Drag files onto any part of the Web UI to insert their original absolute paths
- Full-page dim + blur hint while dragging
- Supports files and folders; drag multiple items at once — one path per line
- Native paths on macOS, Linux, and Windows
- POSIX paths, Windows drive-letter paths, and UNC network paths
- No uploading, moving, or copying of files
- Locates files in the current Workspace and registered Workspaces first
- When the browser hides the original path, uses the local file index and bounded directory search
- Computes content fingerprints only when multiple candidates exist
- When several byte-identical copies cannot be told apart automatically, lets the user pick the path
- Failed lookups surface as a dismissible plugin toast (auto-dismisses after 8s; hovering pauses the timer)
- Writes the draft via DSH's input-state service instead of touching the input DOM
Usage
Drag files or folders from Finder, a Linux file manager, or Windows Explorer onto any part of the DSH Web UI.
Release the mouse when the full-page drag hint appears; the plugin writes the resolved original absolute path into the current conversation input.
Dropping multiple items at once inserts one path per line.
Install
The plugin is a DSH bundle (package.json declares dsh.bundle + dsh.client). Install it into the web profile with the standard dsh plugin mechanism — no DSH source changes and no config.yaml needed:
dsh plugin --profile web add github:omdsh-dev/dsh-drag-and-drop
# or from a local checkout:
dsh plugin --profile web add /path/to/dsh-drag-and-drop
The repository ships its build output (lib/ is committed) — no build step needed after installing.
The old README's
pnpm --filter @deepseek-ai/dsh add ...+config.yamlflow is obsolete: under the official profile/bundle modelconfig.yamlis no longer read.
After installing, restart the Web UI the way you normally start DSH, then refresh the browser page — the plugin appears in the browser boot manifest (__DSH_BOOT__) and its client bundle loads automatically.
Upgrade
dsh plugin --profile web update github:omdsh-dev/dsh-drag-and-drop
For a local-path installation, run add again against the replacement checkout.
Uninstall
dsh plugin --profile web remove @omdsh-dev/dsh-drag-and-drop
The command removes the package from the profile and from dsh.profile.bundles. After uninstalling, restart the Web UI and hard-refresh the browser.
Troubleshooting
| Symptom | Resolution |
|---|---|
| Dropping a file inserts nothing | Drag again and confirm the full-page hint appears. Verify the bundle is in the profile (`dsh --profile web --dump-config |
| Wrong path inserted when several copies share a name | Candidates are filtered by full file name and size, then content-sampled only among the survivors. If byte-identical copies remain, the plugin shows a chooser — pick the correct path there |
| Path resolution is slow on a large disk | Install the platform index (Linux: plocate; Windows: Everything CLI) and keep files inside a Workspace or a common directory. Every search is bounded: 3s per index command, at most 100 candidates, at most 20,000 directory entries per root |
| macOS/Linux: dropping a folder resolves nothing | Folders are matched by name against Workspaces and common directories; a folder outside every searchable root cannot be located when the browser hides the path — move it into a Workspace or install the OS index |
| Plugin does not load after install | Restart the Web UI and hard-refresh the browser — the client bundle only loads on a fresh page load with the plugin in __DSH_BOOT__ |
Path resolution
If the browser exposes a local file URI, the plugin converts it directly into the operating system's native path.
If the browser hides the original path for security reasons, the plugin locates the file in this order:
- The current Workspace
- Other registered Workspaces
- Desktop, Documents, and Downloads
- A depth-1..3 shallow scan within each search root: the root's direct child, the direct children of its direct subdirectories, and the direct children of those subdirectories — this resolves the vast majority of real drops (e.g.
~/Downloads/dump2 11/iotclaw.ndjson) without walking the whole tree - The operating system's file index
- A bounded, platform-specific directory search
System indexes used per platform:
- macOS: Spotlight
- Linux:
plocatefirst, thenlocate - Windows: Everything CLI first, then PowerShell
On Linux, when the system index returns no candidates, the plugin also searches the user home directory and mount points under /mnt and /media.
On Windows, when the system index returns no candidates, the plugin also searches the user directory and available fixed disks.
To keep searches bounded:
- a single external index command times out after 3 seconds
- at most 100 candidate paths are kept
- the depth-3 shallow scan expands at most 4,096 direct subdirectories per root
- each recursive search root visits at most 20,000 directory entries
- unreadable directories and files are ignored
Candidate confirmation
Candidates are first filtered by:
- the full file name
- the file size
Modification time is used only for ranking candidates, never as identity.
<<<<<<< HEAD If only one candidate remains, the plugin uses that path directly without reading the file's content.
每一层搜索都先做浅层快速定位:先检查搜索根的直接子项,再检查直接子目录与孙目录内的直接子项(共三层以内的文件,绝大多数拖拽都在这一范围内),随后才查询该范围内的操作系统索引,最后才递归目录。当前 Workspace、其他 Workspace 和常用目录的优先级保持不变。
4bab506 (feat: resolve dropped-file paths up to three levels deep)
If multiple candidates remain, the plugin compares sampled fingerprints from the beginning, middle, and end of the files. Only when sampled fingerprints of large files still collide does it compute a full SHA-256.
If several paths correspond to byte-identical files, the plugin shows the list of paths and lets the user choose which one to insert.
Folders are first searched by name only. A unique candidate is returned directly without traversing the browser directory; multiple same-name candidates are compared by sorted relative path, project type, and file size. For directories that are structurally identical, content samples of up to 24 deterministically chosen files are computed; if still identical, the user picks the path. Directory traversal processes at most 10,000 entries and 32 levels deep, and never follows symlinks or Windows junctions.
Each search level first checks the direct children of the search root, then queries the OS index within that scope, and only then recurses into directories. The priority of the current Workspace, other Workspaces, and common directories is preserved.
Privacy & file access
The plugin never:
- uploads files
- copies files
- moves files
- modifies files
- deletes files
In most cases the plugin only reads file metadata.
Only when multiple candidates share the same name and size does it read a small amount of content to compute sampled fingerprints, and only when large files cannot be told apart by sampling does it read the full content to compute SHA-256.
All resolution and fingerprinting happens locally on the machine running DSH.
Platform notes
macOS
Finder drag-and-drop and the Spotlight index are supported. Verified in Chrome on macOS.
Linux
File managers that provide text/uri-list are supported. When the browser hides the path, the plugin searches Workspaces, common directories, plocate, locate, and bounded mount directories.
Installing plocate is recommended for faster global path resolution.
Windows
Drive-letter paths and UNC network paths are supported. When the browser hides the path, the plugin prefers the Everything CLI; without Everything it uses PowerShell to search the user directory and fixed disks.
Installing Everything and its command-line tools significantly speeds up path resolution on large disks.
Development and verification
The build script needs a DSH checkout. By default it locates one through the dsh command; you can also point it explicitly:
DSH_CHECKOUT=/path/to/dsh pnpm run build
Run tests:
pnpm test
Type-check:
pnpm run check
Build:
pnpm run build
Repository layout:
src/— host (node) half: path resolution, directory walk, fingerprinting, platform search, and the file-locate HTTP routesrc/client/— browser half: drag handling, drop items, path locator, candidate chooser, toast UItests/— vitest suites for the host and client logiclib/— committed build output (host + client bundles)
Community and About
- Use GitHub Issues for reproducible bugs, focused feature requests, and usage questions.
- Read CONTRIBUTING.md before proposing changes; report vulnerabilities privately via SECURITY.md.
- Follow releases and compatibility notes in CHANGELOG.md.
License
BSD-3-Clause
Read the usage guide →
Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.
Listing badge
[](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.