pi-image-placeholder

为 pi --tui-mode fullscreen 提供图片占位符。粘贴或拖入图片后，编辑器中显示紧凑的 [Image #N]；发送时附加真正的图片数据，模型无需调用 read 即可查看图片。

本扩展独立运行，不修改 pi 安装包或全局原型。

最近更新

v0.3.0 · 2026-09-29

• feat：发送后的图片仅显示 [Image #N]，隐藏冗长的临时路径，让聊天记录更清爽。
• 恢复历史会话后同样生效，模型接收的图片和会话原始数据保持不变。

使用

安装后，在 pi 中执行 /reload，再用 /image-placeholder-status 检查是否启用。

然后在 /settings 中 Block images为false，并选择支持图片的模型。扩展不会绕过图片屏蔽设置。全局设置对应 images.blockImages: false。但需要注意：您所使用的模型需要本身就支持图片识别，本插件只是提供一个编辑器的占位符。

• 按 Ctrl+V 粘贴剪贴板图片；剪贴板没有图片时，仍可粘贴普通文字。
• 从 Finder 拖入本地图片，可一次拖入多张。支持 PNG、JPEG、GIF、WebP，以及带空格、中文、引号/反斜杠转义的路径和本地 file:// URL。
• 导入后，图片显示为 [Image #N]，提交时，图片作为附件发送。发送后的聊天记录也只显示 [Image #N]，不再显示插件生成的快照路径。

单张图片上限为 20 MiB，一次导入或单条消息的图片总量上限为 50 MiB。超限会报错，不会静默省略图片。模型和服务商自身的图片限制仍然适用。

优化交互

• 左右键跨过整个占位符，Backspace/Delete 可将图片"整块"删除（就是把占位符[Image #N]整个删掉，不会留下文件路径）。
• 原生支持撤销可恢复图片对象，Ctrl+W/Ctrl+Y 的内部剪切/粘回保留图片绑定。
• 支持快捷键 ↑ 跳转到历史编辑、排队消息后，保留上一次的图片，且无需重新再导入。即使原图后来被覆盖、移动或删除，也不影响已导入的图片。
• 粘贴或拖入时保存图片快照。原图后来被覆盖、移动或删除，不影响已导入的图片。
• 提交前均验证图片。快照缺失、被改动、开启 Block images 或模型不支持图片时，会阻止提交并保留草稿。

中断对话情况

图片发送后，图片数据会保留在用户消息历史中。若中断当前对话不会删除已发送的图片，在同一会话中继续追问时，无需重新粘贴或手动发送图片。

此说明以图片消息仍在当前上下文中为前提。如果历史上下文被压缩后，模型会选择性的保留原图，这是模型自身的抉择，不是此插件的问题，此插件不保证模型仍能读取原图。

图片保存与隐私

粘贴的图片会写入本地临时目录，正常退出时清理。已发送图片会随 pi 会话记录保存，不会因清理临时快照而删除。

• 拖入的图片也会保存为临时快照。快照目录权限为 0700，文件权限为 0600。
• 删除占位符不会立即删除快照，以便撤销和历史编辑使用。
• 正常退出只清理本进程自己的快照，绝不删除原图。强制退出或系统崩溃可能留下临时目录；扩展不会自动删除其他进程或未知来源的文件。
• /reload 所需的编辑状态仅保留在进程内，扩展不把未发送截图写入会话 JSONL。未发送草稿和通过旧占位符重新发送图片，不保证跨重启恢复。

兼容性

需要 pi 0.85.0 或更新版本，使用 registerMarkdownTransformer 处理聊天区显示。

适配原生编辑区实例的分段、光标边界、提交展开、粘贴及历史；保留原生布局、撤销、kill ring 和快捷键。

扩展通过 getEditorComponent / setEditorComponent 包装已有工厂，在 resources_discover（所有 session_start 之后）接入。支持原生 CustomEditor、pi-zentui PolishedEditor 及其已验证的 base 包装结构。未知编辑器结构会报错停用，不偷偷改用可拆分文字。其他插件若在运行中强行替换整个编辑器，需要重新 /reload 并确认状态。

目前不保证浏览器直接拖图、远程 SSH、其他系统/版本或将无括号拖入路径逐字节拆分传输的终端。

实现说明

提交时，扩展将图片对象展开为 [Image #N] "快照路径"，在 input 钩子里附加标准 { type: "image", data, mimeType } 内容，再交由 pi 原有模型请求流程发送。普通路径文字本身不会自动变成图片附件。

聊天区通过 Markdown 显示转换，将符合插件快照格式的 [Image #N] "快照路径" 显示为 [Image #N]；普通路径和助手回复不变。此转换不依赖进程内记录或快照文件，重新打开会话后仍然生效。模型输入和会话保存内容保持原样，仍包含完整路径和图片附件；隐藏路径仅是显示优化，不是隐私脱敏，也不延长临时文件的生命周期。

扩展按原始字节生成图片附件，不自行缩放；后续处理由 pi 和模型决定。

手动输入普通的 [Image #N] 不会附加图片。

安装

从 GitHub 直接安装：

pi install git:github.com/Jul1en-Lin/pi-image-placeholder

发布到 npm 后，也可通过 npm 安装：

pi install npm:pi-image-placeholder

本地开发安装：

cd ~/prj/pi-image-placeholder
npm ci --ignore-scripts
pi install "$PWD"

安装后，在 pi 中执行 /reload，再用 /image-placeholder-status 检查是否启用。

卸载

本地开发安装对应的卸载命令：

pi remove ~/prj/pi-image-placeholder

卸载后执行 /reload 或重启 pi。