前言¶

跑 DSH 智能體的時候，多數調試時間花在重複的失敗上：同一個工具以同樣的參數失敗兩次、長錯誤原文把上下文喫光、上一回合失敗的提示到下一回合就不見了。dsh-failure-ledger 是 TMrazbw 維護的一個 profile 級 Host + Client 插件，做四件事：把大型工具錯誤壓縮成短摘要、跨會話統計對話異常、每回合結束給一次零 token 的提醒，再把節省下來的 token 折算成估算金額顯示在側欄面板裏。

它不新增 session event type，不改 DSH 核心，只用公開事件與服務；規則默認全開、閾值取保守值，面板可逐條關閉或調整。下面按它實際提供的能力介紹。

這是什麼¶

插件名 dsh-failure-ledger，倉庫 https://github.com/TMrazbw/dsh-failure-ledger，分類爲「工作流」，當前版本 V2.8（package 0.1.2，194 項測試通過，MIT）。它由兩部分組成：

• Host 入口 index.js，負責 post-execute 摘要、failureLedger 會話投影和 failure_inbox 工具。
• Client 入口 client.js，負責回合尾提醒（conversation.chat.turnTail）、主面板和側欄圖標。

設計目標是全局失敗採集：所有 DSH 會話、代理、子代理自動生效，同一套規則和統計。

核心功能¶

大錯誤壓縮與落盤¶

長錯誤原文不進上下文，而是寫入 failure-reports 目錄（默認 D:\deepseek插件\dsh-failure-ledger\failure-reports），模型只看到短摘要 + 下一步 + 報告路徑。只有大錯誤才替換；小錯誤或含圖片的結果只加一條插件 hint；下游 block 原樣保留；同一 callId 不重複注入。

落盤的數據包括 index.jsonl、savings.jsonl、anomalies.jsonl、totals.json、playbook.jsonl，以及 reports\、raw\、handoffs\、INBOX.md。totals.json 單調累計，清理明細不會讓它回退；空間策略只有兩條：每 200 次寫入檢查一次，明細總上限 100 MB。

對話異常統計¶

異常通過 INBOX.md、index.jsonl、reports/<fingerprint>.md 和 failure_inbox 工具暴露。會話級統計由 failureLedger 投影提供（n1/n2/saved/usage），摘要裏的 Tokens: 標記讓重放也能恢復節省數。子代理按 sessionId 去重聚合。

V2.6 增加上下文歸因：面板顯示當前 tokens / window、本回合增量、壓縮次數、主要來源 Top3 與最近 5 次請求，並引入 contextJump 規則（默認 8000 tokens + 10% 窗口，最多 3 條），近似 ±10%，不壓縮、不阻斷、不注入模型。

每回合提醒與面板¶

回合尾提醒默認走 UI（零模型請求），只顯示本回合統計（turnN1 / turnSavedTokens）；本回合沒有失敗或節省時不顯示。模型可見的提醒是 V1.5 的可選開關，默認關閉。conversation.composer.dock 另有一個會話累計徽標，文本形如 失敗 n · 異常 m · 節省 x，無數據時不顯示。

打開面板的方式有三種：

• 輸入 /dfl-ui，Client 在命令列表顯示左側 PanelIcon、label DFL-UI，並直接打開面板。輸入名仍是平臺要求的小寫。
• 直接說「打開對話異常統計」或「打開 DFL-UI 面板」，模型會調用 open_failure_ledger 工具。
• 點擊側欄的「對話異常統計」圖標。

面板包含概覽卡片（含「未解決」數量）、錯誤源、異常明細、最近失敗（只列 10 條）、按模型節省與只讀估算金額，以及規則與參數表單。規則與參數放在診斷/統計之前且不折疊；Guard 只顯示已出現（hits > 0）的，最多 20 條，超出的和未出現的收進摺疊區。保存走自有 POST api/failure-ledger.admin + Host settings，只允許 .volatile() 字段，並落 profile 配置。

Guard 觀察與防復發¶

V2.0 起有 13 個默認 Guard，覆蓋 edit/read 路徑、搜索 asar、路徑檢查、命令路徑、超時、sandbox、stale write、PWSh 啓動失敗、未知工具、依賴缺失、人工驗證、瀏覽器下載/授權等。失敗落盤後寫入 guard-hits.jsonl 並累加 guards.json；下一次 agent/pre-step 注入一行防復發提示（≤320 字符），同一 turn 最多一次、60s TTL，不阻斷、不創建額外模型請求。Guard 只進入觀察與提示，A 模式永不 block。

自愈、固化與自動交接¶

後續版本在這個骨架上加了幾條機制：

