zh CN Attachments

附件与文件预览

English · 指南首页

准备发送文件

在打开的聊天中输入 :attach /绝对路径。多文件使用当前平台的参数引号规则， 也支持本机 file: URL。路径直接复用 Yazi 的解析器，不执行 shell、不展开变量。 普通文字直接进入输入框。以图片扩展名结尾的粘贴路径会在后台检查，只有所有路径 都能读取图片头时才加入草稿；支持引号、空格和本机文件 URL。设 attachments.auto_attach_images = false 可将图片路径也保留为文字。

文件在后台加入发起操作的聊天草稿，此时不会上传。输入框显示附件数量。 用 :attachments 或在输入框按 Ctrl-O 查看文件名、大小和发送格式，点击行或用 j/k 选择。

附件列表中的按键	行为
a	打开 :attach，继续添加
p	支持的图片在 Telegram 照片与原始文件之间切换
d / Delete	移除所选引用；准备期间则取消准备
o / Enter	预览支持的图片，Esc 返回列表
O	在系统文件管理器中定位原件
i	回到说明文字输入框
Esc	返回之前的视图，保留草稿

在输入框内按 Enter 才会发送，第一份文件携带输入框中的说明文字和回复对象。 每个草稿最多八份文件、共 2 GiB。上传与下载共享最多 32 个任务的队列，同时执行三个。 同一聊天的文件按入队顺序上传。当前版本逐条发送文件，相册组合会在后续版本加入。

文件引用、格式选择和内容摘要随本地草稿保存，正常重启后恢复。 移除附件不会删除原文件。上传前会一边生成私有临时副本，一边检查内容摘要； 原文件缺失或发生变化时，会在上传前报错。更改过的文件需要重新添加、重新检查。 传输结束或取消后自动删除上传副本。在准备期间切换聊天，结果仍加入最初的聊天草稿。

如需把其他类型的粘贴文件路径也自动加入草稿，在 Lua 中启用：

attachments = { auto_attach_paths = true },

此选项也不会自动发送；无法识别的内容仍作为文字。列表使用 attachments 按键上下文， 动作包括 attach、attachments、remove_attachment、attachment_format、preview、reveal。

剪贴板粘贴

在会话或输入框使用 :paste、Ctrl-V、Alt-V 或 Ctrl-Alt-V。终端转发 Cmd-V 时也能 直接处理，Lua 按键写法为 <D-v>。附件列表同样支持这些快捷键，? 查看实际绑定。 本机快捷键优先读取系统剪贴板：先取可读取的文件，再取图片数据，最后取文字。 文件列表无法读取时会尝试其图片表示。位图保存为 PNG 草稿文件。 这些操作不会发送；仍需回到输入框主动发送。Lua 动作为 paste_clipboard。

attachments = {
  auto_attach_paths = false,
  auto_attach_images = true,
  clipboard_as_photo = true,
  terminal_clipboard = true,
},

设 clipboard_as_photo = false 可让剪贴板图片默认作为原文件发送，列表中的 p 仍可逐项切换。系统返回的位图最多接受 128 MiB RGBA，PNG 文件上限 16 MiB，文字上限 1 MiB。 准备过程十秒超时；如果底层系统调用尚未结束，新的读取会被拒绝，不会叠加阻塞线程。 过期结果会丢弃，未加入草稿的截图文件会清理。

未发送截图保存在用户状态数据库旁的 <状态文件名>.attachments/<Telegram 账号 ID>/， 不参与下载缓存淘汰。正常重启保留有引用的草稿；移除或成功发送后，在最后一个使用者释放时 删除临时原件，失败则保留重试文件。启动时只清理当前账号的孤立截图，同时保护已保存的草稿 和还在等待后台写入的进程内草稿。

环境	剪贴板后端
macOS / Windows	arboard 原生文件列表、图片、文字
Linux X11 / XWayland	arboard X11 后端
Linux Wayland	合成器支持时使用 data-control，否则尝试 X11
WSL	原生优先，失败后使用 Windows PowerShell 和 wslpath，子进程有输出限制与四秒超时
SSH / 无桌面剪贴板	检测到 OSC 5522 时可由终端提供图片和文字；否则用 :attach 添加当前主机可读取的文件

