AI Agent等你回复怎么办？herdr-web-ui推送提醒与状态追踪完全指南-开发者社区

【免费下载链接】herdr-web-ui

Browser and phone client for herdr: chat and live terminal for every agent pane, remote PCs over SSH, web push alerts

项目地址：https://gitcode.com/gh_mirrors/he/herdr-web-ui

用 Claude Code、Codex 这类 AI Agent 干活时，最令人抓狂的瞬间莫过于：它在等你确认一条命令、等你回答一个选择题，而你已经切走了页面、甚至合上了电脑。herdr-web-ui 是 herdr 的浏览器与手机端客户端，它能实时追踪每个 agent 窗格（pane）的 RUN / INPUT / DONE / READY 状态，并在 agent 等你输入或完成工作时，通过 Tab 通知、Web Push 推送提醒你——哪怕应用已关闭，手机也能第一时间收到。

先认识 herdr-web-ui：一个窗格，三种视角

herdr-web-ui 把你在 herdr 里跑的每一个 agent 窗格变成三张面孔：

视角	你看到什么
Chat（聊天）	agent 自己的完整对话记录，每轮执行的工具调用折叠成一个"Worked for …"块，可点开细看
Terminal（终端）	同一个窗格的真实现场，通过`herdr terminal attach`共享滚动历史
状态标记	侧边栏与标签条上的实时状态点：工作中转圈、等待输入变红、完成打勾

它不需要你在 agent 和模型之间加任何中间层，终端、浏览器、手机同时看着同一个窗格。一行命令即可安装（详见 docs/guide.md 的 Quick start 章节）：

git clone https://gitcode.com/gh_mirrors/he/herdr-web-ui.git cd herdr-web-ui bun install bun run start

然后打开http://localhost:7317就能用了。

状态追踪：一眼看出谁在等你

agent 最需要你的时刻，通常有两种：

INPUT（blocked）：它在等你回答提问、点批准、输密码；
DONE（done）：一轮工作结束了，产物在等你检查。

herdr-web-ui 对这两种状态做了重点追踪：

侧边栏与标签条实时变色：每个 workspace、tab 的行尾都带 agent 状态标记（默认 Classic 样式，也可在 Settings → Appearance → Status indicators 里切换成 herdr TUI 同款 Dots / Symbols）。
"Needs you" 汇总区：所有正在等输入的窗格会被收拢到侧边栏顶部，本地和远程 PC 的 agent 一并列出，点击直达对应窗格。
服务器持续监听：服务端通过 herdr 的 socket 读取窗口与状态，同时用文件监听循环盯住各 agent 的会话文件（如 server/conversation-monitor.ts 每 250ms 轮询一次文件特征），状态一变就广播。

三级提醒机制：从页内提示到手机推送

herdr-web-ui 的提醒设计成三级，覆盖你"在页面里、在浏览器里、完全不在电脑前"三种场景：

层级	触发条件	需要 HTTPS？
应用内提醒	窗口处于前台，界面本身给出变化	否
Tab 通知	页面开着但在后台/隐藏时弹出系统通知	是（或 localhost）
Web Push 推送	应用关闭、手机锁屏都能收到	是

开启方式很简单：

打开应用右上角⋯菜单，点击Alerts（开启后这一行会显示对勾）；
浏览器弹出权限询问，选择允许通知；
服务器会立即发一条确认推送，证明整条链路是通的。

Tab 通知由浏览器端触发（src/lib/notifications.ts），推送订阅由服务端触发（server/push.ts），两者的判定策略共用同一份 shared/notify-policy.ts，保证手机和桌面在完全相同的事件上响铃。

智能防打扰：为什么有时"不响"是好事

推送提醒最怕的是"狼来了"。herdr-web-ui 内置了几条非常克制的规则，读懂它们你会更信任它的每一条通知：

