前言¶
智能體 Harness（調度循環）在處理工具調用、狀態管理和錯誤恢復時，容易出現導致循環失效的故障模式。傳統的審計方式依賴人工閱讀代碼，效率低下且容易遺漏；而依賴大模型進行自動審計則可能產生“幻覺”，即給出沒有代碼依據的結論。
dsh-harness-audit 旨在解決這兩個問題。這是一個由 Leeaoyin 維護的工作流類 DSH 插件，它通過機器強制執行的證據驗證，對 Harness 進行自動化審計。它拒絕任何無法在代碼中找到證據的發現，並生成基於代碼而非模型生成的摘要報告。
核心能力¶
插件包含以下核心功能：
- 十五項檢查機制：覆蓋智能體循環的各個關鍵環節，每個檢查對應一個特定的故障模式。
- 機器強制證據驗證：所有發現必須能被代碼中的具體行、文本或路徑證明，否則將被拒絕。
- 自包含安裝：安裝插件即完成所有判斷標準的安裝，無需額外配置。
- 代碼驅動摘要：報告的最終總結由代碼編寫，不依賴大模型生成，確保客觀性。
- 後臺作業執行：審計命令立即返回，作爲後臺任務運行，不阻塞會話。
- 報告與指標：在
outputDir（默認.harness-audit/）生成 Markdown 和 JSON 報告，並提供子代理質量監控的“拒絕率”指標。
檢查清單¶
插件包含 15 項檢查，分爲五個組別。其中 p1 代表 7 個關鍵檢查（標記爲 ★）。以下是各檢查的具體內容：
| 組別 | 檢查代碼 | 檢查內容 |
|---|---|---|
| State stays self-consistent | C1 | 工具調用配對完整性：確保所有執行結束方式（錯誤、超時、取消）都有記錄，且並行批次中的失敗不會丟棄其他結果。 |
| C2 | 歷史追加：確保消息添加後不可編輯。 | |
| C3 | 崩潰與檢查點語義：檢查多部分寫入間進程死亡時的狀態可見性與可檢測性。 | |
| Untrusted input is treated as untrusted | C4 | 模型輸出解析：處理畸形參數、截斷流或重複調用 ID，而非信任它們。 |
| C5 | 路徑與沙盒邊界：解析並檢查模型提供的路徑是否在工作區根目錄內。 | |
| C6 | 密鑰與環境：檢查模型生成命令繼承的環境變量中是否包含密鑰。 | |
| Failure is a first-class outcome | C7 | 錯誤分類與重試性：確保失敗攜帶明確的錯誤代碼分類（可重試/不可重試/致命）。 |
| C8 | 部分成功：檢查獨立結果是否合併爲一個單一狀態，導致隱藏或丟棄成功。 | |
| C9 | 冪等性與副作用安全：檢查重試包裝器內的寫入、命令或出站消息是否會被重複執行。 | |
| Boundaries can be closed | C10 | 取消傳播：檢查取消信號是否真正到達出站請求和子進程。 |
| C11 | 超時分層：檢查工具調用層與底層資源的超時大小關係。 | |
| C12 | 循環與預算限制：檢查輪次、工具調用、時鐘時間、Token 和委託深度的硬性上限。 | |
| Finite resources are accounted for | C13 | 上下文管理與截斷邊界：檢查上下文是否隨會話增長而管理，以及截斷是否破壞調用/結果對。 |
| C14 | 提示前綴確定性：檢查運行間系統提示、工具定義、歷史消息的字節一致性。 | |
| The run is observable | C15 | 追蹤完整性與重放：檢查運行是否留下足夠的事件記錄以重建過程。 |
執行流程¶
一次審計運行包含三個階段：
- Recon（偵察）：一個子代理定位關鍵地標（如 Agent 循環、請求組裝、工具執行），並通過
report_landmark報告。 - Fan-out（分發）：爲每個檢查啓動一個一次性子代理，每個子代理僅接收與其相關的地標和特定的檢查標準。如果缺少必要地標，該檢查不會被分發。
- Summary（彙總）：由純代碼生成最終報告。模型不參與撰寫摘要，而是通過代碼將“疑似”標記轉化爲“確認”或移除無證據的聲明。
使用方法¶
插件提供命令行接口，支持指定檢查維度或運行全部檢查。
基本命令¶
/harness-audit # 詢問需要審計哪些維度，顯示純語言菜單
/harness-audit C1 # 審計單個維度
/harness-audit C1,C9 # 審計多個維度
/harness-audit p1 # 運行 7 個關鍵檢查（★ 標記的項）
/harness-audit all # 運行全部 15 項檢查
報告與後臺作業¶
命令執行後會立即返回，審計作爲後臺任務運行。完成後 Agent 會被喚醒並彙報。
查看後臺作業輸出：
job_output <id>
報告文件默認保存在 .harness-audit/ 目錄下，按時間和維度命名：
report-2026-08-17_095736-C1.md
report-2026-08-17_095736-C1.json
證據驗證與指標¶
插件內置嚴格的證據驗證機制，確保審計結論的可信度。report_finding 拒絕以下情況的發現：
1. 檢查不屬於本次運行。
2. 路徑不是第一方代碼（如 .venv, site-packages）。
3. 文件不在工作區內。
4. 引用的行不存在。
5. 引用的文本不在引用行附近 ±3 行內。
6. “疑似”結論缺少“確認提示”。
拒絕率是核心指標。如果拒絕率過高，意味着子代理在捏造 claims，需要調整提示。拒絕無法解析的輸入也是插件的設計原則，避免靜默的錯誤處理。
注意事項¶
- 安裝方式：已覈實事實中未提供明確的安裝命令。插件作爲 DSH 插件管理，請參考官方目錄或倉庫獲取安裝指引。
- 權限與範圍：插件以當前 DSH 進程權限運行。作用域強制機制防止插件審計第三方庫（如 vendored 代碼），確保審計對象是項目自身代碼。
- 誤報控制：在未找到目標地標時運行檢查是產生誤報的主要原因。插件會自動跳過未找到地標的檢查。
生態背景¶
DeepSeek Harness (DSH) 採用“一切皆插件”的理念。dsh-harness-audit 是社區貢獻的一個工作流插件，旨在幫助開發者構建更健壯的智能體系統。如需瞭解更多或獲取最新版本，請訪問：
* 插件目錄
* GitHub 倉庫
