Agentation：给 AI 编码代理用的网页标注组件，把”右边那个蓝色按钮”变成结构化反馈

Agentation（agent + annotation）是一个让用户直接在运行中的网页元素上做标注、并把反馈以结构化 JSON 交给 AI 编码代理（Claude Code、Codex、Gemini CLI、Grok Build 等）的轻量方案。作者 Benji Taylor，仓库 github.com/benjitaylor/agentation，协议为 PolyForm Shield 1.0.0（源码可见，非 OSI 认证开源）。本文基于官网、安装页、MCP README 与仓库 TypeScript 类型定义做一手核对。

一、背景动机：人对人说”右边那个按钮”可以，对 Agent 说不行

人与设计师、同事沟通页面问题时，“右上角那个蓝色按钮点了没反应”靠视觉上下文就能对齐；但把这句话转述给编码 Agent，Agent 拿不到你的视线落点，只能靠模糊的文本去猜 DOM 节点，结果经常改错元素。截图沟通又缺少可机读的定位信息。

Agentation 的思路是：在开发环境页面上叠一层标注工具栏，用户点哪个元素、框哪片区域、选哪段文字，组件就采集该元素的选择器、文本、计算样式、React 组件层级乃至开发态源码路径，连同备注一起结构化，再通过本地 MCP 服务器送给 Agent。

二、是什么：React 工具栏 + 本地 MCP 服务器的两件套

方案拆成两个 npm 包：

工具栏组件挂在应用根部，用 NODE_ENV === "development" 判断只在开发态渲染，不进生产包：

{process.env.NODE_ENV === "development" && <Agentation endpoint="http://localhost:4747" />}

不带 endpoint 时，批注只存浏览器本地、手动复制，不发任何外部请求；接上 MCP 服务器后才同步。Agent 侧用 claude mcp add agentation -- npx -y agentation-mcp server 注册，npx agentation-mcp doctor 自检。

三、技术机制：三种标注类型 + 结构化采集 + 9 个 MCP 工具

3.1 标注类型与枚举

类型定义（仓库 package/src/types.ts）把批注分成三类：

• kind: "feedback" | "placement" | "rearrange"：普通反馈、放置建议、重排建议；
• intent: "fix" | "change" | "question" | "approve"：修复、改动、提问、认可；
• severity: "blocking" | "important" | "suggestion"：阻塞、重要、建议；
• status: "pending" | "acknowledged" | "resolved" | "dismissed"：待处理、已确认、已解决、已忽略。

3.2 采集到的结构化字段

每条批注携带的不只是一句备注，还包括：

• 坐标 x（视口宽度百分比）、y（文档绝对像素，fixed 元素为视口坐标）；
• element 标签与 elementPath 选择器、attributes 标识属性、cssClasses、nearbyText、computedStyles；
• selectedText 划选文本、boundingBox 与多选时的 elementBoundingBoxes；
• reactComponents 组件层级（如 <App> <Dashboard> <Button>）；
• sourceFile：React _debugSource 提供的 src/Button.tsx:42，仅开发态可得；
• frame：iframe 内元素的路径与坐标；
• placement 批注带 componentType/width/height/scrollY/text，rearrange 批注带 selector/label/tagName/originalRect/currentRect。

3.3 交互：点击、多选、框选、暂停动画

工具栏支持单击元素标注、拖拽多选、区域框选；暂停 CSS 动画后再截图/标注，用于捕捉闪烁或轮播中的特定状态。MCP 服务器暴露 9 个工具：

watch_annotations 支持免手持循环：Agent 阻塞等新批注 → 批量窗口（默认 10 秒、上限 60 秒）收集 → 逐条 acknowledge、改代码、resolve → 再次监听。默认超时 120 秒、上限 300 秒。

3.4 存储与投递

默认 SQLite 落盘 ~/.agentation/store.db，可切内存存储；SQLite 事件保留默认 7 天。内存模式下事件上限 10000 条、TTL 1 小时、5 分钟清理一次。Webhook 可外发：额外重试 3 次、初始指数退避 1000ms（带 25% 抖动）、最大间隔 30 秒、单次超时 10 秒，以 X-Agentation-Delivery-Id 去重。

