# Pi Image Paste

[![npm](https://img.shields.io/npm/v/@leokon3/pi-image-paste?style=flat-square)](https://www.npmjs.com/package/@leokon3/pi-image-paste)

[English](README.md) | **简体中文**

一个 pi 扩展，提供 `/image-paste` 命令，让 pi 运行在 WSL 或虚拟机中时也能把图片交给模型。

## 开发背景

pi 运行在 WSL 或虚拟机里时，剪贴板和截图都在 Windows 宿主机上，而 pi 跑在 Linux 一侧。pi 内置的图片粘贴（Ctrl+V）和拖拽只能到达终端，进不到虚拟机的文件系统，所以没办法直接把图片粘贴进会话。每次都手动通过 `/mnt/c` 或共享目录复制文件，既慢又打断思路。

这个扩展把两侧连了起来：调用原生 Windows 文件对话框，把你选中的图片复制到虚拟机内部的私有临时目录，再把这些路径插入 pi 编辑器。之后模型就能像读取任何普通文件一样，用 `read` 工具查看它们。

## 安装

```bash
pi install npm:@leokon3/pi-image-paste
```

然后重启 pi，或在已有会话中执行 `/reload`。

## 使用

1. 在 pi 交互会话中执行 `/image-paste`。
2. 在 Windows 文件对话框中选择一张或多张图片。
3. 选中的图片会被复制到私有临时目录，路径插入编辑器。
4. 按需补充说明，然后回车。模型会用 `read` 工具查看这些图片。

也可以直接把说明写在命令后面，它会在对话框打开前先填入编辑器：

```text
/image-paste 对比这两张截图，告诉我有什么变化
```

取消对话框则不会向编辑器添加任何内容。如果当前模型不支持图片，pi 会给出提示。

## 行为与限制

- 支持 PNG、JPEG、WebP、GIF、BMP，单张最大 20 MiB。
- 每次最多 10 张图片；对话框 5 分钟后超时。
- 通过文件内容嗅探校验，而不是只看扩展名。
- 副本所在目录权限为 `0700`，每个文件为 `0600`，因此后续的 `read` 调用、排队消息和会话恢复都能继续读取。
- 校验失败或取消选择时会清理干净，不留临时文件。
- 需要交互式 TUI 模式，且同一时间只能打开一个对话框。
- 不会改动 pi 已有的 `/paste` 文本粘贴扩展。

## 环境要求

- 启用了 WSL interop 的 WSL 2，或在其中运行 pi 的 Windows 虚拟机
- `PATH` 中可用的 Windows PowerShell（`powershell.exe`）
- 能显示 Windows Forms 对话框的 Windows 桌面会话

原生 Windows 上的 pi 同样可用，并会跳过路径转换步骤。不支持 WSL 之外的 Linux 和 macOS。

## 本地开发

```bash
git clone https://github.com/LeoKon3/pi-image-paste.git
cd pi-image-paste
pi -e ./index.ts    # 加载本地代码
npm test            # 运行测试
```

## 许可证

[MIT](LICENSE) © leokon3