视觉与图像粘贴
Hermes Agent 支持 多模态视觉 — 你可以直接将剪贴板中的图像粘贴到 CLI 中，并让代理对其进行分析、描述或处理。图像以 base64 编码的内容块形式发送给模型，因此任何具备视觉能力的模型都可以处理它们。
工作原理
- 将图像复制到剪贴板（截图、浏览器图片等）
- 使用以下方法之一附加图像
- 输入你的问题并按 Enter 键
- 图像会以
[📎 图像 #1]的徽章形式显示在输入框上方 - 提交时，图像作为视觉内容块发送给模型
你可以在发送前附加多个图像 —— 每个图像都会获得自己的徽章。按 Ctrl+C 可清除所有附加的图像。
图像会被保存到 ~/.hermes/images/ 目录下，以时间戳命名的 PNG 文件格式保存。
粘贴方法
如何附加图像取决于你的终端环境。并非所有方法在所有地方都有效 —— 以下是完整说明：
/paste 命令
最可靠的方法，适用于所有环境。
/paste
输入 /paste 并按 Enter。Hermes 会检查你的剪贴板中是否有图像并自动附加。此方法在所有环境中都有效，因为它显式调用了剪贴板后端 —— 无需担心终端快捷键拦截。
Ctrl+V / Cmd+V（带括号的粘贴）
当你粘贴剪贴板中的文本时，如果其中还包含图像，Hermes 会自动检测图像。此方法在以下情况下有效：
- 剪贴板中同时包含 文本和图像（某些应用程序在复制时会同时放入文本和图像）
- 你的终端支持带括号的粘贴（大多数现代终端都支持）
如果你的剪贴板中仅包含图像（没有文本），在大多数终端中 Ctrl+V 不会生效。终端只能粘贴文本 —— 目前没有标准机制可以粘贴二进制图像数据。请使用 /paste 或 Alt+V。
Alt+V
Alt 键组合通常能绕过大多数终端模拟器（它们以 ESC + 键的形式发送，而非被拦截）。按 Alt+V 可检查剪贴板中是否有图像。
在 VSCode 内置终端中无法使用。 VSCode 会拦截许多 Alt+键组合用于其自身 UI。请改用 /paste。
Ctrl+V（原始模式 — 仅限 Linux）
在 Linux 桌面终端（GNOME Terminal、Konsole、Alacritty 等）中，Ctrl+V 并非粘贴快捷键 —— 实际是 Ctrl+Shift+V。因此 Ctrl+V 会向应用程序发送原始字节，Hermes 会捕获该字节以检查剪贴板。此方法仅适用于支持 X11 或 Wayland 剪贴板访问的 Linux 桌面终端。
平台兼容性
| 环境 | /paste | Ctrl+V（文本+图像） | Alt+V | 说明 |
|---|---|---|---|---|
| macOS Terminal / iTerm2 | ✅ | ✅ | ✅ | 最佳体验 —— osascript 始终可用 |
| Linux X11 桌面 | ✅ | ✅ | ✅ | 需要 xclip（apt install xclip） |
| Linux Wayland 桌面 | ✅ | ✅ | ✅ | 需要 wl-paste（apt install wl-clipboard） |
| WSL2（Windows Terminal） | ✅ | ✅¹ | ✅ | 使用 powershell.exe —— 无需额外安装 |
| VSCode 终端（本地） | ✅ | ✅¹ | ❌ | VSCode 拦截 Alt+键 |
| VSCode 终端（SSH） | ❌² | ❌² | ❌ | 远程剪贴板不可访问 |
| SSH 终端（任意） | ❌² | ❌² | ❌² | 远程剪贴板不可访问 |
¹ 仅当剪贴板中同时包含文本和图像时有效（仅图像剪贴板 = 无操作） ² 详见下方 SSH 与远程会话
平台特定设置
macOS
无需设置。 Hermes 使用 macOS 内置的 osascript 读取剪贴板。为获得更快性能，可选择性安装 pngpaste：
brew install pngpaste
Linux（X11）
安装 xclip：
# Ubuntu/Debian
sudo apt install xclip
# Fedora
sudo dnf install xclip
# Arch
sudo pacman -S xclip
Linux（Wayland）
现代 Linux 桌面系统（Ubuntu 22.04+、Fedora 34+）通常默认使用 Wayland。安装 wl-clipboard：
# Ubuntu/Debian
sudo apt install wl-clipboard
# Fedora
sudo dnf install wl-clipboard
# Arch
sudo pacman -S wl-clipboard
echo $XDG_SESSION_TYPE
# "wayland" = Wayland, "x11" = X11, "tty" = no display server
WSL2
无需额外设置。 Hermes 会自动检测 WSL2（通过 /proc/version），并使用 powershell.exe 通过 .NET 的 System.Windows.Forms.Clipboard 访问 Windows 剪贴板。这是 WSL2 的 Windows 互操作功能内置的 —— powershell.exe 默认可用。
剪贴板数据通过 stdout 以 base64 编码的 PNG 格式传输，因此无需文件路径转换或临时文件。
如果你正在运行 WSLg（WSL2 带 GUI 支持），Hermes 会优先尝试 PowerShell 路径，然后回退到 wl-paste。WSLg 的剪贴板桥仅支持 BMP 格式的图像 —— Hermes 会自动使用 Pillow（如果已安装）或 ImageMagick 的 convert 命令将 BMP 转换为 PNG。
验证 WSL2 剪贴板访问
# 1. Check WSL detection
grep -i microsoft /proc/version
# 2. Check PowerShell is accessible
which powershell.exe
# 3. Copy an image, then check
powershell.exe -NoProfile -Command "Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.Clipboard]::ContainsImage()"
# Should print "True"
SSH 与远程会话
SSH 连接中无法使用剪贴板粘贴功能。 当你通过 SSH 登录远程机器时，Hermes CLI 在远程主机上运行。所有剪贴板工具（xclip、wl-paste、powershell.exe、osascript）读取的是它们所在机器的剪贴板 —— 即远程服务器，而非你的本地机器。你的本地剪贴板无法从远程端访问。
SSH 的替代方案
-
上传图像文件 — 将图像文件本地保存，通过
scp、VSCode 文件资源管理器（拖放）或任何文件传输方式上传至远程服务器。然后通过路径引用该图像。(未来版本计划支持/attach <filepath>命令。) -
使用 URL — 如果图像在线可访问，只需将 URL 粘贴到消息中。代理可直接使用
vision_analyze查看任意图像 URL。 -
X11 转发 — 使用
ssh -X连接以转发 X11。这使得远程机器上的xclip能够访问本地 X11 剪贴板。需要本地运行 X 服务器（macOS 上为 XQuartz，Linux X11 桌面环境内置）。对于大图像，速度较慢。 -
使用消息平台 — 通过 Telegram、Discord、Slack 或 WhatsApp 向 Hermes 发送图像。这些平台原生支持图像上传，不受剪贴板/终端限制的影响。
为什么终端无法粘贴图像
这是常见的困惑来源，以下是技术解释：
终端是基于文本的接口。当你按下 Ctrl+V（或 Cmd+V）时，终端模拟器会：
- 从剪贴板读取文本内容
- 将其包裹在 带括号的粘贴 转义序列中
- 通过终端的文本流发送给应用程序
如果剪贴板中仅包含图像（无文本），终端将无内容可发送。目前没有标准的终端转义序列用于二进制图像数据。因此终端什么也不做。
这就是为什么 Hermes 使用独立的剪贴板检查机制——它不通过终端粘贴事件接收图像数据，而是通过子进程直接调用操作系统级别的工具（osascript、powershell.exe、xclip、wl-paste）来独立读取剪贴板。
支持的模型
图像粘贴功能适用于任何具备视觉能力的模型。图像将以 OpenAI 视觉内容格式的 base64 编码数据 URL 形式发送：
{
"type": "image_url",
"image_url": {
"url": "data:image/png;base64,..."
}
}
大多数现代模型均支持此格式，包括 GPT-4 Vision、Claude（具备视觉功能）、Gemini，以及通过 OpenRouter 提供的开源多模态模型。