# @ganziliang/pi-attention

Pi 多会话 Windows 托盘提醒器。它使用本地状态文件连接 Pi extension 和独立托盘进程；托盘进程不可用时不会影响 Pi 正常运行。

## 安装

```bash
pi install npm:@ganziliang/pi-attention
```

启动任意 Pi 后执行：

```text
/attention:setup
```

安装完成后，Windows 安装脚本会自动：

- 创建 `PiAttention` Toast 注册；
- 创建开始菜单快捷方式 `Pi Attention.lnk`；
- 创建 Windows 登录自启动项 `PiAttentionTray`；
- 写入默认配置，但不会立即弹出测试通知。

如果包管理器禁用了 npm 生命周期脚本，首次启动 Pi 时 extension 仍会尝试启动托盘；此时可在 Pi 中执行 `/attention:setup` 完成 Windows 注册。

## 命令

- `/attention`：查看当前机器上的 Pi 会话状态
- `/attention:setup`：配置固定播报文本和 Windows 登录自启动
- `/attention:check`：检查 Windows 自启动项和开始菜单快捷方式
- `/attention:reset`：清理并重新启动托盘进程，修复旧进程占用互斥锁的问题
- `/attention:ack`：确认当前会话，下一次进入等待状态时重新提醒

### 配置文件

配置和运行数据默认保存在：

```text
%LOCALAPPDATA%\PiAttention
```

主要文件和目录：

- `config.json`：播报文本和自启动配置
- `states\`：各个 Pi agent 的会话状态
- `notifications.json`：已播报的等待事件，避免托盘重启后重复通知
- `tray.log`：托盘进程运行日志
- `launcher.log`：托盘启动器日志
- `tray.pid`：当前托盘进程 PID
- `sounds\notification.wav`：缓存的播报音频

`/attention:setup` 会让你设置播报文本，并询问是否启用 Windows 登录自启动。固定文本只在配置或首次运行时生成音频缓存。

### 托盘故障排查

如果没有看到托盘图标：

1. 在 Pi 中执行 `/attention:reset`；
2. 查看 `%LOCALAPPDATA%\PiAttention\launcher.log` 和 `tray.log`；
3. 在任务管理器中搜索 `powershell.exe`，托盘程序以独立 PowerShell 进程运行；
4. 检查 Windows 任务栏右下角的隐藏图标区域；
5. 如果仍然没有图标，可以手动启动：

```powershell
node "$env:USERPROFILE\.pi\agent\npm\node_modules\@ganziliang\pi-attention\cli\pi-attention-cli.js" start
```

所有托盘和通知故障均采用 fail-open 策略，不会阻塞 Pi agent。

## 卸载

正常通过 npm 卸载时，包的 `preuninstall` 会自动清理 Windows 托盘相关资源：

- 停止托盘提醒器；
- 移除 Windows 登录自启动项 `PiAttentionTray`；
- 移除 `PiAttention` Toast 注册；
- 移除开始菜单快捷方式 `Pi Attention.lnk`；
- 删除本地状态、配置和缓存声音。

如果使用 Pi 的包管理命令，也可以先执行：

```bash
pi-attention full-uninstall
```

然后再移除 Pi 包：

```bash
pi remove npm:@ganziliang/pi-attention
```

如果某个包管理器跳过 npm 生命周期脚本，`full-uninstall` 是可靠的兜底方式。

## 设计约束

- 每个 Pi 进程一个状态文件，支持任意数量的会话。
- 所有提醒和托盘错误均 fail-open，不阻塞 Pi。
- 固定文本只在配置时生成一次 WAV，运行时只播放缓存文件。
- Windows 退出、崩溃和强制结束都由托盘程序进行过期状态清理。
- 当前版本仅实现 Windows 托盘模式。