提供結構化、可操作的錯誤訊息
錯誤格式化模組將原始錯誤轉換為結構化、使用者友好的訊息，包含診斷資訊和解決建議。
┌─────────────────────────────────────────────────────────────────┐
│ ❌ E-AGT-001: Agent 超時 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 📍 位置 │
│ 階段: IMPLEMENT > 視角: tdd-enforcer │
│ │
│ 📝 詳情 │
│ TDD 守護者執行超過 5 分鐘未完成，已超過預設超時限制。 │
│ │
│ 🔍 可能原因 │
│ • 測試套件過大，執行時間過長 │
│ • 存在無限迴圈或死鎖 │
│ • 外部依賴（如資料庫）回應緩慢 │
│ │
│ 💡 建議步驟 │
│ 1. 檢查測試套件大小，考慮拆分 │
│ 2. 檢查最近新增的測試是否有問題 │
│ 3. 增加超時限制：--agent-timeout 600 │
│ │
│ 🤖 自動處理 │
│ 狀態: 已自動重試 1 次 │
│ 結果: 仍然失敗 │
│ │
│ 📚 文檔 │
│ 詳見: docs/troubleshooting/E-AGT-001.md │
│ │
└─────────────────────────────────────────────────────────────────┘
| 欄位 | 必要 | 說明 |
|---|---|---|
| 錯誤碼 | 是 | 標準錯誤碼（E-XXX-NNN） |
| 標題 | 是 | 簡短描述 |
| 位置 | 是 | 發生位置（階段 > 視角） |
| 詳情 | 是 | 完整說明 |
| 可能原因 | 是 | 列出常見原因 |
| 建議步驟 | 是 | 可操作的解決步驟 |
| 自動處理 | 否 | 系統已嘗試的處理 |
| 文檔連結 | 是 | 詳細文檔路徑 |
| 嚴重度 | 圖示 | 邊框顏色 |
|---|---|---|
| CRITICAL | 🚨 | 紅色 |
| HIGH | ❌ | 橙色 |
| MEDIUM | 黃色 | |
| LOW | ℹ️ | 藍色 |
階段: {STAGE_NAME} > 視角: {PERSPECTIVE_ID}
範例:
階段: IMPLEMENT > 視角: tdd-enforcer
階段: REVIEW > 視角: code-quality
階段: VERIFY （無視角）
- 最多列出 5 個原因
- 按可能性由高到低排序
- 每個原因簡潔明瞭
- 步驟編號從 1 開始
- 每步驟一個明確動作
- 包含具體命令/參數
- 最多 5 個步驟
┌─────────────────────────────────────────────────────────────────┐
│ ❌ E-AGT-001: Agent 超時 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 📍 位置 │
│ 階段: {stage} > 視角: {perspective} │
│ │
│ 📝 詳情 │
│ {perspective_name} 執行超過 {timeout} 秒未完成。 │
│ │
│ 🔍 可能原因 │
│ • 任務複雜度過高 │
│ • 存在無限迴圈 │
│ • 外部依賴回應緩慢 │
│ • 網路問題 │
│ │
│ 💡 建議步驟 │
│ 1. 檢查任務是否可以拆分為更小的單元 │
│ 2. 增加超時限制：--agent-timeout {timeout*2} │
│ 3. 使用 --debug 模式查看詳細日誌 │
│ │
│ 📚 docs/troubleshooting/E-AGT-001.md │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ 🚨 E-WKF-001: 回退超限 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 📍 位置 │
│ 工作流: {workflow_id} │
│ 當前階段: {current_stage} │
│ │
│ 📝 詳情 │
│ 工作流已回退 {rollback_count} 次，超過上限 {max_rollbacks}。 │
│ 連續的審查/驗證失敗導致無法完成工作流。 │
│ │
│ 🔍 可能原因 │
│ • 需求理解有誤，導致持續錯誤實作 │
│ • 存在難以通過的技術障礙 │
│ • 審查標準過於嚴格 │
│ │
│ 💡 建議步驟 │
│ 1. 審查失敗原因清單（見下方） │
│ 2. 手動修復關鍵問題 │
│ 3. 考慮調整需求或降低標準 │
│ 4. 使用 --resume {workflow_id} 繼續 │
│ │
│ 📋 失敗歷程 │
│ • 迭代 1: BLOCKER - SQL 注入風險 │
│ • 迭代 2: BLOCKER - XSS 漏洞 │
│ • 迭代 3: HIGH - 測試覆蓋不足 │
│ │
│ 📚 docs/troubleshooting/E-WKF-001.md │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ ❌ E-MEM-001: Memory 讀取失敗 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 📍 位置 │
│ 路徑: {file_path} │
│ │
│ 📝 詳情 │
│ 無法讀取指定的 Memory 檔案。 │
│ 系統訊息: {system_error} │
│ │
│ 🔍 可能原因 │
│ • 檔案不存在或已被刪除 │
│ • 檔案權限不足 │
│ • 檔案被其他程序鎖定 │
│ • 路徑格式錯誤 │
│ │
│ 💡 建議步驟 │
│ 1. 確認檔案存在：ls -la {file_path} │
│ 2. 檢查檔案權限：chmod 644 {file_path} │
│ 3. 使用 --no-memory 跳過 Memory 讀取 │
│ │
│ 📚 docs/troubleshooting/E-MEM-001.md │
└─────────────────────────────────────────────────────────────────┘
使用 ANSI 顏色和格式：
\033[31m❌ E-AGT-001: Agent 超時\033[0m
📍 位置
階段: IMPLEMENT > 視角: tdd-enforcer
📝 詳情
TDD 守護者執行超過 5 分鐘未完成。
🔍 可能原因
• 測試套件過大
• 存在無限迴圈
💡 建議步驟
1. 檢查測試套件大小
2. 增加超時限制
📚 詳見: docs/troubleshooting/E-AGT-001.md
{
"error": {
"code": "E-AGT-001",
"title": "Agent 超時",
"severity": "HIGH",
"location": {
"stage": "implement",
"perspective": "tdd-enforcer"
},
"message": "TDD 守護者執行超過 5 分鐘未完成。",
"possible_causes": [
"測試套件過大，執行時間過長",
"存在無限迴圈或死鎖"
],
"suggested_actions": [
"檢查測試套件大小，考慮拆分",
"增加超時限制：--agent-timeout 600"
],
"auto_handling": {
"status": "retried",
"attempts": 1,
"result": "failed"
},
"documentation": "docs/troubleshooting/E-AGT-001.md",
"timestamp": "2026-01-24T10:30:00Z"
}
}## ❌ E-AGT-001: Agent 超時
**位置**: IMPLEMENT > tdd-enforcer
**詳情**: TDD 守護者執行超過 5 分鐘未完成。
**可能原因**:
- 測試套件過大
- 存在無限迴圈
**建議步驟**:
1. 檢查測試套件大小
2. 增加超時限制
📚 [詳細文檔](docs/troubleshooting/E-AGT-001.md)| 狀態 | 說明 |
|---|---|
not_attempted |
未嘗試自動處理 |
retrying |
正在重試 |
retried |
已重試（顯示次數和結果） |
resolved |
自動解決 |
escalated |
已升級給使用者 |
🤖 自動處理
狀態: 已重試 2 次
結果: 第 2 次成功
或
🤖 自動處理
狀態: 已重試 3 次
結果: 仍然失敗，需要人工介入
format_error:
input:
code: "E-AGT-001"
context:
stage: "implement"
perspective: "tdd-enforcer"
timeout: 300
error_message: "..."
auto_handling:
status: "retried"
attempts: 1
result: "failed"
output:
format: "terminal" | "json" | "markdown"<!-- 在 SKILL.md 中 -->
捕獲到錯誤時：
<!-- ERROR: format code=E-AGT-001 context={...} -->