前言¶

在使用 DeepSeek Harness (DSH) 构建智能体时，模型容易陷入重复调用同一工具的循环（例如不断重试一个 404 的 API，或者重复发送相同的 read 命令）。这不仅浪费 Token，还可能触发限流。为了避免这种情况，需要在 DSH 端进行阻断。

插件介绍¶

dsh-repeat-tool-breaker 是一个用于 DeepSeek Harness (DSH) 的同步插件。它通过注册一个 ctx.tools.guard 门控，对智能体在滑动窗口内的工具调用进行语义指纹检测。一旦检测到重复调用或连续失败，它会触发警告、要求总结，并在达到阈值时阻断调用，从而强制模型改变策略。

核心功能¶

1. 语义指纹检测：插件不依赖完全相同的字节，而是基于语义指纹进行匹配。支持的指纹类型包括：
   • exact：完全相同的工具调用。
   • cmd：命令级指纹。
   • net：网络级指纹（如主机名折叠后的路径）。
   • host：主机级指纹。
   • sink：数据流指纹。
2. 失败追踪轨道：除了检测重复调用外，插件还追踪连续失败。如果指纹连续失败，会在第 3 次触发提示，第 5 次触发阻断。
3. HTTP 请求处理：插件会拒绝 Shell 环境下的 HTTP 请求，并重定向模型使用 web_fetch_file 工具来获取页面并返回路径。
4. 门控机制：这是一个同步门控，一旦触发，调用不会执行，模型会收到错误反馈。

安装与启用¶

安装前请确保你的 DSH 版本符合要求。该插件支持 dsh >= 0.1.7 (Session 格式 4) 以及 dsh 0.2.0 系列版本。

如果使用 DSH 0.1.5，请安装特定版本：

dsh plugin install dsh-repeat-tool-breaker@0.7

对于 DSH 0.1.7 及 0.2.0 (rc.1 到 0.2.1 之前)，请使用最新版本（目前为 0.8.x 系列）：

dsh plugin install dsh-repeat-tool-breaker

典型用法¶

插件安装后，其门控逻辑默认生效。当调用被阻断时，模型会收到一个 isError 结果，该结果以 REPEAT_TOOL_BLOCKED 开头，并包含对之前调用的引用及建议的替代方案。

在配置层面，可以通过 onLimit 参数控制阻断后的行为：
* onLimit: ask（默认）：在阻断时询问操作员是否允许本次调用（即给予一次性的豁免权）。
* onLimit: deny：直接拒绝，不询问。

适用场景与注意¶

1. 版本兼容性：该插件依赖 DSH 的 Session 格式 4，且 0.1.7 版本重构了设置 API。这意味着在一个构建中无法同时为 0.1.7 和 0.1.5 两个世代注册设置页面。如果使用 0.1.5，只能获得功能逻辑，无法使用设置卡片。
2. 官方插件协同：官方插件 @deepseek-ai/dsh-repeat-tool-reminder 可以与 dsh-repeat-tool-breaker 共存。Reminder 负责早期提示（在 3/5/8 次重复时），Breaker 负责后期的阻断（在 12 次时）。
3. 运行权限：插件以当前 DSH 进程的权限运行。在安装前，建议检查其源码与许可证（MIT）。

结语¶

dsh-repeat-tool-breaker 通过引入语义指纹和双轨道检测机制，为 DSH 智能体提供了防止死循环的硬性保障。它从简单的重复计数演变为对失败行为的分析，能够有效识别模型在特定资源上的“钻牛角尖”行为。

查看目录页
查看 GitHub 源码