{"_id":"@cqh6666/pi-image","_rev":"3-e1d40969dad02c9716f8921fd6bdc979","name":"@cqh6666/pi-image","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@cqh6666/pi-image","version":"1.0.0","keywords":["pi-package","image","gallery","quicklook","multimodal","vision"],"author":{"name":"cqh6666"},"license":"MIT","_id":"@cqh6666/pi-image@1.0.0","maintainers":[{"name":"cqh6666","email":"2018ch@m.scnu.edu.cn"}],"homepage":"https://github.com/cqh6666/pi-image#readme","bugs":{"url":"https://github.com/cqh6666/pi-image/issues"},"pi":{"image":"https://raw.githubusercontent.com/cqh6666/pi-image/main/assets/preview.png","extensions":["./src/index.ts"]},"dist":{"shasum":"49cbeba73ee91f4eeef43e94a8c58f429515289b","tarball":"https://registry.npmjs.org/@cqh6666/pi-image/-/pi-image-1.0.0.tgz","fileCount":7,"integrity":"sha512-EagJcowPnK4WDy2Rsa6WOSBSBsRHyFiY6EtJwE55tKWfuMHo0XgJ/dJHv9LoTr9ifn2y16EL6b/UxWONZ+q4aQ==","signatures":[{"sig":"MEYCIQDovfHXrNZOvPh+V5EJD8UU7kpQ5BrNvFHDl9urchDowQIhAL8SLd4o+rCyoKxlXlvw8UFywMnzvq2ViiS00oJU4E6h","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":129243},"main":"src/index.ts","type":"module","gitHead":"d99171ba6d3c81f01c19cb95a1012c1458ec8468","_npmUser":{"name":"cqh6666","email":"2018ch@m.scnu.edu.cn"},"repository":{"url":"git+https://github.com/cqh6666/pi-image.git","type":"git"},"_npmVersion":"11.19.0","description":"Image gallery, remote URL caching, multimodal delivery, and macOS Quick Look for Pi","directories":{},"_nodeVersion":"26.7.0","_hasShrinkwrap":false,"peerDependencies":{"@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-image_1.0.0_1788441692912_0.44989264906236337","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@cqh6666/pi-image","version":"1.0.1","keywords":["pi-package","image","gallery","quicklook","multimodal","vision"],"author":{"name":"cqh6666"},"license":"MIT","_id":"@cqh6666/pi-image@1.0.1","maintainers":[{"name":"cqh6666","email":"2018ch@m.scnu.edu.cn"}],"homepage":"https://github.com/cqh6666/pi-image#readme","bugs":{"url":"https://github.com/cqh6666/pi-image/issues"},"pi":{"image":"https://raw.githubusercontent.com/cqh6666/pi-image/main/assets/preview.png","extensions":["./src/index.ts"]},"dist":{"shasum":"993c29427870e75be65f57e1d6d750a97d85bf8a","tarball":"https://registry.npmjs.org/@cqh6666/pi-image/-/pi-image-1.0.1.tgz","fileCount":7,"integrity":"sha512-zSPE7yTVjlv1jQ/Lf3rfl17uRxd2BZLkRvVnDgBHRO924tl0Jum/rbGZOfNMoNEjIbbs8wmB2gbkwAArHhWTNg==","signatures":[{"sig":"MEUCIGf5y5G0WgReEKTDbI+Vf3u/wT/zosFzH6myjdhSLpn+AiEAlqSOsyfn6oNcVxGsjr3cX0d6/a0yFUNQNYJYJjuYO8U=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIB2m/wDKhI9/E5sqFllAbjnKvKp8fZ8fmLfkMywd2SwAAiBgYds2I6w4kUQXDhFpdGtec4N7Picr6AeeWCaRUWOiWg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":130455},"main":"src/index.ts","type":"module","gitHead":"5f1859fbf97cf60eb06e2506eafd4258cf6bfa69","_npmUser":{"name":"cqh6666","email":"2018ch@m.scnu.edu.cn"},"repository":{"url":"git+https://github.com/cqh6666/pi-image.git","type":"git"},"_npmVersion":"11.19.0","description":"Image gallery, remote URL caching, multimodal delivery, and macOS Quick Look for Pi","directories":{},"_nodeVersion":"26.7.0","_hasShrinkwrap":false,"peerDependencies":{"@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-image_1.0.1_1788770954739_0.22146768476661305","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"pi":{"image":"https://raw.githubusercontent.com/cqh6666/pi-image/main/assets/preview.png","extensions":["./src/index.ts"]},"_id":"@cqh6666/pi-image@1.0.2","bugs":{"url":"https://github.com/cqh6666/pi-image/issues"},"dist":{"shasum":"0760ccb5b2f9d29cabeb91fd66b048d34fe3988f","tarball":"https://registry.npmjs.org/@cqh6666/pi-image/-/pi-image-1.0.2.tgz","fileCount":17,"integrity":"sha512-Rl3MhaMi5bJdXrA/dHrvyRYtbpFXTaOr5TQXymXyzlII2cO7/vkbAwU7LON+NZ2h2w7vg4yGiL4xLo+blqvMVg==","signatures":[{"sig":"MEUCIAOlu4eTHSy5iaDLBheUM51rRqVUdIjjjwe/gKHbx5BmAiEA3Olr57mRcYk3AdxKWqFd/bX//doPS54D8grABnVJujo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGIu4iOdFfq5KFXT5FVJpiVhF+A8wEtV66TR6bMEWUJdAiBABrL3DIiWiFeEzOCzFi8wVnNDhJdM++xR3G/xPYO1bA=="}],"unpackedSize":160668},"main":"src/index.ts","name":"@cqh6666/pi-image","type":"module","author":{"name":"cqh6666"},"gitHead":"71f1ec728ae2eb77535e870cb52249d364a80c52","license":"MIT","scripts":{"test":"node --experimental-strip-types --test test/*.test.ts","check":"tsc --noEmit"},"version":"1.0.2","_npmUser":{"name":"cqh6666","email":"2018ch@m.scnu.edu.cn"},"homepage":"https://github.com/cqh6666/pi-image#readme","keywords":["pi-package","image","gallery","quicklook","multimodal","vision"],"repository":{"url":"git+https://github.com/cqh6666/pi-image.git","type":"git"},"_npmVersion":"11.19.0","description":"Image gallery, remote URL caching, multimodal delivery, and macOS Quick Look for Pi","directories":{},"maintainers":[{"name":"cqh6666","email":"2018ch@m.scnu.edu.cn"}],"_nodeVersion":"26.7.0","_hasShrinkwrap":false,"devDependencies":{"typescript":"5.9.3","@types/node":"22.19.19"},"peerDependencies":{"@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-image_1.0.2_1788946171134_0.9623983832060923"}}},"time":{"created":"2026-09-03T13:21:32.665Z","modified":"2026-09-09T09:29:31.444Z","1.0.0":"2026-09-03T13:21:33.058Z","1.0.1":"2026-09-07T08:49:14.834Z","1.0.2":"2026-09-09T09:29:31.270Z"},"bugs":{"url":"https://github.com/cqh6666/pi-image/issues"},"author":{"name":"cqh6666"},"license":"MIT","homepage":"https://github.com/cqh6666/pi-image#readme","keywords":["pi-package","image","gallery","quicklook","multimodal","vision"],"repository":{"url":"git+https://github.com/cqh6666/pi-image.git","type":"git"},"description":"Image gallery, remote URL caching, multimodal delivery, and macOS Quick Look for Pi","maintainers":[{"name":"cqh6666","email":"2018ch@m.scnu.edu.cn"}],"readme":"# pi-image\n\n[English](README.md) | [简体中文](README.zh-CN.md)\n\n[![npm version](https://img.shields.io/npm/v/@cqh6666/pi-image.svg)](https://www.npmjs.com/package/@cqh6666/pi-image)\n[![license](https://img.shields.io/github/license/cqh6666/pi-image.svg)](LICENSE)\n\n> 专为 [Pi](https://pi.dev) 打造的交互式图片画廊、多模态直传、远程 URL 自动拉取、Token 消耗估算与 macOS Quick Look 快速预览插件。\n\n`pi-image` 全面优化了在终端中使用 Pi 时的视觉交互体验。它可以自动捕获剪贴板截图、本地文件路径以及远程 HTTP/HTTPS 图片链接，并将其转化为多模态附件直传给大模型；同时提供了基于终端内联图形与 macOS 原生快速预览的交互式画廊。\n\n![pi-image 终端画廊预览效果](assets/preview.png)\n\n---\n\n## 核心特性\n\n- **多模态附件直传**：自动提取本地文件、剪贴板截图或网络图片，通过 Pi 的结构化 `ImageContent` API 直接发送给视觉大模型。将提示词中的冗长文件路径替换为 `[image #1: filename]` 紧凑标签，避免模型额外调用工具读取图片。\n- **文本模型可靠降级**：如果当前模型不支持图片输入，插件会把紧凑标签恢复为原始路径或 URL，模型仍可使用工具读取图片。\n- **自定义输入框兼容**：增强其他插件已经注册的输入框，而不是覆盖它；已验证兼容 `pi-powerline-footer`。\n- **远程图片校验与缓存**：以流式方式下载网络图片，提供 8 秒超时、重定向限制、MIME/文件签名校验和单图 20 MiB 限制，校验通过后才写入本地缓存。\n- **终端交互式画廊 (`/image`)**：支持终端内联图片渲染（兼容 Kitty 协议，非兼容终端自动降级为 ASCII 占位）。支持使用 `←` / `→` 或 `N` / `P` 双向连续翻页切图。\n- **macOS 原生快速预览 (`空格` 键)**：在画廊中按 `空格` 键，毫秒级弹出 macOS 系统级原生 Quick Look 快速预览浮窗。看完随手按空格或 `Esc` 瞬时关闭，窗口焦点无缝留在终端，不打断输入心智。\n- **系统应用独立打开 (`O` 键)**：在画廊中按 `O` 键，直接在 macOS“预览 App”（或 Linux `xdg-open` / Windows 默认图片查看器）中独立打开大图，满足涂鸦标注、裁剪或缩放需求。\n- **结构化元信息栏 (Meta Bar)**：实时展示格式、分辨率、宽高比、物理大小，并根据视觉模型规范（512×512 Tile 算法）**精准估算并高亮当前图片占用的 Context Token 消耗**。\n- **严格会话隔离**：图片历史记录与当前会话 ID 强绑定。通过 `/new` 开启新会话时自动重置，避免旧会话图片干扰。\n\n---\n\n## 安装说明\n\n### 从 npm 安装（推荐）\n\n```bash\npi install npm:@cqh6666/pi-image\n```\n\n### 从 GitHub 安装\n\n```bash\npi install git:github.com/cqh6666/pi-image\n```\n\n### 本地源码安装\n\n```bash\npi install /path/to/pi-image\n```\n\n或者直接添加到全局配置文件 `~/.pi/agent/settings.json`：\n\n```json\n{\n  \"packages\": [\n    \"/path/to/pi-image\"\n  ]\n}\n```\n\n### 免安装单次试用\n\n```bash\npi -e npm:@cqh6666/pi-image\n```\n\n---\n\n## 使用指南\n\n### 1. 附加图片\n\n- **剪贴板截图**：直接按 `Ctrl+V`（或在 Mac 终端中 `Cmd+V` 粘贴路径）。\n- **网络图片**：直接粘贴 URL，如 `https://example.com/screenshot.png`。\n- **本地文件**：在提问中提及相对或绝对路径，如 `./diagram.png` 或 `~/Desktop/mockup.jpg`。路径包含空格时请加引号，例如 `\"~/Desktop/system diagram.png\"`。\n\n向支持视觉输入的模型提交时，`pi-image` 会直接附加图片，并把长路径替换为简洁的 `[image #1: filename]`。Pi 或其他扩展已经附加的图片会被保留；同一来源被重复引用时只附加一次。\n\n对于纯文本模型，或图片读取失败的情况，提示词会保留原始路径或 URL。插件会明确报告错误，不会留下模型无法解析的紧凑标签。\n\n### 附件限制\n\n- 支持格式：PNG、JPEG、WebP、GIF\n- 单张图片上限：20 MiB\n- 每条消息最多 10 张图片（包括已有附件）\n- 插件每条消息新增图片总大小上限：50 MiB\n- 远程下载超时：8 秒，最多跟随 3 次重定向\n\n### 2. 画廊控制命令\n\n| 命令 | 说明 |\n| :--- | :--- |\n| `/image` | 打开画廊并查看最新一张图片 |\n| `/image <序号>` | 打开画廊并直接跳转到第 N 张图片 (例如 `/image 2`) |\n| `/image list` | 打开交互式选择弹窗列表 |\n| `/image <路径\\|URL>` | 直接预览指定的本地文件或网络图片链接 |\n| `/image clear` | 清空当前会话所记录的图片历史 |\n| `/image help` | 显示命令用法摘要 |\n\n### 3. 画廊键盘快捷键\n\n当画廊处于打开状态时：\n\n| 按键 | 对应动作 |\n| :--- | :--- |\n| `空格` (Space) | **原生快速预览** (macOS 系统悬浮窗、Windows QuickLook 或平滑降级) |\n| `O` | **系统应用打开** (macOS Preview.app、Windows 照片或 Linux 默认查看器) |\n| `→` / `↓` / `N` / `Tab` | 切换到下一张图片 |\n| `←` / `↑` / `P` / `Shift+Tab` | 切换到上一张图片 |\n| `Esc` / `Q` | 关闭画廊并返回终端光标 |\n\n---\n\n## 开源协议\n\n[MIT](LICENSE)\n","readmeFilename":"README.zh-CN.md"}