前言¶
DSH 的側邊欄默認面向會話。當你同時開着多個工作區、又想在不改代碼的前提下翻看項目裏的 Markdown 文檔和圖片時，反覆開終端 ls、cat、less 並不順手。@vfvrpq/dsh-file-explorer 就是用來補這個缺口：它在左側欄加一個圖標入口，點進去是文件樹加一個面板內的預覽區，支持文本、Markdown 和圖片。下面介紹它的能力、安裝和配置。
這是什麼¶
- 插件名：
@vfvrpq/dsh-file-explorer - 維護者：
439436269-ctrl - 倉庫：https://github.com/439436269-ctrl/dsh-file-explorer
- 分類：客戶端（宿主半隨 Host 啓動加載，客戶端半由頁面加載）
- 許可：MIT
- 定位：給 DeepSeek Harness 加一個 VSCode 風格的「文件夾 + 文件預覽器」，左側欄多一個圖標入口，點開是主區域的文件樹、打開的 tab 與文本 / Markdown / 圖片預覽。
需要說明的是，npm 上還有一個不帶 scope 的 dsh-file-explorer，是另一個作者的同名插件。本包使用 @vfvrpq/ scope 區分，兩者不衝突、可共存。
核心功能¶
安裝後主要得到下面幾樣東西。
左側欄入口註冊在 sidebar.panellist 槽位，id 與主面板 key 同爲 file-explorer，點圖標即切換到面板。
文件樹支持懶加載（展開才列目錄）、文件夾優先排序、按後綴着色的類型徽標、隱藏文件開關，目錄樹寬度可拖動。
單擊文件就在面板內預覽：左邊是樹，右邊是一張獨立的預覽卡片，帶 tab、麪包屑、行號或渲染後的 Markdown，狀態欄顯示字節數、行數、是否截斷，不會跳走。展開過的文件夾會按根記住，刷新後樹還在原處。
除了面板內預覽，還有兩個外發動作：
- 麪包屑旁的「在右側打開」把當前文件送進會話的右側文檔預覽（內置渲染器支持代碼 / PDF / Office 等）。因爲右側欄屬於會話，這個動作會讓會話回來、面板讓位。想每次都這樣，把
openInRightPanel設爲true。 - 「用默認程序打開」按鈕把當前文件交給系統默認程序（Windows
start/ macOSopen/ Linuxxdg-open），POST 到認證路由?op=open。
預覽能力分幾類：
- 文本：等寬字體、行號、自動換行開關，單文件默認最多 1 MiB、最多渲染 4000 行。
- Markdown：標題 / 列表 / 引用 / 代碼塊 / 鏈接 / 圖片，相對圖片走原始字節路由，可一鍵切回源碼。
- 圖片：png / jpg / gif / webp / avif / bmp / ico / svg。
- 其它二進制：只顯示類型與大小，不加載內容。
搜索按文件名在當前根目錄內遞歸，受目錄數、命中數、時間三重預算約束。
安裝與啓用¶
插件是標準 bundle，包內帶 dsh.bundle.patch，適配 DSH 0.2 預覽版。裝進某個 profile 時會同時寫入 dependencies 與 dsh.profile.bundles：
dsh plugin --profile desktop add @vfvrpq/dsh-file-explorer@0.1.0
或者手寫進 profile 的 package.json：
{
"dependencies": { "@vfvrpq/dsh-file-explorer": "0.1.0" },
"dsh": { "profile": { "bundles": [ ..., "@vfvrpq/dsh-file-explorer" ] } }
}
也可以只在 profile 的 cordis.patch.yml 裏掛一行。兩種方式不要同時用，insert 不按 id 去重，會掛載兩次：
- insert:
- id: file-explorer
name: "@vfvrpq/dsh-file-explorer"
config:
enabled: true
裝好後重啓一次 DSH（或讓 Loader 重載），側欄就會出現「文件瀏覽」圖標。
這裏有一個容易踩的坑：不要用 link: / 目錄 junction 安裝。@deepseek-ai/schemastery 由宿主在 profile 的 node_modules 裏解析，軟鏈會被 Node 還原成源碼真實路徑，從那裏向上找不到宿主包，插件會以 failed to import 靜默不激活。要用 npm 安裝或 file: tar 包（真實拷貝）。
配置¶
配置層在 cordis.patch.yml 的 config 下，字段與默認值如下：
| 字段 | 默認值 | 說明 |
|---|---|---|
enabled |
true |
關掉後路由不再響應，但側欄入口仍在 |
routePath |
/api/file-explorer |
認證路由，必須以 /api/ 開頭才能喫到連接層的鑑權圍欄 |
extraRoots |
[] |
額外可瀏覽的絕對目錄（除了工作區、默認目錄、進程目錄、主目錄） |
includeHome |
true |
是否把用戶主目錄作爲根 |
ignored |
[] |
列表與搜索裏隱藏的條目名，例如 node_modules |
maxTextBytes |
1048576 |
文本預覽上限（超出截斷並標註） |
maxRawBytes |
33554432 |
原始字節路由上限（圖片預覽） |
defaultShowHidden |
false |
文件樹初始是否顯示點文件 |
openInRightPanel |
false |
設爲 true 時點文件改爲送進右側欄文檔預覽；默認留在面板內預覽 |
allowOpenWithDefaultApp |
true |
是否顯示「用默認程序打開」按鈕；關掉後 ?op=open 直接 403 |
blockedOpenExtensions |
exe,com,bat,cmd,msi,scr,pif,vbs,vbe,ps1,reg,sh,command,app,desktop |
啓動器拒絕交給系統處理的後綴；設空數組表示不攔 |
權限模型¶
這個插件只讀，並且不接受任意路徑：
- 可瀏覽的根 = 已註冊工作區 + 默認工作目錄 + 進程目錄 + 主目錄 +
extraRoots，去重後只保留真實存在的目錄。 - 每次請求的
path都用ctx.fs.resolve解析成穩定 target，再用ctx.fs.contains(root, target)證明它落在某個根內，否則 403。 - 路由掛在
/api/下，繼承連接層的 Host/Origin 校驗與會話 cookie 鑑權。 - 原始字節路由只對圖片類型內聯（帶
nosniff+ CSP sandbox），其它一律按附件下發。 ?op=open只接受POST（GET一律 405），只接受普通文件且拒絕可執行後綴，啓動命令由平臺決定，不拼接 shell 字符串。
適用場景與注意¶
適合想在 DSH 界面裏直接瀏覽項目結構、閱讀文檔和查看圖片的開發者，尤其是同時維護多個工作區、頻繁翻看 Markdown 與截圖的場景。
注意幾點：
- 插件在當前 dsh 進程權限下運行。安裝前應自行檢查源碼與許可證（MIT），不要把它當成免審的信任邊界。
- 只讀：不提供保存、重命名、刪除，目的之一是避免和會話的寫權限、審批策略打架。
- 無語法高亮，只做行號與類型着色。
- 單文件渲染上限 4000 行，文本讀取上限 1 MiB，都可配。
- 搜索是文件名子串匹配，不是內容檢索；單次最多開 400 個目錄、4 秒預算。
- 二進制文件不給下載按鈕，原始路由只服務圖片內聯。
結尾¶
它把 DSH 默認會話側邊欄之外補上了一塊獨立的、只讀的文件瀏覽與預覽區域，安裝方式是標準的 profile bundle，配置項圍繞根目錄、大小上限與打開行爲。
- 目錄頁：https://www.skillhub.cn/plugins/439436269-ctrl/dsh-file-explorer
- GitHub：https://github.com/439436269-ctrl/dsh-file-explorer
