Vite Agent Debugger (에이전트 자가치료 & 제출 거버넌스)

Vite Agent Debugger

Vite 프로젝트에서 작업하는 에이전트에게 런타임 가시성을 부여하여, '로그 읽기 → 진단 → 수정 → dev 재시작 → 재검증'의 자가치료 루프를 실행합니다.

동반 npm 패키지 vite-plugin-agent-eyes (소스코드는 이 디렉토리의 src/에 있으며, npm publish 또는 git 설치 가능). 에이전트 조작 흐름만 필요하다면 AGENT_GUIDE.md를 먼저 읽으십시오. Codex, Claude, Gemini, Hermes가 이 스킬을 능동적으로 발견하고 사용하도록 하려면 AGENT_BOOTSTRAP.md를 읽으십시오. README는 인간 사용자의 설치 및 평가를 위한 것입니다.

사용 시기

• 사용자가 "페이지가 깨졌어요 / 로그인이 안 돼요 / 요청이 실패했어요 / 쿠키 문제예요"라고 보고했지만, 코드를 추측해서는 안 됩니다 — 원격 측정을 먼저 읽으십시오.
• 직접 수정한 후 검증이 필요할 때: dev 재시작, 작업 트리거, 로그를 읽어 동작이 올바른지 확인.
• 로그인된 UI를 복원하거나 브라우저 콘솔을 확인해야 할 때, 먼저 log/<port>/auth-state.json으로 현재 계정 프로필을 확인하고, log/<port>/interaction.log로 최근 인터랙션 경로를 복원하십시오.
• 사용자의 커밋이 guard에 의해 차단되었거나, 명백한 오류/레거시 신호를 사전에 방지해야 할 때, 먼저 log/guard-report.json을 읽으십시오.
• 아직 이 자가치료 능력이 도입되지 않은 Vite 프로젝트에 설정할 때.

설치 (1회성, 기본 1단계)

// vite.config.ts
import { agentEyes, agentProxy } from 'vite-plugin-agent-eyes'
export default defineConfig({
  plugins: [...agentEyes()],  // 기본값: 로깅 + 자동 클라이언트 계측 + 프로젝트 검사 + size watch + 커밋 guard
  server: { proxy: { '/api': agentProxy('https://your-api.example.com') } },
})

agentEyes()는 vite dev에서만 활성화되며, dev HTML에 autoInstrument()를 자동으로 주입합니다. 일반 프로젝트는 애플리케이션 진입점을 더 이상 수정할 필요가 없습니다.

자동 주입을 비활성화한 경우 (agentEyes({ client: false })), 애플리케이션 진입점에서 수동으로 추가해야 합니다:

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

또는 수동 계측 (세밀한 제어가 필요할 때):

import { installAgentErrorReporter, logApiCall, logConsoleEntry, snapshotDom } from 'vite-plugin-agent-eyes/client'
installAgentErrorReporter()   // 전역 오류 + 모든 콘솔 + DOM 스냅샷 캡처
// fetch/ky/axios 인터셉터에서, 각 요청 종료 시 호출
logApiCall({ method, path, url, ok, duration_ms, code, status, request_id, error, request, response })
logConsoleEntry('warn', ['deprecated API called'])

로그인 성공 후 민감 정보가 제거된 계정 프로필 기록:

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

민감 정보가 제거된 프로필만 저장하며, token/cookie는 저장하지 않습니다. 브라우저에서 window.__AGENT_EYES_AUTH__로 읽을 수 있으며, 파일은 log/<port>/auth-state.json에 저장됩니다.

인터랙션 궤적은 기본적으로 autoInstrument()에 의해 설치되며, log/<port>/interaction.log에 기록됩니다. input / change는 <redacted>만 기록하며, 실제 양식 값을 저장하지 않습니다.

패키지가 설치되지 않았지만 임시로 사용해야 하는 경우: git 또는 workspace 방식을 통해 이 패키지를 설치하십시오. src/index.ts / src/client.ts만 복사하지 마십시오. 이들은 같은 디렉토리의 cdp, git, guard-* 등 모듈에 의존합니다.

