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.1.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

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