前言¶

在 DeepSeek Harness (DSH) 的插件化架構中，當工具（如網頁抓取）返回過大的結果時，往往會直接消耗掉對話上下文窗口，導致任務中斷。dsh-result-cap 作爲一個模型推理類插件，解決的是單條工具結果的長度控制問題。它不管理整體上下文窗口，而是對單次工具返回進行確定性截斷。

什麼是 dsh-result-cap¶

這是一個由 jwilson411 維護的插件，核心是對工具結果進行確定性 UTF-8 字節限制。它保留結果的前 N 個字節，同時返回完整原始內容的 SHA256 哈希值，確保截斷後的結果能被識別爲非完整內容。

核心功能¶

該插件提供以下功能：

1. 確定性截斷：按 UTF-8 字節對結果進行截斷，保留前 N 個字節。
2. 明確標記：返回 truncated 布爾標誌和 omitted_bytes（被丟棄的字節數）。
3. 完整哈希：返回完整原始內容的 SHA256 哈希值，而非截斷後內容的哈希。
4. 配置與優先級：支持配置 maxBytes（默認 8192），支持通過環境變量 DSH_RESULT_CAP_MAX_BYTES 設置。配置優先級爲：配置文件 > 環境變量 > 默認值。
5. 直接調用：支持直接使用 capResult 函數進行單元測試。
6. 類型限制：當前版本僅限制字符串類型（text 字段），不處理 Buffer 或圖片。

安裝與啓用¶

安裝插件需要 @deepseek-ai/dsh-tools 依賴。

1. 安裝：

    dsh plugin --profile default add github:jwilson411/dsh-result-cap

2. 配置：

    - id: result-cap
      config:
        maxBytes: 32000

典型用法¶

在代碼中可以直接使用 capResult 函數進行測試：

import { capResult } from 'dsh-result-cap'

capResult('short enough', 8192)
// → 'short enough'   (未截斷)

capResult('x'.repeat(20000), 8192)
// → { text: 'xxxx…', truncated: true, omitted_bytes: 11808, sha256: '…' }

適用場景與注意¶

• 適用場景：當工具返回的內容遠超上下文窗口時，作爲最後一道防線，只保留頭部內容並標記截斷，防止整個任務因單條結果過大而中斷。
• 注意：
  • 它不是 Headroom、壓縮模型、語義壓縮或總結器，只是簡單的字節切片。
  • 當前版本 v1 僅支持字符串類型，不支持 Buffer 或圖片。
  • 配置時，id-targeted patch 會替換整個 config 塊，不能合併。
  • 不靜默截斷，必須返回 truncated: true 標誌。
  • 配置參數必須爲整數且至少爲 1。無效值（如浮點數、負數、布爾值或未知鍵）會被拒絕，拋出 InvalidResultCapConfigError（代碼 RESULT_CAP_CONFIG）。

結尾¶

dsh-result-cap 提供了可控的字節截斷能力，配合 SHA256 哈希值，解決了工具結果溢出上下文的問題。更多細節可查閱 GitHub 倉庫 或 技能中心目錄。