前言¶

在 DeepSeek Harness (DSH) 的開發中，處理超長工具結果是一個常見痛點。DSH 自帶兩種機制：dsh-spill-policy 和 dsh-compaction-tool-result-pruner。前者在結果超過 50KB 時觸發，後者在文本超過 8192 字符且滿足壓縮壓力條件時觸發。前者支持無損恢復，後者在模型側無法恢復中間內容。本文介紹的插件填補了這個空白，旨在解決中間態結果的剪枝與恢復問題。

這是什麼¶

這是一個針對 DeepSeek Harness (DSH) 的 dsh-plugin。其核心功能是在工具執行後，優先將過大的純文本結果溢出到文件，然後用包含精確截斷位置和文件定位符的頭部/尾部預覽替換原始結果。這確保了模型始終可以通過 read、grep 或 sed 恢復被截斷的中間內容，且沒有任何數據丟失。由 may3rr 維護，遵循 MIT 許可證。

核心功能¶

1. 無損剪枝：針對 DSH 的工具結果進行剪枝，確保不丟失任何數據。
2. 先溢出後剪枝：將過大的純文本結果優先寫入文件，再在返回給模型的內容中保留頭部和尾部。
3. 精確定位：預覽內容包含被截斷的精確範圍和溢出文件的路徑。
4. 可恢復性：模型可以通過 read、grep 或 sed 在溢出文件中找回被截斷的中間部分。
5. 監聽器模式：作爲 tools/post-execute 水位線監聽器運行，在工具投影和其他鉤子之後執行剪枝。
6. 冪等性：剪枝後的內容始終在閾值範圍內，不會重複剪枝。

安裝與啓用¶

安裝只需一條命令：

dsh plugin --profile web add dsh-tool-result-guard

安裝後重啓 DSH。插件會自動應用到該 profile 下的所有智能體預設。

配置文件位於 ~/.dsh/profiles/web/cordis.patch.yml：

- id: tool-result-guard
  config:
    thresholdChars: 16384

典型用法¶

恢復被剪枝的內容
當模型收到類似以下的剪枝結果時：

[pruned: kept chars [0, 4096) + [28976, 30000) of 30000; the elided middle
[4096, 28976) is NOT lost — full output saved at: /tmp/dsh-spill/.../bash.txt.
Recover any elided span with the read tool (offset/limit), grep, or sed on that file.]

<head: first 4096 chars>
...
<tail: last 1024 chars>

模型可以使用 read 工具（配合 offset/limit 參數）、grep -n 或 sed -n 'X,Yp' 在溢出文件中讀取被截斷的部分。

配置剪枝閾值
在配置文件中調整剪枝參數：

- id: tool-result-guard
  config:
    thresholdChars: 8192    # 超過此字數開始剪枝
    headChars: 4096          # 保留前多少字符
    tailChars: 1024          # 保留後多少字符
    excludeTools: ["read"]   # 不剪枝這些工具的結果

適用場景與注意¶

適用場景
適用於需要處理中等長度（8K-50K 字節）工具結果的場景，這些結果超過了 dsh-compaction-tool-result-pruner 的處理範圍但未達到 dsh-spill-policy 的閾值。適合追求模型側完全可控、無數據丟失的 LLM Agent 開發。

注意事項
1. 配置限制：headChars + tailChars 必須小於 thresholdChars，否則標記無法放入結果中。
2. 容錯機制：如果溢出文件寫入失敗，插件會保持原始內聯結果不變（Fail-open），不會導致任務報錯。
3. 配置鍵檢查：配置文件中未知的鍵會導致加載失敗，需嚴格使用支持的字段。
4. 依賴要求：需要 Node.js 環境版本 >= 18。
5. 權限與安全：插件以當前 DSH 進程權限運行，安裝前請檢查源碼與許可證。

短結尾¶

通過 dsh-tool-result-guard，DSH 開發者可以解決工具結果中間態剪枝不可恢復的痛點。它通過文件溢出與精確標記，確保了上下文管理的完整性。更多細節請查看插件目錄或源碼倉庫。