# error-handling

> 錯誤處理與恢復策略知識。自動載入於遇到錯誤、異常、失敗需要處理的情境。
觸發詞：error, 錯誤, exception, 異常, fail, 失敗, retry, 重試, fallback, 回退, recover, 恢復

- Author: SBU
- Repository: ryu111/claude-workflow
- Version: 20260125172738
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/ryu111/claude-workflow
- Web: https://mule.run/skillshub/@@ryu111/claude-workflow~error-handling:20260125172738

---

---
name: error-handling
description: |
  錯誤處理與恢復策略知識。自動載入於遇到錯誤、異常、失敗需要處理的情境。
  觸發詞：error, 錯誤, exception, 異常, fail, 失敗, retry, 重試, fallback, 回退, recover, 恢復
user-invocable: false
disable-model-invocation: false
---

# 錯誤處理知識

## 錯誤分類

### 按可恢復性

| 類型 | 說明 | 處理策略 |
|------|------|----------|
| 🟢 可重試 | 暫時性問題 | 自動重試 |
| 🟡 可修復 | 需要調整後重試 | 修復後重試 |
| 🔴 致命 | 無法繼續 | 報告並停止 |

### 常見錯誤類型

```
可重試錯誤：
- 網路超時 (ETIMEDOUT)
- 連線拒絕 (ECONNREFUSED)
- 服務暫時不可用 (503)
- Rate limit (429)

可修復錯誤：
- 檔案不存在 (ENOENT) → 建立檔案
- 權限不足 (EACCES) → 請求權限
- 驗證失敗 → 修正輸入

致命錯誤：
- 語法錯誤 → 需人工修復
- 依賴缺失 → 需安裝依賴
- 配置錯誤 → 需修正配置
```

## 重試策略

### 指數退避

```
第 1 次重試：等待 1 秒
第 2 次重試：等待 2 秒
第 3 次重試：等待 4 秒
最大重試：3 次
```

### 重試決策樹

```
錯誤發生
    │
    ├─ 是可重試錯誤？
    │   ├─ 是 → 重試次數 < 3？
    │   │       ├─ 是 → 等待後重試
    │   │       └─ 否 → 標記為可修復錯誤
    │   └─ 否 → 繼續判斷
    │
    ├─ 是可修復錯誤？
    │   ├─ 是 → 嘗試自動修復
    │   │       ├─ 修復成功 → 重試操作
    │   │       └─ 修復失敗 → 請求用戶協助
    │   └─ 否 → 繼續判斷
    │
    └─ 致命錯誤 → 保存狀態並報告
```

## 自動修復策略

### 檔案相關

| 錯誤 | 自動修復 |
|------|----------|
| 目錄不存在 | `mkdir -p` 建立目錄 |
| 檔案不存在 | 建立空檔案或從範本建立 |
| 編碼問題 | 嘗試 UTF-8 重新讀取 |

### 依賴相關

| 錯誤 | 自動修復 |
|------|----------|
| npm 套件缺失 | `npm install` |
| Python 套件缺失 | `pip install` |
| 版本不符 | 提示升級指令 |

### Git 相關

| 錯誤 | 自動修復 |
|------|----------|
| 未 commit 的變更 | 提示 stash 或 commit |
| 合併衝突 | 標記衝突，請求用戶解決 |
| 分支不存在 | 提示建立或切換 |

## 錯誤報告格式

### 標準格式

```markdown
## ⚠️ 錯誤報告

### 錯誤類型
[可重試 | 可修復 | 致命]

### 發生位置
**步驟**: [哪個步驟]
**檔案**: [相關檔案]
**行數**: [如果適用]

### 錯誤訊息
```
[原始錯誤訊息]
```

### 分析
[為什麼會發生這個錯誤]

### 建議行動
1. [行動 1]
2. [行動 2]

### 自動修復
[如果可以自動修復，說明將執行什麼]
```

## 優雅降級

### 降級策略

```
主要方案失敗
    │
    ├─ 嘗試備用方案 A
    │   └─ 失敗 → 嘗試備用方案 B
    │               └─ 失敗 → 最小功能模式
    │
    └─ 成功 → 繼續執行（標記已降級）
```

### 範例

```
場景：API 呼叫失敗

主要方案：呼叫外部 API
備用方案 A：使用本地快取
備用方案 B：使用預設值
最小功能：跳過該功能，繼續其他任務
```

## 錯誤追蹤

### 錯誤日誌結構

```yaml
errors:
  - timestamp: "2024-01-01T10:30:00Z"
    type: "retryable"
    code: "ECONNREFUSED"
    message: "Connection refused"
    context:
      step: "fetch_data"
      attempt: 2
    resolution: "retry_success"

  - timestamp: "2024-01-01T10:31:00Z"
    type: "recoverable"
    code: "ENOENT"
    message: "File not found: config.json"
    context:
      step: "read_config"
    resolution: "auto_created"
```

## 用戶通知時機

### 需要通知

- 致命錯誤（必須）
- 重試 3 次後仍失敗
- 自動修復後需確認
- 降級執行時

### 不需通知

- 第 1-2 次重試
- 自動修復成功且不影響結果
- 可預期的警告

## 資源

### Templates

- [error-report.md](templates/error-report.md) - 錯誤報告範本

### References

- [error-codes.md](references/error-codes.md) - 錯誤碼完整參考表