前言¶

在 DSH 的插件體系裏，agent 經常需要訪問本地文件。已有做法中，dsh 自帶的文件工具通常作用於 dsh 宿主所在機器；如果 dsh 部署在遠程環境，而用戶瀏覽器在另一臺機器上，agent 就無法直接操作瀏覽器所在機器的本地文件。

dsh-browser-fs 用來補上這個缺口：它讓 dsh web 頁面裏的 agent 通過 File System Access API 獲得用戶對本地目錄的授權，並通過插件提供的模型工具完成目錄列表、文本讀取和文本寫入。

這是什麼¶

whitefirer/dsh-browser-fs 是一個面向 dsh web 端面的客戶端插件，核心目標是讓 dsh 的 agent 讀寫瀏覽器所在機器的本地文件。

它主要做三件事：

• 註冊 browser_fs_list、browser_fs_read、browser_fs_write 三個模型工具；
• 插件自建 WebSocket 通道，把工具調用轉發到持有授權句柄的瀏覽器標籤執行；
• 瀏覽器端在 shell.overlay 層註冊浮動卡片，顯示連接/授權狀態並管理目錄授權。

許可證爲 MIT。倉庫地址：

https://github.com/whitefirer/dsh-browser-fs

核心功能¶

授權目錄與模型工具¶

插件允許用戶通過 File System Access API 授權一個本地目錄。完整模式下，選擇目錄需要 readwrite 權限。

授權後，agent 可以調用下面三個工具：

browser_fs_list { path?, recursive? }
browser_fs_read { path, maxBytes? }
browser_fs_write { path, content }

其中：

• browser_fs_list 用於列目錄；
• browser_fs_read 用於讀文本文件；
• browser_fs_write 用於寫文本文件。

browser_fs_read 默認上限爲 256 KiB，截斷時會標註。agent 工具僅支持 UTF-8 文本讀寫，二進制寫入不在範圍內。

卡片瀏覽與文件預覽¶

瀏覽器端的 browser-fs 卡片可以提供授權目錄內容樹瀏覽，並支持文件名/路徑搜索、複製相對路徑。

在目錄樹中點文件名可以打開預覽窗，支持圖片與文本預覽。文本預覽只取前 64KB。圖片超過 8MB 時不拉取。

完整模式下，文本預覽可編輯並保存。文本/代碼預覽支持語法着色，highlight.js 採用懶加載。

圖片僅在卡片內預覽，不提供 agent 工具讀取二進制內容的完整支持。

多設備與連接狀態¶

多臺設備可以各自授權各自的本機目錄。host 半維護執行者名單，並把工具調用路由到合適的瀏覽器標籤執行。

客戶端斷線時會指數退避重連，並支持 abort 與瀏覽器 cancel 幀。

兼容模式¶

File System Access API 要求 HTTPS 或 localhost 安全上下文。非安全上下文下，插件會自動進入兼容模式。

完整模式與兼容模式的能力差異如下：

安裝與啓用¶

先執行安裝命令：

dsh plugin --profile web add dsh-browser-fs

然後重啓 dsh，使插件生效。

本地開發或從源碼安裝時，需要先構建，再用 file: 路徑重裝：

npm run build
dsh plugin --profile web add file:/abs/path/to/dsh-browser-fs

完成後重啓 dsh。

安裝時注意兩點：

• host 半以 peerDependency 依賴 @deepseek-ai/dsh-tools；
• client 半默認固定連接 WebSocket 路徑 /browser-fs/ws。如果 host 半修改 wsPath，client 半的 DEFAULT_WS_PATH 需要同步修改並重新 build。

典型用法¶

下面是一個常見流程。

1. 打開 dsh web 頁面，在右下角的 browser-fs 卡片點擊“授權目錄”，選擇一個本地目錄。
2. 在卡片內瀏覽授權目錄，搜索文件名或路徑，並複製相對路徑。
3. 讓 agent 調用工具操作文件，例如：

browser_fs_list { path: "docs", recursive: true }

browser_fs_read { path: "docs/hello.txt" }

browser_fs_write { path: "docs/hello.txt", content: "hello" }

4. 在目錄樹中點文件名，打開預覽窗，查看圖片或文本內容。完整模式下可編輯文本並保存。
5. 如果通過局域網或手機經 http 訪問，插件會自動進入兼容模式，可使用“選擇目錄”或“選多個文件”完成只讀選擇。

若需要完整模式，可以通過以下方式之一獲得安全上下文：

• 將訪問轉發到 localhost；
• 在瀏覽器中把目標 origin 加入不安全 origin 白名單；
• 部署 HTTPS。

適用場景與注意¶

這個插件適合下面這類場景：

• dsh 部署在遠程環境，agent 需要操作瀏覽器所在機器的本地文件；
• 用戶希望授權一個本地目錄，而不是把整個宿主文件暴露給 agent；
• 需要在瀏覽器端看到連接狀態、授權狀態、目錄樹和文件預覽；
• 多設備各自授權各自本機目錄，由 host 側路由工具調用。

使用前需要注意：

• File System Access API 要求 HTTPS 或 localhost 安全上下文；純 HTTP 遠程訪問頁面時，授權按鈕會報明確錯誤。
• 瀏覽器標籤必須在線且已授權目錄，否則工具調用會立即返回明確錯誤。
• agent 工具僅支持 UTF-8 文本讀寫；二進制寫入不在範圍內。
• browser_fs_read 默認上限爲 256 KiB，截斷會標註。
• 文本預覽只取前 64KB；圖片超過 8MB 不拉取。
• 兼容模式只讀，無句柄持久化，刷新後需要重新選擇。
• 插件以當前 dsh 進程權限運行。安裝前應檢查源碼與許可證。

結尾¶

dsh-browser-fs 的價值在於把瀏覽器所在機器的本地文件接入 dsh agent 的工具鏈：用戶通過瀏覽器授權目錄，agent 通過明確工具完成目錄列表、文本讀取和文本寫入，瀏覽器端保留狀態卡片、目錄瀏覽與預覽能力。

倉庫地址：

https://github.com/whitefirer/dsh-browser-fs

目錄頁線索：

https://www.skillhub.cn/plugins/whitefirer/dsh-browser-fs