agentation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

agentation — Visual UI Feedback Bridge for AI Agents

agentation — 面向AI Agent的可视化UI反馈桥接工具

The missing link between human eyes and agent code.
Instead of describing "the blue button in the sidebar," you hand the agent
.sidebar > button.primary
. It can
grep
for that directly.

连接人类视觉与Agent代码的缺失环节。
无需描述“侧边栏中的蓝色按钮”，只需将
.sidebar > button.primary
交给Agent，它就能直接用
grep
定位代码。

When to use this skill

适用场景

Human needs to point at a UI element and give feedback — without writing selectors
Running iterative UI/UX review cycles between human and coding agent
Building a watch-loop where agent auto-fixes every annotation a human leaves
Capturing CSS selectors, bounding boxes, and React component trees for precise code targeting
Autonomous design critique via
```
agent-browser
```
+ self-driving pattern
Integrating visual feedback into agent hooks so annotations auto-appear in agent context

人类需要指向UI元素并提供反馈，无需编写选择器
在人类与编码Agent之间开展迭代式UI/UX评审循环
构建监听循环，让Agent自动修复人类留下的每一条标注
捕获CSS选择器、边界框和React组件树，实现精准代码定位
通过
```
agent-browser
```
结合自主模式实现自动化设计评审
将视觉反馈集成到Agent钩子中，使标注自动出现在Agent的上下文里

1. Architecture

1. 架构

agentation (monorepo)
├── agentation          → npm: agentation (React toolbar component)
│   └── src/index.ts   → exports Agentation component + types + utilities
└── agentation-mcp      → npm: agentation-mcp (MCP server + CLI)
    ├── src/cli.ts      → agentation-mcp CLI (init, server, doctor)
    └── src/server/     → HTTP REST API (port 4747) + SSE events + MCP stdio tools

Two modes of operation:

Mode	How it works
Copy-Paste	Human annotates → clicks Copy → pastes markdown into agent chat
Agent Sync	`endpoint` prop connects toolbar to MCP server → agent uses `agentation_watch_annotations` loop

agentation (monorepo)
├── agentation          → npm: agentation (React toolbar component)
│   └── src/index.ts   → exports Agentation component + types + utilities
└── agentation-mcp      → npm: agentation-mcp (MCP server + CLI)
    ├── src/cli.ts      → agentation-mcp CLI (init, server, doctor)
    └── src/server/     → HTTP REST API (port 4747) + SSE events + MCP stdio tools

两种运行模式：

模式	工作原理
复制粘贴	人类完成标注 → 点击复制 → 将Markdown粘贴到Agent对话窗口
Agent同步	通过 `endpoint` 属性将工具栏连接到MCP服务器 → Agent使用 `agentation_watch_annotations` 循环

2. Installation

2. 安装

bash

undefined

bash

undefined

React toolbar (dev dependency)

npm install agentation -D

or

pnpm add agentation -D

MCP server (for agent integration)

npm install agentation-mcp -D

or

pnpm add agentation-mcp -D


**Requirements**: React 18+, Node.js 18+, desktop browser (no mobile support)

---

pnpm add agentation-mcp -D


**系统要求**：React 18+、Node.js 18+、桌面浏览器（不支持移动端）

---

3. React Component Setup

3. React组件配置

Basic (Copy-Paste mode — no server needed)

基础配置（复制粘贴模式 — 无需服务器）

tsx

import { Agentation } from 'agentation';

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

tsx

import { Agentation } from 'agentation';

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

Next.js App Router

Next.js App Router配置

tsx

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

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        {children}
        {process.env.NODE_ENV === 'development' && (
          <Agentation endpoint="http://localhost:4747" />
        )}
      </body>
    </html>
  );
}

tsx

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

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        {children}
        {process.env.NODE_ENV === 'development' && (
          <Agentation endpoint="http://localhost:4747" />
        )}
      </body>
    </html>
  );
}

Next.js Pages Router

Next.js Pages Router配置

tsx

// pages/_app.tsx
import { Agentation } from 'agentation';

export default function App({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      {process.env.NODE_ENV === 'development' && (
        <Agentation endpoint="http://localhost:4747" />
      )}
    </>
  );
}

tsx

// pages/_app.tsx
import { Agentation } from 'agentation';

export default function App({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      {process.env.NODE_ENV === 'development' && (
        <Agentation endpoint="http://localhost:4747" />
      )}
    </>
  );
}

Full Props Reference

完整属性参考

Prop	Type	Default	Description
`endpoint`	`string`	—	MCP server URL for Agent Sync mode
`sessionId`	`string`	—	Pre-existing session ID to join
`onAnnotationAdd`	`(a: Annotation) => void`	—	Callback when annotation created
`onAnnotationDelete`	`(a: Annotation) => void`	—	Callback when annotation deleted
`onAnnotationUpdate`	`(a: Annotation) => void`	—	Callback when annotation edited
`onAnnotationsClear`	`(a: Annotation[]) => void`	—	Callback when all cleared
`onCopy`	`(markdown: string) => void`	—	Callback with markdown on copy
`onSubmit`	`(output: string, annotations: Annotation[]) => void`	—	On "Send Annotations" click
`copyToClipboard`	`boolean`	`true`	Set false to suppress clipboard write
`onSessionCreated`	`(sessionId: string) => void`	—	Called on new session creation
`webhookUrl`	`string`	—	Webhook URL to receive annotation events

