前言¶

在 DeepSeek Harness（DSH）的 Web 界面裏，@ 是引用文件和會話的主要入口。默認實現下，每敲一個字符都要向 Host 發一次請求，由 Host 端過濾候選；工作區文件多、歷史會話多時，菜單打開和過濾的延遲會明顯堆積。

dsh-better-at 的做法是把文件索引和會話索引提前拉到瀏覽器，過濾和排序全部在本地完成，同時保留原生 @ 引用的行爲和 mention 格式。下面介紹這個插件。

這是什麼¶

dsh-better-at 是一個面向 DSH Web GUI 的插件，定位是「@ 文件/會話引用的本地緩存加速」，由 Ruiming-cn 維護，MIT 許可證，當前版本 0.2.0。

它保留原生 DSH @ 引用行爲——層級式的工作區文件/文件夾引用和 DSH 會話引用——只是把「每次按鍵都請求 Host」變成「初始化時拉一次索引，之後本地過濾」。實現上不修改 Harness 源碼，由一個樹外 Host Remote 加一個瀏覽器 client bundle 組成。

核心功能¶

• 會話級預熱：首次 @ 之前預加載工作區文件索引與 DSH 會話索引，加快首次打開速度。
• 本地按鍵過濾：初始加載後，輸入過濾與候選排序完全在瀏覽器本地完成，不再每次按鍵請求 Host。預熱後的首個 @ 通常直接由內存返回，後續按鍵是對緩存索引做 O(N) 字符串打分。
• 層級文件/文件夾引用：空查詢或路徑查詢顯示直接子項；純模糊查詢在整個工作區搜索文件 basename。
• DSH 會話引用：完整會話元數據在本地建索引，按工作目錄親和度排序，與原生排序一致。
• 原生 mention 兼容：包裝現有的 reference source 並保留其 onPick/codec，文件與會話 mention 保持原始序列化形式（@path、@"path"、@[label](dsh-session:...)）。

整體結構如下（來自倉庫 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

Host 側提供兩個接口：

• betterAt/listFiles：遍歷當前工作區一次，返回有上限的文件/目錄索引。默認只排除 .git 和 node_modules，與原生文件引用搜索的行爲一致。
• betterAt/listSessions：通過 ctx.sessionQuery 讀取完整會話數據，爲瀏覽器生成原生 dsh-session: mention。

緩存策略與代價¶

緩存是這類插件的核心，先說清楚參數：

• 文件索引按會話緩存 30 秒；會話索引全局緩存 5 分鐘。
• 兩者都採用 stale-while-revalidate：緩存過期時先返回舊快照，再在後臺刷新，刷新期間菜單不會空白。

代價是一個小的即時性窗口：文件變更最長約 30 秒纔出現在候選裏，會話元數據最長約 5 分鐘。對引用場景來說，這通常是可以接受的折衷。

安裝與啓用¶

前提：DSH Web 需具備原生 @ reference source；本地開發/構建需要 Node.js。lib/ 已提交到倉庫，profile 安裝本身不需要本地構建步驟。

1、從 GitHub 源碼安裝：

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

2、也可以用 GitHub release tarball：

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

3、或者從本地檢出安裝：

dsh plugin --profile web add .

安裝後需重啓 dsh web 生效。如果要本地開發或跑測試，倉庫提供了 npm install --legacy-peer-deps 和 npm run check（含 typecheck、test、build 腳本）。

典型用法¶

裝好後按原來的習慣使用 @ 即可：

• @ 打開快速文件/文件夾 + 會話選擇器；
• @src/ 瀏覽 src/ 目錄內部；
• @README 對文件 basename 做模糊搜索；
• @refactor 按 id、cwd 或 label 過濾 DSH 會話。

選中之後走原生 composer 行爲：文件變成原子文件引用（或可編輯的目錄路徑），DSH 會話變成原生會話引用。

配置¶

插件只提供兩個配置項，通過 profile patch 設置，示例文件爲 ~/.dsh/profiles/web/cordis.patch.yml：

- id: dsh-better-at
  config:
    maxEntries: 10000
    ignoreDirs:
      - .git
      - node_modules

• maxEntries：默認 10000，索引工作區條目的硬上限，遍歷超出時會報告截斷。
• ignoreDirs：默認 ['.git', 'node_modules']，這些目錄名從不被索引或遍歷。

兼容性與邊界¶

• 符號鏈接不被索引或遍歷，與原生文件引用搜索行爲一致。
• 當前會話會從 DSH 會話候選中排除，避免自引用——原生會話引用協議會拒絕這種情況。
• 瀏覽器集成使用與 dsh-skill-fuzzy 相同的私有 inputTriggers.live.sources 包裝模式；若未來 Harness 版本改變了這個內部結構且 Remote 不可用，插件會降級爲原生 candidates 路徑。
• 依賴前文的私有包裝模式，意味着它對 Harness 內部實現有一定耦合，版本升級後值得驗證一遍。

適用場景與安全提醒¶

適合的人羣：工作區文件多、歷史會話多，經常在 DSH Web 裏用 @ 引用文件或會話，對菜單響應速度敏感的使用者。反過來，如果你的工作區很小、@ 菜單本來就不慢，收益有限，還要接受最長 30 秒/5 分鐘的新鮮度窗口，可以先觀察再決定。

一點提醒：DSH 的理念是「一切皆插件」，插件以當前 dsh 進程的權限運行。安裝第三方插件前，建議閱讀其源碼並確認許可證（本項目爲 MIT），評估無誤後再裝。

結尾¶

回顧一下：dsh-better-at 通過會話級預熱加瀏覽器本地過濾，去掉了 @ 菜單的逐鍵 Host 往返，同時保留原生 mention 形式與排序，配置只有 maxEntries 和 ignoreDirs 兩項，裝完重啓 dsh web 即可。

• 社區目錄頁：https://www.skillhub.cn/plugins/Ruiming-cn/dsh-better-at
• GitHub 倉庫：https://github.com/Ruiming-cn/dsh-better-at

文中目錄頁來自社區維護的獨立站點，與 DeepSeek、幻方無官方從屬關係。