webkubor/vite-plugin-agent-eyes

Vite Agent Debugger

Gib dem in einem Vite-Projekt arbeitenden Agenten Laufzeiteinblicke, um den selbstheilenden Kreislauf „Logs lesen → Lokalisieren → Ändern → Dev neustarten → Erneut lesen und bestätigen“ zu durchlaufen. Passendes npm-Paket vite-plugin-agent-eyes (Quellcode im Verzeichnis src/, kann per npm publish oder Git installiert werden). Wenn nur der Agenten-Workflow benötigt wird, lese zuerst AGENT_GUIDE.md; damit Codex, Claude, Gemini, Hermes es aktiv entdecken und nutzen können, lies AGENT_BOOTSTRAP.md; die README.md richtet sich an Menschen zur Installation und Bewertung.

Wann verwenden

• Der Benutzer meldet „Seite defekt / Anmeldung fehlgeschlagen / Anfrage fehlgeschlagen / Cookie-Problem“, aber du solltest nicht den Code erraten – lies zuerst die Telemetrie.
• Du hast selbst Änderungen vorgenommen und musst validieren: Dev neustarten, Aktionen auslösen, Logs lesen, um das Verhalten zu bestätigen.
• Wenn die bereits angemeldete UI oder die Browserkonsole wiederhergestellt werden soll, lies zuerst log/<port>/auth-state.json für das aktuelle Kontenprofil, dann log/<port>/interaction.log für den letzten Interaktionspfad.
• Wenn ein Commit durch Guard blockiert wurde oder vorzeitige Warnungen vor offensichtlichen Fehlern/schlechtem Code benötigt werden, lies zuerst log/guard-report.json.
• Ein Vite-Projekt, das noch nicht integriert ist, mit diesen Selbstheilungsfähigkeiten ausstatten.

Integration (einmalig, standardmäßig 1 Schritt)

// vite.config.ts
import { agentEyes, agentProxy } from 'vite-plugin-agent-eyes'
export default defineConfig({
  plugins: [...agentEyes()],  // Standard: Logging + automatische Client-Instrumentierung + Projekt-Health-Check + Size Watch + Commit Guard
  server: { proxy: { '/api': agentProxy('https://your-api.example.com') } },
})

agentEyes() wirkt nur bei vite dev und injiziert automatisch autoInstrument() in die Dev-HTML-Datei; normale Projekte müssen den Anwendungseinstiegspunkt nicht mehr ändern.

Wenn die automatische Injektion deaktiviert ist (agentEyes({ client: false })), muss sie manuell am Anwendungseinstiegspunkt hinzugefügt werden:

import { autoInstrument } from 'vite-plugin-agent-eyes/client'
autoInstrument()

Oder manuelles Instrumentieren (bei feinerer Kontrolle):

import { installAgentErrorReporter, logApiCall, logConsoleEntry, snapshotDom } from 'vite-plugin-agent-eyes/client'
installAgentErrorReporter()   // Erfasst globale Fehler + gesamte Konsole + DOM-Snapshot
// Im fetch/ky/axios-Interceptor nach jedem Request aufrufen
logApiCall({ method, path, url, ok, duration_ms, code, status, request_id, error, request, response })
logConsoleEntry('warn', ['deprecated API called'])

Nach erfolgreichem Login das anonymisierte Kontenprofil aufzeichnen:

import { recordLoginSuccess } from 'vite-plugin-agent-eyes/client'
recordLoginSuccess({ userId, email, name, roles, tenantId })

Speichert nur das anonymisierte Profil, kein Token/Cookie. Im Browser lesbar unter window.__AGENT_EYES_AUTH__, Datei unter log/<port>/auth-state.json.

Interaktionsspuren werden standardmäßig von autoInstrument() installiert und in log/<port>/interaction.log geschrieben. input / change werden nur als <redacted> aufgezeichnet, keine echten Formularwerte.

