代理自我反思除錯 是做什麼的？
當代理執行反覆失敗、消耗 tokens 卻無進展、在同一個工具上重複循環，或偏離原定任務時，請使用此技能。
這是一個工作流程技能，而非隱藏的運行時機制。它教導代理在升級給人類之前，先系統性地自我除錯。
何時激活
- 達到最大工具呼叫 / 循環限制失敗
- 反覆重試但無任何進展
- 上下文增長或提示偏移導致輸出品質下降
- 檔案系統或環境狀態與預期不符
- 工具失敗但可能透過診斷和較小的修正行動復原
範圍界限
此技能用於：
- 在盲目重試前捕獲失敗狀態
- 診斷常見的代理特定失敗模式
- 執行受控的復原行動
- 產生結構化的人類可讀除錯報告
請勿將此技能作為以下情況的主要來源：
- 程式碼變更後的功能驗證；請使用
verification-loop - 當存在更狹義的 ECC 技能時的特定框架除錯
- 當前執行環境無法自動強制執行的運行時承諾
四階段循環
階段 1：失敗捕獲
在嘗試恢復之前，先精確記錄失敗資訊。
捕獲內容：
- 錯誤類型、訊息及堆疊追蹤（如可用）
- 最後一次有意義的工具呼叫序列
- 代理當時嘗試要做的事
- 當前上下文壓力：重複的提示、過大的貼上記錄、重複的計劃或失控的筆記
- 當前環境假設：cwd、分支、相關服務狀態、預期檔案
最小捕獲範本：
## 失敗捕獲
- Session / 任務：
- 進行中的目標：
- 錯誤：
- 最後成功步驟：
- 最後失敗的工具 / 命令：
- 觀察到的重複模式：
- 需要驗證的環境假設：
階段 2：根本原因診斷
在改變任何事物之前，先將失敗匹配到已知模式。
| 模式 | 可能原因 | 檢查方式 |
|---|---|---|
| 達到最大工具呼叫 / 重複相同命令 | 循環或無退出觀察者路徑 | 檢查最近 N 次工具呼叫是否有重複 |
| 上下文溢出 / 推理品質下降 | 無限制的筆記、重複的計劃、過大的記錄 | 檢查近期上下文是否有重複和低訊號的大量內容 |
ECONNREFUSED / 超時 | 服務不可用或連接埠錯誤 | 驗證服務健康狀態、URL 和連接埠假設 |
429 / 配額耗盡 | 重試風暴或缺少退避機制 | 計算重複呼叫次數並檢查重試間隔 |
| 寫入後檔案遺失 / 差異過時 | 競爭條件、錯誤的 cwd 或分支偏移 | 重新檢查路徑、cwd、git 狀態和實際檔案是否存在 |
| 修正後測試仍然失敗 | 錯誤的假設 | 隔離確切失敗的測試並重新推導錯誤原因 |
診斷問題：
- 這是邏輯失敗、狀態失敗、環境失敗還是策略失敗？
- 代理是否遺失真正目標而開始最佳化錯誤的子任務？
- 失敗是確定性的還是短暫性的？
- 能驗證診斷的最小可逆行動是什麼？
階段 3：受控恢復
以改變診斷面貌的最小行動進行恢復。
安全的恢復行動：
- 停止反覆重試，重新陳述假設
- 修剪低訊號的上下文，僅保留活躍目標、阻礙因素和證據
- 重新檢查實際的檔案系統 / 分支 / 進程狀態
- 將任務縮小到一個失敗的命令、一個檔案或一個測試
- 從推測性推理切換到直接觀察
- 當失敗是高風險或受到外部阻礙時，升級給人類
除非你目前在當前環境中透過真實工具實際執行它們，否則不要聲稱不支援的自動修復行動，例如「重設代理狀態」或「更新執行環境設定」。
受控恢復檢查清單：
## 恢復行動
- 選擇的診斷：
- 採用的最小行動：
- 為何這項行動安全：
- 哪些證據可以證明修復有效：
階段 4：反思報告
以一份讓下一個代理或人類能清楚理解的報告結束。
## 代理自我除錯報告
- Session / 任務：
- 失敗：
- 根本原因：
- 恢復行動：
- 結果：成功 | 部分成功 | 受阻
- Token / 時間耗損風險：
- 後續需要處理的事項：
- 日後應編碼的預防性變更：
恢復啟發式規則
請依下列順序選擇干預方式：
- 用一句話重新陳述真正的目標。
- 驗證世界狀態，而非信任記憶。
- 縮小失敗範圍。
- 執行一個具辨別力的檢查。
- 然後才重試。
不良模式：
- 以稍微不同的措辭重試相同動作三次
良好模式：
- 捕獲失敗
- 分類模式
- 執行一個直接檢查
- 僅在檢查支援時才改變計劃
與 ECC 的整合
- 如果恢復後有變更程式碼，請使用
verification-loop。 - 當失敗模式值得轉化為直覺或後續技能時，請使用
continuous-learning-v2。 - 當問題並非技術失敗而是決策模糊時，請使用
council。 - 如果失敗來自衝突的本機狀態或儲存庫偏移，請使用
workspace-surface-audit。
輸出標準
當此技能啟用時，不要只以「我修好了」結束。
始終提供：
- 失敗模式
- 根本原因假設
- 恢復行動
- 證明目前狀況已改善或仍受阻的證據