제출 거버넌스: agentEyes / agentGit / agentGuard / agentSizeWatch (설정 빠른 참조)

이 진입점들의 책임(훅은 apply:'serve' 플러그인이 dev 시작 시 설치/덮어씁니다 — 설정을 변경하거나 버전을 업그레이드하려면 pnpm dev를 한 번 실행해야 적용됩니다. Astro 프로젝트는 astro.config의 vite.plugins에 추가하십시오):

플러그인	시점	역할
agentEyes	dev 시작	기본 조합 진입점: 로깅 + 자동 클라이언트 계측 + 프로젝트 검사 + size watch + guard-only git hook
agentGit	커밋 전/후	husky 대체: precommit 명령 실행 + guard 내장 가능. 커밋 후 Feishu 알림. rebase/cherry 재생 중복 제거 기능 내장
agentGuard	커밋 시	staged 강제 차단: secret/초대형 파일/초과 행 수/TODO/any/console.log. agentGit을 이미 사용 중이라면 agentGit({ guard })에 설정하고, 별도로 마운트하지 마십시오 (pre-commit 경합)
agentSizeWatch	dev 코딩 중	초대형 파일이 콘솔에 [agent-eyes:size] warn으로 표시되며, 차단 없이 경고만 합니다. AI가 초대형 CSS를 생성하는 경우 전용

일반적인 설정 (이 프로젝트의 3개 저장소에서 사용 중인 형태):

agentGit({
  projectLabel: '국내 공식 사이트',
  precommit: ['sh scripts/precommit.sh'],     // 하나라도 0이 아닌 종료 코드면 차단
  webhook: [{ url: 'https://open.feishu.cn/open-apis/bot/v2/hook/xxxx', format: 'feishu' }],
  guard: { level: 'block', fileLength: { warn: 400, block: 800 } },  // 레거시 코드 강제 차단
  claimHooksPath: true,   // 전역 core.hooksPath (lefthook 등)가 이 저장소 훅을 가릴 때, 로컬 덮어쓰기 설정
  force: true,            // 이미 존재하는 다른 플러그인의 pre-commit을 대체
})
// dev 실시간 경고 (선택 사항, 독립적으로 마운트): agentSizeWatch({ warn: 400, cssWarn: 300 })

level: warn은 보고만 / block (권장)은 빨간선 차단 / strict는 현재 block과 동일. guard.checks: ['secrets','largeFiles','fileLength','todo','noAny','noConsoleLog'], 필요에 따라 켜고 끌 수 있습니다.

0.12.0의 두 가지 동작, guard 설정 전에 반드시 알아야 합니다 (버그라고 생각하지 않도록):

