卡死循环防护erdholion/dsh-loop-guard

dsh-loop-guard

面向 DeepSeek Harness 的结果感知卡死循环防护：建议性提醒加上单调递增的硬性停止。

为什么需要它

一个阶段如果重复相同的工具调用并不断得到相同的结果，那就是卡住了——它在消耗步骤（和 token），却没有产生新信息。本插件移植了一个曾在多 harness LLM 网关前运行数周的防护机制，在那里，这种两阶段设计可测量地将中止的智能体运行转变为完成的运行（该模式沿袭自 OpenHands 的 StuckDetector 谱系）。

关键的设计决策是：只有结果完全相同的重复才计数。要求结果一致，就免费地把合法的重复列入白名单，无需配置工具名称：

- 轮询一个状态不断推进的任务 → 结果不同 → 永不触发
- 在编辑后重新读取文件 → 结果不同 → 永不触发
- 重试一个不稳定的命令，最终行为有所不同 → 永不触发

它与 @deepseek-ai/dsh-repeat-tool-reminder 的关系

官方基础包已经附带了一个建议性重复检测器。本插件是补充性的，而非替代品：

|  | repeat-tool-reminder（官方） | dsh-loop-guard |
|---|---|---|
| 链身份 | 工具名称 + 参数 | 工具名称 + 参数 + 结果 |
| 推进中的轮询循环 | 触发提醒（除非被模式排除） | 透明，永不触发 |
| 强制执行 | 从不——按设计仅为建议性 | 在硬阈值处拒绝进一步的相同调用 |
| 忽略提醒的模型 | 循环直到回合/预算耗尽 | 被停止，并收到可据以行动的纠正性反馈 |

同时运行两者没有问题：提醒会在参数相同的重复早期就发出提醒；本防护只在循环可证明无产出（结果相同）时才介入，并且它是两者中唯一能终止循环的。拒绝是一个普通的错误结果——会话得以存活，模型收到纠正性反馈，这对那些将提供方级 4xx 错误视为致命错误的前端来说很重要。

安装

dsh plugin --profile  add github:erdholion/dsh-loop-guard

或从本地检出安装：dsh plugin --profile  add ./dsh-loop-guard。

行为

对每个智能体，防护会跟踪连续工具调用的运行长度，这些调用具有相同的（名称、按规范键排序的参数）以及相同的结果内容。

- 软阶段（运行长度 ≥ softThreshold，默认 4）：此后每一次相同的重复都会在工具结果之后注入一条来自插件的通知，告诉模型这些调用完全相同，重复将在硬阈值处被拒绝，并应基于它已经知道的信息采取行动。
- 硬阶段（运行长度 ≥ hardThreshold，默认 8）：一个单调递增的工具防护会拒绝下一次相同的调用，并给出纠正性反馈。不相同的调用不受影响；在拒绝重复期间该链会冻结，因此防护会保持介入，直到模型改变其行动。
- 重置：真正的用户插话（source.kind === 'user'）会重置链条——跨用户消息的重复不算循环。守卫自身注入的通知来自插件，不会重置任何内容。

配置

- id: loop-guard
name: dsh-loop-guard
config:
softThreshold: 4     # 0 禁用提醒
hardThreshold: 8     # 0 禁用拒绝；必须大于 softThreshold
resultHashChars: 4000 # 参与哈希的序列化结果前缀

无效配置（非整数、负数、hard ≤ soft）会在插件加载时抛出——配置错误的守卫会大声失败，绝不静默。

许可证

MIT