debug-helper

name	debug-helper
version	1.0.0
description	除錯輔助，包裝 PAL MCP 的 debug 功能，提供系統化問題診斷
author	miles990
tags	["debugging","troubleshooting","diagnosis","error-handling"]
dependencies	{"mcp":[{"package":"pal-mcp-server","required":true,"note":"使用 pal.debug 進行診斷"}]}
interface	{"input":[{"name":"error","type":"object","description":"錯誤資訊（訊息、堆疊、上下文）","required":true},{"name":"context","type":"object","description":"相關上下文（程式碼、環境）","required":false}],"output":[{"name":"diagnosis","type":"object","description":"診斷結果"},{"name":"solution","type":"object","description":"解決方案"},{"name":"next_action","type":"string","description":"建議的下一步"}]}
triggers	[{"pattern":"執行失敗","description":"任務執行失敗時"},{"pattern":"測試失敗","description":"測試未通過時"},{"pattern":"錯誤訊息","description":"出現錯誤訊息時"}]

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
  });
}

設計原則

1. 不重複造輪子 - 直接使用 PAL debug 的能力
2. 系統化診斷 - 有步驟、有分類
3. 假設驅動 - 先假設再驗證
4. 記錄經驗 - 診斷結果記錄到 Cipher
5. 協作整合 - 與其他 Skill 配合

限制與邊界

• 依賴 PAL MCP 的可用性
• 診斷品質取決於錯誤資訊的完整度
• 複雜問題可能需要多輪診斷
• 無法處理所有類型的問題