属性	类型	默认值	说明
`endpoint`	`string`	—	Agent同步模式下的MCP服务器地址
`sessionId`	`string`	—	预先生成的会话ID，用于加入现有会话
`onAnnotationAdd`	`(a: Annotation) => void`	—	创建标注时的回调函数
`onAnnotationDelete`	`(a: Annotation) => void`	—	删除标注时的回调函数
`onAnnotationUpdate`	`(a: Annotation) => void`	—	编辑标注时的回调函数
`onAnnotationsClear`	`(a: Annotation[]) => void`	—	清空所有标注时的回调函数
`onCopy`	`(markdown: string) => void`	—	复制操作完成时的回调函数，返回Markdown内容
`onSubmit`	`(output: string, annotations: Annotation[]) => void`	—	点击“发送标注”按钮时的回调函数
`copyToClipboard`	`boolean`	`true`	设置为false可禁用自动复制到剪贴板
`onSessionCreated`	`(sessionId: string) => void`	—	创建新会话时的回调函数
`webhookUrl`	`string`	—	接收标注事件的Webhook地址

4. MCP Server Setup — All Platforms

4. MCP服务器配置 — 全平台支持

Start the server first before configuring any agent:

bash

npx agentation-mcp server          # HTTP :4747 + MCP stdio
npx agentation-mcp server --port 8080   # custom port
npx agentation-mcp doctor          # verify setup

配置Agent前请先启动服务器：

bash

npx agentation-mcp server          # HTTP :4747 + MCP stdio
npx agentation-mcp server --port 8080   # 自定义端口
npx agentation-mcp doctor          # 验证配置

Claude Code (

.claude/

)

Claude Code (

.claude/

)

Option A — CLI (recommended):

bash

claude mcp add agentation -- npx -y agentation-mcp server

Option B — config file (

~/.claude/claude_desktop_config.json

for global, or

.claude/mcp.json

for project-level):

json

{
  "mcpServers": {
    "agentation": {
      "command": "npx",
      "args": ["-y", "agentation-mcp", "server"]
    }
  }
}

Interactive wizard (Claude Code only):

bash

npx agentation-mcp init

UserPromptSubmit hook — auto-inject pending annotations on every message. Add to

.claude/settings.json

(project) or

~/.claude/settings.json

(global):

json

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "type": "command",
        "command": "curl -sf --connect-timeout 1 http://localhost:4747/pending 2>/dev/null | python3 -c \"import sys,json;d=json.load(sys.stdin);c=d['count'];exit(0)if c==0 else[print(f'\\n=== AGENTATION: {c} UI annotations ===\\n'),*[print(f\\\"[{i+1}] {a['element']} ({a['elementPath']})\\n    {a['comment']}\\n\\\")for i,a in enumerate(d['annotations'])],print('=== END ===\\n')]\" 2>/dev/null;exit 0"
      }
    ]
  }
}

选项A — CLI（推荐）：

bash

claude mcp add agentation -- npx -y agentation-mcp server

选项B — 配置文件（全局配置：

~/.claude/claude_desktop_config.json

，项目级配置：

.claude/mcp.json

）：

json

{
  "mcpServers": {
    "agentation": {
      "command": "npx",
      "args": ["-y", "agentation-mcp", "server"]
    }
  }
}

交互式向导（仅支持Claude Code）：

bash

npx agentation-mcp init

UserPromptSubmit钩子 — 每条消息自动注入待处理标注。添加到项目级

.claude/settings.json

或全局

~/.claude/settings.json

：

json

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "type": "command",
        "command": "curl -sf --connect-timeout 1 http://localhost:4747/pending 2>/dev/null | python3 -c \"import sys,json;d=json.load(sys.stdin);c=d['count'];exit(0)if c==0 else[print(f'\\n=== AGENTATION: {c} UI annotations ===\\n'),*[print(f\\\"[{i+1}] {a['element']} ({a['elementPath']})\\n    {a['comment']}\\n\\\")for i,a in enumerate(d['annotations'])],print('=== END ===\\n')]\" 2>/dev/null;exit 0"
      }
    ]
  }
}

Codex CLI (

~/.codex/

)

Codex CLI (

~/.codex/

)

Add to

~/.codex/config.toml

toml

undefined

添加到

~/.codex/config.toml

：

toml

undefined

Agentation MCP Server

[[mcp_servers]] name = "agentation" command = "npx" args = ["-y", "agentation-mcp", "server"]

Optional: teach Codex about watch-loop

developer_instructions = """ When user says "watch mode" or "agentation watch", call agentation_watch_annotations in a loop. For each annotation: acknowledge it, fix the code using the elementPath CSS selector, resolve with summary. """


Restart Codex CLI after editing `config.toml`.

---


编辑`config.toml`后重启Codex CLI。

---

Gemini CLI (

~/.gemini/

)

Gemini CLI (

~/.gemini/

)

Option A — CLI:

