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