文件附件增强 wszhoho/dsh-file-attachment

dsh-file-attachment

文件附件插件，用于 DeepSeek Harness (DSH) Web GUI

拖拽 / Ctrl+V 粘贴 / 📎 按钮上传 · 内联缩略图 · @绝对路径 引用 · VLM 图片识别

DSH web GUI 的文件附件插件： 在输入框里拖入、粘贴或上传文件与图片；内联缩略图、可点击预览、@绝对路径 引用，还可选配 VLM 生成图片描述。

目录

- 快速开始
- 核心能力
- 处理流程
- 界面
- 行为一览
- 存储细节
- 安装
- 架构
- 开发说明
- English

快速开始

dsh plugin --profile web add @wszhoho/dsh-file-attachment

安装后重启 web GUI 即生效。

核心能力

| 能力 | 说明 |
| 📥 三种入口 | 拖入、Ctrl+V 粘贴、接管 dsh 原生 📎 附件按钮（加号右侧、modes 左侧，可多选）；PC 与移动端浏览器均适用 |
| 🗂️ 统一落盘管线 | 图片与文档同走一条链路，平铺保存到 <会话工作区>/.dsh-file-attachment/<文件名>；同名冲突追加 -N 绝不覆盖；同名同大小自动去重复用；单文件上限 50MB |
| 🔗 @绝对路径 引用 | 落盘后在光标处插入 chip，文本模型也能「看懂」附件 |
| 🖼️ 双区预览 | 输入框内联附件条（图片缩略图 / 文档类型图标 + 文件名，可移除并同步清除引用）；聊天区图片渲染为可点击放大的缩略图（Lightbox） |
| 🤖 VLM 识别 | 非多模态模型下自动调用 OpenAI 兼容接口生成中文图片描述回填草稿（仅注入模型上下文）；智能体可主动调用 describe_image 工具 |

处理流程

flowchart LR
A["📥 拖入 / 粘贴 / 📎 选择"] --> B{"文件校验类型 · 大小 ≤50MB"}
B -- "不合规" --> X["跳过并 toast 提示"]
B -- "通过" --> C["读全文 → base64 → Host 落盘"]
C --> D[(".dsh-file-attachment/YYYY-MM-DD/文件名同名追加 -N")]
D --> E["光标处插入 @绝对路径 chip"]
E --> F{"模型支持多模态？"}
F -- "否 · 已配 VLM" --> G["VLM 生成中文描述仅注入模型上下文"]
F -- "是 / 未配 VLM" --> H["随消息正常发送"]

界面

演示：拖入/粘贴 → 落盘并插入 @ 引用 → 输入框内联附件条待发送状态。

插件演示

VLM 图片识别

设置页（「设置 → 文件附件」）：

| 设置组 | 内容 |
| 可上传类型 | 按文档 / 代码 / 配置文件三类增删扩展名（小写不带点，图片恒可发送） |
| VLM 参数 | Base URL / API Key / 模型 / 思考模式开关（默认禁用）/ 超时时间（默认 60 秒）；未填 API Key 时静默跳过 |

可上传类型设置、多模态API设置

行为一览

| 操作 | 行为 |
| 📎 按钮多选 / 拖入 / 粘贴文档、代码、配置文件 | 读全文 → base64 → 落盘 → 光标一次性插入全部 @ 引用；成功不提示，失败简短 toast |
| 一次多个文件 | 批量处理，一次性插入全部引用；部分失败仅提示「N 个已跳过」 |
| 拖入 / 粘贴图片 | 同一管线落盘 + 插引用；附件条缩略图预览，聊天区可点击放大 |
| 当前模型不支持多模态 | 自动调 VLM 生成中文描述回填草稿；智能体可用 describe_image 工具 |
| 拖入目录 | 拒绝，toast 提示「不支持拖入目录」 |
| 粘贴纯文本 | 不改写，完全原生行为 |
| 重复拖入同名文件（同一天内） | 追加 -1、-2 序号，绝不覆盖 |
| 点附件条 × 移除 | 移除条目并清除该文件路径的全部 @ 引用 chip，其他文件不受影响 |
| 单文件 > 50MB | 跳过并提示 |

存储细节

- 命名：.dsh-file-attachment/<清洗后文件名>（如 .dsh-file-attachment/说明.docx，0.7.0 起平铺、不再按日期分子目录），同名在扩展名前追加 -N。
- 去重：上传前先查重（键 = 文件名 + 文件大小，元数据级判定），命中直接复用已有文件路径、零字节上传；.dsh-file-attachment/.index.json 为去重索引（自动维护，删除后自动重建）。历史 <日期>/ 子目录中的旧文件不受影响，引用保持有效。
- 根目录 = 当前会话工作区（回退顺序：session.header.cwd → sandboxPolicy.workspaceRoot → process.cwd()），每个项目各自维护自己的 .dsh-file-attachment/。
- 跨平台：保存路径用 path.join 自适应分隔符；文件名清洗对 Windows / POSIX 均安全；Host 半经 node:fs/promises 直接写字节，无 shell 依赖。

