在 DSH (DeepSeek Harness) 中開發智能體時，讓 Agent 讀寫本地文件是常見需求。直接將文件內容灌入上下文會消耗大量 token，且可能包含無關信息。dsh-file-mention 插件提供了在輸入框中直接引用文件路徑的方案。Agent 收到該引用後，會通過自帶的本地文件工具按路徑自行讀取或操作文件，而不是將內容注入上下文。
功能概述¶
這是由 Seryta 維護的 DSH Web GUI 插件。核心能力是在輸入框裏用 @（或 /file 命令）模糊搜索會話工作區下的文件路徑，選中後插入 @相對路徑。
主要特性包括：
- 雙入口觸發：支持
@內聯觸發（推薦）和/file命令觸發。 - 模糊搜索：支持子序列模糊匹配，如輸入
src/butt可命中src/button.go。 - 實時索引：打開會話即後臺預熱索引，利用服務端 BFS 遍歷和 30s 內存緩存，新文件秒級可見。
- 交互體驗：輸入
@即彈出工作區頂層條目菜單。支持鍵盤（Enter/Tab）或鼠標選擇。Composer 上方會顯示附件條 dock，列出 draft 中的所有引用。純單詞形態的文件名（如Makefile）會被高亮裝飾。 - 併發控制：擊鍵產生的過時信號只丟棄對應結果，在途請求繼續存活，避免打字快於首查時菜單無法更新。
安裝與啓用¶
使用官方安裝命令添加插件：
dsh plugin --profile web add github:Seryta/dsh-file-mention
安裝後重啓 dsh web 並刷新頁面。
典型用法¶
1. @ 內聯觸發¶
這是推薦的用法。
- 在輸入框開頭或空格後輸入
@，彈出工作區淺層條目菜單。 - 繼續輸入路徑片段（如
@src/butt）進行過濾。 - 候選菜單按
file分組列出匹配的文件與目錄。 - 鍵盤選中後按 Enter 或 Tab 補全當前高亮項（鼠標點擊同樣生效）。
補全遵循文件系統慣例：文件補全爲 @file（空格結束）；目錄補全爲 @dir/。如果是空目錄，補全後自動加空格；有子內容（或未確認）則不加空格，光標停在斜槓後繼續輸入子路徑瀏覽。想提前結束目錄瀏覽，手動輸入一個空格即可。
2. /file 命令¶
如果 @ 觸發異常，可使用此備用入口。
- 輸入
/file後直接接路徑片段（如/fileAGENTS，無空格）。 - pick 後同樣插入
@相對路徑。
示例¶
輸入：請修復 @src/main.go 裏的空指針
Agent 會按 src/main.go 路徑定位並操作。
配置項¶
插件提供可選的環境變量配置：
FILE_MENTION_ALLOWED_ROOTS：逗號分隔的允許搜索根目錄（絕對路徑）。設置後才啓用白名單，白名單外的 root 返回 400；不設置則放行（與host.listDirectory的瀏覽暴露面一致）。FILE_MENTION_IGNORE_DIRS：追加剪枝目錄 basename，逗號分隔（默認爲內置剪枝表）。FILE_MENTION_MAX_FILES：單次遍歷收集文件數上限，默認爲600000。
已知限制¶
- 空格問題：引用路徑不能含空格，含空格的文件名無法通過輸入完整路徑選中。
- 符號鏈接：符號鏈接不跟隨；不返回文件大小。
- 內容預覽：插入的是路徑引用而非文件內容，Agent 需要讀文件時會自己調 read 工具。超大/二進制文件不在菜單裏做任何預覽。
- 端點暴露：API 端點僅暴露路徑列表，不讀內容。
與同類插件的區別¶
| 項目 | dsh-at-file | dsh-file-mention (本插件) |
|---|---|---|
| 行爲 | 發送時內容注入 | 發送時路徑引用，Agent 自讀 |
| 優缺點 | 模型可直接看到內容，但不便操作文件 | 省 token，Agent 可操作文件，模型需自行決定讀哪些文件 |
總結¶
dsh-file-mention 解決了在 Web GUI 中快速引用本地文件的需求，通過路徑引用而非內容注入，節省了 token 並保持了 Agent 對文件操作的靈活性。開發者可以根據需要調整搜索範圍（ALLOWED_ROOTS）和忽略目錄（IGNORE_DIRS）。
