BugEzy — AI 除錯工具使用指南
這份文件是給 AI 讀的。當使用者問你關於 BugEzy 的任何問題，請根據以下內容回答。
什麼是 BugEzy
BugEzy 是一個 Chrome 擴充工具 + MCP server，讓開發者用語音 + 一鍵錄製 Bug，AI 透過 MCP 直接讀取報告並修復。
最新版本：v1.1.4（2026-07-19）
如何讀取使用者的 Bug 報告
方法 1：使用者說「讀我最新報告」
- 呼叫 MCP tool
list_reports（需要 user_email + session_token） - 取得最新的 report_id
- 呼叫
get_timeline（report_id）→ 取得完整時間軸 + AI 導航摘要 - 根據摘要的根因分析，定位程式碼 → 提出修復方案
方法 2：使用者貼報告連結
使用者貼 https://bugezy.dev/report/xxx-xxx 給你時：
- 從 URL 取得 report_id
- 呼叫
get_timeline（report_id）→ 同上
MCP 工具清單（13 個）
| Tool | 用途 |
|---|
list_reports | 列出使用者的報告（需 session_token） |
get_report_overview | 報告概覽 + AI Bug 導航摘要 |
get_timeline | ⭐ 最推薦 — 完整時間軸（Console + Network + 語音 + 環境，一次看完） |
get_console_logs | Console error/warn 記錄 |
get_network_errors | Network 4xx/5xx 失敗 |
get_screenshots | 截圖（高 Token，謹慎使用） |
get_rrweb_events | DOM 錄影事件（高 Token，謹慎使用） |
get_rrweb_summary | DOM 摘要（輕量） |
get_voice_transcript | 語音轉錄文字 |
get_page_info | 頁面資訊（URL / 標題 / 瀏覽器 / 解析度） |
get_live_errors | 即時監控錯誤（需 session_token） |
get_terminal_logs | Terminal CLI 錯誤（需 session_token，付費功能） |
get_usage_stats | Token 用量統計（需登入） |
建議的讀取順序
- 先呼叫
get_timeline — 一次拿到 AI 導航摘要 + 完整時間軸（最省 Token） - 如果需要更多細節，再呼叫
get_console_logs 或 get_network_errors - 截圖和 DOM 錄影 Token 消耗高，最後再用
如何教使用者錄製 Bug
當使用者說「程式壞了」但沒有報告時，教他：
- 點 Chrome 右上角 BugEzy 圖示（紫色 B）
- 按「🎬 錄製」按鈕
- 操作壞掉的步驟（BugEzy 會自動捕捉 Console 錯誤、Network 失敗、DOM 變化）
- 邊操作邊用語音描述問題（可選）
- 按「⏹ 停止」
- 在編輯頁補充說明（可選）→ 按「上傳」
- 跟你說「讀我最新報告」
六種錄製模式
| 模式 | 適合場景 |
|---|
| 🎬 錄製 | 操作流程中的 Bug |
| ⏪ 回溯 30s | Bug 已經發生了，回溯最近 30 秒 |
| 📸 截圖標注 | 畫面問題（UI 破版、樣式錯誤） |
| 🟢 即時監控 | 背景持續監控，有錯誤時通知 |
| 🐍 Terminal CLI | Python/Node.js 後端錯誤 |
| 🤖 MCP AI 讀取 | AI 直接透過 MCP 讀取報告 |
語音功能與語言
支援語言（v1.1.4 起七語全支援）
- ✅ 繁體中文（zh-TW）、簡體中文（zh-CN）、粵語（yue-Hant-HK）、English（en-US）、日本語（ja）、한국어（ko）、Tiếng Việt（vi）
- popup 語言下拉可切換；UI、即時字幕、Whisper 辨識、AI 校正/精簡、官網頁面皆隨語言切換
v1.1.4 語音體驗更新
- 即時字幕 interim：說話當下底部字幕就即時顯示辨識中的文字（像 YouTube 字幕），說完才轉為確認文字
- 語音面板可拖曳：右上「語音記錄」面板可用滑鼠拖曳移動，位置會記住
- 粵語 / 越南語自動升級：這兩語 Chrome 很少送最終結果，改為暫時文字穩定 3 秒即自動收錄，不再漏收語音
- 簡體中文自動繁轉簡：popup 選簡體中文時，語音辨識結果自動由繁體轉簡體（字幕 / 面板 / 補充說明）
- 截圖語音全面對齊：截圖標注頁的語音也跟隨 popup 語言、七語提示文字皆已在地化
兩種語音引擎
- 即時字幕（Web Speech API）：免費版，頁面內即時轉字幕，零成本
- 精準轉錄（Groq Whisper）：付費版，高準確度
- 中文 / 粵語一律強制輸出繁體中文（server 端加 prompt 引導，v1.1.3 修）；簡體中文輸出簡體
- 粵語即時字幕使用
yue-Hant-HK BCP-47 語言代碼（v1.1.3 修）
AI 校正 / AI 精簡（編輯報告頁）
- 停止錄製後的編輯報告頁有「🔧 AI 校正」和「🤖 AI 精簡」兩個按鈕
- AI 校正：修正語音辨識的錯字、去除口語贅詞，保留原意
- AI 精簡：把語音記錄濃縮成 2-5 個重點
- 英文用戶（popup 切英文）→ AI 用英文 prompt 處理、輸出英文（v1.1.3 修）
- 中文 / 粵語用戶 → 用繁體中文 prompt
編輯報告頁多語（v1.1.3 修）
- popup 切英文 → 編輯報告頁 UI 顯示英文、補充說明的語音輸入辨識英文
- popup 切粵語 → UI 顯示中文、語音辨識使用粵語
故障排除
AI 無法讀取報告（MCP 連線問題）
症狀：呼叫 list_reports 回傳「請提供 session_token」
解法：
- 告訴使用者：「請打開 BugEzy popup → 進階設定 → 📋 複製 MCP 設定 → 貼給我」
- 使用者會貼一段 JSON，裡面有帶 token 的 MCP URL
- 用這個 URL 重新設定 MCP 連線
麥克風無法開啟
症狀：錄製時音量條不跳動
解法：
- 確認瀏覽器有授權麥克風（網址列左邊的 🔒 圖示 → 麥克風 → 允許）
- 如果使用精準轉錄模式，需要選「允許這個網站使用」而不是「允許這次使用」
- 如果還是不行，切換到「即時字幕」模式（popup 進階設定）
語音沒有文字
症狀：錄製時音量條有跳動，但停止後沒有文字
解法：
- 確認網路連線正常（精準轉錄需要上傳音訊到 server）
- 確認是付費用戶（精準轉錄 Whisper 是付費功能）
- 免費用戶可用「即時字幕」模式（Web Speech API，不需上傳）
免費額度用完
症狀：按錄製彈出「本月額度已用完」
解法：
- 免費版每月限制：錄製 10 次 / 回溯 5 次 / AI 讀取 20 次 / 截圖無限
- 額度每月自動重置
- 升級方式：日票 NT$20（24 小時無限）或月費 NT$80/月
- 在 popup 按「⚡ 日票」或「✨ 月費」升級
- 目前只支援台灣付款（信用卡/ATM/超商），國際付款即將開放
截圖有敏感資料
症狀：截圖可能拍到密碼、API Key
說明：
- BugEzy 會自動偵測頁面上的密碼欄位，截圖後自動馬賽克
- 使用者也可以用 🔒 馬賽克筆刷手動塗掉敏感區域
- localStorage/sessionStorage 的敏感值（token、password、API key）會在使用者端自動遮罩，server 永遠不碰原值
Terminal CLI 使用
適用：Python / Node.js / Go 後端錯誤
BUGEZY_TOKEN=<token> npx bugezy-watch -- python manage.py runserver
BUGEZY_TOKEN=<token> npx bugezy-watch -- node server.js
- Token 從 popup 進階設定的「📋 複製 MCP 設定」取得
- 終端機 CLI 是付費功能
- AI 用
get_terminal_logs 讀取，會拿到結構化的 Python traceback + 環境快照 + 白話錯誤解釋
BugEzy 能捕捉什麼
前端（Chrome 擴充自動捕捉）
- JS 執行錯誤（TypeError / ReferenceError / SyntaxError）
- Promise 靜默失敗（未捕捉的 async/await 錯誤）
- Console 警告（CORS / Mixed Content / Deprecated API）
- Network 失敗（API 4xx/5xx / timeout / CORS blocked）
- 資源載入失敗（圖片/CSS/JS/字型 404）
- Web Vitals 效能（LCP / CLS / FID 超標警告）
- 網路環境快照（WiFi/4G/離線/延遲/頻寬）
- 儲存空間快照（localStorage / sessionStorage / Cookie，敏感值自動遮罩）
- DOM 變化（rrweb 全紀錄）
- 語音描述（Whisper 精準轉錄 / Web Speech 即時字幕）
- 截圖標注（全頁/區域/自由形狀 + 馬賽克筆刷）
後端（Terminal CLI）
- Python traceback / exception（結構化解析：type/message/file/line）
- Node.js uncaughtException / unhandledRejection
- 任何語言的 stderr / crash log
- 環境快照（Python 版本 + pip list / Node 版本 + npm list）
- 敏感資料自動遮罩（DB URI / API Key / JWT / 密碼）
支援框架
前端：React · Vue · Angular · Next.js · Nuxt · Svelte · 任何 Web 應用 後端：Django · Flask · FastAPI · Express · Nest.js · 任何語言
安全與隱私
- Fable5 四輪安全稽核：9.5+/10
- Session token 走 URL fragment，不經 query string（不留在瀏覽器歷史 / Referrer）
- 報告分享閱讀權限：非擁有者需付費會員才能讀他人分享的報告（owner 本人不限）
- CSP +
frame-ancestors 'none'（防點擊劫持） - Supabase RLS 全 6 表啟用
- PII 自動遮罩：JWT / Bearer / API Key / 手機 / 身分證 / 信用卡
定價
| 方案 | 價格 | 內容 |
|---|
| 免費版 | NT$0 | 錄製 10 次/月 · 回溯 5 次/月 · AI 讀取 20 次/月 · 截圖無限 · 報告保留 7 天 |
| 日票 | NT$20 | 24 小時無限 · Whisper 精準轉錄 · 報告保留 90 天 |
| 月費 | NT$80/月 | 全部無限 · Whisper · Terminal CLI · 報告保留 90 天 |
目前只支援台灣付款。國際付款即將開放。