前言¶

DeepSeek Harness（dsh）是 DeepSeek AI 開源的智能體框架，官方倉庫把架構概括成一句話：一切皆插件。當前仍處於開發者預覽階段，Web UI 默認跑在 http://127.0.0.1:3080。日常寫代碼時，真正費事的往往不是模型本身，而是怎麼把「就看這個文件」說清楚：完整相對路徑要手敲，複製粘貼又容易把無關內容塞進上下文。

OpenAI Codex 一類工具用 @文件 解決這件事。社區插件 dsh-at-file 把類似交互接到了 DeepSeek Harness 的 Web 輸入框：輸入 @ 搜索當前工作區，選中後把路徑引用進提示詞。需要說明的是，社區插件目錄頁仍寫着「把內容直接附進提示詞」；倉庫 README 和 package.json 對 0.3.0 及之後版本的描述不同——插件只附路徑，不注入文件正文。本文按目錄頁、GitHub 倉庫 README（含中文版）和 package.json 交叉覈對後整理。

社區目錄站點 deepseek-harness-plugin.com 是獨立收錄站，與 DeepSeek / 幻方沒有官方從屬關係，不要把它當成官方應用商店。

這是什麼¶

dsh-at-file 是一款面向 DeepSeek Harness Web 界面 的工作區路徑引用插件，由組織賬號 omdsh-dev 維護，許可證爲 MIT，主要語言是 JavaScript。社區目錄把它歸在「工具與能力」，並標爲精選；倉庫創建於 2026-08-13，GitHub 主題爲 dsh、dsh-plugin。2026-08-17 覈對該倉庫時，星標爲 271（目錄頁當時顯示 172，以 GitHub 爲準）。

它解決的問題很具體：在輸入框裏用 @ 搜索並插入工作區文件或目錄路徑，讓後續步驟知道「目標在哪」，而不是把整份文件塞進提示詞。package.json 裏的一句話更直白：search workspace paths without injecting file content。

當前倉庫 package.json 版本爲 0.6.1，Git 標籤同樣有 v0.6.1。dsh.client.platform 聲明爲 web，因此它服務的是 Web GUI，不是 headless 會話。

核心功能¶

1. 在輸入框用 @ 選路徑¶

在 composer（輸入框）裏輸入 @，插件會搜索當前工作區，彈出路徑選擇器。選中一項後，路徑會留在草稿裏；輸入框上方的引用欄可以打開該路徑，也可以移除引用。倉庫給出的示例是：

請檢查 @docs/spec.pdf

普通關鍵詞只匹配文件名。完整名稱、前綴和緊湊匹配會排在前面，不會因爲長目錄路徑裏碰巧散落幾個字母就給出無關結果。關鍵詞裏帶 / 時，按路徑片段依次匹配，例如 src/view 可以找到 src/client/view.ts；輸入 src/ 則在該路徑下繼續搜。

高亮某個目錄後，按右方向鍵可以進入該目錄：草稿會變成 @路徑/，末尾不加空格，候選菜單保持打開。回車或鼠標點選目錄，則直接完成這次目錄引用。

候選項優先顯示文件名，下方是父目錄；重名文件會把父目錄寫進主標題。內置 SVG 圖標用來區分目錄、源代碼、文本、PDF、圖片、數據與配置、壓縮包以及其他文件。

2. 提交時只附加路徑引用，不讀文件內容¶

每次 agent 開始處理前，插件會確認該路徑仍在當前工作區且確實存在，然後補充一條短消息：

<workspace-reference path="docs/spec.pdf" kind="file" />

引用裏只有工作區相對路徑和類型（kind）。插件不會打開被引用的文件，也不會列出被引用目錄的內容。真正讀文件、看圖、解析 PDF，都交給當前會話裏已有的工具。README 寫明：DSH 的 read 用於 UTF-8 文本，read_image 用於支持的圖片；PDF 能否處理，取決於這次會話裝了什麼工具。

文件格式和文件大小都不會改這條流程。PDF 和普通源碼走同一套路徑引用。倉庫明確說：以上機制適用於 0.3.0 及後續版本；更早的版本會在提交時讀取文件內容，並受文件大小限制。如果目錄頁或第三方列表仍寫「把內容附進提示詞」，那是舊行爲，不要按舊版預期來用現在的插件。

3. 默認跳過噪音目錄，過濾規則可改¶

默認索引會跳過常見版本控制目錄、IDE 元數據、依賴樹、緩存和構建產物，覆蓋 VS Code、Visual Studio、JetBrains IDE、Fleet、Eclipse、Android / Gradle、Xcode、CMake、Flutter、.NET、Unity、Unreal，以及常見 JavaScript、Python 輸出目錄。desktop.ini、Thumbs.db、.DS_Store 也會默認排除。

需要再收緊時，打開 設置 → 文件提及：

• 全局：所有工作區共用
• 工作區：當前所選工作區路徑的附加規則；面板會同時顯示繼承來的全局規則

每條規則可單獨選匹配方式和大小寫：

• Exact：匹配一個完整文件名，不接受路徑分隔符
• Regex：用 JavaScript 正則匹配完整文件名，不包含父目錄或工作區路徑
• 區分大小寫：默認關閉，Exact 和 Regex 都能開

無效正則會在保存前報錯，Host 也會拒絕。恢復默認值只重置全局列表；清空工作區規則只刪當前工作區的附加項。設置通過插件自己的 Host 接口寫進 DSH web profile。舊的字符串規則會繼續當成不區分大小寫的 Exact 規則。改規則會清掉相關索引緩存，下一次輸入 @ 就會用新規則。

