Wahajolla/annotate

註解 (Annotate)

使用者點擊頁面上的元素、寫下筆記，Claude 就會收到該筆記以及對應的選取器、鄰近文字、邊界框和網址，從而在程式碼中找到該元素並修正問題。

建構於 Agentation：agentation 工具列 (React 18+，僅限桌面) 以及 agentation-mcp 筆記伺服器 (基於 SQLite 的 HTTP API，另提供 MCP 工具)。

先選擇模式

如果不是很明確，請詢問使用者：

• 本地 (Local)：僅使用者與 Claude，同一台機器。筆記伺服器執行於 localhost:4747。不進行任何部署。這是預設模式。
• 共享 (Shared)：同事對託管網站進行評論，每個人都能看到所有人的筆記。需要一個公開 HTTPS 主機上的筆記伺服器。請參閱 references/shared.md。該頁面說明了架構與需求，由使用者選擇託管方式。

工具列的放置位置

根據頁面類型選擇。這兩種模式都適用相同的選項；只有 endpoint 和 session 會改變。

1. 在使用者的 React 應用內部。 npm i -D agentation，然後在應用旁渲染它，並確保絕不進入正式環境：

   {import.meta.env.DEV && <Agentation endpoint="http://localhost:4747" />}
   

   針對 hash router，可加上 useHashLocation；以 appName 為回饋加上標籤。
2. 任何使用者可控制的 HTML 頁面，無論是否為 React。 加入一個 script 標籤。載入器 會在自己的容器和自己的 React root 中掛載工具列，因此不會影響宿主頁面：

   <script type="module" src="https://cdn.jsdelivr.net/gh/Wahajolla/[email protected]/embed/annotator.js?endpoint=http://localhost:4747"></script>
   

   查詢參數：endpoint、session、app、hash=1。或者，在 script 載入前設定 window.ANNOTATOR_CONFIG = {endpoint, session, app, hash}。
3. 任何網站，且不修改其程式碼。 使用書籤小工具。提供使用者這行程式碼儲存為書籤；點擊即可切換工具列的開啟與關閉：

   javascript:(()=>{const s=document.createElement('script');s.type='module';s.src='https://cdn.jsdelivr.net/gh/Wahajolla/[email protected]/embed/annotator.js?endpoint=http://localhost:4747&t='+Date.now();document.head.appendChild(s)})()
   

   需要告知使用者的限制：
   • 具有嚴格內容安全策略 (CSP) 的網站（GitHub、許多銀行和大型應用）會封鎖注入的指令碼，因此工具列在這些網站上不會出現。
   • 在與 localhost 溝通的公開 https:// 網站上，瀏覽器可能會要求允許本機網路存取：請允許。
   • 筆記伺服器必須允許該網站的來源（請參閱下方的 CORS）。
   • 筆記與網站的 URL 綁定，工具列的本地草稿儲存在該網站的 localStorage 中。
4. Chrome 擴充功能。 這是註解任何網站最穩健的方式。單擊或按下 Alt+Shift+A 即可切換；能在嚴格 CSP 的網站（GitHub、Notion 等）上運作；且無需 CORS 設定：請求透過擴充功能發出。安裝方式：從 https://github.com/Wahajolla/annotator-skill/releases/latest 下載 annotator-extension.zip，然後進入 chrome://extensions → 開發人員模式 → 載入未封裝項目。筆記伺服器在擴充功能選項中設定。預設值為 http://localhost:4747；在共享模式下，請使用託管 URL 加上 session id。即時同步為每 5 秒輪詢一次。如果筆記伺服器無法連線，擴充功能會顯示一則「筆記伺服器離線」卡片，內含啟動指令，而 #annotator-ext-root 會取得 data-annotator-server="offline"（連線成功後變為 "online"）：如果你正在操控瀏覽器，請先檢查它，再告訴使用者他們的筆記已儲存。在選項中，「以 GitHub 登入」會以使用者的登入名稱簽署每一則筆記，因此同事的筆記會顯示留言者。

如果沒有 endpoint，工具列執行唯複製模式。筆記僅留在瀏覽器中，使用者按下「複製」並將 Markdown 貼到對話中。這不需要伺服器，因此當使用者僅想要一次性使用時使用。

本地模式

