webkubor/vite-plugin-agent-eyes

Vite Agent Debugger

Permet à un agent travaillant dans un projet Vite d'acquérir une visibilité sur l'exécution, en exécutant la boucle auto-réparatrice « Lire les logs → Diagnostiquer → Modifier → Redémarrer le serveur de développement → Relire les logs pour vérifier ». Package npm associé : vite-plugin-agent-eyes (code source dans le répertoire src/, peut être installé via npm publish ou git). Si vous avez uniquement besoin du processus d'utilisation de l'agent, lisez d'abord AGENT_GUIDE.md ; si vous voulez que Codex, Claude, Gemini, Hermes le découvrent et l'utilisent activement, lisez AGENT_BOOTSTRAP.md ; le README est destiné à l'installation et à l'évaluation par des humains.

Quand l'utiliser

• L'utilisateur signale « la page est cassée / impossible de se connecter / échec de la requête / problème de cookie », mais vous ne devez pas deviner le code – lisez d'abord la télémétrie.
• Vous avez vous-même modifié et devez vérifier : redémarrez le serveur de développement, déclenchez l'action, lisez les logs pour confirmer le comportement.
• Lorsque vous devez restaurer une UI authentifiée ou une console navigateur, consultez d'abord log/<port>/auth-state.json pour confirmer le profil actuel, puis log/<port>/interaction.log pour reconstituer le parcours d'interaction récent.
• Lorsque la soumission de l'utilisateur est bloquée par guard ou que vous devez anticiper des erreurs évidentes / signaux de code de mauvaise qualité, lisez d'abord log/guard-report.json.
• Pour installer ces capacités auto-réparatrices sur un projet Vite qui ne les a pas encore.

Installation (ponctuelle, par défaut en 1 étape)

// vite.config.ts
import { agentEyes, agentProxy } from 'vite-plugin-agent-eyes'
export default defineConfig({
  plugins: [...agentEyes()],  // Par défaut : logs + instrumentation client automatique + vérification du projet + surveillance de taille + guard des commits
  server: { proxy: { '/api': agentProxy('https://your-api.example.com') } },
})

agentEyes() ne s'active qu'en mode vite dev et injecte automatiquement autoInstrument() dans le HTML de développement ; les projets normaux n'ont pas besoin de modifier le point d'entrée de l'application.

Si l'injection automatique est désactivée (agentEyes({ client: false })), ajoutez manuellement dans le point d'entrée de l'application :

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