bash

gemini mcp add agentation npx -y agentation-mcp server

选项A — CLI：

bash

gemini mcp add agentation npx -y agentation-mcp server

or with explicit scope

gemini mcp add -s user agentation npx -y agentation-mcp server


**Option B — config file** (`~/.gemini/settings.json` for global, `.gemini/settings.json` for project):
```json
{
  "mcpServers": {
    "agentation": {
      "command": "npx",
      "args": ["-y", "agentation-mcp", "server"]
    }
  }
}

AfterAgent hook — trigger annotation check after each agent turn:

json

{
  "mcpServers": {
    "agentation": {
      "command": "npx",
      "args": ["-y", "agentation-mcp", "server"]
    }
  },
  "hooks": {
    "AfterAgent": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "curl -sf --connect-timeout 1 http://localhost:4747/pending 2>/dev/null | python3 -c \"import sys,json;d=json.load(sys.stdin);c=d.get('count',0);[print(f'[agentation] {c} pending annotations'),exit(1)]if c>0 else exit(0)\" 2>/dev/null;exit 0",
            "description": "Check for pending agentation annotations"
          }
        ]
      }
    ]
  }
}

gemini mcp add -s user agentation npx -y agentation-mcp server


**选项B — 配置文件**（全局配置：`~/.gemini/settings.json`，项目级配置：`.gemini/settings.json`）：
```json
{
  "mcpServers": {
    "agentation": {
      "command": "npx",
      "args": ["-y", "agentation-mcp", "server"]
    }
  }
}

AfterAgent钩子 — 每次Agent响应后检查标注：

json

{
  "mcpServers": {
    "agentation": {
      "command": "npx",
      "args": ["-y", "agentation-mcp", "server"]
    }
  },
  "hooks": {
    "AfterAgent": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "curl -sf --connect-timeout 1 http://localhost:4747/pending 2>/dev/null | python3 -c \"import sys,json;d=json.load(sys.stdin);c=d.get('count',0);[print(f'[agentation] {c} pending annotations'),exit(1)]if c>0 else exit(0)\" 2>/dev/null;exit 0",
            "description": "Check for pending agentation annotations"
          }
        ]
      }
    ]
  }
}

OpenCode (

~/.config/opencode/

)

OpenCode (

~/.config/opencode/

)

Add to

~/.config/opencode/opencode.json

json

{
  "mcp": {
    "agentation": {
      "type": "local",
      "command": ["npx", "-y", "agentation-mcp", "server"]
    }
  }
}

With environment variables:

json

{
  "mcp": {
    "agentation": {
      "type": "local",
      "command": ["npx", "-y", "agentation-mcp", "server"],
      "environment": {
        "AGENTATION_STORE": "sqlite",
        "AGENTATION_EVENT_RETENTION_DAYS": "7"
      }
    }
  }
}

Restart OpenCode after editing. MCP tools (

agentation_*

) will be available immediately.

添加到

~/.config/opencode/opencode.json

：

json

{
  "mcp": {
    "agentation": {
      "type": "local",
      "command": ["npx", "-y", "agentation-mcp", "server"]
    }
  }
}

结合环境变量：

json

{
  "mcp": {
    "agentation": {
      "type": "local",
      "command": ["npx", "-y", "agentation-mcp", "server"],
      "environment": {
        "AGENTATION_STORE": "sqlite",
        "AGENTATION_EVENT_RETENTION_DAYS": "7"
      }
    }
  }
}

编辑后重启OpenCode，MCP工具(

agentation_*

)将立即可用。

Universal (npx add-mcp)

通用方式（npx add-mcp）

Works for any MCP-compatible agent:

bash

npx add-mcp "npx -y agentation-mcp server"

适用于所有兼容MCP的Agent：

bash

npx add-mcp "npx -y agentation-mcp server"

Quick-Setup Script

快速设置脚本

Save and run

bash setup-agentation-mcp.sh [--all | --claude | --codex | --gemini | --opencode]

bash

#!/usr/bin/env bash

保存并运行

bash setup-agentation-mcp.sh [--all | --claude | --codex | --gemini | --opencode]

：

bash

#!/usr/bin/env bash

setup-agentation-mcp.sh — Register agentation MCP for all agent platforms

set -euo pipefail SETUP_CLAUDE=false; SETUP_CODEX=false; SETUP_GEMINI=false; SETUP_OPENCODE=false

