Introduction

In the DeepSeek Harness (DSH) Web interface, @ is the primary entry point for referencing files and sessions. Under the default implementation, every keystroke sends a request to the Host for candidate filtering; when there are many files in the workspace and many historical sessions, the delay for opening the menu and filtering becomes noticeably accumulated.

The approach taken by dsh-better-at is to pull file and session indexes to the browser in advance, performing all filtering and sorting locally, while preserving native @ reference behavior and mention formats. Here is an introduction to this plugin.

What is it

dsh-better-at is a plugin for the DSH Web GUI, positioned as a “local caching accelerator for @ file/session references”. It is maintained by Ruiming-cn, under the MIT license, and the current version is 0.2.0.

It preserves the native DSH @ reference behavior—hierarchical workspace file/folder references and DSH session references—just changing “requesting the Host on every keystroke” to “pull the index once on initialization, followed by local filtering”. In terms of implementation, it does not modify Harness source code but consists of a Host Remote plus a browser client bundle.

Core Features

  • Session-level Preheating: Preloads workspace file index and DSH session index before the first @, speeding up the initial opening speed.
  • Local Keystroke Filtering: After initial load, input filtering and candidate ranking are performed entirely in the browser locally, no longer requesting the Host on every keystroke. The first @ after preheating is usually returned directly from memory; subsequent keystrokes perform O(N) string scoring on the cached index.
  • Hierarchical File/Folder References: Empty queries or path queries show direct children; pure fuzzy queries search the entire workspace for file basenames.
  • DSH Session References: Complete session metadata is indexed locally, sorted by working directory affinity, consistent with native sorting.
  • Native Mention Compatibility: Wraps the existing reference source and preserves its onPick/codec, keeping file and session mentions in their original serialized form (@path, @"path", @[label](dsh-session:...)).

The overall structure is as follows (from the repository README):

DSH Web @ menu
      │  candidates() · local filter/rank
      ▼
dsh-better-at client cache
      │  listFiles / listSessions (once per TTL)
      ▼
DSH Host betterAt Remote
      ├── bounded workspace file/directory index
      └── full DSH session index + canonical mentions

The Host side provides two interfaces:

  • betterAt/listFiles: Traverses the current workspace once, returning a bounded file/directory index. Defaults to excluding .git and node_modules, consistent with native file reference search behavior.
  • betterAt/listSessions: Reads complete session data via ctx.sessionQuery and generates native dsh-session: mentions for the browser.

Caching Strategy and Trade-offs

Caching is the core of this type of plugin; let’s clarify the parameters first:

  • File index is cached per session for 30 seconds; session index is globally cached for 5 minutes.
  • Both use stale-while-revalidate: when the cache expires, the old snapshot is returned first, followed by a background refresh; during the refresh, the menu will not appear blank.

The cost is a small real-time window: file changes take up to approximately 30 seconds to appear in candidates, and session metadata takes up to approximately 5 minutes. For reference scenarios, this is usually an acceptable trade-off.

Installation and Activation

Prerequisites: DSH Web must have the native @ reference source; local development/build requires Node.js. lib/ is committed to the repository, and profile installation itself does not require local build steps.

  1. Install from GitHub source:
dsh plugin --profile web add github:Ruiming-cn/dsh-better-at
  1. Alternatively, use a GitHub release tarball:
dsh plugin --profile web add https://github.com/Ruiming-cn/dsh-better-at/archive/refs/tags/v0.2.0.tar.gz
  1. Or install from a local checkout:
dsh plugin --profile web add .

After installation, restart dsh web for the changes to take effect. If doing local development or running tests, the repository provides npm install --legacy-peer-deps and npm run check (containing typecheck, test, and build scripts).

Typical Usage

After installing, just use @ as you normally would:

  • @ opens the quick file/folder + session selector;
  • @src/ browses inside the src/ directory;
  • @README fuzzy searches for file basenames;
  • @refactor filters DSH sessions by id, cwd, or label.

After selection, the native composer behavior is followed: files become atomic file references (or editable directory paths), and DSH sessions become native session references.

Configuration

The plugin only provides two configuration items, set via a profile patch; the example file is ~/.dsh/profiles/web/cordis.patch.yml:

- id: dsh-better-at
  config:
    maxEntries: 10000
    ignoreDirs:
      - .git
      - node_modules
  • maxEntries: Default 10000, the hard limit for indexing workspace entries; reports truncation when traversing beyond this limit.
  • ignoreDirs: Default ['.git', 'node_modules'], these directory names are never indexed or traversed.

Compatibility and Boundaries

  • Symbolic links are not indexed or traversed, consistent with native file reference search behavior.
  • The current session is excluded from DSH session candidates to avoid self-reference—the native session reference protocol will reject this case.
  • Browser integration uses the same private inputTriggers.live.sources wrapper pattern as dsh-skill-fuzzy; if a future Harness version changes this internal structure and the Remote is unavailable, the plugin will fall back to the native candidates path.
  • Relying on the private wrapper pattern mentioned earlier means it has some coupling to Harness’s internal implementation; it is worth verifying after version upgrades.

Suitable Use Cases and Security Reminders

Suitable for: Users with many workspace files, many historical sessions, who frequently use @ to reference files or sessions in DSH Web, and are sensitive to menu response speed. Conversely, if your workspace is small and the @ menu isn’t slow to begin with, the benefit is limited, and you have to accept a freshness window of up to 30 seconds/5 minutes, you might want to observe the situation first before deciding.

A reminder: DSH’s philosophy is “everything is a plugin,” and plugins run with the permissions of the current dsh process. Before installing third-party plugins, it is recommended to read the source code and check the license (this project is MIT), and confirm it is safe before installing.

Conclusion

Recap: dsh-better-at removes the per-keystroke Host round-trips of the @ menu by combining session-level preheating with browser local filtering, while preserving native mention forms and sorting. Configuration only has two items, maxEntries and ignoreDirs; restart dsh web after installing.

The directory page mentioned in the text comes from a community-maintained independent site and has no official affiliation with DeepSeek or Hanhua.