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