前言¶
DSH Web GUI 原本只支持圖片附件。當需要在網頁端把 PDF、代碼、壓縮包等非圖片文件交給 agent 時，缺少一個穩定入口。dsh-file-upload 解決的是這個問題：把頁面拖入的文件落盤或引用到本機，使 agent 可以讀取，同時讓輸入框保持簡潔。
插件定位¶
dsh-file-upload 是一個 Web 客戶端插件。它把 DSH Web GUI 僅支持圖片的附件通道擴展爲任意文件上傳。
基本事實如下：
- 許可證：MIT
- 運行要求：Node >=20
- 插件形式：持久化 profile 插件，
dsh.bundle+dsh.client雙聲明，DSH 重啓後自動生效 - Web 聲明：
dsh.client，platform web - 依賴官方服務：
webServer、slots、inputTriggers、conversation/sessions - 倉庫地址：
https://github.com/GLFzr/dsh-file-upload
核心能力¶
任意文件拖入¶
插件支持頁面任意位置拖入任意文件，多文件和圖片都可以。文件進入後，上傳或引用到本機中轉目錄，輸入框中出現藍色文件 chip，agent 可直接讀取該文件。
本機文件直引與上傳中轉¶
在 Chromium 系瀏覽器（Edge/Chrome）中，拖入本機文件時，插件可直接引用源文件路徑，實現零上傳、零複製。瀏覽器拿不到源文件路徑時，則走上傳中轉。
文件 chip¶
文件以整體藍色 chip 插入輸入框，只顯示文件名和格式。Backspace / Delete 一次刪除整個引用。
chip 寬度按文件名自適應，插入前會用 composer 真實字體實測文件名寬度。
用戶界面隱藏 .b64、_N 重名序號和中轉目錄路徑；提交給 agent 的是完整真實路徑。
兩級去重¶
去重分兩級。同名、同大小且 manifest 登記的源修改時間一致時，走快路徑，秒回且零上傳；否則完整上傳，並由 sha256 逐字節比對裁決。
上傳目錄清理¶
側邊欄底部、設置圖標上方的垃圾桶圖標可打開上傳目錄清理浮層。清理浮層提供文件清單、一鍵清理冗餘 _N 副本、按大小清理、清空全部等能力，操作前有確認。
完整性校驗與加載提示¶
上傳校驗包括分塊精確長度、分塊齊全、解碼後字節數與聲明一致。
插入點待機圓環僅在真正等待時顯示，chip 插入瞬間消失。
安裝與驗證¶
使用本地倉庫路徑安裝：
dsh plugin --profile web add ./plugins/file-upload
安裝後，運行下面命令驗證插件層是否出現：
dsh web --dump-config
輸出中應出現 # == dsh-file-upload 層。
如果之前使用的是舊名 dsh-drop-file-to-path，插件 id 與路由已更名爲 file-upload。按新命令重裝後，舊版本無需卸載。
典型用法¶
1、拖入文件後，文件上傳或引用到本機中轉目錄，輸入框出現藍色文件 chip，agent 可直接讀取該文件。
2、側邊欄底部、設置圖標上方的垃圾桶圖標可打開上傳目錄清理浮層。
3、回退上傳的二進制文件會落盤爲 base64 文本，並追加 .b64。agent 需先 base64 解碼再使用。
4、本地語法檢查和宿主測試可以執行：
node --check lib/index.js lib/client.js
node --test tests/host.test.mjs
適用場景與注意¶
適合在 DSH Web GUI 中處理非圖片文件，或需要在網頁端把本機文件交給 agent 的場景。
需要注意：
- 瀏覽器沙盒限制：網頁 JavaScript 拿不到本地文件磁盤路徑；agent 只能讀磁盤路徑，因此需要物化到本機中轉目錄，默認
~/.dsh-dropbox。 - 大文件首次拖入必須完整上傳；重複文件命中去重時零上傳。
- 清理上傳目錄會使歷史會話引用的文件失效。操作前需確認沒有正在使用的會話。
- HTTP 路由有跨源防護：
Origin ≠ Host時返回 403；無Origin的本地調用不受影響。 - 無 composer occurrence 擴展的公開版 DSH 會降級爲固定 1em chip，提交、複製、刷新草稿仍正確。
- 插件以當前 DSH 進程的文件訪問能力運行；安裝前應檢查源碼與許可證。
參考鏈接¶
- GitHub 倉庫：
https://github.com/GLFzr/dsh-file-upload - 目錄頁線索：
https://www.skillhub.cn/plugins/GLFzr/dsh-file-upload
