Herdr事件订阅：构建实时代理状态监控面板

Herdr事件订阅构建实时代理状态监控面板【免费下载链接】herdrthe runtime your coding agents live on项目地址: https://gitcode.com/GitHub_Trending/her/herdrHerdr 事件订阅events.subscribe是构建实时代理状态监控面板的关键能力它把每个编码代理Coding Agent的状态变化——工作中、被阻塞、已完成——以事件推送的方式实时送达你的脚本或工具让你无需反复轮询就能一眼看清所有 Agent 的当前状态。Herdr 是一个编码代理的运行时它作为后台服务常驻运行Claude Code、Codex、Cursor 等 Agent 的终端进程都活在它里面。正因为如此Herdr 能看见每个面板pane里 Agent 的每一次状态迁移并把它们变成可订阅的事件流。为什么选事件推送而不是轮询想象你同时跑着 5 个 Agent想做一个面板显示谁在工作、谁卡住了。方式轮询agent.list订阅pane.agent_status_changed状态变化感知最快要等一个轮询周期事件即时推送CPU / 开销每 N 秒全量请求一次一条长连接安静时零流量错过状态瞬间会如一闪而过的 blocked不会事件带有序号实现复杂度低低一行 JSON 发起订阅轮询是你问我答事件订阅是有变化我就喊你。对于监控面板这种场景推送模式几乎是唯一正确答案。Herdr 事件订阅的工作原理理解它只需三个概念后台服务器Herdr 是常驻后台服务ctrlb q断开客户端后进程照常运行。事件由服务器统一产生因此你断开重连、甚至换台机器 SSH 过来监控面板依然有效。事件中心Event Hub所有事件按发生顺序编号sequence。订阅从被服务器接受的那一刻开始接收不重放更早的历史——配合session.snapshot引导快照可以做到零丢失后文细说。两个入口events.subscribe长连接流式订阅适合监控面板events.wait一次性等待等到某个状态出现就返回适合脚本协调。完整协议由 src/api/schema/events.rs 定义订阅的过滤与去重逻辑在 src/api/subscriptions.rs。你可以订阅哪些事件速查表Herdr 的事件覆盖了整个工作区 → 标签页 → 面板 → 代理的层级结构类别事件能监控到什么 代理状态pane.agent_detected面板里识别出了哪个 Agent⚡ 代理状态pane.agent_status_changed状态迁移working / blocked / idle / done / unknown 面板pane.created/closed/updated/focused/moved/exited面板生命周期与焦点 标签页tab.created/closed/renamed/focused/moved视图切换 工作区workspace.created/updated/renamed/moved/reordered/closed/focused项目级容器变化 Worktreeworktree.created/opened/removedGit 分支检出生命周期 输出pane.output_matched面板输出命中子串/正则 滚动pane.scroll_changed面板滚动位置变化 布局layout.updated分屏布局快照更新其中对监控面板最核心的是pane.agent_status_changed它的载荷长这样{ event: pane.agent_status_changed, data: { pane_id: w1:p1, workspace_id: w1, agent_status: blocked, agent: claude, title: Refactor auth middleware } }agent_status只有五个语义值见 concepts.mdxworking正在跑、blocked需要你做决定、done完成待查看、idle已结束且已看过、unknown无法判定。监控面板要盯的基本就是前三个。快速上手三步订阅代理状态变化第 1 步先看看本机 Herdr 的完整协议不写死字段升级不踩坑herdr api schema --json第 2 步向本地 socket 发一条订阅请求每行一个 JSONUnix 上是 Unix domain socket{id:sub_1,method:events.subscribe,params:{subscriptions:[{type:pane.agent_status_changed,pane_id:w1:p1,agent_status:blocked}]}}第 3 步第一条响应是订阅确认ack之后的每一行就是一条推送事件。两个贴心的细节agent_status是过滤器只想被卡住这件事吵醒就填blocked其他状态变化不会推给你如果订阅时该面板已经处于目标状态会立刻收到一条初始事件面板启动前就阻塞住的 Agent 不会漏掉。上图就是 Herdr 自带的最小监控面板侧边栏实时汇总每个 Agent 的状态pi 显示 idle、claude 显示 working状态还会逐层向上卷起——一个 Agent 卡住它所在的面板、标签页、工作区都会标红提醒。你只需复制这套状态 事件的组合。从零搭建不丢事件的监控面板生产级面板的黄金套路是先订阅后快照开一条连接执行events.subscribe等 ack缓冲这条连接开始推来的事件调用session.snapshotCLI 里就是herdr api snapshot拿到一次完整的引导快照所有工作区、标签页、面板、Agent 记录用快照初始化面板再按序回放缓冲的事件继续监听。这样从订阅到快照之间的任何状态变化都不会丢。重连或缓存可能过期时重新做一次快照即可。协议细节见官方文档 socket-api.mdx。如果你的面板还需要等某个 Agent 卡住时触发提醒不必自己写循环Herdr 内置了服务器侧的等待herdr agent wait w1:p1 --until blockedagent.wait由服务器事件驱动还会锁定具体是哪个终端进程Agent 被替换后不会误判。状态语义与检测机制可参考 agents.mdx。进阶输出匹配、滚动监听与通知监控面板做到这里已经能用了还有几个事件让它更聪明pane.output_matched订阅时给出pane_id 匹配规则子串或正则面板输出一旦出现命中行就推送该行及上下文。用它实现测试失败立即弹提醒非常顺手。pane.scroll_changed推送offset_from_bottom等滚动指标0表示停留在底部可用来判断 Agent 是否还在实时刷屏。notification.show面板发现异常后通过一条请求就能让所有已连接的客户端弹出提示可配声音把监控升级为告警。此外Herdr 插件的[[events]]钩子可以监听同一套事件名如pane.agent_status_changed、worktree.created不用写任何 socket 客户端用脚本就能挂自动化动作。小结事件订阅是推送轮询是拉取——监控面板永远选推送核心事件是pane.agent_status_changed五个状态值 状态过滤 初始事件回放把代理是否卡住这件事做到零漏报先订阅后快照模式保证面板从冷启动到稳态不丢事件输出匹配、滚动监听、系统通知是面板升级告警的三件套。Agent 们会在你睡觉时继续工作而 Herdr 事件订阅确保你醒来时——甚至醒来之前——就知道它们做得怎么样。【免费下载链接】herdrthe runtime your coding agents live on项目地址: https://gitcode.com/GitHub_Trending/her/herdr创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考