agentation-self-driving

Agentation 自駕模式

透過 Agentation 工具列在網頁上新增設計註解，進行自主評論 — 使用可見的 headed 瀏覽器，讓使用者即時觀看代理操作，就像觀看自駕車導航一樣。

啟動 — 務必使用 Headed 模式

瀏覽器必須可見。絕對不要以 headless 模式執行。使用者會觀看您掃描、懸停、點擊和註解的過程。

前置檢查：在執行任何操作前，先確認 agent-browser 可用：

command -v agent-browser >/dev/null || { echo "錯誤：找不到 agent-browser。請先安裝 agent-browser 技能。"; exit 1; }

啟動：先嘗試直接開啟。僅在開啟指令因 session 過期而失敗時，才關閉現有 session — 這樣可避免關閉他人正在使用的瀏覽器：

# 嘗試開啟。若失敗（session 過期），先關閉再重試。
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
# 若已展開：會看到「封鎖頁面互動」核取方塊、顏色按鈕（紫色、藍色等）
# 若收合：只會看到小型切換按鈕 — 重試步驟 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 選擇器。請使用 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. 取得註解對話框的 ref — 讀取完整的快照輸出
#    對話框 ref 會出現在清單底部，不要用 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 選擇器

快照會顯示元素角色、名稱和 ref。將其對應到 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. 讀取完整快照輸出，在底部找到對話框 ref
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。」：來自先前執行的過期 session — 執行 agent-browser close 2>/dev/null 然後重試 --headed open 指令
• 頁面上找不到工具列：未安裝 Agentation — 先執行 /agentation 進行設定
• 點擊後無對話框：工具列已收合 — 使用狀態感知的 eval（先檢查 [class*=expanded]）重新展開，然後重試
• 定位到錯誤元素：點擊 Cancel，捲動到目標元素，使用正確座標重試
• Add 按鈕保持停用：未填寫文字 — 重新擷取快照並填寫文字框
• 頁面導航：「封鎖頁面互動」已關閉 — 透過工具列設定啟用
• 註解計數未增加：提交失敗 — 對話框可能仍開啟，重新擷取快照並檢查
• 執行中斷（Ctrl+C）：瀏覽器會保持開啟，狀態為中斷時的狀態。在開始新 session 前執行 agent-browser close 清理

agent-browser 陷阱

如果不注意，這些問題會靜默破壞工作流程：

陷阱	結果	修正
scrollintoview @ref	崩潰：「不支援的 token @ref 於解析 CSS 選擇器時」	使用 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	註解對話框 ref（textbox "What should change?"、Add、Cancel）出現在快照底部	一律讀取完整快照輸出 — 絕不截斷
click @ref 作用於覆蓋層元素	點擊會穿透到真實 DOM，繞過 Agentation 覆蓋層	使用 mouse move → mouse down left → mouse up left 進行基於座標的點擊，讓覆蓋層攔截
--headed open 失敗並顯示「瀏覽器未啟動」	來自先前執行的過期 session 會封鎖新啟動	執行 agent-browser close 2>/dev/null 然後重試開啟指令

經驗法則：@ref 適用於互動指令（click、fill、type、hover）。對於其他所有情況（eval、get、scrollintoview），請在 eval 中使用 querySelector 搭配 CSS 選擇器。

雙 Session 工作流程（完整自駕）

當 MCP 連線（工具列顯示「MCP Connected」）時，註解會自動發送給任何監聽中的代理。這可實現：

• Session 1（此技能）：監看頁面，在可見瀏覽器中新增評論註解
• Session 2：在迴圈中執行 agentation_watch_annotations，接收註解，編輯程式碼以處理每個註解

使用者觀看 Session 1 在瀏覽器中驅動頁面，同時 Session 2 在程式碼庫中修正問題 — 完全自主的設計審查與實作。