• lockfile/압축 산물은 fileLength에서 제외됩니다: pnpm-lock.yaml/package-lock.json/yarn.lock/*.lock/go.sum/.min.js|css는 자동으로 건너뜁니다 — 생성물은 수작업 코드가 아닙니다. 예외 목록을 더 확장하려면 GENERATED_FILE_PATTERN을 수정하십시오 (guard-core + guard-hook 두 복사본 동기화).

• webhook은 스스로를 피해로 간주하지 않습니다: agentGit은 자신의 webhook URL을 자동으로 guard의 allowSecrets에 주입하므로, secret 검사가 더 이상 이를 유출로 간주하지 않습니다. 다른 리터럴을 수동으로 허용하려면 guard.allowSecrets: [...]를 사용하십시오.

• guard는 staged 파일만 검사합니다. 가장 최근 JSON 보고서는 log/guard-report.json에 있습니다.

• 전체 옵션 목록은 README ### agentGit / agentGuard / agentSizeWatch API 섹션을 참조하십시오.

자가치료 루프 (핵심, 이 순서대로 실행)

1. 먼저 log/README.md를 읽으십시오 — 프로젝트 자체 설명으로, 현재 포트의 로그 위치와 각 스트림이 무엇을 보여주는지 확인합니다.
2. log/project-guide.json을 읽으십시오 — 먼저 프로젝트 유형, API/비즈니스/라우팅/설정 계층, @ alias 권장 사항을 확인합니다.
3. log/<port>/errors.log를 읽으십시오 — "무엇이 고장 났는지" 파악 (가장 최신이 위에 있음, head 명령어 사용 가능).
4. 단서에 따라 드릴다운:
   • 재현 경로가 불명확한 경우 → log/<port>/interaction.log에서 click/input/change/submit/route 순서 확인.
   • 인터페이스/필드 문제 → log/<port>/api-calls.log에서 실제 요청/응답 본문 확인 (절대 타입만 보고 필드를 추측하지 마십시오).
   • 콘솔 경고/디버그 정보 → log/<port>/console.log에서 모든 수준의 출력 확인 (React dev warning, 라이브러리 deprecation 등).
   • 로그인/cookie/CORS/302 등 네트워크 계층 → log/<port>/proxy-<host>.log에서 Cookie(req) 및 Set-Cookie 확인.
   • 로그인된 UI 복원 → log/<port>/auth-state.json에서 현재 계정 프로필 확인.
   • 시각적 문제 → log/<port>/snapshots/에서 오류 스크린샷 (PNG) 및 DOM 스냅샷 (HTML) 확인.
   • 커밋 전 게이트 문제 → log/guard-report.json에서 차단/경고 세부 사항 확인.
5. 노이즈 예측: 로그인하지 않은 상태의 /auth/session 401, 브라우저 확장의 runtime.lastError는 예상된 노이즈이므로 버그가 아니며 추적하지 마십시오.
6. 코드 수정 → dev 재시작 (vite 설정/플러그인 변경 사항은 HMR이 다시 로드하지 않으므로, 반드시 재시작해야 함) → 다시 트리거 → 로그를 다시 읽어 검증. 로그는 시작할 때마다 지워지며, 현재 세션의 내용만 표시됩니다.

대표 진단: 로그인 성공 후에도 계속 401

log/<port>/api-calls.log:  POST .../auth/login  code=0        ← 로그인 성공
log/<port>/api-calls.log:  GET  .../auth/session code=40101    ← 직후에 로그인되지 않음
log/<port>/proxy-<host>.log: GET .../auth/session → 200 | Cookie(req): 없음   ← 브라우저가 쿠키를 보내지 않음

근본 원인: 업스트림 Set-Cookie가 Domain=<부모 도메인> + Secure + SameSite=None인 경우, 로컬 http://localhost 도메인이 일치하지 않고 Secure가 무시되어 쿠키가 거부됩니다. agentProxy는 기본적으로 dev에서 이를 수정합니다 (도메인 제거 / Secure 제거 / SameSite=None→Lax). 비활성화: agentProxy(target, { rewriteCookiesForLocalhost: false }).

로그 빠른 참조

파일	용도
log/<port>/errors.log	API 실패 + 프론트엔드 런타임 오류 (집계 중복 제거 + 빈도)
log/<port>/console.log	모든 수준의 콘솔 출력 (log/warn/error/info/debug)
log/<port>/interaction.log	click/input/change/submit/route 민감 정보 제거된 인터랙션 궤적
log/<port>/api-calls.log	전체 API + 라우팅, 요청/응답 본문 포함
log/<port>/proxy-<host>.log	프록시 계층 Cookie / Set-Cookie 속성 / status (다중 프록시는 host별 파일 분리)
log/<port>/auth-state.json	가장 최근 로그인 성공 시 민감 정보 제거된 계정 프로필
log/<port>/snapshots/err-*.png	오류 스크린샷 (CDP 필요, 자동 포트 감지)
log/<port>/snapshots/dom-*.html	DOM 스냅샷 (항상 사용 가능, CDP 불필요)
log/project-guide.json	프로젝트 유형, API/비즈니스/라우팅/설정 계층, alias 및 계획 권장 사항
log/guard-report.json	가장 최근 커밋 전 guard JSON 보고서