dsh-screenshot-paste: DeepSeek Harness Plugin, Install & GitHub Guide

📎 dsh-screenshot-paste

为 DeepSeek Harness (DSH) Web GUI 提供截图与文件粘贴板功能：粘贴、拖拽或浏览上传文件，以引用芯片的形式置于输入框上方，发送消息时自动附带文件路径。

纯外部插件：不修改 DSH 源码，仅使用官方扩展点（UI 插槽、API 路由、agent/pre-step 事件）。

✨ 功能特性

	特性	说明
📋	多方式上传	Ctrl+V 粘贴、拖拽、点击浏览（支持多文件）
🗂️	文件类型丰富	图片 / PDF / Office 文档 / 压缩包 / 音视频 / 文本；白名单之外的类型（如 `.exe`）明确拒绝
🏷️	引用芯片	上传的文件以芯片形式显示在输入框上方，支持预览与移除
📤	自动附带路径	发送消息时自动将文件路径追加至消息内容，发送后自动清空
📁	原生目录选择	面板「更改」按钮弹出系统原生文件夹选择框（官方 `directoryPicker` 服务，PowerShell 兜底），随时更换保存目录
🔄	自动迁移	更换保存目录时自动把旧目录文件搬到新目录（同名加后缀不覆盖），已引用路径同步更新，引用状态不丢失
🧹	引用自动清理	源文件被删除后，对应引用芯片自动消失，不会附带失效路径
🧹	零输入框污染	不向输入框、光标或草稿插入任何内容
💰	零常驻开销	不注册工具、不贡献提示词；无引用时对模型请求无任何影响
🔒	安全	所有 API 仅限本机回环访问；文件名经过校验，防止路径穿越；保存目录自动创建

📦 安装

环境要求

已安装 DeepSeek Harness 及其 dsh 命令行工具
目标 profile 为 web

安装插件

固定版本（推荐，可复现）：

dsh plugin --profile web add github:PdxGame/dsh-screenshot-paste@v0.1.1

如需跟踪最新 main，去掉 @v0.1.1 后缀。

[!TIP] 若 dsh 不在 PATH（例如通过 pnpm dsh 启动的环境），在 DSH 安装目录下改用：
pnpm dsh plugin --profile web add github:PdxGame/dsh-screenshot-paste@v0.1.1

[!IMPORTANT] 安装完成后，重启 dsh web 并强制刷新浏览器（Ctrl+F5），客户端资源才会重新加载。

安装后验证

重启后打开 http://127.0.0.1:3080，任意会话输入框工具区应出现 📎 按钮。也可命令行验证宿主 API：

curl http://127.0.0.1:3080/api/screenshot-paste/list
# 应返回 {"dir":"<插件目录>/screenshots","files":[...]}

卸载

dsh plugin --profile web remove dsh-screenshot-paste

卸载后重启 dsh web 生效。

⚙️ 配置

插件开箱即用，零配置。保存目录按以下优先级解析：

优先级	配置来源	说明
1	设置项 `dsh-screenshot-paste.dir`	在 DSH 设置页或 `~/.dsh/settings.yaml` 中配置，改动即时生效，无需重启
2	环境变量 `DSH_SCREENSHOT_DIR`	显式指定保存目录
3	默认值	插件目录下的 `screenshots/`（临时中转文件，已被 `.gitignore` 排除）；该路径不可用时自动回退至 `~/.dsh/screenshots`

设置项（优先级 1）与其他 DSH 插件（如 dsh-ssh）使用同一配置机制。示例：

# ~/.dsh/settings.yaml
dsh-screenshot-paste:
  dir: "D:\\dsh-screenshots"

环境变量（优先级 2）示例：

set DSH_SCREENSHOT_DIR=D:\dsh-screenshots

设置项留空时，按优先级 2、3 依次解析。

🎯 使用

打开任意会话，在输入框工具区找到 📎 按钮
点击 📎 打开粘贴板面板，粘贴、拖拽或浏览上传文件
文件保存后，输入框上方显示引用芯片（图片芯片可点击预览）
输入消息并发送，消息自动附带文件路径：

[附件引用]
<插件目录>\screenshots\shot-142314.png
<插件目录>\screenshots\报告-150601.docx

智能体按文件类型处理：文本与 Office 文档可直接读取；图片的识别依赖视觉能力（见下文）

