agentation-visual-feedback

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agentation Visual Feedback

Agentation 视觉反馈

Skill by ara.so — AI Agent Skills collection.

Agentation is an agent-agnostic visual feedback tool that helps developers capture precise UI element references for AI coding agents. It provides click-to-annotate functionality with automatic selector identification, text selection, multi-select, and structured markdown output that includes selectors, positions, and context.

由 ara.so 提供的Skill — AI Agent技能合集。

Agentation是一款与Agent无关的视觉反馈工具，可帮助开发者为AI编码Agent捕获精准的UI元素引用。它提供点击标注功能，支持自动选择器识别、文本选择、多选，以及包含选择器、位置和上下文的结构化Markdown输出。

Installation

安装

bash

npm install agentation -D

For other package managers:

bash

yarn add agentation -D

bash

npm install agentation -D

对于其他包管理器：

bash

yarn add agentation -D

or

pnpm add agentation -D

undefined

pnpm add agentation -D

undefined

Basic Usage

基础用法

React Integration

React集成

Add the Agentation component to your app:

tsx

import { Agentation } from 'agentation';

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

在你的应用中添加Agentation组件：

tsx

import { Agentation } from 'agentation';

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

Next.js Integration

Next.js集成

For Next.js apps, wrap in a client component:

tsx

// components/AgentationWrapper.tsx
'use client';

import { Agentation } from 'agentation';

export function AgentationWrapper() {
  return <Agentation />;
}

Then add to your layout or page:

tsx

// app/layout.tsx
import { AgentationWrapper } from '@/components/AgentationWrapper';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <AgentationWrapper />
      </body>
    </html>
  );
}

对于Next.js应用，将其包裹在客户端组件中：

tsx

// components/AgentationWrapper.tsx
'use client';

import { Agentation } from 'agentation';

export function AgentationWrapper() {
  return <Agentation />;
}

然后添加到布局或页面中：

tsx

// app/layout.tsx
import { AgentationWrapper } from '@/components/AgentationWrapper';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <AgentationWrapper />
      </body>
    </html>
  );
}

Conditional Loading (Development Only)

条件加载（仅开发环境）

Only load Agentation in development:

tsx

import { Agentation } from 'agentation';

function App() {
  return (
    <>
      <YourApp />
      {process.env.NODE_ENV === 'development' && <Agentation />}
    </>
  );
}

仅在开发环境中加载Agentation：

tsx

import { Agentation } from 'agentation';

function App() {
  return (
    <>
      <YourApp />
      {process.env.NODE_ENV === 'development' && <Agentation />}
    </>
  );
}

Configuration

配置

Basic Props

基础属性

tsx

<Agentation
  position="bottom-right"  // 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
  theme="auto"            // 'auto' | 'light' | 'dark'
  defaultOpen={false}     // Start with toolbar expanded
/>

tsx

<Agentation
  position="bottom-right"  // 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
  theme="auto"            // 'auto' | 'light' | 'dark'
  defaultOpen={false}     // 初始展开工具栏
/>

Custom Styling

自定义样式

tsx

<Agentation
  style={{
    zIndex: 10000,
    bottom: '20px',
    right: '20px'
  }}
/>

tsx

<Agentation
  style={{
    zIndex: 10000,
    bottom: '20px',
    right: '20px'
  }}
/>

Features & Usage Patterns

功能与使用模式

Click to Annotate

点击标注

Click the Agentation toolbar button (bottom-right by default)
Click any element on the page
Add your feedback/note in the modal
Copy the structured output with selectors

Example output format:

markdown

undefined

点击Agentation工具栏按钮（默认位于右下角）
点击页面上的任意元素
在弹窗中添加反馈/备注
复制包含选择器的结构化输出

示例输出格式：

markdown

undefined

Element: .sidebar > button.primary

元素: .sidebar > button.primary

Selector:

.sidebar > button.primary

