# pi-pwsh-notify

[![npm](https://img.shields.io/npm/v/pi-pwsh-notify)](https://www.npmjs.com/package/pi-pwsh-notify)
[![license](https://img.shields.io/npm/l/pi-pwsh-notify)](LICENSE)

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

面向 Windows 的 [pi](https://pi.dev) PowerShell 7 扩展。

```powershell
pi install npm:pi-pwsh-notify
```

## 为什么

Pi 已经有轻量的前台 `powershell` 工具。`pi-pwsh-notify` 在它和持久终端平台之间补了一层：保留前台命令的简单感，同时加上会话级后台任务、自动通知、跨调用 `cd` 和简洁的任务面板。

## 工具

| 工具 | 用途 |
| --- | --- |
| `pwsh` | 前台运行命令，或启动后台任务 |
| `pwsh_job` | 读取输出、等待、列出或终止任务 |

### `pwsh`

默认以前台方式运行。输出实时显示，`cd` 可跨调用保持，每次调用都会启动新的 PowerShell 进程。

需要后台运行时再显式开启：

```text
pwsh {
  command: "npm run dev",
  run_in_background: true,
  name: "vite",
  notify_on: "Local:.*http"
}
```

`notify_on` 是 JavaScript 正则。第一次匹配发送就绪通知，进程退出发送完成通知。

### `pwsh_job`

下一步依赖后台任务结果时，直接等待，不要轮询：

```text
pwsh_job { action: "wait", id: "bg-1", pattern: "ready|listening", timeout: 120 }
```

超时不会终止任务。

### 任务面板

活动任务显示在编辑器下方。输入框为空时，按 `Right` 或 `Tab` 聚焦，`Up`/`Down` 切换，`Enter` 打开实时输出，连续按两次 `x` 终止，`Esc` 返回编辑器。

## 选择

| | Pi `powershell` | `pi-pwsh-notify` | `@4fu/pi-pwsh` |
| --- | --- | --- | --- |
| 前台输出 | 实时 | 实时 | 任务快照 |
| 后台任务 | 不支持 | 会话级显式任务 | 所有命令都进入持久任务 |
| 就绪 / 等待 | 不支持 | 未读输出正则 | 持久任务状态 |
| 输出读取 | 当前结果 | 增量读取 + 完整日志 | 可重复快照 + 持久日志 |
| 跨 reload / 重启 | 不支持 | 不支持 | 支持 |
| 交互式 ConPTY | 不支持 | 不支持 | 支持 |
| 适合 | 简单命令 | 日常命令 + 会话级后台任务 | 持久和交互式工作负载 |

简单前台命令用 Pi 内置工具。日常仍以前台为主，但又需要后台任务、正则等待、持久 `cd` 和可预测清场时，用本扩展。任务必须跨重启，或需要交互式终端时，用 [`@4fu/pi-pwsh`](https://github.com/4fuu/pi-pwsh)。

不建议同时安装两个 PowerShell 扩展，因为它们都会注册名为 `pwsh`、但生命周期语义不同的工具。

## 要求

- Windows
- Node.js 22.19+
- PowerShell Core 7+
- Pi 0.84+

## 日志

完整日志位于系统临时目录下的 `pi-pwsh-notify-*` 目录。旧目录会在后续启动时清理。

## 开发

```powershell
npm ci
npm run check
npm pack --dry-run
```

测试会执行真实 PowerShell 进程，覆盖运行时降级、UTF-8 传输、退出码、持久 `cd`、后台通知、输出滚动、会话清理和任务界面。

## License

[MIT](LICENSE)