BugEzy MCP Voice Debug Tool Dev Guide

BugEzy 平台開發規範

平台概覽

亞洲專屬平價 MCP 語音除錯工具。開發者用中文語音錄 Bug → 自動產出 DOM 軌跡 + Console + Network + 中文字幕 → 一鍵分享 → AI 透過 MCP Pull 模式直接讀取修復。 FOX 是唯一創辦人（同時也是 LottoShare 創辦人），外送員 + 雙專案創業者。

角色分工

• Claude Chat（Opus） = PM/策略，出任務、驗收、維護文件
• Claude Code（Sonnet，在 Zed 編輯器） = 工程師，讀 job 檔執行
• FOX = 最高管理員 + 手動驗收

七代迭代計畫

代	名稱	狀態
① 能錄能存	Chrome 擴充骨架（rrweb + Console + Network）	✅ 完成
② 能聽能說	Web Speech API 中文語音辨識	✅ 完成
③ 能存能看	Cloudflare Workers + Supabase + R2 + React 報告頁	✅ 完成
④ AI 能讀	MCP Server（Pull 模式 12 Tool，回應附 token 省錢對比）= MVP 封測	✅ 完成
⑤ 能收錢	Google OAuth 登入 + 產品首頁（含聯絡資訊）+ 隱私政策頁 + 用量限制 + 兩層定價 + 使用指南/FAQ 頁 + Web Store 文案/zip + 綠界 ECPay 金流（測試環境跑通：單次 + 定期定額月訂閱 + 取消訂閱，CheckMacValue 對官方測試向量驗證）（PM-61~75）→ Chrome Web Store 已送審 + 綠界補件已重送（2026-06-29）；換正式 key + 等審核通過	🔨 進行中（PM-75，待審）
⑥ 更好用	六模式（錄製/⏪回溯/截圖/🔍即時監控/🔇鍵盤/🖥終端機CLI）+ 跨頁錄製 + 時間軸標記 + AI精簡/校正 + 乾淨toggle；上架前打磨（跨頁游標/CSP 相容/語音穩定，PM-68~70）	✅ 完成（PM-2761, 6870）
⑦ 規模化	日韓越語音、跨境除錯鏈、企業自託管	待做

技術架構（第 2 代完成後）

Chrome 擴充（Manifest V3 + TypeScript + esbuild）
├── inject.ts（MAIN world）
│   ├── rrweb DOM 側錄
│   ├── Console 攔截（warn/error）
│   ├── Network 攔截（fetch/XHR 4xx+5xx）
│   └── SpeechRecognition 語音辨識（zh-TW）
├── content.ts（ISOLATED world）— postMessage 橋接 + storage
├── background.ts（Service Worker）— 狀態管理 + Badge
└── popup.ts + popup.html — 三態 UI + 複製/匯出 JSON

專案路徑

• 主專案：C:\dev\bugezy
• 接手指南：docs/BugEzy_project_status.md（270 行，§1~§11 完整全貌）

技術棧

