Agentation

Agentation（agent + annotation）是一个轻量级的开发工具，让你在网页上直接点击元素、选择文本、添加注释，并生成结构化的反馈信息，供 AI 编程助手使用。

它的核心目标很简单：让 AI 知道你具体指的是哪个 UI 元素。当助手能准确识别出你所指的组件或 DOM 节点时，它就能更快地在代码库中找到对应文件并进行修改。

为什么需要 Agentation？

在日常开发中，你可能经常遇到这样的场景：

“侧边栏里那个蓝色按钮有点宽，能不能调窄一点？”

这种描述对人类来说或许足够，但对 AI 助手而言却充满歧义。它不知道“侧边栏”是哪个组件，也不知道“蓝色按钮”对应的是 .btn-primary 还是 .action-button。

而 Agentation 通过自动捕获元素的 CSS 选择器、类名、层级路径和位置信息，将模糊的自然语言转化为精确的代码上下文。例如，它会输出：

- **Selector**: `.sidebar > .nav-actions > button.primary`
- **Text**: "Submit"
- **Position**: (x: 120, y: 450)
- **Comment**: 按钮宽度太大，建议设为 max-width: 120px

你可以直接复制这段 Markdown，粘贴到 Claude Code、Cursor、Windsurf 或任何支持访问本地代码库的 AI 工具中。助手会利用这些信息快速定位源文件，无需猜测。

快速上手

1. 安装依赖：

   npm install agentation -D
   

2. 在你的 React 应用中引入：

   import { Agentation } from 'agentation';
   
   function App() {
     return (
       <>
         <YourApp />
         <Agentation />
       </>
     );
   }
   

3. 启动应用后，右下角会出现一个浮动图标。点击激活工具栏，即可开始标记。

核心功能

• 点击标记：点击任意元素，自动推导最优 CSS 选择器
• 文本选择：高亮一段文字，标记其所在上下文
• 多元素选择：拖拽框选多个元素，批量添加反馈
• 区域选择：即使空白区域也能标记，适用于布局调整
• 动画暂停：冻结 CSS 动画，方便捕捉悬停或过渡状态
• 结构化输出：生成包含选择器、坐标、文本和注释的 Markdown
• 主题适配：自动匹配系统深色/浅色模式，也可手动切换
• 零运行时依赖：仅依赖 React，无额外库，纯 CSS 实现交互效果

与 AI 助手如何协作？

Agentation 本身不绑定任何特定 AI 平台。它只负责生成标准化的反馈数据，由你决定粘贴到哪里。典型工作流如下：

1. 在本地运行的 Web 应用中发现 UI 问题
2. 使用 Agentation 标记该元素并写下修改建议
3. 复制生成的 Markdown
4. 粘贴到 Cursor、Claude Code 等支持代码库访问的 AI 助手中
5. 助手利用选择器（如 .sidebar > button.primary）在项目中搜索，定位到对应的 React 组件或样式文件
6. 自动生成修复建议或直接提交代码变更

这种方式显著减少了沟通成本，也避免了因描述不清导致的反复澄清。

技术细节与限制

• 依赖：仅需 React 18+
• 平台：仅支持桌面浏览器（移动端暂不支持）
• 隐私：所有操作在本地完成，无网络请求，不上传任何数据
• 开源：MIT 许可，可自由集成与修改

Agentation 的设计灵感来自 Benji Taylor 关于“如何向 AI 编程助手提供有效反馈”的思考。它不试图取代 AI，而是成为你与 AI 之间的精准翻译器——把视觉意图转化为机器可理解的代码线索。