DSH 工作區通常需要通過特定的 API 調用來管理文件。dock-files 插件面向 DSH 工作區提供文件瀏覽功能，由 AKS1st 維護。它解決了在沒有原生文件管理器的情況下，開發者需要通過命令行或 API 逐個操作文件的繁瑣問題。
安裝與依賴¶
安裝 dock-files 需要依賴 dock-base 插件。
dsh plugin --profile web add dock-base
dsh plugin --profile web add dock-files
環境要求：
* DSH Web 環境：>=0.1.3-alpha.2
* dock-base：>=0.2.0
* 框架：cordis ^4.0.0-rc.7
* 渲染：react ^18.2.0（可選，用於渲染 UI）
核心功能¶
目錄樹瀏覽¶
插件提供 VSCode 風格的文件樹界面。目錄採用惰性遞歸展開，排序邏輯爲目錄優先、大小寫不敏感（與 VSCode 資源管理器一致）。界面包含類型彩色圖標、樹形導引線、工具欄（刷新/摺疊全部）以及懸停操作按鈕。
會話隔離與安全¶
所有操作以會話工作目錄爲邊界。路徑經過 realpath 規範化後必須位於工作區內，越界路徑會返回 403 錯誤。主機路由只接受來自受信任來源（迴環地址 / trustedHosts + 同源）的請求。
文件打開與分發¶
點擊文件時，插件通過 ctx.files.open 分發給已註冊的文件查看器（如 dock-editor），以浮窗形式打開。
打開來源模式¶
在設置中配置 dock-files.open-source（默認 dock）：
* dock 模式：識別 dsh-resource://file/session/... 和 file/absolute/... 路徑，按 b67 規則解碼，將文件交給 Workbench。
* harness 模式：不包裝 sidebarRight.openResource()，完全保留原生行爲。
文件管理¶
右鍵菜單提供完整的文件管理操作：
1. 新建：新建文件/文件夾（自動去重，創建後進入行內重命名）。
2. 重命名：行內編輯，Enter 確認 / Esc 取消。
3. 複製/剪切/粘貼：複製可重複粘貼，剪切項變灰，粘貼後清除剪貼板。
4. 粘貼圖片：檢測系統剪貼板，僅在包含圖片時顯示，自動按 MIME 類型命名去重。
5. 刪除：遞歸刪除，不會覆蓋同名文件。
6. 其他：複製路徑、刷新、瀏覽器下載。
* 空白區域右鍵可對根目錄執行新建、粘貼等操作。
拖放與粘貼¶
- 系統拖入：將系統文件拖入瀏覽器即可導入到目標文件夾（按原名自動去重）。
- 樹內移動：拖動文件/文件夾到其它文件夾或空白區域（視爲根目錄）可移動文件。
- Ctrl+V：在系統複製文件後，點擊面板使其獲得焦點，按
Ctrl+V即可粘貼導入。
傳輸任務中心¶
普通文件使用分塊上傳以支持大文件。所有傳輸任務進入全局內存任務中心，支持在浮窗、狀態欄或底部查看進度。任務支持暫停、繼續和取消。注意：任務狀態不跨重啓保留。
多語言與擴展¶
界面文案跟隨 DSH 語言設置（zh/en），新建文件/文件夾的默認名也隨之切換。插件提供 ctx.files 服務，允許其他插件註冊文件查看器（registerFileViewer）和圖標（registerFileIcon）。
典型用法¶
- 掛載面板：通過
dock-base側邊欄掛載文件面板，瀏覽當前會話工作目錄。 - 打開文件：點擊文件，由已註冊的查看器打開。
- 配置打開方式：在設置中修改
dock-files.open-source。 - 自定義擴展：在其他插件中調用
ctx.files.registerFileViewer註冊擴展名匹配或默認的查看器。
注意事項¶
- Windows 限制：暫不支持在 Windows 原生資源管理器中直接粘貼文件、複製文件內容、複製下載鏈接或下載文件夾。
- 任務持久化：傳輸任務狀態不跨重啓保留，重啓後任務會消失。
- 拖放限制：拖到自身或子孫目錄會被拒絕。
- 安全：安裝前應檢查源碼與許可證。
