前言¶

在 DeepSeek Harness (DSH) 的开发实践中，智能体很容易陷入逻辑死循环。例如，一个智能体调用 search 查询天气，读取结果，决定再次调用 search 查询天气。单个调用没有错误，直到达到预算或预算限制或人工干预。dsh-loop-brake 插件通过检测并阻止第三次连续调用，解决了这个问题。

插件介绍¶

dsh-loop-brake 是 DeepSeek Harness 的一个函数插件，它是一个针对相同工具调用的电路断路器。

• 维护者：jwilson411
• 类别：工作流
• 许可证：MIT
• 核心价值：防止智能体无限重复执行相同的工具调用，无需进行模型推理或额外的运行时依赖。

安装与配置¶

安装插件需要使用官方的 DSH CLI 命令。该命令会从包清单中读取 dsh.bundle.patch 并将其追加到配置文件的有序插件列表中。

dsh plugin --profile default add github:jwilson411/dsh-loop-brake

安装后，插件会应用默认配置。默认行为是允许连续执行 3 次相同的工具调用，第 4 次将被拒绝。可以在插件配置中调整此阈值。

配置示例：

- id: loop-brake
  config:
    maxRepeats: 5

注意：
* maxRepeats 必须是至少为 1 的整数。
* 如果值为 1，将立即拒绝所有重复调用（包括同一次调用中的第一次），主要用于调试。
* 配置项缺失时，插件会读取环境变量 DSH_LOOP_BRAKE_MAX_REPEATS，但插件配置优先级高于环境变量。

工作原理¶

该插件使用 SHA256 哈希算法进行精确匹配。两个调用被视为相同，当且仅当以下哈希值相同：

sha256(toolName + "\n" + canonicalJson(args))

这里的 canonicalJson 仅对对象键进行排序，不进行其他标准化处理。这意味着 {"a":1,"b":2} 和 {"b":2,"a":1} 被视为一次调用。

匹配规则：
* 捕获：智能体逐字节重复相同的调用（例如 search {q: "weather"}）。
* 不捕获：参数中包含时间戳、nonce、页游标或重试计数器的调用。这些调用虽然逻辑上相似，但哈希不同，插件不干预。
* 不捕获：在两个调用之间交替（例如 A, B, A, B）。插件只跟踪连续的重复次数，而不是总次数。

会话隔离：
计数是按会话进行的。一个会话内的重复计数不会影响其他会话。如果计数器中断（例如调用了不同的工具），计数会重置。

错误处理¶

当插件触发断路器时，会抛出 LoopBrakeError 错误。工具主体代码不会执行。错误对象包含以下属性，用于在日志中快速定位问题：

• code: 'LOOP_BRAKE'
• toolName: 触发错误的工具名称
• count: 当前重复次数（包含本次被拒绝的调用）
• maxRepeats: 配置的最大重复次数
• hashPrefix: 调用哈希的前 12 个十六进制字符（用于在日志中识别调用，无需记录完整参数）
• sessionId: 触发错误的会话 ID
• plugin: 插件名称 'dsh-loop-brake'

由于安全原因，错误的详细信息中不包含具体的参数内容。

直接使用库¶

除了作为插件使用外，该库也提供了独立的 API，供希望在调用点直接控制断路逻辑的主机使用。

import { LoopBrake, decorateTool, wrapExecute } from 'dsh-loop-brake/loop-brake'

const brake = new LoopBrake({ maxRepeats: 3 })

// 包装单个执行函数
const guarded = wrapExecute(execute, brake, { tool: 'search', sessionId: 's1' })

// 或复制整个工具定义并包裹其执行逻辑
const braked = decorateTool(definition, brake)

注意事项与适用场景¶

• 适用场景：智能体因为逻辑缺陷或上下文不足而反复调用同一个工具且参数完全一致。
• 不适用场景：智能体在循环中修改参数（如增加页码），或在不同工具间轮询。
• 依赖要求：无运行时依赖，仅依赖 Node.js 内置的 node:crypto。
• 版本要求：需要与 @deepseek-ai/dsh-tools 版本 0.1.1-rc.2 兼容。
• 补丁机制：如果通过 id-targeted 补丁配置此插件，必须替换整个 config 对象，而不是合并。

结语¶

dsh-loop-brake 提供了一种低成本、无模型调用开销的方式来防止智能体陷入重复调用的死循环。它通过严格的哈希匹配机制，确保了断路行为的确定性，便于调试和排查。

• 目录页: https://www.skillhub.cn/plugins/jwilson411/dsh-loop-brake
• GitHub 仓库: https://github.com/jwilson411/dsh-loop-brake