用 Agentation 把 AI 前端改稿变成可视化标注

用 AI（人工智能）编程助手改前端页面时，最麻烦的往往不是“怎么改”，而是“改哪里”。

比如你让 Claude、Cursor 或 Windsurf 帮你改一个按钮：

把右上角那个蓝色登录按钮改成红色。

如果页面结构简单，AI 可能能猜到。但一旦组件层级复杂、同类按钮很多、样式类名相似，AI 很容易改错元素。它缺少运行中页面的精确信息，只能根据自然语言猜测：你说的“右上角”到底是哪个 DOM（文档对象模型）节点？按钮对应哪个类名？组件层级在哪里？有没有唯一的 CSS 选择器？

Agentation 解决的就是这个问题：把“口头描述 UI”变成“在页面上点选 UI”，再把点选结果转换成 AI 能理解的结构化上下文。

它更像是前端页面和 AI 编程助手之间的一层标注桥梁。

flowchart LR
    A[开发者在页面上点选元素] --> B[Agentation 收集 DOM 信息]
    B --> C[生成结构化 Markdown]
    C --> D[粘贴给 Claude / Cursor / Windsurf]
    D --> E[AI 根据选择器和备注修改代码]

Agentation 解决的核心问题

前端页面的视觉信息和代码信息之间有一道鸿沟。

开发者看到的是：

页面右上角有一个登录按钮；
某个卡片间距太小；
某段文案颜色太浅；
某个区域需要加交互动画。

AI 编程助手需要的是：

具体的 CSS 选择器；
元素类名、ID、标签名；
元素文本；
所在区域坐标；
父子层级关系；
你希望怎么修改。

只用自然语言描述时，这些信息会丢失很多。Agentation 的做法很直接：在运行中的网页里开启标注模式，点一下元素，工具自动提取 DOM 信息，并让你补充备注，最后生成一段 Markdown。

这段 Markdown 可以直接交给 AI 编程助手，减少“你说的是哪个按钮？”这种反复确认。

它会从页面里提取哪些信息

Agentation 点击元素后，会尽量生成一个稳定、短小、能定位到目标节点的 CSS 选择器，同时附带一组上下文信息。

信息	作用
CSS 选择器	让 AI 能在代码或样式中定位目标元素
类名、ID、标签名	帮助 AI 判断元素语义和样式来源
文本内容	区分多个外观相似的按钮、链接或标题
Bounding rect	描述元素在页面中的位置和尺寸
层级路径	辅助判断元素所在组件或父子结构
备注	告诉 AI 具体要做什么改动

生成结果大致类似这样：

**Element 1**
- Selector: .navbar > .btn-primary.login
- Classes: btn btn-primary login
- Text: 登录
- Bounding rect: {x: 1240, y: 18, width: 98, height: 42}
- Note: 把背景色改成 #ef4444，文字白色，加一点阴影

这类结构化信息对 AI 很友好。它既有机器可定位的选择器，也有人类语义层面的备注，比一句“改右上角登录按钮”清楚得多。

标注方式不只支持单个元素

前端改稿不总是针对一个按钮。很多时候，需求针对的是一组元素、一个区域，或者一段文本。Agentation 支持多种标注方式：

标注方式	适合处理的问题
单点元素	修改按钮、输入框、链接、图标等单个节点
拖拽框选	标记一整块区域，例如导航栏、卡片列表、表单区域
文本选择	处理文案、标题、说明文字等文本节点
添加备注	补充具体修改要求，例如颜色、间距、动画、交互状态

比如要让 AI 调整一个卡片区域的布局，可以框选整个卡片，再写备注：

**Selection 1**
- Area: {x: 320, y: 180, width: 420, height: 260}
- Note: 这个卡片内部上下间距太挤，标题和描述之间增加 8px，按钮区域下移 12px

这样 AI 不只能知道“要改卡片”，还知道你认为问题出现在什么位置，以及期望的视觉结果。

Agentation 的工作方式

Agentation 是纯前端工具，不依赖后端服务。它被挂载到 React 应用里后，会在页面右下角显示一个小工具入口。进入标注模式后，它会监听页面上的点击、拖拽、文本选择等操作，并把目标 DOM 节点的信息整理出来。

整体流程可以理解为：

sequenceDiagram
    participant Dev as 开发者
    participant Page as 运行中的页面
    participant Agent as Agentation
    participant AI as AI 编程助手

    Dev->>Page: 打开页面并进入标注模式
    Dev->>Agent: 点击或框选目标元素
    Agent->>Page: 读取 DOM、选择器、文本、坐标
    Dev->>Agent: 添加修改备注
    Agent-->>Dev: 输出 Markdown
    Dev->>AI: 粘贴 Markdown 和需求
    AI-->>Dev: 给出代码修改方案

这里最重要的是：Agentation 不替代 Claude、Cursor 这类 AI 编程助手，它负责把页面上下文整理清楚。真正的代码修改仍然由 AI 工具完成。

在 React 项目中接入