Position: x: 120, y: 340 Note: This button should be blue (#0066FF) instead of green

undefined

选择器:

.sidebar > button.primary

位置: x: 120, y: 340 备注: 该按钮应为蓝色（#0066FF）而非绿色

undefined

Text Selection Mode

文本选择模式

Select specific text content for annotation:

Activate Agentation
Click and drag to select text
Add annotation
Get selector + text content in output

选择特定文本内容进行标注：

激活Agentation
点击并拖动选择文本
添加标注
在输出中获取选择器+文本内容

Multi-Select Mode

多选模式

Select multiple related elements at once:

Activate Agentation
Hold Shift (or use multi-select button)
Drag across multiple elements
Annotate all selected elements together

同时选择多个相关元素：

激活Agentation
按住Shift键（或使用多选按钮）
拖动选择多个元素
为所有选中元素统一添加标注

Area Selection

区域选择

Annotate regions or empty space:

Activate Agentation
Enable area mode
Drag to create a selection box
Annotate the entire region

标注区域或空白空间：

激活Agentation
启用区域模式
拖动创建选择框
标注整个区域

Animation Pause

动画暂停

Freeze animations to capture specific states:

Click the pause button in the toolbar
All CSS animations, transitions, JS animations, and videos freeze
Click elements in their paused state
Resume animations when done

tsx

// Agentation automatically pauses:
// - CSS animations and transitions
// - requestAnimationFrame loops
// - Video playback
// - GIF animations

冻结动画以捕获特定状态：

点击工具栏中的暂停按钮
所有CSS动画、过渡效果、JS动画和视频都会冻结
在暂停状态下点击元素
完成后恢复动画

tsx

// Agentation会自动暂停以下内容:
// - CSS动画和过渡效果
// - requestAnimationFrame循环
// - 视频播放
// - GIF动画

Working with AI Agents

与AI Agent协作

Using Structured Output

使用结构化输出

When you copy annotations, Agentation provides:

markdown

undefined

复制标注内容时，Agentation会提供：

markdown

undefined

Feedback Report

反馈报告

Element 1: Navigation Button

元素1: 导航按钮

Selector:

nav.header > button[aria-label="Menu"]

Position: x: 24, y: 16 Classes:

.btn-menu

.mobile-only

Note: Button should have hover state with 0.2s transition

选择器:

nav.header > button[aria-label="Menu"]

位置: x: 24, y: 16 类名:

.btn-menu

.mobile-only

备注: 按钮应添加带有0.2s过渡效果的悬停状态

Element 2: Card Title

元素2: 卡片标题

Selector:

.card-container > .card-header > h3

Position: x: 340, y: 280 Text Content: "Featured Product" Note: Font size should be 24px, currently 18px

undefined

选择器:

.card-container > .card-header > h3

位置: x: 340, y: 280 文本内容: "Featured Product" 备注: 字体大小应为24px，当前为18px

undefined

Providing Feedback to AI Agents

向AI Agent提供反馈

Best practices when using Agentation output with AI agents:

Copy the full structured output - includes selectors agents can grep for
Add specific requirements - color values, spacing, behavior
Reference multiple elements - select related components together
Capture animation states - pause animations at the exact frame you want

Example prompt to AI agent:

Here's feedback from Agentation:

[paste structured output]

Please update these components according to the notes. The selectors provided 
should help you locate the exact code to modify.

将Agentation输出用于AI Agent时的最佳实践：

复制完整的结构化输出 - 包含Agent可识别的选择器
添加具体要求 - 颜色值、间距、行为
关联多个元素 - 同时选择相关组件
捕获动画状态 - 在所需的精确帧处暂停动画

给AI Agent的示例提示：

以下是来自Agentation的反馈:

[粘贴结构化输出]

请根据备注更新这些组件。提供的选择器将帮助你定位需要修改的代码。

TypeScript Support

TypeScript支持

Agentation is written in TypeScript and includes full type definitions:

tsx

import { Agentation } from 'agentation';
import type { AgentationProps } from 'agentation';

const config: AgentationProps = {
  position: 'bottom-right',
  theme: 'dark',
  defaultOpen: false
};

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

Agentation使用TypeScript编写，并包含完整的类型定义：

tsx

import { Agentation } from 'agentation';
import type { AgentationProps } from 'agentation';

const config: AgentationProps = {
  position: 'bottom-right',
  theme: 'dark',
  defaultOpen: false
};

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

Troubleshooting

故障排查

Toolbar Not Visible

工具栏不可见

Issue: Agentation toolbar doesn't appear

Solutions:

Check z-index conflicts - default is 999999
Verify the component is rendered in the DOM
Check for CSS that might hide fixed position elements

tsx

// Increase z-index if needed
<Agentation style={{ zIndex: 10000000 }} />

问题: Agentation工具栏未显示

解决方案:

检查z-index冲突 - 默认值为999999
验证组件是否已渲染到DOM中
检查是否有CSS隐藏了固定定位元素

tsx

// 如有需要，提高z-index
<Agentation style={{ zIndex: 10000000 }} />

Elements Not Selectable

元素无法选择

Issue: Can't click or select certain elements

Solutions:

Check for overlays or modals with higher z-index
Verify elements aren't hidden by pointer-events: none
Try area selection mode for hard-to-click elements

问题: 无法点击或选择某些元素

解决方案:

检查是否有更高z-index的覆盖层或弹窗
验证元素是否被pointer-events: none隐藏
尝试使用区域选择模式选择难以点击的元素

Selectors Too Generic

选择器过于通用

Issue: Generated selectors like

div > div > span

aren't useful

Solutions:

Add meaningful class names to your components
Use semantic HTML elements
Add data attributes for better selector generation

tsx

// Better markup for Agentation
<div className="product-card" data-testid="product-card">
  <h3 className="product-title">Title</h3>
  <button className="add-to-cart-btn">Add to Cart</button>
</div>

问题: 生成的选择器如

div > div > span

实用性低

解决方案:

为组件添加有意义的类名
使用语义化HTML元素
添加数据属性以优化选择器生成

tsx

// 适合Agentation的更优标记
<div className="product-card" data-testid="product-card">
  <h3 className="product-title">Title</h3>
  <button className="add-to-cart-btn">Add to Cart</button>
</div>

Performance Issues

性能问题

Issue: App slows down when Agentation is active

Solutions:

Only load in development environments
Disable animation pause if not needed
Check for extremely deep DOM trees

tsx

// Load only in development
{process.env.NODE_ENV === 'development' && <Agentation />}

问题: 激活Agentation后应用运行变慢

解决方案:

仅在开发环境中加载
如不需要，禁用动画暂停功能
检查是否存在过深的DOM树

tsx

// 仅在开发环境加载
{process.env.NODE_ENV === 'development' && <Agentation />}

Dark Mode Not Matching

深色模式不匹配

Issue: Agentation theme doesn't match app theme

Solutions:

Manually set theme prop
Ensure prefers-color-scheme is set correctly
Check for theme overrides in CSS

tsx

// Force specific theme
<Agentation theme="dark" />

问题: Agentation主题与应用主题不匹配

解决方案:

手动设置theme属性
确保prefers-color-scheme设置正确
检查CSS中的主题覆盖规则

tsx

// 强制设置特定主题
<Agentation theme="dark" />

Browser Support

浏览器支持

Agentation requires:

Modern desktop browser (Chrome, Firefox, Safari, Edge)
JavaScript enabled
No mobile support (desktop only)

Agentation需要：

现代桌面浏览器（Chrome、Firefox、Safari、Edge）
启用JavaScript
不支持移动端（仅桌面端）

Common Integration Patterns

常见集成模式

With Vite

与Vite集成

tsx

// main.tsx
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { Agentation } from 'agentation';
import App from './App';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
    {import.meta.env.DEV && <Agentation />}
  </StrictMode>
);

