DeepSeek Harness 插件：jwilson411/dsh-tool-quota

DSH (DeepSeek Harness) 生態中，智能體對工具的調用往往缺乏細粒度的控制。一個看似無害的搜索工具，可能被連續調用數十次，或者返回幾兆字節的超大結果，導致上下文膨脹或資源浪費。jwilson411/dsh-tool-quota 插件正是爲了解決這一問題而設計。

插件簡介¶

這是一個 DeepSeek Harness 插件，核心功能是按會話、按工具名稱限制調用次數和返回結果字節數。與靜默截斷不同，該插件在觸達限制時會拋出明確的錯誤，迫使系統或開發者介入。

維護者：jwilson411
許可證：MIT
類別：模型推理

安裝與啓用¶

安裝此插件需要使用 DSH 的插件管理命令。安裝後，插件本身不包含任何默認限制，需要通過配置文件指定具體的配額規則。

dsh plugin --profile default add github:jwilson411/dsh-tool-quota

前置條件：
* Node.js 版本需 >= 22.14.0
* 需要滿足以下對等依賴：@deepseek-ai/cordis ^4.0.1 和 @deepseek-ai/dsh-tools ^0.1.1-rc.2

配置說明¶

安裝後，需要通過 DSH 的配置文件（通常涉及 dsh.bundle.patch 或相關配置）定義具體的規則。配置是一個 YAML 結構，其頂層鍵爲工具名稱，或者使用通配符 * 作爲默認規則。

每條規則包含以下字段（均爲整數，至少爲 0）：

maxCalls：限制該工具在一個會話中最多可調用的次數。達到上限後，第 N 次調用會被直接拒絕。
maxResultBytes：限制該工具返回結果的最大字節數（UTF-8）。如果結果超過此限制，結果會被丟棄，調用報錯。

配置示例：

- id: tool-quota
  config:
    arxiv_search:
      maxCalls: 8
      maxResultBytes: 32000
    "*":
      maxCalls: 40
      maxResultBytes: 64000

規則覆蓋邏輯¶

具體工具優先：如果配置中明確指定了某個工具（如 arxiv_search），則該工具使用其自身的規則，不會與 * 規則進行字段合併。
默認規則：未明確指定的工具將使用 * 規則。
無限制：如果工具未在配置中列出，且沒有 * 規則，則該工具不受任何限制。

功能細節¶

1. 會話與計數機制¶

按會話計數：配額屬於會話，多個代理共享進程時不會互相消耗配額。會話 ID 優先取調用時傳入的 sessionId，否則取執行輸入中的代理 ID，最後默認爲 default。
按工具計數：每個工具名有獨立的配額池。例如，* 規則設置 maxCalls: 40，意味着每個未配置的具體工具都有 40 次調用機會，而不是所有工具共享 40 次。
拒絕不計入：被拒絕的調用不會記錄在 used 計數中。

2. 結果字節限制¶

字節限制在工具執行之後進行檢查。這意味着調用已經發生（且可能產生費用），插件的作用是保護對話上下文，防止過大的結果被傳給後續模型。如果結果無法測量（如 BigInt 或循環引用），將被視爲超限並報錯。

3. 錯誤處理¶

插件會拋出兩種特定錯誤，便於調用方進行分支處理：

ToolQuotaCallsError：調用次數超限。
- 包含 code、toolName、sessionId、count（被拒絕的調用序號）、used（已使用次數）、maxCalls。
ToolQuotaBytesError：結果字節超限。
- 包含 code、toolName、sessionId、byteLength、maxResultBytes、reason（OVER_LIMIT 或 UNMEASURABLE）。

4. 狀態查詢工具¶

插件註冊了一個名爲 tool_quota_status 的工具，供智能體查詢當前會話的剩餘配額。該工具無參數，返回 JSON 格式的狀態信息，包括每個工具的已用次數、最大次數和剩餘次數。

{
  "plugin": "dsh-tool-quota",
  "sessionId": "agent-1",
  "tools": [
    {
      "name": "arxiv_search",
      "rule": "tool",
      "used": 3,
      "maxCalls": 8,
      "remaining": 5,
      "maxResultBytes": 32000
    }
  ]
}

適用場景與注意¶

資源控制：適合需要防止某個工具被過度使用（如搜索、數據庫查詢）導致系統負載過高的情況。
上下文保護：適合需要防止超大文件或長文本被模型讀取，導致上下文溢出的場景。
注意：這不是一個預算系統（不涉及 USD），也不是時間限制器（不涉及時間窗口）。它只關心單次會話內的總量。

結語¶

jwilson411/dsh-tool-quota 提供了一種強制性的手段來控制工具使用邊界。通過明確的錯誤拋出和會話級計數，它幫助開發者構建更穩定、可控的 DeepSeek Harness 智能體應用。

GitHub 倉庫：https://github.com/jwilson411/dsh-tool-quota
插件目錄：https://www.skillhub.cn/plugins/jwilson411/dsh-tool-quota