前言¶
DeepSeek Harness（DSH）的插件體系允許擴展 Web GUI 的功能。目前，系統對圖片的上傳已有原生支持，但對於任意文件（如 PDF、代碼文件、二進制數據等），需要手動提供下載鏈接或通過模型工具讀取。dsh-upload-file 插件通過在瀏覽器端注入上傳控件，並在宿主端提供持久化存儲和讀取工具，解決了這一問題。
是什麼¶
這是一個 DSH 客戶端插件，由 OctKwong30 維護。它爲 Web GUI 的 composer 輸入框增加了文件上傳能力。用戶可以通過點擊附件按鈕或拖拽本地文件將文件上傳至宿主進程，並在會話中通過卡片或工具引用這些文件。
安裝¶
安裝過程通過 dsh plugin 命令完成。執行以下命令即可從 GitHub 安裝：
dsh plugin --profile web add github:OctKwong30/dsh-upload-file
安裝完成後，需重啓 Web GUI (dsh web 或對應的啓動方式) 以加載插件。
核心功能¶
該插件主要包含以下能力：
- UI 入口：在 composer 輸入框工具行新增附件按鈕（SVG 回形針圖標），支持多選文件；支持直接將 OS 文件拖拽至 composer 區域上傳。
- 待發送狀態：上傳的文件以膠囊 chip 形式顯示在輸入框上方（待發送文件條），包含文件名、大小及移除按鈕。
- 消息集成：發送鉤子會將文件鏈接併入消息文本，格式爲
📎 [名稱（大小）](http://…/dsh-upload/raw/<id>)。 - 會話渲染：用戶消息中的文件鏈接會渲染成文件卡片（圖標 + 名稱 + 大小 + 打開鏈接）。若渲染崩潰，會自動回退到官方渲染器。
- 模型工具：宿主端提供
read_uploaded_file工具，模型可據此讀取文件內容（文本或二進制元數據）。 - 持久化與下載：文件以 SHA256 內容尋址方式存儲在
~/.dsh/uploads/，並提供GET /dsh-upload/raw/<id>接口進行下載或預覽。
使用方式¶
1. 按鈕上傳¶
打開任意會話，點擊輸入框工具行的回形針按鈕，選擇本地文件。文件上傳後會顯示在“待發送文件條”中，發送後消息文本會包含文件鏈接。
2. 拖拽上傳¶
從文件管理器中拖拽一個或多個文件到 Web GUI 的 composer 區域。鬆開鼠標後，非圖片文件會自動上傳並進入待發送文件條；圖片文件則由 shell 自帶管線處理，不產生衝突。
3. 模型調用¶
模型收到包含文件鏈接的消息後，可調用 read_uploaded_file 工具。該工具支持接收裸 id、JSON 註釋、markdown 鏈接或原始 URL 路徑作爲參數。
配置與安全¶
在 Settings → 插件配置 → dsh-upload-file 中，可以調整以下參數：
maxFileBytes：單文件字節上限（默認 20 MiB）。maxTextReadBytes：read_uploaded_file工具讀取文本內容的上限（默認 256 KiB）。uploadsDir：上傳根目錄，默認爲~/.dsh/uploads。
安全方面，插件對文件 ID 進行了嚴格的 SHA256 校驗，並對文件名進行了清洗，防止路徑遍歷攻擊。
注意事項¶
- 日誌處理：文件字節不會進入對話日誌，僅引用文本，與官方 describe-image 插件的邏輯一致。
- UI 漂移風險：會話內的文件卡片依賴手寫復刻的官方氣泡樣式。隨着 shell 版本升級，官方 CSS 類名可能發生變化，導致卡片樣式漂移。插件內置了自動回退機制，但建議關注更新。
- 主題適配：拖放時的提示條使用內聯樣式，未跟隨 GUI 的皮膚主題。
- 存儲清理：上傳的文件不會自動定期清理，需手動處理
~/.dsh/uploads/目錄。
生態背景¶
DSH 插件通過 dsh.bundle.patch 機制組合宿主與客戶端代碼。該插件爲純 JavaScript 實現（ESM），無需構建即可運行。其架構參考了官方 describe-image 插件的 attach 路由與 sendSession 發送鉤子模式。
- 目錄頁：dsh-upload-file
- GitHub 倉庫：OctKwong30/dsh-upload-file