更换保存目录

面板底部「保存目录」旁点击**「更改」**，弹出系统原生文件夹选择框，选好后：

保存目录立即切换，面板显示新路径
旧目录中的文件自动迁移到新目录（同名文件自动加 -1/-2 后缀，绝不覆盖）
已添加的引用路径同步更新，引用状态保持不变
面板提示「已迁移 N 个文件到新目录」

[!NOTE] 保存目录的默认位置是插件目录下的 screenshots/（已加入 .gitignore，不会上传到 GitHub；首次使用时自动创建）。它是临时中转目录，重装或更新插件时会被清空——长期保留的文件请换到其他位置。

[!NOTE] 模型拿到的是文件路径（如 <插件目录>\screenshots\报告-150601.docx），需要智能体的文件访问能力能读到该路径。受限沙箱会话可能无法访问保存目录之外的文件——如需使用，请将保存目录配置在会话工作区可达的位置（见「⚙️ 配置」）。

👁️ 识图能力（可选，需自行配置）

本插件不包含任何视觉模型或识图能力，仅负责文件落地与路径附带。若需要智能体识别图片内容（描述图片、提取图中文字等），必须另行配置。

推荐：安装 claude-vision-skill ——让无视觉能力的模型获得识图能力，把图片交给视觉模型识别后用文字返回：

克隆仓库：git clone https://github.com/asuojun/claude-vision-skill.git
按仓库 README 配置：将 vision.js 放入 DSH 技能目录，填写 API Key 与模型名
默认推荐阿里云百炼千问模型（新用户有免费额度）；也支持 OpenAI 等任何 OpenAI 兼容格式的服务，改 BASE_URL 即可

备选方案：使用其他支持视觉的 skill，或选择支持图片输入的多模态模型。

两种方式由你的运行环境提供，与本插件完全解耦，配置与否不影响插件本身的功能。

[!NOTE] 未配置视觉能力时：文本、Office 文档等文件照常处理；图片仍会以路径形式附带，但模型无法查看其内容，通常会明确说明这一点——不会静默失败。

❓ 常见问题

Q：不附带引用时，会影响 token 消耗或缓存吗？

不会。插件不注册工具、不贡献提示词；无引用时 agent/pre-step 监听器直接放行，模型请求与未安装插件时完全一致。唯一的额外开销是附带引用时追加的路径文本（约几十 token）。

Q：插件自带识图能力吗？

不带。插件只负责文件落地与路径附带，不调用任何视觉模型。识别图片内容需要自行配置视觉 skill（推荐 claude-vision-skill，见上文「👁️ 识图能力」）或使用支持视觉的模型。没有识图能力时，文本类文件照常处理，图片会得到明确提示而非静默失败。

Q：DSH 升级会影响插件吗？

插件安装于 profile（用户数据区），独立于 DSH 安装目录，升级不会丢失。插件仅依赖官方扩展点；若 DSH 大版本变更相关接口，需要按新接口适配。

Q：更换保存目录后，旧文件会丢吗？

不会。切换目录时插件自动把旧目录中的文件迁移到新目录（同名文件加后缀，绝不覆盖），已添加的引用路径也会同步更新。若个别文件迁移失败（如被占用），会留在原目录，不影响新目录使用。

Q：删除了已引用的文件，引用会怎样？

引用会自动消失。面板刷新时会校验引用对应的文件是否还存在，不存在的引用会被自动清理，因此不会把失效路径附带进消息。

Q：为什么修改后需要重启服务器？

DSH 的客户端资源版本号在服务器启动时生成。任何插件变更（宿主端或客户端）都需要重启 dsh web 并硬刷新浏览器才能生效。

🧪 开发

仓库自带离线冒烟测试，运行于临时目录，不触碰真实数据：

node tests/test-host.mjs

📁 项目结构

dsh-screenshot-paste/
├── lib/
│   ├── index.js    # 宿主端：文件 API、引用存储、agent/pre-step 附带
│   └── client.js   # 浏览器端：📎 入口、粘贴板面板、引用芯片
├── tests/test-host.mjs   # 离线冒烟测试
├── cordis.patch.yml      # 插件注册（bundle patch）
└── package.json          # 包声明（dsh.bundle / dsh.client）

📄 许可证

MIT

PdxGame / dsh-screenshot-paste

Installation

README