Johnny-xuan/dsh-paste-to-path

dsh-paste-to-path

A universal attachment dock for DSH.

dsh-paste-to-path 给 DSH Web composer 增加了一个通用附件 Dock。

你可以直接粘贴、拖入或选择图片、PDF、Word、Excel、压缩包、代码、日志以及其他文件，在发送前统一查看和管理它们。

图片、PDF、压缩包等不同格式，都可以放进同一个附件 Dock。

DSH 0.1.2-rc.1 的 Web composer 提供原生图片附件链路，但 PDF、Office 文档、压缩包以及其他格式仍没有同样独立于模型能力的入口；即使是图片，在不支持图像输入的模型或 text-only adapter 下，也可能无法直接发送。

dsh-paste-to-path 不去扩展模型原生的 content 类型，而是走另一条更简单的路径：

文件
↓
DSH Host
↓
本地路径
↓
Agent
↓
你自己接入的工具

图片可以交给你自己接入的 vision 工具，PDF 可以交给文档读取工具，压缩包可以用 shell 或解压工具处理。

插件负责的是附件接收、管理和路径传递；文件具体怎么读取，由你的 Agent 工具栈决定。

路径流程概览

文件先保存到 DSH Host，再把路径交给 Agent。

能做什么

通用附件 Dock

粘贴、拖入或选择文件后，输入框上方会出现对应的附件卡片。插件提供的回形针按钮接受任意格式，不进入 DSH 原生的图片专用附件栏。

每张卡片会显示文件名、大小、类型和路径，并且可以在发送前移除。

图片还支持缩略图和灯箱预览。

文件管理器剪贴板支持

只要浏览器确实提供了 File 对象，插件就会接住它，包括空文件。浏览器如果提供 file: URI 或绝对路径，并且该路径确实存在于 DSH Host，插件也可以直接把它变成附件卡片。

路径转换是事务性的：候选路径必须全部存在于 DSH Host。只要其中一个不可用，插件就会把剪贴板原文作为普通文本粘贴，不显示附件错误，也不会只转换一部分。

Windows Explorer、Finder 和 Linux 文件管理器复制非图片文件时，不同浏览器暴露的剪贴板内容并不一致。如果粘贴事件既没有文件字节，也没有可用的 Host 路径，普通网页无法从被浏览器隐藏的系统剪贴板格式中恢复文件。为处理 Issue #2，本机 Windows Host 通过直接 localhost 使用时，插件会在这一步读取 Explorer 的 FileDropList；远程连接不会访问 Host 剪贴板。其他情况下请使用插件自己的回形针按钮或拖放。

多种文件使用同一套流程

图片、PDF、Office 文档、代码、日志、压缩包以及其他二进制文件，都走同一个附件流程：

文件 → 保存到 Host → 路径引用 → Agent

不需要为每种文件类型单独设计一套模型输入协议。

长文本自动转成附件

普通文本仍然正常粘贴。

当粘贴内容超过设定阈值时，插件可以自动把它保存为 .txt 文件，而不是把几万字直接塞进输入框。

默认阈值是 8000 个字符。

发送前编辑文本文件

文本和代码附件在不超过配置的大小限制时，可以直接在 Dock 中修改。

默认上限为 1 MiB。

用系统应用打开文件

本机部署时，可以通过 DSH 已鉴权的 session.openWorkspacePath Remote API 使用系统默认程序打开附件。

安装

安装到 DSH Web profile：

dsh plugin --profile web add dsh-paste-to-path

也可以直接安装 GitHub 当前分支：

dsh plugin --profile web add github:Johnny-xuan/dsh-paste-to-path

安装完成后重新启动：

dsh web

包内包含 dsh.bundle manifest，所需的 loader patch 会随插件一起加载。

它是怎么工作的

当你粘贴、拖入或选择文件时，插件会先接住这个文件并在 DSH Host 保存一份私有副本：

/.dsh/pastes//

输入框中不会直接塞入文件内容，而是保留一个附件引用。

如果粘贴的是已经存在于 DSH Host 的绝对路径，插件会直接引用原文件，不再复制；这类路径附件不能在 Dock 中编辑原文件。

发送消息时，DSH 的 reference codec 会把这个引用展开成一段简短的路径说明：

粘贴 / 拖入文件
│
▼
保存到 DSH Host
│
▼
Attachment Dock
显示附件卡片
│
▼
发送消息
│
▼
reference codec
生成文件路径说明
│
▼
Agent 收到路径
│
▼
调用当前可用的工具读取

整个过程使用 DSH 自己提供的扩展机制：

- conversation.input.dock
- conversation.input.left
- input-trigger reference codec
- settingsScope

不需要修改 DSH 核心代码。

Agent 实际收到什么

插件不会把文件字节直接放进首次模型请求。

例如，一个 PDF 会被展开成：

Document attachment: /absolute/path/to/report.pdf
Read it using an appropriate tool for this file format.

图片则类似：

Image attachment: /absolute/path/to/image.png
Inspect it using an available image-reading method.

文本、代码、压缩包和其他格式也会生成对应的路径说明。

这些说明不会指定某一个固定工具。Agent 会根据当前会话真正可用的工具决定下一步怎么处理。

使用你自己的工具

dsh-paste-to-path 本身不提供文件解析能力。

你可以按照自己的 Agent 环境接入任意工具，例如：

- 图片 → 自己配置的 read_image、vision 工具
- PDF / Word / Excel → 文档读取工具
- 扫描件 → OCR
- 代码 / 日志 → shell 或文件系统工具
- ZIP / TAR → 解压工具

插件不会安装这些工具，也不会假设当前模型具备这些能力。

只要工具能够访问 DSH Host 上的文件路径，就可以读取插件保存下来的附件。

