@ganziliang/pi-attention

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

安装

pi install npm:@ganziliang/pi-attention

启动任意 Pi 后执行：

/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：确认当前会话，下一次进入等待状态时重新提醒

配置文件

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

%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. 如果仍然没有图标，可以手动启动：

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 的包管理命令，也可以先执行：

pi-attention full-uninstall

然后再移除 Pi 包：

pi remove npm:@ganziliang/pi-attention

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

设计约束

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