tauri-menubar-agent-app

name	tauri-menubar-agent-app
description	Use when building a macOS menu-bar (tray) app with Tauri v2, especially one that observes external CLI agents via hooks — covers native window layering with objc2 (transparent windows, NSStatusWindowLevel, flipped coordinates), Unix-socket IPC from hook bridge binaries, multi-agent event normalization, and non-intrusive interaction design.

Tauri 菜单栏应用（macOS）与多 Agent 事件桥接

Tauri v2 + Rust (src-tauri) + bun/vite 前端（固定端口 + strictPort）的菜单栏应用经验，含监听外部 coding agent 的 hook 桥接架构。

1. macOS 顶层窗口：纯 Tauri API 不够，要下到 objc2

• 透明窗口崩溃：transparent: true 需要开 app.macOSPrivateApi = true。
• IPC 崩溃（no reactor running）：IPC 监听不能在无 Tokio reactor 的上下文初始化——改用标准线程 + UnixStream 监听。
• 窗口被菜单栏压住：用 objc2-app-kit 拿 ns_window()，把层级提到 NSStatusWindowLevel(25)，Floating(3) 不够。
• 贴不到屏幕顶部有两个叠加原因：① setFrameTopLeftPoint 用 flipped 坐标，会贴在菜单栏下方；② macOS constraint 保护会自动修正坐标。要同时设置 collectionBehavior 允许覆盖菜单栏 + 原生精确定位。
• 原生窗口操作必须在主线程执行。
• 不要猜 magic offset：坐标不对时从坐标系语义根源解决，不要试 -28 之类的魔法值。

2. 多 Agent hook 桥接架构

• 注入点：各 agent 的 hook 配置（~/.claude settings、~/.codex/hooks.json、~/.cursor/hooks.json），覆盖 SessionStart / Stop / SubagentStop / Notification / PermissionRequest / UserPromptSubmit。
• bridge 是独立小二进制（--source <claude|codex|cursor>），打进 .app 的 Contents/Helpers。
• IPC：bridge 写入 ~/.<app>/run/<app>.sock（UnixStream），协议为单行 JSON { event: ... }。
• 核心难点是事件归一化：各 agent 原始字段结构不同，覆盖面不足的症状是「日志进来了但 UI action 没联动」——归一化层要按 agent 逐个校准状态机映射（如 Codex：UserPromptSubmit 即 running，Stop 即 idle，SessionStart 后可能什么都不发生）。
• 常见状态机 bug：permission 请求与 ask_user_question 未区分；permission 未处理被误判会话结束；会话结束后仍显示运行中；第二个 agent 进程不可见。排查一律先加日志读运行时输出。

3. 交互设计原则

• 菜单栏应用的介入要克制：需要用户介入时改变图标状态（如「招手」动画），不主动弹 popover 打断；用户的回应仍回到 agent 自身完成。
• 涉及 permission 的事件优先级最高，菜单栏计数与动画图标要同步更新。
• 消息预览区不做占位：0 条显示 0 条，最多显示最近 N 条，不为对齐而填充。