剪贴板里的截图,一行命令变成 Hermes 的输入:hermes clipboard image


你截了一张图,想直接问一句“这个报错是哪个环节出的”。人坐在终端里,最自然的动作是 Ctrl+V,但这套动作在你的脚本里根本不存在:你的脚本只会跑命令,不会按粘贴。于是你写了三行 shell 去调 xclip 存图,Windows 上那三行不生效,macOS 上又要换一套,最后只好放弃,手动另存文件。

11 月 6 日合并的改动把这件事收进了 Hermes 自己:hermes clipboard image 把本机剪贴板里的图片写成文件,成功时打印路径,加 --json 就得到一个稳定的 JSON 回复和分好的退出码。它读的只是运行它的这台机器的剪贴板——不需要网关在跑,也不碰会话库和配置文件。

以前的做法:去跑 TUI 的私有脚本

Hermes 的终端界面早就能粘贴图片,实现放在 hermes_cli/clipboard.py 里,做了很细的平台适配。但对外暴露的入口一直是个内部脚本:ui-tui/scripts/clipboard_image.py,第三方客户端要想用,得把 PYTHONPATH 指到 Hermes 源码树,再调这个脚本。

这条路能走,但三个地方都脆弱:脚本的路径可能变,参数可能变,连它返回的 true/false 都可能变。更麻烦的是“源码树在哪”这件事——客户端凭什么知道用户把 Hermes 装在哪里?

新命令就是把同一个提取器(hermes_cli.clipboard.save_clipboard_image)包成一个有文档、有退出码、有 JSON 的正式接口。

一行命令,把剪贴板变成文件

hermes clipboard image --out /tmp/shot.png

成功就打印路径。--out 指定的文件会被创建或覆盖,目录不存在会先建。脚本里更常用的是带 --json 的形态:

hermes clipboard image --out /tmp/shot.png --json
{"ok": true, "path": "/tmp/shot.png", "mime": "image/png", "bytes": 248193}

mime 不是猜的,是按文件头判的:PNG、JPEG、GIF、BMP、TIFF、WebP 都认。正常情况下输出一定是 PNG,因为提取器统一转成 PNG;唯一的例外是你复制的是一个图片文件(Windows/WSL 里拖文件那种),这时它是按字节原样拷过来的,所以格式可能是 jpg 或 webp。

每一种结局,都有对应的退出码

自动化里最怕的不是失败,是“失败了但你说不清为什么”。这个命令把每一种结局分开,各有退出码:

情况 JSON 里的 reason 退出码
图片写出来了 没有 reason,ok: true 0
剪贴板里没有图片(只有文字) no_image 1
这台机器没装任何可用的剪贴板工具 no_tool,并列出它找过的工具 3
--out 写不进去 write_failed 4
参数写错了 没有 JSON,走 argparse 的用法错误 2

no_image 和 no_tool 分开是有意义的:前者是“你没截图”,后者是“这台机器读不了剪贴板”,两种情况的修法完全不同。装在服务器上(没有图形会话)跑,得到的会是 no_tool,而不是一句含糊的失败。

为什么这个命令值得单独存在

因为它解决了一个具体的工程问题:读剪贴板必须是本地操作。

想一下网关的部署形态。用户的 Hermes 网关可能跑在一台远端机器或容器里,而人和他的剪贴板在笔记本上。如果把“读剪贴板”做成一个网关 RPC,那它读到的会是远端那台机器的剪贴板——毫无意义,通常是空的。所以这个命令被刻意设计成设备本地:不连网关、不读会话库、不读 profile 文件,严格只做“把本机剪贴板里的图写到路径”这一件事。

写文件的部分也做得比较谨慎:先在同目录下开一个私有临时目录,把图写进去,成功后再 rename 覆盖到 --out。所以失败时原有的 --out 文件原封不动,不会出现半个文件;覆盖已有文件时还会保留它原来的权限(0600 的临时文件不会把权限放宽)。

和 Hermes 串起来用

有了输出路径,剩下的就顺了。hermes chat 本来就有 --image,可以直接把一张本地图片附在一次提问上:

hermes clipboard image --out /tmp/shot.png --json > /tmp/shot.json
hermes chat -q "这个报错出在哪个环节?给出一句结论和一条排查命令" --image /tmp/shot.png --oneshot

想省掉中间文件也不难,jq 取一下路径:

SHOT=$(hermes clipboard image --out /tmp/shot.png --json | jq -r .path) && hermes chat -q "这个界面哪里对齐错了?" --image "$SHOT" --oneshot

如果不带 --oneshot,hermes chat 会进入交互式对话,图片只附在这一条提问上——日常用起来就是“截个图、问一句、接着聊”。

平台上会遇到的具体情况

  • macOS:先用 pngpaste(快,支持的格式多),没有再退回 osascript(系统自带,永远可用)。
  • Windows:先用 powershell,没有再用 pwsh。
  • Linux:WSL 里先试 powershell.exe;Wayland 上用 wl-paste;X11 上回到 xclip。WSL 探测失败会继续往下试——WSLg 下 wl-paste 或 xclip 也可能是通的。
  • NixOS 容器模式:所有 hermes 子命令都跑在受管容器里,这个命令也一样,所以它看不到宿主机的剪贴板,--out 也是容器内的路径。这不是 bug,是容器模式的固有边界。

顺带一提,终端里显示图片是另一件事:CLI 和 TUI 的行内图片 讲的是“附件和工具产出的图片怎么画在对话里”,而这篇讲的是“图片怎么从剪贴板落到磁盘”——两个方向,经常配着用。

现在能用吗

这个命令在 main 上(11 月 6 日,PR #150285),不在 v0.23.0 的标签里。判断方式很直接:hermes clipboard --help 有输出就说明你的版本带它;报 “invalid choice” 就是还没有。文档已经写进命令参考的 hermes clipboard 一节,等你升级之后照着用就行。

更新(2026-11-10):这批改动已随 v0.23.1 发布(2026-11-09),hermes update 升级即可用。上文「不在 v0.23.0 里」仍然成立,v0.23.1 把缺口补上了。

如果你想先确认自己这台机器有没有可用的提取工具,命令本身就会告诉你:在没有图片的时候,它区分“没图”和“没工具”,后者还会把找过的工具名列出来——那基本就是你需要装的东西清单。

总结

hermes clipboard image 是个小命令,但它修的是接口边界:把“读本机剪贴板”从 TUI 的私有实现提升成有文档、有退出码、有 JSON 的公开入口,并顺手把设备本地的语义说清楚。对写脚本的人来说,最实用的其实不是那条命令,而是那四个退出码——它让你在 shell 里用一个 case 就能把“没截图”“没工具”“写不进”“成功”分开处理,而不是去 grep 错误文本。