Agentation 主要面向 React 18+ 项目。安装时建议作为开发依赖引入：

npm install agentation -D

在应用根组件里挂载 Agentation：

import { Agentation } from 'agentation';

function App() {
  return (
    <>
      <YourApp />
      <Agentation />
    </>
  );
}

如果只希望开发环境启用，可以加一层环境判断：

import { Agentation } from 'agentation';

function App() {
  return (
    <>
      <YourApp />
      {import.meta.env.DEV && <Agentation />}
    </>
  );
}

启动应用后，页面右下角会出现工具入口。典型使用流程是：

打开本地开发页面；
点击 Agentation 工具入口；
进入标注模式；
点选元素、框选区域或选择文本；
添加修改备注；
复制生成的 Markdown；
粘贴到 Claude、Cursor、Windsurf 等 AI 编程助手里。

和 AI 编程助手配合时怎么写提示词

Agentation 生成的是定位信息，但 AI 仍然需要清晰的任务目标。比较稳妥的方式是把“页面上下文”和“修改要求”分开写。

例如：

请根据下面的页面标注信息修改 React 组件和样式。

要求：
1. 只修改登录按钮的视觉样式，不影响其他按钮。
2. 背景色改成 #ef4444。
3. 文字保持白色。
4. 增加轻微阴影。
5. 如果有共用 class，避免影响同类按钮。

页面标注：

**Element 1**
- Selector: .navbar > .btn-primary.login
- Classes: btn btn-primary login
- Text: 登录
- Bounding rect: {x: 1240, y: 18, width: 98, height: 42}
- Note: 把背景色改成 #ef4444，文字白色，加一点阴影

这种写法能降低误改概率。尤其是“不要影响其他按钮”这类约束，最好明确写出来，因为很多前端样式问题都出在共用类名上。

适合和不适合的场景

Agentation 的价值主要体现在“页面上看得见，但代码里不好快速定位”的场景。

场景	是否适合	原因
用 AI 修改 React 页面样式	适合	能把 DOM 选择器、文本、坐标一起交给 AI
调整复杂组件布局	适合	框选区域比文字描述更准确
修改按钮、导航栏、表单等 UI	适合	元素有明确 DOM 节点，容易标注
让 AI 理解页面视觉问题	适合	备注可以补足“哪里不好看、想怎么改”
后端接口开发	不适合	它主要处理浏览器页面标注，不解决接口逻辑问题
非 React 项目	视情况而定	当前主要面向 React 18+，其他框架需要看适配情况
完全依赖截图改代码	不太适合	截图缺少 DOM 结构，Agentation 的优势在于结构化页面信息

其他细节功能

除了基础标注，Agentation 还有几个对前端调试比较有用的能力：

可以暂停 CSS 动画，便于观察某些动态状态；
支持深色模式和浅色模式适配；
纯前端运行，不需要额外部署后端；
生成 Markdown，适合复制到各种支持长文本上下文的 AI 工具里。

也可以结合 Claude 的技能机制使用：

npx add-skill benjitaylor/agentation

配置完成后，可以在 Claude 中通过 /agentation 相关能力配合页面标注信息使用。具体可用能力取决于当前 Claude 环境和技能配置方式。

使用时要注意的坑

Agentation 能减少定位成本，但它不是万能的。实际使用时有几个点需要留意。

1. CSS 选择器不等于组件文件路径

选择器能告诉 AI 页面上哪个元素被选中，但不一定能直接映射到某个 React 组件文件。组件拆分复杂时，最好再补充一两句说明，例如：

这个按钮在顶部导航栏中，可能对应 Header 或 Navbar 组件。

2. 动态 class 可能影响定位

如果项目使用 CSS Modules、Tailwind 原子类、CSS-in-JS 或构建时哈希类名，选择器可能不够稳定。遇到这类情况，文本、坐标、父级结构和备注就更重要。

3. 不建议在生产环境常驻

Agentation 更适合作为开发辅助工具。生产环境通常不需要暴露标注入口，因此建议用环境变量控制，只在开发环境挂载。

{import.meta.env.DEV && <Agentation />}

4. SSR 项目要注意客户端渲染

如果项目使用服务端渲染（SSR，Server-Side Rendering），需要确保 Agentation 只在浏览器侧运行。因为它依赖页面 DOM，服务端环境没有 window 和真实 DOM。

官方入口

官网：https://agentation.dev/
GitHub：https://github.com/benjitaylor/agentation

判断是否需要引入 Agentation

如果前端开发流程里经常出现这类对话：

“不是这个按钮，是旁边那个。”
“改错组件了。”
“这个区域不是 sidebar，是内容区里的卡片。”
“我说的是 hover 状态下的那个元素。”

Agentation 就能派上用场。它把模糊的自然语言描述转换成可复制、可定位、可追踪的页面标注信息，让 AI 编程助手少猜一点，多依据一点。对于经常用 AI 修改 React 页面、组件样式和交互细节的开发流程，这个工具能明显减少来回解释的成本。

菜单