用 Agentation 把 UI 註解直接餵給 AI agent

跟 AI coding agent 說「這個按鈕往左一點」、「這裡間距怪怪的」，最後往往變成一大段文字描述，模型還是抓錯元素。這篇主要想分享給：平常用 Cursor、Claude Code 改前端，但又懶得截圖標箭頭的人。

Agentation 的做法很直接——在瀏覽器裡點元素、留註解，輸出結構化 context 給 agent 讀。我最近在這個站的 Next.js 專案裝好了，從 React component 到 Cursor MCP 都走過一遍，紀錄如下。

⸻

▍Agentation 是什麼？

dev-only 的 React overlay。開發模式下你可以：

點頁面上任何元素
寫要改什麼
複製 markdown，或同步到本機 MCP server

預設資料不會離開你的電腦。註解先留在瀏覽器，除非你手動複製，或接上 localhost。對設計師跟前端來說，跟 Cursor、Claude Code、Codex 這類工具搭起來，feedback loop 會緊很多。

❖ 關鍵句：不是截圖工具，是把「你手指指著哪裡」變成 agent 讀得懂的格式。

⸻

▍安裝與掛載

❶ 安裝套件

專案根目錄執行：

pnpm add agentation -D

裝在 dev dependency 就好，production 不需要。

❷ 掛到 app root

Next.js App Router 通常放在 src/app/layout.tsx：

import { Agentation } from "agentation";

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

NODE_ENV 檢查很重要。Agentation 會讀 DOM，只該出現在本地開發，別帶進 production。

跑 pnpm dev，桌面瀏覽器打開網站就能看到 UI。（官方說不優化手機，別在手機上硬試。）

⸻

▍接上 AI agent：MCP 設定

手動複製貼上也行，但老實說，MCP 同步順很多。Agentation MCP server 提供 agentation_get_all_pending、agentation_list_sessions、agentation_resolve 等工具，agent 可以即時讀取、處理你的註解。

一鍵註冊（支援多種 agent）：

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

Cursor 手動設定 — 在 .cursor/mcp.json 加上：

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

驗證是否設定正確：

npx agentation-mcp doctor

預設 port 是 4747，要換的話加 --port 8080。改完 MCP config 記得重開 Cursor。

⸻

▍開啟即時同步

要讓 component 跟 server 連線，加上 endpoint：

<Agentation
  endpoint="http://localhost:4747"
  onSessionCreated={(sessionId) => {
    console.log("Session started:", sessionId);
  }}
/>

接上之後：

註解先存本地，server 在線才同步
重新整理頁面會回到同一個 session，不會洗出一堆重複註解
agent 那邊 resolve / dismiss 的狀態，重連時以 server 為準

沒設 endpoint 也能用——一切留在瀏覽器，自己 copy markdown 貼給 agent。

⸻

▍實際工作流長怎樣

我現在大概是這樣跑：

開 dev server，打開要 review 的頁面
點元素加註解（「padding 加大」、「字重不對」、「連結應該去 /blog」）
在 Cursor 叫 agent 看 pending 的 Agentation feedback
agent 改完，逐條 resolve

比截圖 → 描述 → 祈禱模型猜對節點，快不只一點。

⸻

▍安全與需求

官方文件有幾點值得記：

預設不外傳 — 處理都在 client-side，除非你主動接 MCP
只連本機 — 有 endpoint 也是打到你的 machine，不是第三方服務
dev-only — 務必保留 NODE_ENV 判斷

需求：React 18+、需要 DOM（component 掛在 layout / client boundary）、桌面瀏覽器。

⸻

❖ 【Asset】快速檢查清單

[ ] pnpm add agentation -D
[ ] layout.tsx 加上 {process.env.NODE_ENV === "development" && <Agentation />}
[ ] npx add-mcp "npx -y agentation-mcp server" 或手動寫 .cursor/mcp.json
[ ] npx agentation-mcp doctor 確認沒問題
[ ] （選用）endpoint="http://localhost:4747" 開即時同步
[ ] 重開 Cursor，跑一輪點選 → agent 修 → resolve

⸻

延伸閱讀

如果你每天都在跟 AI agent 改 UI，Agentation 算是那種裝了之後「怎麼以前沒有」的小工具。下次開 dev branch 試試看，你的「幫我改這塊」prompt 應該會短不少。