Agentation SITES

// 01 Agentation 是什么

平台总体概述

核心定义

Agentation 是一个轻量级的前端开发辅助组件，一般认为主要用于开发环境内帮助开发者将视觉上的 UI 或交互问题转化为 AI 可解析的结构化反馈。用户通过在网页上标注元素、输入反馈并复制生成的 Markdown 内容，将上下文信息传递给 AI 编程助手。

核心问题与动机

在常规的开发流程中，开发者描述问题时经常使用自然语言，这通常不能准确表达具体的 UI 元素在源代码中的位置。Agentation 的设计目标在于通过技术参数（如 CSS 选择器、类名等）让 AI 工具能直接定位相关代码片段，而无需依赖模糊描述。

核心功能结构

可视化元素标注

用户可以在运行中的网页上悬停并点击目标元素进行标注，标注过程会自动捕获元素的 CSS 选择器、类名、层级路径 等关键信息。该信息随后用于生成精确定位文本。

文本选择标注与反馈结构

Agentation 支持直接选择页面上的文本段落进行标注。被选定的文本将作为搜索关键字包含在 Markdown 输出中，使得 AI 编程助手能够在代码库中进行精确查找。

暂停动画与静态标注

工具提供暂停 CSS 动画的功能，以便在动态页面上捕获需要静态定位的元素。该功能通常仅适用于 CSS 动画，对于纯 JavaScript 动画可能无法生效。

多种输出格式

生成的 Markdown 反馈支持多种格式，包括：

• Compact — 精简上下文

• Standard — 平衡详细信息和简洁性

• Detailed — 包含更多上下文与元素框信息

• Forensic — 包含计算样式详细数据

这些格式可根据特定任务需求灵活选择。

React 集成与前端环境要求

Agentation 作为 React 组件运行，需在 React 18 以上项目中集成。通常在开发环境（NODE_ENV === 'development'）中使用，而不建议在生产环境启用。

注释持久化与存储

标注信息存储在浏览器本地的 localStorage 中，并且通常根据页面路径键存储；默认情况下，这些注释在刷新后保留，但可能在一定时间后清除。

技术细节与实现

结构化反馈生成流程

1. 用户在浏览器页面中选中或点击元素。

2. Agentation 自动提取元素的类名、CSS 选择器、文本内容等。

3. 用户输入文字注释作为上下文反馈。

4. 工具将技术参数和文字描述组合成 Markdown 格式生成输出。

5. 用户将 structured Markdown 复制并粘贴到 AI 编程助手界面。

开发者集成方式

Agentation 可通过 npm、yarn、pnpm 或 bun 安装，并作为 React 组件添加到项目根组件中，其加载受环境变量控制，从而仅在开发模式下启用。

应用场景

UI 问题准确定位

当开发者在浏览器中发现 UI 样式、布局或交互问题时，可通过 Agentation 进行精准标注，将视觉定位信息与文字反馈整合，生成结构化输出供 AI 编程助手使用。

开发者与 AI 协作

在与 AI 辅助工具（如 Claude Code、Cursor、Windsurf 等）协作修复代码时，Agentation 提供更精确的上下文信息，从而减少 AI 误解和猜测，使 AI 能直接在代码库中定位并生成修复建议。

跨角色协作

设计师可在开发环境中标注设计反馈，生成技术可读的上下文信息；开发者和测试人员可共享这些结构化描述，实现跨团队沟通一致性。

动态页面调试

对于包含复杂过渡和动画的页面，使用动画暂停功能可生成静态标注，从而更准确捕获并反馈问题。

使用指南

安装与集成

1. 在现有 React 项目中运行:

   npm install agentation

    

   或使用 yarn、pnpm、bun 等进行安装。

2. 将组件导入并集成到根组件，建议在开发模式下启用：

   import { Agentation } from "agentation";

    

   并在 NODE_ENV === 'development' 条件下渲染。

启动与标注流程

1. 启动开发服务器并打开浏览器本地页面。

2. 点击悬浮工具栏激活标注模式。

3. 悬停并点击需反馈的元素或文本。

4. 输入反馈说明并生成 Markdown。

5. 复制输出 Markdown 并粘贴到支持文本输入的 AI 工具中。

// 04 常见 问题

// 05 资料 来源