All packages Compare

@cqh6666/pi-image

extensionmaintained

Image gallery, remote URL caching, multimodal delivery, and macOS Quick Look for Pi

by — · v1.0.2 · published 2w ago

$ pi install npm:@cqh6666/pi-image
downloads/mo
0
stars
0
last push
2w ago
open issues
0

Signals

license: MITtestspi manifest: missinginstall size: —deps: 0peer deps: 0

Download trend

244 downloads · last 12 weeks (weekly)

vision
npm ↗ repo ↗

README

pi-image

English | 简体中文

npm version license

专为 Pi 打造的交互式图片画廊、多模态直传、远程 URL 自动拉取、Token 消耗估算与 macOS Quick Look 快速预览插件。

pi-image 全面优化了在终端中使用 Pi 时的视觉交互体验。它可以自动捕获剪贴板截图、本地文件路径以及远程 HTTP/HTTPS 图片链接，并将其转化为多模态附件直传给大模型；同时提供了基于终端内联图形与 macOS 原生快速预览的交互式画廊。

pi-image 终端画廊预览效果

核心特性

  • 多模态附件直传：自动提取本地文件、剪贴板截图或网络图片，通过 Pi 的结构化 ImageContent API 直接发送给视觉大模型。将提示词中的冗长文件路径替换为 [image #1: filename] 紧凑标签，避免模型额外调用工具读取图片。
  • 文本模型可靠降级：如果当前模型不支持图片输入，插件会把紧凑标签恢复为原始路径或 URL，模型仍可使用工具读取图片。
  • 自定义输入框兼容：增强其他插件已经注册的输入框，而不是覆盖它；已验证兼容 pi-powerline-footer。
  • 远程图片校验与缓存：以流式方式下载网络图片，提供 8 秒超时、重定向限制、MIME/文件签名校验和单图 20 MiB 限制，校验通过后才写入本地缓存。
  • 终端交互式画廊 (/image)：支持终端内联图片渲染（兼容 Kitty 协议，非兼容终端自动降级为 ASCII 占位）。支持使用 ← / → 或 N / P 双向连续翻页切图。
  • macOS 原生快速预览 (空格 键)：在画廊中按 空格 键，毫秒级弹出 macOS 系统级原生 Quick Look 快速预览浮窗。看完随手按空格或 Esc 瞬时关闭，窗口焦点无缝留在终端，不打断输入心智。
  • 系统应用独立打开 (O 键)：在画廊中按 O 键，直接在 macOS“预览 App”（或 Linux xdg-open / Windows 默认图片查看器）中独立打开大图，满足涂鸦标注、裁剪或缩放需求。
  • 结构化元信息栏 (Meta Bar)：实时展示格式、分辨率、宽高比、物理大小，并根据视觉模型规范（512×512 Tile 算法）精准估算并高亮当前图片占用的 Context Token 消耗。
  • 严格会话隔离：图片历史记录与当前会话 ID 强绑定。通过 /new 开启新会话时自动重置，避免旧会话图片干扰。

安装说明

从 npm 安装（推荐）

pi install npm:@cqh6666/pi-image

从 GitHub 安装

pi install git:github.com/cqh6666/pi-image

本地源码安装

pi install /path/to/pi-image

或者直接添加到全局配置文件 ~/.pi/agent/settings.json：

{
  "packages": [
    "/path/to/pi-image"
  ]
}

免安装单次试用

pi -e npm:@cqh6666/pi-image

使用指南

1. 附加图片

  • 剪贴板截图：直接按 Ctrl+V（或在 Mac 终端中 Cmd+V 粘贴路径）。
  • 网络图片：直接粘贴 URL，如 https://example.com/screenshot.png。
  • 本地文件：在提问中提及相对或绝对路径，如 ./diagram.png 或 ~/Desktop/mockup.jpg。路径包含空格时请加引号，例如 "~/Desktop/system diagram.png"。

向支持视觉输入的模型提交时，pi-image 会直接附加图片，并把长路径替换为简洁的 [image #1: filename]。Pi 或其他扩展已经附加的图片会被保留；同一来源被重复引用时只附加一次。

对于纯文本模型，或图片读取失败的情况，提示词会保留原始路径或 URL。插件会明确报告错误，不会留下模型无法解析的紧凑标签。

附件限制

  • 支持格式：PNG、JPEG、WebP、GIF
  • 单张图片上限：20 MiB
  • 每条消息最多 10 张图片（包括已有附件）
  • 插件每条消息新增图片总大小上限：50 MiB
  • 远程下载超时：8 秒，最多跟随 3 次重定向

2. 画廊控制命令

命令说明
/image打开画廊并查看最新一张图片
/image <序号>打开画廊并直接跳转到第 N 张图片 (例如 /image 2)
/image list打开交互式选择弹窗列表
/image <路径|URL>直接预览指定的本地文件或网络图片链接
/image clear清空当前会话所记录的图片历史
/image help显示命令用法摘要

3. 画廊键盘快捷键

当画廊处于打开状态时：

按键对应动作
空格 (Space)原生快速预览 (macOS 系统悬浮窗、Windows QuickLook 或平滑降级)
O系统应用打开 (macOS Preview.app、Windows 照片或 Linux 默认查看器)
→ / ↓ / N / Tab切换到下一张图片
← / ↑ / P / Shift+Tab切换到上一张图片
Esc / Q关闭画廊并返回终端光标

开源协议

MIT