| name | debug-helper |
| version | 1.0.0 |
| description | 除錯輔助，包裝 PAL MCP 的 debug 功能，提供系統化問題診斷 |
| author | miles990 |
| tags | debugging, troubleshooting, diagnosis, error-handling |
| dependencies | [object Object] |
| interface | [object Object] |
| triggers | [object Object], [object Object], [object Object] |
Debug Helper
收集錯誤 → 分析原因 → 診斷問題 → 提出解法
核心理念
┌─────────────────────────────────────────────────────────────────┐
│ 不重複造輪子，直接使用 PAL MCP 的專業診斷能力 │
│ │
│ 本 Skill 職責： │
│ • 收集錯誤資訊和上下文 │
│ • 調用 PAL debug 進行診斷 │
│ • 整理診斷結果 │
│ • 與 smart-learning-loop 協作（失敗時學習） │
└─────────────────────────────────────────────────────────────────┘
使用方式
調用 PAL debug
await mcp__pal__debug({
step: "診斷登入失敗問題",
step_number: 1,
total_steps: 2,
next_step_required: true,
findings: "初始診斷",
hypothesis: "可能是 token 過期",
relevant_files: [
"/path/to/auth.js"
],
model: "gemini-2.5-pro"
})
失敗類型分類
┌─────────────────────────────────────────────────────────────────┐
│ 失敗類型 處理方式 │
├─────────────────────────────────────────────────────────────────┤
│ 類型 A: 知識缺口 → smart-learning-loop │
│ ├─ 症狀：不知道怎麼做 │
│ └─ 處方：搜尋技能 → 安裝 → 學習 │
│ │
│ 類型 B: 執行錯誤 → 重新檢查程式碼 │
│ ├─ 症狀：語法錯誤、參數錯誤 │
│ └─ 處方：仔細檢查，修正錯誤 │
│ │
│ 類型 C: 環境問題 → 修復環境 │
│ ├─ 症狀：依賴缺失、版本不符 │
│ └─ 處方：安裝依賴、切換版本 │
│ │
│ 類型 D: 策略錯誤 → 切換策略 │
│ ├─ 症狀：方法不適合當前情境 │
│ └─ 處方：從策略池選擇其他方案 │
│ │
│ 類型 E: 資源限制 → 優化或換方案 │
│ ├─ 症狀：記憶體不足、API 限制 │
│ └─ 處方：優化資源使用、分批處理 │
└─────────────────────────────────────────────────────────────────┘
診斷流程
┌─────────────────────────────────────────────────────────────────┐
│ 1. 收集資訊 │
│ → 錯誤訊息、堆疊追蹤、相關程式碼 │
│ │
│ 2. 分類失敗類型 │
│ → 是知識缺口？執行錯誤？環境問題？ │
│ │
│ 3. 調用 PAL debug │
│ → 深度診斷問題根因 │
│ │
│ 4. 提出假設 │
│ → 根據症狀推測原因 │
│ │
│ 5. 驗證假設 │
│ → 測試假設是否正確 │
│ │
│ 6. 提出解法 │
│ → 具體的修正步驟 │
└─────────────────────────────────────────────────────────────────┘
輸出格式
diagnosis:
error_type: "執行錯誤"
category: "B"
symptoms:
- "TypeError: Cannot read property 'map' of undefined"
- "發生在 UserList.jsx:42"
hypothesis: "users 資料在渲染時還沒載入完成"
confidence: "high"
root_cause:
file: "UserList.jsx"
line: 42
issue: "未處理 loading 狀態"
solution:
steps:
- "加入 loading 狀態檢查"
- "在資料載入前顯示 loading UI"
code_fix: |
if (loading) return <Loading />;
if (!users) return null;
return users.map(...)
prevention:
- "使用 TypeScript 確保型別安全"
- "加入單元測試覆蓋 loading 狀態"
next_action: "套用修正並重新測試"
最小範例
錯誤：TypeError: Cannot read property 'map' of undefined
AI 執行 debug-helper：
1. 收集資訊：
- 錯誤訊息：Cannot read property 'map'
- 位置：UserList.jsx:42
- 程式碼：users.map(...)
2. 分類：類型 B（執行錯誤）
3. 調用 PAL debug
4. 診斷結果：
┌─────────────────────────────────────────────────────┐
│ 🔍 Debug 診斷 │
│ │
│ 問題：users 在渲染時為 undefined │
│ 原因：非同步資料未載入完成就嘗試渲染 │
│ 信心度：高 │
│ │
│ 解法： │
│ 1. 加入 loading 狀態檢查 │
│ 2. 處理 undefined 情況 │
│ │
│ 修正程式碼： │
│ if (!users) return <Loading />; │
│ return users.map(...) │
│ │
│ 預防措施： │
│ • 使用 TypeScript │
│ • 加入 loading 狀態測試 │
└─────────────────────────────────────────────────────┘
要我幫您套用這個修正嗎？
與其他 Skill 的協作
┌─────────────────────────────────────────────────────────────────┐
│ 失敗處理流程 │
│ │
│ [執行失敗] → [debug-helper] → 診斷 │
│ │ │
│ ┌────────────┼────────────┐ │
│ ↓ ↓ ↓ │
│ 類型 A 類型 B-E 無法解決 │
│ ↓ ↓ ↓ │
│ [smart-learning] 修正 詢問用戶 │
│ ↓ ↓ │
│ 學習技能 重新執行 │
└─────────────────────────────────────────────────────────────────┘
與 smart-learning-loop 整合
當診斷結果是「知識缺口」時：
// 診斷結果
if (diagnosis.category === 'A') {
// 觸發學習迴圈
await smartLearningLoop({
task: currentTask,
gap: diagnosis.root_cause.skill_needed
});
}
設計原則
- 不重複造輪子 - 直接使用 PAL debug 的能力
- 系統化診斷 - 有步驟、有分類
- 假設驅動 - 先假設再驗證
- 記錄經驗 - 診斷結果記錄到 Cipher
- 協作整合 - 與其他 Skill 配合
限制與邊界
- 依賴 PAL MCP 的可用性
- 診斷品質取決於錯誤資訊的完整度
- 複雜問題可能需要多輪診斷
- 無法處理所有類型的問題