macOS 上 Ghostty 1.3.1 的默认 Cmd-V 在剪贴板没有文字或路径时会转发按键， Termgram 随后读取系统剪贴板。Finder 复制的文件以转义路径传入，由图片路径识别处理。 行为依据：Ghostty 剪贴板回调 和路径转换。 其他终端或自定义绑定可能吞掉 Cmd-V 且不发送事件，此时使用 Ctrl-V、Alt-V 或 :paste。 各平台能力取决于桌面会话及其权限；不会为此新增终端输入读取器。

终端 MIME 粘贴

SSH 环境中，检测到 OSC 5522 支持时，:paste 和剪贴板快捷键请求终端所在主机 的剪贴板；本机快捷键优先读系统剪贴板。两种环境都可接收终端主动传入的 MIME 粘贴事件。 设置 attachments.terminal_clipboard = false 可关闭 MIME 协商，保留原生读取和普通文字粘贴。

类型优先级为文件列表、PNG/JPEG/WebP/GIF、UTF-8 纯文本。图片保留原始编码字节， 作为草稿拥有的文件保存，不统一转为 PNG；GIF 以原文件发送。图片编码上限 16 MiB， 单边最多 8192 像素，解码体积上限 128 MiB；文字与文件列表上限 1 MiB。

同时最多等待一次读取，每个请求阶段十秒超时。超时、权限拒绝、终端忙碌或内容不支持 会在底栏提示，不会悄悄改读另一处剪贴板。切换聊天仍写入发起时的草稿；取消或切换账号 后丢弃迟到结果。搜索、过滤、命令和登录输入只接受纯文本，输入目标改变时取消粘贴。

通过 SSH 时，终端可以传递图片字节和文字。文件 URL 仍指向终端所在主机的路径， 不能证明远端有同一份文件，所以此时拒绝文件列表；已在远端的文件用 :attach 添加。 OSC 5522 需要终端与复用器的整条链路支持，未实测所有 SSH/tmux 组合。 协商、数据解析和退出恢复仍由唯一的 Yazi 输入解析器和 TTY 所有者负责。

收到的文件

用 j/k 选择附件消息，或点击它，再按大写 O（Shift-O），即可在系统文件管理器 中显示文件。这里是单次按键，不依赖长按计时；终端上报的重复按键事件会被忽略。 同一附件下载期间重复操作不会启动额外下载。

已有原尺寸图片预览或下载文件时直接复用，否则先下载原始附件，再自动显示。 动态贴纸的缩略图只用于预览，O 下载其原始文件。缓存文件已被删除时会重新下载。 失败原因显示在状态区，可再次操作重试。

macOS 在 Finder 中选中文件，Windows 在资源管理器中选中文件；Linux 用 xdg-open 打开所在目录，能否选中文件取决于文件管理器。不会执行附件本身。即使设置中 Enter 下载行为选择 Keep in cache，O 仍表示明确的“显示文件”操作。

单击媒体只选择并显示可用按键。o 在终端展开图片或贴纸，Esc 关闭大图，i 回复， O 定位原始文件。选择不会直接激活链接、机器人按钮或文件管理器操作。 g n / g p 切换可操作项，Enter 激活。Lua 动作为 preview、next_action、 previous_action 和 reveal；大图使用 preview 上下文。

使用 Telegram 媒体 ID 和请求编号校验结果，避免旧下载覆盖已编辑或已删除的附件。 文件映射随消息缓存保存，重启后可复用。完成的文件位于 <会话文件名>.media/<Telegram 账号 ID>/。每个目录最多保留 512 个已完成文件， 目标体积上限为 1 GiB，超过后清理较旧文件。刚下载的文件即使单独超过体积上限也会 保留，之后的清理仍可能移除它。需要长期保存的文件应复制到缓存目录之外。

下载中的文件复用维护中的 tempfile 库，与已完成文件分开。取消下载会清理临时 文件，进程中断遗留的文件会在下一次开始传输前清理。同一账号缓存只允许一个进程 持有，未结束的媒体任务会保留锁直到清理完成，避免两个客户端同时推进同一缓存的 同步进度。

照片、图片文档和贴纸在消息流内预览，只请求可见预览，应用最多同时等待两个预览下载， 全部网络传输共享有界工作任务。动态 TGS/WebM 贴纸显示 Telegram 的栅格缩略图并标注为 静态预览；失败预览选中后可按 o 或 Enter 重试。Ctrl-L 重绘，协议说明见终端。 本地文件使用 :attach 加入草稿，检查后再发送。

---

Documentation source / 文档来源