# pi-pwsh-notify
### agent 启动 dev server，然后接着干活。
服务一就绪，它马上知道。
面向 Windows 上 [pi](https://pi.dev) 的后台任务与自动通知，不用轮询。
[](https://www.npmjs.com/package/pi-pwsh-notify)
[](LICENSE)
[English](README.md) · **简体中文**
```powershell
pi install npm:pi-pwsh-notify
```
无需配置。下一个会话就能用上 PowerShell 7 和受管理的后台任务。
## 实际体验
```text
你 启动 dev server，跑一下测试，有问题就修
agent pwsh npm run dev → bg-1 (vite) 已启动
pwsh npm test → bg-2 (tests) 已启动
两个都在跑了，我继续写登录页。
● bg job bg-1 (vite) · ready · 2s
● bg job bg-2 (tests) · exited 1 · 41s
agent 测试失败了，我看一下输出。
pwsh_job output bg-2
auth.test.ts 期望返回 401，我来修处理函数。
```
没人需要问“跑完了吗”，任务自己会告诉 agent。
## 为什么需要它
dev server 永远不会退出，普通的 shell 调用也就永远不返回，agent 的回合只能卡在那里。耗时长的测试同样会占住它，反复查询状态又白白消耗 token。
| | 普通 shell 工具 | pi-pwsh-notify |
| --- | --- | --- |
| `npm run dev` | 卡住回合，直到被杀掉 | 在后台运行，agent 继续工作 |
| “服务起来了吗？” | 反复轮询 | 输出首次匹配时收到通知 |
| 要跑 10 分钟的测试 | 干等，或不停查询 | 退出时收到通知，附状态和运行时长 |
| `cd` 到某个目录 | 下次调用就忘了 | 一直保持 |
## 特性
- 🔔 **自动通知。** 任务结束时唤醒空闲的 agent，或在下一次模型调用前插入正在进行的回合。
- ⚡ **知道服务何时就绪。** `notify_on: "Local:.*http"` 在首次匹配时触发，专治永不退出的进程。
- ⏳ **该等的时候才等。** `pwsh_job wait` 可以等正则匹配、进程退出或超时，不用写循环。
- 📍 **`cd` 不会丢。** 工作目录跨调用保持。
- 📺 **实时任务面板。** 在编辑器下方浏览任务、查看实时输出，按两下键就能终止。
- 🧹 **不留孤儿进程。** 退出、重载、切换会话、关闭终端时，都会清理任务及其进程树。
- 📜 **完整日志。** 每个后台任务都保留完整日志，输出再多也不会塞满上下文。
- 🌏 **全程 UTF-8。** 中文、日本語和 emoji 都不会乱码。
- 🔒 **输出按需读取。** 通知只带状态，进程没法靠打印内容影响你的 agent。
- 🪶 **零依赖。** 除了扩展本身，什么都不用装。
## 使用
直接说你想做什么，agent 会自己调用这两个工具：
| 工具 | 用途 |
| --- | --- |
| `pwsh` | 前台运行命令，或启动后台任务 |
| `pwsh_job` | 读取输出、等待、列出或终止任务 |
```text
pwsh { command: "npm run dev", run_in_background: true, name: "vite", notify_on: "Local:.*http" }
pwsh_job { action: "wait", id: "bg-1", pattern: "ready|listening", timeout: 120 }
```
**任务面板：** 输入框为空时，按 `→` 或 `Tab` 聚焦，`↑` `↓` 切换，`Enter` 查看实时输出，连按两次 `x` 终止，`Esc` 返回。
## 对比
| | Pi `powershell` | **pi-pwsh-notify** | `@4fu/pi-pwsh` |
| --- | --- | --- | --- |
| 前台输出 | 实时 | **实时** | 任务快照 |
| 后台任务 | 不支持 | **会话级任务** | 所有命令都是持久任务 |
| 自动通知 | 不支持 | **支持** | 支持（仅 TUI） |
| TUI 之外的后台任务 | 不支持 | **支持** | 不支持 |
| 就绪检测 | 不支持 | **正则** | 固定文本 |
| 跨重载和重启 | 不支持 | 不支持 | 支持 |
| 交互式终端（ConPTY） | 不支持 | 不支持 | 支持 |
| 额外依赖 | 无，内置 | **无** | 有 |
简单的前台命令用 Pi 内置工具。日常以前台为主、又需要受管理的后台任务时，用本扩展。需要长期运行或交互式的工作负载时，用 [`@4fu/pi-pwsh`](https://github.com/4fuu/pi-pwsh)。
不建议同时安装两个 PowerShell 扩展，它们都会注册名为 `pwsh` 的工具，但生命周期语义不同。
## 常见问题
它会替换 bash 吗？
只要有 PowerShell 7 就会，`!` 和 `!!` 命令也会走 PowerShell。没有的话，扩展会自动让路，Pi 内置的 bash 继续可用。
通知为什么不带输出？
结果重要时，agent 会用 `pwsh_job` 读取输出。这样既省 token，也能让密钥和不可信文本在真正需要之前不进入对话。
日志在哪里？
在系统临时目录下的 `pi-pwsh-notify-*` 文件夹里，旧文件夹会在之后启动时清理。
能指定使用哪个 PowerShell 吗？
把 `PI_PWSH_NOTIFY_EXECUTABLE` 设为 `pwsh.exe` 的绝对路径即可。
任务能跨重启保留吗？
不能，任务属于当前会话。需要长期保留的话，请用 `@4fu/pi-pwsh`。
## 要求
Windows · Node.js 22.19+ · PowerShell 7+ · Pi 0.84+
## 参与贡献
欢迎提交 Issue 和 Pull Request。
```powershell
npm ci
npm run check
```
## 致谢
感谢 [radioflyer28](https://github.com/radioflyer28)，这个版本的很多改进都来自其提交的 [issue](https://github.com/oversk7/pi-pwsh-notify/issues?q=author%3Aradioflyer28) 和 [pi-pwsh-notify-secure](https://github.com/radioflyer28/pi-pwsh-notify-secure) 分支。
## License
[MIT](LICENSE)