如果当前 Agent 没有适合的工具，那么文件虽然已经成功进入 Dock 并保存到 Host，Agent 仍然无法理解它的内容。

为什么使用路径

DSH 原生附件链路里，文件格式和模型能力通常绑得比较紧。

在 DSH 0.1.2-rc.1 中，原生 Web 图片入口接收：

- PNG
- JPEG
- WebP
- GIF

其他 MIME 类型不会进入同一套原生图片链路。

而通过格式检查的图片，如果最终进入一个不支持图像输入的模型或 text-only adapter，也仍然可能失败。

dsh-paste-to-path 把这两件事拆开：

把文件交给 Agent

和：

理解文件内容

插件只处理前一件事。

文件先变成 Host 上的普通文件，再由 Agent 的工具层负责第二步。

配置

默认配置位于随包提供的 cordis.patch.yml：

- insert:
- id: paste-to-path
name: dsh-paste-to-path
config:
capturePaste: true
captureDrop: true
showPicker: true
showDock: true
longTextAsAttachment: true
longTextThreshold: 8000
pathTextAsAttachment: true
windowsClipboardFallback: true
maxBytes: 26214400
editableTextMaxBytes: 1048576

| 配置项                    | 默认值    | 说明                    |
| ---------------------- | ------ | --------------------- |
| capturePaste | true | 注册文件、Host 路径和长文本的 paste 监听器 |
| captureDrop | true | 注册文件拖拽监听器 |
| showPicker | true | 在 conversation.input.left 注册回形针入口 |
| showDock | true | 在 conversation.input.dock 注册路径附件 Dock |
| longTextAsAttachment | true | 是否把长文本保存为 .txt 附件   |
| longTextThreshold    | 8000 | 长文本触发阈值，单位为字符         |
| pathTextAsAttachment | true | 把确实存在于 DSH Host 的绝对路径变成附件 |
| windowsClipboardFallback | true | 浏览器隐藏文件字节时，仅在 Windows Host 的直接 localhost 连接读取 Explorer FileDropList |
| maxBytes             | 25 MiB | 单个附件最大大小              |
| editableTextMaxBytes | 1 MiB  | Dock 中允许直接编辑的最大文本文件大小 |

十项配置都可以在 Settings → Plugins → Paste to Path 中修改。0.0.6 使用 DSH 官方第三方 settings scope，配置通过 DSH settings 持久化并立即生效。关闭前四项中的任何一项时，插件会真正注销对应 listener 或 slot，而不是保留一个空转 handler。重置按钮会把十项配置恢复为上方 profile 中的默认值。

附件 Dock、操作提示和设置卡会跟随 DSH 的 Language 设置，目前提供英文和简体中文。发送给 Agent 的路径说明仍保持为稳定的英文协议文本，不会跟随界面语言变化。

如果 Web UI 没有可写的 settings scope，请在对应 profile 的 cordis.patch.yml 中覆盖 paste-to-path 配置；即使设置卡只读，附件处理仍会按 Host 返回的配置继续工作。

与其他上传插件共存

默认配置仍保留 Paste to Path 的完整体验。如果希望其他插件接管拖放和回形针，而 Paste to Path 保留剪贴板入口与路径 Dock，可以使用：

capturePaste: true
captureDrop: false
showPicker: false
showDock: true

如果粘贴也应完全交给其他插件，再把 capturePaste 设为 false。Host 路径存储、会话隔离、reference 序列化、路由鉴权和生命周期清理始终保留；释放的只有指定的浏览器 listener 和 UI slot。

文件存储

有 workspace 时，附件保存在：

/.dsh/pastes//

没有 workspace 时回退到：

$DSH_HOME/tmp-paste//

复制到插件存储目录的文件权限为：

0600

把已经存在于 Host 的路径粘贴成附件时，插件只原地引用：不会复制文件、修改其权限，也不会允许 Dock 编辑原文件。

从 Dock 中移除一个附件，只会移除当前草稿里的引用，不会删除磁盘上的文件。

这样在撤销、重新发送或重新引用附件时，原来的路径仍然有效。

隐私

通过选择、拖放或浏览器 File 对象进入的文件会上传到你自己的 DSH Host，并保存在 Host 的本地文件系统中；已经存在的 Host 路径只会被原地引用。

在 DSH 0.1.2-rc.1 上，插件所有 HTTP 路由都会经过 DSH 的浏览器鉴权与 Host/Origin 信任检查；附件记录按会话隔离，路由注册也由插件的 Cordis 生命周期负责回收。

插件本身不会：

- 把文件直接上传给模型供应商
- 上传到第三方文件服务
- 在上传阶段解析文件内容

首次模型请求中出现的只是文件路径和一条简短说明。

如果 Agent 后续调用其他工具或外部服务处理文件，则以对应工具自己的行为和配置为准。

设计边界

dsh-paste-to-path 只负责这一段：

File
↓
Attachment Dock
↓
Host filesystem
↓
Path reference

至于：

Path
↓
Vision / PDF Reader / OCR / Shell / ...

属于 Agent 的工具层。

因此插件不会：

- 修改或替换模型 adapter
- 伪装模型具备视觉能力
- 绑定固定的 vision / OCR / document 工具
- 在传输阶段解析附件内容
- 生成 DSH 原生 image content block

兼容性

0.0.6 面向并已在以下版本验证：

DeepSeek Harness 0.1.2-rc.1

它适配了 Lexical composer、slot 的 useInput store、带长度的 reference occurrence、Web 路由鉴权、Cordis 路由回收，以及当前 Remote 打开路径 API。已发布的 0.0.4 继续作为 DSH 0.1.0-rc.6 到 0.1.0-rc.8 的兼容版本。

DSH 当前仍处于 developer preview。后续版本如果调整相关扩展接口，插件可能需要同步适配。