前言¶
在 DSH Web GUI 中讓模型讀取工作區文件時，常見做法是手動把文件路徑寫進輸入框，或在提示裏說明“請看某個文件”。在多文件項目裏，這樣容易漏選文件、寫錯路徑，也容易被 .gitignore、項目文檔、編譯產物等邊界干擾。
dsh-file-mention 是 DSH（DeepSeek Harness）Web GUI 的一個客戶端插件。它在聊天輸入框裏提供 @ 文件引用能力：輸入 @ 後即時過濾工作區文件，選中後插入 @相對路徑，模型即可直接讀取該文件。下面介紹它的定位、核心功能、安裝方式和適用場景。
插件定位¶
- 插件名：
@hucj/dsh-file-mention - 倉庫：
hucj09/dsh-file-mention - 許可證：MIT © 2026 hucj
- 平臺：
dsh.client.platform爲web - 運行環境：
package.json要求 Node >= 22 - 用途：在 DSH Web GUI 輸入框中，通過
@選擇工作區文件並插入相對路徑
核心功能¶
輸入 @ 觸發文件候選¶
在輸入框輸入 @，會觸發工作區文件候選菜單。
插件支持按文件名或完整路徑即時過濾，大小寫不敏感，最多展示 30 條。選中文件後，輸入框會插入 @相對路徑，用於讓模型讀取該文件。
掃描範圍¶
插件的文件候選來源包括：
- git 跟蹤文件
- 未跟蹤且未被忽略的新文件
這意味着新建文件即使沒有 git add，也可以被 @ 引用；同時插件天然遵守 .gitignore，被忽略的文件和目錄默認不會進入候選。
如果 git 不可用或當前目錄不是倉庫，插件會回退爲 .gitignore 解析與全量掃描。
.aiinclude 重新納入¶
有些文件雖然被 .gitignore 忽略，但模型或開發者仍然希望在 @ 菜單中引用，例如本地文檔、配置草稿或輔助材料。
可以在工作區根目錄創建 .aiinclude，使用 .gitignore 語法，把被忽略的文件或目錄重新納入掃描範圍。
# 使用 .gitignore 語法，把需要納入掃描的文件或目錄寫在這裏
子目錄也可以配置 .aiinclude。子目錄中的規則相對該目錄生效，並覆蓋根配置。
修改 .aiinclude 後，數據約 90 秒內收斂；刷新頁面可加速客戶端部分生效。
目錄引用與排序¶
插件支持目錄引用，並支持逐級展開和單段查詢直達子目錄。
候選排序支持以下匹配優先級：
- 精確匹配
- 前綴匹配
- 子串匹配
在同等匹配條件下，插件優先展示變更文件。最近修改或新增的變更文件會置頂，上限 5 個。
菜單、緩存與邊界¶
插件將候選菜單加寬至 720px，並調整字號與行高，用於提升文件候選的可讀性。
緩存方面：
- 客戶端按工作區
cwd共享緩存，並採用 stale-while-revalidate - Host 側對 git 結果做分層緩存
安全邊界方面，插件限制：
- 文件總數上限 10000
- 遍歷深度 32
- 跳過重型目錄
安裝與卸載¶
npm 方式安裝¶
先執行安裝命令：
dsh plugin --profile web add @hucj/dsh-file-mention
執行後重啓 dsh web，在瀏覽器中按 Ctrl+F5 強刷頁面。進入輸入框輸入 @，如果出現 file 分組，即表示安裝成功。
本地路徑安裝¶
如果需要在本地調試，也可以使用本地路徑安裝：
dsh plugin --profile web add file:D:/path/to/dsh-file-mention
需要注意，file: 安裝是一次性拷貝。源碼改動後，需要重新編譯並重新安裝，安裝目錄不會自動同步源碼變化。
宿主依賴¶
插件需要宿主已組裝 input-trigger 相關依賴。README 註明標準 web 部署默認包含該依賴。
卸載¶
卸載命令如下：
dsh plugin --profile web remove @hucj/dsh-file-mention
執行後重啓 dsh web 使卸載生效。
典型用法¶
- 在 DSH Web GUI 輸入框中輸入
@，彈出工作區文件候選菜單。 - 按文件名或完整路徑繼續輸入，即時過濾候選文件。
- 選擇目標文件後，輸入框中插入
@相對路徑。 - 將消息發送給模型，模型即可基於該路徑讀取對應文件。
如果項目中存在被 .gitignore 忽略但需要被 @ 引用的文件，可以這樣做：
- 在工作區根目錄創建
.aiinclude。 - 使用
.gitignore語法，將目標文件或目錄寫入.aiinclude。 - 等待約 90 秒內收斂，或刷新頁面加速客戶端部分更新。
- 重新輸入
@，確認目標文件進入候選列表。
如果某個子目錄需要單獨調整納入規則，也可以在子目錄中放置 .aiinclude。規則相對該目錄生效，並覆蓋根配置。
適用場景與注意¶
適合以下情況使用：
- 在 DSH Web GUI 中頻繁讓模型讀取工作區文件
- 希望減少手工輸入路徑帶來的錯誤
- 需要把 git 跟蹤文件和未跟蹤新文件統一納入候選
- 需要遵循
.gitignore邊界，同時保留部分本地文檔或配置的引用能力 - 需要在目錄結構中快速定位子目錄或子文件
使用注意：
- 插件以當前
dsh進程權限運行，安裝前建議檢查源碼與許可證。 .aiinclude會擴大可被引用的文件範圍，不要把敏感文件無差別納入。- 本地
file:安裝是一次性拷貝，源碼修改後需要重新編譯並重新安裝。 - DSH 插件生態強調可擴展性；社區目錄是獨立站點，與 DeepSeek / 幻方無官方從屬關係，不應把它寫成官方應用商店。
