# @runminton/pi-powershell-tool

<a href="https://www.npmjs.com/package/@runminton/pi-powershell-tool">
  <img src="https://img.shields.io/npm/dm/@runminton/pi-powershell-tool" alt="npm monthly downloads" />
</a>
<a href="https://www.npmjs.com/package/@runminton/pi-powershell-tool">
  <img src="https://img.shields.io/npm/dt/@runminton/pi-powershell-tool" alt="npm total downloads" />
</a>

最小版 Pi PowerShell extension。

## 文件
- `index.ts` — 注册一个 `powershell` 工具
- `package.json` — 运行时依赖和 pi package 入口
- `docs/pi-tui-rendering-playbook.md` — PI TUI 插件渲染排障与实现经验

## 功能
- 仅使用 PowerShell 7+ 的 `pwsh`（会在结果里报告实际 PowerShell 版本）
- 不 fallback 到 Windows PowerShell 5.1；找不到 `pwsh` 或版本低于 7 会明确失败
- 支持 `cwd`
- 支持 `timeoutMs`，超时会尝试终止进程树
- 支持 pi abort signal（例如 Esc 取消）
- 使用 `-EncodedCommand` 传递命令，并设置 UTF-8 输出编码
- 超长命令自动落到临时 `.ps1` 执行，避免 Windows 命令行长度限制
- 使用流式 UTF-8 解码，避免中文/emoji 跨 chunk 乱码
- 输出保留尾部并截断；默认 stdout 最多返回 500 行或 20KB，stderr 最多 120 行或 8KB；截断时完整输出保存到临时文件
- PI TUI 中长命令和输出支持使用 `Ctrl+O` 展开/收起
- 长命令运行时会推送 `Running PowerShell... Ns` 进度

## Install

```bash
pi install npm:@runminton/pi-powershell-tool
```

Restart Pi or start a new session after installation. The extension adds a `powershell` tool for Windows PowerShell 7+ sessions.

## 临时测试
```bash
pi -e ./index.ts
```

## 单元测试
```bash
npm install
npm test
```

## 长期使用
把这个目录接到 pi 的 extensions/package 配置里，或者复制到：
- `~/.pi/agent/extensions/`
- `.pi/extensions/`