Ruiming-cn/dsh-better-at

Fast @ file/session reference caching for the DeepSeek Harness Web GUI.

dsh-better-at keeps the native DSH @ reference behavior — hierarchical workspace file/folder references and DSH session references — while removing the per-keystroke host round trips that make the @ menu feel slow.

Features

• ⚡ Fast first open: session-scope warm-up preloads the workspace file index and the DSH session index before the first @.
• ⚡ Local keystroke filtering: after the initial load, typing filters and ranks candidates entirely in the browser; no Host request per keystroke.
• 📁 Hierarchical file/folder references: empty/path queries show direct children, bare fuzzy queries search basenames across the whole workspace.
• 💬 DSH session references: full session metadata is indexed locally and ranked by working-directory affinity, matching the native ordering.
• 🔒 Native mention compatibility: the plugin wraps the existing reference source and keeps its onPick/codec, so file and session mentions keep the original serialized form (@path, @"path", @[label](dsh-session:...)).
• 🧩 No Harness source changes: everything is implemented as an out-of-tree Host Remote + browser client bundle.

How It Works

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

• betterAt/listFiles walks the current workspace once and returns a bounded file/directory index. Defaults exclude .git and node_modules only, matching the native file-reference behavior.
• betterAt/listSessions reads the complete logical session corpus from ctx.sessionQuery and generates native dsh-session: mentions for the browser.
• File indices are cached per session for 30 seconds; the session index is cached globally for 5 minutes. Both use stale-while-revalidate: an expired cache returns the previous snapshot immediately while refreshing in the background.
• The browser wraps the native @ source (trigger='@', name='reference') without replacing its pick/codec path.

Requirements

• DeepSeek Harness (DSH) Web with the native @ reference source available.
• Node.js for local development/building.

Installation

One command from GitHub source:

dsh plugin --profile web add github:Ruiming-cn/dsh-better-at

From the GitHub release tarball:

dsh plugin --profile web add https://github.com/Ruiming-cn/dsh-better-at/archive/refs/tags/v0.2.0.tar.gz

From a local checkout:

dsh plugin --profile web add .

Restart dsh web after installation.

Usage

Use @ exactly as usual:

• @ opens the fast file/folder + session picker.
• @src/ browses inside src/.
• @README fuzzy-searches file basenames.
• @refactor filters DSH sessions by id, cwd, or label.

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

Configuration

The Host plugin accepts two settings through the profile patch:

# ~/.dsh/profiles/web/cordis.patch.yml
- id: dsh-better-at
  config:
    maxEntries: 10000
    ignoreDirs:
      - .git
      - node_modules

Option	Default	Description
maxEntries	10000	Hard cap on indexed workspace entries; the walk reports truncation.
ignoreDirs	['.git', 'node_modules']	Directory basenames never indexed or traversed.

Performance Notes

• The first @ after a warm session is normally served from memory.
• Subsequent keystrokes are local O(N) string scoring over the cached index (file index is bounded by maxEntries; session index is bounded by the local session corpus).
• The main trade-off is a small freshness window: file changes may take up to 30 seconds to appear; session metadata up to 5 minutes. Background refreshes keep the previous snapshot visible while updating.

Compatibility Notes

• The browser integration intentionally uses the same private inputTriggers.live.sources wrapping pattern as dsh-skill-fuzzy. If a future Harness version changes that internal structure, the plugin degrades to the native candidates path when the Remote is unavailable.
• Symbolic links are not indexed or traversed, matching the native file-reference search behavior.
• The current session is excluded from DSH session candidates to avoid self-references, which the native session-reference protocol rejects.

Development

npm install --legacy-peer-deps
npm run check

• npm run typecheck — TypeScript strict typecheck.
• npm run test — pure-function unit tests (Node test runner).
• npm run build — builds lib/index.js (Host ESM), lib/client.js (single-file browser bundle) and .d.ts declarations.

lib/ is committed so profile installs can run without a build step.

License

MIT