agentation-self-driving

Agentation 自动驾驶模式

通过 Agentation 工具栏添加设计注释，自主评审网页。使用可见的有头浏览器，让用户实时观看 Agent 工作，就像观看自动驾驶汽车在路上行驶一样。

启动 — 始终使用有头模式

浏览器必须可见。绝不使用无头模式运行。用户会看到你扫描、悬停、点击和添加注释。

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

command -v agent-browser >/dev/null || { echo "ERROR: agent-browser not found. Install the agent-browser skill first."; exit 1; }

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

# Try to open. If it fails (stale session), close first then retry.
agent-browser --headed open <url> 2>&1 || { agent-browser close 2>/dev/null; agent-browser --headed open <url>; }

然后确认 Agentation 工具栏已显示并将其展开：

# 1. Check toolbar exists on the page. Agentation 3.1+ renders inside a shadow root on <agentation-toolbar>,
#    so query through it (the fallback to document keeps older versions working)
agent-browser eval "(document.querySelector('agentation-toolbar')?.shadowRoot || document).querySelector('[data-feedback-toolbar]') ? 'toolbar found' : 'NOT FOUND'"
# If "NOT FOUND": Agentation is not installed on this page — stop and tell the user

# 2. Expand ONLY if collapsed (clicking when already expanded collapses it)
agent-browser eval "(document.querySelector('agentation-toolbar')?.shadowRoot || document).querySelector('[data-feedback-toolbar][class*=expanded]') ? 'already expanded' : ((document.querySelector('agentation-toolbar')?.shadowRoot || document).querySelector('[class*=toggleContent]')?.click(), 'expanding')"

# 3. Verify: take a snapshot and look for toolbar controls
agent-browser snapshot -i
# If expanded: you'll see "Block page interactions" checkbox, color buttons (Purple, Blue, etc.)
# If collapsed: you'll only see the small toggle button — retry step 2

必须勾选“阻止页面交互”（默认：开启）。

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 选择器。滚动和查找位置时，请使用带 querySelector 的 eval。

# 1. Take interactive snapshot — identify target element and build a CSS selector
agent-browser snapshot -i
# Example: snapshot shows  heading "Point at bugs." [ref=e10]
# Derive a CSS selector: 'h1', or more specific: 'h1:first-of-type'

# 2. Scroll the element into view via eval (NOT scrollintoview @ref — that breaks)
agent-browser eval "document.querySelector('h1').scrollIntoView({block:'center'})"

# 3. Get its bounding box via eval (NOT get box @ref — that also breaks)
agent-browser eval "((r) => r.x+','+r.y+','+r.width+','+r.height)(document.querySelector('h1').getBoundingClientRect())"
# Returns: "383,245,200,40"  (parse these as x,y,width,height)

# 4. Move cursor to element center, then click
#    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. Get the annotation dialog refs — read the FULL snapshot output
#    Dialog refs appear at the BOTTOM of the list, don't truncate with head/tail
agent-browser snapshot -i
# Look for: textbox "What should change?" and "Cancel" / "Add" buttons

# 6. Type critique — fill and click DO support @ref
agent-browser fill @<textboxRef> "Your critique here"

# 7. Submit (Add button enables after text is filled)
agent-browser click @<addRef>

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

agent-browser eval "(document.querySelector('agentation-toolbar')?.shadowRoot || document).querySelector('[data-feedback-toolbar][class*=expanded]') ? 'ok' : ((document.querySelector('agentation-toolbar')?.shadowRoot || 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.querySelector('agentation-toolbar')?.shadowRoot || document).querySelectorAll('[data-annotation-marker]').length"
# Should return the expected count (1 after first, 2 after second, etc.)

如果计数没有增加，则提交可能已静默失败 — 请重新获取快照，并检查对话框是否仍处于打开状态。

除非另有要求，否则每页目标为 5 至 8 条注释。

评审内容

区域	关注点
主视觉区 / 首屏内容	标题层级、CTA 位置、视觉分组
导航	标签样式、类别分组、视觉权重
演示 / 插图	清晰度、层次感、动画易读性
内容区块	间距节奏、强调内容样式、字体层级
关键标语	是否给予有感染力的文案足够的视觉强调
CTA 和页脚	转化权重、视觉区隔、最终操作

批评风格

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

• 具体且可执行：“将安装命令放在副标题下方，字号设为 16px”，而不是“修复布局”
• 提供 1-2 个具体替代方案：参考 CSS 值、布局模式或设计系统
• 指出设计原则：视觉层级、格式塔分组、留白、强调、转化设计
• 参考类似产品：“像 Stripe/Linear/Vercel 处理这类内容的方式”

反例：“这一部分需要改进” 正例：“这个项目符号列表看起来像文档，不像产品展示。采用带图标的 3 列卡片网格，类似 Stripe 的指南布局。这样能形成视觉节奏，便于快速浏览。”

安装

必须将此技能符号链接到 ~/.claude/skills/，Claude Code 才能发现它：

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

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

故障排除

• “Browser not launched. Call launch first.”：上次运行的会话已过期——运行 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 常见问题

如果不了解以下情况，工作流可能会悄无声息地失败：

常见问题	发生情况	解决方法
scrollintoview @ref	崩溃：“Unsupported token @ref while parsing css selector”	使用 eval "document.querySelector('sel').scrollIntoView({block:'center'})"
get box @ref	同样会崩溃——get box 会将引用解析为 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 因“Browser not launched”而失败	上次运行留下的过期会话会阻止新会话启动	运行 agent-browser close 2>/dev/null，然后重试 open 命令

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

双会话工作流（全自动执行）

连接 MCP 后（工具栏显示“MCP Connected”），批注会自动发送给任何正在监听的 Agent。这样即可实现：

• 会话 1（此技能）：监视页面，在可见的浏览器中添加评审批注
• 会话 2：循环运行 agentation_watch_annotations，接收批注并修改代码以处理每条批注

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