tsx

// main.tsx
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { Agentation } from 'agentation';
import App from './App';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
    {import.meta.env.DEV && <Agentation />}
  </StrictMode>
);

With Create React App

与Create React App集成

tsx

// index.tsx
import { Agentation } from 'agentation';
import App from './App';

root.render(
  <React.StrictMode>
    <App />
    {process.env.NODE_ENV === 'development' && <Agentation />}
  </React.StrictMode>
);

tsx

// index.tsx
import { Agentation } from 'agentation';
import App from './App';

root.render(
  <React.StrictMode>
    <App />
    {process.env.NODE_ENV === 'development' && <Agentation />}
  </React.StrictMode>
);

With Remix

与Remix集成

tsx

// app/root.tsx
import { Agentation } from 'agentation';

export default function App() {
  return (
    <html>
      <head>
        <Meta />
        <Links />
      </head>
      <body>
        <Outlet />
        <ScrollRestoration />
        <Scripts />
        <LiveReload />
        {process.env.NODE_ENV === 'development' && <Agentation />}
      </body>
    </html>
  );
}

tsx

// app/root.tsx
import { Agentation } from 'agentation';

export default function App() {
  return (
    <html>
      <head>
        <Meta />
        <Links />
      </head>
      <body>
        <Outlet />
        <ScrollRestoration />
        <Scripts />
        <LiveReload />
        {process.env.NODE_ENV === 'development' && <Agentation />}
      </body>
    </html>
  );
}

License

许可证

PolyForm Shield 1.0.0 - Free for non-commercial use. Check the license for commercial usage terms.

PolyForm Shield 1.0.0 - 非商业使用免费。商业使用请查看许可证条款。