03. 给助手上下文

图片

输入栏里的截图，往往比一段描述对话框的文字更清楚。

概念

Matcha CLI 接受图片作为输入附件：剪贴板上的图、在文件管理器里复制的文件，或从 Finder / Files / Explorer 拖入的文件。每一张都会变成 [Image #N] 片段。字节会存进该会话在 ~/.matcha/sessions/ 下的 images/ 文件夹，发送之后以及以后恢复会话时图还在。

一条输入最多 10 个图片片段。每条边至少 8 像素。能在发送和恢复后保留的格式是 JPEG、PNG 和 WebP。GIF、BMP 和 TIFF 会被拒绝。

为何重要

错误对话框、设计稿和白板照片不好转成文字。粘贴或拖入图片，写上你要做什么，然后发送。

图已经在仓库里时，@ 就够了——不必再做片段。像素在剪贴板或工作区之外时，才用图片片段。

如何加入图片

操作	macOS	Linux	Windows
从文件管理器把图片拖进输入栏	Finder	Files / Dolphin	Explorer
在文件管理器里复制文件，再粘贴	`Cmd+V`	`Ctrl+V`	`Ctrl+V`
截图或「复制图像」，再粘贴	`Cmd+V`	`Ctrl+V`	`Alt+V`

Cmd+V / Ctrl+V 同样可用（Super+V 是同一类）。在 Windows 上，Windows Terminal 默认的 Ctrl+V 只粘贴文字，会悄悄丢掉截图剪贴板。Alt+V 是 Matcha CLI 用来拿到图片的快捷键。若要让 Ctrl+V 也能粘贴图片，把下面加进 Windows Terminal settings.json 的 actions：

{ "command": null, "keys": "ctrl+v" }

拖入或从文件管理器复制的非图片文件，会插入绝对路径作为文字，而不是片段。

片段出现之后

片段标签是 [Image #N]。编号在这份草稿的生命周期内递增；删掉一个也不会复用空号。
在片段上按 Enter 打开预览（不会发送）。预览需要能画行内图的终端。否则会看到 Image rendering not supported in this terminal，或 Inline images disabled within tmux.
在片段旁写说明（这个 [Image #1] 有什么问题），光标离开片段后再按 Enter 发送。

无效图片会怎样

Matcha CLI 会用提示告诉你。粘贴被拒绝时不会插入任何东西。

你会看到	含义
`Image too small (W×H). Must be at least 8×8 pixels.`	任一边不足 8 px。
`Image limit reached (max 10)`	这份草稿已有十个片段。多出来的拖入会被跳过。
`Couldn't save pasted image`	会话无法把文件写到 `~/.matcha/sessions/…/images/` 下。
`Couldn't load image preview`	片段在，但预览解码失败。
`Images can't be attached when editing a shared queued prompt`	来自另一客户端的队列编辑；文字可以，图片不行。

不是真正图片的文件（截断的 PNG、随机字节，或模型会拒绝的格式）不会变成片段，或在再次加载会话时被剥掉，以免后续回合因此失败。若你以为会贴进图片、却什么都没发生，检查剪贴板里是否真是图片，以及是否用了上表里的快捷键。