代理架構稽核 是做什麼的？
一套診斷工作流程，用於找出代理系統中隱藏在包裝層、過時記憶、重試迴圈或傳輸/渲染變異後的故障。
何時啟用
必須啟用於：
- 將任何代理或 LLM 驅動的應用程式發布至正式環境前
- 推出具備工具呼叫、記憶或多步驟工作流程的功能時
- 代理行為在加入包裝層後出現退化
- 使用者回報「代理越來越差」或「工具不穩定」
- 同一個模型在遊樂場中正常，但在您的包裝層內卻故障
- 偵錯代理行為超過 15 分鐘仍未找到根本原因
在以下情況尤其關鍵：
- 您已新增新的提示層、工具定義或記憶系統
- 系統中不同的代理行為不一致
- 模型昨天還正常，但今天卻開始產生幻覺
- 您懷疑有隱藏的修復/重試迴圈在默默地變異回應
不適用於：
- 一般程式碼偵錯 — 請使用
agent-introspection-debugging - 程式碼審查 — 請使用特定語言的審查代理
- 安全掃描 — 請使用
security-review或security-review/scan - 代理效能基準測試 — 請使用
agent-eval - 撰寫新功能 — 請使用適當的工作流程技能
12 層堆疊
每個代理系統都有這些層級。任何一層都可能會破壞答案：
| # | 層級 | 可能出錯的地方 |
|---|---|---|
| 1 | 系統提示 | 指令衝突、指令膨脹 |
| 2 | 對話歷史 | 從先前輪次注入過時的情境 |
| 3 | 長期記憶 | 跨對話的污染，新對話中出現舊主題 |
| 4 | 提煉 | 壓縮後的產物以偽事實的形式重新進入 |
| 5 | 主動召回 | 多餘的重新摘要層浪費情境空間 |
| 6 | 工具選擇 | 錯誤的工具路由，模型跳過所需工具 |
| 7 | 工具執行 | 幻覺式執行 — 聲稱已呼叫但實際未執行 |
| 8 | 工具解讀 | 誤讀或忽略工具輸出 |
| 9 | 答案成形 | 最終回應的格式損壞 |
| 10 | 平台渲染 | 傳輸層變異（UI、API、CLI 會變異有效答案） |
| 11 | 隱藏修復迴圈 | 執行第二次 LLM 執行的無聲備援/重試代理 |
| 12 | 持久化 | 過期的狀態或快取產物被當作即時證據重用 |
常見故障模式
1. 包裝層回歸
基礎模型能產生正確答案，但包裝層使其變得更糟。
症狀：
- 模型在遊樂場或直接 API 呼叫時正常，但在您的代理中故障
- 新增了一個提示層，現有行為退化
- 代理聽起來很有信心，但卻自信地給出錯誤答案
- 「上次更新前還能用」
2. 記憶體污染
舊主題透過歷史記錄、記憶檢索或提煉而洩漏到新對話中。
症狀：
- 代理提起無關的過往主題
- 使用者的修正無效（舊記憶蓋過新記憶）
- 相同對話的產物以偽事實的形式重新進入
- 記憶無限制增長，隨著時間推移降低回應品質
3. 工具紀律失效
工具在提示中宣告但未在程式碼中強制執行。模型會跳過它們或幻覺式執行。
症狀：
- 提示中有「必須使用工具 X」的規則，但模型在未呼叫的情況下直接回答
- 工具結果看起來正確，但實際上從未被執行過
- 不同的工具爭奪相同的責任
- 模型在不該使用工具時使用，或在必須使用時跳過
4. 渲染/傳輸損壞
代理的內部答案正確，但平台層在傳遞過程中對其進行了變異。
症狀：
- 日誌顯示正確答案，使用者看到損壞的輸出
- Markdown 渲染、JSON 解析或串流片段破壞了有效的回應
- 隱藏的備援代理在傳遞前悄悄替換了答案
- 終端機與 UI 的輸出不同
5. 隱藏代理層
無聲的修復、重試、摘要或召回代理在沒有明確合約的情況下運行。
症狀：
- 內部生成與使用者傳遞之間的輸出發生變化
- 「自動修復」迴圈執行了使用者不知道的第二次 LLM 執行
- 多個代理在沒有協調的情況下修改相同的輸出
- 答案被不可見的層級「平滑」或「修正」
稽核工作流程
階段 1：界定範圍
定義您要稽核的內容：
- 目標系統 — 哪個代理應用程式？
- 進入點 — 使用者如何與之互動？
- 模型堆疊 — 使用哪個/哪些 LLM 和供應商？
- 症狀 — 使用者回報了什麼？
- 時間窗口 — 何時開始？
- 需稽核的層級 — 適用哪 12 層中的哪些層級？
階段 2：收集證據
從程式碼庫收集證據：
- 原始碼 — 代理迴圈、工具路由器、記憶准入、提示組裝
- 日誌 — 歷史對話追蹤、工具呼叫記錄
- 設定檔 — 提示模板、工具結構、供應商設定
- 記憶檔案 — SOP、知識庫、對話存檔
使用 rg 搜尋反模式：
# 工具需求僅在提示文字中表達（非程式碼）
rg "must.*tool|必須.*工具|required.*call" --type md
# 未經驗證的工具執行
rg "tool_call|toolCall|tool_use" --type py --type ts
# 主要代理迴圈以外的隱藏 LLM 呼叫
rg "completion|chat\.create|messages\.create|llm\.invoke"
# 沒有使用者修正優先級的記憶准入
rg "memory.*admit|long.*term.*update|persist.*memory" --type py --type ts
# 執行額外 LLM 呼叫的備援迴圈
rg "fallback|retry.*llm|repair.*prompt|re-?prompt" --type py --type ts
# 無聲輸出變異
rg "mutate|rewrite.*response|transform.*output|shap" --type py --type ts
階段 3：故障對應
針對每個發現，記錄：
- 症狀 — 使用者看到的內容
- 機制 — 包裝層如何導致此問題
- 來源層級 — 12 層中的哪一層
- 根本原因 — 最深層的原因
- 證據 — 檔案:行號 或 日誌:行號 參考
- 信心度 — 0.0 到 1.0
階段 4：修復策略
預設修復順序（以程式碼為優先，非提示詞）：
- 程式碼閘控工具要求 — 在程式碼中強制執行，而非僅在提示文字中
- 移除或縮小隱藏修復代理 — 使用明確合約使備援行為明確化
- 減少情境重複 — 相同資訊同時透過提示、歷史、記憶和提煉傳遞
- 收緊記憶准入 — 使用者修正 > 代理斷言
- 收緊提煉觸發條件 — 不要壓縮不該壓縮的內容
- 減少渲染變異 — 直接傳遞，不要轉換
- 轉換為型別化 JSON 信封 — 結構化內部流程，而非自由格式散文
嚴重性模型
| 等級 | 意義 | 行動 |
|---|---|---|
critical | 代理可能自信地產生錯誤的運作行為 | 在下個版本前修復 |
high | 代理經常降低正確性或穩定性 | 在此衝刺中修復 |
medium | 正確性通常能維持，但輸出脆弱或浪費資源 | 規劃下個週期處理 |
low | 主要是表面或可維護性問題 | 加入待辦事項 |
輸出格式
按以下順序向使用者呈現發現事項：
- 按嚴重性排序的發現事項（最嚴重的優先）
- 架構診斷（哪一層破壞了什麼，以及原因）
- 有序的修復計畫（以程式碼為優先，非提示詞）
不要以讚美或摘要開頭。如果系統已損壞，請直接說明。
快速診斷問題
稽核代理系統時，回答以下問題：
| # | 問題 | 如果「是」→ |
|---|---|---|
| 1 | 模型是否可以跳過所需工具仍然回答？ | 工具未經程式碼閘控 |
| 2 | 舊對話內容是否出現在新的輪次中？ | 記憶體污染 |
| 3 | 相同資訊是否同時存在於系統提示、記憶和歷史中？ | 情境重複 |
| 4 | 平台是否在傳遞前執行了第二次 LLM 執行？ | 隱藏修復迴圈 |
| 5 | 內部生成與使用者傳遞之間的輸出是否不同？ | 渲染損壞 |
| 6 | 「必須使用工具 X」的規則是否僅存在於提示文字中？ | 工具紀律失效 |
| 7 | 代理自身的獨白是否可能成為持久記憶？ | 記憶中毒 |
應避免的反模式
- 避免在尚未排除包裝層回歸之前就先歸咎於模型。
- 避免在未顯示污染路徑的情況下指責記憶。
- 不要讓乾淨的目前狀態抹去骯髒的歷史事件。
- 不要將 Markdown 散文視為值得信賴的內部協定。
- 當程式碼從未強制執行時，不要接受提示文字中的「必須使用工具」。
- 保持發現事項直接、有證據支持，並按嚴重性排序。
報告結構
稽核應產生遵循以下形狀的結構化報告：
{
"schema_version": "ecc.agent-architecture-audit.report.v1",
"executive_verdict": {
"overall_health": "high_risk",
"primary_failure_mode": "string",
"most_urgent_fix": "string"
},
"scope": {
"target_name": "string",
"model_stack": ["string"],
"layers_to_audit": ["string"]
},
"findings": [
{
"severity": "critical|high|medium|low",
"title": "string",
"mechanism": "string",
"source_layer": "string",
"root_cause": "string",
"evidence_refs": ["file:line"],
"confidence": 0.0,
"recommended_fix": "string"
}
],
"ordered_fix_plan": [
{ "order": 1, "goal": "string", "why_now": "string", "expected_effect": "string" }
]
}
相關技能
agent-introspection-debugging— 偵錯代理運行時故障（迴圈、逾時、狀態錯誤）agent-eval— 基準測試代理效能，進行頭對頭比較security-review— 程式碼與設定的安全稽核autonomous-agent-harness— 設定自主代理操作agent-harness-construction— 從頭建構代理測試框架