pi-attention 🍎

Pi 的 iTerm2 / Orca 注意力集成扩展：把 iTerm2 标签页标题显示为会话第一次 pi 提问，回答完成时弹 macOS 系统通知，并在 pi 等待你选择时提醒（权限弹窗 / 计划菜单；iTerm2 原生转义序列与 Orca notification 事件，无需第三方工具）。

• 源码仓库: pi-packages（GitHub monorepo 负责源码与文档）
• npm 包: pi-attention（独立安装、升级和卸载）

功能

1. 标题恒定显示提问 — 标题显示本会话最开始的一次提问，跨 reload / resume 稳定，退出时还原。
2. 回答完成系统通知 — 每次回答完成后，在 macOS 通知中心弹出通知，标题显示 assistant 回复摘要。
3. 等待用户操作提醒 — 权限弹窗（pi-permission-system）、计划菜单（pi-plan-mode）等阻塞等待你选择时：
   • iTerm2：弹系统通知 + dock 弹跳，终端标题变为「⏸ 等待选择…」；
   • Orca：上报 notification 事件，Orca 弹原生系统通知（来源为 Orca 应用）——仅在 Orca 不在前台时弹出。

安装

# 全局安装
pi install npm:pi-attention

# 项目级安装
pi install -l npm:pi-attention

# 本地开发：在 pi-packages 仓库根目录执行
pi install ./extensions/pi-attention

# 卸载
pi remove npm:pi-attention

安装后重启 pi，或在 pi 内执行 /reload 即可生效。GitHub monorepo 仅作为源码和文档中心，不再通过根目录合集安装本扩展。

配置

环境变量	默认	说明
PI_ATTENTION_NOTIFY	开	设为 0 关闭「回答完成通知」
PI_ATTENTION_NOTIFY_WAITING	开	设为 0 关闭「等待用户操作」的系统通知

通知机制（iTerm2 原生，无需第三方工具）

回答完成时，扩展直接向 iTerm2 发送两条原生转义序列来触发通知，发送者即 iTerm2：

• OSC 9 ; <消息> → 弹系统通知
• OSC 1337 ; RequestAttention=once → dock 图标弹跳一次 + 系统提示音

无需安装 terminal-notifier 或 osascript。仅当不在 iTerm2 终端（如 tmux）时，才回退到 osascript 方式（并用显式提示音）。

通知机制（Orca：notification 事件）

Orca pane 下等待用户操作时，扩展经 agent-hook 上报 notification 事件（title / body / message / notification_type），Orca 主进程走原生系统通知：

• 来源为 Orca 应用本体，标题自动带 pi: 前缀；
• 仅在 Orca 不在前台时弹出——你正看着窗口时不打扰，切到别的应用时才提醒；
• 相关调研见 docs/orca-notification-mechanism.md（ui_prompt_* 为何不被 Orca 消费、ask_user_question 白名单等）。

标题行为

• 标题恒定显示本会话最开始的一次提问（会话里第一条 user 消息），跨 reload / resume 稳定
• 退出 pi → 标题还原为基础标题 π · <会话名> · <目录名>

通知

• 回答完成（agent_settled，消息已落盘）时触发 iTerm2 原生通知
• 通知标题显示 assistant 回复摘要（最后一条回复的前 60 字）
• 发送者为 iTerm2（OSC 9）+ dock 弹跳 + 系统提示音（RequestAttention=once）

事件/原理

• request-title.ts — 标题 + 回答完成通知
  • session_start — 会话启动/加载/恢复时，设定标题为最开始提问
  • agent_settled — 回答完成（消息已落盘）时触发，发系统通知 + 校正标题
  • session_shutdown — 会话退出时还原标题
• waiting-notify.ts — 等待用户操作提醒（权限弹窗 / 计划菜单 / 任意 ctx.ui.* 阻塞提示）
  • ui_prompt_start — 等待开始：标题切「⏸ 等待选择…」；Orca 上报 notification 事件 → 原生系统通知（后台才弹）；iTerm2 弹 OSC 通知
  • ui_prompt_end — 等待结束：恢复基础标题
  • 环境判定：Orca pane（ORCA_PANE_KEY / ORCA_AGENT_HOOK_ENDPOINT）→ 上报 notification 事件；TERM_PROGRAM === "iTerm.app" 且非 PI_WEB_HOSTNAME → iTerm2 原生通知；否则静默

为什么 waiting-notify 不放 Orca 的扩展里：Orca 会定期覆盖它自己分发的扩展（文件头标 @orca-managed-pi-extension 的那些），补丁会被冲掉；放本包统一维护。

License

MIT