前言¶
用 DeepSeek Harness（DSH）做智能體開發時，經常需要讓模型「盯住」某個具體文件：審查一份 PDF 規格、對照 src/client/view.ts 改代碼、或者只討論某個目錄下的配置。如果每次都要手動複製路徑、粘貼進提示詞，對話一多就容易出錯，上下文也容易變得冗長。
社區插件 dsh-at-file（維護者 FSMargoo）把 Cursor / Codex 裏常見的 @file 體驗搬到了 DSH 的 Web 輸入區：在 composer 裏輸入 @，搜索當前工作區文件或目錄，選中後把路徑掛到提示詞上。截至 2026 年 8 月，該倉庫在 GitHub 上約有 466 個 Star、19 個 Fork，採用 MIT 許可證。
需要提前說明：官方 DeepSeek Harness 較新版本已內置 @file 與 @session 引用能力，新環境可優先用官方實現；dsh-at-file 仍適合已有插件化部署、需要獨立配置過濾規則或沿用舊工作流的場景，維護者表示會盡力繼續維護。
這是什麼¶
dsh-at-file 是一款面向 DSH Web 界面的社區插件。它在輸入框提供工作區路徑檢索與引用，而不是在後臺替模型做推理。
一句話概括：在 composer 裏用 @ 搜索工作區，把文件或目錄的相對路徑附到提示詞；智能體開始執行前，插件會校驗路徑是否落在當前工作區內，並插入一條簡短的引用標記，由會話中的工具按需讀取內容。
在 SkillHub 插件庫 中，該插件歸類爲「模型推理」；在 DeepSeek Harness 社區插件目錄 中則歸入「工具與能力」。無論目錄怎麼分，它的核心價值都在於降低「指定文件上下文」的操作成本。
核心功能與亮點¶
Codex 風格的 @ 路徑選擇器¶
在 composer 輸入 @ 後會彈出可滾動候選列表（最多 50 條）。純文件名查詢時，精確匹配、前綴匹配會排在更前面；空查詢時，淺層路徑優先於深層路徑，同深度下目錄排在文件前面。
查詢裏帶 / 時按路徑段順序匹配，例如 src/view 可定位到 src/client/view.ts；src/ 則在該目錄下繼續篩選。高亮目錄時按 ArrowRight 可進入子目錄，草稿會變成 @path/ 並保持菜單打開；Enter 或鼠標點選則完成引用。
每條結果上方顯示完整文件名，下方顯示父目錄；重名文件會在主標籤裏附帶父目錄，並用內置 SVG 圖標區分文件夾、源碼、文本、PDF、圖片、配置、壓縮包等類型。
路徑引用，而非強行塞全文¶
自 v0.3.0 起，插件不再在提交時直接把文件內容讀進提示詞，也不再對文件大小做硬性截斷。選中路徑後，智能體啓動前會生成類似下面的引用標記：
<workspace-reference path="docs/spec.pdf" kind="file" />
標記只包含工作區相對路徑與類型（file / directory）。插件本身不會打開文件，也不會列出目錄內容；需要時由當前會話裏的 read、read_image 等工具處理。PDF 與文本文件走同一套路徑引用流程。
智能過濾與可配置忽略規則¶
默認索引會跳過常見版本庫目錄、IDE 元數據、依賴樹、構建產物與緩存（覆蓋 VS Code、JetBrains、Gradle、Xcode、CMake、Flutter、.NET、Unity 等生態），並排除 desktop.ini、Thumbs.db、.DS_Store 等系統文件。
在 Settings → File mentions 中可管理過濾規則：
- Global：所有工作區共享；
- Workspace：僅對當前工作區追加規則，並繼承全局列表。
每條規則支持 Exact（完整 basename）或 Regex（對 basename 做 JavaScript 正則），可單獨開關大小寫敏感。無效正則在保存前會被攔截；Restore defaults 可恢復內置全局列表，Clear workspace rules 只清空當前工作區附加項。
粘貼行爲與安全邊界¶
默認情況下，從外部粘貼的 @path 文本不會觸發選擇器、不會出現在引用欄，也不會生成 workspace-reference 標記，避免誤把聊天記錄裏的 @ 當成文件引用。若需要舊行爲，可在 Settings → File mentions 關閉 Ignore @ mentions in pasted text。
Host 只接受工作區相對路徑；絕對路徑或試圖逃逸工作區的路徑會被忽略。@path 令牌不能包含空白或第二個 @。點擊引用欄中的路徑會調用 Harness 的 host.openPath 打開文件。
安裝與啓用¶
社區目錄頁給出的通用安裝命令如下：
dsh plugin add github:FSMargoo/dsh-at-file
如需可復現安裝，可固定 commit：
dsh plugin add github:FSMargoo/dsh-at-file#<commit-hash>
該插件主要服務 Web profile。倉庫 README 中推薦的帶版本號安裝方式如下（安裝後需重啓 dsh web，以便 Host 與瀏覽器客戶端加載 v0.6.8）：
dsh plugin --profile web add https://github.com/omdsh-dev/dsh-at-file/archive/refs/tags/v0.6.8.tar.gz
說明：README 安裝包 URL 指向 omdsh-dev/dsh-at-file 的 release 歸檔，與當前主倉庫 FSMargoo/dsh-at-file 爲同一插件線的發佈來源，以倉庫文檔爲準。
⚠️ 安全提示：DSH 插件以當前 dsh 進程權限運行，安裝過程可能執行構建或初始化腳本。安裝前請閱讀 GitHub 源碼 與 MIT 許可證，確認來源可信。
典型用法示例¶
在提示詞裏引用單個文件¶
在 composer 輸入 @，搜索並選擇 docs/spec.pdf，草稿可能類似：
Review @docs/spec.pdf
發送後，插件校驗路徑存在，再插入 workspace-reference 標記；智能體隨後可用會話工具打開並閱讀該 PDF。
引用目錄¶
用 @ 選中目錄（例如 src/components/），引用類型爲 directory。插件不會自動枚舉目錄內容，適合表達「請在這個目錄範圍內改動」這類意圖，具體文件仍由智能體按需讀取。
通過 cordis.patch.yml 調整索引規模¶
若工作區文件極多，可在 Web profile 的配置補丁中限制索引條目數或自定義忽略目錄。配置文件通常位於 ~/.dsh/profiles/web/cordis.patch.yml：
- id: dsh-at-file
config:
maxIndexedFiles: 10000
ignoreDirs 若省略，則沿用內置忽略列表；若顯式提供，則需自行列出所有要排除的目錄名。設爲 [] 表示索引時不跳過任何目錄（大型 monorepo 需謹慎）。
適用場景與注意事項¶
適合誰用
- 已在 DSH Web 界面高頻對話、希望用
@快速點名文件或目錄的開發者； - 需要細粒度文件過濾（Exact / Regex、全局與工作區分級）的團隊；
- 暫時無法升級到有內置
@file的 Harness 版本、但仍想保留路徑引用體驗的舊環境。
使用注意
- 與官方能力重疊：新裝 DSH 可先確認內置
@file/@session是否已滿足需求，再決定是否單獨安裝本插件。 - Web 場景爲主：安裝命令與設置面板均圍繞
--profile web；CLI-only 工作流收益有限。 - 索引緩存：路徑索引按會話緩存約 30 秒；修改過濾規則後會清空相關緩存，下次
@搜索會重建索引。 maxIndexedFiles隻影響選擇器：超出索引上限時，仍可通過手動輸入存在的相對路徑完成引用。- 工具能力取決於會話：UTF-8 文本通常可用
read，圖片可用read_image；PDF 等格式能否處理，取決於當前智能體綁定的工具集。 - 社區目錄非官方商店：SkillHub 與 deepseek-harness-plugin.com 均爲社區維護的插件索引，與 DeepSeek / 幻方無官方從屬關係；「一切皆插件」是 DSH 的架構理念，安裝決策仍應回到源碼與許可證。
結尾¶
如果你希望在 DSH 的 Web composer 裏用 @ 像寫 IDE 一樣引用工作區路徑，而不是反覆複製粘貼絕對路徑，dsh-at-file 是目前社區裏較成熟的選擇之一：搜索體驗完整、過濾可配置、引用語義與官方 Harness 工具鏈銜接清晰。即便官方已內置類似能力，瞭解這款插件的路徑標記與過濾機制，也有助於理解 DSH 如何把「文件上下文」從 UI 層傳到智能體層。