while [[ $# -gt 0 ]]; do case "$1" in --claude) SETUP_CLAUDE=true ;; --codex) SETUP_CODEX=true ;; --gemini) SETUP_GEMINI=true ;; --opencode) SETUP_OPENCODE=true ;; --all) SETUP_CLAUDE=true; SETUP_CODEX=true; SETUP_GEMINI=true; SETUP_OPENCODE=true ;; esac shift done [[ "$SETUP_CLAUDE$SETUP_CODEX$SETUP_GEMINI$SETUP_OPENCODE" == "falsefalsefalsefalse" ]] &&
SETUP_CLAUDE=true && SETUP_CODEX=true && SETUP_GEMINI=true && SETUP_OPENCODE=true

MCP_JSON='"agentation": {"command": "npx", "args": ["-y", "agentation-mcp", "server"]}'

set -euo pipefail SETUP_CLAUDE=false; SETUP_CODEX=false; SETUP_GEMINI=false; SETUP_OPENCODE=false

MCP_JSON='"agentation": {"command": "npx", "args": ["-y", "agentation-mcp", "server"]}'

Claude Code

if [[ "$SETUP_CLAUDE" == "true" ]]; then mkdir -p ~~/.claude CFG=~~/.claude/claude_desktop_config.json if [[ -f "$CFG" ]] && command -v jq &>/dev/null; then jq ".mcpServers += {$MCP_JSON}" "$CFG" > "$CFG.tmp" && mv "$CFG.tmp" "$CFG" else echo "{"mcpServers": {$MCP_JSON}}" > "$CFG" fi echo "✅ Claude Code: $CFG" fi

Codex CLI

if [[ "$SETUP_CODEX" == "true" ]]; then mkdir -p ~~/.codex CFG=~~/.codex/config.toml if ! grep -q "agentation" "$CFG" 2>/dev/null; then printf '\n[[mcp_servers]]\nname = "agentation"\ncommand = "npx"\nargs = ["-y", "agentation-mcp", "server"]\n' >> "$CFG" fi echo "✅ Codex CLI: $CFG" fi

Gemini CLI

if [[ "$SETUP_GEMINI" == "true" ]]; then mkdir -p ~~/.gemini CFG=~~/.gemini/settings.json if [[ -f "$CFG" ]] && command -v jq &>/dev/null; then jq ".mcpServers += {$MCP_JSON}" "$CFG" > "$CFG.tmp" && mv "$CFG.tmp" "$CFG" else echo "{"mcpServers": {$MCP_JSON}}" > "$CFG" fi echo "✅ Gemini CLI: $CFG" fi

OpenCode

if [[ "$SETUP_OPENCODE" == "true" ]]; then mkdir -p ~~/.config/opencode CFG=~~/.config/opencode/opencode.json ENTRY='"agentation": {"type": "local", "command": ["npx", "-y", "agentation-mcp", "server"]}' if [[ -f "$CFG" ]] && command -v jq &>/dev/null; then jq ".mcp += {$ENTRY}" "$CFG" > "$CFG.tmp" && mv "$CFG.tmp" "$CFG" else echo "{"mcp": {$ENTRY}}" > "$CFG" fi echo "✅ OpenCode: $CFG" fi

echo "" echo "Done. Restart your agent(s) and run: npx agentation-mcp server"

---

echo "" echo "Done. Restart your agent(s) and run: npx agentation-mcp server"

---

5. MCP Tools (Agent API)

5. MCP工具（Agent API）

Tool	Parameters	Description
`agentation_list_sessions`	none	List all active annotation sessions
`agentation_get_session`	`sessionId: string`	Get session with all annotations
`agentation_get_pending`	`sessionId: string`	Get pending annotations for a session
`agentation_get_all_pending`	none	Get pending annotations across ALL sessions
`agentation_acknowledge`	`annotationId: string`	Mark annotation as acknowledged (agent is working on it)
`agentation_resolve`	`annotationId: string, summary?: string`	Mark as resolved with optional summary
`agentation_dismiss`	`annotationId: string, reason: string`	Dismiss with required reason
`agentation_reply`	`annotationId: string, message: string`	Add reply to annotation thread
`agentation_watch_annotations`	`sessionId?: string, batchWindowSeconds?: number (default 10, max 60), timeoutSeconds?: number (default 120, max 300)`	Block until new annotations arrive — core watch-loop tool

工具	参数	说明
`agentation_list_sessions`	无	列出所有活跃的标注会话
`agentation_get_session`	`sessionId: string`	获取指定会话及其所有标注
`agentation_get_pending`	`sessionId: string`	获取指定会话的待处理标注
`agentation_get_all_pending`	无	获取所有会话的待处理标注
`agentation_acknowledge`	`annotationId: string`	将标注标记为已确认（表示Agent正在处理）
`agentation_resolve`	`annotationId: string, summary?: string`	将标注标记为已解决，可选添加总结
`agentation_dismiss`	`annotationId: string, reason: string`	驳回标注，需填写原因
`agentation_reply`	`annotationId: string, message: string`	为标注添加回复
`agentation_watch_annotations`	`sessionId?: string, batchWindowSeconds?: number (default 10, max 60), timeoutSeconds?: number (default 120, max 300)`	阻塞直到新标注到来 — 核心监听循环工具

6. Workflow Patterns

6. 工作流模式

Pattern 1: Copy-Paste (Simplest, No Server)

模式1：复制粘贴（最简单，无需服务器）

1. Human opens app in browser
2. Clicks agentation toolbar → activates
3. Clicks element → adds comment → clicks Copy
4. Pastes markdown output into agent chat
5. Agent receives CSS selectors, elementPath, boundingBox
6. Agent greps/edits code using selector

1. 人类在浏览器中打开应用
2. 点击agentation工具栏 → 激活标注功能
3. 点击目标元素 → 添加评论 → 点击复制
4. 将Markdown输出粘贴到Agent对话窗口
5. Agent获取CSS选择器、elementPath、边界框信息
6. Agent使用选择器搜索/编辑代码

Pattern 2: MCP Watch Loop (Recommended for iterative review)

模式2：MCP监听循环（迭代评审推荐方案）

Agent: agentation_watch_annotations (blocks up to 120s)
  → Human adds annotation in browser
  → Agent receives batch immediately
  → Agent: agentation_acknowledge(annotationId)
  → Agent makes code changes using elementPath as grep target
  → Agent: agentation_resolve(annotationId, "Changed button color to #3b82f6")
  → Agent: agentation_watch_annotations (loops again)

CLAUDE.md / GEMINI.md / Codex developer_instructions — add for automated watch:

markdown

When I say "watch mode" or "agentation watch", call agentation_watch_annotations in a loop.
For each annotation received:
  1. Call agentation_acknowledge(annotationId)
  2. Use elementPath to locate the code: Grep(elementPath) or search codebase for CSS class
  3. Make the minimal change described in the comment
  4. Call agentation_resolve(annotationId, "<brief summary of what was changed>")
Continue watching until I say stop, or until timeout.

Agent: agentation_watch_annotations (最多阻塞120秒)
  → 人类在浏览器中添加标注
  → Agent立即收到标注批量
  → Agent: agentation_acknowledge(annotationId)
  → Agent使用elementPath作为搜索目标修改代码
  → Agent: agentation_resolve(annotationId, "Changed button color to #3b82f6")
  → Agent: agentation_watch_annotations（循环执行）

CLAUDE.md / GEMINI.md / Codex开发指南 — 添加自动化监听规则：

markdown

当用户说"watch mode"或"agentation watch"时，循环调用agentation_watch_annotations。
对于每个标注：确认接收，使用elementPath CSS选择器修复代码，完成后添加总结并标记为已解决。

Pattern 3: Platform-Specific Hook (Passive Injection)

模式3：平台专属钩子（被动注入）

The hook from Section 4 auto-appends pending annotations to every agent message — no "watch mode" needed. Works across all platforms.

第4节中的钩子会在每条Agent消息后自动附加待处理标注，无需手动开启"watch mode"，适用于所有平台。

Pattern 4: Autonomous Self-Driving Critique

模式4：全自动自主评审

Two-agent setup for fully autonomous UI review cycles:

Session 1 (Critic — uses
agent-browser
):

bash

undefined

双Agent配置实现完全自动化的UI评审循环：

会话1（评审Agent — 使用
agent-browser
）：

bash

undefined

Start headed browser pointing at your dev server

启动有头浏览器指向开发服务器

agent-browser open http://localhost:3000 agent-browser snapshot -i

Agent navigates, clicks elements via agentation toolbar, adds critique

Agent导航页面，通过agentation工具栏点击元素并添加评审意见

Annotations flow to agentation MCP server automatically

标注将自动同步到agentation MCP服务器


**Session 2 (Fixer — watches MCP):**

agentation_watch_annotations → receives critique → acknowledge → edit → resolve → loop

undefined


**会话2（修复Agent — 监听MCP）：**

agentation_watch_annotations → 接收评审意见 → 确认 → 编辑代码 → 解决 → 循环

undefined

Pattern 5: Webhook Integration

模式5：Webhook集成

tsx

<Agentation webhookUrl="https://your-server.com/webhook" />

tsx

<Agentation webhookUrl="https://your-server.com/webhook" />

or env var:

或使用环境变量:

AGENTATION_WEBHOOK_URL=https://your-server.com/webhook

---

---

7. Annotation Type (Full Schema)

7. 标注类型（完整Schema）

typescript

type Annotation = {
  // Core
  id: string;
  x: number;            // % of viewport width (0-100)
  y: number;            // px from document top
  comment: string;      // User's feedback text
  element: string;      // Tag name: "button", "div", etc.
  elementPath: string;  // CSS selector: "body > main > button.cta"  ← grep target
  timestamp: number;

  // Context
  selectedText?: string;
  boundingBox?: { x: number; y: number; width: number; height: number };
  nearbyText?: string;
  cssClasses?: string;
  nearbyElements?: string;
  computedStyles?: string;
  fullPath?: string;
  accessibility?: string;
  reactComponents?: string;  // "App > Dashboard > Button"  ← component grep target
  isMultiSelect?: boolean;
  isFixed?: boolean;

  // Lifecycle (server-synced)
  sessionId?: string;
  url?: string;
  intent?: "fix" | "change" | "question" | "approve";
  severity?: "blocking" | "important" | "suggestion";
  status?: "pending" | "acknowledged" | "resolved" | "dismissed";
  thread?: ThreadMessage[];
  createdAt?: string;
  updatedAt?: string;
  resolvedAt?: string;
  resolvedBy?: "human" | "agent";
};

Annotation lifecycle:

pending → acknowledged → resolved
                      ↘ dismissed (requires reason)

typescript

type Annotation = {
  // 核心字段
  id: string;
  x: number;            // 视口宽度占比（0-100）
  y: number;            // 距文档顶部的像素距离
  comment: string;      // 用户反馈文本
  element: string;      // 标签名："button"、"div"等
  elementPath: string;  // CSS选择器："body > main > button.cta"  ← 代码搜索目标
  timestamp: number;

  // 上下文信息
  selectedText?: string;
  boundingBox?: { x: number; y: number; width: number; height: number };
  nearbyText?: string;
  cssClasses?: string;
  nearbyElements?: string;
  computedStyles?: string;
  fullPath?: string;
  accessibility?: string;
  reactComponents?: string;  // "App > Dashboard > Button"  ← 组件搜索目标
  isMultiSelect?: boolean;
  isFixed?: boolean;

  // 生命周期（服务器同步）
  sessionId?: string;
  url?: string;
  intent?: "fix" | "change" | "question" | "approve";
  severity?: "blocking" | "important" | "suggestion";
  status?: "pending" | "acknowledged" | "resolved" | "dismissed";
  thread?: ThreadMessage[];
  createdAt?: string;
  updatedAt?: string;
  resolvedAt?: string;
  resolvedBy?: "human" | "agent";
};

标注生命周期：

待处理 → 已确认 → 已解决
                ↘ 已驳回（需填写原因）

8. HTTP REST API (port 4747)

8. HTTP REST API（端口4747）

bash

undefined

bash

undefined

Sessions

会话管理

POST /sessions # Create session GET /sessions # List all sessions GET /sessions/:id # Get session + annotations

POST /sessions # 创建会话 GET /sessions # 列出所有会话 GET /sessions/:id # 获取指定会话及标注

Annotations

标注管理

POST /sessions/:id/annotations # Add annotation GET /annotations/:id # Get annotation PATCH /annotations/:id # Update annotation DELETE /annotations/:id # Delete annotation GET /sessions/:id/pending # Pending for session GET /pending # ALL pending across sessions

POST /sessions/:id/annotations # 添加标注 GET /annotations/:id # 获取指定标注 PATCH /annotations/:id # 更新标注 DELETE /annotations/:id # 删除标注 GET /sessions/:id/pending # 获取指定会话的待处理标注 GET /pending # 获取所有会话的待处理标注

Events (SSE streaming)

事件流（SSE）

GET /sessions/:id/events # Session stream GET /events # Global stream (?domain=filter)

GET /sessions/:id/events # 指定会话的事件流 GET /events # 全局事件流（可通过?domain=过滤）

Health

健康检查

GET /health GET /status

---

GET /health GET /status

---

9. Environment Variables

9. 环境变量

Variable	Description	Default
`AGENTATION_STORE`	`memory` or `sqlite`	`sqlite`
`AGENTATION_WEBHOOK_URL`	Single webhook URL	—
`AGENTATION_WEBHOOKS`	Comma-separated webhook URLs	—
`AGENTATION_EVENT_RETENTION_DAYS`	Days to keep events	`7`

SQLite storage:

~/.agentation/store.db

变量名	说明	默认值
`AGENTATION_STORE`	存储类型，可选 `memory` 或 `sqlite`	`sqlite`
`AGENTATION_WEBHOOK_URL`	单个Webhook地址	—
`AGENTATION_WEBHOOKS`	逗号分隔的多个Webhook地址	—
`AGENTATION_EVENT_RETENTION_DAYS`	事件保留天数	`7`

SQLite存储路径：

~/.agentation/store.db

10. Programmatic Utilities

10. 编程工具函数

typescript

import {
  identifyElement, identifyAnimationElement,
  getElementPath, getNearbyText, getElementClasses,
  isInShadowDOM, getShadowHost, closestCrossingShadow,
  loadAnnotations, saveAnnotations, getStorageKey,
  type Annotation, type Session, type ThreadMessage,
} from 'agentation';

typescript

import {
  identifyElement, identifyAnimationElement,
  getElementPath, getNearbyText, getElementClasses,
  isInShadowDOM, getShadowHost, closestCrossingShadow,
  loadAnnotations, saveAnnotations, getStorageKey,
  type Annotation, type Session, type ThreadMessage,
} from 'agentation';

11. Platform Support Matrix

11. 平台支持矩阵

Platform	Config File	MCP Key	Hook
Claude Code	`~/.claude/claude_desktop_config.json`	`mcpServers`	`hooks.UserPromptSubmit` in `settings.json`
Codex CLI	`~/.codex/config.toml`	`[[mcp_servers]]` (TOML)	`developer_instructions` + `notify`
Gemini CLI	`~/.gemini/settings.json`	`mcpServers`	`hooks.AfterAgent` in `settings.json`
OpenCode	`~/.config/opencode/opencode.json`	`mcp` ( `type: "local"` )	Skills system (no hook needed)
Cursor / Windsurf	`.cursor/mcp.json` / `.windsurf/mcp.json`	`mcpServers`	—

平台	配置文件	MCP配置键	钩子
Claude Code	`~/.claude/claude_desktop_config.json`	`mcpServers`	`settings.json` 中的 `hooks.UserPromptSubmit`
Codex CLI	`~/.codex/config.toml`	`[[mcp_servers]]` (TOML格式)	`developer_instructions` + `notify`
Gemini CLI	`~/.gemini/settings.json`	`mcpServers`	`settings.json` 中的 `hooks.AfterAgent`
OpenCode	`~/.config/opencode/opencode.json`	`mcp` ( `type: "local"` )	技能系统（无需钩子）
Cursor / Windsurf	`.cursor/mcp.json` / `.windsurf/mcp.json`	`mcpServers`	—

Best practices

最佳实践

Always gate
```
<Agentation>
```
with
```
NODE_ENV === 'development'
```
— never ship to production
Use MCP watch-loop over copy-paste for iterative cycles — eliminates context switching
Call
```
agentation_acknowledge
```
immediately when starting a fix — signals human
Include a
```
summary
```
in
```
agentation_resolve
```
— gives human traceability
Process
```
severity: "blocking"
```
annotations first in the watch loop
Use
```
elementPath
```
as the primary grep/search target in code — it's a valid CSS selector
Use
```
reactComponents
```
field when the codebase is React — matches component names directly
Add the appropriate hook for your platform (Section 4) for zero-friction passive injection
For autonomous self-driving, use
```
agent-browser
```
in headed mode with
```
agentation
```
mounted

始终用
```
NODE_ENV === 'development'
```
限制
```
<Agentation>
```
的加载——绝不要部署到生产环境
迭代循环中优先使用MCP监听循环而非复制粘贴——减少上下文切换
开始修复时立即调用
```
agentation_acknowledge
```
——向人类发送处理中信号
在
```
agentation_resolve
```
中添加
```
summary
```
——为人类提供可追溯的修复记录
在监听循环中优先处理
```
severity: "blocking"
```
（阻塞级）的标注
将
```
elementPath
```
作为代码中主要的搜索定位目标——它是合法的CSS选择器
当代码库为React时，使用
```
reactComponents
```
字段——可直接匹配组件名称
为你的平台添加合适的钩子（第4节），实现无感知的被动注入
若要实现全自动自主评审，需在有头模式下运行
```
agent-browser
```
并挂载
```
agentation
```

12. jeo Integration (agentui keyword)

12. jeo集成（agentui关键字）

agentation은 jeo 스킬의 VERIFY_UI 단계로 통합됩니다. plannotator가
planui
/
ExitPlanMode
에서 동작하는 방식과 동일한 패턴입니다.

agentation已集成到jeo技能的VERIFY_UI阶段。其工作模式与plannotator在
planui
/
ExitPlanMode
中的运行模式一致。

엄게나 작동 방식

工作方式

plannotator (planui):         agentation (agentui):
plan.md 작성                   앱 UI에 <Agentation> 마운트
    ↓ 블로킹                        ↓ 블로킹
plannotator 실행            agentation_watch_annotations
    ↓                              ↓
UI에서 Approve/Feedback       UI에서 어노테이션 생성
    ↓                              ↓
approved:true 확인             annotation ack→fix→resolve
    ↓                              ↓
EXECUTE 진입                  다음 단계 또는 루프

plannotator (planui):         agentation (agentui):
编写plan.md                   在应用UI中挂载<Agentation>
    ↓ 阻塞                         ↓ 阻塞
运行plannotator            调用agentation_watch_annotations
    ↓                              ↓
在UI中点击Approve/Feedback       在UI中创建标注
    ↓                              ↓
确认approved:true             标注 确认→修复→解决
    ↓                              ↓
进入EXECUTE阶段                进入下一阶段或循环

트리거 키워드

触发关键字

키워드	플랫폼	동작
`agentui`	Claude Code	`agentation_watch_annotations` MCP 블로킹 호출
`agentui`	Codex	`AGENTUI_READY` 신호 → `jeo-notify.py` HTTP 폴링
`agentui`	Gemini	GEMINI.md 지시: HTTP REST 폴링 패턴
`/jeo-agentui`	OpenCode	opencode.json `mcp.agentation` + 지시사항

关键字	平台	动作
`agentui`	Claude Code	阻塞式调用 `agentation_watch_annotations` MCP工具
`agentui`	Codex	发送 `AGENTUI_READY` 信号 → `jeo-notify.py` 执行HTTP轮询
`agentui`	Gemini	按照GEMINI.md指示：执行HTTP REST轮询模式
`/jeo-agentui`	OpenCode	读取opencode.json中的 `mcp.agentation` 配置 + 执行相关指令

jeo에서 사용하기

在jeo中使用

bash

undefined

bash

undefined

1. jeo 실치 시 agentation 자동 등록

1. 安装jeo时自动注册agentation

bash .agent-skills/jeo/scripts/install.sh --with-agentation

또는 전체 설치:

或完整安装:

bash .agent-skills/jeo/scripts/install.sh --all

2. 앱에 agentation 컴포넌트 마운트

2. 在应用中挂载agentation组件

app/layout.tsx 또는 pages/_app.tsx:

编辑app/layout.tsx或pages/_app.tsx:

<Agentation endpoint="http://localhost:4747" />

3. MCP 서버 실행

3. 启动MCP服务器

npx agentation-mcp server

4. 에이전트에서 agentui 키워드 입력 → watch loop 시작

4. 在Agent中输入agentui关键字 → 启动监听循环

Claude Code: MCP 도구 직접 호출

Claude Code: 直接调用MCP工具

Codex: AGENTUI_READY 출력 → notify hook 자동 폴링

Codex: 输出AGENTUI_READY信号 → 通知钩子自动轮询

Gemini: GEMINI.md HTTP 폴링 패턴

Gemini: 按照GEMINI.md执行HTTP轮询模式

OpenCode: /jeo-agentui 슬래시 커맨드

OpenCode: 使用/jeo-agentui斜杠命令

undefined

undefined

평가 플로우 (jeo VERIFY_UI 단계)

评估流程（jeo VERIFY_UI阶段）

jeo "<task>"
    │
[1] PLAN (plannotator loop)    ← plan.md 승인
[2] EXECUTE (team/bmad)
[3] VERIFY
    ├─ agent-browser snapshot
    └─ agentui → VERIFY_UI (agentation loop)   ← 이 단계
[4] CLEANUP

자세한 jeo 통합 내용: jeo SKILL.md Section 3.3.1 상세 워크플로우 확인

jeo "<任务内容>"
    │
[1] 规划阶段（plannotator循环）    ← 确认plan.md
[2] 执行阶段（team/bmad）
[3] 验证阶段
    ├─ agent-browser 截图
    └─ agentui → VERIFY_UI（agentation循环）   ← 当前阶段
[4] 清理阶段

更多jeo集成细节：查看jeo SKILL.md第3.3.1节的详细工作流

References

参考资料

Metadata

元数据

Version: 1.0.0
Source: benjitaylor/agentation (PolyForm Shield 1.0.0)
Packages:
```
agentation@2.2.1
```
,
```
agentation-mcp@1.2.0
```
Last updated: 2026-03-04
Scope: UI annotation bridge for human-agent feedback loops — Claude Code, Codex, Gemini CLI, OpenCode

版本：1.0.0
来源：benjitaylor/agentation（PolyForm Shield 1.0.0协议）
包版本：
```
agentation@2.2.1
```
,
```
agentation-mcp@1.2.0
```
最后更新：2026-03-04
适用范围：人类与Agent反馈循环的UI标注桥接工具 — 支持Claude Code、Codex、Gemini CLI、OpenCode

agentation

Original

Translation

agentation — Visual UI Feedback Bridge for AI Agents

agentation — 面向AI Agent的可视化UI反馈桥接工具

When to use this skill

适用场景

1. Architecture

1. 架构

2. Installation

2. 安装

React toolbar (dev dependency)

React toolbar (dev dependency)

or

or

MCP server (for agent integration)

MCP server (for agent integration)

or

or

3. React Component Setup

3. React组件配置

Basic (Copy-Paste mode — no server needed)

基础配置（复制粘贴模式 — 无需服务器）

Next.js App Router

Next.js App Router配置

Next.js Pages Router

Next.js Pages Router配置

Full Props Reference

完整属性参考

4. MCP Server Setup — All Platforms

4. MCP服务器配置 — 全平台支持

Claude Code (.claude/)

Claude Code (.claude/)

Codex CLI (~/.codex/)

Codex CLI (~/.codex/)

Agentation MCP Server

Agentation MCP Server

Optional: teach Codex about watch-loop

Optional: teach Codex about watch-loop

Gemini CLI (~/.gemini/)

Gemini CLI (~/.gemini/)

or with explicit scope

or with explicit scope

OpenCode (~/.config/opencode/)

OpenCode (~/.config/opencode/)

Universal (npx add-mcp)

通用方式（npx add-mcp）

Quick-Setup Script

快速设置脚本

setup-agentation-mcp.sh — Register agentation MCP for all agent platforms

setup-agentation-mcp.sh — Register agentation MCP for all agent platforms

Claude Code

Claude Code

Codex CLI

Codex CLI

Gemini CLI

Gemini CLI

OpenCode

OpenCode

5. MCP Tools (Agent API)

5. MCP工具（Agent API）

6. Workflow Patterns

6. 工作流模式

Pattern 1: Copy-Paste (Simplest, No Server)

模式1：复制粘贴（最简单，无需服务器）

Pattern 2: MCP Watch Loop (Recommended for iterative review)

模式2：MCP监听循环（迭代评审推荐方案）

Pattern 3: Platform-Specific Hook (Passive Injection)

模式3：平台专属钩子（被动注入）

Pattern 4: Autonomous Self-Driving Critique

模式4：全自动自主评审

Start headed browser pointing at your dev server

启动有头浏览器指向开发服务器

Agent navigates, clicks elements via agentation toolbar, adds critique

Agent导航页面，通过agentation工具栏点击元素并添加评审意见

Annotations flow to agentation MCP server automatically

标注将自动同步到agentation MCP服务器

Pattern 5: Webhook Integration

模式5：Webhook集成

or env var:

Claude Code (
`.claude/`
)

Claude Code (
`.claude/`
)

Codex CLI (
`~/.codex/`
)

Codex CLI (
`~/.codex/`
)

Gemini CLI (
`~/.gemini/`
)

Gemini CLI (
`~/.gemini/`
)

OpenCode (
`~/.config/opencode/`
)

OpenCode (
`~/.config/opencode/`
)