dsh-file-mention: Referencing Files via @ Commands in the DSH Web Interface

When developing agents in DSH (DeepSeek Harness), reading and writing local files is a common requirement. Injecting file contents directly into the context consumes many tokens and may include irrelevant information. The dsh-file-mention plugin provides a way to reference file paths directly in the input box. After receiving such a mention, the Agent uses its built-in local file tools to read or operate on the file by path, instead of injecting the content into the context.

Feature Overview¶

This is a DSH Web GUI plugin maintained by Seryta. Its core capability is to fuzzy search for file paths under the session workspace using @ (or the /file command) in the input box, and insert @relative path after selection.

Main features include:

• Dual trigger entries: Supports @ inline triggering (recommended) and /file command triggering.
• Fuzzy search: Supports subsequence fuzzy matching. For example, typing src/butt can match src/button.go.
• Real-time indexing: The index is warmed up in the background when a session is opened. It uses server-side BFS traversal and a 30-second memory cache, so new files become visible within seconds.
• Interaction experience: Typing @ opens a menu with top-level entries in the workspace. Selection is supported via keyboard (Enter/Tab) or mouse. An attachment dock is displayed above the Composer and lists all mentions in the draft. Filenames that are plain single words (such as Makefile) are highlighted.
• Concurrency control: Stale signals caused by keystrokes only drop the corresponding results, while in-flight requests remain alive. This prevents the menu from failing to update when typing is faster than the initial lookup.

Installation and Activation¶

Add the plugin using the official install command:

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

After installation, restart dsh web and refresh the page.

Typical Usage¶

1. @ Inline Trigger¶

This is the recommended usage.

1. Type @ at the beginning of the input box or after a space to open the workspace shallow-entry menu.
2. Continue typing a path fragment (for example, @src/butt) to filter.
3. The candidate menu lists matching files and directories, grouped by file.
4. After keyboard selection, press Enter or Tab to complete the current highlighted item (mouse click also works).

Completion follows file system conventions: files are completed as @file (terminated with a space); directories are completed as @dir/. If the directory is empty, a space is added automatically after completion. If it has subcontent (or status is unconfirmed), no space is added, and the cursor stays after the slash so you can continue typing the subpath. To end directory browsing early, manually type a space.

2. /file Command¶

If the @ trigger does not work correctly, use this fallback entry.

1. Type /file followed directly by a path fragment (for example, /fileAGENTS, with no space).
2. After selection, @relative path is inserted in the same way.

Example¶

Input: Please fix the null pointer in @src/main.go

The Agent will locate and operate on the file using the path src/main.go.

Configuration¶

The plugin supports optional environment variable configuration:

• FILE_MENTION_ALLOWED_ROOTS: Comma-separated allowed search root directories (absolute paths). The whitelist is enabled only after this is set; roots outside the whitelist return 400. If not set, access is allowed (consistent with the browsing exposure of host.listDirectory).
• FILE_MENTION_IGNORE_DIRS: Additional directory basenames to prune, comma-separated (default is the built-in pruning list).
• FILE_MENTION_MAX_FILES: Maximum number of files collected in a single traversal; defaults to 600000.

Known Limitations¶

• Spaces: Mentioned paths cannot contain spaces, so files with spaces in their names cannot be selected by typing the full path.
• Symbolic links: Symbolic links are not followed; file sizes are not returned.
• Content preview: The inserted value is a path mention, not file content. When the Agent needs to read the file, it will invoke the read tool itself. Oversized or binary files are not previewed in the menu.
• Endpoint exposure: API endpoints expose only path lists, not file contents.

Differences from Similar Plugins¶

Summary¶

dsh-file-mention addresses the need to quickly reference local files in the Web GUI. By using path mentions instead of content injection, it saves tokens while preserving the Agent’s flexibility for file operations. Developers can adjust the search scope (ALLOWED_ROOTS) and ignored directories (IGNORE_DIRS) as needed.