Vite Agent Debugger

讓在 Vite 專案裡工作的 agent 擁有運行時視野，執行「讀日誌 → 定位 → 改 → 重啟 dev → 再讀驗證」的自癒閉環。配套 npm 套件 vite-plugin-agent-eyes（原始碼在本目錄 src/，可 npm publish 或 git 安裝）。如果只需要 agent 操作流程，優先讀 AGENT_GUIDE.md；如果要讓 Codex、Claude、Gemini、Hermes 主動發現並使用，讀 AGENT_BOOTSTRAP.md；README 面向人類安裝和評估。

何時用

使用者回報「頁面壞了 / 登入不上 / 請求失敗 / cookie 問題」，但你不該靠猜程式碼——先讀遙測。
你自己改完要驗證：重啟 dev、觸發操作、讀日誌確認行為對了。
需要還原已登入 UI 或瀏覽器控制時，先看 log/<port>/auth-state.json 確認當前帳號畫像，再看 log/<port>/interaction.log 還原最近互動路徑。
使用者提交被 guard 阻斷或要求提前規避明顯錯誤 / 屎山訊號時，先讀 log/guard-report.json。
給一個還沒接入的 Vite 專案裝上這套自癒能力。

接入（一次性，預設 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`；提交後飛書通知。自帶 rebase/cherry 重放去重
`agentGuard`	提交時	硬擋 staged：secret/超大檔案/超長行數/TODO/any/console.log。已用 agentGit 就配進 `agentGit({ guard })`，別再單獨掛（爭用 pre-commit）
`agentSizeWatch`	dev 寫碼當下	超長檔案在控制台 `[agent-eyes:size]` warn，只警告不阻斷。專治 AI 堆超長 CSS

典型配置（本專案三倉在用的形態）：

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 } },  // 硬擋屎山
  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 前必須知道（否則會以為是 bug）：

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 files；最近一次 JSON 報告在 log/guard-report.json。
完整選項表見 README ### agentGit / agentGuard / agentSizeWatch API 段。

自癒閉環（核心，照此執行）

先讀 log/README.md —— 專案自描述，確認當前埠日誌在哪、各流看什麼。
讀 log/project-guide.json —— 先看專案類型、API/業務/路由/配置層級和 @ alias 建議。
讀 log/<port>/errors.log —— 定位「哪壞了」（最新在最上，head 即可）。
按線索下鑽：
- 重現路徑不清 → 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 看阻斷 / 預警明細。
雜訊預判：未登入時 /auth/session 的 401、瀏覽器擴充套件的 runtime.lastError 都是預期雜訊，不是 bug，別去追。
改程式碼 → 重啟 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.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 報告

webkubor/vite-plugin-agent-eyes

vite-plugin-agent-eyes 是什麼？

在你喜歡的 AI 中提問

說明文件

Vite Agent Debugger

何時用

接入（一次性，預設 1 步）

提交治理：agentEyes / agentGit / agentGuard / agentSizeWatch（配置速查）

自癒閉環（核心，照此執行）

招牌診斷：登入成功卻一直 401

日誌速查

相關技能

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me