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