1. 執行筆記伺服器。 選擇一種方式：

   • MCP（最適合重複使用）。 獲得使用者同意後：claude mcp add agentation -- npx -y agentation-mcp server。之後 Claude Code 會隨著每個 session 啟動它，重新啟動後就會出現 agentation_* 工具：get_all_pending、resolve、reply 以及用於免動手循環的 watch_annotations。
   • 純 HTTP（無需重啟）。 將 npx -y agentation-mcp server 作為背景指令執行，並透過 HTTP 讀取筆記（請參閱下方說明）。

   使用 curl http://localhost:4747/health 檢查，應回傳 {"status":"ok"}。

2. CORS。 預設僅允許開發來源（localhost、*.localhost、127.0.0.1、私有 IP、.local、.test、.internal）。若要從公開網站的書籤小工具連線，請以 AGENTATION_CORS_ORIGINS=https://that-site.com 啟動伺服器（確切來源，以逗號分隔）。也可以使用 *，但這會讓任何開啟的分頁都能寫入筆記，因此建議使用確切來源。

3. 使用上述任一選項將工具列放到頁面上，並設定 endpoint=http://localhost:4747。

4. 驗證。 透過工具列新增一筆測試筆記，檢查 curl localhost:4747/pending 是否顯示它，然後將其刪除。

筆記持久儲存在 ~/.agentation/store.db。

讀取與處理筆記（兩種模式皆適用）

• MCP：agentation_get_all_pending，然後修正程式碼，接著用簡短摘要執行 agentation_resolve。
• HTTP：GET /pending（所有開啟的筆記）、GET /sessions、GET /sessions/:id。修正筆記後，發送 PATCH /annotations/:id 並帶入 {"status":"resolved"}。
• 誰寫的： 來自 Chrome 擴充功能且已登入 GitHub 的筆記會帶有 authorId: "github:<login>"，而預設留言會以 @<login>: 開頭。沒有 authorId 的筆記是匿名筆記（任何其他方式載入工具列）。當你回報時，請提及作者。
• 有用的欄位包括 comment、url、element、elementPath、fullPath、nearbyText、selectedText、boundingBox 以及 reactComponents（僅開發建置）。
• 在刪除任何內容之前，請先讓使用者決定。

顯示筆記以供截圖

Agentation 僅在游標懸浮於標記上時才顯示筆記文字。若要一次顯示所有筆記，請使用筆記圖層：每個筆記會有一個外框、一個編號和一個包含完整文字的卡片。繪製完成後，<html> 會取得 data-annotator-notes="<count>"。

• 使用者，在 Chrome 中： 擴充功能中按下 Alt+Shift+N（或右鍵點選圖示 → 在此頁面顯示所有筆記）。
• 你，在你操控的頁面上（Playwright、Chrome DevTools MCP 等）：設定自己的筆記並載入圖層，然後等待該屬性並截圖：

  window.ANNOTATOR_NOTES = [
    { selector: "h1", comment: "太長了。改為「簡單定價」", author: "claude" },
    { selector: "#cta", comment: "使用品牌藍色" },
  ]
  const s = document.createElement("script"); s.type = "module"
  s.src = "https://cdn.jsdelivr.net/gh/Wahajolla/[email protected]/embed/notes.js?t=" + Date.now()
  document.head.appendChild(s)
  

  每個筆記需要 selector（或頁面座標的 boundingBox: {x, y, width, height}）、comment 以及可選的 author。選取器未匹配任何內容的筆記會被跳過並在控制台中顯示警告，因此請檢查計數是否相符。除了 ANNOTATOR_NOTES 之外，也可傳入 ?endpoint=http://localhost:4747 以顯示該頁面的伺服器筆記；加上 &all=1 則包含已解決的筆記。再次載入時加上新的 t 可以隱藏圖層。
• 嚴格 CSP 的網站（GitHub 等）會封鎖該 script。在 Playwright 中，請使用 bypassCSP: true 建立 context；否則請使用擴充功能。
• 若要讓你的筆記變成真正的筆記（使用者在他們的工具列中也看得到，而且可以解決它們）：先 POST /sessions 帶入 {"url": "<page url>"}，然後 POST /sessions/:id/annotations 帶入 comment、element、elementPath（CSS 選取器）、url、boundingBox 以及 x/y（頁面座標）。接著以 ?endpoint=… 顯示它們。務必先詢問使用者：這些會變成共享筆記。

注意事項

• 工具列僅適用於桌面版。
• 筆記伺服器沒有認證機制，只有 CORS。任何瀏覽器來源被允許的人都可以寫入和刪除筆記。
• useHashLocation 會讓筆記依照 #route 保留。事後開啟它不會移動既有的筆記。
• Agentation 採用 PolyForm Shield 授權，適用於內部回饋用途。