agentation

agentation

agentation 是此仓库中的 渲染 UI 反馈桥接工具。

当人工审核者需要点击实际 UI、将反馈关联到他们所指的确切元素或区域，并将结构化数据包传递给编码 Agent 时，请使用它。它的主要工作是注释路由：选择正确的注释模式，捕获精确证据，然后将修复流程交给合适的相邻技能或 Agent 运行时。

何时使用此技能

当任务需要满足以下一项或多项要求时，请使用 agentation：

• 人工审核者指向真实 UI 元素，而不是含糊地描述它
• 包含选择器、元素路径、边界框或复制的 Markdown 的结构化反馈数据包
• 在浏览器与编码 Agent 之间进行本地复制粘贴审核
• 由 MCP 支持的同步／监视循环，让新注释自动流入 Agent 上下文
• 从渲染 UI 证据开始的自动批判／修复循环
• 为 Claude Code、Codex、Gemini CLI 或 OpenCode 配置平台，以传递待处理的 UI 注释

以下情况不要默认使用 agentation：

• 在新会话中验证浏览器或执行确定性回归检查 → browser-harness
• 复用正在运行、已登录或依赖扩展程序的浏览器 → playwriter
• 审核计划、批准差异，或对提议的产物进行视觉验收 → plannotator
• 没有具体渲染 UI 数据包的通用设计系统、无障碍或启发式审核

快速路由规则

如果任务需要……	使用
人工点击 UI 并为 Agent 留下准确反馈	agentation
在干净、可重复的会话中验证浏览器	browser-harness
用户已打开的浏览器、Cookie 或已登录的标签页	playwriter
执行前审核或批准计划／差异	plannotator

说明

步骤 1：选择正确的注释模式

在处理设置细节之前，先选择一种模式：

模式	适用情况	输出
复制粘贴审核	一位审核者想要标注 UI，并将数据包粘贴到聊天中	结构化 Markdown 数据包
同步监视循环	新注释应自动显示在 Agent 工作流中	待处理注释队列 + 循环
自动批判	Agent／浏览器循环将反复生成或使用注释	审核／修复循环数据包
平台设置	核心问题是将注释桥接工具接入 Claude/Codex/Gemini/OpenCode	设置清单和配置目标

如果任务实质上是“测试网站”或“操作已登录的浏览器”，请先转到其他工具；只有在缺少精确的人工 UI 反馈时，才回到 agentation。

步骤 2：明确浏览器边界

agentation 不会取代浏览器运行时的选择。

• 需要干净、一次性的验证浏览器时，使用 browser-harness。
• 必须复用用户的真实浏览器会话时，使用 playwriter。
• 有了可供人工或循环进行精确注释的渲染页面后，再使用 agentation。

步骤 3：遵循核心循环

1. 准备渲染 UI
   • 如有需要，先选择合适的浏览器／运行时技能。
2. 在开发中的应用中添加 Agentation 工具栏。
3. 选择注释模式：复制粘贴、监视循环、自动批判或设置。
4. 捕获一个具体的 UI 数据包。
5. 将数据包交给编码 Agent。
6. 使用同一审核流程重新验证修复结果。

步骤 4：采用最快且安全的安装方式

对于大多数设置，建议按以下实用顺序操作：

# React toolbar
npm install agentation -D

# MCP bridge / auto-registration for supported agents
npx add-mcp "npx -y agentation-mcp server"

# verify the bridge
npx agentation-mcp doctor

Claude Code 用户也可以在这是最简单的引导方式时，安装上游官方技能：

npx skills add benjitaylor/agentation -g
# then use /agentation in Claude Code

步骤 5：先采用最精简的工具栏集成

从最小但实用的嵌入开始：

import { Agentation } from 'agentation';

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

只有在所选模式确实需要时，才添加 endpoint、回调或 webhook 行为。

步骤 6：选择合适的交接模式

A. 复制粘贴审查

适用于人工正在审查页面，并将反馈包粘贴到 Agent 聊天中的情况。

适用于：

• 快速修复错误或打磨 UI
• 一次性针对性修复
• 低配置协作

B. 同步监视循环

适用于 Agent 需要持续轮询或接收待处理批注的情况。

适用于：

• 多轮 QA/修复
• 设计师 ↔ Agent 协作循环
• 前端工作进行期间的本地审查队列

在信任该循环之前，请先运行随附的验证脚本：

bash .agent-skills/agentation/scripts/verify-loop.sh

C. 自动评审

适用于 Agent/浏览器循环反复审查 UI，且 agentation 是结构化反馈包，而非浏览器运行时本身的情况。

典型流程：

• 浏览器工具捕获当前状态
• agentation 编码具体的反馈目标
• 编码 Agent 应用修复
• 浏览器工具重新检查结果

第 7 步：缩小平台配置范围

如果请求实际涉及平台连接配置，只需回答：

• 配置文件的位置
• 如何注册 agentation-mcp
• 待处理批注如何进入 Agent 循环
• 如何验证配置

将特定于平台的配置块放入参考文档中，避免让主要工作流臃肿。

脚本

优先使用随附脚本，而不是重新输入冗长命令：

脚本	用途
scripts/setup-agentation-mcp.sh	为受支持的 Agent 注册 MCP 桥接
scripts/verify-loop.sh	验证批注队列 / ACK → RESOLVE 风格的监视循环行为

示例

示例 1：人工审查者需要精确的 UI 反馈

• 提示词：“我可以指出损坏的结账按钮，但不想手动描述选择器。”
• 预期行为：选择 agentation，建议使用复制粘贴审查或同步模式，并将浏览器运行时的选择分开处理。

示例 2：浏览器验证才是真正的任务

• 提示词：“运行可重复的无头 UI 回归检查，并比较结果。”
• 预期行为：转到 browser-harness，而不是 agentation，除非后续步骤需要人工批注。

示例 3：复用已登录的浏览器

• 提示词：“使用我已登录的浏览器，让我标注一个账单页面的问题。”
• 预期行为：将浏览器运行时转到 playwriter，然后使用 agentation 生成批注反馈包。

示例 4：审查计划，而非审查 UI

• 提示词：“在浏览器中打开生成的计划，让我在开始编码前批准或拒绝其中的步骤。”
• 预期行为：转到 plannotator，因为产物是计划/差异，而不是渲染后的 UI 问题。

最佳实践

1. 先选择浏览器/运行时路径；agentation 是反馈桥接工具，不是所有浏览器工具的替代品。
2. 一次优先使用一种批注模式，不要在同一个回答中混合复制粘贴、监视循环和平台配置。
3. 首次集成应保持精简；只有在工作流需要时才添加钩子、回调或 webhook。
4. 修复后，使用生成该批注的同一审查路径重新验证。
5. 将精确的 UI 反馈作为交付成果，而不是大量罗列安装方案。
6. 如果任务实际涉及计划审查、全新浏览器验证或复用正在运行的浏览器，应积极转到相应工具。

参考资料

此技能的深入文档：

• modes-and-routing
• platform-setup-and-hooks
• watch-loop-and-self-driving

主要来源：

• https://github.com/benjitaylor/agentation
• https://agentation.com
• https://www.npmjs.com/package/agentation
• https://www.npmjs.com/package/agentation-mcp

元数据

• 版本：1.1.0
• 最后更新：2026-04-15
• 范围：面向编码 Agent 的精确渲染 UI 反馈包、监视循环和平台交接