dsh-file-mention

繁體中文版：README.zh.md

@ file mentions + drag-and-drop file → path text for the
DeepSeek Harness (DSH) Web composer.

A DSH Web plugin that turns files in your workspace into lightweight, agent-readable
references. Pick a file from an @ menu — or drop one onto the page — and the composer
inserts an @-prefixed path as plain text; the agent then reads that path with its
own tools (read, etc.). No provider attachment mechanism is involved.

Features

• @ file mentions — type @ and a files group appears, scanned from the current
  session's workspace directory.
• Workspace-relative by default — files inside the workspace present and insert their
  relative path (concise); files reached through an explicit outside path (/…, ~/…,
  ../…) present and insert their absolute path (more information).
• Bare @ opens the menu — an empty query still lists a default set of workspace files.
• Tab to accept — highlight a candidate with the arrow keys and press Tab to
  insert it, no mouse needed.
• Drag-and-drop files — drop any non-image file onto the page; it is uploaded to the
  host and its path is inserted as @-prefixed text. Pure-image drags pass through to the
  built-in image rail untouched.
• All references carry @ — inserted paths are always prefixed with @ to mark them as
  file references (@README.md, @/Users/you/project/README.md).

Installation

Requires a running DeepSeek Harness
Web profile with the @ input-trigger service (ctx.inputTriggers; the plugin
peer-depends on dsh-client-ui-input-trigger / dsh-client-runtime / dsh-client-locale
^0.1.0-rc.7). On an older host the @/files menu never appears.

Install straight from GitHub — no npm publish required (the plugin is build-less, so a
git install needs no extra allowBuilds step):

dsh plugin --profile web add github:tipoLi5890/dsh-file-mention

While developing, link a local clone instead (edits take effect on restart):

dsh plugin --profile web add link:/absolute/path/to/dsh-file-mention

Verify the entry joined the profile, then restart the web server for the new Loader entry
and its bundle to take effect:

dsh --profile web --dump-config   # you should see a row with id: file-mention

Usage

In the composer:

The path is plain text. On send, the agent resolves a relative path against its session
cwd (the workspace) and reads absolute paths directly.

How it works

The package declares a dsh.bundle.patch (a self-inserting Loader entry) and a dsh.client
browser half served into the /plugins boot graph.

Host half — lib/index.js

Hand-written ESM, no build step. Registers a /api/file-mention route prefix on the
profile's web server (ctx.webServer):

• GET /api/file-mention/search?base=<abs workspace dir>&q=<query> — a bounded directory
  scan (depth ≤ 8, ≤ 2000 entries, ≤ 50 results, ~600 ms budget; skips .git/node_modules,
  never follows symlinks; hidden files are included only when the query starts with . or
  matches). base is the session workspace cwd (falls back to the host home). Name-only
  queries scan the whole workspace; path-like queries (/…, ~/…, ./…, ../…) resolve
  the directory part and scan only that directory. Returns
  { files: [{ name, dir, path, rel }] } — path is always absolute, rel is the
  workspace-relative path (or null when outside), and dir is the display directory
  (relative inside the workspace, absolute outside).
• POST /api/file-mention/upload?sessionId=&name= (raw bytes body, 50 MB cap) — sanitizes
  the name/session id, writes collision-safely under <DSH_HOME>/uploads/<sessionId>/,
  returns { path }.

Browser half — lib/client.js

Loaded in the lazy-CJS factory form the client module loader expects (no build step, no
React). Registers an @/files InputTriggerSource via ctx.inputTriggers; onPick
returns { text: "@" + path + " " } (the pipeline replaces the @query token span with
plain text). Capture-phase dragenter/dragover/drop listeners claim non-image drags,
upload each file, and insert the returned paths at the caret.

API

Limitations

• Browsers do not expose a dragged file's native path, so dropped files are copied into
  <DSH_HOME>/uploads/<sessionId>/ and the copy's path is inserted (the agent can read it;
  your workspace is untouched).
• The @ menu group title shows the source's raw name files (the
  inputTriggers.menu locale namespace is owned by dsh-client-ui-input-trigger).
• Mixed drags (images + files) upload images as files too (inserting path text rather than
  going to the image rail).
• When the composer is busy/locked, the machine may reject the insertion; the plugin falls
  back to copying the paths to the clipboard.
• Single-file upload cap is 50 MB (host constant).
• The web server remains loopback-only and unauthenticated (same posture as the app).

License

MIT © 2026 dsh-file-mention contributors