前言¶
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