Ou instrumentation manuelle (lorsqu'un contrôle fin est nécessaire) :

import { installAgentErrorReporter, logApiCall, logConsoleEntry, snapshotDom } from 'vite-plugin-agent-eyes/client'
installAgentErrorReporter()   // Capture les erreurs globales + toute la console + instantané DOM
// Dans un intercepteur fetch/ky/axios, appelez à la fin de chaque requête
logApiCall({ method, path, url, ok, duration_ms, code, status, request_id, error, request, response })
logConsoleEntry('warn', ['deprecated API called'])

Enregistrement du profil désensibilisé après connexion réussie :

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

Seul le profil désensibilisé est sauvegardé, pas le token/cookie. Dans le navigateur, lisible via window.__AGENT_EYES_AUTH__, fichier dans log/<port>/auth-state.json.

La trace d'interaction est installée par défaut avec autoInstrument(), écrite dans log/<port>/interaction.log. Les événements input / change sont remplacés par <redacted>, les vraies valeurs des formulaires ne sont pas sauvegardées.

Si le package n'est pas installé mais que vous voulez l'utiliser temporairement : privilégiez l'installation via git / workspace ; ne copiez pas seulement src/index.ts / src/client.ts, elles dépendent des modules cdp, git, guard-* du même répertoire.

Gouvernance des commits : agentEyes / agentGit / agentGuard / agentSizeWatch (Aide-mémoire de configuration)

Ces responsabilités (les hooks sont installés/réécrits par le plugin apply:'serve' au démarrage du serveur de développement – après un changement de configuration ou une mise à jour de version, exécutez pnpm dev pour les appliquer ; pour les projets Astro, ajoutez dans astro.config à vite.plugins) :

Plugin	Moment	Rôle
agentEyes	Démarrage du serveur de développement	Point d'entrée combiné par défaut : logs + instrumentation client automatique + vérification du projet + surveillance de taille + guard-only git hook
agentGit	Avant/après le commit	Remplace husky : exécute les commandes precommit + peut intégrer guard ; notification Feishu après le commit. Déduplication intégrée pour les rebase/cherry-pick
agentGuard	Au moment du commit	Bloque les fichiers staged : secrets/fichiers très longs/lignes très longues/TODO/any/console.log. Si vous utilisez déjà agentGit, configurez-le via agentGit({ guard }), ne l'ajoutez pas séparément (conflit sur pre-commit)
agentSizeWatch	Pendant le développement en temps réel	Les fichiers très longs sont signalés dans la console avec [agent-eyes:size] en avertissement, ne bloque pas. Conçu pour les fichiers CSS très longs générés par l'IA

Configuration typique (utilisée dans les trois dépôts de ce projet) :

agentGit({
  projectLabel: '国内官网',
  precommit: ['sh scripts/precommit.sh'],     // Si l'un d'eux se termine avec un code non nul, le commit est bloqué
  webhook: [{ url: 'https://open.feishu.cn/open-apis/bot/v2/hook/xxxx', format: 'feishu' }],
  guard: { level: 'block', fileLength: { warn: 400, block: 800 } },  // Bloque le code de mauvaise qualité
  claimHooksPath: true,   // Masque global core.hooksPath (par ex. lefthook) pour les hooks de ce dépôt, définit un remplacement local
  force: true,            // Prend le contrôle d'un pre-commit existant qui n'est pas de ce plugin
})
// Avertissement en temps réel en développement (optionnel, indépendant) : agentSizeWatch({ warn: 400, cssWarn: 300 })

level : warn rapporte seulement / block (recommandé) ligne rouge bloquante / strict équivalent à block pour l'instant. guard.checks : ['secrets','largeFiles','fileLength','todo','noAny','noConsoleLog'], activables/désactivables au besoin.

Deux comportements de la version 0.12.0 à connaître avant de configurer guard (sinon vous pourriez croire à un bug) :

• Les fichiers lockfile/compressés ne sont pas comptés dans fileLength : pnpm-lock.yaml/package-lock.json/yarn.lock/*.lock/go.sum/.min.js|css sont automatiquement ignorés – ce sont des fichiers générés, pas du code écrit à la main. Pour étendre la liste, modifiez GENERATED_FILE_PATTERN (copies synchronisées dans guard-core + guard-hook).

• Le webhook ne s'auto-blesse pas : agentGit injecte automatiquement l'URL de son propre webhook dans guard.allowSecrets, la vérification des secrets ne le considère plus comme une fuite. Pour autoriser manuellement d'autres littéraux, utilisez guard.allowSecrets: [...].

• guard vérifie uniquement les fichiers staged ; le dernier rapport JSON se trouve dans log/guard-report.json.

• La table complète des options se trouve dans la section API du README ### agentGit / agentGuard / agentSizeWatch.

Boucle auto-réparatrice (cœur du système, suivez cela)

1. Lisez d'abord log/README.md – Auto-description du projet, confirmez où se trouvent les logs du port actuel et ce que chaque flux contient.
2. Lisez log/project-guide.json – Identifiez d'abord le type de projet, la hiérarchie API/métier/routage/configuration et les suggestions d'alias @.
3. Lisez log/<port>/errors.log – Identifiez « ce qui est cassé » (le plus récent en haut, utilisez head).
4. Approfondissez selon les indices :
   • Parcours de reproduction peu clair → log/<port>/interaction.log pour voir l'ordre des click/input/change/submit/route.
   • Problème d'interface/champ → log/<port>/api-calls.log pour voir le vrai corps de requête/réponse (ne devinez jamais les champs en vous basant sur le type).
   • Avertissements/informations de débogage de la console → log/<port>/console.log pour voir la sortie de tous les niveaux (React dev warning, dépréciations de bibliothèques, etc.).
   • Problèmes de couche réseau comme login/cookie/CORS/302 → log/<port>/proxy-<host>.log pour voir Cookie(req) et Set-Cookie.
   • Restauration de l'UI authentifiée → log/<port>/auth-state.json pour voir le profil actuel.
   • Problèmes visuels → log/<port>/snapshots/ pour voir les captures d'écran d'erreur (PNG) + instantanés DOM (HTML).
   • Problèmes de barrière de pré-commit → log/guard-report.json pour voir les détails des blocages/avertissements.
5. Anticipation du bruit : Les 401 de /auth/session non authentifiés, les runtime.lastError des extensions navigateur sont du bruit attendu, pas des bugs, ne les poursuivez pas.
6. Modifiez le code → Redémarrez le serveur de développement (les modifications de configuration/plugins de Vite ne sont pas rechargées par HMR, vous devez redémarrer) → Déclenchez à nouveau → Relisez les logs pour vérifier. Les logs sont vidés à chaque démarrage, ce que vous voyez correspond à la session en cours.

Diagnostic emblématique : Connexion réussie mais toujours 401

log/<port>/api-calls.log:  POST .../auth/login  code=0        ← Connexion réussie
log/<port>/api-calls.log:  GET  .../auth/session code=40101    ← Immédiatement après, non authentifié
log/<port>/proxy-<host>.log: GET .../auth/session → 200 | Cookie(req): aucun   ← Le navigateur n'a pas envoyé le cookie

Cause racine : Le Set-Cookie en amont a Domain=<domaine parent> + Secure + SameSite=None, le domaine local http://localhost ne correspond pas + Secure est ignoré → refusé. agentProxy corrige par défaut en développement (supprime Domain / retire Secure / SameSite=None→Lax). Désactiver : agentProxy(target, { rewriteCookiesForLocalhost: false }).

Référence rapide des logs

Fichier	Que regarder
log/<port>/errors.log	Échecs API + erreurs d'exécution frontend (agrégation dédupliquée + fréquence)
log/<port>/console.log	Sortie console de tous les niveaux (log/warn/error/info/debug)
log/<port>/interaction.log	Trace d'interaction désensibilisée (click/input/change/submit/route)
log/<port>/api-calls.log	API complète + routage, avec corps de requête/réponse
log/<port>/proxy-<host>.log	Propriétés Cookie / Set-Cookie / status au niveau proxy (fichiers séparés par host pour les proxies multiples)
log/<port>/auth-state.json	Profil désensibilisé du dernier compte connecté avec succès
log/<port>/snapshots/err-*.png	Capture d'écran d'erreur (nécessite CDP, détection automatique du port)
log/<port>/snapshots/dom-*.html	Instantané DOM (toujours disponible, sans CDP)
log/project-guide.json	Type de projet, hiérarchie API/métier/routage/configuration, alias et suggestions de planification
log/guard-report.json	Dernier rapport JSON de guard avant commit