Communitygithub.com

webkubor/vite-plugin-agent-eyes

AIエージェント向けViteプラグイン。自己修復テレメトリー（構造化ランタイムログ、ログイン状態の匿名化、スクリーンショット、DOMスナップショット）とコミットガバナンス（agentGit、agentGuard、agentSizeWatch）を提供します。

vite-plugin-agent-eyes とは？

このスキルは、Viteプロジェクトで動作するAIエージェント（Claude Code、Codex、Cursorなど）に「ランタイムの可視性」を付与し、「ログ読み取り→問題特定→コード修正→dev再起動→再確認」という自己修復サイクルを実行可能にします。主な機能は2つあります。1つ目は「自己修復テレメトリー」で、構造化されたランタイムログ（API呼び出し、エラー、コンソール出力、ユーザー操作、プロキシヘッダー）の読み取り、ログイン状態の匿名化、スクリーンショット、DOMスナップショットを提供します。これにより、エージェントはコードを推測するだけでなく、実際の実行時データに基づいて問題を診断・修正できます。2つ目は「コミットガバナンス」で、huskyを置き換えるagentGit（pre-commit/post-commitフックの統一、Feishu通知）、agentGuard（シークレット、巨大ファイル、 techdebtの防止）、agentSizeWatch（開発中の長大ファイル警告）を提供します。対応プラットフォームはViteおよびAstroプロジェクトで、スキルはSKILL.mdに詳細な手順が記載されています。

対応✓Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add webkubor/vite-plugin-agent-eyes
オリジナルを見る→すべてのスキルを見る

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

ドキュメント

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は人間のインストールと評価向けです。

使用するタイミング

  • ユーザーが「ページが壊れている/ログインできない/リクエストが失敗する/cookieの問題」と報告したが、コードを推測すべきではない場合——まずテレメトリーを読んでください。
  • 自分で修正した後に検証する必要がある場合：devを再起動し、操作をトリガーし、ログを読んで動作が正しいことを確認します。
  • ログイン済みUIやブラウザコンソールを再現する必要がある場合、まず log/<port>/auth-state.json で現在のアカウントプロファイルを確認し、次に log/<port>/interaction.log で最近のインタラクションパスを再現します。
  • ユーザーのコミットがguardによってブロックされた場合、または明らかなエラー/ techdebtのシグナルを事前に回避するよう要求された場合、まず log/guard-report.json を読んでください。
  • まだこの自己修復機能を導入していないViteプロジェクトにセットアップする場合。

導入（一度限り、デフォルト1ステップ）

// vite.config.ts
import { agentEyes, agentProxy } from 'vite-plugin-agent-eyes'
export default defineConfig({
  plugins: [...agentEyes()],  // デフォルト：ログ + 自動クライアント計装 + プロジェクトヘルスチェック + size watch + コミットガード
  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 })

匿名化されたプロファイルのみを保存し、トークンや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 に追加します）：

プラグインタイミング役割
agentEyesdev起動時デフォルトの組み合わせエントリ：ログ + 自動クライアント計装 + プロジェクトヘルスチェック + size watch + guard-only git hook
agentGitコミット前/後huskyの代替：precommit コマンドを実行 + オプションで guard を内包、コミット後にFeishuに通知。リベース/チェリーピックの重複排除を内蔵
agentGuardコミット時ステージングをハードブロック：secret/巨大ファイル/長すぎる行/TODO/any/console.log。agentGitを使用している場合は agentGit({ guard }) 内に設定し、単独で追加しないでください（pre-commitの競合）
agentSizeWatchdevコーディング中長すぎるファイルをコンソールに [agent-eyes:size] warnで警告、ブロックはしません。AIが生成した長大なCSSを治療するために特化

典型的な設定（このプロジェクトの3つのリポジトリで使用中のフォーム）：

agentGit({
  projectLabel: '国内官网',
  precommit: ['sh scripts/precommit.sh'],     // いずれかが非ゼロで終了したらブロック
  webhook: [{ url: 'https://open.feishu.cn/open-apis/bot/v2/hook/xxxx', format: 'feishu' }],
  guard: { level: 'block', fileLength: { warn: 400, block: 800 } },  // techdebtをハードブロック
  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の2つの動作、guardを設定する前に必ず知っておくべきこと（そうしないとバグと誤解する可能性があります）：

  • lockfile/圧縮成果物は fileLength の対象外：pnpm-lock.yaml/package-lock.json/yarn.lock/*.lock/go.sum/.min.js|css は自動スキップ——生成物は手書きコードではありません。さらにリストを拡張するには GENERATED_FILE_PATTERN を変更します（guard-core + guard-hookの2つのコピーを同期）。

  • webhookは自己攻撃しない：agentGit は自動的に自身の設定したwebhook URLをguardの allowSecrets に注入し、secretチェックで漏洩として扱わなくなります。他のリテラルを手動で許可するには guard.allowSecrets: [...] を使用します。

  • guardはステージングされたファイルのみをチェックします。最新のJSONレポートは log/guard-report.json にあります。

  • 完全なオプション一覧はREADMEの ### agentGit / agentGuard / agentSizeWatch APIセクションを参照してください。

自己修復サイクル（コア、これに従って実行）

  1. 最初に log/README.md を読む —— プロジェクトの自己説明。現在のポートのログがどこにあるか、各ストリームが何を見ているかを確認します。
  2. log/project-guide.json を読む —— まずプロジェクトタイプ、API/ビジネス/ルーティング/設定階層、@ エイリアスの推奨を確認します。
  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警告、ライブラリの非推奨など）を確認します。
    • ログイン/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): 無   ← ブラウザがcookieを持っていない

根本原因：上流のSet-Cookieが Domain=<親ドメイン> + Secure + SameSite=None であり、ローカルの http://localhost ドメインが一致せず + Secureが破棄される → 拒否。 agentProxy はデフォルトでdevでこれを修正します（Domainを削除 / Secureを剥奪 / SameSite=None→Lax）。オフにする場合：agentProxy(target, { rewriteCookiesForLocalhost: false })。

ログクイックリファレンス

ファイル見るもの
log/<port>/errors.logAPIエラー + フロントエンドランタイムエラー（集約重複排除 + 頻度）
log/<port>/console.log全レベルのコンソール出力（log/warn/error/info/debug）
log/<port>/interaction.logclick/input/change/submit/routeの匿名化されたインタラクショントレイル
log/<port>/api-calls.logAPI全量 + ルーティング、リクエスト/レスポンスボディ付き
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-*.htmlDOMスナップショット（常に利用可能、CDP不要）
log/project-guide.jsonプロジェクトタイプ、API/ビジネス/ルーティング/設定階層、エイリアスと計画の推奨
log/guard-report.json最新のコミット前guard JSONレポート

関連スキル

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community