四、关键数据：可核对的官方数字

五、评测方法批判：这些数字与能力的口径偏差

1. sourceFile:42 不是生产事实：React 开发元数据来自 _debugSource，生产构建不包含，官方明确标注 best-effort，线上页面拿不到行号；
2. “agent-agnostic”指 AI 代理无关，不是框架无关：工具栏本身是 React 专属，Vue/Svelte/原生项目无法直接挂；
3. 投递是尽力而为：Webhook 与待发队列在内存中，不是持久队列，不保证 exactly-once，关服即取消未完成重试，重启不恢复；
4. CORS 是浏览器访问策略不是鉴权：默认只放行 loopback 与常见开发源，跨网访问需显式 --host 与 AGENTATION_CORS_ORIGINS；
5. 跨域 iframe 是盲区：组件读不到跨域 frame 内容；旋转/倾斜的 frame、跨 frame 边界移动的多元素组不在支持范围；
6. 协议是 Shield 而非 MIT/Apache：个人与公司内部使用免费，把它作为在售产品的一部分再分发需要商业授权（联系作者），“开源”一词要谨慎使用。

六、适用 / 不适用场景

适合：

• 用 Claude Code / Codex 等编码 Agent 做前端迭代，需要把视觉问题精准定位到组件的开发者；
• 设计评审走 Agent、需要把”这块留白太大/这个表单顺序不对”结构化传给代理的小团队；
• 本地单机开发流，愿意跑一个 loopback MCP 服务器；
• 需要会话线程、状态流转（pending→resolved）与免手持 watch 循环的轻量反馈管理。

不适合：

• 移动端页面（官方明确桌面优先，未优化触摸）；
• Vue/Svelte/原生 JS 应用（工具栏 React-only）；
• 生产环境给真实用户收集反馈（设计为 dev-only，无多租户鉴权）；
• 需要持久化、多设备同步、 exactly-once 外发的正式反馈系统。

七、客观分析：优势与局限

优势：

1. 定位信息密度高：选择器 + React 层级 + 开发态源码位置 + 划选文本 + 计算样式一次采集，Agent 改错元素的概率明显低于纯文字描述；
2. 本地优先、默认不外发：不带 endpoint 时零网络请求，隐私边界清晰；
3. MCP 原生：9 个工具覆盖会话、状态流转与阻塞监听，能直接嵌进编码 Agent 循环；
4. 交互贴合视觉工作：暂停动画抓瞬时状态、框选与多选覆盖”一片区域”这类文字难描述的反馈；
5. 接入成本低：一个 dev-only 组件 + 一条 MCP 注册命令。

局限：

1. 技术栈绑定 React 18+，非 React 项目被挡在门外；
2. 桌面优先、移动不支持；
3. 源码行号仅开发态可得，生产页面反馈定位会退化到选择器与层级；
4. 跨域 iframe 与复杂变换元素支持有限；
5. 持久化与投递偏弱：内存队列、非 exactly-once、重启丢失；
6. PolyForm Shield 限制商业内嵌，与传统开源协议的再分发权利不同。

八、它意味着什么 / 谁该关注

Agentation 代表”人机协作前端”里一个务实的小切口：不做完整的设计标注平台，只解决”让人把指认喂给编码 Agent”这一环，用 MCP 把浏览器内的视觉动作变成代理可消费的结构化上下文。值得关注：使用编码 Agent 做前端的独立开发者与小团队、MCP 工具作者、研究人机指认（deixis）与界面定位的工具团队。建议先在本地 dev 模式跑通 copy-paste 流程，确认采集到的选择器在你的组件库里稳定，再开 MCP 与 Webhook。

参考来源

• Agentation 官网
• Agentation GitHub 仓库（benjitaylor/agentation）
• MCP README（工具表/HTTP API/Webhook/存储）
• 安装文档
• npm: agentation / agentation-mcp
• Koala 项目库条目 #1536