前言¶

做 DSH 插件開發或智能體調試時，經常需要在瀏覽器界面裏確認宿主機上的目錄結構、配置文件內容或某張圖片。此前這類操作要麼跳回終端敲命令，要麼讓插件自己實現一份文件樹組件。下面介紹的插件直接在 DSH 左側邊欄加了一個文件管理面板，把宿主機的文件瀏覽、預覽、下載和上傳收進界面裏。

• 插件名稱：ccfeeling/dsh-host-file-explorer（npm 包名 @local/dsh-host-file-explorer，版本 1.2.0）
• 維護者：ccfeeling
• 許可證：MIT
• 分類：客戶端插件
• 來源：社區插件目錄（非 DeepSeek / 幻方官方應用商店），GitHub 倉庫爲 https://github.com/ccfeeling/dsh-host-file-explorer

定位¶

這是一個標準的 DSH bundle，由 Host 半和 Client 半組成。Host 半在 ctx.hostFiles 上掛了一個服務，基於 node:fs/promises 提供七個動詞；Client 半在側邊欄註冊 host-files 面板，提供目錄列表、文本與圖片預覽、文件下載、文件上傳和新建文件夾，並支持十二種界面語言。

所有讀取都經過 Host/Client Remote 通道——也就是智能體自身文件系統工具所使用的同一條邊界——而不是繞過去直接訪問文件系統。

核心功能¶

功能清單如下，全部來自 README：

• 目錄列表：目錄在前、文件在後，每項帶類型、大小、修改時間，隱藏項以變暗樣式展示。
• 文本預覽：讀取文本文件的前 256 KiB 並渲染；二進制文件會自行報告而不打印亂碼。
• 圖片預覽：PNG、JPEG、GIF、WebP、AVIF、SVG 以內聯方式顯示，而不是按文本讀取。
• 下載：通過 Harness 的認證文件路由交給瀏覽器，保留文件原名。
• 上傳：把瀏覽器中的文件作爲一次 Remote 調用發送到當前打開的目錄，字節隨命令攜帶，不經過瀏覽器文件路由。
• 新建文件夾：在當前目錄下創建單段子目錄。
• 路徑導航：可跳轉到絕對路徑、返回上級，還有 HOME、tmp、cwd、文件系統根的快捷鍵。

安裝與啓用¶

有三種安裝方式，按使用場景選擇。

第一種是插件管理器安裝（README 推薦）。先克隆倉庫，再從本地路徑安裝：

# clone
git clone https://github.com/ccfeeling/dsh-host-file-explorer.git

# 安裝到某個 DSH profile，profile 名稱與路徑按自己環境替換
dsh plugin --profile web add /path/to/dsh-host-file-explorer

對應的 tool call 是 plugin_manager { action: 'install_bundle', target: '<local path>' }。

第二種是從插件市場安裝。該插件收錄在 awesome-dsh-plugin 列表中，因此可以直接從 GitHub 安裝：

dsh plugin --profile web add github:ccfeeling/dsh-host-file-explorer

第三種是作爲 profile 依賴聲明。編輯 ~/.dsh/profiles/<profile>/package.json：

{
  "dependencies": {
    "@local/dsh-host-file-explorer": "link:/abs/path/to/dsh-host-file-explorer"
  }
}

安裝完成後，側邊欄會在 Plugins 和 Schedules 之後出現一個文件夾圖標，點擊即打開面板。

一個與 profile 依賴相關的坑：如果 profile 裏有會隨包發佈 agent skills 的依賴（例如 dsh-answer-me-with-html），pnpm 10.11+ 和 12.x 在 skills 目錄未聲明時會拒絕安裝並拋出 ERR_PNPM_NO_AGENT_SKILLS_DIR。在該 profile 的 pnpm-workspace.yaml 里加一段即可：

skills:
  dirs: []

底層架構¶

插件的代碼結構如下：

index.js   (Host)    ctx.hostFiles  ——  七個動詞，基於 node:fs/promises
client.js  (Client)  側邊欄入口 + 主面板 + Remote 命名空間掛載

Host 半用原型標記 @deepseek-ai/dsh-typert-protocol/remote-methods 聲明 Remote 傳輸，讓網關在 SRC 模式下能發現這些方法：

這裏有個簽名約束：signal 必須是最後一個參數。網關用 Function.prototype.toString() 解析方法簽名來推導線上參數，簽名寫錯會導致調用失敗。

關於文件如何到達瀏覽器：頁面本身不走 Remote 通道傳文件字節，而是向 Host 詢問文件在 Harness 認證文件路由上的地址（與文檔預覽中 Markdown 圖片所用的路線相同），瀏覽器複用頁面已持有的會話去取。下載保留原名，預覽拿到原始 Content-Type，所以 PNG 就按 PNG 渲染。單次響應受 Harness 附件字節上限約束（默認 20 MiB）；面板會先從 Host 讀取這個上限，遇到超限的下載直接拒絕並說明原因，而不是啓動註定失敗的傳輸。

Client 半手寫了一個 Typert Remote 貢獻，用 ctx.remote.$mount(...) 掛載，隨後註冊兩個槽位：

• sidebar.panellist：id host-files，order 30，帶獨立的文件夾圖標；
• main：key host-files，即側邊欄按鈕打開的面板。

兩個開發陷阱¶

README 特別強調了兩點，擴展或複製該插件時需要留意。

第一，命名空間不能聲明爲插件自己的 inject。掛載出來的 remote.hostFiles 是一個獨立的服務，且只有在本插件掛載之後才存在；若有 fiber 去等它，會永遠等不到，插件也就無法啓動。要用 Cordis mixin 的入口直接從共享 store 讀取：

const namespace = ctx.get('remote.hostFiles');

官方插件能寫 inject: ['remote.agentPresets']，是因爲有別的包掛載了那些命名空間，消費者可以直接聲明依賴；本插件不能這麼寫，正因如此。

第二，Client 半不依賴任何 Harness client 包。它只用 react 和 zod，樣式用 --dsw-alias-* 主題變量實現，沒有從 @deepseek-ai/dsh-client-ui-primitives 及其同類包導入任何東西。

權限與邊界¶

使用前需要明確這些限制：

• 插件以 Harness 進程自身的權限讀取宿主機文件系統，賬戶能讀到什麼，它就能讀到什麼。這是宿主機文件瀏覽器的固有屬性，因此只在你信任的機器和賬戶上啓用。
• 能力範圍是隻讀，加上新建文件夾和上傳文件。它不能修改、刪除或重命名已有文件，上傳也從不覆蓋同名文件。
• 單次列表最多返回 2000 項，單次預覽最多讀 256 KiB。
• 單次下載不超過 Harness 附件字節上限（默認 20 MiB），面板會在超限下載開始前說明原因。

安裝第三方插件前，建議先讀一遍源碼和許可證（本插件爲 MIT），確認下載與上傳的目錄範圍符合預期。

小結¶

這個插件的價值在於把宿主機文件系統的操作收斂進 DSH 界面，同時複用智能體已有的 Remote 通道，不引入額外的越權路徑。對於需要在 Web 端覈對配置文件、查看圖片或收發文件的 DSH 用戶和插件開發者，它是一個可以直接安裝的客戶端工具。

• 目錄頁：https://www.skillhub.cn/plugins/ccfeeling/dsh-host-file-explorer
• GitHub：https://github.com/ccfeeling/dsh-host-file-explorer

開發階段可以使用 README 提供的命令做基本檢查：

node --check index.js
node --check client.js
npm pack --dry-run      # 查看實際發佈的文件列表