用 file-based MQ + Hooks 做了个 AI Agent 实时监控面板，端到端延迟 3-17ms 的架构分享

之前在分享创造发过功能介绍，这次换个角度聊聊架构设计。

背景

用 Claude Code / Gemini CLI 同时跑多个 Agent 会话，需要实时知道每个 Agent 的状态（在跑、等 approve 、还是卡了）。写了个本地监控面板来解决这个问题，这里分享下技术选型和一些有意思的设计。

核心挑战：Hook 不能拖慢 CLI

AI coding agent 通过 hook 回调通知外部系统。最大的约束是 hook 脚本不能阻塞 CLI，否则影响编码体验。

方案对比

最初用 HTTP POST （ curl ），但每次 hook 要 spawn 一个进程 + TCP 连接，延迟 50-200ms 。改成 file-based MQ 后：

Hook bash 脚本
  → jq enrichment （ PID, TTY, terminal 环境变量）~2-5ms
  → echo "$ENRICHED" >> /tmp/queue.jsonl        ~0.1ms （ POSIX 原子写入）
  → 后台子 shell + disown （不阻塞 CLI ）

Server 端
  → fs.watch() + 10ms debounce 即时通知
  → 从 byte offset 读取（不重读已处理数据）
  → 1MB 阈值自动截断

端到端 3-17ms ，对 CLI 几乎零感知。HTTP 作为 fallback 保留。

Session Matching：5 级优先级匹配

hook 带着 session_id 过来，但 SSH 终端创建的会话没法直接关联。设计了 5 级 fallback：

优先级越低风险越高，比如 priority 2 在同目录开两个 session 会误匹配。

Approval 检测：启发式 + 可靠信号

用 Claude Code 时，PreToolUse 到 PostToolUse 之间如果超时，说明在等用户 approve 。不同工具类型超时不同：

• fast（ Read, Write, Grep ）: 3s
• slow（ Bash, Task ）: 8s — 额外检查 pgrep -P 是否有子进程在跑
• medium（ WebFetch ）: 15s

medium+ 密度的 hook 有 PermissionRequest 事件，是可靠信号，直接替代启发式。

技术栈

• 后端: Express 5 + ws 8 + tsx （ ESM ，TypeScript 直接跑）
• 前端: React 19 + Three.js （@react-three/fiber ）+ Zustand
• 持久化: SQLite （服务端）+ IndexedDB/Dexie （浏览器端）
• 终端: node-pty （ SSH/PTY ）+ xterm.js
• 架构模式: Coordinator pattern — sessionStore 委托给 sessionMatcher 、approvalDetector 、teamManager 等子模块，避免 God Object

一些工程细节

• 原子写入 settings.json: hook 安装时 write-to-temp + rename ，防止写坏 ~/.claude/settings.json
• WebSocket ring buffer: 保留最近 500 条事件，断线重连时 replay
• Session 状态机: SessionStart → idle → prompting → working → approval/input → waiting → ended

npx ai-agent-session-center

GitHub: https://github.com/coding-by-feng/ai-agent-session-center

MIT 开源。欢迎看代码提 issue ，架构相关的讨论尤其欢迎。