如何打造无人值守前端工作流Agentation watch_annotations 轮询与 Webhooks 集成教程【免费下载链接】agentationThe visual feedback tool for agents.项目地址: https://gitcode.com/gh_mirrors/ag/agentationAgentation 是一款面向 AI 编程代理的视觉反馈工具在浏览器中点击元素、写下批注Agent 就能精确定位到对应源码。本文将手把手教你利用agentation_watch_annotations阻塞轮询工具与 Webhooks 推送机制用 5 个步骤搭建一条无人值守的前端反馈工作流——你只管在页面上标注Agent 自动接收、修复并回复。1. Agentation 是什么一句话概括The visual feedback tool for agents代理的视觉反馈工具。它的工作原理非常直观在页面右下角打开工具栏点击任意元素即可添加批注工具会自动捕获类名、CSS 选择器和元素位置。于是你不再需要用「侧边栏里那个蓝色按钮」这种模糊描述而是直接给 Agent 一条.sidebar button.primary加你的反馈意见——Agent 一查就懂。核心特性包括点击标注、文本选区标注、多选、区域框选、动画冻结、结构化 Markdown 输出且零运行时依赖。详细特性说明见 README.md。2. 无人值守工作流的整体架构要理解watch_annotations轮询先看数据是怎么流动的浏览器工具栏 ──HTTP(4747)── Agentation 服务端 ──SSE/HTTP── MCP 服务 ──stdio── AI AgentHTTP 服务默认端口 4747接收浏览器工具栏发来的批注并提供 SSE 事件流MCP 服务stdio把批注数据以工具形式暴露给 Claude Code 等 AI 编程代理事件总线所有批注事件带全局序号通过 SSE 实时推送给所有监听者含 Agent这条链路正是「无人值守」的基础你在浏览器里的每一次点击都会实时出现在等待中的 Agent 手里。3. 核心工具详解agentation_watch_annotations 轮询agentation_watch_annotations是 MCP 服务暴露的 9 个工具中唯一的「阻塞式」工具它的设计目标就是让 Agent 挂起等待而不是反复空转轮询Agent 调用该工具连接 SSE 事件流并阻塞等待检测到第一条新批注后开启一个批收集窗口把同一波到达的批注攒成一个批次窗口结束一次性返回整批批注含 feedback、placement 布局放置、rearrange 区块重排三种类型Agent 处理完毕后再次调用形成循环几个关键实现细节源码见 mcp/src/server/mcp.tsPending 预排空阻塞前先拉取一次已有未处理批注避免漏掉「上一批处理期间到达」的反馈序号过滤SSE 连接建立时的历史回放事件sequence 为 0会被跳过不会误触发优雅超时超时后返回timeout: true而非报错方便外层循环安全重试轮询参数速查表参数默认值上限作用sessionId监听全部会话-可选按会话过滤批注batchWindowSeconds10 秒60 秒首条批注后的批次收集窗口timeoutSeconds120 秒300 秒等待首条批注的最长时间 批次窗口宁大勿小用户连续标注多条反馈时较大的窗口能让 Agent 一次拿到完整上下文减少往返次数。4. 一句话配置让 Agent 进入值守循环在项目的CLAUDE.md或代理的系统指令中加入一段话即可开启官方文档称为Hands-Free Mode免手模式的自动处理循环当我说 watch mode 时循环调用 agentation_watch_annotations。 对每条批注先 acknowledge再做代码修改最后带总结调用 resolve。 持续监听直到我说停止或超时。这样 Agent 的行为就固化为一个闭环watch阻塞等待→ acknowledge标记已读→ 修改代码 → resolve标记完成并附总结→ 再次 watch用户侧的体验是批注处理完会自动从浏览器工具栏消失并留下一条 Agent 的处理总结。完整流程说明见 mcp/README.md 的 Hands-Free Mode 章节。5. Webhooks 集成给工作流装第二条推送通道MCP 轮询是「拉」通道Webhooks 则是「推」通道两者可并行使用分别适配 Agent 与外部系统Slack、CI/CD、自建后端等。服务端 Webhook 配置启动 MCP 服务前通过环境变量注入回调地址源码逻辑见 mcp/src/server/http.ts# 单个 Webhook export AGENTATION_WEBHOOK_URLhttps://your-server.com/webhook # 多个 Webhook逗号分隔 export AGENTATION_WEBHOOKShttps://server1.com/hook,https://server2.com/hook浏览器端 Webhook 配置也可在 React 组件上直接传webhookUrl属性开启 Auto-Send 后批注创建、更新、删除、清空、提交等事件都会自动 POST 推送。触发的事件包括annotation.add、annotation.delete、annotation.update、annotations.clear和submit。Webhook 载荷结构所有事件都携带统一的 JSON 结构事件类型、时间戳、页面 URL以及批注本体。批注数据包含元素选择器路径、用户评论、位置坐标等字段——这正是 Agent 能直接 grep 到源码的关键。结构示意如下官方文档中还给出了三个典型用例Slack 通知、自动创建 Issue、实时仪表盘广播安全方面建议启用 HTTPS、校验来源、加限流并清理用户输入详见 package/example/src/app/webhooks/page.tsx。6. 进阶玩法双会话 Self-Driving 工作流当批注的来源不再是「人」而是「另一个 Agent」时工作流升级为完全自治会话 1评审者在可见浏览器中从上到下扫描页面通过工具栏自动添加设计批注你坐在旁边就能看着它「开车」会话 2修复者运行agentation_watch_annotations循环实时接收会话 1 产生的每条批注读码、修复、resolve评审者跑得比修复者快也没关系——批注会自动排队。若修复触发热更新导致工具栏收起评审者会自动重新展开。这套模式还支持设计模式下的组件放置placement与区块重排rearrange批注完整的双会话工作流参考文档见 skills/agentation-self-driving/references/two-session-workflow.md评审技能规范见 skills/agentation-self-driving/SKILL.md。7. 常见排错小贴士 现象原因与解决提示无法连接 HTTP 服务ECONNREFUSED4747 端口服务未启动先运行agentation-mcp server工具报「SSE 连接意外关闭」服务端可能重启过重新调用 watch 即可监听时立刻返回旧批注这是 Pending 预排空机制属正常行为不确定环境是否就绪运行agentation-mcp doctor一键体检⏱️ 小贴士先启动值守会话再开始标注避免首批反馈等待超时timeoutSeconds最长 300 秒长空闲场景可显式调大。8. 关键文件导航项目总览与特性README.mdMCP 服务文档工具表、Webhooks、环境变量mcp/README.md工具定义与轮询实现mcp/src/server/mcp.ts实时事件总线mcp/src/server/events.tsWebhook 发送逻辑mcp/src/server/http.ts双会话工作流参考skills/agentation-self-driving/references/two-session-workflow.md总结无人值守前端工作流的配方其实很简单agentation_watch_annotations负责「不丢单」的阻塞轮询resolve/acknowledge 负责闭环反馈Webhooks 负责触达外部系统。三者配合你只需在浏览器里点点标注Agent 就会自动认领、修复、汇报。从手工粘贴反馈到全自动值守前端迭代的速度提升不是一点半点。【免费下载链接】agentationThe visual feedback tool for agents.项目地址: https://gitcode.com/gh_mirrors/ag/agentation创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考