Wenn das Paket nicht installiert ist, aber temporär genutzt werden soll: Bevorzugt Installation per Git oder Workspace; kopiere nicht nur src/index.ts / src/client.ts, da sie von den Modulen cdp/git/guard-* im selben Verzeichnis abhängen.

Commit-Governance: agentEyes / agentGit / agentGuard / agentSizeWatch (Konfigurations-Spickzettel)

Diese Einstiege (Hooks werden vom apply:'serve'-Plugin beim Dev-Start gesetzt/überschrieben – bei Konfigurationsänderung oder Update muss pnpm dev einmal ausgeführt werden, damit sie wirksam werden; in Astro-Projekten in die vite.plugins der astro.config einfügen):

Plugin	Zeitpunkt	Wirkung
agentEyes	Dev-Start	Standard-Kombinationseinstieg: Logging + automatische Client-Instrumentierung + Projekt-Health-Check + Size Watch + Guard-only-Git-Hook
agentGit	Vor/Nach Commit	Ersetzt Husky: Führt precommit-Befehl aus + kann guard einbetten; nach Commit Feishu-Benachrichtigung. Inkludiert Deduplizierung bei Rebase/Cherry-Pick
agentGuard	Beim Commit	Blockiert Staged-Dateien hart: Secrets/übermäßig große Dateien/übermäßige Zeilen/TODO/any/console.log. Wenn agentGit bereits verwendet wird, in agentGit({ guard }) konfigurieren, nicht separat anhängen (Konflikt um pre-commit)
agentSizeWatch	Während des Codierens in Dev	Übermäßig lange Dateien warnen in der Konsole mit [agent-eyes:size], nur Warnung, kein Block. Speziell gegen von KI erstellte überlange CSS-Dateien

Typische Konfiguration (wie in den drei Repos dieses Projekts):

agentGit({
  projectLabel: '国内官网',
  precommit: ['sh scripts/precommit.sh'],     // Jeder Exit-Code ungleich 0 blockiert
  webhook: [{ url: 'https://open.feishu.cn/open-apis/bot/v2/hook/xxxx', format: 'feishu' }],
  guard: { level: 'block', fileLength: { warn: 400, block: 800 } },  // Blockiert schlechten Code hart
  claimHooksPath: true,   // Überschreibt globales core.hooksPath (z.B. von Lefthook) mit lokaler Überschreibung
  force: true,            // Übernimmt bereits vorhandene, nicht von diesem Plugin stammende pre-commit-Hooks
})
// Echtzeitwarnung während der Entwicklung (optional, unabhängig): agentSizeWatch({ warn: 400, cssWarn: 300 })

level: warn nur melden / block (empfohlen) hart blockieren / strict vorerst gleichbedeutend mit block. guard.checks: ['secrets','largeFiles','fileLength','todo','noAny','noConsoleLog'], einzeln schaltbar.

Zwei Verhaltensweisen ab Version 0.12.0, die vor der Konfiguration von guard bekannt sein müssen (sonst wird es als Bug angesehen):

