前言¶
用 DeepSeek Harness（DSH）跑 Agent 时，内容和系统剪贴板之间往往还要人工中转：模型生成一段 SQL 或文案，你要选中再复制；你把报错贴进聊天框之前，有时还得先落盘成文件，模型才读得到。npm 上已有只支持写文本的 dsh-clipboard；维护者 kohjuz 发布的 dsh-clipboard-tools 在读写两侧都覆盖文本与图片，并在 Windows 下通过 UTF-8 文件路径处理中文和 emoji。下面介绍它是什么、怎么装、怎么用。
这是什么¶
dsh-clipboard-tools 是 DSH 客户端类插件（GitHub：kohjuz/dsh-clipboard-tools，社区目录：skillhub.cn 条目）。它在宿主里注册两个模型工具，让 Agent 能读你刚复制的文字或截图，也能把生成结果写回剪贴板，方便你在任意应用里粘贴。运行时零 npm 依赖，平台能力走系统自带或常见系统工具（PowerShell、pbpaste/pbcopy、wl-clipboard、xclip 等）。
核心功能¶
插件暴露两个工具，对应 README 中的说明：
| 工具 | 作用 |
|---|---|
clipboard_read |
读取剪贴板文字；若为图片则存成 PNG 到工作区，供模型通过 read_image 查看 |
clipboard_write |
将文字、文本文件内容或图片写入剪贴板 |
clipboard_read 支持 format: "auto"（默认）、"text"、"image"，以及 saveDir 指定图片落盘目录。clipboard_write 可通过 path 写文本文件内容，或通过 imagePath 写图片。
设计上的几个要点（均来自仓库 README）：子进程 stdio 走临时文件而非管道，以适配 DSH Windows 沙箱；每次调用有超时（默认配置见下文）；读到的图片先落盘再交给模型，避免把二进制塞进上下文；clipboard_write 只写不读回，不会悄悄把剪贴板内容送回模型，除非你再次调用 clipboard_read。
平台支持¶
| 平台 | 文本 | 图片 | 依赖 |
|---|---|---|---|
| Windows 10/11 | ✅ | ✅（GDI+） | 系统自带 PowerShell |
| macOS | ✅ | ✅（TIFF 经 sips 转 PNG） |
系统自带 |
| Linux / Wayland | ✅ | ✅ | apt install wl-clipboard |
| Linux / X11 | ✅ | ✅（仅 xclip） | apt install xclip |
装好后可在插件目录用 CLI 自检：
node bin/clipboard.js doctor
node bin/clipboard.js selftest
doctor 打印识别到的后端和已安装的助手工具；selftest 真实写一次再读回来比对。package.json 里等价脚本为 npm run doctor、npm run selftest。
安装与启用¶
发布到 npm 后，一条命令把 bundle 追加进指定 profile 的 dsh.profile.bundles，下次启动生效：
dsh plugin --profile <profile> add dsh-clipboard-tools
仓库 README 还说明：在尚未发 npm 时，可在本地执行 npm pack 得到 dsh-clipboard-tools-0.1.0.tgz（package.json 当前版本为 0.1.0），再安装 tarball：
dsh plugin --profile <profile> add ./dsh-clipboard-tools-0.1.0.tgz
验证是否装配成功：
dsh --profile <profile> --dump-config | grep -B2 -A6 dsh-clipboard-tools
插件要求 Node.js >= 20。许可证为 MIT。
配置¶
可在 profile 的 cordis.patch.yml（或 --patch 覆盖层）中调整 clipboard 插件项，README 示例为：
- id: clipboard
config:
maxChars: 20000
imageDir: clipboard
timeoutMs: 8000
maxChars 为单次读取返回的最大字符数，超长会截断并标记 truncated；imageDir 为读到的图片落在工作区的目录；timeoutMs 为单次剪贴板调用的超时。
典型用法¶
对话里用自然语言即可，例如：
- 「把我刚复制的那段日志读一下，找出报错行」
- 「把 README 里「安装」那一节复制到我剪贴板」
- 「把刚生成的图表复制好，我要发到群里」
模型侧等价调用示例：
{ "name": "clipboard_read", "arguments": { "format": "auto" } }
{ "name": "clipboard_write", "arguments": { "path": "dist/report.md" } }
{ "name": "clipboard_write", "arguments": { "imagePath": "charts/revenue.png" } }
适用场景与注意¶
适合经常在 DSH Agent 与浏览器、IDE、聊天软件之间搬运文本或截图的开发者。插件只读写本机剪贴板、不联网；除图片外不落盘，图片写到当前 agent 工作区（默认目录见配置）。读到的内容会作为工具结果进入会话记录，与手动粘贴进对话的暴露面相当，敏感内容需自行判断。
权限与安全：插件以当前 dsh 进程的权限运行。安装前应阅读 GitHub 仓库 源码与 MIT 许可证，确认符合你的环境策略。DSH 生态强调「一切皆插件」；skillhub.cn 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。
README 已记录的环境验证包括 Windows 11 + dsh 0.2.1-rc.5 下的中文、emoji 与 PNG 读写，以及 headless profile 中 clipboard_write → clipboard_read 与 PowerShell Get-Clipboard 的独立复核。
结尾¶
dsh-clipboard-tools 把剪贴板做成 clipboard_read / clipboard_write 两个工具，补齐 Agent 与日常应用之间的「最后一公里」。进一步了解可访问社区目录页 https://www.skillhub.cn/plugins/kohjuz/dsh-clipboard-tools 与 GitHub https://github.com/kohjuz/dsh-clipboard-tools。