安装

本仓库是标准 dsh 插件包（声明了 dsh.bundle.patch），已发布 npm 包 @wszhoho/dsh-file-attachment。dsh plugin add 的参数会转发给 profile 目录的 pnpm 执行，三种来源任选其一：

从 npm 安装（普通用户推荐）
dsh plugin --profile web add @wszhoho/dsh-file-attachment

本地源码安装（开发用，边改边验；相对路径等价 pnpm link，改完 lib/.js 后重启 GUI 即生效）
cd <parent>
dsh plugin --profile web add ./dsh-file-attachment

从 GitHub 安装
dsh plugin --profile web add github:wszhoho/dsh-file-attachment

无论哪种来源，安装后都自动进入 profile 的 dsh.profile.bundles，无需手改 profile package.json；升级：dsh plugin --profile web update dsh-file-attachment。

架构

├── package.json # dsh.client 声明 + bundle patch 指向 ├── cordis.patch.yml # bundle 补丁：插入本插件行 └── lib/ ├── index.js # Host 半：webServer 路由（/save /config /describe）+ describe_image 工具 └── client.js # Client 半：document 级 capture drop/paste 监听 + 📎 按钮接管 + 槽组件

flowchart TB
subgraph client["Client 半 · lib/client.js"]
C1["capture 阶段拦截drop / paste / 📎 fileInput"]
C2["shadow 内联附件条conversation.input.attachments"]
C3["shadow 用户消息渲染器聊天区图片缩略图"]
C4["shell.overlay 浮动 toast"]
end
subgraph host["Host 半 · lib/index.js"]
H1["POST /savebase64 → node:fs/promises 写盘"]
H2["GET/POST /config可上传类型 · VLM 配置"]
H3["POST /describe"]
H4["tools.registerdescribe_image"]
end
VLM[("OpenAI 兼容 VLMMiMo 格式")]
C1 -- "文件 base64" --> H1
C2 -.-> H2
C1 -.-> C4
H3 --> VLM
H4 --> VLM
C3 -- "GET /api/file?path=" --> FS[(".dsh-file-attachment/ 落盘文件")]
H1 --> FS

- Host 半：前缀路由 /dsh-file-attachment——POST /save（base64 解码后用 node:fs/promises 写盘）、GET/POST /config（读写可上传类型与 VLM 配置）、POST /describe（调 VLM 返回中文描述与思考模式配置）；另经 tools.register 注册 describe_image 工具。响应信封 { ok, value | error }。
- Client 半：shadow 原生附件条（conversation.input.attachments）实现内联附件条；shadow 用户消息渲染器（conversation.chat.node keyed user）把聊天区 @图片路径 渲染为缩略图（经宿主 /api/file?path= 读取落盘图片）；capture 阶段拦截原生 fileInput change 事件接管 📎 按钮，文件进入插件统一管线；纯文本粘贴完全原生不改写。
- 通知与浮层：shell.overlay frame-wide 浮动 toast（不参与文档流，4 秒自动消失）；拖入任何文件时 capture 阶段拦截应用自带的图片 DropOverlay（其文案对文档是误导）。

开发说明

- lib/.js、package.json、cordis.patch.yml、README.md 均为 UTF-8 无 BOM，编辑时保持原编码。
- 纯 ESM 无构建，不依赖装饰器 / 远程反射。
- VLM 请求按 MiMo 官方格式发送 thinking: { type: "enabled"|"disabled" }（扁平的 thinkingType 会被 API 忽略；mimo-v2.5 默认开启深度思考，导致识别极慢——实测 206 秒，关闭后 22~73 秒）；超时后明确报错中止，不会挂死会话；未填 API Key 时识别静默跳过，不影响落盘。
- 50MB 上限两侧一致（client 跳过 + host 校验）。

Star

如果这个插件帮到了你，欢迎到 GitHub 仓库 点个 ⭐ Star，感谢支持！

dsh-file-attachment 是 DeepSeek Harness (DSH) 的 Web GUI 插件，支持通过拖拽、粘贴或 DSH 原生回形针按钮，把文件和图片附加到聊天输入框。

核心能力：统一存储管线，落在 .dsh-file-attachment/ 下；@absolute-path 引用，让纯文本模型也能使用附件；内联附件预览，以及可点击的聊天缩略图（带灯箱）；多文件上传，处理同名冲突，并设 50MB 上限；可选 OpenAI 兼容 VLM 描述，供非多模态模型使用；桌面端和移动端浏览器均可使用。

安装：

dsh plugin --profile web add @wszhoho/dsh-file-attachment

详细行为、设置、架构和开发说明，见上方的中文文档。

License

MIT