# pi-power-paste

[English](./README.md) | 中文

为 [pi](https://github.com/earendil-works/pi) 带来 OpenCode 级别的 Windows 剪贴板粘贴体验。

| 剪贴板内容 | 粘贴效果 |
|---|---|
| 图片(截图、复制的图片) | `[#image 1]` 占位符 + 真正的图片附件随消息发给模型 |
| 资源管理器里 Ctrl+C 复制的文件 | 图片文件 → `[#image N]` 附件;文本文件 → `[paste #N +X lines]` 折叠块(提交时自动展开全文);二进制/文件夹 → 纯路径 |
| 大段文本(超过 3 行或 1000 字符) | 折叠成 `[paste #N +X lines]` 标记,提交时展开 |
| 小段文本 | 原样插入 |

两个让它"感觉原生"的额外特性:

- **常驻 PowerShell 剪贴板助手**——pi 原版每读一次剪贴板图片就冷启动一个 PowerShell(约 500ms);power-paste 常驻一个进程,探测仅需 **5~10ms**。
- **真正能用的 Ctrl+V**——通过 pi 的 Kitty 协议感知快捷键层注册(见下文 [Windows Terminal 设置](#windows-terminal-ctrlv-设置))。`Alt+V`(pi 默认贴图键)开箱即用,无需任何配置。

基于 [pi-paster](https://github.com/beowulf11/pi-paster)(MIT)构建——它作为库被内嵌(占位符存储、编辑器、图片优化、预览组件),其自身的扩展不会被加载。

## 安装

```bash
pi install npm:pi-power-paste
```

不安装直接试用:

```bash
pi -e npm:pi-power-paste
```

## Windows Terminal Ctrl+V 设置

Windows Terminal 默认把 **Ctrl+V 绑定成它自己的"粘贴文本"动作**,按键根本到不了 pi(以及任何 TUI 程序)。症状:Ctrl+V 贴图无反应;Win+V → Enter 也无效。修复方法——在 WT 的 `settings.json` 中解绑:

```json
"actions": [
    { "command": "unbound", "keys": "ctrl+v" }
]
```

WT 会热加载配置,无需重启。PowerShell 自带的 PSReadLine 仍可用 Ctrl+V 粘贴,右键粘贴也不受影响,代价很小。

注意事项:

- **稳定版和 Preview 版 WT 的配置文件是分开的**,改你实际在用的那个(`%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal[Preview]_8wekyb3d8bbwe\LocalState\settings.json`)。
- **VS Code 内置终端**同样会拦截 Ctrl+V,如需在那里使用,请解绑 `workbench.action.terminal.paste`(`terminalFocus` 条件下)。
- 不做以上任何配置也没关系,`Alt+V` 永远可用,功能完全一致。

## 命令

- `/power-paste` —— 现场自检:探测一次剪贴板,报告助手模式(`persistent helper` 常驻 / `one-shot fallback` 一次性)、耗时、剪贴板内容类型和待发送附件数。

## 实现原理

- 首次粘贴时惰性拉起一个 PowerShell 进程(`-STA -NoExit`);每次探测通过 stdin 发送单行脚本,以哨兵符分隔响应(WinForms 剪贴板 API:`GetFileDropList` → 文件列表,`GetImage` → PNG 字节,`GetText` → 文本)。进程挂掉或超时会自动降级为一次性 `spawnSync` 探测——粘贴功能永不中断。
- 图片变成 `[#image N]` 占位符并携带真实附件(发送前自动优化尺寸/体积);文本和文件内容复用 pi 原生的 `[paste #N]` 折叠机制——可整块删除,提交时自动展开。
- Ctrl+V 通过 `pi.registerShortcut` 匹配——当 Kitty 键盘协议激活时(Windows Terminal 1.22+),Ctrl+V 以 CSI-u 转义序列形式到达,**不是** `\x16` 字节。匹配原始字节是个坑,别踩。

## 运行要求

- 完整功能需要 Windows;macOS/Linux 下自动降级为 pi-paster 原有的剪贴板贴图行为。
- Windows Terminal 用户:完成上述 Ctrl+V 解绑(或直接使用 Alt+V)。

## 致谢

- [pi-paster](https://github.com/beowulf11/pi-paster)(作者 beowulf11,MIT)——附件存储、编辑器基类、图片处理管线。以库形式内嵌,协议文本见 [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)。
- 使用 [pi](https://github.com/earendil-works/pi) 构建。

## 许可证

MIT