webkubor/vite-plugin-agent-eyes

Vite Agent Debugger

Permite que o agente trabalhando em um projeto Vite tenha visibilidade em tempo de execução, executando o ciclo de autocuração "ler log → localizar → modificar → reiniciar dev → ler novamente para verificar". Pacote npm complementar vite-plugin-agent-eyes (código-fonte neste diretório src/, pode ser instalado via npm publish ou git). Se precisar apenas do fluxo de operação do agente, leia AGENT_GUIDE.md primeiro; se quiser que Codex, Claude, Gemini, Hermes descubram e usem ativamente, leia AGENT_BOOTSTRAP.md; o README é voltado para instalação e avaliação por humanos.

Quando usar

• O usuário relata "página quebrada / não consigo fazer login / requisição falhou / problema com cookie", mas você não deve adivinhar o código – primeiro leia a telemetria.
• Você mesmo fez uma alteração e precisa verificar: reiniciar dev, disparar a ação, ler o log para confirmar que o comportamento está correto.
• Para restaurar a UI logada ou o contexto do navegador, primeiro veja log/<port>/auth-state.json para confirmar o perfil da conta atual, depois veja log/<port>/interaction.log para reconstruir o caminho de interação recente.
• Quando um commit do usuário é bloqueado pelo guard ou você precisa evitar antecipadamente erros óbvios / sinais de código espaguete, leia primeiro log/guard-report.json.
• Para instalar essa capacidade de autocuração em um projeto Vite que ainda não a possui.

Integração (única, por padrão 1 passo)

// vite.config.ts
import { agentEyes, agentProxy } from 'vite-plugin-agent-eyes'
export default defineConfig({
  plugins: [...agentEyes()],  // Padrão: logs + instrumentação automática do cliente + verificação do projeto + size watch + guard de commit
  server: { proxy: { '/api': agentProxy('https://your-api.example.com') } },
})

agentEyes() só funciona em vite dev e injeta automaticamente autoInstrument() no HTML de desenvolvimento; projetos normais não precisam modificar a entrada da aplicação.

Se a injeção automática estiver desativada (agentEyes({ client: false })), apenas adicione manualmente na entrada da aplicação:

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

Ou instrumentação manual (quando precisar de controle fino):

import { installAgentErrorReporter, logApiCall, logConsoleEntry, snapshotDom } from 'vite-plugin-agent-eyes/client'
installAgentErrorReporter()   // Captura erros globais + console completo + instantâneo DOM
// No interceptador fetch/ky/axios, ao final de cada requisição
logApiCall({ method, path, url, ok, duration_ms, code, status, request_id, error, request, response })
logConsoleEntry('warn', ['deprecated API called'])

Registrar perfil de conta dessensibilizado após login bem-sucedido:

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

Apenas salva o perfil dessensibilizado, não salva token/cookie. No navegador, pode ser lido em window.__AGENT_EYES_AUTH__, e o arquivo está em log/<port>/auth-state.json.

A trilha de interação é instalada por padrão por autoInstrument(), gravada em log/<port>/interaction.log. Eventos input / change apenas registram <redacted>, não salvam valores reais de formulário.

Se o pacote não estiver instalado mas quiser usar temporariamente: instale este pacote via git / workspace; não copie apenas src/index.ts / src/client.ts, pois eles dependem de módulos cdp, git, guard-* no mesmo diretório.

Governança de Commits: agentEyes / agentGit / agentGuard / agentSizeWatch (Referência Rápida de Configuração)

Responsabilidades dessas entradas (os hooks são instalados/reescritos pelo plugin apply:'serve' na inicialização do dev server – após alterar configuração ou atualizar versão, execute pnpm dev para que tenham efeito; em projetos Astro, adicione em vite.plugins no astro.config):

Plugin	Momento	Função
agentEyes	Inicialização do dev	Entrada padrão combinada: logs + instrumentação automática do cliente + verificação do projeto + size watch + guard hook git
agentGit	Antes/depois do commit	Substitui husky: executa comando precommit + pode incorporar guard; notificação Feishu após commit. Deduplicação nativa para rebase/cherry-pick
agentGuard	No momento do commit	Bloqueia arquivos staged: secret/arquivo muito grande/linhas muito longas/TODO/any/console.log. Se já usa agentGit, configure guard dentro de agentGit({ guard }), não o monte separadamente (concorrência no pre-commit)
agentSizeWatch	Durante o desenvolvimento	Avisa no console [agent-eyes:size] para arquivos muito longos, apenas aviso, não bloqueia. Especialmente útil para AI que gera CSS muito longo

Configuração típica (usada neste projeto de três repositórios):

agentGit({
  projectLabel: '国内官网',
  precommit: ['sh scripts/precommit.sh'],     // Qualquer saída não zero bloqueia
  webhook: [{ url: 'https://open.feishu.cn/open-apis/bot/v2/hook/xxxx', format: 'feishu' }],
  guard: { level: 'block', fileLength: { warn: 400, block: 800 } },  // Bloqueia código espaguete
  claimHooksPath: true,   // Quando `core.hooksPath` global (ex.: lefthook) oculta os hooks do repositório, define substituição local
  force: true,            // Assume o controle de pre-commit existente que não é deste plugin
})
// Aviso em tempo real durante dev (opcional, monta independente): agentSizeWatch({ warn: 400, cssWarn: 300 })

