前言¶
DeepSeek Harness (DSH) 的智能体循环执行中，有时会出现单轮步数过高或陷入重复调用的问题。根据 2026-09-13 的实测日志，单次 turn 最多可能跑出 337 步，同一条命令被重复调用 120 次甚至 85 次。
DSH 自带的 repeat-tool-reminder 插件仅做提醒，不进行中断；而 dsh-agent-loop 目前只暴露 maxParallelToolCalls 参数，缺乏对步数上限的控制。这导致用户往往需要等待数小时，或在最后时刻手动输入 /stop。
dsh-loop-breaker 插件就是为了解决这一缺口而设计，通过硬止损机制，在检测到重复调用时直接中断本轮。
定位¶
这是一款硬止损插件，用于在 DSH 环境中，当同一工具配合同一参数被反复调用时，强制中断当前执行轮次。
- 维护者: ikta2010
- 许可证: MIT
- 核心作用: 防止 Agent 陷入死循环或无效重复
核心功能¶
插件通过两个上游扩展点实现逻辑：
tools/post-execute(waterfall): 计数，当达到阈值时返回{kind:'block', feedback, additionalContexts}，否决当前结果并展示说明。agent/pre-step(waterfall): 返回{kind:'reject'}，阻止下一步进入，从而结束本轮。
判定键为「工具名 + 参数规范化后的 JSON」。这意味着正常的差异化命令调用不会触发误伤。
配置项支持以下功能：
* consecutiveLimit: 控制连续重复多少次触发硬止损。
* totalLimit: 控制单轮内累计重复多少次触发硬止损。
* include / exclude: 过滤需要统计的工具列表。
* argumentsPreviewChars: 控制参数预览的字符数。
安装与启用¶
安装脚本位于指定路径，执行即可：
bash /nas/dsh/工具/dsh-loop-breaker/install.sh
安装完成后，必须重启一次 dsh web 才会加载该插件。重启期间网页会短暂断开，但会话数据不会丢失：
dsh-restart
典型用法¶
在 DSH 的配置文件中添加以下 YAML 配置：
- id: loop-breaker
name: 'dsh-loop-breaker'
config:
consecutiveLimit: 4 # 连续重复多少次硬止损
totalLimit: 12 # 单轮内累计多少次硬止损
include: [] # 只统计这些工具（空=全部）
exclude: [] # 排除这些工具
argumentsPreviewChars: 400
适用场景与注意¶
本插件以当前 DSH 进程的权限运行。安装前，建议检查源码与许可证。
- 加载机制: 插件安装后需重启 Web 服务才能生效。
- 判定逻辑: 依赖工具名和规范化后的 JSON 作为判定键，能够有效区分不同命令，避免误杀正常业务逻辑。
- 生态背景: DSH 的核心理念是「一切皆插件」。社区目录（如 SkillHub）提供插件索引，独立于 DeepSeek 或幻方，供开发者查阅。
结语¶
dsh-loop-breaker 补齐了 repeat-tool-reminder 只提醒不中断的短板，为 DSH 智能体循环提供了必要的硬性约束。通过合理的 consecutiveLimit 和 totalLimit 设置，可以有效避免长时间无意义的重复执行。
