好奇心花园🪴

搜索

SearchSearch

最近的笔记

视觉与图片粘贴

2026年5月24日12分钟阅读

视觉与图片粘贴

Hermes Agent 支持多模态视觉——您可以将剪贴板中的图片直接粘贴到 CLI 中，让代理分析、描述或处理它们。图片作为 base64 编码的内容块发送给模型，因此任何支持视觉的模型都可以处理它们。

工作原理

  1. 将图片复制到剪贴板（截图、浏览器图片等）
  2. 使用以下方法之一附加图片
  3. 输入您的问题并按 Enter
  4. 图片在输入上方显示为 [📎 图片 #1] 徽章
  5. 提交时，图片作为视觉内容块发送给模型

您可以在发送前附加多张图片——每张都有其自己的徽章。按 Ctrl+C 清除所有已附加的图片。

图片保存到 ~/.hermes/images/ 目录，文件名为带时间戳的 PNG 文件。

粘贴方法

如何附加图片取决于您的终端环境。并非所有方法在所有环境下都适用——以下是完整的说明：

/paste 命令

最可靠的显式图片附加回退。

/paste

输入 /paste 并按 Enter。Hermes 检查您的剪贴板是否有图片并附加它。这是最安全的选项，当您的终端重写了 Cmd+V/Ctrl+V，或当您只复制了图片并且没有括号粘贴文本负载可供检查时。

Ctrl+V / Cmd+V

Hermes 现在将粘贴视为分层流程：

  • 先普通文本粘贴
  • 如果终端未干净地传送文本，则使用原生剪贴板 / OSC52 文本回退
  • 当剪贴板或粘贴负载解析为图片或图片路径时，自动附加图片

这意味着粘贴的 macOS 截图临时路径和 file://... 图片 URI 可以立即附加，而不是作为原始文本留在编辑器中。

:::warning 如果您的剪贴板中只有图片（没有文本），终端仍然无法直接发送二进制图片字节。请使用 /paste 作为显式图片附加回退。 :::

/terminal-setup 用于 VS Code / Cursor / Windsurf

如果您在本地 macOS 上的 VS Code 家族集成终端中运行 TUI，Hermes 可以安装推荐的 workbench.action.terminal.sendSequence 绑定，以获得更好的多行和撤销/重做体验：

/terminal-setup

当 Cmd+Enter、Cmd+Z 或 Shift+Cmd+Z 被 IDE 拦截时，这尤其有用。仅在本地机器上运行——不要在 SSH 会话内运行。

平台兼容性

环境/pasteCmd/Ctrl+V/terminal-setup说明
macOS Terminal / iTerm2✅✅n/a最佳体验——原生剪贴板 + 截图路径恢复
Apple Terminal✅✅n/a如果 Cmd+←/→/⌫ 被重写，使用 Ctrl+A / Ctrl+E / Ctrl+U 回退
Linux X11 桌面✅✅n/a需要 xclip（apt install xclip）
Linux Wayland 桌面✅✅n/a需要 wl-paste（apt install wl-clipboard）
WSL2（Windows Terminal）✅✅n/a使用 powershell.exe——无需额外安装
VS Code / Cursor / Windsurf（本地）✅✅✅推荐用于更好的 Cmd+Enter / undo / redo 体验
VS Code / Cursor / Windsurf（SSH）❌²❌²❌³改为在本地机器上运行 /terminal-setup
SSH 终端（任何）❌²❌²n/a远程剪贴板不可访问

² 参见下方的 SSH 与远程会话 ³ 该命令写入本地 IDE 快捷键绑定，不应从远程主机运行

平台特定设置

macOS

无需设置。 Hermes 使用 osascript（macOS 内置）读取剪贴板。为获得更快的性能，可选择安装 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

:::tip 如何检查您是否在使用 Wayland

echo $XDG_SESSION_TYPE
# "wayland" = Wayland, "x11" = X11, "tty" = 无显示服务器

:::

WSL2

无需额外设置。 Hermes 自动检测 WSL2（通过 /proc/version），并使用 powershell.exe 通过 .NET 的 System.Windows.Forms.Clipboard 访问 Windows 剪贴板。这是 WSL2 的 Windows 互操作内置功能——powershell.exe 默认可用。

剪贴板数据通过 stdout 作为 base64 编码的 PNG 传输，因此无需文件路径转换或临时文件。

:::info WSLg 说明 如果您在运行 WSLg（带 GUI 支持的 WSL2），Hermes 先尝试 PowerShell 路径，然后回退到 wl-paste。WSLg 的剪贴板桥仅支持 BMP 格式的图片——Hermes 使用 Pillow（如果已安装）或 ImageMagick 的 convert 命令自动将 BMP 转换为 PNG。 :::

验证 WSL2 剪贴板访问

# 1. 检查 WSL 检测
grep -i microsoft /proc/version
 
# 2. 检查 PowerShell 可访问
which powershell.exe
 
# 3. 复制一张图片，然后检查
powershell.exe -NoProfile -Command "Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.Clipboard]::ContainsImage()"
# 应打印 "True"

SSH 与远程会话

剪贴板图片粘贴在 SSH 下不能完全工作。 当您 SSH 到远程机器时，Hermes CLI 在远程主机上运行。剪贴板工具（xclip、wl-paste、powershell.exe、osascript）读取的是它们运行所在的机器的剪贴板——即远程服务器，而非您的本地机器。因此您的本地剪贴板图片无法从远程端访问。

文本有时仍可通过终端粘贴或 OSC52 桥接，但图片剪贴板访问和本地截图临时路径仍与运行 Hermes 的机器绑定。

SSH 的解决方法

  1. 上传图片文件 — 将图片保存到本地，通过 scp、VSCode 的文件资源管理器（拖放）或任何文件传输方法上传到远程服务器。然后通过路径引用它。（/attach <filepath> 命令计划在将来版本中实现。）

  2. 使用 URL — 如果图片可通过网络访问，只需在您的消息中粘贴 URL。代理可以使用 vision_analyze 直接查看任何图片 URL。

  3. X11 转发 — 使用 ssh -X 连接以转发 X11。这允许远程机器上的 xclip 访问您的本地 X11 剪贴板。需要在本地运行 X 服务器（macOS 上的 XQuartz，Linux X11 桌面内置）。大图片时较慢。

  4. 使用消息平台 — 通过 Telegram、Discord、Slack 或 WhatsApp 向 Hermes 发送图片。这些平台原生处理图片上传，不受剪贴板/终端限制影响。

为什么终端不能粘贴图片

这是一个常见的困惑来源，所以这里是技术解释：

终端是基于文本的接口。当您按 Ctrl+V（或 Cmd+V）时，终端模拟器：

  1. 读取剪贴板的文本内容
  2. 用括号粘贴转义序列包装
  3. 通过终端的文本流发送给应用程序

如果剪贴板中只有图片（没有文本），终端就没有内容可发送。没有标准的终端转义序列用于二进制图片数据。终端只是什么都不做。

这就是为什么 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 服务的开源多模态模型。

图片路由（支持视觉模型 vs 纯文本模型）

当用户附加图片时——来自 CLI 剪贴板、网关（Telegram/Discord 图片）或任何其他入口——Hermes 根据您当前模型是否实际支持视觉来路由它：

您的模型图片的处理方式
支持视觉（GPT-4V、带视觉的 Claude、Gemini、Qwen-VL、MiMo-VL 等）使用提供商的原生图片内容格式作为真实像素发送。无文本摘要层。
纯文本（DeepSeek V3、较小的开源模型、较旧的仅聊天端点）通过 vision_analyze 辅助工具路由——辅助视觉模型描述图片，文本描述被注入到对话中。

您无需配置此功能——Hermes 在提供商元数据中查找当前模型的能力并自动选择正确的路径。实际效果：您可以在会话中在视觉和非视觉模型之间切换，图片处理”即开即用”，无需更改工作流程。纯文本模型获得关于图片的连贯上下文，而不是它们必须拒绝的损坏的多模态负载。

哪个辅助模型处理文本描述路径可在 auxiliary.vision 下配置——请参阅辅助模型。

vision_analyze 具有相同的双重行为

vision_analyze 工具本身遵循相同的路由。当活跃的主模型支持视觉并且其提供商支持工具结果内的图片内容时（目前是 Anthropic、OpenAI、Azure-OpenAI 和 Gemini 3.x 技术栈），vision_analyze 会短路辅助描述器并返回原始图片像素作为多模态工具结果信封。主模型在其下一轮中原生看到图片——无需辅助调用、无文本摘要信息损失、无额外延迟。

对于纯文本主模型（或其工具结果通道不支持图片的提供商），vision_analyze 回退到传统路径：它要求配置的辅助视觉模型描述图片并以纯文本形式返回描述。无论哪种方式，调用工具签名都是相同的——工具在运行时根据活跃模型决定走哪条路径。

关系图谱

反向链接