level: warn apenas relata / block (recomendado) bloqueia na linha vermelha / strict atualmente equivale a block. guard.checks: ['secrets','largeFiles','fileLength','todo','noAny','noConsoleLog'], pode ser ativado/desativado conforme necessário.

Dois comportamentos da versão 0.12.0 que você precisa saber antes de configurar guard (senão achará que é bug):

• Arquivos de lockfile e artefatos comprimidos não contam para fileLength: pnpm-lock.yaml/package-lock.json/yarn.lock/*.lock/go.sum/.min.js|css são ignorados automaticamente – são artefatos, não código escrito à mão. Para expandir a lista, modifique GENERATED_FILE_PATTERN (duas cópias sincronizadas: guard-core + guard-hook).

• Webhook não causa auto-danos: agentGit injeta automaticamente a URL do webhook configurado no allowSecrets do guard, a verificação de segredos não o tratará mais como vazamento. Para liberar manualmente outras literais, use guard.allowSecrets: [...].

• guard verifica apenas arquivos staged; o relatório JSON mais recente está em log/guard-report.json.

• Tabela de opções completa na seção ### agentGit / agentGuard / agentSizeWatch do README.

Ciclo de Autocuração (Núcleo, Siga este Fluxo)

1. Leia log/README.md primeiro – autodescrição do projeto, confirme onde estão os logs da porta atual e o que cada fluxo mostra.
2. Leia log/project-guide.json – veja primeiro o tipo de projeto, hierarquia de API/negócios/rotas/configurações e sugestões de alias @.
3. Leia log/<port>/errors.log – localize "o que quebrou" (o mais recente no topo, use head).
4. Aprofunde conforme as pistas:
   • Caminho de reprodução não claro → log/<port>/interaction.log veja a sequência de click/input/change/submit/route.
   • Problema de interface/campo → log/<port>/api-calls.log veja o corpo real da requisição/resposta (nunca adivinhe campos pelo tipo).
   • Avisos/informações de depuração no console → log/<port>/console.log veja saída de todos os níveis (React dev warning, depreciação de bibliotecas, etc.).
   • Camada de rede (login/cookie/CORS/302 etc.) → log/<port>/proxy-<host>.log veja Cookie(req) e Set-Cookie.
   • Restaurar UI logada → log/<port>/auth-state.json veja o perfil da conta atual.
   • Problemas visuais → log/<port>/snapshots/ veja capturas de tela de erro (PNG) + instantâneos DOM (HTML).
   • Problemas de bloqueio pré-commit → log/guard-report.json veja detalhes do bloqueio / aviso.
5. Pré-julgamento de ruído: 401 em /auth/session quando não logado, runtime.lastError de extensões de navegador são ruídos esperados, não são bugs, não vá atrás.
6. Modifique o código → Reinicie o dev server (mudanças na configuração/plugin do Vite não recarregam via HMR, é necessário reiniciar) → Reexecute → Leia os logs novamente para verificar. Os logs são limpos a cada inicialização, o que você vê é da execução atual.

Diagnóstico Emblemático: Login Bem-sucedido mas Sempre 401

log/<port>/api-calls.log:  POST .../auth/login  code=0        ← Login bem-sucedido
log/<port>/api-calls.log:  GET  .../auth/session code=40101    ← Imediatamente depois, não logado
log/<port>/proxy-<host>.log: GET .../auth/session → 200 | Cookie(req): nenhum   ← Navegador não enviou cookie

Causa raiz: O Set-Cookie upstream tem Domain=<domínio pai> + Secure + SameSite=None, o http://localhost local não corresponde ao domínio + Secure é descartado → rejeitado. agentProxy já corrige por padrão no dev (remove Domain / remove Secure / SameSite=None→Lax). Desligue com: agentProxy(target, { rewriteCookiesForLocalhost: false }).

Referência Rápida de Logs

Arquivo	O que ver
log/<port>/errors.log	Falhas de API + erros de runtime no frontend (agregados e deduplicados + frequência)
log/<port>/console.log	Saída completa do console (log/warn/error/info/debug)
log/<port>/interaction.log	Trilha dessensibilizada de interações click/input/change/submit/route
log/<port>/api-calls.log	Todas as chamadas de API + rotas, com corpo de requisição/resposta
log/<port>/proxy-<host>.log	Atributos Cookie / Set-Cookie / status da camada de proxy (arquivos separados por host para múltiplos proxies)
log/<port>/auth-state.json	Perfil de conta dessensibilizado do último login bem-sucedido
log/<port>/snapshots/err-*.png	Captura de tela de erro (requer CDP, detecção automática de porta)
log/<port>/snapshots/dom-*.html	Instantâneo DOM (sempre disponível, não requer CDP)
log/project-guide.json	Tipo de projeto, hierarquia de API/negócios/rotas/configurações, alias e sugestões de planejamento
log/guard-report.json	Relatório JSON do guard do commit mais recente