Pi Notify

面向本机所有 Pi 项目的 Windows 系统通知扩展。

首次安装

扩展不会在加载时静默修改注册表。在 Pi TUI 中运行：

/notify setup

确认后，扩展会在当前用户的 HKCU\Software\Classes\pi-notify 注册固定动作 URI 协议并发送测试通知。点击测试通知后，再运行：

/notify doctor

确认“点击聚焦已验证”为“是”。点击聚焦是 best-effort：发送通知前记录来源 Windows Terminal 的窗口句柄，点击时优先验证并聚焦该句柄；句柄失效才按会话名/项目名匹配标题。会话映射不存在或无法解析时直接失败，不会跳到任意 Terminal 并报告假成功。不创建窗口或标签页，也不修改标题。激活脚本仅在窗口最小化时执行恢复；已最大化或普通窗口保持原尺寸。脚本会附加相关输入线程并尝试置顶/前台/聚焦，最终以目标窗口是否真的成为前台窗口作为验证结果。

命令

/notify status
/notify on
/notify off
/notify mute 30m
/notify mute 1h
/notify mute today
/notify unmute
/notify setup
/notify uninstall
/notify doctor
/notify test
/notify repair-title

默认仅 TUI 模式发送通知。配置保存在 ~/.pi/agent/notify.json；运行时映射与最小诊断日志保存在 ~/.pi/agent/notify-runtime/。日志不记录通知标题、正文、项目路径或命令。

明确等待用户输入时，扩展在 Toast 成功发送后额外发送一次 Terminal BEL；等待选择时的可视提示由现有提问插件负责，本扩展不重复添加标题图标。最终完成或未完整结束的 Toast 发送成功后，来源 Pi Tab 标题分别显示为 ✅ π - 会话名 - 项目 或 ⚠️ π - 会话名 - 项目，表示结果未读。用户提交下一条交互式输入时自动清除；关闭会话、关闭通知或运行 /notify repair-title 也会清除。

结果图标不根据 Terminal 窗口是否前台进行抑制。Windows Terminal 未公开当前活动 Tab 的独立 HWND/API，同一窗口内所有 Tab 共用顶层窗口句柄，因此只有“下一次用户输入即已读”是可靠的清除信号。扩展不会通过延时轮询猜测 Tab 焦点。Windows Terminal 是否播放 BEL 声音、闪烁任务栏或显示铃铛图标由对应配置文件的 bellStyle 与系统设置决定。PowerShell Helper 调用采用标题栈保护，并在 Helper 退出后的 finally 通过 Pi 官方标题 API 按当前未读结果状态自动恢复标题。

共享人工介入事件

其他扩展可通过 Pi event bus 接入明确的人工阻塞状态：

pi.events.emit("pi-notify:blocked", {
  active: true,
  source: "deploy-confirmation",
  summary: "需要用户确认部署目标",
});

try {
  // 等待用户输入
} finally {
  pi.events.emit("pi-notify:blocked", {
    active: false,
    source: "deploy-confirmation",
  });
}

active 必须是 boolean。source 是建议提供的稳定来源 ID，用来避免多个等待流程互相清除；省略时使用单一默认来源。summary 可选，会按通知配置截断。首版还原生监听 rpiv:ask-user:prompt、rpiv:ask-user:blocked，以及 pi-subagents 的 supervisor-request 人工介入事件；子代理普通完成不产生系统通知。

安全边界

• URI 只接受 16 位十六进制会话哈希（符合 Windows Toast Tag 长度限制）。
• 激活协议由 GUI 子系统的原生 activate.exe 直接执行固定的 Windows Terminal 聚焦逻辑，点击链路不启动 PowerShell，避免新建 PowerShell 窗口或 Terminal 标签页。
• URI 不接受命令、路径、窗口标题或自由文本。
• 用户按 Esc 导致的 aborted 不通知。
• length、最终 error 和失败的最终工具批次显示为“Pi 未完整结束”。
• 通知后端失败不会阻塞 Pi 主任务。