4. 索引範圍可以寫進 profile¶

路徑選擇器還有兩項配置，寫在所選 profile 的 cordis.patch.yml 裏，常用路徑是 ~/.dsh/profiles/web/cordis.patch.yml：

• maxIndexedFiles：工作區索引條目上限
• ignoreDirs：替換內置忽略目錄列表；設成 [] 會索引所有目錄

倉庫給出的示例只改上限：

- id: dsh-at-file
  config:
    maxIndexedFiles: 10000

省略 ignoreDirs 就繼續用內置列表；一旦填寫，就要列出全部想排除的目錄名，不是在默認列表上追加。

路徑處理還有幾條硬約束，都來自 README：

• 只索引常規文件和目錄，跳過已配置的目錄名與符號鏈接
• 全局和工作區文件名規則在 Host 遍歷時合併；被過濾的條目不佔用 maxIndexedFiles，也不會發到瀏覽器
• Host 只接受工作區相對路徑；絕對路徑、越出工作區的路徑會被忽略
• 只有用戶自己輸入的文本會生成引用消息
• 點擊引用路徑會調用 Harness 的 host.openPath
• 每個會話的路徑索引緩存 30 秒
• @路徑 不能包含空白，也不能再含另一個 @
• maxIndexedFiles 只限制選擇器結果；手動輸入的路徑只要在工作區且存在，仍可引用

安裝與啓用¶

社區目錄頁給出的安裝命令是：

dsh plugin add github:omdsh-dev/dsh-at-file

需要可復現安裝時，目錄頁建議固定 commit：

dsh plugin add github:omdsh-dev/dsh-at-file#commit

把 #commit 換成實際提交哈希。倉庫 README 寫明：lib/ 裏的構建產物會提交進倉庫，profile 安裝不必再跑包構建腳本。

README 另外給出了針對 web profile、並釘到標籤包的寫法（文檔示例仍是 v0.6.0）：

dsh plugin --profile web add https://github.com/omdsh-dev/dsh-at-file/archive/refs/tags/v0.6.0.tar.gz

同一條命令也可用來更新已有安裝。裝完後重啓 dsh web，讓 Host 和瀏覽器客戶端都加載對應版本。倉庫當前最新標籤是 v0.6.1，與 package.json 的 0.6.1 一致；README 安裝段尚未改到這個標籤。若要跟文檔走，用上面的 v0.6.0 包；若要跟最新標籤，把 URL 裏的 v0.6.0 換成 v0.6.1 即可。

目錄頁有一條安全提示，安裝前應當看完：插件以當前 dsh 進程的權限運行，安裝時可能執行代碼。先檢查源代碼倉庫和許可證，再決定是否安裝。

典型用法¶

裝好並重啓 Web UI 之後，流程就是：打開工作區 → 在輸入框輸入 @ → 選文件或目錄 → 用自然語言寫任務。

下面這個例子直接來自倉庫文檔，可以按原樣試：

請檢查 @docs/spec.pdf

提交後，agent 側會看到類似：

<workspace-reference path="docs/spec.pdf" kind="file" />

它拿到的是路徑，不是 PDF 正文。接下來會不會調用 read、別的解析工具，或告訴你當前會話沒有合適工具，取決於這次會話的工具集，而不是插件本身。

需要引用某個子目錄時，可以輸入 src/ 縮小範圍，或在目錄候選上按右方向鍵進入後再選文件。路徑裏不要加空格，也不要寫第二個 @。選擇器沒列出的文件，只要路徑確實在工作區內，仍可手動寫成 @相對路徑 再提交。

索引太大或太吵時，先改 設置 → 文件提及 的文件名規則；還不夠再改 cordis.patch.yml 裏的 maxIndexedFiles 和 ignoreDirs。改完不必重裝插件，但 ignoreDirs 是整表替換，漏寫內置目錄名會把原先跳過的依賴目錄重新編進索引。

適用場景與注意事項¶

比較適合這些情況：

• 主要在 dsh web 裏工作，需要反覆指向某個源文件、配置、文檔或目錄
• 希望交互接近 Codex 的 @ 提及，但不想把大文件或 PDF 整份打進提示詞
• 工作區裏噪音目錄多，需要默認忽略規則，或按倉庫再加一層文件名過濾

使用前注意：

1. 平臺是 Web。package.json 把 client 平臺寫成 web，不要默認它在 headless / TUI 裏同樣可用。
2. 它是路徑引用，不是自動貼正文。0.3.0 之後不再在提交時讀文件；agent 讀不讀、讀不了某種格式，取決於會話工具。
3. 安全邊界按工作區切。絕對路徑和逃出工作區的路徑會被忽略；符號鏈接默認不進索引。
4. DeepSeek Harness 仍在開發者預覽，官方 README 寫明會有破壞兼容性的變更。插件也在快速發版（倉庫已有 v0.2.0 到 v0.6.1 一串標籤），安裝時儘量釘 commit 或標籤。
5. 插件以當前 dsh 進程權限運行。安裝前讀一遍源碼和 MIT 許可證，只裝自己信任的來源。

小結¶

dsh-at-file 給 DeepSeek Harness 的 Web 輸入框補了一層 Codex 風格的 @ 路徑選擇：搜索工作區、插入相對路徑、在 agent 起步前附上 <workspace-reference />。當前實現刻意不注入文件內容，把「打開、閱讀、解析」留給會話裏的工具。這和部分目錄摘要裏的舊錶述不一致，以倉庫 README 爲準。

目錄頁：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-at-file/

GitHub：https://github.com/omdsh-dev/dsh-at-file