前言¶
DeepSeek Harness（DSH）的 Web 端自帶「文件」面板，可以列出目錄、預覽文檔，但寫方向的能力——上傳、打包下載、重命名、刪除、建文件夾——並不在默認實現裏。日常改工作區內容時，很多人仍要開 SFTP 或本機同步工具，和瀏覽器裏的會話來回切換。
下面介紹社區插件 dsh-file-manager（維護者 wchengk09，分類：客戶端）。它在同一套 Web GUI 裏補上 authenticated、限定在當前 session workspace 內的傳輸與管理界面，目標是把常見文件操作留在 DSH 會話裏完成。
這是什麼¶
dsh-file-manager 是標準 DSH profile bundle（dsh.bundle.patch + dsh.client），爲 DeepSeek Harness Web 的 Files 能力增加寫方向：上傳、下載、文件夾 ZIP、重命名、刪除、新建文件夾。官方文件面板只負責列表與預覽；本插件額外提供完整「文件管理」側欄標籤，並在內置「文件」標籤的操作行裏增加快捷入口。
插件與 DSH 同屬「一切皆插件」生態；社區目錄頁在 skillhub.cn，源碼在 GitHub。目錄信息與 README 一致時，以倉庫文檔爲準。
核心功能¶
界面層¶
| 位置 | 能力 |
|---|---|
| 右側邊欄新標籤 文件管理（可從引導頁進入） | 麪包屑導航、目錄優先排序、多選、拖放上傳（含文件夾）、單文件進度與取消、覆蓋確認、文件下載、文件夾 ZIP 下載、重命名、刪除、新建文件夾 |
| 內置 文件 標籤操作行 | 對當前展示目錄：Upload、ZIP download、Open manager |
| 文檔預覽標籤操作行 | 對當前打開文件：Download |
上傳以流式寫入磁盤（不做整文件內存緩衝）；下載支持 HTTP Range；文件夾 ZIP 在遍歷目錄樹時流式輸出。
Host API¶
路由前綴爲 /api2/dsh-file-manager/*（不走 reflection 的 /api 通道）：
| 方法 | 路徑 | 用途 |
|---|---|---|
| GET | /info?sessionId |
會話工作區根路徑 |
| GET | /list?sessionId&path |
單層目錄列表 |
| POST | /upload?sessionId&path&name&overwrite |
application/octet-stream 流式上傳；name 可含 a/b/c |
| GET | /download?sessionId&path[&inline=1] |
單文件下載，支持 Range |
| GET | /zip?sessionId&path |
目錄流式 ZIP |
| POST | /mkdir |
JSON {sessionId, path} |
| POST | /move |
JSON {sessionId, from, to, overwrite?} |
| POST | /copy |
JSON {sessionId, from, to, overwrite?} |
| POST | /delete |
JSON {sessionId, paths: []} |
成功響應形如 { "ok": true, "value": … }；失敗爲 { "ok": false, "error": { code, message, details } }，並帶對應 HTTP 狀態（例如 outside-workspace 403、exists 409、upload-too-large 413）。
安全與邊界¶
- 認證與來源：各路由先走 composition 的
connection.requestRejection()，與官方/api相同的 Host/Origin 校驗與會話 cookie；無 Connection 的 composition 直接拒絕。 - CSRF：所有 mutating 路由要求請求頭
x-dsh-fm: 1，跨站表單無法設置。 - 工作區隔離：路徑相對 session 的
cwd（回退到sandboxPolicy.workspaceRoot）解析；禁止..逃出；realpath 二次校驗，指向工作區外的 symlink 在 download、zip、delete、move 等操作中被拒絕。 - 覆蓋：upload、move 默認不覆蓋（
exists）；瀏覽器確認後可帶overwrite重試。 - 上限：單文件上傳默認 16 GiB（
maxUploadBytes）；列表最多 5000 項；ZIP 最多 60000 項 / 4 GiB（ZIP32）。
已知限制¶
- 上傳不支持斷點續傳；失敗需從頭傳。下載可通過 Range 續傳。
- Host 重載前
/copy未就緒時，粘貼會回退爲「下載再上傳」（目錄遞歸），結果相同但更慢；路由加載後會自動走服務端 copy。 - 僅 ZIP32；超限會明確報錯，不生成損壞包。
- 不支持
chmod/chown。 - 只管理當前 session 的工作區。
- 與內置文件面板同類型接管：啓用後 shadow 官方實現，不會出現兩個文件面板並排。
安裝與啓用¶
包爲標準 web profile 依賴，Node 引擎要求 >=20，許可證 MIT（見 package.json 版本 0.1.0）。
先用 pnpm 把本地包裝進 web profile：
cd ~/.dsh/profiles/web
pnpm add file:/path/to/dsh-file-manager
# then add "dsh-file-manager" to package.json -> dsh.profile.bundles
不經過 pnpm 時可用符號鏈接：
ln -s /path/to/dsh-file-manager ~/.dsh/profiles/web/node_modules/dsh-file-manager
# add "dsh-file-manager" to package.json -> dsh.profile.bundles
在 package.json 的 dsh.profile.bundles 中加入 "dsh-file-manager"。重啓 dsh web（或等待 profile 熱重載），再刷新頁面。捆綁的 cordis.patch.yml 會插入 host 行：
- insert:
- id: file-manager
name: dsh-file-manager
若要在 profile patch 裏關閉插件，可對 - id: file-manager 設置 disabled: true；瀏覽器側隨 host 行一併消失。
可選 host 配置示例：
- id: file-manager
config:
maxUploadBytes: 17179869184
maxListEntries: 5000
zipMaxEntries: 60000
zipMaxBytes: 4294967294
典型用法¶
- 完成安裝並刷新 Web 後，從引導頁或右側邊欄打開 文件管理，用麪包屑進入目標目錄。
- 拖放文件或文件夾到面板，或在內置 文件 標籤對當前目錄點 Upload；大文件可看單文件進度，必要時取消。
- 選中文件或目錄：下載單個文件、對文件夾 ZIP download，或在內置 文件 標籤對當前目錄打包下載。
- 重命名、刪除、新建文件夾在 文件管理 標籤內完成；需要覆蓋已有路徑時按界面確認後再提交。
- 預覽某個文檔時，在預覽標籤操作行使用 Download 拉取當前文件。
開發自測（來自 README）：
cd dsh-file-manager
ln -s ~/.dsh/profiles/web/node_modules node_modules # schemastery for tests
node --test test/*.test.mjs
適用場景與注意¶
適合在 DSH Web 會話裏頻繁改工作區、又不想爲每次小改動開 SFTP 的智能體開發者或運維。插件 Host 路由與當前 dsh 進程權限 一致，讀寫範圍仍被限制在該 session 的 workspace；安裝前應自行審閱 源碼與 MIT 許可證，確認符合你的安全策略。
社區目錄星標等信息以站點展示爲準（抓取時爲 0）；功能細節以 GitHub README 爲準。
結尾¶
dsh-file-manager 把上傳、下載、ZIP、重命名、刪除和建目錄收進 DSH Web，與內置只讀文件列表形成互補，減少會話內外來回切工具的成本。
