agentation-self-driving

Agentation 自动驾驶模式

通过 Agentation 工具栏自主评审网页并添加设计注释——在可见的有头浏览器中运行，让用户实时观看代理工作，就像观看自动驾驶汽车导航一样。

启动——始终有头

浏览器必须可见。切勿无头运行。用户观看你扫描、悬停、点击和注释。

预检：在执行任何操作前，先确认 agent-browser 可用：

command -v agent-browser >/dev/null || { echo "错误：未找到 agent-browser。请先安装 agent-browser 技能。"; exit 1; }

启动：首先尝试直接打开。仅当打开命令因会话过期失败时才关闭现有会话——这可以避免关闭他人正在使用的浏览器：

# 尝试打开。如果失败（会话过期），先关闭再重试。
agent-browser --headed open <url> 2>&1 || { agent-browser close 2>/dev/null; agent-browser --headed open <url>; }

然后验证 Agentation 工具栏是否存在并展开它：

# 1. 检查页面上是否存在工具栏（data-feedback-toolbar 是根标记）
agent-browser eval "document.querySelector('[data-feedback-toolbar]') ? 'toolbar found' : 'NOT FOUND'"
# 如果返回 "NOT FOUND"：该页面未安装 Agentation——停止并告知用户

# 2. 仅在折叠时展开（如果已展开则点击会折叠）
agent-browser eval "document.querySelector('[data-feedback-toolbar][class*=expanded]') ? 'already expanded' : (document.querySelector('[class*=toggleContent]')?.click(), 'expanding')"

# 3. 验证：截取快照并查找工具栏控件
agent-browser snapshot -i
# 如果展开：你会看到“Block page interactions”复选框、颜色按钮（紫色、蓝色等）
# 如果折叠：你只会看到小的切换按钮——重试步骤 2

“Block page interactions”必须勾选（默认开启）。

eval 引号规则：在 eval 字符串中始终使用 [class*=toggleContent]（属性值不带引号）。不要在 eval 中使用双感叹号，因为 bash 会将其视为历史扩展。也不要使用反斜杠转义内部引号，因为它们在跨 shell 时可能意外失效。

关键：如何创建注释

标准元素点击（click @ref）不会触发注释对话框。 Agentation 覆盖层在坐标级别拦截指针事件。请使用基于坐标的鼠标事件——这也会使交互在浏览器中可见，因为光标会在页面上移动。

@ref 兼容性：只有 click、fill、type、hover、focus、check、select、drag 支持 @ref 语法。命令 scrollintoview、get box 和 eval 不支持——它们期望 CSS 选择器。使用 eval 配合 querySelector 进行滚动和位置查找。

# 1. 获取交互式快照——识别目标元素并构建 CSS 选择器
agent-browser snapshot -i
# 示例：快照显示 heading "Point at bugs." [ref=e10]
# 推导 CSS 选择器：'h1'，或更具体：'h1:first-of-type'

# 2. 通过 eval 将元素滚动到视图中（不要用 scrollintoview @ref——那会出错）
agent-browser eval "document.querySelector('h1').scrollIntoView({block:'center'})"

# 3. 通过 eval 获取其边界框（不要用 get box @ref——那也会出错）
agent-browser eval "((r) => r.x+','+r.y+','+r.width+','+r.height)(document.querySelector('h1').getBoundingClientRect())"
# 返回："383,245,200,40"（解析为 x,y,width,height）

# 4. 将光标移动到元素中心，然后点击
#    centerX = x + width/2,  centerY = y + height/2
agent-browser mouse move <centerX> <centerY>
agent-browser mouse down left
agent-browser mouse up left

# 5. 获取注释对话框引用——读取完整的快照输出
#    对话框引用出现在列表底部，不要用 head/tail 截断
agent-browser snapshot -i
# 查找：textbox "What should change?" 和 "Cancel" / "Add" 按钮

# 6. 输入评审意见——fill 和 click 支持 @ref
agent-browser fill @<textboxRef> "你的评审意见"

# 7. 提交（填写文本后 Add 按钮启用）
agent-browser click @<addRef>

如果点击后没有出现对话框，工具栏可能已折叠。重新展开（仅在折叠时）并重试：

agent-browser eval "document.querySelector('[data-feedback-toolbar][class*=expanded]') ? 'ok' : (document.querySelector('[class*=toggleContent]')?.click(), 'expanded')"

从快照构建 CSS 选择器

快照显示元素角色、名称和引用。将它们映射到 CSS 选择器：

快照行	CSS 选择器
heading "Point at bugs." [ref=e10]	h1 或 h1:first-of-type
button "npm install agentation Copy" [ref=e15]	button:has(code) 或通过 eval 按文本内容
link "Star on GitHub" [ref=e28]	a[href*=github]
paragraph (long text...) [ref=e20]	按区域定位：section:nth-of-type(2) p

如有疑问，使用更宽泛的选择器并通过 eval 验证：

agent-browser eval "document.querySelector('h2').textContent"

循环流程

从上到下处理页面。对于每个注释：

