代理架構稽核 是做什麼的？
一個診斷性工作流程，用於找出那些將故障隱藏在包裝層、陳舊記憶、重試迴圈或傳輸/渲染變異後方的代理系統。
何時啟用
對以下情況是強制性的：
- 將任何代理或 LLM 驅動的應用程式發佈至正式環境
- 發佈具備工具呼叫、記憶或多步驟工作流程的功能
- 代理行為在新增包裝層後退化
- 使用者回報「代理越來越糟」或「工具不穩定」
- 同一個模型在 Playground 能正常運作，但在您的包裝層內卻故障
- 花了超過 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. 包裝回歸
基礎模型能產生正確答案，但包裝層讓它變得更糟。
症狀：
- 模型在 Playground 或直接 API 呼叫時正常，但在您的代理中出錯
- 新增了一個提示詞層後，現有行為退化
- 代理聽起來很有自信，但卻是充滿自信的錯誤
- 「上次更新之前明明是正常的」
2. 記憶污染
舊主題透過歷史、記憶檢索或提煉洩漏到新對話中。
症狀：
- 代理提起無關的舊主題
- 使用者的修正沒有被記住（舊記憶覆寫了新記憶）
- 同一對話的成品以偽事實的形式重新進入
- 記憶無限制增長，隨著時間降低回應品質
3. 工具紀律失效
工具雖然在提示詞中被宣告，但未在程式碼中強制執行。模型會跳過它們或幻覺其執行。
症狀：
- 提示詞中有「必須使用工具 X」，但模型在未呼叫它的情況下回答了問題
- 工具結果看起來正確，但實際上從未被執行
- 不同的工具爭奪同一個責任
- 模型在不該使用時使用工具，或在不該跳過時跳過工具
4. 渲染/傳輸損壞
代理的內部答案是正確的，但平台層在傳遞時對其進行了變異。
症狀：
- 記錄顯示正確答案，使用者卻看到損壞的輸出
- 有效的回應被 Markdown 渲染、JSON 解析或串流片段破壞
- 隱藏的備援代理在傳遞前默默地替換了答案
- 終端機與 UI 之間的輸出不一致
5. 隱藏代理層
靜默修復、重試、摘要或召回代理在沒有明確合約的情況下運行。
症狀：
- 內部生成與使用者傳遞之間的輸出發生變化
- 「自動修正」迴圈運行了使用者不知情的第二次 LLM 傳遞
- 多個代理在沒有協調的情況下修改同一個輸出
- 答案被不可見的層「平滑化」或「修正」
稽核工作流程
第一階段：範圍界定
定義您要稽核的內容：
- 目標系統 — 哪個代理應用程式？
- 進入點 — 使用者如何與它互動？
- 模型堆疊 — 使用哪些 LLM 和提供者？
- 症狀 — 使用者回報了什麼？
- 時間窗口 — 何時開始發生的？
- 要稽核的層級 — 12 層中的哪些層級適用？
第二階段：證據收集
從程式碼庫收集證據：
- 原始碼 — 代理迴圈、工具路由器、記憶准入、提示詞組裝
- 日誌 — 歷史對話追蹤、工具呼叫記錄
- 設定 — 提示詞範本、工具結構描述、提供者設定
- 記憶檔案 — 標準作業程序、知識庫、對話存檔
使用 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
第三階段：故障映射
對於每個發現，記錄：
- 症狀 — 使用者看到了什麼
- 機制 — 包裝層如何導致該問題
- 來源層級 — 12 層中的哪一層
- 根本原因 — 最深層的原因
- 證據 — 檔案:行號 或 日誌:行號 參考
- 信心水準 — 0.0 到 1.0
第四階段：修復策略
預設的修復順序（以程式碼為優先，而非提示詞）：
- 程式碼閘控工具要求 — 在程式碼中強制執行，而非僅在提示文字中
- 移除或縮小隱藏修復代理 — 使用合約讓備援變得明確
- 減少脈絡重複 — 相同資訊同時透過提示詞 + 歷史 + 記憶 + 提煉傳遞
- 收緊記憶准入 — 使用者修正 > 代理斷言
- 收緊提煉觸發條件 — 不要壓縮不該被壓縮的內容
- 減少渲染變異 — 穿透傳遞，不要轉換
- 轉換為型別化 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— 從頭開始建構代理測試框架