Annotate (Kommentieren)

Was macht Annotate (Kommentieren)?

Der Benutzer klickt auf ein Element einer Seite, schreibt eine Notiz, und Claude erhält die Notiz zusammen mit einem Selektor, umgebendem Text, der Bounding-Box und der URL – so kann Claude das Element im Code wiederfinden und korrigieren.

Basiert auf Agentation: der agentation-Toolbar (React 18+, nur Desktop) und dem agentation-mcp-Notes-Server (HTTP-API auf SQLite, optional mit MCP-Tools).

Zuerst den Modus wählen

Fragen Sie den Benutzer, falls es nicht offensichtlich ist:

• Lokal: nur der Benutzer und Claude, auf diesem Rechner. Der Notes-Server läuft auf localhost:4747. Es wird nichts deployed. Dies ist der Standard.
• Geteilt: Kollegen kommentieren auf einer gehosteten Seite, und jeder sieht die Notizen aller. Dazu wird ein Notes-Server auf einem öffentlichen HTTPS-Host benötigt. Siehe references/shared.md. Diese Seite beschreibt die Architektur und die Anforderungen; der Benutzer wählt das Hosting.

Wo die Toolbar platziert wird

Wählen Sie je nach Art der Seite. Die gleichen Optionen funktionieren in beiden Modi; nur endpoint und session ändern sich.

1. Innerhalb der React-App des Benutzers. npm i -D agentation, dann neben der App rendern, abgesichert damit es nie in Produktion gelangt:

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

   Fügen Sie useHashLocation für Hash-Router und appName zur Beschriftung des Feedbacks hinzu.
2. Jede HTML-Seite, die der Benutzer kontrolliert, React oder nicht. Ein Script-Tag einfügen. Der Loader mountet die Toolbar in einem eigenen Container und einem eigenen React-Root, so dass die Host-Seite nicht beeinträchtigt wird:

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

   Query-Parameter: endpoint, session, app, hash=1. Alternativ kann window.ANNOTATOR_CONFIG = {endpoint, session, app, hash} gesetzt werden, bevor das Script geladen wird.
3. Jede beliebige Seite, ohne deren Code zu ändern. Verwenden Sie ein Bookmarklet. Geben Sie dem Benutzer diese Zeile, die er als Lesezeichen speichern kann; ein Klick schaltet die Toolbar ein und aus:

   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)})()
   

   Einschränkungen, die dem Benutzer mitgeteilt werden sollten:
   • Seiten mit strenger Content-Security-Policy (GitHub, viele Banken und große Apps) blockieren die eingefügten Skripte, daher erscheint die Toolbar dort nicht.
   • Auf einer öffentlichen https://-Seite, die mit localhost kommuniziert, fragt der Browser möglicherweise nach lokalem Netzwerkzugriff: dem zustimmen.
   • Der Notes-Server muss den Ursprung dieser Seite erlauben (siehe CORS unten).
   • Notizen sind an die URL der Seite gebunden, und die lokalen Entwürfe der Toolbar befinden sich im localStorage dieser Seite.
4. Chrome-Erweiterung. Dies ist die robusteste Methode, um jede Seite zu annotieren. Sie wird mit einem Klick oder Alt+Umschalt+A umgeschaltet, funktioniert auf Seiten mit strenger CSP (GitHub, Notion usw.) und benötigt keine CORS-Konfiguration: Die Anfragen laufen über die Erweiterung. Installation: annotator-extension.zip von https://github.com/Wahajolla/annotator-skill/releases/latest herunterladen, dann chrome://extensions → Entwicklermodus → Entpackte Erweiterung laden. Der Notes-Server wird in den Optionen der Erweiterung festgelegt. Standard ist http://localhost:4747; für den geteilten Modus die gehostete URL plus die Session-ID verwenden. Live-Synchronisierung erfolgt alle 5 Sekunden. Ist der Notes-Server nicht erreichbar, zeigt die Erweiterung eine Karte „Notes-Server ist offline“ mit dem Startbefehl an, und #annotator-ext-root erhält data-annotator-server="offline" („online“, sobald der Server antwortet): Wenn Sie den Browser steuern, überprüfen Sie dies, bevor Sie dem Benutzer mitteilen, dass seine Notizen gespeichert wurden. In den Optionen kann „Mit GitHub anmelden“ jede Notiz mit dem Benutzernamen des Anmeldenden signieren, so dass bei Kollegen-Notizen sichtbar ist, wer sie hinterlassen hat.

Ohne endpoint läuft die Toolbar im Nur-Kopieren-Modus. Notizen bleiben im Browser, und der Benutzer drückt „Kopieren“ und fügt das Markdown in den Chat ein. Dies benötigt keinen Server; verwenden Sie es, wenn der Benutzer nur einmalig annotieren möchte.

Lokaler Modus

