dsh-tool-failure-circuit-breaker：DeepSeek Harness 工具失败熔断器

前言¶

DeepSeek Harness（DSH）的插件生态允许开发者扩展智能体的能力。在开发过程中，模型经常会对失败的工具调用进行重试，尤其是那些依赖外部状态（如轮询 API）的操作。如果模型重试了参数完全相同的失败调用，这会浪费大量的延迟、网络请求、执行资源以及提供商成本。

与官方的 @deepseek-ai/dsh-repeat-tool-reminder 不同，该插件仅提供建议而不进行阻断。dsh-tool-failure-circuit-breaker 旨在解决这一痛点，它通过在插件层拦截重复的失败调用，直接阻止模型发送无意义的重试请求。

插件介绍¶

这是一个用于 DeepSeek Harness 的安全类插件，用于阻止 Agent 在工具调用失败后，再次分发参数完全相同的请求。

名称：dsh-tool-failure-circuit-breaker
维护者：icyaaaww
类别：admin-security
许可：MIT

安装与启用¶

插件通过本地路径安装。在安装前，请确保插件目录位于 Harness 项目的父目录中。

dsh plugin --profile web add ./dsh-tool-failure-circuit-breaker

核心功能¶

该插件通过以下机制工作：

阻断重复失败：插件会观察权威的 tools/result 失败结果，并在达到配置的阈值后，拒绝下一次参数完全相同的调度。
预执行拦截：监听 tools/pre-execute 事件，被拒绝的重试请求从未到达工具的具体执行逻辑。
结果一致性：将拒绝操作记录为正常的工具结果，确保模型历史记录和重放机制的一致性。
隔离故障链：故障链按“活动代理”隔离，以工具名称加上规范 JSON 参数作为键值。

配置说明¶

插件会在安装时插入默认配置行。你需要根据业务逻辑调整以下参数：

- id: tool-failure-circuit-breaker
  name: dsh-tool-failure-circuit-breaker
  config:
    maxFailures: 2        # 允许连续失败的最大次数，默认为 2
    include: []           # 需要保护的工具名通配符模式，为空则保护所有工具
    exclude: []           # 需要绕过熔断机制的工具名通配符模式
    errorPreviewChars: 300 # 在拒绝消息中展示的失败信息字符数，默认为 300

include：用于指定哪些工具需要开启熔断保护。
exclude：对于某些需要保持不变参数进行轮询的工具（例如检查特定状态是否就绪），应使用 exclude 来跳过熔断检测。
maxFailures：决定在触发阻断前允许多少次相同的失败。

行为与限制¶

状态管理：插件状态存储在内存中。当进程或插件重启时，历史失败记录会重置。
并行调用：如果多个并行请求同时发出且都失败，在达到阈值前，所有请求都可能已经发出。
匹配精度：仅检测参数完全一致的重试，无法检测参数相似的重试。
阻断方式：阻断是可选的，需通过安装插件来启用。请谨慎选择 exclude 规则，避免拦截合法的重复探查。

结语¶

该插件通过在 tools/pre-execute 阶段切断无意义的重试链路，有效降低了智能体的运行开销。对于需要频繁调用外部 API 且存在重试逻辑的 Agent 场景，这是一个实用的防御性工具。