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 工具中。

常见问题（FAQ）

Q1: Agentation 是什么？
A1: Agentation 是一个 React 组件工具，用于网页元素可视化标注并生成结构化 Markdown 反馈，以便 AI 编程助手能够解析并定位对应的代码。

Q2: Agentation 支持哪些 AI 工具？
A2: 任何支持文本输入的 AI 编程助手，例如 Claude Code、Cursor、Github Copilot Workspace 等均可处理生成的 structured Markdown。

Q3: 支持哪些标注模式？
A3: 支持单元素标注、文本选择、多选区域等多种 marker 类型，并可自定义输出复杂度（Compact、Standard、Detailed、Forensic）。

Q4: 是否适合生产环境？
A4: 通常建议仅在开发环境使用，并通过环境变量控制加载逻辑，避免影响生产性能。

Q5: 标注数据是否共享？
A5: 注释存储在浏览器 localStorage 中，因此不会自动共享；如需团队协作，需要复制输出并分发给他人。

术语定义

结构化 Markdown
指包含元素定位参数与反馈说明的格式化文本，便于 AI 工具解析和执行具体修改任务。

CSS 选择器
用于唯一标识网页 DOM 元素的路径表达式，帮助 AI 在代码库中检索对应结构。

可视化标注
指在运行中的网页上通过界面工具直接指定元素并附加反馈信息的操作。