• Lockfiles/komprimierte Artefakte werden nicht von fileLength erfasst: pnpm-lock.yaml/package-lock.json/yarn.lock/*.lock/go.sum/.min.js|css werden automatisch übersprungen – generierte Dateien sind kein handgeschriebener Code. Um die Liste zu erweitern, GENERATED_FILE_PATTERN ändern (zwei Kopien in guard-core + guard-hook synchron halten).

• Webhook ruft sich nicht selbst auf: agentGit injiziert automatisch seine eigene Webhook-URL in guard allowSecrets, sodass die Secret-Prüfung es nicht mehr als Leck erkennt. Um andere Literale manuell zu erlauben, guard.allowSecrets: [...] verwenden.

• Guard prüft nur gestagte Dateien; der letzte JSON-Bericht befindet sich in log/guard-report.json.

• Vollständige Optionsliste siehe README im API-Abschnitt ### agentGit / agentGuard / agentSizeWatch.

Selbstheilungskreislauf (Kern, genau so ausführen)

1. Zuerst log/README.md lesen – Projekt-Selbstbeschreibung, um den aktuellen Port-Log-Pfad und die Bedeutung der Streams zu erfahren.
2. log/project-guide.json lesen – Zuerst Projekttyp, API-/Geschäfts-/Routing-/Konfigurationsebenen und @-Alias-Empfehlungen prüfen.
3. log/<port>/errors.log lesen – Lokalisieren, „was kaputt ist“ (Neuestes zuerst, head reicht).
4. Den Hinweisen folgen:
   • Reproduktionspfad unklar → log/<port>/interaction.log für die Reihenfolge von click/input/change/submit/route.
   • API-/Feldprobleme → log/<port>/api-calls.log für die echten Request-/Response-Bodies (niemals Felder nur anhand des Typs erraten).
   • Konsolenwarnungen/Debug-Info → log/<port>/console.log für alle Level (React-Dev-Warnungen, Library-Deprecations usw.).
   • Login/Cookie/CORS/302 usw. auf Netzwerkebene → log/<port>/proxy-<host>.log für Cookie(req) und Set-Cookie.
   • Wiederherstellung der angemeldeten UI → log/<port>/auth-state.json für das aktuelle Kontenprofil.
   • Visuelle Probleme → log/<port>/snapshots/ für Fehler-Screenshots (PNG) + DOM-Snapshots (HTML).
   • Commit-Türsteher-Probleme → log/guard-report.json für Details zu Blockaden/Warnungen.
5. Rauschen vorhersagen: 401 von /auth/session ohne Login, runtime.lastError von Browsererweiterungen sind erwartetes Rauschen, kein Bug, nicht nachgehen.
6. Code ändern → Dev neustarten (Vite-Konfiguration/Plugin-Änderungen werden nicht per HMR neu geladen, Neustart erforderlich) → Aktion erneut auslösen → Logs erneut lesen und bestätigen. Logs werden bei jedem Start gelöscht, was gelesen wird, stammt aus diesem Durchlauf.

Vorzeigediagnose: Login erfolgreich, aber immer 401

log/<port>/api-calls.log:  POST .../auth/login  code=0        ← Login erfolgreich
log/<port>/api-calls.log:  GET  .../auth/session code=40101    ← Direkt danach nicht angemeldet
log/<port>/proxy-<host>.log: GET .../auth/session → 200 | Cookie(req): Keine   ← Browser hat kein Cookie

Ursache: Upstream-Set-Cookie hat Domain=<Elterndomäne> + Secure + SameSite=None, der lokale http://localhost-Bereich passt nicht + Secure wird verworfen → abgelehnt. agentProxy repariert dies standardmäßig im Dev-Modus (Domain entfernen / Secure abziehen / SameSite=None→Lax). Deaktivieren: agentProxy(target, { rewriteCookiesForLocalhost: false }).

Log-Übersicht

Datei	Wofür
log/<port>/errors.log	API-Fehler + Frontend-Laufzeitfehler (aggregiert, dedupliziert + Frequenz)
log/<port>/console.log	Konsolenausgabe aller Level (log/warn/error/info/debug)
log/<port>/interaction.log	Anonymisierte Interaktionsspuren von click/input/change/submit/route
log/<port>/api-calls.log	Alle API-Aufrufe + Routen mit Request-/Response-Bodies
log/<port>/proxy-<host>.log	Proxy-Ebene: Cookie/Set-Cookie-Attribute/Status (mehrere Proxies nach Host getrennt)
log/<port>/auth-state.json	Anonymisiertes Profil des letzten erfolgreichen Logins
log/<port>/snapshots/err-*.png	Fehler-Screenshots (benötigt CDP, Port-Erkennung automatisch)
log/<port>/snapshots/dom-*.html	DOM-Snapshots (immer verfügbar, kein CDP erforderlich)
log/project-guide.json	Projekttyp, API-/Geschäfts-/Routing-/Konfigurationsebenen, Alias und Planungsempfehlungen
log/guard-report.json	Letzter JSON-Guard-Bericht vor einem Commit