• V2.5 A：Guard 未命中的新失敗自動進入下一步，形如 [未解決失敗] tool/category/code: hint，不阻斷。
• V2.5 B：同一 turn、同一 tool，失敗後不同參數的成功調用視爲自愈，自動 resolve、生成 learned Guard 與迴歸草案，並清理 pending hint；默認 selfHeal.enabled=true，窗口 180s。
• V2.6 Step 4 固化：resolve 自動生成/更新 learned-<fingerprint> Guard，寫出 regressions/<fingerprint>.md；playbook 記錄 guardId / regression，面板顯示「固化/未固化」。舊 playbook 不回填，避免把測試證據變成規則。
• V2.7 Step 1 unstick：同一 session / fingerprint 第 2 次失敗時提示一次，記下共同假設、最小 probe、三個不同機制，不第三次變體。
• V2.7 Step 2 claimWithoutEvidence（觀察版）：記錄 lastEdit / lastVerify / lastClaim，聲稱完成但最近編輯後沒有成功驗證則記異常，只進面板與異常計數，不注入 hint。
• V2.8 換對話自動 handoff：不再提供按鈕，由 Agent 判斷用戶是否表達「換對話 / 新開會話 / 下次繼續 / 先到這裏」，調用 failure_inbox action=handoff。工具返回已調用功能、寫入路徑、用戶下一步，輸出 Goal / Done / Open failures / Open questions / Key facts，只寫事實、不做 LLM 語義總結，寫入 handoffs/<sessionId>.md。

特別注意 Goal 只取真實用戶消息（跳過 runner 注入塊與 DFL 通知），Done 只寫路徑/命令摘要。

Token 估算與花費¶

lib/savings.js 與 lib/cost.js 按 usage 與官方價格估算。金額估算只計直接壓縮節省，不乘後續重發，默認取空閒時段緩存未命中輸入價；formatCNY 與 snapshot 的 estimatedCNY 都只保留 2 位小數（分）。

價格口徑來自 DeepSeek 官方文檔（抓取於 2026-10-22），單位爲人民幣/百萬 tokens：

峯值時段爲北京時間週一至週五 09:00–12:00、14:00–18:00（法定節假日除外），空閒價爲高峯價的一半。未知模型按 flash 回退。預算功能默認關閉，可設本會話/今日 CNY 與預警比例。這些數字只是本地估算，不是賬單。

安裝與啓用¶

README 給出的安裝方式是 plugin_manager install_bundle，指向 GitHub 倉庫：

plugin_manager install_bundle
target: https://github.com/TMrazbw/dsh-failure-ledger

本地 desktop profile 已通過該命令安裝（application: applied）。按插件維護者的說明，修改 Host 代碼後，DSH 的 ESM 模塊緩存要求重啓應用；Client 代碼變化則要求刷新 Web 頁面。

典型用法¶

下面是一套可復現的最小流程。

1、跑一輪包含超大工具錯誤的會話，讓插件把長錯誤壓縮並落盤。錯誤原文會出現在 failure-reports\reports\，索引在 index.jsonl。

2、輸出 /dfl-ui 打開面板，確認概覽卡片的未解決數量、錯誤源和近期失敗。若要讓 Agent 主動讀取，可用 failure_inbox 工具：

failure_inbox action="unresolved"

它返回按 fingerprint 分組的未解決失敗；action="playbook" 則返回已解決的修復記錄。這些後臺讀取不依賴 UI。

3、想結束當前對話、把上下文交接出去時直接說「先到這裏」，讓 Agent 決定是否調用：

failure_inbox action=handoff

工具會寫出 handoffs/<sessionId>.md 並返回用戶下一步。

適用場景與注意¶

適合長期跑 DSH 智能體、希望事後復盤失敗規律、或想量化大錯誤壓縮帶來的 token 節省的開發者。它做的是觀察與提示，不是阻斷器：默認不調用 LLM，不把統計寫入 session log，提醒默認零模型請求。

需要注意三點：

• 插件以當前 dsh 進程的權限運行，安裝前應先閱讀源碼與 LICENSE（MIT）。
• 錯誤原文、報告、日誌只保存在本機，採集按工具定製並脫敏；面板寫參數前必須確認，且只允許 .volatile() 字段。
• 金額與節省都是估算值，不得作爲計費或對賬依據。

結尾¶

dsh-failure-ledger 的價值在於把「失敗」從一次性的上下文噪聲變成可累積、可查詢、可交接的臺賬，同時不打斷當前對話。目錄頁在 https://www.skillhub.cn/plugins/TMrazbw/dsh-failure-ledger ，代碼與文檔在 https://github.com/TMrazbw/dsh-failure-ledger 。