前言¶
在 DeepSeek Harness（DSH）裏跑智能體會話時，工作區裏的源碼、日誌和產物往往只靠默認的 Files 預覽瀏覽，上傳、批量下載和大目錄整理並不順手。dsh-files-manager 是面向 DSH Web UI 的客戶端插件，在右側邊欄增加 File manager 標籤，用可排序的樹形表格統一管理當前會話工作區內的文件，並支持分塊上傳、流式 ZIP 下載和多選操作。下面介紹它的定位、能力、安裝方式與使用時的注意點。
這是什麼¶
dsh-files-manager 由 NoelJudeNoel 維護，倉庫爲 NoelJudeNoel/dsh-files-manager。插件在 DSH Web 右側邊欄增加文件管理頁，所有讀寫都限定在當前會話的工作區根目錄內，不擴大宿主進程的文件訪問範圍。生態上 DSH 奉行「一切皆插件」；社區目錄站點 skillhub.cn 與 DeepSeek、幻方無官方從屬關係，安裝前仍建議自行查閱源碼與 MIT 許可證。
核心功能¶
插件在資料中說明的主要能力如下。
樹形列表與排序：表格展示文件名（含擴展名）、修改時間與大小；適配 DSH 淺色/深色主題和窄側欄。可按名稱、修改時間或大小排序；每個文件夾內單獨排序，文件夾始終排在文件之上。中文文件名按拼音首字母參與名稱排序，排序偏好會被記住。
下載：單文件以原名下載且支持斷點續傳；多選或整文件夾下載時，服務端按需流式生成 ZIP，不把整個歸檔載入內存。資料稱曾在約 2 GB 規模下做過測試。
多選：複選框、Shift 範圍選擇、同級全選；選擇條顯示文件數與總大小。
上傳：通過菜單或拖拽（可拖到面板或指定文件夾）上傳文件或整個文件夾；分塊大小爲 8 MiB，帶進度、速率、取消與網絡錯誤自動重試；重名會提示；保留原始修改時間。
管理：新建文件夾、重命名、刪除，輸入時做名稱校驗。點擊文件可在 DSH 常規預覽中打開。
其他行爲：頁面可見時每 15 秒自動刷新列表，並在每次操作後刷新。符號鏈接、套接字等特殊文件不會打進歸檔，狀態欄會報告跳過數量。按大小排序文件夾時，用的是其直接子項數量，而非遞歸計算整棵子樹大小（避免大目錄下列表過慢）。
安裝與啓用¶
需要 Node.js 22.5 或更高版本。資料註明在 DSH 0.2.1-rc.2 上測試過，無額外運行時依賴。package.json 中版本爲 2.0.0，engines.dsh 要求 >=0.2.1-rc.2。
先執行官方安裝命令（須使用資料中的 owner/repo 大小寫）：
dsh plugin --profile web add github:NoelJudeNoel/dsh-files-manager
若 pnpm 報 ERR_PNPM_ADDING_TO_ROOT，加上 -w：
dsh plugin --profile web add -w github:NoelJudeNoel/dsh-files-manager
安裝後重啓 dsh web。在起始頁打開右側邊欄並選擇 File manager，或在常規 Files 標籤頁頂欄點擊 Manage 進入同一管理界面。
可選配置¶
可在 profile 的 cordis.patch.yml 中限制單文件上傳上限（默認 10 GiB）：
- id: files-manager
config:
maxUploadBytes: 10737418240 # largest single uploaded file; default 10 GiB
典型用法¶
- 安裝並重啓 Web 後，從側欄進入 File manager，瀏覽當前會話工作區樹表。
- 需要拉取多個文件或文件夾時，勾選目標項，通過下載流程獲取流式 ZIP；單個大文件可走支持
Range的直鏈下載（見下方 API）。 - 將文件或文件夾拖到面板或某個文件夾節點上完成分塊上傳；若名稱衝突，按提示處理。
- 用新建、重命名、刪除維護目錄結構；點擊文件名回到 DSH 內置預覽。
開發與本地調試時，資料給出的做法是直接指向本地路徑（示例中的路徑需換成你的檢出目錄）：
dsh plugin --profile web add -w /path/to/dsh-files-manager
安全與 HTTP 接口¶
安全相關說明（摘自 README）：
- 操作範圍限於宿主記錄的會話工作區；工作區根來自會話記錄，不由請求參數指定。
- 路徑做詞法檢查並在解析符號鏈接後再次校驗；指向工作區外的鏈接不展示詳情，下載時跳過。
- 工作區根不可刪除或重命名。
- 請求經 DSH 已認證連接，需要 owner principal；下載使用綁定會話、有效期 10 分鐘的短期 ticket。
- 上傳先寫臨時文件，完成後再重命名，避免半成品出現在列表中。
對外 HTTP 路由（均需 DSH 連接認證）：
| 路由 | 用途 |
|---|---|
POST /api/files-manager?sessionId=&op= |
list、mkdir、rename、delete、conflicts、measure、prepare、upload、upload-abort |
GET /api/files-manager/download?sessionId=&ticket= |
流式返回 prepare 簽發的文件或 ZIP；單文件支持 Range |
適用場景與注意¶
適合經常在 DSH Web 裏整理會話工作區、需要批量上傳下載或拖拽傳文件的開發者。插件以當前 dsh 進程權限訪問文件系統，安裝前應閱讀倉庫源碼與許可證，確認符合你的安全策略。
符號鏈接等特殊條目在歸檔中的限制、文件夾按大小排序的語義，以及 15 秒自動刷新，在長會話或大倉庫場景下需要心裏有數。測試套件可通過 npm test 運行（資料註明需 python3 校驗 ZIP）。
結尾¶
dsh-files-manager 把 DSH Web 會話工作區的瀏覽、排序、上傳和下載收到同一側欄界面裏，並強調工作區邊界與流式 ZIP。目錄頁：skillhub.cn 插件頁；源碼與完整說明：GitHub 倉庫。
