seeingrain/dsh-upload-file

dsh-upload-file

🇬🇧 English: README.en.md

这个插件允许你将任意文件上传给 DSH，上传后的文件是工作区+会话隔离的。

尤其适合：DSH 运行在单独服务器上的用户——聊天里直接上传文件到服务器，后续直接 @ 引用。

功能

• 输入框工具行（加号旁）多了个 📎 按钮，角标显示本会话文件数，点开就是本会话的文件库
• 上传：一次可以选多个文件，上传中有进度条
• 列表：一个文件一行——缩略图（图片 / 视频 / PDF）或类型图标 + 名字 + 大小，最新上传的在最上面
• @ 文件：在输入框里提及这个文件，模型就能直接用它，不用你报路径
• 右键一个文件（手机上长按）做 6 件事：
  • @ 提及文件
  • 用系统默认程序打开（装了 Better Sidebar 就在侧栏打开）
  • 复制文件名 / 复制完整路径
  • 重新下载一份到本地
  • 删除文件（确认后真删，没有回收站）
• 隔离：每个会话各存各的，互不干扰；同会话重传同名文件自动加数字后缀，不会覆盖

存储（文件系统即注册表，无 JSON 索引）

• 每个会话一个子目录：<会话工作区>/.uploaded_files/<sessionId>/（隐藏目录）
• 文件名就是唯一身份（无 displayName 间接层）；同会话重传同名文件自动加 _1/_2 数字后缀，@UPLOAD: 引用名 = 目录内实际文件名
• 会话间完全隔离：同名文件在不同会话目录互不冲突
• 列表 = readdir + stat（按 mtime 降序，最新上传在最顶上）
• system prompt 按会话注入指向本会话目录的约定文本（目录为空时不注入）

缩略图（服务端抽帧，图片 / 视频 / PDF）

• 图片（png/jpg/gif/webp/bmp/ico）取原图、视频（mp4/webm/mov/mkv/avi）取 5% 处帧（避开片头黑场，上限 60s）、PDF 取首页，统一缩放到最长边 160px 的 JPEG，质量阶梯递减压到 ≤10KB
• 存在会话目录的隐藏子目录 .thumbs/<原文件名>.jpg；列表接口天然跳过点开头目录，不污染文件库
• 原文件名在会话内唯一且永不被覆盖 → 缩略图生成一次即终态，响应带 immutable 长期缓存
• 懒生成 + 并发去重：首次请求缩略图时按需生成（上传 commit 时也会尽力预生成，失败无碍，取图时兜底）；同一文件并发请求只生成一次
• 降级友好：依赖系统 ffmpeg（图片/视频）与 pdftoppm（PDF，poppler）；缺失或失败时该文件回落为原图（图片）或类型徽章（视频/PDF），不影响上传与列表
• 办公文档（docx/xlsx/pptx）在生成器注册表中预留接口（当前不生成，回类型徽章），后续接 LibreOffice 无头转 PDF 链路即可启用；SVG 为矢量、体积天然小，浏览器原生渲染，不生成

安全

• 上传全程 SHA-256 校验（客户端摘要 → 提交时服务端比对）
• 所有文件路径操作做目录穿越防护（normalize(join()) 必须仍在本会话目录内）
• sessionId 严格校验（UUID 格式），工作区从会话自身 header.cwd 解析，不信任客户端传入的路径

HTTP 接口（前缀 /dsh-upload-file/v1）

• POST /uploads/prepare {sessionId, name, size} → {uploadId, putUrl, commitUrl, deleteUrl}
• PUT /uploads/<id> 流式上传（application/octet-stream，inline sha256）
• POST /uploads/<id>/commit {expectedSha256} → {name, displayName, absolutePath, size, createdAt}
• DELETE /uploads/<id> 取消（已 commit 的 id 返回 404，客户端吞掉）
• GET /sessions/<sessionId>/attachments 目录列表
• GET /attachments/content?sessionId&name 下载 / 打开（防路径穿越）
• GET /attachments/thumbnail?sessionId&name 服务端缩略图（懒生成，image/jpeg + immutable 缓存；不支持的类型 404，客户端回落）
• DELETE /sessions/<sessionId>/attachments?name= 删除已提交文件（连带删除缩略图）

构建

pnpm install
pnpm run build

安装

dsh plugin --profile web add github:seeingrain/dsh-upload-file
# host 半边需要重启 web；client 半边下次刷新页面即加载

本地开发链接方式：在 profiles/web/package.json 的 dependencies 里加 "dsh-upload-file": "link:<本仓库路径>"，并在 bundles 列表追加 dsh-upload-file，然后 pnpm install。

License

MIT — 见 LICENSE。