1. 通过 eval 滚动到目标区域（scrollIntoView）
2. 选择一个具体元素——标题、段落、按钮、区域容器
3. 通过 eval 获取其边界框（getBoundingClientRect）
4. 执行坐标点击序列（mouse move → mouse down → mouse up）
5. 读取完整快照输出，在底部找到对话框引用
6. 写入评审意见（fill @ref）并提交（click @ref）
7. 验证注释已添加（见下文）
8. 移动到下一个区域

验证注释

提交每个注释后，确认计数增加：

agent-browser eval "document.querySelectorAll('[data-annotation-marker]').length"
# 应返回预期计数（第一次后为 1，第二次后为 2，依此类推）

如果计数未增加，则提交静默失败——重新快照并检查对话框是否仍打开。

除非另有说明，每页目标为 5-8 条注释。

评审内容

区域	关注点
首屏/折叠区上方	标题层级、CTA 位置、视觉分组
导航	标签样式、分类分组、视觉权重
演示/插图	清晰度、深度、动画可读性
内容区域	间距节奏、标注处理、排版层级
关键标语	有共鸣的语句是否获得足够视觉强调
CTA 和页脚	转化权重、视觉分隔、最终操作

评审风格

每条注释最多 2-3 句话：

• 具体且可操作：“将安装命令堆叠在副标题下方，字号 16px”而不是“修复布局”
• 1-2 个具体替代方案：引用 CSS 值、布局模式或设计系统
• 命名原则：视觉层级、格式塔分组、留白、强调、转化设计
• 参考同类产品：“就像 Stripe/Linear/Vercel 处理此问题的方式”

不好：“此区域需要改进”
好：“这个项目列表读起来像文档，而不是展示。使用三列卡片网格加图标——类似于 Stripe 的指南模式。创造视觉节奏和可扫描性。”

安装

该技能必须符号链接到 ~/.claude/skills/ 中，以便 Claude Code 发现它：

ln -s "$(pwd)/skills/agentation-self-driving" ~/.claude/skills/agentation-self-driving

安装后重启 Claude Code。使用 /agentation-self-driving 验证——如果加载了技能说明，则符号链接生效。

故障排除

• “浏览器未启动。请先调用 launch。”：上次运行的会话过期——运行 agent-browser close 2>/dev/null 然后重试 --headed open 命令
• 页面上未找到工具栏：未安装 Agentation——先运行 /agentation 进行设置
• 点击后无对话框：工具栏折叠——使用状态感知的 eval 重新展开（先检查 [class*=expanded]），重试
• 定位到错误元素：点击 Cancel，滚动到目标元素，使用正确坐标重试
• Add 按钮保持禁用：未填写文本——重新快照并填写文本框
• 页面导航：“Block page interactions”关闭——通过工具栏设置启用
• 注释计数未增加：提交失败——对话框可能仍打开，重新快照并检查
• 运行中途中断（Ctrl+C）：浏览器保持打开，状态停留在当时。运行 agent-browser close 清理后再开始新会话

agent-browser 陷阱

如果不注意，以下问题会静默破坏工作流：

陷阱	后果	修复
scrollintow @ref	崩溃：“解析 CSS 选择器时遇到不支持的令牌 @ref”	使用 eval "document.querySelector('sel').scrollIntoView({block:'center'})"
get box @ref	同样崩溃——get box 将 ref 解析为 CSS 选择器	使用 eval "((r)=>r.x+','+r.y+','+r.width+','+r.height)(document.querySelector('sel').getBoundingClientRect())"
eval 中使用双感叹号	Bash 在命令运行前将双感叹号扩展为历史替换	改用 expr !== null 或 expr ? true : false
eval 中使用反斜杠转义引号	转义的内部引号跨 shell 失效	去掉引号：[class*=toggleContent] 适用于不含空格的简单值
snapshot -i | head -50	注释对话框引用（textbox "What should change?"、Add、Cancel）出现在快照底部	始终读取完整快照输出——绝不截断
click @ref 在覆盖层元素上	点击穿透到真实 DOM，绕过 Agentation 覆盖层	使用 mouse move → mouse down left → mouse up left 进行基于坐标的点击，覆盖层会拦截
--headed open 失败并显示“浏览器未启动”	上次运行的过期会话阻止新启动	运行 agent-browser close 2>/dev/null 然后重试打开命令

经验法则：@ref 适用于交互命令（click、fill、type、hover）。对于其他所有操作（eval、get、scrollintoview），在 eval 中使用 querySelector 的 CSS 选择器。

双会话工作流（完全自动驾驶）

连接 MCP 后（工具栏显示“MCP Connected”），注释会自动发送到任何监听的代理。这可以实现：

• 会话 1（本技能）：观察页面，在可见浏览器中添加评审注释
• 会话 2：循环运行 agentation_watch_annotations，接收注释，编辑代码以解决每条注释

用户观看会话 1 在浏览器中驱动页面，同时会话 2 在代码库中修复问题——完全自主的设计评审和实现。