• Chrome 擴充：Manifest V3 + TypeScript + esbuild
• DOM 側錄：rrweb 2.0-alpha（JSON，非影片）
• 語音辨識：Web Speech API（inject.ts MAIN world + 頁面授權橫幅）
• 語音降級：Groq Whisper API（待第 6 代）
• 後端 API：Cloudflare Workers（✅ 已部署 bugezy-api.bugezy-api.workers.dev：reports + /mcp + /api/summarize）
• 資料庫：Supabase PostgreSQL + Auth（✅ reports 表上線；Auth 待第 5 代）
• 檔案儲存：Cloudflare R2（✅ rrweb + screenshots 大檔）
• Web 報告頁：React + Vite（✅ @rrweb/replay 回放 + 四面板 + 深色主題）
• MCP Server：stdio（mcp-server/）+ Workers /mcp（12 Tool，加 get_live_errors/get_terminal_logs/get_screenshots/get_usage_stats；每次回應附 token 省錢 footer）（✅ 已驗證）
• 截圖標注：annotate.html canvas（畫筆/箭頭/框/文字）+ 三擷取模式 + 即時字幕（✅ 第 6 代）
• AI 精簡：Cloudflare Workers AI @cf/meta/llama-3.3-70b-instruct-fp8-fast（✅ 已部署）
• 跨頁錄製：inject 即時 flush → background chrome.storage.local buffer → STOP 合併去重（PM-34~37，頁面跳轉不丟資料）
• 編輯頁：停止後 edit-report（@rrweb/replay mini player + 時間軸標記 📌 + 乾淨/原始 toggle + AI 精簡），markers 經 MCP get_report_overview 可讀
• ⏪ 30 秒回溯：inject 背景循環緩存（不必先按錄製），按⏪打包最近 30s（PM-50）
• 🔍 即時監控：背景每 10s 推 live errors → R2 暫存 → AI 經 MCP get_live_errors 查當前頁，不產報告、token 極低（PM-51/52）
• 🖥 終端機 CLI：cli/ npx bugezy-watch -- <command> 攔截 stderr/throw/crash → R2 → MCP get_terminal_logs（PM-53）
• 測試專頁：server GET /test + page2/3 + /test/api/:status（可預測 Bug 場景，PM-48）
• 即時監控/終端機暫存：Cloudflare R2 單一物件（非全域 Map — 跨 Worker isolate 才一致）
• Token 省錢透明度：MCP 每次回應附 token 估算 + 對比 Claude in Chrome 省錢 %（PM-54）；edit-report 上傳前各區塊估算（PM-55）；Supabase mcp_usage 月度統計 GET /api/usage/monthly + MCP get_usage_stats（PM-56，記錄要 await 否則 Workers 提前終止丟寫入）
• 報告頁：Server 直接 serve GET /report/:id HTML（深色 DevTools Tab 分頁 + Token，vanilla JS 讀 /api/reports/:id，PM-59）；web React 版 ReportPage 同款 Tab（PM-58，Worker 未服務 SPA，靠 Vite 預覽）
• AI 語音：精簡 /api/summarize（Llama 3.3，轉重點）+ 校正 /api/correct（Llama 3.3，修錯字/去贅字/還原術語、保留原意，PM-60c）。踩雷：測中文 API 用 Python 送 UTF-8，別用 Windows Git-Bash curl（會把 body 編碼壞 + 終端機顯示花掉）
• 登入：Google OAuth（chrome.identity.getAuthToken + manifest oauth2/identity）→ POST /api/auth/google（Google userinfo 驗 → Supabase users）→ session 存 storage；報告帶 user_id（PM-61，第 5 代前置；擴充 ID 須對上 Google Console 註冊值）
• 對外頁面（上架/審核用）：產品首頁 GET /（HOMEPAGE_HTML，Hero + 六模式 + 兩層定價 + 聯絡 email，PM-62/65）+ 隱私政策 GET /privacy（PRIVACY_PAGE_HTML，中英雙語，PM-64）+ 使用指南 GET /guide（四步驟 + 六模式 + MCP 設定）+ FAQ GET /faq（手風琴 14 題，PM-66）。皆深色主題、無 JS、RWD；首頁 footer 串四頁。Chrome Web Store 上架文案存 docs/chrome-web-store.md（PM-67，權限說明依實際 manifest 校正）。綠界 ECPay 已送審
• 上架前打磨（PM-68~70，皆待瀏覽器實機驗收）：跨頁回放游標（edit-report injectCrossPageCursor 每段新 FullSnapshot 後補合成 MouseMove）；CSP 相容（注入早是宣告式 world:MAIN 免改，inject.ts 把頁面 MAIN world 的 innerHTML 改 DOM+textContent 以過 Trusted Types 如 GitHub）；語音穩定（inject.ts 補 onstart 重置計數、onerror 分類 no-speech/audio-capture/權限/其他、統一狀態指示 🟢🟡🔴）
• popup 版本更新通知（PM-71）：checkVersionNotice() 用 chrome.storage.local 的 bugezy:lastVersion 比對 manifest 版本，有舊記錄且不同才跳 .update-notice 卡片（首裝不跳）。Web Store 打包：PowerShell + .NET ZipFile.CreateFromDirectory 從 dist/ 取執行期 11 檔（排 .map）→ bugezy-v0.1.0.zip（manifest 在根）；offscreen/icons 實際不存在故不含
• 綠界 ECPay 金流（PM-72/72b/73，測試環境跑通）：GET /checkout?user_id= 回自動提交綠界表單（含定期定額 Period 參數，月扣 NT$80）→ 付款 → POST /api/ecpay/callback（首期）/POST /api/ecpay/period-callback（第 2 期起）驗 CheckMacValue → 更新 users.plan（成功 paid/失敗 free，並記 ecpay_trade_no + 展延 plan_expires_at）→ POST /checkout/result 結果頁。取消訂閱（PM-73）：POST /api/user/cancel 呼叫綠界 /Cashier/CreditCardPeriodAction（Action=Cancel + TimeStamp，非 /CreditDetail/DoAction） → 標 plan='cancelled'（用量檢查視同 paid，到期由 /api/user/plan 自動降 free）；popup 顯「取消訂閱」/「已取消，可用到 YYYY/MM/DD」。plan 三態：free/paid/cancelled。popup 升級鈕開 /checkout。CheckMacValue 踩雷：依綠界官方 AI Skill ECPay/ECPay-API-Skill（guides/13 + test-vectors；端點/欄位看 guides/01）——TS 的 encodeURIComponent 不編碼 ~/'，需額外 ~→%7e、'→%27、%20→+ 再小寫 + 還原 .NET 7 字元；Workers 無同步 crypto 改用 crypto.subtle（async SHA256）。務必對官方 8 個測試向量驗證。測試帳號 MerchantID 3002607（公開），正式上線換正式 key（HASH_KEY/IV 建議 wrangler secret）。schema：users 加 ecpay_trade_no/plan_expires_at（FOX 跑 ALTER）
• 用量限制（PM-63）：FREE_LIMITS（錄製 10／回溯 5／MCP 20 月）+ getUserIdFromHeader（解 Bearer base64(user_id:ts)）；GET /api/user/plan（查方案 + 剩餘 + 跨月自動重置）、POST /api/user/usage（遞增，免費版達上限回 403 limit_reached、付費版 unlimited）。popup 顯示「剩 N 次／已用完」+ 升級提示；background 錄製前 checkRecordingUsage()（未登入/API 不通不擋）。schema 加 users.recording_count/rewind_count/mcp_count/usage_reset_at。目前僅 recording 串前端，rewind/mcp 後端就緒待接