前言¶
用 dsh web 做智能體開發時，常有這樣的時刻：agent 在工作區裏寫了一批文件，你想自己翻一翻目錄、看一眼日誌或截圖，而不是讓模型逐個描述。常見做法是另起一個靜態文件服務——多一個進程、多一個端口要維護；或者退回終端敲 ls，文件一多效率就下來了。
DSH 的理念是「一切皆插件」。下面介紹的 @open-agfs/dsh-agfs 是這個思路下的一個具體實現：它把文件瀏覽器 Web 應用直接掛在 dsh web 的宿主 webserver 上，不開獨立端口，也不起子進程。
這是什麼¶
@open-agfs/dsh-agfs 由 openAGFS 維護，MIT 許可證，當前版本 0.1.9。它由三部分組成：
- 由宿主 webserver 提供的 React 前端與 REST API；
- 一個
/dsh-agfs對話框命令； browse_files與read_file兩個模型工具。
分工很清楚：人在瀏覽器裏瀏覽、搜索、預覽和整理文件；模型通過工具列出、搜索和讀取瀏覽根下的文本文件。雙方面對同一個瀏覽根，不需要爲「看文件」單獨起服務。
核心功能¶
文件瀏覽¶
- 列表與搜索、文本預覽（markdown、代碼、日誌）、圖片預覽；
- 文件夾的創建、重命名、複製、刪除；
- 麪包屑導航，逐級點回根目錄；
- 視圖切換（列表/卡片網格）與三種顯示尺寸（窗口面板、整個視圖、全屏）；
- 側邊欄提供項目目錄、快速訪問（Desktop/Downloads/Documents 等）、自定義根目錄與驅動器；
- 工具欄搜索支持遞歸模式，上限 200 條命中。
前端隨包離線分發：React/ReactDOM 打包在包內，啓動無需 CDN，也不依賴 Babel（圖標仍走 cdnjs，見後文已知限制）。
會話聯動¶
- 本地打開（僅本地模式）：右下角浮動按鈕可在系統文件管理器中打開當前目錄；
- 一鍵 AI 分析（僅本地模式）：右鍵文件或文件夾輸入需求，dsh 會創建工作區並喚醒新會話進行分析。
模型工具¶
插件註冊兩個模型工具：
browse_files（參數path、keyword、recursive）：列出目錄，或按關鍵字搜索條目名，可選遞歸；read_file（參數path）：讀取瀏覽器根下的文本文件內容。
有了這兩個工具，模型可以直接查看目錄結構和文件內容，而不只是文件名。
路徑安全與響應頭¶
瀏覽被限制在可瀏覽根內；strictRoot 開啓後執行實路徑檢查，symlink/junction 逃逸會被攔截並返回 400 envelope；另有 readOnly 只讀模式與 remoteMode。響應附帶安全頭 X-Content-Type-Options: nosniff、X-Frame-Options: DENY、Referrer-Policy: no-referrer。
API 端點位於 ${basePath}/api/file_browser/ 下，路徑同樣限制在可瀏覽根內；search 支持 recursive=1，有 200 條命中上限和目錄深度上限 5。
安裝與啓用¶
插件通過 dsh.bundle 一行安裝，以 profile layer 激活。Node 版本要求 ^22.19.0 || >=24.0.0。
方式一：對話框安裝¶
在 DeepSeek Harness 對話框裏直接讓 agent 安裝，例如：
Install the file-browser plugin
dsh-agfs
agent 會調用 shell 工具執行：
dsh plugin --profile web add @open-agfs/dsh-agfs
這條鏈路要求 agent 的 shell 工具（bash/pwsh）可用。web profile 默認禁用 shell 工具，需要在 Settings → tools/permissions 裏啓用，或在 agent 請求批准時放行；不方便開 shell 工具就用方式二。
方式二：CLI 一行安裝¶
dsh plugin --profile web add @open-agfs/dsh-agfs
升級到最新版：
dsh plugin --profile web add @open-agfs/dsh-agfs@latest
無論哪種方式，安裝後都需要重啓 dsh web 才能生效。
源碼 overlay（開發調試）¶
從倉庫 checkout 出發，可以通過 --patch 掛載源碼：
- insert:
- id: dsh-agfs
name: 'file:///absolute/path/to/dsh-agfs/src/index.ts'
然後運行 dsh web --patch ./overlay.yml。
典型用法¶
經過上面的步驟，在對話框運行：
/dsh-agfs
系統默認瀏覽器會打開文件瀏覽器並報告 URL；當前會話帶工作區目錄（session cwd）時，瀏覽器直接定位到該工作區。
若配置了 openOnCommand: false，這一步只報告 URL，不自動打開瀏覽器。
配置¶
配置存於 profile 的 user patch 層（$DSH_HOME/profiles/<name>/cordis.patch.yml）：
- id: dsh-agfs
config:
fileRoot: 'D:/projects/my-project'
readOnly: true
常用配置項：
fileRoot：文件瀏覽器的根目錄；readOnly：只讀模式；strictRoot：實路徑檢查，攔截 symlink/junction 逃逸；remoteMode：遠程模式；openOnCommand：/dsh-agfs是否自動打開系統默認瀏覽器。
適用場景與注意事項¶
適合的場景：在 dsh web 裏做日常開發、需要人工覈對 agent 產出的文件；希望模型具備列目錄、搜條目名、讀文本文件的能力，而不想爲此單獨維護一個文件服務。
使用前注意：
- 插件以當前 dsh 進程的權限運行。安裝前建議閱讀源碼和許可證（MIT），確認符合自己的安全要求再裝。
- Font Awesome 圖標仍從 cdnjs 加載。無網絡時應用本身可用（React/ReactDOM 已隨包分發），只是沒有圖標。
- 搜索只匹配條目名，未實現遞歸內容搜索；遞歸模式有 200 條命中上限、目錄深度上限 5。
- 縮略圖直接傳輸原圖，不做縮放。
openOnCommand觸發的瀏覽器在運行 dsh 的主機上打開，對遠程客戶端來說這個行爲可能出乎意料。
結尾¶
簡單回顧：@open-agfs/dsh-agfs 把文件瀏覽器掛進 dsh web 的宿主進程，不開端口、不起子進程；/dsh-agfs 直達當前會話的工作區，browse_files 與 read_file 讓模型能直接查看瀏覽根下的文件。如果你在用 DSH 做開發，值得一試。
- GitHub 倉庫：https://github.com/openAGFS/dsh-agfs
- 社區目錄收錄頁：https://www.skillhub.cn/plugins/openAGFS/dsh-agfs（社區獨立維護的目錄站點，與 DeepSeek / 幻方無官方從屬關係）