1. Notes-Server starten. Wählen Sie eine Option:

   • MCP (am besten für wiederholte Nutzung). Mit Zustimmung des Benutzers: claude mcp add agentation -- npx -y agentation-mcp server. Claude Code startet ihn dann mit jeder Session, und die agentation_*-Tools erscheinen nach einem Neustart: get_all_pending, resolve, reply und watch_annotations für automatische Abläufe.
   • Reines HTTP (kein Neustart). npx -y agentation-mcp server als Hintergrundbefehl ausführen und Notizen über HTTP lesen (siehe unten).

   Überprüfen Sie mit curl http://localhost:4747/health; dies sollte {"status":"ok"} zurückgeben.

2. CORS. Standardmäßig sind nur Entwicklungs-Ursprünge erlaubt (localhost, *.localhost, 127.0.0.1, private IPs, .local, .test, .internal). Für ein Bookmarklet auf einer öffentlichen Seite starten Sie den Server mit AGENTATION_CORS_ORIGINS=https://diese-seite.com (exakte Ursprünge, durch Komma getrennt). * funktioniert ebenfalls, erlaubt aber jedem offenen Tab, Notizen zu schreiben; daher sind exakte Ursprünge zu bevorzugen.

3. Toolbar auf der Seite platzieren mit einer der obigen Optionen, mit endpoint=http://localhost:4747.

4. Überprüfen. Eine Testnotiz über die Toolbar hinzufügen, prüfen, dass curl localhost:4747/pending sie anzeigt, dann löschen.

Notizen bleiben in ~/.agentation/store.db erhalten.

Notizen lesen und umsetzen (beide Modi)

• MCP: agentation_get_all_pending, dann den Code korrigieren, dann agentation_resolve mit einer kurzen Zusammenfassung.
• HTTP: GET /pending (alle offenen Notizen), GET /sessions, GET /sessions/:id. Nach dem Beheben einer Notiz PATCH /annotations/:id mit {"status":"resolved"} senden.
• Wer hat geschrieben: Notizen von der Chrome-Erweiterung mit GitHub-Anmeldung enthalten authorId: "github:<login>", und standardmäßig beginnt der Kommentar mit @<login>: . Eine Notiz ohne authorId ist anonym (jede andere Art, die Toolbar zu laden). Den Autor erwähnen, wenn Sie berichten.
• Nützliche Felder sind comment, url, element, elementPath, fullPath, nearbyText, selectedText, boundingBox und reactComponents (nur in Dev-Builds).
• Lassen Sie den Benutzer entscheiden, bevor etwas gelöscht wird.

Notizen für Screenshots anzeigen

Agentation zeigt den Text einer Notiz nur, während die Maus über ihrer Markierung schwebt. Um alle gleichzeitig anzuzeigen, verwenden Sie die Notizen-Ebene: eine Umrandung, eine Nummer und eine Volltext-Karte für jede Notiz. Wenn das Zeichnen abgeschlossen ist, erhält <html> data-annotator-notes="<anzahl>".

• Der Benutzer, in Chrome: Alt+Umschalt+N in der Erweiterung (oder Rechtsklick auf das Symbol → „Alle Notizen auf dieser Seite anzeigen“).
• Sie, auf einer von Ihnen gesteuerten Seite (Playwright, Chrome DevTools MCP usw.): Eigene Notizen setzen und die Ebene laden, dann auf das Attribut warten und einen Screenshot machen:

  window.ANNOTATOR_NOTES = [
    { selector: "h1", comment: "Zu lang. Mach „Einfache Preise“ daraus", author: "claude" },
    { selector: "#cta", comment: "Das Markenblau verwenden" },
  ]
  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)
  

  Jede Notiz benötigt selector (oder boundingBox: {x, y, width, height} in Seitenkoordinaten), comment und optional author. Notizen, deren Selektor nichts findet, werden mit einer Konsolenwarnung übersprungen – überprüfen Sie daher, ob die Anzahl stimmt. Anstelle von ANNOTATOR_NOTES können Sie ?endpoint=http://localhost:4747 übergeben, um die Notizen des Servers für diese Seite anzuzeigen; &all=1 hinzufügen, um auch erledigte Notizen einzuschließen. Ein erneutes Laden mit einem neuen t blendet die Ebene aus.
• Seiten mit strenger CSP (GitHub und andere) blockieren dieses Skript. Erstellen Sie in Playwright den Kontext mit bypassCSP: true; andernfalls die Erweiterung verwenden.
• Um Ihre Notizen „echt“ zu machen (der Benutzer sieht sie auch in seiner Toolbar und kann sie als erledigt markieren): POST /sessions mit {"url": "<seiten-url>"} und dann POST /sessions/:id/annotations mit comment, element, elementPath (ein CSS-Selektor), url, boundingBox und x/y (Seitenkoordinaten). Dann mit ?endpoint=… anzeigen. Fragen Sie zuerst den Benutzer: diese werden zu geteilten Notizen.

Fallstricke

• Die Toolbar ist nur für Desktop ausgelegt.
• Der Notes-Server hat keine Authentifizierung, nur CORS. Jeder, dessen Browserursprung erlaubt ist, kann Notizen schreiben und löschen.
• useHashLocation hält Notizen pro #route. Wenn es später aktiviert wird, werden bestehende Notizen nicht verschoben.
• Agentation ist unter der PolyForm Shield-Lizenz lizenziert, was für internes Feedback in Ordnung ist.