前言¶
在 DSH 這類插件式 harness 中，Agent 經常需要引用本機文件路徑，但聊天界面本身不一定有方便瀏覽本機磁盤的入口。dsh-file-browser 是 Clearchenpro 維護的一個 DSH 插件，許可證爲 MIT，面向 web 版 harness：它在會話頭部提供“文件”按鈕，點擊後在聊天界面右端打開一個文件瀏覽欄，用來查看、排序本機目錄，並把文件路徑或圖片附件送入聊天草稿。
這是什麼¶
一句話定位：DSH 客戶端插件，給 web 版 DSH 會話右側加一個全盤文件瀏覽面板。
它解決的是“從聊天界面快速找到本機文件，並把路徑交給 Agent”的入口問題。插件瀏覽的是 host 進程所在機器的磁盤，只對 web 版 harness 有意義。
核心功能¶
- 在聊天界面右端添加全盤文件瀏覽欄。
- 逐層瀏覽所有盤符：Windows 枚舉
A:–Z:，POSIX 爲/；同時支持主目錄，並提供麪包屑導航。 - 按名稱、大小、修改時間排序，支持升序和降序；文件夾默認分組置頂。
- 服務端流式掃描，並有界 Top-K 截斷，默認每層 1000 條。
- 拖文件進聊天框：
- 圖片：
png、jpg、jpeg、gif、webp，且不超過readMaxBytes時，變成真正的圖片附件； - 其他文件或目錄：在草稿中插入反引號包裹的絕對路徑。
- 行內快捷操作：插入路徑、直接發送路徑給 Agent、複製路徑、用系統默認應用打開。
- 會話頭部提供“文件”按鈕開合面板；面板寬度可拖，範圍
280–560px。 - 文案支持中/英雙語：通過 harness
locale服務註冊file-browser命名空間，無服務時回退中文。
安裝與啓用¶
先確認目標 profile。下面命令用於把插件安裝到指定 DSH profile：
dsh plugin --profile <目標profile> add "dsh-file-browser@file:<本目錄絕對路徑>"
如果已經打出 tarball，也可以用 tarball 安裝：
dsh plugin --profile <目標profile> add ./dsh-file-browser-0.1.0.tgz
安裝後，用下面命令確認插件已註冊，並重啓對應 DSH 實例：
dsh plugin --profile <目標profile> list
dsh --profile <目標profile> --dump-config
dsh --profile <目標profile>
已運行的實例需要重啓後才生效。
開發期如果用 --patch 指向構建產物，源碼路徑條目沒有可解析的 package.json，client 半不會加載。本地聯調 client 半時，建議使用上面的 dsh plugin add 方式安裝。
典型用法¶
會話頭部出現“文件”按鈕後，點擊它，右端會出現文件瀏覽欄。
在目錄列表中，可以切換名稱、大小、修改時間排序，並切換升序、降序。超過每層 1000 條時，列表會按當前排序保留最靠前的條目，需要用排序或導航縮小範圍。
把文件拖入聊天框：
- 拖入
txt、py等普通文件，草稿中會插入`路徑`； - 拖入
png、jpg、jpeg、gif、webp圖片，若大小滿足readMaxBytes，聊天框中出現圖片附件； - 無會話時拖拽會有提示。
行內操作可以直接完成常見動作：
- “發送”：把路徑作爲消息發給 Agent；
- “插入路徑”：把路徑寫入草稿；
- “複製”：複製路徑；
- “打開”：用系統默認應用打開該文件或目錄。
兼容與依賴¶
插件按 harness @deepseek-ai/*@0.1.0-rc.6 的實際 API 編寫。
已覈實的依賴信息：
- 依賴：
@deepseek-ai/schemastery ^3.18.1 - peer 依賴：
@deepseek-ai/cordis ^4.0.1、@deepseek-ai/dsh-web ^0.1.0-rc.6、react ^18.2.0
安全與限制¶
這個插件會讀取 host 進程所在機器上的文件系統，並以當前 DSH 進程權限運行。安裝前應檢查源碼、許可證和運行環境。
需要注意：
- 它僅對 web 版 harness 有意義。
- 瀏覽的是 host 進程所在機器的磁盤，不是瀏覽器所在機器的本地磁盤。
- 拖拽默認把路徑寫進草稿，而不是把任意二進制上傳爲附件；DSH 會話只有圖片附件語義，其他文件通常由 Agent 的 fs 工具按路徑讀取。
- 目錄大小不遞歸統計，顯示爲
—；目錄在按大小排序時按名稱排序。 - 隱藏文件按 dot 前綴判斷，與 harness 既有約定一致；面板內可開關顯示隱藏文件。
- 插件路由不在
/api信任圍欄內，因此執行 Host 頭 loopback 校驗，支持127.0.0.1、localhost、[::1]，可用trustedHosts擴展。 - 路由只接受 GET，不設 CORS，並設置
Cache-Control: no-store。 - 如果 harness 以 LAN 地址訪問且 Host 頭不是 loopback，需要在
trustedHosts中列明該 Host，否則文件面板相關請求會返回 403。
結尾¶
dsh-file-browser 的價值比較具體：給 web 版 DSH 會話提供一個本機文件入口，讓 Agent 更容易拿到明確的路徑或圖片附件。適合需要頻繁讓 Agent 處理本機文件的開發者使用。
GitHub：https://github.com/Clearchenpro/dsh-file-browser
社區目錄：https://www.skillhub.cn/plugins/Clearchenpro/dsh-file-browser
