dsh-clipboard

Readme

# dsh-clipboard

把文本写入**系统剪贴板**的 DSH 插件。零依赖、纯 ESM JavaScript、无需构建。

## 简介

注册一个工具 `clipboard_write`，接收任意文本并写入系统剪贴板，方便 agent 把生成的结果直接交给用户粘贴使用（例如复制命令、代码片段、URL、密钥等）。

执行结果始终返回规范 JSON 值，**任何失败都不抛异常**：

```jsonc
{ "ok": true,  "bytes": 42, "tool": "pbcopy" }
{ "ok": false, "bytes": 42, "tool": null, "error": "no clipboard tool available (install xclip or xsel): ..." }
```

## 安装

```sh
dsh plugin --profile <profile-name> add dsh-clipboard
# 本地开发：
dsh plugin --profile <profile-name> add file:./plugins/dsh-clipboard
```

## 平台依赖

| 平台 | 实现 | 是否需要安装 |
|---|---|---|
| macOS | `pbcopy`（`/usr/bin/pbcopy`） | 免装，系统自带 |
| Windows | `clip` | 免装，系统自带 |
| Linux | `xclip`（优先）或 `xsel` | 需要安装其一：`sudo apt install xclip` 或 `sudo apt install xsel`；两者都没装时工具返回 `ok: false` 并提示安装 |

> 注意：Linux 下需要可用的 X11/Wayland 会话（`DISPLAY`/`WAYLAND_DISPLAY`）。无图形会话（如纯 SSH、CI 容器）会写入失败。

## 使用场景

- 让 agent 把生成的一行命令、SQL、JSON、代码片段直接放进剪贴板，用户粘贴即用。
- 复制临时 token / URL / 文件路径，省去手动选中。
- 作为多步工作流里的“交接输出”步骤。

## 自检

插件挂载时自动写入一次 `clipboard-probe-<时间戳>`；macOS 上会用 `pbpaste` 读回比对，Linux/Windows 只报告写入结果。日志前缀 `[dsh-clipboard]`。

## License

MIT