dsh-clipboard-tools

把系统剪贴板接进 DeepSeek Harness：AI 读得到你刚复制的文字和截图，也写得进剪贴板让你随手粘贴。

用 Agent 干活，最常断的是"最后一公里"：模型写好一段文案、一段 SQL、一张图表，你还得手动选中再复制；反过来你把报错贴进了聊天框，却还得先存成文件模型才读得到。这个插件把剪贴板本身做成两个模型工具。

名字说明：npm 上已经有一个只支持"写文本"的 dsh-clipboard，所以本包叫 dsh-clipboard-tools——它是超集：读 + 写、图片双向、Windows 下中文和 emoji 不丢字。

工具	作用	用户会怎么说
clipboard_read	读剪贴板里的文字；如果是图片，就存成 PNG 放进工作区，再交给 read_image 看	"我刚复制的那段报错" / "看下我截的图" / "剪贴板里是什么"
clipboard_write	把文字、文本文件内容或图片放进剪贴板	"把这段放我剪贴板" / "这张图复制好，我去发群"

安装

仓库刚建好、还没发 npm 时，用 tarball 安装（推荐，依赖解析最干净）：

git clone https://github.com/kohjuz/dsh-clipboard-tools.git
cd dsh-clipboard-tools
npm pack
dsh plugin --profile <profile> add ./dsh-clipboard-tools-0.1.0.tgz

发布到 npm 之后就是一条命令：

dsh plugin --profile <profile> add dsh-clipboard-tools

dsh plugin add 会把 bundle 追加进该 profile 的 dsh.profile.bundles，下次启动生效。验证装配：

dsh --profile <profile> --dump-config | grep -B2 -A6 dsh-clipboard-tools

平台支持

平台	文本	图片	依赖
Windows 10/11	✅ Get-Clipboard / Set-Clipboard	✅ GDI+	系统自带 PowerShell
macOS	✅ pbpaste / pbcopy	✅（TIFF 经 sips 转 PNG）	系统自带
Linux / Wayland	✅ wl-paste / wl-copy	✅	apt install wl-clipboard
Linux / X11	✅ xclip / xsel	✅ 仅 xclip	apt install xclip

先体检再排查：

node bin/clipboard.js doctor     # 打印识别到的后端和已安装的助手工具
node bin/clipboard.js selftest   # 真实写一次再读回来比对

用法

在对话里说人话就行：

• "把我刚复制的那段日志读一下，找出报错行"
• "把 README 里「安装」那一节复制到我剪贴板"
• "把刚生成的图表复制好，我要发到群里"

模型侧等价于：

{ "name": "clipboard_read",  "arguments": { "format": "auto" } }
{ "name": "clipboard_write", "arguments": { "path": "dist/report.md" } }
{ "name": "clipboard_write", "arguments": { "imagePath": "charts/revenue.png" } }

clipboard_read 也可以指定 format: "text" / "image" 跳过自动探测，或用 saveDir 指定图片落盘目录。

配置

写进 profile 的 cordis.patch.yml（或 --patch 覆盖层）：

- id: clipboard
  config:
    maxChars: 20000      # 单次读取返回的最大字符数，超长截断并标记 truncated
    imageDir: clipboard  # 读到的图片落在工作区哪个目录
    timeoutMs: 8000      # 单次剪贴板调用的超时

设计取舍

• 零运行时依赖：不装任何 npm 包，平台能力全部走系统自带工具，安装不会污染 profile。
• 子进程 stdio 走临时文件，不走管道：DSH 的 Windows 沙箱禁止命名管道，stdio: 'pipe' 会让子进程直接 EPERM；文件在沙箱内外都能用，顺带也更省内存。
• 每次调用都有超时：剪贴板助手卡住时杀进程返回 124，不会拖住整轮对话。
• Windows 文本经 UTF-8 文件进出：不经过 argv / stdout，中文、emoji、长文本都不受控制台代码页影响。
• 图片先落盘再交给模型：不把二进制塞进上下文，模型用 read_image 自己决定看不看。
• 工具定义与宿主解耦：lib/tools.js 不 import 任何 @deepseek-ai/*，单测里传个假的 defineTool 就能跑全部逻辑。

安全

• 只读写本机剪贴板，不联网。
• 除图片外不落盘；图片写到当前 agent 工作区（默认 clipboard/，文件名带时间戳）。
• 读到的内容会作为工具结果进入会话记录，和粘贴进对话是同一级别的暴露面；密码管理器一类的敏感内容请自己把握。
• clipboard_write 只写不读回，不会把剪贴板内容悄悄送给模型——除非你让它再读一次。

开发

index.js            插件入口：name / inject / apply，只有 20 行
lib/clipboard.js    平台适配、进程调用、PNG 尺寸解析（零依赖，可单测）
lib/tools.js        两个 defineTool 定义（不 import 宿主包，可单测）
test/               node:test 用例（39 个）
bin/clipboard.js    命令行自测：doctor / read / write / selftest
docs/DEVELOPING.md  架构、测试、装进 profile 调试的完整流程
docs/PUBLISHING.md  发布到 GitHub / npm 的逐步清单

npm test              # 跑全部用例（39 个）
npm run test:inline   # 在 DSH 沙箱里跑测试时用（沙箱禁管道 stdio，测试器起子进程会 EPERM）
npm run doctor        # 看本机剪贴板后端
npm run selftest      # 真实写读一次

已验证

• Windows 11 + dsh 0.2.1-rc.5：中文 + emoji 文本写入/读出无差异；320×200 PNG 写入后读回，尺寸与内容一致。
• 真实 Agent 链路：在隔离 profile 里用 headless 跑一轮，模型调用 clipboard_write → clipboard_read，随后用 PowerShell Get-Clipboard 独立复核，剪贴板内容与指令一致。

License

MIT