Agentation 是一款专为前端开发者设计的轻量级辅助工具，旨在解决人与AI编程助手（如 Claude Code、Cursor、Windsurf）之间沟通 UI 问题时的“上下文缺失”难题。在传统开发流程中，当开发者在网页上发现样式错误或交互 Bug 时，往往难以用自然语言向 AI 准确描述该元素在代码库中的具体位置。Agentation 遵循“所见即所得”的原则，允许用户直接点击网页上的元素进行标注，自动抓取该组件的类名（Class Names）、选择器（Selectors）和层级位置，并将这些技术细节与用户的修改意见组合成结构化的 Markdown 格式。用户只需将这段信息复制给 AI，AI 即可利用这些精确的定位信息在代码库中快速索引到对应的源文件并进行修复。该工具目前基于 React 构建，零额外依赖，且完全独立于特定的 AI 模型，任何能够读取文本的 AI Agent 均可使用。
功能列表
- 可视化元素标注：通过鼠标悬停和点击，直接在运行中的网页上选中任意 DOM 元素（如按钮、卡片、文本段落）。
- 自动提取技术参数：选中元素后，工具会自动捕获该元素的 CSS 类名、ID、层级路径（Selectors）等关键定位信息。
- 结构化反馈生成：支持在选定元素上添加自定义文字说明（如“修改颜色”、“修复间距”），并一键生成包含技术上下文的 Markdown 文本。
- 动画暂停调试：提供“暂停动画”功能，方便捕捉和标注动态效果或特定帧的 UI 问题。
- 文本精准定位：支持直接选中网页中的具体文本段落进行纠错，方便 AI 快速定位文案所在的组件位置。
- 跨平台兼容：生成的输出格式为标准 Markdown，无缝支持 Claude Code、Cursor、Windsurf 或任何支持上下文输入的 LLM 编程工具。
使用帮助
Agentation 的核心设计理念是“轻量化”与“无缝集成”，它不需要复杂的后台配置，主要以 React 组件的形式集成在开发环境中。以下是详细的操作流程与使用指南：
1. 启动与激活
Agentation 目前主要针对桌面端浏览器环境。在集成了 Agentation 的项目中（通常在开发环境下），你的网页右下角会出现一个工具图标。
- 激活工具：点击屏幕右下角的 Agentation 图标，或者使用快捷键（如果配置）激活标注模式。此时，当你移动鼠标时，页面上的各个 HTML 元素（如
<div>、<button>、<p>）会被高亮显示，表明它们处于可被选中的状态。
2. 标注目标元素
当你在网页预览中发现需要修改的地方（例如一个按钮的颜色不对，或者一段文字排版错误）：
- 选择元素：将鼠标悬停在目标元素上，点击左键即可“锁定”该元素。
- 添加反馈：点击后会弹出一个输入框。在这里输入你对该元素的修改意见，例如：“这个按钮的圆角应该是 8px”或者“点击这个卡片没有反应”。
- 多点标注：你可以连续点击页面上的多个不同位置，一次性收集多个修改需求。例如，你可以同时指出导航栏的高度问题和页脚的链接错误。
3. 处理动态内容
对于包含复杂动画或过渡效果的页面，捕捉特定状态往往很困难。
- 暂停动画：在 Agentation 的工具栏中点击“暂停”图标（通常是一个冻结符号）。这会强制停止页面上的 CSS 动画和 JS 渲染循环，让页面停留在当前帧。
- 精准标注：在页面静止的状态下，你可以从容地选中那些平时一闪而过的动态元素进行标注。
4. 生成并导出上下文
完成所有问题的标注后，需要将这些信息传递给 AI：
- 生成报告：点击工具栏上的“Copy”或“Export”按钮。Agentation 会将你选中的元素路径（如
.sidebar > .nav-actions > button.primary）和你输入的文字说明整合成一段格式清晰的 Markdown 文本。 - 内容预览：生成的文本不仅包含你的自然语言描述，还包含机器可读的代码定位符。这正是 AI 能够精准找到文件的关键。
5. 驱动 AI 修复代码
最后一步是连接你的 AI 编程助手：
- 粘贴指令：打开你正在使用的 AI 工具（如 Cursor 的 Chat 窗口，或者 Claude Code 的终端界面），粘贴刚才复制的文本。
- 执行修复：AI 接收到信息后，不再需要猜测“那个蓝色的按钮”是哪个文件，它会直接通过类名和选择器在代码库中进行全局搜索（Grep），迅速定位到对应的 React 组件或 CSS 文件，并根据你的反馈生成修复代码。
应用场景
- UI 样式微调
前端开发中经常需要调整组件的 Padding、Margin 或颜色。使用 Agentation，开发者无需手动去查找该组件对应的 CSS 文件名，只需在浏览器中点击组件并备注“Padding 增加到 20px”，AI 就能直接定位到样式文件进行修改。 - 复杂组件的 Bug 修复
在层级极深的 React 组件树中（例如一个嵌套在 Sidebar 里的 Modal 里的 Button），手动寻找源文件非常耗时。Agentation 能生成精确的 DOM 路径，帮助 AI 瞬间找到该组件在项目中的具体位置。 - 文案内容的批量校对
当网页中存在多处拼写错误时，非技术人员（如产品经理或设计师）如果在开发环境下使用该工具，可以直接选中错误文本并输入正确文案，生成的反馈直接交给 AI 替换，避免了口头沟通的歧义。
QA
- Q: Agentation 需要后端服务支持吗？
A: 不需要。它是一个纯前端的工具，通常作为一个 React 组件引入你的项目中，零后端依赖，所有数据处理都在浏览器本地完成。 - Q: 它只支持 React 项目吗？
A: 目前官方文档主要展示了 React 环境的使用，但其核心逻辑（DOM 选取和路径生成）是通用的。不过作为 npm 包引入时，目前主要适配 React 生态。 - Q: 为什么生成的反馈能让 AI 工作得更好？
A: 大模型（LLM）虽然聪明，但它们看不见你的屏幕。传统的提示词“修复右上角的按钮”非常模糊。Agentation 提供的.header-right .login-btn这种精确的代码特征，让 AI 可以像使用grep命令一样直接检索代码库，从而消除了“幻觉”和猜测。 - Q: 这个工具收费吗？
A: 目前该工具以开源或免费开发工具的形式存在，主要目的是为了优化 AI 辅助编程的工作流体验。