先等 10 秒再发：提问类提醒会先等约 10 秒（完成类等待约 60 秒）。如果你在桌面端已经手动回答了，提醒会自动取消——它假设"变化这么快，说明有人在电脑前"。
有人在看就不打扰：只要任何设备上的应用窗口处于可见且聚焦状态，所有设备都不会收到提醒（逻辑见 server/push.ts 头部的注释）。
完成提醒默认只报"长回合"：Finished 策略默认Long turns，只有干满一定时长（默认 1 分钟以上）的回合结束才推送；秒回的小问题默认静默。
订阅失效自动修复：推送服务端会把已退役的端点记录下来（push-retired.json），你重新开启提醒时会创建一个新订阅，而不是反复往死掉的端点发（修复记录见 changelog.d/push-retired-endpoint.md）。

提醒偏好怎么调：Needs input 与 Finished 两档开关

每台设备的提醒偏好是独立的，在Settings → Alerts里配置（策略常量定义在 shared/notify-policy.ts）：

选项	含义	可选值
Needs input	agent 等待你的输入或权限时提醒	开 / 关（默认开）
Finished	agent 完成一轮工作时提醒	Off（不提醒）· Long turns（默认，仅长回合）· Every turn（每次都提醒）
Send test	向当前设备发一条测试推送，验证链路	按钮，结果会明确告诉你成功或失败

如果订阅丢失，测试结果会直接给出Turn alerts on again按钮，点一下就重新订阅——不用再翻设置页找开关。

手机上开启推送提醒（三步）

手机是这套机制真正的价值所在。前提只有一个：应用地址必须是 HTTPS（或 localhost）。最省事的方案是 Tailscale，它同时解决"手机怎么连到你的电脑"和"HTTPS 从哪来"两件事：

tailscale serve --bg --https=443 http://127.0.0.1:7317

一行安装脚本检测到本机在跑 Tailscale 时会自动帮你执行并打印二维码（详见 docs/guide.md 的 On your phone 章节）。之后：

手机扫码打开地址，添加到主屏幕（Safari 是"分享 → 添加到主屏幕"，Chrome 是"安装应用"）；
打开⋯菜单 → 点击Alerts，授予通知权限；
到Settings → Alerts → Send test验证一次。

小提醒：iPhone 上只有"添加到主屏幕"后的应用才能收到推送（iOS 16.4+），在普通网页标签页里是收不到的；服务器进程需要保持运行，HERDR_WEB_STATE_DIR（默认~/.config/herdr-web-ui）里的推送密钥和订阅记录也要跨重启保留，重启不会让手机掉订阅。

关键文件速查

想深入了解实现，可以从这几处入手：

推送服务端（订阅、VAPID、提醒等待与取消）：server/push.ts
浏览器端推送订阅（Service Worker + PushManager）：src/lib/push.ts
页内与 Tab 通知：src/lib/notifications.ts
通知判定策略（两端共用）：shared/notify-policy.ts
会话文件监听（聊天与状态刷新）：server/conversation-monitor.ts
用户使用手册（安装、手机、安全）：docs/guide.md

常见问题

问：我在看网页的时候为什么手机不响？这是特性不是 bug：只要任意设备的窗口可见且聚焦，提醒就被视为"有人已看到"而自动抑制；窗口一失去焦点，提醒立即恢复。

问：点推送通知跳到哪里？点击会直接打开对应 PC 和窗格；如果该窗格已关闭，会打开它所在的 workspace 并在页头说明（修复记录见 changelog.d/notification-tap-target.md）。

问：提醒太吵/太安静怎么调？把 Finished 从 Every turn 调回 Long turns（默认），或者关掉 Needs input 中你不关心的类别；每台设备独立配置，桌面可以全开、手机只留关键项。

结语

herdr-web-ui 用"状态追踪 + 三级提醒 + 智能防打扰"三件套，把"AI Agent 干着干着卡住了没人知道"这个高频痛点解决得很彻底：侧边栏的 Needs you 区块让你一眼看到谁在等，Tab 通知盯住你切走的浏览器窗口，Web Push 则负责你在远离电脑的时刻。配置不到三分钟，却能省下大量"回来才发现 agent 半小时前就在等我点批准"的空等时间。